@bubstack/moe-glass 0.1.0

package/skills/browsing/lib/select-option.js

@@ -0,0 +1,99 @@
+const { getElementSelectorAll } = require('./element-selector');
+const { throwIfExceptionDetails } = require('./cdp-utils');
+
+/**
+ * Native HTML `<select>` element control.
+ *
+ * Each requested value matches an `<option>` by its `value` attribute
+ * first, then by trimmed visible label. Arrays of values require a
+ * `<select multiple>` — passing more than one to a single-select is an
+ * error. Selection replaces (every existing `selected` is cleared
+ * before applying the new set), matching Playwright's `selectOption`
+ * semantics.
+ *
+ * Multi-element warning (JRV-129): if the selector matches more than
+ * one element on the page, we use the element at `index` (default 0)
+ * and emit a warning so the caller knows the selector is ambiguous.
+ *
+ * `attachSelectOption({ getPageSession })` returns the bound action.
+ */
+function attachSelectOption({ getPageSession }) {
+  async function selectOption(tabIndexOrWsUrl, selector, value, index = 0) {
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+    const values = Array.isArray(value) ? value : [value];
+
+    const countJs = `${getElementSelectorAll(selector)}.length`;
+    const countResult = await pageSession.send('Runtime.evaluate', {
+      expression: countJs,
+      returnByValue: true
+    });
+    throwIfExceptionDetails(countResult);
+    const matchCount = countResult.result.value || 0;
+
+    let warning = null;
+    if (matchCount > 1) {
+      warning = `Selector "${selector}" matches ${matchCount} elements. Using element at index ${index}. Use a more specific selector or pass index parameter.`;
+      console.error(`WARNING: ${warning}`);
+    }
+
+    const js = `
+      (() => {
+        const elements = ${getElementSelectorAll(selector)};
+        const el = elements[${index}];
+        if (!el) return { success: false, error: 'Element not found at index ${index}' };
+        if (el.tagName !== 'SELECT') return { success: false, error: 'Element is not a SELECT' };
+
+        const requested = ${JSON.stringify(values)};
+        if (requested.length > 1 && !el.multiple) {
+          return { success: false, error: 'Cannot select multiple values on a non-multiple <select>' };
+        }
+
+        const options = Array.from(el.options);
+        const matched = [];
+        const unmatched = [];
+        for (const v of requested) {
+          const opt = options.find(o => o.value === v) ||
+                      options.find(o => o.textContent.trim() === v);
+          if (opt) matched.push(opt);
+          else unmatched.push(v);
+        }
+        if (unmatched.length) {
+          return { success: false, error: 'No matching option for: ' + JSON.stringify(unmatched) };
+        }
+
+        for (const o of options) o.selected = false;
+        for (const o of matched) o.selected = true;
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+
+        return {
+          success: true,
+          matchCount: elements.length,
+          matched: matched.map(o => ({ value: o.value, text: o.textContent.trim() }))
+        };
+      })()
+    `;
+
+    const result = await pageSession.send('Runtime.evaluate', {
+      expression: js,
+      returnByValue: true
+    });
+    throwIfExceptionDetails(result);
+
+    const resultValue = result.result.value;
+    if (!resultValue.success) {
+      throw new Error(resultValue.error);
+    }
+
+    return {
+      success: true,
+      matchCount: resultValue.matchCount,
+      matched: resultValue.matched,
+      warning,
+      selectedIndex: index
+    };
+  }
+
+  return { selectOption };
+}
+
+module.exports = { attachSelectOption };

package/skills/browsing/lib/session-state.js

