@xbrowser/cli 0.15.1 → 1.0.0

package/dist/index.js

@@ -1,3 +1,47 @@
+import {
+  forwardCommandLog,
+  forwardNetworkAnalyze,
+  forwardNetworkAround,
+  forwardNetworkClear,
+  forwardNetworkCurl,
+  forwardNetworkDislike,
+  forwardNetworkExport,
+  forwardNetworkInspect,
+  forwardNetworkLike,
+  forwardNetworkList,
+  forwardNetworkReplay,
+  forwardNetworkTop,
+  forwardRecordCheckpoint,
+  forwardRecordStart,
+  forwardRecordStatus,
+  forwardRecordStop,
+  forwardRecordSummary,
+  forwardReplay,
+  forwardSessionClose,
+  forwardSessionCreate,
+  forwardSessionList,
+  forwardViewerCheckSelector,
+  getDaemonConfig,
+  getDaemonProcessStatus,
+  killAllDaemonProcesses,
+  startDaemonProcess,
+  stopDaemonProcess
+} from "./chunk-IDVD44ED.js";
+import {
+  CaptchaDetector,
+  HumanInteractionManager,
+  NPM_REGISTRY_URL,
+  NPM_SCOPE,
+  ScreencastCapturer,
+  WebhookNotifier,
+  getCaptchaConfig,
+  getConfigValue,
+  getMarketplaceUrl,
+  loadConfig,
+  readJsonFile,
+  resolveNpmPackageWithFallback,
+  setConfigValue
+} from "./chunk-ITKPSIP7.js";
 import {
   generateBashScript,
   generateJSScript,
@@ -14,7 +58,7 @@ import {
 } from "./chunk-OPRXFZVE.js";
 import {
   SessionRecorder
-} from "./chunk-KDYXFLAC.js";
+} from "./chunk-2MFXKN32.js";
 import {
   closeAllSessions,
   closeEphemeralContext,
@@ -31,7 +75,9 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-RS6YYWTK.js";
+} from "./chunk-YKOHDEFV.js";
+import "./chunk-42RPMJ76.js";
+import "./chunk-T4J4C2NZ.js";
 import {
   CDPInterceptorProxy,
   advise,
@@ -46,50 +92,6 @@ import {
   networkAnomalyRule,
   pageLifecycleRule
 } from "./chunk-ZZ2TFWIV.js";
-import {
-  forwardCommandLog,
-  forwardNetworkAnalyze,
-  forwardNetworkAround,
-  forwardNetworkClear,
-  forwardNetworkCurl,
-  forwardNetworkDislike,
-  forwardNetworkExport,
-  forwardNetworkInspect,
-  forwardNetworkLike,
-  forwardNetworkList,
-  forwardNetworkReplay,
-  forwardNetworkTop,
-  forwardRecordCheckpoint,
-  forwardRecordStart,
-  forwardRecordStatus,
-  forwardRecordStop,
-  forwardRecordSummary,
-  forwardReplay,
-  forwardSessionClose,
-  forwardSessionCreate,
-  forwardSessionList,
-  forwardViewerCheckSelector,
-  getDaemonConfig,
-  getDaemonProcessStatus,
-  killAllDaemonProcesses,
-  startDaemonProcess,
-  stopDaemonProcess
-} from "./chunk-ATFTAKMN.js";
-import {
-  CaptchaDetector,
-  HumanInteractionManager,
-  NPM_REGISTRY_URL,
-  NPM_SCOPE,
-  ScreencastCapturer,
-  WebhookNotifier,
-  getCaptchaConfig,
-  getConfigValue,
-  getMarketplaceUrl,
-  loadConfig,
-  readJsonFile,
-  resolveNpmPackageWithFallback,
-  setConfigValue
-} from "./chunk-ITKPSIP7.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";
@@ -102,12 +104,13 @@ var version = pkg.version;
 
 // src/executor.ts
 import {
-  ok as ok25,
+  ok as ok26,
   fail as fail7,
   isCommandResult,
   configureArchiveStore,
   appendCommandToArchive,
-  checkGuard
+  checkGuard,
+  PluginStorage
 } from "@dyyz1993/xcli-core";
 
 // src/utils/positional-params.ts
@@ -580,7 +583,7 @@ var pressCommand = registerCommand({
     key: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.press(p.selector || "body", p.key, { delay: p.delay, timeout: 1e4 });
+    await ctx.page.press(p.selector || "body", p.key, { timeout: 1e4 });
     return ok2({ key: p.key });
   }
 });
@@ -599,7 +602,7 @@ var selectCommand = registerCommand({
   }),
   handler: async (p, ctx) => {
     const values = typeof p.value === "string" ? [p.value] : p.value;
-    await ctx.page.selectOption(p.selector, values, { force: true, timeout: 1e4 });
+    await ctx.page.selectOption(p.selector, values);
     return ok2({ selector: p.selector, value: p.value });
   }
 });
@@ -615,7 +618,7 @@ var checkCommand = registerCommand({
     selector: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.check(p.selector, { force: true, timeout: 1e4 });
+    await ctx.page.check(p.selector, { timeout: 1e4 });
     return ok2({ selector: p.selector });
   }
 });
@@ -632,7 +635,7 @@ var hoverCommand = registerCommand({
     selector: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.hover(p.selector, { modifiers: p.modifiers, force: true, timeout: 1e4 });
+    await ctx.page.hover(p.selector, { timeout: 1e4 });
     return ok2({ selector: p.selector });
   }
 });
