viewable-one 0.0.0-stage → 0.12.1

package/lib/picker.mjs

@@ -0,0 +1,300 @@
+// Arrow-key checkbox picker (brief 31, ruling 2026-09-12: "when selecting a
+// model I prefer not to type anything: go up and down with arrows to select
+// the right one or even multiple ones"). Step 1 of `glytch init` used to be a
+// numbered list and a comma-separated answer; this is the checkbox list that
+// replaces it for a real terminal.
+//
+// A PURE FUNCTION OF ITS STREAMS. No global terminal state, no dependency:
+// `input`/`output` are injected so a test can drive it with a fake stream
+// that emits key sequences and read back exactly what was painted, and so
+// the non-TTY path in agent-selection.mjs never has to know this module
+// exists. Paint goes through cli-output.mjs's helpers only (`bold`, `ok`,
+// `warn`, `dim`), so `color: false` (NO_COLOR, a pipe, TERM=dumb) renders a
+// plain `>` and `[x]` with no escapes at all - only the cursor-hide/show and
+// redraw sequences remain, because those are structural, not decoration.
+//
+// RENDERS IN PLACE: hide the cursor once, then on every keypress move the
+// cursor back up over the block just drawn and clear each line before
+// repainting it. The block is always `items.length + 3` lines - the agent
+// rows, a trailing "Continue" row, the empty-selection warning (blank when
+// there is nothing to warn about), and a one-line legend - so the redraw
+// math never has to account for a growing or shrinking frame.
+//
+// ENTER SELECTS (2026-09-12, real run): the user arrowed onto opencode and
+// pressed Enter expecting to check it; Enter confirmed the whole picker
+// instead, with only Claude checked, and there was no way back short of
+// re-running init. The expectation is the rule now - Enter on an agent row
+// toggles it, exactly like Space - so confirming needs its own row. "Continue"
+// is that row: it carries the cursor like any other, has no checkbox, and is
+// the only row where Enter finishes the picker.
+import { bold, dim, ok, warn, wrap } from "./cli-output.mjs";
+
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const up = (n) => `\x1b[${n}A`;
+const CLEAR_LINE = "\x1b[2K";
+// 79 code points: fits inside one 80-column row by default, unlike the
+// wording this replaced (82 code points - one over). P1 (review
+// 2026-09-12): draw() counted one physical terminal row per logical line,
+// so the moment the legend itself wrapped at 80 columns the cursor-up count
+// fell one row short on every redraw and the whole picker smeared. A
+// narrower `columns` still wraps this (draw() below now measures physical
+// rows rather than assuming one each), but the common case needs no wrap.
+const LEGEND = "↑↓ move · Enter/Space select · a all · Enter on Continue to finish · Esc cancel";
+
+// Strip the SGR escapes this module ever paints with before measuring -
+// colour codes take zero columns on a real terminal. Every remaining code
+// point then counts as one column; true for the arrows and middle dot this
+// legend uses, not a general-purpose East-Asian-width table, but nothing
+// this picker renders needs one.
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+function displayWidth(text) {
+  return [...String(text).replace(ANSI_RE, "")].length;
+}
+
+// How many terminal rows one rendered line actually occupies, so draw()'s
+// cursor-up count matches what the terminal did with it instead of
+// assuming one array entry is always one row (P1).
+function physicalRows(line, columns) {
+  return Math.max(1, Math.ceil(displayWidth(line) / columns));
+}
+
+/**
+ * @param {object} args
+ * @param {{key: string, label: string}[]} args.items - rows, in display order.
+ * @param {string[]} [args.checked] - keys checked at start.
+ * @param {NodeJS.ReadStream} [args.input]
+ * @param {NodeJS.WriteStream} [args.output]
+ * @param {boolean} [args.color]
+ * @param {number} [args.columns] - terminal width for redraw math (P1);
+ *   defaults to `output.columns`, falling back to 80 for a pipe or a fake
+ *   stream in a test that reports none.
+ * @returns {Promise<string[]|null>} the checked keys in `items` order, or
+ *   `null` if the user cancelled with Escape, Ctrl-C, Ctrl-D, or stdin ending.
+ */
+export function pickMany({
+  items, checked = [], input = process.stdin, output = process.stdout, color = false,
+  columns = output.columns || 80,
+}) {
+  return new Promise((resolvePromise) => {
+    // The cursor ranges over the agent rows plus one more: `items.length`
+    // itself is the Continue row, kept as a plain index rather than a
+    // sentinel so Up/Down/j/k treat it exactly like any other row.
+    const continueIndex = items.length;
+    const rowCount = items.length + 1;
+    const state = { cursor: 0, checked: new Set(checked), warning: "" };
+    let drawn = 0;
+    let settled = false;
+
+    // Fake streams in tests have no setRawMode; skip raw mode rather than
+    // throw, per the module's own contract.
+    const canRaw = typeof input.setRawMode === "function";
+    const wasRaw = canRaw ? input.isRaw : undefined;
+
+    function renderLines() {
+      const lines = items.map((item, i) => {
+        const marker = i === state.cursor ? bold(">", { color }) : " ";
+        const box = state.checked.has(item.key) ? ok("[x]", { color }) : "[ ]";
+        return `${marker} ${box} ${item.label}`;
+      });
+      const continueMarker = state.cursor === continueIndex ? bold(">", { color }) : " ";
+      const continueLabel = state.checked.size > 0 ? bold("Continue", { color }) : dim("Continue", { color });
+      lines.push(`${continueMarker} ${continueLabel}`);
+      lines.push(state.warning ? warn(state.warning, { color }) : "");
+      // Wrapped explicitly into its own rows (rather than left to the
+      // terminal) so each pushed entry is already <= `columns` wide: draw()
+      // can then paint one CLEAR_LINE per entry and have it actually own
+      // the physical row it clears (P1).
+      for (const row of wrap(LEGEND, columns, "")) lines.push(dim(row, { color }));
+      return lines;
+    }
+
+    function draw() {
+      const lines = renderLines();
+      if (drawn > 0) output.write(up(drawn));
+      for (const line of lines) output.write(`\r${CLEAR_LINE}${line}\n`);
+      drawn = lines.reduce((total, line) => total + physicalRows(line, columns), 0);
+    }
+
+    // P2: a bare ESC, or ESC + "[" with nothing after it yet, held here when
+    // it lands at the very end of a `data` chunk - it might be the first
+    // byte(s) of a CSI arrow sequence split across two chunks by a slow pty
+    // (reproduced by hand 2026-09-12), or it might really be the Escape key
+    // on its own. `escapeTimer` decides which: cleared the moment another
+    // chunk arrives (so the arrow's remaining bytes complete it normally),
+    // and fired after 50ms of silence to treat the hold as Escape.
+    let pendingEscape = "";
+    let escapeTimer = null;
+
+    function clearEscapeTimer() {
+      if (escapeTimer) { clearTimeout(escapeTimer); escapeTimer = null; }
+    }
+
+    function cleanup() {
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("close", onEnd);
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigterm);
+      process.removeListener("SIGHUP", onSighup);
+      clearEscapeTimer();
+      if (canRaw && wasRaw !== undefined) input.setRawMode(wasRaw);
+      // Adding the `data` listener below switches a real stdin into flowing
+      // mode; removing the listener does not by itself put it back to
+      // sleep. Left flowing, the process never sees an empty event loop and
+      // `glytch init` hangs after printing its last line until Ctrl-C - seen
+      // for real 2026-09-12. Pause explicitly, on every exit path (confirm,
+      // cancel, SIGINT) - they all funnel through here via `finish`.
+      if (typeof input.pause === "function") input.pause();
+      output.write(SHOW_CURSOR);
+    }
+
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolvePromise(result);
+    }
+
+    // A real SIGINT (raw mode disables the tty's own ISIG handling of ^C, so
+    // this fires only for a signal sent from outside - `kill -INT`, a parent
+    // process, Windows' console handler) must still leave the cursor shown.
+    // Cancelling is the right response either way: there is no "resume the
+    // picker" story for a signal that arrived out of band.
+    function onSigint() { finish(null); }
+
+    // P3: SIGTERM/SIGHUP used to reach no handler here at all, so `cleanup`
+    // never ran and a killed `glytch init` left the shell in raw mode with
+    // the cursor hidden. `finish` runs cleanup (and, via it, removes these
+    // very listeners) before resolving; re-raising afterwards restores the
+    // signal's own default action - now unopposed, because our listener is
+    // already gone - instead of this module silently swallowing a kill.
+    function onSigterm() { finish(null); process.kill(process.pid, "SIGTERM"); }
+    function onSighup() { finish(null); process.kill(process.pid, "SIGHUP"); }
+
+    // P3: stdin ending or closing out from under the picker (piped input
+    // exhausted, the terminal disconnected) used to leave the promise
+    // pending forever with the cursor hidden. Treat it exactly like Escape.
+    function onEnd() { finish(null); }
+
+    function toggleCursor() {
+      const itemKey = items[state.cursor].key;
+      if (state.checked.has(itemKey)) state.checked.delete(itemKey);
+      else state.checked.add(itemKey);
+      state.warning = "";
+      draw();
+    }
+
+    // A chunk is not a keystroke: a fast typist, a paste, or (proven while
+    // driving this by hand through a pty) a handful of printf'd keys can all
+    // land in one `data` event holding several key events back to back. Walk
+    // it token by token - a three-byte arrow sequence, or one character -
+    // instead of matching the whole chunk, or every key after the first is
+    // silently dropped.
+    function handleKey(key) {
+      if (settled) return;
+      // \x04 is Ctrl-D (EOF) in raw mode - it never reaches "data" as end of
+      // stream the way it would in cooked mode, so it must be read as a key
+      // like any other (P3).
+      if (key === "\x03" || key === "\x1b" || key === "\x04") { finish(null); return; }
+      if (key === "\r" || key === "\n") {
+        // Enter selects (the rule, 2026-09-12): on an agent row it toggles
+        // that row, same as Space. Only Enter on the Continue row confirms.
+        if (state.cursor !== continueIndex) { toggleCursor(); return; }
+        if (state.checked.size === 0) {
+          state.warning = "choose at least one";
+          draw();
+          return;
+        }
+        finish(items.filter((item) => state.checked.has(item.key)).map((item) => item.key));
+        return;
+      }
+      if (key === "\x1b[A" || key === "k") {
+        state.cursor = (state.cursor - 1 + rowCount) % rowCount;
+        state.warning = "";
+        draw();
+        return;
+      }
+      if (key === "\x1b[B" || key === "j") {
+        state.cursor = (state.cursor + 1) % rowCount;
+        state.warning = "";
+        draw();
+        return;
+      }
+      if (key === " ") {
+        // Continue has no checkbox; Space on it does nothing rather than
+        // guessing at a confirm it was never asked for.
+        if (state.cursor === continueIndex) return;
+        toggleCursor();
+        return;
+      }
+      if (key === "a" || key === "A") {
+        if (state.checked.size === items.length) state.checked.clear();
+        else for (const item of items) state.checked.add(item.key);
+        state.warning = "";
+        draw();
+        return;
+      }
+      // Anything else (a stray escape sequence, an unmapped letter) is
+      // ignored rather than mis-parsed as a selection.
+    }
+
+    // P2 (confirmed, reproduced): a slow pty can split a 3-byte CSI arrow
+    // across two "data" events, most often right after the ESC byte. The old
+    // walk treated a trailing bare \x1b as a complete, standalone Escape the
+    // instant it saw it - cancelling the whole picker on the first half of
+    // an arrow key. Held bytes at the end of a chunk are stashed in
+    // `pendingEscape` and given 50ms to be completed by the next chunk
+    // before `flushPending` resolves them as ordinary keys (a lone \x1b is
+    // still Escape; anything else is still ignored).
+    function flushPending() {
+      escapeTimer = null;
+      const held = pendingEscape;
+      pendingEscape = "";
+      for (const ch of held) {
+        if (settled) break;
+        handleKey(ch);
+      }
+    }
+
+    function onData(chunk) {
+      clearEscapeTimer();
+      const data = pendingEscape + chunk.toString("utf8");
+      pendingEscape = "";
+      let i = 0;
+      while (i < data.length && !settled) {
+        // The only multi-byte sequences this picker knows are the 3-byte
+        // CSI arrows; a bare \x1b not followed by `[A`/`[B` is the Escape
+        // key on its own and cancels, exactly as it always did - UNLESS the
+        // chunk simply ran out before the sequence could finish, handled
+        // below.
+        if (data[i] === "\x1b" && data[i + 1] === "[" && (data[i + 2] === "A" || data[i + 2] === "B")) {
+          handleKey(data.slice(i, i + 3));
+          i += 3;
+          continue;
+        }
+        if (data[i] === "\x1b" && (i === data.length - 1 || (data[i + 1] === "[" && i + 1 === data.length - 1))) {
+          pendingEscape = data.slice(i);
+          break;
+        }
+        handleKey(data[i]);
+        i += 1;
+      }
+      // Deliberately NOT unref'd: a held ESC is a real decision still
+      // waiting to be made (Escape, or the rest of an arrow), and the
+      // process should wait the 50ms for it rather than being free to exit
+      // with the picker's promise never settled.
+      if (pendingEscape && !settled) escapeTimer = setTimeout(flushPending, 50);
+    }
+
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    process.on("SIGHUP", onSighup);
+    if (canRaw) input.setRawMode(true);
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("close", onEnd);
+    output.write(HIDE_CURSOR);
+    draw();
+  });
+}

