@hera-al/browser-server 1.0.0

package/dist/logger.js

@@ -0,0 +1,125 @@
+import { appendFileSync, statSync, renameSync, unlinkSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let globalLevel = "info";
+export function setLogLevel(level) {
+    globalLevel = level;
+}
+export function getLogLevel() {
+    return globalLevel;
+}
+function fmt(level, tag, msg) {
+    const ts = new Date().toISOString();
+    return `${ts} [${level.toUpperCase().padEnd(5)}] [${tag}] ${msg}`;
+}
+// --- Log file writer with rotation ---
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_FILES = 9; // gmab.1.log through gmab.9.log
+const SIZE_CHECK_INTERVAL = 100; // check size every N writes
+class LogFileWriter {
+    dir;
+    filePath;
+    writeCount = 0;
+    constructor(dir) {
+        this.dir = dir;
+        this.filePath = join(dir, "gmab.log");
+        mkdirSync(dir, { recursive: true });
+    }
+    append(line) {
+        try {
+            appendFileSync(this.filePath, line + "\n");
+            this.writeCount++;
+            if (this.writeCount >= SIZE_CHECK_INTERVAL) {
+                this.writeCount = 0;
+                this.checkRotation();
+            }
+        }
+        catch {
+            // Silently ignore file write errors to avoid infinite loops
+        }
+    }
+    checkRotation() {
+        try {
+            const stats = statSync(this.filePath);
+            if (stats.size >= MAX_FILE_SIZE) {
+                this.rotate();
+            }
+        }
+        catch {
+            // File may not exist yet
+        }
+    }
+    rotate() {
+        // Delete oldest: gmab.9.log
+        const oldest = join(this.dir, `gmab.${MAX_FILES}.log`);
+        try {
+            if (existsSync(oldest))
+                unlinkSync(oldest);
+        }
+        catch { /* noop */ }
+        // Shift: gmab.8.log -> gmab.9.log, ..., gmab.1.log -> gmab.2.log
+        for (let i = MAX_FILES - 1; i >= 1; i--) {
+            const from = join(this.dir, `gmab.${i}.log`);
+            const to = join(this.dir, `gmab.${i + 1}.log`);
+            try {
+                renameSync(from, to);
+            }
+            catch { /* noop */ }
+        }
+        // Current -> gmab.1.log
+        try {
+            renameSync(this.filePath, join(this.dir, "gmab.1.log"));
+        }
+        catch { /* noop */ }
+    }
+}
+let writer = null;
+let logsDir = "";
+/** Initialize file logging. Call once at startup. */
+export function initLogFile(dir) {
+    logsDir = dir;
+    writer = new LogFileWriter(dir);
+}
+/** Returns the logs directory path (empty string if not initialized). */
+export function getLogsDir() {
+    return logsDir;
+}
+export function createLogger(tag) {
+    const shouldLog = (level) => LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[globalLevel];
+    return {
+        debug: (msg, ...args) => {
+            if (shouldLog("debug")) {
+                const line = fmt("debug", tag, msg);
+                console.debug(line, ...args);
+                writer?.append(line);
+            }
+        },
+        info: (msg, ...args) => {
+            if (shouldLog("info")) {
+                const line = fmt("info", tag, msg);
+                console.log(line, ...args);
+                writer?.append(line);
+            }
+        },
+        warn: (msg, ...args) => {
+            if (shouldLog("warn")) {
+                const line = fmt("warn", tag, msg);
+                console.warn(line, ...args);
+                writer?.append(line);
+            }
+        },
+        error: (msg, ...args) => {
+            if (shouldLog("error")) {
+                const line = fmt("error", tag, msg);
+                console.error(line, ...args);
+                writer?.append(line);
+            }
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/playwright/pw-role-snapshot.d.ts

@@ -0,0 +1,32 @@
+export type RoleRef = {
+    role: string;
+    name?: string;
+    /** Index used only when role+name duplicates exist. */
+    nth?: number;
+};
+export type RoleRefMap = Record<string, RoleRef>;
+export type RoleSnapshotStats = {
+    lines: number;
+    chars: number;
+    refs: number;
+    interactive: number;
+};
+export type RoleSnapshotOptions = {
+    /** Only include interactive elements (buttons, links, inputs, etc.). */
+    interactive?: boolean;
+    /** Maximum depth to include (0 = root only). */
+    maxDepth?: number;
+    /** Remove unnamed structural elements and empty branches. */
+    compact?: boolean;
+};
+export declare function getRoleSnapshotStats(snapshot: string, refs: RoleRefMap): RoleSnapshotStats;
+export declare function parseRoleRef(raw: string): string | null;
+export declare function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot: string, options?: RoleSnapshotOptions): {
+    snapshot: string;
+    refs: RoleRefMap;
+};
+export declare function buildRoleSnapshotFromAiSnapshot(aiSnapshot: string, options?: RoleSnapshotOptions): {
+    snapshot: string;
+    refs: RoleRefMap;
+};
+//# sourceMappingURL=pw-role-snapshot.d.ts.map

package/dist/playwright/pw-role-snapshot.js

@@ -0,0 +1,337 @@
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "listbox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "tab",
+    "treeitem",
+]);
+const CONTENT_ROLES = new Set([
+    "heading",
+    "cell",
+    "gridcell",
+    "columnheader",
+    "rowheader",
+    "listitem",
+    "article",
+    "region",
+    "main",
+    "navigation",
+]);
+const STRUCTURAL_ROLES = new Set([
+    "generic",
+    "group",
+    "list",
+    "table",
+    "row",
+    "rowgroup",
+    "grid",
+    "treegrid",
+    "menu",
+    "menubar",
+    "toolbar",
+    "tablist",
+    "tree",
+    "directory",
+    "document",
+    "application",
+    "presentation",
+    "none",
+]);
+export function getRoleSnapshotStats(snapshot, refs) {
+    const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
+    return {
+        lines: snapshot.split("\n").length,
+        chars: snapshot.length,
+        refs: Object.keys(refs).length,
+        interactive,
+    };
+}
+function getIndentLevel(line) {
+    const match = line.match(/^(\s*)/);
+    return match ? Math.floor(match[1].length / 2) : 0;
+}
+function createRoleNameTracker() {
+    const counts = new Map();
+    const refsByKey = new Map();
+    return {
+        counts,
+        refsByKey,
+        getKey(role, name) {
+            return `${role}:${name ?? ""}`;
+        },
+        getNextIndex(role, name) {
+            const key = this.getKey(role, name);
+            const current = counts.get(key) ?? 0;
+            counts.set(key, current + 1);
+            return current;
+        },
+        trackRef(role, name, ref) {
+            const key = this.getKey(role, name);
+            const list = refsByKey.get(key) ?? [];
+            list.push(ref);
+            refsByKey.set(key, list);
+        },
+        getDuplicateKeys() {
+            const out = new Set();
+            for (const [key, refs] of refsByKey) {
+                if (refs.length > 1) {
+                    out.add(key);
+                }
+            }
+            return out;
+        },
+    };
+}
+function removeNthFromNonDuplicates(refs, tracker) {
+    const duplicates = tracker.getDuplicateKeys();
+    for (const [ref, data] of Object.entries(refs)) {
+        const key = tracker.getKey(data.role, data.name);
+        if (!duplicates.has(key)) {
+            delete refs[ref]?.nth;
+        }
+    }
+}
+function compactTree(tree) {
+    const lines = tree.split("\n");
+    const result = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.includes("[ref=")) {
+            result.push(line);
+            continue;
+        }
+        if (line.includes(":") && !line.trimEnd().endsWith(":")) {
+            result.push(line);
+            continue;
+        }
+        const currentIndent = getIndentLevel(line);
+        let hasRelevantChildren = false;
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const childIndent = getIndentLevel(lines[j]);
+            if (childIndent <= currentIndent) {
+                break;
+            }
+            if (lines[j]?.includes("[ref=")) {
+                hasRelevantChildren = true;
+                break;
+            }
+        }
+        if (hasRelevantChildren) {
+            result.push(line);
+        }
+    }
+    return result.join("\n");
+}
+function processLine(line, refs, options, tracker, nextRef) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== undefined && depth > options.maxDepth) {
+        return null;
+    }
+    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+    if (!match) {
+        return options.interactive ? null : line;
+    }
+    const [, prefix, roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+        return options.interactive ? null : line;
+    }
+    const role = roleRaw.toLowerCase();
+    const isInteractive = INTERACTIVE_ROLES.has(role);
+    const isContent = CONTENT_ROLES.has(role);
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.interactive && !isInteractive) {
+        return null;
+    }
+    if (options.compact && isStructural && !name) {
+        return null;
+    }
+    const shouldHaveRef = isInteractive || (isContent && name);
+    if (!shouldHaveRef) {
+        return line;
+    }
+    const ref = nextRef();
+    const nth = tracker.getNextIndex(role, name);
+    tracker.trackRef(role, name, ref);
+    refs[ref] = {
+        role,
+        name,
+        nth,
+    };
+    let enhanced = `${prefix}${roleRaw}`;
+    if (name) {
+        enhanced += ` "${name}"`;
+    }
+    enhanced += ` [ref=${ref}]`;
+    if (nth > 0) {
+        enhanced += ` [nth=${nth}]`;
+    }
+    if (suffix) {
+        enhanced += suffix;
+    }
+    return enhanced;
+}
+export function parseRoleRef(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const normalized = trimmed.startsWith("@")
+        ? trimmed.slice(1)
+        : trimmed.startsWith("ref=")
+            ? trimmed.slice(4)
+            : trimmed;
+    return /^e\d+$/.test(normalized) ? normalized : null;
+}
+export function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
+    const lines = ariaSnapshot.split("\n");
+    const refs = {};
+    const tracker = createRoleNameTracker();
+    let counter = 0;
+    const nextRef = () => {
+        counter += 1;
+        return `e${counter}`;
+    };
+    if (options.interactive) {
+        const result = [];
+        for (const line of lines) {
+            const depth = getIndentLevel(line);
+            if (options.maxDepth !== undefined && depth > options.maxDepth) {
+                continue;
+            }
+            const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+            if (!match) {
+                continue;
+            }
+            const [, , roleRaw, name, suffix] = match;
+            if (roleRaw.startsWith("/")) {
+                continue;
+            }
+            const role = roleRaw.toLowerCase();
+            if (!INTERACTIVE_ROLES.has(role)) {
+                continue;
+            }
+            const ref = nextRef();
+            const nth = tracker.getNextIndex(role, name);
+            tracker.trackRef(role, name, ref);
+            refs[ref] = {
+                role,
+                name,
+                nth,
+            };
+            let enhanced = `- ${roleRaw}`;
+            if (name) {
+                enhanced += ` "${name}"`;
+            }
+            enhanced += ` [ref=${ref}]`;
+            if (nth > 0) {
+                enhanced += ` [nth=${nth}]`;
+            }
+            if (suffix.includes("[")) {
+                enhanced += suffix;
+            }
+            result.push(enhanced);
+        }
+        removeNthFromNonDuplicates(refs, tracker);
+        return {
+            snapshot: result.join("\n") || "(no interactive elements)",
+            refs,
+        };
+    }
+    const result = [];
+    for (const line of lines) {
+        const processed = processLine(line, refs, options, tracker, nextRef);
+        if (processed !== null) {
+            result.push(processed);
+        }
+    }
+    removeNthFromNonDuplicates(refs, tracker);
+    const tree = result.join("\n") || "(empty)";
+    return {
+        snapshot: options.compact ? compactTree(tree) : tree,
+        refs,
+    };
+}
+function parseAiSnapshotRef(suffix) {
+    const match = suffix.match(/\[ref=(e\d+)\]/i);
+    return match ? match[1] : null;
+}
+export function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
+    const lines = String(aiSnapshot ?? "").split("\n");
+    const refs = {};
+    if (options.interactive) {
+        const out = [];
+        for (const line of lines) {
+            const depth = getIndentLevel(line);
+            if (options.maxDepth !== undefined && depth > options.maxDepth) {
+                continue;
+            }
+            const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+            if (!match) {
+                continue;
+            }
+            const [, , roleRaw, name, suffix] = match;
+            if (roleRaw.startsWith("/")) {
+                continue;
+            }
+            const role = roleRaw.toLowerCase();
+            if (!INTERACTIVE_ROLES.has(role)) {
+                continue;
+            }
+            const ref = parseAiSnapshotRef(suffix);
+            if (!ref) {
+                continue;
+            }
+            refs[ref] = { role, ...(name ? { name } : {}) };
+            out.push(`- ${roleRaw}${name ? ` "${name}"` : ""}${suffix}`);
+        }
+        return {
+            snapshot: out.join("\n") || "(no interactive elements)",
+            refs,
+        };
+    }
+    const out = [];
+    for (const line of lines) {
+        const depth = getIndentLevel(line);
+        if (options.maxDepth !== undefined && depth > options.maxDepth) {
+            continue;
+        }
+        const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+        if (!match) {
+            out.push(line);
+            continue;
+        }
+        const [, , roleRaw, name, suffix] = match;
+        if (roleRaw.startsWith("/")) {
+            out.push(line);
+            continue;
+        }
+        const role = roleRaw.toLowerCase();
+        const isStructural = STRUCTURAL_ROLES.has(role);
+        if (options.compact && isStructural && !name) {
+            continue;
+        }
+        const ref = parseAiSnapshotRef(suffix);
+        if (ref) {
+            refs[ref] = { role, ...(name ? { name } : {}) };
+        }
+        out.push(line);
+    }
+    const tree = out.join("\n") || "(empty)";
+    return {
+        snapshot: options.compact ? compactTree(tree) : tree,
+        refs,
+    };
+}
+//# sourceMappingURL=pw-role-snapshot.js.map

