browser-commander 0.28.0 → 0.30.0

package/src/core/page-trigger-manager.js

@@ -182,6 +182,23 @@ export function createPageTriggerManager(options = {}) {
   let isActionRunning = false,
     isStopping = false;
   let startQueue = Promise.resolve();
+  let pendingStart = null;
+  let destroyed = false;
+
+  function drainPending() {
+    if (destroyed || isActionRunning || isStopping || !pendingStart) {
+      return;
+    }
+    const pending = pendingStart;
+    pendingStart = null;
+    if (
+      triggers.includes(pending.trigger) &&
+      (!pending.commander.page?.url ||
+        pending.commander.page.url() === pending.url)
+    ) {
+      void startAction(pending.url, pending.commander, pending.readyOn);
+    }
+  }
 
   /**
    * Register a page trigger
@@ -208,7 +225,7 @@ export function createPageTriggerManager(options = {}) {
     ) {
       throw new RangeError(`Unknown trigger readyOn: ${readyOn}`);
     }
-    if (!['skip', 'restart'].includes(concurrency)) {
+    if (!['skip', 'restart', 'queue'].includes(concurrency)) {
       throw new RangeError(`Unknown trigger concurrency: ${concurrency}`);
     }
 
@@ -242,6 +259,9 @@ export function createPageTriggerManager(options = {}) {
       const index = triggers.indexOf(triggerConfig);
       if (index !== -1) {
         triggers.splice(index, 1);
+        if (pendingStart?.trigger === triggerConfig) {
+          pendingStart = null;
+        }
         log.debug(() => `📋 Unregistered page trigger: "${name}"`);
       }
     };
@@ -298,7 +318,7 @@ export function createPageTriggerManager(options = {}) {
     }
 
     // Wait for action to finish (with timeout)
-    const timeoutMs = 10000; // 10 second max wait
+    const timeoutMs = options.stopGraceMs ?? 10000;
     let stopTimer;
     const timeoutPromise = new Promise((resolve) => {
       stopTimer = setTimeout(() => {
@@ -337,6 +357,7 @@ export function createPageTriggerManager(options = {}) {
     }
 
     log.debug(() => '✅ Action stopped');
+    drainPending();
   }
 
   /**
@@ -345,6 +366,9 @@ export function createPageTriggerManager(options = {}) {
    * @param {Object} commander - BrowserCommander instance
    */
   function startAction(url, commander, readyOn = 'networkidle') {
+    if (destroyed) {
+      return Promise.resolve();
+    }
     // Create context for condition checking
     const conditionCtx = {
       url,
@@ -359,14 +383,18 @@ export function createPageTriggerManager(options = {}) {
       return Promise.resolve();
     }
     if (isActionRunning) {
-      if (matchingTrigger.concurrency === 'skip') {
+      if (
+        matchingTrigger.concurrency === 'skip' &&
+        !isStopping &&
+        !currentAbortController?.signal.aborted
+      ) {
         return Promise.resolve();
       }
-      return stopCurrentAction().then(() => {
-        if (!isActionRunning) {
-          return startAction(url, commander, readyOn);
-        }
-      });
+      // One latest start bounds memory while preserving readiness during stop.
+      pendingStart = { url, commander, readyOn, trigger: matchingTrigger };
+      return matchingTrigger.concurrency === 'restart'
+        ? stopCurrentAction()
+        : Promise.resolve();
     }
 
     log.debug(() => `🚀 Starting action "${matchingTrigger.name}" for: ${url}`);
@@ -377,12 +405,15 @@ export function createPageTriggerManager(options = {}) {
     isActionRunning = true;
 
     // Create action context
-    const context = createActionContext({
-      url,
-      abortSignal: currentAbortController.signal,
-      commander,
-      triggerName: matchingTrigger.name,
-    });
+    const context = createActionContext(
+      {
+        url,
+        abortSignal: currentAbortController.signal,
+        commander,
+        triggerName: matchingTrigger.name,
+      },
+      log
+    );
 
     // Run action
     actionPromise = (async () => {
@@ -411,6 +442,7 @@ export function createPageTriggerManager(options = {}) {
           isActionRunning = false;
           currentTrigger = null;
           currentAbortController = null;
+          globalThis.queueMicrotask(drainPending);
         }
       }
     })();
@@ -423,130 +455,12 @@ export function createPageTriggerManager(options = {}) {
    * @param {Object} options
    * @returns {Object} - Action context
    */
-  function createActionContext(options) {
-    const { url, abortSignal, commander, triggerName } = options;
-
-    /**
-     * Check if stopped and throw if so
-     */
-    function checkStopped() {
-      if (abortSignal.aborted) {
-        throw new ActionStoppedError(`Action "${triggerName}" stopped`);
-      }
-    }
-
-    /**
-     * Wrap async function to check abort before and after
-     */
-    function wrapAsync(fn) {
-      return async (...args) => {
-        checkStopped();
-        const result = await fn(...args);
-        checkStopped();
-        return result;
-      };
-    }
-
-    /**
-     * Create abort-aware loop helper
-     * Use this instead of for/while loops for stoppability
-     */
-    async function forEach(items, callback) {
-      for (let i = 0; i < items.length; i++) {
-        checkStopped();
-        await callback(items[i], i, items);
-      }
-    }
-
-    /**
-     * Wait with abort support
-     */
-    async function wait(ms) {
-      checkStopped();
-      await new Promise((resolve, reject) => {
-        const timeout = setTimeout(resolve, ms);
-        abortSignal.addEventListener(
-          'abort',
-          () => {
-            clearTimeout(timeout);
-            reject(new ActionStoppedError());
-          },
-          { once: true }
-        );
-      });
-    }
-
-    /**
-     * Register cleanup callback (called when action stops)
-     */
-    const cleanupCallbacks = [];
-    function onCleanup(callback) {
-      const unsubscribe = subscribeCallbacks(cleanupCallbacks, callback);
-      const onAbort = async () => {
-        try {
-          await callback();
-        } catch (e) {
-          log.debug(() => `⚠️  Cleanup error: ${e.message}`);
-        }
-      };
-      abortSignal.addEventListener('abort', onAbort, { once: true });
-      return () => {
-        abortSignal.removeEventListener('abort', onAbort);
-        unsubscribe();
-      };
-    }
-
-    // Wrap all commander methods to be abort-aware
-    const wrappedCommander = {};
-    for (const [key, value] of Object.entries(commander)) {
-      if (
-        typeof value === 'function' &&
-        key !== 'destroy' &&
-        key !== 'pageTrigger'
-      ) {
-        wrappedCommander[key] = wrapAsync(value);
-      } else {
-        wrappedCommander[key] = value;
-      }
-    }
-
-    return {
-      // URL this action is running for
-      url,
-
-      // Abort signal - use with fetch() or custom abort logic
-      abortSignal,
-
-      // Check if action should stop
-      isStopped: () => abortSignal.aborted,
-
-      // Throw if stopped - call this in loops
-      checkStopped,
-
-      // Abort-aware iteration helper
-      forEach,
-
-      // Abort-aware wait
-      wait,
-
-      // Register cleanup callback
-      onCleanup,
-
-      // Wrapped commander - all methods throw ActionStoppedError if stopped
-      commander: wrappedCommander,
-
-      // Original commander (use carefully)
-      rawCommander: commander,
-
-      // Trigger name for debugging
-      triggerName,
-    };
-  }
 
   /**
    * Handle navigation start - stop current action first
    */
   async function onNavigationStart() {
+    pendingStart = null;
     await stopCurrentAction();
   }
 
@@ -586,13 +500,18 @@ export function createPageTriggerManager(options = {}) {
   /**
    * Cleanup
    */
-  const destroy = createTriggerDestroy({
+  const cleanup = createTriggerDestroy({
     subscriptions,
     getQueue: () => startQueue,
     stopCurrentAction,
     triggers,
     log,
   });
+  const destroy = async () => {
+    destroyed = true;
+    pendingStart = null;
+    await cleanup();
+  };
 
   return {
     pageTrigger,
@@ -652,3 +571,123 @@ function createTriggerDestroy({
     log.debug(() => '📋 PageTriggerManager destroyed');
   };
 }
+
+function createActionContext(options, log) {
+  const { url, abortSignal, commander, triggerName } = options;
+
+  /**
+   * Check if stopped and throw if so
+   */
+  function checkStopped() {
+    if (abortSignal.aborted) {
+      throw new ActionStoppedError(`Action "${triggerName}" stopped`);
+    }
+  }
+
+  /**
+   * Wrap async function to check abort before and after
+   */
+  function wrapAsync(fn) {
+    return async (...args) => {
+      checkStopped();
+      const result = await fn(...args);
+      checkStopped();
+      return result;
+    };
+  }
+
+  /**
+   * Create abort-aware loop helper
+   * Use this instead of for/while loops for stoppability
+   */
+  async function forEach(items, callback) {
+    for (let i = 0; i < items.length; i++) {
+      checkStopped();
+      await callback(items[i], i, items);
+    }
+  }
+
+  /**
+   * Wait with abort support
+   */
+  async function wait(ms) {
+    checkStopped();
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, ms);
+      abortSignal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timeout);
+          reject(new ActionStoppedError());
+        },
+        { once: true }
+      );
+    });
+  }
+
+  /**
+   * Register cleanup callback (called when action stops)
+   */
+  const cleanupCallbacks = [];
+  function onCleanup(callback) {
+    const unsubscribe = subscribeCallbacks(cleanupCallbacks, callback);
+    const onAbort = async () => {
+      try {
+        await callback();
+      } catch (e) {
+        log.debug(() => `⚠️  Cleanup error: ${e.message}`);
+      }
+    };
+    abortSignal.addEventListener('abort', onAbort, { once: true });
+    return () => {
+      abortSignal.removeEventListener('abort', onAbort);
+      unsubscribe();
+    };
+  }
+
+  // Wrap all commander methods to be abort-aware
+  const wrappedCommander = {};
+  for (const [key, value] of Object.entries(commander)) {
+    if (
+      typeof value === 'function' &&
+      key !== 'destroy' &&
+      key !== 'pageTrigger'
+    ) {
+      wrappedCommander[key] = wrapAsync(value);
+    } else {
+      wrappedCommander[key] = value;
+    }
+  }
+
+  return {
+    // URL this action is running for
+    url,
+
+    // Abort signal - use with fetch() or custom abort logic
+    abortSignal,
+
+    // Check if action should stop
+    isStopped: () => abortSignal.aborted,
+
+    // Throw if stopped - call this in loops
+    checkStopped,
+
+    // Abort-aware iteration helper
+    forEach,
+
+    // Abort-aware wait
+    wait,
+
+    // Register cleanup callback
+    onCleanup,
+
+    // Wrapped commander - all methods throw ActionStoppedError if stopped
+    commander: wrappedCommander,
+
+    // Original commander (use carefully)
+    rawCommander: commander,
+
+    // Trigger name for debugging
+    triggerName,
+  };
+}

package/src/index.js

@@ -20,3 +20,5 @@ export {
 export * from './exports.js';
 export * from './capture/index.js';
 export { connectOrLaunch } from './browser/persistent-session.js';
+
+export { renderTrace, summarizeTrace } from './traces/render.js';

package/src/interactions/overlays.js

@@ -1,28 +1,73 @@
+import { withDeadline } from '../traces/deadline.js';
 import { isVisible } from '../elements/visibility.js';
 
-/** Dismiss only overlays explicitly named by the caller. No page markers. */
-export async function dismissOverlays({ page, engine, overlays = [] }) {
+async function dismissVisible({ page, engine, selector, timeout = 1000 }) {
+  if (engine === 'playwright') {
+    const matches = page.locator(selector);
+    for (let index = 0; index < (await matches.count()); index++) {
+      const target = matches.nth(index);
+      if (await target.isVisible()) {
+        await target.click({ timeout });
+        return 'dismissed';
+      }
+    }
+    return 'absent';
+  }
+  const matches = await page.$$(selector);
+  try {
+    for (const target of matches) {
+      if (await isVisible({ page, engine, selector: target })) {
+        await target.click({ timeout });
+        return 'dismissed';
+      }
+    }
+    return 'absent';
+  } finally {
+    await Promise.allSettled(
+      matches.map(async (target) => await target.dispose?.())
+    );
+  }
+}
+
+/** Dismiss caller-named overlays; a failed dismissal never blocks an action. */
+export async function dismissOverlays({
+  page,
+  engine,
+  overlays = [],
+  onDismiss,
+}) {
   if (!Array.isArray(overlays)) {
     throw new TypeError('overlays must be an array');
   }
+  const reports = [];
   for (const item of overlays) {
     const options = typeof item === 'string' ? { selector: item } : item;
     if (!options?.selector) {
       throw new TypeError('overlay requires selector');
     }
-    if (engine === 'playwright') {
-      const target = page.locator(options.selector).first();
-      if (await target.isVisible()) {
-        await target.click({ timeout: options.timeout ?? 1000 });
-      }
-    } else {
-      const target = await page.$(options.selector);
-      if (
-        target &&
-        (await isVisible({ page, engine, selector: options.selector }))
-      ) {
-        await target.click();
+    const report = { selector: options.selector, status: 'absent' };
+    try {
+      report.status = await withDeadline(
+        dismissVisible({ page, engine, ...options }),
+        options.timeout || 1000,
+        `overlay ${options.selector}`
+      );
+    } catch (error) {
+      report.status = 'error';
+      report.error = error;
+    }
+    reports.push(report);
+    for (const callback of [options.onDismiss, onDismiss]) {
+      try {
+        await withDeadline(
+          Promise.resolve(callback?.(report)),
+          options.timeout || 1000,
+          'overlay report'
+        );
+      } catch {
+        // Reporting must not interrupt the caller's requested interaction.
       }
     }
   }
+  return reports;
 }

package/src/traces/bundle.js

@@ -43,6 +43,7 @@ export async function openTraceBundle(options = {}) {
     now = () => Date.now(),
     monotonic = () => performance.now(),
     onEvent = null,
+    nextSequence = null,
   } = options;
 
   if (typeof output !== 'string' || output === '') {
@@ -70,6 +71,9 @@ export async function openTraceBundle(options = {}) {
   let dropped = 0;
   const counts = { checkpoints: 0, events: 0, mutationBatches: 0 };
   const problems = [];
+  let mutationIndex = null;
+  let mutationBytes = 0;
+  let mutationTruncated = false;
 
   /** Close the timeline exactly once, after every queued append. */
   function closeEvents() {
@@ -117,11 +121,13 @@ export async function openTraceBundle(options = {}) {
    * @returns {Promise<Object|null>} The event as written
    */
   async function appendEvent(event, { retry = true } = {}) {
+    const number = nextSequence?.() ?? ++sequence;
     const record = {
-      sequence: ++sequence,
+      sequence: number,
       at: new Date(now()).toISOString(),
       monotonicMs: Math.round(monotonic()),
       ...event,
+      ...(nextSequence ? { sequence: number } : {}),
     };
     const line = `${JSON.stringify(record)}\n`;
     const bytes = Buffer.byteLength(line);
@@ -275,10 +281,39 @@ export async function openTraceBundle(options = {}) {
       return null;
     }
     const member = `${TRACE_FILES.MUTATIONS_DIR}/${sequenceName(index)}.ndjson`;
-    const body = `${batches.map((batch) => JSON.stringify(batch)).join('\n')}\n`;
+    if (mutationIndex !== index) {
+      mutationIndex = index;
+      mutationBytes = 0;
+      mutationTruncated = false;
+    }
+    if (mutationTruncated) {
+      return null;
+    }
+    const ceiling = Math.min(
+      limits.maxMutationBytes ?? 4 * 1024 * 1024,
+      maxResourceBytes
+    );
+    const lines = [];
+    for (const batch of batches) {
+      const line = `${JSON.stringify(batch)}\n`;
+      if (mutationBytes + Buffer.byteLength(line) + 256 > ceiling) {
+        mutationTruncated = true;
+        const marker = `${JSON.stringify({ records: [{ kind: 'truncated', reason: 'mutation interval size limit' }] })}\n`;
+        if (mutationBytes + Buffer.byteLength(marker) <= ceiling) {
+          lines.push(marker);
+        }
+        break;
+      }
+      lines.push(line);
+      mutationBytes += Buffer.byteLength(line);
+    }
+    if (!lines.length) {
+      return null;
+    }
+    const body = lines.join('');
     const result = await writeMember(member, body, { append: true });
     if (result) {
-      counts.mutationBatches += batches.length;
+      counts.mutationBatches += lines.length;
     }
     return result ? result.member : null;
   }
@@ -319,6 +354,9 @@ export async function openTraceBundle(options = {}) {
     get bytesWritten() {
       return written;
     },
+    get mutationTruncated() {
+      return mutationTruncated;
+    },
     appendEvent,
     writeMember,
     writeCheckpoint,

package/src/traces/checkpoints.js

@@ -1,6 +1,6 @@
 import { captureSnapshotInPage } from './page-capture.js';
 import { withDeadline } from './deadline.js';
-import { redactValue, redactUrl, REDACTED } from './redaction.js';
+import { redactText, redactValue, redactUrl, REDACTED } from './redaction.js';
 import { TRACE_EVENT, TRACE_DROP_REASON } from './schema.js';
 export function createCheckpointRecorder({
   isStopped,
@@ -42,13 +42,14 @@ export function createCheckpointRecorder({
         evaluateInPage(captureSnapshotInPage, {
           redactSelectors: privacyOptions.redactSelectors,
           redactAttributes: privacyOptions.redactAttributes,
+          useDefaults: privacyOptions.useDefaults,
           redacted: REDACTED,
           html: domOptions.html,
           liveControlState: domOptions.liveControlState,
           openShadowRoots: domOptions.openShadowRoots,
           ignoreSelectors: domOptions.ignoreSelectors ?? [],
           captureText: links?.dom === 'text',
-          maxHtmlBytes: limits.maxHtmlBytes ?? 0,
+          maxHtmlBytes: limits.maxHtmlBytes ?? 4 * 1024 * 1024,
         }),
         captureTimeoutMs,
         'trace checkpoint capture'
@@ -70,7 +71,10 @@ export function createCheckpointRecorder({
 
     const members = await bundle.writeCheckpoint({
       index,
-      html: captured?.html ?? undefined,
+      html: redactText(captured?.html, privacyOptions, {
+        kind: 'dom',
+        name: 'html',
+      }),
       state: state ? { ...state, name, actor, reason } : undefined,
       screenshot: shot ?? undefined,
     });