explorbot 0.5.3 → 0.5.5

package/src/ai/navigator.ts

@@ -13,6 +13,7 @@ import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -24,7 +25,7 @@ import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from './tools.ts';
 
@@ -59,7 +60,7 @@ class Navigator implements Agent {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -136,11 +137,11 @@ class Navigator implements Agent {
     return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
-  async visit(url: string): Promise<void> {
-    return this.visitOnce(url);
+  async visit(url: string, opts: { recover?: boolean } = {}): Promise<boolean> {
+    return this.visitOnce(url, opts.recover !== false);
   }
 
-  private async visitOnce(url: string): Promise<void> {
+  private async visitOnce(url: string, recover: boolean): Promise<boolean> {
     try {
       const action = this.explorer.action();
 
@@ -153,7 +154,10 @@ class Navigator implements Agent {
 
       await this.hooksRunner.runBeforeHook('navigator', url);
 
-      if (!this.isOnExpectedPage(url, action.stateManager)) {
+      if (!recover && action.lastError) throw new Error(`Navigation to ${url} failed: ${action.lastError.message}`);
+
+      const arrived = this.isOnExpectedPage(url, action.stateManager);
+      if (recover && !arrived) {
         const actualPath = action.stateManager.getCurrentState()?.url || '';
         const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState()!);
         const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
@@ -177,6 +181,7 @@ class Navigator implements Agent {
       }
       await this.explorer.capture({ screenshot: true });
       await this.hooksRunner.runAfterHook('navigator', url);
+      return arrived || recover;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       if (errorMessage.includes('ERR_CONNECTION_REFUSED')) {
@@ -284,7 +289,7 @@ class Navigator implements Agent {
             return;
           }
           tag('operation').log('Feeding failures back to AI for a new batch...');
-          conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, actionResult));
+          conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, action.actionResult ?? actionResult));
           htmlContextAdded = true;
           codeBlocks = [];
           batchFailures.length = 0;
@@ -377,6 +382,9 @@ class Navigator implements Agent {
       experience = this.experienceTracker.renderExperienceFor(actionResult);
     }
 
+    let credentials = '';
+    if (isLoginPage(actionResult)) credentials = credentialsRule;
+
     return dedent`
       <message>
         ${message}
@@ -384,10 +392,6 @@ class Navigator implements Agent {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -397,6 +401,8 @@ class Navigator implements Agent {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
 
@@ -404,6 +410,8 @@ class Navigator implements Agent {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}
@@ -813,7 +821,9 @@ class Navigator implements Agent {
 
           const verified = await action.attempt(codeBlock, message);
           const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
-          results.push({ code: codeBlock, passed: verified, proof });
+          const result: AssertionResult = { code: codeBlock, passed: verified, proof };
+          if (!verified && action.lastError) result.error = action.lastError.message;
+          results.push(result);
 
           if (verified) {
             tag('success').log('Verification passed');
@@ -862,6 +872,6 @@ class Navigator implements Agent {
 
 type BatchFailure = { code: string; error: string; ariaChanges?: string | null; urlAfter?: string };
 
-export type AssertionResult = { code: string; passed: boolean; proof: string[] };
+export type AssertionResult = { code: string; passed: boolean; proof: string[]; error?: string };
 
 export { Navigator };

package/src/ai/pilot.ts

@@ -8,7 +8,7 @@ import type Explorer from '../explorer.ts';
 import type { PlaywrightRecorder } from '../playwright-recorder.ts';
 import type { StateManager } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
-import { type Test, TestResult, TestStatus } from '../test-plan.ts';
+import { SettledExpectation, type SettledStatus, type Test, TestResult, TestStatus } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
 import { ErrorPageError } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -39,6 +39,12 @@ const OUTCOME_STATUS: Record<string, SettledStatus> = {
   'The run shows this outcome did not happen.': 'failed',
 };
 
+const CONTRADICTION_RESOLUTION: Record<string, { status: SettledStatus; resolution: string }> = {
+  'The page structure agrees with the screenshot, and the outcome happened.': { status: 'passed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the screenshot, and the outcome did not happen.': { status: 'failed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the run log: the page holds it, but the screenshot does not show it.': { status: 'contradiction', resolution: 'the page structure agrees with the run log: the page holds it but does not display it, a likely rendering bug' },
+};
+
 export class Pilot implements Agent {
   emoji = '🧭';
   private provider: Provider;
@@ -619,7 +625,7 @@ export class Pilot implements Agent {
     let settledByJudge = new Map<string, SettledStatus>();
     if (!image) settledByJudge = await this.settleByJudge(task, undecided);
     undecided = undecided.filter((text) => !settledByJudge.has(text));
-    if (!undecided.length) return task.expected.map((text) => ({ text, status: settledByJudge.get(text) || decided(text) }));
+    if (!undecided.length) return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
 
     const schema = z.object({
       outcomes: z.array(
@@ -691,14 +697,36 @@ export class Pilot implements Agent {
     if (!response) response = await settle(userContent, this.provider.getAgenticModel('pilot'));
 
     const judged = new Map((response?.object?.outcomes || []).map((outcome: any) => [outcome.expectation, outcome]));
-    return task.expected.map((text) => {
+    const settled = task.expected.map((text) => {
       const byJudge = settledByJudge.get(text);
-      if (byJudge) return { text, status: byJudge };
-      if (!undecided.includes(text)) return { text, status: decided(text) };
+      if (byJudge) return new SettledExpectation(text, byJudge);
+      if (!undecided.includes(text)) return new SettledExpectation(text, decided(text));
       const outcome = judged.get(text) as { status: SettledStatus; evidence?: string } | undefined;
-      if (!outcome) return { text, status: 'unverified' as SettledStatus };
-      return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+      if (!outcome) return new SettledExpectation(text, 'unverified');
+      return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
     });
+    return this.resolveContradictions(settled, finalState);
+  }
+
+  private async resolveContradictions(outcomes: SettledExpectation[], finalState?: ActionResult): Promise<SettledExpectation[]> {
+    const judge = this.judge;
+    if (!judge || !finalState) return outcomes;
+    if (!outcomes.some((outcome) => outcome.contradicted)) return outcomes;
+
+    const page = finalState.getCompactARIA().slice(0, JUDGE_PAGE_CAP);
+    return Promise.all(
+      outcomes.map(async (outcome) => {
+        if (!outcome.contradicted) return outcome;
+        const decision = await judge.decide(`The screenshot and the run log disagree about the expected outcome: ${outcome.text}. Which side does the page structure support?`, [...Object.keys(CONTRADICTION_RESOLUTION), UNDECIDED], {
+          expectation: outcome.text,
+          disagreement: outcome.evidence || '',
+          page,
+        });
+        const resolved = CONTRADICTION_RESOLUTION[decision.value ?? ''];
+        if (!resolved) return outcome;
+        return outcome.resolve(resolved.status, resolved.resolution);
+      })
+    );
   }
 
   private async settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>> {
@@ -1275,11 +1303,3 @@ export class Pilot implements Agent {
     `;
   }
 }
-
-export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
-
-export interface SettledExpectation {
-  text: string;
-  status: SettledStatus;
-  evidence?: string;
-}

package/src/ai/researcher.ts

@@ -103,8 +103,8 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
-    const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; light?: boolean; _retriesLeft?: number } = {}): Promise<string> {
+    const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
     const maxRetries = this.settings.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
@@ -133,6 +133,7 @@ export class Researcher extends ResearcherBase implements Agent {
     return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
       const displayUrl = state.fullUrl || state.url;
       tag('info').log(`Researching ${displayUrl} to understand the context...`);
+      if (light) tag('info').log('Light research: single pass, locator verification skipped');
       setActivity(`${this.emoji} Researching...`, 'action');
 
       await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
@@ -171,7 +172,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       const isOnCurrentState = this.actionResult!.getStateHash() === this.stateManager.getCurrentState()?.hash;
-      this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+      this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
 
       const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
 
@@ -205,13 +206,13 @@ export class Researcher extends ResearcherBase implements Agent {
       result.parseLocators();
       debugLog(`Extracted ${result.locators.length} locators from research`);
 
-      if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+      if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
         tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
         await new Promise((r) => setTimeout(r, 1000));
         return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 } as any);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         const brokenContainers = await this.resolveContainers(result);
         const containerCount = result.containers.length;
         if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -232,7 +233,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 3: Fix broken sections via AI conversation continuation
-      if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+      if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
         await this.fixBrokenSections(result, activeConversation);
       }
 
@@ -273,12 +274,12 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 5: Backfill broken elements
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.backfillCoordinates(result);
         await this.backfillBrokenLocators(result);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.detectPagination(result);
       }
 
