@ait-co/devtools 0.1.54 → 0.1.56

package/dist/unplugin/index.js

@@ -121,6 +121,8 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 				});
 				if (shouldTunnel) {
 					let tunnel = null;
+					let relayTunnel = null;
+					let relay = null;
 					const httpServer = server.httpServer;
 					httpServer?.once("listening", () => {
 						const address = httpServer?.address();
@@ -129,15 +131,39 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 							console.warn("[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.");
 							return;
 						}
-						import("../tunnel-D0_TwDNE.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
+						import("../tunnel-Cj8g1LIL.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
 							const t = await startQuickTunnel(port);
 							tunnel = t;
-							await printTunnelBanner(t.url, { qr: tunnelConfig.qr });
+							let relayWssUrl;
+							if (tunnelConfig.cdp) try {
+								const { assertRelayAuthConfigured, buildRelayVerifyAuth } = await import("../totp-CxHsagqY.js");
+								assertRelayAuthConfigured();
+								const verifyAuth = buildRelayVerifyAuth();
+								const { startChiiRelay } = await import("../chii-relay-itXOz7kS.js");
+								const r = await startChiiRelay({
+									port: 0,
+									verifyAuth
+								});
+								relay = r;
+								const rt = await startQuickTunnel(r.port);
+								relayTunnel = rt;
+								relayWssUrl = rt.url.replace(/^https:/, "wss:");
+							} catch (err) {
+								console.warn(`[@ait-co/devtools] tunnel: CDP relay not started — screen preview works without on-device debugging: ${err instanceof Error ? err.message : String(err)}`);
+							}
+							await printTunnelBanner(t.url, {
+								qr: tunnelConfig.qr,
+								relayWssUrl
+							});
 						}).catch((err) => {
 							console.warn(`[@ait-co/devtools] tunnel failed to start: ${err instanceof Error ? err.message : String(err)}`);
 						});
 					});
-					const cleanup = () => tunnel?.stop();
+					const cleanup = () => {
+						tunnel?.stop();
+						relayTunnel?.stop();
+						relay?.close();
+					};
 					httpServer?.once("close", cleanup);
 					process.once("SIGINT", cleanup);
 					process.once("SIGTERM", cleanup);

