@monoes/monobrowse 1.0.1 → 1.0.3

package/src/browser/ref-cache.ts

@@ -0,0 +1,90 @@
+/**
+ * AX-tree ref cache persistence.
+ *
+ * `snapshot` and `find` are separate CLI invocations — each starts a fresh
+ * node process, so the in-memory ElementRef Map built by captureSnapshot()
+ * does not survive between them. This module persists a lightweight lookup
+ * index (ref -> role/name/nodeId/backendDOMNodeId, i.e. everything CDP needs
+ * to re-target an element) to disk so a later process can rehydrate it.
+ *
+ * The full AX-tree text/dump is intentionally NOT persisted — only the
+ * per-ref index, to keep the file small.
+ */
+import { readFile, writeFile, mkdir, rm } from 'fs/promises';
+import { join } from 'path';
+import type { ElementRef } from './types.js';
+
+const CACHE_DIR = join(process.cwd(), '.monomind', 'monobrowse');
+const CACHE_FILE = join(CACHE_DIR, 'ax-snapshot.json');
+
+/** Snapshot older than this is flagged as possibly stale (page may have changed). */
+export const REF_CACHE_STALE_MS = 30_000;
+
+interface RefCacheFile {
+  targetId: string;
+  url: string;
+  savedAt: number;
+  refs: ElementRef[];
+}
+
+export interface RefCacheEntry {
+  refs: Map<string, ElementRef>;
+  url: string;
+  savedAt: number;
+  ageMs: number;
+  stale: boolean;
+}
+
+/** Persist the current ref index for a target so a later CLI process can read it back. */
+export async function saveRefCache(
+  targetId: string,
+  url: string,
+  refs: Map<string, ElementRef>
+): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    const data: RefCacheFile = {
+      targetId,
+      url,
+      savedAt: Date.now(),
+      refs: [...refs.values()],
+    };
+    await writeFile(CACHE_FILE, JSON.stringify(data));
+  } catch {
+    // Best-effort — persistence failure just means cross-process rehydration
+    // won't work; in-process (same run) behavior is unaffected.
+  }
+}
+
+/**
+ * Load the persisted ref index, scoped to the given targetId (a cache from a
+ * different tab/target is ignored). Returns null if no usable cache exists —
+ * callers fall back to an empty in-memory Map, matching prior behavior.
+ */
+export async function loadRefCache(targetId: string): Promise<RefCacheEntry | null> {
+  try {
+    const raw = await readFile(CACHE_FILE, 'utf8');
+    const data: RefCacheFile = JSON.parse(raw);
+    if (!data || !Array.isArray(data.refs) || data.targetId !== targetId) return null;
+
+    const refs = new Map<string, ElementRef>();
+    for (const ref of data.refs) {
+      if (ref && typeof ref.ref === 'string') refs.set(ref.ref, ref);
+    }
+    if (refs.size === 0) return null;
+
+    const ageMs = Date.now() - data.savedAt;
+    return { refs, url: data.url, savedAt: data.savedAt, ageMs, stale: ageMs > REF_CACHE_STALE_MS };
+  } catch {
+    return null;
+  }
+}
+
+/** Drop the persisted ref index — call whenever refs are invalidated (navigation, tab switch, close). */
+export async function clearRefCache(): Promise<void> {
+  try {
+    await rm(CACHE_FILE, { force: true });
+  } catch {
+    // Nothing to clear, or not writable — non-fatal.
+  }
+}

package/src/browser/tabs.ts

