@auxiora/browser 1.0.0

package/src/url-validator.ts

@@ -0,0 +1,198 @@
+import { isIP } from 'node:net';
+import { BLOCKED_PROTOCOLS } from './types.js';
+
+interface ValidatorOptions {
+  allowedUrls?: string[];
+  blockedUrls?: string[];
+}
+
+/**
+ * Check if an IP address (v4 or v6) falls within private/internal ranges.
+ * Uses numeric comparison instead of string prefix matching to prevent
+ * bypass via decimal, hex, or octal IP encodings.
+ */
+function isPrivateIP(ip: string): boolean {
+  // IPv6 checks
+  if (ip.includes(':')) {
+    const normalized = normalizeIPv6(ip);
+    // ::1 (loopback)
+    if (normalized === '0000:0000:0000:0000:0000:0000:0000:0001') return true;
+    // :: (unspecified)
+    if (normalized === '0000:0000:0000:0000:0000:0000:0000:0000') return true;
+    // fe80::/10 (link-local)
+    if (normalized.startsWith('fe8') || normalized.startsWith('fe9') ||
+        normalized.startsWith('fea') || normalized.startsWith('feb')) return true;
+    // fc00::/7 (unique local)
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+    // ::ffff:x.x.x.x (IPv4-mapped IPv6)
+    if (normalized.startsWith('0000:0000:0000:0000:0000:ffff:')) {
+      const lastTwo = normalized.slice(30); // e.g., "7f00:0001"
+      const hi = parseInt(lastTwo.slice(0, 4), 16);
+      const lo = parseInt(lastTwo.slice(5, 9), 16);
+      const ipv4 = ((hi << 16) | lo) >>> 0;
+      return isPrivateIPv4Numeric(ipv4);
+    }
+    return false;
+  }
+
+  // IPv4: parse to numeric
+  const num = parseIPv4ToNumber(ip);
+  if (num === null) return false;
+  return isPrivateIPv4Numeric(num);
+}
+
+/**
+ * Parse an IPv4 address string to a 32-bit unsigned number.
+ * Handles standard dotted-decimal (e.g. "127.0.0.1").
+ */
+function parseIPv4ToNumber(ip: string): number | null {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+
+  let result = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    result = (result << 8) | n;
+  }
+  return result >>> 0; // unsigned
+}
+
+/**
+ * Check if a numeric IPv4 address is in a private/internal range.
+ */
+function isPrivateIPv4Numeric(ip: number): boolean {
+  // 127.0.0.0/8 (loopback)
+  if ((ip >>> 24) === 127) return true;
+  // 10.0.0.0/8
+  if ((ip >>> 24) === 10) return true;
+  // 172.16.0.0/12
+  if ((ip >>> 20) === (172 << 4 | 1)) return true; // 0xAC1 = 172.16-31
+  // 192.168.0.0/16
+  if ((ip >>> 16) === (192 << 8 | 168)) return true; // 0xC0A8
+  // 169.254.0.0/16 (link-local)
+  if ((ip >>> 16) === (169 << 8 | 254)) return true; // 0xA9FE
+  // 0.0.0.0
+  if (ip === 0) return true;
+  return false;
+}
+
+/**
+ * Normalize an IPv6 address to its full expanded form.
+ */
+function normalizeIPv6(ip: string): string {
+  // Handle IPv4-mapped addresses like ::ffff:127.0.0.1
+  const v4MappedMatch = ip.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (v4MappedMatch) {
+    const v4num = parseIPv4ToNumber(v4MappedMatch[1]);
+    if (v4num !== null) {
+      const hi = (v4num >>> 16) & 0xffff;
+      const lo = v4num & 0xffff;
+      return `0000:0000:0000:0000:0000:ffff:${hi.toString(16).padStart(4, '0')}:${lo.toString(16).padStart(4, '0')}`;
+    }
+  }
+
+  let parts = ip.split(':');
+  // Handle :: expansion
+  const emptyIndex = parts.indexOf('');
+  if (ip.includes('::')) {
+    const before = ip.split('::')[0].split(':').filter(Boolean);
+    const after = ip.split('::')[1].split(':').filter(Boolean);
+    const missing = 8 - before.length - after.length;
+    parts = [...before, ...Array(missing).fill('0'), ...after];
+  }
+
+  return parts.map((p) => (p || '0').padStart(4, '0').toLowerCase()).join(':');
+}
+
+/**
+ * Check if a hostname looks like a numeric IP (decimal, hex, octal)
+ * that could bypass string-based checks.
+ */
+function isNumericHostname(hostname: string): boolean {
+  // Pure decimal number (e.g., 2130706433 for 127.0.0.1)
+  if (/^\d+$/.test(hostname)) return true;
+  // Hex number (e.g., 0x7f000001)
+  if (/^0x[0-9a-fA-F]+$/i.test(hostname)) return true;
+  // Octal parts (e.g., 0177.0.0.1)
+  if (/^[0-7]+\./.test(hostname) && hostname.startsWith('0') && !hostname.startsWith('0.')) return true;
+  return false;
+}
+
+/**
+ * Validates a URL for browser navigation.
+ * Returns null if valid, or an error message string.
+ *
+ * Blocks:
+ * - Non http/https protocols (file:, javascript:, data:, blob:)
+ * - Private/internal IP addresses (127.x, 10.x, 192.168.x, 172.16-31.x, 169.254.x, localhost)
+ * - Numeric IP bypasses (decimal, hex, octal encodings)
+ * - IPv6-mapped IPv4 addresses (::ffff:127.0.0.1)
+ */
+export function validateUrl(url: string, options?: ValidatorOptions): string | null {
+  if (!url || typeof url !== 'string') {
+    return 'URL must be a non-empty string';
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return 'Invalid URL format';
+  }
+
+  // Check blocked protocols
+  if (BLOCKED_PROTOCOLS.includes(parsed.protocol)) {
+    return `Blocked protocol: ${parsed.protocol} — only http: and https: are allowed`;
+  }
+
+  // Only allow http and https
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return `Blocked protocol: ${parsed.protocol} — only http: and https: are allowed`;
+  }
+
+  const hostname = parsed.hostname;
+
+  // Check blocklist first (takes priority)
+  if (options?.blockedUrls?.some((pattern) => hostname.includes(pattern))) {
+    return `URL blocked by blocklist: ${hostname}`;
+  }
+
+  // Check if in allowlist (skip private IP check if allowed)
+  const isAllowed = options?.allowedUrls?.some((pattern) => hostname.includes(pattern));
+  if (isAllowed) {
+    return null;
+  }
+
+  // Block numeric IP encodings (decimal, hex, octal) that could bypass string checks
+  if (isNumericHostname(hostname)) {
+    return `Blocked numeric IP encoding: ${hostname}`;
+  }
+
+  // Block localhost
+  if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+    return `Blocked private/internal address: ${hostname}`;
+  }
+
+  // Check if hostname is an IP address
+  const ipVersion = isIP(hostname);
+  if (ipVersion > 0) {
+    // It's a direct IP — check against private ranges numerically
+    if (isPrivateIP(hostname)) {
+      return `Blocked private/internal address: ${hostname}`;
+    }
+  }
+
+  // Check hostnames that resolve to IPv6 loopback patterns
+  if (hostname.startsWith('[') && hostname.endsWith(']')) {
+    const innerIP = hostname.slice(1, -1);
+    if (isPrivateIP(innerIP)) {
+      return `Blocked private/internal address: ${hostname}`;
+    }
+  }
+
+  return null;
+}
+
+// Export for testing
+export { isPrivateIP, parseIPv4ToNumber, isNumericHostname, normalizeIPv6 };

