@farmslot/adapter-web 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.4.1 - 2026-10-07
+
+- `network-observer`: `createExtensionNetworkObserver` takes an optional `extensionId`, the extension to capture. Without it the observer still takes the first extension with a target, which in a branded Chrome can be a component or policy extension listed before the one under test.
+- Publish with adapter-sdk 0.6.0 and recipe-runner 0.26.0.
+
+## 0.4.0 - 2026-10-06
+
+- Add `network-observer` (`createExtensionNetworkObserver({ cdpPort, runtimeDir })`) and `performance-observer` (`createExtensionPerformanceBackend({ cdpPort, extensionId, uiPaths, kind, platform, markerPrefix })`), the Extension network and performance observers moved from mm-harness. The network observer attaches to every target of the loaded extension and feeds their Network events to a `@farmslot/recipe-runner/cdp-broker`; it returns an `@farmslot/adapter-sdk` `NetworkCaptureBackend`. The performance observer traces the extension page found at the first of `uiPaths` with exactly one open renderer, through `@farmslot/recipe-runner/runtime/cdp-trace`. Both run on `connectBrowserCdp`; `connectTimeoutMs` and `commandTimeoutMs` default to 10 s. The package now depends on `@farmslot/recipe-runner` and `@farmslot/adapter-sdk`.
+- `browser-cdp`: `connectBrowserCdp` clients gain `onEvent(handler)` (every CDP event, as `{ method, params, sessionId? }`; events were dropped before) and `onClose(handler)` (once, when the socket closes; at once on a client that has already closed), each returning an unsubscribe function. `onEvent` on a closed client keeps nothing. Add `asBrowserCdpTarget` and `extensionIdFromCdpTargets`.
+- `page-target`: add `selectExtensionTarget(targets, extensionId, { paths })`, the extension UI renderer at the first path with any match, or null when that path has several.
+- Publish with adapter-sdk 0.5.1 and recipe-runner 0.26.0.
+
 ## 0.3.1 - 2026-10-06
 
 - Browser probes no longer leave Chrome for Testing running when the resolver is stopped mid-probe (a hook timeout, a signal, or the resolver killed outright): the probe browser and its temporary profile are removed.

package/README.md

@@ -12,21 +12,23 @@ Docs: https://farmslot.io/docs/reference/adapter-web
 
 ## Source layout
 
