@farmslot/adapter-web 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.5.0 - 2026-10-08
+
+- `launchBrowser` takes an optional `progress` callback for the caller's stage: starting the browser, waiting for the CDP listener (with the attempt count, about every 5 s), loading the extension over CDP and opening the start window. The `[launch]` log lines are unchanged.
+- Publish with adapter-sdk 0.7.0 and recipe-runner 0.26.0 so consumers share one adapter-sdk copy.
+
+## 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`.

package/dist/launch-browser.d.cts

@@ -56,6 +56,16 @@ export type LaunchBrowserOptions = {
      * Progress lines (default stderr).
      */
     log?: ((line: string) => void) | undefined;
+    /**
+     * What the launch is waiting for, for a caller's stage handle (`stage.progress`).
+     */
+    progress?: ((progress: {
+        message?: string;
+        waitingFor?: string;
+        current?: number;
+        total?: number;
+        unit?: string;
+    }) => void) | undefined;
 };
 /**
  * @typedef {object} LaunchBrowserOptions
@@ -77,6 +87,8 @@ export type LaunchBrowserOptions = {
  * @property {string} [rerunCommand] Command named in "Next:" hints.
  * @property {number} [focusSettleMs] macOS: wait before the one focus check (default 1000).
  * @property {(line: string) => void} [log] Progress lines (default stderr).
+ * @property {(progress: { message?: string, waitingFor?: string, current?: number, total?: number, unit?: string }) => void} [progress]
+ *   What the launch is waiting for, for a caller's stage handle (`stage.progress`).
  */
 /**
  * @param {LaunchBrowserOptions} options

package/dist/network-observer.d.cts

@@ -1,12 +1,15 @@
 /**
- * @param {{ cdpPort: number, runtimeDir: string, connectTimeoutMs?: number, commandTimeoutMs?: number }} options
+ * @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.
+ *   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, connectTimeoutMs, commandTimeoutMs, }: {
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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": {
@@ -79,7 +79,7 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/adapter-web"
   },
   "dependencies": {
-    "@farmslot/adapter-sdk": "0.5.1",
+    "@farmslot/adapter-sdk": "0.7.0",
     "@farmslot/recipe-runner": "0.26.0",
     "ws": "^8.18.0"
   },

package/src/launch-browser.cjs

@@ -78,6 +78,8 @@ const BROWSER_RESOLVER_CLI = require.resolve('./browser-resolver.cjs');
  * @property {string} [rerunCommand] Command named in "Next:" hints.
  * @property {number} [focusSettleMs] macOS: wait before the one focus check (default 1000).
  * @property {(line: string) => void} [log] Progress lines (default stderr).
+ * @property {(progress: { message?: string, waitingFor?: string, current?: number, total?: number, unit?: string }) => void} [progress]
+ *   What the launch is waiting for, for a caller's stage handle (`stage.progress`).
  */
 
 /**
@@ -117,6 +119,7 @@ function normalizeOptions(options) {
     if (!opts[key]) throw new Error(`Missing --${flag}`);
   }
   opts.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+  opts.progress = opts.progress ?? (() => {});
   return opts;
 }
 
@@ -254,12 +257,13 @@ function runLaunch(opts, acquireLock) {
   try {
     try {
       beginDetachedLaunch(cdpPort, profile, activeValidationLease);
+      opts.progress({ message: 'starting the browser' });
       if (application) {
         execFileSync('open', macBackgroundOpenArgs(application, chromeArgs), {
           env: sanitizedChildEnv(),
           stdio: ['ignore', logFd, logFd],
         });
-        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser);
+        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser, opts.progress);
         if (browserPid === null) {
           stopProfileProcessesSync(profile, { waitForAppearanceMs: 400 });
           throw ownedListenerMissing();
@@ -271,7 +275,7 @@ function runLaunch(opts, acquireLock) {
           stdio: ['ignore', logFd, logFd],
         });
         child.unref();
-        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser);
+        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser, opts.progress);
         if (browserPid === null) {
           stopProfileProcessesSync(profile, { extraPids: child.pid ? [child.pid] : [] });
           throw ownedListenerMissing();
@@ -342,6 +346,7 @@ function runLaunch(opts, acquireLock) {
 // Without it the slot has no window at all, so a failure fails the launch:
 // the owned browser is stopped (its markers kept if it cannot be).
 function openBackgroundWindow(opts, pid, url, clearLaunchMarkers) {
+  opts.progress({ message: 'opening the start window' });
   const result = spawnSync(
     process.execPath,
     [BROWSER_RESOLVER_CLI, 'open-window', '--port', String(opts.cdpPort), '--url', url],
@@ -399,6 +404,7 @@ function writeBrowserResolution(runtime, resolution) {
 }
 
 function loadExtensionOverCdp(opts, pid, initialUrl, clearLaunchMarkers) {
+  opts.progress({ message: 'loading the extension over CDP' });
   const result = spawnSync(
     process.execPath,
     [
@@ -495,10 +501,20 @@ function macApplicationForExecutable(executable) {
   return null;
 }
 
-function waitForOwnedCdpPid(port, ownedBrowser) {
-  for (let i = 0; i < 300; i += 1) {
+function waitForOwnedCdpPid(port, ownedBrowser, progress) {
+  const attempts = 300;
+  for (let i = 0; i < attempts; i += 1) {
     const pid = cdpListenerPids(port).find(ownedBrowser);
     if (pid !== undefined) return pid;
+    // Every 50 attempts (about 5 s): enough to show the wait is moving.
+    if (i > 0 && i % 50 === 0) {
+      progress({
+        waitingFor: `an owned CDP listener on 127.0.0.1:${port}`,
+        current: i,
+        total: attempts,
+        unit: 'attempts',
+      });
+    }
     spawnSync('sleep', ['0.1']);
   }
   return null;

package/src/network-observer.cjs

@@ -27,14 +27,17 @@ const asRecord = (value) =>
   value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 
 /**
- * @param {{ cdpPort: number, runtimeDir: string, connectTimeoutMs?: number, commandTimeoutMs?: number }} options
+ * @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.
+ *   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,
 }) {
@@ -133,7 +136,7 @@ async function createExtensionNetworkObserver({
   await send('Target.setDiscoverTargets', { discover: true });
   const targetInfos = asRecord(await send('Target.getTargets')).targetInfos;
   const targets = Array.isArray(targetInfos) ? targetInfos : [];
-  extensionId = extensionIdFromCdpTargets(targets);
+  extensionId = requestedExtensionId || extensionIdFromCdpTargets(targets);
   if (!extensionId) {
     connection.close();
     throw new Error('Extension CDP browser or loaded extension target is unavailable.');
@@ -141,7 +144,11 @@ async function createExtensionNetworkObserver({
   await Promise.all(targets.map(asBrowserCdpTarget).filter(Boolean).map(attachTarget));
   if (targetSessions.size === 0) {
     connection.close();
-    throw new Error('Extension CDP exposes no attachable extension targets.');
+    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 }]]);