package/tests/browser-actions.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BrowserManager } from '../src/browser-manager.js';
+
+// --- Mock factories ---
+
+function createMockPage(overrides: Record<string, any> = {}) {
+  return {
+    isClosed: vi.fn().mockReturnValue(false),
+    close: vi.fn().mockResolvedValue(undefined),
+    goto: vi.fn().mockResolvedValue(undefined),
+    title: vi.fn().mockResolvedValue('Test Page'),
+    url: vi.fn().mockReturnValue('https://example.com'),
+    content: vi.fn().mockResolvedValue('<html><body><h1>Hello</h1></body></html>'),
+    click: vi.fn().mockResolvedValue(undefined),
+    fill: vi.fn().mockResolvedValue(undefined),
+    screenshot: vi.fn().mockResolvedValue(Buffer.from('fake-png')),
+    $: vi.fn().mockResolvedValue(null),
+    $$eval: vi.fn().mockResolvedValue([]),
+    evaluate: vi.fn().mockResolvedValue({}),
+    waitForSelector: vi.fn().mockResolvedValue(undefined),
+    setViewportSize: vi.fn().mockResolvedValue(undefined),
+    setDefaultNavigationTimeout: vi.fn(),
+    setDefaultTimeout: vi.fn(),
+    keyboard: {
+      press: vi.fn().mockResolvedValue(undefined),
+    },
+    ...overrides,
+  };
+}
+
+function createMockContext(overrides: Record<string, any> = {}) {
+  const mockPage = createMockPage();
+  return {
+    newPage: vi.fn().mockResolvedValue(mockPage),
+    close: vi.fn().mockResolvedValue(undefined),
+    _mockPage: mockPage,
+    ...overrides,
+  };
+}
+
+function createMockBrowser(overrides: Record<string, any> = {}) {
+  const mockContext = createMockContext();
+  return {
+    isConnected: vi.fn().mockReturnValue(true),
+    newContext: vi.fn().mockResolvedValue(mockContext),
+    close: vi.fn().mockResolvedValue(undefined),
+    _mockContext: mockContext,
+    ...overrides,
+  };
+}
+
+// --- Tests ---
+
+describe('BrowserManager Actions', () => {
+  let mockBrowser: ReturnType<typeof createMockBrowser>;
+  let mockPage: ReturnType<typeof createMockPage>;
+  let browserFactory: ReturnType<typeof vi.fn>;
+  let manager: BrowserManager;
+
+  beforeEach(async () => {
+    mockBrowser = createMockBrowser();
+    mockPage = mockBrowser._mockContext._mockPage;
+    browserFactory = vi.fn().mockResolvedValue(mockBrowser);
+    manager = new BrowserManager({
+      browserFactory,
+      config: { screenshotDir: '' } as any,
+    });
+  });
+
+  describe('navigate', () => {
+    it('should return page info after navigation', async () => {
+      const result = await manager.navigate('s1', 'https://example.com');
+      expect(result.url).toBe('https://example.com');
+      expect(result.title).toBe('Test Page');
+      expect(result.content).toBeDefined();
+      expect(mockPage.goto).toHaveBeenCalledWith('https://example.com', { waitUntil: 'domcontentloaded' });
+    });
+
+    it('should reject blocked URLs', async () => {
+      await expect(
+        manager.navigate('s1', 'https://evil.com', )
+      ).resolves.toBeDefined(); // not blocked by default
+
+      const blockedManager = new BrowserManager({
+        browserFactory,
+        config: { blockedUrls: ['evil.com'], screenshotDir: '' } as any,
+      });
+      await expect(
+        blockedManager.navigate('s1', 'https://evil.com')
+      ).rejects.toThrow('blocked');
+    });
+
+    it('should reject private IPs', async () => {
+      await expect(
+        manager.navigate('s1', 'http://127.0.0.1')
+      ).rejects.toThrow('private');
+    });
+  });
+
+  describe('click', () => {
+    it('should call page.click with selector and timeout', async () => {
+      await manager.click('s1', '#btn');
+      expect(mockPage.click).toHaveBeenCalledWith('#btn', expect.objectContaining({ timeout: expect.any(Number) }));
+    });
+  });
+
+  describe('type', () => {
+    it('should fill input with text', async () => {
+      await manager.type('s1', '#input', 'hello');
+      expect(mockPage.fill).toHaveBeenCalledWith('#input', 'hello');
+      expect(mockPage.keyboard.press).not.toHaveBeenCalled();
+    });
+
+    it('should press Enter when requested', async () => {
+      await manager.type('s1', '#input', 'hello', true);
+      expect(mockPage.fill).toHaveBeenCalledWith('#input', 'hello');
+      expect(mockPage.keyboard.press).toHaveBeenCalledWith('Enter');
+    });
+  });
+
+  describe('extract', () => {
+    it('should return elements by selector', async () => {
+      const mockElements = [
+        { text: 'Hello', tagName: 'h1', attributes: { class: 'title' } },
+      ];
+      mockPage.$$eval.mockResolvedValue(mockElements);
+
+      const result = await manager.extract('s1', 'h1');
+      expect(result.selector).toBe('h1');
+      expect(result.elements).toEqual(mockElements);
+    });
+  });
+
+  describe('wait', () => {
+    it('should wait for selector', async () => {
+      await manager.wait('s1', '.loaded');
+      expect(mockPage.waitForSelector).toHaveBeenCalledWith('.loaded', expect.objectContaining({ timeout: expect.any(Number) }));
+    });
+
+    it('should wait for fixed delay', async () => {
+      const start = Date.now();
+      await manager.wait('s1', 50);
+      const elapsed = Date.now() - start;
+      expect(elapsed).toBeGreaterThanOrEqual(40); // allow small timing margin
+    });
+  });
+
+  describe('runScript', () => {
+    it('should return JSON result', async () => {
+      mockPage.evaluate.mockResolvedValue({ answer: 42 });
+      const result = await manager.runScript('s1', 'document.title');
+      expect(result).toBe('{"answer":42}');
+    });
+
+    it('should reject oversized results', async () => {
+      const bigObj = { data: 'x'.repeat(200_000) };
+      mockPage.evaluate.mockResolvedValue(bigObj);
+      await expect(manager.runScript('s1', 'big()')).rejects.toThrow('Result too large');
+    });
+  });
+
+  describe('screenshot', () => {
+    it('should capture full-page screenshot as base64', async () => {
+      const fakeBuffer = Buffer.from('png-data');
+      mockPage.screenshot.mockResolvedValue(fakeBuffer);
+
+      const result = await manager.screenshot('s1');
+      expect(result.base64).toBe(fakeBuffer.toString('base64'));
+      expect(mockPage.screenshot).toHaveBeenCalledWith(expect.objectContaining({ fullPage: true, type: 'png' }));
+    });
+  });
+
+  describe('browse', () => {
+    it('should return mutation message for write tasks', async () => {
+      const result = await manager.browse('s1', 'Click the login button');
+      expect(result.result).toContain('interactions');
+      expect(result.steps).toEqual([]);
+    });
+
+    it('should handle read tasks', async () => {
+      const result = await manager.browse('s1', 'Find the pricing information');
+      expect(result.result).toContain('Browse task queued');
+    });
+  });
+});