@@ -0,0 +1,66 @@
+const { createOverride } = require('../host-override');
+
+/**
+ * Build the per-session mutable state bag.
+ *
+ * Every Chrome session has a small set of mutable values that the rest of
+ * the library reads and writes: the active CDP port, per-tab
+ * console-message buffers, the launched Chrome process handle, the chosen
+ * profile name and data directory, the headless flag, and the auto-capture
+ * session directory and counter.
+ *
+ * Pulling them into one object (and one file) makes the per-session
+ * surface explicit, lets methods that get extracted to sibling files
+ * accept it as a single parameter, and keeps the rest of chrome-ws-lib
+ * focused on behaviour rather than state.
+ *
+ * `host`/`port` are forwarded to `createOverride` to seed the per-session
+ * host-override; omitting them seeds from the `CHROME_WS_HOST` /
+ * `CHROME_WS_PORT` env vars (see host-override.js).
+ */
+function createState({ host, port } = {}) {
+  const hostOverride = createOverride({ host, port });
+
+  // CHROME_WS_PROFILE is the way to opt into a stable named profile from
+  // outside this process — typically used to share a Chrome instance across
+  // MCP restarts or between cooperating tools. When it's set, we treat the
+  // profile as explicit and skip auto-disambiguation in chrome-process.js.
+  const envProfile = process.env.CHROME_WS_PROFILE;
+  const profileFromEnv = envProfile && /^[a-zA-Z0-9_-]+$/.test(envProfile)
+    ? envProfile
+    : null;
+
+  return {
+    hostOverride,
+    rewriteWsUrl: hostOverride.rewriteWsUrl,
+
+    // Dynamic port: updated by startChrome() when Chrome launches or reconnects.
+    activePort: hostOverride.getPort(),
+
+    // Per-tab buffer of console messages for auto-capture.
+    consoleMessages: new Map(),
+
+    // Auto-capture session: lazily initialised on first capture.
+    sessionDir: null,
+    captureCounter: 0,
+
+    // Chrome process management.
+    chromeProcess: null,
+    chromeHeadless: true,
+    chromeUserDataDir: null,
+    chromeProfileName: profileFromEnv || 'moe-glass',
+    // True when the profile name came from env/set_profile rather than the
+    // default. chrome-process.js uses this to decide whether to auto-pick an
+    // unused alternate name on startup.
+    _profileExplicit: profileFromEnv !== null,
+
+    // Bridge primitives: the session's BrowserBridge instance and active BrowserSession.
+    browserBridge: null,
+    browserSession: null,
+
+    // Sticky tab state: updated by switch_tab, new_tab, close_tab.
+    activeTab: 0,
+  };
+}
+
+module.exports = { createState };

package/skills/browsing/lib/tabs.js

