@apps-in-toss/devtools 3.0.5 → 3.1.0-beta.1

package/dist/unplugin/index.js

@@ -2,6 +2,71 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createUnplugin } from "unplugin";
+//#region src/shared/parent-watcher.ts
+/**
+* Shared parent-PID watcher — used by both the MCP debug daemon and the
+* unplugin tunnel path to self-terminate when the parent process (e.g. Claude
+* Code, vite) has died or been reparented without sending SIGTERM/SIGHUP.
+*
+* Intentionally react-free and Node-stdlib-only so this module is safe to
+* import from the MCP daemon bundle (`dist/mcp/cli.js`) without violating the
+* install-graph invariant.
+*/
+/**
+* Returns `true` when the given PID refers to a running process.
+*
+* Uses `process.kill(pid, 0)` — a no-op signal that succeeds when the process
+* exists and we have permission to signal it; throws ESRCH when it doesn't exist.
+*/
+function isPidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		if (err.code === "EPERM") return true;
+		return false;
+	}
+}
+/**
+* Starts a periodic watcher that detects when the parent process (e.g. Claude
+* Code) has died without sending SIGTERM/SIGHUP, and calls `onOrphaned` so the
+* daemon can self-terminate rather than running as a zombie.
+*
+* Mirrors the `startAttachWatcher` pattern: `setInterval`-based, returns
+* `{ stop(): void }`, injectable deps for testability.
+*
+* @param onOrphaned - Called once when the parent is gone.
+* @param opts.intervalMs   - Poll interval in milliseconds (default 5 000).
+* @param opts.initialPpid  - Parent PID to watch (default `process.ppid`).
+* @param opts.isAlive      - Predicate to test if a PID is running (default `isPidAlive`).
+* @param opts.getPpid      - Supplier of current ppid (default `() => process.ppid`).
+*                            Detects ppid changes as well as death.
+* @param opts.log          - Logger (default `process.stderr.write`).
+*
+* @returns `stop` — call during shutdown to clear the interval.
+*/
+function startParentWatcher(onOrphaned, opts) {
+	const { intervalMs = 5e3, initialPpid = process.ppid, isAlive = isPidAlive, getPpid = () => process.ppid, log = (msg) => process.stderr.write(msg) } = opts ?? {};
+	if (initialPpid <= 1) {
+		log("[ait-debug] parent-pid watcher: no parent to watch (ppid<=1), skipping\n");
+		return { stop() {} };
+	}
+	let fired = false;
+	const handle = setInterval(() => {
+		if (fired) return;
+		const currentPpid = getPpid();
+		if (currentPpid !== initialPpid || !isAlive(initialPpid)) {
+			fired = true;
+			clearInterval(handle);
+			log(`[ait-debug] parent-pid watcher: parent PID ${initialPpid} is gone (currentPpid=${currentPpid}) — shutting down\n`);
+			onOrphaned();
+		}
+	}, intervalMs);
+	return { stop() {
+		clearInterval(handle);
+	} };
+}
+//#endregion
 //#region src/unplugin/index.ts
 /**
 * @apps-in-toss/devtools unplugin
@@ -55,14 +120,6 @@ function detectInstalledSdkMajor(cwd = process.cwd()) {
 	} catch {}
 	return null;
 }
-/**
-* 패널 자동 주입 대상 진입점 파일명 기본 패턴. `entryPattern` 옵션 미지정 시
-* 사용된다. `id.test()`는 상태를 갖지 않아야 하므로(매 파일마다 호출) 이
-* 패턴과 사용자 지정 `entryPattern` 모두 `g`/`y` 플래그를 붙이지 않는다는
-* 전제다 — `RegExp.prototype.test`는 global/sticky 플래그가 있으면 호출마다
-* `lastIndex`가 전진해 다음 파일 매칭이 간헐적으로 실패한다.
-*/
-const DEFAULT_ENTRY_PATTERN = /\/(main|index|entry|app)\.[tj]sx?$/i;
 const FRAMEWORK_ID = "@apps-in-toss/web-framework";
 const BRIDGE_ID = "@apps-in-toss/web-bridge";
 const ANALYTICS_ID = "@apps-in-toss/web-analytics";