-| module                         | owns                                                                                                           |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `browser-resolver`             | Chrome for Testing vs branded Chrome, probe-launch and its cache, extension loading method; CLI entry          |
-| `browser-cdp`                  | browser-level CDP client with deadlines, CDP-port ownership proof, `Extensions.loadUnpacked`, window placement |
-| `chrome-args`                  | remote-debugging flags, isolated profile flags, runtime identity nonce, launch quarantine markers              |
-| `dapp`                         | web dapps: strict EIP-1193 test wallet, wallet-request page script and its host binding, wallet request log    |
-| `extension-id`                 | Chromium extension id from a manifest key or an unpacked directory                                             |
-| `launch-browser`               | launch (or release) one isolated, detached, owned Chromium with an unpacked extension                          |
-| `macos-focus`                  | capture the frontmost app before a headed launch and restore it if one of our browsers took it                 |
-| `origin`                       | exact app-origin checks, the app top-frame CDP context check, URLs without query strings                       |
-| `page-target`                  | pick the page on an origin, preferring one whose URL carries a hash                                            |
-| `playwright-cdp`               | page evaluation over a raw CDP session (safe under LavaMoat scuttling)                                         |
-| `slot-title`                   | prefix the extension home tab's title with the farm slot id, kept across the page's own title resets           |
-| `validation-process-ownership` | find and stop the processes that own a slot profile                                                            |
-| `validation-launch-supervisor` | supervised child for one validation launch: port lease, quarantine and cleanup                                 |
+| module                         | owns                                                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `browser-resolver`             | Chrome for Testing vs branded Chrome, probe-launch and its cache, extension loading method; CLI entry                     |
+| `browser-cdp`                  | browser-level CDP client with deadlines and events, CDP-port ownership proof, `Extensions.loadUnpacked`, window placement |
+| `chrome-args`                  | remote-debugging flags, isolated profile flags, runtime identity nonce, launch quarantine markers                         |
+| `dapp`                         | web dapps: strict EIP-1193 test wallet, wallet-request page script and its host binding, wallet request log               |
+| `extension-id`                 | Chromium extension id from a manifest key or an unpacked directory                                                        |
+| `launch-browser`               | launch (or release) one isolated, detached, owned Chromium with an unpacked extension                                     |
+| `macos-focus`                  | capture the frontmost app before a headed launch and restore it if one of our browsers took it                            |
+| `network-observer`             | network capture for every target of a loaded extension, through recipe-runner's CDP broker                                |
+| `origin`                       | exact app-origin checks, the app top-frame CDP context check, URLs without query strings                                  |
+| `page-target`                  | pick the page on an origin, or an extension's UI renderer by path                                                         |
+| `performance-observer`         | CDP performance traces of an extension's UI renderer, through recipe-runner's trace collector                             |
+| `playwright-cdp`               | page evaluation over a raw CDP session (safe under LavaMoat scuttling)                                                    |
+| `slot-title`                   | prefix the extension home tab's title with the farm slot id, kept across the page's own title resets                      |
+| `validation-process-ownership` | find and stop the processes that own a slot profile                                                                       |
+| `validation-launch-supervisor` | supervised child for one validation launch: port lease, quarantine and cleanup                                            |
 
 Sources are CommonJS (`src/**/*.cjs`) and ship as is; `yarn build` emits `.d.cts` declarations. Every library subpath can be `require`d or `import`ed with named imports, except `validation-launch-supervisor`: it is a child-process entry (it runs when loaded), so hosts `require.resolve` it and fork it.
 

package/dist/browser-cdp.d.cts

@@ -1,3 +1,13 @@
+export type BrowserCdpEvent = {
+    method: string;
+    params: Record<string, any>;
+    sessionId?: string;
+};
+export type BrowserCdpTarget = {
+    targetId: string;
+    type: string;
+    url: string;
+};
 export const DEFAULT_COMMAND_TIMEOUT_MS: 15000;
 export const START_TIME_SLACK_MS: 2000;
 /**
@@ -14,6 +24,11 @@ export function assertCdpOwnedByProfile(port: number, profile: string, options?:
     profile: string;
     cdpPort: number;
 };
+/**
+ * @param {unknown} value
+ * @returns {BrowserCdpTarget | null}
+ */
+export function asBrowserCdpTarget(value: unknown): BrowserCdpTarget | null;
 /**
  * @param {{ pid: number, startedAt: string, profile: string, cdpPort: number }} owner
  * @param {{ exec?: typeof defaultExec, timeoutMs?: number }} [options]
@@ -57,14 +72,33 @@ export function waitForCdpOwner(port: any, profile: any, { timeoutMs, exec }?: {
     profile: string;
     cdpPort: number;
 };
+/**
+ * @typedef {{ method: string, params: Record<string, any>, sessionId?: string }} BrowserCdpEvent
+ * @typedef {{ targetId: string, type: string, url: string }} BrowserCdpTarget
+ */
 export function connectBrowserCdp(port: any, { timeoutMs, commandTimeoutMs }?: {
     timeoutMs?: number | undefined;
     commandTimeoutMs?: number | undefined;
 }): Promise<{
-    send: (method: any, params: {} | undefined, sessionId: any, timeout?: number) => Promise<any>;
+    send: (method: string, params?: Record<string, any>, sessionId?: string, timeout?: number) => Promise<any>;
+    /**
+     * @param {(event: BrowserCdpEvent) => void} handler
+     * @returns {() => void}
+     */
+    onEvent: (handler: (event: BrowserCdpEvent) => void) => () => void;
+    /**
+     * @param {() => void} handler
+     * @returns {() => void}
+     */
+    onClose: (handler: () => void) => () => void;
     close: () => void;
 }>;
 export function expectedExtensionId(extensionDir: any): string | null;