package/dist/playwright/pw-session.d.ts

@@ -0,0 +1,119 @@
+import type { BrowserContext, Page, Request } from "playwright-core";
+export type BrowserConsoleMessage = {
+    type: string;
+    text: string;
+    timestamp: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+};
+export type BrowserPageError = {
+    message: string;
+    name?: string;
+    stack?: string;
+    timestamp: string;
+};
+export type BrowserNetworkRequest = {
+    id: string;
+    timestamp: string;
+    method: string;
+    url: string;
+    resourceType?: string;
+    status?: number;
+    ok?: boolean;
+    failureText?: string;
+};
+type SnapshotForAIResult = {
+    full: string;
+    incremental?: string;
+};
+type SnapshotForAIOptions = {
+    timeout?: number;
+    track?: string;
+};
+export type WithSnapshotForAI = {
+    _snapshotForAI?: (options?: SnapshotForAIOptions) => Promise<SnapshotForAIResult>;
+};
+type PageState = {
+    console: BrowserConsoleMessage[];
+    errors: BrowserPageError[];
+    requests: BrowserNetworkRequest[];
+    requestIds: WeakMap<Request, string>;
+    nextRequestId: number;
+    armIdUpload: number;
+    armIdDialog: number;
+    armIdDownload: number;
+    roleRefs?: Record<string, {
+        role: string;
+        name?: string;
+        nth?: number;
+    }>;
+    roleRefsMode?: "role" | "aria";
+    roleRefsFrameSelector?: string;
+};
+type RoleRefs = NonNullable<PageState["roleRefs"]>;
+type ContextState = {
+    traceActive: boolean;
+};
+export declare function rememberRoleRefsForTarget(opts: {
+    cdpUrl: string;
+    targetId: string;
+    refs: RoleRefs;
+    frameSelector?: string;
+    mode?: NonNullable<PageState["roleRefsMode"]>;
+}): void;
+export declare function storeRoleRefsForTarget(opts: {
+    page: Page;
+    cdpUrl: string;
+    targetId?: string;
+    refs: RoleRefs;
+    frameSelector?: string;
+    mode: NonNullable<PageState["roleRefsMode"]>;
+}): void;
+export declare function restoreRoleRefsForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    page: Page;
+}): void;
+export declare function ensurePageState(page: Page): PageState;
+export declare function ensureContextState(context: BrowserContext): ContextState;
+export declare function getPageForTargetId(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<Page>;
+export declare function refLocator(page: Page, ref: string): import("playwright-core").Locator;
+export declare function closePlaywrightBrowserConnection(): Promise<void>;
+export declare function forceDisconnectPlaywrightForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    reason?: string;
+}): Promise<void>;
+export declare function listPagesViaPlaywright(opts: {
+    cdpUrl: string;
+}): Promise<Array<{
+    targetId: string;
+    title: string;
+    url: string;
+    type: string;
+}>>;
+export declare function createPageViaPlaywright(opts: {
+    cdpUrl: string;
+    url: string;
+}): Promise<{
+    targetId: string;
+    title: string;
+    url: string;
+    type: string;
+}>;
+export declare function closePageByTargetIdViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<void>;
+export declare function focusPageByTargetIdViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=pw-session.d.ts.map