explorbot 0.4.0 → 0.4.2

package/dist/src/remote.js

@@ -26,15 +26,6 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
-    registerOption(program) {
-        program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
-        program.hook('preAction', (_thisCommand, actionCommand) => {
-            const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
-            if (!url)
-                return;
-            this.attach(String(url), this.commandPath(actionCommand));
-        });
-    }
     attach(url, command) {
         if (this.url)
             return;
@@ -222,14 +213,5 @@ export class Remote {
             return failure.message;
         return undefined;
     }
-    commandPath(command) {
-        const parts = [];
-        let node = command;
-        while (node) {
-            parts.unshift(node.name());
-            node = node.parent;
-        }
-        return parts.slice(1).join(' ') || parts.join(' ');
-    }
 }
 export const remote = new Remote();

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

@@ -1,7 +1,7 @@
 import { ActionResult, type FocusedElement } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
-import { Overlay } from './utils/overlay.js';
+import type { Region } from './utils/region.js';
 export interface Link {
     title: string;
     url: string;
@@ -41,7 +41,7 @@ export interface WebPageState {
     focusedElement?: FocusedElement | null;
     links?: Link[];
     verifications?: Record<string, boolean>;
-    overlay?: Overlay;
+    overlay?: Region;
     /** 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 */
@@ -95,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;
-    hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
+    regionOpened(previousState: WebPageState | null, newState: WebPageState): boolean;
     /**
      * Generate a basic hash for state comparison
      */

package/dist/src/state-manager.js

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

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

@@ -147,6 +147,7 @@ export declare class Plan {
     get allSuccessful(): boolean;
     get allFailed(): boolean;
     updateStatus(): void;
+    static resolveFile(file: string, plansDir?: string): string | null;
     static loadFromFile(file: string, plansDir?: string): Plan | null;
     static fromMarkdown(filePath: string): Plan;
     saveToMarkdown(filePath: string): void;

package/dist/src/test-plan.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { listSites } from "./global-config.js";
+import { listSitePlanDirs } from "./global-config.js";
 import { tag } from "./utils/logger.js";
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from "./utils/test-plan-markdown.js";
 import { uniqSessionName } from "./utils/unique-names.js";
@@ -323,7 +323,6 @@ export class Test extends Task {
             .sort((a, b) => a.timestamp - b.timestamp);
     }
 }
-const SITE_PLANS_DIR = ['output', 'plans'];
 export class Plan {
     title;
     tests = [];
@@ -398,7 +397,7 @@ export class Plan {
         return this.tests.length > 0 && this.tests.every((test) => test.hasFailed);
     }
     updateStatus() { }
-    static loadFromFile(file, plansDir) {
+    static resolveFile(file, plansDir) {
         const names = [file];
         if (!file.endsWith('.md'))
             names.push(`${file}.md`);
@@ -406,17 +405,22 @@ export class Plan {
         if (plansDir)
             dirs.push(plansDir);
         if (!plansDir)
-            dirs.push(...listSites().map((site) => path.join(site.dir, ...SITE_PLANS_DIR)));
+            dirs.push(...listSitePlanDirs());
         for (const dir of dirs) {
             const filePath = names.map((name) => path.resolve(dir, name)).find(existsSync);
-            if (!filePath)
-                continue;
-            const loaded = parsePlanFromMarkdown(filePath);
-            loaded.filePath = filePath;
-            return loaded;
+            if (filePath)
+                return filePath;
         }
         return null;
     }
+    static loadFromFile(file, plansDir) {
+        const filePath = Plan.resolveFile(file, plansDir);
+        if (!filePath)
+            return null;
+        const loaded = parsePlanFromMarkdown(filePath);
+        loaded.filePath = filePath;
+        return loaded;
+    }
     static fromMarkdown(filePath) {
         return parsePlanFromMarkdown(filePath);
     }

package/dist/src/utils/aria.d.ts

@@ -1,5 +1,4 @@
 export interface FocusAreaResult {
-    detected: boolean;
     type: 'modal' | null;
     name: string | null;
 }
@@ -8,6 +7,7 @@ export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?:
 export declare const diffAriaSnapshots: (previous: string | null, current: string | null) => AriaDiff;
 export declare const detectFocusArea: (snapshot: string | null) => FocusAreaResult;
 export declare const collectInteractiveNodes: (snapshot: string | null) => Array<Record<string, unknown>>;
+export declare const ariaTemplateSignature: (snapshot: string | null) => Set<string>;
 export declare function parseAriaLocator(ariaStr: string): {
     role: string;
     text: string;

package/dist/src/utils/aria.js

@@ -473,7 +473,7 @@ const findDialogOrModal = (nodes) => {
     let topmost = null;
     for (const node of nodes) {
         if (node.role === 'dialog' || node.role === 'alertdialog' || node.attributes.modal === true || node.attributes.modal === 'true') {
-            topmost = { detected: true, type: 'modal', name: node.name || null };
+            topmost = { type: 'modal', name: node.name || null };
         }
         const child = findDialogOrModal(node.children);
         if (child)
@@ -517,7 +517,7 @@ export const detectFocusArea = (snapshot) => {
     let tree = parseSnapshot(snapshot);
     tree = unwrapIgnored(tree);
     tree = dropEmpty(tree, { keepNamed: true });
-    return findDialogOrModal(tree) ?? { detected: false, type: null, name: null };
+    return findDialogOrModal(tree) ?? { type: null, name: null };
 };
 export const collectInteractiveNodes = (snapshot) => {
     let tree = parseSnapshot(snapshot);
@@ -526,6 +526,27 @@ export const collectInteractiveNodes = (snapshot) => {
     tree = dropEmpty(tree);
     return flatten(tree).map((e) => e.entry);
 };
+const TEMPLATE_CHROME_ROLES = new Set(['banner', 'navigation', 'contentinfo', 'complementary']);
+const TEMPLATE_PROSE_ROLE = 'text';
+const dropChrome = (nodes) => nodes.flatMap((node) => {
+    if (TEMPLATE_CHROME_ROLES.has(node.role))
+        return [];
+    return [{ ...node, children: dropChrome(node.children) }];
+});
+const collectRolePaths = (nodes, prefix, into) => {
+    for (const node of nodes) {
+        if (node.role === TEMPLATE_PROSE_ROLE)
+            continue;
+        const path = prefix ? `${prefix}/${node.role}` : node.role;
+        into.add(path);
+        collectRolePaths(node.children, path, into);
+    }
+};
+export const ariaTemplateSignature = (snapshot) => {
+    const paths = new Set();
+    collectRolePaths(dropChrome(parseSnapshot(snapshot)), '', paths);
+    return paths;
+};
 // ─────────────────────────────────────────────────────────────────
 // Standalone helpers (regex on raw strings — not part of the pipeline)
 // ─────────────────────────────────────────────────────────────────

package/dist/src/utils/cli-section.d.ts

@@ -0,0 +1 @@
+export declare function renderSection(title: string, entries: [string, string][], indent?: number): string[];

package/dist/src/utils/cli-section.js

@@ -0,0 +1,12 @@
+import chalk from 'chalk';
+export function renderSection(title, entries, indent = 0) {
+    if (!entries.length)
+        return [];
+    const pad = ' '.repeat(indent);
+    const width = Math.max(...entries.map(([label]) => label.length));
+    const lines = [`${pad}${chalk.bold(title)}`];
+    for (const [label, value] of entries)
+        lines.push(`${pad}  ${chalk.dim(label.padEnd(width))}  ${value}`);
+    lines.push('');
+    return lines;
+}

package/dist/src/utils/html-diff.d.ts

@@ -6,6 +6,7 @@ export interface HtmlDiffPart {
     added: string[];
     removed: string[];
     appearedSelector?: string;
+    containerWasEmpty?: boolean;
 }
 export interface HtmlDiffResult {
     parts: HtmlDiffPart[];

package/dist/src/utils/html-diff.js

@@ -1,5 +1,5 @@
 import { parse, serialize } from 'parse5';
-import { TAILWIND_CLASS_PATTERNS, TRASH_HTML_CLASSES, minifyHtml } from "./html.js";
+import { isTailwindClass, isTrashClass, minifyHtml } from "./html.js";
 import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 const SHELL_RATIO = 0.8;
@@ -364,14 +364,13 @@ const directTextDiffer = (current, previous) => {
     }
     return false;
 };
-const trashHtmlClasses = TRASH_HTML_CLASSES;
 function filterContainerClasses(classes) {
     return classes
         .filter((cls) => !/\d/.test(cls))
         .filter((cls) => !isGenericClass(cls))
-        .filter((cls) => !trashHtmlClasses.test(cls))
+        .filter((cls) => !isTrashClass(cls))
         .filter((cls) => !/(:|__)/.test(cls))
-        .filter((cls) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(cls)));
+        .filter((cls) => !isTailwindClass(cls));
 }
 function buildContainerSelector(element, allElements) {
     const tag = element.tagName?.toLowerCase();
@@ -529,7 +528,8 @@ async function buildDiffParts(originalMap, modifiedMap, pageSize) {
         appearedPaths.sort((a, b) => sizeOf(b) - sizeOf(a));
         const addedLines = appearedPaths.map((p) => `ELEMENT:${p}`);
         const removedLines = [];
-        const part = { container: selector, subtree, rawSize: serialized.length, added: addedLines, removed: removedLines };
+        const heldContentBefore = (originalMap.get(containerPath)?.childNodes ?? []).some((child) => 'tagName' in child && !!child.tagName);
+        const part = { container: selector, subtree, rawSize: serialized.length, added: addedLines, removed: removedLines, containerWasEmpty: !heldContentBefore };
         const appearedPath = appearedPaths[0];
         if (appearedPath) {
             const appearedElement = modifiedMap.get(appearedPath);

package/dist/src/utils/html.d.ts

@@ -76,6 +76,8 @@ export declare function extractComponentScopeHtml(eidx: string, config: Componen
 export declare function getComponentScopeHtmlExtractorSource(): string;
 export declare const TRASH_HTML_CLASSES: RegExp;
 export declare const TAILWIND_CLASS_PATTERNS: RegExp[];
+export declare const isTailwindClass: (cls: string) => boolean;
+export declare const isTrashClass: (cls: string) => boolean;
 export declare function sanitizeHtmlDocument(html: string, htmlConfig?: HtmlConfig): parse5TreeAdapter.Document;
 export declare function sanitizeHtmlString(html: string, htmlConfig?: HtmlConfig): string;
 /**

package/dist/src/utils/html.js

@@ -509,6 +509,8 @@ export const TAILWIND_CLASS_PATTERNS = [
     /^aspect-/i,
     /^prose$/i,
 ];
+export const isTailwindClass = (cls) => TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(cls));
+export const isTrashClass = (cls) => TRASH_HTML_CLASSES.test(cls);
 const NON_SEMANTIC_TAGS = new Set([
     'style',
     'script',
@@ -688,7 +690,6 @@ export function sanitizeHtmlString(html, htmlConfig) {
  */
 export function htmlMinimalUISnapshot(html, htmlConfig) {
     const document = parse(html);
-    const trashHtmlClasses = TRASH_HTML_CLASSES;
     const removeElements = ['path', 'script'];
     function isFilteredOut(node) {
         // Check exclude selectors first
@@ -790,9 +791,9 @@ export function htmlMinimalUISnapshot(html, htmlConfig) {
                     attr.value = value
                         .split(' ')
                         .filter((className) => !/\d/.test(className))
-                        .filter((className) => !className.match(trashHtmlClasses))
+                        .filter((className) => !isTrashClass(className))
                         .filter((className) => !className.match(/(:|__)/))
-                        .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))
+                        .filter((className) => !isTailwindClass(className))
                         .join(' ');
                     if (attr.value === '')
                         return false;
@@ -1312,7 +1313,7 @@ function cleanElement(element) {
                 .filter(Boolean)
                 .filter((className) => !/\d/.test(className))
                 .filter((className) => !className.includes(':'))
-                .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))
+                .filter((className) => !isTailwindClass(className))
                 .join(' ');
             if (!attr.value) {
                 element.attrs = element.attrs.filter((a) => a.name !== 'class');

package/dist/src/utils/overlay.d.ts

@@ -1,31 +1,13 @@
-import type { HtmlDiffPart } from './html-diff.js';
-export type OverlayType = 'modal' | 'region';
-export type OverlayData = {
-    type?: OverlayType | null;
-    name?: string | null;
-    root?: string | null;
-    html?: string | null;
-    xpath?: string | null;
-    parent?: OverlayData | null;
-};
-export declare class Overlay {
-    readonly type: OverlayType | null;
-    readonly name: string | null;
-    readonly root: string | null;
-    readonly html: string | null;
-    readonly xpath: string | null;
-    readonly parent: OverlayData | null;
-    constructor(data?: OverlayData);
-    get detected(): boolean;
-    get present(): boolean;
-    describe(): string;
-    withGeometry(geometry: Overlay): Overlay;
-    withParent(parent: Overlay): Overlay;
-    static fromAria(snapshot: string | null): Overlay;
+import { Region, type RegionData, type RegionDiff } from './region.js';
+export declare class Overlay extends Region {
+    constructor(data?: RegionData);
+    get isModal(): boolean;
+    withGeometry(geometry: Region): Overlay;
+    static fromAria(snapshot: string | null): Region;
     static resolve(data: {
-        overlay?: OverlayData | null;
+        overlay?: RegionData | null;
         ariaSnapshot?: string | null;
-    }): Overlay;
+    }): Region;
 }
 export declare class OverlayPage {
     page: {
@@ -34,36 +16,18 @@ export declare class OverlayPage {
     constructor(page: {
         evaluate(fn: any, arg: any): Promise<any>;
     } | null);
-    detectRegion(diff: RegionDiff): Promise<Overlay | null>;
-    isStillOpen(overlay: Overlay): Promise<boolean>;
-    appearedSubRoots(diff: RegionDiff): AppearedSubRoot[];
-    probe(xpath: string): Promise<RegionProbe | null>;
-    toOverlay(subRoot: AppearedSubRoot, probe: RegionProbe | null, previousHtml: string): Overlay;
-    nameFrom(html: string, previousHtml: string): string | null;
-    freshHeading(html: string, previousHtml: string): string | null;
-    headingsOf(html: string): string[];
+    detectRegion(diff: RegionDiff): Promise<Region | null>;
+    isStillOpen(region: Region): Promise<boolean>;
+    measure(xpath: string): Promise<RegionLayout | null>;
 }
-export interface RegionDiff {
-    parts: HtmlDiffPart[];
-    pageSize: number;
-    similarity: number;
-    sameUrl: boolean;
-    previousHtml: string;
-}
-interface AppearedSubRoot {
-    container: string;
-    elementXPath: string;
-    subtree: string;
-    size: number;
-    rawSize: number;
-    appearedSelector?: string;
-    fresh: boolean;
-}
-interface RegionProbe {
-    found: boolean;
-    onScreen: boolean;
-    floating: boolean;
+interface RegionLayout {
+    rendered: boolean;
+    inViewport: boolean;
+    outOfFlow: boolean;
     centerBelongs: boolean;
-    coveredByFloating: boolean;
+    coveredOutOfFlow: boolean;
+    holdsViewportCenter: boolean;
+    viewportCoverage: number;
+    controls: number;
 }
 export {};