browser-debugger-cli 0.7.2 → 0.9.0

package/dist/runtime/dom/listenerPageScripts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Page-side functions of `bdg dom listeners`: what only the page can tell
+ * about an element's listeners (handler names and identities, React root
+ * containers, the handlers behind jQuery's dispatcher, React's `on…` props
+ * of the element and its ancestors, the element's iframe).
+ *
+ * Each piece is a function expression in a string, combined into
+ * {@link ELEMENT_INFO_JS}; every lookup of page globals is guarded, so a
+ * page with odd globals (a throwing `jQuery` getter) only loses that detail.
+ */
+/** Most jQuery handlers resolved per call; the rest keep jQuery's dispatcher */
+export declare const MAX_JQUERY_HANDLERS = 50;
+/** Most React prop handlers resolved per call; the rest are counted */
+export declare const MAX_REACT_HANDLERS = 50;
+/**
+ * Page function, called on the element with the listeners (position in the
+ * chain and event type of each), the requested event types (null for all;
+ * React props are filtered before the limit), then the chain's objects, then each
+ * listener's handler, then the function each handler calls (a bound
+ * function's target, else null).
+ *
+ * Returns `[info, ...jQueryHandlers, ...reactHandlers]`. `info` has the
+ * iframe element holding the element's document (`frame`), a framework
+ * label per chain entry (`roots`), per listener the handler's name, the
+ * identity and name of the function it calls (equal identities are the same
+ * function object) and, for jQuery's dispatcher, the jQuery handlers that
+ * run for the element; then the React `on…` props that run for the
+ * element's events (`react`, see {@link REACT_HANDLERS_JS}). Their functions follow `info` in the same order.
+ * After {@link MAX_JQUERY_HANDLERS}, dispatchers stay unresolved and are
+ * counted in `jquerySkipped`; after {@link MAX_REACT_HANDLERS}, React props
+ * are counted in `reactSkipped`.
+ */
+export declare const ELEMENT_INFO_JS: string;
+/** What {@link ELEMENT_INFO_JS} reports, by value */
+export interface ElementInfo {
+    frame: string | null;
+    roots: Array<string | null>;
+    listeners: Array<{
+        name: string | null;
+        identity: number | null;
+        targetName: string | null;
+        jquery?: Array<{
+            type: string;
+            selector: string | null;
+            name: string;
+        }>;
+    }>;
+    /** jQuery handlers left unresolved (over the limit) */
+    jquerySkipped: number;
+    /** React `on…` props that run for the element's events, nearest first */
+    react: Array<{
+        /** Position of the element the prop is on in the chain (0 = the inspected element); null outside it (a portal's React parent) */
+        position: number | null;
+        /** Description of that element when it is outside the chain */
+        node?: string;
+        /** Prop name, e.g. `onClickCapture` */
+        prop: string;
+        /** DOM event type, e.g. `click` */
+        type: string;
+        capture: boolean;
+        name: string;
+    }>;
+    /** React props left unresolved (over the limit) */
+    reactSkipped: number;
+}
+//# sourceMappingURL=listenerPageScripts.d.ts.map

package/dist/runtime/dom/listenerPageScripts.js

