explorbot 0.2.3 → 0.2.5

package/src/state-manager.ts

@@ -1,8 +1,8 @@
-import { ActionResult } from './action-result.js';
+import { ActionResult, type FocusedElement } 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';
-import { createDebug } from './utils/logger.js';
+import { createDebug, tag } from './utils/logger.js';
 import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
@@ -46,6 +46,7 @@ export interface WebPageState {
   h4?: string;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  focusedElement?: FocusedElement | null;
   links?: Link[];
   verifications?: Record<string, boolean>;
 }
@@ -116,6 +117,9 @@ export class StateManager {
    * Emit state change event to all listeners
    */
   private emitStateChange(event: StateTransition): void {
+    const state = event.toState;
+    tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+
     this.stateChangeListeners.forEach((listener) => {
       try {
         listener(event);

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

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import figures from 'figures';
 import { WebPageState } from './state-manager.ts';
+import { tag } from './utils/logger.ts';
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from './utils/test-plan-markdown.ts';
 import { uniqSessionName } from './utils/unique-names.ts';
 
@@ -27,6 +28,7 @@ export interface Note {
   endTime: number;
   screenshot?: string;
   log?: string;
+  observation?: boolean;
 }
 
 export class ActiveNote {
@@ -131,6 +133,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;
@@ -308,6 +318,7 @@ export class Test extends Task {
     this.startTime = performance.now();
     this.addNote(`Test started. Session name: ${this.sessionName}`);
     this.plan?.notifyChange();
+    this.reportStatus();
   }
 
   finish(result: TestResultType = TestResult.FAILED): void {
@@ -315,6 +326,7 @@ export class Test extends Task {
     this.result = result;
     this.endTime = performance.now();
     this.plan?.notifyChange();
+    this.reportStatus();
   }
 
   getDurationMs(): number | null {
@@ -327,6 +339,18 @@ export class Test extends Task {
     return this.expected.filter((e) => !achieved.includes(e));
   }
 
+  private reportStatus(): void {
+    tag('data').log('test', {
+      scenario: this.scenario,
+      status: this.status,
+      result: this.result,
+      priority: this.priority,
+      sessionName: this.sessionName,
+      url: this.startUrl,
+      plan: this.plan?.title,
+    });
+  }
+
   override getLog(): Array<{ type: 'step' | 'note' | 'artifact'; content: string; timestamp: number }> {
     const merged: Record<string, { type: 'step' | 'note' | 'artifact'; content: string }> = {};
 
@@ -398,6 +422,11 @@ export class Plan {
     for (const listener of this.changeListeners) {
       listener(this.tests);
     }
+    tag('data').log('plan', {
+      title: this.title,
+      url: this.url,
+      tests: this.tests.map((test) => ({ scenario: test.scenario, status: test.status, result: test.result, priority: test.priority })),
+    });
   }
 
   getAllTests(): Test[] {

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

@@ -11,7 +11,7 @@ import { Observability } from '../observability.ts';
 import { RecentStepFilter } from './log-filters.ts';
 import { parseMarkdownToTerminal } from './markdown-terminal.ts';
 
-export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input';
+export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input' | 'data';
 
 export interface TaggedLogEntry {
   type: LogType;
@@ -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);
   }
@@ -440,6 +458,14 @@ class Logger {
       return;
     }
 
+    if (type === 'data') {
+      const entry: TaggedLogEntry = { type, content: String(args[0]), timestamp: new Date(), originalArgs: args };
+      for (const destination of this.extra) {
+        if (destination.isEnabled()) destination.write(entry);
+      }
+      return;
+    }
+
     const options = this.extractLogOptions(type, args);
     let content = this.processArgs(args);
     if (type === 'step' && args[0]?.toCode) {
@@ -456,6 +482,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 +566,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 {