package/tests/browser-manager.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BrowserManager } from '../src/browser-manager.js';
+
+// --- Mock factories ---
+
+function createMockPage(overrides: Record<string, any> = {}) {
+  return {
+    isClosed: vi.fn().mockReturnValue(false),
+    close: vi.fn().mockResolvedValue(undefined),
+    goto: vi.fn().mockResolvedValue(undefined),
+    title: vi.fn().mockResolvedValue('Test Page'),
+    url: vi.fn().mockReturnValue('https://example.com'),
+    content: vi.fn().mockResolvedValue('<html><body><h1>Hello</h1></body></html>'),
+    click: vi.fn().mockResolvedValue(undefined),
+    fill: vi.fn().mockResolvedValue(undefined),
+    screenshot: vi.fn().mockResolvedValue(Buffer.from('fake-png')),
+    $: vi.fn().mockResolvedValue(null),
+    $$eval: vi.fn().mockResolvedValue([]),
+    evaluate: vi.fn().mockResolvedValue({}),
+    waitForSelector: vi.fn().mockResolvedValue(undefined),
+    setViewportSize: vi.fn().mockResolvedValue(undefined),
+    setDefaultNavigationTimeout: vi.fn(),
+    setDefaultTimeout: vi.fn(),
+    keyboard: {
+      press: vi.fn().mockResolvedValue(undefined),
+    },
+    ...overrides,
+  };
+}
+
+function createMockContext(overrides: Record<string, any> = {}) {
+  const mockPage = createMockPage();
+  return {
+    newPage: vi.fn().mockResolvedValue(mockPage),
+    close: vi.fn().mockResolvedValue(undefined),
+    _mockPage: mockPage,
+    ...overrides,
+  };
+}
+
+function createMockBrowser(overrides: Record<string, any> = {}) {
+  const mockContext = createMockContext();
+  return {
+    isConnected: vi.fn().mockReturnValue(true),
+    newContext: vi.fn().mockResolvedValue(mockContext),
+    close: vi.fn().mockResolvedValue(undefined),
+    _mockContext: mockContext,
+    ...overrides,
+  };
+}
+
+// --- Tests ---
+
+describe('BrowserManager', () => {
+  let mockBrowser: ReturnType<typeof createMockBrowser>;
+  let browserFactory: ReturnType<typeof vi.fn>;
+  let manager: BrowserManager;
+
+  beforeEach(() => {
+    mockBrowser = createMockBrowser();
+    browserFactory = vi.fn().mockResolvedValue(mockBrowser);
+    manager = new BrowserManager({
+      browserFactory,
+      config: { screenshotDir: '' } as any,
+    });
+  });
+
+  describe('launch and shutdown', () => {
+    it('should launch browser on first use', async () => {
+      await manager.launch();
+      expect(browserFactory).toHaveBeenCalledTimes(1);
+      expect(mockBrowser.newContext).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not re-launch if already running', async () => {
+      await manager.launch();
+      await manager.launch();
+      expect(browserFactory).toHaveBeenCalledTimes(1);
+    });
+
+    it('should close all pages and browser on shutdown', async () => {
+      await manager.launch();
+      const page = await manager.getPage('session-1');
+      await manager.shutdown();
+
+      expect(page.close).toHaveBeenCalled();
+      expect(mockBrowser.close).toHaveBeenCalled();
+      expect(manager.getPageCount()).toBe(0);
+    });
+  });
+
+  describe('page lifecycle', () => {
+    it('should create new page for new session', async () => {
+      const page = await manager.getPage('session-1');
+      expect(page).toBeDefined();
+      expect(page.setViewportSize).toHaveBeenCalled();
+      expect(manager.getPageCount()).toBe(1);
+    });
+
+    it('should reuse existing page for same session', async () => {
+      const page1 = await manager.getPage('session-1');
+      const page2 = await manager.getPage('session-1');
+      expect(page1).toBe(page2);
+      expect(manager.getPageCount()).toBe(1);
+    });
+
+    it('should close a specific page', async () => {
+      const page = await manager.getPage('session-1');
+      await manager.closePage('session-1');
+      expect(page.close).toHaveBeenCalled();
+      expect(manager.getPageCount()).toBe(0);
+    });
+
+    it('should enforce max concurrent pages', async () => {
+      const limitedManager = new BrowserManager({
+        browserFactory,
+        config: { maxConcurrentPages: 2, screenshotDir: '' } as any,
+      });
+
+      await limitedManager.getPage('s1');
+      await limitedManager.getPage('s2');
+      await expect(limitedManager.getPage('s3')).rejects.toThrow('Max concurrent pages');
+    });
+  });
+
+  describe('crash recovery', () => {
+    it('should re-launch browser if disconnected', async () => {
+      await manager.getPage('session-1');
+      expect(browserFactory).toHaveBeenCalledTimes(1);
+
+      // Simulate browser crash
+      mockBrowser.isConnected.mockReturnValue(false);
+
+      // Create a new mock browser for re-launch
+      const newMockBrowser = createMockBrowser();
+      browserFactory.mockResolvedValue(newMockBrowser);
+
+      await manager.getPage('session-2');
+      expect(browserFactory).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/tests/integration.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { BrowserManager } from '../src/browser-manager.js';
+import { DEFAULT_BROWSER_CONFIG } from '../src/types.js';
+import { validateUrl } from '../src/url-validator.js';
+
+function createMockPage(overrides: any = {}) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    title: vi.fn().mockResolvedValue(overrides.title || 'Test Page'),
+    content: vi.fn().mockResolvedValue(
+      overrides.html || '<html><body><h1>Test</h1><p>Content here</p></body></html>'
+    ),
+    url: vi.fn().mockReturnValue(overrides.url || 'https://example.com'),
+    click: vi.fn().mockResolvedValue(undefined),
+    fill: vi.fn().mockResolvedValue(undefined),
+    keyboard: { press: vi.fn().mockResolvedValue(undefined) },
+    screenshot: vi.fn().mockResolvedValue(Buffer.from('screenshot-data')),
+    $: vi.fn().mockResolvedValue(null),
+    $$eval: vi.fn().mockResolvedValue(
+      overrides.elements || [
+        { text: 'Story 1', tagName: 'a', attributes: { href: '/story/1' } },
+        { text: 'Story 2', tagName: 'a', attributes: { href: '/story/2' } },
+      ]
+    ),
+    waitForSelector: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(overrides.evalResult || null),
+    close: vi.fn().mockResolvedValue(undefined),
+    isClosed: vi.fn().mockReturnValue(false),
+    setViewportSize: vi.fn().mockResolvedValue(undefined),
+    setDefaultNavigationTimeout: vi.fn(),
+    setDefaultTimeout: vi.fn(),
+  };
+}
+
+function createMockBrowser(page: any) {
+  const context = {
+    newPage: vi.fn().mockResolvedValue(page),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+  return {
+    newContext: vi.fn().mockResolvedValue(context),
+    isConnected: vi.fn().mockReturnValue(true),
+    close: vi.fn().mockResolvedValue(undefined),
+    contexts: vi.fn().mockReturnValue([context]),
+  };
+}
+
+describe('Browser integration', () => {
+  let manager: BrowserManager;
+
+  afterEach(async () => {
+    if (manager) await manager.shutdown();
+  });
+
+  it('should navigate then extract then screenshot flow', async () => {
+    const mockPage = createMockPage({
+      title: 'Hacker News',
+      url: 'https://news.ycombinator.com',
+    });
+    const mockBrowser = createMockBrowser(mockPage);
+
+    manager = new BrowserManager({
+      config: { ...DEFAULT_BROWSER_CONFIG, screenshotDir: '' },
+      browserFactory: vi.fn().mockResolvedValue(mockBrowser),
+    });
+
+    // Navigate
+    const navResult = await manager.navigate('s1', 'https://news.ycombinator.com');
+    expect(navResult.title).toBe('Hacker News');
+    expect(navResult.url).toBe('https://news.ycombinator.com');
+
+    // Extract
+    const extractResult = await manager.extract('s1', '.storylink');
+    expect(extractResult.elements).toHaveLength(2);
+    expect(extractResult.elements[0].text).toBe('Story 1');
+
+    // Screenshot
+    const screenshotResult = await manager.screenshot('s1');
+    expect(screenshotResult.base64).toBeDefined();
+    expect(screenshotResult.base64.length).toBeGreaterThan(0);
+  });
+
+  it('should isolate multi-session pages', async () => {
+    const page1 = createMockPage({ title: 'Page 1', url: 'https://site1.com' });
+    const page2 = createMockPage({ title: 'Page 2', url: 'https://site2.com' });
+
+    let callCount = 0;
+    const context = {
+      newPage: vi.fn().mockImplementation(async () => {
+        callCount++;
+        return callCount === 1 ? page1 : page2;
+      }),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const mockBrowser = {
+      newContext: vi.fn().mockResolvedValue(context),
+      isConnected: vi.fn().mockReturnValue(true),
+      close: vi.fn().mockResolvedValue(undefined),
+      contexts: vi.fn().mockReturnValue([context]),
+    };
+
+    manager = new BrowserManager({
+      config: DEFAULT_BROWSER_CONFIG,
+      browserFactory: vi.fn().mockResolvedValue(mockBrowser),
+    });
+
+    const nav1 = await manager.navigate('session-a', 'https://site1.com');
+    const nav2 = await manager.navigate('session-b', 'https://site2.com');
+
+    expect(nav1.title).toBe('Page 1');
+    expect(nav2.title).toBe('Page 2');
+    expect(manager.getPageCount()).toBe(2);
+  });
+
+  it('should enforce URL validation throughout the stack', () => {
+    expect(validateUrl('file:///etc/passwd')).not.toBeNull();
+    expect(validateUrl('javascript:alert(1)')).not.toBeNull();
+    expect(validateUrl('http://127.0.0.1')).not.toBeNull();
+    expect(validateUrl('http://10.0.0.1:8080')).not.toBeNull();
+
+    expect(validateUrl('https://example.com')).toBeNull();
+    expect(validateUrl('https://news.ycombinator.com')).toBeNull();
+  });
+
+  it('should handle browse mutation detection', async () => {
+    const mockPage = createMockPage();
+    const mockBrowser = createMockBrowser(mockPage);
+
+    manager = new BrowserManager({
+      config: DEFAULT_BROWSER_CONFIG,
+      browserFactory: vi.fn().mockResolvedValue(mockBrowser),
+    });
+
+    const mutationResult = await manager.browse('s1', 'click the buy button');
+    expect(mutationResult.result).toContain('primitive browser tools');
+
+    const readResult = await manager.browse('s1', 'get the price of BTC');
+    expect(readResult.result).toBeDefined();
+  });
+});