@@ -0,0 +1,144 @@
+const { chromeHttpAt } = require('./chrome-launcher-helpers');
+
+/**
+ * Tab management plus the two transport helpers it depends on:
+ *
+ *   - `chromeHttp` — the per-session HTTP client, bound to
+ *     `state.activePort` and the session's host-override.
+ *   - `resolveWsUrl` — accept a tab index, a numeric string, or a `ws://`
+ *     URL and return a usable WebSocket URL. Auto-creates a tab if none
+ *     exist (mirrors the auto-start-Chrome behaviour).
+ *   - `getTabs` / `newTab` / `closeTab` — list, open, close. List/open
+ *     rewrite the returned `webSocketDebuggerUrl` through the session's
+ *     host-override so the URL can actually be connected to from the
+ *     calling process even when the host-override remaps host/port.
+ *
+ * All three helpers feed every other attach* in the library, so this
+ * module is the foundation the rest sits on.
+ *
+ * `attachTabs({ state })` returns the bound API. The session state bag
+ * carries the host-override (for `getHost` and `rewriteWsUrl`) and the
+ * mutable `activePort`, which is everything the transport helpers need.
+ */
+function attachTabs({ state, _chromeHttp }) {
+  const CHROME_DEBUG_HOST = state.hostOverride.getHost();
+  const { rewriteWsUrl } = state;
+
+  // HTTP request to Chrome's DevTools endpoint on the session's active port.
+  // _chromeHttp may be injected for testing; state.chromeHttp is also accepted.
+  async function chromeHttp(httpPath, method = 'GET') {
+    if (_chromeHttp) return _chromeHttp(httpPath, method);
+    return chromeHttpAt(CHROME_DEBUG_HOST, state.activePort, httpPath, method);
+  }
+
+  async function resolveWsUrl(wsUrlOrIndex) {
+    if (typeof wsUrlOrIndex === 'string' && wsUrlOrIndex.startsWith('ws://')) {
+      return rewriteWsUrl(wsUrlOrIndex, CHROME_DEBUG_HOST, state.activePort);
+    }
+
+    const index = typeof wsUrlOrIndex === 'number' ? wsUrlOrIndex : parseInt(wsUrlOrIndex);
+    if (!isNaN(index)) {
+      const tabs = await chromeHttp('/json');
+      if (!Array.isArray(tabs)) {
+        throw new Error('Chrome DevTools returned an invalid response — is Chrome running?');
+      }
+      const pageTabs = tabs.filter(t => t.type === 'page');
+
+      // Auto-create tab if none exist (matches the auto-start-Chrome behaviour
+      // — callers shouldn't have to special-case "fresh Chrome with no tabs").
+      if (pageTabs.length === 0) {
+        const newTabInfo = await newTab();
+        return newTabInfo.webSocketDebuggerUrl;
+      }
+
+      if (index < 0 || index >= pageTabs.length) {
+        throw new Error(`Tab index ${index} out of range (0-${pageTabs.length - 1})`);
+      }
+      return pageTabs[index].webSocketDebuggerUrl;
+    }
+
+    throw new Error(`Invalid tab specifier: ${wsUrlOrIndex}`);
+  }
+
+  async function getTabs() {
+    const tabs = await chromeHttp('/json');
+    if (!Array.isArray(tabs)) {
+      return [];
+    }
+    return tabs
+      .filter(tab => tab.type === 'page')
+      .map(tab => ({
+        ...tab,
+        webSocketDebuggerUrl: rewriteWsUrl(tab.webSocketDebuggerUrl, CHROME_DEBUG_HOST, state.activePort)
+      }));
+  }
+
+  async function newTab(url = 'about:blank') {
+    const encoded = encodeURIComponent(url);
+    const tab = await chromeHttp(`/json/new?${encoded}`, 'PUT');
+    if (tab && typeof tab === 'object') {
+      tab.webSocketDebuggerUrl = rewriteWsUrl(tab.webSocketDebuggerUrl, CHROME_DEBUG_HOST, state.activePort);
+    }
+    return tab;
+  }
+
+  async function closeTab(tabIndexOrWsUrl) {
+    const wsUrl = await resolveWsUrl(tabIndexOrWsUrl);
+    const tabs = await chromeHttp('/json');
+    if (!Array.isArray(tabs)) return;
+    const tab = tabs.find(t => t.webSocketDebuggerUrl === wsUrl);
+    if (tab) {
+      // Release the cached page-session before Chrome tears down the target.
+      await state.pageSessionResolver?.release(tab.id);
+      await chromeHttp(`/json/close/${tab.id}`, 'GET');
+    }
+  }
+
+  return { chromeHttp, resolveWsUrl, getTabs, newTab, closeTab };
+}
+
+/**
+ * createPageSessionResolver({bridge}) — returns a resolver that caches one
+ * pageSession per tab.id. The cache is keyed by tab.id (which is the CDP
+ * targetId in our model).
+ *
+ * Usage:
+ *   const getPageSession = createPageSessionResolver({ bridge });
+ *   const ps = await getPageSession(tab);     // attaches once
+ *   await getPageSession(tab);                 // returns the cached session
+ *   await getPageSession.release(tab.id);      // detaches + removes cache
+ */
+function createPageSessionResolver({ bridge }) {
+  const cache = new Map();
+  async function resolve(tab) {
+    if (!tab || !tab.id) throw new Error('createPageSessionResolver: tab.id is required');
+    const cached = cache.get(tab.id);
+    if (cached) return cached;
+    const ps = await bridge.attachPageSession(tab.id);
+    cache.set(tab.id, ps);
+    return ps;
+  }
+  resolve.release = async (tabId) => {
+    const ps = cache.get(tabId);
+    if (!ps) return;
+    cache.delete(tabId);
+    try { await ps.detach(); } catch { /* best-effort */ }
+  };
+  // Prime the cache with an already-attached pageSession (from autoAttach).
+  // Subsequent resolve(tab) calls for this targetId return the primed session
+  // instead of issuing a second Target.attachToTarget. No-op if already cached.
+  resolve.prime = (targetId, ps) => {
+    if (!cache.has(targetId)) cache.set(targetId, ps);
+  };
+  // Synchronous cache peek — returns the cached pageSession for a targetId, or
+  // null if not yet resolved. Used by wrapWithDialogGate to check dialog state
+  // without triggering I/O.
+  resolve.peek = (tabId) => cache.get(tabId) || null;
+  // Bulk-clear the cache without calling detach. Use when the underlying WebSocket
+  // is already dead (e.g. Chrome was killed externally) so detach calls would fail.
+  // Callers that want graceful detach should call resolve.release() per-tab first.
+  resolve.releaseAll = () => { cache.clear(); };
+  return resolve;
+}
+
+module.exports = { attachTabs, createPageSessionResolver };