@@ -25,13 +25,42 @@ export async function activateTab(client: CdpClient, oldSessionId: string, targe
 }
 
 export async function switchToFrame(
-  _client: CdpClient,
-  _sessionId: string,
-  _frameSelector: string
+  client: CdpClient,
+  sessionId: string,
+  frameSelector: string
 ): Promise<string | null> {
-  throw new Error(
-    'switchToFrame is not yet implemented. ' +
-    'For same-origin frames, CDP commands already apply to the whole page. ' +
-    'For cross-origin (OOPIF) frames, call Target.attachToTarget with the frame target ID.'
+  const { result } = await client.send<{ result: { result: { value: string | null } } }>(
+    'Runtime.evaluate',
+    {
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(frameSelector)});
+        if (!el || el.tagName !== 'IFRAME') return null;
+        return el.src || null;
+      })()`,
+      returnByValue: true,
+    },
+    sessionId
   );
+  const frameSrc = result?.result?.value ?? null;
+
+  const { frameTree } = await client.send<{
+    frameTree: { childFrames?: Array<{ frame: { id: string; url: string; securityOrigin: string } }> };
+  }>('Page.getFrameTree', {}, sessionId);
+
+  const match = frameTree.childFrames?.find(
+    (cf) => cf.frame.url === frameSrc || cf.frame.id === frameSelector
+  );
+  if (!match) return frameSrc;
+
+  const targets = await client.send<{ targetInfos: Array<{ targetId: string; type: string; url: string }> }>(
+    'Target.getTargets', {}
+  );
+  const oopif = targets.targetInfos.find(
+    (t) => t.type === 'iframe' && t.url === match.frame.url
+  );
+  if (oopif) {
+    await client.send('Target.attachToTarget', { targetId: oopif.targetId, flatten: true });
+  }
+
+  return frameSrc;
 }

package/src/cli/action.ts

@@ -1,10 +1,14 @@
 // src/commands/browse-action.ts
 import { Command } from 'commander';
-import { readdir, writeFile, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { analyzePageForAction, type AnalyzerPage, readAction } from '../index.js';
-import type { ActionDef } from '../index.js';
+import { analyzePageForAction, type AnalyzerPage } from '../index.js';
+import type { ActionDef, StepDef } from '../index.js';
+
+async function readAction(filePath: string): Promise<ActionDef> {
+  return JSON.parse(await readFile(filePath, 'utf8')) as ActionDef;
+}
 
 // Built-in actions (shipped with the CLI) — actual step definitions live in adapters/
 const BUILTIN_ACTIONS: { id: string; platform: string; name: string }[] = [
@@ -92,8 +96,90 @@ export function createActionCommand(): Command {
         if (eq > 0) params[pair.slice(0, eq)] = pair.slice(eq + 1);
       }
       console.log(`Running action: ${actionId} with account: ${opts.account}`);
-      console.log('Params:', params);
-      console.log('(Action runner not yet implemented — use browse playbook run for full execution)');
+
+      const custom = await getCustomActions();
+      const def = custom.find(a => a.id === actionId);
+      if (!def) {
+        console.error(`Action not found in custom actions: ${actionId}`);
+        console.error('Built-in actions require adapter step definitions — use "action build" to create a custom action.');
+        process.exit(1);
+      }
+
+      const { connectToTarget } = await import('../browser/browser.js');
+      const { openUrl } = await import('../browser/browser.js');
+      const { clickElement, fillElement, evaluateJs } = await import('../browser/actions.js');
+      const { findBySelector } = await import('../browser/find.js');
+      const { waitFor } = await import('../browser/wait.js');
+      const port = parseInt(process.env.MONOBROWSE_PORT ?? '9222', 10);
+      const { client, sessionId } = await connectToTarget(port);
+      const refs = new Map<string, import('../browser/types.js').ElementRef>();
+
+      const interpolate = (s: string) =>
+        s.replace(/\{\{(\w+)\}\}/g, (_, k: string) => params[k] ?? `{{${k}}}`);
+
+      async function runSteps(steps: StepDef[]): Promise<void> {
+        for (const step of steps) {
+          switch (step.type) {
+            case 'navigate':
+              await openUrl(client, sessionId, interpolate(step.url));
+              console.log(`  navigate → ${step.url}`);
+              break;
+            case 'find': {
+              for (const sel of step.selectors) {
+                const found = await findBySelector(client, sessionId, refs, interpolate(sel)).catch(() => null);
+                if (found) { refs.set(step.as, found); break; }
+              }
+              console.log(`  find → ${step.as}`);
+              break;
+            }
+            case 'click': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              await clickElement(client, sessionId, ref);
+              console.log(`  click → ${step.target}`);
+              break;
+            }
+            case 'type': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              await fillElement(client, sessionId, ref, interpolate(step.text));
+              console.log(`  type → ${step.target}`);
+              break;
+            }
+            case 'wait':
+              if (step.condition === 'network_idle') {
+                await waitFor(client, sessionId, { load: 'networkidle', timeout: step.timeout });
+              } else if (step.condition === 'selector' && step.selector) {
+                await waitFor(client, sessionId, { selector: step.selector, timeout: step.timeout });
+              } else if (step.condition === 'duration') {
+                await new Promise(r => setTimeout(r, step.timeout ?? 1000));
+              }
+              console.log(`  wait → ${step.condition}`);
+              break;
+            case 'extract': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              const val = step.attribute
+                ? await evaluateJs(client, sessionId, `document.querySelector('[data-ref="${ref.ref}"]')?.getAttribute('${step.attribute}')`)
+                : await evaluateJs(client, sessionId, `document.querySelector('[data-ref="${ref.ref}"]')?.textContent`);
+              console.log(`  extract → ${step.as}: ${val}`);
+              break;
+            }
+            case 'condition': {
+              const result = await evaluateJs(client, sessionId, step.expression);
+              if (result) {
+                await runSteps(step.then);
+              } else if (step.else) {
+                await runSteps(step.else);
+              }
+              break;
+            }
+          }
+        }
+      }
+
+      await runSteps(def.steps);
+      console.log(`\nAction ${actionId} completed successfully.`);
     });
 
   cmd

package/src/cli/commands.ts

@@ -5,7 +5,6 @@
 
 import type { Command, CommandContext, CommandResult } from './types.js';
 import { output } from './output.js';
-import { createPlaybookCommand } from './playbook.js';
 import { createActionCommand } from './action.js';
 import { createPlatformCommand } from './platform.js';
 import type { CdpClient, ElementRef, NetworkRoute, FindAction } from '../index.js';
@@ -37,10 +36,27 @@ async function ensureConnected(port: number, targetId?: string) {
     _sessionId = conn.sessionId;
     _targetId = conn.target.id;
     _refs = new Map();
+    await hydrateRefsFromCache(browser, _targetId);
   }
   return { client: _client!, sessionId: _sessionId, targetId: _targetId };
 }
 
+// Each CLI invocation is a fresh process, so the in-memory _refs Map built by
+// a prior `snapshot` command is gone by the time a later `find`/`click`/etc.
+// command runs. Rehydrate it from the on-disk ref cache (written by
+// captureSnapshot call sites below) so refs resolved by a previous process
+// remain usable. Falls back silently to an empty Map if no cache exists.
+async function hydrateRefsFromCache(browser: Awaited<ReturnType<typeof getBrowser>>, targetId: string): Promise<void> {
+  const cached = await browser.loadRefCache(targetId);
+  if (!cached) return;
+  _refs = cached.refs;
+  if (cached.stale) {
+    output.printWarning(
+      `AX ref cache is ${Math.round(cached.ageMs / 1000)}s old — page may have changed since the last snapshot; re-run snapshot if refs don't resolve as expected`
+    );
+  }
+}
+
 // URL patterns that signal an unambiguous login/auth wall.
 // Excludes 'auth', 'oauth', 'sso', 'saml' — their callback/ACS/token paths
 // (/auth/callback, /sso/callback, /saml/acs) are completion endpoints, not walls.