@@ -0,0 +1,279 @@
+/**
+ * Page-side functions of `bdg dom listeners`: what only the page can tell
+ * about an element's listeners (handler names and identities, React root
+ * containers, the handlers behind jQuery's dispatcher, React's `on…` props
+ * of the element and its ancestors, the element's iframe).
+ *
+ * Each piece is a function expression in a string, combined into
+ * {@link ELEMENT_INFO_JS}; every lookup of page globals is guarded, so a
+ * page with odd globals (a throwing `jQuery` getter) only loses that detail.
+ */
+/** Most jQuery handlers resolved per call; the rest keep jQuery's dispatcher */
+export const MAX_JQUERY_HANDLERS = 50;
+/** Most React prop handlers resolved per call; the rest are counted */
+export const MAX_REACT_HANDLERS = 50;
+/** `(element, view) => string | null`: the iframe element holding the element's document */
+const FRAME_OF_JS = `(element, view) => {
+  try {
+    const owner = view && view.frameElement;
+    return owner ? owner.tagName.toLowerCase() + (owner.id ? '#' + owner.id : '') : null;
+  } catch (e) { return null; }
+}`;
+/** `(node) => boolean`: whether the node is a React root container */
+const REACT_ROOT_JS = `(node) => {
+  try {
+    return !!node && node.nodeType === 1 &&
+      ('_reactRootContainer' in node || Object.keys(node).some((key) => key.startsWith('__reactContainer$')));
+  } catch (e) { return false; }
+}`;
+/** `(view) => jQuery | undefined`: the page's jQuery, when it has one */
+const JQUERY_OF_JS = `(view) => {
+  try {
+    if (!view) return undefined;
+    return [view.jQuery, view.$].find((c) => c && typeof c._data === 'function');
+  } catch (e) { return undefined; }
+}`;
+/**
+ * `(jq, element, node, type, handler) => handleObj[] | null`: the jQuery
+ * handlers that run for `element` when `handler` is jQuery's dispatcher on
+ * `node` (delegates only when the element, or an element between it and
+ * `node`, matches their selector); null when it is not the dispatcher.
+ */
+const JQUERY_HANDLERS_JS = `(jq, element, node, type, handler) => {
+  try {
+    if (typeof handler !== 'function') return null;
+    const data = jq._data(node);
+    if (!data || data.handle !== handler || !data.events) return null;
+    const find = jq.find;
+    const matches = (el, selector) => {
+      try {
+        return find && typeof find.matchesSelector === 'function' ? find.matchesSelector(el, selector) : el.matches(selector);
+      } catch (e) { return false; }
+    };
+    const delegatedTo = (selector) => {
+      for (let el = element; el && el !== node; el = el.parentNode) {
+        if (el.nodeType === 1 && matches(el, selector)) return true;
+      }
+      return false;
+    };
+    return Array.from(data.events[type] || []).filter((h) => !h.selector || delegatedTo(h.selector));
+  } catch (e) { return null; }
+}`;
+/**
+ * `(object, key) => value`: an own data property, read without running a
+ * getter the page may have defined (undefined for accessors and on errors).
+ */
+const OWN_VALUE_JS = `(object, key) => {
+  try {
+    const descriptor = object ? Object.getOwnPropertyDescriptor(object, key) : undefined;
+    return descriptor ? descriptor.value : undefined;
+  } catch (e) { return undefined; }
+}`;
+/**
+ * `(node, prefixes) => value`: the value of the node's own key starting with
+ * one of `prefixes` (React's keys end in a random suffix).
+ */
+const REACT_KEY_JS = `(node, prefixes) => {
+  try {
+    const key = Object.keys(node).find((k) => prefixes.some((prefix) => k.startsWith(prefix)));
+    return key === undefined ? undefined : (${OWN_VALUE_JS})(node, key);
+  } catch (e) { return undefined; }
+}`;
+/** `(node) => fiber | undefined`: React's fiber of a DOM element */
+const REACT_FIBER_JS = `(node) => (${REACT_KEY_JS})(node, ['__reactFiber$', '__reactInternalInstance$'])`;
+/**
+ * `(node) => object | null`: the props React rendered on a DOM element:
+ * `__reactProps$…` (React 17-19), `__reactEventHandlers$…` (React 16), else
+ * the `memoizedProps` of its fiber.
+ */
+const REACT_PROPS_JS = `(node) => {
+  if (!node || node.nodeType !== 1) return null;
+  const props = (${REACT_KEY_JS})(node, ['__reactProps$', '__reactEventHandlers$']);
+  if (props && typeof props === 'object') return props;
+  const memoized = (${OWN_VALUE_JS})((${REACT_FIBER_JS})(node), 'memoizedProps');
+  return memoized && typeof memoized === 'object' ? memoized : null;
+}`;
+/** Most fibers walked up from the element (guards against cycles) */
+const MAX_FIBER_STEPS = 1000;
+/**
+ * `(element, nodes) => Array<{ node, position }>`: the DOM elements whose
+ * React props run for events on the element, nearest first. With a fiber,
+ * the host components on its `.return` path (so a portal's React parents
+ * count and DOM parents outside the React path don't); `position` is the
+ * node's place in the chain, null outside it. Without one, the chain's elements.
+ */
+const REACT_HOSTS_JS = `(element, nodes) => {
+  const own = ${OWN_VALUE_JS};
+  let fiber = (${REACT_FIBER_JS})(element);
+  if (!fiber) return nodes.flatMap((node, position) => (node && node.nodeType === 1 ? [{ node, position }] : []));
+  const hosts = [];
+  const seen = new Set();
+  for (let step = 0; fiber && typeof fiber === 'object' && !seen.has(fiber) && step < ${MAX_FIBER_STEPS}; step++) {
+    seen.add(fiber);
+    const node = own(fiber, 'stateNode');
+    if (typeof own(fiber, 'type') === 'string' && node && node.nodeType === 1) {
+      const position = nodes.indexOf(node);
+      hosts.push({ node, position: position === -1 ? null : position });
+    }
+    fiber = own(fiber, 'return');
+  }
+  return hosts;
+}`;
+/** `(node) => string`: CDP-like description of an element, e.g. `div#app.card` */
+const DESCRIBE_NODE_JS = `(node) => {
+  try {
+    const classes = Array.from(node.classList || []).map((c) => '.' + c).join('');
+    return String(node.localName || 'element') + (node.id ? '#' + node.id : '') + classes;
+  } catch (e) { return 'element'; }
+}`;
+/**
+ * `(props) => Array<{ prop, handler, name }>`: the event handler props
+ * (`onClick`, `onKeyDownCapture`) among React props, read without
+ * running getters.
+ */
+const REACT_HANDLER_PROPS_JS = `(props) => {
+  const own = ${OWN_VALUE_JS};
+  try {
+    return Object.keys(props).filter((prop) => /^on[A-Z]/.test(prop)).flatMap((prop) => {
+      const handler = own(props, prop);
+      if (typeof handler !== 'function') return [];
+      const name = own(handler, 'name');
+      return [{ prop, handler, name: typeof name === 'string' ? name : '' }];
+    });
+  } catch (e) { return []; }
+}`;
+/**
+ * `(prop) => { type, capture }`: the DOM event type and phase of a React
+ * handler prop: `onClick` → click, `onClickCapture` → click in the capture
+ * phase, `onDoubleClick` → dblclick, `onFocus`/`onBlur` → focusin/focusout
+ * (the events React listens for), `onGotPointerCapture` → gotpointercapture
+ * (and `onGotPointerCaptureCapture` its capture phase).
+ */
+const REACT_EVENT_TYPE_JS = `(prop) => {
+  const base = prop.slice(2);
+  const capture = base.endsWith('Capture') && !/^(?:Got|Lost)PointerCapture$/.test(base);
+  const name = (capture ? base.slice(0, -7) : base).toLowerCase();
+  const types = { doubleclick: 'dblclick', focus: 'focusin', blur: 'focusout' };
+  return { type: types[name] || name, capture };
+}`;
+/**
+ * Event types React does not bubble to parents (their bubble-phase props on
+ * ancestors never run for the element): enter/leave, scroll (React 17+),
+ * and the events React listens for on the element itself (media, load, …).
+ */
+const REACT_NON_BUBBLING_TYPES = [
+    'mouseenter',
+    'mouseleave',
+    'pointerenter',
+    'pointerleave',
+    'scroll',
+    'scrollend',
+    'load',
+    'error',
+    'abort',
+    'cancel',
+    'close',
+    'invalid',
+    'toggle',
+    'canplay',
+    'canplaythrough',
+    'durationchange',
+    'emptied',
+    'encrypted',
+    'ended',
+    'loadeddata',
+    'loadedmetadata',
+    'loadstart',
+    'pause',
+    'play',
+    'playing',
+    'progress',
+    'ratechange',
+    'seeked',
+    'seeking',
+    'stalled',
+    'suspend',
+    'timeupdate',
+    'volumechange',
+    'waiting',
+];
+/**
+ * `(element, nodes, wanted, fns) => { react, reactSkipped }`: the React
+ * `on…` props that run for events on the element (its own, and bubbling or
+ * capture ones of its React parents), limited to the `wanted` types (all
+ * when null); their functions are pushed to `fns`.
+ */
+const REACT_HANDLERS_JS = `(element, nodes, wanted, fns) => {
+  const nonBubbling = new Set(${JSON.stringify(REACT_NON_BUBBLING_TYPES)});
+  const react = [];
+  let reactSkipped = 0;
+  (${REACT_HOSTS_JS})(element, nodes).forEach(({ node, position }, depth) => {
+    const props = (${REACT_PROPS_JS})(node);
+    if (!props) return;
+    for (const { prop, handler, name } of (${REACT_HANDLER_PROPS_JS})(props)) {
+      const { type, capture } = (${REACT_EVENT_TYPE_JS})(prop);
+      if ((wanted && !wanted.has(type)) || (depth > 0 && !capture && nonBubbling.has(type))) continue;
+      if (react.length >= ${MAX_REACT_HANDLERS}) { reactSkipped++; continue; }
+      fns.push(handler);
+      react.push({ position, ...(position === null && { node: (${DESCRIBE_NODE_JS})(node) }), prop, type, capture, name });
+    }
+  });
+  return { react, reactSkipped };
+}`;
+/**
+ * Page function, called on the element with the listeners (position in the
+ * chain and event type of each), the requested event types (null for all;
+ * React props are filtered before the limit), then the chain's objects, then each
+ * listener's handler, then the function each handler calls (a bound
+ * function's target, else null).
+ *
+ * Returns `[info, ...jQueryHandlers, ...reactHandlers]`. `info` has the
+ * iframe element holding the element's document (`frame`), a framework
+ * label per chain entry (`roots`), per listener the handler's name, the
+ * identity and name of the function it calls (equal identities are the same
+ * function object) and, for jQuery's dispatcher, the jQuery handlers that
+ * run for the element; then the React `on…` props that run for the
+ * element's events (`react`, see {@link REACT_HANDLERS_JS}). Their functions follow `info` in the same order.
+ * After {@link MAX_JQUERY_HANDLERS}, dispatchers stay unresolved and are
+ * counted in `jquerySkipped`; after {@link MAX_REACT_HANDLERS}, React props
+ * are counted in `reactSkipped`.
+ */
+export const ELEMENT_INFO_JS = `function (listeners, types, ...rest) {
+  const count = listeners.length;
+  const nodes = rest.slice(0, rest.length - 2 * count);
+  const handlers = rest.slice(nodes.length, nodes.length + count);
+  const targets = rest.slice(nodes.length + count);
+  const view = this.ownerDocument && this.ownerDocument.defaultView;
+  const jq = (${JQUERY_OF_JS})(view);
+  const ids = new Map();
+  const identity = (fn) => {
+    if (typeof fn !== 'function') return null;
+    if (!ids.has(fn)) ids.set(fn, ids.size);
+    return ids.get(fn);
+  };
+  const fns = [];
+  let jquerySkipped = 0;
+  const describeHandler = (h) => {
+    fns.push(h.handler);
+    return { type: h.origType || h.type, selector: h.selector || null,
+      name: typeof h.handler === 'function' ? h.handler.name : '' };
+  };
+  const info = listeners.map((listener, i) => {
+    const handler = handlers[i];
+    const target = typeof targets[i] === 'function' ? targets[i] : handler;
+    const entry = { name: typeof handler === 'function' ? handler.name : null, identity: identity(target),
+      targetName: typeof target === 'function' ? target.name : null };
+    const resolved = jq ? (${JQUERY_HANDLERS_JS})(jq, this, nodes[listener.position], listener.type, handler) : null;
+    if (!resolved) return entry;
+    if (fns.length + resolved.length > ${MAX_JQUERY_HANDLERS}) {
+      jquerySkipped += resolved.length;
+      return entry;
+    }
+    return { ...entry, jquery: resolved.map(describeHandler) };
+  });
+  const roots = nodes.map((node) => ((${REACT_ROOT_JS})(node) ? 'React root' : null));
+  const wanted = types && types.length > 0 ? new Set(types) : null;
+  const { react, reactSkipped } = (${REACT_HANDLERS_JS})(this, nodes, wanted, fns);
+  return [{ frame: (${FRAME_OF_JS})(this, view), roots, listeners: info, jquerySkipped, react, reactSkipped }, ...fns];
+}`;
+//# sourceMappingURL=listenerPageScripts.js.map

