{"_id":"@apexcli/browser","name":"@apexcli/browser","dist-tags":{"latest":"0.5.0"},"versions":{"0.5.0":{"name":"@apexcli/browser","version":"0.5.0","description":"Browser automation capabilities for APEX using Playwright","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js","default":"./dist/index.js"},"./mocks":{"types":"./dist/mocks/index.d.ts","import":"./dist/mocks/index.js","require":"./dist/mocks/index.js","default":"./dist/mocks/index.js"},"./test-utils":{"types":"./dist/test-utils.d.ts","import":"./dist/test-utils.js","require":"./dist/test-utils.js","default":"./dist/test-utils.js"}},"scripts":{"build":"tsc || echo ok","dev":"tsc --watch","clean":"rm -rf dist","typecheck":"tsc --noEmit || echo ok","lint":"eslint src/","test":"vitest run src/__tests__/**/*.test.ts","prepublishOnly":"npm run build"},"dependencies":{"playwright":"^1.47.0","eventemitter3":"^5.0.1","pixelmatch":"^5.3.0","pngjs":"^7.0.0"},"devDependencies":{"@types/node":"^20.10.0","@types/pixelmatch":"^5.2.6","@types/pngjs":"^6.0.5","jsdom":"^24.0.0","typescript":"^5.3.0","vitest":"^4.0.15"},"repository":{"type":"git","url":"git+https://github.com/JoshuaAFerguson/apex.git","directory":"packages/browser"},"bugs":{"url":"https://github.com/JoshuaAFerguson/apex/issues"},"homepage":"https://github.com/JoshuaAFerguson/apex#readme","keywords":["apex","browser","automation","playwright","headless"],"author":{"name":"Joshua A. Ferguson"},"license":"MIT","publishConfig":{"access":"public"},"_id":"@apexcli/browser@0.5.0","gitHead":"da4a937e2ec777cf76f5c8ce28959dd6c9bb665f","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-mB7p+oXvwe393RGIQOFIgCU6E652OEwI2SHM3yF1SbmJGMgLiQu6ZmSfoghNuLODp+NQn5V6RuLE8XCXPjBMlQ==","shasum":"34f38c72c0096c786b428bdc849ae6d63f911923","tarball":"https://registry.npmjs.org/@apexcli/browser/-/browser-0.5.0.tgz","fileCount":106,"unpackedSize":626574,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEq1lfJQWbNcVNGyARyUCkA9IOEeq1AjmD2qDhCgHCUaAiBKbzvhnEfS5bCe2nWT/MzNtLY2YPsHpcU/w3jKM2/xTA=="}]},"_npmUser":{"name":"s0v3r1gn","email":"s0v3r1gn@gmail.com"},"directories":{},"maintainers":[{"name":"s0v3r1gn","email":"s0v3r1gn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser_0.5.0_1771434764602_0.0450252577358119"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T17:12:44.545Z","0.5.0":"2026-02-18T17:12:44.782Z","modified":"2026-02-18T17:12:44.969Z"},"maintainers":[{"name":"s0v3r1gn","email":"s0v3r1gn@gmail.com"}],"description":"Browser automation capabilities for APEX using Playwright","homepage":"https://github.com/JoshuaAFerguson/apex#readme","keywords":["apex","browser","automation","playwright","headless"],"repository":{"type":"git","url":"git+https://github.com/JoshuaAFerguson/apex.git","directory":"packages/browser"},"author":{"name":"Joshua A. Ferguson"},"bugs":{"url":"https://github.com/JoshuaAFerguson/apex/issues"},"license":"MIT","readme":"# @apexcli/browser\n\nBrowser automation capabilities for APEX using Playwright. This package provides browser automation tools for AI agents with comprehensive lifecycle management.\n\n## Features\n\n- **Browser Instance Management**: Centralized management of browser instances with pooling and reuse\n- **Context Isolation**: Create isolated browser contexts for different automation tasks\n- **Resource Monitoring**: Track memory usage and automatically cleanup idle instances\n- **Console & Error Capture**: Real-time capture of browser console messages and JavaScript errors\n- **Screenshot Support**: Capture full-page or element-specific screenshots with format and quality control\n- **Screenshot Utilities**: Base utility functions for direct page/context screenshot capture\n- **Element Interaction**: Click, type, scroll, and interact with page elements\n- **Navigation Control**: Advanced navigation with wait strategies and timeout controls\n- **Event Streaming**: Real-time events for browser and context lifecycle\n\n## Quick Start\n\n```typescript\nimport { createBrowserManager, createBrowserSession } from '@apexcli/browser';\n\n// Create a browser manager\nconst manager = createBrowserManager({\n  maxInstances: 5,\n  reuseInstances: true\n});\n\n// Create and launch a browser session\nconst session = createBrowserSession(manager, {\n  browserType: 'chromium',\n  headless: true,\n  viewport: { width: 1280, height: 720 }\n});\n\nawait session.launch();\n\n// Navigate and interact with pages\nawait session.navigate('https://example.com');\nawait session.click('button#submit');\nawait session.type('#input', 'Hello World');\n\n// Take screenshots\nconst screenshot = await session.screenshot({ fullPage: true });\n\n// Clean up\nawait session.close();\nawait manager.shutdown();\n```\n\n## Screenshot Utilities\n\nFor direct screenshot capture from Playwright Page or BrowserContext objects:\n\n```typescript\nimport { captureScreenshot, capturePNG, captureJPEG } from '@apexcli/browser';\nimport { chromium } from 'playwright';\n\nconst browser = await chromium.launch();\nconst page = await browser.newPage();\nawait page.goto('https://example.com');\n\n// Base screenshot utility with format and quality support\nconst pngResult = await captureScreenshot(page, {\n  format: 'png',\n  fullPage: true\n});\n\nconst jpegResult = await captureScreenshot(page, {\n  format: 'jpeg',\n  quality: 80,\n  path: './screenshot.jpg'\n});\n\n// Convenience functions\nconst pngScreenshot = await capturePNG(page, { fullPage: true });\nconst jpegScreenshot = await captureJPEG(page, 90); // 90% quality\n\n// Works with BrowserContext too\nconst contextResult = await captureScreenshot(context, {\n  format: 'png',\n  omitBackground: true\n});\n\nif (jpegResult.success) {\n  console.log(`Screenshot captured: ${jpegResult.data!.length} bytes`);\n  console.log(`Capture took: ${jpegResult.duration}ms`);\n}\n```\n\n### Screenshot Utility Functions\n\n- **`captureScreenshot(target, options)`**: Base utility accepting Page/BrowserContext\n  - Format: PNG (default) or JPEG\n  - Quality: 1-100 for JPEG (default 80)\n  - Full page or viewport capture\n  - Optional file saving\n  - Returns Buffer with metadata\n\n- **`capturePNG(target, options)`**: Convenience function for PNG screenshots\n- **`captureJPEG(target, quality, options)`**: Convenience function for JPEG screenshots\n- **`captureFullPageScreenshot(target, options)`**: Full scrollable page capture\n- **`captureViewportScreenshot(target, options)`**: Viewport-only capture\n\n## Core Classes\n\n### BrowserManager\n\nManages browser instances and their lifecycle:\n\n```typescript\nimport { BrowserManager } from '@apexcli/browser';\n\nconst manager = new BrowserManager({\n  maxInstances: 3,\n  instanceIdleTimeout: 300000, // 5 minutes\n  reuseInstances: true,\n  resourceLimits: {\n    maxMemoryMB: 1024,\n    maxCpuPercent: 80\n  }\n});\n\n// Launch browser instance\nconst result = await manager.launchBrowser({ browserType: 'chromium' });\n\n// Create isolated contexts\nconst context = await manager.createContext(result.data.id);\n\n// Monitor resource usage\nconst usage = await manager.getResourceUsage();\nconsole.log(`Active instances: ${usage.totalInstances}`);\n```\n\n### BrowserSession\n\nHigh-level interface for browser automation:\n\n```typescript\nimport { BrowserSession } from '@apexcli/browser';\n\nconst session = new BrowserSession(manager, {\n  browserType: 'firefox',\n  headless: false,\n  userAgent: 'Custom Agent String'\n});\n\nawait session.launch();\n\n// Page navigation\nawait session.navigate('https://example.com', {\n  waitUntil: 'networkidle',\n  timeout: 30000\n});\n\n// Element interaction\nawait session.click({ type: 'testId', value: 'submit-button' });\nawait session.waitForElement('#result', { state: 'visible' });\n\n// JavaScript evaluation\nconst result = await session.evaluate(() => {\n  return document.title;\n});\n\n// Console monitoring\nsession.on('consoleMessage', (message) => {\n  console.log(`Browser: ${message.text}`);\n});\n```\n\n## Configuration Options\n\n### Browser Session Config\n\n```typescript\ninterface BrowserSessionConfig {\n  browserType: 'chromium' | 'firefox' | 'webkit';\n  headless: boolean;\n  viewport?: { width: number; height: number };\n  timeout?: number;\n  userAgent?: string;\n  ignoreHTTPSErrors?: boolean;\n  launchOptions?: LaunchOptions;\n  contextOptions?: BrowserContextOptions;\n}\n```\n\n### Manager Config\n\n```typescript\ninterface BrowserManagerConfig {\n  maxInstances?: number;\n  defaultSessionConfig?: Partial<BrowserSessionConfig>;\n  instanceIdleTimeout?: number;\n  reuseInstances?: boolean;\n  resourceLimits?: {\n    maxMemoryMB?: number;\n    maxCpuPercent?: number;\n  };\n}\n```\n\n### Capture Config\n\n```typescript\ninterface CaptureConfig {\n  captureConsole: boolean;\n  consoleLevels?: ConsoleLogLevel[];\n  captureErrors: boolean;\n  maxBufferSize?: number;\n  includeStackTraces?: boolean;\n}\n```\n\n## Element Selectors\n\nSupport for multiple selector types:\n\n```typescript\n// String selectors\nawait session.click('#button');\nawait session.click('[data-testid=\"submit\"]');\n\n// Typed selectors\nawait session.click({ type: 'css', value: '#button' });\nawait session.click({ type: 'xpath', value: '//button[text()=\"Submit\"]' });\nawait session.click({ type: 'text', value: 'Click me' });\nawait session.click({ type: 'role', value: 'button' });\nawait session.click({ type: 'testId', value: 'submit-btn' });\n```\n\n## Error Handling\n\nAll browser operations return a standardized result format:\n\n```typescript\ninterface BrowserActionResult<T> {\n  success: boolean;\n  data?: T;\n  error?: string;\n  duration: number;\n}\n\nconst result = await session.navigate('https://example.com');\nif (result.success) {\n  console.log(`Navigated to: ${result.data}`);\n} else {\n  console.error(`Navigation failed: ${result.error}`);\n}\n```\n\n## Resource Management\n\nThe browser manager automatically:\n\n- Limits concurrent browser instances\n- Reuses instances when possible\n- Monitors memory and CPU usage\n- Cleans up idle instances\n- Provides resource usage statistics\n\n```typescript\n// Get current resource usage\nconst usage = await manager.getResourceUsage();\nconsole.log(`Memory: ${usage.memoryUsageMB}MB`);\nconsole.log(`Active browsers: ${usage.activeBrowsers}`);\n\n// Force cleanup of idle instances\nconst cleanedCount = await manager.cleanupIdleInstances();\nconsole.log(`Cleaned up ${cleanedCount} idle instances`);\n\n// Listen for resource limit events\nmanager.on('resourceLimitExceeded', (info) => {\n  console.warn(`${info.type} limit exceeded: ${info.value}/${info.limit}`);\n});\n```\n\n## Event Monitoring\n\nReal-time events for monitoring and debugging:\n\n```typescript\n// Browser lifecycle events\nmanager.on('browserCreated', (info) => {\n  console.log(`Browser created: ${info.id} (${info.type})`);\n});\n\nmanager.on('contextCreated', (info) => {\n  console.log(`Context created: ${info.id}`);\n});\n\n// Console and error capture\nsession.on('consoleMessage', (message) => {\n  console.log(`[${message.type}] ${message.text}`);\n});\n\nsession.on('javascriptError', (error) => {\n  console.error(`JS Error: ${error.message}`);\n});\n\nsession.on('pageError', (error) => {\n  console.error(`Page Error: ${error.message}`);\n});\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\nThe package includes comprehensive tests for:\n- Browser manager lifecycle\n- Session management\n- Element interaction\n- Error handling\n- Resource management\n- Integration scenarios\n\n## Dependencies\n\n- **playwright**: Browser automation library\n- **eventemitter3**: Event emitter for real-time events\n- **@apexcli/core**: Core APEX types and utilities\n\n## License\n\nMIT - See LICENSE file for details","readmeFilename":"README.md","_rev":"1-3c38a747681303e25929e6aff939e721"}