vibeview 0.10.0 → 0.11.0

package/dist/{chunk-NA3JOV5Z.js → chunk-4UGLSIZM.js}

@@ -4,7 +4,7 @@ import {
   loadConfig,
   resolveAuth,
   uploadAppBuild
-} from "./chunk-YD2X6TQV.js";
+} from "./chunk-AG3RZCPW.js";
 
 // src/lib/dev-state.ts
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -71,7 +71,14 @@ function clearDevState(cwd) {
 // src/lib/dev-config.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join2 } from "path";
-var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv", "roku"];
+var PLATFORM_NEEDS_METRO = {
+  ios: true,
+  android: true,
+  tvos: true,
+  androidtv: true,
+  roku: false
+};
 var FILE = "vibeview.json";
 function isDevPlatform(p) {
   return typeof p === "string" && DEV_PLATFORMS.includes(p);
@@ -137,6 +144,18 @@ function loadDevConfig(cwd) {
         );
       }
     }
+    if (entry.watchIgnore !== void 0) {
+      if (!Array.isArray(entry.watchIgnore)) {
+        throw new Error(
+          `vibeview.json: platforms.${key}.watchIgnore must be an array of paths to ignore while watching`
+        );
+      }
+      if (entry.watchIgnore.some((p) => typeof p !== "string" || !p)) {
+        throw new Error(
+          `vibeview.json: platforms.${key}.watchIgnore entries must be non-empty strings`
+        );
+      }
+    }
     if (entry.metroCommand !== void 0 && (typeof entry.metroCommand !== "string" || !entry.metroCommand)) {
       throw new Error(`vibeview.json: platforms.${key}.metroCommand must be a non-empty string`);
     }
@@ -169,10 +188,10 @@ function buildSavedConfig(input2) {
     firstRunMetro,
     firstRunBuild
   } = input2;
