@web-auto/camo 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/camo",
-  "version": "0.1.0002",
+  "version": "0.1.0003",
   "description": "Camoufox Browser CLI - Cross-platform browser automation",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node --test tests/*.test.mjs",
+    "test": "node --test 'tests/**/*.test.mjs'",
+    "test:coverage": "c8 --reporter=text --reporter=lcov node --test 'tests/**/*.test.mjs'",
     "version:bump": "node scripts/bump-version.mjs",
     "install:global": "npm run build && npm install -g .",
     "uninstall:global": "npm uninstall -g @web-auto/camo",
@@ -32,8 +33,10 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "dependencies": {},
   "peerDependencies": {
     "camoufox": "^0.1.0"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3"
   }
 }

package/src/cli.mjs

@@ -11,6 +11,7 @@ import { handleCookiesCommand } from './commands/cookies.mjs';
 import { handleWindowCommand } from './commands/window.mjs';
 import { handleMouseCommand } from './commands/mouse.mjs';
 import { handleSystemCommand } from './commands/system.mjs';
+import { handleContainerCommand } from './commands/container.mjs';
 import {
   handleStartCommand, handleStopCommand, handleStatusCommand,
   handleGotoCommand, handleBackCommand, handleScreenshotCommand,
@@ -112,11 +113,16 @@ async function main() {
     return;
   }
 
+  if (cmd === 'container') {
+    await handleContainerCommand(args);
+    return;
+  }
+
   const serviceCommands = new Set([
     'start', 'stop', 'close', 'status', 'list', 'goto', 'navigate', 'back', 'screenshot',
     'new-page', 'close-page', 'switch-page', 'list-pages', 'shutdown',
     'scroll', 'click', 'type', 'highlight', 'clear-highlight', 'viewport',
-    'cookies', 'window', 'mouse', 'system',
+    'cookies', 'window', 'mouse', 'system', 'container',
   ]);
 
   if (!serviceCommands.has(cmd)) {

package/src/commands/container.mjs

@@ -0,0 +1,178 @@
+// Container commands - filter and watch elements
+import { resolveProfileId, getPositionals } from '../utils/args.mjs';
+import { callAPI, getSessionByProfile } from '../utils/browser-service.mjs';
+import { getDefaultProfile } from '../utils/config.mjs';
+import { getChangeNotifier } from '../container/change-notifier.mjs';
+import { createElementFilter } from '../container/element-filter.mjs';
+
+const notifier = getChangeNotifier();
+const elementFilter = createElementFilter();
+
+export async function handleContainerFilterCommand(args) {
+  const profileId = resolveProfileId(args);
+  const session = await getSessionByProfile(profileId);
+  if (!session) {
+    throw new Error(`No active session for profile: ${profileId || 'default'}`);
+  }
+
+  const selectors = [];
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--profile' || arg === '-p') { i++; continue; }
+    if (arg.startsWith('--')) continue;
+    selectors.push(arg);
+  }
+
+  if (selectors.length === 0) {
+    throw new Error('Usage: camo container filter <selector> [--profile <id>]');
+  }
+
+  // Get DOM snapshot from browser service
+  const result = await callAPI(`/session/${session.session_id}/dom-tree`, { method: 'POST' });
+  const snapshot = result.dom_tree || result;
+
+  // Filter elements
+  const matched = [];
+  for (const selector of selectors) {
+    const elements = notifier.findElements(snapshot, { css: selector });
+    matched.push(...elements.map(e => ({
+      path: e.path,
+      tag: e.tag,
+      id: e.id,
+      classes: e.classes,
+      text: (e.textSnippet || e.text || '').slice(0, 50),
+    })));
+  }
+
+  console.log(JSON.stringify({ ok: true, count: matched.length, elements: matched }, null, 2));
+}
+
+export async function handleContainerWatchCommand(args) {
+  const profileId = resolveProfileId(args);
+  const session = await getSessionByProfile(profileId);
+  if (!session) {
+    throw new Error(`No active session for profile: ${profileId || 'default'}`);
+  }
+
+  const positionalArgs = getPositionals(args, ['--profile', '-p', '--selector', '-s', '--throttle', '-t']);
+  
+  const selectorIdx = args.indexOf('--selector') !== -1 ? args.indexOf('--selector') : args.indexOf('-s');
+  const throttleIdx = args.indexOf('--throttle') !== -1 ? args.indexOf('--throttle') : args.indexOf('-t');
+  
+  const selector = selectorIdx >= 0 ? args[selectorIdx + 1] : positionalArgs[0];
+  const throttle = throttleIdx >= 0 ? parseInt(args[throttleIdx + 1], 10) : 500;
+
+  if (!selector) {
+    throw new Error('Usage: camo container watch --selector <css> [--throttle ms] [--profile <id>]');
+  }
+
+  console.log(JSON.stringify({ ok: true, message: `Watching selector: ${selector}`, throttle }));
+
+  // Setup WebSocket connection for DOM updates
+  // For now, poll the browser service
+  const interval = setInterval(async () => {
+    try {
+      const result = await callAPI(`/session/${session.session_id}/dom-tree`, { method: 'POST' });
+      const snapshot = result.dom_tree || result;
+      notifier.processSnapshot(snapshot);
+    } catch (err) {
+      console.error(JSON.stringify({ ok: false, error: err.message }));
+    }
+  }, throttle);
+
+  // Watch the selector
+  notifier.watch({ css: selector }, {
+    onAppear: (elements) => {
+      console.log(JSON.stringify({ event: 'appear', selector, count: elements.length, elements }));
+    },
+    onDisappear: (elements) => {
+      console.log(JSON.stringify({ event: 'disappear', selector, count: elements.length }));
+    },
+    onChange: ({ appeared, disappeared }) => {
+      console.log(JSON.stringify({ event: 'change', selector, appeared: appeared.length, disappeared: disappeared.length }));
+    },
+    throttle,
+  });
+
+  // Keep process alive
+  process.on('SIGINT', () => {
+    clearInterval(interval);
+    notifier.destroy();
+    console.log(JSON.stringify({ ok: true, message: 'Watch stopped' }));
+    process.exit(0);
+  });
+}
+
+export async function handleContainerListCommand(args) {
+  const profileId = resolveProfileId(args);
+  const session = await getSessionByProfile(profileId);
+  if (!session) {
+    throw new Error(`No active session for profile: ${profileId || 'default'}`);
+  }
+
+  const result = await callAPI(`/session/${session.session_id}/dom-tree`, { method: 'POST' });
+  const snapshot = result.dom_tree || result;
+
+  // Get viewport info
+  const viewportResult = await callAPI(`/session/${session.session_id}/viewport`);
+  const viewport = viewportResult.viewport || { width: 1280, height: 720 };
+
+  // Collect all visible elements
+  const collectElements = (node, path = 'root') => {
+    const elements = [];
+    if (!node) return elements;
+
+    const rect = node.rect || node.bbox;
+    if (rect && viewport) {
+      const inViewport = elementFilter.isInViewport(rect, viewport);
+      const visibilityRatio = elementFilter.getVisibilityRatio(rect, viewport);
+
+      if (inViewport && visibilityRatio > 0.1) {
+        elements.push({
+          path,
+          tag: node.tag,
+          id: node.id,
+          classes: node.classes?.slice(0, 3),
+          visibilityRatio: Math.round(visibilityRatio * 100) / 100,
+          rect: { x: rect.left || rect.x, y: rect.top || rect.y, w: rect.width, h: rect.height },
+        });
+      }
+    }
+
+    if (node.children) {
+      for (let i = 0; i < node.children.length; i++) {
+        elements.push(...collectElements(node.children[i], `${path}/${i}`));
+      }
+    }
+
+    return elements;
+  };
+
+  const elements = collectElements(snapshot);
+  console.log(JSON.stringify({ ok: true, viewport, count: elements.length, elements: elements.slice(0, 50) }, null, 2));
+}
+
+export async function handleContainerCommand(args) {
+  const sub = args[1];
+
+  switch (sub) {
+    case 'filter':
+      return handleContainerFilterCommand(args.slice(1));
+    case 'watch':
+      return handleContainerWatchCommand(args.slice(1));
+    case 'list':
+      return handleContainerListCommand(args.slice(1));
+    default:
+      console.log(`Usage: camo container <filter|watch|list> [options]
+
+Commands:
+  filter <selector>  - Filter DOM elements by CSS selector
+  watch --selector <css> - Watch for element changes (outputs JSON events)
+  list               - List all visible elements in viewport
+
+Options:
+  --profile, -p <id>  - Profile to use
+  --throttle, -t <ms> - Throttle interval for watch (default: 500)
+`);
+  }
+}

package/src/container/change-notifier.mjs

@@ -0,0 +1,170 @@
+// Change Notifier - Subscribe to DOM changes and element events
+
+export class ChangeNotifier {
+  constructor() {
+    this.subscriptions = new Map(); // topic -> Set<callback>
+    this.elementWatchers = new Map(); // selector -> { lastState, callbacks }
+    this.lastSnapshot = null;
+  }
+
+  // Subscribe to a topic
+  subscribe(topic, callback) {
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, new Set());
+    }
+    this.subscriptions.get(topic).add(callback);
+    return () => {
+      this.subscriptions.get(topic)?.delete(callback);
+    };
+  }
+
+  // Watch specific elements by selector
+  watch(selector, options = {}) {
+    const { onAppear, onDisappear, onChange, throttle = 200 } = options;
+
+    if (!this.elementWatchers.has(selector)) {
+      this.elementWatchers.set(selector, {
+        lastState: null,
+        lastNotifyTime: 0,
+        callbacks: { onAppear, onDisappear, onChange },
+      });
+    } else {
+      const watcher = this.elementWatchers.get(selector);
+      if (onAppear) watcher.callbacks.onAppear = onAppear;
+      if (onDisappear) watcher.callbacks.onDisappear = onDisappear;
+      if (onChange) watcher.callbacks.onChange = onChange;
+    }
+
+    return () => {
+      this.elementWatchers.delete(selector);
+    };
+  }
+
+  // Notify all subscribers of a topic
+  notify(topic, data) {
+    const callbacks = this.subscriptions.get(topic);
+    if (!callbacks) return;
+    for (const callback of callbacks) {
+      try {
+        callback(data);
+      } catch (err) {
+        console.error(`[ChangeNotifier] callback error for ${topic}:`, err);
+      }
+    }
+  }
+
+  // Process new DOM snapshot and trigger notifications
+  processSnapshot(snapshot) {
+    const now = Date.now();
+    const prevSnapshot = this.lastSnapshot;
+    this.lastSnapshot = snapshot;
+
+    // Notify general DOM change
+    this.notify('dom:changed', { snapshot, prevSnapshot });
+
+    // Process element watchers
+    for (const [selector, watcher] of this.elementWatchers) {
+      const { lastState, callbacks, lastNotifyTime, throttle } = watcher;
+
+      // Throttle notifications
+      if (now - lastNotifyTime < throttle) continue;
+
+      const currentElements = this.findElements(snapshot, selector);
+      const currentState = currentElements.map(e => e.path).sort().join(',');
+
+      if (lastState !== null && currentState !== lastState) {
+        // Something changed
+        const prevElements = watcher.prevElements || [];
+        const appeared = currentElements.filter(e => !prevElements.find(p => p.path === e.path));
+        const disappeared = prevElements.filter(e => !currentElements.find(c => c.path === e.path));
+
+        if (appeared.length > 0 && callbacks.onAppear) {
+          callbacks.onAppear(appeared);
+          watcher.lastNotifyTime = now;
+        }
+        if (disappeared.length > 0 && callbacks.onDisappear) {
+          callbacks.onDisappear(disappeared);
+          watcher.lastNotifyTime = now;
+        }
+        if (callbacks.onChange) {
+          callbacks.onChange({ current: currentElements, previous: prevElements, appeared, disappeared });
+          watcher.lastNotifyTime = now;
+        }
+      }
+
+      watcher.lastState = currentState;
+      watcher.prevElements = currentElements;
+    }
+  }
+
+  // Find elements matching selector in DOM tree
+  findElements(node, selector, path = 'root') {
+    const results = [];
+    if (!node) return results;
+
+    // Check if current node matches
+    if (this.nodeMatchesSelector(node, selector)) {
+      results.push({ ...node, path });
+    }
+
+    // Recurse into children
+    if (node.children) {
+      for (let i = 0; i < node.children.length; i++) {
+        const childResults = this.findElements(node.children[i], selector, `${path}/${i}`);
+        results.push(...childResults);
+      }
+    }
+
+    return results;
+  }
+
+  // Check if node matches selector
+  nodeMatchesSelector(node, selector) {
+    if (!node) return false;
+
+    // CSS selector match
+    if (selector.css && node.selector === selector.css) return true;
+    if (selector.css && node.classes) {
+      const selClasses = selector.css.match(/\.[\w-]+/g);
+      if (selClasses) {
+        const nodeClasses = new Set(node.classes || []);
+        if (selClasses.map(s => s.slice(1)).every(c => nodeClasses.has(c))) return true;
+      }
+    }
+
+    // ID match
+    if (selector.id && node.id === selector.id) return true;
+
+    // Class match
+    if (selector.classes) {
+      const nodeClasses = new Set(node.classes || []);
+      if (selector.classes.every(c => nodeClasses.has(c))) return true;
+    }
+
+    return false;
+  }
+
+  // Cleanup
+  destroy() {
+    this.subscriptions.clear();
+    this.elementWatchers.clear();
+    this.lastSnapshot = null;
+  }
+}
+
+// Global instance
+let globalNotifier = null;
+
+export function getChangeNotifier() {
+  if (!globalNotifier) {
+    globalNotifier = new ChangeNotifier();
+  }
+  return globalNotifier;
+}
+
+export function destroyChangeNotifier() {
+  if (globalNotifier) {
+    globalNotifier.destroy();
+    globalNotifier = null;
+  }
+}