package/dist/unplugin/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/unplugin/index.ts"],"sourcesContent":["/**\n * @ait-co/devtools unplugin\n *\n * 모든 주요 번들러를 지원하는 단일 플러그인.\n * @apps-in-toss/web-framework → @ait-co/devtools/mock 으로 alias 설정.\n *\n * Usage:\n *   import aitDevtools from '@ait-co/devtools/unplugin';\n *\n *   // Vite\n *   export default { plugins: [aitDevtools.vite()] };\n *\n *   // Webpack / Next.js\n *   config.plugins.push(aitDevtools.webpack());\n *\n *   // Rspack\n *   config.plugins.push(aitDevtools.rspack());\n *\n *   // esbuild\n *   { plugins: [aitDevtools.esbuild()] }\n *\n *   // Rollup\n *   { plugins: [aitDevtools.rollup()] }\n */\n\nimport { fileURLToPath } from 'node:url';\nimport { createUnplugin } from 'unplugin';\n\n/**\n * Resolve `@ait-co/devtools/mock` to its real file path at plugin-load time.\n *\n * Returning the bare specifier from `resolveId` would stop the bundler from\n * walking node_modules for it — Vite 8+ treats such a non-null string as the\n * final resolved id and serves it via the virtual `/@id/` prefix, which 404s\n * because we don't provide a `load` hook. Resolving to an absolute path here\n * lets every supported bundler load the file the normal way.\n */\nconst MOCK_PATH = (() => {\n  try {\n    return fileURLToPath(import.meta.resolve('@ait-co/devtools/mock'));\n  } catch {\n    // Fallback for runtimes where `import.meta.resolve` is unavailable.\n    return '@ait-co/devtools/mock';\n  }\n})();\n\nexport interface AitDevtoolsOptions {\n  /**\n   * 패널 자동 주입 여부 (default: true)\n   * true이면 진입점에 floating panel import를 자동 추가한다.\n   */\n  panel?: boolean;\n  /**\n   * production 환경에서도 devtools를 강제로 활성화 (default: false)\n   */\n  forceEnable?: boolean;\n  /**\n   * mock alias 활성화 여부. default: true (development), false (production + forceEnable)\n   */\n  mock?: boolean;\n  /**\n   * Vite dev server에 MCP state endpoint를 추가할지 여부 (default: false).\n   *\n   * `true`로 설정하면:\n   *  - GET  /api/ait-devtools/state  — 마지막으로 브라우저가 push한 mock state 스냅샷 반환\n   *  - POST /api/ait-devtools/state  — 브라우저 panel이 상태 변경 시 자동 push (panel 내부 처리)\n   *\n   * 이 endpoint를 `@ait-co/devtools` MCP stdio server가 읽어 AI 에이전트에 mock state를 노출한다.\n   * Vite 전용: webpack/rspack/esbuild/rollup 환경에서는 무시된다.\n   */\n  mcp?: boolean;\n  /**\n   * Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, 계정 불필요)로\n   * 외부 노출해 실제 폰에서 미리보기. **Vite dev 모드 전용** — production은\n   * `forceEnable`이어도 터널을 띄우지 않는다 (의도치 않은 노출 방지). 다른 번들러는\n   * 무시. `true`면 기본 동작, 객체로 세부 설정 가능.\n   */\n  tunnel?:\n    | boolean\n    | {\n        /** 노출할 포트 (미지정 시 dev 서버가 실제 listen한 포트 자동 감지). */\n        port?: number;\n        /** 터미널 ASCII QR 출력 (default: true). */\n        qr?: boolean;\n      };\n}\n\nconst FRAMEWORK_ID = '@apps-in-toss/web-framework';\nconst BRIDGE_ID = '@apps-in-toss/web-bridge'; // back-compat (2.x)\nconst ANALYTICS_ID = '@apps-in-toss/web-analytics'; // back-compat (2.x)\nconst WEBVIEW_BRIDGE_ID = '@apps-in-toss/webview-bridge'; // 3.0+\n\n/** MCP state endpoint path — browser panel POSTs here, MCP server GETs here */\nconst MCP_STATE_PATH = '/api/ait-devtools/state';\n\nconst aitDevtoolsPlugin = createUnplugin((options?: AitDevtoolsOptions) => {\n  const isDev = process.env.NODE_ENV !== 'production';\n  const shouldEnable = isDev || (options?.forceEnable ?? false);\n  const shouldMock = shouldEnable && (options?.mock ?? isDev);\n  const shouldPanel = shouldEnable && (options?.panel ?? true);\n  const shouldMcp = shouldEnable && (options?.mcp ?? false);\n\n  // In-memory store for the last state snapshot pushed by the browser panel.\n  // Only allocated when mcp: true to avoid any overhead in the common case.\n  let lastState: string | null = null;\n\n  // Tunnel is dev-only and Vite-only. Never under production — even with\n  // forceEnable — so a production build can't accidentally expose itself.\n  const tunnelOpt = options?.tunnel;\n  const shouldTunnel = isDev && !!tunnelOpt;\n  const tunnelConfig = typeof tunnelOpt === 'object' ? tunnelOpt : {};\n\n  return {\n    name: 'ait-co-devtools',\n    enforce: 'pre' as const,\n\n    resolveId(id: string) {\n      if (!shouldMock) return null;\n      // @apps-in-toss/web-framework → @ait-co/devtools/mock (absolute path)\n      if (\n        id === FRAMEWORK_ID ||\n        id === WEBVIEW_BRIDGE_ID ||\n        id === BRIDGE_ID ||\n        id === ANALYTICS_ID\n      ) {\n        return MOCK_PATH;\n      }\n      return null;\n    },\n\n    transformInclude(id: string) {\n      if (!shouldPanel) return false;\n      // 진입점 파일에만 패널 import를 주입\n      return (\n        /\\.(tsx?|jsx?)$/.test(id) &&\n        /\\/(main|index|entry|app)\\.[tj]sx?$/i.test(id) &&\n        !id.includes('node_modules')\n      );\n    },\n\n    transform(code: string) {\n      // transformInclude가 이미 shouldPanel을 확인하지만, 안전망으로 유지\n      if (!shouldPanel) return null;\n      // 이미 패널이 import 되어있으면 스킵\n      if (code.includes('@ait-co/devtools/panel')) return null;\n      // transformInclude가 진입점 파일만 통과시키므로 바로 prepend\n      return `import '@ait-co/devtools/panel';\\n${code}`;\n    },\n\n    // Vite-only: register the MCP state HTTP endpoint on the dev server, and\n    // optionally start a Cloudflare quick tunnel once the dev server is listening.\n    // Non-Vite bundlers do not have a dev server concept so this is silently\n    // skipped (unplugin passes `vite` key only when building for Vite).\n    vite: {\n      config() {\n        if (!shouldTunnel) return;\n        // Vite blocks requests whose Host header isn't in `server.allowedHosts`\n        // (defaults to localhost only). The quick-tunnel hostname is random per\n        // run, so allow the whole `.trycloudflare.com` suffix while the tunnel\n        // is on. (A leading `.` makes Vite match the domain and its subdomains.)\n        return { server: { allowedHosts: ['.trycloudflare.com'] } };\n      },\n\n      configureServer(server: import('vite').ViteDevServer) {\n        // MCP state endpoint: browser panel POSTs state here, MCP stdio server GETs it.\n        if (shouldMcp) {\n          server.middlewares.use(MCP_STATE_PATH, (req, res) => {\n            // Allow Claude Code / AI agents (running locally) to read state\n            res.setHeader('Access-Control-Allow-Origin', '*');\n            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');\n            res.setHeader('Access-Control-Allow-Headers', 'Content-Type');\n\n            if (req.method === 'OPTIONS') {\n              res.writeHead(204);\n              res.end();\n              return;\n            }\n\n            if (req.method === 'GET') {\n              if (lastState === null) {\n                res.writeHead(503, { 'Content-Type': 'application/json' });\n                res.end(\n                  JSON.stringify({\n                    error: 'No state received yet. Open the app in a browser first.',\n                  }),\n                );\n                return;\n              }\n              res.writeHead(200, { 'Content-Type': 'application/json' });\n              res.end(lastState);\n              return;\n            }\n\n            if (req.method === 'POST') {\n              const chunks: Buffer[] = [];\n              req.on('data', (chunk: Buffer) => chunks.push(chunk));\n              req.on('end', () => {\n                try {\n                  const body = Buffer.concat(chunks).toString('utf-8');\n                  // Validate it's parseable JSON before caching\n                  JSON.parse(body);\n                  lastState = body;\n                  res.writeHead(204);\n                  res.end();\n                } catch {\n                  res.writeHead(400, { 'Content-Type': 'application/json' });\n                  res.end(JSON.stringify({ error: 'Invalid JSON' }));\n                }\n              });\n              return;\n            }\n\n            res.writeHead(405, { 'Content-Type': 'application/json' });\n            res.end(JSON.stringify({ error: 'Method not allowed' }));\n          });\n        }\n\n        // Tunnel: start a Cloudflare quick tunnel once the dev server is listening.\n        if (shouldTunnel) {\n          let tunnel: { stop: () => void } | null = null;\n          const httpServer = server.httpServer;\n\n          httpServer?.once('listening', () => {\n            const address = httpServer?.address();\n            const port =\n              tunnelConfig.port ??\n              (address && typeof address === 'object' ? address.port : undefined);\n            if (!port) {\n              console.warn(\n                '[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.',\n              );\n              return;\n            }\n            // Dynamic import keeps `cloudflared` / `qrcode-terminal` off the\n            // module graph unless the tunnel is actually used.\n            import('./tunnel.js')\n              .then(async ({ startQuickTunnel, printTunnelBanner }) => {\n                const t = await startQuickTunnel(port);\n                tunnel = t;\n                await printTunnelBanner(t.url, { qr: tunnelConfig.qr });\n              })\n              .catch((err: unknown) => {\n                console.warn(\n                  `[@ait-co/devtools] tunnel failed to start: ${\n                    err instanceof Error ? err.message : String(err)\n                  }`,\n                );\n              });\n          });\n\n          const cleanup = () => tunnel?.stop();\n          httpServer?.once('close', cleanup);\n          process.once('SIGINT', cleanup);\n          process.once('SIGTERM', cleanup);\n          process.once('exit', cleanup);\n        }\n      },\n    },\n  };\n});\n\nexport const vite = aitDevtoolsPlugin.vite;\nexport const webpack = aitDevtoolsPlugin.webpack;\nexport const rollup = aitDevtoolsPlugin.rollup;\nexport const esbuild = aitDevtoolsPlugin.esbuild;\nexport const rspack = aitDevtoolsPlugin.rspack;\n\nexport default aitDevtoolsPlugin;\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/unplugin/index.ts"],"sourcesContent":["/**\n * @ait-co/devtools unplugin\n *\n * 모든 주요 번들러를 지원하는 단일 플러그인.\n * @apps-in-toss/web-framework → @ait-co/devtools/mock 으로 alias 설정.\n *\n * Usage:\n *   import aitDevtools from '@ait-co/devtools/unplugin';\n *\n *   // Vite\n *   export default { plugins: [aitDevtools.vite()] };\n *\n *   // Webpack / Next.js\n *   config.plugins.push(aitDevtools.webpack());\n *\n *   // Rspack\n *   config.plugins.push(aitDevtools.rspack());\n *\n *   // esbuild\n *   { plugins: [aitDevtools.esbuild()] }\n *\n *   // Rollup\n *   { plugins: [aitDevtools.rollup()] }\n */\n\nimport { fileURLToPath } from 'node:url';\nimport { createUnplugin } from 'unplugin';\n\n/**\n * Resolve `@ait-co/devtools/mock` to its real file path at plugin-load time.\n *\n * Returning the bare specifier from `resolveId` would stop the bundler from\n * walking node_modules for it — Vite 8+ treats such a non-null string as the\n * final resolved id and serves it via the virtual `/@id/` prefix, which 404s\n * because we don't provide a `load` hook. Resolving to an absolute path here\n * lets every supported bundler load the file the normal way.\n */\nconst MOCK_PATH = (() => {\n  try {\n    return fileURLToPath(import.meta.resolve('@ait-co/devtools/mock'));\n  } catch {\n    // Fallback for runtimes where `import.meta.resolve` is unavailable.\n    return '@ait-co/devtools/mock';\n  }\n})();\n\nexport interface AitDevtoolsOptions {\n  /**\n   * 패널 자동 주입 여부 (default: true)\n   * true이면 진입점에 floating panel import를 자동 추가한다.\n   */\n  panel?: boolean;\n  /**\n   * production 환경에서도 devtools를 강제로 활성화 (default: false)\n   */\n  forceEnable?: boolean;\n  /**\n   * mock alias 활성화 여부. default: true (development), false (production + forceEnable)\n   */\n  mock?: boolean;\n  /**\n   * Vite dev server에 MCP state endpoint를 추가할지 여부 (default: false).\n   *\n   * `true`로 설정하면:\n   *  - GET  /api/ait-devtools/state  — 마지막으로 브라우저가 push한 mock state 스냅샷 반환\n   *  - POST /api/ait-devtools/state  — 브라우저 panel이 상태 변경 시 자동 push (panel 내부 처리)\n   *\n   * 이 endpoint를 `@ait-co/devtools` MCP stdio server가 읽어 AI 에이전트에 mock state를 노출한다.\n   * Vite 전용: webpack/rspack/esbuild/rollup 환경에서는 무시된다.\n   */\n  mcp?: boolean;\n  /**\n   * Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, 계정 불필요)로\n   * 외부 노출해 실제 폰에서 미리보기. **Vite dev 모드 전용** — production은\n   * `forceEnable`이어도 터널을 띄우지 않는다 (의도치 않은 노출 방지). 다른 번들러는\n   * 무시. `true`면 기본 동작, 객체로 세부 설정 가능.\n   */\n  tunnel?:\n    | boolean\n    | {\n        /** 노출할 포트 (미지정 시 dev 서버가 실제 listen한 포트 자동 감지). */\n        port?: number;\n        /** 터미널 ASCII QR 출력 (default: true). */\n        qr?: boolean;\n        /**\n         * 환경 2(실기기 PWA)에 CDP 디버깅 배선 (default: false).\n         *\n         * `true`면 dev 서버 HTTP 터널과 **별도로** Chii relay를 띄우고 그 relay에\n         * 두 번째 quick tunnel을 붙여, launcher QR deep-link에 `&debug=1&relay=<wss>`를\n         * 실어 보낸다. 폰의 PWA iframe이 in-app debug gate를 통과해 target.js를 주입받고,\n         * AI host MCP가 그 relay에 client로 붙으면 실기기 WebKit 위에서 CDP 디버깅이 열린다.\n         * mock SDK는 그대로라 `call_sdk`는 환경 2에서 mock을 친다 (fidelity 사다리의\n         * 설계 의도 — SDK fidelity가 필요하면 환경 3로 올라간다).\n         */\n        cdp?: boolean;\n      };\n}\n\nconst FRAMEWORK_ID = '@apps-in-toss/web-framework';\nconst BRIDGE_ID = '@apps-in-toss/web-bridge'; // back-compat (2.x)\nconst ANALYTICS_ID = '@apps-in-toss/web-analytics'; // back-compat (2.x)\nconst WEBVIEW_BRIDGE_ID = '@apps-in-toss/webview-bridge'; // 3.0+\n\n/** MCP state endpoint path — browser panel POSTs here, MCP server GETs here */\nconst MCP_STATE_PATH = '/api/ait-devtools/state';\n\nconst aitDevtoolsPlugin = createUnplugin((options?: AitDevtoolsOptions) => {\n  const isDev = process.env.NODE_ENV !== 'production';\n  const shouldEnable = isDev || (options?.forceEnable ?? false);\n  const shouldMock = shouldEnable && (options?.mock ?? isDev);\n  const shouldPanel = shouldEnable && (options?.panel ?? true);\n  const shouldMcp = shouldEnable && (options?.mcp ?? false);\n\n  // In-memory store for the last state snapshot pushed by the browser panel.\n  // Only allocated when mcp: true to avoid any overhead in the common case.\n  let lastState: string | null = null;\n\n  // Tunnel is dev-only and Vite-only. Never under production — even with\n  // forceEnable — so a production build can't accidentally expose itself.\n  const tunnelOpt = options?.tunnel;\n  const shouldTunnel = isDev && !!tunnelOpt;\n  const tunnelConfig = typeof tunnelOpt === 'object' ? tunnelOpt : {};\n\n  return {\n    name: 'ait-co-devtools',\n    enforce: 'pre' as const,\n\n    resolveId(id: string) {\n      if (!shouldMock) return null;\n      // @apps-in-toss/web-framework → @ait-co/devtools/mock (absolute path)\n      if (\n        id === FRAMEWORK_ID ||\n        id === WEBVIEW_BRIDGE_ID ||\n        id === BRIDGE_ID ||\n        id === ANALYTICS_ID\n      ) {\n        return MOCK_PATH;\n      }\n      return null;\n    },\n\n    transformInclude(id: string) {\n      if (!shouldPanel) return false;\n      // 진입점 파일에만 패널 import를 주입\n      return (\n        /\\.(tsx?|jsx?)$/.test(id) &&\n        /\\/(main|index|entry|app)\\.[tj]sx?$/i.test(id) &&\n        !id.includes('node_modules')\n      );\n    },\n\n    transform(code: string) {\n      // transformInclude가 이미 shouldPanel을 확인하지만, 안전망으로 유지\n      if (!shouldPanel) return null;\n      // 이미 패널이 import 되어있으면 스킵\n      if (code.includes('@ait-co/devtools/panel')) return null;\n      // transformInclude가 진입점 파일만 통과시키므로 바로 prepend\n      return `import '@ait-co/devtools/panel';\\n${code}`;\n    },\n\n    // Vite-only: register the MCP state HTTP endpoint on the dev server, and\n    // optionally start a Cloudflare quick tunnel once the dev server is listening.\n    // Non-Vite bundlers do not have a dev server concept so this is silently\n    // skipped (unplugin passes `vite` key only when building for Vite).\n    vite: {\n      config() {\n        if (!shouldTunnel) return;\n        // Vite blocks requests whose Host header isn't in `server.allowedHosts`\n        // (defaults to localhost only). The quick-tunnel hostname is random per\n        // run, so allow the whole `.trycloudflare.com` suffix while the tunnel\n        // is on. (A leading `.` makes Vite match the domain and its subdomains.)\n        return { server: { allowedHosts: ['.trycloudflare.com'] } };\n      },\n\n      configureServer(server: import('vite').ViteDevServer) {\n        // MCP state endpoint: browser panel POSTs state here, MCP stdio server GETs it.\n        if (shouldMcp) {\n          server.middlewares.use(MCP_STATE_PATH, (req, res) => {\n            // Allow Claude Code / AI agents (running locally) to read state\n            res.setHeader('Access-Control-Allow-Origin', '*');\n            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');\n            res.setHeader('Access-Control-Allow-Headers', 'Content-Type');\n\n            if (req.method === 'OPTIONS') {\n              res.writeHead(204);\n              res.end();\n              return;\n            }\n\n            if (req.method === 'GET') {\n              if (lastState === null) {\n                res.writeHead(503, { 'Content-Type': 'application/json' });\n                res.end(\n                  JSON.stringify({\n                    error: 'No state received yet. Open the app in a browser first.',\n                  }),\n                );\n                return;\n              }\n              res.writeHead(200, { 'Content-Type': 'application/json' });\n              res.end(lastState);\n              return;\n            }\n\n            if (req.method === 'POST') {\n              const chunks: Buffer[] = [];\n              req.on('data', (chunk: Buffer) => chunks.push(chunk));\n              req.on('end', () => {\n                try {\n                  const body = Buffer.concat(chunks).toString('utf-8');\n                  // Validate it's parseable JSON before caching\n                  JSON.parse(body);\n                  lastState = body;\n                  res.writeHead(204);\n                  res.end();\n                } catch {\n                  res.writeHead(400, { 'Content-Type': 'application/json' });\n                  res.end(JSON.stringify({ error: 'Invalid JSON' }));\n                }\n              });\n              return;\n            }\n\n            res.writeHead(405, { 'Content-Type': 'application/json' });\n            res.end(JSON.stringify({ error: 'Method not allowed' }));\n          });\n        }\n\n        // Tunnel: start a Cloudflare quick tunnel once the dev server is listening.\n        if (shouldTunnel) {\n          let tunnel: { stop: () => void } | null = null;\n          // env-2 CDP wiring (tunnel.cdp): a second tunnel + Chii relay, torn\n          // down alongside the HTTP tunnel. Fire-and-forget close on teardown.\n          let relayTunnel: { stop: () => void } | null = null;\n          let relay: { close: () => Promise<void> } | null = null;\n          const httpServer = server.httpServer;\n\n          httpServer?.once('listening', () => {\n            const address = httpServer?.address();\n            const port =\n              tunnelConfig.port ??\n              (address && typeof address === 'object' ? address.port : undefined);\n            if (!port) {\n              console.warn(\n                '[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.',\n              );\n              return;\n            }\n            // Dynamic import keeps `cloudflared` / `qrcode-terminal` off the\n            // module graph unless the tunnel is actually used.\n            import('./tunnel.js')\n              .then(async ({ startQuickTunnel, printTunnelBanner }) => {\n                const t = await startQuickTunnel(port);\n                tunnel = t;\n\n                // env-2 CDP: boot a Chii relay (OS-assigned local port) and a\n                // second quick tunnel to it. The relay's https tunnel URL becomes\n                // the `wss://` relay the launcher QR carries (&debug=1&relay=).\n                let relayWssUrl: string | undefined;\n                if (tunnelConfig.cdp) {\n                  try {\n                    // Relay-auth baseline (issue #250): the env-2 CDP relay is\n                    // reachable over a public `*.trycloudflare.com` tunnel, so a\n                    // configured TOTP secret is MANDATORY and the relay enforces\n                    // it on every WS upgrade. assertRelayAuthConfigured throws\n                    // when AIT_DEBUG_TOTP_SECRET is unset/weak — the catch below\n                    // then skips the relay entirely (no UNAUTHENTICATED relay is\n                    // ever exposed; screen preview still works).\n                    // SECRET-HANDLING: the guard/predicate never log the value.\n                    const { assertRelayAuthConfigured, buildRelayVerifyAuth } = await import(\n                      '../mcp/totp.js'\n                    );\n                    assertRelayAuthConfigured();\n                    const verifyAuth = buildRelayVerifyAuth();\n                    const { startChiiRelay } = await import('../mcp/chii-relay.js');\n                    const r = await startChiiRelay({ port: 0, verifyAuth });\n                    relay = r;\n                    const rt = await startQuickTunnel(r.port);\n                    relayTunnel = rt;\n                    relayWssUrl = rt.url.replace(/^https:/, 'wss:');\n                  } catch (err: unknown) {\n                    console.warn(\n                      `[@ait-co/devtools] tunnel: CDP relay not started — screen preview works without on-device debugging: ${\n                        err instanceof Error ? err.message : String(err)\n                      }`,\n                    );\n                  }\n                }\n\n                await printTunnelBanner(t.url, { qr: tunnelConfig.qr, relayWssUrl });\n              })\n              .catch((err: unknown) => {\n                console.warn(\n                  `[@ait-co/devtools] tunnel failed to start: ${\n                    err instanceof Error ? err.message : String(err)\n                  }`,\n                );\n              });\n          });\n\n          const cleanup = () => {\n            tunnel?.stop();\n            relayTunnel?.stop();\n            void relay?.close();\n          };\n          httpServer?.once('close', cleanup);\n          process.once('SIGINT', cleanup);\n          process.once('SIGTERM', cleanup);\n          process.once('exit', cleanup);\n        }\n      },\n    },\n  };\n});\n\nexport const vite = aitDevtoolsPlugin.vite;\nexport const webpack = aitDevtoolsPlugin.webpack;\nexport const rollup = aitDevtoolsPlugin.rollup;\nexport const esbuild = aitDevtoolsPlugin.esbuild;\nexport const rspack = aitDevtoolsPlugin.rspack;\n\nexport default aitDevtoolsPlugin;\n"],"mappings":"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"}

package/dist/unplugin/tunnel.cjs

@@ -33,9 +33,16 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * 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 `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+* `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+* the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+* a Chii target.js is injected into the live view.
 */
-function buildLauncherDeepLink(tunnelUrl) {
-	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+function buildLauncherDeepLink(tunnelUrl, relayWssUrl) {
+	const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (!relayWssUrl) return base;
+	return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;
 }
 /**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
@@ -45,7 +52,7 @@ function buildLauncherDeepLink(tunnelUrl) {
 */
 async function printTunnelBanner(url, opts = {}) {
 	const log = opts.log ?? ((m) => console.log(m));
-	const deepLink = buildLauncherDeepLink(url);
+	const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
@@ -54,6 +61,7 @@ async function printTunnelBanner(url, opts = {}) {
 		`  │  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).",
+		...opts.relayWssUrl ? ["  │  The same scan also attaches CDP — connect your AI host", "  │  to the relay and debug the live view on-device."] : [],
 		"  │  Quick tunnels are unauthenticated, change every run, and are",
 		"  │  not for production use.",
 		"  └──────────────────────────────────────────────────────────────",

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 * 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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,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   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\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 *\n * When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): string {\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  if (!relayWssUrl) return base;\n  return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;\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, opts.relayWssUrl);\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    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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;;AAiBpB,MAAM,eAAe;;;;;;;;;;;;;;AAerB,SAAgB,sBAAsB,WAAmB,aAA8B;CACrF,MAAM,OAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;AACjE,KAAI,CAAC,YAAa,QAAO;AACzB,QAAO,GAAG,KAAK,iBAAiB,mBAAmB,YAAY;;;;;;;;AASjE,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,KAAK,KAAK,YAAY;AAoB7D,KAnBwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA,GAAI,KAAK,cACL,CACE,+DACA,uDACD,GACD,EAAE;EACN;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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/unplugin/tunnel.d.cts

@@ -21,6 +21,13 @@ interface PrintTunnelBannerOptions {
   qr?: boolean;
   /** Sink for the banner text (default: `console.log`). Injected for testing. */
   log?: (msg: string) => void;
+  /**
+   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When
+   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the
+   * framed PWA passes the in-app debug gate and attaches a Chii target — the
+   * same single scan opens screen preview *and* CDP debugging.
+   */
+  relayWssUrl?: string;
 }
 /**
  * Build the deep-link URL that QR codes encode: when the launcher PWA is
@@ -29,8 +36,13 @@ interface PrintTunnelBannerOptions {
  * 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 `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+ * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+ * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+ * a Chii target.js is injected into the live view.
  */
-declare function buildLauncherDeepLink(tunnelUrl: string): string;
+declare function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): 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

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;;EAEf,EAAA;EA2B2E;EAzB3E,GAAA,IAAO,GAAA;EAqC8B;;;;;;EA9BrC,WAAA;AAAA;;AAsEF;;;;;AAeA;;;;;;;iBAnEgB,qBAAA,CAAsB,SAAA,UAAmB,WAAA;;;;;;;iBAYnC,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UAqCc,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.d.ts

@@ -21,6 +21,13 @@ interface PrintTunnelBannerOptions {
   qr?: boolean;
   /** Sink for the banner text (default: `console.log`). Injected for testing. */
   log?: (msg: string) => void;
+  /**
+   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When
+   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the
+   * framed PWA passes the in-app debug gate and attaches a Chii target — the
+   * same single scan opens screen preview *and* CDP debugging.
+   */
+  relayWssUrl?: string;
 }
 /**
  * Build the deep-link URL that QR codes encode: when the launcher PWA is
@@ -29,8 +36,13 @@ interface PrintTunnelBannerOptions {
  * 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 `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+ * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+ * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+ * a Chii target.js is injected into the live view.
  */
-declare function buildLauncherDeepLink(tunnelUrl: string): string;
+declare function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): 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

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;;EAEf,EAAA;EA2B2E;EAzB3E,GAAA,IAAO,GAAA;EAqC8B;;;;;;EA9BrC,WAAA;AAAA;;AAsEF;;;;;AAeA;;;;;;;iBAnEgB,qBAAA,CAAsB,SAAA,UAAmB,WAAA;;;;;;;iBAYnC,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UAqCc,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.js

@@ -32,9 +32,16 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * 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 `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries
+* `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so
+* the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and
+* a Chii target.js is injected into the live view.
 */
-function buildLauncherDeepLink(tunnelUrl) {
-	return `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+function buildLauncherDeepLink(tunnelUrl, relayWssUrl) {
+	const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (!relayWssUrl) return base;
+	return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;
 }
 /**
 * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
@@ -44,7 +51,7 @@ function buildLauncherDeepLink(tunnelUrl) {
 */
 async function printTunnelBanner(url, opts = {}) {
 	const log = opts.log ?? ((m) => console.log(m));
-	const deepLink = buildLauncherDeepLink(url);
+	const deepLink = buildLauncherDeepLink(url, opts.relayWssUrl);
 	log([
 		"",
 		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
@@ -53,6 +60,7 @@ async function printTunnelBanner(url, opts = {}) {
 		`  │  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).",
+		...opts.relayWssUrl ? ["  │  The same scan also attaches CDP — connect your AI host", "  │  to the relay and debug the live view on-device."] : [],
 		"  │  Quick tunnels are unauthenticated, change every run, and are",
 		"  │  not for production use.",
 		"  └──────────────────────────────────────────────────────────────",

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 * 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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,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   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\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 *\n * When `relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n */\nexport function buildLauncherDeepLink(tunnelUrl: string, relayWssUrl?: string): string {\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  if (!relayWssUrl) return base;\n  return `${base}&debug=1&relay=${encodeURIComponent(relayWssUrl)}`;\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, opts.relayWssUrl);\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    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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;;AAiBpB,MAAM,eAAe;;;;;;;;;;;;;;AAerB,SAAgB,sBAAsB,WAAmB,aAA8B;CACrF,MAAM,OAAO,GAAG,aAAa,OAAO,mBAAmB,UAAU;AACjE,KAAI,CAAC,YAAa,QAAO;AACzB,QAAO,GAAG,KAAK,iBAAiB,mBAAmB,YAAY;;;;;;;;AASjE,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;CACtD,MAAM,WAAW,sBAAsB,KAAK,KAAK,YAAY;AAoB7D,KAnBwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,wCAAwC;EACxC;EACA;EACA,GAAI,KAAK,cACL,CACE,+DACA,uDACD,GACD,EAAE;EACN;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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,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.54",
+  "version": "0.1.56",
   "description": "Development tools for Apps in Toss mini-apps — mock SDK, floating devtools panel, and universal bundler plugin",
   "type": "module",
   "engines": {
@@ -64,7 +64,7 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@apps-in-toss/web-framework": "3.0.0-beta.9d42c0b",
+    "@apps-in-toss/web-framework": "3.0.0-beta.3051978",
     "@biomejs/biome": "2.4.15",
     "@changesets/cli": "^2.31.0",
     "@khmyznikov/pwa-install": "^0.6.3",

package/dist/tunnel-BYP0yRBN.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tunnel-BYP0yRBN.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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/tunnel-D0_TwDNE.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tunnel-D0_TwDNE.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      cleanup();\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      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\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      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\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,YAAS;AACT,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,YAAS;AACT,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;EAG/B,MAAM,gBAAgB;AACpB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;;AAK7B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,YAAS;AACT,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,YAAS;AACT,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}