@hienlh/ppm 0.8.59 → 0.8.61

package/docs/streaming-input-guide.md

@@ -0,0 +1,267 @@
+# Streaming Input Migration Quick Reference (v0.8.55+)
+
+## What Changed?
+
+**Before (v0.8.54):** Each message triggered a new SDK query
+```
+Message 1 → SDK subprocess spawn → generate response → close
+Message 2 → SDK subprocess spawn → generate response → close
+(Slow, context resets between messages)
+```
+
+**After (v0.8.55):** Single persistent streaming session
+```
+Session created → AsyncGenerator streaming input opened
+Message 1 → Push into generator → process events
+Message 2 → Push into same generator → continue streaming
+(Fast, continuous context, no SDK restarts)
+```
+
+## Key Concepts
+
+### Session State (BE-Owned)
+The backend maintains a `SessionEntry` per chat session:
+- Tracks connected clients (can be zero if FE disconnected)
+- Maintains streaming phase (idle, connecting, thinking, streaming)
+- Buffers events for reconnection sync
+- Auto-cleans after 5 minutes of FE inactivity
+
+### Message Priority (v0.8.55+)
+```typescript
+// Send message with priority
+ws.send({
+  type: "message",
+  content: "Debug this code",
+  priority: "now"  // "now" | "next" | "later"
+})
+```
+- **"now"** — Abort current query, restart with this message
+- **"next"** — Queue after current, run next
+- **"later"** — Append to queue, run last
+
+### Event Buffering on Reconnect
+When FE WS reconnects after disconnect:
+1. BE sends `session_state` with current phase + pending approval
+2. BE sends `turn_events` with all buffered events since last connection
+3. FE rebuilds chat UI state from buffered events
+4. No message loss (unless session cleaned up after 5min)
+
+## Common Patterns
+
+### Frontend: Send Message
+```typescript
+// In useChat hook or message input handler
+ws.send(JSON.stringify({
+  type: "message",
+  content: userInput,
+  priority: "now",  // Optional
+  images: [{ id: "img1", data: "base64..." }]  // Optional
+}));
+```
+
+### Frontend: Handle Reconnection
+```typescript
+function handleReconnect() {
+  // 1. WS open fires
+  // 2. Server sends session_state
+  const sessionState = JSON.parse(msg);
+  // 3. Server sends turn_events
+  const turnEvents = JSON.parse(msg);
+
+  // 4. FE rebuilds state from buffered events
+  turnEvents.events.forEach(event => {
+    chatStore.addEvent(event);
+  });
+
+  // 5. FE is now synced with BE
+}
+```
+
+### Backend: Session Lifecycle
+```typescript
+// 1. FE connects
+open(ws) {
+  const entry = activeSessions.get(sessionId);
+  if (!entry) {
+    // Create new session entry
+    activeSessions.set(sessionId, {
+      phase: "idle",
+      clients: new Set([ws]),
+      turnEvents: []
+    });
+  } else {
+    // Reconnect: clear cleanup timer, add client
+    entry.clients.add(ws);
+  }
+}
+
+// 2. FE sends message
+message(ws, data) {
+  const parsed = JSON.parse(data);
+  if (parsed.type === "message") {
+    // Abort current if streaming, wait for cleanup
+    if (entry.phase !== "idle") {
+      entry.abort.abort();
+      await entry.streamPromise;
+    }
+    // Start new streaming loop (detached)
+    entry.streamPromise = runStreamLoop(...);
+  }
+}
+
+// 3. Streaming loop runs independently
+async function runStreamLoop() {
+  for await (const event of chatService.sendMessage(...)) {
+    bufferAndBroadcast(sessionId, event);  // To all connected clients
+  }
+  setPhase(sessionId, "idle");  // Back to idle when done
+  if (entry.clients.size === 0) {
+    startCleanupTimer(sessionId);  // 5-min cleanup
+  }
+}
+
+// 4. FE disconnects
+close(ws) {
+  entry.clients.delete(ws);
+  // Stream continues! (BE owns the connection)
+  // Timer started if no more clients
+}
+```
+
+## Phase State Machine
+
+```
+     ┌─ initializing  (setup, session resume)
+     ↓
+  idle ←→ connecting  (waiting for first SDK event, heartbeat)
+     ↑         ↓
+     │    ┌──→ thinking  (extended thinking)
+     │    ↓  ↓
+     └─── streaming  (text/tool_use content)
+          ↑     ↓
+          └─────┘ (dynamic switch)
+```
+
+**Transitions:**
+- Heartbeat: `connecting` → (5s elapsed updates) → `thinking` (when content arrives)
+- Content: `thinking` → `streaming` (first text event)
+- Dynamic: `streaming` ↔ `thinking` (based on event types)
+- Done: Any → `idle` (stream complete, ready for next message)
+
+## WebSocket Messages (v0.8.55+)
+
+### Client → Server
+```typescript
+// Send message
+{ type: "message"; content: string; priority?: string; images?: {...}[] }
+
+// Approve tool
+{ type: "approval_response"; requestId: string; approved: boolean }
+
+// Cancel current
+{ type: "cancel" }
+
+// Handshake after open
+{ type: "ready" }
+```
+
+### Server → Client
+```typescript
+// Content
+{ type: "text"; content: string }
+{ type: "thinking"; content: string }
+
+// Tool execution
+{ type: "tool_use"; tool: string; input: unknown }
+{ type: "tool_result"; output: string; isError?: boolean }
+
+// User approval request
+{ type: "approval_request"; requestId: string; tool: string; input: unknown }
+
+// Session state (sent on open/ready)
+{ type: "session_state"; sessionId: string; phase: SessionPhase; pendingApproval: {...} | null }
+
+// Buffered events (on reconnect)
+{ type: "turn_events"; events: unknown[] }
+
+// Metadata
+{ type: "account_info"; accountId: string; accountLabel: string }
+{ type: "phase_changed"; phase: SessionPhase; elapsed?: number }
+{ type: "title_updated"; title: string }
+
+// Completion
+{ type: "done"; sessionId: string; contextWindowPct?: number }
+
+// Error
+{ type: "error"; message: string }
+
+// Keepalive
+{ type: "ping" }
+```
+
+## Benefits
+
+| Aspect | Before (v0.8.54) | After (v0.8.55) |
+|--------|------------------|-----------------|
+| **SDK Restarts** | Per message | Once per session |
+| **Context** | Resets between messages | Persistent |
+| **Startup Time** | 2-5s per message | Instant follow-ups |
+| **Reconnection** | Message loss | Event buffering ensures sync |
+| **Concurrency** | N/A | Multiple clients per session |
+| **Tool Approvals** | Restarts query | Integrated in stream |
+
+## Troubleshooting
+
+### Session Cleaned Up (No Longer Exists)
+**Cause:** FE disconnected for >5 minutes
+**Solution:** Create new session, FE reconnects with new sessionId
+
+### Events Missing After Reconnect
+**Cause:** Server-side event buffer (10k event limit) overflowed
+**Solution:** Flush buffer periodically or increase limit if needed
+
+### Phase Stuck in "Connecting"
+**Cause:** SDK subprocess not responding (120s timeout)
+**Solution:** Check environment (ANTHROPIC_API_KEY, network), see error message for hints
+
+### Multiple Clients Out of Sync
+**Cause:** Broadcast failed for one client, others ahead
+**Solution:** Evicted client will reconnect and re-sync from buffered events
+
+## Debugging
+
+### Enable Logging
+```bash
+# Check server logs for session lifecycle
+[chat] session=abc123 phase → connecting
+[chat] session=abc123 first SDK event after 1250ms: type=text
+[chat] session=abc123 stream completed (45 events)
+[chat] session=abc123 phase → idle
+```
+
+### Check Session State
+```typescript
+// On WS message handler
+console.log(`Session entry:`, activeSessions.get(sessionId));
+// Outputs: { phase, clients.size, pendingApprovalEvent, turnEvents.length }
+```
+
+### Monitor Reconnections
+```typescript
+// In WS open handler
+console.log(`FE reconnected (phase=${existing.phase}, clients=${existing.clients.size})`);
+// Tells you: active streaming, how many clients connected
+```
+
+## Performance Notes
+
+- **No SDK overhead:** Persistent streaming eliminates subprocess spawn overhead
+- **Event buffering:** Clients see all events after reconnect (max 10k events per turn)
+- **Memory:** Session entries cleaned after 5min (bounded memory usage)
+- **Latency:** Follow-up messages start immediately (no SDK init)
+
+---
+
+**For detailed architecture:** See `docs/system-architecture.md` → "Chat Streaming Flow" section
+**For API types:** See `src/types/api.ts` and `src/types/chat.ts`
+**For implementation:** See `src/server/ws/chat.ts` and `src/providers/claude-agent-sdk.ts`

