@ait-co/devtools 0.1.20 → 0.1.22

package/README.en.md

@@ -268,15 +268,19 @@ export default defineConfig({
 }
 ```
 
-### 2. Per-phone setup
+### 2. Per-phone setup (required)
 
-Open `https://devtools.aitc.dev/launcher/` on your phone and **add it to your home screen** (iOS Safari: Share → Add to Home Screen; Android Chrome: Install app). The launcher URL never changes, so this is a one-time step.
+Open `https://devtools.aitc.dev/launcher/` on your phone and **add it to your home screen**. The launcher shows an "Install launcher to your phone" button that triggers the platform-native install flow automatically — Android Chrome gets the in-app install prompt, iOS Safari gets a Share → Add to Home Screen illustration, and Firefox / Samsung Internet get a manual instruction card. The launcher URL never changes, so this is a one-time step per phone.
+
+The launcher **only works when launched as an installed PWA from the home screen**. Opening it in a regular browser tab shows only the install hint — the URL input and scanner are hidden. The chrome-less standalone display is the whole point of the launcher shell, and a regular tab can't provide that.
 
 ### 3. Each session
 
 1. Run `pnpm dev:phone` on your desktop (or `AIT_TUNNEL=1 pnpm dev` if you skipped step 1-(c)). The terminal will print a `https://*.trycloudflare.com` URL along with an ASCII QR code.
-2. Open the launcher icon on your phone → scan the QR code with your camera (or paste the URL) → your dev app opens full-screen without an address bar.
-3. Next session, just scan the new URL. The launcher remembers the last URL and you can swap it any time with the "Rescan" button.
+2. Scan the QR code with your phone's camera (or with the "Scan QR" button inside the launcher). The QR encodes a `https://devtools.aitc.dev/launcher/?url=<tunnel>` deep-link, so the launcher PWA opens and auto-enters the day's dev app full-screen — no paste step required.
+3. Next session, just scan the new QR. The launcher remembers the last URL and you can swap it any time with the "Rescan" button.
+
+> Whether the OS camera routes the QR straight into the installed launcher PWA (instead of a regular browser tab) is most reliable on Android Chrome; iOS Safari versions may fall back to a normal tab. In that case, open the launcher from its home-screen icon and use its in-page "Scan QR" button.
 
 ### Background
 

package/README.md

@@ -268,15 +268,19 @@ export default defineConfig({
 }
 ```
 
-### 2. 폰당 1회 셋업
+### 2. 폰당 1회 셋업 (필수)
 
-폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가**합니다 (iOS Safari "공유 → 홈 화면에 추가", Android Chrome "앱 설치"). launcher 자체는 URL이 바뀌지 않으니 한 번만 하면 됩니다.
+폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가**합니다. launcher는 페이지 상단에 "Install launcher to your phone" 버튼을 띄우는데, 누르면 플랫폼별 네이티브 설치 흐름이 자동으로 안내됩니다 — Android Chrome은 인앱 설치 프롬프트, iOS Safari는 "공유 → 홈 화면에 추가" 일러스트, Firefox/Samsung Internet 등은 수동 안내 카드. launcher URL은 매번 동일하므로 폰당 한 번만 하면 됩니다.
+
+launcher는 **PWA(홈 화면 앱)로 실행할 때만 동작**합니다. 일반 브라우저 탭에서 열면 설치 안내만 노출되고 입력/스캐너 UI는 숨겨집니다 — 크롬리스 standalone 디스플레이가 PWA 셸의 본질이라, 일반 탭에서의 동작은 의도적으로 막아둡니다.
 
 ### 3. 매 세션
 
 1. 데스크톱에서 `pnpm dev:phone`을 실행합니다 (1-(c) 스크립트를 추가하지 않았다면 `AIT_TUNNEL=1 pnpm dev`). 터미널에 `https://*.trycloudflare.com` URL + ASCII QR이 출력됩니다.
-2. 폰의 launcher 아이콘 실행 → 카메라로 QR 스캔(또는 URL 붙여넣기) → 주소창 없는 풀스크린으로 dev 앱이 뜹니다.
-3. 다음 세션엔 새 URL을 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
+2. 폰의 카메라(또는 launcher 아이콘 안의 "Scan QR")로 QR을 스캔합니다. QR은 `https://devtools.aitc.dev/launcher/?url=<tunnel>` 딥링크라 launcher PWA가 자동으로 열리고 그날의 dev 앱이 풀스크린으로 뜹니다 — URL 붙여넣기 단계가 필요 없습니다.
+3. 다음 세션엔 새 QR을 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
+
+> QR을 일반 카메라 앱으로 찍었을 때 Safari/Chrome이 일반 탭이 아닌 설치된 launcher PWA로 곧장 라우팅하는 동작은 Android Chrome에서 가장 안정적이고, iOS Safari는 버전에 따라 일반 탭으로 폴백할 수 있습니다. 그 경우 launcher 홈 화면 아이콘에서 한 번 열어주면 그 안의 QR 스캐너로 다시 시도할 수 있습니다.
 
 ### 배경
 

package/dist/panel/index.js

@@ -1050,7 +1050,7 @@ function readGlobalString(key) {
 }
 const TELEMETRY_ENDPOINT = readGlobalString("__TELEMETRY_ENDPOINT__") ?? "https://t.aitc.dev";
 function getVersion() {
-	return "0.1.20";
+	return "0.1.22";
 }
 let panelVisibleSince = null;
 let accumulatedMs = 0;
@@ -4167,7 +4167,7 @@ function mount() {
 		mockBadge.textContent = aitState.state.panelEditable ? t("panel.editMode.on") : t("panel.editMode.off");
 		refreshPanel();
 	});
-	const headerRight = h("span", { style: "display:flex;align-items:center;gap:6px" }, mockBadge, h("span", { style: "font-size:11px;color:#666;font-weight:400" }, `v0.1.20`), closeBtn);
+	const headerRight = h("span", { style: "display:flex;align-items:center;gap:6px" }, mockBadge, h("span", { style: "font-size:11px;color:#666;font-weight:400" }, `v0.1.22`), closeBtn);
 	const header = h("div", { className: "ait-panel-header" }, h("span", {}, t("panel.title")), headerRight);
 	tabsEl = h("div", { className: "ait-panel-tabs" });
 	for (const tab of getTabs()) {

package/dist/{tunnel-BbcgVy4L.js → tunnel-CY1velpk.js}

@@ -26,20 +26,33 @@ function parseTrycloudflareUrl(line) {
 }
 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.
+*/
+function buildLauncherDeepLink(tunnelUrl) {
+	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+}
+/**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
-* QR encoding it, 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.
+* 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);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
 		`  │  ${url}`,
 		"  │",
-		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
-		"  │  Scan the QR below from there (or paste the 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.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -48,7 +61,7 @@ async function printTunnelBanner(url, opts = {}) {
 	if (opts.qr !== false) {
 		const qrcode = (await import("qrcode-terminal")).default;
 		await new Promise((resolve) => {
-			qrcode.generate(url, { small: true }, (out) => {
+			qrcode.generate(deepLink, { small: true }, (out) => {
 				log(out);
 				resolve();
 			});
@@ -111,4 +124,4 @@ async function startQuickTunnel(port) {
 //#endregion
 export { printTunnelBanner, startQuickTunnel };
 
-//# sourceMappingURL=tunnel-BbcgVy4L.js.map
+//# sourceMappingURL=tunnel-CY1velpk.js.map

package/dist/tunnel-CY1velpk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-CY1velpk.js","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string): string {\n  return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,sBAAsB,WAA2B;AAC/D,QAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;;;;;;;;AAS7D,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,IAAI;AAc3C,KAbwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/{tunnel-DeXfLGRl.cjs → tunnel-DgiECOnW.cjs}

@@ -26,20 +26,33 @@ function parseTrycloudflareUrl(line) {
 }
 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.
+*/
+function buildLauncherDeepLink(tunnelUrl) {
+	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+}
+/**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
-* QR encoding it, 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.
+* 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);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
 		`  │  ${url}`,
 		"  │",
-		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
-		"  │  Scan the QR below from there (or paste the 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.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -48,7 +61,7 @@ async function printTunnelBanner(url, opts = {}) {
 	if (opts.qr !== false) {
 		const qrcode = (await import("qrcode-terminal")).default;
 		await new Promise((resolve) => {
-			qrcode.generate(url, { small: true }, (out) => {
+			qrcode.generate(deepLink, { small: true }, (out) => {
 				log(out);
 				resolve();
 			});
@@ -112,4 +125,4 @@ async function startQuickTunnel(port) {
 exports.printTunnelBanner = printTunnelBanner;
 exports.startQuickTunnel = startQuickTunnel;
 
-//# sourceMappingURL=tunnel-DeXfLGRl.cjs.map
+//# sourceMappingURL=tunnel-DgiECOnW.cjs.map

package/dist/tunnel-DgiECOnW.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-DgiECOnW.cjs","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string): string {\n  return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,sBAAsB,WAA2B;AAC/D,QAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;;;;;;;;AAS7D,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,IAAI;AAc3C,KAbwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/unplugin/index.cjs

@@ -89,7 +89,7 @@ const aitDevtoolsPlugin = (0, unplugin.createUnplugin)((options) => {
 						console.warn("[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.");
 						return;
 					}
-					Promise.resolve().then(() => require("../tunnel-DeXfLGRl.cjs")).then(async ({ startQuickTunnel, printTunnelBanner }) => {
+					Promise.resolve().then(() => require("../tunnel-DgiECOnW.cjs")).then(async ({ startQuickTunnel, printTunnelBanner }) => {
 						const t = await startQuickTunnel(port);
 						tunnel = t;
 						await printTunnelBanner(t.url, { qr: tunnelConfig.qr });

package/dist/unplugin/index.js

@@ -85,7 +85,7 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 						console.warn("[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.");
 						return;
 					}
-					import("../tunnel-BbcgVy4L.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
+					import("../tunnel-CY1velpk.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
 						const t = await startQuickTunnel(port);
 						tunnel = t;
 						await printTunnelBanner(t.url, { qr: tunnelConfig.qr });

package/dist/unplugin/tunnel.cjs

@@ -27,20 +27,33 @@ function parseTrycloudflareUrl(line) {
 }
 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.
+*/
+function buildLauncherDeepLink(tunnelUrl) {
+	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+}
+/**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
-* QR encoding it, 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.
+* 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);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
 		`  │  ${url}`,
 		"  │",
-		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
-		"  │  Scan the QR below from there (or paste the 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.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -49,7 +62,7 @@ async function printTunnelBanner(url, opts = {}) {
 	if (opts.qr !== false) {
 		const qrcode = (await import("qrcode-terminal")).default;
 		await new Promise((resolve) => {
-			qrcode.generate(url, { small: true }, (out) => {
+			qrcode.generate(deepLink, { small: true }, (out) => {
 				log(out);
 				resolve();
 			});
@@ -110,6 +123,7 @@ async function startQuickTunnel(port) {
 	});
 }
 //#endregion
+exports.buildLauncherDeepLink = buildLauncherDeepLink;
 exports.parseTrycloudflareUrl = parseTrycloudflareUrl;
 exports.printTunnelBanner = printTunnelBanner;
 exports.startQuickTunnel = startQuickTunnel;

package/dist/unplugin/tunnel.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.cjs","names":[],"sources":["../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}
+{"version":3,"file":"tunnel.cjs","names":[],"sources":["../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string): string {\n  return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,sBAAsB,WAA2B;AAC/D,QAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;;;;;;;;AAS7D,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,IAAI;AAc3C,KAbwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/unplugin/tunnel.d.cts

@@ -22,11 +22,20 @@ interface PrintTunnelBannerOptions {
   /** Sink for the banner text (default: `console.log`). Injected for testing. */
   log?: (msg: string) => void;
 }
+/**
+ * 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.
+ */
+declare function buildLauncherDeepLink(tunnelUrl: string): string;
 /**
  * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
- * QR encoding it, 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.
+ * 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 {
@@ -43,5 +52,5 @@ interface QuickTunnel {
  */
 declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
 //#endregion
-export { PrintTunnelBannerOptions, QuickTunnel, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+export { PrintTunnelBannerOptions, QuickTunnel, buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
 //# sourceMappingURL=tunnel.d.cts.map

package/dist/unplugin/tunnel.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAeA;iBApBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAkBP;EAhBR,EAAA;EAeM;EAbN,GAAA,IAAO,GAAA;AAAA;;;AA2CT;;;;iBAhCsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA6Bc,WAAA;EAeqB;EAbpC,GAAA;EAa2D;EAX3D,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAiBA;iBAtBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAiBqB;EAfpC,EAAA;EAyBoB;EAvBpB,GAAA,IAAO,GAAA;AAAA;;;;;;;;AAyDT;iBA5CgB,qBAAA,CAAsB,SAAA;;;;AA2DtC;;;iBAjDsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA+Bc,WAAA;EAeqC;EAbpD,GAAA;EAauE;EAXvE,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.d.ts

@@ -22,11 +22,20 @@ interface PrintTunnelBannerOptions {
   /** Sink for the banner text (default: `console.log`). Injected for testing. */
   log?: (msg: string) => void;
 }
+/**
+ * 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.
+ */
+declare function buildLauncherDeepLink(tunnelUrl: string): string;
 /**
  * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
- * QR encoding it, 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.
+ * 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 {
@@ -43,5 +52,5 @@ interface QuickTunnel {
  */
 declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
 //#endregion
-export { PrintTunnelBannerOptions, QuickTunnel, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+export { PrintTunnelBannerOptions, QuickTunnel, buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
 //# sourceMappingURL=tunnel.d.ts.map

package/dist/unplugin/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAeA;iBApBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAkBP;EAhBR,EAAA;EAeM;EAbN,GAAA,IAAO,GAAA;AAAA;;;AA2CT;;;;iBAhCsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA6Bc,WAAA;EAeqB;EAbpC,GAAA;EAa2D;EAX3D,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAiBA;iBAtBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAiBqB;EAfpC,EAAA;EAyBoB;EAvBpB,GAAA,IAAO,GAAA;AAAA;;;;;;;;AAyDT;iBA5CgB,qBAAA,CAAsB,SAAA;;;;AA2DtC;;;iBAjDsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA+Bc,WAAA;EAeqC;EAbpD,GAAA;EAauE;EAXvE,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.js

@@ -26,20 +26,33 @@ function parseTrycloudflareUrl(line) {
 }
 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.
+*/
+function buildLauncherDeepLink(tunnelUrl) {
+	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+}
+/**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
-* QR encoding it, 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.
+* 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);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
 		`  │  ${url}`,
 		"  │",
-		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
-		"  │  Scan the QR below from there (or paste the 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.",
 		"  └──────────────────────────────────────────────────────────────",
@@ -48,7 +61,7 @@ async function printTunnelBanner(url, opts = {}) {
 	if (opts.qr !== false) {
 		const qrcode = (await import("qrcode-terminal")).default;
 		await new Promise((resolve) => {
-			qrcode.generate(url, { small: true }, (out) => {
+			qrcode.generate(deepLink, { small: true }, (out) => {
 				log(out);
 				resolve();
 			});
@@ -109,6 +122,6 @@ async function startQuickTunnel(port) {
 	});
 }
 //#endregion
-export { parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+export { buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
 
 //# sourceMappingURL=tunnel.js.map

package/dist/unplugin/tunnel.js.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.js","names":[],"sources":["../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}
+{"version":3,"file":"tunnel.js","names":[],"sources":["../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string): string {\n  return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url);\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,sBAAsB,WAA2B;AAC/D,QAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;;;;;;;;AAS7D,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,IAAI;AAc3C,KAbwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,UAAU,EAAE,OAAO,MAAM,GAAG,QAAQ;AAClD,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ait-co/devtools",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Development tools for Apps in Toss mini-apps — mock SDK, floating devtools panel, and universal bundler plugin",
   "type": "module",
   "engines": {
@@ -47,6 +47,7 @@
     "@apps-in-toss/web-framework": "2.5.0",
     "@biomejs/biome": "2.4.15",
     "@changesets/cli": "^2.31.0",
+    "@khmyznikov/pwa-install": "^0.6.3",
     "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",

package/dist/tunnel-BbcgVy4L.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tunnel-BbcgVy4L.js","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/tunnel-DeXfLGRl.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tunnel-DeXfLGRl.cjs","names":[],"sources":["../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}