@venturewild/workspace 0.6.28 → 0.6.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturewild/workspace",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "Claude Code Web — Replit/Lovable-style chat-first browser UI that wraps the AI agent already installed on your machine.",
   "license": "MIT",
   "bin": {

package/server/src/index.mjs

@@ -58,6 +58,16 @@ import { DaemonSupervisor } from './daemon-supervisor.mjs';
 import { TunnelWatchdog } from './tunnel-watchdog.mjs';
 import { SyncControl } from './sync.mjs';
 import { detectPreviewPorts, checkPort } from './preview.mjs';
+import {
+  LocalPreviewRegistry,
+  previewTokenFromHeaders,
+  proxyHttpToPort,
+  proxyWsUpgrade,
+  reconcilePreviews,
+  previewUrlFor,
+  PREVIEW_ENDED_PAGE,
+} from './preview-proxy.mjs';
+import { createPreviewRails } from './preview-rails.mjs';
 import { createBazaar } from './bazaar/core.mjs';
 import { createCanvas } from './canvas/core.mjs';
 import { createCanvasRails } from './canvas-rails.mjs';
@@ -434,6 +444,9 @@ export async function createServer(overrides = {}) {
   // Cross-host shared chat sessions client (Phase 2). Inert without an account /
   // bmo-sync URL; only used for SHARED workspaces (local ones stay per-host).
   const sessionRails = overrides.sessionRails || createSessionRails(config, config.account);
+  // Shared-preview registry client (ticket tk-5d09bf04-5). Inert until login;
+  // the dev-port watcher (below) publishes/heartbeats/retires live previews here.
+  const previewRails = overrides.previewRails || createPreviewRails(config);
   // Shared-workspace membership client (sharing slice — design §4). The account
   // token is kept top-level on config (out of the broadcast `config.account`), so
   // pass it explicitly, mirroring the CLI `wild-workspace workspace …`. Inert (and
@@ -1081,6 +1094,34 @@ export async function createServer(overrides = {}) {
     );
   }
 
+  // --- shared-preview reverse-proxy (ticket tk-5d09bf04-5) ------------------
+  // MUST be the FIRST middleware. A `pv-<token>` Host means a viewer is looking
+  // at a dev server running on THIS machine (routed here through the tunnel:
+  // vw-proxy → bmo-sync preview-registry → this account's daemon → :5173). We
+  // reverse-proxy it straight to the local dev port and return — deliberately
+  // BEFORE the auth wall + the security-headers/CSP middleware, because the dev
+  // server is the user's OWN product on its OWN origin: the app's
+  // X-Frame-Options/CSP would break it, and access is anyone-with-link (the
+  // unguessable token IS the capability — decision D3). SSRF-safe: the only
+  // reachable target is a loopback port THIS server itself registered, and the
+  // relay strips any client-forged X-Forwarded-* so the host can't be spoofed
+  // from off-box. Populated by the dev-port watcher (Part B).
+  const localPreviews = overrides.localPreviews || new LocalPreviewRegistry();
+  app.use('*', async (c, next) => {
+    const token = previewTokenFromHeaders((n) => c.req.header(n));
+    if (!token) return next();
+    const port = localPreviews.portForToken(token);
+    if (!port) {
+      // Unknown / expired token → a graceful "ended" page, never the SPA shell.
+      return c.body(PREVIEW_ENDED_PAGE, 404, {
+        'content-type': 'text/html',
+        'cache-control': 'no-store',
+      });
+    }
+    localPreviews.heartbeat(token);
+    return proxyHttpToPort(port, c.req.raw);
+  });
+
   // Security headers on every response (SECURITY.md S7). Set AFTER next() so they
   // land on static-asset + SPA-fallback responses too. Referrer-Policy: no-referrer
   // also backstops S1 — a stale `?t=` in the URL can't leak via the Referer header.
@@ -2909,6 +2950,46 @@ export async function createServer(overrides = {}) {
     return c.json({ port, host, listening: await checkPort(port, host) });
   });
 