package/skills/browsing/lib/viewport.js

@@ -0,0 +1,103 @@
+// Pixel 7 UA string used for mobile emulation. Matches what Chrome's own
+// device-mode dropdown sends for the same device.
+const MOBILE_USER_AGENT = 'Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36';
+
+/**
+ * Viewport / device emulation — set, clear, and read the CDP
+ * Emulation.setDeviceMetricsOverride state. Mobile emulation toggles touch
+ * input and a Pixel-7-class user-agent string in lockstep with the metrics.
+ *
+ * `attachViewport({ getPageSession })` returns the bound actions.
+ * `getPageSession(tabIndexOrWsUrl)` resolves to a page-session object
+ * with a `send(method, params)` interface.
+ */
+function attachViewport({ getPageSession }) {
+  /**
+   * Set device viewport / emulation parameters (CDP: Emulation.setDeviceMetricsOverride).
+   *
+   * @param {number|string} tabIndexOrWsUrl - Tab index or WebSocket URL
+   * @param {Object} params
+   * @param {number} [params.width=1200] - CSS pixels (320–7680)
+   * @param {number} [params.height=800] - CSS pixels (200–4320)
+   * @param {number} [params.deviceScaleFactor=1] - DPI multiplier (0.25–5)
+   * @param {boolean} [params.mobile=false] - Touch + mobile UA when true
+   */
+  async function setViewport(tabIndexOrWsUrl, params) {
+    if (!params || typeof params !== 'object') {
+      throw new Error('setViewport requires a params object');
+    }
+
+    const ps = await getPageSession(tabIndexOrWsUrl);
+
+    const viewportParams = {
+      width: params.width ?? 1200,
+      height: params.height ?? 800,
+      deviceScaleFactor: params.deviceScaleFactor !== undefined ? params.deviceScaleFactor : 1,
+      mobile: params.mobile === true
+    };
+
+    if (viewportParams.width < 320 || viewportParams.width > 7680) {
+      throw new Error(`Invalid viewport width ${viewportParams.width} (must be 320-7680)`);
+    }
+    if (viewportParams.height < 200 || viewportParams.height > 4320) {
+      throw new Error(`Invalid viewport height ${viewportParams.height} (must be 200-4320)`);
+    }
+    if (viewportParams.deviceScaleFactor < 0.25 || viewportParams.deviceScaleFactor > 5) {
+      throw new Error(`Invalid deviceScaleFactor ${viewportParams.deviceScaleFactor} (must be 0.25-5)`);
+    }
+
+    await ps.send('Emulation.setDeviceMetricsOverride', viewportParams);
+
+    if (viewportParams.mobile) {
+      await ps.send('Emulation.setTouchEmulationEnabled', { enabled: true });
+      await ps.send('Emulation.setUserAgentOverride', { userAgent: MOBILE_USER_AGENT });
+    } else {
+      await ps.send('Emulation.setTouchEmulationEnabled', { enabled: false });
+      // Empty UA string resets to browser default (CDP convention)
+      await ps.send('Emulation.setUserAgentOverride', { userAgent: '' });
+    }
+
+    return { ...viewportParams, touch: viewportParams.mobile };
+  }
+
+  /**
+   * Clear viewport emulation (reset to browser default). Clears device
+   * metrics, touch emulation, and UA override.
+   */
+  async function clearViewport(tabIndexOrWsUrl) {
+    const ps = await getPageSession(tabIndexOrWsUrl);
+    await ps.send('Emulation.clearDeviceMetricsOverride', {});
+    await ps.send('Emulation.setTouchEmulationEnabled', { enabled: false });
+    await ps.send('Emulation.setUserAgentOverride', { userAgent: '' });
+  }
+
+  /**
+   * Get current viewport dimensions from the browser.
+   * Returns { innerWidth, innerHeight, outerWidth, outerHeight,
+   *          devicePixelRatio, orientation }.
+   */
+  async function getViewport(tabIndexOrWsUrl) {
+    const ps = await getPageSession(tabIndexOrWsUrl);
+
+    const result = await ps.send('Runtime.evaluate', {
+      expression: `({
+        innerWidth: window.innerWidth,
+        innerHeight: window.innerHeight,
+        outerWidth: window.outerWidth,
+        outerHeight: window.outerHeight,
+        devicePixelRatio: window.devicePixelRatio,
+        orientation: screen.orientation ? screen.orientation.type : 'unknown'
+      })`,
+      returnByValue: true
+    });
+
+    if (result.exceptionDetails) {
+      throw new Error(`getViewport failed: ${result.exceptionDetails.text}`);
+    }
+    return result.result?.value || {};
+  }
+
+  return { setViewport, clearViewport, getViewport };
+}
+
+module.exports = { attachViewport };

