browser-commander 0.29.0 → 0.30.0

package/.jscpd-baseline.json

@@ -58,6 +58,7 @@
     "326f1ff9016e1e37": 1,
     "33357ce94e07cc4b": 1,
     "35cf2769645f3234": 1,
+    "364e8930fe8fdf71": 1,
     "37bd4114d0089f49": 1,
     "3adca52a3f04837c": 1,
     "3c1017def7b3216c": 1,
@@ -167,6 +168,7 @@
     "a36f66312d5bfbf8": 1,
     "a4c8498d4f2d2191": 1,
     "a5298242b5439858": 1,
+    "a5861532b8efced8": 1,
     "a6ad7ab6c05656dc": 1,
     "a6ffab1aacd00af6": 1,
     "a71a4b720d466e32": 1,
@@ -210,7 +212,6 @@
     "c714beebc66381dd": 1,
     "c9cf3c28bed33a5b": 1,
     "ca7e08d1eec2ad8c": 1,
-    "cab590a1d04b5a05": 1,
     "cbd444e9a6a9072e": 1,
     "cebff7d1cc87f646": 1,
     "cfc928aa393146b6": 1,

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.30.0
+
+### Minor Changes
+
+- 0abb9c9: Enable complete JavaScript session recording by default for commanders, launches, and explicit traces. Record trusted user actions with private target descriptions alongside commander actions, DOM changes, network metadata, and a self-contained trace.lino export. Use debug: false or BROWSER_COMMANDER_DEBUG=0 to opt out.
+
 ## 0.29.0
 
 ### Minor Changes

package/README.md

