feat: embeddable web browser as a canvas tile (phases 0–2)

[srid]

Kolu currently has no webview / iframe capability. Adding one unlocks dev-server preview (the killer use case), doc/dashboard embeds while pairing, and — as a free side-effect — inclusion in tab-capture video recording (#632), since getDisplayMedia() already records the whole tab.

Architectural commitments

• A browser is a first-class canvas tile, not a sub-panel of a terminal. Rationale: Kolu's direction is mode-less canvas workspace (commit 6318813); tying the browser's lifetime to a terminal's parentId would complect placement with terminal state and force preview to die when the terminal running pnpm dev restarts. Keep tile identity = URL, nothing more.
• Tile identity is just a URL. No repo/branch/port metadata on the tile. Ports are globally unique on the host, so there's nothing to disambiguate.
• Transparent localhost rewrite. User types http://localhost:5173 in the URL bar; Kolu detects the localhost host and routes through the Hono reverse proxy. Proxy is invisible infrastructure, not a separate mode.

Phase 0 — Browser canvas tile, any URL, no proxy

Drop a tile on the canvas, type any URL, renders in an iframe. Full canvas-tile citizenship: movable, resizable, multi-instance, captured by recording for free. Handle X-Frame-Options / frame-ancestors: none blocks explicitly — detect and show an "open externally" fallback instead of a silent blank tile. Useful standalone for docs, Figma, Grafana, the Kolu website. localhost:* silently fails at this phase (or shows a hint that Phase 1 is needed).

• Browser tile component (iframe + minimal chrome: URL bar, reload, open-externally)
• Canvas-tile integration (drag, resize, focus, persistence)
• X-Frame-Options / CSP frame-ancestors block detection + fallback UI
• Recording verification (open browser tile during recording → appears in captured .webm)

Phase 1 — Transparent localhost rewrite via Hono reverse proxy

Same URL bar; http://localhost:NNNN or 127.0.0.1:NNNN detected and rewritten through a Hono proxy route before loading. Choose subdomain-based proxy from the start (NNNN.preview.<kolu-host>) rather than path-prefix, so Vite HMR WebSockets and absolute asset paths just work. SSRF guard: allowlist ports that some terminal has announced recently (plus user-confirmed manual entries). Handle WebSocket upgrade in the proxy for HMR. Tile model doesn't change — proxy is a URL resolver inside the fetch path.

• Hono proxy route (NNNN.preview.<host> → 127.0.0.1:NNNN)
• WebSocket upgrade passthrough (Vite HMR)
• Client-side URL rewrite in the tile fetch path (localhost / 127.0.0.1 → proxy subdomain)
• SSRF guard: port allowlist from announced-ports + explicit user confirmation
• Smoke test with Vite, Next, Astro, plain python -m http.server

Phase 2 — Port discovery from terminal stdout

Scrape terminal stdout for Local: http://localhost:NNNN patterns (Vite, Next, Astro, etc.). Ephemeral global suggestion list, labeled by announcing terminal ("5173 — from kolu:savage-touch"). Surface via: command palette entry ("Open preview…"), terminal context menu, or a small chrome-bar indicator. Pill-tree indicator per branch: derived at render time from "any terminal under this branch has a recently-announced URL" — no per-tile storage.

• Stdout scanner (regex for common dev-server announcement patterns)
• Ephemeral suggestion list (keyed by port; labeled by terminal)
• Command palette entry: "Open preview…"
• Terminal context-menu entry: "Open preview for this terminal"
• Pill-tree branch indicator (derived, no storage)

Non-goals for this issue

• Auto-snap / tiling placement behaviors — tracked in feat: tiling-WM-style pinned relative placement for canvas tiles #634.
• Recording-specific choreography — tab recording captures the canvas transparently.
• Multi-user auth on the proxy — single-user local-first for now.

Three-worktree stress test

Three dev servers on three unique ports → three tiles, each a URL. Canvas composites all three; getDisplayMedia() records all three in one frame. No per-tile repo/branch metadata needed because ports are globally unique.

[srid]

Design rationale & rejected alternatives

Preserving the reasoning path so future agents don't re-propose paths we've already walked.

Hickey-lens findings

• SubPanelState as parallel optionals is a sum type in disguise. packages/client/src/terminal/useSubPanel.ts:8-31 already encodes "sub-panel shows nothing OR a child terminal tab." Adding browserUrl?: string alongside activeSubTab? produces three parallel optionals with unenforced invariants (at most one non-null, panel must be expanded iff content exists, focus target validity). This is classic complecting of variant choice with null-as-tag. If a browser were to share the sub-panel slot (it shouldn't — see below), the right model would be a discriminated union:

  type SubPanelContent =
    | { kind: "empty" }
    | { kind: "tab"; tabId: TerminalId }
    | { kind: "browser"; url: string };

• Per-terminal browser binding fragments preview identity. Every consumer (sub-panel render, proxy router, recording composer, discovery) would have to independently reconstruct "which URL belongs to this terminal" from convention rather than from one stored association. When the terminal is closed or restarted, the binding orphans silently.

Lowy-lens findings (volatility axes)

Drawing boundaries around what will change:

• Transport (high volatility): path-prefix vs subdomain proxy, HMR WebSocket rewriting, asset-path fixup. Committing to subdomain-from-day-1 contains this. Absorb all transport concerns in the Hono proxy layer; the tile's fetch path just sees a URL.
• Placement (highest volatility — product iterates constantly): right-split, float-PiP, fullscreen, grid, snap-adjacent. Placement cannot be structurally bound to any consumer. Extracted to feat: tiling-WM-style pinned relative placement for canvas tiles #634 as a general canvas capability.
• Port discovery (medium volatility): manual → stdout scrape → LSP $/progress → vendor hooks. Put discovery behind an event stream (portAnnounced(terminalId, port)) so consumers don't know how it was detected.
• Identity (should be low volatility): Settled on "tile identity is a URL" — nothing else. Port uniqueness on the host means no disambiguation metadata needed.
• Auth/SSRF policy: belongs in a separate guard in the Hono router, not inside the proxy itself. Topology changes (multi-user, public deploy) change only that guard.

Rejected alternatives and why

1. Browser as a right-split of a terminal (sub-panel sibling of child-terminal tabs).
Original user instinct. Rejected because:

• Wrong identity axis. The terminal that runs pnpm dev often isn't the terminal you're editing in.
• Port outlives terminal. Kill terminal A, restart it → port may still be live, but the sub-panel binding is gone.
• Overloads SubPanelState with a second variant (see Hickey finding above).
• Complects placement (a render-time concern) with terminal lifecycle (a process concern).

2. PreviewSession as a new server-side entity keyed by repo origin.
Rejected because:

• Kolu has no project/workspace/session concept. Inventing one is over-engineering.
• Breaks on worktrees: three worktrees of the same repo share origin but run three different dev servers.

3. Worktree-scoped PreviewSession keyed by git rev-parse --show-toplevel.
Closer, but rejected because:

• Still a new server entity with its own RPC surface and lifecycle.
• Became unnecessary once we noticed ports are globally unique on a host — OS enforces this. If tile identity is the port (or the URL containing it), there's nothing to scope.

4. Per-tile { repo, branch, port } triple.
Rejected because the { repo, branch } pair is dead weight. Port alone identifies the preview unambiguously; repo/branch metadata would have to be kept in sync against terminal state with no payoff.

5. "Port mode" vs "URL mode" toggle on the tile.
Rejected in favor of transparent localhost rewrite. One URL bar behaves like any browser's; http://localhost:* is detected and routed through the proxy invisibly. Users never think about proxy vs direct — matches developer muscle memory.

Why phases 0 / 1 / 2 and not 0 / 1 / 2 / 3

An earlier sketch had a Phase 3 for "placement presets + recording choreography." Collapsed because:

• Placement is a canvas-wide concern, not a browser-tile concern → extracted to feat: tiling-WM-style pinned relative placement for canvas tiles #634.
• Recording choreography evaporates: getDisplayMedia() captures the whole tab, so any tile placement is already in frame. No compositing code needed.

What remains is genuinely two things (browser tile + proxy) and one optional polish (port discovery as URL suggestions) — three phases, clean decomposition.

Three-worktree stress test (how we arrived at "URL is the identity")

Scenario: three Kolu worktrees, each running a dev server on a unique port, wanting 2–3 previews visible at once.

• Under per-terminal binding: breaks (one terminal owns the preview, can't compose).
• Under repo-scoped session: breaks (three worktrees share one repo origin).
• Under worktree-scoped session: works, but introduces an entity.
• Under "tile is a URL": works trivially. Three tiles, three URLs, canvas composites all three. getDisplayMedia() captures all three in one frame.

This test is what pushed the design to its final minimal form.