@monoes/monobrowse 1.0.11 → 1.0.13

package/src/__tests__/snapshot.test.ts

@@ -4,9 +4,14 @@
  * resolves against. That transform is pure — the only browser interaction is
  * the AX-tree fetch, which a stub answers from a literal node array.
  */
-import { describe, it, expect, vi } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { CdpClient } from '../browser/cdp.js';
-import { captureSnapshot, resolveRef, getObjectIdForRef, getElementBox } from '../browser/snapshot.js';
+import {
+  captureSnapshot,
+  getElementBox,
+  getObjectIdForRef,
+  resolveRef,
+} from '../browser/snapshot.js';
 import type { ElementRef } from '../browser/types.js';
 
 interface AXProp {
@@ -29,7 +34,7 @@ interface AXNode {
 /** Client that serves a fixed AX tree plus location.href / document.title. */
 function axClient(
   nodes: AXNode[],
-  extra: { url?: string; title?: string; partial?: AXNode[]; selectorNodeId?: number } = {}
+  extra: { url?: string; title?: string; partial?: AXNode[]; selectorNodeId?: number } = {},
 ): { client: CdpClient; calls: string[] } {
   const calls: string[] = [];
   const client = {
@@ -49,8 +54,8 @@ function axClient(
             result: {
               value:
                 (params as { expression: string }).expression === 'location.href'
-                  ? extra.url ?? 'https://x.test/'
-                  : extra.title ?? 'Test Page',
+                  ? (extra.url ?? 'https://x.test/')
+                  : (extra.title ?? 'Test Page'),
             },
           };
         default:
@@ -80,10 +85,14 @@ describe('captureSnapshot — tree shape', () => {
     expect(snap.text).toBe(
       'RootWebArea "Test Page" [ref=e1]\n' +
         '  form "Login" [ref=e2]\n' +
-        '    button "Submit" [ref=e3]'
+        '    button "Submit" [ref=e3]',
     );
     expect([...snap.refs.keys()]).toEqual(['e1', 'e2', 'e3']);
-    expect(snap.refs.get('e3')).toMatchObject({ role: 'button', name: 'Submit', backendDOMNodeId: 30 });
+    expect(snap.refs.get('e3')).toMatchObject({
+      role: 'button',
+      name: 'Submit',
+      backendDOMNodeId: 30,
+    });
     expect(snap).toMatchObject({ url: 'https://x.test/', title: 'Test Page' });
   });
 
@@ -157,13 +166,13 @@ describe('captureSnapshot — options', () => {
   });
 
   it('compact drops indentation and descriptions', async () => {
-    const { client } = axClient([
-      button(1, 'Go', { description: { value: 'primary action' } }),
-    ]);
+    const { client } = axClient([button(1, 'Go', { description: { value: 'primary action' } })]);
     const spaced = await captureSnapshot(client, 'S1');
     expect(spaced.text).toBe('button "Go" (primary action) [ref=e1]');
 
-    const { client: c2 } = axClient([button(1, 'Go', { description: { value: 'primary action' } })]);
+    const { client: c2 } = axClient([
+      button(1, 'Go', { description: { value: 'primary action' } }),
+    ]);
     const compact = await captureSnapshot(c2, 'S1', { compact: true });
     expect(compact.text).toBe('button "Go" [ref=e1]');
     // The description is still available on the ref even when not printed.
@@ -198,7 +207,13 @@ describe('captureSnapshot — options', () => {
 describe('captureSnapshot — property extraction and rendering', () => {
   async function snapOf(props: AXProp[], over: Partial<AXNode> = {}) {
     const { client } = axClient([
-      { nodeId: 1, role: { value: 'textbox' }, name: { value: 'Email' }, properties: props, ...over },
+      {
+        nodeId: 1,
+        role: { value: 'textbox' },
+        name: { value: 'Email' },
+        properties: props,
+        ...over,
+      },
     ]);
     return captureSnapshot(client, 'S1');
   }
@@ -210,14 +225,18 @@ describe('captureSnapshot — property extraction and rendering', () => {
       { name: 'required', value: { value: true } },
     ]);
     expect(snap.text).toBe(
-      'textbox "Email" [ref=e1, value="a@b.c", placeholder="you@example.com", required]'
+      'textbox "Email" [ref=e1, value="a@b.c", placeholder="you@example.com", required]',
     );
     expect(snap.refs.get('e1')).toMatchObject({ value: 'a@b.c', placeholder: 'you@example.com' });
   });
 
   it('renders disabled as a bare flag only when true', async () => {
-    expect((await snapOf([{ name: 'disabled', value: { value: true } }])).text).toContain(', disabled]');
-    expect((await snapOf([{ name: 'disabled', value: { value: false } }])).text).not.toContain('disabled');
+    expect((await snapOf([{ name: 'disabled', value: { value: true } }])).text).toContain(
+      ', disabled]',
+    );
+    expect((await snapOf([{ name: 'disabled', value: { value: false } }])).text).not.toContain(
+      'disabled',
+    );
   });
 
   it('accepts checked/expanded as either the boolean or the string "true"', async () => {
@@ -280,12 +299,14 @@ describe('resolveRef', () => {
     const refs = new Map<string, ElementRef>([
       ['e1', { ref: 'e1', role: 'button', name: 'Go', nodeId: 1 }],
     ]);
-    await expect(resolveRef({} as CdpClient, 'S1', refs, 'e1')).resolves.toMatchObject({ ref: 'e1' });
+    await expect(resolveRef({} as CdpClient, 'S1', refs, 'e1')).resolves.toMatchObject({
+      ref: 'e1',
+    });
   });
 
   it('throws a snapshot-first hint when the ref is unknown', async () => {
     await expect(resolveRef({} as CdpClient, 'S1', new Map(), 'e9')).rejects.toThrow(
-      'Element ref @e9 not found. Run snapshot first.'
+      'Element ref @e9 not found. Run snapshot first.',
     );
   });
 });
@@ -295,7 +316,7 @@ describe('getObjectIdForRef', () => {
     const send = vi.fn();
     const client = { send } as unknown as CdpClient;
     await expect(
-      getObjectIdForRef(client, 'S1', { ref: 'e1', role: 'button', name: '', nodeId: 1 })
+      getObjectIdForRef(client, 'S1', { ref: 'e1', role: 'button', name: '', nodeId: 1 }),
     ).resolves.toBeNull();
     expect(send).not.toHaveBeenCalled();
   });
@@ -304,7 +325,13 @@ describe('getObjectIdForRef', () => {
     const send = vi.fn(async () => ({ object: { objectId: 'OBJ' } }));
     const client = { send } as unknown as CdpClient;
     await expect(
-      getObjectIdForRef(client, 'S1', { ref: 'e1', role: 'button', name: '', nodeId: 1, backendDOMNodeId: 77 })
+      getObjectIdForRef(client, 'S1', {
+        ref: 'e1',
+        role: 'button',
+        name: '',
+        nodeId: 1,
+        backendDOMNodeId: 77,
+      }),
     ).resolves.toBe('OBJ');
     expect(send.mock.calls[0]).toEqual(['DOM.resolveNode', { backendNodeId: 77 }, 'S1']);
   });
@@ -312,7 +339,13 @@ describe('getObjectIdForRef', () => {
   it('returns null when the node no longer resolves to an object', async () => {
     const client = { send: vi.fn(async () => ({ object: {} })) } as unknown as CdpClient;
     await expect(
-      getObjectIdForRef(client, 'S1', { ref: 'e1', role: 'button', name: '', nodeId: 1, backendDOMNodeId: 77 })
+      getObjectIdForRef(client, 'S1', {
+        ref: 'e1',
+        role: 'button',
+        name: '',
+        nodeId: 1,
+        backendDOMNodeId: 77,
+      }),
     ).resolves.toBeNull();
   });
 });
@@ -325,7 +358,13 @@ describe('getElementBox', () => {
       })),
     } as unknown as CdpClient;
     await expect(
-      getElementBox(client, 'S1', { ref: 'e1', role: 'button', name: '', nodeId: 1, backendDOMNodeId: 5 })
+      getElementBox(client, 'S1', {
+        ref: 'e1',
+        role: 'button',
+        name: '',
+        nodeId: 1,
+        backendDOMNodeId: 5,
+      }),
     ).resolves.toEqual({ x: 60, y: 40, width: 100, height: 40 });
   });
 });

package/src/__tests__/storage-eval.test.ts

@@ -5,24 +5,27 @@
  * evaluateJs's error/timeout contract is what this file pins down.
  * Fake client throughout — no browser.
  */
-import { describe, it, expect, vi } from 'vitest';
-import type { CdpClient } from '../browser/cdp.js';
+import { describe, expect, it, vi } from 'vitest';
 import { evaluateJs } from '../browser/actions.js';
+import type { CdpClient } from '../browser/cdp.js';
 import {
-  getLocalStorageKey,
-  setLocalStorageKey,
-  removeLocalStorageKey,
   clearLocalStorage,
+  clearSessionStorage,
   getAllLocalStorage,
+  getAllSessionStorage,
+  getLocalStorageKey,
   getSessionStorageKey,
-  setSessionStorageKey,
+  removeLocalStorageKey,
   removeSessionStorageKey,
-  clearSessionStorage,
-  getAllSessionStorage,
+  setLocalStorageKey,
+  setSessionStorageKey,
 } from '../browser/storage.js';
 
 /** Client stub returning a fixed Runtime.evaluate value, recording expressions. */
-function stubClient(value?: unknown, exceptionDetails?: unknown): {
+function stubClient(
+  value?: unknown,
+  exceptionDetails?: unknown,
+): {
   client: CdpClient;
   exprs: string[];
   sids: Array<string | undefined>;
@@ -33,7 +36,9 @@ function stubClient(value?: unknown, exceptionDetails?: unknown): {
     send: vi.fn(async (_m: string, params: { expression: string }, sid?: string) => {
       exprs.push(params.expression);
       sids.push(sid);
-      return exceptionDetails ? { result: {}, exceptionDetails } : { result: { value, type: 'string' } };
+      return exceptionDetails
+        ? { result: {}, exceptionDetails }
+        : { result: { value, type: 'string' } };
     }),
   } as unknown as CdpClient;
   return { client, exprs, sids };
@@ -58,19 +63,21 @@ describe('evaluateJs', () => {
       exception: { description: 'ReferenceError: foo is not defined' },
     });
     await expect(evaluateJs(client, 'S1', 'foo')).rejects.toThrow(
-      'JS evaluation error: ReferenceError: foo is not defined'
+      'JS evaluation error: ReferenceError: foo is not defined',
     );
   });
 
   it('falls back to exceptionDetails.text when there is no description', async () => {
     const { client } = stubClient(undefined, { text: 'Uncaught SyntaxError' });
     await expect(evaluateJs(client, 'S1', '{{')).rejects.toThrow(
-      'JS evaluation error: Uncaught SyntaxError'
+      'JS evaluation error: Uncaught SyntaxError',
     );
   });
 
   it('returns undefined for an expression with no value', async () => {
-    const client = { send: vi.fn(async () => ({ result: { type: 'undefined' } })) } as unknown as CdpClient;
+    const client = {
+      send: vi.fn(async () => ({ result: { type: 'undefined' } })),
+    } as unknown as CdpClient;
     await expect(evaluateJs(client, 'S1', 'void 0')).resolves.toBeUndefined();
   });
 
@@ -79,14 +86,19 @@ describe('evaluateJs', () => {
     // without the race; a 20ms budget proves the timer is armed.
     const client = { send: vi.fn(() => new Promise(() => {})) } as unknown as CdpClient;
     await expect(evaluateJs(client, 'S1', 'new Promise(() => {})', 20)).rejects.toThrow(
-      'JS evaluation timed out after 20ms'
+      'JS evaluation timed out after 20ms',
     );
   });
 
   it('waits indefinitely when the timeout is disabled with 0', async () => {
     let resolveSend: (v: unknown) => void = () => {};
     const client = {
-      send: vi.fn(() => new Promise((r) => { resolveSend = r; })),
+      send: vi.fn(
+        () =>
+          new Promise((r) => {
+            resolveSend = r;
+          }),
+      ),
     } as unknown as CdpClient;
     const p = evaluateJs(client, 'S1', 'slow()', 0);
     resolveSend({ result: { value: 'done', type: 'string' } });
@@ -165,7 +177,9 @@ describe('sessionStorage helpers mirror the localStorage ones', () => {
   });
 
   it('getAll parses, and degrades to {} on garbage', async () => {
-    await expect(getAllSessionStorage(stubClient('{"s":"1"}').client, 'S1')).resolves.toEqual({ s: '1' });
+    await expect(getAllSessionStorage(stubClient('{"s":"1"}').client, 'S1')).resolves.toEqual({
+      s: '1',
+    });
     await expect(getAllSessionStorage(stubClient('<html>').client, 'S1')).resolves.toEqual({});
   });
 });

package/src/__tests__/tabs.test.ts

@@ -2,9 +2,9 @@
  * tabs.ts — target filtering and the CDP command sequences for
  * close/activate/frame-switch. Fake fetch + fake client; no browser.
  */
-import { describe, it, expect, afterEach, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { CdpClient } from '../browser/cdp.js';
-import { listTabs, newTab, closeTab, activateTab, switchToFrame } from '../browser/tabs.js';
+import { activateTab, closeTab, listTabs, newTab, switchToFrame } from '../browser/tabs.js';
 
 const realFetch = globalThis.fetch;
 afterEach(() => {
@@ -55,7 +55,7 @@ describe('listTabs', () => {
 
   it('propagates a failed /json/list', async () => {
     globalThis.fetch = vi.fn(() =>
-      Promise.resolve(new Response('', { status: 502, statusText: 'Bad Gateway' }))
+      Promise.resolve(new Response('', { status: 502, statusText: 'Bad Gateway' })),
     ) as unknown as typeof fetch;
     await expect(listTabs(9222)).rejects.toThrow('Failed to fetch targets: Bad Gateway');
   });
@@ -66,7 +66,7 @@ describe('newTab', () => {
     const fn = stubFetch({ id: 'T1', type: 'page' });
     await newTab(9222);
     expect(fn.mock.calls[0]![0]).toBe(
-      'http://127.0.0.1:9222/json/new?' + encodeURIComponent('about:blank')
+      `http://127.0.0.1:9222/json/new?${encodeURIComponent('about:blank')}`,
     );
   });
 
@@ -81,7 +81,9 @@ describe('closeTab', () => {
   it('sends Target.closeTarget for the given targetId', async () => {
     const { client, calls } = stubClient();
     await closeTab(client, 'S1', 'T9');
-    expect(calls).toEqual([{ method: 'Target.closeTarget', params: { targetId: 'T9' }, sid: undefined }]);
+    expect(calls).toEqual([
+      { method: 'Target.closeTarget', params: { targetId: 'T9' }, sid: undefined },
+    ]);
   });
 });
 
@@ -129,7 +131,10 @@ describe('switchToFrame', () => {
       'Runtime.evaluate': { result: { result: { value: null } } },
       'Page.getFrameTree': { frameTree: {} },
     });
-    await expect(switchToFrame(client, 'S1', 'div.not-a-frame')).resolves.toEqual({ url: null, sessionId: null });
+    await expect(switchToFrame(client, 'S1', 'div.not-a-frame')).resolves.toEqual({
+      url: null,
+      sessionId: null,
+    });
     // The selector is embedded as a JSON string literal, never interpolated raw.
     const expr = (calls[0]!.params as { expression: string }).expression;
     expect(expr).toContain('document.querySelector("div.not-a-frame")');
@@ -149,9 +154,14 @@ describe('switchToFrame', () => {
     const { client, calls } = stubClient({
       'Runtime.evaluate': { result: { result: { value: 'https://f.test/frame' } } },
       'Page.getFrameTree': frameTreeWith('https://f.test/frame'),
-      'Target.getTargets': { targetInfos: [{ targetId: 'T1', type: 'page', url: 'https://x.test' }] },
+      'Target.getTargets': {
+        targetInfos: [{ targetId: 'T1', type: 'page', url: 'https://x.test' }],
+      },
+    });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({
+      url: 'https://f.test/frame',
+      sessionId: null,
     });
-    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: null });
     expect(calls.map((c) => c.method)).not.toContain('Target.attachToTarget');
   });
 
@@ -167,7 +177,10 @@ describe('switchToFrame', () => {
       },
       'Target.attachToTarget': { sessionId: 'S-FRAME' },
     });
-    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: 'S-FRAME' });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({
+      url: 'https://f.test/frame',
+      sessionId: 'S-FRAME',
+    });
     const attach = calls.find((c) => c.method === 'Target.attachToTarget');
     expect(attach!.params).toEqual({ targetId: 'T-OOPIF', flatten: true });
   });