package/skills/browsing/lib/websocket-client.js

@@ -0,0 +1,162 @@
+const http = require('http');
+const crypto = require('crypto');
+
+/**
+ * Minimal dependency-free WebSocket client used for CDP transport.
+ *
+ * We don't pull in `ws` or any other npm package: the MCP server is shipped
+ * as a single bundled file and the browsing skill is a plain script, so a
+ * zero-dependency Node-only implementation keeps both distribution paths
+ * trivial. Only the slice of RFC 6455 we actually need is implemented:
+ * client-side handshake, masked text frames out, unmasked text frames in
+ * (with 7/16/64-bit length fields), and best-effort close.
+ *
+ * Event interface mirrors the `ws` package: `on('open'|'message'|'error'|
+ * 'close', cb)`. `connect()` returns a Promise that resolves once the
+ * upgrade completes.
+ */
+class WebSocketClient {
+  constructor(url) {
+    this.url = new URL(url);
+    this.callbacks = {};
+    this.socket = null;
+    this.buffer = Buffer.alloc(0);
+    this.connected = false;
+  }
+
+  on(event, callback) {
+    this.callbacks[event] = callback;
+  }
+
+  isConnected() {
+    return this.connected && this.socket !== null;
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const key = crypto.randomBytes(16).toString('base64');
+
+      const options = {
+        hostname: this.url.hostname,
+        port: this.url.port || 80,
+        path: this.url.pathname + this.url.search,
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Sec-WebSocket-Key': key,
+          'Sec-WebSocket-Version': '13'
+        }
+      };
+
+      const req = http.request(options);
+
+      req.on('upgrade', (_res, socket) => {
+        this.socket = socket;
+        this.connected = true;
+
+        socket.on('data', (data) => {
+          this.buffer = Buffer.concat([this.buffer, data]);
+          this.processFrames();
+        });
+
+        socket.on('error', (err) => {
+          this.connected = false;
+          if (this.callbacks.error) this.callbacks.error(err);
+        });
+
+        socket.on('close', () => {
+          this.connected = false;
+          if (this.callbacks.close) this.callbacks.close();
+        });
+
+        if (this.callbacks.open) this.callbacks.open();
+        resolve();
+      });
+
+      req.on('error', reject);
+      req.end();
+    });
+  }
+
+  processFrames() {
+    while (this.buffer.length >= 2) {
+      const firstByte = this.buffer[0];
+      const secondByte = this.buffer[1];
+
+      const _fin = (firstByte & 0x80) !== 0;
+      const opcode = firstByte & 0x0F;
+      const _masked = (secondByte & 0x80) !== 0;
+      let payloadLen = secondByte & 0x7F;
+
+      let offset = 2;
+
+      if (payloadLen === 126) {
+        if (this.buffer.length < 4) return;
+        payloadLen = this.buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (payloadLen === 127) {
+        if (this.buffer.length < 10) return;
+        payloadLen = Number(this.buffer.readBigUInt64BE(2));
+        offset = 10;
+      }
+
+      if (this.buffer.length < offset + payloadLen) return;
+
+      const payload = this.buffer.slice(offset, offset + payloadLen);
+      this.buffer = this.buffer.slice(offset + payloadLen);
+
+      if (opcode === 0x1 && this.callbacks.message) {
+        this.callbacks.message(payload.toString('utf8'));
+      }
+    }
+  }
+
+  send(data) {
+    if (!this.socket || !this.connected) {
+      throw new Error('WebSocket not connected');
+    }
+    const payload = Buffer.from(data, 'utf8');
+    const payloadLen = payload.length;
+
+    let frame;
+    let offset = 2;
+
+    if (payloadLen < 126) {
+      frame = Buffer.alloc(payloadLen + 6);
+      frame[1] = payloadLen | 0x80;
+    } else if (payloadLen < 65536) {
+      frame = Buffer.alloc(payloadLen + 8);
+      frame[1] = 126 | 0x80;
+      frame.writeUInt16BE(payloadLen, 2);
+      offset = 4;
+    } else {
+      frame = Buffer.alloc(payloadLen + 14);
+      frame[1] = 127 | 0x80;
+      frame.writeBigUInt64BE(BigInt(payloadLen), 2);
+      offset = 10;
+    }
+
+    frame[0] = 0x81; // FIN + text frame
+
+    const mask = Buffer.alloc(4);
+    crypto.randomFillSync(mask);
+    mask.copy(frame, offset);
+    offset += 4;
+
+    for (let i = 0; i < payloadLen; i++) {
+      frame[offset + i] = payload[i] ^ mask[i % 4];
+    }
+
+    this.socket.write(frame);
+  }
+
+  close() {
+    this.connected = false;
+    if (this.socket) {
+      this.socket.end();
+      this.socket = null;
+    }
+  }
+}
+
+module.exports = { WebSocketClient };

