browsecraft 0.1.1 → 0.2.0

package/dist/{chunk-77HRTGXZ.js → chunk-3OBA6D2X.js}

@@ -31,6 +31,121 @@ function resolveConfig(userConfig) {
   };
 }
 
+// src/errors.ts
+var BrowsecraftError = class extends Error {
+  name = "BrowsecraftError";
+  /** What action was being performed */
+  action;
+  /** What target was being acted on */
+  target;
+  /** Element state at the time of failure */
+  elementState;
+  /** Hint for how to fix the issue */
+  hint;
+  /** How long we waited before giving up (ms) */
+  elapsed;
+  constructor(options) {
+    const parts = [];
+    parts.push(`Could not ${options.action} '${options.target}'`);
+    parts.push(`\u2014 ${options.message}`);
+    if (options.elementState) {
+      parts.push("");
+      parts.push(formatElementState(options.elementState));
+    }
+    if (options.hint) {
+      parts.push("");
+      parts.push(`Hint: ${options.hint}`);
+    }
+    if (options.elapsed !== void 0) {
+      parts.push(`(waited ${options.elapsed}ms)`);
+    }
+    super(parts.join("\n"));
+    this.action = options.action;
+    this.target = options.target;
+    this.elementState = options.elementState;
+    this.hint = options.hint;
+    this.elapsed = options.elapsed;
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ElementNotFoundError = class extends BrowsecraftError {
+  name = "ElementNotFoundError";
+  constructor(options) {
+    const hint = options.suggestions?.length ? `Did you mean one of these?
+${options.suggestions.map((s) => `  - ${s}`).join("\n")}` : "Check that the element exists on the page and the text/selector is correct.";
+    super({
+      action: options.action,
+      target: options.target,
+      message: "no matching element found on the page.",
+      elementState: { found: false },
+      hint,
+      elapsed: options.elapsed
+    });
+  }
+};
+var ElementNotActionableError = class extends BrowsecraftError {
+  name = "ElementNotActionableError";
+  reason;
+  constructor(options) {
+    const messages = {
+      "not-visible": "the element was found but is not visible (display:none, visibility:hidden, opacity:0, or zero size).",
+      disabled: "the element was found but is disabled.",
+      obscured: `the element was found but is obscured by another element${options.elementState.obscuredBy ? ` (${options.elementState.obscuredBy})` : ""}.`,
+      "zero-size": "the element was found but has zero width/height.",
+      detached: "the element was found but is no longer attached to the DOM."
+    };
+    const hints = {
+      "not-visible": "Wait for a loading state to complete, or check CSS visibility rules.",
+      disabled: "Wait for the element to become enabled, or check if a prerequisite action is needed first.",
+      obscured: "Scroll the page, close overlapping modals/tooltips, or use { force: true } to bypass.",
+      "zero-size": "Check if the element has proper dimensions. It may be collapsed or off-screen.",
+      detached: "The element was removed from the DOM while waiting. This often happens with dynamic content."
+    };
+    super({
+      action: options.action,
+      target: options.target,
+      message: messages[options.reason] ?? `the element is not actionable (${options.reason}).`,
+      elementState: options.elementState,
+      hint: hints[options.reason],
+      elapsed: options.elapsed
+    });
+    this.reason = options.reason;
+  }
+};
+var NetworkError = class extends BrowsecraftError {
+  name = "NetworkError";
+  constructor(options) {
+    super({
+      action: options.action,
+      target: options.target,
+      message: options.message,
+      hint: "Check that the URL pattern is correct and network interception is set up before navigation.",
+      elapsed: options.elapsed
+    });
+  }
+};
+var TimeoutError = class extends BrowsecraftError {
+  name = "TimeoutError";
+};
+function formatElementState(state) {
+  if (!state.found) return "Element state: NOT FOUND in DOM";
+  const lines = ["Element state:"];
+  if (state.tagName) lines.push(`  Tag: <${state.tagName.toLowerCase()}>`);
+  if (state.id) lines.push(`  Id: #${state.id}`);
+  if (state.classes) lines.push(`  Classes: ${state.classes}`);
+  if (state.textPreview) lines.push(`  Text: "${state.textPreview}"`);
+  if (state.visible !== void 0) lines.push(`  Visible: ${state.visible}`);
+  if (state.enabled !== void 0) lines.push(`  Enabled: ${state.enabled}`);
+  if (state.obscured !== void 0) lines.push(`  Obscured: ${state.obscured}`);
+  if (state.boundingBox) {
+    const b = state.boundingBox;
+    lines.push(`  Position: (${b.x}, ${b.y}) Size: ${b.width}x${b.height}`);
+  }
+  return lines.join("\n");
+}
+
 // src/wait.ts
 async function waitFor(description, fn, options) {
   const { timeout, interval = 100 } = options;
@@ -50,9 +165,7 @@ async function waitFor(description, fn, options) {
   const elapsed = Date.now() - startTime;
   const errorMsg = lastError ? `
 Last error: ${lastError.message}` : "";
-  throw new Error(
-    `Timed out after ${elapsed}ms waiting for: ${description}${errorMsg}`
-  );
+  throw new Error(`Timed out after ${elapsed}ms waiting for: ${description}${errorMsg}`);
 }
 async function waitForLoadState(session, contextId, state = "load", timeout = 3e4) {
   const result = await session.script.evaluate({
@@ -85,44 +198,258 @@ async function waitForLoadState(session, contextId, state = "load", timeout = 3e
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function checkActionability(session, contextId, ref, checks = {}) {
+  const doVisible = checks.visible !== false;
+  const doEnabled = checks.enabled !== false;
+  const doObscured = checks.notObscured === true;
+  try {
+    const result = await session.script.callFunction({
+      functionDeclaration: `function(el, doVisible, doEnabled, doObscured) {
+				// Check if element is still in the DOM
+				if (!el.isConnected) {
+					return {
+						actionable: false,
+						reason: 'detached',
+						state: { found: true, visible: false, enabled: false }
+					};
+				}
+
+				const style = window.getComputedStyle(el);
+				const rect = el.getBoundingClientRect();
+				const tagName = el.tagName || '';
+				const textPreview = (el.innerText || el.textContent || '').slice(0, 80).trim();
+				const classes = el.className || '';
+				const id = el.id || '';
+
+				const state = {
+					found: true,
+					tagName: tagName,
+					textPreview: textPreview,
+					classes: typeof classes === 'string' ? classes : '',
+					id: id,
+					boundingBox: {
+						x: Math.round(rect.x),
+						y: Math.round(rect.y),
+						width: Math.round(rect.width),
+						height: Math.round(rect.height)
+					}
+				};
+
+				// Visibility check
+				if (doVisible) {
+					const isVisible = style.display !== 'none'
+						&& style.visibility !== 'hidden'
+						&& style.opacity !== '0'
+						&& rect.width > 0
+						&& rect.height > 0;
+
+					state.visible = isVisible;
+
+					if (!isVisible) {
+						if (rect.width === 0 || rect.height === 0) {
+							return { actionable: false, reason: 'zero-size', state: state };
+						}
+						return { actionable: false, reason: 'not-visible', state: state };
+					}
+				}
+
+				// Enabled check (only for form elements)
+				if (doEnabled) {
+					const formTags = ['INPUT', 'BUTTON', 'SELECT', 'TEXTAREA', 'FIELDSET'];
+					const isFormElement = formTags.includes(tagName);
+					const isDisabled = isFormElement && el.disabled === true;
+					state.enabled = !isDisabled;
+
+					if (isDisabled) {
+						return { actionable: false, reason: 'disabled', state: state };
+					}
+				}
+
+				// Obscured check (elementFromPoint)
+				if (doObscured) {
+					const cx = rect.x + rect.width / 2;
+					const cy = rect.y + rect.height / 2;
+					const topEl = document.elementFromPoint(cx, cy);
+
+					if (topEl && topEl !== el && !el.contains(topEl)) {
+						state.obscured = true;
+						state.obscuredBy = '<' + topEl.tagName.toLowerCase()
+							+ (topEl.id ? '#' + topEl.id : '')
+							+ (topEl.className ? '.' + topEl.className.split(' ').join('.') : '')
+							+ '>';
+						return { actionable: false, reason: 'obscured', state: state };
+					}
+					state.obscured = false;
+				}
+
+				state.visible = true;
+				state.enabled = true;
+				return { actionable: true, state: state };
+			}`,
+      target: { context: contextId },
+      arguments: [
+        ref,
+        { type: "boolean", value: doVisible },
+        { type: "boolean", value: doEnabled },
+        { type: "boolean", value: doObscured }
+      ],
+      awaitPromise: false
+    });
+    if (result.type === "success" && result.result?.type === "object") {
+      return deserializeActionabilityResult(result.result.value);
+    }
+    return {
+      actionable: true,
+      state: { found: true, visible: true, enabled: true }
+    };
+  } catch {
+    return {
+      actionable: false,
+      reason: "detached",
+      state: { found: true, visible: false, enabled: false }
+    };
+  }
+}
+async function waitForActionable(session, contextId, ref, description, options, checks) {
+  let lastResult = null;
+  try {
+    return await waitFor(
+      `${description} to be actionable`,
+      async () => {
+        const result = await checkActionability(session, contextId, ref, checks);
+        lastResult = result;
+        return result.actionable ? result : null;
+      },
+      options
+    );
+  } catch {
+    return lastResult ?? {
+      actionable: false,
+      reason: "not-visible",
+      state: { found: true }
+    };
+  }
+}
+function deserializeActionabilityResult(value) {
+  if (!Array.isArray(value)) {
+    return { actionable: true, state: { found: true } };
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of value) {
+    if (Array.isArray(entry) && entry.length === 2) {
+      const val = entry[1];
+      map.set(entry[0], val && typeof val === "object" && "value" in val ? val.value : val);
+    }
+  }
+  const stateRaw = map.get("state");
+  let state = { found: true };
+  if (Array.isArray(stateRaw)) {
+    const stateMap = /* @__PURE__ */ new Map();
+    for (const entry of stateRaw) {
+      if (Array.isArray(entry) && entry.length === 2) {
+        const val = entry[1];
+        stateMap.set(entry[0], val && typeof val === "object" && "value" in val ? val.value : val);
+      }
+    }
+    let boundingBox;
+    const bbRaw = stateMap.get("boundingBox");
+    if (Array.isArray(bbRaw)) {
+      const bbMap = /* @__PURE__ */ new Map();
+      for (const entry of bbRaw) {
+        if (Array.isArray(entry) && entry.length === 2) {
+          const val = entry[1];
+          bbMap.set(entry[0], val && typeof val === "object" && "value" in val ? val.value : val);
+        }
+      }
+      boundingBox = {
+        x: bbMap.get("x") ?? 0,
+        y: bbMap.get("y") ?? 0,
+        width: bbMap.get("width") ?? 0,
+        height: bbMap.get("height") ?? 0
+      };
+    }
+    state = {
+      found: true,
+      visible: stateMap.get("visible"),
+      enabled: stateMap.get("enabled"),
+      tagName: stateMap.get("tagName"),
+      textPreview: stateMap.get("textPreview"),
+      classes: stateMap.get("classes"),
+      id: stateMap.get("id"),
+      obscured: stateMap.get("obscured"),
+      obscuredBy: stateMap.get("obscuredBy"),
+      boundingBox
+    };
+  }
+  return {
+    actionable: map.get("actionable") ?? true,
+    reason: map.get("reason"),
+    state
+  };
+}
 
 // src/locator.ts
+var HEAD_ONLY_ELEMENTS = /* @__PURE__ */ new Set([
+  "title",
+  "meta",
+  "link",
+  "style",
+  "base",
+  "head",
+  "noscript"
+  // can appear in head too
+]);
 async function locateElement(session, contextId, target, options) {
   const opts = normalizeTarget(target);
-  return waitFor(
-    describeTarget(target),
-    async () => {
-      const strategies = buildStrategies(opts);
-      for (const { locator, strategy, isLabelLookup } of strategies) {
-        try {
-          const result = await session.browsingContext.locateNodes({
-            context: contextId,
-            locator,
-            maxNodeCount: (opts.index ?? 0) + 10
-            // fetch extra for label resolution
-          });
-          if (result.nodes.length > 0) {
-            if (isLabelLookup) {
-              const resolved = await resolveLabelsToInputs(session, contextId, result.nodes);
-              if (resolved) {
-                return { node: resolved, strategy };
+  const description = describeTarget(target);
+  const startTime = Date.now();
+  try {
+    return await waitFor(
+      description,
+      async () => {
+        const strategies = buildStrategies(opts);
+        for (const { locator, strategy, isLabelLookup } of strategies) {
+          try {
+            const result = await session.browsingContext.locateNodes({
+              context: contextId,
+              locator,
+              maxNodeCount: (opts.index ?? 0) + 10
+              // fetch extra for label resolution
+            });
+            const nodes = result.nodes.filter(
+              (n) => !HEAD_ONLY_ELEMENTS.has(n.value?.localName ?? "")
+            );
+            if (nodes.length > 0) {
+              if (isLabelLookup) {
+                const resolved = await resolveLabelsToInputs(session, contextId, nodes);
+                if (resolved) {
+                  return { node: resolved, strategy };
+                }
+                continue;
+              }
+              const nodeIndex = opts.index ?? 0;
+              const node = nodes[nodeIndex];
+              if (node) {
+                return { node, strategy };
               }
-              continue;
-            }
-            const nodeIndex = opts.index ?? 0;
-            const node = result.nodes[nodeIndex];
-            if (node) {
-              return { node, strategy };
             }
+          } catch {
           }
-        } catch {
-          continue;
         }
-      }
-      return null;
-    },
-    options
-  );
+        return null;
+      },
+      options
+    );
+  } catch (err) {
+    const elapsed = Date.now() - startTime;
+    const suggestions = await findSimilarElements(session, contextId, target);
+    throw new ElementNotFoundError({
+      action: "find",
+      target: typeof target === "string" ? target : description,
+      elapsed,
+      suggestions
+    });
+  }
 }
 async function locateAllElements(session, contextId, target) {
   const opts = normalizeTarget(target);
@@ -134,11 +461,11 @@ async function locateAllElements(session, contextId, target) {
         locator,
         maxNodeCount: 1e3
       });
-      if (result.nodes.length > 0) {
-        return result.nodes.map((node) => ({ node, strategy }));
+      const nodes = result.nodes.filter((n) => !HEAD_ONLY_ELEMENTS.has(n.value?.localName ?? ""));
+      if (nodes.length > 0) {
+        return nodes.map((node) => ({ node, strategy }));
       }
     } catch {
-      continue;
     }
   }
   return [];
@@ -209,6 +536,13 @@ function buildStrategies(opts) {
       },
       strategy: `innerText("${name}")`
     });
+    strategies.push({
+      locator: {
+        type: "css",
+        value: `[data-testid="${name}"], [data-test="${name}"], [data-test-id="${name}"]`
+      },
+      strategy: `data-testid("${name}")`
+    });
     if (name.match(/^[#.\[a-z]/i)) {
       strategies.push({
         locator: { type: "css", value: name },
@@ -281,11 +615,57 @@ async function resolveLabelsToInputs(session, contextId, nodes) {
         return result.result;
       }
     } catch {
-      continue;
     }
   }
   return null;
 }
+async function findSimilarElements(session, contextId, target) {
+  const searchText = typeof target === "string" ? target : target.name ?? target.text ?? target.label ?? "";
+  if (!searchText) return [];
+  try {
+    const result = await session.script.callFunction({
+      functionDeclaration: `function(searchText) {
+				const suggestions = [];
+				const lower = searchText.toLowerCase();
+
+				// Look at all interactive elements and visible text
+				const interactiveSelectors = 'button, a, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"]';
+				const elements = document.querySelectorAll(interactiveSelectors);
+
+				for (const el of elements) {
+					const text = (el.innerText || el.textContent || '').trim();
+					const ariaLabel = el.getAttribute('aria-label') || '';
+					const placeholder = el.getAttribute('placeholder') || '';
+					const value = el.getAttribute('value') || '';
+					const title = el.getAttribute('title') || '';
+
+					const candidates = [text, ariaLabel, placeholder, value, title].filter(Boolean);
+					for (const c of candidates) {
+						if (c.toLowerCase().includes(lower.slice(0, 3)) || lower.includes(c.toLowerCase().slice(0, 3))) {
+							const tag = el.tagName.toLowerCase();
+							const desc = c.length > 40 ? c.slice(0, 40) + '...' : c;
+							suggestions.push('<' + tag + '> "' + desc + '"');
+							break;
+						}
+					}
+
+					if (suggestions.length >= 5) break;
+				}
+
+				return suggestions;
+			}`,
+      target: { context: contextId },
+      arguments: [{ type: "string", value: searchText }],
+      awaitPromise: false
+    });
+    if (result.type === "success" && result.result?.type === "array") {
+      const arr = result.result.value;
+      return arr.filter((item) => item?.type === "string").map((item) => item.value);
+    }
+  } catch {
+  }
+  return [];
+}
 
 // src/page.ts
 var Page = class {
@@ -366,6 +746,7 @@ var Page = class {
   async click(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const located = await locateElement(this.session, this.contextId, target, { timeout });
+    await this.ensureActionable(located, "click", target, { timeout });
     await this.scrollIntoViewAndClick(located, options);
   }
   /**
@@ -381,6 +762,7 @@ var Page = class {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
     const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    await this.ensureActionable(located, "fill", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: `function(element, value) {
@@ -419,6 +801,7 @@ var Page = class {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
     const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    await this.ensureActionable(located, "type", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: "function(el) { el.focus(); }",
@@ -447,6 +830,7 @@ var Page = class {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
     const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    await this.ensureActionable(located, "select", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: `function(element, value) {
@@ -474,6 +858,7 @@ var Page = class {
   async check(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const located = await locateElement(this.session, this.contextId, target, { timeout });
+    await this.ensureActionable(located, "check", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
       functionDeclaration: "function(el) { return el.checked; }",
@@ -492,6 +877,7 @@ var Page = class {
   async uncheck(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const located = await locateElement(this.session, this.contextId, target, { timeout });
+    await this.ensureActionable(located, "uncheck", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
       functionDeclaration: "function(el) { return el.checked; }",
@@ -514,6 +900,7 @@ var Page = class {
   async hover(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const located = await locateElement(this.session, this.contextId, target, { timeout });
+    await this.ensureActionable(located, "hover", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: 'function(el) { el.scrollIntoView({ block: "center", behavior: "instant" }); }',
@@ -533,14 +920,14 @@ var Page = class {
     const pos = await this.getElementCenter(ref);
     await this.session.input.performActions({
       context: this.contextId,
-      actions: [{
-        type: "pointer",
-        id: "mouse",
-        parameters: { pointerType: "mouse" },
-        actions: [
-          { type: "pointerMove", x: pos.x, y: pos.y, origin: "viewport" }
-        ]
-      }]
+      actions: [
+        {
+          type: "pointer",
+          id: "mouse",
+          parameters: { pointerType: "mouse" },
+          actions: [{ type: "pointerMove", x: pos.x, y: pos.y, origin: "viewport" }]
+        }
+      ]
     });
   }
   // -----------------------------------------------------------------------
@@ -750,10 +1137,7 @@ var Page = class {
    */
   async mock(pattern, response) {
     const { method, urlPattern } = parseMockPattern(pattern);
-    await this.session.subscribe(
-      ["network.beforeRequestSent"],
-      [this.contextId]
-    );
+    await this.session.subscribe(["network.beforeRequestSent"], [this.contextId]);
     const result = await this.session.network.addIntercept({
       phases: ["beforeRequestSent"],
       urlPatterns: [urlPattern],
@@ -850,6 +1234,7 @@ var Page = class {
   async tap(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const located = await locateElement(this.session, this.contextId, target, { timeout });
+    await this.ensureActionable(located, "tap", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: 'function(el) { el.scrollIntoView({ block: "center", behavior: "instant" }); }',
@@ -860,16 +1245,18 @@ var Page = class {
     const pos = await this.getElementCenter(ref);
     await this.session.input.performActions({
       context: this.contextId,
-      actions: [{
-        type: "pointer",
-        id: "touch",
-        parameters: { pointerType: "touch" },
-        actions: [
-          { type: "pointerMove", x: pos.x, y: pos.y, origin: "viewport" },
-          { type: "pointerDown", button: 0 },
-          { type: "pointerUp", button: 0 }
-        ]
-      }]
+      actions: [
+        {
+          type: "pointer",
+          id: "touch",
+          parameters: { pointerType: "touch" },
+          actions: [
+            { type: "pointerMove", x: pos.x, y: pos.y, origin: "viewport" },
+            { type: "pointerDown", button: 0 },
+            { type: "pointerUp", button: 0 }
+          ]
+        }
+      ]
     });
   }
   /**
@@ -883,6 +1270,7 @@ var Page = class {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
     const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    await this.ensureActionable(located, "focus", target, { timeout, enabled: false });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: "function(el) { el.focus(); }",
@@ -979,6 +1367,7 @@ var Page = class {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
     const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    await this.ensureActionable(located, "selectOption", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const valuesArray = Array.isArray(values) ? values : [values];
     await this.session.script.callFunction({
@@ -990,7 +1379,10 @@ var Page = class {
 				element.dispatchEvent(new Event('change', { bubbles: true }));
 			}`,
       target: { context: this.contextId },
-      arguments: [ref, { type: "array", value: valuesArray.map((v) => ({ type: "string", value: v })) }],
+      arguments: [
+        ref,
+        { type: "array", value: valuesArray.map((v) => ({ type: "string", value: v })) }
+      ],
       awaitPromise: false
     });
   }
@@ -1011,17 +1403,19 @@ var Page = class {
     const destPos = await this.getElementCenter(destRef);
     await this.session.input.performActions({
       context: this.contextId,
-      actions: [{
-        type: "pointer",
-        id: "mouse",
-        parameters: { pointerType: "mouse" },
-        actions: [
-          { type: "pointerMove", x: sourcePos.x, y: sourcePos.y, origin: "viewport" },
-          { type: "pointerDown", button: 0 },
-          { type: "pointerMove", x: destPos.x, y: destPos.y, origin: "viewport", duration: 300 },
-          { type: "pointerUp", button: 0 }
-        ]
-      }]
+      actions: [
+        {
+          type: "pointer",
+          id: "mouse",
+          parameters: { pointerType: "mouse" },
+          actions: [
+            { type: "pointerMove", x: sourcePos.x, y: sourcePos.y, origin: "viewport" },
+            { type: "pointerDown", button: 0 },
+            { type: "pointerMove", x: destPos.x, y: destPos.y, origin: "viewport", duration: 300 },
+            { type: "pointerUp", button: 0 }
+          ]
+        }
+      ]
     });
   }
   // -----------------------------------------------------------------------
@@ -1040,7 +1434,7 @@ var Page = class {
     const state = options?.state ?? "visible";
     if (state === "hidden") {
       await waitFor(
-        `element to be hidden`,
+        "element to be hidden",
         async () => {
           try {
             const elements = await locateAllElements(this.session, this.contextId, target);
@@ -1069,7 +1463,7 @@ var Page = class {
     if (state === "visible") {
       const ref = this.getSharedRef(located.node);
       await waitFor(
-        `element to be visible`,
+        "element to be visible",
         async () => {
           const result = await this.session.script.callFunction({
             functionDeclaration: `function(el) {
@@ -1140,6 +1534,185 @@ var Page = class {
     await waitForLoadState(this.session, this.contextId, state, this.config.timeout);
   }
   // -----------------------------------------------------------------------
+  // English API aliases — reads like instructions to a person
+  // -----------------------------------------------------------------------
+  /**
+   * Navigate to a URL. English-friendly alias for goto().
+   *
+   * ```ts
+   * await page.go('https://example.com');
+   * await page.go('/login');
+   * ```
+   */
+  async go(url, options) {
+    return this.goto(url, options);
+  }
+  /**
+   * Assert that an element with the given text is visible on the page.
+   * Returns the ElementHandle for further assertions.
+   *
+   * ```ts
+   * await page.see('Welcome back!');
+   * await page.see('Products');
+   * await page.see({ role: 'heading', name: 'Dashboard' });
+   * ```
+   */
+  async see(target, options) {
+    const timeout = options?.timeout ?? this.config.timeout;
+    const startTime = Date.now();
+    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const ref = this.getSharedRef(located.node);
+    const elapsed = Date.now() - startTime;
+    const remaining = Math.max(timeout - elapsed, 5e3);
+    await waitFor(
+      `${describeTarget2(target)} to be visible`,
+      async () => {
+        try {
+          const result = await this.session.script.callFunction({
+            functionDeclaration: `function(el) {
+							const style = window.getComputedStyle(el);
+							const rect = el.getBoundingClientRect();
+							return style.display !== 'none' && style.visibility !== 'hidden' &&
+								style.opacity !== '0' && rect.width > 0 && rect.height > 0;
+						}`,
+            target: { context: this.contextId },
+            arguments: [ref],
+            awaitPromise: false
+          });
+          if (result.type === "success" && result.result?.type === "boolean" && result.result.value === true) {
+            return true;
+          }
+          return null;
+        } catch {
+          return null;
+        }
+      },
+      { timeout: remaining }
+    );
+    return new ElementHandle(this, target);
+  }
+  // -----------------------------------------------------------------------
+  // Network interception & observation
+  // -----------------------------------------------------------------------
+  /**
+   * Intercept network requests matching a pattern. Calls your handler
+   * for each matching request, letting you modify or respond to it.
+   *
+   * ```ts
+   * await page.intercept('POST /api/login', async (request) => {
+   *   // Modify request, or provide a response
+   *   return { status: 200, body: { token: 'abc' } };
+   * });
+   * ```
+   */
+  async intercept(pattern, handler) {
+    const { method, urlPattern } = parseMockPattern(pattern);
+    await this.session.subscribe(["network.beforeRequestSent"], [this.contextId]);
+    const result = await this.session.network.addIntercept({
+      phases: ["beforeRequestSent"],
+      urlPatterns: [urlPattern],
+      contexts: [this.contextId]
+    });
+    this.interceptIds.push(result.intercept);
+    const unsubscribe = this.session.on("network.beforeRequestSent", async (event) => {
+      const params = event.params;
+      if (!params.isBlocked || params.context !== this.contextId) return;
+      if (!params.intercepts?.includes(result.intercept)) return;
+      if (method && params.request.method.toUpperCase() !== method.toUpperCase()) {
+        await this.session.network.continueRequest({ request: params.request.request });
+        return;
+      }
+      const reqInfo = {
+        url: params.request.url,
+        method: params.request.method,
+        headers: Object.fromEntries(params.request.headers.map((h) => [h.name, h.value.value]))
+      };
+      try {
+        const response = await handler(reqInfo);
+        if (response) {
+          const headers = buildMockHeaders(response);
+          const body = buildMockBody(response);
+          await this.session.network.provideResponse({
+            request: params.request.request,
+            statusCode: response.status ?? 200,
+            headers,
+            body: body ? { type: "string", value: body } : void 0
+          });
+        } else {
+          await this.session.network.continueRequest({ request: params.request.request });
+        }
+      } catch {
+        await this.session.network.continueRequest({ request: params.request.request });
+      }
+    });
+    this.eventCleanups.push(unsubscribe);
+  }
+  /**
+   * Wait for a network response matching a URL pattern.
+   *
+   * ```ts
+   * const response = await page.waitForResponse('/api/users');
+   * console.log(response.status); // 200
+   * ```
+   */
+  async waitForResponse(urlPattern, options) {
+    const timeout = options?.timeout ?? this.config.timeout;
+    const method = options?.method?.toUpperCase();
+    await this.session.subscribe(["network.responseCompleted"], [this.contextId]);
+    try {
+      const event = await this.session.waitForEvent(
+        "network.responseCompleted",
+        (e) => {
+          const params2 = e.params;
+          if (params2.context !== this.contextId) return false;
+          if (method && params2.request.method.toUpperCase() !== method) return false;
+          const url = params2.request.url;
+          if (typeof urlPattern === "string") {
+            return url.includes(urlPattern);
+          }
+          return urlPattern.test(url);
+        },
+        timeout
+      );
+      const params = event.params;
+      return {
+        url: params.request.url,
+        status: params.response.status,
+        method: params.request.method
+      };
+    } finally {
+      await this.session.unsubscribe(["network.responseCompleted"], [this.contextId]).catch(() => {
+      });
+    }
+  }
+  /**
+   * Block network requests matching URL patterns (e.g., ads, analytics).
+   *
+   * ```ts
+   * await page.blockRequests(['*.google-analytics.com*', '*.doubleclick.net*']);
+   * await page.blockRequests(['/api/telemetry']);
+   * ```
+   */
+  async blockRequests(patterns) {
+    await this.session.subscribe(["network.beforeRequestSent"], [this.contextId]);
+    for (const pattern of patterns) {
+      const urlPattern = pattern.startsWith("http") ? { type: "string", pattern } : { type: "pattern", pathname: pattern };
+      const result = await this.session.network.addIntercept({
+        phases: ["beforeRequestSent"],
+        urlPatterns: [urlPattern],
+        contexts: [this.contextId]
+      });
+      this.interceptIds.push(result.intercept);
+      const unsubscribe = this.session.on("network.beforeRequestSent", async (event) => {
+        const params = event.params;
+        if (!params.isBlocked || params.context !== this.contextId) return;
+        if (!params.intercepts?.includes(result.intercept)) return;
+        await this.session.network.failRequest({ request: params.request.request });
+      });
+      this.eventCleanups.push(unsubscribe);
+    }
+  }
+  // -----------------------------------------------------------------------
   // Lifecycle
   // -----------------------------------------------------------------------
   /**
@@ -1177,6 +1750,34 @@ var Page = class {
   // -----------------------------------------------------------------------
   // Private helpers
   // -----------------------------------------------------------------------
+  /**
+   * Ensure an element is actionable (visible + enabled) before interacting.
+   * Throws a rich ElementNotActionableError if it's not ready within the timeout.
+   */
+  async ensureActionable(located, action, target, options) {
+    const ref = this.getSharedRef(located.node);
+    const targetDesc = typeof target === "string" ? target : describeTarget2(target);
+    const result = await waitForActionable(
+      this.session,
+      this.contextId,
+      ref,
+      targetDesc,
+      { timeout: Math.min(options.timeout, 5e3) },
+      {
+        visible: true,
+        enabled: options.enabled !== false
+      }
+    );
+    if (!result.actionable && result.reason) {
+      throw new ElementNotActionableError({
+        action,
+        target: targetDesc,
+        reason: result.reason,
+        elementState: result.state,
+        elapsed: options.timeout
+      });
+    }
+  }
   /** Resolve a relative URL against the baseURL */
   resolveURL(url) {
     if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("about:") || url.startsWith("data:")) {
@@ -1342,7 +1943,7 @@ var ElementHandle = class {
     const located = await this.locate();
     const ref = this.getRef(located);
     const result = await this.page.session.script.callFunction({
-      functionDeclaration: `function(el, name) { return el.getAttribute(name); }`,
+      functionDeclaration: "function(el, name) { return el.getAttribute(name); }",
       target: { context: this.page.contextId },
       arguments: [ref, { type: "string", value: name }],
       awaitPromise: false
@@ -1480,7 +2081,12 @@ var ElementHandle = class {
             const v = map.get(key);
             return typeof v === "object" && v !== null && "value" in v ? v.value : 0;
           };
-          return { x: extract("x"), y: extract("y"), width: extract("width"), height: extract("height") };
+          return {
+            x: extract("x"),
+            y: extract("y"),
+            width: extract("width"),
+            height: extract("height")
+          };
         }
       }
       return null;
@@ -1536,12 +2142,9 @@ var ElementHandle = class {
   }
   /** @internal Locate the element with auto-wait */
   async locate(timeout) {
-    return locateElement(
-      this.page.session,
-      this.page.contextId,
-      this.target,
-      { timeout: timeout ?? 3e4 }
-    );
+    return locateElement(this.page.session, this.page.contextId, this.target, {
+      timeout: timeout ?? 3e4
+    });
   }
   getRef(located) {
     if (located.node.sharedId) {
@@ -1550,6 +2153,17 @@ var ElementHandle = class {
     throw new Error("Element has no shared reference");
   }
 };
+function describeTarget2(target) {
+  if (typeof target === "string") return target;
+  const parts = [];
+  if (target.role) parts.push(`role="${target.role}"`);
+  if (target.name) parts.push(`name="${target.name}"`);
+  if (target.text) parts.push(`text="${target.text}"`);
+  if (target.label) parts.push(`label="${target.label}"`);
+  if (target.testId) parts.push(`testId="${target.testId}"`);
+  if (target.selector) parts.push(`selector="${target.selector}"`);
+  return `[${parts.join(", ")}]`;
+}
 function mapKey(key) {
   const keyMap = {
     Enter: "\uE007",
@@ -1734,7 +2348,7 @@ var Browser = class _Browser {
       return new BrowserContext(this.session, this.config, userContext);
     } catch (err) {
       console.warn(
-        "[browsecraft] Warning: browser.createUserContext is not supported. Pages will share cookies/storage. " + (err instanceof Error ? err.message : String(err))
+        `[browsecraft] Warning: browser.createUserContext is not supported. Pages will share cookies/storage. ${err instanceof Error ? err.message : String(err)}`
       );
       return new BrowserContext(this.session, this.config, null);
     }
@@ -1926,7 +2540,9 @@ async function runTest(testCase, sharedBrowser, userConfig) {
     }
     let screenshotPath;
     if (config.screenshot === "always" && page) {
-      screenshotPath = await captureScreenshot(page, testCase, config.outputDir).catch(() => void 0);
+      screenshotPath = await captureScreenshot(page, testCase, config.outputDir).catch(
+        () => void 0
+      );
     }
     const duration = Date.now() - startTime;
     return {
@@ -1940,7 +2556,9 @@ async function runTest(testCase, sharedBrowser, userConfig) {
     const duration = Date.now() - startTime;
     let screenshotPath;
     if ((config.screenshot === "on-failure" || config.screenshot === "always") && page) {
-      screenshotPath = await captureScreenshot(page, testCase, config.outputDir).catch(() => void 0);
+      screenshotPath = await captureScreenshot(page, testCase, config.outputDir).catch(
+        () => void 0
+      );
     }
     return {
       title: testCase.title,
@@ -1960,9 +2578,7 @@ async function runTest(testCase, sharedBrowser, userConfig) {
   }
 }
 async function runAfterAllHooks(suitePath, fixtures) {
-  const applicableAfterAll = hooks.afterAll.filter(
-    (h) => isHookApplicable(h.suitePath, suitePath)
-  );
+  const applicableAfterAll = hooks.afterAll.filter((h) => isHookApplicable(h.suitePath, suitePath));
   for (const hook of applicableAfterAll) {
     const hookKey = `${hook.suitePath.join(">")}:${hooks.afterAll.indexOf(hook)}`;
     if (!executedAfterAllHooks.has(hookKey)) {
@@ -1999,6 +2615,6 @@ async function captureScreenshot(page, testCase, outputDir) {
   return filePath;
 }
 
-export { Browser, BrowserContext, ElementHandle, Page, afterAll, afterEach, beforeAll, beforeEach, defineConfig, describe, resetTestState, resolveConfig, runAfterAllHooks, runTest, test, testRegistry };
-//# sourceMappingURL=chunk-77HRTGXZ.js.map
-//# sourceMappingURL=chunk-77HRTGXZ.js.map
+export { BrowsecraftError, Browser, BrowserContext, ElementHandle, ElementNotActionableError, ElementNotFoundError, NetworkError, Page, TimeoutError, afterAll, afterEach, beforeAll, beforeEach, defineConfig, describe, resetTestState, resolveConfig, runAfterAllHooks, runTest, test, testRegistry };
+//# sourceMappingURL=chunk-3OBA6D2X.js.map
+//# sourceMappingURL=chunk-3OBA6D2X.js.map