-  const topLevelMetroPort = metroPortFlag ? parseInt(metroPortFlag, 10) : existing?.metroPort ?? 8081;
+  const topLevelMetroPort = metroPortFlag ? parseInt(metroPortFlag, 10) : existing?.metroPort ?? (PLATFORM_NEEDS_METRO[platform] ? 8081 : void 0);
   return {
     defaultPlatform: platform,
-    metroPort: topLevelMetroPort,
+    ...topLevelMetroPort !== void 0 ? { metroPort: topLevelMetroPort } : {},
     ...isFirstRun && firstRunMetro ? { metroCommand: firstRunMetro } : existing?.metroCommand ? { metroCommand: existing.metroCommand } : {},
     platforms: {
       ...existing?.platforms,
@@ -181,6 +200,9 @@ function buildSavedConfig(input2) {
         deviceCategory: isTv ? void 0 : deviceCategory,
         ...existing?.platforms?.[platform]?.build ? { build: existing.platforms[platform].build } : {},
         ...isFirstRun && firstRunBuild ? { build: firstRunBuild } : {},
+        // Never invented — absent means "no extra ignores", and first-run
+        // setup does not ask for it. Only ever carried forward.
+        ...existing?.platforms?.[platform]?.watchIgnore ? { watchIgnore: existing.platforms[platform].watchIgnore } : {},
         ...existing?.platforms?.[platform]?.metroCommand ? { metroCommand: existing.platforms[platform].metroCommand } : {},
         ...existing?.platforms?.[platform]?.metroPort !== void 0 ? { metroPort: existing.platforms[platform].metroPort } : {}
       }
@@ -268,8 +290,22 @@ function prepareUploadArtifact(path) {
 import { input, select } from "@inquirer/prompts";
 
 // src/lib/project-detect.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
 import { join as join4 } from "path";
+function readJson(cwd, name) {
+  try {
+    return JSON.parse(readFileSync3(join4(cwd, name), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function isFile(path) {
+  try {
+    return statSync2(path).isFile();
+  } catch {
+    return false;
+  }
+}
 function detectFlavor(cwd) {
   let deps = {};
   try {
@@ -279,6 +315,7 @@ function detectFlavor(cwd) {
   }
   if ("expo" in deps) return "expo";
   if (existsSync3(join4(cwd, "android", "gradlew")) || iosWorkspaceName(cwd)) return "bare-rn";
+  if (isFile(join4(cwd, "manifest"))) return "roku";
   return "unknown";
 }
 function iosWorkspaceName(cwd) {
@@ -291,9 +328,32 @@ function iosWorkspaceName(cwd) {
 }
 var IOS_ARTIFACT = "ios/build/Build/Products/Debug-iphonesimulator/*.app";
 var ANDROID_ARTIFACT = "android/app/build/outputs/apk/debug/*.apk";
+var ROKU_DEFAULT_ARTIFACT = "out/channel.zip";
+var ROKU_ZIP_COMMAND = "zip -r out/channel.zip manifest source components images -x '*.DS_Store'";
+function rokuDefaults(cwd) {
+  const pkg = readJson(cwd, "package.json");
+  const scripts = pkg?.scripts ?? {};
+  const runner = existsSync3(join4(cwd, "yarn.lock")) ? "yarn" : "npm run";
+  const packageScript = Object.entries(scripts).find(
+    ([name, body]) => !name.startsWith("deploy") && (name.startsWith("package") || body.includes("--package-only") || body.includes("zipPackage"))
+  );
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  let artifact = ROKU_DEFAULT_ARTIFACT;
+  if ("roku-deploy" in deps) {
+    const rd = readJson(cwd, "rokudeploy.json");
+    const outDir = rd?.outDir ?? "out";
+    const outFile = rd?.outFile ?? "roku-deploy.zip";
+    artifact = `${outDir}/${outFile}`;
+  }
+  if (packageScript) {
+    return { buildCommand: `${runner} ${packageScript[0]}`, artifact };
+  }
+  return { buildCommand: ROKU_ZIP_COMMAND, artifact };
+}
 function defaultsFor(cwd, platform) {
   const flavor = detectFlavor(cwd);
-  if (flavor === "unknown") return {};
+  if (platform === "roku") return flavor === "roku" ? rokuDefaults(cwd) : {};
+  if (flavor === "unknown" || flavor === "roku") return {};
   const metroCommand = flavor === "expo" ? "npx expo start" : "yarn start";
   if (platform === "tvos" || platform === "androidtv") return { metroCommand };
   if (platform === "android") {
@@ -319,6 +379,16 @@ function defaultsFor(cwd, platform) {
 }
 
 // src/lib/dev-setup.ts
+function platformChoices(cwd) {
+  const choices = [
+    { value: "ios", name: "iOS simulator" },
+    { value: "android", name: "Android emulator" },
+    { value: "tvos", name: "Apple TV simulator" },
+    { value: "androidtv", name: "Android TV emulator" }
+  ];
+  if (detectFlavor(cwd) === "roku") choices.unshift({ value: "roku", name: "Roku (beta)" });
+  return choices;
+}
 function firstRunAppStrategy(apps, buildConfigured) {
   if (!buildConfigured) return "picker";
   return apps.length === 0 ? "build_now" : "ask";
@@ -352,7 +422,7 @@ async function promptBuildConfig(cwd, platform) {
   }
   const command = await input({ message: `Build command for ${platform}`, required: true });
   const artifact = await input({
-    message: "Path to the built app it produces (.apk, or .app dir; * allowed)",
+    message: platform === "roku" ? "Path to the channel zip it produces (* allowed)" : "Path to the built app it produces (.apk, or .app dir; * allowed)",
     default: defaults.artifact,
     required: true
   });
@@ -425,12 +495,7 @@ async function buildCommand(opts) {
     }
     platform = await select2({
       message: "Platform to run on",
-      choices: [
-        { value: "ios", name: "iOS simulator" },
-        { value: "android", name: "Android emulator" },
-        { value: "tvos", name: "Apple TV simulator" },
-        { value: "androidtv", name: "Android TV emulator" }
-      ]
+      choices: platformChoices(cwd)
     });
   }
   let build = cfg?.platforms?.[platform]?.build;
@@ -496,7 +561,7 @@ function fail(opts, message, code) {
 // src/commands/dev.ts
 import { spawn as spawn3 } from "child_process";
 import { createWriteStream, mkdirSync as mkdirSync3 } from "fs";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import { createInterface as createInterface3 } from "readline";
 import { select as select3 } from "@inquirer/prompts";
 import chalk2 from "chalk";
@@ -815,19 +880,163 @@ async function waitFor(cond, timeoutMs, everyMs) {
   }
 }
 
+// src/lib/reload-loop.ts
+import { watch } from "fs";
+import { basename as basename2, dirname as dirname4 } from "path";
+function createReloadLoop(deps) {
+  let inFlight = null;
+  let pendingFollowUp = false;
+  let debounceTimer = null;
+  let stopWatch = null;
+  let stopped = false;
+  async function run() {
+    inFlight = (async () => {
+      try {
+        await deps.push();
+      } catch (err) {
+        (deps.logError ?? deps.log)(err.message);
+      }
+    })();
+    try {
+      await inFlight;
+    } finally {
+      inFlight = null;
+    }
+    if (pendingFollowUp && !stopped) {
+      pendingFollowUp = false;
+      await run();
+    }
+  }
+  async function trigger() {
+    if (stopped) return;
+    if (inFlight) {
+      deps.log("already reloading \u2014 ignoring");
+      return;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    await run();
+  }
+  function onChange() {
+    if (stopped) return;
+    if (inFlight) {
+      pendingFollowUp = true;
+      return;
+    }
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(
+      () => {
+        debounceTimer = null;
+        void trigger();
+      },
+      (deps.watchSeconds ?? 2) * 1e3
+    );
+  }
+  if (deps.watch && deps.watchSeconds !== void 0) {
+    stopWatch = deps.watch(onChange);
+  }
+  return {
+    trigger,
+    stop() {
+      stopped = true;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      stopWatch?.();
+    }
+  };
+}
+var IGNORED_SEGMENTS = ["node_modules", ".git", ".vibeview"];
+var IGNORED_FILES = ["vibeview.json"];
+function isUnderPath(rel, entry) {
+  const norm = normalizeRel(entry).replace(/\/+$/, "");
+  if (!norm) return false;
+  return rel === norm || rel.startsWith(`${norm}/`);
+}
+function normalizeRel(p) {
+  return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isIgnoredWatchPath(relPath, artifact, userIgnore = []) {
+  const rel = normalizeRel(relPath);
+  const segments = rel.split("/");
+  if (segments.some((s) => IGNORED_SEGMENTS.includes(s) || s.includes("staging"))) return true;
+  if (IGNORED_FILES.includes(rel)) return true;
+  if (userIgnore.some((entry) => isUnderPath(rel, entry))) return true;
+  const artifactPattern = artifact.replace(/\\/g, "/").replace(/^\.\//, "");
+  const artifactDir = dirname4(artifactPattern);
+  if (artifactDir !== "." && (rel === artifactDir || rel.startsWith(`${artifactDir}/`))) {
+    return true;
+  }
+  if (dirname4(rel) !== artifactDir) return false;
+  const name = basename2(artifactPattern);
+  const re = new RegExp(`^${name.split("*").map(escapeRegExp2).join(".*")}$`);
+  return re.test(basename2(rel));
+}
+function escapeRegExp2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function watchProjectFiles(cwd, artifact, userIgnore = []) {
+  return (onChange) => {
+    const watcher = watch(cwd, { recursive: true }, (_event, filename) => {
+      if (filename !== null && isIgnoredWatchPath(filename.toString(), artifact, userIgnore)) {
+        return;
+      }
+      onChange();
+    });
+    return () => watcher.close();
+  };
+}
+
+// src/lib/roku-push.ts
+function createRokuPush(opts) {
+  const runBuild = opts.runBuild ?? runBuildForPlatform;
+  return async () => {
+    const started = Date.now();
+    let result;
+    try {
+      result = await runBuild(
+        opts.cwd,
+        "roku",
+        opts.build,
+        { token: opts.token, baseUrl: opts.baseUrl },
+        opts.log
+      );
+    } catch (err) {
+      const message = err.message;
+      if (/artifact not found/i.test(message)) {
+        throw new Error(
+          `${message}
+your build command must produce a zip \u2014 use the package/zip step, not deploy`
+        );
+      }
+      throw err;
+    }
+    if (!result.build_id) {
+      throw new Error(`upload returned no build id for ${result.name ?? result.public_id}`);
+    }
+    await opts.api.installBuild(opts.sessionId, result.build_id, true);
+    opts.log(`reloaded in ${((Date.now() - started) / 1e3).toFixed(1)}s`);
+  };
+}
+
 // src/commands/dev.ts
+function parseWatchSeconds(flag) {
+  if (flag === void 0 || flag === false) return void 0;
+  if (flag === true) return 2;
+  const seconds = Number(flag);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(`--watch expects a positive number of seconds, got "${flag}"`);
+  }
+  return seconds;
+}
 function emit(json, evt) {
   if (json) console.log(JSON.stringify(evt));
 }
 async function startDevSession(cfg, onEvent = () => {
 }, onTunnelState) {
   const api = new ApiClient(cfg.baseUrl, cfg.token);
-  const created = await api.createSession({
-    device_type: PLATFORM_DEVICE[cfg.platform].deviceType,
-    device_category: cfg.deviceCategory,
-    app_id: cfg.appId,
-    tunnel: true
-  });
+  const usesTunnel = PLATFORM_NEEDS_METRO[cfg.platform];
+  const created = await api.createSession(devSessionCreateBody(cfg));
   const sessionId = created.session_id;
   let stopping = false;
   let tunnel = null;
@@ -841,52 +1050,66 @@ async function startDevSession(cfg, onEvent = () => {
   };
   try {
     await api.startSession(sessionId);
-    const ready = await pollUntilTunnelReady(api, sessionId, 18e4);
-    for (const w of ready.warnings ?? []) {
-      onEvent({ event: "warning", message: w });
-    }
     const pageUrl = `${cfg.webUrl || cfg.baseUrl}/sandbox/${sessionId}`;
-    tunnel = new TunnelClient({
-      url: ready.tunnel_url,
-      metroPort: cfg.metroPort,
-      // Re-mint the URL on each reconnect: the tunnel token has a ~1h TTL and
-      // a worker restart drops the proxy registration, so the original URL
-      // eventually goes stale. Every authorized GET /sessions/{id} re-signs a
-      // fresh tunnel token. Null (session stopped/failed) ends the tunnel.
-      refreshUrl: async () => {
-        const info = await api.getSession(sessionId);
-        if (info.status === "stopped" || info.status === "failed") return null;
-        return info.tunnel_url ?? null;
-      },
-      onDebug: cfg.debug ? (msg) => onEvent({ event: "warning", message: `[tunnel] ${msg}` }) : void 0,
-      onState: (s) => {
-        onTunnelState?.(s);
-        if (s === "connected") {
-          onEvent({ event: "tunnel_connected", session_id: sessionId });
-        } else if (s === "metro-unreachable") {
-          onEvent({
-            event: "warning",
-            message: `can't reach Metro on localhost:${cfg.metroPort} \u2014 is it running? (yarn start)`
-          });
-        } else if (s === "closed" && !stopping) {
-          void stopSession(1);
-        }
+    const reportedWarnings = /* @__PURE__ */ new Set();
+    if (usesTunnel) {
+      const ready = await pollUntilTunnelReady(api, sessionId, 18e4);
+      for (const w of ready.warnings ?? []) {
+        reportedWarnings.add(w);
+        onEvent({ event: "warning", message: w });
       }
-    });
-    tunnel.start();
+      tunnel = new TunnelClient({
+        url: ready.tunnel_url,
+        metroPort: cfg.metroPort,
+        // Re-mint the URL on each reconnect: the tunnel token has a ~1h TTL and
+        // a worker restart drops the proxy registration, so the original URL
+        // eventually goes stale. Every authorized GET /sessions/{id} re-signs a
+        // fresh tunnel token. Null (session stopped/failed) ends the tunnel.
+        refreshUrl: async () => {
+          const info = await api.getSession(sessionId);
+          if (info.status === "stopped" || info.status === "failed") return null;
+          return info.tunnel_url ?? null;
+        },
+        onDebug: cfg.debug ? (msg) => onEvent({ event: "warning", message: `[tunnel] ${msg}` }) : void 0,
+        onState: (s) => {
+          onTunnelState?.(s);
+          if (s === "connected") {
+            onEvent({ event: "tunnel_connected", session_id: sessionId });
+          } else if (s === "metro-unreachable") {
+            onEvent({
+              event: "warning",
+              message: `can't reach Metro on localhost:${cfg.metroPort} \u2014 is it running? (yarn start)`
+            });
+          } else if (s === "closed" && !stopping) {
+            void stopSession(1);
+          }
+        }
+      });
+      tunnel.start();
+    }
     if (cfg.open !== false) await openBrowser(pageUrl).catch(() => {
     });
     const active = await pollUntilActive(api, sessionId, 18e4);
-    const seen = new Set(ready.warnings ?? []);
     for (const w of active.warnings ?? []) {
-      if (!seen.has(w)) onEvent({ event: "warning", message: w });
+      if (reportedWarnings.has(w)) continue;
+      reportedWarnings.add(w);
+      onEvent({ event: "warning", message: w });
     }
-    return { sessionId, pageUrl, stop: () => stopSession(0) };
+    return { sessionId, pageUrl, stop: () => stopSession(0), reportedWarnings };
   } catch (err) {
     await stopSession(1);
     throw err;
   }
 }
+function devSessionCreateBody(cfg) {
+  return {
+    device_type: PLATFORM_DEVICE[cfg.platform].deviceType,
+    device_category: cfg.deviceCategory,
+    app_id: cfg.appId,
+    // Roku has no JS bundle to serve, so there is nothing to tunnel.
+    tunnel: PLATFORM_NEEDS_METRO[cfg.platform]
+  };
+}
 var BLOCKING_WARNING_PREFIXES = ["No debug build", "App install failed", "App not found"];
 function findBlockingWarning(info) {
   return (info.warnings ?? []).find((w) => BLOCKING_WARNING_PREFIXES.some((p) => w.includes(p)));
@@ -921,11 +1144,38 @@ async function pollUntilActive(api, sessionId, timeoutMs, intervalMs = 2e3) {
     await new Promise((r) => setTimeout(r, intervalMs));
   }
 }
+function sessionLivenessVerdict(info) {
+  if (info && (info.status === "stopped" || info.status === "failed")) {
+    return { end: true, message: `session ${info.status} \u2014 ending the reload loop` };
+  }
+  return { end: false };
+}
+function lateWarningVerdict(info, reportedWarnings) {
+  if (!info) return { toReport: [], blocking: false };
+  const toReport = (info.warnings ?? []).filter((w) => !reportedWarnings.has(w));
+  const blocking = findBlockingWarning({ warnings: toReport }) !== void 0;
+  return { toReport, blocking };
+}
+var ROKU_LIVENESS_INTERVAL_MS = 1e4;
+function rokuKeyAction(char) {
+  if (char === "") return "interrupt";
+  switch (char.toLowerCase()) {
+    case "r":
+      return "reload";
+    case "q":
+      return "quit";
+    default:
+      return null;
+  }
+}
 var PLATFORM_DEVICE = {
   ios: { deviceType: "ios", tv: false },
   android: { deviceType: "android", tv: false },
   tvos: { deviceType: "ios", tv: true },
-  androidtv: { deviceType: "android", tv: true }
+  androidtv: { deviceType: "android", tv: true },
+  // Roku IS its own device type (unlike tvOS/Android TV, which are the
+  // handheld type plus category tv) — the worker registers it as such.
+  roku: { deviceType: "roku", tv: true }
 };
 function appsForPlatform(apps, platform) {
   return apps.filter((a) => a.platform === platform);
@@ -953,7 +1203,7 @@ function requireNonInteractive(json) {
 async function ensureConfig(api, opts) {
   const existing = loadDevConfig(process.cwd());
   if (opts.platform && !isDevPlatform(opts.platform)) {
-    console.error(chalk2.red(`error: --platform must be one of ios, android, tvos, androidtv`));
+    console.error(chalk2.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
     process.exit(2);
   }
   if (!opts.platform && !existing?.defaultPlatform) {
@@ -961,12 +1211,7 @@ async function ensureConfig(api, opts) {
   }
   const platform = opts.platform || existing?.defaultPlatform || await select3({
     message: "Platform to run on",
-    choices: [
-      { value: "ios", name: "iOS simulator" },
-      { value: "android", name: "Android emulator" },
-      { value: "tvos", name: "Apple TV simulator" },
-      { value: "androidtv", name: "Android TV emulator" }
-    ]
+    choices: platformChoices(process.cwd())
   });
   const isTv = PLATFORM_DEVICE[platform].tv;
   if (isTv && opts.deviceCategory) {
@@ -988,7 +1233,9 @@ async function ensureConfig(api, opts) {
       requireNonInteractive(opts.json);
     } else if (process.stdin.isTTY) {
       firstRunBuild = await promptBuildConfig(process.cwd(), platform);
-      firstRunMetro = await promptMetroCommand(process.cwd(), platform);
+      if (PLATFORM_NEEDS_METRO[platform]) {
+        firstRunMetro = await promptMetroCommand(process.cwd(), platform);
+      }
     }
   }
   const entry = existing?.platforms?.[platform];
@@ -1098,7 +1345,10 @@ Run \`vibeview dev\` without --app to pick from the list.`
   });
   saveDevConfig(process.cwd(), cfg);
   if (isFirstRun) {
-    const hint = fillLaterHint({ build: !firstRunBuild, metro: !firstRunMetro }, platform);
+    const hint = fillLaterHint(
+      { build: !firstRunBuild, metro: PLATFORM_NEEDS_METRO[platform] && !firstRunMetro },
+      platform
+    );
     if (hint) console.error(chalk2.dim(hint));
   }
   const finalMetro = isFirstRun ? resolveMetro(cfg, platform, opts.metroPort ? parseInt(opts.metroPort, 10) : void 0) : metroResolved;
@@ -1113,6 +1363,15 @@ Run \`vibeview dev\` without --app to pick from the list.`
   };
 }
 async function runDevInProcess(opts) {
+  let watchSeconds;
+  try {
+    watchSeconds = parseWatchSeconds(opts.watch);
+  } catch (err) {
+    const message = err.message;
+    console.error(chalk2.red(`error: ${message}`));
+    emit(opts.json, { event: "error", code: "invalid_flag", message });
+    process.exit(2);
+  }
   if (opts.json) {
     const hasToken = !!(opts.token || process.env.VIBEVIEW_API_TOKEN || loadConfig().token);
     if (!hasToken) {
@@ -1158,51 +1417,68 @@ async function runDevInProcess(opts) {
       process.exit(1);
     }
   }
-  const metroPort = cfg.metroPort ?? 8081;
-  let metroResult;
-  try {
-    let metroLogStream = null;
-    const captureMetroLine = (line) => {
-      try {
-        if (!metroLogStream) {
-          mkdirSync3(dirname4(metroLogPath(process.cwd())), { recursive: true });
-          metroLogStream = createWriteStream(metroLogPath(process.cwd()), { flags: "w" });
+  let metroOwnedThisRun = false;
+  let rokuBuild;
+  let watchIgnore = [];
+  if (PLATFORM_NEEDS_METRO[cfg.platform]) {
+    const metroPort = cfg.metroPort ?? 8081;
+    let metroResult;
+    try {
+      let metroLogStream = null;
+      const captureMetroLine = (line) => {
+        try {
+          if (!metroLogStream) {
+            mkdirSync3(dirname5(metroLogPath(process.cwd())), { recursive: true });
+            metroLogStream = createWriteStream(metroLogPath(process.cwd()), { flags: "w" });
+          }
+          metroLogStream.write(line.replace(/^\[metro\] /, "") + "\n");
+        } catch {
         }
-        metroLogStream.write(line.replace(/^\[metro\] /, "") + "\n");
-      } catch {
-      }
-      if (shouldEchoMetroLine(line, opts.debug === true)) console.error(chalk2.dim(line));
-    };
-    metroResult = await ensureMetro(
-      process.cwd(),
-      {
-        command: cfg.metroCommand,
-        port: metroPort,
-        platformHasOverride: cfg.platformHasMetroOverride
-      },
-      captureMetroLine
-    );
-  } catch (err) {
-    const message = err.message;
-    console.error(chalk2.red(`error: ${message}`));
-    emit(opts.json, { event: "error", code: "metro_down", message });
-    process.exit(1);
-  }
-  for (const w of metroResult.warnings) console.error(chalk2.yellow(`\u26A0 ${w}`));
-  if (metroResult.status === "spawned" || metroResult.status === "respawned") {
-    console.error(chalk2.green(`\u2713 started Metro (${cfg.metroCommand})`));
-    console.error(
-      chalk2.dim(`  full Metro output: ${metroLogPath(process.cwd())} (--debug echoes it here)`)
-    );
+        if (shouldEchoMetroLine(line, opts.debug === true)) console.error(chalk2.dim(line));
+      };
+      metroResult = await ensureMetro(
+        process.cwd(),
+        {
+          command: cfg.metroCommand,
+          port: metroPort,
+          platformHasOverride: cfg.platformHasMetroOverride
+        },
+        captureMetroLine
+      );
+    } catch (err) {
+      const message = err.message;
+      console.error(chalk2.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "metro_down", message });
+      process.exit(1);
+    }
+    for (const w of metroResult.warnings) console.error(chalk2.yellow(`\u26A0 ${w}`));
+    if (metroResult.status === "spawned" || metroResult.status === "respawned") {
+      console.error(chalk2.green(`\u2713 started Metro (${cfg.metroCommand})`));
+      console.error(
+        chalk2.dim(`  full Metro output: ${metroLogPath(process.cwd())} (--debug echoes it here)`)
+      );
+    }
+    metroOwnedThisRun = metroResult.status === "spawned" || metroResult.status === "respawned";
+  } else {
+    const rokuEntry = loadDevConfig(process.cwd())?.platforms?.[cfg.platform];
+    rokuBuild = rokuEntry?.build;
+    watchIgnore = rokuEntry?.watchIgnore ?? [];
+    if (!rokuBuild) {
+      const message = `no build config for ${cfg.platform} \u2014 run \`vibeview build --platform ${cfg.platform}\` once to set it up`;
+      console.error(chalk2.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "config_required", message });
+      process.exit(1);
+    }
   }
-  const metroOwnedThisRun = metroResult.status === "spawned" || metroResult.status === "respawned";
   console.error(chalk2.dim(`Starting a ${cfg.platform} dev session for ${cfg.appId}...`));
   let stopping = false;
   let handle = null;
+  let reloadLoop = null;
   const stopSession = async (code) => {
     if (stopping) return;
     stopping = true;
     console.error(chalk2.dim("\nStopping session..."));
+    reloadLoop?.stop();
     await handle?.stop();
     if (metroOwnedThisRun) killOwnedMetro(process.cwd());
     clearDevState(process.cwd());
@@ -1213,6 +1489,7 @@ async function runDevInProcess(opts) {
   let everConnected = false;
   let waitingPrinted = false;
   let nextWarningIsMetroUnreachable = false;
+  let endedEmitted = false;
   try {
     handle = await startDevSession(
       {
@@ -1243,10 +1520,15 @@ async function runDevInProcess(opts) {
         } else if (evt.event === "session_ended" && !stopping && handle) {
           console.error(chalk2.red("tunnel closed by server \u2014 session ended"));
           stopping = true;
+          endedEmitted = true;
           emit(opts.json, evt);
           clearDevState(process.cwd());
           process.exit(1);
         }
+        if (evt.event === "session_ended") {
+          if (endedEmitted) return;
+          endedEmitted = true;
+        }
         emit(opts.json, evt);
       },
       (s) => {
@@ -1266,12 +1548,11 @@ async function runDevInProcess(opts) {
         }
       }
     );
-    console.error(
-      `
+    const keysLine = rokuBuild ? `Press ${chalk2.bold("r")} to reload the channel, ${chalk2.bold("q")} or Ctrl-C to end the session.` : "Ctrl-C to end the session.";
+    console.error(`
   Watch and interact: ${chalk2.cyan(handle.pageUrl)}
-  Ctrl-C to end the session.
-`
-    );
+  ${keysLine}
+`);
     writeDevState(process.cwd(), {
       pid: process.pid,
       session_id: handle.sessionId,
@@ -1289,6 +1570,86 @@ async function runDevInProcess(opts) {
     });
     if (opts.open !== false) await openBrowser(handle.pageUrl).catch(() => {
     });
+    if (rokuBuild) {
+      reloadLoop = createReloadLoop({
+        push: createRokuPush({
+          cwd: process.cwd(),
+          sessionId: handle.sessionId,
+          build: rokuBuild,
+          token,
+          baseUrl,
+          api,
+          // Build output and loop notices are human output, so they go to
+          // stderr like every other line this command prints — stdout stays
+          // reserved for the `--json` event stream.
+          log: (line) => console.error(chalk2.dim(line))
+        }),
+        log: (line) => console.error(chalk2.yellow(line)),
+        // A failed reload is an error, not a notice — same red as every other
+        // failure this command prints, so it doesn't read like the yellow
+        // "already reloading" line.
+        logError: (line) => console.error(chalk2.red(`\u2717 ${line}`)),
+        ...watchSeconds !== void 0 ? {
+          watchSeconds,
+          watch: watchProjectFiles(process.cwd(), rokuBuild.artifact, watchIgnore)
+        } : {}
+      });
+      if (watchSeconds !== void 0) {
+        console.error(
+          chalk2.dim(`  Watching for changes \u2014 reloading after ${watchSeconds}s of quiet.`)
+        );
+      }
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onKeyData = (chunk) => {
+          for (const char of chunk) {
+            const action = rokuKeyAction(char);
+            if (action === "reload") void reloadLoop?.trigger();
+            else if (action === "quit" || action === "interrupt") void stopSession(0);
+          }
+        };
+        process.stdin.on("data", onKeyData);
+        process.on("exit", () => {
+          process.stdin.removeListener("data", onKeyData);
+          if (process.stdin.isTTY) process.stdin.setRawMode(false);
+          process.stdin.pause();
+        });
+      }
+      const sessionId = handle.sessionId;
+      const reportedWarnings = handle.reportedWarnings;
+      const keepAlive = setInterval(() => {
+        void (async () => {
+          if (stopping) return;
+          let info = null;
+          try {
+            info = await api.getSession(sessionId);
+          } catch {
+          }
+          const verdict = sessionLivenessVerdict(info);
+          if (verdict.end && !stopping) {
+            console.error(chalk2.red(verdict.message));
+            emit(opts.json, { event: "session_ended", session_id: sessionId, code: 1 });
+            endedEmitted = true;
+            await stopSession(1);
+            return;
+          }
+          const warningVerdict = lateWarningVerdict(info, reportedWarnings);
+          for (const w of warningVerdict.toReport) {
+            reportedWarnings.add(w);
+            console.error(chalk2.yellow(`\u26A0 ${w}`));
+            emit(opts.json, { event: "warning", message: w });
+          }
+          if (warningVerdict.blocking && !stopping) {
+            emit(opts.json, { event: "session_ended", session_id: sessionId, code: 1 });
+            endedEmitted = true;
+            await stopSession(1);
+          }
+        })();
+      }, ROKU_LIVENESS_INTERVAL_MS);
+      process.on("exit", () => clearInterval(keepAlive));
+    }
   } catch (err) {
     const message = err.message;
     console.error(chalk2.red(`error: ${message}`));
@@ -2055,6 +2416,7 @@ async function runAgentVerb(cmd, positionals, opts) {
 export {
   readDevState,
   clearDevState,
+  PLATFORM_NEEDS_METRO,
   isDevPlatform,
   loadDevConfig,
   checkMetro,

package/dist/{chunk-YD2X6TQV.js → chunk-AG3RZCPW.js}

@@ -44,13 +44,31 @@ var ApiClient = class {
     this.baseUrl = baseUrl;
     this.token = token;
   }
+  /**
+   * fetch() rejects with undici's bare "TypeError: fetch failed" on any
+   * network-level failure (connection refused, DNS, TLS). Translate that
+   * into a message that names the base URL — a stray VIBEVIEW_BASE_URL
+   * pointing at a dead dev backend is indistinguishable from an outage
+   * otherwise.
+   */
+  async fetchOrExplain(url, init) {
+    try {
+      return await fetch(url, init);
+    } catch (e) {
+      const cause = e.cause;
+      const detail = cause?.code ? ` (${cause.code})` : "";
+      throw new Error(
+        `Cannot reach ${this.baseUrl}${detail}. Check the server URL (--base-url flag, VIBEVIEW_BASE_URL, or ~/.vibeview/config.json) and your network.`
+      );
+    }
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}/api/v1/ci${path}`;
     const headers = {
       Authorization: `Bearer ${this.token}`,
       "Content-Type": "application/json"
     };
-    const resp = await fetch(url, {
+    const resp = await this.fetchOrExplain(url, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
@@ -122,7 +140,7 @@ var ApiClient = class {
       Authorization: `Bearer ${this.token}`,
       "Content-Type": "application/json"
     };
-    const resp = await fetch(url, {
+    const resp = await this.fetchOrExplain(url, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
@@ -142,7 +160,7 @@ var ApiClient = class {
       Authorization: `Bearer ${this.token}`
       // Do NOT set Content-Type — let fetch set multipart boundary automatically
     };
-    const resp = await fetch(url, {
+    const resp = await this.fetchOrExplain(url, {
       method,
       headers,
       body: formData
@@ -214,6 +232,15 @@ var ApiClient = class {
   async stopSession(sessionId) {
     await this.requestRaw("DELETE", `/sessions/${sessionId}`);
   }
+  /** Install an already-uploaded build into a running session. Used by the
+   *  Roku dev reload loop; the worker sideloads and (with launchAfterInstall)
+   *  relaunches the channel in place. */
+  async installBuild(sessionId, buildId, launchAfterInstall = true) {
+    return this.requestRaw("POST", `/sessions/${sessionId}/install-build`, {
+      build_id: buildId,
+      launch_after_install: launchAfterInstall
+    });
+  }
   async agentTool(sessionId, tool, args) {
     return this.requestRaw("POST", `/sessions/${sessionId}/agent/tools`, { tool, args });
   }
@@ -223,7 +250,7 @@ var ApiClient = class {
 import ora from "ora";
 function createSpinner(text) {
   const isCI = process.env.CI === "true" || process.env.CI === "1" || !process.stdout.isTTY;
-  return ora({ text, isEnabled: !isCI, stream: process.stderr });
+  return ora({ text, isEnabled: !isCI, stream: process.stderr, discardStdin: false });
 }
 
 // src/lib/types.ts

package/dist/cli.js

@@ -8,7 +8,7 @@ import {
   readDevState,
   readMetroState,
   runAgentVerb
-} from "./chunk-NA3JOV5Z.js";
+} from "./chunk-4UGLSIZM.js";
 import {
   ApiClient,
   EXIT_INFRA_ERROR,
@@ -19,7 +19,7 @@ import {
   resolveAuth,
   saveConfig,
   uploadApp
-} from "./chunk-YD2X6TQV.js";
+} from "./chunk-AG3RZCPW.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -1022,6 +1022,37 @@ Opening browser to log in...
   process.exit(EXIT_INFRA_ERROR);
 }
 
+// src/commands/logout.ts
+async function logout() {
+  const config = loadConfig();
+  if (!config.token) {
+    console.log("Not logged in (no token saved in ~/.vibeview/config.json).");
+    if (process.env.VIBEVIEW_API_TOKEN) {
+      console.log("Note: VIBEVIEW_API_TOKEN is set; logout does not manage env tokens.");
+    }
+    return;
+  }
+  const baseUrl = config.baseUrl || "https://vibeview.io";
+  let revoked = false;
+  try {
+    const resp = await fetch(`${baseUrl}/api/v1/auth/cli-token/revoke`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${config.token}` }
+    });
+    revoked = resp.ok || resp.status === 401;
+  } catch {
+    revoked = false;
+  }
+  saveConfig({ ...config, token: void 0 });
+  if (revoked) {
+    console.log("Logged out. Token revoked and removed from ~/.vibeview/config.json.");
+  } else {
+    console.log("Logged out. Removed token from ~/.vibeview/config.json.");
+    console.log(`  Warning: could not reach ${baseUrl} to revoke the token server-side.`);
+    console.log("  It stays active until revoked in the dashboard (Settings -> API Tokens).");
+  }
+}
+
 // src/commands/dev-status.ts
 import chalk9 from "chalk";
 async function devStatus(opts) {
@@ -1423,9 +1454,12 @@ program.command("list-devices").description("List devices registered with the pl
 program.command("upload-app <file>").description("Upload an app build (zipped simulator .app for iOS, .apk for Android)").option("--token <token>", "API token").option("--output <format>", "Output format: human, json", "human").option("--name <name>", "App name (auto-detected if not provided)").action((file, opts) => uploadApp(file, opts));
 program.command("create-test [name]").description("Create a standalone AI test case").option("--token <token>", "API token").option("--output <format>", "Output format: human, json", "human").option("--app <app>", "App ID (public_id) or package name (requires --platform)").option("--platform <platform>", "Platform (ios, android) when using package name for --app").option("--steps <json>", "Test steps as inline JSON array").option("--steps-file <path>", "Path to JSON file containing test steps").option("--context <text>", "Additional context for AI test execution").option("--test-name <name>", "Test case name (alternative to positional arg)").action((name, opts) => createTest({ ...opts, testName: name || opts.testName || "CLI Test" }));
 program.command("login").description("Log in to VibeView (interactive)").option("--base-url <url>", "VibeView server URL (defaults to https://vibeview.io)").action((opts) => login(opts));
-program.command("dev").description("Stream your app from the fleet with live Metro hot-reload (RN debug builds)").option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option("--web-url <url>", "Dashboard URL if different from the API URL (local dev)").option(
+program.command("logout").description("Revoke the saved login token and remove it from ~/.vibeview/config.json").action(() => logout());
+program.command("dev").description(
+  "Stream your app from the fleet with live Metro hot-reload (RN debug builds), or press `r` to re-package and reload a Roku channel in place"
+).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option("--web-url <url>", "Dashboard URL if different from the API URL (local dev)").option(
   "--platform <platform>",
-  "ios, android, tvos, or androidtv (first run is interactive otherwise)"
+  "ios, android, tvos, androidtv, or roku (first run is interactive otherwise)"
 ).option("--app <app_id>", "Uploaded debug build to run (see `vibeview list-apps`)").option("--metro-port <port>", "Local Metro port (default: 8081, remembered in vibeview.json)").option(
   "--device-category <category>",
   "phone or tablet (default: phone; TV platforms always use tv)",
@@ -1438,17 +1472,20 @@ program.command("dev").description("Stream your app from the fleet with live Met
   "--build",
   "Build and upload first (uses platforms.<platform>.build from vibeview.json)",
   false
+).option(
+  "--watch [seconds]",
+  "Roku only: auto-reload after file changes settle (default: 2 seconds of quiet)"
 ).action((opts) => dev(opts));
 program.command("build").description("Run your configured build command and upload the result (see vibeview.json)").option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option(
   "--platform <platform>",
-  "ios, android, tvos, or androidtv (default: vibeview.json defaultPlatform)"
+  "ios, android, tvos, androidtv, or roku (default: vibeview.json defaultPlatform)"
 ).option("--json", "Print the result as one JSON line", false).action((opts) => buildCommand(opts));
 program.command("dev-status").description("Show the status of a `vibeview dev --detach` session in this project").option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option("--json", "Print as one JSON line", false).action((opts) => devStatus(opts));
 program.command("dev-stop").description("Stop a `vibeview dev --detach` session in this project").option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option("--json", "Print as one JSON line", false).action((opts) => devStop(opts));
 program.command("mcp").description(
   "Run an MCP stdio server exposing the agent verbs (tap, swipe, type, ...) plus dev_start/dev_stop as tools"
 ).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").action(async (opts) => {
-  const { runMcpServer } = await import("./server-B2PDQJLR.js");
+  const { runMcpServer } = await import("./server-S6OCJERW.js");
   await runMcpServer(opts);
 });
 program.command("agent-setup").description(
@@ -1470,4 +1507,12 @@ for (const cmd of AGENT_COMMANDS) {
     return runAgentVerb(cmd, positionals, opts);
   });
 }
-program.parse();
+program.parseAsync().catch((e) => {
+  if (e instanceof Error && e.name === "ExitPromptError") {
+    process.exit(130);
+  }
+  if (process.env.VIBEVIEW_DEBUG) throw e;
+  process.stderr.write(`error: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(EXIT_INFRA_ERROR);
+});

package/dist/{server-B2PDQJLR.js → server-S6OCJERW.js}

@@ -2,6 +2,7 @@
 import {
   AGENT_COMMANDS,
   PLATFORM_DEVICE,
+  PLATFORM_NEEDS_METRO,
   buildToolCall,
   checkMetro,
   decodeScreenshotResult,
@@ -10,11 +11,11 @@ import {
   readDevState,
   renderEnvelope,
   startDevSession
-} from "./chunk-NA3JOV5Z.js";
+} from "./chunk-4UGLSIZM.js";
 import {
   ApiClient,
   resolveAuth
-} from "./chunk-YD2X6TQV.js";
+} from "./chunk-AG3RZCPW.js";
 
 // src/mcp/server.ts
 import { writeFileSync } from "fs";
@@ -25,7 +26,10 @@ var SESSION_ID_PROPERTY = {
   type: "string",
   description: "Session ID to target. Optional: falls back to the MCP-server-held dev_start session, then this project's `vibeview dev --detach` state, if either is available."
 };
-var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+var MCP_DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+function isMcpDevPlatform(p) {
+  return isDevPlatform(p) && MCP_DEV_PLATFORMS.includes(p);
+}
 function paramToProperty(param) {
   return { type: param.type, description: param.description };
 }
@@ -62,7 +66,7 @@ var DEV_START_DEF = {
     platform: {
       type: "string",
       description: "Platform to run on.",
-      enum: [...DEV_PLATFORMS]
+      enum: [...MCP_DEV_PLATFORMS]
     },
     app: {
       type: "string",
@@ -194,9 +198,14 @@ function optsFor(cmd, args) {
 }
 async function handleDevStart(args, deps) {
   const platform = args.platform;
-  if (!isDevPlatform(platform)) {
+  if (platform === "roku") {
+    return errorResult(
+      "dev_start does not support roku \u2014 the reload loop needs a foreground terminal; run `vibeview dev --platform roku` instead"
+    );
+  }
+  if (!isMcpDevPlatform(platform)) {
     return errorResult(
-      `dev_start: platform must be one of ${DEV_PLATFORMS.join(", ")}, got "${String(platform)}"`
+      `dev_start: platform must be one of ${MCP_DEV_PLATFORMS.join(", ")}, got "${String(platform)}"`
     );
   }
   try {
@@ -230,7 +239,7 @@ async function handleUploadApp(args, deps) {
   }
   const name = typeof args.name === "string" && args.name ? args.name : void 0;
   const upload = deps.uploadApp ?? (async (f, n) => {
-    const { uploadAppBuild } = await import("./upload-app-GAZVQZYR.js");
+    const { uploadAppBuild } = await import("./upload-app-JIOFLMS3.js");
     const { result: result2 } = await uploadAppBuild(f, { ...deps.auth, name: n });
     return result2;
   });
@@ -280,11 +289,13 @@ function createDevSessionController(auth, webUrl) {
         );
       }
       const metroPort = cfg.metroPort ?? devConfig?.metroPort ?? 8081;
-      const metro = await checkMetro(metroPort);
-      if (metro === "down") {
-        throw new Error(
-          `Metro isn't running on localhost:${metroPort} \u2014 start it in the project first (yarn start), or pass metro_port if Metro uses another port`
-        );
+      if (PLATFORM_NEEDS_METRO[cfg.platform]) {
+        const metro = await checkMetro(metroPort);
+        if (metro === "down") {
+          throw new Error(
+            `Metro isn't running on localhost:${metroPort} \u2014 start it in the project first (yarn start), or pass metro_port if Metro uses another port`
+          );
+        }
       }
       const isTv = PLATFORM_DEVICE[cfg.platform].tv;
       handle = await startDevSession({

package/dist/{upload-app-GAZVQZYR.js → upload-app-JIOFLMS3.js}

@@ -2,7 +2,7 @@
 import {
   uploadApp,
   uploadAppBuild
-} from "./chunk-YD2X6TQV.js";
+} from "./chunk-AG3RZCPW.js";
 export {
   uploadApp,
   uploadAppBuild

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeview",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "VibeView CLI -- run mobile tests from CI/CD pipelines",
   "type": "module",
   "bin": {

package/skills/vibeview-agent/SKILL.md

@@ -50,6 +50,11 @@ https://vibeview.io/docs/preparing-your-build.
    fires once the session accepts commands (device up, app installed) —
    no need to poll `dev-status` first. If the app ships no native changes
    since the last run, skip step 1 and just do steps 2–4.
+5. **Immediately tell the developer the session `url`** — "watch or take
+   over at any time: `<url>`". The page is a live, fully interactive view
+   of the device; the developer watching along is a feature, not a risk.
+   (For a session you attached to with `--session` instead of starting,
+   the page is `https://vibeview.io/sandbox/<session_id>`.)
 
 Running `dev` writes two things into the project root: a `.vibeview/`
 directory (live session state — local machine state, never commit) and a
@@ -150,7 +155,26 @@ it rather than letting it appear unexplained in their `git status`.
   focus directly with `tap-focused` (moves focus AND activates) / `focus`
   (moves focus only, no activation).
 
-## 4. Cleanup
+## 4. When only a human can act — stop and hand off
+
+Some screens need things you must never guess or invent: **login
+credentials, 2FA/OTP codes, CAPTCHAs, destructive confirmations
+("Delete account?"), anything payment- or real-account-shaped.** When you
+hit one:
+
+1. **Stop driving.** Do not type guessed credentials, do not tap through a
+   destructive confirmation to "see what happens".
+2. **Ask the developer, naming exactly what you need and where**: "I'm at
+   the login screen — please sign in at `<session url>` and tell me when
+   you're done." The session page is fully interactive; the developer can
+   drive the device directly while you wait.
+3. **On resume, run `ui-tree` FIRST** — the human just changed the screen,
+   so every ref you held is stale — and **verify the blocker is actually
+   gone from the tree** (e.g. the login form is absent) instead of trusting
+   the confirmation alone. If it's still there, say what you still see and
+   ask again.
+
+## 5. Cleanup
 
 **Always** stop the session when done verifying — a running session bills
 streaming minutes even when idle:
@@ -158,7 +182,7 @@ streaming minutes even when idle:
 vibeview dev-stop
 ```
 
-## 5. Command reference
+## 6. Command reference
 
 Every verb accepts `--session <id>` to target a specific session (falls
 back to the current project's `vibeview dev --detach` session if omitted)
@@ -194,7 +218,7 @@ Dev-loop lifecycle commands (not registry verbs, but needed for every run):
 | `dev-status` | Check on the current project's detached dev session. |
 | `dev-stop` | End the current project's detached dev session. |
 
-## 6. If you're calling VibeView over MCP
+## 7. If you're calling VibeView over MCP
 
 Everything above is also exposed as MCP tools by `vibeview mcp`, so an agent
 with no shell can run the whole loop. Tool names are the CLI verbs with
@@ -210,7 +234,7 @@ steps the CLI does with plain shell commands:
 | MCP tool | Args | Purpose |
 |----------|------|---------|
 | `upload_app` | `file` (required path), `name` | Upload a debug build. The MCP equivalent of `vibeview upload-app`, so step 1 of the loop needs no shell. Returns the `app_id` to pass to `dev_start`. |
-| `dev_start` | `platform` (required: `ios`/`android`/`tvos`/`androidtv`), `app`, `metro_port` | Start a dev-loop session held open by the MCP server. The MCP equivalent of `vibeview dev --detach`. |
+| `dev_start` | `platform` (required: `ios`/`android`/`tvos`/`androidtv`), `app`, `metro_port` | Start a dev-loop session held open by the MCP server. The MCP equivalent of `vibeview dev --detach`. Returns `page_url` — relay it to the developer immediately, same as step 5 of the loop. |
 | `dev_stop` | — | Stop the session `dev_start` started. The MCP equivalent of `vibeview dev-stop`. |
 
 **`dev_start` is stateful — it changes the default session for every later