explorbot 0.3.4 → 0.4.0

package/dist/src/ai/tools.js

@@ -7,8 +7,9 @@ import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
+import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage } from "../utils/strings.js";
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
@@ -1161,6 +1162,8 @@ export function clickFailureSuggestion(attempts) {
     return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
 }
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
+const MAX_DISAMBIGUATE_TEXT = 80;
+const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 async function extractWebElements(error) {
     if (!error || error.name !== 'MultipleElementsFound')
@@ -1172,8 +1175,9 @@ async function extractWebElements(error) {
     for (let i = 0; i < Math.min(elements.length, MAX_DISAMBIGUATE_ELEMENTS); i++) {
         try {
             const xpath = await elements[i].toAbsoluteXPath();
-            const html = await elements[i].toSimplifiedHTML();
-            result.push({ xpath, html });
+            const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
+            const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
+            result.push({ xpath, html, text });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1181,17 +1185,20 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-async function formatMatchedElements(error) {
+function formatElementList(details) {
+    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+}
+export async function formatMatchedElements(error) {
     const details = await extractWebElements(error);
     if (!details)
         return 'Could not fetch element details. Repeat the action to get better info.';
-    return details.map((el, i) => `Element ${i + 1}\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    return formatElementList(details);
 }
 async function disambiguateElements(error, explanation, provider) {
     const elementDetails = await extractWebElements(error);
     if (!elementDetails)
         return null;
-    const elementList = elementDetails.map((el, i) => `Element ${i + 1}:\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    const elementList = formatElementList(elementDetails);
     const schema = z.object({
         position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
     });

package/dist/src/api/request-result.d.ts

@@ -33,8 +33,10 @@ export declare class RequestResult {
     get rawResponseBody(): string;
     set rawResponseBodyValue(value: string);
     get responseBody(): any;
+    get isWrite(): boolean;
     save(outputDir: string): void;
     static load(requestFile: string): RequestResult;
+    toEndpoint(): string;
     toSummary(): string;
     extractIdAndTitle(): {
         id?: string | number;

package/dist/src/api/request-result.js

@@ -64,6 +64,9 @@ export class RequestResult {
             return raw;
         }
     }
+    get isWrite() {
+        return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(this.method);
+    }
     save(outputDir) {
         const requestsDir = path.join(outputDir, 'requests');
         if (!existsSync(requestsDir)) {
@@ -137,14 +140,17 @@ export class RequestResult {
             statusText: meta.statusText || '',
             responseHeaders: meta.responseHeaders || {},
             timing: Number.parseInt(meta.timing) || 0,
-            timestamp: new Date(meta.timestamp || Date.now()),
+            timestamp: new Date(meta.timestamp || 0),
         });
         result.requestFile = requestFile;
         result.responseFile = responseFile;
         return result;
     }
+    toEndpoint() {
+        return `${this.method} ${this.path}`;
+    }
     toSummary() {
-        return `${this.method} ${this.path} → ${this.status} (${this.timing}ms)`;
+        return `${this.toEndpoint()} → ${this.status} (${this.timing}ms)`;
     }
     extractIdAndTitle() {
         const body = this.responseBody;

package/dist/src/api/request-store.d.ts

@@ -5,6 +5,7 @@ export declare class RequestStore {
     failedRequests: RequestResult[];
     onFailedListeners: Array<(r: RequestResult) => void>;
     outputDir: string;
+    sessionStartedAt: Date;
     constructor(outputDir: string);
     addCapturedRequest(result: RequestResult): void;
     addFailedRequest(result: RequestResult): void;
@@ -19,9 +20,9 @@ export declare class RequestStore {
     getRequestsByEndpoint(pathPrefix: string): RequestResult[];
     getRequestsByMethod(method: string): RequestResult[];
     getRequestsByStatus(status: number): RequestResult[];
-    toEndpointList(): string;
+    toEndpointList(scopePath?: string): string;
     extractAuthHeaders(): Record<string, string>;
-    findCapturedRequest(method: string, pathPrefix: string): RequestResult | undefined;
+    findCapturedRequest(method: string, searchPath: string): RequestResult | undefined;
     toLog(): string;
     loadFromDisk(): void;
     getWriteRequestsForScope(scopePath: string): RequestResult[];

package/dist/src/api/request-store.js

@@ -1,13 +1,15 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { isDynamicSegment } from "../utils/url-matcher.js";
 import { RequestResult } from "./request-result.js";
-const AUTH_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-csrf-token'];
+const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
     capturedRequests = [];
     madeRequests = [];
     failedRequests = [];
     onFailedListeners = [];
     outputDir;
+    sessionStartedAt = new Date();
     constructor(outputDir) {
         this.outputDir = outputDir;
     }
@@ -61,12 +63,14 @@ export class RequestStore {
     getRequestsByStatus(status) {
         return this.madeRequests.filter((r) => r.status === status);
     }
-    toEndpointList() {
+    toEndpointList(scopePath) {
+        let requests = this.capturedRequests;
+        if (scopePath)
+            requests = this.getWriteRequestsForScope(scopePath);
         const seen = new Set();
         const lines = [];
-        for (const req of this.capturedRequests) {
-            const normalized = normalizePathPattern(req.path);
-            const key = `${req.method} ${normalized}`;
+        for (const req of requests) {
+            const key = `${req.method} ${normalizePathPattern(req.path)}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -76,21 +80,42 @@ export class RequestStore {
     }
     extractAuthHeaders() {
         const headers = {};
-        for (let i = this.capturedRequests.length - 1; i >= 0; i--) {
-            const req = this.capturedRequests[i];
+        const sessionCaptures = this.capturedRequests.filter((r) => r.timestamp >= this.sessionStartedAt).sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        for (const req of sessionCaptures) {
             for (const [key, value] of Object.entries(req.requestHeaders)) {
                 if (AUTH_HEADERS.includes(key.toLowerCase()) && !headers[key]) {
                     headers[key] = value;
                 }
             }
-            if (AUTH_HEADERS.every((h) => Object.keys(headers).some((k) => k.toLowerCase() === h)))
-                break;
         }
         return headers;
     }
-    findCapturedRequest(method, pathPrefix) {
+    findCapturedRequest(method, searchPath) {
         const upper = method.toUpperCase();
-        return this.capturedRequests.find((r) => r.method === upper && r.path.startsWith(pathPrefix));
+        const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+        let best;
+        let bestScore = -1;
+        for (const req of this.capturedRequests) {
+            if (req.method !== upper)
+                continue;
+            const segments = normalizePathPattern(req.path).split('/').filter(Boolean);
+            if (segments.length < search.length)
+                continue;
+            if (!search.every((segment, i) => segment === segments[i]))
+                continue;
+            let score = 0;
+            if (segments.length === search.length)
+                score += 4;
+            if (req.status < 400)
+                score += 2;
+            if (score < bestScore)
+                continue;
+            if (score === bestScore && best && req.timestamp <= best.timestamp)
+                continue;
+            best = req;
+            bestScore = score;
+        }
+        return best;
     }
     toLog() {
         return this.madeRequests.map((r, i) => `${i + 1}. ${r.toSummary()} [${r.id}]`).join('\n');
@@ -100,7 +125,7 @@ export class RequestStore {
         if (!existsSync(requestsDir))
             return;
         const existingIds = new Set(this.capturedRequests.map((r) => r.id));
-        const files = readdirSync(requestsDir).filter((f) => f.endsWith('.request.yaml'));
+        const files = readdirSync(requestsDir).filter((f) => f.startsWith('xhr_') && f.endsWith('.request.yaml'));
         for (const file of files) {
             try {
                 const result = RequestResult.load(path.join(requestsDir, file));
@@ -115,7 +140,31 @@ export class RequestStore {
     }
     getWriteRequestsForScope(scopePath) {
         const writeMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-        return this.capturedRequests.filter((r) => writeMethods.has(r.method) && r.path.startsWith(scopePath));
+        const writes = this.capturedRequests.filter((r) => writeMethods.has(r.method));
+        const scopeSegments = scopePath.split('/').filter(Boolean);
+        if (scopeSegments.length === 0)
+            return writes;
+        let scoped = [];
+        let fewest = Number.POSITIVE_INFINITY;
+        let ambiguous = false;
+        for (const segment of scopeSegments) {
+            if (isDynamicSegment(segment))
+                continue;
+            const matches = writes.filter((r) => r.path.split('/').includes(segment));
+            if (matches.length === 0 || matches.length > fewest)
+                continue;
+            if (matches.length === fewest) {
+                if (!scoped.every((r, i) => r.id === matches[i].id))
+                    ambiguous = true;
+                continue;
+            }
+            scoped = matches;
+            fewest = matches.length;
+            ambiguous = false;
+        }
+        if (ambiguous)
+            return [];
+        return scoped;
     }
     clear() {
         this.capturedRequests = [];
@@ -124,5 +173,8 @@ export class RequestStore {
     }
 }
 function normalizePathPattern(urlPath) {
-    return urlPath.replace(/\/[0-9a-f]{24}\b/g, '/{id}').replace(/\/\d+\b/g, '/{id}');
+    return urlPath
+        .split('/')
+        .map((segment) => (segment && isDynamicSegment(segment) ? '{id}' : segment))
+        .join('/');
 }

package/dist/src/commands/explore-command.d.ts

@@ -1,5 +1,7 @@
 import { type Plan, type Test } from '../test-plan.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
+export declare const DEADLINE_RESERVE_MS: number;
+export declare const DEADLINE_TEST_ALLOWANCE_MS: number;
 export declare class ExploreCommand extends BaseCommand {
     name: string;
     description: string;
@@ -9,8 +11,11 @@ export declare class ExploreCommand extends BaseCommand {
     }[];
     suggestions: Suggestion[];
     maxTests?: number;
+    maxDurationMinutes?: number;
+    hardDeadlineAt?: number;
     dryRun: boolean;
     testsRun: number;
+    deadlineLogged: boolean;
     completedPlans: Plan[];
     failedSubPages: Set<string>;
     oldTestRefs: Set<Test>;
@@ -36,6 +41,7 @@ export declare class ExploreCommand extends BaseCommand {
     printResults(): void;
     printNextSteps(savedPlanPath?: string | null): void;
     isLimitReached(): boolean;
+    isDeadlineReached(): boolean;
     runPendingTests(): Promise<void>;
     runOneTest(test: Test): Promise<void>;
 }

package/dist/src/commands/explore-command.js

@@ -13,11 +13,14 @@ import { safeFilename } from "../utils/strings.js";
 import { BaseCommand } from './base-command.js';
 const MAX_SUB_PAGE_ATTEMPTS = 30;
 const PRIORITY_ORDER = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
+export const DEADLINE_RESERVE_MS = 3 * 60_000;
+export const DEADLINE_TEST_ALLOWANCE_MS = 5 * 60_000;
 export class ExploreCommand extends BaseCommand {
     name = 'explore';
     description = 'Start web exploration';
     options = [
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
+        { flags: '--max-duration <minutes>', description: 'Wall-clock budget in minutes; wraps up the session before the limit is hit' },
         { flags: '--focus <feature>', description: 'Focus area for exploration' },
         { flags: '--configure <spec>', description: 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"' },
         { flags: '--dry-run', description: 'Mark picked tests as skipped without executing or generating new ones' },
@@ -28,8 +31,11 @@ export class ExploreCommand extends BaseCommand {
         { command: 'plan <feature>', hint: 'plan testing' },
     ];
     maxTests;
+    maxDurationMinutes;
+    hardDeadlineAt;
     dryRun = false;
     testsRun = 0;
+    deadlineLogged = false;
     completedPlans = [];
     failedSubPages = new Set();
     oldTestRefs = new Set();
@@ -43,6 +49,12 @@ export class ExploreCommand extends BaseCommand {
         if (opts.maxTests) {
             this.maxTests = Number.parseInt(opts.maxTests, 10);
         }
+        if (opts.maxDuration) {
+            this.maxDurationMinutes = Number.parseInt(opts.maxDuration, 10);
+        }
+        if (this.hardDeadlineAt == null && this.maxDurationMinutes != null) {
+            this.hardDeadlineAt = Date.now() + this.maxDurationMinutes * 60_000 - DEADLINE_RESERVE_MS;
+        }
         const feature = opts.focus || remaining.join(' ') || undefined;
         const cfg = this.parseConfigure(opts.configure);
         if (cfg.priorities)
@@ -515,7 +527,20 @@ export class ExploreCommand extends BaseCommand {
         printNextSteps(sections);
     }
     isLimitReached() {
-        return this.maxTests != null && this.testsRun >= this.maxTests;
+        if (this.maxTests != null && this.testsRun >= this.maxTests)
+            return true;
+        return this.isDeadlineReached();
+    }
+    isDeadlineReached() {
+        if (this.hardDeadlineAt == null)
+            return false;
+        if (Date.now() < this.hardDeadlineAt - DEADLINE_TEST_ALLOWANCE_MS)
+            return false;
+        if (!this.deadlineLogged) {
+            this.deadlineLogged = true;
+            tag('info').log(`Time budget reached after ${this.testsRun} test(s): stopping new work and finishing the session`);
+        }
+        return true;
     }
     async runPendingTests() {
         const plan = this.explorBot.getCurrentPlan();
@@ -539,7 +564,7 @@ export class ExploreCommand extends BaseCommand {
             test.finish(TestResult.SKIPPED);
         }
         else {
-            await this.explorBot.agentTester().test(test);
+            await this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
         }
         this.testsRun++;
     }

package/dist/src/commands/freesail-command.js

@@ -4,7 +4,7 @@ import { Stats } from '../stats.js';
 import { tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
 import { BaseCommand } from './base-command.js';
-import { ExploreCommand } from './explore-command.js';
+import { DEADLINE_RESERVE_MS, DEADLINE_TEST_ALLOWANCE_MS, ExploreCommand } from './explore-command.js';
 export class FreesailCommand extends BaseCommand {
     name = 'freesail';
     description = 'Continuously explore and navigate to new pages autonomously';
@@ -15,6 +15,7 @@ export class FreesailCommand extends BaseCommand {
         { flags: '--shallow', description: 'Use shallow navigation strategy' },
         { flags: '--scope <url>', description: 'Limit navigation to URLs starting with this prefix' },
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
+        { flags: '--max-duration <number>', description: 'Wall-clock budget in minutes for the whole run' },
     ];
     async execute(args) {
         Stats.mode = 'freesail';
@@ -26,11 +27,17 @@ export class FreesailCommand extends BaseCommand {
             strategy = 'shallow';
         const scope = opts.scope;
         const maxTests = opts.maxTests ? Number.parseInt(opts.maxTests, 10) : undefined;
+        const maxDuration = opts.maxDuration ? Number.parseInt(opts.maxDuration, 10) : undefined;
+        let hardDeadlineAt;
+        if (maxDuration != null)
+            hardDeadlineAt = Date.now() + maxDuration * 60_000 - DEADLINE_RESERVE_MS;
         await this.explorBot.visitInitialState();
         let testsRun = 0;
         await loop(async (ctx) => {
             if (maxTests != null && testsRun >= maxTests)
                 ctx.stop();
+            if (hardDeadlineAt != null && Date.now() >= hardDeadlineAt - DEADLINE_TEST_ALLOWANCE_MS)
+                ctx.stop();
             const stateManager = this.explorBot.stateManager();
             const state = stateManager.getCurrentState();
             if (state && !Researcher.getCachedResearch(state)) {
@@ -44,6 +51,8 @@ export class FreesailCommand extends BaseCommand {
                 const exploreCmd = new ExploreCommand(this.explorBot);
                 if (maxTests != null)
                     exploreCmd.maxTests = maxTests - testsRun;
+                if (hardDeadlineAt != null)
+                    exploreCmd.hardDeadlineAt = hardDeadlineAt;
                 await exploreCmd.execute('');
                 const plan = this.explorBot.getCurrentPlan();
                 if (plan)

package/dist/src/commands/plans-command.js

@@ -70,14 +70,14 @@ export class PlansCommand extends BaseCommand {
                 throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
             return file;
         }
-        const resolved = this.explorBot.resolvePlanPath(target);
-        if (!existsSync(resolved)) {
-            throw new Error(`Plan file not found: ${resolved}`);
+        const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
+        if (!plan?.filePath) {
+            throw new Error(`Plan file not found: ${target}`);
         }
         return {
-            name: path.basename(resolved),
-            path: resolved,
-            modifiedAt: statSync(resolved).mtimeMs,
+            name: path.basename(plan.filePath),
+            path: plan.filePath,
+            modifiedAt: statSync(plan.filePath).mtimeMs,
         };
     }
 }

package/dist/src/config.js

@@ -48,6 +48,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
     { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
     { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
+    { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
 export class ConfigParser {
     static instance;

package/dist/src/experience-tracker.js

@@ -105,6 +105,11 @@ export class ExperienceTracker {
                 url: state.url ? extractStatePath(state.url) : '',
                 title: state.title,
             };
+            if (state.overlay.present && state.overlay.name) {
+                frontmatter.region = state.overlay.name;
+                if (state.overlay.root)
+                    frontmatter.root = state.overlay.root;
+            }
             this.writeExperienceFile(stateHash, '', frontmatter);
         }
         return filePath;

package/dist/src/explorbot.d.ts

@@ -114,7 +114,6 @@ export declare class ExplorBot {
     savePlan(filename?: string): string | null;
     savePlans(plans: Plan[], filename?: string): string | null;
     generatePlanFilename(feature?: string): string;
-    resolvePlanPath(filename: string): string;
     loadPlan(filename: string): Plan;
     loadPlans(filename: string): Plan[];
     setCurrentPlan(plan?: Plan): void;

package/dist/src/explorbot.js

@@ -290,14 +290,22 @@ export class ExplorBot {
                     return null;
                 }
             };
-            const cookieProvider = async () => {
-                const cookies = await this.explorer.withPage((page) => page.context().cookies()).catch(() => []);
-                if (!cookies.length)
-                    return {};
-                return { Cookie: cookies.map((c) => `${c.name}=${c.value}`).join('; ') };
+            const browserHeaderProvider = async () => {
+                const session = await this.explorer
+                    .withPage(async (page) => ({
+                    cookies: await page.context().cookies(baseEndpoint),
+                    csrf: await page.evaluate(() => document.querySelector('meta[name="csrf-token"]')?.getAttribute('content') || '').catch(() => ''),
+                }))
+                    .catch(() => ({ cookies: [], csrf: '' }));
+                const headers = {};
+                if (session.cookies.length)
+                    headers.Cookie = session.cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+                if (session.csrf)
+                    headers['x-csrf-token'] = session.csrf;
+                return headers;
             };
             this.agents.fisherman = this.createAgent(({ ai }) => {
-                return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, cookieProvider, configHeaders, hasApiConfig);
+                return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, browserHeaderProvider, configHeaders, hasApiConfig);
             });
         }
         return this.agents.fisherman;
@@ -383,39 +391,18 @@ export class ExplorBot {
             return urlPart.slice(0, 256 - suffix.length) + suffix;
         return urlPart + featurePart.slice(0, maxFeatureLen) + suffix;
     }
-    resolvePlanPath(filename) {
-        let planPath = filename;
-        if (path.isAbsolute(filename)) {
-            if (!existsSync(planPath) && !filename.endsWith('.md')) {
-                planPath = `${filename}.md`;
-            }
-        }
-        else if (existsSync(filename) || existsSync(`${filename}.md`)) {
-            planPath = existsSync(filename) ? filename : `${filename}.md`;
-        }
-        else {
-            const plansDir = this.getPlansDir();
-            planPath = path.join(plansDir, filename);
-            if (!existsSync(planPath) && !filename.endsWith('.md')) {
-                planPath = path.join(plansDir, `${filename}.md`);
-            }
-        }
-        return planPath;
-    }
     loadPlan(filename) {
-        const planPath = this.resolvePlanPath(filename);
-        if (!existsSync(planPath)) {
-            throw new Error(`Plan file not found: ${planPath}`);
-        }
-        this.setCurrentPlan(Plan.fromMarkdown(planPath));
-        return this.currentPlan;
+        const plan = Plan.loadFromFile(filename, this.getPlansDir());
+        if (!plan)
+            throw new Error(`Plan file not found: ${filename}`);
+        this.setCurrentPlan(plan);
+        return plan;
     }
     loadPlans(filename) {
-        const planPath = this.resolvePlanPath(filename);
-        if (!existsSync(planPath)) {
-            throw new Error(`Plan file not found: ${planPath}`);
-        }
-        return parsePlansFromMarkdown(planPath);
+        const plan = Plan.loadFromFile(filename, this.getPlansDir());
+        if (!plan?.filePath)
+            throw new Error(`Plan file not found: ${filename}`);
+        return parsePlansFromMarkdown(plan.filePath);
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;

package/dist/src/state-manager.d.ts

@@ -42,6 +42,10 @@ export interface WebPageState {
     links?: Link[];
     verifications?: Record<string, boolean>;
     overlay?: Overlay;
+    /** Region name, the persisted scalar form of overlay.name used in experience frontmatter */
+    region?: string;
+    /** Region root selector, the persisted scalar form of overlay.root used in experience frontmatter */
+    root?: string;
 }
 export interface StateTransition {
     /** Previous state (null if this is the first state) */
@@ -91,7 +95,7 @@ export declare class StateManager {
      * Update state from basic data (for navigation events)
      */
     updateStateFromBasic(url: string, title?: string, trigger?: 'manual' | 'navigation' | 'automatic'): WebPageState;
-    hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
+    hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
     /**
      * Generate a basic hash for state comparison
      */

package/dist/src/state-manager.js

@@ -41,7 +41,10 @@ export class StateManager {
      */
     emitStateChange(event) {
         const state = event.toState;
-        tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+        const payload = { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 };
+        if (state.overlay?.present)
+            payload.region = state.overlay.name || state.overlay.type;
+        tag('data').log('state', payload);
         this.stateChangeListeners.forEach((listener) => {
             try {
                 listener(event);
@@ -63,8 +66,8 @@ export class StateManager {
         if (newState.url)
             this.allVisitedUrls.add(normalizeUrl(newState.url));
         const hashChanged = actionResult.hash !== previousHash;
-        const dialogOpened = !hashChanged && this.hasDialogAppeared(previousState, newState);
-        if (hashChanged || dialogOpened) {
+        const regionAppeared = !hashChanged && this.hasRegionAppeared(previousState, newState);
+        if (hashChanged || regionAppeared) {
             const transition = {
                 fromState: previousState,
                 toState: newState,
@@ -74,8 +77,8 @@ export class StateManager {
             };
             this.stateHistory.push(transition);
             this.emitStateChange(transition);
-            if (dialogOpened) {
-                debugLog('State change detected: modal dialog appeared');
+            if (regionAppeared) {
+                debugLog('State change detected: region of interest appeared');
             }
         }
         debugLog(`State updated: ${this.currentState.url} (${this.currentState.hash})`);
@@ -113,10 +116,10 @@ export class StateManager {
         debugLog(`State updated from navigation: ${this.currentState.url} (${this.currentState.hash})`);
         return newState;
     }
-    hasDialogAppeared(previousState, newState) {
+    hasRegionAppeared(previousState, newState) {
         const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
         const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
-        return !prevFocus.detected && newFocus.detected;
+        return !prevFocus.present && newFocus.present;
     }
     /**
      * Generate a basic hash for state comparison

package/dist/src/test-plan.d.ts

@@ -129,6 +129,7 @@ export declare class Plan {
     title: string;
     tests: Test[];
     url?: string;
+    filePath?: string;
     iteration: number;
     parentPlan?: Plan;
     changeListeners: PlanChangeListener[];
@@ -141,10 +142,12 @@ export declare class Plan {
     getAllTests(): Test[];
     listTests(): Test[];
     getPendingTests(): Test[];
+    get startUrl(): string | undefined;
     get isComplete(): boolean;
     get allSuccessful(): boolean;
     get allFailed(): boolean;
     updateStatus(): void;
+    static loadFromFile(file: string, plansDir?: string): Plan | null;
     static fromMarkdown(filePath: string): Plan;
     saveToMarkdown(filePath: string): void;
     static saveMultipleToMarkdown(plans: Plan[], filePath: string): void;