@xbrowser/cli 0.16.0 → 1.0.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   SessionRecorder
-} from "./chunk-KDYXFLAC.js";
+} from "./chunk-2MFXKN32.js";
 import {
   closeAllSessions,
   closeEphemeralContext,
@@ -17,7 +17,8 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-2ONMTDLK.js";
+} from "./chunk-2BQZIT3S.js";
+import "./chunk-T4J4C2NZ.js";
 import {
   forwardCommandLog,
   forwardNetworkAnalyze,
@@ -46,7 +47,8 @@ import {
   killAllDaemonProcesses,
   startDaemonProcess,
   stopDaemonProcess
-} from "./chunk-ATFTAKMN.js";
+} from "./chunk-IDVD44ED.js";
+import "./chunk-3RG5ZIWI.js";
 
 // src/router.ts
 import { parseArgs, outputFormatter as outputFormatter2, isCommandResult as isCommandResult2, helpGenerator as helpGenerator2 } from "@dyyz1993/xcli-core";
@@ -169,7 +171,7 @@ var version = pkg.version;
 
 // src/executor.ts
 import {
-  ok as ok25,
+  ok as ok26,
   fail as fail7,
   isCommandResult,
   configureArchiveStore,
@@ -535,7 +537,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 });
   }
 });
@@ -554,7 +556,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 });
   }
 });
@@ -570,7 +572,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 });
   }
 });
@@ -587,7 +589,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 });
   }
 });
@@ -2116,7 +2118,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) {
@@ -3121,7 +3123,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 }));
@@ -3517,7 +3519,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;
@@ -3828,6 +3830,24 @@ var ENGINE_KEY_ENUM = z20.enum(ALL_ENGINE_KEYS);
 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) {
@@ -3999,9 +4019,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) {
@@ -4010,7 +4030,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) {
@@ -4291,6 +4321,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",
@@ -4300,7 +4728,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(),
@@ -4313,6 +4748,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);
@@ -4363,10 +4810,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();
@@ -4377,7 +4824,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(() => "");
 }
@@ -4413,22 +4860,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();
@@ -4468,7 +5001,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();
@@ -4490,7 +5023,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,
@@ -4518,7 +5051,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)
@@ -4540,7 +5073,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,
@@ -4549,8 +5082,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
@@ -4728,7 +5261,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;
@@ -4778,7 +5311,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"] }
 };
@@ -4790,14 +5323,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) {
@@ -4838,15 +5371,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);
@@ -4854,74 +5387,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":
@@ -4934,10 +5527,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":
@@ -4950,6 +5557,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}")`;
   }
@@ -5072,7 +5689,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())) {
@@ -5203,8 +5820,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";
 
@@ -5507,14 +6124,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" }
@@ -5527,17 +6144,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
@@ -5552,7 +6169,7 @@ var promoCommand = registerCommand({
       cdpEndpoint: p.cdpEndpoint ?? _ctx.cdpEndpoint,
       session: p.session ?? p.platform
     });
-    return ok24(result);
+    return ok25(result);
   }
 });
 
@@ -5692,6 +6309,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 {
@@ -5734,6 +6537,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);
   }