+  // The live previews to show in this workspace's Live view (ticket tk-5d09bf04-5,
+  // Part C). Combines the previews THIS server hosts (`mine`) with members'
+  // previews on the rails (membership-gated by the shared slug). Each carries the
+  // public `pv-` URL the iframe loads; `mine` entries also carry the local port so
+  // the owner viewing on THIS machine can load localhost directly (no tunnel hop).
+  // A non-member viewing a raw `pv-` link never calls this — they load the link.
+  app.get('/api/preview/live', async (c) => {
+    const forbidden = require(c, 'preview');
+    if (forbidden) return forbidden;
+    const byToken = new Map();
+    for (const e of localPreviews.list()) {
+      byToken.set(e.token, {
+        token: e.token,
+        url: previewUrlFor(config.shareBaseUrl, e.token),
+        port: e.port, // owner-only convenience (local fast path); harmless to expose to the owner
+        label: e.initiator || config.account?.email || 'You',
+        mine: true,
+        startedAt: e.startedAt,
+      });
+    }
+    const slug = sharedSlugFor(c);
+    if (slug && previewRails.capable) {
+      const r = await previewRails.listWorkspace(slug);
+      if (r.ok) {
+        for (const p of r.previews) {
+          if (byToken.has(p.token)) continue; // a local (mine) entry always wins
+          byToken.set(p.token, {
+            token: p.token,
+            url: p.url || previewUrlFor(config.shareBaseUrl, p.token),
+            label: p.label || p.owner_email || 'A teammate',
+            mine: false,
+            startedAt: p.created_at ? p.created_at * 1000 : Date.now(),
+          });
+        }
+      }
+    }
+    const previews = [...byToken.values()].sort((a, b) => b.startedAt - a.startedAt);
+    return c.json({ previews, shared: Boolean(slug) });
+  });
+
   // --- bazaar (producer/remix marketplace — §3.7) ---------------------------
   // The shelf + ledger state for the UI. Live updates ride the chat chunk stream
   // (agent tool results) and the /preview/match broadcast below — never a watcher.
@@ -3615,12 +3696,74 @@ export async function createServer(overrides = {}) {
     } catch { /* best-effort — restart-server falls back to a health probe */ }
   }
 
+  // --- shared-preview dev-port watcher (ticket tk-5d09bf04-5, Part B) --------
+  // Proactively detects the user's local dev servers and keeps each one published
+  // as a live `pv-` preview (so a collaborator's Live view shows it even when the
+  // owner isn't looking). Only runs when logged in (a `pv-` link needs the
+  // tunnel); degrade-never below it. Tagged with the boot/default workspace's
+  // shared slug for member discovery (the picker covers the multi-server edge).
+  // Skipped under the test runner; tests drive reconcilePreviews directly.
+  let previewTimer = null;
+  function defaultSharedSlug() {
+    try {
+      const entry = getWorkspace(config.workspaceId, registryEnv);
+      return entry?.kind === 'shared' && entry.shared?.slug ? entry.shared.slug : null;
+    } catch {
+      return null;
+    }
+  }
+  async function previewWatcherTick() {
+    if (!previewRails.capable) {
+      localPreviews.sweep();
+      return;
+    }
+    await reconcilePreviews({
+      detect: () => detectPreviewPorts(),
+      registry: localPreviews,
+      rails: previewRails,
+      slug: defaultSharedSlug(),
+      initiator: config.account?.email || config.account?.slug || null,
+      selfPort: config.port,
+    });
+  }
+  if (
+    process.env.VITEST !== 'true' &&
+    config.nodeEnv !== 'test' &&
+    !overrides.previewWatcherDisabled
+  ) {
+    previewWatcherTick().catch((e) => log('[preview]', `watcher tick failed: ${e?.message || e}`));
+    previewTimer = setInterval(() => {
+      previewWatcherTick().catch((e) => log('[preview]', `watcher tick failed: ${e?.message || e}`));
+    }, 20_000);
+    if (previewTimer.unref) previewTimer.unref();
+  }
+
   // --- websocket bridge ---
   // The power-user terminal (T1) loads node-pty lazily + optionally — same loader as
   // in-app sign-in. Overridable so tests can inject a deterministic fake PTY.
   const ptyLoader = overrides.ptyLoader || defaultPtyLoader;
   const wss = new WebSocketServer({ noServer: true });