@@ -71,14 +128,40 @@ const WEBVIEW_BRIDGE_ID = "@apps-in-toss/webview-bridge";
 const MCP_STATE_PATH = "/api/ait-devtools/state";
 /** Browser runtime opt-in consumed by the panel's state-sync helper. */
 const MCP_ENABLE_SNIPPET = "globalThis.__AIT_DEVTOOLS_MCP_ENABLED__ = true;";
+/**
+* Resolves the effective tunnel option (#425).
+*
+* An explicit `tunnel` value (including `false`) always takes priority over
+* env vars — the `??` operator means `undefined` (= omitted) falls through,
+* but `false` / `true` / an object are preserved as-is (non-breaking).
+*
+* When the option is omitted:
+* - `AIT_TUNNEL=1` enables the screen-preview tunnel.
+* - Not set → `false` (disabled).
+*
+* Extracted as a pure function so it can be unit-tested without standing up
+* a full Vite dev server.
+*
+* @param explicit - The `tunnel` option as passed by the consumer (or `undefined` when omitted).
+* @param env - The process environment (injectable for testing).
+*/
+function resolveTunnelOption(explicit, env) {
+	return explicit ?? !!env.AIT_TUNNEL;
+}
 const aitDevtoolsPlugin = createUnplugin((options) => {
 	const isDev = process.env.NODE_ENV !== "production";
-	const shouldEnable = isDev || !!options?.forceEnable;
+	const shouldEnable = isDev;
 	const shouldMock = shouldEnable && (options?.mock ?? isDev);
 	const sdkMajor = options?.sdkVersion === "2" || options?.sdkVersion === "3" ? options.sdkVersion : detectInstalledSdkMajor() ?? "3";
 	const shouldPanel = shouldEnable && (options?.panel ?? true);
 	const shouldMcp = shouldEnable && (options?.mcp ?? false);
 	let lastState = null;
+	const tunnelOpt = resolveTunnelOption(options?.tunnel, process.env);
+	const shouldTunnel = isDev && !!tunnelOpt;
+	const webViewType = options?.webViewType ?? "partner";
+	const navBarTransparent = options?.navBarTransparent;
+	const navBarTheme = options?.navBarTheme;
+	const tunnelConfig = typeof tunnelOpt === "object" ? tunnelOpt : {};
 	return {
 		name: "ait-co-devtools",
 		enforce: "pre",
@@ -93,7 +176,7 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 		},
 		transformInclude(id) {
 			if (!shouldPanel && !shouldMcp) return false;
-			return /\.(tsx?|jsx?)$/.test(id) && (options?.entryPattern ?? DEFAULT_ENTRY_PATTERN).test(id) && !id.includes("node_modules");
+			return /\.(tsx?|jsx?)$/.test(id) && /\/(main|index|entry|app)\.[tj]sx?$/i.test(id) && !id.includes("node_modules");
 		},
 		transform(code) {
 			let result = code;
@@ -110,8 +193,12 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 		},
 		vite: {
 			config() {
-				if (options?.initialState === void 0) return {};
-				return { define: { __AIT_INITIAL_STATE__: JSON.stringify(options.initialState) } };
+				const define = { __WEB_VIEW_TYPE__: JSON.stringify(webViewType) };
+				if (!shouldTunnel) return { define };
+				return {
+					define,
+					server: { allowedHosts: [".trycloudflare.com"] }
+				};
 			},
 			configureServer(server) {
 				if (shouldMcp) server.middlewares.use(MCP_STATE_PATH, (req, res) => {
@@ -153,6 +240,53 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 					res.writeHead(405, { "Content-Type": "application/json" });
 					res.end(JSON.stringify({ error: "Method not allowed" }));
 				});
+				if (shouldTunnel) {
+					let tunnel = null;
+					let parentWatcher = null;
+					const httpServer = server.httpServer;
+					httpServer?.once("listening", () => {
+						const address = httpServer?.address();
+						const port = tunnelConfig.port ?? (address && typeof address === "object" ? address.port : void 0);
+						if (!port) {
+							console.warn("[@apps-in-toss/devtools] tunnel: could not determine the dev server port; skipping.");
+							return;
+						}
+						import("../tunnel-BvEf1qGV.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
+							const t = await startQuickTunnel(port);
+							tunnel = t;
+							let tunnelAppName;
+							try {
+								const { readFileSync } = await import("node:fs");
+								const pkgRaw = readFileSync(`${server.config.root}/package.json`, "utf8");
+								const pkg = JSON.parse(pkgRaw);
+								const rawName = typeof pkg.name === "string" ? pkg.name : "";
+								tunnelAppName = (rawName.includes("/") ? rawName.slice(rawName.indexOf("/") + 1) : rawName).trim() || void 0;
+							} catch {}
+							await printTunnelBanner(t.url, {
+								qr: tunnelConfig.qr,
+								name: tunnelAppName,
+								webViewType,
+								navBarTransparent,
+								navBarTheme
+							});
+							parentWatcher = startParentWatcher(() => {
+								cleanup();
+								process.exit(0);
+							});
+						}).catch((err) => {
+							console.warn(`[@apps-in-toss/devtools] tunnel failed to start: ${err instanceof Error ? err.message : String(err)}`);
+						});
+					});
+					const cleanup = () => {
+						parentWatcher?.stop();
+						tunnel?.stop();
+					};
+					httpServer?.once("close", cleanup);
+					process.once("SIGINT", cleanup);
+					process.once("SIGTERM", cleanup);
+					process.once("SIGHUP", cleanup);
+					process.once("exit", cleanup);
+				}
 			}
 		}
 	};