@@ -155,6 +171,18 @@ async function switchToHeaded(url: string, port: number): Promise<void> {
   }
 }
 
+/**
+ * Sanitize an image-format flag. The host CLI (monomind) defines a GLOBAL
+ * --format flag for output shaping (text|json|table, default 'text') that
+ * leaks into subcommand flags — so ctx.flags.format arrives as 'text' even
+ * when the user never passed it, and Chrome rejects it with
+ * "CDP error -32602: Invalid image format". Only trust values that are real
+ * image formats; otherwise fall back to the subcommand's own default.
+ */
+function imageFormat<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return allowed.includes(value as T) ? (value as T) : fallback;
+}
+
 function print(msg: string) {
   process.stdout.write(msg + '\n');
 }
@@ -267,6 +295,7 @@ const snapshotCommand: Command = {
     });
 
     _refs = result.refs;
+    await browser.saveRefCache(_targetId, result.url, _refs);
 
     const applyOutputLimits = (text: string): string => {
       let out = text;
@@ -546,7 +575,7 @@ const screenshotCommand: Command = {
       result = await browser.captureScreenshot(client, sessionId, {
         path: ctx.args[0] as string,
         fullPage: ctx.flags.full as boolean,
-        format: ctx.flags.format as 'png' | 'jpeg' | 'webp',
+        format: imageFormat(ctx.flags.format, ['png', 'jpeg', 'webp'] as const, 'png'),
         quality: ctx.flags.quality as number,
         annotate,
         refs: annotate ? _refs : undefined,
@@ -919,6 +948,7 @@ const stateCommand: Command = {
         await browser.clearLocalStorage(c, sid);
         await browser.clearSessionStorage(c, sid);
         _refs = new Map();
+        await browser.clearRefCache();
         output.printSuccess('Browser state cleared (cookies, localStorage, sessionStorage, refs)');
         return { success: true };
       }
@@ -2229,6 +2259,7 @@ const diffCommand: Command = {
       const snap2 = await browser.captureSnapshot(client, sessionId, { interactiveOnly: ctx.flags.interactive as boolean });
 
       _refs = snap2.refs;
+      await browser.saveRefCache(_targetId, snap2.url, _refs);
 
       // Text diff
       const lines1 = snap1.text.split('\n');
@@ -2497,7 +2528,7 @@ const recordCommand: Command = {
     switch (action) {
       case 'start':
         await browser.startRecording(client, sessionId, {
-          format: ctx.flags.format as 'jpeg' | 'png',
+          format: imageFormat(ctx.flags.format, ['jpeg', 'png'] as const, 'jpeg'),
           quality: ctx.flags.quality as number,
         });
         output.printSuccess('Recording started');
@@ -2516,7 +2547,7 @@ const recordCommand: Command = {
           output.printInfo(`Previous recording saved: ${prevPath}`);
         }
         await browser.startRecording(client, sessionId, {
-          format: ctx.flags.format as 'jpeg' | 'png',
+          format: imageFormat(ctx.flags.format, ['jpeg', 'png'] as const, 'jpeg'),
           quality: ctx.flags.quality as number,
         });
         output.printSuccess('Recording restarted');
@@ -2734,7 +2765,6 @@ function wrapCommanderCommand(factory: () => import('commander').Command): Comma
   };
 }
 
-const playbookSubcommand: Command = wrapCommanderCommand(createPlaybookCommand);
 const actionSubcommand: Command = wrapCommanderCommand(createActionCommand);
 const platformSubcommand: Command = wrapCommanderCommand(createPlatformCommand);
 
@@ -2806,7 +2836,6 @@ const browseCommand: Command = {
     harCommand,
     resizeCommand,
     closeCommand,
-    playbookSubcommand,
     actionSubcommand,
     platformSubcommand,
   ],

package/src/index.ts

@@ -1,25 +1,5 @@
-// Re-export the full monoplaybook engine so consumers only need @monoes/monobrowse
-export * from '@monoes/monoplaybook';
-
 export * from './browser/index.js';
 export * from './browser/action-builder/analyzer.js';
 export * from './browser/action-builder/types.js';
 export * from './browser/adapters/index.js';
 export { startDashboard, getDashboard } from './browser/dashboard/server.js';
-export { createBuiltinHandlers, createBrowserHandlers } from './browser/playbook/index.js';
-export { readAction } from './browser/playbook/store.js';
-
-// Batteries-included handler factory: service nodes + browser automation + builtins.
-// This is the recommended entry point when using monobrowse as the default executor.
-import { createNodeHandlers } from '@monoes/monoplaybook';
-import { createBrowserHandlers } from './browser/playbook/browser-handlers.js';
-import { createBuiltinHandlers } from './browser/playbook/builtin-handlers.js';
-import type { NodeHandler } from '@monoes/monoplaybook';
-
-export function createDefaultHandlers(): Map<string, NodeHandler> {
-  return new Map<string, NodeHandler>([
-    ...createNodeHandlers(),
-    ...createBrowserHandlers(),
-    ...createBuiltinHandlers(),
-  ]);
-}

package/dist/package.json

@@ -1,75 +0,0 @@
-{
-    "name": "@monoes/monobrowse",
-    "version": "1.0.1",
-    "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
-    "type": "module",
-    "bin": {
-        "monobrowse": "./dist/src/cli.js"
-    },
-    "main": "./dist/src/index.js",
-    "types": "./dist/src/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/src/index.d.ts",
-            "import": "./dist/src/index.js"
-        },
-        "./cli": {
-            "types": "./dist/src/cli.d.ts",
-            "import": "./dist/src/cli.js"
-        },
-        "./cli/commands": {
-            "types": "./dist/src/cli/commands.d.ts",
-            "import": "./dist/src/cli/commands.js"
-        },
-        "./cli/types": {
-            "types": "./dist/src/cli/types.d.ts",
-            "import": "./dist/src/cli/types.js"
-        }
-    },
-    "files": [
-        "dist",
-        "src"
-    ],
-    "engines": {
-        "node": ">=18.0.0"
-    },
-    "scripts": {
-        "build": "tsc && mkdir -p dist/src/browser/dashboard && cp src/browser/dashboard/ui.html dist/src/browser/dashboard/ui.html",
-        "prepublishOnly": "npm run build"
-    },
-    "keywords": [
-        "browser-automation",
-        "cdp",
-        "chrome-devtools-protocol",
-        "monomind",
-        "web-scraping",
-        "accessibility"
-    ],
-    "author": {
-        "name": "nokhodian",
-        "email": "nokhodian@gmail.com",
-        "url": "https://github.com/nokhodian"
-    },
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/monoes/monomind.git",
-        "directory": "packages/@monoes/monobrowse"
-    },
-    "dependencies": {
-        "commander": "^12.1.0",
-        "ws": "^8.21.0"
-    },
-    "peerDependencies": {
-        "@anthropic-ai/sdk": ">=0.20.0"
-    },
-    "peerDependenciesMeta": {
-        "@anthropic-ai/sdk": {
-            "optional": true
-        }
-    },
-    "devDependencies": {
-        "@anthropic-ai/sdk": "^0.39.0",
-        "typescript": "^5.8.3"
-    }
-}

package/dist/src/browser/playbook/browser-handlers.d.ts

@@ -1,3 +0,0 @@
-import type { NodeHandler } from '@monoes/monoplaybook';
-export declare function createBrowserHandlers(): Map<string, NodeHandler>;
-//# sourceMappingURL=browser-handlers.d.ts.map

package/dist/src/browser/playbook/browser-handlers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser-handlers.d.ts","sourceRoot":"","sources":["../../../../src/browser/playbook/browser-handlers.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAQ,MAAM,sBAAsB,CAAC;AAkI9D,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CA2ShE"}