@taodigital/crawler 0.0.0-stage → 1.2.1

package/src/state-graph.ts

@@ -0,0 +1,280 @@
+import type { Page } from 'playwright';
+
+// ---------------------------------------------------------------------------
+// Internal: FNV-1a 32-bit SimHash
+// ---------------------------------------------------------------------------
+
+function fnv1a32(token: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < token.length; i++) {
+    h = Math.imul(h ^ token.charCodeAt(i), 16777619);
+    h = h >>> 0;
+  }
+  return h;
+}
+
+export function simHash32(text: string): number {
+  const tokens = text
+    .split(/\W+/)
+    .filter((t) => t.length > 2)
+    .slice(0, 500);
+
+  const vec = new Array<number>(32).fill(0);
+
+  for (const token of tokens) {
+    const h = fnv1a32(token);
+    for (let b = 0; b < 32; b++) {
+      vec[b] += (h >>> b) & 1 ? 1 : -1;
+    }
+  }
+
+  let result = 0;
+  for (let b = 0; b < 32; b++) {
+    if (vec[b] > 0) result |= 1 << b;
+  }
+  return result >>> 0;
+}
+
+export function hammingDistance32(a: number, b: number): number {
+  let n = (a ^ b) >>> 0;
+  n = n - ((n >>> 1) & 0x55555555);
+  n = (n & 0x33333333) + ((n >>> 2) & 0x33333333);
+  n = (n + (n >>> 4)) & 0x0f0f0f0f;
+  return Math.imul(n, 0x01010101) >>> 24;
+}
+
+// ---------------------------------------------------------------------------
+// URL normalisation
+// ---------------------------------------------------------------------------
+
+const STRIP_PARAMS = new Set([
+  'utm_source', 'utm_medium', 'utm_campaign',
+  'ref', '_ga', 'fbclid', 'session_id',
+]);
+
+export function normalizeUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    u.hash = '';
+    const keep: Array<[string, string]> = [];
+    u.searchParams.forEach((v, k) => {
+      if (!STRIP_PARAMS.has(k)) keep.push([k, v]);
+    });
+    keep.sort((a, b) => a[0].localeCompare(b[0]));
+    u.search = keep.length
+      ? '?' + keep.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
+      : '';
+    return u.toString();
+  } catch {
+    return raw;
+  }
+}
+
+export function computeStateId(normalizedUrl: string, hash: number): string {
+  let path = normalizedUrl.slice(0, 40).replace(/[^a-zA-Z0-9]/g, '_');
+  const hex = hash.toString(16).padStart(8, '0');
+  return `${path}_${hex}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface UIStateNode {
+  id: string;
+  url: string;
+  normalizedUrl: string;
+  title: string;
+  interactiveElementCount: number;
+  domFingerprint: string;
+  simHashValue: number;
+  visitedAt: string;
+}
+
+export interface StateTransition {
+  fromId: string;
+  toId: string;
+  action: string;
+  label: string;
+  triggeredAt: string;
+}
+
+export interface CoverageReport {
+  totalStates: number;
+  totalTransitions: number;
+  uniqueUrls: number;
+  interactiveElementsTotal: number;
+  estimatedCoveragePercent: number;
+}
+
+// ---------------------------------------------------------------------------
+// Page fingerprinting
+// ---------------------------------------------------------------------------
+
+export async function fingerprintPage(
+  page: Page,
+  visitedAt: string,
+): Promise<{
+  fingerprint: string;
+  visibleText: string;
+  interactiveCount: number;
+  simHashValue: number;
+}> {
+  let visibleText = '';
+  let interactiveCount = 0;
+
+  try {
+    visibleText = await page.evaluate(() => {
+      const el = document.querySelector('main') ?? document.body;
+      return (el as HTMLElement).innerText ?? '';
+    });
+  } catch {
+    visibleText = '';
+  }
+
+  try {
+    interactiveCount = await page.evaluate(() =>
+      document.querySelectorAll(
+        'a[href], button, input, select, textarea, [role="button"], [role="link"], [tabindex]',
+      ).length,
+    );
+  } catch {
+    interactiveCount = 0;
+  }
+
+  const simHashValue = simHash32(visibleText + visitedAt.slice(0, 10));
+  const fingerprint = simHashValue.toString(16).padStart(8, '0');
+
+  return { fingerprint, visibleText, interactiveCount, simHashValue };
+}
+
+// ---------------------------------------------------------------------------
+// ScreenTransitionGraph
+// ---------------------------------------------------------------------------
+
+export class ScreenTransitionGraph {
+  private states = new Map<string, UIStateNode>();
+  private transitions: StateTransition[] = [];
+  /** Maps simHash value → array of state ids with that hash (for near-dup lookup) */
+  private hashIndex = new Map<number, string[]>();
+
+  // -------------------------------------------------------------------------
+  // State management
+  // -------------------------------------------------------------------------
+
+  addState(node: UIStateNode): { added: boolean; duplicateOf?: string } {
+    if (this.states.has(node.id)) {
+      return { added: false, duplicateOf: node.id };
+    }
+
+    // Check near-duplicate via hamming distance across all indexed hashes
+    for (const [indexedHash, ids] of this.hashIndex) {
+      if (hammingDistance32(node.simHashValue, indexedHash) < 3) {
+        return { added: false, duplicateOf: ids[0] };
+      }
+    }
+
+    this.states.set(node.id, node);
+
+    const bucket = this.hashIndex.get(node.simHashValue);
+    if (bucket) {
+      bucket.push(node.id);
+    } else {
+      this.hashIndex.set(node.simHashValue, [node.id]);
+    }
+
+    return { added: true };
+  }
+
+  addTransition(
+    fromId: string,
+    toId: string,
+    action: string,
+    label: string,
+    triggeredAt: string,
+  ): void {
+    this.transitions.push({ fromId, toId, action, label, triggeredAt });
+  }
+
+  isDuplicate(url: string, visibleText: string, threshold = 3): boolean {
+    const normalized = normalizeUrl(url);
+    const hash = simHash32(visibleText);
+    for (const [indexedHash] of this.hashIndex) {
+      if (hammingDistance32(hash, indexedHash) < threshold) return true;
+    }
+    // Also check exact normalized URL match
+    for (const node of this.states.values()) {
+      if (node.normalizedUrl === normalized) return true;
+    }
+    return false;
+  }
+
+  // -------------------------------------------------------------------------
+  // Reporting
+  // -------------------------------------------------------------------------
+
+  getCoverageReport(): CoverageReport {
+    const totalStates = this.states.size;
+    const totalTransitions = this.transitions.length;
+    const uniqueUrls = new Set(
+      Array.from(this.states.values()).map((n) => n.normalizedUrl),
+    ).size;
+    const interactiveElementsTotal = Array.from(this.states.values()).reduce(
+      (sum, n) => sum + n.interactiveElementCount,
+      0,
+    );
+    const estimatedCoveragePercent = Math.min(
+      100,
+      (totalTransitions / Math.max(1, totalStates)) * 50,
+    );
+    return {
+      totalStates,
+      totalTransitions,
+      uniqueUrls,
+      interactiveElementsTotal,
+      estimatedCoveragePercent,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Serialisation
+  // -------------------------------------------------------------------------
+
+  toJSON(): { states: UIStateNode[]; transitions: StateTransition[] } {
+    return {
+      states: Array.from(this.states.values()),
+      transitions: this.transitions,
+    };
+  }
+
+  static fromJSON(data: { states: UIStateNode[]; transitions: StateTransition[] }): ScreenTransitionGraph {
+    const graph = new ScreenTransitionGraph();
+    for (const node of data.states) {
+      graph.states.set(node.id, node);
+      const bucket = graph.hashIndex.get(node.simHashValue);
+      if (bucket) {
+        bucket.push(node.id);
+      } else {
+        graph.hashIndex.set(node.simHashValue, [node.id]);
+      }
+    }
+    graph.transitions = [...data.transitions];
+    return graph;
+  }
+
+  // -------------------------------------------------------------------------
+  // Accessors
+  // -------------------------------------------------------------------------
+
+  getState(id: string): UIStateNode | undefined {
+    return this.states.get(id);
+  }
+
+  getAllStates(): UIStateNode[] {
+    return Array.from(this.states.values());
+  }
+
+  getTransitionsFrom(id: string): StateTransition[] {
+    return this.transitions.filter((t) => t.fromId === id);
+  }
+}

package/src/stealth/human-behavior.ts

@@ -0,0 +1,227 @@
+import type { Page } from 'playwright';
+
+// Gaussian random using Box-Muller transform
+function gaussian(mean: number, sigma: number): number {
+  const u1 = Math.random();
+  const u2 = Math.random();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return mean + z * sigma;
+}
+
+export async function humanDelay(min = 80, max = 450): Promise<void> {
+  const mean = (min + max) / 2;
+  const sigma = (max - min) / 6;
+  const delay = Math.max(min, Math.min(max, gaussian(mean, sigma)));
+  await new Promise(r => setTimeout(r, Math.round(delay)));
+}
+
+export async function simulateMouseMovement(page: Page, targetX: number, targetY: number): Promise<void> {
+  try {
+    const mouse = page.mouse;
+    const steps = 8 + Math.floor(Math.random() * 8);
+    // Generate Bezier control points with slight perpendicular offset
+    const startX = targetX - 100 + Math.random() * 200;
+    const startY = targetY - 100 + Math.random() * 200;
+    const cpX = (startX + targetX) / 2 + (Math.random() - 0.5) * 80;
+    const cpY = (startY + targetY) / 2 + (Math.random() - 0.5) * 80;
+
+    for (let i = 0; i <= steps; i++) {
+      const t = i / steps;
+      // Quadratic Bezier: B(t) = (1-t)^2 * P0 + 2(1-t)t * P1 + t^2 * P2
+      const x = (1 - t) * (1 - t) * startX + 2 * (1 - t) * t * cpX + t * t * targetX;
+      const y = (1 - t) * (1 - t) * startY + 2 * (1 - t) * t * cpY + t * t * targetY;
+      await mouse.move(x + (Math.random() - 0.5) * 2, y + (Math.random() - 0.5) * 2);
+      if (i < steps) await humanDelay(8, 25);
+    }
+    // Small overshoot correction
+    await mouse.move(targetX + (Math.random() - 0.5) * 4, targetY + (Math.random() - 0.5) * 4);
+    await humanDelay(30, 80);
+    await mouse.move(targetX, targetY);
+  } catch { /* non-fatal */ }
+}
+
+export async function simulateMouseHover(page: Page, selector: string): Promise<void> {
+  try {
+    const el = await page.$(selector);
+    if (!el) return;
+    const box = await el.boundingBox();
+    if (!box) return;
+    const cx = box.x + box.width / 2;
+    const cy = box.y + box.height / 2;
+    await simulateMouseMovement(page, cx, cy);
+    await humanDelay(100, 300);
+  } catch { /* non-fatal */ }
+}
+
+export async function simulateClick(page: Page, selector: string): Promise<void> {
+  try {
+    await simulateMouseHover(page, selector);
+    await humanDelay(50, 150);
+    await page.click(selector, { delay: Math.round(gaussian(80, 30)) });
+  } catch { /* non-fatal */ }
+}
+
+export async function injectFingerprintOverrides(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    // Canvas noise — subtle per-pixel perturbation
+    const origToDataURL = HTMLCanvasElement.prototype.toDataURL;
+    HTMLCanvasElement.prototype.toDataURL = function(this: HTMLCanvasElement, ...args: any[]) {
+      const ctx = this.getContext('2d');
+      if (ctx) {
+        const imageData = ctx.getImageData(0, 0, this.width, this.height);
+        for (let i = 0; i < imageData.data.length; i += 4) {
+          imageData.data[i] = Math.max(0, Math.min(255, imageData.data[i] + (Math.random() < 0.01 ? (Math.random() > 0.5 ? 1 : -1) : 0)));
+        }
+        ctx.putImageData(imageData, 0, 0);
+      }
+      return origToDataURL.apply(this, args as [type?: string, quality?: number]);
+    };
+
+    // WebGL parameter spoofing
+    const origGetParam = WebGLRenderingContext.prototype.getParameter;
+    WebGLRenderingContext.prototype.getParameter = function(this: WebGLRenderingContext, parameter: number) {
+      const UNMASKED_VENDOR_WEBGL = 0x9245;
+      const UNMASKED_RENDERER_WEBGL = 0x9246;
+      if (parameter === UNMASKED_VENDOR_WEBGL) return 'Intel Inc.';
+      if (parameter === UNMASKED_RENDERER_WEBGL) return 'Intel Iris OpenGL Engine';
+      return origGetParam.call(this, parameter);
+    };
+
+    // Hardware concurrency — pick from common values
+    const cpuCounts = [4, 6, 8, 8];
+    Object.defineProperty(navigator, 'hardwareConcurrency', {
+      get: () => cpuCounts[Math.floor(Math.random() * cpuCounts.length)],
+      configurable: true,
+    });
+
+    // Device memory
+    Object.defineProperty(navigator, 'deviceMemory', {
+      get: () => [4, 8][Math.floor(Math.random() * 2)],
+      configurable: true,
+    });
+  }).catch(() => {});
+}
+
+export async function infiniteScrollToBottom(
+  page: Page,
+  opts: { maxScrolls?: number; scrollDelay?: number; stabilizeMs?: number } = {},
+  rawPage?: any,
+): Promise<{ scrollCount: number; heightReached: number }> {
+  const { maxScrolls = 50, scrollDelay = 400, stabilizeMs = 600 } = opts;
+  let scrollCount = 0;
+  let stableScrollCount = 0;
+  let previousHeight = 0;
+
+  // One CDP session for wheel events (triggers IntersectionObserver-based virtual scrollers).
+  // React-window / react-virtualized / TanStack Virtual ignore window.scrollBy but respond to
+  // wheel events because they attach their own scroll listeners to the list container.
+  let cdpForWheel: any = null;
+  let viewW = 1280;
+  let viewH = 800;
+  if (rawPage && typeof rawPage.context === 'function') {
+    try {
+      const ctx = rawPage.context();
+      if (typeof ctx?.newCDPSession === 'function') {
+        cdpForWheel = await ctx.newCDPSession(rawPage);
+        const { result } = await cdpForWheel.send('Runtime.evaluate', {
+          expression: `({"w":window.innerWidth,"h":window.innerHeight})`,
+          returnByValue: true,
+        }).catch(() => ({ result: { value: null } }));
+        if (result?.value) { viewW = result.value.w ?? 1280; viewH = result.value.h ?? 800; }
+      }
+    } catch { cdpForWheel = null; }
+  }
+
+  try {
+    while (scrollCount < maxScrolls) {
+      previousHeight = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
+
+      const scrollBy = 500 + Math.floor(Math.random() * 300);
+      // window.scrollBy handles standard scroll containers
+      await page.evaluate((by: number) => window.scrollBy(0, by), scrollBy).catch(() => {});
+      // CDP wheel event triggers IntersectionObserver + virtual list scroll listeners
+      if (cdpForWheel) {
+        await cdpForWheel.send('Input.dispatchMouseEvent', {
+          type: 'mouseWheel',
+          x: Math.floor(viewW / 2),
+          y: Math.floor(viewH / 2),
+          deltaX: 0,
+          deltaY: scrollBy,
+          modifiers: 0,
+        }).catch(() => {});
+      }
+      await humanDelay(scrollDelay - 100, scrollDelay + 200);
+
+      // Use Node.js setTimeout — page.waitForTimeout may not be available on Stagehand proxy
+      await new Promise<void>(r => setTimeout(r, stabilizeMs));
+      scrollCount++;
+
+      const newHeight: number = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
+      if (newHeight - previousHeight < 10) {
+        stableScrollCount++;
+        if (stableScrollCount >= 3) break; // no new content after 3 consecutive non-growing scrolls
+      } else {
+        stableScrollCount = 0;
+      }
+      previousHeight = newHeight;
+    }
+  } catch { /* non-fatal */ }
+
+  if (cdpForWheel) cdpForWheel.detach().catch(() => {});
+  return { scrollCount, heightReached: previousHeight };
+}
+
+export async function extractIframeContent(page: Page): Promise<Array<{ src: string; content: string; markdown: string }>> {
+  const results: Array<{ src: string; content: string; markdown: string }> = [];
+  try {
+    const iframeSrcs: string[] = await page.evaluate(() =>
+      Array.from(document.querySelectorAll('iframe')).map(f => f.getAttribute('src') ?? f.getAttribute('data-src') ?? '')
+    ).catch(() => []);
+
+    for (const frame of page.frames()) {
+      const src = frame.url();
+      if (!src || src === 'about:blank' || src === page.url()) continue;
+      try {
+        const content = await frame.content().catch(() => '');
+        if (!content || content.length < 50) continue;
+        // Simple text extraction from iframe HTML
+        const text = content.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+          .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+          .replace(/<[^>]+>/g, ' ')
+          .replace(/\s+/g, ' ')
+          .trim();
+        results.push({ src, content: content.slice(0, 10_000), markdown: text.slice(0, 5_000) });
+      } catch { /* skip this frame */ }
+    }
+  } catch { /* non-fatal */ }
+  return results;
+}
+
+export async function pierceShadowDom(page: Page): Promise<string> {
+  try {
+    return await page.evaluate(() => {
+      const parts: string[] = [];
+      function walkShadow(root: Element | ShadowRoot): void {
+        const shadow = (root as any).shadowRoot;
+        if (shadow) {
+          parts.push(shadow.innerHTML ?? '');
+          for (const child of [...shadow.querySelectorAll('*')]) walkShadow(child);
+        }
+        for (const child of Array.from(root.querySelectorAll(':not(script):not(style)'))) {
+          if ((child as any).shadowRoot) walkShadow(child);
+        }
+      }
+      walkShadow(document.body);
+      return parts
+        .join('\n')
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 10_000);
+    }).catch(() => '');
+  } catch {
+    return '';
+  }
+}

package/src/telemetry.ts

@@ -0,0 +1,122 @@
+/**
+ * Lightweight OTel-compatible tracing for Zeta crawler.
+ *
+ * Emits spans as structured JSON logs compatible with OpenTelemetry format.
+ * Drop-in upgrade path: replace this module with @opentelemetry/sdk-node when needed.
+ *
+ * Usage:
+ *   const span = startSpan('crawl.url', { url, engine });
+ *   // ... do work ...
+ *   endSpan(span, { screensFound: 3 });
+ */
+
+import { randomBytes } from 'node:crypto';
+
+export interface Span {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  startTimeMs: number;
+  attributes: Record<string, string | number | boolean>;
+}
+
+export interface FinishedSpan extends Span {
+  endTimeMs: number;
+  durationMs: number;
+  status: 'ok' | 'error';
+  error?: string;
+}
+
+// Active trace context — per async execution context (simplified: per-process global)
+let currentTraceId: string | null = null;
+let currentSpanId: string | null = null;
+
+function genId(bytes: number): string {
+  return randomBytes(bytes).toString('hex');
+}
+
+/** Start a new span. If a trace is already active, the new span is a child. */
+export function startSpan(name: string, attributes: Record<string, string | number | boolean> = {}): Span {
+  const traceId = currentTraceId ?? genId(16);
+  const spanId = genId(8);
+  const parentSpanId = currentSpanId ?? undefined;
+
+  if (!currentTraceId) currentTraceId = traceId;
+  currentSpanId = spanId;
+
+  return { traceId, spanId, parentSpanId, name, startTimeMs: Date.now(), attributes };
+}
+
+/** End a span and emit it as a structured log line. */
+export function endSpan(span: Span, extraAttributes: Record<string, string | number | boolean> = {}, error?: Error): FinishedSpan {
+  const endTimeMs = Date.now();
+  const durationMs = endTimeMs - span.startTimeMs;
+  const finished: FinishedSpan = {
+    ...span,
+    attributes: { ...span.attributes, ...extraAttributes },
+    endTimeMs,
+    durationMs,
+    status: error ? 'error' : 'ok',
+    error: error?.message,
+  };
+
+  // Reset context when root span ends
+  if (!span.parentSpanId) {
+    currentTraceId = null;
+    currentSpanId = span.parentSpanId ?? null;
+  } else {
+    currentSpanId = span.parentSpanId ?? null;
+  }
+
+  // Emit as structured JSON — compatible with Datadog/Grafana log parsing
+  console.log(JSON.stringify({
+    ts: new Date(endTimeMs).toISOString(),
+    level: error ? 'error' : 'info',
+    msg: `span:${finished.name}`,
+    trace_id: finished.traceId,
+    span_id: finished.spanId,
+    parent_span_id: finished.parentSpanId,
+    duration_ms: durationMs,
+    status: finished.status,
+    error: finished.error,
+    ...finished.attributes,
+  }));
+
+  return finished;
+}
+
+/** Convenience: wrap an async function in a span. */
+export async function withSpan<T>(
+  name: string,
+  attributes: Record<string, string | number | boolean>,
+  fn: (span: Span) => Promise<T>,
+): Promise<T> {
+  const span = startSpan(name, attributes);
+  try {
+    const result = await fn(span);
+    endSpan(span);
+    return result;
+  } catch (err: any) {
+    endSpan(span, {}, err);
+    throw err;
+  }
+}
+
+/** Counter metrics — increment and log on flush. */
+const counters: Map<string, number> = new Map();
+
+export function increment(metric: string, value = 1, tags: Record<string, string> = {}): void {
+  const key = metric + (Object.keys(tags).length ? ':' + Object.entries(tags).map(([k, v]) => `${k}=${v}`).join(',') : '');
+  counters.set(key, (counters.get(key) ?? 0) + value);
+}
+
+/** Flush counters as a structured log — call periodically (e.g. at job end). */
+export function flushMetrics(): Record<string, number> {
+  const snapshot = Object.fromEntries(counters);
+  if (Object.keys(snapshot).length > 0) {
+    console.log(JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg: 'metrics:flush', ...snapshot }));
+    counters.clear();
+  }
+  return snapshot;
+}

package/src/test-executor.test.ts

@@ -0,0 +1,72 @@
+import http from 'node:http';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { executeTestPlan } from './test-executor.js';
+import type { ExecutionStep } from '@taodigital/agents';
+
+async function startFixtureServer(html: string): Promise<{ url: string; close: () => Promise<void> }> {
+  const server = http.createServer((_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}
+
+// No AI healing context is passed in these tests (healCtx omitted), so the AI tier
+// (which needs a real LLM call) never engages — this is regression coverage for the
+// pre-existing mechanical strategy-fallback tier that self-healing wiring must not break.
+
+test('resolveLocator: primary strategy succeeds when the selector/strategy pair is correct', async () => {
+  const fixture = await startFixtureServer('<html><body><button>Submit</button></body></html>');
+  try {
+    const plan: ExecutionStep[] = [
+      { stepNumber: 1, description: 'navigate', action: 'navigate', url: fixture.url },
+      { stepNumber: 2, description: 'click Submit', action: 'click', selector: 'Submit', selectorStrategy: 'text' },
+    ];
+    const result = await executeTestPlan(plan, { screenshotDir: '/tmp', testRunId: 'test-primary-ok', allowUnsafeLocalUrlsForTests: true });
+    assert.equal(result.status, 'PASSED');
+    assert.equal(result.stepResults[1].healed, false);
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('resolveLocator: mechanical tier heals when the strategy is wrong but the text still matches', async () => {
+  // "label" strategy looks for a form control associated with a <label> — a bare
+  // <button> has no such association, so the primary lookup must fail and fall
+  // through to the "text" strategy, which does find it.
+  const fixture = await startFixtureServer('<html><body><button>Submit</button></body></html>');
+  try {
+    const plan: ExecutionStep[] = [
+      { stepNumber: 1, description: 'navigate', action: 'navigate', url: fixture.url },
+      { stepNumber: 2, description: 'click Submit', action: 'click', selector: 'Submit', selectorStrategy: 'label' },
+    ];
+    const result = await executeTestPlan(plan, { screenshotDir: '/tmp', testRunId: 'test-mechanical-heal', allowUnsafeLocalUrlsForTests: true });
+    assert.equal(result.status, 'PASSED');
+    assert.equal(result.stepResults[1].healed, true);
+    assert.equal(result.stepResults[1].healedVia, 'mechanical');
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('resolveLocator: fails cleanly (no healCtx configured) when no strategy matches at all', async () => {
+  const fixture = await startFixtureServer('<html><body><button>Submit</button></body></html>');
+  try {
+    const plan: ExecutionStep[] = [
+      { stepNumber: 1, description: 'navigate', action: 'navigate', url: fixture.url },
+      { stepNumber: 2, description: 'click Nonexistent', action: 'click', selector: 'Nonexistent Button', selectorStrategy: 'text', timeout: 500 },
+    ];
+    const result = await executeTestPlan(plan, { screenshotDir: '/tmp', testRunId: 'test-no-match', allowUnsafeLocalUrlsForTests: true });
+    assert.equal(result.status, 'FAILED');
+    assert.equal(result.stepResults[1].healed, undefined);
+  } finally {
+    await fixture.close();
+  }
+});