opensteer 0.4.5 → 0.4.7

package/dist/index.cjs

@@ -338,6 +338,8 @@ var init_extractor = __esm({
 var index_exports = {};
 __export(index_exports, {
   ActionWsClient: () => ActionWsClient,
+  CloudCdpClient: () => CloudCdpClient,
+  CloudSessionClient: () => CloudSessionClient,
   CounterResolutionError: () => CounterResolutionError,
   ElementPathError: () => ElementPathError,
   LocalSelectorStorage: () => LocalSelectorStorage,
@@ -351,9 +353,7 @@ __export(index_exports, {
   OS_UNAVAILABLE_ATTR: () => OS_UNAVAILABLE_ATTR,
   Opensteer: () => Opensteer,
   OpensteerActionError: () => OpensteerActionError,
-  OpensteerRemoteError: () => OpensteerRemoteError,
-  RemoteCdpClient: () => RemoteCdpClient,
-  RemoteSessionClient: () => RemoteSessionClient,
+  OpensteerCloudError: () => OpensteerCloudError,
   buildElementPathFromHandle: () => buildElementPathFromHandle,
   buildElementPathFromSelector: () => buildElementPathFromSelector,
   buildPathSelectorHint: () => buildPathSelectorHint,
@@ -365,6 +365,9 @@ __export(index_exports, {
   clearCookies: () => clearCookies,
   cloneElementPath: () => cloneElementPath,
   closeTab: () => closeTab,
+  cloudNotLaunchedError: () => cloudNotLaunchedError,
+  cloudSessionContractVersion: () => cloudSessionContractVersion,
+  cloudUnsupportedMethodError: () => cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries: () => collectLocalSelectorCacheEntries,
   countArrayItemsWithPath: () => countArrayItemsWithPath,
   createEmptyRegistry: () => createEmptyRegistry,
@@ -396,8 +399,6 @@ __export(index_exports, {
   performSelect: () => performSelect,
   prepareSnapshot: () => prepareSnapshot,
   pressKey: () => pressKey,
-  remoteNotLaunchedError: () => remoteNotLaunchedError,
-  remoteUnsupportedMethodError: () => remoteUnsupportedMethodError,
   resolveCounterElement: () => resolveCounterElement,
   resolveCountersBatch: () => resolveCountersBatch,
   resolveElementPath: () => resolveElementPath,
@@ -826,7 +827,7 @@ var BrowserPool = class {
       const context = contexts[0];
       const pages = context.pages();
       const page = pages.length > 0 ? pages[0] : await context.newPage();
-      return { browser, context, page, isRemote: true };
+      return { browser, context, page, isExternal: true };
     } catch (error) {
       if (browser) {
         await browser.close().catch(() => void 0);
@@ -861,7 +862,7 @@ var BrowserPool = class {
       context = await browser.newContext(options.context || {});
       page = await context.newPage();
     }
-    return { browser, context, page, isRemote: false };
+    return { browser, context, page, isExternal: false };
   }
   async launchSandbox(options) {
     const browser = await import_playwright.chromium.launch({
@@ -872,7 +873,7 @@ var BrowserPool = class {
     const context = await browser.newContext(options.context || {});
     const page = await context.newPage();
     this.browser = browser;
-    return { browser, context, page, isRemote: false };
+    return { browser, context, page, isExternal: false };
   }
 };
 
@@ -943,28 +944,27 @@ function assertNoLegacyAiConfig(source, config) {
     );
   }
 }
-function assertNoLegacyModeConfig(source, config) {
+function assertNoLegacyRuntimeConfig(source, config) {
   if (!config || typeof config !== "object") return;
   const configRecord = config;
   if (hasOwn(configRecord, "runtime")) {
     throw new Error(
-      `Legacy "runtime" config is no longer supported in ${source}. Use top-level "mode" instead.`
+      `Legacy "runtime" config is no longer supported in ${source}. Use top-level "cloud" instead.`
     );
   }
-  if (hasOwn(configRecord, "apiKey")) {
+  if (hasOwn(configRecord, "mode")) {
     throw new Error(
-      `Top-level "apiKey" config is not supported in ${source}. Use "remote.apiKey" instead.`
+      `Top-level "mode" config is no longer supported in ${source}. Use "cloud: true" to enable cloud mode.`
     );
   }
-  const remoteValue = configRecord.remote;
-  if (typeof remoteValue === "boolean") {
+  if (hasOwn(configRecord, "remote")) {
     throw new Error(
-      `Boolean "remote" config is no longer supported in ${source}. Use "mode: \\"remote\\"" with "remote" options.`
+      `Top-level "remote" config is no longer supported in ${source}. Use "cloud" options instead.`
     );
   }
-  if (remoteValue && typeof remoteValue === "object" && !Array.isArray(remoteValue) && hasOwn(remoteValue, "key")) {
+  if (hasOwn(configRecord, "apiKey")) {
     throw new Error(
-      `Legacy "remote.key" config is no longer supported in ${source}. Use "remote.apiKey" instead.`
+      `Top-level "apiKey" config is not supported in ${source}. Use "cloud.apiKey" instead.`
     );
   }
 }
@@ -1010,20 +1010,52 @@ function parseNumber(value) {
   if (!Number.isFinite(parsed)) return void 0;
   return parsed;
 }
-function parseMode(value, source) {
+function parseRuntimeMode(value, source) {
   if (value == null) return void 0;
   if (typeof value !== "string") {
     throw new Error(
-      `Invalid ${source} value "${String(value)}". Use "local" or "remote".`
+      `Invalid ${source} value "${String(value)}". Use "local" or "cloud".`
     );
   }
   const normalized = value.trim().toLowerCase();
   if (!normalized) return void 0;
-  if (normalized === "local" || normalized === "remote") {
+  if (normalized === "local" || normalized === "cloud") {
     return normalized;
   }
   throw new Error(
-    `Invalid ${source} value "${value}". Use "local" or "remote".`
+    `Invalid ${source} value "${value}". Use "local" or "cloud".`
+  );
+}
+function parseAuthScheme(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "api-key" or "bearer".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "api-key" || normalized === "bearer") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "api-key" or "bearer".`
+  );
+}
+function parseCloudAnnounce(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "always", "off", or "tty".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "always" || normalized === "off" || normalized === "tty") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
   );
 }
 function resolveOpensteerApiKey() {
@@ -1031,29 +1063,46 @@ function resolveOpensteerApiKey() {
   if (!value) return void 0;
   return value;
 }
-function normalizeRemoteOptions(value) {
+function resolveOpensteerAuthScheme() {
+  return parseAuthScheme(
+    process.env.OPENSTEER_AUTH_SCHEME,
+    "OPENSTEER_AUTH_SCHEME"
+  );
+}
+function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
   return value;
 }
-function resolveModeSelection(config) {
-  const configMode = parseMode(config.mode, "mode");
-  if (configMode) {
+function parseCloudEnabled(value, source) {
+  if (value == null) return void 0;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "object" && !Array.isArray(value)) return true;
+  throw new Error(
+    `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
+  );
+}
+function resolveCloudSelection(config) {
+  const configCloud = parseCloudEnabled(config.cloud, "cloud");
+  if (configCloud !== void 0) {
     return {
-      mode: configMode,
-      source: "config.mode"
+      cloud: configCloud,
+      source: "config.cloud"
     };
   }
-  const envMode = parseMode(process.env.OPENSTEER_MODE, "OPENSTEER_MODE");
+  const envMode = parseRuntimeMode(
+    process.env.OPENSTEER_MODE,
+    "OPENSTEER_MODE"
+  );
   if (envMode) {
     return {
-      mode: envMode,
+      cloud: envMode === "cloud",
       source: "env.OPENSTEER_MODE"
     };
   }
   return {
-    mode: "local",
+    cloud: false,
     source: "default"
   };
 }
@@ -1069,11 +1118,11 @@ function resolveConfig(input = {}) {
     );
   }
   assertNoLegacyAiConfig("Opensteer constructor config", input);
-  assertNoLegacyModeConfig("Opensteer constructor config", input);
+  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
   const rootDir = input.storage?.rootDir ?? DEFAULT_CONFIG.storage.rootDir ?? process.cwd();
   const fileConfig = loadConfigFile(rootDir);
   assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
-  assertNoLegacyModeConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const envConfig = {
     browser: {
       headless: parseBool(process.env.OPENSTEER_HEADLESS),
@@ -1090,20 +1139,39 @@ function resolveConfig(input = {}) {
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey();
-  const inputRemoteOptions = normalizeRemoteOptions(input.remote);
-  const inputHasRemoteApiKey = Boolean(
-    inputRemoteOptions && Object.prototype.hasOwnProperty.call(inputRemoteOptions, "apiKey")
+  const envAuthScheme = resolveOpensteerAuthScheme();
+  const envCloudAnnounce = parseCloudAnnounce(
+    process.env.OPENSTEER_REMOTE_ANNOUNCE,
+    "OPENSTEER_REMOTE_ANNOUNCE"
+  );
+  const inputCloudOptions = normalizeCloudOptions(input.cloud);
+  const inputAuthScheme = parseAuthScheme(
+    inputCloudOptions?.authScheme,
+    "cloud.authScheme"
+  );
+  const inputCloudAnnounce = parseCloudAnnounce(
+    inputCloudOptions?.announce,
+    "cloud.announce"
+  );
+  const inputHasCloudApiKey = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
-  const modeSelection = resolveModeSelection({
-    mode: resolved.mode
+  const cloudSelection = resolveCloudSelection({
+    cloud: resolved.cloud
   });
-  if (modeSelection.mode === "remote") {
-    const resolvedRemote = normalizeRemoteOptions(resolved.remote);
-    resolved.remote = resolvedRemote ?? {};
+  if (cloudSelection.cloud) {
+    const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
+    const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
+    const announce = inputCloudAnnounce ?? envCloudAnnounce ?? parseCloudAnnounce(resolvedCloud.announce, "cloud.announce") ?? "always";
+    resolved.cloud = {
+      ...resolvedCloud,
+      authScheme,
+      announce
+    };
   }
-  if (envApiKey && modeSelection.mode === "remote" && !inputHasRemoteApiKey) {
-    resolved.remote = {
-      ...normalizeRemoteOptions(resolved.remote) ?? {},
+  if (envApiKey && cloudSelection.cloud && !inputHasCloudApiKey) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
       apiKey: envApiKey
     };
   }
@@ -1146,15 +1214,52 @@ function getCallerFilePath() {
 // src/navigation.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_SETTLE_MS = 750;
+var FRAME_EVALUATE_GRACE_MS = 200;
+var STEALTH_WORLD_NAME = "__opensteer_wait__";
+var StealthWaitUnavailableError = class extends Error {
+  constructor(cause) {
+    super("Stealth visual wait requires Chromium CDP support.", { cause });
+    this.name = "StealthWaitUnavailableError";
+  }
+};
+function isStealthWaitUnavailableError(error) {
+  return error instanceof StealthWaitUnavailableError;
+}
+var FRAME_OWNER_VISIBILITY_FUNCTION = `function() {
+    if (!(this instanceof HTMLElement)) return false;
+
+    var rect = this.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return false;
+    if (
+        rect.bottom <= 0 ||
+        rect.right <= 0 ||
+        rect.top >= window.innerHeight ||
+        rect.left >= window.innerWidth
+    ) {
+        return false;
+    }
+
+    var style = window.getComputedStyle(this);
+    if (
+        style.display === 'none' ||
+        style.visibility === 'hidden' ||
+        Number(style.opacity) === 0
+    ) {
+        return false;
+    }
+
+    return true;
+}`;
 function buildStabilityScript(timeout, settleMs) {
   return `new Promise(function(resolve) {
     var deadline = Date.now() + ${timeout};
-    var timer = null;
     var resolved = false;
+    var timer = null;
     var observers = [];
     var observedShadowRoots = [];
     var fonts = document.fonts;
     var fontsReady = !fonts || fonts.status === 'loaded';
+    var lastRelevantMutationAt = Date.now();
 
     function clearObservers() {
         for (var i = 0; i < observers.length; i++) {
@@ -1172,9 +1277,87 @@ function buildStabilityScript(timeout, settleMs) {
         resolve();
     }
 
+    function isElementVisiblyIntersectingViewport(element) {
+        if (!(element instanceof Element)) return false;
+
+        var rect = element.getBoundingClientRect();
+        var inViewport =
+            rect.width > 0 &&
+            rect.height > 0 &&
+            rect.bottom > 0 &&
+            rect.right > 0 &&
+            rect.top < window.innerHeight &&
+            rect.left < window.innerWidth;
+
+        if (!inViewport) return false;
+
+        var style = window.getComputedStyle(element);
+        if (style.visibility === 'hidden' || style.display === 'none') {
+            return false;
+        }
+        if (Number(style.opacity) === 0) {
+            return false;
+        }
+
+        return true;
+    }
+
+    function resolveRelevantElement(node) {
+        if (!node) return null;
+        if (node instanceof Element) return node;
+        if (typeof ShadowRoot !== 'undefined' && node instanceof ShadowRoot) {
+            return node.host instanceof Element ? node.host : null;
+        }
+        var parentElement = node.parentElement;
+        return parentElement instanceof Element ? parentElement : null;
+    }
+
+    function isNodeVisiblyRelevant(node) {
+        var element = resolveRelevantElement(node);
+        if (!element) return false;
+        return isElementVisiblyIntersectingViewport(element);
+    }
+
+    function hasRelevantMutation(records) {
+        for (var i = 0; i < records.length; i++) {
+            var record = records[i];
+            if (isNodeVisiblyRelevant(record.target)) return true;
+
+            var addedNodes = record.addedNodes;
+            for (var j = 0; j < addedNodes.length; j++) {
+                if (isNodeVisiblyRelevant(addedNodes[j])) return true;
+            }
+
+            var removedNodes = record.removedNodes;
+            for (var k = 0; k < removedNodes.length; k++) {
+                if (isNodeVisiblyRelevant(removedNodes[k])) return true;
+            }
+        }
+
+        return false;
+    }
+
+    function scheduleCheck() {
+        if (resolved) return;
+        if (timer) clearTimeout(timer);
+
+        var remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            done();
+            return;
+        }
+
+        var checkDelay = Math.min(120, Math.max(16, ${settleMs}));
+        timer = setTimeout(checkNow, checkDelay);
+    }
+
     function observeMutations(target) {
         if (!target) return;
-        var observer = new MutationObserver(function() { settle(); });
+        var observer = new MutationObserver(function(records) {
+            if (!hasRelevantMutation(records)) return;
+            lastRelevantMutationAt = Date.now();
+            scheduleCheck();
+        });
         observer.observe(target, {
             childList: true,
             subtree: true,
@@ -1212,18 +1395,25 @@ function buildStabilityScript(timeout, settleMs) {
         var images = root.querySelectorAll('img');
         for (var i = 0; i < images.length; i++) {
             var img = images[i];
-            var rect = img.getBoundingClientRect();
-            var inViewport =
-                rect.bottom > 0 &&
-                rect.right > 0 &&
-                rect.top < window.innerHeight &&
-                rect.left < window.innerWidth;
-            if (inViewport && !img.complete) return false;
+            if (!isElementVisiblyIntersectingViewport(img)) continue;
+            if (!img.complete) return false;
         }
         return true;
     }
 
-    function hasRunningFiniteAnimations() {
+    function getAnimationTarget(effect) {
+        if (!effect) return null;
+        var target = effect.target;
+        if (target instanceof Element) return target;
+
+        if (target && target.element instanceof Element) {
+            return target.element;
+        }
+
+        return null;
+    }
+
+    function hasRunningVisibleFiniteAnimations() {
         if (typeof document.getAnimations !== 'function') return false;
         var animations = document.getAnimations();
 
@@ -1237,6 +1427,9 @@ function buildStabilityScript(timeout, settleMs) {
                 ? timing.endTime
                 : Number.POSITIVE_INFINITY;
             if (Number.isFinite(endTime) && endTime > 0) {
+                var target = getAnimationTarget(effect);
+                if (!target) continue;
+                if (!isElementVisiblyIntersectingViewport(target)) continue;
                 return true;
             }
         }
@@ -1247,21 +1440,29 @@ function buildStabilityScript(timeout, settleMs) {
     function isVisuallyReady() {
         if (!fontsReady) return false;
         if (!checkViewportImages(document)) return false;
-        if (hasRunningFiniteAnimations()) return false;
+        if (hasRunningVisibleFiniteAnimations()) return false;
         return true;
     }
 
-    function settle() {
-        if (Date.now() > deadline) { done(); return; }
-        if (timer) clearTimeout(timer);
+    function checkNow() {
+        if (Date.now() >= deadline) {
+            done();
+            return;
+        }
+
         observeOpenShadowRoots();
-        timer = setTimeout(function() {
-            if (isVisuallyReady()) {
-                done();
-            } else {
-                settle();
-            }
-        }, ${settleMs});
+
+        if (!isVisuallyReady()) {
+            scheduleCheck();
+            return;
+        }
+
+        if (Date.now() - lastRelevantMutationAt >= ${settleMs}) {
+            done();
+            return;
+        }
+
+        scheduleCheck();
     }
 
     observeMutations(document.documentElement);
@@ -1270,67 +1471,266 @@ function buildStabilityScript(timeout, settleMs) {
     if (fonts && fonts.ready && typeof fonts.ready.then === 'function') {
         fonts.ready.then(function() {
             fontsReady = true;
-            settle();
+            scheduleCheck();
+        }, function() {
+            fontsReady = true;
+            scheduleCheck();
         });
     }
 
     var safetyTimer = setTimeout(done, ${timeout});
 
-    settle();
+    scheduleCheck();
 })`;
 }
+var StealthCdpRuntime = class _StealthCdpRuntime {
+  constructor(session) {
+    this.session = session;
+  }
+  contextsByFrame = /* @__PURE__ */ new Map();
+  disposed = false;
+  static async create(page) {
+    let session;
+    try {
+      session = await page.context().newCDPSession(page);
+    } catch (error) {
+      throw new StealthWaitUnavailableError(error);
+    }
+    const runtime = new _StealthCdpRuntime(session);
+    try {
+      await runtime.initialize();
+      return runtime;
+    } catch (error) {
+      await runtime.dispose();
+      throw new StealthWaitUnavailableError(error);
+    }
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.contextsByFrame.clear();
+    await this.session.detach().catch(() => void 0);
+  }
+  async waitForMainFrameVisualStability(options) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+    if (timeout <= 0) return;
+    const frameRecords = await this.getFrameRecords();
+    const mainFrame = frameRecords[0];
+    if (!mainFrame) return;
+    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs);
+  }
+  async collectVisibleFrameIds() {
+    const frameRecords = await this.getFrameRecords();
+    if (frameRecords.length === 0) return [];
+    const visibleFrameIds = [];
+    for (const frameRecord of frameRecords) {
+      if (!frameRecord.parentFrameId) {
+        visibleFrameIds.push(frameRecord.frameId);
+        continue;
+      }
+      try {
+        const parentContextId = await this.ensureFrameContextId(
+          frameRecord.parentFrameId
+        );
+        const visible = await this.isFrameOwnerVisible(
+          frameRecord.frameId,
+          parentContextId
+        );
+        if (visible) {
+          visibleFrameIds.push(frameRecord.frameId);
+        }
+      } catch (error) {
+        if (isIgnorableFrameError(error)) continue;
+        throw error;
+      }
+    }
+    return visibleFrameIds;
+  }
+  async waitForFrameVisualStability(frameId, timeout, settleMs) {
+    if (timeout <= 0) return;
+    const script = buildStabilityScript(timeout, settleMs);
+    let contextId = await this.ensureFrameContextId(frameId);
+    try {
+      await this.evaluateWithGuard(contextId, script, timeout);
+    } catch (error) {
+      if (!isMissingExecutionContextError(error)) {
+        throw error;
+      }
+      this.contextsByFrame.delete(frameId);
+      contextId = await this.ensureFrameContextId(frameId);
+      await this.evaluateWithGuard(contextId, script, timeout);
+    }
+  }
+  async initialize() {
+    await this.session.send("Page.enable");
+    await this.session.send("Runtime.enable");
+    await this.session.send("DOM.enable");
+  }
+  async getFrameRecords() {
+    const treeResult = await this.session.send("Page.getFrameTree");
+    const records = [];
+    walkFrameTree(treeResult.frameTree, null, records);
+    return records;
+  }
+  async ensureFrameContextId(frameId) {
+    const cached = this.contextsByFrame.get(frameId);
+    if (cached != null) {
+      return cached;
+    }
+    const world = await this.session.send("Page.createIsolatedWorld", {
+      frameId,
+      worldName: STEALTH_WORLD_NAME
+    });
+    this.contextsByFrame.set(frameId, world.executionContextId);
+    return world.executionContextId;
+  }
+  async evaluateWithGuard(contextId, script, timeout) {
+    const evaluationPromise = this.evaluateScript(contextId, script);
+    const settledPromise = evaluationPromise.then(
+      () => ({ kind: "resolved" }),
+      (error) => ({ kind: "rejected", error })
+    );
+    const timeoutPromise = sleep(
+      timeout + FRAME_EVALUATE_GRACE_MS
+    ).then(() => ({ kind: "timeout" }));
+    const result = await Promise.race([
+      settledPromise,
+      timeoutPromise
+    ]);
+    if (result.kind === "rejected") {
+      throw result.error;
+    }
+  }
+  async evaluateScript(contextId, expression) {
+    const result = await this.session.send("Runtime.evaluate", {
+      contextId,
+      expression,
+      awaitPromise: true,
+      returnByValue: true
+    });
+    if (result.exceptionDetails) {
+      throw new Error(formatCdpException(result.exceptionDetails));
+    }
+  }
+  async isFrameOwnerVisible(frameId, parentContextId) {
+    const owner = await this.session.send("DOM.getFrameOwner", {
+      frameId
+    });
+    const resolveParams = {
+      executionContextId: parentContextId
+    };
+    if (typeof owner.backendNodeId === "number") {
+      resolveParams.backendNodeId = owner.backendNodeId;
+    } else if (typeof owner.nodeId === "number") {
+      resolveParams.nodeId = owner.nodeId;
+    } else {
+      return false;
+    }
+    const resolved = await this.session.send(
+      "DOM.resolveNode",
+      resolveParams
+    );
+    const objectId = resolved.object?.objectId;
+    if (!objectId) return false;
+    try {
+      const callResult = await this.session.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: FRAME_OWNER_VISIBILITY_FUNCTION,
+        returnByValue: true
+      });
+      if (callResult.exceptionDetails) {
+        throw new Error(formatCdpException(callResult.exceptionDetails));
+      }
+      return callResult.result.value === true;
+    } finally {
+      await this.releaseObject(objectId);
+    }
+  }
+  async releaseObject(objectId) {
+    await this.session.send("Runtime.releaseObject", {
+      objectId
+    }).catch(() => void 0);
+  }
+};
 async function waitForVisualStability(page, options = {}) {
-  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
-  const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
-  await waitForFrameVisualStability(page.mainFrame(), {
-    timeout,
-    settleMs
-  });
+  const runtime = await StealthCdpRuntime.create(page);
+  try {
+    await runtime.waitForMainFrameVisualStability(options);
+  } finally {
+    await runtime.dispose();
+  }
 }
 async function waitForVisualStabilityAcrossFrames(page, options = {}) {
   const timeout = options.timeout ?? DEFAULT_TIMEOUT;
   const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+  if (timeout <= 0) return;
   const deadline = Date.now() + timeout;
-  while (true) {
-    const remaining = Math.max(0, deadline - Date.now());
-    if (remaining === 0) return;
-    const frames = page.frames();
-    await Promise.all(
-      frames.map(async (frame) => {
-        try {
-          await waitForFrameVisualStability(frame, {
-            timeout: remaining,
-            settleMs
-          });
-        } catch (error) {
-          if (isIgnorableFrameError(error)) return;
-          throw error;
-        }
-      })
-    );
-    const currentFrames = page.frames();
-    if (sameFrames(frames, currentFrames)) {
-      return;
+  const runtime = await StealthCdpRuntime.create(page);
+  try {
+    while (true) {
+      const remaining = Math.max(0, deadline - Date.now());
+      if (remaining === 0) return;
+      const frameIds = await runtime.collectVisibleFrameIds();
+      if (frameIds.length === 0) return;
+      await Promise.all(
+        frameIds.map(async (frameId) => {
+          try {
+            await runtime.waitForFrameVisualStability(
+              frameId,
+              remaining,
+              settleMs
+            );
+          } catch (error) {
+            if (isIgnorableFrameError(error)) return;
+            throw error;
+          }
+        })
+      );
+      const currentFrameIds = await runtime.collectVisibleFrameIds();
+      if (sameFrameIds(frameIds, currentFrameIds)) {
+        return;
+      }
     }
+  } finally {
+    await runtime.dispose();
   }
 }
-async function waitForFrameVisualStability(frame, options) {
-  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
-  const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
-  if (timeout <= 0) return;
-  await frame.evaluate(buildStabilityScript(timeout, settleMs));
+function walkFrameTree(node, parentFrameId, records) {
+  const frameId = node.frame?.id;
+  if (!frameId) return;
+  records.push({
+    frameId,
+    parentFrameId
+  });
+  for (const child of node.childFrames ?? []) {
+    walkFrameTree(child, frameId, records);
+  }
 }
-function sameFrames(before, after) {
+function sameFrameIds(before, after) {
   if (before.length !== after.length) return false;
-  for (const frame of before) {
-    if (!after.includes(frame)) return false;
+  for (const frameId of before) {
+    if (!after.includes(frameId)) return false;
   }
   return true;
 }
+function formatCdpException(details) {
+  return details.exception?.description || details.text || "CDP runtime evaluation failed.";
+}
+function isMissingExecutionContextError(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
+}
 function isIgnorableFrameError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
-  return message.includes("Frame was detached") || message.includes("Execution context was destroyed") || message.includes("Target page, context or browser has been closed");
+  return message.includes("Frame was detached") || message.includes("Execution context was destroyed") || message.includes("Target page, context or browser has been closed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context") || message.includes("No frame for given id found");
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
 // src/storage/local.ts
@@ -2231,6 +2631,66 @@ var OS_BOUNDARY_ATTR = "data-os-boundary";
 var OS_UNAVAILABLE_ATTR = "data-os-unavailable";
 var OS_IFRAME_BOUNDARY_TAG = "os-iframe-root";
 var OS_SHADOW_BOUNDARY_TAG = "os-shadow-root";
+function decodeSerializedNodeTableEntry(nodeTable, rawIndex, label) {
+  if (typeof rawIndex !== "number" || !Number.isInteger(rawIndex) || rawIndex < 0 || rawIndex >= nodeTable.length) {
+    throw new Error(
+      `Invalid serialized path node index at "${label}": expected a valid table index.`
+    );
+  }
+  const node = nodeTable[rawIndex];
+  if (!node || typeof node !== "object") {
+    throw new Error(
+      `Invalid serialized path node at "${label}": table entry is missing.`
+    );
+  }
+  return node;
+}
+function decodeSerializedDomPath(nodeTable, rawPath, label) {
+  if (!Array.isArray(rawPath)) {
+    throw new Error(
+      `Invalid serialized path at "${label}": expected an array of node indexes.`
+    );
+  }
+  return rawPath.map(
+    (value, index) => decodeSerializedNodeTableEntry(nodeTable, value, `${label}[${index}]`)
+  );
+}
+function decodeSerializedElementPath(nodeTable, rawPath, label) {
+  if (!rawPath || typeof rawPath !== "object") {
+    throw new Error(
+      `Invalid serialized element path at "${label}": expected an object.`
+    );
+  }
+  if (rawPath.context !== void 0 && !Array.isArray(rawPath.context)) {
+    throw new Error(
+      `Invalid serialized context at "${label}.context": expected an array.`
+    );
+  }
+  const contextRaw = Array.isArray(rawPath.context) ? rawPath.context : [];
+  const context = contextRaw.map((hop, hopIndex) => {
+    if (!hop || typeof hop !== "object" || hop.kind !== "shadow") {
+      throw new Error(
+        `Invalid serialized context hop at "${label}.context[${hopIndex}]": expected a shadow hop.`
+      );
+    }
+    return {
+      kind: "shadow",
+      host: decodeSerializedDomPath(
+        nodeTable,
+        hop.host,
+        `${label}.context[${hopIndex}].host`
+      )
+    };
+  });
+  return {
+    context,
+    nodes: decodeSerializedDomPath(
+      nodeTable,
+      rawPath.nodes,
+      `${label}.nodes`
+    )
+  };
+}
 async function serializePageHTML(page, _options = {}) {
   return serializeFrameRecursive(page.mainFrame(), [], "f0");
 }
@@ -2287,6 +2747,8 @@ async function serializeFrameRecursive(frame, baseContext, frameKey) {
         (Array.isArray(deferredMatchAttrKeys) ? deferredMatchAttrKeys : []).map((key) => String(key))
       );
       let counter = 1;
+      const nodeTable = [];
+      const nodeTableIndexByKey = /* @__PURE__ */ new Map();
       const entries = [];
       const helpers = {
         nextToken() {
@@ -2488,6 +2950,47 @@ async function serializeFrameRecursive(frame, baseContext, frameKey) {
             nodes: target
           };
         },
+        buildPathNodeKey(node) {
+          const attrs = Object.entries(node.attrs || {}).sort(
+            ([a], [b]) => a.localeCompare(b)
+          );
+          const match = (node.match || []).map(
+            (clause) => clause.kind === "attr" ? [
+              "attr",
+              clause.key,
+              clause.op || "exact",
+              clause.value ?? null
+            ] : ["position", clause.axis]
+          );
+          return JSON.stringify([
+            node.tag,
+            node.position.nthChild,
+            node.position.nthOfType,
+            attrs,
+            match
+          ]);
+        },
+        internPathNode(node) {
+          const key = helpers.buildPathNodeKey(node);
+          const existing = nodeTableIndexByKey.get(key);
+          if (existing != null) return existing;
+          const index = nodeTable.length;
+          nodeTable.push(node);
+          nodeTableIndexByKey.set(key, index);
+          return index;
+        },
+        packDomPath(path5) {
+          return path5.map((node) => helpers.internPathNode(node));
+        },
+        packElementPath(path5) {
+          return {
+            context: (path5.context || []).map((hop) => ({
+              kind: "shadow",
+              host: helpers.packDomPath(hop.host)
+            })),
+            nodes: helpers.packDomPath(path5.nodes)
+          };
+        },
         ensureNodeId(el) {
           const next = `${frameKey2}_${counter++}`;
           el.setAttribute(nodeAttr, next);
@@ -2517,9 +3020,12 @@ async function serializeFrameRecursive(frame, baseContext, frameKey) {
         serializeElement(el) {
           const nodeId = helpers.ensureNodeId(el);
           const instanceToken = helpers.setInstanceToken(el);
+          const packedPath = helpers.packElementPath(
+            helpers.buildElementPath(el)
+          );
           entries.push({
             nodeId,
-            path: helpers.buildElementPath(el),
+            path: packedPath,
             instanceToken
           });
           const tag = el.tagName.toLowerCase();
@@ -2547,11 +3053,12 @@ async function serializeFrameRecursive(frame, baseContext, frameKey) {
       win[frameTokenKey] = frameToken;
       const root = document.documentElement;
       if (!root) {
-        return { html: "", frameToken, entries };
+        return { html: "", frameToken, nodeTable, entries };
       }
       return {
         html: helpers.serializeElement(root),
         frameToken,
+        nodeTable,
         entries
       };
     },
@@ -2569,13 +3076,18 @@ async function serializeFrameRecursive(frame, baseContext, frameKey) {
   );
   const nodePaths = /* @__PURE__ */ new Map();
   const nodeMeta = /* @__PURE__ */ new Map();
-  for (const entry of frameSnapshot.entries) {
+  for (const [index, entry] of frameSnapshot.entries.entries()) {
+    const path5 = decodeSerializedElementPath(
+      frameSnapshot.nodeTable,
+      entry.path,
+      `entries[${index}].path`
+    );
     nodePaths.set(entry.nodeId, {
       context: [
         ...baseContext,
-        ...entry.path.context || []
+        ...path5.context || []
       ],
-      nodes: entry.path.nodes
+      nodes: path5.nodes
     });
     nodeMeta.set(entry.nodeId, {
       frameToken: frameSnapshot.frameToken,
@@ -4969,7 +5481,7 @@ async function performInput(page, path5, options) {
       await resolved.element.type(options.text);
     }
     if (options.pressEnter) {
-      await resolved.element.press("Enter");
+      await resolved.element.press("Enter", { noWaitAfter: true });
     }
     return {
       ok: true,
@@ -5645,7 +6157,26 @@ var ACTION_WAIT_PROFILES = {
   type: ROBUST_PROFILE
 };
 var NETWORK_POLL_MS = 50;
-var IGNORED_RESOURCE_TYPES = /* @__PURE__ */ new Set(["websocket", "eventsource"]);
+var NETWORK_RELAX_AFTER_MS = 1800;
+var RELAXED_ALLOWED_PENDING = 2;
+var HEAVY_VISUAL_REQUEST_WINDOW_MS = 5e3;
+var TRACKED_RESOURCE_TYPES = /* @__PURE__ */ new Set([
+  "document",
+  "fetch",
+  "xhr",
+  "stylesheet",
+  "image",
+  "font",
+  "media"
+]);
+var HEAVY_RESOURCE_TYPES = /* @__PURE__ */ new Set(["document", "fetch", "xhr"]);
+var HEAVY_VISUAL_RESOURCE_TYPES = /* @__PURE__ */ new Set([
+  "stylesheet",
+  "image",
+  "font",
+  "media"
+]);
+var IGNORED_RESOURCE_TYPES = /* @__PURE__ */ new Set(["websocket", "eventsource", "manifest"]);
 var NOOP_SESSION = {
   async wait() {
   },
@@ -5655,7 +6186,7 @@ var NOOP_SESSION = {
 function createPostActionWaitSession(page, action, override) {
   const profile = resolveActionWaitProfile(action, override);
   if (!profile.enabled) return NOOP_SESSION;
-  const tracker = profile.includeNetwork ? new ScopedNetworkTracker(page) : null;
+  const tracker = profile.includeNetwork ? new AdaptiveNetworkTracker(page) : null;
   tracker?.start();
   let settled = false;
   return {
@@ -5663,19 +6194,32 @@ function createPostActionWaitSession(page, action, override) {
       if (settled) return;
       settled = true;
       const deadline = Date.now() + profile.timeout;
-      const networkWait = tracker ? tracker.waitForQuiet({
-        deadline,
-        quietMs: profile.networkQuietMs
-      }) : Promise.resolve();
+      const visualTimeout = profile.includeNetwork ? Math.min(
+        profile.timeout,
+        resolveNetworkBackedVisualTimeout(profile.settleMs)
+      ) : profile.timeout;
       try {
-        await Promise.all([
-          waitForVisualStabilityAcrossFrames(page, {
-            timeout: profile.timeout,
+        try {
+          await waitForVisualStabilityAcrossFrames(page, {
+            timeout: visualTimeout,
             settleMs: profile.settleMs
-          }),
-          networkWait
-        ]);
-      } catch {
+          });
+        } catch (error) {
+          if (isStealthWaitUnavailableError(error)) {
+            throw error;
+          }
+        } finally {
+          tracker?.freezeCollection();
+        }
+        if (tracker) {
+          try {
+            await tracker.waitForQuiet({
+              deadline,
+              quietMs: profile.networkQuietMs
+            });
+          } catch {
+          }
+        }
       } finally {
         tracker?.stop();
       }
@@ -5715,53 +6259,70 @@ function normalizeMs(value, fallback) {
   }
   return Math.max(0, Math.floor(value));
 }
-var ScopedNetworkTracker = class {
+function resolveNetworkBackedVisualTimeout(settleMs) {
+  const derived = settleMs * 3 + 300;
+  return Math.max(1200, Math.min(2500, derived));
+}
+var AdaptiveNetworkTracker = class {
   constructor(page) {
     this.page = page;
   }
-  pending = /* @__PURE__ */ new Set();
+  pending = /* @__PURE__ */ new Map();
   started = false;
+  collecting = false;
+  startedAt = 0;
   idleSince = Date.now();
   start() {
     if (this.started) return;
     this.started = true;
+    this.collecting = true;
+    this.startedAt = Date.now();
+    this.idleSince = this.startedAt;
     this.page.on("request", this.handleRequestStarted);
     this.page.on("requestfinished", this.handleRequestFinished);
     this.page.on("requestfailed", this.handleRequestFinished);
   }
+  freezeCollection() {
+    if (!this.started) return;
+    this.collecting = false;
+  }
   stop() {
     if (!this.started) return;
     this.started = false;
+    this.collecting = false;
     this.page.off("request", this.handleRequestStarted);
     this.page.off("requestfinished", this.handleRequestFinished);
     this.page.off("requestfailed", this.handleRequestFinished);
     this.pending.clear();
+    this.startedAt = 0;
     this.idleSince = Date.now();
   }
   async waitForQuiet(options) {
     const quietMs = Math.max(0, options.quietMs);
     if (quietMs === 0) return;
     while (Date.now() < options.deadline) {
-      if (this.pending.size === 0) {
+      const now = Date.now();
+      const allowedPending = this.resolveAllowedPending(now);
+      if (this.pending.size <= allowedPending) {
         if (this.idleSince === 0) {
-          this.idleSince = Date.now();
+          this.idleSince = now;
         }
-        const idleFor = Date.now() - this.idleSince;
+        const idleFor = now - this.idleSince;
         if (idleFor >= quietMs) {
           return;
         }
       } else {
         this.idleSince = 0;
       }
-      const remaining = Math.max(1, options.deadline - Date.now());
-      await sleep(Math.min(NETWORK_POLL_MS, remaining));
+      const remaining = Math.max(1, options.deadline - now);
+      await sleep2(Math.min(NETWORK_POLL_MS, remaining));
     }
   }
   handleRequestStarted = (request) => {
-    if (!this.started) return;
-    const resourceType = request.resourceType();
-    if (IGNORED_RESOURCE_TYPES.has(resourceType)) return;
-    this.pending.add(request);
+    if (!this.started || !this.collecting) return;
+    const trackedRequest = this.classifyRequest(request);
+    if (!trackedRequest) return;
+    this.pending.set(request, trackedRequest);
     this.idleSince = 0;
   };
   handleRequestFinished = (request) => {
@@ -5771,8 +6332,35 @@ var ScopedNetworkTracker = class {
       this.idleSince = Date.now();
     }
   };
+  classifyRequest(request) {
+    const resourceType = request.resourceType().toLowerCase();
+    if (IGNORED_RESOURCE_TYPES.has(resourceType)) return null;
+    if (!TRACKED_RESOURCE_TYPES.has(resourceType)) return null;
+    const frame = request.frame();
+    if (!frame || frame !== this.page.mainFrame()) return null;
+    return {
+      resourceType,
+      startedAt: Date.now()
+    };
+  }
+  resolveAllowedPending(now) {
+    const relaxed = now - this.startedAt >= NETWORK_RELAX_AFTER_MS ? RELAXED_ALLOWED_PENDING : 0;
+    if (this.hasHeavyPending(now)) return 0;
+    return relaxed;
+  }
+  hasHeavyPending(now) {
+    for (const trackedRequest of this.pending.values()) {
+      if (HEAVY_RESOURCE_TYPES.has(trackedRequest.resourceType)) {
+        return true;
+      }
+      if (HEAVY_VISUAL_RESOURCE_TYPES.has(trackedRequest.resourceType) && now - trackedRequest.startedAt < HEAVY_VISUAL_REQUEST_WINDOW_MS) {
+        return true;
+      }
+    }
+    return false;
+  }
 };
-async function sleep(ms) {
+async function sleep2(ms) {
   await new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
@@ -6890,36 +7478,39 @@ function clonePersistedExtractNode(node) {
   return JSON.parse(JSON.stringify(node));
 }
 
-// src/remote/action-ws-client.ts
+// src/cloud/contracts.ts
+var cloudSessionContractVersion = "v3";
+
+// src/cloud/action-ws-client.ts
 var import_ws2 = __toESM(require("ws"), 1);
 
-// src/remote/errors.ts
-var OpensteerRemoteError = class extends Error {
+// src/cloud/errors.ts
+var OpensteerCloudError = class extends Error {
   code;
   status;
   details;
   constructor(code, message, status, details) {
     super(message);
-    this.name = "OpensteerRemoteError";
+    this.name = "OpensteerCloudError";
     this.code = code;
     this.status = status;
     this.details = details;
   }
 };
-function remoteUnsupportedMethodError(method, message) {
-  return new OpensteerRemoteError(
-    "REMOTE_UNSUPPORTED_METHOD",
-    message || `${method} is not supported in remote mode.`
+function cloudUnsupportedMethodError(method, message) {
+  return new OpensteerCloudError(
+    "CLOUD_UNSUPPORTED_METHOD",
+    message || `${method} is not supported in cloud mode.`
   );
 }
-function remoteNotLaunchedError() {
-  return new OpensteerRemoteError(
-    "REMOTE_SESSION_NOT_FOUND",
-    "Remote session is not connected. Call launch() first."
+function cloudNotLaunchedError() {
+  return new OpensteerCloudError(
+    "CLOUD_SESSION_NOT_FOUND",
+    "Cloud session is not connected. Call launch() first."
   );
 }
 
-// src/remote/action-ws-client.ts
+// src/cloud/action-ws-client.ts
 var ActionWsClient = class _ActionWsClient {
   ws;
   sessionId;
@@ -6936,18 +7527,18 @@ var ActionWsClient = class _ActionWsClient {
     });
     ws.on("error", (error) => {
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_TRANSPORT_ERROR",
-          `Remote action websocket error: ${error.message}`
+        new OpensteerCloudError(
+          "CLOUD_TRANSPORT_ERROR",
+          `Cloud action websocket error: ${error.message}`
         )
       );
     });
     ws.on("close", () => {
       this.closed = true;
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_SESSION_CLOSED",
-          "Remote action websocket closed."
+        new OpensteerCloudError(
+          "CLOUD_SESSION_CLOSED",
+          "Cloud action websocket closed."
         )
       );
     });
@@ -6959,8 +7550,8 @@ var ActionWsClient = class _ActionWsClient {
       ws.once("open", () => resolve());
       ws.once("error", (error) => {
         reject(
-          new OpensteerRemoteError(
-            "REMOTE_TRANSPORT_ERROR",
+          new OpensteerCloudError(
+            "CLOUD_TRANSPORT_ERROR",
             `Failed to connect action websocket: ${error.message}`
           )
         );
@@ -6970,9 +7561,9 @@ var ActionWsClient = class _ActionWsClient {
   }
   async request(method, args) {
     if (this.closed || this.ws.readyState !== import_ws2.default.OPEN) {
-      throw new OpensteerRemoteError(
-        "REMOTE_SESSION_CLOSED",
-        "Remote action websocket is closed."
+      throw new OpensteerCloudError(
+        "CLOUD_SESSION_CLOSED",
+        "Cloud action websocket is closed."
       );
     }
     const id = this.nextRequestId;
@@ -6991,8 +7582,8 @@ var ActionWsClient = class _ActionWsClient {
       this.ws.send(JSON.stringify(payload));
     } catch (error) {
       this.pending.delete(id);
-      const message = error instanceof Error ? error.message : "Failed to send remote action request.";
-      throw new OpensteerRemoteError("REMOTE_TRANSPORT_ERROR", message);
+      const message = error instanceof Error ? error.message : "Failed to send cloud action request.";
+      throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
     }
     return await resultPromise;
   }
@@ -7010,9 +7601,9 @@ var ActionWsClient = class _ActionWsClient {
       parsed = JSON.parse(rawDataToUtf8(raw));
     } catch {
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_TRANSPORT_ERROR",
-          "Invalid remote action response payload."
+        new OpensteerCloudError(
+          "CLOUD_TRANSPORT_ERROR",
+          "Invalid cloud action response payload."
         )
       );
       return;
@@ -7025,7 +7616,7 @@ var ActionWsClient = class _ActionWsClient {
       return;
     }
     pending.reject(
-      new OpensteerRemoteError(
+      new OpensteerCloudError(
         parsed.code,
         parsed.error,
         void 0,
@@ -7053,7 +7644,7 @@ function withTokenQuery(wsUrl, token) {
   return url.toString();
 }
 
-// src/remote/local-cache-sync.ts
+// src/cloud/local-cache-sync.ts
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
 function collectLocalSelectorCacheEntries(storage) {
@@ -7177,24 +7768,24 @@ function dedupeNewest(entries) {
   return [...byKey.values()];
 }
 
-// src/remote/cdp-client.ts
+// src/cloud/cdp-client.ts
 var import_playwright2 = require("playwright");
-var RemoteCdpClient = class {
+var CloudCdpClient = class {
   async connect(args) {
     const endpoint = withTokenQuery2(args.wsUrl, args.token);
     let browser;
     try {
       browser = await import_playwright2.chromium.connectOverCDP(endpoint);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to connect to remote CDP endpoint.";
-      throw new OpensteerRemoteError("REMOTE_TRANSPORT_ERROR", message);
+      const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
+      throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
     }
     const context = browser.contexts()[0];
     if (!context) {
       await browser.close();
-      throw new OpensteerRemoteError(
-        "REMOTE_INTERNAL",
-        "Remote browser returned no context."
+      throw new OpensteerCloudError(
+        "CLOUD_INTERNAL",
+        "Cloud browser returned no context."
       );
     }
     const page = context.pages()[0] || await context.newPage();
@@ -7207,34 +7798,46 @@ function withTokenQuery2(wsUrl, token) {
   return url.toString();
 }
 
-// src/remote/session-client.ts
+// src/cloud/session-client.ts
 var CACHE_IMPORT_BATCH_SIZE = 200;
-var RemoteSessionClient = class {
+var CloudSessionClient = class {
   baseUrl;
   key;
-  constructor(baseUrl, key) {
+  authScheme;
+  constructor(baseUrl, key, authScheme = "api-key") {
     this.baseUrl = normalizeBaseUrl(baseUrl);
     this.key = key;
+    this.authScheme = authScheme;
   }
   async create(request) {
     const response = await fetch(`${this.baseUrl}/sessions`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
-        "x-api-key": this.key
+        ...this.authHeaders()
       },
       body: JSON.stringify(request)
     });
     if (!response.ok) {
       throw await parseHttpError(response);
     }
-    return await response.json();
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpensteerCloudError(
+        "CLOUD_CONTRACT_MISMATCH",
+        "Invalid cloud session create response: expected a JSON object.",
+        response.status
+      );
+    }
+    return parseCreateResponse(body, response.status);
   }
   async close(sessionId) {
     const response = await fetch(`${this.baseUrl}/sessions/${sessionId}`, {
       method: "DELETE",
       headers: {
-        "x-api-key": this.key
+        ...this.authHeaders()
       }
     });
     if (response.status === 204) {
@@ -7264,7 +7867,7 @@ var RemoteSessionClient = class {
       method: "POST",
       headers: {
         "content-type": "application/json",
-        "x-api-key": this.key
+        ...this.authHeaders()
       },
       body: JSON.stringify({ entries })
     });
@@ -7273,10 +7876,148 @@ var RemoteSessionClient = class {
     }
     return await response.json();
   }
+  authHeaders() {
+    if (this.authScheme === "bearer") {
+      return {
+        authorization: `Bearer ${this.key}`
+      };
+    }
+    return {
+      "x-api-key": this.key
+    };
+  }
 };
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
+function parseCreateResponse(body, status) {
+  const root = requireObject(
+    body,
+    "Invalid cloud session create response: expected a JSON object.",
+    status
+  );
+  const sessionId = requireString(root, "sessionId", status);
+  const actionWsUrl = requireString(root, "actionWsUrl", status);
+  const cdpWsUrl = requireString(root, "cdpWsUrl", status);
+  const actionToken = requireString(root, "actionToken", status);
+  const cdpToken = requireString(root, "cdpToken", status);
+  const cloudSessionUrl = requireString(root, "cloudSessionUrl", status);
+  const cloudSessionRoot = requireObject(
+    root.cloudSession,
+    "Invalid cloud session create response: cloudSession must be an object.",
+    status
+  );
+  const cloudSession = {
+    sessionId: requireString(cloudSessionRoot, "sessionId", status, "cloudSession"),
+    workspaceId: requireString(
+      cloudSessionRoot,
+      "workspaceId",
+      status,
+      "cloudSession"
+    ),
+    state: requireString(cloudSessionRoot, "state", status, "cloudSession"),
+    createdAt: requireNumber(cloudSessionRoot, "createdAt", status, "cloudSession"),
+    sourceType: requireSourceType(cloudSessionRoot, "sourceType", status, "cloudSession"),
+    sourceRef: optionalString(cloudSessionRoot, "sourceRef", status, "cloudSession"),
+    label: optionalString(cloudSessionRoot, "label", status, "cloudSession")
+  };
+  const expiresAt = optionalNumber(root, "expiresAt", status);
+  return {
+    sessionId,
+    actionWsUrl,
+    cdpWsUrl,
+    actionToken,
+    cdpToken,
+    expiresAt,
+    cloudSessionUrl,
+    cloudSession
+  };
+}
+function requireObject(value, message, status) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new OpensteerCloudError("CLOUD_CONTRACT_MISMATCH", message, status);
+  }
+  return value;
+}
+function requireString(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a non-empty string.`,
+      status
+    );
+  }
+  return value;
+}
+function requireNumber(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalString(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a string when present.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalNumber(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number when present.`,
+      status
+    );
+  }
+  return value;
+}
+function requireSourceType(source, field, status, parent) {
+  const value = source[field];
+  if (value === "agent-thread" || value === "agent-run" || value === "local-cloud" || value === "manual") {
+    return value;
+  }
+  throw new OpensteerCloudError(
+    "CLOUD_CONTRACT_MISMATCH",
+    `Invalid cloud session create response: ${formatFieldPath(
+      field,
+      parent
+    )} must be one of "agent-thread", "agent-run", "local-cloud", or "manual".`,
+    status
+  );
+}
+function formatFieldPath(field, parent) {
+  return parent ? `"${parent}.${field}"` : `"${field}"`;
+}
 function zeroImportResponse() {
   return {
     imported: 0,
@@ -7300,33 +8041,46 @@ async function parseHttpError(response) {
   } catch {
     body = null;
   }
-  const code = typeof body?.code === "string" ? toRemoteErrorCode(body.code) : "REMOTE_TRANSPORT_ERROR";
-  const message = typeof body?.error === "string" ? body.error : `Remote request failed with status ${response.status}.`;
-  return new OpensteerRemoteError(code, message, response.status, body?.details);
+  const code = typeof body?.code === "string" ? toCloudErrorCode(body.code) : "CLOUD_TRANSPORT_ERROR";
+  const message = typeof body?.error === "string" ? body.error : `Cloud request failed with status ${response.status}.`;
+  return new OpensteerCloudError(code, message, response.status, body?.details);
 }
-function toRemoteErrorCode(code) {
-  if (code === "REMOTE_AUTH_FAILED" || code === "REMOTE_SESSION_NOT_FOUND" || code === "REMOTE_SESSION_CLOSED" || code === "REMOTE_UNSUPPORTED_METHOD" || code === "REMOTE_INVALID_REQUEST" || code === "REMOTE_MODEL_NOT_ALLOWED" || code === "REMOTE_ACTION_FAILED" || code === "REMOTE_INTERNAL" || code === "REMOTE_CAPACITY_EXHAUSTED" || code === "REMOTE_RUNTIME_UNAVAILABLE" || code === "REMOTE_RUNTIME_MISMATCH" || code === "REMOTE_SESSION_STALE" || code === "REMOTE_CONTROL_PLANE_ERROR") {
+function toCloudErrorCode(code) {
+  if (code === "CLOUD_AUTH_FAILED" || code === "CLOUD_SESSION_NOT_FOUND" || code === "CLOUD_SESSION_CLOSED" || code === "CLOUD_UNSUPPORTED_METHOD" || code === "CLOUD_INVALID_REQUEST" || code === "CLOUD_MODEL_NOT_ALLOWED" || code === "CLOUD_ACTION_FAILED" || code === "CLOUD_INTERNAL" || code === "CLOUD_CAPACITY_EXHAUSTED" || code === "CLOUD_RUNTIME_UNAVAILABLE" || code === "CLOUD_RUNTIME_MISMATCH" || code === "CLOUD_SESSION_STALE" || code === "CLOUD_CONTRACT_MISMATCH" || code === "CLOUD_CONTROL_PLANE_ERROR") {
     return code;
   }
-  return "REMOTE_TRANSPORT_ERROR";
+  return "CLOUD_TRANSPORT_ERROR";
 }
 
-// src/remote/runtime.ts
-var DEFAULT_REMOTE_BASE_URL = "https://remote.opensteer.com";
-function createRemoteRuntimeState(key, baseUrl = resolveRemoteBaseUrl()) {
+// src/cloud/runtime.ts
+var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
+var DEFAULT_CLOUD_APP_URL = "https://opensteer.com";
+function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key", appUrl = resolveCloudAppUrl()) {
   return {
-    sessionClient: new RemoteSessionClient(baseUrl, key),
-    cdpClient: new RemoteCdpClient(),
+    sessionClient: new CloudSessionClient(baseUrl, key, authScheme),
+    cdpClient: new CloudCdpClient(),
+    appUrl: normalizeCloudAppUrl(appUrl),
     actionClient: null,
-    sessionId: null
+    sessionId: null,
+    localRunId: null,
+    cloudSessionUrl: null
   };
 }
-function resolveRemoteBaseUrl() {
+function resolveCloudBaseUrl() {
   const value = process.env.OPENSTEER_BASE_URL?.trim();
-  if (!value) return DEFAULT_REMOTE_BASE_URL;
+  if (!value) return DEFAULT_CLOUD_BASE_URL;
+  return value.replace(/\/+$/, "");
+}
+function resolveCloudAppUrl() {
+  const value = process.env.OPENSTEER_APP_URL?.trim();
+  if (!value) return DEFAULT_CLOUD_APP_URL;
+  return normalizeCloudAppUrl(value);
+}
+function normalizeCloudAppUrl(value) {
+  if (!value) return null;
   return value.replace(/\/+$/, "");
 }
-function readRemoteActionDescription(payload) {
+function readCloudActionDescription(payload) {
   const description = payload.description;
   if (typeof description !== "string") return void 0;
   const normalized = description.trim();
@@ -7334,7 +8088,7 @@ function readRemoteActionDescription(payload) {
 }
 
 // src/opensteer.ts
-var REMOTE_INTERACTION_METHODS = /* @__PURE__ */ new Set([
+var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
   "click",
   "dblclick",
   "rightclick",
@@ -7351,7 +8105,7 @@ var Opensteer = class _Opensteer {
   namespace;
   storage;
   pool;
-  remote;
+  cloud;
   browser = null;
   pageRef = null;
   contextRef = null;
@@ -7359,8 +8113,8 @@ var Opensteer = class _Opensteer {
   snapshotCache = null;
   constructor(config = {}) {
     const resolved = resolveConfig(config);
-    const modeSelection = resolveModeSelection({
-      mode: resolved.mode
+    const cloudSelection = resolveCloudSelection({
+      cloud: resolved.cloud
     });
     const model = resolved.model;
     this.config = resolved;
@@ -7370,20 +8124,22 @@ var Opensteer = class _Opensteer {
     this.namespace = resolveNamespace(resolved, rootDir);
     this.storage = new LocalSelectorStorage(rootDir, this.namespace);
     this.pool = new BrowserPool(resolved.browser || {});
-    if (modeSelection.mode === "remote") {
-      const remoteConfig = resolved.remote && typeof resolved.remote === "object" ? resolved.remote : void 0;
-      const apiKey = remoteConfig?.apiKey?.trim();
+    if (cloudSelection.cloud) {
+      const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
+      const apiKey = cloudConfig?.apiKey?.trim();
       if (!apiKey) {
         throw new Error(
-          "Remote mode requires a non-empty API key via remote.apiKey or OPENSTEER_API_KEY."
+          "Cloud mode requires a non-empty API key via cloud.apiKey or OPENSTEER_API_KEY."
         );
       }
-      this.remote = createRemoteRuntimeState(
+      this.cloud = createCloudRuntimeState(
         apiKey,
-        remoteConfig?.baseUrl
+        cloudConfig?.baseUrl,
+        cloudConfig?.authScheme,
+        cloudConfig?.appUrl
       );
     } else {
-      this.remote = null;
+      this.cloud = null;
     }
   }
   createLazyResolveCallback(model) {
@@ -7421,32 +8177,32 @@ var Opensteer = class _Opensteer {
     };
     return extract;
   }
-  async invokeRemoteActionAndResetCache(method, args) {
-    const result = await this.invokeRemoteAction(method, args);
+  async invokeCloudActionAndResetCache(method, args) {
+    const result = await this.invokeCloudAction(method, args);
     this.snapshotCache = null;
     return result;
   }
-  async invokeRemoteAction(method, args) {
-    const actionClient = this.remote?.actionClient;
-    const sessionId = this.remote?.sessionId;
+  async invokeCloudAction(method, args) {
+    const actionClient = this.cloud?.actionClient;
+    const sessionId = this.cloud?.sessionId;
     if (!actionClient || !sessionId) {
-      throw remoteNotLaunchedError();
+      throw cloudNotLaunchedError();
     }
     const payload = args && typeof args === "object" ? args : {};
     try {
       return await actionClient.request(method, payload);
     } catch (err) {
-      if (err instanceof OpensteerRemoteError && err.code === "REMOTE_ACTION_FAILED" && REMOTE_INTERACTION_METHODS.has(method)) {
+      if (err instanceof OpensteerCloudError && err.code === "CLOUD_ACTION_FAILED" && CLOUD_INTERACTION_METHODS.has(method)) {
         const detailsRecord = err.details && typeof err.details === "object" ? err.details : null;
-        const remoteFailure = normalizeActionFailure(
+        const cloudFailure = normalizeActionFailure(
           detailsRecord?.actionFailure
         );
-        const failure = remoteFailure || classifyActionFailure({
+        const failure = cloudFailure || classifyActionFailure({
           action: method,
           error: err,
           fallbackMessage: defaultActionFailureMessage(method)
         });
-        const description = readRemoteActionDescription(payload);
+        const description = readCloudActionDescription(payload);
         throw this.buildActionError(
           method,
           description,
@@ -7487,8 +8243,36 @@ var Opensteer = class _Opensteer {
     }
     return this.contextRef;
   }
-  getRemoteSessionId() {
-    return this.remote?.sessionId ?? null;
+  getCloudSessionId() {
+    return this.cloud?.sessionId ?? null;
+  }
+  getCloudSessionUrl() {
+    return this.cloud?.cloudSessionUrl ?? null;
+  }
+  announceCloudSession(args) {
+    if (!this.shouldAnnounceCloudSession()) {
+      return;
+    }
+    const fields = [
+      `sessionId=${args.sessionId}`,
+      `workspaceId=${args.workspaceId}`
+    ];
+    if (args.cloudSessionUrl) {
+      fields.push(`url=${args.cloudSessionUrl}`);
+    }
+    process.stderr.write(`[opensteer] cloud session ready ${fields.join(" ")}
+`);
+  }
+  shouldAnnounceCloudSession() {
+    const cloudConfig = this.config.cloud && typeof this.config.cloud === "object" ? this.config.cloud : null;
+    const announce = cloudConfig?.announce ?? "always";
+    if (announce === "off") {
+      return false;
+    }
+    if (announce === "tty") {
+      return Boolean(process.stderr.isTTY);
+    }
+    return true;
   }
   async launch(options = {}) {
     if (this.pageRef && !this.ownsBrowser) {
@@ -7499,22 +8283,29 @@ var Opensteer = class _Opensteer {
     if (this.pageRef && this.ownsBrowser) {
       return;
     }
-    if (this.remote) {
+    if (this.cloud) {
       let actionClient = null;
       let browser = null;
       let sessionId = null;
+      let localRunId = null;
       try {
         try {
-          await this.syncLocalSelectorCacheToRemote();
+          await this.syncLocalSelectorCacheToCloud();
         } catch (error) {
           if (this.config.debug) {
             const message = error instanceof Error ? error.message : String(error);
             console.warn(
-              `[opensteer] remote selector cache sync failed: ${message}`
+              `[opensteer] cloud selector cache sync failed: ${message}`
             );
           }
         }
-        const session2 = await this.remote.sessionClient.create({
+        localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
+        this.cloud.localRunId = localRunId;
+        const session2 = await this.cloud.sessionClient.create({
+          cloudSessionContractVersion,
+          sourceType: "local-cloud",
+          clientSessionHint: this.namespace,
+          localRunId,
           name: this.namespace,
           model: this.config.model,
           launchContext: options.context || void 0
@@ -7525,7 +8316,7 @@ var Opensteer = class _Opensteer {
           token: session2.actionToken,
           sessionId: session2.sessionId
         });
-        const cdpConnection = await this.remote.cdpClient.connect({
+        const cdpConnection = await this.cloud.cdpClient.connect({
           wsUrl: session2.cdpWsUrl,
           token: session2.cdpToken
         });
@@ -7535,8 +8326,17 @@ var Opensteer = class _Opensteer {
         this.pageRef = cdpConnection.page;
         this.ownsBrowser = true;
         this.snapshotCache = null;
-        this.remote.actionClient = actionClient;
-        this.remote.sessionId = sessionId;
+        this.cloud.actionClient = actionClient;
+        this.cloud.sessionId = sessionId;
+        this.cloud.cloudSessionUrl = buildCloudSessionUrl(
+          this.cloud.appUrl,
+          session2.cloudSession.sessionId
+        );
+        this.announceCloudSession({
+          sessionId: session2.sessionId,
+          workspaceId: session2.cloudSession.workspaceId,
+          cloudSessionUrl: this.cloud.cloudSessionUrl
+        });
         return;
       } catch (error) {
         if (actionClient) {
@@ -7546,8 +8346,9 @@ var Opensteer = class _Opensteer {
           await browser.close().catch(() => void 0);
         }
         if (sessionId) {
-          await this.remote.sessionClient.close(sessionId).catch(() => void 0);
+          await this.cloud.sessionClient.close(sessionId).catch(() => void 0);
         }
+        this.cloud.cloudSessionUrl = null;
         throw error;
       }
     }
@@ -7565,13 +8366,13 @@ var Opensteer = class _Opensteer {
   }
   static from(page, config = {}) {
     const resolvedConfig = resolveConfig(config);
-    const modeSelection = resolveModeSelection({
-      mode: resolvedConfig.mode
+    const cloudSelection = resolveCloudSelection({
+      cloud: resolvedConfig.cloud
     });
-    if (modeSelection.mode === "remote") {
-      throw remoteUnsupportedMethodError(
+    if (cloudSelection.cloud) {
+      throw cloudUnsupportedMethodError(
         "Opensteer.from(page)",
-        "Opensteer.from(page) is not supported in remote mode."
+        "Opensteer.from(page) is not supported in cloud mode."
       );
     }
     const instance = new _Opensteer(config);
@@ -7584,12 +8385,14 @@ var Opensteer = class _Opensteer {
   }
   async close() {
     this.snapshotCache = null;
-    if (this.remote) {
-      const actionClient = this.remote.actionClient;
-      const sessionId = this.remote.sessionId;
+    if (this.cloud) {
+      const actionClient = this.cloud.actionClient;
+      const sessionId = this.cloud.sessionId;
       const browser = this.browser;
-      this.remote.actionClient = null;
-      this.remote.sessionId = null;
+      this.cloud.actionClient = null;
+      this.cloud.sessionId = null;
+      this.cloud.localRunId = null;
+      this.cloud.cloudSessionUrl = null;
       this.browser = null;
       this.pageRef = null;
       this.contextRef = null;
@@ -7601,7 +8404,7 @@ var Opensteer = class _Opensteer {
         await browser.close().catch(() => void 0);
       }
       if (sessionId) {
-        await this.remote.sessionClient.close(sessionId).catch(() => void 0);
+        await this.cloud.sessionClient.close(sessionId).catch(() => void 0);
       }
       return;
     }
@@ -7613,17 +8416,17 @@ var Opensteer = class _Opensteer {
     this.contextRef = null;
     this.ownsBrowser = false;
   }
-  async syncLocalSelectorCacheToRemote() {
-    if (!this.remote) return;
+  async syncLocalSelectorCacheToCloud() {
+    if (!this.cloud) return;
     const entries = collectLocalSelectorCacheEntries(this.storage);
     if (!entries.length) return;
-    await this.remote.sessionClient.importSelectorCache({
+    await this.cloud.sessionClient.importSelectorCache({
       entries
     });
   }
   async goto(url, options) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("goto", { url, options });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("goto", { url, options });
       return;
     }
     const { waitUntil = "domcontentloaded", ...rest } = options ?? {};
@@ -7632,8 +8435,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async snapshot(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache("snapshot", {
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache("snapshot", {
         options
       });
     }
@@ -7642,8 +8445,8 @@ var Opensteer = class _Opensteer {
     return prepared.cleanedHtml;
   }
   async state() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("state", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("state", {});
     }
     const html = await this.snapshot({ mode: "action" });
     return {
@@ -7653,8 +8456,8 @@ var Opensteer = class _Opensteer {
     };
   }
   async screenshot(options = {}) {
-    if (this.remote) {
-      const b64 = await this.invokeRemoteAction(
+    if (this.cloud) {
+      const b64 = await this.invokeCloudAction(
         "screenshot",
         options
       );
@@ -7668,8 +8471,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async click(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "click",
         options
       );
@@ -7681,8 +8484,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async dblclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "dblclick",
         options
       );
@@ -7694,8 +8497,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async rightclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "rightclick",
         options
       );
@@ -7707,8 +8510,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async hover(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "hover",
         options
       );
@@ -7806,8 +8609,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async input(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "input",
         options
       );
@@ -7836,7 +8639,7 @@ var Opensteer = class _Opensteer {
             await handle.type(options.text);
           }
           if (options.pressEnter) {
-            await handle.press("Enter");
+            await handle.press("Enter", { noWaitAfter: true });
           }
         });
       } catch (err) {
@@ -7909,8 +8712,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async select(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "select",
         options
       );
@@ -8019,8 +8822,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async scroll(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "scroll",
         options
       );
@@ -8121,14 +8924,14 @@ var Opensteer = class _Opensteer {
   }
   // --- Tab Management ---
   async tabs() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("tabs", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("tabs", {});
     }
     return listTabs(this.context, this.page);
   }
   async newTab(url) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache("newTab", {
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache("newTab", {
         url
       });
     }
@@ -8138,8 +8941,8 @@ var Opensteer = class _Opensteer {
     return info;
   }
   async switchTab(index) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("switchTab", { index });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("switchTab", { index });
       return;
     }
     const page = await switchTab(this.context, index);
@@ -8147,8 +8950,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async closeTab(index) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("closeTab", { index });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("closeTab", { index });
       return;
     }
     const newPage = await closeTab(this.context, this.page, index);
@@ -8159,8 +8962,8 @@ var Opensteer = class _Opensteer {
   }
   // --- Cookie Management ---
   async getCookies(url) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getCookies",
         { url }
       );
@@ -8168,41 +8971,41 @@ var Opensteer = class _Opensteer {
     return getCookies(this.context, url);
   }
   async setCookie(cookie) {
-    if (this.remote) {
-      await this.invokeRemoteAction("setCookie", cookie);
+    if (this.cloud) {
+      await this.invokeCloudAction("setCookie", cookie);
       return;
     }
     return setCookie(this.context, cookie);
   }
   async clearCookies() {
-    if (this.remote) {
-      await this.invokeRemoteAction("clearCookies", {});
+    if (this.cloud) {
+      await this.invokeCloudAction("clearCookies", {});
       return;
     }
     return clearCookies(this.context);
   }
   async exportCookies(filePath, url) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "exportCookies",
-        "exportCookies() is not supported in remote mode because it depends on local filesystem paths."
+        "exportCookies() is not supported in cloud mode because it depends on local filesystem paths."
       );
     }
     return exportCookies(this.context, filePath, url);
   }
   async importCookies(filePath) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "importCookies",
-        "importCookies() is not supported in remote mode because it depends on local filesystem paths."
+        "importCookies() is not supported in cloud mode because it depends on local filesystem paths."
       );
     }
     return importCookies(this.context, filePath);
   }
   // --- Keyboard Input ---
   async pressKey(key) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("pressKey", { key });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("pressKey", { key });
       return;
     }
     await this.runWithPostActionWait("pressKey", void 0, async () => {
@@ -8211,8 +9014,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async type(text) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("type", { text });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("type", { text });
       return;
     }
     await this.runWithPostActionWait("type", void 0, async () => {
@@ -8222,8 +9025,8 @@ var Opensteer = class _Opensteer {
   }
   // --- Element Info ---
   async getElementText(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getElementText", options);
+    if (this.cloud) {
+      return await this.invokeCloudAction("getElementText", options);
     }
     return this.executeElementInfoAction(
       "getElementText",
@@ -8236,8 +9039,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementValue(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementValue",
         options
       );
@@ -8252,8 +9055,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementAttributes(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementAttributes",
         options
       );
@@ -8274,8 +9077,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementBoundingBox(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementBoundingBox",
         options
       );
@@ -8290,14 +9093,14 @@ var Opensteer = class _Opensteer {
     );
   }
   async getHtml(selector) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getHtml", { selector });
+    if (this.cloud) {
+      return await this.invokeCloudAction("getHtml", { selector });
     }
     return getPageHtml(this.page, selector);
   }
   async getTitle() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getTitle", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("getTitle", {});
     }
     return getPageTitle(this.page);
   }
@@ -8335,10 +9138,10 @@ var Opensteer = class _Opensteer {
   }
   // --- File Upload ---
   async uploadFile(options) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "uploadFile",
-        "uploadFile() is not supported in remote mode because file paths must be accessible on the remote server."
+        "uploadFile() is not supported in cloud mode because file paths must be accessible on the cloud runtime."
       );
     }
     const storageKey = this.resolveStorageKey(options.description);
@@ -8440,15 +9243,15 @@ var Opensteer = class _Opensteer {
   }
   // --- Wait for Text ---
   async waitForText(text, options) {
-    if (this.remote) {
-      await this.invokeRemoteAction("waitForText", { text, options });
+    if (this.cloud) {
+      await this.invokeCloudAction("waitForText", { text, options });
       return;
     }
     await this.page.getByText(text).first().waitFor({ timeout: options?.timeout ?? 3e4 });
   }
   async extract(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("extract", options);
+    if (this.cloud) {
+      return await this.invokeCloudAction("extract", options);
     }
     const storageKey = this.resolveStorageKey(options.description);
     const schemaHash = options.schema ? computeSchemaHash(options.schema) : null;
@@ -8500,8 +9303,8 @@ var Opensteer = class _Opensteer {
     return inflateDataPathObject(data);
   }
   async extractFromPlan(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "extractFromPlan",
         options
       );
@@ -8550,10 +9353,10 @@ var Opensteer = class _Opensteer {
     return this.storage;
   }
   clearCache() {
-    if (this.remote) {
+    if (this.cloud) {
       this.snapshotCache = null;
-      if (!this.remote.actionClient) return;
-      void this.invokeRemoteAction("clearCache", {});
+      if (!this.cloud.actionClient) return;
+      void this.invokeCloudAction("clearCache", {});
       return;
     }
     this.storage.clearNamespace();
@@ -9581,6 +10384,16 @@ function getScrollDelta2(options) {
       return { x: 0, y: absoluteAmount };
   }
 }
+function buildLocalRunId(namespace) {
+  const normalized = namespace.trim() || "default";
+  return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto2.randomUUID)().slice(0, 8)}`;
+}
+function buildCloudSessionUrl(appUrl, sessionId) {
+  if (!appUrl) {
+    return null;
+  }
+  return `${appUrl}/browser/${encodeURIComponent(sessionId)}`;
+}
 
 // src/ai/index.ts
 init_resolver();
@@ -9589,6 +10402,8 @@ init_model();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionWsClient,
+  CloudCdpClient,
+  CloudSessionClient,
   CounterResolutionError,
   ElementPathError,
   LocalSelectorStorage,
@@ -9602,9 +10417,7 @@ init_model();
   OS_UNAVAILABLE_ATTR,
   Opensteer,
   OpensteerActionError,
-  OpensteerRemoteError,
-  RemoteCdpClient,
-  RemoteSessionClient,
+  OpensteerCloudError,
   buildElementPathFromHandle,
   buildElementPathFromSelector,
   buildPathSelectorHint,
@@ -9616,6 +10429,9 @@ init_model();
   clearCookies,
   cloneElementPath,
   closeTab,
+  cloudNotLaunchedError,
+  cloudSessionContractVersion,
+  cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries,
   countArrayItemsWithPath,
   createEmptyRegistry,
@@ -9647,8 +10463,6 @@ init_model();
   performSelect,
   prepareSnapshot,
   pressKey,
-  remoteNotLaunchedError,
-  remoteUnsupportedMethodError,
   resolveCounterElement,
   resolveCountersBatch,
   resolveElementPath,