@@ -164,4 +298,4 @@ const esbuild = aitDevtoolsPlugin.esbuild;
 const rspack = aitDevtoolsPlugin.rspack;
 const aitDevtools = aitDevtoolsPlugin;
 //#endregion
-export { aitDevtools as default, detectInstalledSdkMajor, esbuild, rollup, rspack, vite, webpack };
+export { aitDevtools as default, detectInstalledSdkMajor, esbuild, resolveTunnelOption, rollup, rspack, vite, webpack };

package/dist/unplugin/tunnel.cjs

@@ -0,0 +1,191 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+//#region src/unplugin/tunnel.ts
+/**
+* Cloudflare quick-tunnel helper for the devtools unplugin.
+*
+* Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+* on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+* case. This is the one place in `@apps-in-toss/devtools` that depends on Node-only
+* APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+* jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+* "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+* (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+*/
+/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */
+const TRYCLOUDFLARE_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+/**
+* Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+* output, or `null` if the line doesn't contain one. Pulled out as a pure
+* function so it can be unit-tested without spawning anything.
+*/
+function parseTrycloudflareUrl(line) {
+	const m = line.match(TRYCLOUDFLARE_RE);
+	return m ? m[0] : null;
+}
+const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
+/**
+* Build the deep-link URL that QR codes encode: when the launcher PWA is
+* already on the phone's home screen, scanning this opens it directly into the
+* live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).
+* Plain-text raw URL is no longer enough — the launcher gates its setup UI to
+* the installed PWA, so a raw tunnel URL opened in a normal browser tab would
+* land on a "please install" screen.
+*
+* When `opts.name` is given (non-blank), it is added as `&name=` so the launcher
+* partner bar shows the app name instead of the generic default (#498).
+*
+* When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the
+* launcher enters game nav chrome (floating capsule, no full bar) automatically
+* on scan. `'partner'` is the launcher's implicit default and is not added to
+* keep the URL clean (#584).
+*
+* When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended
+* so the launcher partner bar renders with a transparent background (#587).
+*
+* When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is
+* appended so the launcher partner bar uses the matching foreground colour (#587).
+*/
+function buildLauncherDeepLink(tunnelUrl, optsParam) {
+	const opts = optsParam ?? {};
+	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (opts.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts.webViewType === "game") url += "&navBarType=game";
+	if (opts.navBarTransparent === true) url += "&navBarTransparent=1";
+	if (opts.navBarTheme === "light" || opts.navBarTheme === "dark") url += `&navBarTheme=${opts.navBarTheme}`;
+	return url;
+}
+/**
+* Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+* QR encoding a launcher deep-link, and a one-line note that quick tunnels are
+* ephemeral, unauthenticated and not for production. Pure w.r.t. side effects
+* other than the injected `log` sink and `qrcode-terminal` — unit-tested.
+*/
+async function printTunnelBanner(url, opts = {}) {
+	const log = opts.log ?? ((m) => console.log(m));
+	const deepLink = buildLauncherDeepLink(url, {
+		name: opts.name,
+		webViewType: opts.webViewType,
+		navBarTransparent: opts.navBarTransparent,
+		navBarTheme: opts.navBarTheme
+	});
+	log([
+		"",
+		"  ┌─ @apps-in-toss/devtools · live tunnel ────────────────────────────",
+		`  │  ${url}`,
+		"  │",
+		`  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,
+		"  │  Then scan the QR below — it opens the launcher directly",
+		"  │  into this tunnel URL (no manual paste needed).",
+		"  │  Quick tunnels are unauthenticated, change every run, and are",
+		"  │  not for production use.",
+		"  └──────────────────────────────────────────────────────────────",
+		""
+	].join("\n"));
+	if (opts.qr !== false) {
+		const qrcode = (await import("qrcode-terminal")).default;
+		await new Promise((resolve) => {
+			qrcode.generate(deepLink, { small: true }, (out) => {
+				log(out);
+				resolve();
+			});
+		});
+	}
+}
+/**
+* Sanitize cloudflared stderr output for error diagnostics (#421).
+*
+* Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs
+* that carry those hostnames so tunnel host values never appear in error
+* messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.
+*
+* SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only
+* placeholder text is emitted.
+*/
+function sanitizeCloudflaredOutput(line) {
+	let s = line.replace(/(?:https?|wss?):\/\/[a-z0-9-]+\.trycloudflare\.com(?:\/[^\s]*)*/gi, (m) => m.replace(/[a-z0-9-]+\.trycloudflare\.com/i, "<HOST>.trycloudflare.com"));
+	s = s.replace(/[a-z0-9-]+\.trycloudflare\.com/gi, "<HOST>.trycloudflare.com");
+	return s;
+}
+const URL_TIMEOUT_MS = 2e4;
+/**
+* Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+* and resolve once the public URL is known. Downloads the `cloudflared` binary
+* on first use if it is not already installed. Rejects with a friendly error if
+* no URL appears within {@link URL_TIMEOUT_MS}.
+*/
+async function startQuickTunnel(port) {
+	const { bin, install, Tunnel } = await import("cloudflared");
+	if (!(0, node_fs.existsSync)(bin)) {
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(bin), { recursive: true });
+		await install(bin);
+	}
+	const tunnel = Tunnel.quick(`http://localhost:${port}`);
+	let stopped = false;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		try {
+			tunnel.stop();
+		} catch {}
+	};
+	return new Promise((resolve, reject) => {
+		const stderrLines = [];
+		/**
+		* Format the last `n` sanitized stderr lines as a diagnostic appendix.
+		* Returns an empty string when no lines have been collected.
+		*/
+		const stderrTail = (n = 15) => {
+			if (stderrLines.length === 0) return "";
+			const tail = stderrLines.slice(-n).map(sanitizeCloudflaredOutput).join("");
+			return `\ncloudflared 출력 (마지막 ${Math.min(n, stderrLines.length)}줄):\n${tail}`;
+		};
+		const timer = setTimeout(() => {
+			cleanup();
+			stop();
+			reject(/* @__PURE__ */ new Error(`[@apps-in-toss/devtools] cloudflared did not report a tunnel URL within ${URL_TIMEOUT_MS / 1e3}s. Check your network connection, or run \`cloudflared tunnel --url http://localhost:${port}\` manually.${stderrTail()}`));
+		}, URL_TIMEOUT_MS);
+		const onUrl = (line) => {
+			const found = parseTrycloudflareUrl(line);
+			if (!found) return;
+			clearTimeout(timer);
+			cleanup();
+			resolve({
+				url: found,
+				stop
+			});
+		};
+		const pushStderr = (line) => {
+			stderrLines.push(line);
+		};
+		const cleanup = () => {
+			tunnel.off("stdout", onUrl);
+			tunnel.off("stderr", onUrl);
+			tunnel.off("stderr", pushStderr);
+		};
+		tunnel.once("url", onUrl);
+		tunnel.on("stdout", onUrl);
+		tunnel.on("stderr", onUrl);
+		tunnel.on("stderr", pushStderr);
+		tunnel.once("error", (err) => {
+			clearTimeout(timer);
+			cleanup();
+			stop();
+			reject(err);
+		});
+		tunnel.once("exit", (code) => {
+			if (stopped) return;
+			clearTimeout(timer);
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`[@apps-in-toss/devtools] cloudflared exited (code ${code ?? "null"}) before reporting a tunnel URL.${stderrTail()}`));
+		});
+	});
+}
+//#endregion
+exports.buildLauncherDeepLink = buildLauncherDeepLink;
+exports.parseTrycloudflareUrl = parseTrycloudflareUrl;
+exports.printTunnelBanner = printTunnelBanner;
+exports.sanitizeCloudflaredOutput = sanitizeCloudflaredOutput;
+exports.startQuickTunnel = startQuickTunnel;

