viewable-one 0.0.0-stage → 0.12.1

package/lib/logs.mjs

@@ -0,0 +1,120 @@
+// THE DAEMON'S LOG, because a background process with no terminal has nowhere
+// else to say anything.
+//
+// Until brief 19 the runner was a thing a person typed, so its output went to
+// that person's terminal and there was nothing to keep. A LaunchAgent has no
+// terminal, so the same lines go to ~/.glytch/logs/runner.log - and a file
+// something appends to for ever is a disk leak, so it rotates by SIZE.
+//
+// Rotation is by size and not by date on purpose: a machine that spawns
+// nothing writes a few lines a day and should keep months of them in one
+// file, while a machine running sessions all night fills a file in hours. The
+// budget that matters is the disk, so the budget is the one that is measured.
+
+import { appendFile, mkdir, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { glytchHome } from "./registry.mjs";
+
+/** 5 MB per file, three rotations kept: at most ~20 MB of logs on a machine,
+ * which is small enough never to be noticed and large enough to hold the
+ * night a session went wrong. */
+export const LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const LOG_KEEP = 3;
+
+export const logDir = (env = process.env) => join(glytchHome(env), "logs");
+export const logPath = (env = process.env) => join(logDir(env), "runner.log");
+
+const sizeOf = async (path) => {
+  try {
+    return (await stat(path)).size;
+  } catch {
+    return 0;
+  }
+};
+
+/** Roll runner.log to runner.log.1, .1 to .2, and drop what falls past `keep`.
+ *
+ * Oldest first, so nothing overwrites a file it is about to move. Returns true
+ * when a rotation actually happened. Never throws: losing a log line is not a
+ * reason to take the daemon down. */
+export async function rotateIfNeeded(
+  { max = LOG_MAX_BYTES, keep = LOG_KEEP, env = process.env } = {},
+) {
+  const path = logPath(env);
+  if ((await sizeOf(path)) < max) return false;
+  try {
+    await rm(`${path}.${keep}`, { force: true });
+    for (let n = keep - 1; n >= 1; n -= 1) {
+      try {
+        await rename(`${path}.${n}`, `${path}.${n + 1}`);
+      } catch {
+        /* that rotation does not exist yet */
+      }
+    }
+    await rename(path, `${path}.1`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every rotated file beyond `keep`, so the sweep can remove what an older
+ * keep count (or a crash mid-rotation) left behind. Names only. */
+export async function staleRotations({ keep = LOG_KEEP, env = process.env } = {}) {
+  const path = logPath(env);
+  const stale = [];
+  for (let n = keep + 1; n <= keep + 20; n += 1) {
+    if ((await sizeOf(`${path}.${n}`)) > 0) stale.push(`${path}.${n}`);
+    else {
+      try {
+        await stat(`${path}.${n}`);
+        stale.push(`${path}.${n}`);
+      } catch {
+        /* not there */
+      }
+    }
+  }
+  return stale;
+}
+
+/** Should a log line ALSO be written to stdout, on top of the file the caller
+ *  always gets? (2026-09-21) The launchd/systemd plist that runs `glytch
+ *  runner watch` as the daemon redirects that process's OWN stdout into the
+ *  same `runner.log` file (`lib/logindaemon.mjs`'s `>> "$out" 2>&1`), so an
+ *  echo there is not "also print it" - it is a second `appendFile` of the
+ *  same line, doubling every line the daemon ever writes. A person running
+ *  `viewable runner watch` by hand in a terminal has no such redirect and still
+ *  wants to see what is happening, and `process.stdout.isTTY` is exactly the
+ *  fact that tells the two apart: a terminal sets it, a file/pipe redirect
+ *  does not. `GLYTCH_LOG_ECHO=1` overrides it either way, for a person who
+ *  redirects `runner watch` somewhere else by hand and still wants the echo.
+ *  `isTTY` is a parameter (not read from `process.stdout` inline) so this is
+ *  provable without a real terminal. */
+export function shouldEchoToStdout({ isTTY = process.stdout.isTTY, env = process.env } = {}) {
+  if ((env.VIEWABLE_LOG_ECHO ?? env.GLYTCH_LOG_ECHO) === "1") return true;
+  return Boolean(isTTY);
+}
+
+/** A `log` function of the shape every function in this package already takes
+ * (`(line) => void`), writing timestamped lines into the rotating file. It
+ * also echoes to stdout by default when stdout is a real terminal
+ * (`shouldEchoToStdout`) - `viewable runner watch` run by hand must still say
+ * what it is doing, while the same process under the daemon's plist (stdout
+ * already redirected into this same file) must not write every line twice.
+ * `echo` still overrides outright when a caller (a test, `GLYTCH_LOG_ECHO`)
+ * has already decided. */
+export function makeFileLogger({ env = process.env, echo, max = LOG_MAX_BYTES, keep = LOG_KEEP } = {}) {
+  const doEcho = echo ?? shouldEchoToStdout({ env });
+  let queue = Promise.resolve();
+  return (line = "") => {
+    if (doEcho) process.stdout.write(`${line}\n`);
+    queue = queue
+      .then(async () => {
+        await mkdir(logDir(env), { recursive: true });
+        await rotateIfNeeded({ max, keep, env });
+        await appendFile(logPath(env), `${new Date().toISOString()} ${line}\n`, "utf8");
+      })
+      .catch(() => {});
+    return queue;
+  };
+}

package/lib/mcpjson.mjs

@@ -0,0 +1,242 @@
+// Fresh configs write viewable (#2328). Existing glytch entries stay readable and keep their name (#2196).
+// .mcp.json, as `glytch init` writes it.
+//
+// ONE WRITER SINCE 2026-10-15 (#494). The app had a second copy of these
+// rules (src/folder/mcpConfig.ts) behind a Help button; that button went
+// with the old Help, and its copy with it. The rules are pinned by
+// bridge/test/fixtures/mcp-json-cases.json, read by bridge/test/mcpjson.test.mjs.
+//
+// THE FIXTURE BRIEFLY DIVERGED HERE, 2026-09-12 (brief 31, Move 3): this side
+// took the `glytch` rename first, writing the key below, and the fixture was
+// forked into mcp-json-cases.bridge.json so `src/folder/mcpConfig.ts` (which
+// still wrote `board`) would not break. REUNITED the same day (Move 3b): that
+// file now writes `glytch` too, with the same rename-in-place and cleanup
+// rules, so this fixture is shared again and the fork is gone.
+//
+// The rules, all three of them, are the app's and are quoted from it:
+//
+//   PRESENCE IS THE KEY, NOT THE VALUE. A dev checkout named a file, a
+//   stranger's named the installed binary. Both are correct, so a `glytch`
+//   key in any shape means connected and nothing is written (one exception,
+//   2026-10-03: a url at the retired address is moved, see below).
+//
+//   A FILE WE CANNOT PARSE IS NEVER REPLACED. It is someone's work.
+//
+//   A FILE WITH NO mcpServers KEY IS STILL SOMEONE'S CONFIG, so the key is
+//   added to it rather than the file being replaced.
+//
+// RENAMED 2026-09-12 (brief 31, Move 3, ruling 3): the key WRITTEN is
+// `glytch`, not `board` - "board" is the product the user thinks on, "glytch"
+// is what the server is called from here on. An existing `board` entry
+// whose `url` is ours (`BOARD_MCP_URL`) is recognised as this package's own
+// and renamed to `glytch` IN PLACE, the same upgrade path a legacy
+// `command`/`args` entry already took - `mergeBoardServer` below treats
+// "ours by url" and "ours by legacy command" as the same `kind:"legacy"`
+// outcome, because both mean "this is our entry, just under the old key."
+// A `board` entry that is neither (a stranger's own remote server, still
+// legitimately named "board") is left exactly alone, `kind:"present"`,
+// same as it always was. And a folder that already has BOTH - a `glytch`
+// entry from a previous `init` plus a leftover `board` entry this rename
+// left behind - gets the stale `board` table dropped on the next run.
+//
+// MOVED 2026-10-24: the board uses `https://app.viewable.one/mcp`; both older
+// app hosts are retired (a Cloudflare redirect sends it to app, but a
+// cross-origin redirect drops the Authorization header, so an agent config
+// still naming the old address stops working rather than following). An entry
+// at either RETIRED_BOARD_MCP_URLS address is ours exactly like one at the current URL, and
+// wherever a merge keeps an entry of ours its `url` is replaced with the
+// current one, keeping its other fields (`moveRetiredUrl` below). An entry at
+// any OTHER url (a developer's GLYTCH_BOARD_URL, a stranger's server) is not
+// touched.
+//
+// THE SHAPE NOW is one hosted endpoint, not a spawned binary: the board lives
+// behind `https://app.viewable.one/mcp` (a streamable-HTTP MCP server, OAuth
+// with dynamic client registration - routes.json rewrites `/mcp` and the
+// `/.well-known/` and `/oauth/*` discovery routes to the `board-mcp` and
+// `board-oauth` Supabase functions), so there is no more per-platform branch:
+// an HTTP url needs no shell to spawn it, so ruling 2A's `cmd /c` wrapper
+// does not exist on this shape at all. `BOARD_MCP_URL` is read at call time,
+// not fixed at import time, so a test (or a developer's shell) can point it
+// at another deployment with `GLYTCH_BOARD_URL` without a second copy of the
+// default living anywhere else. `env` rather than `platform` is the only
+// axis every writer below now takes, for the same reason ruling 2A took
+// `platform` before it: the axis a shape can vary on has to be an argument,
+// not an assumption about the machine running this code.
+import { runnerApiUrlFrom } from "./runnerApi.mjs";
+import { DEFAULT_APP_URL } from "./auth.mjs";
+import { RETIRED_APP_URL, RETIRED_APP_URLS } from "./retired-address.mjs";
+
+export const DEFAULT_BOARD_MCP_URL = "https://app.viewable.one/mcp";
+/** The address this package wrote until 2026-10-03. ONE definition: every
+ * other bridge file imports it from here. */
+export const RETIRED_BOARD_MCP_URL = `${RETIRED_APP_URL}/mcp`;
+export const RETIRED_BOARD_MCP_URLS = RETIRED_APP_URLS.map(origin => `${origin}/mcp`);
+export const BOARD_MCP_URL = (env = process.env) => {
+  const value = (env?.VIEWABLE_BOARD_URL ?? env?.GLYTCH_BOARD_URL);
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : DEFAULT_BOARD_MCP_URL;
+};
+/** Run children already have a bearer, so use the runner's direct function
+ * host for the production MCP endpoint. Keep discovered/custom endpoints.
+ * The hosted project address stays owned by runnerApiUrlFrom (#813). */
+export function runnerMcpUrlFrom({ appUrl, mcpUrl }, env = process.env) {
+  if (appUrl !== DEFAULT_APP_URL || mcpUrl !== DEFAULT_BOARD_MCP_URL) return mcpUrl;
+  const runnerUrl = new URL(runnerApiUrlFrom(appUrl, env));
+  // A trailing slash still names the runner endpoint, not a directory.
+  runnerUrl.pathname = runnerUrl.pathname.replace(/\/+$/, "");
+  return new URL("board-mcp", runnerUrl).href;
+}
+
+/** Seconds Codex lets one board tool call run. check_answer can hold a call
+ *  up to 50s waiting for the person's answer; Codex's own default is 60s. */
+export const CODEX_TOOL_TIMEOUT_SEC = 120;
+
+/** THE SHAPE EVERY WRITER PRODUCES NOW, on every platform: a remote MCP
+ * server, described the way Claude Code's own `claude mcp add --transport
+ * http` produces one. `env` stays a parameter (rather than reading
+ * `process.env` inline) for the same reason `boardServerFor` used to take
+ * `platform`: a test, or `GLYTCH_BOARD_URL` in a developer's shell, needs to
+ * say which URL without a second implementation. */
+export const boardServerFor = (env = process.env) => ({ type: "http", url: BOARD_MCP_URL(env) });
+
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+// Two-space JSON with a trailing newline - what every editor and every
+// formatter in this repo writes, so adding one entry does not show up as a
+// whole-file diff.
+const render = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+/** Is this `command`/`args` pair one of the shapes THIS PACKAGE ITSELF wrote
+ * before the local server was retired? Recognised regardless of which writer
+ * produced it or which platform it ran on:
+ *
+ *   - `pm-agent` (a bin alias every version up to 0.6.0 installed, spawned
+ *     bare; 0.7.0 stopped shipping it, which is exactly why configs naming
+ *     it have to be found and rewritten)
+ *   - `glytch` with `mcp` among its args (ruling 2 of brief 19, POSIX)
+ *   - `cmd` with `glytch` and `mcp` among its args (ruling 2A, native Windows)
+ *   - `node` with an arg ending `pm-agent.mjs` (a dev checkout's own spelling
+ *     of the same server)
+ *
+ * Anything else - a custom command, a disabled entry, someone's own remote
+ * server named "board" - is NOT recognised, and stays exactly as the
+ * presence rule above has always left it. This is the one place that
+ * definition lives; lib/project-mcp.mjs imports it rather than repeating it,
+ * so Codex and opencode upgrade the same shapes .mcp.json does. */
+export function isLegacyBoardCommand(command, args) {
+  const list = Array.isArray(args) ? args.filter((a) => typeof a === "string") : [];
+  if (command === "pm-agent") return true;
+  if (command === "glytch" && list.includes("mcp")) return true;
+  if (command === "cmd" && list.includes("glytch") && list.includes("mcp")) return true;
+  if (command === "node" && list.some((a) => a.replace(/\\/g, "/").endsWith("pm-agent.mjs"))) return true;
+  return false;
+}
+
+/** Is this entry sitting at the retired address, and is that address not the
+ * one this run is pointed at (a developer who set GLYTCH_BOARD_URL to the old
+ * host on purpose has nothing to move)? Shared by every writer: Codex's TOML
+ * and opencode's JSON carry the same `url` key. */
+export function entryIsAtRetiredUrl(entry, env) {
+  return isObject(entry) && RETIRED_BOARD_MCP_URLS.includes(entry.url) && BOARD_MCP_URL(env) !== entry.url;
+}
+
+/** The entry with its retired `url` replaced by the current one and every
+ * other field kept; any other entry comes back as the same object. */
+export function moveRetiredUrl(entry, env) {
+  return entryIsAtRetiredUrl(entry, env) ? { ...entry, url: BOARD_MCP_URL(env) } : entry;
+}
+
+/** Is this `board` entry ours - either the old spawned-command shape
+ * (`isLegacyBoardCommand`) or already the hosted-URL shape this package
+ * itself wrote before the rename (`url` matches `BOARD_MCP_URL`, or the
+ * retired address this package wrote before 2026-10-03)? Either
+ * way it is safe to rename to `glytch` rather than a stranger's own server
+ * that merely happens to be named "board".
+ *
+ * EXPORTED (brief 31 review, 2026-09-12) so lib/uninstall-project.mjs can
+ * use this exact check for `.mcp.json` rather than keeping its own
+ * byte-identical copy - the removal side of this file's merge needs the
+ * same "is this ours" answer the merge itself does. */
+export function boardEntryIsOurs(entry, env) {
+  if (!isObject(entry)) return false;
+  if (isLegacyBoardCommand(entry.command, entry.args)) return true;
+  return typeof entry.url === "string" && (entry.url === BOARD_MCP_URL(env) || RETIRED_BOARD_MCP_URLS.includes(entry.url));
+}
+
+/** Decide what to write, given whatever is on disk (null = no file).
+ *
+ *  Returns one of:
+ *    {kind:"create", text}  - no file at all; `text` is a whole new one
+ *    {kind:"add", text}     - a file with other servers; `text` is it plus glytch
+ *    {kind:"legacy", text}  - an existing `board` entry is OUR OWN, either the
+ *                             retired spawned-command shape
+ *                             (isLegacyBoardCommand) or the hosted-URL shape
+ *                             written under the old key; `text` is it
+ *                             renamed to `glytch` in place (a legacy command
+ *                             entry is replaced with the canonical server
+ *                             value; a url-match entry keeps its own other
+ *                             fields). Also covers the cleanup case where
+ *                             both `glytch` and a stale `board` (ours) are
+ *                             present - `text` drops the leftover `board`.
+ *                             `moved:true` is added when the retired address
+ *                             was replaced (so a caller's message can say
+ *                             "moved to app.viewable.one", not "upgraded from
+ *                             the old command shape"). An existing `glytch`
+ *                             entry at the retired address is rewritten the
+ *                             same way; one at any other url is untouched.
+ *    {kind:"present"}       - already has a `board` server we do not
+ *                             recognise as ours, or already has `glytch`
+ *                             with no stale `board` to clean up; nothing
+ *                             touched
+ *    {kind:"unreadable"}    - there is a file and we cannot extend it; never
+ *                             written over
+ */
+export function mergeBoardServer(existing, env = process.env) {
+  const server = boardServerFor(env);
+  if (existing === null || existing === undefined || existing.trim() === "") {
+    return { kind: "create", text: render({ mcpServers: { viewable: server } }) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (!isObject(parsed)) return { kind: "unreadable" };
+
+  const servers = parsed.mcpServers;
+  if (servers === undefined) {
+    return { kind: "add", text: render({ ...parsed, mcpServers: { viewable: server } }) };
+  }
+  if (!isObject(servers)) return { kind: "unreadable" };
+
+  // Read old, write new: keep either existing product entry without duplicating it (#2196).
+  if ("viewable" in servers) return { kind: "present" };
+  const boardEntry = servers.board;
+  const boardIsOurs = boardEntryIsOurs(boardEntry, env);
+
+  if (!("glytch" in servers)) {
+    if (!("board" in servers)) {
+      return { kind: "add", text: render({ ...parsed, mcpServers: { ...servers, viewable: server } }) };
+    }
+    if (!boardIsOurs) return { kind: "present" };
+    const { board: _dropped, ...rest } = servers;
+    const renamed = isLegacyBoardCommand(boardEntry.command, boardEntry.args) ? server : moveRetiredUrl(boardEntry, env);
+    return {
+      kind: "legacy",
+      ...(entryIsAtRetiredUrl(boardEntry, env) ? { moved: true } : {}),
+      text: render({ ...parsed, mcpServers: { ...rest, glytch: renamed } }),
+    };
+  }
+
+  // `glytch` is already there. A leftover `board` entry that is ours (from
+  // before this rename shipped, or from a folder init'd between the two) is
+  // dropped; anything else about the file, including a stranger's own
+  // "board" server, is left exactly as it is. A `glytch` entry at the retired
+  // address is ours too, and moves to the current one.
+  const glytchMoved = entryIsAtRetiredUrl(servers.glytch, env);
+  if (!boardIsOurs && !glytchMoved) return { kind: "present" };
+  const { board: _dropped, ...rest } = servers;
+  const next = boardIsOurs ? rest : { ...servers };
+  if (glytchMoved) next.glytch = moveRetiredUrl(servers.glytch, env);
+  return { kind: "legacy", ...(glytchMoved ? { moved: true } : {}), text: render({ ...parsed, mcpServers: next }) };
+}

package/lib/memberPreview.mjs

@@ -0,0 +1,165 @@
+/** Board-member authorization around an outbound preview transport. No bearer
+ * Supabase session ever leaves the app: this verifies preview-scoped grants. */
+import { createPublicKey, randomBytes, randomUUID, verify } from "node:crypto";
+import { createPreviewGateway } from "./previewGateway.mjs";
+import { startQuickPreviewTunnel } from "./previewTunnel.mjs";
+
+export const PREVIEW_COOKIE = "__glytch_preview";
+const AUTH_PATH = "/__glytch_preview/auth";
+const SESSION_PATH = "/__glytch_preview/session";
+
+export function previewAuthConfig(env = process.env) {
+  if (!env.PREVIEW_VERIFY_JWK || !env.PM_PREVIEW_APP_ORIGINS) {
+    throw new Error("Shared preview access is not configured. Set PREVIEW_VERIFY_JWK and PM_PREVIEW_APP_ORIGINS on this runner after deploying preview-grant.");
+  }
+  let key;
+  try {
+    const jwk = JSON.parse(env.PREVIEW_VERIFY_JWK);
+    if (jwk.kty !== "RSA" || jwk.d) throw new Error("public RSA key required");
+    key = createPublicKey({ key: jwk, format: "jwk" });
+    if (key.asymmetricKeyDetails.modulusLength < 2048) throw new Error("RSA key too small");
+  } catch { throw new Error("PREVIEW_VERIFY_JWK must contain a public RSA JWK of at least 2048 bits."); }
+  const appOrigins = env.PM_PREVIEW_APP_ORIGINS.split(",").map((s) => s.trim()).filter(Boolean);
+  if (!appOrigins.length || appOrigins.some((s) => {
+    try {
+      const u = new URL(s);
+      return u.origin !== s || u.hostname.includes("*") || (u.protocol !== "https:" && !(u.protocol === "http:" && ["localhost", "127.0.0.1"].includes(u.hostname)));
+    } catch { return true; }
+  })) throw new Error("PM_PREVIEW_APP_ORIGINS must list exact HTTPS app origins (HTTP loopback is allowed for local development).");
+  return { key, appOrigins };
+}
+
+export function verifyPreviewGrant(token, key, expected, now = Date.now()) {
+  try {
+    if (typeof token !== "string" || token.length > 8192) return null;
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some((p) => !/^[A-Za-z0-9_-]+$/.test(p))) return null;
+    const [header, claims] = parts.slice(0, 2).map((p) => JSON.parse(Buffer.from(p, "base64url").toString("utf8")));
+    if (header.alg !== "RS256" || header.typ !== "JWT" || header.crit) return null;
+    if (!verify("RSA-SHA256", Buffer.from(`${parts[0]}.${parts[1]}`), key, Buffer.from(parts[2], "base64url"))) return null;
+    if (claims.iss !== "glytch-preview" || typeof claims.sub !== "string" || !claims.sub) return null;
+    for (const field of ["aud", "boardId", "workspaceId", "nodeId", "runKey", "previewId"]) {
+      if (typeof expected[field] !== "string" || !expected[field] || claims[field] !== expected[field]) return null;
+    }
+    if (!Number.isInteger(claims.iat) || !Number.isInteger(claims.exp) || claims.exp * 1000 <= now ||
+      claims.iat * 1000 > now + 5000 || claims.exp <= claims.iat || claims.exp - claims.iat > 60) return null;
+    return claims;
+  } catch { return null; }
+}
+
+function cookie(req) {
+  const matches = String(req.headers.cookie ?? "").split(";").map((s) => s.trim()).filter((s) => s.startsWith(`${PREVIEW_COOKIE}=`));
+  return matches.length === 1 ? matches[0].slice(PREVIEW_COOKIE.length + 1) : "";
+}
+
+const json = (res, status, body, extra = {}) => {
+  res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", ...extra });
+  res.end(JSON.stringify(body));
+};
+
+function authPage(appOrigins, nonce) {
+  // Only the dedicated parent iframe can exchange a grant. Neither grant nor
+  // the application session token appears in a URL, referrer, or app response.
+  const origins = JSON.stringify(appOrigins).replaceAll("<", "\\u003c");
+  return `<!doctype html><meta charset="utf-8"><title>Preview access</title><script nonce="${nonce}">
+const origins = ${origins};
+addEventListener('message', async (event) => {
+  if (event.source !== parent || !origins.includes(event.origin) || event.data?.type !== 'glytch-preview-grant') return;
+  try {
+    const response = await fetch('${SESSION_PATH}', {method:'POST', credentials:'include', headers:{'content-type':'application/json'}, body:JSON.stringify({grant:event.data.grant})});
+    const result = await response.json();
+    if (!response.ok) throw Error();
+    const confirmed = await fetch('${SESSION_PATH}', {credentials:'include',cache:'no-store'});
+    if (!confirmed.ok) throw Error();
+    parent.postMessage({type:'glytch-preview-authorized',expiresAt:result.expiresAt}, event.origin);
+  } catch { parent.postMessage({type:'glytch-preview-error'}, event.origin); }
+});
+for (const origin of origins) parent.postMessage({type:'glytch-preview-ready'}, origin);
+</script>`;
+}
+
+/** Tests inject transport, not authorization. Production always checks grants. */
+export async function createMemberPreviewTunnel(origin, context, {
+  env = process.env, startTransport = startQuickPreviewTunnel, now = Date.now,
+} = {}) {
+  context.signal?.throwIfAborted();
+  const { key, appOrigins } = previewAuthConfig(env);
+  for (const field of ["cloudBoardId", "workspaceId", "nodeId", "runKey"]) {
+    if (typeof context[field] !== "string" || !context[field]) throw new Error(`Shared preview needs ${field}.`);
+  }
+  const previewId = randomUUID();
+  let publicOrigin;
+  const expected = () => ({ aud: publicOrigin, boardId: context.cloudBoardId, workspaceId: context.workspaceId,
+    nodeId: context.nodeId, runKey: context.runKey, previewId });
+  const check = (token) => publicOrigin && verifyPreviewGrant(token, key, expected(), now());
+  const gateway = await createPreviewGateway({
+    target: origin,
+    authorize: async (req) => {
+      // A partitioned cookie is the primary browser isolation boundary. Also
+      // reject cross-origin writes/upgrades for browsers without CHIPS support.
+      const callerOrigin = req.headers.origin;
+      if (callerOrigin && callerOrigin !== publicOrigin) return false;
+      if ((!['GET', 'HEAD', 'OPTIONS'].includes(req.method) || req.headers.upgrade) && callerOrigin !== publicOrigin) return false;
+      const grant = check(cookie(req));
+      if (!grant) return false;
+      if (context.authorizeTarget && !await context.authorizeTarget()) return false;
+      // Ownership verification may take time; never forward an expired lease.
+      return grant.exp * 1000 > now() ? { expiresAt: grant.exp * 1000 } : false;
+    },
+    handleAuth: async (req, res) => {
+      const path = new URL(req.url, "http://gateway.invalid").pathname;
+      if (!path.startsWith("/__glytch_preview/")) return false;
+      if (!publicOrigin) { json(res, 503, { error: "Preview is connecting." }); return true; }
+      if (path === AUTH_PATH && req.method === "GET") {
+        const nonce = randomBytes(16).toString("base64");
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store",
+          "referrer-policy": "no-referrer", "x-content-type-options": "nosniff",
+          "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${appOrigins.join(" ")}; base-uri 'none'; form-action 'none'` });
+        res.end(authPage(appOrigins, nonce)); return true;
+      }
+      if (path === SESSION_PATH && req.method === "GET") {
+        const claims = check(cookie(req));
+        json(res, claims ? 200 : 403, claims ? { expiresAt: claims.exp * 1000 } : { error: "Preview access is required." });
+        return true;
+      }
+      if (path !== SESSION_PATH || req.method !== "POST" || req.headers.origin !== publicOrigin ||
+        !String(req.headers["content-type"] ?? "").startsWith("application/json")) {
+        json(res, 403, { error: "Preview access is required." }); return true;
+      }
+      const chunks = []; let length = 0;
+      for await (const chunk of req) {
+        length += chunk.length;
+        if (length > 12_000) { json(res, 413, { error: "Grant is too large." }); return true; }
+        chunks.push(chunk);
+      }
+      let grant;
+      try { grant = JSON.parse(Buffer.concat(chunks).toString("utf8")).grant; } catch { /* refused below */ }
+      const claims = check(grant);
+      if (!claims) { json(res, 403, { error: "Preview access expired or does not match this board." }); return true; }
+      json(res, 200, { expiresAt: claims.exp * 1000 }, { "set-cookie":
+        `${PREVIEW_COOKIE}=${grant}; Path=/; Max-Age=${Math.max(0, Math.floor((claims.exp * 1000 - now()) / 1000))}; Secure; HttpOnly; SameSite=None; Partitioned` });
+      return true;
+    },
+  });
+  let transport;
+  try {
+    transport = await startTransport(gateway.origin, { bin: env.PM_CLOUDFLARED_BIN, signal: context.signal });
+    context.signal?.throwIfAborted();
+    const remote = new URL(transport.url);
+    if (remote.protocol !== "https:" || remote.username || remote.password ||
+      ["localhost", "127.0.0.1", "[::1]"].includes(remote.hostname)) throw new Error("Preview transport must supply a public HTTPS origin.");
+    publicOrigin = remote.origin;
+    const local = new URL(context.fullLocalUrl ?? context.localUrl ?? origin);
+    const url = `${publicOrigin}${local.pathname}${local.search}${local.hash}`;
+    let stopped = false;
+    return { previewId, url, alive: () => !stopped && (transport.alive?.() ?? true), stop: async () => {
+      if (stopped) return; stopped = true;
+      // Close the authorized gateway first even if the transport refuses to die.
+      await gateway.close(); await transport.stop();
+    } };
+  } catch (error) {
+    await gateway.close();
+    try { await transport?.stop(); } catch { /* gateway is already unreachable */ }
+    throw error;
+  }
+}