@xbrowser/cli 1.9.7 → 1.9.9

package/dist/index.js

@@ -1,21 +1,7 @@
 import {
   detectAntiBot,
   formatDetectionMessage
-} from "./chunk-DPJNCMLC.js";
-import {
-  CaptchaDetector,
-  HumanInteractionManager,
-  NPM_REGISTRY_URL,
-  NPM_SCOPE,
-  ScreencastCapturer,
-  WebhookNotifier,
-  getCaptchaConfig,
-  getConfigValue,
-  getMarketplaceUrl,
-  loadConfig,
-  resolveNpmPackageWithFallback,
-  setConfigValue
-} from "./chunk-ZJHQPMCY.js";
+} from "./chunk-INTQPBYF.js";
 import {
   forwardCommandLog,
   forwardNetworkAnalyze,
@@ -38,13 +24,32 @@ import {
   forwardSessionClose,
   forwardSessionList,
   forwardViewerCheckSelector,
+  version
+} from "./chunk-YMUSHPU4.js";
+import {
+  buildViewerUrl
+} from "./chunk-3OD76SUE.js";
+import {
+  CaptchaDetector,
+  HumanInteractionManager,
+  NPM_REGISTRY_URL,
+  NPM_SCOPE,
+  ScreencastCapturer,
+  WebhookNotifier,
+  getCaptchaConfig,
+  getConfigValue,
+  getMarketplaceUrl,
+  loadConfig,
+  resolveNpmPackageWithFallback,
+  setConfigValue
+} from "./chunk-DWDXEGVK.js";
+import {
   getDaemonConfig,
   getDaemonProcessStatus,
   killAllDaemonProcesses,
   startDaemonProcess,
-  stopDaemonProcess,
-  version
-} from "./chunk-YAUG3NSI.js";
+  stopDaemonProcess
+} from "./chunk-Q2DFJQGS.js";
 import {
   generateBashScript,
   generateJSScript,
@@ -61,7 +66,7 @@ import {
 } from "./chunk-ANVL2ID2.js";
 import {
   SessionRecorder
-} from "./chunk-CH5ZQV64.js";
+} from "./chunk-4452SPFI.js";
 import {
   addKnownIssue,
   getKnowledgePath,
@@ -86,8 +91,8 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-5JSOGINQ.js";
-import "./chunk-VJNMAWPZ.js";
+} from "./chunk-RZM5CNIY.js";
+import "./chunk-RRBXV7KE.js";
 import "./chunk-TNEN6VQ2.js";
 import {
   errMsg
@@ -6197,7 +6202,7 @@ function attachWaitForHuman(ctx, getOrCreateWSServer) {
     if (!ctx.page) {
       throw new Error("waitForHuman requires an active page");
     }
-    const { HumanInteractionManager: HumanInteractionManager2 } = await import("./human-interaction-2DZK4MW7.js");
+    const { HumanInteractionManager: HumanInteractionManager2 } = await import("./human-interaction-C5OEGXGO.js");
     const wsServer2 = await getOrCreateWSServer(ctx.browserContext);
     const manager = new HumanInteractionManager2(wsServer2, ctx.page);
     return manager.waitForHuman(options);
@@ -6205,7 +6210,7 @@ function attachWaitForHuman(ctx, getOrCreateWSServer) {
 }
 function attachDetectAntiBot(ctx) {
   ctx.detectAntiBot = async (page, config) => {
-    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-MCVM6IFB.js");
+    const { detectAntiBot: detectAntiBot2 } = await import("./anti-bot-DR56Y63V.js");
     return detectAntiBot2(page, config);
   };
 }
@@ -6658,18 +6663,6 @@ async function getPluginLoader() {
   return pluginLoader;
 }
 
-// src/utils/viewer-url.ts
-function buildViewerUrl(sessionName = "default") {
-  try {
-    const status = getDaemonProcessStatus();
-    if (!status.running) return void 0;
-    const port = status.port || getDaemonConfig().basePort;
-    return `http://localhost:${port}/preview/${encodeURIComponent(sessionName)}`;
-  } catch {
-    return void 0;
-  }
-}
-
 // src/plugin/login-guard.ts
 async function checkPluginLoginRequired(options) {
   const { site, command, commandName, ctx, page, sessionName } = options;
@@ -7406,7 +7399,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-ZPQP6VW7.js");
+    const { findTargetPage } = await import("./browser-YCO4GJMZ.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -7423,7 +7416,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     params = result.data;
   }
   if (command.scope !== "cli" && !process.env.XBROWSER_DAEMON_WORKER) {
-    const { forwardExec } = await import("./daemon-client-CMRAWXTN.js");
+    const { forwardExec } = await import("./daemon-client-O6BYVRXV.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -7611,6 +7604,26 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     const end = Date.now();
     const duration = end - start;
     const errorMessage = errMsg(err);
+    if (session?.page && process.env.XBROWSER_RECOVERY && !extraOpts?._recoveryAttempted) {
+      try {
+        const { attemptRecovery } = await import("./recovery-ZJVVHP7N.js");
+        const recovery = await attemptRecovery(
+          session.page,
+          sessionName,
+          commandName,
+          errorMessage
+        );
+        if (recovery.recovered) {
+          const retry = await executeCommand(commandName, params, sessionName, {
+            ...extraOpts,
+            skipCleanup: true,
+            _recoveryAttempted: true
+          });
+          return retry;
+        }
+      } catch {
+      }
+    }
     if (session) {
       streamCommandEvent(session.id, {
         sessionId: session.id,
@@ -10937,7 +10950,7 @@ async function handlePlugin(args, options, mode) {
       } catch {
       }
       try {
-        const { daemonPing } = await import("./daemon-client-CMRAWXTN.js");
+        const { daemonPing } = await import("./daemon-client-O6BYVRXV.js");
         if (await daemonPing()) {
           await fetch("http://localhost:9224/rpc", {
             method: "POST",
@@ -11503,7 +11516,7 @@ async function handleFilter(args, _mode, options) {
   }
 }
 async function handleGeneratePlugin(sessionName, pluginName, outputDir) {
-  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-RFOPX4SF.js");
+  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-QRZMKFVL.js");
   const { readSiteKnowledge: readSiteKnowledge2, toMarkdown } = await import("./site-knowledge-SYC6VCDB.js");
   const { mkdirSync: mkdirSync11, writeFileSync: writeFileSync13 } = await import("fs");
   const { join: join14 } = await import("path");
@@ -11740,7 +11753,7 @@ async function handleRun(filePath, options) {
 
 // src/cli/viewer-routes.ts
 async function handleViewer(_args, options, mode, _cdpEndpoint) {
-  const name = options.name || process.env.XBROWSER_SESSION || "default";
+  const name = options.session || process.env.XBROWSER_SESSION || "default";
   const selector = options.selector;
   const userPort = options.port ? Number(options.port) : void 0;
   let status = getDaemonProcessStatus();
@@ -13440,9 +13453,9 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
           }
           const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
-            const { forwardExec } = await import("./daemon-client-CMRAWXTN.js");
+            const { forwardPluginExec } = await import("./daemon-client-O6BYVRXV.js");
             const userTimeout = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 + 3e4 : void 0;
-            const result = await forwardExec(`${command}.${subCommand}`, params, sessionName, cdpEndpoint, userTimeout);
+            const result = await forwardPluginExec(`${command}.${subCommand}`, params, sessionName, cdpEndpoint, userTimeout);
             const resultData = result && typeof result === "object" && "data" in result ? result.data : void 0;
             if (result && result.success === false && resultData?.code === "LOGIN_REQUIRED") {
               process.exitCode = 1;
@@ -13480,7 +13493,7 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
               const targetPage = pages[cmdTabIndex];
               await targetPage.bringToFront().catch(() => {
               });
-              const { setActivePage: setActivePage2 } = await import("./browser-ZPQP6VW7.js");
+              const { setActivePage: setActivePage2 } = await import("./browser-YCO4GJMZ.js");
               setActivePage2(session, targetPage);
             }
           }
@@ -14085,10 +14098,37 @@ import { EventEmitter as EventEmitter2 } from "events";
 // src/stream/frame-processor.ts
 import sharp from "sharp";
 var STATE_CONFIGS = {
-  user_interacting: { format: "jpeg", quality: 85, maxFps: 60, scale: 0.8 },
-  screen_moving: { format: "jpeg", quality: 85, maxFps: 8, scale: 0.8 },
-  static: { format: "jpeg", quality: 95, maxFps: 2, scale: 1 }
+  // Full-screen: aggressive compression for speed
+  // user_interacting: low quality + downscale — prioritize FPS over clarity
+  user_interacting: { format: "jpeg", quality: 40, maxFps: 30, scale: 0.6 },
+  // screen_moving: page is animating but user is NOT operating.
+  // Keep quality close to interacting to avoid visible flicker on state change.
+  screen_moving: { format: "jpeg", quality: 45, maxFps: 2, scale: 0.7 },
+  // static: highest quality — user is reading, bandwidth is not a concern
+  static: { format: "jpeg", quality: 95, maxFps: 1, scale: 1 }
 };
+function adjustConfigForSize(config, frameWidth, frameHeight, fullViewportWidth, fullViewportHeight) {
+  const framePixels = frameWidth * frameHeight;
+  const fullPixels = fullViewportWidth * fullViewportHeight;
+  const ratio = fullPixels > 0 ? framePixels / fullPixels : 1;
+  if (ratio < 0.3) {
+    return {
+      ...config,
+      quality: Math.min(config.quality + 40, 90),
+      // boost quality
+      scale: Math.max(config.scale, 0.9)
+      // don't downscale
+    };
+  }
+  if (ratio < 0.6) {
+    return {
+      ...config,
+      quality: Math.min(config.quality + 20, 80),
+      scale: Math.max(config.scale, 0.7)
+    };
+  }
+  return config;
+}
 var StreamStateManager = class {
   currentState = "static";
   isUserInteracting = false;
@@ -14097,9 +14137,11 @@ var StreamStateManager = class {
   frameInterval = Infinity;
   onStateChange = null;
   staticTimer = null;
-  USER_INTERACTION_TIMEOUT_MS = 1e3;
+  USER_INTERACTION_TIMEOUT_MS = 2e3;
+  // 1s → 2s: linger in interacting longer
   SCREEN_MOVING_THRESHOLD_MS = 1e3;
-  STATIC_TIMEOUT_MS = 1500;
+  STATIC_TIMEOUT_MS = 3e3;
+  // 1.5s → 3s: don't rush to static
   setStateChangeCallback(callback) {
     this.onStateChange = callback;
   }
@@ -14208,12 +14250,25 @@ var FrameProcessor = class {
     }
     let processed = sharp(buffer);
     if (cropConfig) {
-      processed = processed.extract({
-        left: Math.round(cropConfig.x),
-        top: Math.round(cropConfig.y),
-        width: Math.round(cropConfig.width),
-        height: Math.round(cropConfig.height)
-      });
+      const meta = await processed.metadata();
+      const actualW = meta.width ?? viewportWidth ?? 1;
+      const actualH = meta.height ?? viewportHeight ?? 1;
+      const refW = viewportWidth ?? actualW;
+      const refH = viewportHeight ?? actualH;
+      const scaleX = actualW / refW;
+      const scaleY = actualH / refH;
+      const cropLeft = Math.round(cropConfig.x * scaleX);
+      const cropTop = Math.round(cropConfig.y * scaleY);
+      const cropW = Math.min(Math.round(cropConfig.width * scaleX), actualW - cropLeft);
+      const cropH = Math.min(Math.round(cropConfig.height * scaleY), actualH - cropTop);
+      if (cropW > 0 && cropH > 0 && cropLeft >= 0 && cropTop >= 0) {
+        processed = processed.extract({
+          left: cropLeft,
+          top: cropTop,
+          width: cropW,
+          height: cropH
+        });
+      }
     }
     if (needsResize) {
       const newWidth = Math.round((viewportWidth ?? 0) * config.scale);
@@ -14362,11 +14417,20 @@ var StreamCoordinator = class {
     const crop = this.sessionCrops.get(sessionId);
     const cropConfig = crop ? crop.box : void 0;
     const effectiveViewport = crop ? { width: crop.box.width, height: crop.box.height } : frameViewport;
-    const processedBuffer = await this.frameProcessor.process(
-      frameData,
+    const adjustedConfig = adjustConfigForSize(
       config,
       effectiveViewport.width,
       effectiveViewport.height,
+      frameViewport.width,
+      frameViewport.height
+    );
+    const processedBuffer = await this.frameProcessor.process(
+      frameData,
+      adjustedConfig,
+      // Pass the ORIGINAL viewport (not cropped) so crop coordinates
+      // can be scaled correctly from viewport space to frame pixel space.
+      crop ? frameViewport.width : effectiveViewport.width,
+      crop ? frameViewport.height : effectiveViewport.height,
       cropConfig
     );
     const header = Buffer.from(JSON.stringify({
@@ -14538,7 +14602,18 @@ var ElementMonitor = class {
         }
         return results;
       });
-      const views = elements.map((e, i) => ({
+      const TOLERANCE_PX = 10;
+      const deduped = [];
+      const isSameSize = (a, b) => Math.abs(a.width - b.width) <= TOLERANCE_PX && Math.abs(a.height - b.height) <= TOLERANCE_PX;
+      const sorted = [...elements].sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height);
+      for (const el of sorted) {
+        const dupe = deduped.some(
+          (d) => isSameSize(d.rect, el.rect) && Math.abs(d.rect.x - el.rect.x) <= TOLERANCE_PX && Math.abs(d.rect.y - el.rect.y) <= TOLERANCE_PX
+        );
+        if (!dupe) deduped.push(el);
+      }
+      deduped.sort((a, b) => b.rect.width * b.rect.height - a.rect.width * a.rect.height);
+      const views = deduped.map((e, i) => ({
         id: "el-" + i + "-" + (e.id || e.tag),
         label: e.id || e.cls || e.tag,
         rect: e.rect
@@ -14597,10 +14672,10 @@ var SessionManager = class extends EventEmitter {
     this.screencasts.set(sessionId, {
       capturer: new ScreencastCapturer({
         interval: options?.interval ?? 100,
-        quality: options?.quality ?? 80,
+        quality: options?.quality ?? 40,
         type: options?.type ?? "jpeg",
-        width: options?.width ?? 1920,
-        height: options?.height ?? 1080
+        width: options?.width ?? 1024,
+        height: options?.height ?? 576
       }),
       page,
       clientCount: 0
@@ -14741,6 +14816,8 @@ var SessionManager = class extends EventEmitter {
       this.resetStaticSnapshotTimer(sessionId);
     });
     await sc.capturer.startCapture(sc.page, sessionId, onFrame);
+    this.streamCoordinator.takeStaticSnapshot(sessionId, sc.page, sc.clientCount).catch(() => {
+    });
   }
   async stopCapturer(sessionId) {
     const sc = this.screencasts.get(sessionId);
@@ -15191,6 +15268,15 @@ var WSServer = class extends EventEmitter2 {
   registerSession(sessionId, page, options) {
     this.sessionManager.registerSession(sessionId, page, options);
   }
+  /** Restart screencast for a session — used by viewer reconnect button. */
+  async reconnectSession(sessionId) {
+    try {
+      await this.sessionManager.stopCapturer(sessionId);
+      await new Promise((r) => setTimeout(r, 500));
+      await this.sessionManager.startCapturer(sessionId);
+    } catch {
+    }
+  }
   unregisterSession(sessionId) {
     this.sessionManager.unregisterSession(sessionId);
   }
@@ -15213,7 +15299,7 @@ var WSServer = class extends EventEmitter2 {
       });
     }
     this.sessionManager.incrementClientCount(sessionId);
-    if (this.streamCoordinator.getLastFrameViewport() && this.sessionManager.isCapturerActive(sessionId)) {
+    if (this.streamCoordinator.getLastFrameViewport()) {
       this.streamCoordinator.replayLastFrame(sessionId).catch(() => {
       });
     }
@@ -15223,7 +15309,6 @@ var WSServer = class extends EventEmitter2 {
     if (count === 0 && this.sessionManager.isCapturerActive(sessionId)) {
       this.sessionManager.stopCapturer(sessionId).then(() => {
         this.streamCoordinator.resetFrameRate();
-        this.streamCoordinator.clearLastFrame();
         this.emit("screencast-stopped", sessionId);
       }).catch(() => {
         this.emit("screencast-stopped", sessionId);
@@ -15399,6 +15484,31 @@ var WSServer = class extends EventEmitter2 {
       this.emit("human-solved", { sessionId: sessionId ?? null, clientId });
       return;
     }
+    if (msg.type === "reconnect") {
+      this.emit("reconnect-request", { sessionId: sessionId ?? null, clientId });
+      return;
+    }
+    if (msg.type === "health_ping") {
+      this.sendToClient(clientId, { type: "health_pong", ts: msg.ts });
+      return;
+    }
+    if (msg.type === "snapshot_request") {
+      const page2 = sessionId ? this.sessionManager.getPageForSession(sessionId) : void 0;
+      if (!page2) {
+        this.sendToClient(clientId, { type: "snapshot_result", data: null, error: "no page" });
+        return;
+      }
+      const fmt = msg.format === "webp" ? "webp" : "png";
+      page2.screenshot({ type: fmt, quality: fmt === "webp" ? msg.quality ?? 90 : void 0 }).then((buf) => {
+        this.sendToClient(clientId, {
+          type: "snapshot_result",
+          data: { data: buf.toString("base64"), format: fmt }
+        });
+      }).catch(() => {
+        this.sendToClient(clientId, { type: "snapshot_result", data: null, error: "screenshot failed" });
+      });
+      return;
+    }
     const ctx = {
       clientId,
       sessionId,
@@ -16543,7 +16653,7 @@ var DataCollector = class {
     return results;
   }
   async createBrowserContext() {
-    const { launch } = await import("./cdp-driver-6EVYLHL2.js");
+    const { launch } = await import("./cdp-driver-J3YQ4LJV.js");
     const { browser } = await launch({
       headless: true,
       args: ["--no-sandbox", "--disable-setuid-sandbox"]

package/dist/recovery-EF33LKRJ.js

@@ -0,0 +1,77 @@
+import {
+  buildViewerUrl
+} from "./chunk-TZPKFUBT.js";
+import "./chunk-CG3D3CHY.js";
+import {
+  HumanInteractionManager
+} from "./chunk-SQHSZENE.js";
+import "./chunk-BNO7OKO4.js";
+import "./chunk-KFQGP6VL.js";
+
+// src/recovery.ts
+function getRecoveryConfig() {
+  const val = process.env.XBROWSER_RECOVERY?.toLowerCase();
+  return {
+    enabled: val === "true" || val === "1" || val === "yes",
+    timeout: Math.max(10, parseInt(process.env.XBROWSER_RECOVERY_TIMEOUT || "120", 10))
+  };
+}
+async function attemptRecovery(page, sessionName, commandName, errorMessage, previewWS) {
+  const cfg = getRecoveryConfig();
+  if (!cfg.enabled) return { recovered: false };
+  if (!page) {
+    return { recovered: false };
+  }
+  const viewerUrl = buildViewerUrl(sessionName);
+  if (previewWS) {
+    try {
+      previewWS.registerSession(sessionName, page);
+      const manager = new HumanInteractionManager(previewWS, page);
+      const result = await manager.waitForHuman({
+        reason: `Command "${commandName}" failed: ${errorMessage}. Fix the issue and confirm via viewer.`,
+        timeout: cfg.timeout,
+        autoDetect: false
+      });
+      return { recovered: result.solved };
+    } catch {
+    }
+  }
+  console.log("");
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log(`\u26A0\uFE0F  COMMAND FAILED: ${commandName}`);
+  console.log(`\u26A0\uFE0F  Error: ${errorMessage}`);
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Recovery mode activated`);
+  if (viewerUrl) {
+    console.log(`\u26A0\uFE0F  Viewer: ${viewerUrl}`);
+  }
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Fix the issue, then press ENTER to retry`);
+  console.log(`\u26A0\uFE0F  Type "abort" + ENTER to cancel`);
+  console.log(`\u26A0\uFE0F  (${cfg.timeout}s timeout)`);
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log("");
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      clearTimeout(timeoutTimer);
+      process.stdin.removeListener("data", onData);
+      process.stdin.pause();
+    };
+    const timeoutTimer = setTimeout(() => {
+      console.log("\u23F0 Recovery timeout \u2014 aborting");
+      cleanup();
+      resolve({ recovered: false });
+    }, cfg.timeout * 1e3);
+    const onData = (buf) => {
+      const line = buf.toString().trim().toLowerCase();
+      cleanup();
+      resolve({ recovered: line !== "abort" && line !== "q" && line !== "exit" });
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+export {
+  attemptRecovery,
+  getRecoveryConfig
+};

package/dist/recovery-J2ISVGUL.js

@@ -0,0 +1,77 @@
+import {
+  buildViewerUrl
+} from "./chunk-3OD76SUE.js";
+import "./chunk-Q2DFJQGS.js";
+import {
+  HumanInteractionManager
+} from "./chunk-MWFHZUIY.js";
+import "./chunk-IIM5GOD7.js";
+import "./chunk-KFQGP6VL.js";
+
+// src/recovery.ts
+function getRecoveryConfig() {
+  const val = process.env.XBROWSER_RECOVERY?.toLowerCase();
+  return {
+    enabled: val === "true" || val === "1" || val === "yes",
+    timeout: Math.max(10, parseInt(process.env.XBROWSER_RECOVERY_TIMEOUT || "120", 10))
+  };
+}
+async function attemptRecovery(page, sessionName, commandName, errorMessage, previewWS) {
+  const cfg = getRecoveryConfig();
+  if (!cfg.enabled) return { recovered: false };
+  if (!page) {
+    return { recovered: false };
+  }
+  const viewerUrl = buildViewerUrl(sessionName);
+  if (previewWS) {
+    try {
+      previewWS.registerSession(sessionName, page);
+      const manager = new HumanInteractionManager(previewWS, page);
+      const result = await manager.waitForHuman({
+        reason: `Command "${commandName}" failed: ${errorMessage}. Fix the issue and confirm via viewer.`,
+        timeout: cfg.timeout,
+        autoDetect: false
+      });
+      return { recovered: result.solved };
+    } catch {
+    }
+  }
+  console.log("");
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log(`\u26A0\uFE0F  COMMAND FAILED: ${commandName}`);
+  console.log(`\u26A0\uFE0F  Error: ${errorMessage}`);
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Recovery mode activated`);
+  if (viewerUrl) {
+    console.log(`\u26A0\uFE0F  Viewer: ${viewerUrl}`);
+  }
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Fix the issue, then press ENTER to retry`);
+  console.log(`\u26A0\uFE0F  Type "abort" + ENTER to cancel`);
+  console.log(`\u26A0\uFE0F  (${cfg.timeout}s timeout)`);
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log("");
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      clearTimeout(timeoutTimer);
+      process.stdin.removeListener("data", onData);
+      process.stdin.pause();
+    };
+    const timeoutTimer = setTimeout(() => {
+      console.log("\u23F0 Recovery timeout \u2014 aborting");
+      cleanup();
+      resolve({ recovered: false });
+    }, cfg.timeout * 1e3);
+    const onData = (buf) => {
+      const line = buf.toString().trim().toLowerCase();
+      cleanup();
+      resolve({ recovered: line !== "abort" && line !== "q" && line !== "exit" });
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+export {
+  attemptRecovery,
+  getRecoveryConfig
+};

package/dist/recovery-ZJVVHP7N.js

@@ -0,0 +1,76 @@
+import {
+  buildViewerUrl
+} from "./chunk-3OD76SUE.js";
+import {
+  HumanInteractionManager
+} from "./chunk-DWDXEGVK.js";
+import "./chunk-Q2DFJQGS.js";
+import "./chunk-KFQGP6VL.js";
+
+// src/recovery.ts
+function getRecoveryConfig() {
+  const val = process.env.XBROWSER_RECOVERY?.toLowerCase();
+  return {
+    enabled: val === "true" || val === "1" || val === "yes",
+    timeout: Math.max(10, parseInt(process.env.XBROWSER_RECOVERY_TIMEOUT || "120", 10))
+  };
+}
+async function attemptRecovery(page, sessionName, commandName, errorMessage, previewWS) {
+  const cfg = getRecoveryConfig();
+  if (!cfg.enabled) return { recovered: false };
+  if (!page) {
+    return { recovered: false };
+  }
+  const viewerUrl = buildViewerUrl(sessionName);
+  if (previewWS) {
+    try {
+      previewWS.registerSession(sessionName, page);
+      const manager = new HumanInteractionManager(previewWS, page);
+      const result = await manager.waitForHuman({
+        reason: `Command "${commandName}" failed: ${errorMessage}. Fix the issue and confirm via viewer.`,
+        timeout: cfg.timeout,
+        autoDetect: false
+      });
+      return { recovered: result.solved };
+    } catch {
+    }
+  }
+  console.log("");
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log(`\u26A0\uFE0F  COMMAND FAILED: ${commandName}`);
+  console.log(`\u26A0\uFE0F  Error: ${errorMessage}`);
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Recovery mode activated`);
+  if (viewerUrl) {
+    console.log(`\u26A0\uFE0F  Viewer: ${viewerUrl}`);
+  }
+  console.log(`\u26A0\uFE0F  `);
+  console.log(`\u26A0\uFE0F  Fix the issue, then press ENTER to retry`);
+  console.log(`\u26A0\uFE0F  Type "abort" + ENTER to cancel`);
+  console.log(`\u26A0\uFE0F  (${cfg.timeout}s timeout)`);
+  console.log("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log("");
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      clearTimeout(timeoutTimer);
+      process.stdin.removeListener("data", onData);
+      process.stdin.pause();
+    };
+    const timeoutTimer = setTimeout(() => {
+      console.log("\u23F0 Recovery timeout \u2014 aborting");
+      cleanup();
+      resolve({ recovered: false });
+    }, cfg.timeout * 1e3);
+    const onData = (buf) => {
+      const line = buf.toString().trim().toLowerCase();
+      cleanup();
+      resolve({ recovered: line !== "abort" && line !== "q" && line !== "exit" });
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+export {
+  attemptRecovery,
+  getRecoveryConfig
+};

package/dist/{session-recorder-7GXI42FO.js → session-recorder-H3KEYU26.js}

@@ -1,6 +1,6 @@
 import {
   SessionRecorder
-} from "./chunk-C4O73DQL.js";
+} from "./chunk-5UGR6MUK.js";
 import "./chunk-KFQGP6VL.js";
 export {
   SessionRecorder

package/dist/{session-recorder-RFOPX4SF.js → session-recorder-QRZMKFVL.js}

@@ -1,6 +1,6 @@
 import {
   SessionRecorder
-} from "./chunk-CH5ZQV64.js";
+} from "./chunk-4452SPFI.js";
 import "./chunk-OZKD3W4X.js";
 import "./chunk-KFQGP6VL.js";
 export {