package/dist/unplugin/tunnel.d.cts

@@ -0,0 +1,140 @@
+//#region src/unplugin/tunnel.d.ts
+/**
+ * Cloudflare quick-tunnel helper for the devtools unplugin.
+ *
+ * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+ * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+ * case. This is the one place in `@apps-in-toss/devtools` that depends on Node-only
+ * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+ * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+ * "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+ * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+ */
+/**
+ * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+ * output, or `null` if the line doesn't contain one. Pulled out as a pure
+ * function so it can be unit-tested without spawning anything.
+ */
+declare function parseTrycloudflareUrl(line: string): string | null;
+interface PrintTunnelBannerOptions {
+  /** Print an ASCII QR encoding the tunnel URL (default: true). */
+  qr?: boolean;
+  /** Sink for the banner text (default: `console.log`). Injected for testing. */
+  log?: (msg: string) => void;
+  /**
+   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).
+   * When provided (non-blank), the launcher partner bar shows this name instead of
+   * the generic default.
+   */
+  name?: string;
+  /**
+   * The miniapp's webViewType. When `'game'`, the deep-link carries `&navBarType=game`
+   * so the launcher enters game nav chrome automatically on scan (#584).
+   * `'partner'` (the default) is the launcher's implicit default — not added to
+   * keep the URL clean.
+   */
+  webViewType?: "partner" | "game";
+  /**
+   * Whether the miniapp's navigationBar has `transparentBackground: true`
+   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).
+   * When `true`, the deep-link carries `&navBarTransparent=1` so the launcher
+   * partner bar renders with a transparent background (content shows through).
+   * `false` / omitted → not added (URL clean, back-compat).
+   */
+  navBarTransparent?: boolean;
+  /**
+   * The miniapp's navigationBar theme (`granite.config `navigationBar.theme`,
+   * SDK 2.8.0, #587). When `'light'` or `'dark'`, the deep-link carries
+   * `&navBarTheme=<v>` so the launcher partner bar uses the matching foreground
+   * colour. Omitted / other values → not added (URL clean, back-compat).
+   */
+  navBarTheme?: "light" | "dark";
+}
+/**
+ * Options for {@link buildLauncherDeepLink}.
+ */
+interface BuildLauncherDeepLinkOptions {
+  /**
+   * Human-readable app name shown in the partner nav bar (`name=` param, #498).
+   * Blank / whitespace-only values are not added.
+   */
+  name?: string;
+  /**
+   * The miniapp's webViewType. When `'game'`, adds `&navBarType=game` to the
+   * deep-link so the launcher enters game nav chrome automatically on scan (#584).
+   * `'partner'` (the launcher's implicit default) is not added to keep the URL
+   * clean.
+   */
+  webViewType?: "partner" | "game";
+  /**
+   * Whether the miniapp's navigationBar has `transparentBackground: true`
+   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).
+   * When `true`, adds `&navBarTransparent=1` to the deep-link so the launcher
+   * partner bar renders with a transparent background. Omitted when `false` /
+   * undefined to keep the URL clean (back-compat).
+   */
+  navBarTransparent?: boolean;
+  /**
+   * The miniapp's navigationBar theme (granite.config `navigationBar.theme`,
+   * SDK 2.8.0, #587). When `'light'` or `'dark'`, adds `&navBarTheme=<v>` to
+   * the deep-link so the launcher partner bar uses the matching foreground colour.
+   * Omitted when undefined / other values to keep the URL clean (back-compat).
+   */
+  navBarTheme?: "light" | "dark";
+}
+/**
+ * Build the deep-link URL that QR codes encode: when the launcher PWA is
+ * already on the phone's home screen, scanning this opens it directly into the
+ * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).
+ * Plain-text raw URL is no longer enough — the launcher gates its setup UI to
+ * the installed PWA, so a raw tunnel URL opened in a normal browser tab would
+ * land on a "please install" screen.
+ *
+ * When `opts.name` is given (non-blank), it is added as `&name=` so the launcher
+ * partner bar shows the app name instead of the generic default (#498).
+ *
+ * When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the
+ * launcher enters game nav chrome (floating capsule, no full bar) automatically
+ * on scan. `'partner'` is the launcher's implicit default and is not added to
+ * keep the URL clean (#584).
+ *
+ * When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended
+ * so the launcher partner bar renders with a transparent background (#587).
+ *
+ * When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is
+ * appended so the launcher partner bar uses the matching foreground colour (#587).
+ */
+declare function buildLauncherDeepLink(tunnelUrl: string, optsParam?: BuildLauncherDeepLinkOptions): string;
+/**
+ * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+ * QR encoding a launcher deep-link, and a one-line note that quick tunnels are
+ * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects
+ * other than the injected `log` sink and `qrcode-terminal` — unit-tested.
+ */
+declare function printTunnelBanner(url: string, opts?: PrintTunnelBannerOptions): Promise<void>;
+interface QuickTunnel {
+  /** The public `https://*.trycloudflare.com` URL. */
+  url: string;
+  /** Stop the underlying `cloudflared` process. Idempotent. */
+  stop: () => void;
+}
+/**
+ * Sanitize cloudflared stderr output for error diagnostics (#421).
+ *
+ * Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs
+ * that carry those hostnames so tunnel host values never appear in error
+ * messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.
+ *
+ * SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only
+ * placeholder text is emitted.
+ */
+declare function sanitizeCloudflaredOutput(line: string): string;
+/**
+ * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+ * and resolve once the public URL is known. Downloads the `cloudflared` binary
+ * on first use if it is not already installed. Rejects with a friendly error if
+ * no URL appears within {@link URL_TIMEOUT_MS}.
+ */
+declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
+//#endregion
+export { BuildLauncherDeepLinkOptions, PrintTunnelBannerOptions, QuickTunnel, buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, sanitizeCloudflaredOutput, startQuickTunnel };

