browser-commander 0.27.0 → 0.29.0

package/src/traces/page-capture.js

@@ -28,10 +28,12 @@ export function captureSnapshotInPage(options) {
   const {
     redactSelectors = [],
     redactAttributes = [],
+    useDefaults = true,
     redacted = '[redacted]',
     html: wantHtml = true,
     liveControlState = true,
     openShadowRoots = true,
+    ignoreSelectors = [],
     maxHtmlBytes = 0,
   } = options || {};
 
@@ -120,6 +122,13 @@ export function captureSnapshotInPage(options) {
   // `<input>` otherwise shows the value the server sent, not the one the user
   // typed.
   const carryLiveState = (original, copy, secret) => {
+    if (
+      useDefaults &&
+      original.localName === 'meta' &&
+      /token|csrf|xsrf|secret/i.test(original.getAttribute('name') || '')
+    ) {
+      copy.setAttribute('content', redacted);
+    }
     for (const attribute of redactAttributes) {
       if (copy.hasAttribute && copy.hasAttribute(attribute)) {
         copy.setAttribute(attribute, redacted);
@@ -147,35 +156,96 @@ export function captureSnapshotInPage(options) {
     } else if (secret) {
       copy.textContent = redacted;
     }
-    if (original.shadowRoot && openShadowRoots) {
+    if (!secret && original.shadowRoot && openShadowRoots) {
       // Shadow content is not serialized by `outerHTML`; a declarative
       // template keeps it in the same document the viewer renders.
       const template = document.createElement('template');
       template.setAttribute('shadowrootmode', 'open');
-      template.innerHTML = original.shadowRoot.innerHTML;
+      for (const child of original.shadowRoot.childNodes) {
+        {
+          const cloned = cloneWithState(child);
+          if (cloned) {
+            template.content.appendChild(cloned);
+          }
+        }
+      }
       copy.appendChild(template);
     }
   };
 
+  const cloneWithState = (original) => {
+    if (
+      original.nodeType === 1 &&
+      ignoreSelectors.some((selector) => original.matches(selector))
+    ) {
+      return null;
+    }
+    const copy = original.cloneNode(false);
+    if (original.nodeType !== 1) {
+      return copy;
+    }
+    const secret = isSecret(original);
+    if (!secret) {
+      for (const child of original.childNodes) {
+        {
+          const cloned = cloneWithState(child);
+          if (cloned) {
+            copy.appendChild(cloned);
+          }
+        }
+      }
+    }
+    carryLiveState(original, copy, secret);
+    return copy;
+  };
+
   let html = null;
   let truncated = false;
   if (wantHtml) {
-    const clone = document.documentElement.cloneNode(true);
-    const originals = document.documentElement.querySelectorAll('*');
-    const copies = clone.querySelectorAll('*');
-    for (let index = 0; index < originals.length; index++) {
-      const copy = copies[index];
-      if (!copy) {
-        break;
-      }
-      carryLiveState(originals[index], copy, isSecret(originals[index]));
+    const clone = cloneWithState(document.documentElement);
+
+    html = `<!DOCTYPE html>\n${clone?.outerHTML ?? ''}`;
+    const encoded = new globalThis.TextEncoder().encode(html);
+    if (maxHtmlBytes > 0 && encoded.length > maxHtmlBytes) {
+      const marker = '<!-- trace HTML truncated -->';
+      const prefix = new globalThis.TextDecoder().decode(
+        encoded.slice(0, Math.max(0, maxHtmlBytes - marker.length - 3))
+      );
+      html = `${prefix}${marker}`;
+      truncated = true;
     }
+  }
 
-    html = `<!DOCTYPE html>\n${clone.outerHTML}`;
-    if (maxHtmlBytes > 0 && html.length > maxHtmlBytes) {
-      html = html.slice(0, maxHtmlBytes);
-      truncated = true;
+  const visibleText = [];
+  const collectText = (node) => {
+    if (node.nodeType === 3 && node.parentElement) {
+      const parent = node.parentElement;
+      if (
+        !parent.getClientRects().length ||
+        window.getComputedStyle(parent).visibility === 'hidden' ||
+        ignoreSelectors.some((selector) => parent.closest(selector))
+      ) {
+        return;
+      }
+      const secret = redactSelectors.some((selector) =>
+        parent.closest(selector)
+      );
+      if (node.nodeValue.trim()) {
+        visibleText.push(
+          `${cssPath(parent)}: ${secret ? redacted : node.nodeValue.trim()}`
+        );
+      }
+    } else {
+      for (const child of node.childNodes ?? []) {
+        collectText(child);
+      }
+      if (node.shadowRoot && openShadowRoots) {
+        collectText(node.shadowRoot);
+      }
     }
+  };
+  if (options?.captureText) {
+    collectText(document.documentElement);
   }
 
   return {
@@ -190,6 +260,7 @@ export function captureSnapshotInPage(options) {
         ? cssPath(document.activeElement)
         : null,
       controls,
+      ...(options?.captureText ? { text: visibleText.join('\n') } : {}),
       frames: [...document.querySelectorAll('iframe, frame')].map((frame) => ({
         path: cssPath(frame),
         src: frame.getAttribute('src'),
@@ -223,8 +294,11 @@ export function installMutationRecorderInPage(options) {
   const {
     globalName = '__browserCommanderTrace__',
     redactSelectors = [],
+    redactAttributes = [],
+    useDefaults = true,
     redacted = '[redacted]',
     maxQueued = 5000,
+    ignoreSelectors = [],
     liveState = true,
   } = options || {};
 
@@ -237,20 +311,18 @@ export function installMutationRecorderInPage(options) {
     queue: [],
     dropped: 0,
     sequence: 0,
-    // Every document gets its own name, so a batch drained from an iframe is
-    // never mistaken for one drained from the page that holds it.
     frameId: `frame-${Math.random().toString(36).slice(2, 10)}`,
     frameName: window.name || null,
     mainFrame: window.top === window,
   };
 
-  const isSecret = (node) => {
+  const matchesAny = (node, selectors) => {
     const element =
       node && node.nodeType === 1 ? node : node && node.parentElement;
     if (!element || !element.matches) {
       return false;
     }
-    return redactSelectors.some((selector) => {
+    return selectors.some((selector) => {
       try {
         return element.matches(selector) || element.closest(selector) !== null;
       } catch {
@@ -258,6 +330,43 @@ export function installMutationRecorderInPage(options) {
       }
     });
   };
+  const isSecret = (node) =>
+    matchesAny(node, redactSelectors) ||
+    (useDefaults &&
+      node?.localName === 'meta' &&
+      /token|csrf|xsrf|secret|password/i.test(node.getAttribute('name') ?? ''));
+  const isIgnored = (node) => matchesAny(node, ignoreSelectors);
+  const sanitized = (node) => {
+    const clone = node.cloneNode(true);
+    for (const selector of ignoreSelectors) {
+      for (const element of clone.querySelectorAll(selector)) {
+        element.remove();
+      }
+    }
+    for (const selector of redactSelectors) {
+      for (const element of clone.querySelectorAll(selector)) {
+        element.textContent = redacted;
+        if (element.hasAttribute('value')) {
+          element.setAttribute('value', redacted);
+        }
+      }
+    }
+    for (const element of [clone, ...clone.querySelectorAll('*')]) {
+      for (const attribute of redactAttributes) {
+        if (element.hasAttribute(attribute)) {
+          element.setAttribute(attribute, redacted);
+        }
+      }
+      if (
+        useDefaults &&
+        element.localName === 'meta' &&
+        /token|csrf|xsrf|secret/i.test(element.getAttribute('name') || '')
+      ) {
+        element.setAttribute('content', redacted);
+      }
+    }
+    return clone;
+  };
 
   // A path the viewer can look the node up by: replay needs to find the same
   // element again in a parsed copy of the checkpoint.
@@ -268,11 +377,9 @@ export function installMutationRecorderInPage(options) {
         steps.unshift(`#${at.id}`);
         break;
       }
-      const siblings = at.parentElement
-        ? [...at.parentElement.children].filter(
-            (c) => c.localName === at.localName
-          )
-        : [];
+      const siblings = [...(at.parentElement?.children ?? [])].filter(
+        (c) => c.localName === at.localName
+      );
       const nth =
         siblings.length > 1 ? `:nth-of-type(${siblings.indexOf(at) + 1})` : '';
       steps.unshift(at.localName + nth);
@@ -288,12 +395,16 @@ export function installMutationRecorderInPage(options) {
   };
 
   const describe = (node) => {
-    if (!node) {
+    if (!node || isIgnored(node)) {
       return null;
     }
     if (node.nodeType === 3) {
       return {
         type: 'text',
+        visible: node.parentElement
+          ? node.parentElement.getClientRects().length > 0 &&
+            window.getComputedStyle(node.parentElement).visibility !== 'hidden'
+          : true,
         path: pathOf(node.parentElement),
         text: isSecret(node) ? redacted : String(node.nodeValue).slice(0, 2000),
       };
@@ -301,12 +412,36 @@ export function installMutationRecorderInPage(options) {
     if (node.nodeType !== 1) {
       return { type: 'node', nodeType: node.nodeType };
     }
+    const clone = sanitized(node);
     return {
       type: 'element',
       tag: node.localName,
       id: node.id || null,
       path: pathOf(node),
-      html: isSecret(node) ? redacted : String(node.outerHTML).slice(0, 4000),
+      html: isSecret(node) ? redacted : String(clone.outerHTML).slice(0, 4000),
+      text: isSecret(node)
+        ? redacted
+        : String(clone.textContent).slice(0, 2000),
+      visible:
+        node.getClientRects().length > 0 &&
+        window.getComputedStyle(node).visibility !== 'hidden',
+    };
+  };
+
+  // Mutation targets identify an existing node. Only additions need markup.
+  const identify = (node) => {
+    if (!node || isIgnored(node)) {
+      return null;
+    }
+    const element = node.nodeType === 1 ? node : node.parentElement;
+    return {
+      type: node.nodeType === 3 ? 'text' : 'element',
+      path: pathOf(element),
+      tag: element?.localName,
+      id: element?.id || null,
+      visible:
+        Boolean(element?.getClientRects().length) &&
+        window.getComputedStyle(element).visibility !== 'hidden',
     };
   };
 
@@ -364,41 +499,45 @@ export function installMutationRecorderInPage(options) {
       return;
     }
     push({
-      records: records.map((record) => {
-        const entry = {
-          kind: record.type,
-          target: describe(record.target),
-        };
-        if (record.type === 'attributes') {
-          entry.attribute = record.attributeName;
-          const secret =
-            isSecret(record.target) ||
-            redactSelectors.includes(record.attributeName);
-          entry.before = secret ? redacted : record.oldValue;
-          entry.after =
-            secret || !record.target.getAttribute
+      records: records
+        .filter((record) => !isIgnored(record.target))
+        .map((record) => {
+          const entry = {
+            kind: record.type,
+            target: identify(record.target),
+          };
+          if (record.type === 'attributes') {
+            entry.attribute = record.attributeName;
+            const secret =
+              isSecret(record.target) ||
+              redactAttributes.includes(record.attributeName) ||
+              (useDefaults &&
+                /token|csrf|xsrf|secret|password/i.test(record.attributeName));
+            entry.before = secret ? redacted : record.oldValue;
+            entry.after =
+              secret || !record.target.getAttribute
+                ? redacted
+                : record.target.getAttribute(record.attributeName);
+          } else if (record.type === 'characterData') {
+            entry.before = isSecret(record.target) ? redacted : record.oldValue;
+            entry.after = isSecret(record.target)
               ? redacted
-              : record.target.getAttribute(record.attributeName);
-        } else if (record.type === 'characterData') {
-          entry.before = isSecret(record.target) ? redacted : record.oldValue;
-          entry.after = isSecret(record.target)
-            ? redacted
-            : record.target.nodeValue;
-        } else {
-          // Where a node went is as much of the change as what it was:
-          // appending every addition to the end replays an insertion before a
-          // sibling in the wrong place, and drops moves and removals entirely.
-          entry.added = [...record.addedNodes].map((node) =>
-            describeAt(node, record)
-          );
-          entry.removed = [...record.removedNodes].map((node) =>
-            describeAt(node, record)
-          );
-          entry.previous = describe(record.previousSibling);
-          entry.next = describe(record.nextSibling);
-        }
-        return entry;
-      }),
+              : record.target.nodeValue;
+          } else {
+            // Where a node went is as much of the change as what it was:
+            // appending every addition to the end replays an insertion before a
+            // sibling in the wrong place, and drops moves and removals entirely.
+            entry.added = [...record.addedNodes]
+              .filter((node) => !isIgnored(node))
+              .map((node) => describeAt(node, record));
+            entry.removed = [...record.removedNodes]
+              .filter((node) => !isIgnored(node))
+              .map((node) => describeAt(node, record));
+            entry.previous = identify(record.previousSibling);
+            entry.next = identify(record.nextSibling);
+          }
+          return entry;
+        }),
     });
   });
 
@@ -420,7 +559,6 @@ export function installMutationRecorderInPage(options) {
     // into a field and then leaving it fires `input` for each keystroke and
     // `change` for the value it ended at, and a checkbox fires both for the
     // one click. Replaying a state that is already on screen shows nothing, so
-    // a repeat of what this element last reported is not recorded.
     const repeats = (element, property, after) => {
       const seen = lastLive.get(element) || {};
       const asText = JSON.stringify(after === undefined ? null : after);
@@ -435,16 +573,13 @@ export function installMutationRecorderInPage(options) {
     const liveEntry = (target, property, after, before) => ({
       kind: 'live-state',
       property,
-      target: describe(target),
+      target: identify(target),
       before: before === undefined ? null : before,
       after,
     });
 
     const pushLive = (entry) => {
-      // Scrolling fires far more often than it changes anything worth
-      // replaying, so consecutive scrolls of one element collapse into the
-      // position it ended at. Every other property keeps each step, because
-      // "stepwise replay must show each state" (issue #93).
+      // Consecutive scrolls collapse; other state changes retain each step.
       const last = state.queue[state.queue.length - 1];
       const only = last && last.records.length === 1 ? last.records[0] : null;
       if (
@@ -470,7 +605,7 @@ export function installMutationRecorderInPage(options) {
 
     const onValue = (event) => {
       const element = event.target;
-      if (!element || element.nodeType !== 1) {
+      if (!element || element.nodeType !== 1 || isIgnored(element)) {
         return;
       }
       if (element.type === 'checkbox' || element.type === 'radio') {
@@ -517,7 +652,7 @@ export function installMutationRecorderInPage(options) {
       pushLive({
         kind: 'live-state',
         property: 'scroll',
-        target: scrolling ? describe(scrolling) : null,
+        target: scrolling ? identify(scrolling) : null,
         before: null,
         after: scrolling
           ? { top: scrolling.scrollTop, left: scrolling.scrollLeft }

package/src/traces/reader.js

@@ -7,8 +7,8 @@
  * than rejected.
  */
 
-import fs from 'node:fs/promises';
 import path from 'node:path';
+import { readTraceText } from './storage.js';
 import {
   assertReadableManifest,
   createManifest,
@@ -18,15 +18,8 @@ import {
   TRACE_OUTCOME,
 } from './schema.js';
 
-async function readIfPresent(file) {
-  try {
-    return await fs.readFile(file, 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return null;
-    }
-    throw error;
-  }
+function readIfPresent(file) {
+  return readTraceText(file);
 }
 
 /**
@@ -64,6 +57,11 @@ export function parseNdjson(body) {
  */
 export async function readTrace(bundlePath) {
   const root = path.resolve(bundlePath);
+  const segments = await readIfPresent(path.join(root, 'segments.json'));
+  if (segments) {
+    const { readRollingTrace } = await import('./rolling.js');
+    return readRollingTrace(root, JSON.parse(segments), readTrace);
+  }
   const manifestBody = await readIfPresent(
     path.join(root, TRACE_FILES.MANIFEST)
   );