package/docs/system-architecture.md

@@ -205,7 +205,47 @@ interface AIProvider {
 **Implementations:**
 - **claude-agent-sdk** (Primary) — @anthropic-ai/claude-agent-sdk, streaming, tool use. Reads model/effort/maxTurns/budget/thinking from config. Settings refreshed per query. Windows CLI fallback for Bun subprocess pipe issues. .env poisoning mitigation. **Multi-account support:** Injects account API token from AccountService instead of relying on ANTHROPIC_API_KEY env var when accounts configured.
 - **mock-provider** (Testing) — Returns canned responses
-- **Note:** CLI provider removed (v2); agent SDK is sole AI provider with Windows CLI fallback
+- **cursor-cli** (CLI-based) — Spawns `cursor-agent` CLI binary with NDJSON streaming. Extends `CliProvider` base class.
+- **codex/gemini** (Planned) — Pluggable via `CliProvider` extension (~100-150 lines each)
+
+#### Multi-Provider Architecture (v0.8.61+)
+
+PPM supports multiple AI providers through a generic `AIProvider` interface and extensible base classes:
+
+**Provider Types:**
+1. **SDK-based** (claude-agent-sdk) — Uses Anthropic SDK for rich features (approvals, thinking blocks)
+2. **CLI-based** (cursor-cli, codex, gemini) — Spawns external binary with NDJSON streaming
+
+**Base Classes:**
+- `AIProvider` interface — Defines required methods (createSession, sendMessage) + optional capabilities (abortQuery, getMessages, listSessionsByDir, ensureProjectPath)
+- `CliProvider` abstract class — Shared spawn/parse/abort logic for all CLI-spawning providers
+- Provider-specific subclasses implement: `buildArgs()`, `mapEvent()`, `extractSessionId()`, `isAvailable()`
+
+**Streaming Infrastructure:**
+- `parseNdjsonLines()` utility — Async generator that buffers partial TCP packets, yields complete JSON lines
+- `ChatEvent` union type — Normalized event format across all providers (text, tool_use, thinking, approval_request, system, done, error)
+- Event mappers translate provider-specific JSON → ChatEvent (e.g., Cursor's `reasoning` type → `thinking` event)
+
+**Provider Registration & Bootstrap:**
+- `ProviderRegistry` maintains active provider instances
+- `bootstrapProviders()` async function checks `isAvailable()` on CLI providers before registering
+- Graceful fallback: if Cursor binary not found, provider skips registration (no crash, logged as info)
+- Config type `AIProviderConfig.type` union: `"agent-sdk" | "cli" | "mock"`
+
+**CLI-Provider Features:**
+- **Session capture** — Extract session ID from provider's init event, re-key process tracking
+- **Workspace trust auto-retry** — Detect trust prompts in stderr, retry once with `--trust` flag
+- **Process lifecycle** — Track active processes per session, escalate SIGTERM → SIGKILL on abort
+- **History loading** — Override `listSessions()` to read native provider history (e.g., Cursor SQLite DAG)
+- **Graceful degradation** — Missing binary → provider skipped, not fatal
+
+**New Files (v0.8.61):**
+- `src/utils/ndjson-line-parser.ts` — NDJSON streaming parser
+- `src/providers/cli-provider-base.ts` — Abstract base class for CLI providers
+- `src/providers/cursor-cli/cursor-provider.ts` — CursorCliProvider implementation
+- `src/providers/cursor-cli/cursor-event-mapper.ts` — NDJSON → ChatEvent mapping
+- `src/providers/cursor-cli/cursor-history.ts` — SQLite DAG reader for Cursor history
+- `src/web/components/chat/provider-selector.tsx` — UI component for provider selection
 
 ---
 
@@ -453,7 +493,27 @@ Returns full updated config. Validates ranges/enums before writing.
 
 ---
 
-## Chat Streaming Flow
+## Chat Streaming Flow (Persistent AsyncGenerator Sessions)
+
+### Architecture Overview (v0.8.55+)
+
+PPM uses a **persistent streaming session** model instead of per-message query execution:
+
+**Key Changes:**
+- Provider maintains **long-lived AsyncGenerator streaming input** per chat session (not per message)
+- Follow-up messages **push into the existing generator** instead of abort-and-replace
+- **Single streaming loop** per session decoupled from WebSocket message handler
+- Message priority support: `now` (interrupt current), `next` (queue first), `later` (queue at end)
+- Supports image attachments in messages
+
+**Design Benefits:**
+- Continuous context preservation — multi-turn conversations flow naturally
+- No SDK subprocess restarts between messages (faster)
+- Clean separation: BE owns Claude connection, FE disconnect doesn't abort
+- Message buffering on reconnect — clients that lose WS connection sync turn events
+- Tool approvals don't restart the query — integrated into streaming loop
+
+### Message Flow
 
 ```
 User types: "Debug this function"
@@ -462,18 +522,26 @@ MessageInput.tsx calls useChat.sendMessage()
     ↓
 useChat opens WebSocket: WS /ws/project/:name/chat/:sessionId
     ↓
-Sends: { type: "message", content: "Debug..." }
+Sends: { type: "message", content: "Debug...", priority?: "now"|"next"|"later" }
+    ↓
+WS handler in chat.ts receives message
     ↓
-Server routes to ChatService.streamMessage()
+If already streaming with different content → abort previous + wait cleanup
+If streaming, new message priority determines queue behavior:
+    • priority: "now" → abort current, restart with new content
+    • priority: "next" → push into pending queue (higher priority)
+    • priority: "later" → push to end of queue (FIFO)
+    ↓
+runStreamLoop() executes in detached async context
     ↓
 ChatService calls provider.sendMessage() (async generator)
     ↓
-Provider (Claude SDK) streams response:
-    1. Yields: { type: "text", content: "Here's what..." }
-    2. Yields: { type: "text", content: " happens..." }
-    3. Yields: { type: "tool_use", tool: "read_file", input: {...} }
+Provider (Claude SDK) yields events:
+    1. { type: "text", content: "Here's what..." }
+    2. { type: "text", content: " happens..." }
+    3. { type: "tool_use", tool: "read_file", input: {...} }
     ↓
-ChatService wraps as WebSocket messages:
+Stream loop buffers + broadcasts to all connected clients:
     { type: "text", content: "Here's what..." }
     { type: "text", content: " happens..." }
     { type: "tool_use", tool: "read_file", input: {...} }
@@ -485,15 +553,112 @@ User sees tool approval prompt, clicks "Approve"
     ↓
 Client sends: { type: "approval_response", requestId, approved: true }
     ↓
-ChatService.onToolApproval() executes tool (file_read, git commands, etc.)
+Provider continues streaming with tool result (no restart)
     ↓
-Provider continues streaming with tool result
+If multiple messages queued, next message processes after done event
     ↓
 Final response streamed, then: { type: "done", sessionId }
     ↓
-useChat closes WebSocket, saves message to store
+Phase transitions to idle, clients can send new message
+    ↓
+useChat saves message to store, displays in chat history
 ```
 
+### Session State Management
+
+**Session Entry** (BE-owned, persists across FE disconnections):
+```typescript
+interface SessionEntry {
+  providerId: string;              // Which AI provider (e.g., "claude")
+  clients: Set<ChatWsSocket>;      // Connected FE clients (may be empty)
+  abort?: AbortController;         // Current stream abort handle
+  projectPath?: string;            // Project context
+  projectName?: string;
+  pingIntervals: Map<...>;         // Per-client keepalive
+  phase: SessionPhase;             // "initializing" | "connecting" | "thinking" | "streaming" | "idle"
+  cleanupTimer?: ReturnType<...>;  // Auto-cleanup if no FE reconnects (5min)
+  pendingApprovalEvent?: {...};    // Current tool approval waiting
+  turnEvents: unknown[];           // Buffered events (for reconnect sync)
+  streamPromise?: Promise<void>;   // Track ongoing runStreamLoop
+  permissionMode?: string;         // Sticky permission mode for session
+}
+```
+
+**Client Connection States:**
+- **Active streaming + FE connected** → Events broadcast to all clients in real-time
+- **Active streaming + FE disconnected** → Events buffered in turnEvents array, BE stream continues
+- **FE reconnects** → Receive session_state + buffered turnEvents, resync with stream
+- **Idle (no query running)** → Phase is "idle", ready for next message
+- **Idle + no FE for 5min** → Cleanup timer removes session from memory
+
+### Follow-up Messages
+
+**Abort-and-Replace Pattern:**
+```typescript
+if (entry.phase !== "idle" && entry.abort) {
+  console.log(`[chat] aborting current query for new message`);
+  entry.abort.abort();
+  await entry.streamPromise;  // Wait for cleanup
+  // Re-fetch entry — may have been mutated during cleanup
+  entry = activeSessions.get(sessionId)!;
+}
+```
+
+**Multiple Message Queueing:**
+- First message: immediately starts runStreamLoop
+- Second message (while streaming): abort current, wait, start new runStreamLoop
+- Priority modes (future): could queue messages for intelligent interleaving
+
+### WebSocket Reconnection Sync
+
+```
+FE WebSocket closes (network issue, tab closes)
+    ↓
+BE keeps session alive, streaming continues
+    ↓
+FE reconnects: WS /ws/project/:name/chat/:sessionId
+    ↓
+open() handler checks activeSessions.get(sessionId)
+    ↓
+If exists (entry found):
+    1. Clear cleanup timer (FE is back)
+    2. Send session_state with current phase + pendingApproval
+    3. If phase !== "idle", send buffered turnEvents
+    4. Add WS to clients Set
+    ↓
+FE processes session_state, renders current phase
+    ↓
+FE applies buffered events to rebuild turn state
+    ↓
+FE displays: "reconnected, current phase: streaming" etc.
+```
+
+### Phase Transitions
+
+```
+idle → initializing → connecting → thinking/streaming ↔ thinking/streaming → idle
+  ^                                      ↑                                    ↓
+  └──────────────────────────────────────────────────────────────────────────┘
+```
+
+**Phase Descriptions:**
+- **idle** — No query running, ready to accept new message
+- **initializing** — Preparing (permission checks, session resume)
+- **connecting** — Waiting for first SDK event (heartbeat: "connecting" with elapsed time every 5s)
+- **thinking** — Receiving thinking content (extended thinking)
+- **streaming** — Receiving text/tool_use content (dynamic switch between thinking/streaming)
+
+### Image Attachment Support
+
+Messages can now include images:
+```typescript
+type ChatWsClientMessage =
+  | { type: "message"; content: string; images?: { id: string; data: string }[]; priority?: string }
+  | ...
+```
+
+Images are passed to provider's message context and included in tool input/output.
+
 ---
 
 ## Terminal Flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.59",
+  "version": "0.8.61",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/providers/claude-agent-sdk.ts

@@ -502,22 +502,24 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
         // Log all system events for debugging SDK lifecycle
         if (msg.type === "system") {
-          console.log(`[sdk] session=${sessionId} system: subtype=${(msg as any).subtype ?? "none"} ${JSON.stringify(msg).slice(0, 500)}`);
-        }
-
-        // Capture SDK session metadata from init message
-        if (msg.type === "system" && (msg as any).subtype === "init") {
-          const initMsg = msg as any;
-          // SDK may assign a different session_id than our UUID
-          if (initMsg.session_id && initMsg.session_id !== sessionId) {
-            // Persist mapping so resume works after server restart
-            setSessionMapping(sessionId, initMsg.session_id);
-            // Update our in-memory mapping
-            const oldMeta = this.activeSessions.get(sessionId);
-            if (oldMeta) {
-              this.activeSessions.set(initMsg.session_id, { ...oldMeta, id: initMsg.session_id });
+          const subtype = (msg as any).subtype ?? "none";
+          console.log(`[sdk] session=${sessionId} system: subtype=${subtype} ${JSON.stringify(msg).slice(0, 500)}`);
+
+          // Capture SDK session metadata from init message
+          if (subtype === "init") {
+            const initMsg = msg as any;
+            if (initMsg.session_id && initMsg.session_id !== sessionId) {
+              setSessionMapping(sessionId, initMsg.session_id);
+              const oldMeta = this.activeSessions.get(sessionId);
+              if (oldMeta) {
+                this.activeSessions.set(initMsg.session_id, { ...oldMeta, id: initMsg.session_id });
+              }
             }
           }
+
+          // Yield system events so streaming loop can transition phases
+          // (e.g. connecting → thinking when hooks/init arrive)
+          yield { type: "system" as any, subtype } as any;
           continue;
         }
 

package/src/providers/mock-provider.ts

@@ -92,8 +92,13 @@ export class MockProvider implements AIProvider {
     const abortController = new AbortController();
     this.activeAborts.set(sessionId, abortController);
 
+    // Simulate SDK system events (hooks, init) — real SDK emits these before content
+    yield { type: "system" as any, subtype: "hook_started" } as any;
+    await sleep(50);
+    yield { type: "system" as any, subtype: "init" } as any;
+
     // Simulate thinking delay
-    await sleep(300);
+    await sleep(250);
 
     // Pick a response
     const responseText =

package/src/server/index.ts

@@ -14,6 +14,7 @@ import { databaseRoutes } from "./routes/database.ts";
 import { fsBrowseRoutes } from "./routes/fs-browse.ts";
 import { accountsRoutes } from "./routes/accounts.ts";
 import { proxyRoutes } from "./routes/proxy.ts";
+import { browserPreviewRoutes } from "./routes/browser-preview.ts";
 import { initAdapters } from "../services/database/init-adapters.ts";
 import { terminalWebSocket } from "./ws/terminal.ts";
 import { chatWebSocket } from "./ws/chat.ts";
@@ -126,6 +127,9 @@ app.route("/proxy", proxyRoutes);
 app.use("/api/*", authMiddleware);
 app.get("/api/auth/check", (c) => c.json(ok(true)));
 
+// Browser preview reverse proxy — proxies to localhost:<port> for iframe embedding
+app.route("/api/preview", browserPreviewRoutes);
+
 // Filesystem operations (browse, list, read, write) — consolidated in fs-browse route
 app.route("/api/fs", fsBrowseRoutes);
 

package/src/server/routes/browser-preview.ts

@@ -0,0 +1,89 @@
+import { Hono } from "hono";
+
+/**
+ * Browser preview reverse proxy — forwards requests to localhost:<port>.
+ * Mounted at /api/preview/:port/* so the frontend iframe can load
+ * any localhost dev server through PPM's own origin (avoiding CORS/framing issues).
+ */
+export const browserPreviewRoutes = new Hono();
+
+/** Only allow proxying to localhost ports (security: prevent SSRF) */
+function isValidPort(port: string): boolean {
+  const n = parseInt(port, 10);
+  return !isNaN(n) && n >= 1 && n <= 65535;
+}
+
+browserPreviewRoutes.all("/:port{[0-9]+}/*", async (c) => {
+  const port = c.req.param("port");
+  if (!isValidPort(port)) {
+    return c.text("Invalid port", 400);
+  }
+
+  // Build target URL — strip the /api/preview/:port prefix
+  const url = new URL(c.req.url);
+  const prefix = `/api/preview/${port}`;
+  const targetPath = url.pathname.slice(prefix.length) || "/";
+  const targetUrl = `http://localhost:${port}${targetPath}${url.search}`;
+
+  try {
+    // Forward the request with original method, headers, and body
+    const headers = new Headers(c.req.raw.headers);
+    // Remove host header so target server sees localhost
+    headers.delete("host");
+
+    const resp = await fetch(targetUrl, {
+      method: c.req.method,
+      headers,
+      body: ["GET", "HEAD"].includes(c.req.method) ? undefined : c.req.raw.body,
+      redirect: "manual",
+    });
+
+    // Clone response headers, remove framing restrictions so iframe works
+    const respHeaders = new Headers(resp.headers);
+    respHeaders.delete("x-frame-options");
+    respHeaders.delete("content-security-policy");
+
+    return new Response(resp.body, {
+      status: resp.status,
+      statusText: resp.statusText,
+      headers: respHeaders,
+    });
+  } catch {
+    return c.text(`Cannot connect to localhost:${port}`, 502);
+  }
+});
+
+// Handle root path (no trailing slash)
+browserPreviewRoutes.all("/:port{[0-9]+}", async (c) => {
+  const port = c.req.param("port");
+  if (!isValidPort(port)) {
+    return c.text("Invalid port", 400);
+  }
+
+  const url = new URL(c.req.url);
+  const targetUrl = `http://localhost:${port}/${url.search}`;
+
+  try {
+    const headers = new Headers(c.req.raw.headers);
+    headers.delete("host");
+
+    const resp = await fetch(targetUrl, {
+      method: c.req.method,
+      headers,
+      body: ["GET", "HEAD"].includes(c.req.method) ? undefined : c.req.raw.body,
+      redirect: "manual",
+    });
+
+    const respHeaders = new Headers(resp.headers);
+    respHeaders.delete("x-frame-options");
+    respHeaders.delete("content-security-policy");
+
+    return new Response(resp.body, {
+      status: resp.status,
+      statusText: resp.statusText,
+      headers: respHeaders,
+    });
+  } catch {
+    return c.text(`Cannot connect to localhost:${port}`, 502);
+  }
+});