explorbot 0.2.3 → 0.2.4

package/src/remote.ts

@@ -0,0 +1,238 @@
+import type { Command } from 'commander';
+import stripAnsi from 'strip-ansi';
+import { type ActivityEntry, addActivityListener } from './activity.ts';
+import { executionController } from './execution-controller.ts';
+import { type LogDestination, type TaggedLogEntry, addDestination } from './utils/logger.ts';
+
+const QUEUE_CAP = 1000;
+const CONTENT_CAP = 8000;
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 10_000;
+const ASK_TIMEOUT_MS = 15 * 60_000;
+const FLUSH_TIMEOUT_MS = 3000;
+
+/**
+ * Streams a run to a remote UI over one WebSocket, dialling out so a child
+ * process and a CI bot are the same case.
+ *
+ * It **is** a LogDestination — that is the whole integration on the logger's
+ * side — and it answers asks by installing itself as the execution
+ * controller's input callback. Nothing else in explorbot knows it exists.
+ */
+export class Remote implements LogDestination {
+  private url: string | null = null;
+  private socket: WebSocket | null = null;
+  private queue: Frame[] = [];
+  private reconnectDelay = RECONNECT_BASE_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private asks = new Map<string, (value: string | null) => void>();
+  private askCounter = 0;
+  private lastActivity: string | null = null;
+
+  registerOption(program: Command): void {
+    program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+      const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
+      if (!url) return;
+      this.attach(String(url), this.commandPath(actionCommand));
+    });
+  }
+
+  attach(url: string, command: string): void {
+    if (this.url) return;
+    this.url = url;
+    this.connect();
+
+    this.send('hello', { command, cwd: process.cwd(), pid: process.pid });
+    addDestination(this);
+    executionController.setInputCallback((prompt) => this.ask(prompt));
+    addActivityListener((activity) => this.reportActivity(activity));
+  }
+
+  isAttached(): boolean {
+    return !!this.url;
+  }
+
+  send(type: string, data: Record<string, unknown> = {}): void {
+    if (!this.url) return;
+    const frame: Frame = { type, ts: Date.now(), ...data };
+    if (this.socket?.readyState === WebSocket.OPEN) {
+      this.push(frame);
+      return;
+    }
+    this.queue.push(frame);
+    if (this.queue.length > QUEUE_CAP) this.queue.splice(0, this.queue.length - QUEUE_CAP);
+  }
+
+  ask(prompt: string): Promise<string | null> {
+    if (!this.url) return Promise.resolve(null);
+    this.askCounter++;
+    const askId = `ask-${this.askCounter}`;
+    this.send('ask', { askId, prompt });
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.asks.delete(askId);
+        resolve(null);
+      }, ASK_TIMEOUT_MS);
+      this.asks.set(askId, (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      });
+    });
+  }
+
+  async close(exitCode: number): Promise<void> {
+    if (!this.url) return;
+    this.send('result', { ok: exitCode === 0, exitCode });
+    await this.flush();
+
+    this.url = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    // Whoever asks next has nobody to ask — leaving the callback installed would
+    // route them into a closed socket and park them until the ask times out.
+    executionController.clearInputCallback();
+    for (const resolve of this.asks.values()) resolve(null);
+    this.asks.clear();
+    this.queue = [];
+    this.socket?.close();
+    this.socket = null;
+  }
+
+  isEnabled(): boolean {
+    return this.isAttached();
+  }
+
+  /**
+   * The entry as the logger already built it, so the `LogType` reaches the UI
+   * as the frame's level and each kind is styled there instead of being scraped
+   * back out of flattened text.
+   */
+  write(entry: TaggedLogEntry): void {
+    if (entry.type === 'html') return;
+    let content = stripAnsi(entry.content ?? '');
+    if (content.length > CONTENT_CAP) content = `${content.slice(0, CONTENT_CAP)}… (${content.length} chars)`;
+    this.send('log', {
+      level: entry.type,
+      content,
+      namespace: entry.namespace,
+      error: this.errorOf(entry.originalArgs),
+    });
+  }
+
+  private connect(): void {
+    if (!this.url) return;
+
+    let opening: WebSocket;
+    try {
+      opening = new WebSocket(this.url);
+    } catch {
+      this.reconnect();
+      return;
+    }
+    this.socket = opening;
+
+    opening.addEventListener('open', () => {
+      this.reconnectDelay = RECONNECT_BASE_MS;
+      this.drain();
+    });
+
+    opening.addEventListener('message', (event: MessageEvent) => this.receive(String(event.data)));
+
+    opening.addEventListener('close', () => {
+      if (this.socket !== opening) return;
+      this.socket = null;
+      this.reconnect();
+    });
+
+    // A failed connection always closes too, which is where the retry is scheduled.
+    opening.addEventListener('error', () => {});
+  }
+
+  private reconnect(): void {
+    if (!this.url || this.reconnectTimer) return;
+    const delay = this.reconnectDelay;
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+
+  private async flush(): Promise<void> {
+    const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      if (this.socket?.readyState === WebSocket.OPEN) {
+        this.drain();
+        if (!this.queue.length && !this.socket.bufferedAmount) return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+
+  private drain(): void {
+    if (this.socket?.readyState !== WebSocket.OPEN) return;
+    const pending = this.queue;
+    this.queue = [];
+    for (const frame of pending) this.push(frame);
+  }
+
+  private push(frame: Frame): void {
+    try {
+      this.socket?.send(JSON.stringify(frame));
+    } catch {
+      this.queue.push(frame);
+    }
+  }
+
+  private receive(raw: string): void {
+    let frame: Frame;
+    try {
+      frame = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (frame.type === 'interrupt') {
+      executionController.interrupt();
+      return;
+    }
+    const resolve = this.asks.get(String(frame.askId));
+    if (!resolve) return;
+    this.asks.delete(String(frame.askId));
+    resolve((frame.value as string | null) ?? null);
+  }
+
+  /** A new listener is primed with the current activity, which at attach time is
+   *  nothing — so skip repeats, the priming null included. */
+  private reportActivity(activity: ActivityEntry | null): void {
+    const message = activity?.message ?? null;
+    if (message === this.lastActivity) return;
+    this.lastActivity = message;
+    this.send('activity', { message, kind: activity?.type });
+  }
+
+  private errorOf(args: any[] | undefined): string | undefined {
+    const failure = args?.[1] ?? args?.[0]?.error;
+    if (!failure) return undefined;
+    if (typeof failure === 'string') return failure;
+    if (typeof failure.message === 'string') return failure.message;
+    return undefined;
+  }
+
+  private commandPath(command: Command): string {
+    const parts: string[] = [];
+    let node: Command | null = command;
+    while (node) {
+      parts.unshift(node.name());
+      node = node.parent;
+    }
+    return parts.slice(1).join(' ') || parts.join(' ');
+  }
+}
+
+export const remote = new Remote();
+
+/** Whatever the run wants to say. Not a schema — the UI renders what it knows
+ *  and ignores the rest, so either side can start sending more at any time. */
+type Frame = { type: string; ts: number; [key: string]: unknown };

package/src/reporter.ts

@@ -283,13 +283,19 @@ export class Reporter {
 
       debugLog(testData);
 
-      await this.client.addTestRun(status, testData);
+      await this.reportTestData(status, testData);
       debugLog(`Test reported: ${test.scenario} - ${status}`);
     } catch (error) {
       debugLog('Failed to report test:', error);
     }
   }
 
+  async reportTestData(status: string | null, testData: Record<string, unknown>): Promise<void> {
+    await this.startRun();
+    if (!this.isRunStarted) return;
+    await this.client.addTestRun(status, testData);
+  }
+
   async finishRun(): Promise<void> {
     if (!this.isRunStarted) {
       return;

package/src/state-manager.ts

@@ -1,4 +1,4 @@
-import { ActionResult } from './action-result.js';
+import { type FocusedElement, ActionResult } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 import { detectFocusArea } from './utils/aria.js';
@@ -46,6 +46,7 @@ export interface WebPageState {
   h4?: string;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  focusedElement?: FocusedElement | null;
   links?: Link[];
   verifications?: Record<string, boolean>;
 }

package/src/stats.ts

@@ -17,6 +17,7 @@ export class Stats {
   static plans = 0;
   static mode?: ExplorbotMode;
   static focus?: string;
+  static visionDisabled = false;
   static models: Record<string, TokenUsage> = {};
 
   static recordTokens(_agent: string, model: string, usage: TokenUsage): void {

package/src/test-plan.ts

@@ -27,6 +27,7 @@ export interface Note {
   endTime: number;
   screenshot?: string;
   log?: string;
+  observation?: boolean;
 }
 
 export class ActiveNote {
@@ -131,6 +132,14 @@ export class Task {
     this.notes[timestamp] = { message, status, startTime: now, endTime: now, screenshot, log };
   }
 
+  addObservation(message: string): void {
+    const isDuplicate = Object.values(this.notes).some((note) => note.message === message);
+    if (isDuplicate) return;
+
+    const now = performance.now();
+    this.notes[`${now}_${this.timestampCounter++}`] = { message, status: TestResult.FAILED, startTime: now, endTime: now, observation: true };
+  }
+
   addUrlNote(state: UrlNoteState, prevState?: { title?: string; h1?: string; h2?: string }): void {
     const fullUrl = state.fullUrl || state.url;
     if (!fullUrl) return;

package/src/utils/aria.ts

@@ -85,8 +85,7 @@ const parseLabel = (label: string): { role: string; name?: string; attributes: R
   }
 
   const attributes: Record<string, string | boolean | null> = {};
-  const attrMatch = rest.match(/\[([^\]]*)\]/);
-  if (attrMatch) {
+  for (const attrMatch of rest.matchAll(/\[([^\]]*)\]/g)) {
     for (const tok of attrMatch[1].split(/[\s,]+/).filter(Boolean)) {
       const eq = tok.indexOf('=');
       if (eq === -1) {
@@ -192,7 +191,9 @@ const dropEmpty = (nodes: AriaNode[], opts: { keepNamed?: boolean } = {}): AriaN
 // ─────────────────────────────────────────────────────────────────
 
 // One-line representation of a node. Stable attr order so diff comparisons are deterministic.
-const formatNode = (node: AriaNode): string => {
+const MAX_INLINE_VALUE = 400;
+
+const formatNode = (node: AriaNode, offload?: ValueOffload): string => {
   let line = node.role;
   if (node.name?.trim()) line += ` "${node.name.trim()}"`;
   const attrStr = Object.keys(node.attributes)
@@ -208,11 +209,19 @@ const formatNode = (node: AriaNode): string => {
   if (attrStr) line += ` [${attrStr}]`;
   if (node.value !== undefined && node.value !== null) {
     const text = String(node.value).trim();
-    if (text) line += `: ${text}`;
+    if (text && text.length <= MAX_INLINE_VALUE) line += `: ${text}`;
+    if (text && text.length > MAX_INLINE_VALUE) line += `: ${offloadValue(text, offload)}`;
   }
   return line;
 };
 
+const offloadValue = (text: string, offload?: ValueOffload): string => {
+  const head = `${text.slice(0, MAX_INLINE_VALUE)}…`;
+  const reference = offload?.(text);
+  if (!reference) return `${head} (${text.length} chars, truncated)`;
+  return `${head} (${text.length} chars) [Full Text: ${reference}]`;
+};
+
 // Group consecutive same-role siblings.  [a,a,b,a,a,a] → [[a,a],[b],[a,a,a]]
 const groupByConsecutiveRole = (nodes: AriaNode[]): AriaNode[][] =>
   nodes.reduce<AriaNode[][]>((groups, node) => {
@@ -239,15 +248,15 @@ const collapseGroup = (group: AriaNode[], depth: number): RenderEntry[] => {
 const collapseSiblingGroups = (nodes: AriaNode[], depth: number): RenderEntry[] => groupByConsecutiveRole(nodes).flatMap((group) => collapseGroup(group, depth));
 
 // Tree → indented YAML text.
-const renderTree = (nodes: AriaNode[], depth = 0): string =>
+const renderTree = (nodes: AriaNode[], depth = 0, offload?: ValueOffload): string =>
   collapseSiblingGroups(nodes, depth)
     .map((entry) => {
       if ('placeholder' in entry) return entry.placeholder;
       const { node } = entry;
       const indent = '  '.repeat(depth);
-      const head = `${indent}- ${formatNode(node)}`;
+      const head = `${indent}- ${formatNode(node, offload)}`;
       if (node.children.length === 0) return head;
-      return `${head}:\n${renderTree(node.children, depth + 1)}`;
+      return `${head}:\n${renderTree(node.children, depth + 1, offload)}`;
     })
     .join('\n');
 
@@ -382,6 +391,40 @@ const detectToggles = (prev: FlatEntry[], curr: FlatEntry[]): { toggled: string[
   return { toggled, togglePaths };
 };
 
+const detectValueChanges = (prev: FlatEntry[], curr: FlatEntry[]): { typed: string[]; typedPaths: Set<string> } => {
+  const typed: string[] = [];
+  const typedPaths = new Set<string>();
+  const currByPath = new Map(curr.map((e) => [e.path, e]));
+
+  for (const before of prev) {
+    const after = currByPath.get(before.path);
+    if (!after) continue;
+    if (before.entry.role !== after.entry.role) continue;
+    if (before.entry.name !== after.entry.name) continue;
+
+    const was = valueWord(before.entry.value);
+    const now = valueWord(after.entry.value);
+    if (was === now) continue;
+
+    typedPaths.add(before.path);
+    let label = String(after.entry.role);
+    const name = after.entry.name;
+    if (typeof name === 'string' && name.trim()) label += ` "${name.trim()}"`;
+    typed.push(`${label}: ${was} -> ${now}`);
+  }
+  return { typed, typedPaths };
+};
+
+const VALUE_EXCERPT = 60;
+
+const valueWord = (value: unknown): string => {
+  if (value === undefined || value === null) return 'empty';
+  const text = String(value).trim();
+  if (!text) return 'empty';
+  if (text.length <= VALUE_EXCERPT) return JSON.stringify(text);
+  return `${JSON.stringify(text.slice(0, VALUE_EXCERPT))}… (${text.length} chars)`;
+};
+
 const TOP_DIFF_ITEMS = 10;
 
 const formatDiffSection = (label: string, items: string[]): string[] => {
@@ -406,9 +449,13 @@ const formatDiffSection = (label: string, items: string[]): string[] => {
   return lines;
 };
 
-const formatDiff = (added: string[], removed: string[], toggled: string[]): string | null => {
-  if (added.length === 0 && removed.length === 0 && toggled.length === 0) return null;
+const formatDiff = (added: string[], removed: string[], toggled: string[], typed: string[] = []): string | null => {
+  if (added.length === 0 && removed.length === 0 && toggled.length === 0 && typed.length === 0) return null;
   const sections = ['ariaDiff:'];
+  if (typed.length > 0) {
+    sections.push('  typed:');
+    for (const line of typed) sections.push(`    - ${line}`);
+  }
   if (toggled.length > 0) {
     sections.push('  toggled:');
     for (const line of toggled) sections.push(`    - ${line}`);
@@ -474,13 +521,15 @@ const findDialogOrModal = (nodes: AriaNode[]): FocusAreaResult | null => {
 // Public API — pipelines composed visibly, top-to-bottom
 // ─────────────────────────────────────────────────────────────────
 
-export const compactAriaSnapshot = (snapshot: string | null, keepNamed = false): string => {
+export type ValueOffload = (value: string) => string | undefined;
+
+export const compactAriaSnapshot = (snapshot: string | null, keepNamed = false, offload?: ValueOffload): string => {
   if (!snapshot) return '';
   let tree = parseSnapshot(snapshot);
   tree = unwrapIgnored(tree);
   tree = nameIconButtons(tree);
   tree = dropEmpty(tree, { keepNamed });
-  return renderTree(tree);
+  return renderTree(tree, 0, offload);
 };
 
 export const diffAriaSnapshots = (previous: string | null, current: string | null): AriaDiff => {
@@ -494,15 +543,17 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
   const prevAll = flat(previous);
   const currAll = flat(current);
   const { toggled, togglePaths } = detectToggles(prevAll, currAll);
-  const prev = prevAll.filter((e) => !togglePaths.has(e.path));
-  const curr = currAll.filter((e) => !togglePaths.has(e.path));
+  const { typed, typedPaths } = detectValueChanges(prevAll, currAll);
+  const skip = (entry: FlatEntry) => togglePaths.has(entry.path) || typedPaths.has(entry.path);
+  const prev = prevAll.filter((e) => !skip(e));
+  const curr = currAll.filter((e) => !skip(e));
   const prevTotals = countBy(prev.map((e) => e.summary));
   const currTotals = countBy(curr.map((e) => e.summary));
   const byCount = diffByCount(prevTotals, currTotals);
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
   const added = [...byCount.added, ...renames.added];
   const removed = [...byCount.removed, ...renames.removed];
-  return { text: formatDiff(added, removed, toggled), count: added.length + removed.length + toggled.length };
+  return { text: formatDiff(added, removed, toggled, typed), count: added.length + removed.length + toggled.length + typed.length };
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
@@ -531,37 +582,6 @@ export const collectInteractiveNodes = (snapshot: string | null): Array<Record<s
 // Standalone helpers (regex on raw strings — not part of the pipeline)
 // ─────────────────────────────────────────────────────────────────
 
-export interface FocusedElementInfo {
-  role: string;
-  name: string;
-  value?: string;
-  attributes?: string[];
-}
-
-export function extractFocusedElement(ariaSnapshot: string | null): FocusedElementInfo | null {
-  if (!ariaSnapshot) return null;
-
-  const focusedMatch = ariaSnapshot.match(/-\s*(\w+)\s+"([^"]*)"([^:\n]*)\[focused\](?::\s*(.*))?/);
-  if (!focusedMatch) return null;
-
-  const [, role, name, attributesStr, value] = focusedMatch;
-
-  const attributes: string[] = [];
-  if (attributesStr) {
-    const attrMatches = attributesStr.matchAll(/\[([^\]]+)\]/g);
-    for (const match of attrMatches) {
-      if (match[1] !== 'focused') {
-        attributes.push(match[1]);
-      }
-    }
-  }
-
-  const result: FocusedElementInfo = { role, name };
-  if (value) result.value = value.trim();
-  if (attributes.length > 0) result.attributes = attributes;
-  return result;
-}
-
 export function parseAriaLocator(ariaStr: string): { role: string; text: string } | null {
   const trimmed = ariaStr.trim();
   if (trimmed === '-' || trimmed === '' || trimmed === '"-"') return null;

package/src/utils/html.ts

@@ -1518,6 +1518,7 @@ function cleanElement(element: parse5TreeAdapter.Element): void {
       attr.value = attr.value
         .split(/\s+/)
         .filter((className) => !/\d/.test(className))
+        .filter((className) => !className.includes(':'))
         .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))
         .join(' ');
 

package/src/utils/logger.ts

@@ -24,7 +24,7 @@ export interface TaggedLogEntry {
 
 type LogEntry = TaggedLogEntry;
 
-interface LogDestination {
+export interface LogDestination {
   isEnabled(): boolean;
   write(entry: TaggedLogEntry): void;
 }
@@ -79,9 +79,11 @@ const debugFilter = new DebugFilter();
 class ConsoleDestination implements LogDestination {
   private verboseMode = false;
   private forceEnabled = false;
+  private quiet = false;
   private recentSteps = new RecentStepFilter();
 
   isEnabled(): boolean {
+    if (this.quiet) return false;
     return this.forceEnabled || !process.env.INK_RUNNING;
   }
 
@@ -89,6 +91,10 @@ class ConsoleDestination implements LogDestination {
     this.forceEnabled = enabled;
   }
 
+  setQuiet(enabled: boolean): void {
+    this.quiet = enabled;
+  }
+
   setVerboseMode(enabled: boolean): void {
     this.verboseMode = enabled;
   }
@@ -136,6 +142,8 @@ class DebugDestination implements LogDestination {
 
   setVerboseMode(enabled: boolean): void {
     this.verboseMode = enabled;
+    // the debug package reads DEBUG when it loads, so a namespace turned on later needs enabling by hand
+    if (enabled) debug.enable(process.env.DEBUG || 'explorbot:*');
   }
 
   write(namespace: string, ...args: any[]): void {
@@ -332,6 +340,7 @@ class Logger {
   private span = new SpanDestination();
   public react = new ReactDestination();
   public captain = new CaptainDestination();
+  private extra: LogDestination[] = [];
   private truncateTags: string[] = ['page_html'];
 
   private constructor() {}
@@ -360,10 +369,19 @@ class Logger {
     this.console.forceEnable(enabled);
   }
 
+  setQuietMode(enabled: boolean): void {
+    this.console.setQuiet(enabled);
+  }
+
   isVerboseMode(): boolean {
     return this.debugDestination.isEnabled();
   }
 
+  addDestination(destination: LogDestination): void {
+    if (this.extra.includes(destination)) return;
+    this.extra.push(destination);
+  }
+
   registerLogPane(addLog: (entry: LogEntry) => void): void {
     this.react.registerLogPane(addLog);
   }
@@ -456,6 +474,9 @@ class Logger {
     if (this.file.isEnabled()) this.file.write(entry);
     if (this.span.isEnabled()) this.span.write(entry);
     if (this.captain.isEnabled()) this.captain.write(entry);
+    for (const destination of this.extra) {
+      if (destination.isEnabled()) destination.write(entry);
+    }
     if (process.env.INK_RUNNING) {
       this.react.write(entry);
     } else if (this.console.isEnabled()) {
@@ -537,10 +558,12 @@ export const startLogCapture = () => logger.captain.startCapture();
 export const stopLogCapture = () => logger.captain.stopCapture();
 export const setVerboseMode = (enabled: boolean) => logger.setVerboseMode(enabled);
 export const setPreserveConsoleLogs = (enabled: boolean) => logger.setPreserveConsoleLogs(enabled);
+export const setQuietMode = (enabled: boolean) => logger.setQuietMode(enabled);
 export const isVerboseMode = () => logger.isVerboseMode();
 export const setDebugMode = (enabled: boolean) => logger.setDebugMode(enabled);
 export const isDebugMode = () => logger.isDebugMode();
 
+export const addDestination = (destination: LogDestination) => logger.addDestination(destination);
 export const registerLogPane = (addLog: (entry: LogEntry) => void) => logger.registerLogPane(addLog);
 export const unregisterLogPane = (addLog: (entry: LogEntry) => void) => logger.unregisterLogPane(addLog);
 export const addTruncateTag = (tagName: string) => logger.addTruncateTag(tagName);

package/src/utils/page-readiness.ts

@@ -4,10 +4,33 @@ export async function waitForPageReadiness(page: any, options: PageReadinessOpti
   const timeout = options.timeout ?? 6000;
   await page.waitForLoadState?.('domcontentloaded', { timeout })?.catch(() => {});
 
-  await Promise.race([waitForNetworkIdle(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => {});
+  await Promise.race([waitForNetworkIdle(page, timeout), waitForDomQuiet(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => {});
   await waitForPageBodyContent(page, timeout);
 }
 
+const DOM_QUIET_MS = 350;
+
+function waitForDomQuiet(page: any, timeout: number): Promise<void> {
+  if (!page?.waitForFunction) return new Promise(() => {});
+
+  return page
+    .waitForFunction(
+      (quiet: number) => {
+        const store = window as any;
+        if (!store.__explorbotDomQuiet) {
+          store.__explorbotDomQuiet = { last: Date.now() };
+          new MutationObserver(() => {
+            store.__explorbotDomQuiet.last = Date.now();
+          }).observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+        }
+        return Date.now() - store.__explorbotDomQuiet.last >= quiet;
+      },
+      DOM_QUIET_MS,
+      { timeout, polling: 100 }
+    )
+    .catch(() => {});
+}
+
 function waitForNetworkIdle(page: any, timeout: number): Promise<void> {
   if (!page?.waitForLoadState) return Promise.resolve();
   return page.waitForLoadState('networkidle', { timeout }).catch(() => {});

package/src/utils/url-matcher.ts

@@ -100,6 +100,9 @@ export function matchesNavigationUrl(expected: string, current: string): boolean
   if (!expectedPath.includes('#')) {
     currentPath = currentPath.split('#')[0];
   }
+  if (!expectedPath.includes('?')) {
+    currentPath = currentPath.split('?')[0];
+  }
   const normalize = (value: string) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
   return normalize(expectedPath) === normalize(currentPath);
 }

package/src/utils/web-element.ts

@@ -125,6 +125,15 @@ export class WebElement {
     return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
   }
 
+  static isAriaRef(ref: string): boolean {
+    return /^(f\d+)?e\d+$/i.test(ref);
+  }
+
+  static async fromAriaRef(page: any, ref: string): Promise<WebElement | null> {
+    if (!WebElement.isAriaRef(ref)) return null;
+    return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
+  }
+
   static async fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]> {
     const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
     if (validEidxList.length === 0) return [];

package/src/utils/web-sandbox.ts

@@ -28,13 +28,12 @@ export function playwrightSandbox(page: any, code: string): Promise<any> {
   return run(page);
 }
 
-export function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): void {
+export function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): any {
   if (typeof codeOrFn === 'function') {
-    codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
-    return;
+    return codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
   }
   const run = createSandbox(CODECEPT_ARG_NAMES, codeOrFn);
-  run(actor, tryTo, retryTo, within, hopeThat, step, faker);
+  return run(actor, tryTo, retryTo, within, hopeThat, step, faker);
 }
 
 function createSandbox(argNames: string[], body: string): (...args: any[]) => any {