speqs 0.5.1 → 0.7.0

package/dist/lib/local-sim/browser.js

@@ -0,0 +1,332 @@
+/**
+ * Playwright browser lifecycle, CDP tree extraction, and node resolution.
+ *
+ * Tree format matches backend's get_accessibility_tree():
+ *   [frame_index:node_id] role "name"
+ * with single-space indentation per level.
+ */
+import { chromium } from "playwright-core";
+// Import install module for side-effect: sets PLAYWRIGHT_BROWSERS_PATH
+import "./install.js";
+// Viewport presets matching backend (app/simulation/computers/config.py)
+const VIEWPORT_PRESETS = {
+    desktop: { width: 1440, height: 900 },
+    mobile_portrait: { width: 393, height: 852 },
+};
+const MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) " +
+    "AppleWebKit/605.1.15 (KHTML, like Gecko) " +
+    "Version/17.0 Mobile/15E148 Safari/604.1";
+const NODE_NAME_MAX_LENGTH = 50;
+/**
+ * Launch a shared browser process with a pre-configured context.
+ * Create tabs with createTab() — they appear as tabs in one window.
+ */
+export async function launchSharedBrowser(opts) {
+    const viewport = opts.viewport ?? VIEWPORT_PRESETS[opts.screenFormat] ?? VIEWPORT_PRESETS.desktop;
+    const isMobile = opts.screenFormat === "mobile_portrait";
+    const browser = await chromium.launch({
+        headless: !opts.headed,
+        ...(opts.slowMo && { slowMo: opts.slowMo }),
+        args: [
+            "--disable-blink-features=AutomationControlled",
+            "--disable-features=IsolateOrigins,site-per-process",
+            "--no-first-run",
+            "--no-default-browser-check",
+        ],
+    });
+    // Create the default context so all tabs share it
+    await browser.newContext({
+        viewport,
+        ...(isMobile && {
+            userAgent: MOBILE_USER_AGENT,
+            deviceScaleFactor: 2,
+            isMobile: true,
+            hasTouch: true,
+        }),
+        ...(opts.locale && { locale: opts.locale }),
+    });
+    return browser;
+}
+/**
+ * Create a new tab in the shared browser's default context.
+ * Tabs share cookies/storage — appears as tabs in one window in headed mode.
+ */
+export async function createTab(browser, opts) {
+    // Reuse the first context (default) so tabs appear in the same window
+    const contexts = browser.contexts();
+    let context;
+    if (contexts.length > 0) {
+        context = contexts[0];
+    }
+    else {
+        const viewport = opts.viewport ?? VIEWPORT_PRESETS[opts.screenFormat] ?? VIEWPORT_PRESETS.desktop;
+        const isMobile = opts.screenFormat === "mobile_portrait";
+        context = await browser.newContext({
+            viewport,
+            ...(isMobile && {
+                userAgent: MOBILE_USER_AGENT,
+                deviceScaleFactor: 2,
+                isMobile: true,
+                hasTouch: true,
+            }),
+            ...(opts.locale && { locale: opts.locale }),
+        });
+    }
+    const page = await context.newPage();
+    page.setDefaultNavigationTimeout(30_000);
+    page.setDefaultTimeout(10_000);
+    return { browser, context, page };
+}
+/**
+ * Launch a standalone browser session (single tester, owns the browser).
+ */
+export async function launchBrowser(opts) {
+    const browser = await launchSharedBrowser(opts);
+    return createTab(browser, opts);
+}
+/**
+ * Capture a full observation from the current page state.
+ */
+export async function captureObservation(page) {
+    await page.waitForLoadState("networkidle").catch(() => { });
+    const screenshotBuffer = await page.screenshot({ type: "png" });
+    const screenshot = screenshotBuffer.toString("base64");
+    const treeData = await extractAccessibilityTree(page);
+    const url = page.url();
+    const viewportSize = page.viewportSize() ?? { width: 1440, height: 900 };
+    const { scrollY, docHeight } = await page.evaluate(() => ({
+        scrollY: Math.round(window.scrollY),
+        docHeight: document.documentElement.scrollHeight,
+    }));
+    return {
+        screenshot,
+        treeData,
+        url,
+        viewportWidth: viewportSize.width,
+        viewportHeight: viewportSize.height,
+        scrollPosition: scrollY,
+        documentHeight: docHeight,
+    };
+}
+/**
+ * Extract accessibility tree via CDP, matching backend's [nodeId] role "name" format.
+ */
+export async function extractAccessibilityTree(page) {
+    const nodeMap = new Map();
+    const allNodes = new Map();
+    let rootId = null;
+    const frames = page.frames();
+    for (let frameIndex = 0; frameIndex < frames.length; frameIndex++) {
+        const frame = frames[frameIndex];
+        let cdp;
+        try {
+            cdp = await frame.page().context().newCDPSession(frame.page());
+        }
+        catch {
+            continue;
+        }
+        try {
+            const result = await cdp.send("Accessibility.getFullAXTree");
+            const nodes = result.nodes || [];
+            for (const node of nodes) {
+                const compositeId = `${frameIndex}:${node.nodeId}`;
+                const parentCompositeId = node.parentId ? `${frameIndex}:${node.parentId}` : null;
+                allNodes.set(compositeId, {
+                    ...node,
+                    compositeId,
+                    children: (node.childIds || []).map(c => `${frameIndex}:${c}`),
+                });
+                if (node.backendDOMNodeId) {
+                    nodeMap.set(compositeId, {
+                        backendNodeId: node.backendDOMNodeId,
+                        frameIndex,
+                    });
+                }
+                // Track the root (first node without a parent in frame 0)
+                if (frameIndex === 0 && !parentCompositeId && !rootId) {
+                    rootId = compositeId;
+                }
+            }
+        }
+        catch {
+            // Frame may have detached
+        }
+        finally {
+            await cdp.detach().catch(() => { });
+        }
+    }
+    // Build simplified text
+    const lines = [];
+    function formatNode(id, depth) {
+        const node = allNodes.get(id);
+        if (!node)
+            return;
+        const role = node.role?.value || "";
+        const name = node.name?.value || "";
+        const ignored = node.ignored ?? false;
+        // Skip ignored nodes without meaningful children
+        const isStructural = ["generic", "none", "presentation", "InlineTextBox"].includes(role);
+        if (ignored || isStructural) {
+            // Still traverse children
+            for (const childId of node.children) {
+                formatNode(childId, depth);
+            }
+            return;
+        }
+        // Skip nodes with no role or only whitespace name
+        if (!role || role === "RootWebArea" && depth > 0) {
+            for (const childId of node.children) {
+                formatNode(childId, depth);
+            }
+            return;
+        }
+        const indent = " ".repeat(depth);
+        const truncatedName = name.length > NODE_NAME_MAX_LENGTH
+            ? name.slice(0, NODE_NAME_MAX_LENGTH) + "..."
+            : name;
+        const nameStr = truncatedName ? ` "${truncatedName}"` : "";
+        lines.push(`${indent}[${id}] ${role}${nameStr}`);
+        // Show grouping marker for many children
+        if (node.children.length >= 3) {
+            lines.push(`${indent} --- ${node.children.length} children ---`);
+        }
+        for (const childId of node.children) {
+            formatNode(childId, depth + 1);
+        }
+    }
+    if (rootId) {
+        formatNode(rootId, 0);
+    }
+    return {
+        simplified: lines.join("\n"),
+        nodeMap,
+    };
+}
+// --- Node Resolution via CDP ---
+/**
+ * Resolve a composite node_id (e.g., "0:42") to bounding box coordinates.
+ */
+export async function resolveNodeToBoundingBox(page, nodeId, treeData) {
+    const nodeInfo = treeData.nodeMap.get(nodeId);
+    if (!nodeInfo)
+        return null;
+    let cdp;
+    try {
+        cdp = await page.context().newCDPSession(page);
+    }
+    catch {
+        return null;
+    }
+    try {
+        // Resolve backend DOM node to a JS object
+        const domResult = await cdp.send("DOM.resolveNode", {
+            backendNodeId: nodeInfo.backendNodeId,
+        });
+        const objectId = domResult?.object?.objectId;
+        if (!objectId)
+            return null;
+        // Get bounding box via JS — walk up to parent if node has zero size
+        // (text nodes and inline elements often have no bounding rect)
+        const boxResult = await cdp.send("Runtime.callFunctionOn", {
+            objectId,
+            functionDeclaration: `function() {
+        let el = this;
+        for (let i = 0; i < 5; i++) {
+          const r = el.getBoundingClientRect ? el.getBoundingClientRect() : null;
+          if (r && r.width > 0 && r.height > 0) {
+            return { x: r.x + r.width / 2, y: r.y + r.height / 2, width: r.width, height: r.height };
+          }
+          if (!el.parentElement) break;
+          el = el.parentElement;
+        }
+        return null;
+      }`,
+            returnByValue: true,
+        });
+        return boxResult?.result?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await cdp.detach().catch(() => { });
+    }
+}
+/**
+ * Resolve a composite node_id to an XPath selector.
+ */
+export async function resolveNodeToXPath(page, nodeId, treeData) {
+    const nodeInfo = treeData.nodeMap.get(nodeId);
+    if (!nodeInfo)
+        return null;
+    let cdp;
+    try {
+        cdp = await page.context().newCDPSession(page);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const domResult = await cdp.send("DOM.resolveNode", {
+            backendNodeId: nodeInfo.backendNodeId,
+        });
+        const objectId = domResult?.object?.objectId;
+        if (!objectId)
+            return null;
+        const xpathResult = await cdp.send("Runtime.callFunctionOn", {
+            objectId,
+            functionDeclaration: `function() {
+        function getXPath(node) {
+          if (!node.parentNode) return '';
+          if (node === document.body) return '/html/body';
+          const siblings = Array.from(node.parentNode.children).filter(c => c.tagName === node.tagName);
+          const index = siblings.indexOf(node) + 1;
+          const tag = node.tagName.toLowerCase();
+          const suffix = siblings.length > 1 ? '[' + index + ']' : '';
+          return getXPath(node.parentNode) + '/' + tag + suffix;
+        }
+        return getXPath(this);
+      }`,
+            returnByValue: true,
+        });
+        return xpathResult?.result?.value || null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await cdp.detach().catch(() => { });
+    }
+}
+// --- Utilities ---
+export async function takeScreenshot(page) {
+    const buffer = await page.screenshot({ type: "png" });
+    return buffer.toString("base64");
+}
+export async function takeScreenshotJpeg(page, quality = 85) {
+    return page.screenshot({ type: "jpeg", quality });
+}
+export async function navigateWithRetry(page, url, maxRetries = 3) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+            return;
+        }
+        catch {
+            if (attempt === maxRetries) {
+                throw new Error(`Navigation failed after ${maxRetries} attempts: ${url}`);
+            }
+            await page.waitForTimeout(Math.min(3000 * attempt, 8000));
+        }
+    }
+}
+export async function closeBrowser(session) {
+    try {
+        await session.context.close();
+    }
+    catch { }
+    try {
+        await session.browser.close();
+    }
+    catch { }
+}