package/lib/platform.mjs

@@ -0,0 +1,60 @@
+// WHAT MACHINE THE RUNNER IS ON, in the one place the app can read it.
+//
+// Brief 21 session 5 (2026-09-07), rulings 3A and 6C. Two things need
+// this and neither can guess:
+//
+//   - THE APP MUST NOT GUESS FROM `navigator`. The words a spawn prompt
+//     carries for starting a detached dev server are POSIX on macOS/Linux and
+//     PowerShell on Windows (ruling 3A), and the session runs where the RUNNER
+//     is - which since brief 19 need not be where the browser is. A board open
+//     in Chrome on a Mac, linked to a folder on a Windows box through a
+//     synced directory, would be told `setsid` by a `navigator.platform`
+//     sniff and hand the session a command it cannot run. So the runner says
+//     what it is, in the mark file it already writes every beat, and the app
+//     reads it there or writes the POSIX words it always wrote.
+//
+//   - WSL IS NOT WINDOWS AND SAYING SO IS THE POINT (ruling 6C: both count,
+//     and doctor names which). Node inside WSL reports `linux`, which is
+//     correct and is also exactly what the words need: `setsid` works there,
+//     `Start-Process` does not. So `wsl` is reported as its own name rather
+//     than folded into either - a consumer that only knows `win32` treats it
+//     as the Linux it is, and a consumer that wants to NAME the environment
+//     (doctor) has the fact.
+//
+// PURE AND INJECTABLE, the same shape as lib/windows-command.mjs beside it:
+// nothing here reads the real platform or the real filesystem unless the
+// caller lets the defaults stand, so the WSL branch is proven on a Mac.
+
+import { readFileSync } from "node:fs";
+
+/** Linux's own record of the kernel it is running. Under WSL 1 and WSL 2 this
+ * names Microsoft; on a real Linux box it does not. It is the check every
+ * other tool uses, and it costs one small read at start rather than a
+ * shell-out. */
+export const PROC_VERSION = "/proc/version";
+
+/** The runner's platform, as the mark file spells it.
+ *
+ * Returns `process.platform` (`darwin`, `win32`, `linux`, ...) except inside
+ * WSL, where it returns `"wsl"`. Never throws: a `/proc/version` that cannot
+ * be read is a machine that is not WSL as far as anyone here is concerned. */
+export function runnerPlatform({ platform = process.platform, readFile = readFileSync } = {}) {
+  if (platform !== "linux") return platform;
+  try {
+    if (/microsoft/i.test(String(readFile(PROC_VERSION, "utf8")))) return "wsl";
+  } catch {
+    // No /proc/version, or no permission to read it. Plain Linux.
+  }
+  return platform;
+}
+
+/** What the mark file gains, in the shape `markExtra()` returns.
+ *
+ * A separate function from `runnerPlatform` so the two callers
+ * (lib/multiwatch.mjs's daemon and spawn-runner.mjs's hand-started watcher)
+ * spread one object rather than each spelling the key, which is how `version`
+ * and `agents` already reach the mark. Computed once per beat and cheap: the
+ * `/proc/version` read only happens on Linux. */
+export function platformMark(options = {}) {
+  return { platform: runnerPlatform(options) };
+}

