pi-lean-portal 0.1.0

package/core/shared/accessibility-tree.ts

@@ -0,0 +1,408 @@
+/**
+ * Accessibility tree utilities.
+ *
+ * Parses Playwright's page.ariaSnapshot() YAML-like output into an
+ * LLM-friendly text format with @e1, @e2 element references. Caches
+ * parsed nodes so interactions (click, type) can map back via getByRole().
+ */
+
+/** A single parsed node from the aria snapshot, cached for interaction */
+export interface AriaCachedNode {
+	ref: string;
+	role: string;
+	name: string;
+	props: string[];
+	depth: number;
+	raw: string;
+	/** 0-based position among siblings with the same role+name in the snapshot */
+	occurrenceIndex: number;
+	/** Ref of the nearest interactive ancestor (e.g., for subtree queries) */
+	parentRef?: string;
+}
+
+export interface AriaParseResult {
+	/** Text with @e1, @e2 refs added */
+	text: string;
+	/** Map of ref → parsed node for interaction lookup */
+	elements: Map<string, AriaCachedNode>;
+	/** Total interactive elements found */
+	count: number;
+}
+
+/**
+ * Roles that get @e refs and can be used for interaction.
+ */
+export const INTERACTIVE_ROLES = new Set([
+	"button",
+	"link",
+	"textbox",
+	"searchbox",
+	"combobox",
+	"checkbox",
+	"radio",
+	"heading",
+	"listbox",
+	"option",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"tab",
+	"treeitem",
+	"switch",
+	"slider",
+	"spinbutton",
+	"progressbar",
+	"meter",
+	"scrollbar",
+	"gridcell",
+	"cell",
+	"columnheader",
+	"rowheader",
+	"tabpanel",
+	"img",
+	"figure",
+	"listitem",
+	"dialog",
+	"alertdialog",
+	"tooltip",
+	"navigation",
+	"banner",
+	"form",
+	"search",
+	"toolbar",
+	"menu",
+	"menubar",
+	"note",
+	"alert",
+	"status",
+	"list",
+	"table",
+	"grid",
+	"treegrid",
+	"article",
+	"section",
+	"blockquote",
+	"code",
+]);
+
+/**
+ * Roles that are shown in the tree but DON'T get @e refs
+ * (informational only, not useful click targets).
+ */
+export const INFORMATIONAL_ROLES = new Set([
+	"paragraph",
+	"text",
+	"group",
+	"region",
+	"main",
+	"complementary",
+	"contentinfo",
+	"definition",
+	"term",
+	"math",
+	"marquee",
+	"timer",
+	"log",
+	"deletion",
+	"insertion",
+	"mark",
+	"suggestion",
+	"comment",
+]);
+
+/**
+ * Parse the YAML-like output of page.ariaSnapshot().
+ *
+ * Assigns @e refs sequentially to all interactive elements in DOM order.
+ * Every interactive element gets a ref — no cap, no dialog prioritization.
+ */
+export function parseSnapshot(snap: string): AriaParseResult {
+	const elements = new Map<string, AriaCachedNode>();
+	const outLines: string[] = [];
+	let refCounter = 0;
+	const occurrenceTracker = new Map<string, number>();
+	const parentStack: string[] = [];
+
+	const lines = snap.split("\n");
+
+	for (const rawLine of lines) {
+		if (!rawLine.trim()) continue;
+
+		const depth = countLeadingSpaces(rawLine);
+		const trimmed = rawLine.trim();
+
+		// Property lines (start with /) — pass through as-is
+		if (trimmed.startsWith("/")) {
+			outLines.push(rawLine);
+			continue;
+		}
+
+		// Parse "- role ..."
+		const parsed = parseLine(trimmed);
+		if (!parsed) {
+			outLines.push(rawLine);
+			continue;
+		}
+
+		const { role, name, props } = parsed;
+
+		// Informational roles: show in tree but no @e ref
+		if (INFORMATIONAL_ROLES.has(role)) {
+			const indent = "  ".repeat(depth);
+			const icon = roleIcon(role);
+			const namePart = name ? ` "${truncate(name, 80)}"` : "";
+			outLines.push(`${indent}${icon}${role}${namePart}`);
+			continue;
+		}
+
+		// Non-interactive skip
+		if (!INTERACTIVE_ROLES.has(role)) {
+			outLines.push(rawLine);
+			continue;
+		}
+
+		refCounter++;
+		const ref = `e${refCounter}`;
+		const occKey = `${role}||${name}`;
+		const occurrenceIndex = occurrenceTracker.get(occKey) ?? 0;
+		occurrenceTracker.set(occKey, occurrenceIndex + 1);
+
+		// Parent stack: trim entries past current depth
+		while (parentStack.length > depth) {
+			parentStack.pop();
+		}
+
+		// Determine parentRef from the element at depth-1 (if any)
+		const parentRef =
+			parentStack.length >= depth && depth > 0
+				? parentStack[depth - 1]
+				: undefined;
+
+		// Push this ref onto the parent stack at its depth
+		parentStack[depth] = ref;
+
+		const node: AriaCachedNode = {
+			ref,
+			role,
+			name,
+			props,
+			depth,
+			raw: trimmed,
+			occurrenceIndex,
+			...(parentRef ? { parentRef } : {}),
+		};
+		elements.set(ref, node);
+
+		const indent = "  ".repeat(depth);
+		const icon = roleIcon(role);
+		const refTag = `@${ref}`;
+		const namePart = name ? ` "${truncate(name, 80)}"` : "";
+		const propStr = props.length > 0 ? ` [${props.join(", ")}]` : "";
+
+		outLines.push(`${indent}${refTag} ${icon}${role}${namePart}${propStr}`);
+	}
+
+	return {
+		text: outLines.join("\n"),
+		elements,
+		count: elements.size,
+	};
+}
+
+/**
+ * Build a Playwright locator for a cached node using getByRole().
+ */
+export function buildLocator(
+	page: import("playwright").Page,
+	node: AriaCachedNode,
+): import("playwright").Locator | null {
+	try {
+		const opts: Record<string, unknown> = {};
+
+		if (node.name) {
+			opts.name = node.name;
+			opts.exact = node.name.length < 60;
+		}
+
+		for (const prop of node.props) {
+			const eqIdx = prop.indexOf("=");
+			if (eqIdx > 0) {
+				const key = prop.slice(0, eqIdx);
+				const val = prop.slice(eqIdx + 1);
+				if (key === "level") opts.level = parseInt(val, 10);
+				if (key === "checked") opts.checked = val === "mixed" ? "mixed" : true;
+				if (key === "expanded") opts.expanded = val === "true";
+				if (key === "pressed") opts.pressed = val === "mixed" ? "mixed" : true;
+				if (key === "selected") opts.selected = val === "true";
+			} else {
+				if (prop === "checked") opts.checked = true;
+				if (prop === "expanded") opts.expanded = true;
+				if (prop === "pressed") opts.pressed = true;
+				if (prop === "selected") opts.selected = true;
+				if (prop === "disabled") opts.disabled = true;
+			}
+		}
+
+		const locator = page.getByRole(node.role as any, opts);
+		// Always use .nth(occurrenceIndex) to avoid strict-mode violations
+		// when multiple elements share the same role+name.  For unique elements
+		// (occurrenceIndex = 0) this is equivalent to the bare locator.
+		return locator.nth(node.occurrenceIndex);
+	} catch {
+		if (node.name) {
+			return page.getByText(node.name, { exact: node.name.length < 60 });
+		}
+		return null;
+	}
+}
+
+// ─── Parsing ──────────────────────────────────────────────────────────
+
+interface ParsedLine {
+	role: string;
+	name: string;
+	props: string[];
+}
+
+function parseLine(line: string): ParsedLine | null {
+	if (!line.startsWith("- ")) return null;
+	const content = line.slice(2).trim();
+
+	const props: string[] = [];
+	const cleaned = content
+		.replace(/\[([^\]]+)\]/g, (_m, capture) => {
+			props.push(capture.trim());
+			return "";
+		})
+		.trim();
+
+	const match = cleaned.match(/^([a-zA-Z_-]+)\s*/);
+	if (!match) return null;
+
+	const role = (match[1] ?? "").toLowerCase();
+	const remainder = cleaned.slice(match[0].length).trim();
+	let name = "";
+
+	// Quoted name: "name" or "name":
+	const nameMatch = remainder.match(/^"((?:[^"\\]|\\.)*)"\s*:?\s*/);
+	if (nameMatch) {
+		name = nameMatch[1] ?? "";
+	} else {
+		// Colon-text format: ": text content"
+		const textMatch = remainder.match(/^:\s*(.*)/);
+		if (textMatch) {
+			name = (textMatch[1] ?? "").trim().slice(0, 100);
+		}
+	}
+
+	return { role, name, props };
+}
+
+function countLeadingSpaces(s: string): number {
+	const match = s.match(/^(\s*)/);
+	return match ? (match[1] ?? "").length : 0;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+export function roleIcon(role: string): string {
+	const icons: Record<string, string> = {
+		alert: "🔔 ",
+		alertdialog: "⚠ ",
+		article: "📰 ",
+		banner: "📰 ",
+		blockquote: "💬 ",
+		button: "🔘 ",
+		cell: "▫ ",
+		checkbox: "☑ ",
+		code: "💻 ",
+		columnheader: "📊 ",
+		combobox: "📋 ",
+		comment: "💬 ",
+		complementary: "📎 ",
+		contentinfo: "ℹ ",
+		definition: "📖 ",
+		deletion: "❌ ",
+		dialog: "💬 ",
+		figure: "🖼 ",
+		form: "📝 ",
+		grid: "📊 ",
+		gridcell: "▫ ",
+		group: "📦 ",
+		heading: "📌 ",
+		img: "🖼 ",
+		insertion: "➕ ",
+		link: "🔗 ",
+		list: "📋 ",
+		listbox: "📋 ",
+		listitem: "• ",
+		log: "📋 ",
+		main: "📄 ",
+		mark: "🖍️ ",
+		marquee: "📜 ",
+		math: "🧮 ",
+		menu: "📋 ",
+		menubar: "📋 ",
+		menuitem: "📋 ",
+		menuitemcheckbox: "☑ ",
+		menuitemradio: "○ ",
+		meter: "📊 ",
+		navigation: "🧭 ",
+		note: "📝 ",
+		option: "• ",
+		paragraph: "📃 ",
+		progressbar: "⏳ ",
+		radio: "○ ",
+		region: "📦 ",
+		rowheader: "📊 ",
+		search: "🔍 ",
+		searchbox: "🔍 ",
+		scrollbar: "📜 ",
+		section: "📄 ",
+		slider: "🔧 ",
+		spinbutton: "🔢 ",
+		status: "📊 ",
+		suggestion: "💡 ",
+		switch: "🔀 ",
+		tab: "📑 ",
+		table: "📊 ",
+		tabpanel: "📑 ",
+		term: "📖 ",
+		text: "📝 ",
+		textbox: "📝 ",
+		timer: "⏱️ ",
+		toolbar: "🔧 ",
+		tooltip: "💡 ",
+		treegrid: "📊 ",
+		treeitem: "• ",
+	};
+	return icons[role] || "";
+}
+
+function truncate(s: string, max: number): string {
+	if (s.length <= max) return s;
+	return s.slice(0, max - 1) + "…";
+}
+
+/**
+ * Compute a stable, lightweight fingerprint of an accessibility snapshot.
+ *
+ * Uses the first 200 characters of the snapshot to produce a short hash.
+ * Same snapshot → same fingerprint. Different content → different fingerprint.
+ * The fingerprint captures enough structural information to detect significant
+ * DOM changes (SPA navigation, dynamic content loading) while being cheap to
+ * compute (O(200) with no allocations).
+ *
+ * The hash is a DJB2 digest of the first 200 chars, returned as a base-36
+ * string for compactness.
+ */
+export function snapshotFingerprint(snapshot: string): string {
+	const sample = snapshot.slice(0, 200);
+	let hash = 5381;
+	for (let i = 0; i < sample.length; i++) {
+		hash = (hash << 5) + hash + sample.charCodeAt(i);
+		hash = hash & hash;
+	}
+	// Use unsigned 32-bit to avoid negative toString(36) output
+	return (hash >>> 0).toString(36);
+}

package/core/shared/bot-detection.ts

@@ -0,0 +1,187 @@
+/**
+ * Bot detection heuristics.
+ *
+ * Analyzes page content to determine if a site is blocking
+ * automation tools (Cloudflare, CAPTCHA, etc.). When detected,
+ * the router flags the navigation as bot-blocked so the agent
+ * can decide how to proceed — try web-fetch, try a different URL,
+ * or switch to a stealth browser backend if one is configured.
+ */
+
+export interface BotDetectionResult {
+	/** True if the page appears to be a bot block/challenge page */
+	isBlocked: boolean;
+	/** Confidence score 0-1 */
+	confidence: number;
+	/** Signal that triggered the detection */
+	signal?: string;
+}
+
+/**
+ * Content patterns that indicate a bot block.
+ *
+ * Only specific challenge phrases are included — generic single words
+ * like "cloudflare", "captcha", "recaptcha", "hcaptcha", "enable javascript"
+ * etc. are excluded because they cause false positives on legitimate
+ * pages (Cloudflare's own site, web scraping articles, CAPTCHA service pages).
+ * Real challenge pages always use these exact phrases.
+ */
+const BLOCK_SIGNALS = [
+	"please verify you are human",
+	"attention required!",
+	"just a moment...",
+	"checking your browser",
+	"you have been blocked",
+	"sorry, you have been blocked",
+	"verify you are human",
+	"your request has been blocked",
+	"we are checking your browser",
+	"cf-challenge",
+	"_cf_chl_opt",
+	"cdn-cgi/challenge",
+];
+
+/**
+ * Body-only string patterns — checked in body text (not the title) to
+ * avoid false matches on legitimate content.  Catches CDN-specific
+ * block pages (Akamai "Access Denied", generic 403s).
+ */
+const BODY_ONLY_SIGNALS = [
+	"errors.edgesuite.net",
+	"you don't have permission to access",
+];
+
+/**
+ * Body-only regex patterns — more specific than string inclusion.
+ * These match the exact format of CDN error reference codes to
+ * avoid false positives from generic "reference #123" in normal content.
+ */
+const BODY_ONLY_PATTERNS: RegExp[] = [
+	/reference\s*#[a-f0-9]+(?:\.[a-f0-9]+)+/i,
+];
+
+/**
+ * HTML-level signals — checked against ``document.documentElement.innerHTML``
+ * rather than visible body text.  These look for CAPTCHA widget embed codes
+ * in the raw HTML source, which is a stronger signal than visible text
+ * (generic mentions of "captcha" in body copy are excluded to avoid false
+ * positives, but embed codes in HTML attributes are unambiguous).
+ */
+const HTML_SIGNALS = [
+	"recaptcha",
+	"hcaptcha",
+	"turnstile",
+	"g-recaptcha",
+	"data-sitekey",
+];
+
+/**
+ * Check if page text content suggests a bot block.
+ */
+export function checkBodyText(bodyText: string): BotDetectionResult {
+	if (!bodyText) return { isBlocked: false, confidence: 0 };
+
+	const lower = bodyText.toLowerCase();
+	for (const signal of BLOCK_SIGNALS) {
+		if (lower.includes(signal)) {
+			return {
+				isBlocked: true,
+				confidence: signal.length > 20 ? 0.9 : 0.7,
+				signal,
+			};
+		}
+	}
+
+	return { isBlocked: false, confidence: 0 };
+}
+
+/**
+ * Check body text against body-only signal patterns that are specific
+ * enough to not false-positive on normal content.  Checks both string
+ * inclusion (for CDN domains, generic 403 messages) and regex patterns
+ * (for Akamai reference codes, etc.).
+ */
+function checkBodyOnlyText(bodyText: string): BotDetectionResult {
+	if (!bodyText) return { isBlocked: false, confidence: 0 };
+
+	const lower = bodyText.toLowerCase();
+
+	// Check string signals first
+	for (const signal of BODY_ONLY_SIGNALS) {
+		if (lower.includes(signal)) {
+			return { isBlocked: true, confidence: 0.85, signal };
+		}
+	}
+
+	// Check regex patterns against raw text (case-insensitive via /i flag)
+	for (const pattern of BODY_ONLY_PATTERNS) {
+		const match = bodyText.match(pattern);
+		if (match) {
+			return {
+				isBlocked: true,
+				confidence: 0.9,
+				signal: `regex: ${match[0].slice(0, 50)}`,
+			};
+		}
+	}
+
+	return { isBlocked: false, confidence: 0 };
+}
+
+/**
+ * Check raw HTML content for CAPTCHA widget embed codes.
+ *
+ * Looks for specific widget identifiers in the HTML source (not visible text),
+ * so false positive risk from generic mentions is low.  Mirrors the Python
+ * bridge's ``_HTML_SIGNALS`` in ``backends/chromium-py/bridge.py``.
+ */
+export function checkHtmlContent(html: string): BotDetectionResult {
+	if (!html) return { isBlocked: false, confidence: 0 };
+
+	const lower = html.toLowerCase();
+	for (const signal of HTML_SIGNALS) {
+		if (lower.includes(signal)) {
+			return {
+				isBlocked: true,
+				confidence: 0.85,
+				signal: `html:${signal}`,
+			};
+		}
+	}
+
+	return { isBlocked: false, confidence: 0 };
+}
+
+/**
+ * Combined check: analyze page title, body text, and (optionally) raw HTML.
+ *
+ * - Title is checked against BLOCK_SIGNALS only (avoids false positives).
+ * - Body is checked against BLOCK_SIGNALS + BODY_ONLY_SIGNALS + BODY_ONLY_PATTERNS
+ *   (catches CDN-specific block pages like Akamai "Access Denied").
+ * - HTML (if provided) is checked for CAPTCHA widget embed codes.
+ */
+export function checkPage(
+	title: string,
+	bodyText: string,
+	html?: string,
+): BotDetectionResult {
+	// Check title first (often contains "Attention Required!" etc.)
+	const titleResult = checkBodyText(title);
+	if (titleResult.isBlocked) return titleResult;
+
+	// Check body against challenge phrases
+	const bodyResult = checkBodyText(bodyText);
+	if (bodyResult.isBlocked) return bodyResult;
+
+	// Check body against CDN-specific patterns (reference #, etc.)
+	const bodyOnlyResult = checkBodyOnlyText(bodyText);
+	if (bodyOnlyResult.isBlocked) return bodyOnlyResult;
+
+	// Check HTML source for CAPTCHA widget embed codes
+	if (html !== undefined) {
+		const htmlResult = checkHtmlContent(html);
+		if (htmlResult.isBlocked) return htmlResult;
+	}
+
+	return { isBlocked: false, confidence: 0 };
+}

package/core/shared/browser-events.ts

@@ -0,0 +1,111 @@
+/**
+ * Browser Event Supervisor — handles JavaScript dialogs and browser events.
+ *
+ * Automatically dismisses alert/confirm/prompt dialogs and logs them
+ * for the user to see. Also handles page crash and unresponsive events.
+ *
+ * Playwright-generic — lives in core/shared so all Playwright-based
+ * backends (chromium, firefox, etc.) share the same handler logic.
+ */
+
+import type { Page } from "playwright";
+
+export interface DialogEvent {
+	type: "alert" | "confirm" | "prompt" | "beforeunload";
+	message: string;
+	/** Default value for prompt dialogs */
+	defaultValue?: string;
+	/** How the dialog was handled */
+	handledAs: "accepted" | "dismissed";
+	timestamp: number;
+}
+
+export interface ConsoleEvent {
+	type:
+		| "log"
+		| "warn"
+		| "error"
+		| "info"
+		| "debug"
+		| "dir"
+		| "trace"
+		| "assert";
+	text: string;
+	timestamp: number;
+}
+
+/** Dialogs logged per task, for reporting to user */
+const _dialogLog = new Map<string, DialogEvent[]>();
+
+/** Console messages logged per task */
+const _consoleLog = new Map<string, ConsoleEvent[]>();
+
+/** Get logged dialogs for a task */
+export function getDialogLog(taskId: string): DialogEvent[] {
+	return _dialogLog.get(taskId) ?? [];
+}
+
+/** Get console messages for a task */
+export function getConsoleLog(taskId: string): ConsoleEvent[] {
+	return _consoleLog.get(taskId) ?? [];
+}
+
+/** Clear console log for a task */
+export function clearConsoleLog(taskId: string): void {
+	_consoleLog.delete(taskId);
+}
+
+/**
+ * Install dialog and console handlers on a Playwright page.
+ * Automatically accepts all dialogs (alert, confirm, prompt) and logs them.
+ * Captures console messages (log, warn, error, info, debug) for retrieval.
+ */
+export function installDialogHandlers(taskId: string, page: Page): void {
+	const dialogLog: DialogEvent[] = [];
+	_dialogLog.set(taskId, dialogLog);
+
+	const consoleLog: ConsoleEvent[] = [];
+	_consoleLog.set(taskId, consoleLog);
+
+	// Auto-accept JavaScript dialogs
+	page.on("dialog", async (dialog) => {
+		const entry: DialogEvent = {
+			type: dialog.type() as DialogEvent["type"],
+			message: dialog.message(),
+			defaultValue: dialog.defaultValue(),
+			handledAs: "accepted",
+			timestamp: Date.now(),
+		};
+
+		try {
+			await dialog.accept();
+		} catch {
+			entry.handledAs = "dismissed";
+		}
+
+		dialogLog.push(entry);
+	});
+
+	// Capture console messages
+	page.on("console", (msg) => {
+		const type = msg.type() as ConsoleEvent["type"];
+		if (consoleLog.length >= 500) {
+			consoleLog.shift(); // Ring buffer: keep latest 500
+		}
+		consoleLog.push({
+			type,
+			text: msg.text(),
+			timestamp: Date.now(),
+		});
+	});
+
+	// Handle page crashes
+	page.on("crash", () => {
+		dialogLog.push({
+			type: "alert",
+			message: "⚠ Page crashed",
+			handledAs: "dismissed",
+			timestamp: Date.now(),
+		});
+	});
+}