package/dist/lib/local-sim/debug-report.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Debug HTML report generator for local simulations.
+ *
+ * Produces a self-contained HTML file with inline screenshots,
+ * coordinate overlays, and step-by-step details.
+ */
+import type { DebugStep } from "./loop.js";
+export type { DebugStep };
+export interface DebugReportMeta {
+    testerId: string;
+    testerName: string;
+    url: string;
+    screenFormat: string;
+    finalStatus: string;
+    assignmentStatuses: Array<{
+        assignment_id: string;
+        status: string;
+        step_count: number;
+    }>;
+}
+export declare function generateDebugReport(steps: DebugStep[], meta: DebugReportMeta): void;

package/dist/lib/local-sim/debug-report.js

@@ -0,0 +1,186 @@
+/**
+ * Debug HTML report generator for local simulations.
+ *
+ * Produces a self-contained HTML file with inline screenshots,
+ * coordinate overlays, and step-by-step details.
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+const SENTIMENT_COLORS = {
+    Positive: "#4caf50",
+    Negative: "#f44336",
+    Neutral: "#9e9e9e",
+    Confused: "#ff9800",
+    Frustrated: "#f44336",
+    Uncertain: "#ff9800",
+    Delighted: "#4caf50",
+    Confident: "#2196f3",
+};
+export function generateDebugReport(steps, meta) {
+    const dir = join(homedir(), ".speqs", "debug");
+    mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const shortId = meta.testerId.slice(0, 12);
+    const fileName = `sim-${shortId}-${ts}.html`;
+    const filePath = join(dir, fileName);
+    const totalSteps = steps.length;
+    const assignmentHtml = meta.assignmentStatuses
+        .map((a) => {
+        const color = a.status === "completed" ? "#4caf50" : a.status === "cancelled" ? "#f44336" : "#ff9800";
+        return `<span class="badge" style="background:${color}">${escapeHtml(a.status)} (${a.step_count} steps)</span>`;
+    })
+        .join(" ");
+    let stepsHtml = "";
+    for (const step of steps) {
+        const sentimentColor = SENTIMENT_COLORS[step.sentiment.label] ?? "#9e9e9e";
+        // Coordinate dot overlays
+        let dotsHtml = "";
+        for (let i = 0; i < step.actions.length; i++) {
+            const a = step.actions[i];
+            if (a.normalizedCoordinates) {
+                const leftPct = a.normalizedCoordinates.x / 10;
+                const topPct = a.normalizedCoordinates.y / 10;
+                const dotColor = a.success ? "#ff4444" : "#ff9800";
+                dotsHtml += `<div class="coord-dot" style="left:${leftPct}%;top:${topPct}%;background:${dotColor};" title="${escapeHtml(a.description)}">${i + 1}</div>\n`;
+            }
+        }
+        // Action details
+        let actionsHtml = "";
+        for (let i = 0; i < step.actions.length; i++) {
+            const a = step.actions[i];
+            const statusClass = a.success ? "action-ok" : "action-fail";
+            const px = a.pixelCoordinates ? `(${Math.round(a.pixelCoordinates.x)}, ${Math.round(a.pixelCoordinates.y)})` : "none";
+            const norm = a.normalizedCoordinates ? `(${a.normalizedCoordinates.x}, ${a.normalizedCoordinates.y})` : "none";
+            actionsHtml += `
+        <div class="action ${statusClass}">
+          <strong>${i + 1}. ${escapeHtml(a.type)}</strong> ${a.elementName ? `on <em>${escapeHtml(a.elementName)}</em>` : ""}
+          ${!a.success ? '<span class="fail-badge">FAILED</span>' : ""}
+          <div class="action-meta">
+            <span>${escapeHtml(a.description)}</span><br/>
+            <span>Pixel: ${px} | Normalized: ${norm}</span>
+          </div>
+        </div>`;
+        }
+        const afterHtml = step.postActionScreenshotBase64
+            ? `<div class="screenshot-panel">
+           <div class="screenshot-label">After</div>
+           <div class="screenshot-container">
+             <img src="data:image/jpeg;base64,${step.postActionScreenshotBase64}" alt="Step ${step.step} after" />
+           </div>
+         </div>`
+            : "";
+        stepsHtml += `
+      <div class="step-card">
+        <div class="step-header">
+          <h3>Step ${step.step}</h3>
+          <span class="assignment-label">${escapeHtml(step.assignmentName)}</span>
+          <span class="sentiment" style="color:${sentimentColor}">${escapeHtml(step.sentiment.label)}</span>
+          ${step.assignmentCompleted ? '<span class="badge" style="background:#4caf50">COMPLETED</span>' : ""}
+        </div>
+        <div class="step-body">
+          <div class="screenshots">
+            <div class="screenshot-panel">
+              <div class="screenshot-label">Before (observation)</div>
+              <div class="screenshot-container">
+                <img src="data:image/jpeg;base64,${step.screenshotBase64}" alt="Step ${step.step} before" />
+                ${dotsHtml}
+              </div>
+            </div>
+            ${afterHtml}
+          </div>
+          <div class="details">
+            <div class="detail-section">
+              <h4>Actions</h4>
+              ${actionsHtml}
+            </div>
+            <div class="detail-section">
+              <h4>Comment</h4>
+              <p class="comment">${step.comment ? escapeHtml(step.comment) : "<em>none</em>"}</p>
+            </div>
+            <div class="detail-row">
+              <span><strong>Location:</strong> ${step.currentLocation ? escapeHtml(step.currentLocation) : "unknown"}</span>
+              <span><strong>URL:</strong> ${escapeHtml(step.url)}</span>
+              <span><strong>Effort:</strong> ${step.effortSeconds.toFixed(1)}s</span>
+              <span><strong>Sentiment:</strong> v=${step.sentiment.valence.toFixed(1)} i=${step.sentiment.intensity.toFixed(1)}</span>
+            </div>
+          </div>
+        </div>
+      </div>`;
+    }
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Local Sim Debug — ${escapeHtml(meta.testerName)}</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { background: #1a1a2e; color: #e0e0e0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace; padding: 20px; }
+  h1 { color: #fff; margin-bottom: 8px; }
+  h3 { color: #fff; }
+  h4 { color: #aaa; margin-bottom: 6px; font-size: 13px; text-transform: uppercase; letter-spacing: 0.5px; }
+  a { color: #64b5f6; }
+  .header { margin-bottom: 24px; padding: 16px; background: #16213e; border-radius: 8px; }
+  .header-meta { display: flex; flex-wrap: wrap; gap: 16px; margin-top: 8px; font-size: 14px; color: #aaa; }
+  .header-meta span { white-space: nowrap; }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 12px; color: #fff; font-weight: 600; }
+  .step-card { margin-bottom: 24px; background: #16213e; border-radius: 8px; overflow: hidden; border: 1px solid #2a2a4a; }
+  .step-header { display: flex; align-items: center; gap: 12px; padding: 12px 16px; background: #1a1a3e; border-bottom: 1px solid #2a2a4a; }
+  .step-header h3 { font-size: 16px; min-width: 70px; }
+  .assignment-label { font-size: 13px; color: #aaa; }
+  .sentiment { font-size: 14px; font-weight: 600; margin-left: auto; }
+  .step-body { display: flex; gap: 16px; padding: 16px; }
+  .screenshots { display: flex; gap: 8px; flex-shrink: 0; max-width: 900px; }
+  .screenshot-panel { flex: 1; min-width: 0; }
+  .screenshot-label { font-size: 11px; color: #666; text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px; }
+  .screenshot-container { position: relative; display: inline-block; width: 100%; }
+  .screenshot-container img { width: 100%; display: block; border-radius: 4px; }
+  .coord-dot {
+    position: absolute; width: 20px; height: 20px; border-radius: 50%;
+    border: 2px solid #fff; transform: translate(-50%, -50%);
+    font-size: 11px; font-weight: 700; color: #fff;
+    display: flex; align-items: center; justify-content: center;
+    text-shadow: 0 0 3px rgba(0,0,0,0.8); cursor: default;
+    box-shadow: 0 0 6px rgba(0,0,0,0.5);
+  }
+  .details { flex: 1; min-width: 280px; }
+  .detail-section { margin-bottom: 12px; }
+  .action { padding: 6px 8px; margin-bottom: 4px; background: #1a1a3e; border-radius: 4px; font-size: 13px; }
+  .action-ok { border-left: 3px solid #4caf50; }
+  .action-fail { border-left: 3px solid #f44336; }
+  .action-meta { font-size: 12px; color: #888; margin-top: 2px; }
+  .fail-badge { background: #f44336; color: #fff; padding: 1px 6px; border-radius: 3px; font-size: 11px; margin-left: 8px; }
+  .comment { font-size: 13px; color: #ccc; line-height: 1.5; white-space: pre-wrap; max-height: 120px; overflow-y: auto; }
+  .detail-row { display: flex; flex-wrap: wrap; gap: 12px; font-size: 12px; color: #888; margin-top: 8px; }
+  @media (max-width: 900px) {
+    .step-body { flex-direction: column; }
+    .screenshots { flex-direction: column; max-width: 100%; }
+  }
+</style>
+</head>
+<body>
+  <div class="header">
+    <h1>Local Sim Debug Report</h1>
+    <div class="header-meta">
+      <span><strong>Tester:</strong> ${escapeHtml(meta.testerName)} (${escapeHtml(meta.testerId.slice(0, 12))})</span>
+      <span><strong>URL:</strong> ${escapeHtml(meta.url)}</span>
+      <span><strong>Format:</strong> ${escapeHtml(meta.screenFormat)}</span>
+      <span><strong>Status:</strong> <span class="badge" style="background:${meta.finalStatus === "completed" ? "#4caf50" : meta.finalStatus === "failed" ? "#f44336" : "#ff9800"}">${escapeHtml(meta.finalStatus)}</span></span>
+      <span><strong>Steps:</strong> ${totalSteps}</span>
+      <span><strong>Assignments:</strong> ${assignmentHtml}</span>
+      <span><strong>Generated:</strong> ${new Date().toISOString()}</span>
+    </div>
+  </div>
+  ${stepsHtml}
+</body>
+</html>`;
+    writeFileSync(filePath, html);
+    console.error(`  Debug report: ${filePath}`);
+}

package/dist/lib/local-sim/debug.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Debug logger for local simulations.
+ *
+ * When enabled (--debug flag), logs the full data flow:
+ *   Backend response → normalized actions → element resolution → execution
+ *
+ * Always writes to stderr so it doesn't interfere with JSON output.
+ * Optionally also writes to a log file (~/.speqs/local-sim.log).
+ */
+import type { LocalSimStepResponse, LocalStepAction } from "./types.js";
+export declare function enableDebug(opts?: {
+    file?: boolean;
+}): void;
+export declare function isDebugEnabled(): boolean;
+export declare function debugObservation(obs: {
+    screenshot: string;
+    treeData: {
+        simplified: string;
+        nodeMap: Map<string, unknown>;
+    };
+    url: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    scrollPosition: number;
+}): void;
+export declare function debugRawResponse(raw: Record<string, unknown>): void;
+export declare function debugNormalizedActions(actions: LocalStepAction[]): void;
+export declare function debugActionExecution(index: number, action: LocalStepAction, result: {
+    success: boolean;
+    coordinates: {
+        x: number;
+        y: number;
+    } | null;
+}, strategy: string): void;
+export declare function debugForwards(forwards: Array<{
+    type: string;
+    content: string;
+}>): void;
+export declare function debugStepSummary(step: number, maxSteps: number, response: LocalSimStepResponse): void;
+export declare function debugRecord(interactionCount: number, status: string, assignmentStatuses: Array<{
+    assignment_id: string;
+    status: string;
+    step_count: number;
+}>): void;