@@ -816,6 +816,13 @@ See [capture, debugging and reusable sessions](https://github.com/link-foundatio
 for screenshots, recordings, full/text DOM links, network/HAR, rotation,
 persistent browsers, early trigger readiness and engine capability limits.
 
+JavaScript commanders and browser launches record complete sessions by default
+under `./browser-commander-traces/`, including trusted user actions, DOM changes,
+network metadata and `trace.lino`. Await `commander.ready` before using its raw
+page, and call `commander.destroy()` or the launch's `close()` to finish the files.
+Use `debug: false` or `BROWSER_COMMANDER_DEBUG=0` to opt out; `debug: { output }`
+chooses the directory. `commander.tracePath` exposes its path.
+
 `startTrace()` records a session into a schema-versioned bundle any of the three
 languages can read - the manifest, an ordered NDJSON timeline, per-checkpoint
 DOM snapshots and the mutation batches between them:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/scripts/run-tests.mjs

@@ -177,7 +177,9 @@ function runNodeTests(options, testFiles) {
     process.execPath,
     buildNodeTestArgs(options, testFiles),
     {
-      env: { ...process.env, ...options.env },
+      // Most fixtures exercise unrelated APIs with incomplete fake pages. The
+      // default-recording regressions explicitly unset this harness opt-out.
+      env: { BROWSER_COMMANDER_DEBUG: '0', ...process.env, ...options.env },
       stdio: 'inherit',
     }
   );

package/src/browser/launcher.js

@@ -8,6 +8,7 @@ import {
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
 import { reserveLoopbackPort } from './debugging-port.js';
+import { attachLaunchDebug } from '../traces/debug-session.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
@@ -319,12 +320,16 @@ export async function launchBrowserWithDependencies(
 ) {
   if (options.keepOpen) {
     const { connectOrLaunch } = await import('./persistent-session.js');
-    return connectOrLaunch({
-      ...options,
-      userDataDir: options.userDataDir ?? (await createTemporaryUserDataDir()),
-      remoteDebuggingPort:
-        options.remoteDebuggingPort ?? (await reserveLoopbackPort()),
-    });
+    return attachLaunchDebug(
+      await connectOrLaunch({
+        ...options,
+        userDataDir:
+          options.userDataDir ?? (await createTemporaryUserDataDir()),
+        remoteDebuggingPort:
+          options.remoteDebuggingPort ?? (await reserveLoopbackPort()),
+      }),
+      options
+    );
   }
   sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
@@ -333,11 +338,17 @@ export async function launchBrowserWithDependencies(
       launch: options.launch ?? 'real',
       attach: options.attach,
     });
-    return await launchSafari(options, dependencies);
+    return attachLaunchDebug(
+      await launchSafari(options, dependencies),
+      options
+    );
   }
   const result = await launchNonSafariBrowser(options, dependencies);
   try {
-    return await installSessionPersistence(result, options);
+    return await attachLaunchDebug(
+      await installSessionPersistence(result, options),
+      options
+    );
   } catch (error) {
     await result.close();
     throw error;

package/src/core/commander-features.js

@@ -1,4 +1,7 @@
 import { startTrace } from '../traces/recorder.js';
+import { debugEnabled, ensureDebugSession } from '../traces/debug-session.js';
+import { observeCommanderActions } from '../traces/commander-actions.js';
+import { TRACED_INTERACTIONS, interactionTarget } from '../traces/observers.js';
 import { touchSessionPage } from '../browser/persistent-session.js';
 import { dismissOverlays } from '../interactions/overlays.js';
 import {
@@ -15,7 +18,7 @@ const INTERACTIONS = new Set([
   'pressKey',
 ]);
 
-/** Bind capture, persistence and opt-in debugging to the commander lifecycle. */
+/** Bind capture, persistence and automatic debugging to the commander lifecycle. */
 export function attachCommanderFeatures(commander, options, recreate) {
   const { page, engine } = commander;
   const managed = new Set();
@@ -46,24 +49,10 @@ export function attachCommanderFeatures(commander, options, recreate) {
     });
   commander.startTrace = async (traceOptions = {}) =>
     track(await startTrace({ commander, page, ...traceOptions }));
-  const output =
-    options.debug?.output ??
-    options.output ??
-    process.env.BROWSER_COMMANDER_TRACE;
-  let debug;
-  const ensureDebug = async () => {
-    if (!output || (!options.debug && !process.env.BROWSER_COMMANDER_TRACE)) {
-      return;
-    }
-    debug ??= commander.startTrace({
-      output,
-      mode: 'continuous',
-      network: { har: true },
-      links: { output: `${output}.links`, dom: 'text' },
-      checkpointOnNavigation: true,
-    });
-    await debug;
-  };
+  let debugSession;
+  let detachActions;
+  commander.tracePath = null;
+  const ensureDebug = () => commander.ready;
   for (const name of [...INTERACTIONS, 'goto', 'evaluate', 'count']) {
     const method = commander[name];
     if (!method) {
@@ -81,10 +70,10 @@ export function attachCommanderFeatures(commander, options, recreate) {
   const destroy = commander.destroy;
   commander.destroy = async () => {
     try {
-      if (debug) {
-        await debug;
-      }
+      await commander.ready;
+      await debugSession?.stop();
       await Promise.all([...managed].map((item) => item.stop()));
+      detachActions?.();
     } finally {
       await destroy();
     }
@@ -104,7 +93,21 @@ export function attachCommanderFeatures(commander, options, recreate) {
     touchSessionPage(selected);
     return selected;
   };
-  if (options.debug || process.env.BROWSER_COMMANDER_TRACE) {
-    commander.ready = ensureDebug();
+  if (debugEnabled({ ...options, page })) {
+    detachActions = observeCommanderActions({
+      commander,
+      page,
+      names: TRACED_INTERACTIONS,
+      targetOf: interactionTarget,
+    });
   }
+  commander.ready = ensureDebugSession({
+    ...options,
+    page,
+    engine,
+    commander,
+  }).then((session) => {
+    debugSession = session;
+    commander.tracePath = session?.path ?? null;
+  });
 }

package/src/traces/commander-actions.js

@@ -0,0 +1,146 @@
+/** One wrapper per commander, even when explicit and automatic traces overlap. */
+import { withDeadline } from './deadline.js';
+import { framesOf } from './init-script.js';
+
+const commanders = new WeakMap();
+
+let actionSequence = 0;
+
+function labelActionInPage(argument, elementOptions) {
+  const { marker, remove } = elementOptions ?? argument;
+  const actions = (window.__browserCommanderActions__ ??= []);
+  if (remove) {
+    const index = actions.findIndex((action) => action.id === marker.id);
+    if (index >= 0) {
+      actions.splice(index, 1);
+    }
+  } else {
+    const focused =
+      !marker.selector && marker.types.includes('keydown')
+        ? document.activeElement
+        : null;
+    actions.push({
+      ...marker,
+      element: elementOptions
+        ? argument
+        : focused !== document.body && focused !== document.documentElement
+          ? focused
+          : null,
+    });
+  }
+}
+
+export function observeCommanderActions({
+  commander,
+  page,
+  names,
+  targetOf,
+  record,
+  identity,
+  now,
+  note,
+}) {
+  if (!commander) {
+    return () => {};
+  }
+  let state = commanders.get(commander);
+  if (!state) {
+    state = { observers: new Set(), originals: new Map() };
+    commanders.set(commander, state);
+    for (const name of names) {
+      const original = commander[name];
+      if (typeof original !== 'function') {
+        continue;
+      }
+      const wrapper = async (...args) => {
+        await commander.ready;
+        const observing = [...state.observers].map((observer) => ({
+          observer,
+          started: observer.now(),
+          actionId: observer.identity?.nextActionId() ?? null,
+        }));
+        const marker = {
+          id: ++actionSequence,
+          selector: targetOf(args[0]),
+          types: /^(click|check)/.test(name)
+            ? ['pointerdown', 'click', 'submit', 'contextmenu']
+            : /^(fill|typeText|pressKey)/.test(name)
+              ? ['keydown', 'submit', 'click']
+              : [],
+        };
+        const element = args[0]?.locatorOrElement ?? args[0]?.selector;
+        const labelAction = async (remove) => {
+          try {
+            if (marker.types.length) {
+              const config = { marker, remove };
+              const frames =
+                remove || (!marker.selector && marker.types.includes('keydown'))
+                  ? framesOf(page)
+                  : [];
+              const target = element?.first?.() ?? element;
+              const work = frames.length
+                ? Promise.all(
+                    frames.map((frame) =>
+                      frame.evaluate(labelActionInPage, config)
+                    )
+                  )
+                : !remove && typeof target?.evaluate === 'function'
+                  ? target.evaluate(labelActionInPage, config, {
+                      timeout: 1000,
+                    })
+                  : page.evaluate?.(labelActionInPage, config);
+              await withDeadline(
+                Promise.resolve(work),
+                1000,
+                'commander input label'
+              );
+            }
+          } catch (error) {
+            note?.(`could not label commander input: ${error.message}`);
+          }
+        };
+        await labelAction(false);
+        let error;
+        try {
+          return await original.apply(commander, args);
+        } catch (failure) {
+          error = failure;
+          throw failure;
+        } finally {
+          await labelAction(true);
+          await Promise.all(
+            observing.map(({ observer, started, actionId }) =>
+              observer.record('interaction', {
+                actionId,
+                source: 'commander',
+                action: name,
+                target: targetOf(args[0]),
+                durationMs: observer.now() - started,
+                ok: !error,
+                ...(error ? { error: error.message } : {}),
+              })
+            )
+          );
+        }
+      };
+      state.originals.set(name, { original, wrapper });
+      commander[name] = wrapper;
+    }
+  }
+  const observer = { record, identity, now };
+  if (record) {
+    state.observers.add(observer);
+  }
+  return () => {
+    state.observers.delete(observer);
+    if (state.observers.size) {
+      return;
+    }
+    for (const [name, { original, wrapper }] of state.originals) {
+      if (commander[name] === wrapper) {
+        commander[name] = original;
+      }
+    }
+    commanders.delete(commander);
+  };
+}

package/src/traces/debug-session.js

@@ -0,0 +1,119 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { startTrace } from './recorder.js';
+
+const sessions = new WeakMap();
+const disabledPages = new WeakSet();
+
+export function debugEnabled(options = {}) {
+  return (
+    options.debug !== false &&
+    process.env.BROWSER_COMMANDER_DEBUG !== '0' &&
+    !(options.debug === undefined && disabledPages.has(options.page))
+  );
+}
+
+/** A launched page and its commander share one recording and one output path. */
+export async function ensureDebugSession(options) {
+  const { page, commander } = options;
+  const existing = sessions.get(page);
+  if (!debugEnabled(options)) {
+    disabledPages.add(page);
+    await existing?.stop();
+    return null;
+  }
+  disabledPages.delete(page);
+  let session = existing;
+  if (!session) {
+    const config =
+      options.debug && typeof options.debug === 'object' ? options.debug : {};
+    const output = path.resolve(
+      config.output ??
+        options.output ??
+        process.env.BROWSER_COMMANDER_TRACE ??
+        path.join(
+          'browser-commander-traces',
+          `${new Date().toISOString().replaceAll(':', '-')}-${process.pid}-${randomUUID().slice(0, 8)}`
+        )
+    );
+    session = { path: output };
+    sessions.set(page, session);
+    session.ready = startTrace({
+      ...config,
+      output,
+      page,
+      commander: commander ?? {
+        page,
+        engine: options.engine,
+        downloads: options.downloads,
+      },
+      checkpointOnNavigation: config.checkpointOnNavigation ?? true,
+    })
+      .then((trace) => {
+        console.error(`[browser-commander] Recording session to ${output}`);
+        return trace;
+      })
+      .catch((error) => {
+        sessions.delete(page);
+        console.warn(
+          `[browser-commander] Could not start recording: ${error.message}`
+        );
+        return null;
+      });
+    let stopping;
+    session.stop = () =>
+      (stopping ??= session.ready.then(async (trace) => {
+        try {
+          return await trace?.stop();
+        } finally {
+          if (sessions.get(page) === session) {
+            sessions.delete(page);
+          }
+        }
+      }));
+  }
+  const trace = await session.ready;
+  if (!trace) {
+    return null;
+  }
+  if (commander) {
+    trace.attachCommander(commander);
+  }
+  return session;
+}
+
+/** Finish trace files before closing/detaching the engine that supplies them. */
+export async function attachLaunchDebug(result, options) {
+  const session = await ensureDebugSession({
+    ...options,
+    engine:
+      options.engine ??
+      (result.page.isWebDriverPage ? 'selenium' : 'playwright'),
+    page: result.page,
+    downloads: result.downloads,
+  });
+  result.tracePath = session?.path ?? null;
+  if (!session) {
+    return result;
+  }
+  const wrap = (owner, name) => {
+    const method = owner?.[name];
+    if (typeof method !== 'function') {
+      return;
+    }
+    owner[name] = async (...args) => {
+      let result;
+      try {
+        await session.stop();
+      } finally {
+        result = await method.apply(owner, args);
+      }
+      return result;
+    };
+  };
+  wrap(result, 'close');
+  wrap(result, 'detach');
+  wrap(result.browser, 'close');
+  wrap(result.browser, 'disconnect');
+  return result;
+}

package/src/traces/drain-timer.js

@@ -0,0 +1,25 @@
+/** Serialize background drains and wait for the active drain during teardown. */
+export function startTraceDrain({
+  mutations,
+  userActions,
+  captureState,
+  note,
+}) {
+  let task;
+  const timer = setInterval(() => {
+    if (!task) {
+      task = Promise.resolve()
+        .then(() => userActions.drain())
+        .then(() => mutations.drain(captureState.index))
+        .catch((error) => note(error.message))
+        .finally(() => {
+          task = null;
+        });
+    }
+  }, 500);
+  timer.unref?.();
+  return async () => {
+    clearInterval(timer);
+    await task;
+  };
+}

package/src/traces/mutation-stream.js

@@ -57,10 +57,11 @@ export function createMutationStream(options) {
   } = options;
 
   const enabled = Boolean(domOptions.mutations);
+  const globalName = `${RECORDER_GLOBAL}${identity.traceId}`;
 
   /** What the in-page recorder is built with, wherever it is installed. */
   const recorderOptions = {
-    globalName: RECORDER_GLOBAL,
+    globalName,
     redactSelectors: privacyOptions.redactSelectors,
     redactAttributes: privacyOptions.redactAttributes,
     useDefaults: privacyOptions.useDefaults,
@@ -168,7 +169,7 @@ export function createMutationStream(options) {
     }
     try {
       const drained = await withDeadline(
-        evaluateInFrames(drainMutationsInPage, RECORDER_GLOBAL),
+        evaluateInFrames(drainMutationsInPage, globalName),
         captureTimeoutMs,
         'trace mutation drain'
       );
@@ -229,7 +230,7 @@ export function createMutationStream(options) {
       return;
     }
     try {
-      await evaluateInFrames(stopMutationRecorderInPage, RECORDER_GLOBAL);
+      await evaluateInFrames(stopMutationRecorderInPage, globalName);
     } catch (error) {
       note?.(`could not stop the in-page recorder: ${error.message}`);
     }

package/src/traces/observers.js

@@ -8,11 +8,49 @@
  */
 
 import { TRACE_EVENT } from './schema.js';
+import { observeCommanderActions } from './commander-actions.js';
+
+/** Keep page observations when a launched trace is adopted by a commander. */
+export function attachRecorderObservers(options) {
+  const ownerSources = ['interaction', 'dialog', 'download', 'navigation'];
+  const detachers = attachTimelineObservers({
+    ...options,
+    commander: null,
+    eventSources: options.eventSources.filter(
+      (source) => !ownerSources.includes(source)
+    ),
+  });
+  let commanderDetachers = [],
+    attachedCommander,
+    hasCommander = false;
+  const attachCommander = (commander) => {
+    if (hasCommander && commander === attachedCommander) {
+      return;
+    }
+    hasCommander = true;
+    attachedCommander = commander;
+    for (const detach of commanderDetachers) {
+      detach();
+    }
+    commanderDetachers = attachTimelineObservers({
+      ...options,
+      commander,
+      eventSources: options.eventSources.filter((source) =>
+        ownerSources.includes(source)
+      ),
+    });
+  };
+  attachCommander(options.commander);
+  detachers.push(() => commanderDetachers.forEach((detach) => detach()));
+  return { detachers, attachCommander };
+}
 
 /** Commander methods recorded as interactions while a trace is running. */
 export const TRACED_INTERACTIONS = Object.freeze([
   'click',
   'clickButton',
+  'clickElement',
+  'check',
   'fill',
   'fillTextArea',
   'goto',
@@ -231,51 +269,17 @@ export function attachTimelineObservers(options) {
     };
   });
 
-  subscribe('interaction', () => {
-    if (!commander) {
-      return null;
-    }
-    const originals = new Map();
-    for (const name of TRACED_INTERACTIONS) {
-      const original = commander[name];
-      if (typeof original !== 'function') {
-        continue;
-      }
-      originals.set(name, original);
-      commander[name] = async (...args) => {
-        const startedMs = now();
-        const target = interactionTarget(args[0]);
-        // Named before the call, so everything the action causes can be traced
-        // back to it even when the action itself ends in an exception.
-        const actionId = identity?.nextActionId() ?? null;
-        try {
-          const result = await original(...args);
-          await record(TRACE_EVENT.INTERACTION, {
-            actionId,
-            action: name,
-            target,
-            durationMs: now() - startedMs,
-            ok: true,
-          });
-          return result;
-        } catch (error) {
-          await record(TRACE_EVENT.INTERACTION, {
-            actionId,
-            action: name,
-            target,
-            durationMs: now() - startedMs,
-            ok: false,
-            error: error.message,
-          });
-          throw error;
-        }
-      };
-    }
-    return () => {
-      for (const [name, original] of originals) {
-        commander[name] = original;
-      }
-    };
-  });
+  subscribe('interaction', () =>
+    observeCommanderActions({
+      commander,
+      page,
+      names: TRACED_INTERACTIONS,
+      targetOf: interactionTarget,
+      record,
+      identity,
+      now,
+      note,
+    })
+  );
   return detachers;
 }