@@ -177,7 +190,10 @@ describe('switchToFrame', () => {
       'Runtime.evaluate': { result: { result: { value: 'https://f.test/frame' } } },
       'Page.getFrameTree': frameTreeWith('https://other.test/elsewhere'),
     });
-    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: null });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({
+      url: 'https://f.test/frame',
+      sessionId: null,
+    });
     expect(calls.map((c) => c.method)).not.toContain('Target.getTargets');
   });
 });

package/src/browser/action-builder/analyzer.ts

@@ -1,5 +1,5 @@
 // src/browser/action-builder/analyzer.ts
-import { spawn } from 'child_process';
+import { spawn } from 'node:child_process';
 import type { ActionDef } from './types.js';
 
 export interface AnalyzerPage {
@@ -45,7 +45,15 @@ function claudeCliCall(prompt: string): Promise<string> {
   return new Promise((resolve, reject) => {
     const child = spawn(
       'claude',
-      ['--print', '--model', 'haiku', '--strict-mcp-config', '--no-session-persistence', '--', prompt],
+      [
+        '--print',
+        '--model',
+        'haiku',
+        '--strict-mcp-config',
+        '--no-session-persistence',
+        '--',
+        prompt,
+      ],
       { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
     );
     let stdout = '';
@@ -54,11 +62,19 @@ function claudeCliCall(prompt: string): Promise<string> {
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
-      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+      try {
+        child.kill('SIGTERM');
+      } catch {
+        /* ignore */
+      }
       reject(new Error('claude --print timed out after 60s'));
     }, 60_000);
-    child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
-    child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
     child.on('close', (code) => {
       if (settled) return;
       settled = true;
@@ -70,7 +86,11 @@ function claudeCliCall(prompt: string): Promise<string> {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      reject(new Error(`claude CLI not found — is Claude Code installed? (${(err as NodeJS.ErrnoException).code})`));
+      reject(
+        new Error(
+          `claude CLI not found — is Claude Code installed? (${(err as NodeJS.ErrnoException).code})`,
+        ),
+      );
     });
   });
 }
@@ -103,7 +123,7 @@ ActionDef schema:
 export async function analyzePageForAction(
   page: AnalyzerPage,
   task: string,
-  options: AnalyzerOptions = {},
+  _options: AnalyzerOptions = {},
 ): Promise<ActionDef> {
   const url = await page.url();
   const title = await page.evaluate<string>('document.title');
@@ -119,13 +139,15 @@ export async function analyzePageForAction(
   const domContext = `URL: ${url}
 Title: ${title}
 Interactive elements (${elements.length}):
-${elements.map((el, i) => {
-  const attrs = Object.entries(el.attrs)
-    .filter(([, v]) => v)
-    .map(([k, v]) => `${k}="${v}"`)
-    .join(' ');
-  return `${i + 1}. <${el.tag}${attrs ? ' ' + attrs : ''}>${el.text}</${el.tag}>`;
-}).join('\n')}`;
+${elements
+  .map((el, i) => {
+    const attrs = Object.entries(el.attrs)
+      .filter(([, v]) => v)
+      .map(([k, v]) => `${k}="${v}"`)
+      .join(' ');
+    return `${i + 1}. <${el.tag}${attrs ? ` ${attrs}` : ''}>${el.text}</${el.tag}>`;
+  })
+  .join('\n')}`;
 
   const fullPrompt = `${SYSTEM_PROMPT}\n\nTask: ${task}\n\nPage context:\n${domContext}`;
   const responseText = await claudeCliCall(fullPrompt);
@@ -138,7 +160,9 @@ ${elements.map((el, i) => {
   }
 
   if (!actionDef.id || !actionDef.steps || !Array.isArray(actionDef.steps)) {
-    throw new Error(`Claude returned invalid ActionDef: missing id or steps\n${responseText.slice(0, 500)}`);
+    throw new Error(
+      `Claude returned invalid ActionDef: missing id or steps\n${responseText.slice(0, 500)}`,
+    );
   }
 
   return actionDef;

package/src/browser/action-builder/types.ts

@@ -1,12 +1,49 @@
-export interface NavigateStep { type: 'navigate'; url: string; }
-export interface FindStep { type: 'find'; selectors: string[]; as: string; }
-export interface ClickStep { type: 'click'; target: string; }
-export interface TypeStep { type: 'type'; target: string; text: string; humanDelay?: boolean; }
-export interface WaitStep { type: 'wait'; condition: 'network_idle' | 'selector' | 'duration'; timeout?: number; selector?: string; }
-export interface ExtractStep { type: 'extract'; target: string; as: string; attribute?: string; }
-export interface ConditionStep { type: 'condition'; expression: string; then: StepDef[]; else?: StepDef[]; }
+export interface NavigateStep {
+  type: 'navigate';
+  url: string;
+}
+export interface FindStep {
+  type: 'find';
+  selectors: string[];
+  as: string;
+}
+export interface ClickStep {
+  type: 'click';
+  target: string;
+}
+export interface TypeStep {
+  type: 'type';
+  target: string;
+  text: string;
+  humanDelay?: boolean;
+}
+export interface WaitStep {
+  type: 'wait';
+  condition: 'network_idle' | 'selector' | 'duration';
+  timeout?: number;
+  selector?: string;
+}
+export interface ExtractStep {
+  type: 'extract';
+  target: string;
+  as: string;
+  attribute?: string;
+}
+export interface ConditionStep {
+  type: 'condition';
+  expression: string;
+  then: StepDef[];
+  else?: StepDef[];
+}
 
-export type StepDef = NavigateStep | FindStep | ClickStep | TypeStep | WaitStep | ExtractStep | ConditionStep;
+export type StepDef =
+  | NavigateStep
+  | FindStep
+  | ClickStep
+  | TypeStep
+  | WaitStep
+  | ExtractStep
+  | ConditionStep;
 
 export interface ActionDef {
   id: string;