package/skills/browsing/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "chrome-ws",
+  "version": "1.0.0",
+  "description": "Lightweight Chrome DevTools Protocol client for direct browser control - zero dependencies",
+  "bin": {
+    "chrome-ws": "./chrome-ws"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/skills/browsing/test-chrome-args.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+const assert = require('assert');
+const path = require('path');
+
+const modulePath = path.join(__dirname, 'chrome-ws-lib.js');
+
+function withEnv(env, fn) {
+  const prev = {};
+  for (const key of Object.keys(env)) {
+    prev[key] = process.env[key];
+    if (env[key] === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = env[key];
+    }
+  }
+  delete require.cache[require.resolve(modulePath)];
+  const mod = require(modulePath).createSession();
+  try {
+    fn(mod);
+  } finally {
+    delete require.cache[require.resolve(modulePath)];
+    for (const key of Object.keys(env)) {
+      if (prev[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prev[key];
+      }
+    }
+  }
+}
+
+const BASE_OPTS = {
+  chosenPort: 9222,
+  chromeUserDataDir: '/tmp/test-profile',
+  chromeHeadless: false,
+};
+
+function run() {
+  withEnv({ CHROME_EXTRA_ARGS: undefined }, ({ buildChromeArgs }) => {
+    assert.strictEqual(typeof buildChromeArgs, 'function', 'buildChromeArgs must be exported');
+    const args = buildChromeArgs(BASE_OPTS);
+    assert.ok(args.includes('--remote-debugging-port=9222'), 'includes the port flag');
+    assert.ok(args.includes('--user-data-dir=/tmp/test-profile'), 'includes the user-data-dir flag');
+    assert.ok(args.includes('--metrics-recording-only'), 'includes an expected baseline flag');
+    assert.ok(buildChromeArgs({ ...BASE_OPTS, noSandbox: true }).includes('--no-sandbox'), 'noSandbox: true adds --no-sandbox');
+    assert.ok(!buildChromeArgs({ ...BASE_OPTS, noSandbox: false }).includes('--no-sandbox'), 'noSandbox: false keeps the sandbox');
+    assert.ok(!args.includes('--headless=new'), 'no headless flag when chromeHeadless is false');
+  });
+
+  withEnv({ CHROME_EXTRA_ARGS: undefined }, ({ buildChromeArgs }) => {
+    const args = buildChromeArgs({ ...BASE_OPTS, chromeHeadless: true });
+    assert.ok(args.includes('--headless=new'), 'headless flag present when chromeHeadless is true');
+  });
+
+  withEnv({ CHROME_EXTRA_ARGS: '--use-gl=angle --use-angle=swiftshader-webgl --enable-unsafe-swiftshader' }, ({ buildChromeArgs }) => {
+    const args = buildChromeArgs(BASE_OPTS);
+    assert.ok(args.includes('--use-gl=angle'), 'extra arg --use-gl=angle appended');
+    assert.ok(args.includes('--use-angle=swiftshader-webgl'), 'extra arg --use-angle=swiftshader-webgl appended');
+    assert.ok(args.includes('--enable-unsafe-swiftshader'), 'extra arg --enable-unsafe-swiftshader appended');
+  });
+
+  withEnv({ CHROME_EXTRA_ARGS: '  --flag-a   --flag-b\t--flag-c\n' }, ({ buildChromeArgs }) => {
+    const args = buildChromeArgs(BASE_OPTS);
+    assert.ok(args.includes('--flag-a'), 'splits on multiple spaces');
+    assert.ok(args.includes('--flag-b'), 'splits on tab');
+    assert.ok(args.includes('--flag-c'), 'splits on newline');
+    assert.ok(!args.includes(''), 'no empty tokens from whitespace runs');
+  });
+
+  withEnv({ CHROME_EXTRA_ARGS: '' }, ({ buildChromeArgs }) => {
+    const baseline = buildChromeArgs.call(null, BASE_OPTS);
+    // An empty env var should not add any tokens
+    assert.strictEqual(baseline.filter(a => a === '').length, 0, 'empty env var does not add empty tokens');
+  });
+
+  console.log('All chrome args tests passed.');
+}
+
+run();

package/skills/browsing/test-cookies.js

@@ -0,0 +1,21 @@
+/**
+ * Simple test for cookie functions
+ * Run with: node test-cookies.js
+ */
+
+const chromeLib = require('./chrome-ws-lib.js').createSession();
+
+async function testCookieFunctionsExist() {
+  console.log('Testing that cookie functions are exported...');
+
+  if (typeof chromeLib.clearCookies !== 'function') {
+    throw new Error('clearCookies not exported');
+  }
+
+  console.log('All cookie functions exported');
+}
+
+testCookieFunctionsExist().catch(err => {
+  console.error('Test failed:', err.message);
+  process.exit(1);
+});