+/**
+ * @param {unknown} targets
+ * @returns {string | null}
+ */
+export function extensionIdFromCdpTargets(targets: unknown): string | null;
 export function loadUnpackedExtension(send: any, extensionDir: any, { expectedId, timeoutMs }?: {
     expectedId?: null | undefined;
     timeoutMs?: number | undefined;

package/dist/network-observer.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @param {{ cdpPort: number, runtimeDir: string, extensionId?: string, connectTimeoutMs?: number, commandTimeoutMs?: number }} options
+ *   `runtimeDir` keys the broker socket; the timeouts bound the CDP connection
+ *   and every command, broker call and capture control. `extensionId` names the
+ *   extension to capture; without it, the first extension with a target is
+ *   used, which can be a component or policy extension in a branded Chrome.
+ * @returns {Promise<import('@farmslot/adapter-sdk').NetworkCaptureBackend>}
+ */
+export function createExtensionNetworkObserver({ cdpPort, runtimeDir, extensionId: requestedExtensionId, connectTimeoutMs, commandTimeoutMs, }: {
+    cdpPort: number;
+    runtimeDir: string;
+    extensionId?: string;
+    connectTimeoutMs?: number;
+    commandTimeoutMs?: number;
+}): Promise<import("@farmslot/adapter-sdk").NetworkCaptureBackend>;

package/dist/page-target.d.cts

@@ -1,3 +1,12 @@
+/**
+ * @param {unknown} targets
+ * @param {string} extensionId
+ * @param {{ paths: readonly string[] }} options
+ * @returns {import('./browser-cdp.cjs').BrowserCdpTarget | null}
+ */
+export function selectExtensionTarget(targets: unknown, extensionId: string, { paths }: {
+    paths: readonly string[];
+}): import("./browser-cdp.cjs").BrowserCdpTarget | null;
 export function selectPageTarget(targets: any, { origin, hash }: {
     origin: any;
     hash?: string | undefined;

package/dist/performance-observer.d.cts

@@ -0,0 +1,26 @@
+/**
+ * @template {string} [P=string]
+ * @param {{
+ *   cdpPort: number,
+ *   extensionId: string,
+ *   uiPaths: readonly string[],
+ *   kind: import('@farmslot/recipe-runner/runtime/cdp-trace').TraceKind,
+ *   platform: P,
+ *   markerPrefix?: string,
+ *   connectTimeoutMs?: number,
+ *   commandTimeoutMs?: number,
+ * }} options
+ *   `uiPaths` are the extension pages to trace, in order of preference (see
+ *   `selectExtensionTarget`); `kind`, `platform` and `markerPrefix` go to the collector.
+ * @returns {Promise<import('@farmslot/recipe-runner/runtime/cdp-trace').PerformanceBackend<P>>}
+ */
+export function createExtensionPerformanceBackend<P extends string = string>({ cdpPort, extensionId, uiPaths, kind, platform, markerPrefix, connectTimeoutMs, commandTimeoutMs, }: {
+    cdpPort: number;
+    extensionId: string;
+    uiPaths: readonly string[];
+    kind: import("@farmslot/recipe-runner/runtime/cdp-trace").TraceKind;
+    platform: P;
+    markerPrefix?: string;
+    connectTimeoutMs?: number;
+    commandTimeoutMs?: number;
+}): Promise<import("@farmslot/recipe-runner/runtime/cdp-trace").PerformanceBackend<P>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {
@@ -32,6 +32,10 @@
       "types": "./dist/macos-focus.d.cts",
       "default": "./src/macos-focus.cjs"
     },
+    "./network-observer": {
+      "types": "./dist/network-observer.d.cts",
+      "default": "./src/network-observer.cjs"
+    },
     "./origin": {
       "types": "./dist/origin.d.cts",
       "default": "./src/origin.cjs"
@@ -41,6 +45,10 @@
       "types": "./dist/page-target.d.cts",
       "default": "./src/page-target.cjs"
     },
+    "./performance-observer": {
+      "types": "./dist/performance-observer.d.cts",
+      "default": "./src/performance-observer.cjs"
+    },
     "./playwright-cdp": {
       "types": "./dist/playwright-cdp.d.cts",
       "default": "./src/playwright-cdp.cjs"
@@ -66,11 +74,13 @@
     "lint": "eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\" --fix",
     "quality": "prettier --check --ignore-path ../../.prettierignore . && eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\" && yarn typecheck && yarn test",
-    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "build": "yarn workspace @farmslot/adapter-sdk build && rm -rf dist && tsc --project tsconfig.build.json",
     "prepack": "cd ../.. && node scripts/quality/check-farmslot-package-readiness.mjs --require-changelog --packages @farmslot/adapter-web && yarn workspace @farmslot/adapter-web build",
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/adapter-web"
   },
   "dependencies": {
+    "@farmslot/adapter-sdk": "0.6.0",
+    "@farmslot/recipe-runner": "0.26.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/src/browser-cdp.cjs

@@ -5,6 +5,8 @@
 //
 // Every command has a deadline and every pending command fails when the
 // socket closes, so a browser that dies or stalls never hangs a launcher.
+// Observers subscribe to CDP events (`onEvent`) and to the socket closing
+// (`onClose`) on the same client.
 'use strict';
 
 const { execFileSync } = require('node:child_process');
@@ -21,6 +23,11 @@ function deadlineError(what, ms) {
   return Object.assign(new Error(`${what} did not answer within ${ms}ms`), { code: 'CDP_TIMEOUT' });
 }
 
+/**
+ * @typedef {{ method: string, params: Record<string, any>, sessionId?: string }} BrowserCdpEvent
+ * @typedef {{ targetId: string, type: string, url: string }} BrowserCdpTarget
+ */
+
 async function connectBrowserCdp(
   port,
   { timeoutMs = 30000, commandTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = {},
@@ -45,6 +52,10 @@ async function connectBrowserCdp(
   const WebSocketImpl = globalThis.WebSocket ?? require('ws');
   const socket = new WebSocketImpl(url);
   const pending = new Map();
+  /** @type {Set<(event: BrowserCdpEvent) => void>} */
+  const eventHandlers = new Set();
+  /** @type {Set<() => void>} */
+  const closeHandlers = new Set();
   let closedError = null;
   const failAll = (error) => {
     closedError ??= error;
@@ -78,10 +89,24 @@ async function connectBrowserCdp(
   const lost = () =>
     failAll(new Error('Browser CDP socket closed (the browser exited or disconnected).'));
   socket.onerror = lost;
-  socket.onclose = lost;
+  socket.onclose = () => {
+    lost();
+    for (const handler of [...closeHandlers]) handler();
+    closeHandlers.clear();
+    eventHandlers.clear();
+  };
   let nextId = 0;
   socket.onmessage = (event) => {
     const message = JSON.parse(typeof event.data === 'string' ? event.data : String(event.data));
+    if (message.id === undefined && message.method) {
+      const cdpEvent = {
+        method: message.method,
+        params: message.params ?? {},
+        ...(message.sessionId ? { sessionId: message.sessionId } : {}),
+      };
+      for (const handler of [...eventHandlers]) handler(cdpEvent);
+      return;
+    }
     const entry = message.id === undefined ? null : pending.get(message.id);
     if (!entry) return;
     pending.delete(message.id);
@@ -89,6 +114,13 @@ async function connectBrowserCdp(
     if (message.error) entry.reject(new Error(`${entry.method}: ${message.error.message}`));
     else entry.resolve(message.result);
   };
+  /**
+   * @param {string} method
+   * @param {Record<string, any>} [params]
+   * @param {string} [sessionId]
+   * @param {number} [timeout]
+   * @returns {Promise<any>}
+   */
   const send = (method, params = {}, sessionId, timeout = commandTimeoutMs) =>
     new Promise((resolve, reject) => {
       if (closedError) {
@@ -109,6 +141,36 @@ async function connectBrowserCdp(
     });
   return {
     send,
+    // Every CDP event (a message without an id), from the browser or an
+    // attached session. Returns the unsubscribe function; a closed client
+    // has no more events and keeps no handler.
+    /**
+     * @param {(event: BrowserCdpEvent) => void} handler
+     * @returns {() => void}
+     */
+    onEvent: (handler) => {
+      if (closedError) return () => {};
+      eventHandlers.add(handler);
+      return () => {
+        eventHandlers.delete(handler);
+      };
+    },
+    // Once, when the socket closes: the browser exited or `close()` was called.
+    // On a client that is already closed, the handler runs at once.
+    /**
+     * @param {() => void} handler
+     * @returns {() => void}
+     */
+    onClose: (handler) => {
+      if (closedError) {
+        handler();
+        return () => {};
+      }
+      closeHandlers.add(handler);
+      return () => {
+        closeHandlers.delete(handler);
+      };
+    },
     close: () => {
       failAll(new Error('Browser CDP client closed.'));
       try {
@@ -712,10 +774,48 @@ function expectedExtensionId(extensionDir) {
   return extensionIdFromExtensionDir(extensionDir) || null;
 }
 
+// ---- target lists ---------------------------------------------------------
+
+// One entry of `Target.getTargets` (`targetId`) or of the `/json` list (`id`),
+// or null when it lacks an id, type or URL.
+/**
+ * @param {unknown} value
+ * @returns {BrowserCdpTarget | null}
+ */
+function asBrowserCdpTarget(value) {
+  const target = /** @type {Record<string, unknown>} */ (
+    value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+  );
+  const targetId = String(target.targetId ?? target.id ?? '');
+  const type = String(target.type ?? '');
+  const url = String(target.url ?? '');
+  return targetId && type && url ? { targetId, type, url } : null;
+}
+
+// The id of the first extension that has a target in the list.
+/**
+ * @param {unknown} targets
+ * @returns {string | null}
+ */
+function extensionIdFromCdpTargets(targets) {
+  for (const candidate of Array.isArray(targets) ? targets : []) {
+    const target = asBrowserCdpTarget(candidate);
+    if (!target) continue;
+    try {
+      const url = new URL(target.url);
+      if (url.protocol === 'chrome-extension:' && url.hostname) return url.hostname;
+    } catch {
+      // Not a URL: not an extension target.
+    }
+  }
+  return null;
+}
+
 module.exports = {
   DEFAULT_COMMAND_TIMEOUT_MS,
   START_TIME_SLACK_MS,
   assertCdpOwnedByProfile,
+  asBrowserCdpTarget,
   assertSameOwner,
   canonicalProfile,
   cdpListenerPids,
@@ -724,6 +824,7 @@ module.exports = {
   waitForCdpOwner,
   connectBrowserCdp,
   expectedExtensionId,
+  extensionIdFromCdpTargets,
   loadUnpackedExtension,
   loadUnpackedOverPort,
   ensureBackgroundWindow,

package/src/network-observer.cjs

@@ -0,0 +1,228 @@
+// network-observer.cjs — network capture for a browser extension: attach to
+// every target of the loaded extension (page, background, service worker) on
+// one browser CDP connection, follow targets as they come and go, and feed
+// their Network events to a recipe-runner CDP broker that owns the captures.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  brokerSocketPath,
+  createBrokerClient,
+  createCdpBroker,
+} = require('@farmslot/recipe-runner/cdp-broker');
+
+const {
+  asBrowserCdpTarget,
+  connectBrowserCdp,
+  extensionIdFromCdpTargets,
+} = require('./browser-cdp.cjs');
+
+const DEVICE_ID = 'extension';
+const DEFAULT_TIMEOUT_MS = 10000;
+const EXTENSION_TARGET_TYPES = new Set(['background_page', 'other', 'page', 'service_worker']);
+
+const asRecord = (value) =>
+  value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+
+/**
+ * @param {{ cdpPort: number, runtimeDir: string, extensionId?: string, connectTimeoutMs?: number, commandTimeoutMs?: number }} options
+ *   `runtimeDir` keys the broker socket; the timeouts bound the CDP connection
+ *   and every command, broker call and capture control. `extensionId` names the
+ *   extension to capture; without it, the first extension with a target is
+ *   used, which can be a component or policy extension in a branded Chrome.
+ * @returns {Promise<import('@farmslot/adapter-sdk').NetworkCaptureBackend>}
+ */
+async function createExtensionNetworkObserver({
+  cdpPort,
+  runtimeDir,
+  extensionId: requestedExtensionId,
+  connectTimeoutMs = DEFAULT_TIMEOUT_MS,
+  commandTimeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+    throw new Error('Extension network observation requires a valid CDP port.');
+  }
+
+  const connection = await connectBrowserCdp(cdpPort, {
+    timeoutMs: connectTimeoutMs,
+    commandTimeoutMs,
+  });
+
+  let closed = false;
+  let extensionId = null;
+  let broker = null;
+  const targetSessions = new Map();
+  const attaching = new Set();
+
+  const send = (method, params = {}, sessionId, timeoutMs = commandTimeoutMs) =>
+    connection.send(method, params, sessionId, timeoutMs);
+
+  const relevantTarget = (target) => {
+    if (!extensionId || !EXTENSION_TARGET_TYPES.has(target.type)) return false;
+    try {
+      return new URL(target.url).hostname === extensionId;
+    } catch {
+      return false;
+    }
+  };
+
+  const refreshBrokerSession = () => {
+    if (!broker) return;
+    broker.onSessionClose(DEVICE_ID);
+    broker.onSessionOpen(DEVICE_ID);
+  };
+
+  const attachTarget = async (target) => {
+    if (
+      closed ||
+      !relevantTarget(target) ||
+      targetSessions.has(target.targetId) ||
+      attaching.has(target.targetId)
+    ) {
+      return;
+    }
+    attaching.add(target.targetId);
+    try {
+      const result = asRecord(
+        await send('Target.attachToTarget', { targetId: target.targetId, flatten: true }),
+      );
+      const sessionId = String(result.sessionId ?? '');
+      if (sessionId) {
+        targetSessions.set(target.targetId, sessionId);
+        refreshBrokerSession();
+      }
+    } catch (error) {
+      if (!/already attached/iu.test(String(error))) broker?.onSessionClose(DEVICE_ID);
+    } finally {
+      attaching.delete(target.targetId);
+    }
+  };
+
+  connection.onEvent(({ method, params, sessionId }) => {
+    if (method === 'Target.targetCreated') {
+      const target = asBrowserCdpTarget(params.targetInfo);
+      if (target) void attachTarget(target);
+      return;
+    }
+    if (method === 'Target.attachedToTarget') {
+      const target = asBrowserCdpTarget(params.targetInfo);
+      const attachedSessionId = String(params.sessionId ?? '');
+      if (target && attachedSessionId && relevantTarget(target)) {
+        targetSessions.set(target.targetId, attachedSessionId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (method === 'Target.detachedFromTarget') {
+      const detachedSessionId = String(params.sessionId ?? '');
+      for (const [targetId, activeSessionId] of targetSessions) {
+        if (activeSessionId !== detachedSessionId) continue;
+        targetSessions.delete(targetId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (sessionId && method.startsWith('Network.')) {
+      broker?.onCdpEvent(DEVICE_ID, method, params);
+    }
+  });
+
+  connection.onClose(() => {
+    if (!closed) broker?.onSessionClose(DEVICE_ID);
+  });
+
+  await send('Target.setDiscoverTargets', { discover: true });
+  const targetInfos = asRecord(await send('Target.getTargets')).targetInfos;
+  const targets = Array.isArray(targetInfos) ? targetInfos : [];
+  extensionId = requestedExtensionId || extensionIdFromCdpTargets(targets);
+  if (!extensionId) {
+    connection.close();
+    throw new Error('Extension CDP browser or loaded extension target is unavailable.');
+  }
+  await Promise.all(targets.map(asBrowserCdpTarget).filter(Boolean).map(attachTarget));
+  if (targetSessions.size === 0) {
+    connection.close();
+    throw new Error(
+      requestedExtensionId
+        ? `Extension ${extensionId} has no attachable CDP targets (service worker stopped and no extension page open?).`
+        : 'Extension CDP exposes no attachable extension targets.',
+    );
+  }
+
+  const sessions = new Map([[DEVICE_ID, { brokerReady: true }]]);
+  const socketPath = brokerSocketPath(path.join(runtimeDir, 'extension-network'));
+  broker = createCdpBroker({
+    socketPath,
+    sessions,
+    async sendCommand(_session, method, params, timeoutMs) {
+      const sessionIds = [...new Set(targetSessions.values())];
+      if (sessionIds.length === 0) {
+        throw new Error('Extension CDP has no active extension target sessions.');
+      }
+      const results = await Promise.allSettled(
+        sessionIds.map((sessionId) => send(method, params, sessionId, timeoutMs)),
+      );
+      const successes = results.filter((result) => result.status === 'fulfilled');
+      if (successes.length === 0) {
+        const firstFailure = results.find((result) => result.status === 'rejected');
+        throw new Error(
+          `Extension CDP command failed on every target: ${String(firstFailure?.reason ?? method)}`,
+        );
+      }
+      if (successes.length !== results.length) {
+        results.forEach((result, index) => {
+          if (result.status === 'fulfilled') return;
+          const failedSession = sessionIds[index];
+          for (const [targetId, sessionId] of targetSessions) {
+            if (sessionId === failedSession) targetSessions.delete(targetId);
+          }
+        });
+        broker?.onSessionClose(DEVICE_ID);
+      }
+      return successes[0].value;
+    },
+    requestDiscovery() {
+      void send('Target.getTargets')
+        .then((result) => {
+          const infos = asRecord(result).targetInfos;
+          if (!Array.isArray(infos)) return;
+          for (const value of infos) {
+            const target = asBrowserCdpTarget(value);
+            if (target) void attachTarget(target);
+          }
+        })
+        .catch(() => broker?.onSessionClose(DEVICE_ID));
+    },
+  });
+  broker.onSessionOpen(DEVICE_ID);
+  await waitForSocket(socketPath, commandTimeoutMs);
+  const client = await createBrokerClient(socketPath, DEVICE_ID, commandTimeoutMs);
+
+  return {
+    start(params) {
+      return client.control('capture-start', params, commandTimeoutMs);
+    },
+    async end(id) {
+      return asRecord(await client.control('capture-end', { id }, commandTimeoutMs));
+    },
+    async close() {
+      closed = true;
+      client.close();
+      broker?.close();
+      connection.close();
+    },
+  };
+}
+
+async function waitForSocket(socketPath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(socketPath)) return;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error('Extension network observer broker did not start.');
+}
+
+module.exports = { createExtensionNetworkObserver };

package/src/page-target.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+const { asBrowserCdpTarget } = require('./browser-cdp.cjs');
+
 // Choose the page a recipe drives from a CDP target list: a page on `origin`,
 // preferring one whose URL carries `hash`. Returns null when no page matches;
 // the caller owns the error it reports.
@@ -22,4 +24,35 @@ function selectPageTarget(targets, { origin, hash = '' }) {
   return pages[0];
 }
 
-module.exports = { selectPageTarget };
+// Choose an extension's UI renderer from a CDP target list (`Target.getTargets`
+// or `/json`): a page or `other` target of `extensionId` whose path is one of
+// `paths`, tried in order. The first path with any match decides: exactly one
+// match is returned, several are ambiguous and return null.
+/**
+ * @param {unknown} targets
+ * @param {string} extensionId
+ * @param {{ paths: readonly string[] }} options
+ * @returns {import('./browser-cdp.cjs').BrowserCdpTarget | null}
+ */
+function selectExtensionTarget(targets, extensionId, { paths }) {
+  const candidates = [];
+  for (const value of Array.isArray(targets) ? targets : []) {
+    const target = asBrowserCdpTarget(value);
+    if (!target || !['page', 'other'].includes(target.type)) continue;
+    try {
+      const url = new URL(target.url);
+      if (url.protocol === 'chrome-extension:' && url.hostname === extensionId) {
+        candidates.push({ target, pathname: url.pathname });
+      }
+    } catch {
+      // Not a URL: not an extension target.
+    }
+  }
+  for (const pathname of paths) {
+    const matches = candidates.filter((candidate) => candidate.pathname === pathname);
+    if (matches.length > 0) return matches.length === 1 ? matches[0].target : null;
+  }
+  return null;
+}
+
+module.exports = { selectExtensionTarget, selectPageTarget };

package/src/performance-observer.cjs

@@ -0,0 +1,94 @@
+// performance-observer.cjs — CDP performance traces of a browser extension's
+// UI renderer: attach to the extension page the host names, write the clock
+// marker there with `performance.mark`, and trace through recipe-runner's
+// CDP trace collector.
+'use strict';
+
+const { connectBrowserCdp } = require('./browser-cdp.cjs');
+const { selectExtensionTarget } = require('./page-target.cjs');
+
+const DEFAULT_TIMEOUT_MS = 10000;
+
+/**
+ * @template {string} [P=string]
+ * @param {{
+ *   cdpPort: number,
+ *   extensionId: string,
+ *   uiPaths: readonly string[],
+ *   kind: import('@farmslot/recipe-runner/runtime/cdp-trace').TraceKind,
+ *   platform: P,
+ *   markerPrefix?: string,
+ *   connectTimeoutMs?: number,
+ *   commandTimeoutMs?: number,
+ * }} options
+ *   `uiPaths` are the extension pages to trace, in order of preference (see
+ *   `selectExtensionTarget`); `kind`, `platform` and `markerPrefix` go to the collector.
+ * @returns {Promise<import('@farmslot/recipe-runner/runtime/cdp-trace').PerformanceBackend<P>>}
+ */
+async function createExtensionPerformanceBackend({
+  cdpPort,
+  extensionId,
+  uiPaths,
+  kind,
+  platform,
+  markerPrefix,
+  connectTimeoutMs = DEFAULT_TIMEOUT_MS,
+  commandTimeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  if (!extensionId) {
+    throw new Error('Extension performance observation requires the extension id.');
+  }
+  // Loaded on use: recipe-runner's trace engine is an ES module built to dist,
+  // and the other adapter-web modules must load without it.
+  const { createCdpTraceCollector } = require('@farmslot/recipe-runner/runtime/cdp-trace');
+  const browser = await connectBrowserCdp(cdpPort, {
+    timeoutMs: connectTimeoutMs,
+    commandTimeoutMs,
+  });
+  let sessionId = '';
+  try {
+    const { targetInfos } = await browser.send('Target.getTargets', {});
+    const uiTarget = selectExtensionTarget(targetInfos, extensionId, { paths: uiPaths });
+    if (!uiTarget) {
+      throw new Error('Extension performance observation requires an open extension UI target.');
+    }
+    const attached = await browser.send('Target.attachToTarget', {
+      targetId: uiTarget.targetId,
+      flatten: true,
+    });
+    sessionId = String(attached?.sessionId ?? '');
+    if (!sessionId) {
+      throw new Error(
+        'Extension performance observation could not attach to the extension UI target.',
+      );
+    }
+  } catch (error) {
+    browser.close();
+    throw error;
+  }
+  const client = {
+    send: (method, params = {}, timeoutMs) => browser.send(method, params, undefined, timeoutMs),
+    on: (method, handler) =>
+      browser.onEvent((event) => {
+        if (event.method === method) handler(event.params);
+      }),
+    close: () => browser.close(),
+  };
+  return createCdpTraceCollector(client, {
+    kind,
+    platform,
+    markerPrefix,
+    marker: async (name) => {
+      const before = Date.now();
+      await browser.send(
+        'Runtime.evaluate',
+        { expression: `performance.mark(${JSON.stringify(name)})`, returnByValue: true },
+        sessionId,
+      );
+      const after = Date.now();
+      return { hostEpochMs: (before + after) / 2, uncertaintyMs: (after - before) / 2 };
+    },
+  });
+}
+
+module.exports = { createExtensionPerformanceBackend };