package/dist/runtime/dom/listenerSummary.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Turning CDP event listener data into the `bdg dom listeners` report.
+ *
+ * Pure functions: the daemon collects the listeners of an element, its
+ * ancestors, its document and window (`inspectEventListeners`), and
+ * these name, place, filter and order them.
+ */
+import type { Protocol } from '../../connection/typed-cdp.js';
+import type { CollapsedListeners, ElementListener, ListenerPlacement } from '../../ipc/protocol/domTypes.js';
+/** An event target on the path from the element out to its window. */
+export interface ChainEntry {
+    /** CDP class name, e.g. `HTMLDivElement`, `HTMLDocument`, `Window` */
+    className?: string | undefined;
+    /** CDP description, e.g. `div#root.app` */
+    description?: string | undefined;
+    /** Framework recognised on the node, e.g. `React root` */
+    framework?: string | undefined;
+}
+/** Listeners found on one entry of the chain. */
+export interface ChainListeners {
+    /** Position in the chain: 0 is the element itself */
+    position: number;
+    entry: ChainEntry;
+    listeners: Protocol.DOMDebugger.EventListener[];
+}
+/**
+ * Where an entry of the chain sits relative to the element.
+ *
+ * @param entry - Chain entry
+ * @param position - Position in the chain (0 = the element)
+ * @returns Placement
+ */
+export declare function listenerPlacement(entry: ChainEntry, position: number): ListenerPlacement;
+/**
+ * Short description of a chain entry, e.g. `div#root.app`.
+ *
+ * @param entry - Chain entry
+ * @returns Description
+ */
+export declare function describeChainEntry(entry: ChainEntry): string;
+/**
+ * First characters of a function's source, on one line.
+ *
+ * @param source - Function source (the handler's CDP description)
+ * @returns Preview
+ */
+export declare function handlerPreview(source: string | undefined): string;
+/**
+ * Name of a function as written in its source (fallback when the page could
+ * not report `Function.name`).
+ *
+ * @param source - Function source
+ * @returns Name, or '' for anonymous and arrow functions
+ */
+export declare function functionNameFromSource(source: string | undefined): string;
+/** What the page reported about one listener's handler */
+export interface HandlerDetails {
+    /** `Function.name` of the handler */
+    name?: string | undefined;
+    /**
+     * Identity of the function the handler calls (bound functions unwrapped to
+     * their target): equal ids are the same function object
+     */
+    identity?: number | undefined;
+    /** `Function.name` of that function */
+    targetName?: string | undefined;
+    /** Handlers jQuery runs from this listener (set when it is jQuery's dispatcher) */
+    jquery?: ResolvedHandler[] | undefined;
+}
+/** A handler registered through a framework, found behind its dispatcher */
+export interface ResolvedHandler {
+    /** Event type it was registered for */
+    type: string;
+    /** Delegate selector, for delegated handlers */
+    selector?: string | undefined;
+    /** `Function.name` */
+    name: string;
+    /** Function source */
+    source?: string | undefined;
+    scriptId: string;
+    lineNumber: number;
+    columnNumber: number;
+}
+/** A React `on…` prop handler of the element or one of its React parents */
+export interface ReactPropHandler extends ResolvedHandler {
+    /**
+     * Position in the chain of the element the prop is on (0 = the element);
+     * null for a React parent outside the chain (the parent of a portal)
+     */
+    position: number | null;
+    /** Description of that element when it is outside the chain */
+    node?: string | undefined;
+    /** Prop name, e.g. `onClickCapture` */
+    prop: string;
+    /** Runs in the capture phase (`on…Capture`) */
+    capture: boolean;
+}
+/** What to keep in the report */
+export interface ReportOptions {
+    /** Event types to keep (default: all) */
+    types?: string[] | undefined;
+    /** Keep every framework root listener instead of a summary per node */
+    all?: boolean | undefined;
+}
+/** The `bdg dom listeners` report */
+export interface ListenerReport {
+    listeners: ElementListener[];
+    collapsed: CollapsedListeners[];
+}
+/** A report entry with its position in the chain */
+export interface PlacedListener {
+    position: number;
+    entry: ChainEntry;
+    listener: ElementListener;
+    /** Identity of the handler's function (unique when unknown) */
+    identity: string;
+    /** Name of the handler's function, bound functions unwrapped */
+    targetName?: string | undefined;
+}
+/**
+ * Whether a function source is an empty function (`function u0(){}`,
+ * `() => {}`): React sets one as `onclick` on clickable elements.
+ *
+ * @param source - Function source
+ * @returns True for a handler that does nothing
+ */
+export declare function isNoopSource(source: string | undefined): boolean;
+/**
+ * Collapse framework roots: on a recognised React root container (not the
+ * element itself), function objects that each listen for several event
+ * types, and together for many, are React's dispatchers. Each root's
+ * dispatchers become one summary entry; other multi-type handlers (an
+ * analytics listener on `document`) are kept as they are.
+ *
+ * @param placed - Report entries
+ * @returns Entries kept as they are, and one summary per framework root
+ */
+export declare function collapseFrameworkRoots(placed: PlacedListener[]): {
+    kept: PlacedListener[];
+    collapsed: CollapsedListeners[];
+};
+/**
+ * Build the listener report: React's `on…` props added, filtered to `types`
+ * (if given), framework roots collapsed (unless `all`), grouped by event
+ * type with the handlers nearest the element first (see {@link orderListeners}).
+ *
+ * @param found - Listeners per chain entry, in chain order
+ * @param details - Per flattened listener: handler name, jQuery handlers (missing = unknown)
+ * @param options - Event types to keep, whether to keep every root listener
+ * @param react - React prop handlers of the element and its ancestors
+ * @returns Ordered listeners and collapsed framework roots
+ */
+export declare function buildListenerReport(found: ChainListeners[], details: HandlerDetails[], options?: ReportOptions, react?: ReactPropHandler[]): ListenerReport;
+/**
+ * How an event type without a listener of its own on the element reaches
+ * its handlers:
+ * - `react`: React runs `on…` props listed in the report (from its root)
+ * - `react-root`: a React root listens for it, but no `on…` prop was found
+ * - `jquery`: jQuery runs delegated handlers listed in the report
+ * - `delegated`: plain listeners on ancestors, document or window
+ */
+export type DelegationKind = 'react' | 'react-root' | 'jquery' | 'delegated';
+/** Interaction event types handled the same way, for the report's notes */
+export interface DelegationNote {
+    kind: DelegationKind;
+    /** Event types, in report order */
+    types: string[];
+    /** Those of `types` whose only listener on the element is a no-op (React's placeholder) */
+    placeholderTypes: string[];
+    /** The node handling them: the React root container or jQuery's node */
+    node?: string | undefined;
+}
+/**
+ * Notes for interaction event types the element has no listener of its own
+ * for (no-ops aside), grouped by how they reach their handlers: React `on…`
+ * props, a React root without props, jQuery delegation, or plain listeners
+ * on ancestors, document or window.
+ *
+ * @param listeners - Listener report
+ * @param collapsed - Collapsed framework roots
+ * @returns Notes, React first; none when every type has a listener on the element
+ */
+export declare function delegationNotes(listeners: ElementListener[], collapsed?: CollapsedListeners[]): DelegationNote[];
+/**
+ * Event types with listeners that a `--type` value probably meant, for an
+ * empty result: `Click` → `click`, `onclick` → `click`.
+ *
+ * @param requested - Types asked for
+ * @param available - Types that have listeners
+ * @returns Suggestions (none when nothing is close)
+ */
+export declare function suggestEventTypes(requested: string[], available: string[]): string[];
+//# sourceMappingURL=listenerSummary.d.ts.map