gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/browser-tools/core.ts

@@ -1,1196 +0,0 @@
-/**
- * Runtime-neutral helper logic for browser-tools.
- *
- * Kept free of pi-specific imports so it can be exercised with node:test.
- */
-
-// ---------------------------------------------------------------------------
-// Interfaces & Types
-// ---------------------------------------------------------------------------
-
-export interface ActionTimeline {
-	limit: number;
-	nextId: number;
-	entries: ActionEntry[];
-}
-
-export interface ActionEntry {
-	id: number;
-	tool: string;
-	paramsSummary: string;
-	startedAt: number;
-	finishedAt: number | null;
-	status: string;
-	beforeUrl: string;
-	afterUrl: string;
-	verificationSummary?: string;
-	warningSummary?: string;
-	diffSummary?: string;
-	changed?: boolean;
-	error?: string;
-}
-
-export interface ActionPartial {
-	tool: string;
-	paramsSummary?: string;
-	startedAt?: number;
-	beforeUrl?: string;
-	afterUrl?: string;
-	verificationSummary?: string;
-	warningSummary?: string;
-	diffSummary?: string;
-	changed?: boolean;
-	error?: string;
-}
-
-export interface ActionUpdates {
-	finishedAt?: number;
-	status?: string;
-	afterUrl?: string;
-	verificationSummary?: string;
-	warningSummary?: string;
-	diffSummary?: string;
-	changed?: boolean;
-	error?: string;
-}
-
-export interface DiffResult {
-	changed: boolean;
-	changes: Array<{ type: string; before: unknown; after: unknown }>;
-	summary: string;
-}
-
-export interface Threshold {
-	op: string;
-	n: number;
-}
-
-export interface PageRegistry {
-	pages: PageEntry[];
-	activePageId: number | null;
-	nextId: number;
-}
-
-export interface PageEntry {
-	id: number;
-	page: any;
-	title: string;
-	url: string;
-	opener: number | null;
-}
-
-export interface PageListEntry {
-	id: number;
-	title: string;
-	url: string;
-	opener: number | null;
-	isActive: boolean;
-}
-
-export interface SnapshotModeConfig {
-	tags: string[];
-	roles: string[];
-	selectors: string[];
-	ariaAttributes: string[];
-	useInteractiveFilter: boolean;
-	visibleOnly?: boolean;
-	containerExpand?: boolean;
-}
-
-export interface AssertionCheckResult {
-	name: string;
-	passed: boolean;
-	actual: unknown;
-	expected: unknown;
-	selector?: string;
-	text?: string;
-}
-
-export interface AssertionEvaluation {
-	verified: boolean;
-	checks: AssertionCheckResult[];
-	summary: string;
-	agentHint: string;
-}
-
-export interface WaitValidationError {
-	error: string;
-}
-
-export interface BatchStepResult {
-	ok: boolean;
-	stopReason: string | null;
-	failedStepIndex: number | null;
-	stepResults: unknown[];
-	summary: string;
-}
-
-export interface FormattedTimeline {
-	entries: Array<{
-		id: number | null;
-		tool: string;
-		status: string;
-		durationMs: number | null;
-		beforeUrl: string;
-		afterUrl: string;
-		line: string;
-	}>;
-	retained: number;
-	totalRecorded: number;
-	bounded: boolean;
-	summary: string;
-}
-
-export interface FailureHypothesis {
-	hasFailures: boolean;
-	categories: string[];
-	summary: string;
-	signals: Array<{ category: string; source: string; detail: string }>;
-}
-
-export interface SessionSummary {
-	counts: {
-		pages: number;
-		actions: { total: number; retained: number; success: number; error: number; running: number };
-		waits: { total: number; success: number; error: number; running: number };
-		assertions: { total: number; passed: number; failed: number; running: number };
-		consoleErrors: number;
-		failedRequests: number;
-		dialogs: number;
-	};
-	activePage: { id: number | null; title: string; url: string } | null;
-	caveats: string[];
-	failureHypothesis: FailureHypothesis;
-	summary: string;
-}
-
-// ---------------------------------------------------------------------------
-// Action Timeline
-// ---------------------------------------------------------------------------
-
-export function createActionTimeline(limit = 60): ActionTimeline {
-  return {
-    limit,
-    nextId: 1,
-    entries: [],
-  };
-}
-
-export function beginAction(timeline: ActionTimeline, partial: ActionPartial): ActionEntry {
-  const entry: ActionEntry = {
-    id: timeline.nextId++,
-    tool: partial.tool,
-    paramsSummary: partial.paramsSummary ?? "",
-    startedAt: partial.startedAt ?? Date.now(),
-    finishedAt: null,
-    status: "running",
-    beforeUrl: partial.beforeUrl ?? "",
-    afterUrl: partial.afterUrl ?? "",
-    verificationSummary: partial.verificationSummary,
-    warningSummary: partial.warningSummary,
-    diffSummary: partial.diffSummary,
-    changed: partial.changed,
-    error: partial.error,
-  };
-  timeline.entries.push(entry);
-  if (timeline.entries.length > timeline.limit) {
-    timeline.entries.splice(0, timeline.entries.length - timeline.limit);
-  }
-  return entry;
-}
-
-export function finishAction(timeline: ActionTimeline, actionId: number, updates: ActionUpdates = {}): ActionEntry | null {
-  const entry = timeline.entries.find((item) => item.id === actionId);
-  if (!entry) return null;
-  Object.assign(entry, updates, {
-    finishedAt: updates.finishedAt ?? Date.now(),
-    status: updates.status ?? entry.status ?? "success",
-    afterUrl: updates.afterUrl ?? entry.afterUrl ?? "",
-    verificationSummary: updates.verificationSummary ?? entry.verificationSummary,
-    warningSummary: updates.warningSummary ?? entry.warningSummary,
-    diffSummary: updates.diffSummary ?? entry.diffSummary,
-    changed: updates.changed ?? entry.changed,
-    error: updates.error ?? entry.error,
-  });
-  return entry;
-}
-
-export function findAction(timeline: ActionTimeline, actionId: number): ActionEntry | null {
-  return timeline.entries.find((item) => item.id === actionId) ?? null;
-}
-
-export function toActionParamsSummary(params: unknown): string {
-  if (!params || typeof params !== "object") return "";
-  const entries: string[] = [];
-  for (const [key, value] of Object.entries(params as Record<string, unknown>)) {
-    if (value === undefined || value === null) continue;
-    if (typeof value === "string") {
-      entries.push(`${key}=${JSON.stringify(value.length > 60 ? `${value.slice(0, 57)}...` : value)}`);
-      continue;
-    }
-    if (Array.isArray(value)) {
-      entries.push(`${key}=[${value.length}]`);
-      continue;
-    }
-    if (typeof value === "object") {
-      entries.push(`${key}={...}`);
-      continue;
-    }
-    entries.push(`${key}=${String(value)}`);
-  }
-  return entries.slice(0, 6).join(", ");
-}
-
-// ---------------------------------------------------------------------------
-// Compact State Diffing
-// ---------------------------------------------------------------------------
-
-interface CompactStateForDiff {
-  url?: string;
-  title?: string;
-  focus?: string;
-  dialog?: { count?: number; title?: string };
-  counts?: Record<string, number>;
-  headings?: string[];
-  bodyText?: string;
-}
-
-export function diffCompactStates(before: CompactStateForDiff | null | undefined, after: CompactStateForDiff | null | undefined): DiffResult {
-  const changes: Array<{ type: string; before: unknown; after: unknown }> = [];
-  if (!before || !after) {
-    return {
-      changed: false,
-      changes: [],
-      summary: "Diff unavailable",
-    };
-  }
-
-  if (before.url !== after.url) {
-    changes.push({ type: "url", before: before.url, after: after.url });
-  }
-  if (before.title !== after.title) {
-    changes.push({ type: "title", before: before.title, after: after.title });
-  }
-  if (before.focus !== after.focus) {
-    changes.push({ type: "focus", before: before.focus, after: after.focus });
-  }
-  if ((before.dialog?.count ?? 0) !== (after.dialog?.count ?? 0)) {
-    changes.push({
-      type: "dialog_count",
-      before: before.dialog?.count ?? 0,
-      after: after.dialog?.count ?? 0,
-    });
-  }
-  if ((before.dialog?.title ?? "") !== (after.dialog?.title ?? "")) {
-    changes.push({
-      type: "dialog_title",
-      before: before.dialog?.title ?? "",
-      after: after.dialog?.title ?? "",
-    });
-  }
-
-  for (const key of ["landmarks", "buttons", "links", "inputs"]) {
-    const beforeValue = before.counts?.[key] ?? 0;
-    const afterValue = after.counts?.[key] ?? 0;
-    if (beforeValue !== afterValue) {
-      changes.push({ type: `count:${key}`, before: beforeValue, after: afterValue });
-    }
-  }
-
-  const beforeHeadings = JSON.stringify(before.headings ?? []);
-  const afterHeadings = JSON.stringify(after.headings ?? []);
-  if (beforeHeadings !== afterHeadings) {
-    changes.push({
-      type: "headings",
-      before: before.headings ?? [],
-      after: after.headings ?? [],
-    });
-  }
-
-  const beforeBody = before.bodyText ?? "";
-  const afterBody = after.bodyText ?? "";
-  if (beforeBody !== afterBody) {
-    changes.push({
-      type: "body_text",
-      before: beforeBody.slice(0, 120),
-      after: afterBody.slice(0, 120),
-    });
-  }
-
-  const changed = changes.length > 0;
-  const summary = changed
-    ? changes
-        .slice(0, 4)
-        .map((change) => {
-          if (change.type === "url") return `URL changed to ${change.after}`;
-          if (change.type === "title") return `title changed to ${change.after}`;
-          if (change.type === "focus") return `focus changed`;
-          if (change.type === "dialog_count") return `dialog count ${change.before}→${change.after}`;
-          if (change.type.startsWith("count:")) return `${change.type.slice(6)} ${change.before}→${change.after}`;
-          if (change.type === "headings") return "headings changed";
-          if (change.type === "body_text") return "visible text changed";
-          return `${change.type} changed`;
-        })
-        .join("; ")
-    : "No meaningful browser-state change detected";
-
-  return { changed, changes, summary };
-}
-
-// ---------------------------------------------------------------------------
-// String helpers
-// ---------------------------------------------------------------------------
-
-function normalizeString(value: unknown): string {
-  return String(value ?? "").trim();
-}
-
-export function includesNeedle(haystack: string, needle: string): boolean {
-  return normalizeString(haystack).toLowerCase().includes(normalizeString(needle).toLowerCase());
-}
-
-// ---------------------------------------------------------------------------
-// Threshold parsing for count-based assertions
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a threshold expression like ">=3", "==0", "<5", or bare "3" (defaults to ">=").
- */
-export function parseThreshold(value: string | null | undefined): Threshold | null {
-  if (value == null) return null;
-  const str = String(value).trim();
-  if (str === "") return null;
-  const match = str.match(/^(>=|<=|==|>|<)?\s*(\d+)$/);
-  if (!match) return null;
-  const op = match[1] || ">=";
-  const n = parseInt(match[2], 10);
-  return { op, n };
-}
-
-/**
- * Evaluate whether a count meets a parsed threshold.
- */
-export function meetsThreshold(count: number, threshold: Threshold): boolean {
-  switch (threshold.op) {
-    case ">=": return count >= threshold.n;
-    case "<=": return count <= threshold.n;
-    case "==": return count === threshold.n;
-    case ">":  return count > threshold.n;
-    case "<":  return count < threshold.n;
-    default:   return false;
-  }
-}
-
-/**
- * Filter entries that occurred at or after a given action's start time.
- * If sinceActionId is missing or the action isn't found, returns all entries.
- */
-export function getEntriesSince(
-  entries: Array<{ timestamp?: number }>,
-  sinceActionId: number | undefined,
-  timeline: ActionTimeline,
-): Array<{ timestamp?: number }> {
-  if (!entries || !Array.isArray(entries)) return [];
-  if (sinceActionId == null || !timeline) return entries;
-  const action = findAction(timeline, sinceActionId);
-  if (!action) return entries;
-  const since = action.startedAt;
-  return entries.filter((e) => (e.timestamp ?? 0) >= since);
-}
-
-// ---------------------------------------------------------------------------
-// Assertion Evaluation
-// ---------------------------------------------------------------------------
-
-interface AssertionCheckInput {
-  kind: string;
-  selector?: string;
-  value?: string;
-  text?: string;
-  checked?: boolean;
-  sinceActionId?: number;
-}
-
-interface AssertionState {
-  url?: string;
-  title?: string;
-  bodyText?: string;
-  focus?: string;
-  selectorStates?: Record<string, { visible?: boolean; value?: string; checked?: boolean | null }>;
-  consoleEntries?: Array<{ type?: string; text?: string; message?: string; timestamp?: number }>;
-  networkEntries?: Array<{ type?: string; url?: string; status?: number; failed?: boolean; timestamp?: number }>;
-  allConsoleEntries?: Array<{ type?: string; text?: string; message?: string; timestamp?: number }>;
-  allNetworkEntries?: Array<{ type?: string; url?: string; status?: number; failed?: boolean; timestamp?: number }>;
-  actionTimeline?: ActionTimeline | null;
-}
-
-export function evaluateAssertionChecks({ checks, state }: { checks: AssertionCheckInput[]; state: AssertionState }): AssertionEvaluation {
-  const results: AssertionCheckResult[] = [];
-  const selectorStates = state.selectorStates ?? {};
-  const consoleEntries = state.consoleEntries ?? [];
-  const networkEntries = state.networkEntries ?? [];
-  const allConsoleEntries = state.allConsoleEntries ?? state.consoleEntries ?? [];
-  const allNetworkEntries = state.allNetworkEntries ?? state.networkEntries ?? [];
-  const actionTimeline = state.actionTimeline ?? null;
-
-  for (const check of checks) {
-    const selectorState = check.selector ? selectorStates[check.selector] ?? null : null;
-    let passed = false;
-    let actual: unknown;
-    let expected: unknown;
-
-    switch (check.kind) {
-      case "url_contains":
-        actual = state.url ?? "";
-        expected = check.value ?? "";
-        passed = includesNeedle(actual as string, expected as string);
-        break;
-      case "title_contains":
-        actual = state.title ?? "";
-        expected = check.value ?? "";
-        passed = includesNeedle(actual as string, expected as string);
-        break;
-      case "text_visible":
-        actual = state.bodyText ?? "";
-        expected = check.text ?? "";
-        passed = includesNeedle(actual as string, expected as string);
-        break;
-      case "text_not_visible":
-        actual = state.bodyText ?? "";
-        expected = check.text ?? "";
-        passed = !includesNeedle(actual as string, expected as string);
-        break;
-      case "selector_visible":
-        actual = selectorState?.visible ?? false;
-        expected = true;
-        passed = actual === true;
-        break;
-      case "selector_hidden":
-        actual = selectorState?.visible ?? false;
-        expected = false;
-        passed = actual === false;
-        break;
-      case "value_equals":
-        actual = selectorState?.value ?? "";
-        expected = check.value ?? "";
-        passed = actual === expected;
-        break;
-      case "value_contains":
-        actual = selectorState?.value ?? "";
-        expected = check.value ?? "";
-        passed = includesNeedle(actual as string, expected as string);
-        break;
-      case "focused_matches":
-        actual = state.focus ?? "";
-        expected = check.value ?? "";
-        passed = includesNeedle(actual as string, expected as string);
-        break;
-      case "checked_equals":
-        actual = selectorState?.checked ?? null;
-        expected = !!check.checked;
-        passed = actual === expected;
-        break;
-      case "no_console_errors":
-        actual = consoleEntries.filter((entry) => entry.type === "error" || entry.type === "pageerror").length;
-        expected = 0;
-        passed = actual === 0;
-        break;
-      case "no_failed_requests":
-        actual = networkEntries.filter((entry) => entry.failed || (typeof entry.status === "number" && entry.status >= 400)).length;
-        expected = 0;
-        passed = actual === 0;
-        break;
-
-      // --- S02: New structured network/console assertion kinds ---
-
-      case "request_url_seen": {
-        const filtered = getEntriesSince(allNetworkEntries, check.sinceActionId, actionTimeline!);
-        const matches = (filtered as typeof allNetworkEntries).filter((e) => includesNeedle(e.url ?? "", check.text ?? ""));
-        actual = matches.length > 0;
-        expected = true;
-        passed = actual === true;
-        break;
-      }
-
-      case "response_status": {
-        const filtered = getEntriesSince(allNetworkEntries, check.sinceActionId, actionTimeline!);
-        const statusNum = parseInt(check.value!, 10);
-        const matches = (filtered as typeof allNetworkEntries).filter(
-          (e) => includesNeedle(e.url ?? "", check.text ?? "") && typeof e.status === "number" && e.status === statusNum
-        );
-        actual = matches.length > 0 ? `found (status=${matches[0].status})` : `not found`;
-        expected = `status=${check.value ?? ""}`;
-        passed = matches.length > 0;
-        break;
-      }
-
-      case "console_message_matches": {
-        const filtered = getEntriesSince(allConsoleEntries, check.sinceActionId, actionTimeline!);
-        const matches = (filtered as typeof allConsoleEntries).filter((e) => includesNeedle(e.text ?? "", check.text ?? ""));
-        actual = matches.length > 0;
-        expected = true;
-        passed = actual === true;
-        break;
-      }
-
-      case "network_count": {
-        const filtered = getEntriesSince(allNetworkEntries, check.sinceActionId, actionTimeline!);
-        const matches = (filtered as typeof allNetworkEntries).filter((e) => includesNeedle(e.url ?? "", check.text ?? ""));
-        const threshold = parseThreshold(check.value);
-        if (!threshold) {
-          actual = `invalid threshold: ${check.value}`;
-          expected = check.value ?? "";
-          passed = false;
-        } else {
-          actual = `count=${matches.length}`;
-          expected = `${threshold.op}${threshold.n}`;
-          passed = meetsThreshold(matches.length, threshold);
-        }
-        break;
-      }
-
-      case "console_count": {
-        const filtered = getEntriesSince(allConsoleEntries, check.sinceActionId, actionTimeline!);
-        const matches = (filtered as typeof allConsoleEntries).filter((e) => includesNeedle(e.text ?? "", check.text ?? ""));
-        const threshold = parseThreshold(check.value);
-        if (!threshold) {
-          actual = `invalid threshold: ${check.value}`;
-          expected = check.value ?? "";
-          passed = false;
-        } else {
-          actual = `count=${matches.length}`;
-          expected = `${threshold.op}${threshold.n}`;
-          passed = meetsThreshold(matches.length, threshold);
-        }
-        break;
-      }
-
-      case "no_console_errors_since": {
-        const filtered = getEntriesSince(allConsoleEntries, check.sinceActionId, actionTimeline!);
-        const errors = (filtered as typeof allConsoleEntries).filter((e) => e.type === "error" || e.type === "pageerror");
-        actual = errors.length;
-        expected = 0;
-        passed = errors.length === 0;
-        break;
-      }
-
-      case "no_failed_requests_since": {
-        const filtered = getEntriesSince(allNetworkEntries, check.sinceActionId, actionTimeline!);
-        const failures = (filtered as typeof allNetworkEntries).filter((e) => e.failed || (typeof e.status === "number" && e.status >= 400));
-        actual = failures.length;
-        expected = 0;
-        passed = failures.length === 0;
-        break;
-      }
-
-      default:
-        actual = "unsupported";
-        expected = check.kind;
-        passed = false;
-        break;
-    }
-
-    results.push({
-      name: check.kind,
-      passed,
-      actual,
-      expected,
-      selector: check.selector,
-      text: check.text,
-    });
-  }
-
-  const failed = results.filter((result) => !result.passed);
-  const verified = failed.length === 0;
-  return {
-    verified,
-    checks: results,
-    summary: verified
-      ? `PASS (${results.length}/${results.length} checks)`
-      : `FAIL (${failed.length}/${results.length} checks failed)`,
-    agentHint: verified
-      ? "All assertion checks passed"
-      : failed[0]
-        ? `Investigate ${failed[0].name} (expected ${JSON.stringify(failed[0].expected)}, got ${JSON.stringify(failed[0].actual)})`
-        : "Assertion failed",
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Wait-condition validation
-// ---------------------------------------------------------------------------
-
-interface WaitConditionSpec {
-  needsValue: boolean;
-  valueLabel: string;
-  needsThreshold?: boolean;
-}
-
-/**
- * All recognized wait conditions with their parameter requirements.
- */
-const WAIT_CONDITIONS: Record<string, WaitConditionSpec> = {
-  // Existing 5 conditions
-  selector_visible:   { needsValue: true,  valueLabel: "CSS selector" },
-  selector_hidden:    { needsValue: true,  valueLabel: "CSS selector" },
-  url_contains:       { needsValue: true,  valueLabel: "URL substring" },
-  network_idle:       { needsValue: false, valueLabel: "" },
-  delay:              { needsValue: true,  valueLabel: "milliseconds as a string (e.g. '1000')" },
-
-  // New 6 conditions (S03)
-  text_visible:       { needsValue: true,  valueLabel: "text to search for" },
-  text_hidden:        { needsValue: true,  valueLabel: "text to search for" },
-  request_completed:  { needsValue: true,  valueLabel: "URL substring to match" },
-  console_message:    { needsValue: true,  valueLabel: "message substring to match" },
-  element_count:      { needsValue: true,  valueLabel: "CSS selector", needsThreshold: true },
-  region_stable:      { needsValue: true,  valueLabel: "CSS selector" },
-};
-
-/**
- * Validate parameters for a browser_wait_for condition.
- */
-export function validateWaitParams(params: { condition: string; value?: string; threshold?: string }): WaitValidationError | null {
-  const { condition, value, threshold } = params ?? {};
-
-  if (!condition) {
-    return { error: "condition is required" };
-  }
-
-  const spec = WAIT_CONDITIONS[condition];
-  if (!spec) {
-    const known = Object.keys(WAIT_CONDITIONS).join(", ");
-    return { error: `unknown condition "${condition}". Known conditions: ${known}` };
-  }
-
-  if (spec.needsValue && (!value || String(value).trim() === "")) {
-    return { error: `${condition} requires a value (${spec.valueLabel})` };
-  }
-
-  if (spec.needsThreshold && threshold != null && String(threshold).trim() !== "") {
-    const parsed = parseThreshold(threshold);
-    if (!parsed) {
-      return { error: `${condition} threshold is malformed: "${threshold}". Expected format: >=N, <=N, ==N, >N, <N, or bare N` };
-    }
-  }
-
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Region-stable script generator
-// ---------------------------------------------------------------------------
-
-/**
- * Generate a JS expression string for page.waitForFunction() that detects
- * DOM stability by comparing snapshot hashes across polling intervals.
- */
-export function createRegionStableScript(selector: string): string {
-  // Create a stable key from the selector (simple hash to avoid special chars)
-  const safeKey = Array.from(selector).reduce((h, c) => ((h << 5) - h + c.charCodeAt(0)) | 0, 0) >>> 0;
-  const windowKey = `__pw_region_stable_${safeKey}`;
-
-  return `(() => {
-  const el = document.querySelector(${JSON.stringify(selector)});
-  if (!el) return false;
-  const snapshot = el.innerHTML.length + '|' + el.childElementCount + '|' + el.innerText.length;
-  const prev = window[${JSON.stringify(windowKey)}];
-  window[${JSON.stringify(windowKey)}] = snapshot;
-  if (prev === undefined) return false;
-  return snapshot === prev;
-})()`;
-}
-
-// ---------------------------------------------------------------------------
-// Page Registry — pure-logic operations for multi-page/tab management
-// ---------------------------------------------------------------------------
-
-export function createPageRegistry(): PageRegistry {
-  return { pages: [], activePageId: null, nextId: 1 };
-}
-
-export function registryAddPage(
-  registry: PageRegistry,
-  { page, title = "", url = "", opener = null }: { page: unknown; title?: string; url?: string; opener?: number | null },
-): PageEntry {
-  const entry: PageEntry = { id: registry.nextId++, page, title, url, opener };
-  registry.pages.push(entry);
-  return entry;
-}
-
-export function registryRemovePage(registry: PageRegistry, pageId: number): { removed: PageEntry; newActiveId: number | null } {
-  const idx = registry.pages.findIndex((p) => p.id === pageId);
-  if (idx === -1) {
-    const available = registry.pages.map((p) => p.id);
-    throw new Error(
-      `registryRemovePage: page ${pageId} not found. ` +
-        `Available page IDs: [${available.join(", ")}]. ` +
-        `Registry size: ${registry.pages.length}.`
-    );
-  }
-  const [removed] = registry.pages.splice(idx, 1);
-
-  // Orphan any pages whose opener was the removed page
-  for (const entry of registry.pages) {
-    if (entry.opener === pageId) {
-      entry.opener = null;
-    }
-  }
-
-  let newActiveId = registry.activePageId;
-  if (registry.activePageId === pageId) {
-    if (registry.pages.length === 0) {
-      newActiveId = null;
-    } else if (removed.opener !== null && registry.pages.some((p) => p.id === removed.opener)) {
-      newActiveId = removed.opener;
-    } else {
-      newActiveId = registry.pages[registry.pages.length - 1].id;
-    }
-    registry.activePageId = newActiveId;
-  }
-
-  return { removed, newActiveId };
-}
-
-export function registrySetActive(registry: PageRegistry, pageId: number): void {
-  const entry = registry.pages.find((p) => p.id === pageId);
-  if (!entry) {
-    const available = registry.pages.map((p) => p.id);
-    throw new Error(
-      `registrySetActive: page ${pageId} not found. ` +
-        `Available page IDs: [${available.join(", ")}]. ` +
-        `Registry size: ${registry.pages.length}.`
-    );
-  }
-  registry.activePageId = pageId;
-}
-
-export function registryGetActive(registry: PageRegistry): PageEntry {
-  if (registry.activePageId === null) {
-    throw new Error(
-      `registryGetActive: no active page. ` +
-        `Registry contains ${registry.pages.length} page(s). ` +
-        `Page IDs: [${registry.pages.map((p) => p.id).join(", ")}].`
-    );
-  }
-  const entry = registry.pages.find((p) => p.id === registry.activePageId);
-  if (!entry) {
-    throw new Error(
-      `registryGetActive: activePageId ${registry.activePageId} not found in registry. ` +
-        `Available page IDs: [${registry.pages.map((p) => p.id).join(", ")}]. ` +
-        `Registry size: ${registry.pages.length}. This indicates stale state.`
-    );
-  }
-  return entry;
-}
-
-export function registryGetPage(registry: PageRegistry, pageId: number): PageEntry | null {
-  return registry.pages.find((p) => p.id === pageId) ?? null;
-}
-
-export function registryListPages(registry: PageRegistry): PageListEntry[] {
-  return registry.pages.map((entry) => ({
-    id: entry.id,
-    title: entry.title,
-    url: entry.url,
-    opener: entry.opener,
-    isActive: entry.id === registry.activePageId,
-  }));
-}
-
-// ---------------------------------------------------------------------------
-// FIFO Bounded Log Pusher
-// ---------------------------------------------------------------------------
-
-export function createBoundedLogPusher(maxSize: number): (array: unknown[], entry: unknown) => void {
-  return function push(array: unknown[], entry: unknown): void {
-    array.push(entry);
-    if (array.length > maxSize) {
-      array.splice(0, array.length - maxSize);
-    }
-  };
-}
-
-export async function runBatchSteps({ steps, executeStep, stopOnFailure = true }: {
-  steps: unknown[];
-  executeStep: (step: unknown, index: number) => Promise<{ ok: boolean; [key: string]: unknown }>;
-  stopOnFailure?: boolean;
-}): Promise<BatchStepResult> {
-  const results: unknown[] = [];
-  for (let i = 0; i < steps.length; i += 1) {
-    const step = steps[i] as { action: string };
-    const result = await executeStep(step, i);
-    results.push(result);
-    if (result.ok === false && stopOnFailure) {
-      return {
-        ok: false,
-        stopReason: "step_failed",
-        failedStepIndex: i,
-        stepResults: results,
-        summary: `Stopped at step ${i + 1} (${step.action})`,
-      };
-    }
-  }
-  return {
-    ok: true,
-    stopReason: null,
-    failedStepIndex: null,
-    stepResults: results,
-    summary: `Completed ${results.length} step(s)`,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Snapshot Modes — semantic element filtering for browser_snapshot_refs
-// ---------------------------------------------------------------------------
-
-export const SNAPSHOT_MODES: Record<string, SnapshotModeConfig> = {
-  interactive: {
-    tags: [],
-    roles: [],
-    selectors: [],
-    ariaAttributes: [],
-    useInteractiveFilter: true,
-  },
-  form: {
-    tags: ["input", "select", "textarea", "button", "fieldset", "label", "output", "datalist"],
-    roles: ["textbox", "searchbox", "combobox", "checkbox", "radio", "switch", "slider", "spinbutton", "listbox", "option"],
-    selectors: ["[contenteditable]"],
-    ariaAttributes: [],
-    useInteractiveFilter: false,
-  },
-  dialog: {
-    tags: ["dialog"],
-    roles: ["dialog", "alertdialog"],
-    selectors: ['[role="dialog"]', '[role="alertdialog"]'],
-    ariaAttributes: [],
-    useInteractiveFilter: false,
-    containerExpand: true,
-  },
-  navigation: {
-    tags: ["a", "nav"],
-    roles: ["link", "navigation", "menubar", "menu", "menuitem"],
-    selectors: [],
-    ariaAttributes: [],
-    useInteractiveFilter: false,
-  },
-  errors: {
-    tags: [],
-    roles: ["alert", "status"],
-    selectors: ['[aria-invalid="true"]', '[role="alert"]', '[role="status"]'],
-    ariaAttributes: ["aria-invalid", "aria-errormessage"],
-    useInteractiveFilter: false,
-    containerExpand: true,
-  },
-  headings: {
-    tags: ["h1", "h2", "h3", "h4", "h5", "h6"],
-    roles: ["heading"],
-    selectors: [],
-    ariaAttributes: [],
-    useInteractiveFilter: false,
-  },
-  visible_only: {
-    tags: [],
-    roles: [],
-    selectors: [],
-    ariaAttributes: [],
-    useInteractiveFilter: false,
-    visibleOnly: true,
-  },
-};
-
-export function getSnapshotModeConfig(mode: string): SnapshotModeConfig | null {
-  return SNAPSHOT_MODES[mode] ?? null;
-}
-
-// ---------------------------------------------------------------------------
-// Fingerprint functions — structural identity for ref resolution
-// ---------------------------------------------------------------------------
-
-export function computeContentHash(text: string): string {
-  if (!text) return "0";
-  let h = 5381;
-  for (let i = 0; i < text.length; i++) {
-    h = ((h << 5) - h + text.charCodeAt(i)) | 0;
-  }
-  return (h >>> 0).toString(16);
-}
-
-export function computeStructuralSignature(tag: string, role: string, childTags: string[]): string {
-  const input = `${tag}|${role}|${childTags.join(",")}`;
-  let h = 5381;
-  for (let i = 0; i < input.length; i++) {
-    h = ((h << 5) - h + input.charCodeAt(i)) | 0;
-  }
-  return (h >>> 0).toString(16);
-}
-
-export function matchFingerprint(
-  stored: { contentHash?: string; structuralSignature?: string },
-  candidate: { contentHash?: string; structuralSignature?: string },
-): boolean {
-  if (!stored || !candidate) return false;
-  if (!stored.contentHash || !stored.structuralSignature) return false;
-  if (!candidate.contentHash || !candidate.structuralSignature) return false;
-  return stored.contentHash === candidate.contentHash &&
-    stored.structuralSignature === candidate.structuralSignature;
-}
-
-// ---------------------------------------------------------------------------
-// Timeline Formatting
-// ---------------------------------------------------------------------------
-
-function formatDurationMs(entry: { startedAt?: number; finishedAt?: number | null }): number | null {
-  const startedAt = typeof entry?.startedAt === "number" ? entry.startedAt : null;
-  const finishedAt = typeof entry?.finishedAt === "number" ? entry.finishedAt : null;
-  if (startedAt == null || finishedAt == null || finishedAt < startedAt) return null;
-  return finishedAt - startedAt;
-}
-
-function summarizeActionStatus(status: string | undefined): string {
-  if (status === "error") return "error";
-  if (status === "running") return "running";
-  return "success";
-}
-
-function looksBoundedWarning(value: unknown): boolean {
-  return /bounded .*history/i.test(String(value ?? ""));
-}
-
-function uniqueStrings(values: (string | undefined)[]): string[] {
-  return [...new Set(values.filter(Boolean))] as string[];
-}
-
-export function formatTimelineEntries(entries: ActionEntry[] = [], options: Record<string, unknown> = {}): FormattedTimeline {
-  const retained = (options.retained as number) ?? entries.length;
-  const totalRecorded = (options.totalRecorded as number) ?? retained;
-  const bounded = totalRecorded > retained;
-
-  if (!entries.length) {
-    return {
-      entries: [],
-      retained,
-      totalRecorded,
-      bounded,
-      summary: "No browser actions recorded.",
-    };
-  }
-
-  const formattedEntries = entries.map((entry) => {
-    const status = summarizeActionStatus(entry.status);
-    const durationMs = formatDurationMs(entry);
-    const parts: string[] = [
-      `#${entry.id ?? "?"}`,
-      entry.tool ?? "unknown_tool",
-      status,
-    ];
-
-    if (durationMs != null) parts.push(`${durationMs}ms`);
-    if (entry.paramsSummary) parts.push(entry.paramsSummary);
-    if (entry.error) parts.push(entry.error);
-    if (entry.verificationSummary) parts.push(entry.verificationSummary);
-    if (entry.diffSummary) parts.push(entry.diffSummary);
-    if (entry.warningSummary) parts.push(entry.warningSummary);
-
-    return {
-      id: entry.id ?? null,
-      tool: entry.tool ?? "",
-      status,
-      durationMs,
-      beforeUrl: entry.beforeUrl ?? "",
-      afterUrl: entry.afterUrl ?? "",
-      line: parts.join(" | "),
-    };
-  });
-
-  const summary = bounded
-    ? `Timeline: showing ${retained} of ${totalRecorded} recorded browser actions; older actions were discarded due to bounded history.`
-    : `Timeline: ${retained} browser action${retained === 1 ? "" : "s"} recorded.`;
-
-  return {
-    entries: formattedEntries,
-    retained,
-    totalRecorded,
-    bounded,
-    summary,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Failure Hypothesis
-// ---------------------------------------------------------------------------
-
-export function buildFailureHypothesis(session: Record<string, any> = {}): FailureHypothesis {
-  const timelineEntries = session.actionTimeline?.entries ?? [];
-  const consoleEntries = session.consoleEntries ?? [];
-  const networkEntries = session.networkEntries ?? [];
-  const dialogEntries = session.dialogEntries ?? [];
-  const signals: Array<{ category: string; source: string; detail: string }> = [];
-
-  for (const entry of timelineEntries) {
-    if (entry?.status !== "error") continue;
-    if (entry.tool === "browser_wait_for") {
-      signals.push({
-        category: "wait",
-        source: `action#${entry.id ?? "?"}`,
-        detail: entry.error || entry.warningSummary || "Wait condition failed",
-      });
-      continue;
-    }
-    if (entry.tool === "browser_assert") {
-      signals.push({
-        category: "assert",
-        source: `action#${entry.id ?? "?"}`,
-        detail: entry.error || entry.verificationSummary || "Assertion failed",
-      });
-      continue;
-    }
-    signals.push({
-      category: "action",
-      source: `action#${entry.id ?? "?"}`,
-      detail: entry.error || `${entry.tool ?? "browser action"} failed`,
-    });
-  }
-
-  for (const entry of consoleEntries) {
-    if (entry?.type !== "error" && entry?.type !== "pageerror") continue;
-    signals.push({
-      category: "console",
-      source: entry.type!,
-      detail: entry.text || "Console error recorded",
-    });
-  }
-
-  for (const entry of networkEntries) {
-    const failed = entry?.failed || (typeof entry?.status === "number" && entry.status >= 400);
-    if (!failed) continue;
-    signals.push({
-      category: "network",
-      source: entry.url || "network request",
-      detail: `${entry.url || "request"} failed${typeof entry?.status === "number" ? ` with ${entry.status}` : ""}`,
-    });
-  }
-
-  for (const entry of dialogEntries) {
-    signals.push({
-      category: "dialog",
-      source: entry?.type || "dialog",
-      detail: entry?.message || "Dialog appeared during failure investigation",
-    });
-  }
-
-  const categories = uniqueStrings(signals.map((signal) => signal.category));
-  const hasFailures = categories.length > 0;
-  const summary = hasFailures
-    ? `Recent failure signals detected across ${categories.join(", ")}.`
-    : "No recent failure signals detected.";
-
-  return {
-    hasFailures,
-    categories,
-    summary,
-    signals,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Session Summary
-// ---------------------------------------------------------------------------
-
-export function summarizeBrowserSession(session: Record<string, any> = {}): SessionSummary {
-  const actionTimeline = session.actionTimeline ?? { limit: 0, entries: [] as ActionEntry[] };
-  const actionEntries: ActionEntry[] = actionTimeline.entries ?? [];
-  const retainedActionCount: number = session.retainedActionCount ?? actionEntries.length;
-  const totalActionCount: number = session.totalActionCount ?? retainedActionCount;
-  const pages: Array<Record<string, any>> = session.pages ?? [];
-  const consoleEntries: Array<Record<string, any>> = session.consoleEntries ?? [];
-  const networkEntries: Array<Record<string, any>> = session.networkEntries ?? [];
-  const dialogEntries: Array<Record<string, any>> = session.dialogEntries ?? [];
-
-  const actionStatusCounts = actionEntries.reduce(
-    (acc: Record<string, number>, entry: ActionEntry) => {
-      const status = summarizeActionStatus(entry.status);
-      acc[status] = (acc[status] ?? 0) + 1;
-      return acc;
-    },
-    { success: 0, error: 0, running: 0 },
-  );
-
-  const waitEntries = actionEntries.filter((entry: ActionEntry) => entry.tool === "browser_wait_for");
-  const assertEntries = actionEntries.filter((entry: ActionEntry) => entry.tool === "browser_assert");
-  const consoleErrors = consoleEntries.filter((entry: Record<string, any>) => entry.type === "error" || entry.type === "pageerror");
-  const failedRequests = networkEntries.filter((entry: Record<string, any>) => entry.failed || (typeof entry.status === "number" && entry.status >= 400));
-  const activePage = pages.find((page: Record<string, any>) => page.isActive) ?? pages[0] ?? null;
-
-  const caveats: string[] = [];
-  if (totalActionCount > retainedActionCount) {
-    caveats.push(`Showing ${retainedActionCount} of ${totalActionCount} recorded actions; older actions were discarded due to bounded history.`);
-  }
-  if (
-    actionEntries.some((entry) => looksBoundedWarning(entry.warningSummary) || looksBoundedWarning(entry.error)) ||
-    consoleEntries.some((entry) => looksBoundedWarning(entry.text) || looksBoundedWarning(entry.message)) ||
-    consoleEntries.length > 0
-  ) {
-    caveats.push("bounded console history may hide older console events.");
-  }
-  if (failedRequests.length > 0 || networkEntries.length > 0) {
-    caveats.push("bounded network history may hide older requests.");
-  }
-
-  const failureHypothesis = buildFailureHypothesis(session);
-
-  if (!actionEntries.length && pages.length === 0 && consoleEntries.length === 0 && networkEntries.length === 0 && dialogEntries.length === 0) {
-    return {
-      counts: {
-        pages: 0,
-        actions: { total: 0, retained: 0, success: 0, error: 0, running: 0 },
-        waits: { total: 0, success: 0, error: 0, running: 0 },
-        assertions: { total: 0, passed: 0, failed: 0, running: 0 },
-        consoleErrors: 0,
-        failedRequests: 0,
-        dialogs: 0,
-      },
-      activePage: null,
-      caveats: [],
-      failureHypothesis,
-      summary: "No browser session activity recorded.",
-    };
-  }
-
-  return {
-    counts: {
-      pages: pages.length,
-      actions: {
-        total: totalActionCount,
-        retained: retainedActionCount,
-        success: actionStatusCounts.success,
-        error: actionStatusCounts.error,
-        running: actionStatusCounts.running,
-      },
-      waits: {
-        total: waitEntries.length,
-        success: waitEntries.filter((entry) => summarizeActionStatus(entry.status) === "success").length,
-        error: waitEntries.filter((entry) => summarizeActionStatus(entry.status) === "error").length,
-        running: waitEntries.filter((entry) => summarizeActionStatus(entry.status) === "running").length,
-      },
-      assertions: {
-        total: assertEntries.length,
-        passed: assertEntries.filter((entry) => summarizeActionStatus(entry.status) === "success").length,
-        failed: assertEntries.filter((entry) => summarizeActionStatus(entry.status) === "error").length,
-        running: assertEntries.filter((entry) => summarizeActionStatus(entry.status) === "running").length,
-      },
-      consoleErrors: consoleErrors.length,
-      failedRequests: failedRequests.length,
-      dialogs: dialogEntries.length,
-    },
-    activePage: activePage
-      ? {
-          id: activePage.id ?? null,
-          title: activePage.title ?? "",
-          url: activePage.url ?? "",
-        }
-      : null,
-    caveats,
-    failureHypothesis,
-    summary: `Session: ${pages.length} page${pages.length === 1 ? "" : "s"}, ${totalActionCount} actions, ${waitEntries.length} wait${waitEntries.length === 1 ? "" : "s"}, ${assertEntries.length} assert${assertEntries.length === 1 ? "" : "s"}.${caveats.length ? ` ${caveats.join(" ")}` : ""}`,
-  };
-}