@@ -309,7 +310,7 @@ export class Researcher extends ResearcherBase implements Agent {
       result.cleanup();
 
       let researchFile: string | null = null;
-      if (stateHash) {
+      if (stateHash && !light) {
         researchFile = saveResearch(researchState, result.text, combinedHtml);
       }
 

package/src/ai/rules.ts

@@ -147,6 +147,14 @@ export const formRequirementsRule = dedent`
   </form_requirements>
 `;
 
+export const credentialsRule = dedent`
+  <credentials>
+  Sign in to an existing account only with credentials present in the provided context (message, knowledge, experience).
+  Never invent, guess, or try default, common, or placeholder credentials for an existing account.
+  If the required credentials are not provided, call stop() and name what is missing — do not submit the form.
+  </credentials>
+`;
+
 // in rage mode we do not protect from irreversible actions
 export const protectionRule = dedent`
   <important>

package/src/ai/tools.ts

@@ -112,7 +112,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         let ambiguityError: Error | null = null;
 
         for (let i = 0; i < commands.length; i++) {
-          const command = transformContainsCommand(commands[i]);
+          let command = transformContainsCommand(commands[i]);
           let success = await action.attempt(command, explanation);
 
           const attempt: { command: string; success: boolean; error?: string } = { command, success };
@@ -125,10 +125,14 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
               const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
               const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
               if (index) success = await action.attemptExactElementIndex(command, index, explanation);
+              if (success) command = action.executedSteps.map((step) => step.command).join('\n') || command;
             }
           }
 
           if (success) {
+            attempt.command = command;
+            attempt.success = true;
+            attempt.error = undefined;
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
 
             if (!hasObservablePageChange(toolResult)) {

package/src/explorbot.ts

@@ -155,7 +155,7 @@ export class ExplorBot {
   }
 
   async visit(url: string): Promise<void> {
-    return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+    await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
   }
 
   async openTab(): Promise<void> {

package/src/test-plan.ts

@@ -66,6 +66,29 @@ export class ActiveNote {
   }
 }
 
+export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
+
+export class SettledExpectation {
+  constructor(
+    readonly text: string,
+    readonly status: SettledStatus,
+    readonly evidence?: string,
+    readonly resolution?: string
+  ) {}
+
+  get failed(): boolean {
+    return this.status === 'failed';
+  }
+
+  get contradicted(): boolean {
+    return this.status === 'contradiction';
+  }
+
+  resolve(status: SettledStatus, resolution: string): SettledExpectation {
+    return new SettledExpectation(this.text, status, this.evidence, resolution);
+  }
+}
+
 export interface StepData {
   text: string;
   duration?: number;

package/src/utils/code-extractor.ts

@@ -3,6 +3,9 @@ import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
 
 const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+const QUOTES = ["'", '"', '`'];
+const OPENING_BRACKETS = ['(', '[', '{'];
+const CLOSING_BRACKETS = [')', ']', '}'];
 
 export function extractCodeBlocks(aiResponse: string): string[] {
   const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
@@ -24,3 +27,41 @@ export function extractCodeBlocks(aiResponse: string): string[] {
 
   return codeBlocks;
 }
+
+export function splitTopLevel(code: string, separator: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let quote = '';
+
+  for (let i = 0; i < code.length; i++) {
+    const char = code[i];
+
+    if (quote) {
+      current += char;
+      if (char === '\\') current += code[++i] || '';
+      if (char === quote) quote = '';
+      continue;
+    }
+
+    if (char === '/' && code[i + 1] === '/') {
+      while (i + 1 < code.length && code[i + 1] !== '\n') i++;
+      continue;
+    }
+
+    if (char === separator && depth <= 0) {
+      parts.push(current);
+      current = '';
+      depth = 0;
+      continue;
+    }
+
+    current += char;
+    if (QUOTES.includes(char)) quote = char;
+    if (OPENING_BRACKETS.includes(char)) depth++;
+    if (CLOSING_BRACKETS.includes(char)) depth--;
+  }
+
+  parts.push(current);
+  return parts;
+}

package/src/utils/error-page.ts

@@ -1,11 +1,14 @@
 import { ActionResult } from '../action-result.js';
 import type { WebPageState } from '../state-manager.js';
 import { isBodyEmpty } from './html.js';
+import { extractStatePath } from './url-matcher.js';
 
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
+const PASSWORD_INPUT = /<input\b[^>]*\btype\s*=\s*["']?password\b/i;
+const AUTH_PATH = /\b(log[-_]?in|sign[-_]?in|auth)\b/i;
 
 export type PageCondition = 'ok' | 'loading' | 'error';
 
@@ -40,6 +43,11 @@ export function isErrorPage(actionResult: ActionResult): boolean {
   return detectPageCondition(actionResult) === 'error';
 }
 
+export function isLoginPage(actionResult: ActionResult): boolean {
+  if (PASSWORD_INPUT.test(actionResult.html || '')) return true;
+  return AUTH_PATH.test(extractStatePath(actionResult.url || '').split('?')[0]);
+}
+
 export function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null {
   if (!state) return null;
   const actionResult = ActionResult.fromState(state);

package/src/utils/html.ts

@@ -88,6 +88,7 @@ export const EXPLORBOT_ATTRS = {
   coveredBy: 'data-explorbot-covered-by',
   context: 'data-explorbot-context',
   eidx: 'data-explorbot-eidx',
+  hidden: 'data-explorbot-hidden',
   hit: 'data-explorbot-hit',
   variant: 'data-explorbot-variant',
 } as const;
@@ -189,6 +190,17 @@ export function captureHtmlForSnapshot(): string {
     }
   }
 
+  const liveElements = Array.from(document.body?.querySelectorAll('*') || []);
+  const clonedElements = Array.from(clone.querySelector('body')?.querySelectorAll('*') || []);
+  for (let i = 0; i < liveElements.length; i++) {
+    const source = liveElements[i];
+    if (source.matches('input, textarea, select, option, optgroup')) continue;
+    if (source.checkVisibility()) continue;
+    if (!source.parentElement?.checkVisibility()) continue;
+    if (getComputedStyle(source).display === 'contents') continue;
+    clonedElements[i]?.setAttribute('data-explorbot-hidden', 'true');
+  }
+
   return clone.outerHTML;
 }
 
@@ -1493,7 +1505,27 @@ function getAttribute(element: parse5TreeAdapter.Element, name: string): string
   return attr?.value;
 }
 
+function getImgAlt(element: parse5TreeAdapter.Element): string {
+  let alt = '';
+
+  function processNode(node: parse5TreeAdapter.Node) {
+    if (alt) return;
+    if ('tagName' in node) {
+      const el = node as parse5TreeAdapter.Element;
+      if (el.tagName.toLowerCase() === 'img') {
+        alt = getAttribute(el, 'alt') || '';
+        return;
+      }
+    }
+    if ('childNodes' in node) node.childNodes.forEach(processNode);
+  }
+
+  processNode(element);
+  return alt;
+}
+
 function hasHiddenClass(element: parse5TreeAdapter.Element): boolean {
+  if (getAttribute(element, EXPLORBOT_ATTRS.hidden)) return true;
   const classAttr = element.attrs.find((attr) => attr.name === 'class');
   if (!classAttr) return false;
 
@@ -1553,7 +1585,7 @@ export function extractLinks(html: string): ExtractedLink[] {
         if (href) {
           const shouldSkip = skipPrefixes.some((prefix) => href.startsWith(prefix));
           if (!shouldSkip) {
-            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element);
+            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element) || getImgAlt(element);
             const title = sanitizeLinkTitle(rawTitle);
             if (title && title.length <= 100) {
               const key = `${href}|${title}`;

package/src/utils/mdq/cli.ts

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, type CommanderError } from 'commander';
 import { type MarkdownQuery, MdqError, mdq } from './query.ts';
 
 const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend', 'append', 'addRow', 'addItem', 'set'] as const;
@@ -7,7 +7,7 @@ const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend
 export async function runMdq(argv: string[], readStdin: StdinReader): Promise<CliResult> {
   const program = new Command();
   program
-    .name('mdq')
+    .name('mdq-cli')
     .description('query and edit markdown')
     .argument('[selector]', 'markdown selector')
     .argument('[file]', 'file to read; stdin when omitted')
@@ -31,6 +31,7 @@ export async function runMdq(argv: string[], readStdin: StdinReader): Promise<Cl
   try {
     program.parse(argv, { from: 'user' });
   } catch (error) {
+    if ((error as CommanderError).code === 'commander.helpDisplayed') return { output: program.helpInformation(), code: 0 };
     return { output: String((error as Error).message), code: 2 };
   }
 

package/src/utils/mdq/query.ts

@@ -13,9 +13,12 @@ export class MarkdownQuery {
   }
 
   query(selector: string, matcher?: Matcher): MarkdownQuery {
-    const segments = parseQuery(selector);
-    if (matcher !== undefined && segments.length > 0) segments[segments.length - 1].textMatch = this.valueMatcher(matcher);
-    return new MarkdownQuery(this.source, this.run(this.expandSections(this.matches), segments));
+    const expression = parseQuery(selector);
+    for (const chain of expression.flat()) {
+      const last = chain.at(-1);
+      if (matcher !== undefined && last) last.textMatch = this.valueMatcher(matcher);
+    }
+    return new MarkdownQuery(this.source, this.evaluate(this.expandSections(this.matches), expression));
   }
 
   section(matcher?: Matcher, options?: SelectorOptions): MarkdownQuery {
@@ -364,6 +367,27 @@ export class MarkdownQuery {
     return expanded;
   }
 
+  private evaluate(candidates: MatchedRange[], expression: QueryExpression): MatchedRange[] {
+    const results: MatchedRange[][] = [];
+    for (const operands of expression) {
+      const matched = operands.map((chain) => this.run(candidates, chain));
+      if (matched.some((ranges) => ranges.length === 0)) continue;
+      results.push(...matched);
+    }
+    return this.union(results);
+  }
+
+  private union(results: MatchedRange[][]): MatchedRange[] {
+    if (results.length === 1) return results[0];
+
+    const unique = new Map<string, MatchedRange>();
+    for (const range of results.flat()) {
+      const key = `${range.start}:${range.length}:${Boolean(range.innerTokens)}`;
+      if (!unique.has(key)) unique.set(key, range);
+    }
+    return [...unique.values()].sort((a, b) => a.start - b.start || b.length - a.length);
+  }
+
   private narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[] {
     if (segment.index !== null) {
       let index = segment.index;
@@ -449,12 +473,24 @@ export function mdq(source: Markdown): MarkdownQuery {
   return new MarkdownQuery(String(source));
 }
 
-export function parseQuery(input: string): QuerySegment[] {
-  const segments: QuerySegment[] = [];
+export function parseQuery(input: string): QueryExpression {
+  const expression: QueryExpression = [[[]]];
+  let chain = expression[0][0];
   SEGMENT.lastIndex = 0;
 
   while (SEGMENT.lastIndex < input.length) {
     const at = SEGMENT.lastIndex;
+    OPERATOR.lastIndex = at;
+    const operator = OPERATOR.exec(input);
+    if (operator) {
+      if (chain.length === 0) throw new MdqSelectorError(`Empty selector before ${operator[1]}`, at);
+      chain = [];
+      if (operator[1] === '||') expression.push([chain]);
+      if (operator[1] === '&&') expression[expression.length - 1].push(chain);
+      SEGMENT.lastIndex = OPERATOR.lastIndex;
+      continue;
+    }
+
     const match = SEGMENT.exec(input);
     if (!match) throw new MdqSelectorError(`Unexpected character "${input[at]}" in selector`, at);
 
@@ -484,10 +520,11 @@ export function parseQuery(input: string): QuerySegment[] {
       if (to) segment.slice.to = Number.parseInt(to, 10);
     }
 
-    segments.push(segment);
+    chain.push(segment);
   }
 
-  return segments;
+  if (expression.flat().length > 1 && chain.length === 0) throw new MdqSelectorError('Empty selector after operator', input.length);
+  return expression;
 }
 
 export function buildTokenIndex(source: string): MatchedRange[] {
@@ -516,6 +553,8 @@ const TOKEN_ALIASES: Record<string, string> = { item: 'list_item' };
 
 const SEGMENT = /(\s*\.?)([A-Za-z]\w*)(?:\((!?)(~?)(?:"((?:[^"\\]|\\.)*)"|\/((?:[^/\\]|\\.)*)\/([a-z]*))\))?((?:\[[^\]]*\])*)\s*/y;
 
+const OPERATOR = /\s*(&&|\|\|)\s*/y;
+
 export type Markdown = string | MarkdownQuery;
 
 export type Matcher = string | RegExp | ((text: string) => boolean);
@@ -534,6 +573,8 @@ export interface TextMatcher {
   predicate?: (text: string) => boolean;
 }
 
+export type QueryExpression = QuerySegment[][][];
+
 export interface QuerySegment {
   selector: SelectorType;
   textMatch?: TextMatcher;

package/src/utils/web-sandbox.ts

@@ -1,6 +1,7 @@
 import { faker } from '@faker-js/faker';
 import { hopeThat, retryTo, tryTo, within } from 'codeceptjs/lib/effects';
 import step from 'codeceptjs/steps';
+import { splitTopLevel } from './code-extractor.ts';
 
 const SHADOWED_GLOBALS = ['process', 'global', 'globalThis', 'fetch', 'Bun', 'require', 'module', 'exports'];
 const ALLOWED_COMMAND_HEADS = ['I.', 'page.', 'await page.', 'await I.'];
@@ -9,10 +10,9 @@ const PLAYWRIGHT_ARG_NAMES = ['page'];
 const CODECEPT_ARG_NAMES = ['I', 'tryTo', 'retryTo', 'within', 'hopeThat', 'step', 'faker'];
 
 export function sanitizeCodeBlock(code: string): string {
-  return code
-    .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => ALLOWED_COMMAND_HEADS.some((head) => line.startsWith(head)))
+  return splitTopLevel(code, '\n')
+    .map((statement) => statement.trim())
+    .filter((statement) => ALLOWED_COMMAND_HEADS.some((head) => statement.startsWith(head)))
     .join('\n');
 }