package/dist/lib/local-sim/debug.js

@@ -0,0 +1,103 @@
+/**
+ * Debug logger for local simulations.
+ *
+ * When enabled (--debug flag), logs the full data flow:
+ *   Backend response → normalized actions → element resolution → execution
+ *
+ * Always writes to stderr so it doesn't interfere with JSON output.
+ * Optionally also writes to a log file (~/.speqs/local-sim.log).
+ */
+import { writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const LOG_DIR = join(homedir(), ".speqs");
+const LOG_FILE = join(LOG_DIR, "local-sim.log");
+let debugEnabled = false;
+let logToFile = false;
+export function enableDebug(opts = {}) {
+    debugEnabled = true;
+    logToFile = opts.file ?? false;
+    if (logToFile) {
+        mkdirSync(LOG_DIR, { recursive: true });
+        writeFileSync(LOG_FILE, `=== Local simulation debug log — ${new Date().toISOString()} ===\n`);
+    }
+}
+export function isDebugEnabled() {
+    return debugEnabled;
+}
+function write(msg) {
+    if (!debugEnabled)
+        return;
+    const line = `[${new Date().toISOString().slice(11, 23)}] ${msg}`;
+    console.error(line);
+    if (logToFile) {
+        appendFileSync(LOG_FILE, line + "\n");
+    }
+}
+// --- Logging methods ---
+export function debugObservation(obs) {
+    write(`OBSERVE | url=${obs.url} | viewport=${obs.viewportWidth}x${obs.viewportHeight} | scroll=${obs.scrollPosition}`);
+    write(`OBSERVE | screenshot=${Math.round(obs.screenshot.length * 0.75 / 1024)}KB | tree=${obs.treeData.simplified.length} chars | nodes=${obs.treeData.nodeMap.size}`);
+    if (debugEnabled) {
+        // Log first 5 lines of the tree for quick inspection
+        const treePreview = obs.treeData.simplified.split("\n").slice(0, 5).join("\n  ");
+        write(`OBSERVE | tree preview:\n  ${treePreview}`);
+    }
+}
+export function debugRawResponse(raw) {
+    const keys = Object.keys(raw);
+    write(`RESPONSE | keys: ${keys.join(", ")}`);
+    const output = raw.output;
+    if (output) {
+        write(`RESPONSE | comment: ${String(output.comment ?? "").slice(0, 100)}`);
+        write(`RESPONSE | sentiment: ${output.sentiment} | location: ${output.current_location} | completed: ${output.assignment_completed}`);
+        const action = output.action;
+        const actions = (action?.actions ?? []);
+        write(`RESPONSE | raw actions: ${actions.length} — ${actions.map(a => a.type).join(", ")}`);
+    }
+    const resolved = raw.resolved_actions;
+    if (Array.isArray(resolved)) {
+        write(`RESPONSE | resolved_actions: ${resolved.length}`);
+        for (let i = 0; i < resolved.length; i++) {
+            const ra = resolved[i];
+            const act = ra.action;
+            write(`RESPONSE |   [${i}] type=${act?.type ?? "?"} node_id=${ra.node_id ?? "null"} desc=${ra.node_description ?? "null"}`);
+        }
+    }
+}
+export function debugNormalizedActions(actions) {
+    write(`ACTIONS | ${actions.length} normalized actions:`);
+    for (let i = 0; i < actions.length; i++) {
+        const a = actions[i];
+        write(`ACTIONS |   [${i}] type=${a.type} element="${a.element_name ?? "?"}" node_id=${a.node_id ?? "null"} element_type=${a.element_type ?? "?"}`);
+        if (a.value)
+            write(`ACTIONS |   [${i}] value="${a.value_type === "secret" ? "***" : a.value}" mode=${a.mode ?? "-"} submit=${a.submit ?? false}`);
+        if (a.direction)
+            write(`ACTIONS |   [${i}] direction=${a.direction} amount=${a.amount ?? "-"}`);
+    }
+}
+export function debugActionExecution(index, action, result, strategy) {
+    const status = result.success ? "OK" : "FAIL";
+    const coords = result.coordinates ? `(${result.coordinates.x}, ${result.coordinates.y})` : "no-coords";
+    write(`EXEC | [${index}] ${status} | ${action.type} on "${action.element_name ?? "?"}" | strategy=${strategy} | ${coords}`);
+}
+export function debugForwards(forwards) {
+    if (forwards.length === 0)
+        return;
+    write(`FORWARDS | ${forwards.length} items:`);
+    for (const f of forwards) {
+        write(`FORWARDS |   ${f.type}: ${f.content.slice(0, 100)}`);
+    }
+}
+export function debugStepSummary(step, maxSteps, response) {
+    const icon = response.assignment_completed ? "DONE" : `${step + 1}/${maxSteps}`;
+    write(`STEP ${icon} | ${response.sentiment} | ${response.current_location} | effort=${response.effort_seconds}s`);
+    if (response.loop_detected)
+        write(`STEP | LOOP DETECTED`);
+}
+export function debugRecord(interactionCount, status, assignmentStatuses) {
+    write(`RECORD | ${interactionCount} interactions | status=${status}`);
+    for (const as of assignmentStatuses) {
+        write(`RECORD | assignment ${as.assignment_id.slice(0, 8)} — ${as.status} (${as.step_count} steps)`);
+    }
+}