@@ -6218,7 +7028,7 @@ function getTipsManager() {
 
 // src/hooks/loader.ts
 var builtinHooks = {
-  screenshot: () => import("./screenshot-MB6R7RSS.js").then((m) => m.screenshotHook)
+  screenshot: () => import("./screenshot-CWAWMXVA.js").then((m) => m.screenshotHook)
 };
 async function loadHooks() {
   const names = process.env.XBROWSER_HOOKS;
@@ -6304,7 +7114,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-GWBH6OJK.js");
+    const { findTargetPage } = await import("./browser-DSVV4GHS.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.`);
@@ -6321,7 +7131,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-XWSSQBEA.js");
+    const { forwardExec } = await import("./daemon-client-YAVQ343A.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -6329,7 +7139,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(() => {
@@ -6354,7 +7175,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(),
@@ -6389,7 +7210,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;
@@ -6459,7 +7280,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 } : {} };
     }
@@ -6472,7 +7293,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;
@@ -6620,7 +7441,7 @@ async function executeChain(input, options) {
             results.push({
               command: `${cmdName} ${subCommand}`,
               raw: cmdStr,
-              ...ok25(data),
+              ...ok26(data),
               duration: duration2,
               ...hookOutputs ? { hookOutputs } : {}
             });
@@ -6837,13 +7658,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) {
@@ -7731,6 +8552,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:",
@@ -7739,6 +8561,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");
 }
@@ -8796,6 +9619,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 = {};
@@ -8818,7 +9660,7 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         let parsedActions;
         if (options.action) {
           const actionList = Array.isArray(options.action) ? options.action : [options.action];
-          const { parseActionDsl } = await import("./parse-action-dsl-DRSPBALP.js");
+          const { parseActionDsl } = await import("./parse-action-dsl-T3DYC33D.js");
           parsedActions = actionList.map((a) => parseActionDsl(a));
         } else if (options["actions-file"]) {
           const fs3 = await import("fs");
@@ -8987,11 +9829,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;
     }
@@ -9011,8 +9853,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 {
@@ -9039,15 +9881,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;
 }
@@ -9211,6 +10066,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);
@@ -9251,17 +10154,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") {
@@ -9272,20 +10178,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>");
@@ -9633,7 +10546,7 @@ async function handleConvert(args, _mode) {
   const fs3 = await import("fs");
   const path3 = await import("path");
   const { default: yaml } = await import("yaml");
-  const { generateJSScript, generatePythonScript, generateBashScript } = await import("./convert-4DUWZIKH.js");
+  const { generateJSScript, generatePythonScript, generateBashScript } = await import("./convert-EGFYNICZ.js");
   const content = fs3.readFileSync(filePath, "utf-8");
   const recording = yaml.parse(content);
   const ext = path3.extname(outputPath).toLowerCase();
@@ -9658,7 +10571,7 @@ async function handleExtract(args, _mode) {
     console.error("Usage: xbrowser extract <recording.yaml>");
     process.exit(1);
   }
-  const { extractAndSave, printExtractSummary } = await import("./extract-EGRXZSSK.js");
+  const { extractAndSave, printExtractSummary } = await import("./extract-L2IW3IUB.js");
   const { summary, outputPath } = extractAndSave(filePath);
   printExtractSummary(summary);
   console.log(`
@@ -9671,7 +10584,7 @@ async function handleFilter(args, _mode) {
     console.error("Usage: xbrowser filter <input.yaml> <output.yaml> [--exclude-types=type1,type2]");
     process.exit(1);
   }
-  const { filterRecording, parseExcludeTypes } = await import("./filter-OLAE26HN.js");
+  const { filterRecording, parseExcludeTypes } = await import("./filter-HC4RA7JY.js");
   const excludeTypes = parseExcludeTypes(args.slice(2));
   const result = filterRecording(filePath, outputPath, excludeTypes);
   console.log(`Filtered ${filePath} -> ${outputPath}`);
@@ -10326,14 +11239,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;
@@ -11022,9 +11935,9 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
           }
           const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
-            const { forwardExec } = await import("./daemon-client-XWSSQBEA.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") {
@@ -11057,6 +11970,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) => {
@@ -11283,7 +12197,7 @@ async function main() {
     const command = process.argv[2];
     const isLongRunning = command === "preview" || command === "serve";
     if (!isLongRunning) {
-      const { ensureProcessCanExit } = await import("./browser-GWBH6OJK.js");
+      const { ensureProcessCanExit } = await import("./browser-DSVV4GHS.js");
       await ensureProcessCanExit().catch(() => {
       });
       process.exit(exitCode);