package/src/container/element-filter.mjs

@@ -0,0 +1,97 @@
+// Container Element Filter - Filter DOM elements by visibility, container definitions
+
+export class ElementFilter {
+  constructor(options = {}) {
+    this.viewportMargin = options.viewportMargin || 0;
+    this.minVisibleRatio = options.minVisibleRatio || 0.5;
+  }
+
+  // Check if element is in viewport
+  isInViewport(rect, viewport) {
+    return (
+      rect.left < viewport.width + this.viewportMargin &&
+      rect.right > -this.viewportMargin &&
+      rect.top < viewport.height + this.viewportMargin &&
+      rect.bottom > -this.viewportMargin
+    );
+  }
+
+  // Calculate visibility ratio
+  getVisibilityRatio(rect, viewport) {
+    const visibleLeft = Math.max(0, rect.left);
+    const visibleTop = Math.max(0, rect.top);
+    const visibleRight = Math.min(viewport.width, rect.right);
+    const visibleBottom = Math.min(viewport.height, rect.bottom);
+
+    const visibleArea = Math.max(0, visibleRight - visibleLeft) * Math.max(0, visibleBottom - visibleTop);
+    const totalArea = rect.width * rect.height;
+
+    return totalArea > 0 ? visibleArea / totalArea : 0;
+  }
+
+  // Filter elements by container definition
+  filterByContainer(elements, containerDef) {
+    const selectors = containerDef.selectors || [];
+    const results = [];
+
+    for (const element of elements) {
+      for (const selector of selectors) {
+        if (this.matchesSelector(element, selector)) {
+          results.push({
+            element,
+            container: containerDef,
+            matchedSelector: selector,
+          });
+          break;
+        }
+      }
+    }
+
+    return results;
+  }
+
+  // Check if element matches selector definition
+  matchesSelector(element, selector) {
+    if (selector.css && element.selector === selector.css) return true;
+    if (selector.id && element.id === selector.id) return true;
+    if (selector.classes) {
+      const elementClasses = new Set(element.classes || []);
+      if (selector.classes.every(c => elementClasses.has(c))) return true;
+    }
+    return false;
+  }
+
+  // Main filter method
+  filter(elements, options = {}) {
+    const {
+      container,
+      viewport,
+      requireVisible = true,
+      minVisibleRatio = this.minVisibleRatio,
+    } = options;
+
+    let results = [...elements];
+
+    // Filter by container definition
+    if (container) {
+      results = this.filterByContainer(results, container);
+    }
+
+    // Filter by viewport visibility
+    if (requireVisible && viewport) {
+      results = results.filter(item => {
+        const rect = item.element?.rect || item.rect;
+        if (!rect) return false;
+        const ratio = this.getVisibilityRatio(rect, viewport);
+        item.visibilityRatio = ratio;
+        return ratio >= minVisibleRatio;
+      });
+    }
+
+    return results;
+  }
+}
+
+export function createElementFilter(options) {
+  return new ElementFilter(options);
+}