@@ -2161,7 +2164,7 @@ var scrapeCommand = registerCommand({
           await page.goto(p.url, { waitUntil: "commit", timeout: p.timeout });
           await page.waitForSelector("body", { timeout: p.timeout }).catch(() => {
           });
-          await page.waitForLoadState("networkidle", { timeout: Math.min(p.timeout, 8e3) }).catch(() => {
+          await page.waitForLoadState("networkidle", Math.min(p.timeout, 8e3)).catch(() => {
           });
           await page.waitForTimeout(p.waitAfterLoad > 0 ? p.waitAfterLoad : 2e3);
           if (p.selector) {
@@ -3166,7 +3169,7 @@ async function fetchFullContent(urls, timeout, cdpEndpoint) {
             const pg = await context.newPage();
             try {
               await pg.goto(url, { waitUntil: "domcontentloaded", timeout });
-              await pg.waitForLoadState("networkidle", { timeout }).catch(() => {
+              await pg.waitForLoadState("networkidle", timeout).catch(() => {
               });
               const html = await pg.content();
               contentMap.set(url, htmlToMarkdown(html, { onlyMainContent: true }));
@@ -3562,7 +3565,7 @@ var networkCommand = registerCommand({
         waitUntil: "domcontentloaded",
         timeout: p.timeout
       });
-      await page.waitForLoadState("networkidle", { timeout: p.timeout }).catch(() => {
+      await page.waitForLoadState("networkidle", p.timeout).catch(() => {
       });
       await page.waitForTimeout(p.wait);
       const totalCount = captures.length;
@@ -4150,6 +4153,24 @@ function parseMarkdownResults(rawText) {
 import { z as z21 } from "zod";
 import { ok as ok20, fail as fail4 } from "@dyyz1993/xcli-core";
 
+// src/runtime/ref-store.ts
+var sessions = /* @__PURE__ */ new Map();
+function normalizeAgentRef(ref) {
+  return ref.startsWith("@") ? ref.slice(1) : ref;
+}
+function replaceRefs(sessionKey2, screenHash, targets) {
+  sessions.set(sessionKey2, {
+    screenHash,
+    targets: new Map(targets.map((target) => [target.ref, target]))
+  });
+}
+function getRefTarget(sessionKey2, ref) {
+  const session = sessions.get(sessionKey2);
+  const target = session?.targets.get(normalizeAgentRef(ref));
+  if (!session || !target) return null;
+  return { screenHash: session.screenHash, target };
+}
+
 // src/utils/resolve-selector.ts
 function buildElementSelector(el) {
   function isUnique(sel) {
@@ -4321,9 +4342,9 @@ async function resolveSelectors(page, ariaSnapshot) {
   }
   return results;
 }
-var REF_ONLY = /^(e\d+)$/;
+var REF_ONLY = /^@?(e\d+)$/;
 var refCache = /* @__PURE__ */ new Map();
-async function resolveRefParams(page, params, selectorKeys, cache) {
+async function resolveRefParams(page, params, selectorKeys, cache, sessionId) {
   const tips = [];
   const newParams = { ...params };
   if (!selectorKeys || selectorKeys.length === 0) {
@@ -4332,7 +4353,17 @@ async function resolveRefParams(page, params, selectorKeys, cache) {
   for (const key of selectorKeys) {
     const val = params[key];
     if (typeof val !== "string" || !REF_ONLY.test(val)) continue;
-    const ref = val;
+    const match = val.match(REF_ONLY);
+    if (!match) continue;
+    const ref = normalizeAgentRef(match[1]);
+    if (sessionId) {
+      const runtimeTarget = getRefTarget(sessionId, ref);
+      if (runtimeTarget) {
+        tips.push(`ref=@${ref} (${key}) => ${runtimeTarget.target.selector}  (observe)`);
+        newParams[key] = runtimeTarget.target.selector;
+        continue;
+      }
+    }
     const activeCache = cache ?? refCache;
     const cached = activeCache.get(ref);
     if (cached) {
@@ -4613,6 +4644,404 @@ async function enhanceSemanticsWithLLM(url, ariaSnapshot, ruleBasedElements) {
   saveSemantics(domain, pathKey, url, llmElements);
 }
 
+// src/runtime/agent-runtime.ts
+function sessionKey(sessionId) {
+  return sessionId || "default";
+}
+async function observePage(page, sessionId, options = {}) {
+  const [title, raw] = await Promise.all([
+    page.title().catch(() => ""),
+    page.evaluate(
+      ({ includeHidden, limit }) => {
+        function hash(input) {
+          let h = 2166136261;
+          for (let i = 0; i < input.length; i++) {
+            h ^= input.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+          }
+          return (h >>> 0).toString(16);
+        }
+        function cssEscape(value) {
+          const css = globalThis.CSS;
+          return css?.escape ? css.escape(value) : value.replace(/["\\#.:,[\]>+~*]/g, "\\$&");
+        }
+        function isUnique(selector2) {
+          try {
+            return document.querySelectorAll(selector2).length === 1;
+          } catch {
+            return false;
+          }
+        }
+        function nthOfType(el) {
+          const tag = el.tagName.toLowerCase();
+          const parent = el.parentElement;
+          if (!parent) return tag;
+          const same = Array.from(parent.children).filter((child) => child.tagName === el.tagName);
+          if (same.length === 1) return tag;
+          return `${tag}:nth-of-type(${same.indexOf(el) + 1})`;
+        }
+        function selectorFor(el) {
+          const tag = el.tagName.toLowerCase();
+          const id = el.getAttribute("id");
+          if (id) {
+            const selector2 = `#${cssEscape(id)}`;
+            if (isUnique(selector2)) return selector2;
+          }
+          for (const attr of ["data-testid", "data-test", "data-qa", "name", "aria-label"]) {
+            const value = el.getAttribute(attr);
+            if (!value) continue;
+            const selector2 = `[${attr}="${cssEscape(value)}"]`;
+            if (isUnique(selector2)) return selector2;
+            const tagged = `${tag}${selector2}`;
+            if (isUnique(tagged)) return tagged;
+          }
+          const classes = Array.from(el.classList).slice(0, 3);
+          for (const cls of classes) {
+            const selector2 = `${tag}.${cssEscape(cls)}`;
+            if (isUnique(selector2)) return selector2;
+          }
+          const parts = [];
+          let cur = el;
+          while (cur && cur !== document.body && cur !== document.documentElement && parts.length < 6) {
+            parts.unshift(nthOfType(cur));
+            const selector2 = parts.join(" > ");
+            if (isUnique(selector2)) return selector2;
+            cur = cur.parentElement;
+          }
+          return parts.join(" > ") || tag;
+        }
+        function roleFor(el) {
+          const explicit = el.getAttribute("role");
+          if (explicit) return explicit;
+          const tag = el.tagName.toLowerCase();
+          if (tag === "a") return "link";
+          if (tag === "button") return "button";
+          if (tag === "select") return "combobox";
+          if (tag === "textarea") return "textbox";
+          if (tag === "input") {
+            const type = (el.getAttribute("type") || "text").toLowerCase();
+            if (type === "checkbox") return "checkbox";
+            if (type === "radio") return "radio";
+            if (type === "button" || type === "submit" || type === "reset") return "button";
+            return "textbox";
+          }
+          return tag;
+        }
+        function textName(el) {
+          const input = el;
+          const direct = el.getAttribute("aria-label") || el.getAttribute("placeholder") || el.getAttribute("title") || input.value || el.textContent || "";
+          return direct.replace(/\s+/g, " ").trim().slice(0, 120);
+        }
+        function actionsFor(role, editable) {
+          const actions = [];
+          if (editable) actions.push("fill", "type");
+          if (role === "combobox") actions.push("select");
+          if (role === "checkbox" || role === "radio") actions.push("check");
+          actions.push("click", "hover");
+          return Array.from(new Set(actions));
+        }
+        const selector = [
+          "a[href]",
+          "button",
+          "input",
+          "textarea",
+          "select",
+          "summary",
+          "label",
+          "[role]",
+          "[tabindex]",
+          '[contenteditable="true"]'
+        ].join(",");
+        const candidates = Array.from(document.querySelectorAll(selector));
+        const seen = /* @__PURE__ */ new Set();
+        const targets2 = [];
+        for (const el of candidates) {
+          const rect = el.getBoundingClientRect();
+          const style = window.getComputedStyle(el);
+          const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+          if (!includeHidden && !visible) continue;
+          const selectorValue = selectorFor(el);
+          if (!selectorValue || seen.has(selectorValue)) continue;
+          seen.add(selectorValue);
+          const input = el;
+          const tag = el.tagName.toLowerCase();
+          const role = roleFor(el);
+          const editable = tag === "textarea" || tag === "select" || tag === "input" && !["button", "submit", "reset", "checkbox", "radio"].includes((input.type || "").toLowerCase()) || el.isContentEditable;
+          const enabled = !input.disabled && el.getAttribute("aria-disabled") !== "true";
+          const checked = typeof input.checked === "boolean" && ["checkbox", "radio"].includes((input.type || "").toLowerCase()) ? input.checked : void 0;
+          targets2.push({
+            selector: selectorValue,
+            role,
+            name: textName(el),
+            tag,
+            visible,
+            enabled,
+            editable,
+            ...checked !== void 0 ? { checked } : {},
+            ...editable && input.value ? { value: input.value.slice(0, 120) } : {},
+            ...visible ? { box: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) } } : {},
+            actions: actionsFor(role, editable)
+          });
+          if (targets2.length >= limit) break;
+        }
+        const stateText = [
+          location.href,
+          document.title,
+          document.body?.innerText?.slice(0, 5e3) || ""
+        ].join("\n");
+        return { screenHash: hash(stateText), targets: targets2 };
+      },
+      { includeHidden: !!options.includeHidden, limit: options.limit ?? 80 }
+    )
+  ]);
+  const targets = raw.targets.map((target, index) => ({
+    ref: `e${index + 1}`,
+    ...target
+  }));
+  replaceRefs(sessionKey(sessionId), raw.screenHash, targets);
+  return {
+    url: page.url(),
+    title,
+    screenHash: raw.screenHash,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    targets
+  };
+}
+function quoteName(name) {
+  const cleaned = name.replace(/\s+/g, " ").trim();
+  if (!cleaned) return "";
+  return ` "${cleaned.replace(/"/g, '\\"')}"`;
+}
+function targetFlags(target) {
+  const flags = [target.role || target.tag];
+  if (!target.enabled) flags.push("disabled");
+  if (target.editable) flags.push("editable");
+  if (target.checked !== void 0) flags.push(target.checked ? "checked" : "unchecked");
+  return flags.join(" ");
+}
+function buildSelectorMap(observation) {
+  return Object.fromEntries(observation.targets.map((target) => [target.ref, target.selector]));
+}
+function formatObservationCompact(observation, options = {}) {
+  const lines = [
+    `Page: ${observation.title || "(untitled)"}`,
+    `URL: ${observation.url}`,
+    `Screen: ${observation.screenHash}`,
+    ""
+  ];
+  if (observation.targets.length === 0) {
+    lines.push("(no interactive targets)");
+  } else {
+    for (const target of observation.targets) {
+      lines.push(`@${target.ref} [${targetFlags(target)}]${quoteName(target.name)}`);
+    }
+  }
+  if (options.selectors && observation.targets.length > 0) {
+    lines.push("", "## Selectors");
+    lines.push(observation.targets.map((target) => `${target.ref}: ${target.selector}`).join(" | "));
+  }
+  return lines.join("\n");
+}
+async function getPageScreenHash(page) {
+  const observation = await page.evaluate(() => {
+    let h = 2166136261;
+    const input = [location.href, document.title, document.body?.innerText?.slice(0, 5e3) || ""].join("\n");
+    for (let i = 0; i < input.length; i++) {
+      h ^= input.charCodeAt(i);
+      h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16);
+  });
+  return observation;
+}
+async function actionability(page, selector) {
+  return await page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return { ok: false, reason: "not_found" };
+    const rect = el.getBoundingClientRect();
+    const style = window.getComputedStyle(el);
+    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+    if (!visible) return { ok: false, reason: "not_visible" };
+    const input = el;
+    const enabled = !input.disabled && el.getAttribute("aria-disabled") !== "true";
+    if (!enabled) return { ok: false, reason: "disabled" };
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const hit = document.elementFromPoint(cx, cy);
+    if (hit && hit !== el && !el.contains(hit) && !hit.contains(el)) {
+      return { ok: false, reason: "covered" };
+    }
+    return { ok: true };
+  }, selector);
+}
+async function actOnPage(page, sessionId, input) {
+  const normalizedRef = input.ref ? normalizeAgentRef(input.ref) : void 0;
+  const refMatch = normalizedRef ? getRefTarget(sessionKey(sessionId), normalizedRef) : null;
+  const selector = input.selector || refMatch?.target.selector;
+  if (!selector) {
+    return {
+      action: input.action,
+      selector: "",
+      ref: normalizedRef,
+      success: false,
+      reason: input.ref ? "unknown_ref" : "missing_target",
+      message: normalizedRef ? `Ref "${input.ref}" not found. Run observe again.` : "Provide ref or selector."
+    };
+  }
+  const hash = await getPageScreenHash(page).catch(() => void 0);
+  const stale = !!(refMatch && hash && hash !== refMatch.screenHash);
+  if (!input.force) {
+    const check = await actionability(page, selector);
+    if (!check.ok) {
+      return {
+        action: input.action,
+        selector,
+        ref: normalizedRef,
+        success: false,
+        reason: stale ? "stale_ref" : check.reason,
+        message: stale ? `Ref "${input.ref}" may be stale. Run observe again.` : `Target is not actionable: ${check.reason}`,
+        stale,
+        screenHash: hash,
+        target: refMatch?.target
+      };
+    }
+  }
+  const timeout = input.timeout ?? 1e4;
+  try {
+    switch (input.action) {
+      case "click":
+        await page.locator(selector).first().click({ timeout, force: !!input.force });
+        break;
+      case "fill":
+        if (input.value === void 0) throw new Error("fill requires value");
+        await page.locator(selector).first().fill(input.value, { timeout, force: !!input.force });
+        break;
+      case "type":
+        if (input.value === void 0) throw new Error("type requires value");
+        await page.locator(selector).first().pressSequentially(input.value, { timeout });
+        break;
+      case "press":
+        if (!input.key) throw new Error("press requires key");
+        await page.locator(selector).first().press(input.key, { timeout });
+        break;
+      case "select":
+        if (input.value === void 0) throw new Error("select requires value");
+        await page.locator(selector).first().selectOption(input.value);
+        break;
+      case "check":
+        await page.locator(selector).first().check({ timeout });
+        break;
+      case "hover":
+        await page.locator(selector).first().hover({ timeout });
+        break;
+      default: {
+        const neverAction = input.action;
+        throw new Error(`Unsupported action: ${neverAction}`);
+      }
+    }
+  } catch (error) {
+    return {
+      action: input.action,
+      selector,
+      ref: normalizedRef,
+      success: false,
+      reason: "browser_error",
+      message: error.message,
+      stale,
+      screenHash: hash,
+      target: refMatch?.target
+    };
+  }
+  return {
+    action: input.action,
+    selector,
+    ref: normalizedRef,
+    success: true,
+    stale,
+    screenHash: hash,
+    target: refMatch?.target
+  };
+}
+function matchUrlPattern(url, pattern) {
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(url);
+  }
+  return url.includes(pattern);
+}
+async function pollUntil(timeout, pollInterval, predicate) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt <= timeout) {
+    if (await predicate()) return true;
+    await new Promise((resolve16) => setTimeout(resolve16, pollInterval));
+  }
+  return false;
+}
+async function waitForPage(page, input) {
+  const timeout = input.timeout ?? 3e4;
+  const pollInterval = input.pollInterval ?? 200;
+  const startedAt = Date.now();
+  try {
+    if (input.selector) {
+      const state = input.state ?? "visible";
+      await page.locator(input.selector).first().waitFor({ state, timeout });
+      return { success: true, matched: "selector", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.text) {
+      await page.getByText(input.text).first().waitFor({ state: "visible", timeout });
+      return { success: true, matched: "text", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.url) {
+      const matched = await pollUntil(timeout, pollInterval, async () => matchUrlPattern(page.url(), input.url));
+      return {
+        success: matched,
+        matched: "url",
+        timeout,
+        elapsed: Date.now() - startedAt,
+        ...matched ? {} : { message: `Timed out waiting for URL pattern: ${input.url}` }
+      };
+    }
+    if (input.load) {
+      await page.waitForLoadState(input.load, timeout);
+      return { success: true, matched: "load", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.fn) {
+      await page.waitForFunction(input.fn, void 0, { timeout });
+      return { success: true, matched: "fn", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.screenHashChanged) {
+      let screenHash = await getPageScreenHash(page);
+      const matched = await pollUntil(timeout, pollInterval, async () => {
+        screenHash = await getPageScreenHash(page);
+        return screenHash !== input.screenHashChanged;
+      });
+      return {
+        success: matched,
+        matched: "screenHashChanged",
+        timeout,
+        elapsed: Date.now() - startedAt,
+        screenHash,
+        ...matched ? {} : { message: `Timed out waiting for screen hash to change: ${input.screenHashChanged}` }
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      matched: input.selector ? "selector" : input.text ? "text" : input.url ? "url" : input.load ? "load" : input.fn ? "fn" : "screenHashChanged",
+      timeout,
+      elapsed: Date.now() - startedAt,
+      message: error.message
+    };
+  }
+  return {
+    success: false,
+    matched: "selector",
+    timeout,
+    elapsed: Date.now() - startedAt,
+    message: "Provide one wait predicate: selector, text, url, load, fn, or screenHashChanged."
+  };
+}
+
 // src/commands/snapshot.ts
 var snapshotCommand = registerCommand({
   name: "snapshot",
@@ -4622,7 +5051,14 @@ var snapshotCommand = registerCommand({
   parameters: z21.object({
     type: z21.enum(["aria", "text", "dom", "all"]).default("aria").describe("Snapshot type: aria (accessibility tree), text (visible text), dom (element summary), all (combined)"),
     selector: z21.string().optional().describe("Scope to a specific element"),
-    depth: z21.number().optional().default(6).describe("Max depth for DOM/aria tree")
+    depth: z21.number().optional().default(6).describe("Max depth for DOM/aria tree"),
+    interactive: z21.boolean().optional().default(false).describe("Return interactive agent refs only"),
+    interactiveOnly: z21.boolean().optional().default(false).describe("Alias for interactive"),
+    i: z21.boolean().optional().default(false).describe("Short alias for interactive"),
+    compact: z21.boolean().optional().default(false).describe("Include compact agent-browser style snapshot text"),
+    c: z21.boolean().optional().default(false).describe("Short alias for compact"),
+    selectors: z21.boolean().optional().default(false).describe("Include ref to CSS selector map"),
+    all: z21.boolean().optional().default(false).describe("Include hidden interactive targets when using interactive snapshot")
   }),
   result: z21.object({
     url: z21.string(),
@@ -4635,6 +5071,18 @@ var snapshotCommand = registerCommand({
     const page = ctx.page;
     const url = page.url();
     const title = await page.title().catch(() => "");
+    if (p.interactive || p.interactiveOnly || p.i || p.compact || p.c || p.selectors) {
+      const observation = await observePage(page, ctx.sessionId, {
+        includeHidden: p.all
+      });
+      if (p.selectors) observation.selectors = buildSelectorMap(observation);
+      if (p.compact || p.c || p.interactive || p.interactiveOnly || p.i) {
+        observation.compact = formatObservationCompact(observation, { selectors: p.selectors });
+      }
+      return ok20(observation, [
+        `refs refreshed for ${observation.targets.length} targets; use click @e1 or fill @e2 "text"`
+      ]);
+    }
     if (p.type === "aria") {
       const aria = await captureAriaSnapshot(page, p.selector, p.depth);
       const tips = await buildRefTips(page, aria);
@@ -4685,10 +5133,10 @@ async function buildRefTips(page, aria) {
     return [];
   }
 }
-async function captureAriaSnapshot(page, selector, depth) {
+async function captureAriaSnapshot(page, selector, _depth) {
   try {
     const locator = selector ? page.locator(selector).first() : page.locator("body");
-    return await locator.ariaSnapshot({ depth });
+    return await locator.ariaSnapshot();
   } catch {
     try {
       return await page.locator("body").ariaSnapshot();
@@ -4699,7 +5147,7 @@ async function captureAriaSnapshot(page, selector, depth) {
 }
 async function captureTextSnapshot(page, selector) {
   if (selector) {
-    return await page.locator(selector).first().innerText({ timeout: 5e3 }).catch(() => "");
+    return await page.locator(selector).first().innerText().catch(() => "");
   }
   return await page.evaluate(() => document.body?.innerText || "").catch(() => "");
 }
@@ -4735,22 +5183,108 @@ async function captureDomSnapshot(page, selector, maxDepth) {
   ).catch(() => ({ tag: "error" }));
 }
 
-// src/commands/tab.ts
+// src/commands/agent.ts
 import { z as z22 } from "zod";
-import { ok as ok21, fail as fail5 } from "@dyyz1993/xcli-core";
-var TabParams = z22.object({
-  subcommand: z22.enum(["list", "new", "close", "switch"]),
-  url: z22.string().optional(),
-  index: z22.number().int().min(0).optional()
+import { ok as ok21 } from "@dyyz1993/xcli-core";
+var observeCommand = registerCommand({
+  name: "observe",
+  description: "Observe the current page as structured agent targets with session refs",
+  scope: "page",
+  parameters: z22.object({
+    includeHidden: z22.boolean().optional().default(false).describe("Include hidden elements in the target list"),
+    limit: z22.number().int().positive().max(300).optional().default(80).describe("Maximum number of targets to return"),
+    compact: z22.boolean().optional().default(false).describe("Include compact agent-browser style snapshot text"),
+    selectors: z22.boolean().optional().default(false).describe("Include ref to stable CSS selector map")
+  }),
+  handler: async (p, ctx) => {
+    const observation = await observePage(ctx.page, ctx.sessionId, {
+      includeHidden: p.includeHidden,
+      limit: p.limit
+    });
+    if (p.selectors) observation.selectors = buildSelectorMap(observation);
+    if (p.compact) observation.compact = formatObservationCompact(observation, { selectors: p.selectors });
+    return ok21(observation, [
+      `refs refreshed for ${observation.targets.length} targets; use act --ref @e1 --action click or click @e1`
+    ]);
+  }
+});
+var actCommand = registerCommand({
+  name: "act",
+  description: "Perform an agent action using an observe ref or explicit selector",
+  scope: "element",
+  selectorParams: ["selector"],
+  parameters: z22.object({
+    action: z22.enum(["click", "fill", "type", "press", "select", "check", "hover"]).default("click"),
+    ref: z22.string().optional().describe("Session-scoped ref returned by observe, such as e1"),
+    selector: z22.string().optional().describe("CSS selector fallback when no ref is available"),
+    value: z22.string().optional().describe("Value for fill/type/select"),
+    key: z22.string().optional().describe("Key for press"),
+    force: z22.boolean().optional().default(false).describe("Bypass actionability checks"),
+    timeout: z22.number().optional().default(1e4).describe("Playwright action timeout in milliseconds")
+  }).refine((p) => !!p.ref || !!p.selector, {
+    message: "Either ref or selector is required"
+  }),
+  handler: async (p, ctx) => {
+    const result = await actOnPage(ctx.page, ctx.sessionId, { ...p });
+    if (!result.success) {
+      return {
+        success: false,
+        data: result,
+        message: result.message || result.reason || "Action failed",
+        tips: result.stale ? ["run observe again to refresh refs"] : []
+      };
+    }
+    return ok21(result, result.stale ? ["ref screen hash changed; run observe if the next action is uncertain"] : []);
+  }
+});
+var waitForCommand = registerCommand({
+  name: "waitFor",
+  description: "Wait for agent predicates such as text, URL, load state, selector state, or screen hash changes",
+  scope: "page",
+  selectorParams: ["selector"],
+  parameters: z22.object({
+    selector: z22.string().optional().describe("CSS selector or observe ref to wait for"),
+    state: z22.enum(["attached", "detached", "visible", "hidden"]).optional().default("visible"),
+    text: z22.string().optional().describe("Visible text to wait for"),
+    url: z22.string().optional().describe("URL substring or glob pattern to wait for"),
+    load: z22.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Load state to wait for"),
+    fn: z22.string().optional().describe("JavaScript predicate to wait for"),
+    screenHashChanged: z22.string().optional().describe("Previous screenHash from observe"),
+    timeout: z22.number().optional().default(3e4),
+    pollInterval: z22.number().optional().default(200)
+  }).refine((p) => [p.selector, p.text, p.url, p.load, p.fn, p.screenHashChanged].filter(Boolean).length === 1, {
+    message: "Provide exactly one wait predicate: selector, text, url, load, fn, or screenHashChanged"
+  }),
+  handler: async (p, ctx) => {
+    const result = await waitForPage(ctx.page, { ...p });
+    if (!result.success) {
+      return {
+        success: false,
+        data: result,
+        message: result.message || `Timed out waiting for ${result.matched}`,
+        tips: []
+      };
+    }
+    return ok21(result);
+  }
+});
+
+// src/commands/tab.ts
+import { z as z23 } from "zod";
+import { ok as ok22, fail as fail5 } from "@dyyz1993/xcli-core";
+var TabParams = z23.object({
+  subcommand: z23.enum(["list", "new", "close", "switch"]),
+  url: z23.string().optional(),
+  index: z23.number().int().min(0).optional()
 });
 var tabCommand = registerCommand({
   name: "tab",
   description: "Manage browser tabs: list, new, close, switch",
   scope: "page",
   parameters: TabParams,
-  result: z22.object({
-    success: z22.boolean(),
-    data: z22.unknown()
+  result: z23.object({
+    success: z23.boolean(),
+    data: z23.unknown()
   }),
   handler: async (p, ctx) => {
     const pages = ctx.browserContext.pages();
@@ -4790,7 +5324,7 @@ function handleList(pages, ctx) {
       active: i === currentIndex
     };
   });
-  return ok21({ tabs, total: tabs.length, activeIndex: currentIndex });
+  return ok22({ tabs, total: tabs.length, activeIndex: currentIndex });
 }
 async function handleNew(p, _pages, ctx) {
   const newPage = await ctx.browserContext.newPage();
@@ -4812,7 +5346,7 @@ async function handleNew(p, _pages, ctx) {
   const title = await newPage.title().catch(() => "");
   const allPages = ctx.browserContext.pages();
   const newIndex = allPages.indexOf(newPage);
-  return ok21({
+  return ok22({
     index: newIndex >= 0 ? newIndex : allPages.length - 1,
     url: newPage.url(),
     title,
@@ -4840,7 +5374,7 @@ async function handleClose(p, pages, ctx) {
     }
     ctx.page = newActivePage;
   }
-  return ok21({
+  return ok22({
     closedIndex: closeIndex,
     total: remainingPages.length,
     activeIndex: isActivePage ? closeIndex < remainingPages.length ? closeIndex : remainingPages.length - 1 : pages.indexOf(ctx.page)
@@ -4862,7 +5396,7 @@ async function handleSwitch(p, pages, ctx) {
   }
   ctx.page = targetPage;
   const title = await targetPage.title().catch(() => "");
-  return ok21({
+  return ok22({
     index: p.index,
     url: targetPage.url(),
     title,
@@ -4871,8 +5405,8 @@ async function handleSwitch(p, pages, ctx) {
 }
 
 // src/commands/addinitscript.ts
-import { z as z23 } from "zod";
-import { ok as ok22 } from "@dyyz1993/xcli-core";
+import { z as z24 } from "zod";
+import { ok as ok23 } from "@dyyz1993/xcli-core";
 import { readFileSync as readFileSync2 } from "fs";
 
 // src/chain-parser.ts
@@ -5050,7 +5584,7 @@ function parseCommandArgs(name, args) {
     } else {
       if (positionalIndex < positionalKeys.length) {
         const isLast = positionalIndex === positionalKeys.length - 1;
-        if (isLast && name === "eval") {
+        if (isLast && (name === "eval" || name === "find")) {
           const remaining = args.slice(i).map(unquote2).join(" ");
           params[positionalKeys[positionalIndex]] = remaining;
           break;
@@ -5100,7 +5634,7 @@ var commandDefCache = {
   frames: { positional: [] },
   frame: { positional: ["selector"] },
   actions: { positional: ["url"] },
-  find: { positional: ["strategy", "value"] },
+  find: { positional: ["strategy", "value", "operation"] },
   addinitscript: { positional: ["script"] },
   tab: { positional: ["subcommand"] }
 };
@@ -5112,14 +5646,14 @@ function registerCommandDefinition(name, positional) {
 }
 
 // src/commands/addinitscript.ts
-var InitScriptParams = z23.object({
-  script: z23.string().optional(),
-  file: z23.string().optional(),
-  stdin: z23.boolean().optional(),
-  name: z23.string().optional(),
-  list: z23.boolean().optional(),
-  remove: z23.string().optional(),
-  base64: z23.string().optional()
+var InitScriptParams = z24.object({
+  script: z24.string().optional(),
+  file: z24.string().optional(),
+  stdin: z24.boolean().optional(),
+  name: z24.string().optional(),
+  list: z24.boolean().optional(),
+  remove: z24.string().optional(),
+  base64: z24.string().optional()
 });
 var registeredScripts = /* @__PURE__ */ new Map();
 function resolveScriptContent(params) {
@@ -5160,15 +5694,15 @@ var addInitScriptCommand = registerCommand({
         size: content2.length,
         preview: content2.slice(0, 80)
       }));
-      return ok22({ scripts });
+      return ok23({ scripts });
     }
     if (params.remove) {
       const existed = registeredScripts.delete(params.remove);
-      return ok22({ removed: params.remove, existed });
+      return ok23({ removed: params.remove, existed });
     }
     let content = params.stdin ? await readStdin() : resolveScriptContent(params);
     if (!content) {
-      return ok22({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
+      return ok23({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
     }
     const scriptName = params.name ?? `script-${Date.now()}`;
     registeredScripts.set(scriptName, content);
@@ -5176,74 +5710,134 @@ var addInitScriptCommand = registerCommand({
     try {
       await ctx.page.evaluate(content);
     } catch {
-      return ok22({
+      return ok23({
         registered: scriptName,
         hint: "Script registered for future page loads; immediate execution skipped (page may not be ready)"
       });
     }
-    return ok22({ registered: scriptName, executedImmediately: true });
+    return ok23({ registered: scriptName, executedImmediately: true });
   }
 });
 registerCommandDefinition("addinitscript", ["script"]);
 
 // src/commands/find.ts
-import { z as z24 } from "zod";
-import { ok as ok23, fail as fail6 } from "@dyyz1993/xcli-core";
+import { z as z25 } from "zod";
+import { ok as ok24, fail as fail6 } from "@dyyz1993/xcli-core";
+var actionSchema2 = z25.enum(["click", "fill", "type", "select", "hover", "check"]);
 var findCommand = registerCommand({
   name: "find",
   description: "Find elements by semantic strategy (text/role/label/placeholder/testid) and optionally perform an action",
   scope: "page",
-  parameters: z24.object({
-    strategy: z24.enum(["text", "role", "label", "placeholder", "testid"]),
-    value: z24.string(),
-    name: z24.string().optional(),
-    exact: z24.boolean().optional().default(false),
-    click: z24.boolean().optional().default(false),
-    fill: z24.string().optional(),
-    type: z24.string().optional(),
-    select: z24.string().optional(),
-    timeout: z24.number().optional().default(1e4)
+  parameters: z25.object({
+    strategy: z25.enum(["text", "role", "label", "placeholder", "testid", "alt", "title", "first", "last", "nth"]),
+    value: z25.string(),
+    name: z25.string().optional(),
+    exact: z25.boolean().optional().default(false),
+    operation: z25.string().optional().describe('Trailing operation syntax, e.g. click, fill "text", type "text"'),
+    action: actionSchema2.optional().describe("Action to perform when not using trailing operation syntax"),
+    actionValue: z25.string().optional().describe("Value for fill/type/select when using action"),
+    index: z25.number().int().optional().describe("Index for nth strategy"),
+    click: z25.boolean().optional().default(false),
+    fill: z25.string().optional(),
+    type: z25.string().optional(),
+    select: z25.string().optional(),
+    hover: z25.boolean().optional().default(false),
+    check: z25.boolean().optional().default(false),
+    timeout: z25.number().optional().default(1e4)
   }),
-  result: z24.object({
-    matched: z24.number(),
-    selector: z24.string(),
-    action: z24.string().optional()
+  result: z25.object({
+    matched: z25.number(),
+    selector: z25.string(),
+    action: z25.string().optional()
   }),
   handler: async (p, ctx) => {
     const page = ctx.page;
-    const locator = buildLocator(page, p.strategy, p.value, {
+    const normalized = normalizeFindParams({ ...p });
+    const parsedOperation = parseOperation(normalized.operation);
+    const actionName = parsedOperation.action || p.action || inferLegacyAction(p);
+    const actionValue = parsedOperation.value ?? p.actionValue ?? p.fill ?? p.type ?? p.select;
+    const locator = buildLocator(page, normalized.strategy, normalized.value, {
       name: p.name,
-      exact: p.exact
+      exact: p.exact,
+      index: normalized.index
     });
     const count = await locator.count();
     if (count === 0) {
       return fail6(`No element found with ${p.strategy}="${p.value}"`);
     }
     const tips = [];
-    const target = locator.first();
+    const target = selectTarget(locator, p.strategy);
     if (count > 1) {
-      tips.push(`\u26A0\uFE0F Matched ${count} elements, using first`);
+      tips.push(`\u26A0\uFE0F Matched ${count} elements, used first match. Use 'find nth <index> ${normalized.strategy} "${normalized.value}" ${actionName || "click"}' for a specific match.`);
     }
-    const selector = describeSelector(p.strategy, p.value, p.name);
-    let action;
-    if (p.click) {
+    const selector = describeSelector(normalized.strategy, normalized.value, p.name);
+    if (actionName === "click") {
       await target.click({ timeout: p.timeout, force: true });
-      action = "click";
-    } else if (p.fill !== void 0) {
-      await target.fill(p.fill, { timeout: p.timeout, force: true });
-      action = `fill("${p.fill}")`;
-    } else if (p.type !== void 0) {
-      await target.type(p.type, { delay: 10, timeout: p.timeout });
-      action = `type("${p.type}")`;
-    } else if (p.select !== void 0) {
-      await target.selectOption(p.select, { timeout: p.timeout, force: true });
-      action = `select("${p.select}")`;
-    }
-    const result = ok23({ matched: count, selector, action });
-    if (tips.length > 0) result.tips = tips;
-    return result;
+      return okWithTips({ matched: count, selector, action: "click" }, tips);
+    } else if (actionName === "fill") {
+      if (actionValue === void 0) return fail6("find fill requires a value");
+      await target.fill(actionValue, { timeout: p.timeout, force: true });
+      return okWithTips({ matched: count, selector, action: `fill("${actionValue}")` }, tips);
+    } else if (actionName === "type") {
+      if (actionValue === void 0) return fail6("find type requires a value");
+      await target.type(actionValue, { delay: 10, timeout: p.timeout });
+      return okWithTips({ matched: count, selector, action: `type("${actionValue}")` }, tips);
+    } else if (actionName === "select") {
+      if (actionValue === void 0) return fail6("find select requires a value");
+      await target.selectOption(actionValue);
+      return okWithTips({ matched: count, selector, action: `select("${actionValue}")` }, tips);
+    } else if (actionName === "hover") {
+      await target.hover({ timeout: p.timeout, force: true });
+      return okWithTips({ matched: count, selector, action: "hover" }, tips);
+    } else if (actionName === "check") {
+      await target.check({ timeout: p.timeout });
+      return okWithTips({ matched: count, selector, action: "check" }, tips);
+    }
+    return okWithTips({ matched: count, selector }, tips);
   }
 });
+function okWithTips(data, tips) {
+  const result = ok24(data);
+  if (tips.length > 0) result.tips = tips;
+  return result;
+}
+function parseOperation(operation) {
+  if (!operation) return {};
+  const match = operation.trim().match(/^(\S+)(?:\s+([\s\S]+))?$/);
+  if (!match) return {};
+  const maybeAction = match[1];
+  const parsed = actionSchema2.safeParse(maybeAction);
+  if (!parsed.success) return {};
+  const rawValue = match[2];
+  const value = rawValue?.replace(/^["']|["']$/g, "");
+  return { action: parsed.data, ...value !== void 0 ? { value } : {} };
+}
+function normalizeFindParams(p) {
+  if (p.strategy !== "nth") return { strategy: p.strategy, value: p.value, operation: p.operation, index: p.index };
+  const parsedIndex = Number(p.value);
+  if (!Number.isInteger(parsedIndex) || !p.operation) {
+    return { strategy: p.strategy, value: p.value, operation: p.operation, index: p.index };
+  }
+  const match = p.operation.trim().match(/^(\S+)(?:\s+([\s\S]+))?$/);
+  if (!match) {
+    return { strategy: p.strategy, value: p.value, operation: p.operation, index: parsedIndex };
+  }
+  return {
+    strategy: p.strategy,
+    value: match[1].replace(/^["']|["']$/g, ""),
+    ...match[2] ? { operation: match[2] } : {},
+    index: parsedIndex
+  };
+}
+function inferLegacyAction(p) {
+  if (p.click) return "click";
+  if (p.fill !== void 0) return "fill";
+  if (p.type !== void 0) return "type";
+  if (p.select !== void 0) return "select";
+  if (p.hover) return "hover";
+  if (p.check) return "check";
+  return void 0;
+}
 function buildLocator(page, strategy, value, opts) {
   switch (strategy) {
     case "text":
@@ -5256,10 +5850,24 @@ function buildLocator(page, strategy, value, opts) {
       return page.getByPlaceholder(value, { exact: opts.exact });
     case "testid":
       return page.getByTestId(value);
+    case "alt":
+      return page.getByAltText(value, { exact: opts.exact });
+    case "title":
+      return page.getByTitle(value, { exact: opts.exact });
+    case "first":
+      return page.locator(value).first();
+    case "last":
+      return page.locator(value).last();
+    case "nth":
+      return page.locator(value).nth(opts.index ?? 0);
     default:
       return page.getByText(value, { exact: opts.exact });
   }
 }
+function selectTarget(locator, strategy) {
+  if (strategy === "first" || strategy === "last" || strategy === "nth") return locator;
+  return locator.first();
+}
 function describeSelector(strategy, value, name) {
   switch (strategy) {
     case "role":
@@ -5272,6 +5880,16 @@ function describeSelector(strategy, value, name) {
       return `getByPlaceholder("${value}")`;
     case "testid":
       return `getByTestId("${value}")`;
+    case "alt":
+      return `getByAltText("${value}")`;
+    case "title":
+      return `getByTitle("${value}")`;
+    case "first":
+      return `first("${value}")`;
+    case "last":
+      return `last("${value}")`;
+    case "nth":
+      return `nth("${value}")`;
     default:
       return `${strategy}("${value}")`;
   }
@@ -5394,7 +6012,7 @@ async function detectCaptcha2(page) {
 }
 async function detectWarningText(page) {
   try {
-    const pageText = await page.textContent("body", { timeout: 1e3 }).catch(() => "") || "";
+    const pageText = await page.textContent("body").catch(() => "") || "";
     const lowerText = pageText.toLowerCase();
     for (const { text, severity } of WARNING_TEXTS) {
       if (lowerText.includes(text.toLowerCase())) {
@@ -5525,8 +6143,8 @@ function formatDetectionMessage(result) {
 }
 
 // src/commands/promo.ts
-import { z as z25 } from "zod";
-import { ok as ok24 } from "@dyyz1993/xcli-core";
+import { z as z26 } from "zod";
+import { ok as ok25 } from "@dyyz1993/xcli-core";
 import { existsSync as existsSync2, readFileSync as readFileSync8 } from "fs";
 import { resolve as resolve6 } from "path";
 
@@ -5829,14 +6447,14 @@ async function dispatchPromo(config) {
 }
 
 // src/commands/promo.ts
-var promoParams = z25.object({
-  platform: z25.enum(["devto", "medium", "csdn", "juejin", "quora"]).describe("Target platform for promotion"),
-  file: z25.string().describe("Path to Markdown file to publish"),
-  tags: z25.string().optional().describe("Comma-separated tags"),
-  title: z25.string().optional().describe("Custom title (default: extracted from file first heading)"),
-  search: z25.string().optional().describe("Quora: search query to find questions"),
-  cdpEndpoint: z25.string().optional().describe("CDP endpoint for agent-browser"),
-  session: z25.string().optional().describe("agent-browser session name")
+var promoParams = z26.object({
+  platform: z26.enum(["devto", "medium", "csdn", "juejin", "quora"]).describe("Target platform for promotion"),
+  file: z26.string().describe("Path to Markdown file to publish"),
+  tags: z26.string().optional().describe("Comma-separated tags"),
+  title: z26.string().optional().describe("Custom title (default: extracted from file first heading)"),
+  search: z26.string().optional().describe("Quora: search query to find questions"),
+  cdpEndpoint: z26.string().optional().describe("CDP endpoint for agent-browser"),
+  session: z26.string().optional().describe("agent-browser session name")
 }).refine(
   (data) => data.platform !== "quora" || !!data.search,
   { message: "Quora platform requires --search parameter" }
@@ -5849,17 +6467,17 @@ var promoCommand = registerCommand({
   description: "Publish promotional articles to various platforms (devto, medium, csdn, juejin, quora)",
   scope: "project",
   parameters: promoParams,
-  result: z25.object({
-    success: z25.boolean(),
-    url: z25.string().optional(),
-    error: z25.string().optional(),
-    platform: z25.string()
+  result: z26.object({
+    success: z26.boolean(),
+    url: z26.string().optional(),
+    error: z26.string().optional(),
+    platform: z26.string()
   }),
   handler: async (p, _ctx) => {
     const filePath = resolve6(p.file);
     const content = readFileSync8(filePath, "utf-8");
     if (content.trim().length === 0) {
-      return ok24({
+      return ok25({
         success: false,
         error: `File is empty: ${filePath}`,
         platform: p.platform
@@ -5874,7 +6492,7 @@ var promoCommand = registerCommand({
       cdpEndpoint: p.cdpEndpoint ?? _ctx.cdpEndpoint,
       session: p.session ?? p.platform
     });
-    return ok24(result);
+    return ok25(result);
   }
 });
 
@@ -5962,7 +6580,7 @@ import { join as join2 } from "path";
 import { execSync as execSync6 } from "child_process";
 var SHARED_PLUGIN_DEPENDENCIES = {
   "zod": "^3.24.0",
-  "@dyyz1993/xcli-core": "^0.9.2"
+  "@dyyz1993/xcli-core": "^0.12.1"
 };
 function ensurePluginDependencies(pluginsDir) {
   const zodPath = join2(pluginsDir, "node_modules", "zod");
@@ -6001,6 +6619,192 @@ function ensurePluginDependencies(pluginsDir) {
   }
 }
 
+// src/plugin/contract.ts
+function buildPluginContract(site) {
+  const commands = site.getAllCommands().map((command) => buildCommandContract(site.getCommand?.(command.name) || command));
+  return {
+    version: 2,
+    plugin: {
+      name: site.name,
+      url: site.url,
+      description: site.config?.description,
+      requiresLogin: site.config?.requiresLogin
+    },
+    commands
+  };
+}
+function buildCommandContract(command) {
+  const extension = command.xbrowser || {};
+  const inferredFields = fieldsFromZodObject(command.parameters);
+  const fields = mergeFields(inferredFields, extension.form?.fields || []);
+  const positional = extension.positional || fields.filter((field) => field.positional).map((field) => field.name);
+  const capabilities = extension.capabilities || inferCapabilities(command.scope || "project", command.requiresLogin);
+  const outputSchema = command.result ? summarizeZod(command.result) : void 0;
+  return {
+    name: command.name,
+    description: command.description || "",
+    scope: command.scope || "project",
+    requiresLogin: command.requiresLogin === true,
+    category: extension.category,
+    capabilities,
+    positional,
+    form: {
+      title: extension.form?.title || command.description || command.name,
+      description: extension.form?.description,
+      submitLabel: extension.form?.submitLabel || "Run",
+      fields
+    },
+    output: extension.output || (outputSchema ? { schema: outputSchema } : void 0)
+  };
+}
+function fieldsFromZodObject(schema) {
+  const shape = getShape(schema);
+  if (!shape) return [];
+  return Object.entries(shape).map(([name, field]) => fieldFromZod(name, field));
+}
+function fieldFromZod(name, schema) {
+  const unwrapped = unwrapZod(schema);
+  const type = zodTypeToContractType(unwrapped.typeName);
+  const enumValues = extractEnumValues(unwrapped.schema);
+  return {
+    name,
+    label: toLabel(name),
+    type,
+    widget: widgetFor(type, enumValues, unwrapped.schema),
+    required: !unwrapped.optional,
+    ...unwrapped.description ? { description: unwrapped.description } : {},
+    ...unwrapped.defaultValue !== void 0 ? { default: unwrapped.defaultValue } : {},
+    ...enumValues ? { enum: enumValues } : {},
+    ...type === "array" ? { multiple: true } : {}
+  };
+}
+function mergeFields(inferred, overrides) {
+  if (overrides.length === 0) return inferred;
+  const byName = new Map(inferred.map((field) => [field.name, field]));
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const override of overrides) {
+    if (!override.name) continue;
+    const base = byName.get(override.name) || {
+      name: override.name,
+      label: toLabel(override.name),
+      type: "string",
+      widget: "text",
+      required: false
+    };
+    merged.push({ ...base, ...override, name: override.name });
+    seen.add(override.name);
+  }
+  for (const field of inferred) {
+    if (!seen.has(field.name)) merged.push(field);
+  }
+  return merged;
+}
+function inferCapabilities(scope, requiresLogin) {
+  const caps = [];
+  if (scope === "page") caps.push("browser.page");
+  if (scope === "browser") caps.push("browser.context");
+  if (requiresLogin) caps.push("auth.login");
+  return caps;
+}
+function getShape(schema) {
+  const zod = schema;
+  const shapeOrFn = zod?.shape ?? zod?._def?.shape;
+  if (!shapeOrFn) return void 0;
+  return typeof shapeOrFn === "function" ? shapeOrFn() : shapeOrFn;
+}
+function unwrapZod(schema) {
+  let current = schema;
+  let optional = typeof current?.isOptional === "function" ? current.isOptional() : false;
+  let description = current?._def?.description;
+  let defaultValue;
+  for (let i = 0; i < 8; i++) {
+    const def = current?._def;
+    const typeName = def?.typeName || "unknown";
+    if (def?.description) description = def.description;
+    if (!def) return { schema: current, typeName, optional, description, defaultValue };
+    if (typeName === "ZodDefault") {
+      optional = true;
+      defaultValue = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+      current = def.innerType || def.type;
+      continue;
+    }
+    if (typeName === "ZodOptional" || typeName === "ZodNullable") {
+      optional = true;
+      current = def.innerType || def.type;
+      continue;
+    }
+    return { schema: current, typeName, optional, description, defaultValue };
+  }
+  return { schema: current, typeName: current?._def?.typeName || "unknown", optional, description, defaultValue };
+}
+function zodTypeToContractType(typeName) {
+  switch (typeName) {
+    case "ZodString":
+      return "string";
+    case "ZodNumber":
+      return "number";
+    case "ZodBoolean":
+      return "boolean";
+    case "ZodEnum":
+    case "ZodNativeEnum":
+      return "enum";
+    case "ZodArray":
+      return "array";
+    case "ZodObject":
+      return "object";
+    default:
+      return typeName.replace(/^Zod/, "").toLowerCase() || "unknown";
+  }
+}
+function widgetFor(type, enumValues, schema) {
+  if (enumValues) return "select";
+  if (type === "boolean") return "checkbox";
+  if (type === "number") return "number";
+  if (type === "array") return "multi-select";
+  if (type === "object") return "json";
+  const checks = schema?._def?.checks;
+  if (checks?.some((check) => check.kind === "url")) return "url";
+  return "text";
+}
+function extractEnumValues(schema) {
+  const def = schema?._def;
+  const values = def?.values;
+  if (Array.isArray(values)) return values.map(String);
+  return void 0;
+}
+function summarizeZod(schema) {
+  const unwrapped = unwrapZod(schema);
+  if (unwrapped.typeName === "ZodArray") {
+    const def = unwrapped.schema?._def;
+    return {
+      type: "array",
+      items: summarizeZod(def?.type || def?.innerType)
+    };
+  }
+  const shape = getShape(schema);
+  if (!shape) {
+    return {
+      type: zodTypeToContractType(unwrapped.typeName),
+      required: !unwrapped.optional,
+      ...unwrapped.description ? { description: unwrapped.description } : {}
+    };
+  }
+  return Object.fromEntries(
+    Object.entries(shape).map(([name, field]) => {
+      const unwrapped2 = unwrapZod(field);
+      return [name, {
+        type: zodTypeToContractType(unwrapped2.typeName),
+        required: !unwrapped2.optional,
+        ...unwrapped2.description ? { description: unwrapped2.description } : {}
+      }];
+    })
+  );
+}
+function toLabel(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim().replace(/^./, (char) => char.toUpperCase());
+}
+
 // src/plugin/loader.ts
 var DEFAULT_PLUGIN_DIRS = [".xcli/plugins", "../.xcli/plugins"];
 var XBrowserPluginLoader = class {
@@ -6043,6 +6847,13 @@ var XBrowserPluginLoader = class {
   getLoadedPlugins() {
     return this.loader.getLoadedPlugins();
   }
+  getPluginContract(siteName, commandName) {
+    const site = this.core.loader.getSite(siteName);
+    if (!site) return void 0;
+    const contract = buildPluginContract(site);
+    if (!commandName) return contract;
+    return contract.commands.find((command) => command.name === commandName);
+  }
   async loadPlugin(pluginPath, id) {
     return this.loader.loadPlugin(pluginPath, id);
   }
@@ -6546,45 +7357,13 @@ async function loadHooks() {
 // src/executor.ts
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
-import { existsSync as existsSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
 var NAVIGATION_COMMANDS = /* @__PURE__ */ new Set(["goto", "back", "forward", "refresh"]);
 var snapshotHintShown = /* @__PURE__ */ new WeakSet();
 var STORAGE_DIR = join3(homedir3(), ".xbrowser", "storage");
 var storageCache = /* @__PURE__ */ new Map();
 function getPluginStorage(pluginName) {
   if (!storageCache.has(pluginName)) {
-    const filePath = join3(STORAGE_DIR, `${pluginName}.json`);
-    let data = {};
-    const load3 = () => {
-      if (existsSync6(filePath)) {
-        try {
-          data = JSON.parse(readFileSync9(filePath, "utf-8"));
-        } catch {
-          data = {};
-        }
-      }
-    };
-    const save = () => {
-      mkdirSync3(STORAGE_DIR, { recursive: true });
-      writeFileSync4(filePath, JSON.stringify(data, null, 2), "utf-8");
-    };
-    load3();
-    storageCache.set(pluginName, {
-      get: async (key) => data[key] ?? null,
-      set: async (key, value) => {
-        data[key] = value;
-        save();
-      },
-      delete: async (key) => {
-        delete data[key];
-        save();
-      },
-      clear: async () => {
-        data = {};
-        save();
-      },
-      keys: async () => Object.keys(data)
-    });
+    storageCache.set(pluginName, new PluginStorage(pluginName, STORAGE_DIR));
   }
   return storageCache.get(pluginName);
 }
@@ -6648,7 +7427,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-I2HJZ7IP.js");
+    const { findTargetPage } = await import("./browser-53KUFEEM.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.`);
@@ -6665,7 +7444,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-3IJD6X4B.js");
+    const { forwardExec } = await import("./daemon-client-YAVQ343A.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -6673,7 +7452,18 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   const existing = await findOrRestoreSession(sessionName, extraOpts?.cdpEndpoint);
   if (existing) {
     session = existing;
-    if (targetPageOverride && session.page) {
+    if (session.page) {
+      try {
+        await Promise.race([
+          session.page.evaluate(() => true),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 3e3))
+        ]);
+      } catch {
+        await closeSessionByName(session.name);
+        session = void 0;
+      }
+    }
+    if (session && targetPageOverride && session.page) {
       const currentUrl = session.page.url();
       if (currentUrl !== targetPageOverride.url) {
         await session.page.goto(targetPageOverride.url, { waitUntil: "domcontentloaded", timeout: 15e3 }).catch(() => {
@@ -6684,6 +7474,10 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     session = await createSession(sessionName, params.url, {
       cdpEndpoint: extraOpts?.cdpEndpoint
     });
+  } else if (command.scope === "browser") {
+    session = await createSession(sessionName, void 0, {
+      cdpEndpoint: extraOpts?.cdpEndpoint
+    });
   } else if (command.scope !== "project") {
     return errorResult(
       `Session '${sessionName}' not found. Run "xbrowser session open <url>" first.`
@@ -6694,7 +7488,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     browser: session?.context.browser(),
     browserContext: session?.context,
     sessionId: session?.id,
-    cdpEndpoint: extraOpts?.cdpEndpoint || session?.cdpEndpoint,
+    cdpEndpoint: session?.cdpEndpoint || extraOpts?.cdpEndpoint,
     args: [],
     options: {},
     cwd: process.cwd(),
@@ -6729,7 +7523,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   let refTips = [];
   if (session?.page && command.selectorParams && command.selectorParams.length > 0) {
     const cache = /* @__PURE__ */ new Map();
-    const resolved = await resolveRefParams(session.page, params, command.selectorParams, cache);
+    const resolved = await resolveRefParams(session.page, params, command.selectorParams, cache, session.id);
     if (resolved.tips.length > 0) {
       refTips = resolved.tips;
       params = resolved.params;
@@ -6799,7 +7593,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
         timestamp: start
       });
       if (isSuccess) {
-        return { ...ok25(raw.data, merged.length > 0 ? merged : raw.tips), duration, ...hookOutputs ? { hookOutputs } : {} };
+        return { ...ok26(raw.data, merged.length > 0 ? merged : raw.tips), duration, ...hookOutputs ? { hookOutputs } : {} };
       }
       return { success: false, data: raw.data, message: raw.message, tips: merged.length > 0 ? merged : raw.tips || [], duration, ...hookOutputs ? { hookOutputs } : {} };
     }
@@ -6812,7 +7606,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       duration,
       timestamp: start
     });
-    return { ...ok25(raw, smartTips), duration, ...hookOutputs ? { hookOutputs } : {} };
+    return { ...ok26(raw, smartTips), duration, ...hookOutputs ? { hookOutputs } : {} };
   } catch (err) {
     const end = Date.now();
     const duration = end - start;
@@ -6960,7 +7754,7 @@ async function executeChain(input, options) {
             results.push({
               command: `${cmdName} ${subCommand}`,
               raw: cmdStr,
-              ...ok25(data),
+              ...ok26(data),
               duration: duration2,
               ...hookOutputs ? { hookOutputs } : {}
             });
@@ -7235,13 +8029,13 @@ var sessionListBuiltin = {
   },
   execute: async () => {
     try {
-      const sessions = await listSessions();
-      if (sessions.length === 0) {
+      const sessions2 = await listSessions();
+      if (sessions2.length === 0) {
         console.log("No active sessions");
         return;
       }
       console.log("Active sessions:");
-      for (const s of sessions) {
+      for (const s of sessions2) {
         console.log(`  ${s.name} (${s.id})`);
       }
     } catch (e) {
@@ -7333,26 +8127,26 @@ var configBuiltin = {
 
 // src/plugin/installer.ts
 import {
-  existsSync as existsSync13,
+  existsSync as existsSync12,
   readdirSync as readdirSync3,
-  mkdirSync as mkdirSync8,
+  mkdirSync as mkdirSync7,
   rmSync as rmSync7
 } from "fs";
 import { resolve as resolve15, basename as basename2 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/plugin/install-sources/local.ts
-import { existsSync as existsSync8, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync7, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
 import { resolve as resolve10 } from "path";
 
 // src/plugin/install-utils.ts
 import {
-  existsSync as existsSync7,
+  existsSync as existsSync6,
   readdirSync as readdirSync2,
   cpSync,
   rmSync,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync10,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync9,
   createWriteStream
 } from "fs";
 import { resolve as resolve9 } from "path";
@@ -7423,7 +8217,7 @@ async function downloadToFile(url, destPath) {
   await pipeline(nodeStream, createWriteStream(destPath));
 }
 function extractTarGz(tarballPath, targetDir) {
-  mkdirSync4(targetDir, { recursive: true });
+  mkdirSync3(targetDir, { recursive: true });
   execSync7(`tar -xzf "${tarballPath}" -C "${targetDir}"`, { stdio: "pipe" });
 }
 function flattenPackageRoot(targetDir) {
@@ -7444,18 +8238,18 @@ function flattenPackageRoot(targetDir) {
 async function verifyPlugin(dir) {
   const warnings = [];
   const indexPath = resolve9(dir, "index.ts");
-  if (!existsSync7(indexPath)) {
+  if (!existsSync6(indexPath)) {
     const indexJs = resolve9(dir, "index.js");
-    if (!existsSync7(indexJs)) {
+    if (!existsSync6(indexJs)) {
       return { valid: false, error: "No index.ts or index.js entry point found", warnings };
     }
   }
   const pkgPath = resolve9(dir, "package.json");
-  if (!existsSync7(pkgPath)) {
+  if (!existsSync6(pkgPath)) {
     warnings.push("No package.json found");
   } else {
     try {
-      const pkg2 = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+      const pkg2 = JSON.parse(readFileSync9(pkgPath, "utf-8"));
       if (!pkg2.xbrowser) {
         warnings.push("No xbrowser metadata in package.json");
       }
@@ -7475,7 +8269,7 @@ function safeCleanup(dir) {
 // src/plugin/install-sources/local.ts
 async function installFromLocal(source, name, targetDir) {
   const srcPath = resolve10(source);
-  if (!existsSync8(srcPath)) {
+  if (!existsSync7(srcPath)) {
     throw new Error(`Local path does not exist: ${srcPath}`);
   }
   const tmpTarget = `${targetDir}-tmp-${Date.now()}`;
@@ -7488,7 +8282,7 @@ async function installFromLocal(source, name, targetDir) {
       safeCleanup(tmpTarget);
       throw new Error(`Invalid plugin: ${verify.error}`);
     }
-    if (existsSync8(targetDir)) {
+    if (existsSync7(targetDir)) {
       rmSync2(targetDir, { recursive: true, force: true });
     }
     cpSync2(tmpTarget, targetDir, { recursive: true, force: true });
@@ -7508,7 +8302,7 @@ async function installFromLocal(source, name, targetDir) {
 }
 
 // src/plugin/install-sources/npm.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync4, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
 import { resolve as resolve11, join as join4 } from "path";
 import { tmpdir } from "os";
 async function installFromNpm(packageName, name, targetDir) {
@@ -7529,7 +8323,7 @@ async function installFromNpm(packageName, name, targetDir) {
   }
   const tarballUrl = versionMeta.dist.tarball;
   const tmpDir = join4(tmpdir(), `xbrowser-npm-${Date.now()}`);
-  mkdirSync5(tmpDir, { recursive: true });
+  mkdirSync4(tmpDir, { recursive: true });
   let warnings = [];
   try {
     const tarballPath = join4(tmpDir, `${name}.tgz`);
@@ -7542,16 +8336,16 @@ async function installFromNpm(packageName, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid npm plugin: ${verify.error}`);
     }
-    if (existsSync9(targetDir)) {
+    if (existsSync8(targetDir)) {
       rmSync3(targetDir, { recursive: true, force: true });
     }
     cpSync3(extractDir, targetDir, { recursive: true, force: true });
     const pkgPath = resolve11(targetDir, "package.json");
-    if (existsSync9(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+    if (existsSync8(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync10(pkgPath, "utf-8"));
       if (!pkg2._npmSource) {
         pkg2._npmSource = { name: packageName, version: latestVersion };
-        writeFileSync5(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync4(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7568,7 +8362,7 @@ async function installFromNpm(packageName, name, targetDir) {
 }
 
 // src/plugin/install-sources/git.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12, writeFileSync as writeFileSync6, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync5, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
 import { resolve as resolve12, join as join5 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 import { execSync as execSync8 } from "child_process";
@@ -7582,17 +8376,17 @@ async function installFromGit(gitUrl, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid git plugin: ${verify.error}`);
     }
-    if (existsSync10(targetDir)) {
+    if (existsSync9(targetDir)) {
       rmSync4(targetDir, { recursive: true, force: true });
     }
     cpSync4(tmpDir, targetDir, { recursive: true, force: true });
     rmSync4(resolve12(targetDir, ".git"), { recursive: true, force: true });
     const pkgPath = resolve12(targetDir, "package.json");
-    if (existsSync10(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    if (existsSync9(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
       if (!pkg2._gitSource) {
         pkg2._gitSource = { url: gitUrl };
-        writeFileSync6(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync5(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7609,12 +8403,12 @@ async function installFromGit(gitUrl, name, targetDir) {
 }
 
 // src/plugin/install-sources/url.ts
-import { existsSync as existsSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync7, mkdirSync as mkdirSync6, rmSync as rmSync5, cpSync as cpSync5 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync12, writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, rmSync as rmSync5, cpSync as cpSync5 } from "fs";
 import { resolve as resolve13, join as join6, basename } from "path";
 import { tmpdir as tmpdir3 } from "os";
 async function installFromUrl(url, name, targetDir) {
   const tmpDir = join6(tmpdir3(), `xbrowser-url-${Date.now()}`);
-  mkdirSync6(tmpDir, { recursive: true });
+  mkdirSync5(tmpDir, { recursive: true });
   let warnings = [];
   try {
     const fileName = basename(new URL(url).pathname) || "plugin.tar.gz";
@@ -7628,16 +8422,16 @@ async function installFromUrl(url, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid plugin from URL: ${verify.error}`);
     }
-    if (existsSync11(targetDir)) {
+    if (existsSync10(targetDir)) {
       rmSync5(targetDir, { recursive: true, force: true });
     }
     cpSync5(extractDir, targetDir, { recursive: true, force: true });
     const pkgPath = resolve13(targetDir, "package.json");
-    if (existsSync11(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    if (existsSync10(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
       if (!pkg2._urlSource) {
         pkg2._urlSource = { url };
-        writeFileSync7(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync6(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7655,10 +8449,10 @@ async function installFromUrl(url, name, targetDir) {
 
 // src/plugin/install-sources/marketplace.ts
 import {
-  existsSync as existsSync12,
-  mkdirSync as mkdirSync7,
-  writeFileSync as writeFileSync8,
-  readFileSync as readFileSync14,
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync6,
+  writeFileSync as writeFileSync7,
+  readFileSync as readFileSync13,
   rmSync as rmSync6,
   cpSync as cpSync6
 } from "fs";
@@ -7680,12 +8474,12 @@ async function installFromMarketplace(pluginsDir, slug, options) {
   const plugin = detailData.data;
   const name = options?.name || String(plugin.slug || slug);
   const targetDir = resolve14(pluginsDir, name);
-  if (existsSync12(targetDir) && !options?.force) {
+  if (existsSync11(targetDir) && !options?.force) {
     throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
   }
-  mkdirSync7(targetDir, { recursive: true });
+  mkdirSync6(targetDir, { recursive: true });
   const tmpDir = join7(tmpdir4(), `xbrowser-marketplace-${Date.now()}`);
-  mkdirSync7(tmpDir, { recursive: true });
+  mkdirSync6(tmpDir, { recursive: true });
   const realSlug = String(plugin.slug || slug);
   try {
     await downloadAndExtractMarketplaceTarball(baseUrl, realSlug, tmpDir, targetDir);
@@ -7715,14 +8509,14 @@ function isManifestArray(data) {
   return Array.isArray(data) && data.length > 0 && typeof data[0].path === "string" && typeof data[0].content === "string";
 }
 function extractManifestToDir(manifest, targetDir) {
-  if (existsSync12(targetDir)) {
+  if (existsSync11(targetDir)) {
     rmSync6(targetDir, { recursive: true, force: true });
   }
-  mkdirSync7(targetDir, { recursive: true });
+  mkdirSync6(targetDir, { recursive: true });
   for (const file of manifest) {
     const filePath = resolve14(targetDir, file.path);
-    mkdirSync7(dirname2(filePath), { recursive: true });
-    writeFileSync8(filePath, Buffer.from(file.content, "base64"));
+    mkdirSync6(dirname2(filePath), { recursive: true });
+    writeFileSync7(filePath, Buffer.from(file.content, "base64"));
   }
 }
 function tryParseAsGzippedManifest(buffer) {
@@ -7749,7 +8543,7 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
     const redirectUrl = tarballRes.headers.get("location");
     const tarballPath = join7(tmpDir, `${slug}.tar.gz`);
     await downloadToFile(redirectUrl, tarballPath);
-    const buffer = readFileSync14(tarballPath);
+    const buffer = readFileSync13(tarballPath);
     const manifest = tryParseAsGzippedManifest(buffer);
     if (manifest) {
       extractManifestToDir(manifest, targetDir);
@@ -7758,7 +8552,7 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
     const extractDir = join7(tmpDir, "extracted");
     extractTarGz(tarballPath, extractDir);
     flattenPackageRoot(extractDir);
-    if (existsSync12(targetDir)) {
+    if (existsSync11(targetDir)) {
       rmSync6(targetDir, { recursive: true, force: true });
     }
     cpSync6(extractDir, targetDir, { recursive: true, force: true });
@@ -7770,12 +8564,12 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
       return;
     }
     const tarballPath = join7(tmpDir, `${slug}.tar.gz`);
-    writeFileSync8(tarballPath, buffer);
+    writeFileSync7(tarballPath, buffer);
     try {
       const extractDir = join7(tmpDir, "extracted");
       extractTarGz(tarballPath, extractDir);
       flattenPackageRoot(extractDir);
-      if (existsSync12(targetDir)) {
+      if (existsSync11(targetDir)) {
         rmSync6(targetDir, { recursive: true, force: true });
       }
       cpSync6(extractDir, targetDir, { recursive: true, force: true });
@@ -7811,24 +8605,24 @@ function writeMarketplacePackageJson(plugin, slug, name, baseUrl, targetDir) {
     }
   };
   const pkgPath = resolve14(targetDir, "package.json");
-  if (!existsSync12(pkgPath)) {
-    writeFileSync8(pkgPath, JSON.stringify(packageJson, null, 2));
+  if (!existsSync11(pkgPath)) {
+    writeFileSync7(pkgPath, JSON.stringify(packageJson, null, 2));
   } else {
     try {
-      const existing = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+      const existing = JSON.parse(readFileSync13(pkgPath, "utf-8"));
       const merged = {
         ...existing,
         xbrowser: { ...existing.xbrowser, ...packageJson.xbrowser },
         _marketplace: packageJson._marketplace
       };
-      writeFileSync8(pkgPath, JSON.stringify(merged, null, 2));
+      writeFileSync7(pkgPath, JSON.stringify(merged, null, 2));
     } catch {
-      writeFileSync8(pkgPath, JSON.stringify(packageJson, null, 2));
+      writeFileSync7(pkgPath, JSON.stringify(packageJson, null, 2));
     }
   }
 }
 function ensureIndexFile(plugin, name, targetDir) {
-  if (!existsSync12(resolve14(targetDir, "index.ts")) && !existsSync12(resolve14(targetDir, "index.js"))) {
+  if (!existsSync11(resolve14(targetDir, "index.ts")) && !existsSync11(resolve14(targetDir, "index.js"))) {
     const commands = plugin.commands || [];
     const commandHandlers = commands.length > 0 ? commands.map((cmd) => {
       return [
@@ -7843,7 +8637,7 @@ function ensureIndexFile(plugin, name, targetDir) {
       `    handler: async () => ({ data: { message: 'Hello from ${name}!' }, tips: [] }),`,
       `  });`
     ].join("\n");
-    writeFileSync8(
+    writeFileSync7(
       resolve14(targetDir, "index.ts"),
       [
         `import type { XCLIAPI } from '@dyyz1993/xcli-core';`,
@@ -7882,10 +8676,10 @@ var PluginInstaller = class {
     const type = this.detectSourceType(source);
     const name = options?.name || this.deriveName(source, type);
     const targetDir = resolve15(this.pluginsDir, name);
-    if (existsSync13(targetDir) && !options?.force) {
+    if (existsSync12(targetDir) && !options?.force) {
       throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
     }
-    mkdirSync8(targetDir, { recursive: true });
+    mkdirSync7(targetDir, { recursive: true });
     const resolvedSource = type === "npm" ? await resolveNpmPackageWithFallback(source) : source;
     switch (type) {
       case "local":
@@ -7943,7 +8737,7 @@ var PluginInstaller = class {
    */
   async uninstall(name) {
     const targetDir = resolve15(this.pluginsDir, name);
-    if (!existsSync13(targetDir)) {
+    if (!existsSync12(targetDir)) {
       throw new Error(`Plugin "${name}" not found`);
     }
     rmSync7(targetDir, { recursive: true, force: true });
@@ -7954,7 +8748,7 @@ var PluginInstaller = class {
    * @returns Array of installed plugin information.
    */
   async list(_options) {
-    if (!existsSync13(this.pluginsDir)) return [];
+    if (!existsSync12(this.pluginsDir)) return [];
     const entries = readdirSync3(this.pluginsDir, { withFileTypes: true });
     const plugins = [];
     for (const entry of entries) {
@@ -7962,7 +8756,7 @@ var PluginInstaller = class {
       const pluginPath = resolve15(this.pluginsDir, entry.name);
       const indexPath = resolve15(pluginPath, "index.ts");
       const indexJsPath = resolve15(pluginPath, "index.js");
-      if (!existsSync13(indexPath) && !existsSync13(indexJsPath)) continue;
+      if (!existsSync12(indexPath) && !existsSync12(indexJsPath)) continue;
       const metadata = PluginMetadataParser.parseFromPackageJson(pluginPath);
       let source = "local";
       const pkg2 = readJsonFile(resolve15(pluginPath, "package.json"), {});
@@ -7989,10 +8783,10 @@ var PluginInstaller = class {
     }
     if (source.startsWith("file://")) {
       const filePath = decodeURIComponent(new URL(source).pathname);
-      if (existsSync13(filePath)) return "url";
+      if (existsSync12(filePath)) return "url";
     }
     if (source.endsWith(".git") || source.includes("github.com/")) return "git";
-    if (existsSync13(resolve15(source))) return "local";
+    if (existsSync12(resolve15(source))) return "local";
     return "npm";
   }
   deriveName(source, type) {
@@ -8067,6 +8861,7 @@ function handlePluginHelp() {
     "  install <slug> --from-marketplace             Install from marketplace",
     "  uninstall <name>                              Uninstall a plugin",
     "  list [--json]                                 List installed plugins",
+    "  schema <name> [command] [--json]              Show plugin contract and command forms",
     "  reload <name>                                 Reload a plugin",
     "",
     "Examples:",
@@ -8075,6 +8870,7 @@ function handlePluginHelp() {
     "  xbrowser plugin install ./my-plugin",
     "  xbrowser plugin uninstall my-plugin",
     "  xbrowser plugin list",
+    "  xbrowser plugin schema my-plugin --json",
     "  xbrowser plugin reload my-plugin"
   ].join("\n");
 }
@@ -9137,6 +9933,25 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         cmdName = "text";
         params = { selector: options.selector || options.s };
         break;
+      case "find": {
+        if (!args[0] || !args[1]) {
+          outputError("Usage: xbrowser find <text|role|label|placeholder|testid|alt|title|first|last|nth> <value> [action] [--name <name>]");
+        }
+        const strategy = args[0];
+        const value = args[1];
+        const operation = args.slice(2).join(" ") || void 0;
+        cmdName = "find";
+        params = {
+          strategy,
+          value,
+          ...operation ? { operation } : {},
+          name: options.name,
+          exact: !!options.exact,
+          timeout: options.timeout ? Number(options.timeout) : void 0,
+          index: options.index ? Number(options.index) : void 0
+        };
+        break;
+      }
       case "back":
         cmdName = "back";
         params = {};
@@ -9328,11 +10143,11 @@ async function handleSession(args, options, mode, cdpEndpoint) {
     case "list":
     case "ls": {
       try {
-        const sessions = await forwardSessionList();
-        outputResult({ sessions }, mode);
+        const sessions2 = await forwardSessionList();
+        outputResult({ sessions: sessions2 }, mode);
       } catch {
-        const sessions = await listSessions();
-        outputResult({ sessions }, mode);
+        const sessions2 = await listSessions();
+        outputResult({ sessions: sessions2 }, mode);
       }
       break;
     }
@@ -9352,8 +10167,8 @@ async function handleSession(args, options, mode, cdpEndpoint) {
     }
     case "kill-all": {
       try {
-        const sessions = await forwardSessionList();
-        for (const s of sessions) {
+        const sessions2 = await forwardSessionList();
+        for (const s of sessions2) {
           try {
             await forwardSessionClose(s.name);
           } catch {
@@ -9380,15 +10195,28 @@ function getPluginLoader2() {
   if (!pluginLoader3) pluginLoader3 = new XBrowserPluginLoader();
   return pluginLoader3;
 }
-async function buildRuntimeCommandsMap() {
+async function buildRuntimePluginInfo() {
   const loader = await getPluginLoader();
   const sites = loader.getCore().loader.getSites();
   const map = /* @__PURE__ */ new Map();
   for (const site of sites) {
-    const cmds = site.getAllCommands().map((c) => c.name);
-    if (cmds.length > 0) {
-      map.set(site.name, cmds);
+    const cmds = site.getAllCommands();
+    const commandNames = cmds.map((c) => c.name);
+    if (commandNames.length === 0) continue;
+    const anySite = site;
+    const hasLoginHandler = typeof anySite.hasLoginCommand === "function" && anySite.hasLoginCommand();
+    const configRequiresLogin = !!site.config.requiresLogin;
+    const hasLogin = hasLoginHandler || configRequiresLogin;
+    let loggedIn = null;
+    if (hasLogin) {
+      try {
+        loggedIn = await site.isLoggedIn();
+      } catch {
+        loggedIn = null;
+      }
     }
+    const requiresLoginCommands = cmds.filter((c) => c.requiresLogin === true).map((c) => c.name);
+    map.set(site.name, { commands: commandNames, hasLogin, loggedIn, requiresLoginCommands });
   }
   return map;
 }
@@ -9552,6 +10380,54 @@ async function handlePluginInfo(args, options, mode) {
     console.error("\u67E5\u8BE2\u5931\u8D25:", err.message);
   }
 }
+async function handlePluginSchema(args, mode) {
+  const pluginName = args[0];
+  const commandName = args[1];
+  if (!pluginName) outputError("Usage: xbrowser plugin schema <name> [command] [--json]");
+  const loader = await getPluginLoader();
+  const contract = loader.getPluginContract(pluginName, commandName);
+  if (!contract) {
+    outputError(commandName ? `Command "${commandName}" not found in plugin "${pluginName}"` : `Plugin "${pluginName}" not found`);
+    return;
+  }
+  if (mode === "json") {
+    outputResult(contract, mode);
+    return;
+  }
+  if ("commands" in contract) {
+    printPluginContract(contract);
+  } else {
+    printCommandContract(pluginName, contract);
+  }
+}
+function printPluginContract(contract) {
+  console.log(`${contract.plugin.name} contract v${contract.version}`);
+  if (contract.plugin.description) console.log(contract.plugin.description);
+  console.log("");
+  for (const command of contract.commands) {
+    printCommandContract(contract.plugin.name, command);
+  }
+}
+function printCommandContract(pluginName, command) {
+  console.log(`${pluginName} ${command.name}`);
+  if (command.description) console.log(`  ${command.description}`);
+  console.log(`  scope: ${command.scope}`);
+  if (command.capabilities.length > 0) {
+    console.log(`  capabilities: ${command.capabilities.join(", ")}`);
+  }
+  if (command.positional.length > 0) {
+    console.log(`  positional: ${command.positional.join(", ")}`);
+  }
+  if (command.form.fields.length > 0) {
+    console.log("  fields:");
+    for (const field of command.form.fields) {
+      const required = field.required ? "required" : "optional";
+      const choices = field.enum ? ` [${field.enum.join("|")}]` : "";
+      console.log(`    --${field.name}: ${field.type}/${field.widget} ${required}${choices}`);
+    }
+  }
+  console.log("");
+}
 async function handlePlugin(args, options, mode) {
   const sub = args[0];
   const subArgs = args.slice(1);
@@ -9592,17 +10468,20 @@ async function handlePlugin(args, options, mode) {
     }
     case "list": {
       const plugins = await installer.list();
-      const runtimeCommands = await buildRuntimeCommandsMap();
+      const runtimeInfo = await buildRuntimePluginInfo();
       const enrichedPlugins = plugins.map((p) => {
         const metadata = p.metadata;
         const staticCommands = metadata?.commands;
-        const dynamicCommands = runtimeCommands.get(p.name);
-        const commands = dynamicCommands || staticCommands;
+        const rt = runtimeInfo.get(p.name);
+        const commands = rt?.commands || staticCommands;
         return {
           ...p,
           commands,
           version: metadata?.version,
-          description: metadata?.description
+          description: metadata?.description,
+          hasLogin: rt?.hasLogin ?? false,
+          loggedIn: rt?.loggedIn ?? null,
+          requiresLoginCommands: rt?.requiresLoginCommands ?? []
         };
       });
       if (mode === "json") {
@@ -9613,20 +10492,27 @@ async function handlePlugin(args, options, mode) {
           return;
         }
         for (const p of enrichedPlugins) {
+          const loginTag = p.hasLogin ? p.loggedIn ? " [logged in]" : " [need login]" : "";
           if (p.version && p.description) {
-            console.log(`${p.name} (${p.version}) - ${p.description}`);
+            console.log(`${p.name} (${p.version}) - ${p.description}${loginTag}`);
           } else {
-            console.log(p.name);
+            console.log(`${p.name}${loginTag}`);
           }
           if (p.commands && p.commands.length > 0) {
             console.log(`  ${p.commands.join(", ")}`);
           }
+          if (p.requiresLoginCommands.length > 0) {
+            console.log(`  requires login: ${p.requiresLoginCommands.join(", ")}`);
+          }
         }
         console.log(`
 Total: ${enrichedPlugins.length} plugins`);
       }
       break;
     }
+    case "schema":
+      await handlePluginSchema(subArgs, mode);
+      break;
     case "reload": {
       const name = subArgs[0];
       if (!name) outputError("Usage: xbrowser plugin reload <name>");
@@ -10021,7 +10907,7 @@ async function handleFilter(args, _mode) {
 
 // src/stdin.ts
 import { createInterface } from "readline";
-import { readFileSync as readFileSync15 } from "fs";
+import { readFileSync as readFileSync14 } from "fs";
 async function readStdin2() {
   if (process.stdin.isTTY) return [];
   const lines = [];
@@ -10035,7 +10921,7 @@ async function readStdin2() {
   return lines;
 }
 function readCommandFile(filePath) {
-  const content = readFileSync15(filePath, "utf-8");
+  const content = readFileSync14(filePath, "utf-8");
   return content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
 }
 
@@ -10667,14 +11553,14 @@ async function listCommands() {
   return jsonResponse(200, { commands });
 }
 async function listSessions2() {
-  const sessions = getAllSessions().map((s) => ({
+  const sessions2 = getAllSessions().map((s) => ({
     id: s.id,
     name: s.name,
     url: s.page?.url() ?? null,
     createdAt: s.createdAt,
     isCDP: s.isCDP ?? false
   }));
-  return jsonResponse(200, { sessions });
+  return jsonResponse(200, { sessions: sessions2 });
 }
 async function createSessionHandler(req) {
   const body = req.body;
@@ -11072,8 +11958,23 @@ async function handleEvalMode(argv) {
 }
 async function handleChainInput(input, argv) {
   const cdpEndpoint = argv ? extractCdpFromArgv(argv) : void 0;
+  const jsonMode = argv ? argv.includes("--json") || argv.includes("-j") : false;
   const chainResult = await executeChain(input, { cdpEndpoint });
-  printChainResult(chainResult);
+  if (jsonMode) {
+    const output = {
+      success: chainResult.success,
+      steps: chainResult.steps.map((s) => ({
+        command: s.raw,
+        success: s.success,
+        data: s.data,
+        duration: s.duration,
+        ...s.hookOutputs?.length ? { hooks: s.hookOutputs } : {}
+      }))
+    };
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    printChainResult(chainResult);
+  }
   if (!chainResult.success) throw new Error("Command failed");
 }
 async function routeCommand(argv, stdinCommands) {
@@ -11098,21 +11999,6 @@ async function routeCommand(argv, stdinCommands) {
   const { positional, options } = parsed;
   const command = positional[0];
   const cmdArgs = positional.slice(1);
-  const isPluginCommand = command ? !allBuiltins.find((b) => b.name === command) && !getCommand(command) && command !== "help" : false;
-  if (!isPluginCommand && command) {
-    const unknownOptions = Object.keys(options).filter((k) => !KNOWN_GLOBAL_OPTIONS.has(k));
-    if (unknownOptions.length > 0) {
-      const unknown = unknownOptions.map((k) => `--${k}`).join(", ");
-      outputError(
-        `Unknown option: ${unknown}
-Did you mean to use a global flag? Global flags must come BEFORE the command:
-  \u2717  xbrowser goto <url> --cdp-endpoint <endpoint>  (treated as unknown)
-  \u2713  xbrowser --cdp <endpoint> goto <url>           (correct)
-Run "xbrowser --help" to see available global options.`
-      );
-      return;
-    }
-  }
   const mode = options.json ? "json" : options.yaml ? "yaml" : "text";
   const sessionName = options.session || process.env.XBROWSER_SESSION || "default";
   const cdpEndpoint = options.cdp;
@@ -11361,11 +12247,11 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
           if (options.target && !params._target) {
             params._target = options.target;
           }
-          const needsBrowser = cmdEntry.scope === "page";
+          const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
-            const { forwardExec } = await import("./daemon-client-3IJD6X4B.js");
+            const { forwardExec } = await import("./daemon-client-YAVQ343A.js");
             const userTimeout = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 + 3e4 : void 0;
-            const result = await forwardExec(command, params, sessionName, cdpEndpoint, userTimeout);
+            const result = await forwardExec(`${command}.${subCommand}`, params, sessionName, cdpEndpoint, userTimeout);
             if (result && result.success !== false) {
               if (isCommandResult2(result)) {
                 if (mode === "json" || mode === "yaml") {
@@ -11398,6 +12284,7 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
             browser: needsBrowser ? session.context.browser() : null,
             browserContext: needsBrowser ? session.context : null,
             sessionId: needsBrowser ? session.id : "",
+            cdpEndpoint: cdpEndpoint || (needsBrowser ? session?.cdpEndpoint : void 0),
             storage: getPluginStorage(command),
             output: { mode, showTips: true, color: true, emoji: true },
             error: (msg) => {
@@ -11411,38 +12298,46 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
             }
           };
           try {
+            const cmdStart = Date.now();
+            const cmdHooks = await loadHooks();
+            if (cmdHooks.length > 0 && session?.page) {
+              await Promise.all(cmdHooks.map((h) => h.onBeforeCommand?.({ page: session.page, command: `${command} ${subCommand}`, params })));
+            }
             const result = await cmdEntry.handler(params, ctx);
+            const hookOutputs = [];
+            if (cmdHooks.length > 0 && session?.page) {
+              for (const h of cmdHooks) {
+                const output = await h.onAfterCommand?.({ page: session.page, command: `${command} ${subCommand}`, params, result, duration: Date.now() - cmdStart });
+                if (output) hookOutputs.push({ _hook: h.name, ...output });
+              }
+            }
             if (session && result && result.data) {
               const convUrl = result.data.conversationUrl;
               if (convUrl) {
                 saveSessionDiskMeta(sessionName, { conversationUrl: convUrl, cdpEndpoint });
               }
             }
-            if (isCommandResult2(result)) {
-              if (mode === "json" || mode === "yaml") {
-                console.log(outputFormatter2.format(result.data, { mode, color: false, emoji: false }));
-                if (result.tips?.length) {
-                  for (const tip of result.tips) console.error(`\u{1F4A1} ${tip}`);
-                }
-              } else {
-                console.log(outputFormatter2.format(result.data, { mode: "text", color: true, emoji: true }));
-                if (result.tips?.length) {
-                  for (const tip of result.tips) console.log(`  \u{1F4A1} ${tip}`);
-                }
+            const outputData = isCommandResult2(result) ? result.data : result && typeof result === "object" ? result.data ?? result : result;
+            const tips = isCommandResult2(result) ? result.tips : result && typeof result === "object" ? result.tips : void 0;
+            if (mode === "json" || mode === "yaml") {
+              const finalOutput = {
+                data: outputData
+              };
+              if (hookOutputs.length > 0) {
+                finalOutput.hooks = hookOutputs;
               }
-            } else if (result && typeof result === "object") {
-              const obj = result;
-              if (mode === "json" || mode === "yaml") {
-                console.log(outputFormatter2.format(obj.data ?? obj, { mode, color: false, emoji: false }));
-                const tips = obj.tips;
-                if (tips?.length) {
-                  for (const tip of tips) console.error(`\u{1F4A1} ${tip}`);
-                }
-              } else {
-                if (obj.data) outputResult(obj.data, mode);
-                const tips = obj.tips;
-                if (tips?.length) {
-                  for (const tip of tips) console.log(`  \u{1F4A1} ${tip}`);
+              console.log(outputFormatter2.format(finalOutput, { mode, color: false, emoji: false }));
+              if (tips?.length) {
+                for (const tip of tips) console.error(`\u{1F4A1} ${tip}`);
+              }
+            } else {
+              console.log(outputFormatter2.format(outputData, { mode: "text", color: true, emoji: true }));
+              if (tips?.length) {
+                for (const tip of tips) console.log(`  \u{1F4A1} ${tip}`);
+              }
+              if (hookOutputs.length > 0) {
+                for (const ho of hookOutputs) {
+                  console.log(`  \u{1F4F8} screenshot: ${ho.screenshot?.url || "captured"}`);
                 }
               }
             }
@@ -12388,7 +13283,7 @@ var WSServer = class extends EventEmitter {
             const vp = this.lastFrameViewport || initSc.page.viewportSize() || await initSc.page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
             this.sendToClient(clientId, {
               type: "status",
-              data: { status: "connected", sessionId: client.sessionId || void 0, viewport: vp }
+              data: { status: "connected", sessionId: client.sessionId || void 0, viewport: vp ?? void 0 }
             });
           } catch {
           }
@@ -12653,10 +13548,10 @@ var WSServer = class extends EventEmitter {
       }
       case "file_download": {
         try {
-          const { readFileSync: readFileSync17 } = await import("fs");
+          const { readFileSync: readFileSync16 } = await import("fs");
           const { resolve: resolve16, basename: basename3 } = await import("path");
           const targetPath = resolve16(msg.path);
-          const data = readFileSync17(targetPath);
+          const data = readFileSync16(targetPath);
           const base64 = data.toString("base64");
           const ext = targetPath.split(".").pop()?.toLowerCase() || "";
           const mimeMap = {
@@ -12806,7 +13701,7 @@ var WSServer = class extends EventEmitter {
           const vp = this.lastFrameViewport || sc.page.viewportSize() || await sc.page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
           this.sendToClient(clientId, {
             type: "status",
-            data: { status: "connected", sessionId, viewport: vp }
+            data: { status: "connected", sessionId, viewport: vp ?? void 0 }
           });
         } catch {
         }
@@ -13937,8 +14832,8 @@ var DataCollector = class {
     return results;
   }
   async createBrowserContext() {
-    const { chromium } = await import("playwright");
-    const browser = await chromium.launch({
+    const { launch } = await import("./cdp-driver-SSXUGXP6.js");
+    const { browser } = await launch({
       headless: true,
       args: ["--no-sandbox", "--disable-setuid-sandbox"]
     });
@@ -13999,6 +14894,7 @@ export {
   WSServer,
   WebhookNotifier,
   XBrowserPluginLoader,
+  actOnPage,
   advise,
   allBuiltins,
   assertPageScope,
@@ -14038,6 +14934,7 @@ export {
   getCommandNames,
   getCompanyType,
   getDaemonProcessStatus,
+  getPageScreenHash,
   getPlatformName,
   getSessionPage,
   getWSServerFromCache,
@@ -14048,6 +14945,7 @@ export {
   mouseTrajectoryRule,
   networkAnomalyRule,
   normalizeSelector,
+  observePage,
   openSession,
   pageLifecycleRule,
   parseCommandArgs,
@@ -14064,5 +14962,6 @@ export {
   splitCommand,
   startDaemonProcess,
   stopDaemonProcess,
-  version
+  version,
+  waitForPage
 };