package/dist/unplugin/tunnel.d.ts

@@ -0,0 +1,140 @@
+//#region src/unplugin/tunnel.d.ts
+/**
+ * Cloudflare quick-tunnel helper for the devtools unplugin.
+ *
+ * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+ * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+ * case. This is the one place in `@apps-in-toss/devtools` that depends on Node-only
+ * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+ * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+ * "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+ * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+ */
+/**
+ * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+ * output, or `null` if the line doesn't contain one. Pulled out as a pure
+ * function so it can be unit-tested without spawning anything.
+ */
+declare function parseTrycloudflareUrl(line: string): string | null;
+interface PrintTunnelBannerOptions {
+  /** Print an ASCII QR encoding the tunnel URL (default: true). */
+  qr?: boolean;
+  /** Sink for the banner text (default: `console.log`). Injected for testing. */
+  log?: (msg: string) => void;
+  /**
+   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).
+   * When provided (non-blank), the launcher partner bar shows this name instead of
+   * the generic default.
+   */
+  name?: string;
+  /**
+   * The miniapp's webViewType. When `'game'`, the deep-link carries `&navBarType=game`
+   * so the launcher enters game nav chrome automatically on scan (#584).
+   * `'partner'` (the default) is the launcher's implicit default — not added to
+   * keep the URL clean.
+   */
+  webViewType?: "partner" | "game";
+  /**
+   * Whether the miniapp's navigationBar has `transparentBackground: true`
+   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).
+   * When `true`, the deep-link carries `&navBarTransparent=1` so the launcher
+   * partner bar renders with a transparent background (content shows through).
+   * `false` / omitted → not added (URL clean, back-compat).
+   */
+  navBarTransparent?: boolean;
+  /**
+   * The miniapp's navigationBar theme (`granite.config `navigationBar.theme`,
+   * SDK 2.8.0, #587). When `'light'` or `'dark'`, the deep-link carries
+   * `&navBarTheme=<v>` so the launcher partner bar uses the matching foreground
+   * colour. Omitted / other values → not added (URL clean, back-compat).
+   */
+  navBarTheme?: "light" | "dark";
+}
+/**
+ * Options for {@link buildLauncherDeepLink}.
+ */
+interface BuildLauncherDeepLinkOptions {
+  /**
+   * Human-readable app name shown in the partner nav bar (`name=` param, #498).
+   * Blank / whitespace-only values are not added.
+   */
+  name?: string;
+  /**
+   * The miniapp's webViewType. When `'game'`, adds `&navBarType=game` to the
+   * deep-link so the launcher enters game nav chrome automatically on scan (#584).
+   * `'partner'` (the launcher's implicit default) is not added to keep the URL
+   * clean.
+   */
+  webViewType?: "partner" | "game";
+  /**
+   * Whether the miniapp's navigationBar has `transparentBackground: true`
+   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).
+   * When `true`, adds `&navBarTransparent=1` to the deep-link so the launcher
+   * partner bar renders with a transparent background. Omitted when `false` /
+   * undefined to keep the URL clean (back-compat).
+   */
+  navBarTransparent?: boolean;
+  /**
+   * The miniapp's navigationBar theme (granite.config `navigationBar.theme`,
+   * SDK 2.8.0, #587). When `'light'` or `'dark'`, adds `&navBarTheme=<v>` to
+   * the deep-link so the launcher partner bar uses the matching foreground colour.
+   * Omitted when undefined / other values to keep the URL clean (back-compat).
+   */
+  navBarTheme?: "light" | "dark";
+}
+/**
+ * Build the deep-link URL that QR codes encode: when the launcher PWA is
+ * already on the phone's home screen, scanning this opens it directly into the
+ * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).
+ * Plain-text raw URL is no longer enough — the launcher gates its setup UI to
+ * the installed PWA, so a raw tunnel URL opened in a normal browser tab would
+ * land on a "please install" screen.
+ *
+ * When `opts.name` is given (non-blank), it is added as `&name=` so the launcher
+ * partner bar shows the app name instead of the generic default (#498).
+ *
+ * When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the
+ * launcher enters game nav chrome (floating capsule, no full bar) automatically
+ * on scan. `'partner'` is the launcher's implicit default and is not added to
+ * keep the URL clean (#584).
+ *
+ * When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended
+ * so the launcher partner bar renders with a transparent background (#587).
+ *
+ * When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is
+ * appended so the launcher partner bar uses the matching foreground colour (#587).
+ */
+declare function buildLauncherDeepLink(tunnelUrl: string, optsParam?: BuildLauncherDeepLinkOptions): string;
+/**
+ * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+ * QR encoding a launcher deep-link, and a one-line note that quick tunnels are
+ * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects
+ * other than the injected `log` sink and `qrcode-terminal` — unit-tested.
+ */
+declare function printTunnelBanner(url: string, opts?: PrintTunnelBannerOptions): Promise<void>;
+interface QuickTunnel {
+  /** The public `https://*.trycloudflare.com` URL. */
+  url: string;
+  /** Stop the underlying `cloudflared` process. Idempotent. */
+  stop: () => void;
+}
+/**
+ * Sanitize cloudflared stderr output for error diagnostics (#421).
+ *
+ * Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs
+ * that carry those hostnames so tunnel host values never appear in error
+ * messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.
+ *
+ * SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only
+ * placeholder text is emitted.
+ */
+declare function sanitizeCloudflaredOutput(line: string): string;
+/**
+ * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+ * and resolve once the public URL is known. Downloads the `cloudflared` binary
+ * on first use if it is not already installed. Rejects with a friendly error if
+ * no URL appears within {@link URL_TIMEOUT_MS}.
+ */
+declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
+//#endregion
+export { BuildLauncherDeepLinkOptions, PrintTunnelBannerOptions, QuickTunnel, buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, sanitizeCloudflaredOutput, startQuickTunnel };