package/src/container/index.mjs

@@ -0,0 +1,3 @@
+// Container module - element filtering and change notification
+export { ElementFilter, createElementFilter } from './element-filter.mjs';
+export { ChangeNotifier, getChangeNotifier, destroyChangeNotifier } from './change-notifier.mjs';

package/src/lib/client.mjs

@@ -0,0 +1,197 @@
+// Camo Container Client - High-level API for container subscription
+
+import { callAPI, getSessionByProfile, checkBrowserService } from '../utils/browser-service.mjs';
+import { getDefaultProfile } from '../utils/config.mjs';
+import { getChangeNotifier } from '../container/change-notifier.mjs';
+import { createElementFilter } from '../container/element-filter.mjs';
+
+export class CamoContainerClient {
+  constructor(options = {}) {
+    this.profileId = options.profileId || getDefaultProfile();
+    this.serviceUrl = options.serviceUrl || 'http://127.0.0.1:7704';
+    this.notifier = getChangeNotifier();
+    this.filter = createElementFilter(options.filterOptions || {});
+    this.session = null;
+    this.pollInterval = null;
+    this.subscriptions = new Map(); // containerId -> callback
+    this.lastSnapshot = null;
+    this.viewport = { width: 1280, height: 720 };
+  }
+
+  async ensureSession() {
+    if (this.session) return this.session;
+    
+    if (!await checkBrowserService()) {
+      throw new Error('Browser service not running. Run: camo init');
+    }
+
+    this.session = await getSessionByProfile(this.profileId);
+    if (!this.session) {
+      throw new Error(`No active session for profile: ${this.profileId}`);
+    }
+
+    return this.session;
+  }
+
+  async getSnapshot() {
+    await this.ensureSession();
+
+    const result = await callAPI(`/session/${this.session.session_id}/dom-tree`, { method: 'POST' });
+    this.lastSnapshot = result.dom_tree || result;
+    return this.lastSnapshot;
+  }
+
+  async getViewport() {
+    await this.ensureSession();
+
+    try {
+      const result = await callAPI(`/session/${this.session.session_id}/viewport`);
+      this.viewport = result.viewport || this.viewport;
+    } catch {}
+
+    return this.viewport;
+  }
+
+  // Subscribe to container changes
+  async subscribe(containers, options = {}) {
+    const { throttle = 500 } = options;
+    await this.ensureSession();
+
+    for (const container of containers) {
+      const { containerId, selector, onAppear, onDisappear, onChange } = container;
+
+      this.notifier.watch(
+        typeof selector === 'string' ? { css: selector } : selector,
+        {
+          onAppear: (elements) => {
+            this.subscriptions.get(containerId)?.onAppear?.(elements);
+          },
+          onDisappear: (elements) => {
+            this.subscriptions.get(containerId)?.onDisappear?.(elements);
+          },
+          onChange: (data) => {
+            this.subscriptions.get(containerId)?.onChange?.(data);
+          },
+          throttle,
+        }
+      );
+
+      this.subscriptions.set(containerId, {
+        selector,
+        onAppear,
+        onDisappear,
+        onChange,
+      });
+    }
+
+    // Start polling
+    if (!this.pollInterval) {
+      this.pollInterval = setInterval(async () => {
+        try {
+          const snapshot = await this.getSnapshot();
+          this.notifier.processSnapshot(snapshot);
+        } catch (err) {
+          // Ignore errors during polling
+        }
+      }, throttle);
+    }
+
+    return {
+      unsubscribe: () => {
+        for (const container of containers) {
+          this.subscriptions.delete(container.containerId);
+        }
+      },
+    };
+  }
+
+  // Checkpoint detection helper
+  async detectCheckpoint(checkpointRules) {
+    const snapshot = await this.getSnapshot();
+    const viewport = await this.getViewport();
+
+    const matched = new Set();
+
+    for (const [checkpointId, rule] of Object.entries(checkpointRules)) {
+      const { selectors, requireAll = false } = rule;
+      let matchCount = 0;
+
+      for (const selector of selectors) {
+        const elements = this.notifier.findElements(snapshot, { css: selector });
+        const visible = elements.filter(e => {
+          const rect = e.rect || e.bbox;
+          if (!rect) return false;
+          return this.filter.isInViewport(rect, viewport);
+        });
+
+        if (visible.length > 0) {
+          matchCount++;
+        }
+      }
+
+      if (requireAll) {
+        if (matchCount === selectors.length) {
+          matched.add(checkpointId);
+        }
+      } else {
+        if (matchCount > 0) {
+          matched.add(checkpointId);
+        }
+      }
+    }
+
+    return Array.from(matched);
+  }
+
+  // List visible elements
+  async listVisibleElements(options = {}) {
+    const { minVisibility = 0.1, maxResults = 50 } = options;
+    const snapshot = await this.getSnapshot();
+    const viewport = await this.getViewport();
+
+    const collect = (node, path = 'root') => {
+      const elements = [];
+      if (!node) return elements;
+
+      const rect = node.rect || node.bbox;
+      if (rect) {
+        const ratio = this.filter.getVisibilityRatio(rect, viewport);
+        if (ratio >= minVisibility) {
+          elements.push({
+            path,
+            tag: node.tag,
+            id: node.id,
+            classes: node.classes?.slice(0, 3),
+            visibilityRatio: Math.round(ratio * 100) / 100,
+            rect: { x: rect.left || rect.x, y: rect.top || rect.y, w: rect.width, h: rect.height },
+          });
+        }
+      }
+
+      if (node.children) {
+        for (let i = 0; i < node.children.length; i++) {
+          elements.push(...collect(node.children[i], `${path}/${i}`));
+        }
+      }
+
+      return elements;
+    };
+
+    const all = collect(snapshot);
+    return all.slice(0, maxResults);
+  }
+
+  // Cleanup
+  destroy() {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = null;
+    }
+    this.subscriptions.clear();
+    this.notifier.destroy();
+  }
+}
+
+export function createCamoClient(options) {
+  return new CamoContainerClient(options);
+}

package/src/utils/help.mjs

@@ -114,6 +114,11 @@ EXAMPLES:
   camo unlock myprofile
   camo stop
 
+CONTAINER FILTER & SUBSCRIPTION:
+  container filter <selector> [--profile <id>]      Filter DOM elements by CSS selector
+  container watch --selector <css>                  Watch for element changes
+  container list                                    List visible elements in viewport
+
 ENV:
   WEBAUTO_BROWSER_URL                       Default: http://127.0.0.1:7704
   WEBAUTO_REPO_ROOT                         Optional explicit webauto repo root