+  // Dedicated upgrader for shared-preview HMR websockets (ticket tk-5d09bf04-5).
+  // Kept separate from `wss` so its connections never reach the chat/activity/pty
+  // 'connection' wiring — a preview ws is bridged straight to the dev server.
+  const previewWss = new WebSocketServer({ noServer: true });
   httpServer.on('upgrade', async (req, socket, head) => {
+    // Shared-preview WS first: a `pv-<token>` Host upgrading ANY path is the dev
+    // server's HMR (or any ws it exposes). Bridge it to the local dev port,
+    // bypassing the app's WS auth (the dev server is the user's own product, and
+    // the token is the capability). Same SSRF guard as the HTTP path: only a
+    // port THIS server registered is reachable.
+    const previewToken = previewTokenFromHeaders((n) => req.headers[n]);
+    if (previewToken) {
+      const port = localPreviews.portForToken(previewToken);
+      if (!port) {
+        socket.destroy();
+        return;
+      }
+      localPreviews.heartbeat(previewToken);
+      proxyWsUpgrade({ previewWss, req, socket, head, port });
+      return;
+    }
     const reqUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
     const supported = ['/ws/chat', '/ws/activity', '/ws/pty'];
     if (!supported.includes(reqUrl.pathname)) {
@@ -3865,6 +4008,8 @@ export async function createServer(overrides = {}) {
     app,
     httpServer,
     wss,
+    localPreviews,
+    previewRails,
     activityBus,
     inboxWatcher,
     tokenRegistry,
@@ -3879,6 +4024,7 @@ export async function createServer(overrides = {}) {
     async stop() {
       try { clearTimeout(autoWakeTimer); } catch {}
       try { if (bazaarSyncTimer) clearInterval(bazaarSyncTimer); } catch {}
+      try { if (previewTimer) clearInterval(previewTimer); } catch {}
       for (const t of currentTurns.values()) {
         try { t.session.close(); } catch {}
       }

package/server/src/preview-proxy.mjs

@@ -0,0 +1,417 @@
+// Shared-preview reverse-proxy (ticket tk-5d09bf04-5).
+//
+// WHY: in a shared workspace only the machine running a dev server can see its
+// preview. The Live-view iframe used to load a literal `http://localhost:PORT`,
+// which the browser resolves to the *viewer's own* machine — so every remote
+// viewer (a collaborator, or the owner on their phone via the public URL) got a
+// blank pane. A shared workspace is N peer servers; files sync, processes don't.
+//
+// THE FIX (decision D1/A): give each running dev server its own temporary
+// capability host `pv-<rand>.venturewild.llc`, routed through the EXISTING
+// tunnel back to the host actually running it:
+//
+//   browser → vw-proxy → bmo-sync (preview registry: token→account→daemon)
+//           → daemon (forwards to :5173, UNCHANGED)
+//           → THIS server, which sees `X-Forwarded-Host: pv-<rand>.…`
+//           → reverse-proxies EVERYTHING to http://127.0.0.1:<devport>
+//
+// A separate ORIGIN (its own host) means the dev server owns the root, so its
+// absolute asset paths (`/assets/*`, `/@vite/client`) and its HMR websocket all
+// resolve correctly — the thing a same-origin path-proxy can't do (decision: the
+// path-proxy was rejected as fragile).
+//
+// SECURITY: this module ONLY ever targets `127.0.0.1:<port>` for a port that is
+// (a) currently in the LocalPreviewRegistry, i.e. one THIS server detected +
+// registered itself. There is no caller-controlled host/port — no SSRF, no
+// internal port scanner. A server only ever receives `pv-` requests for tokens
+// it minted (bmo-sync routes a token to the account that registered it, whose
+// daemon forwards to this same server), so the local map is authoritative.
+
+import { customAlphabet } from 'nanoid';
+import { WebSocket } from 'ws';
+
+// `pv-` + 12 lowercase-alnum chars. Stays inside bmo-sync's slug shape
+// (`^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$`, 3–30 chars) so vw-proxy forwards it with
+// no change, and ~36^12 of entropy makes the link an unguessable capability.
+export const PREVIEW_TOKEN_PREFIX = 'pv-';
+const TOKEN_BODY_LEN = 12;
+const mintBody = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', TOKEN_BODY_LEN);
+
+// Lifetime defaults (live-only, decision D2). The owning server heartbeats every
+// ~PREVIEW_HEARTBEAT_MS; an entry that misses several beats (machine crashed,
+// slept, or disconnected) auto-expires so dead links never accumulate.
+export const PREVIEW_HEARTBEAT_MS = 30_000;
+export const PREVIEW_TTL_MS = 100_000; // ~3 missed heartbeats
+
+/** Mint a fresh preview token (e.g. "pv-7a3f2b9c1d0e"). */
+export function mintPreviewToken() {
+  return `${PREVIEW_TOKEN_PREFIX}${mintBody()}`;
+}
+
+// A host is a preview host iff its leftmost label is a `pv-` token. Accepts the
+// public form (`pv-xxx.venturewild.llc`), a bare token, an explicit port, and is
+// case-insensitive. Returns the token (lowercased) or null.
+export function parsePreviewToken(host) {
+  if (!host || typeof host !== 'string') return null;
+  const bare = host.trim().toLowerCase().split(':')[0]; // strip any :port
+  if (!bare) return null;
+  const label = bare.split('.')[0]; // leftmost DNS label (or the whole bare token)
+  if (!label.startsWith(PREVIEW_TOKEN_PREFIX)) return null;
+  // Validate the full slug shape so a malformed/oversized label can't slip
+  // through as a "token" and key the registry with junk.
+  if (!/^pv-[a-z0-9]{4,40}$/.test(label)) return null;
+  return label;
+}
+
+// Pick the token to route on: prefer the relay-stamped X-Forwarded-Host (the
+// public subdomain the visitor actually typed), falling back to Host for genuine
+// local testing. `getHeader` is a (name) => value|undefined accessor.
+export function previewTokenFromHeaders(getHeader) {
+  const fwd = getHeader('x-forwarded-host');
+  return parsePreviewToken(fwd) || parsePreviewToken(getHeader('host'));
+}
+
+// ---------------------------------------------------------------------------
+// LocalPreviewRegistry — the previews THIS server is hosting (one per dev port).
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks the dev-server previews this machine is currently serving. Keyed by
+ * port (a machine has at most one dev server per port). Each entry carries the
+ * minted token, the workspace it belongs to, and who started it, so the canvas
+ * can default a viewer to their own preview and list the rest in a picker (D2).
+ *
+ * `nowFn` is injectable so tests drive expiry without real clocks.
+ */
+export class LocalPreviewRegistry {
+  constructor({ ttlMs = PREVIEW_TTL_MS, nowFn = () => Date.now() } = {}) {
+    this.ttlMs = ttlMs;
+    this.now = nowFn;
+    this.byPort = new Map(); // port -> entry
+    this.byToken = new Map(); // token -> entry (same object)
+  }
+
+  /**
+   * Register (idempotently) a preview for a local dev port. Re-registering the
+   * same (workspaceId, port) just refreshes its heartbeat and returns the
+   * existing entry — so the dev-port poller can call this every tick without
+   * minting a new token each time.
+   */
+  register({ port, workspaceId, initiator = null, label = null }) {
+    const p = Number(port);
+    if (!Number.isInteger(p) || p < 1 || p > 65535) {
+      throw new Error(`invalid preview port: ${port}`);
+    }
+    const existing = this.byPort.get(p);
+    if (existing && existing.workspaceId === workspaceId) {
+      existing.lastSeen = this.now();
+      if (initiator != null) existing.initiator = initiator;
+      if (label != null) existing.label = label;
+      return existing;
+    }
+    // Port reused for a different workspace → retire the stale entry first.
+    if (existing) this.remove(existing.token);
+    const now = this.now();
+    const entry = {
+      token: mintPreviewToken(),
+      port: p,
+      workspaceId: workspaceId ?? null,
+      initiator,
+      label,
+      startedAt: now,
+      lastSeen: now,
+    };
+    this.byPort.set(p, entry);
+    this.byToken.set(entry.token, entry);
+    return entry;
+  }
+
+  /** Look up the entry for a token (used by the reverse-proxy). */
+  get(token) {
+    return this.byToken.get(token) || null;
+  }
+
+  /** The dev port behind a token, or null. */
+  portForToken(token) {
+    const e = this.byToken.get(token);
+    return e ? e.port : null;
+  }
+
+  /** The entry currently registered for a dev port, or null. */
+  getByPort(port) {
+    return this.byPort.get(Number(port)) || null;
+  }
+
+  /** Refresh a token's heartbeat. Returns true if it existed. */
+  heartbeat(token) {
+    const e = this.byToken.get(token);
+    if (!e) return false;
+    e.lastSeen = this.now();
+    return true;
+  }
+
+  /** Remove a preview (dev server stopped). Returns the removed entry or null. */
+  remove(token) {
+    const e = this.byToken.get(token);
+    if (!e) return null;
+    this.byToken.delete(token);
+    this.byPort.delete(e.port);
+    return e;
+  }
+
+  removeByPort(port) {
+    const e = this.byPort.get(Number(port));
+    return e ? this.remove(e.token) : null;
+  }
+
+  /** All live previews this server hosts. */
+  list() {
+    return [...this.byToken.values()];
+  }
+
+  /**
+   * Drop entries whose heartbeat is older than the TTL (crash/sleep/disconnect).
+   * Returns the removed entries so the caller can also retire them on the rails.
+   */
+  sweep() {
+    const cutoff = this.now() - this.ttlMs;
+    const dead = [];
+    for (const e of this.byToken.values()) {
+      if (e.lastSeen < cutoff) dead.push(e);
+    }
+    for (const e of dead) this.remove(e.token);
+    return dead;
+  }
+}
+
+// Derive a preview's public URL from the install's share base by swapping the
+// leftmost label for the token: `https://tuananh.venturewild.llc` +
+// `pv-7a3f` → `https://pv-7a3f.venturewild.llc`. Returns null for a non-public
+// base (localhost / bare IP / no subdomain) where a `pv-` host can't resolve.
+export function previewUrlFor(shareBaseUrl, token) {
+  if (!shareBaseUrl || !token) return null;
+  let u;
+  try {
+    u = new URL(shareBaseUrl);
+  } catch {
+    return null;
+  }
+  const host = u.hostname;
+  if (host === 'localhost' || /^\d+\.\d+\.\d+\.\d+$/.test(host) || host.includes(':')) return null;
+  const parts = host.split('.');
+  if (parts.length < 3) return null; // need a real <slug>.<domain.tld>
+  parts[0] = token;
+  return `https://${parts.join('.')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Dev-port reconcile (Part B) — one detection pass, kept pure for unit tests.
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile the LocalPreviewRegistry against the dev ports currently listening:
+ *   - a newly-seen port → register (mint token) + rails.publish
+ *   - a port that vanished → remove locally + rails.retire
+ *   - a surviving port → heartbeat locally + on the rails (keeps it live)
+ *   - a TTL-expired straggler (crash/sleep) → swept + rails.retire
+ *
+ * `rails` is a degrade-never client (its calls no-op when not logged in / the
+ * endpoint is absent), so this is safe to run before bmo-sync ships Part D.
+ * Injected `detect` is `detectPreviewPorts`. `selfPort` excludes the
+ * wild-workspace server's own port from ever being treated as a preview.
+ */
+export async function reconcilePreviews({
+  detect,
+  registry,
+  rails,
+  slug = null,
+  initiator = null,
+  selfPort = null,
+}) {
+  const found = (await detect()) || [];
+  const livePorts = new Set(found.map((d) => d.port).filter((p) => p !== selfPort));
+
+  for (const port of livePorts) {
+    const existing = registry.getByPort(port);
+    if (existing) {
+      registry.heartbeat(existing.token);
+      await rails.heartbeat(existing.token);
+    } else {
+      const entry = registry.register({ port, workspaceId: slug, initiator, label: initiator });
+      await rails.publish({ token: entry.token, slug, label: initiator });
+    }
+  }
+  for (const entry of registry.list()) {
+    if (!livePorts.has(entry.port)) {
+      registry.remove(entry.token);
+      await rails.retire(entry.token);
+    }
+  }
+  for (const dead of registry.sweep()) {
+    await rails.retire(dead.token);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP reverse-proxy
+// ---------------------------------------------------------------------------
+
+// Headers we never forward to / from the local dev server.
+const REQ_STRIP = new Set([
+  'host', // we set our own (127.0.0.1:port) so a Host-checking dev server (Vite
+  // allowedHosts / DNS-rebind guard) accepts the request
+  'connection',
+  'keep-alive',
+  'proxy-authorization',
+  'proxy-authenticate',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  // The relay's forwarding headers describe the public hop, not this local one.
+  'x-forwarded-host',
+  'x-forwarded-proto',
+]);
+// NOTE on compression: we let undici (global fetch) own content negotiation — it
+// sets its own `accept-encoding` and transparently DECODES the response body, so
+// the body stream we forward is already plaintext. We therefore strip the now-
+// stale `content-encoding`/`content-length` from the response (see RES_STRIP)
+// rather than trying to suppress compression on the request.
+
+const RES_STRIP = new Set([
+  'connection',
+  'keep-alive',
+  'transfer-encoding',
+  'content-encoding', // body is already decoded by undici fetch
+  'content-length', // length changed with the encoding
+  'x-frame-options', // must NOT block the Live-view iframe framing this origin
+]);
+
+/**
+ * Reverse-proxy one web `Request` to `http://127.0.0.1:<port>` and return the
+ * web `Response` (suitable for returning straight from a Hono handler). The
+ * dev server is the user's own trusted code; we transport it faithfully but
+ * strip framing/encoding headers that would break the iframe or the body.
+ *
+ * On upstream failure (dev server stopped) returns a small 502 page rather than
+ * throwing, so the iframe shows a graceful "ended" state.
+ */
+export async function proxyHttpToPort(port, request, { fetchImpl = (...a) => globalThis.fetch(...a) } = {}) {
+  const p = Number(port);
+  if (!Number.isInteger(p) || p < 1 || p > 65535) {
+    return new Response('bad preview port', { status: 502 });
+  }
+  const inUrl = new URL(request.url);
+  const target = `http://127.0.0.1:${p}${inUrl.pathname}${inUrl.search}`;
+
+  const headers = new Headers();
+  for (const [name, value] of request.headers) {
+    if (!REQ_STRIP.has(name.toLowerCase())) headers.set(name, value);
+  }
+  headers.set('host', `127.0.0.1:${p}`);
+
+  const method = request.method.toUpperCase();
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  let upstream;
+  try {
+    upstream = await fetchImpl(target, {
+      method,
+      headers,
+      body: hasBody ? request.body : undefined,
+      redirect: 'manual', // let the browser see the dev server's redirects verbatim
+      ...(hasBody ? { duplex: 'half' } : {}),
+    });
+  } catch {
+    return new Response(PREVIEW_ENDED_PAGE, {
+      status: 502,
+      headers: { 'content-type': 'text/html', 'cache-control': 'no-store' },
+    });
+  }
+
+  const outHeaders = new Headers();
+  for (const [name, value] of upstream.headers) {
+    if (!RES_STRIP.has(name.toLowerCase())) outHeaders.append(name, value);
+  }
+  outHeaders.set('cache-control', 'no-store');
+  return new Response(upstream.body, { status: upstream.status, headers: outHeaders });
+}
+
+export const PREVIEW_ENDED_PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>Preview</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0f1117;color:#9aa4b2}div{text-align:center;max-width:340px;line-height:1.6}</style>
+</head><body><div><p>This preview has ended — the dev server that was running it is no longer live.</p></div></body></html>`;
+
+// ---------------------------------------------------------------------------
+// WebSocket reverse-proxy (HMR / any ws the dev server exposes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge an already-accepted browser WebSocket to the dev server's ws at
+ * `upstreamUrl`. Pipes messages both ways and mirrors close/error so neither
+ * side hangs. Browser→upstream messages that arrive before upstream is open are
+ * queued and flushed on connect. `WS` is injectable for tests.
+ *
+ * Returns the upstream socket (so callers/tests can observe it).
+ */
+export function bridgeWebSocket(browserWs, upstreamUrl, { protocols, headers } = {}, WS = WebSocket) {
+  const upstream = protocols
+    ? new WS(upstreamUrl, protocols, { headers })
+    : new WS(upstreamUrl, { headers });
+
+  const pending = [];
+  let upstreamOpen = false;
+  const safeClose = (sock, code, reason) => {
+    try {
+      // Only application/normal close codes are valid to send.
+      const c = Number.isInteger(code) && code >= 1000 && code <= 4999 ? code : 1000;
+      sock.close(c, reason);
+    } catch {
+      try { sock.terminate?.(); } catch { /* ignore */ }
+    }
+  };
+
+  upstream.on('open', () => {
+    upstreamOpen = true;
+    for (const [data, isBinary] of pending) upstream.send(data, { binary: isBinary });
+    pending.length = 0;
+  });
+  upstream.on('message', (data, isBinary) => {
+    if (browserWs.readyState === browserWs.OPEN) browserWs.send(data, { binary: isBinary });
+  });
+  upstream.on('close', (code, reason) => safeClose(browserWs, code, reason));
+  upstream.on('error', () => safeClose(browserWs, 1011, 'upstream error'));
+
+  browserWs.on('message', (data, isBinary) => {
+    if (upstreamOpen && upstream.readyState === upstream.OPEN) {
+      upstream.send(data, { binary: isBinary });
+    } else {
+      pending.push([data, isBinary]);
+    }
+  });
+  browserWs.on('close', (code, reason) => safeClose(upstream, code, reason));
+  browserWs.on('error', () => safeClose(upstream, 1011, 'client error'));
+
+  return upstream;
+}
+
+/**
+ * Complete a raw HTTP upgrade for a preview host: accept the browser side via a
+ * `noServer` WebSocketServer, then bridge it to `ws://127.0.0.1:<port><path>`.
+ * Forwards the requested subprotocol. Caller has already resolved `port` from
+ * the LocalPreviewRegistry (so the target is guaranteed loopback + registered).
+ */
+export function proxyWsUpgrade({ previewWss, req, socket, head, port, WS = WebSocket }) {
+  const p = Number(port);
+  if (!Number.isInteger(p) || p < 1 || p > 65535) {
+    try { socket.destroy(); } catch { /* ignore */ }
+    return;
+  }
+  const reqUrl = new URL(req.url, `http://127.0.0.1:${p}`);
+  const upstreamUrl = `ws://127.0.0.1:${p}${reqUrl.pathname}${reqUrl.search}`;
+  const subprotocol = req.headers['sec-websocket-protocol'];
+  const protocols = subprotocol
+    ? subprotocol.split(',').map((s) => s.trim()).filter(Boolean)
+    : undefined;
+  previewWss.handleUpgrade(req, socket, head, (browserWs) => {
+    bridgeWebSocket(browserWs, upstreamUrl, { protocols }, WS);
+  });
+}