package/lib/previewGateway.mjs

@@ -0,0 +1,129 @@
+/** Fixed-origin preview proxy. Every HTTP request and WebSocket upgrade is authorized. */
+import http from "node:http";
+import https from "node:https";
+
+export function previewOrigin(value) {
+  const url = new URL(value);
+  if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+    || url.username || url.password) throw new Error("A preview must target a loopback HTTP dev server.");
+  return url;
+}
+
+const AUTH_COOKIE = "__glytch_preview";
+const HOP_HEADERS = ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"];
+function headersFor(headers, target, upgrade = false) {
+  const out = { ...headers };
+  const nominated = String(out.connection ?? "").split(",").map((name) => name.trim().toLowerCase());
+  for (const name of [...HOP_HEADERS, ...nominated]) delete out[name];
+  // Gateway credentials must never reach application code or its logs.
+  delete out["x-glytch-preview-grant"];
+  if (out.cookie) {
+    out.cookie = out.cookie.split(";").filter((part) => part.trim().split("=", 1)[0] !== AUTH_COOKIE).join(";");
+    if (!out.cookie.trim()) delete out.cookie;
+  }
+  out.host = target.host;
+  if (upgrade) { out.connection = "Upgrade"; out.upgrade = "websocket"; }
+  return out;
+}
+function responseHeaders(headers) {
+  const out = { ...headers };
+  const nominated = String(out.connection ?? "").split(",").map((name) => name.trim().toLowerCase());
+  for (const name of [...HOP_HEADERS, ...nominated]) delete out[name];
+  if (out["set-cookie"]) out["set-cookie"] = out["set-cookie"].filter((cookie) => cookie.split("=", 1)[0].trim() !== AUTH_COOKIE);
+  out["cache-control"] = "no-store";
+  return out;
+}
+const validPath = (path) => typeof path === "string" && path.startsWith("/") && !path.startsWith("//") && !/[\r\n]/.test(path);
+
+// Existing callers can return true. Scoped grants return an expiry so open
+// streams and WebSockets cannot outlive membership's bounded lease.
+function expireConnection(authorization, target) {
+  if (typeof authorization !== "object" || !Number.isFinite(authorization.expiresAt)) return;
+  const timer = setTimeout(() => target.destroy(), Math.max(0, authorization.expiresAt - Date.now()));
+  timer.unref?.();
+  target.once("close", () => clearTimeout(timer));
+}
+
+/** The authorization callback is mandatory; public transport never implies access. */
+export async function createPreviewGateway({ target: value, authorize, handleAuth, timeoutMs = 30_000, maxConnections = 128, requestTimeoutMs = 15_000 }) {
+  const target = previewOrigin(value);
+  if (typeof authorize !== "function") throw new Error("Preview authorization is required.");
+  const transport = target.protocol === "https:" ? https : http;
+  const sockets = new Set();
+  const upstreams = new Set();
+  let closed = false;
+  const server = http.createServer(async (req, res) => {
+    try {
+      if (closed || !validPath(req.url)) { res.writeHead(400); res.end(); return; }
+      if (handleAuth && await handleAuth(req, res)) return;
+      const authorization = await authorize(req);
+      if (!authorization) { res.writeHead(403, { "cache-control": "no-store" }); res.end("Preview access is required."); return; }
+      if (closed || res.destroyed) return;
+      expireConnection(authorization, res);
+      const upstream = transport.request({ protocol: target.protocol, hostname: target.hostname.replace(/^\[|\]$/g, ""), port: target.port,
+        method: req.method, path: req.url, headers: headersFor(req.headers, target) }, (reply) => {
+        res.writeHead(reply.statusCode ?? 502, responseHeaders(reply.headers));
+        reply.pipe(res);
+      });
+      upstreams.add(upstream);
+      upstream.on("close", () => upstreams.delete(upstream));
+      upstream.setTimeout(timeoutMs, () => upstream.destroy(new Error("Preview upstream timed out.")));
+      upstream.on("error", () => { if (!res.headersSent) res.writeHead(502, { "cache-control": "no-store" }); res.end("The dev server is unavailable."); });
+      res.on("close", () => upstream.destroy());
+      req.pipe(upstream);
+    } catch {
+      if (!res.headersSent) res.writeHead(403, { "cache-control": "no-store" });
+      res.end("Preview access could not be verified.");
+    }
+  });
+  // Bound unauthenticated slow clients before grant verification or proxying.
+  server.maxConnections = maxConnections;
+  server.requestTimeout = requestTimeoutMs;
+  server.headersTimeout = Math.min(10_000, requestTimeoutMs);
+  server.keepAliveTimeout = 5_000;
+  server.maxRequestsPerSocket = 100;
+  server.setTimeout(requestTimeoutMs, (socket) => socket.destroy());
+  server.on("connection", (socket) => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); });
+  server.on("upgrade", async (req, socket, head) => {
+    const refuse = () => socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+    try {
+      if (closed || !validPath(req.url) || String(req.headers.upgrade).toLowerCase() !== "websocket") { refuse(); return; }
+      const authorization = await authorize(req);
+      if (!authorization) { refuse(); return; }
+      if (closed || socket.destroyed) return;
+      expireConnection(authorization, socket);
+      const upstream = transport.request({ protocol: target.protocol, hostname: target.hostname.replace(/^\[|\]$/g, ""), port: target.port,
+        method: "GET", path: req.url, headers: headersFor(req.headers, target, true) });
+      upstreams.add(upstream);
+      upstream.on("close", () => upstreams.delete(upstream));
+      upstream.setTimeout(timeoutMs, () => upstream.destroy());
+      socket.on("close", () => upstream.destroy());
+      upstream.on("error", () => socket.destroy());
+      upstream.on("response", () => socket.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\nContent-Length: 0\r\n\r\n"));
+      upstream.on("upgrade", (reply, peer, peerHead) => {
+        peer.setTimeout(0); socket.setTimeout(0);
+        if (closed || socket.destroyed) { peer.destroy(); return; }
+        sockets.add(peer); peer.on("close", () => { sockets.delete(peer); socket.destroy(); });
+        socket.on("close", () => peer.destroy()); peer.on("error", () => socket.destroy()); socket.on("error", () => peer.destroy());
+        const headers = responseHeaders(reply.headers);
+        headers.connection = "Upgrade"; headers.upgrade = "websocket";
+        socket.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(headers).flatMap(([key, values]) => (Array.isArray(values) ? values : [values]).map((v) => `${key}: ${v}\r\n`)).join("")}\r\n`);
+        if (peerHead.length) socket.write(peerHead);
+        if (head.length) peer.write(head);
+        socket.pipe(peer); peer.pipe(socket);
+      });
+      upstream.end();
+    } catch { refuse(); }
+  });
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  return {
+    origin: `http://127.0.0.1:${server.address().port}`,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      for (const request of upstreams) request.destroy();
+      for (const socket of sockets) socket.destroy();
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}

package/lib/previewTunnel.mjs

@@ -0,0 +1,85 @@
+/** Outbound transport only. Callers expose an authorized gateway, never a raw dev port. */
+import { spawn as spawnProcess } from "node:child_process";
+import { previewOrigin } from "./previewGateway.mjs";
+import { ensureCloudflared } from "./cloudflared.mjs";
+import { killTree } from "./kill.mjs";
+
+export function quickTunnelUrl(text) {
+  return /https:\/\/[a-z0-9]+(?:-[a-z0-9]+)*\.trycloudflare\.com(?=[\s/]|$)/i.exec(text)?.[0] ?? null;
+}
+
+export async function startQuickPreviewTunnel(gatewayOrigin, {
+  bin = process.env.PM_CLOUDFLARED_BIN,
+  ensureBinary = ensureCloudflared,
+  spawn = spawnProcess,
+  timeoutMs = 30_000,
+  kill = killTree,
+  signal,
+} = {}) {
+  const local = previewOrigin(gatewayOrigin);
+  if (local.pathname !== "/" || local.search || local.hash) throw new Error("The tunnel requires a gateway origin.");
+  if (signal?.aborted) throw new Error("Preview sharing was stopped.");
+  if (!bin) bin = await ensureBinary({ signal });
+  if (signal?.aborted) throw new Error("Preview sharing was stopped.");
+  const child = spawn(bin, ["tunnel", "--no-autoupdate", "--url", local.origin, "--loglevel", "info"], {
+    stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+  });
+  let exited = false;
+  let stopped = false;
+  let stopPromise;
+  child.once("exit", () => { exited = true; });
+  child.once("error", () => { exited = true; });
+  const stop = () => {
+    if (stopPromise) return stopPromise;
+    stopped = true;
+    stopPromise = (async () => {
+      signal?.removeEventListener("abort", abort);
+      if (exited || !child.pid) return;
+      try { await kill(child.pid); } catch { /* child may already have exited */ }
+      if (!exited) {
+        await new Promise((resolve) => {
+          const timer = setTimeout(resolve, 1_000);
+          child.once("exit", () => { clearTimeout(timer); resolve(); });
+        });
+      }
+      if (!exited) { try { await kill(child.pid, { force: true }); } catch { /* already gone */ } }
+    })();
+    return stopPromise;
+  };
+  let cancelStart;
+  const abort = () => { cancelStart?.(); void stop(); };
+  signal?.addEventListener("abort", abort, { once: true });
+  try {
+    const url = await new Promise((resolve, reject) => {
+      let tail = "";
+      const timeout = setTimeout(() => finish(new Error("The preview tunnel did not connect. Check the network and retry.")), timeoutMs);
+      const onError = (error) => finish(new Error(error.code === "ENOENT"
+        ? "Shared previews need cloudflared installed on your computer. Install it once, then sharing starts on its own."
+        : "The preview tunnel could not start."));
+      const onExit = () => finish(new Error("The preview tunnel stopped before it connected."));
+      const onData = (chunk) => {
+        tail = (tail + chunk.toString()).slice(-8192);
+        const found = quickTunnelUrl(tail);
+        if (found) finish(null, found);
+      };
+      const finish = (error, found) => {
+        cancelStart = undefined;
+        clearTimeout(timeout);
+        child.removeListener("error", onError); child.removeListener("exit", onExit);
+        child.stdout?.removeListener("data", onData); child.stderr?.removeListener("data", onData);
+        // Keep draining output without retaining URLs or user project logs.
+        child.stdout?.resume(); child.stderr?.resume();
+        if (error) reject(error); else resolve(found);
+      };
+      cancelStart = () => finish(new Error("Preview sharing was stopped."));
+      child.once("error", onError); child.once("exit", onExit);
+      child.stdout?.on("data", onData); child.stderr?.on("data", onData);
+      if (signal?.aborted) finish(new Error("Preview sharing was stopped."));
+    });
+    if (stopped || signal?.aborted || exited) throw new Error("Preview sharing was stopped.");
+    return { url, stop, alive: () => !stopped && !exited };
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+}