browser-debugger-cli 0.15.0 → 0.16.0

package/dist/runtime/dom/actionEffects.js

@@ -5,12 +5,17 @@
  * working on the result. Costs one page script sent before the action (not
  * waited for: CDP runs it before the action's own scripts) and one read
  * after it, plus a second look 300 ms later when nothing seemed to happen.
+ * While watching, a timer in bdg's world notes the stalls during which the
+ * page's tasks could not run ({@link STALL_WATCH_START_SCRIPT}); they do not
+ * count as quiet time when deciding whether the DOM kept changing.
  * Worst case, when the page does not answer (a navigation is pending, or a
  * long script runs), the snapshot is given up after {@link START_TIMEOUT_MS}
- * and each read after {@link READ_TIMEOUT_MS}.
+ * and each read after {@link READ_TIMEOUT_MS}, plus as long again, once per
+ * action, to ask whether the page ran a long task ({@link pageAnswer}).
  */
-import { EFFECTS_READ_SCRIPT, EFFECTS_START_SCRIPT, EFFECTS_STOP_SCRIPT, } from './actionEffectsScripts.js';
+import { AWAIT_DUE_TIMERS_SCRIPT, EFFECTS_READ_SCRIPT, EFFECTS_START_SCRIPT, EFFECTS_STOP_SCRIPT, LONG_TASKS_READ_SCRIPT, START_DUE_TIMERS_SCRIPT, STALL_READ_SCRIPT, STALL_WATCH_START_SCRIPT, STALL_WATCH_STOP_SCRIPT, } from './actionEffectsScripts.js';
 import { listenForActivity, } from './pageActivity.js';
+import { evaluateInBdgWorld, hasBdgWorld } from '../page/bdgWorld.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { delay, raceTimeout } from '../../utils/async.js';
 import { getErrorMessage } from '../../utils/errors.js';
@@ -21,21 +26,53 @@ const MAX_NEW_MESSAGES = 3;
 const MAX_SHOWN_ELEMENTS = 3;
 /**
  * Bursts of DOM changes that make the DOM look busy: at least this many
- * within {@link BUSY_WINDOW_MS}, the last within {@link BUSY_RECENT_MS}
+ * within {@link BUSY_WINDOW_MS}, the last within {@link BUSY_RECENT_MS} of
+ * quiet time ({@link quietMs})
  */
 const BUSY_BURSTS = 2;
 const BUSY_WINDOW_MS = 500;
 const BUSY_RECENT_MS = 150;
-/** Second look at a DOM that looked busy; it is still changing with {@link BUSY_BURSTS} new bursts by then (ms) */
+/**
+ * Quiet time since a single burst under which the DOM still looks busy (ms):
+ * the page stalled for most of the time since, so its next change could not
+ * come. Higher, a short task after a single render (garbage collection, a
+ * layout) would cost every such click a second look.
+ */
+const LONE_BURST_QUIET_MS = 75;
+/**
+ * Second look at a DOM that looked busy; it is still changing when it
+ * changed again and was never quiet longer than {@link BUSY_RECENT_MS}
+ * until then (ms)
+ */
 const STILL_CHANGING_RECHECK_MS = 250;
 /** Resource types of pending requests that mean more content is coming */
 const CONTENT_REQUEST_TYPES = new Set(['Document', 'XHR', 'Fetch', 'Script']);
 /** Longest message text reported */
 const MAX_MESSAGE_LENGTH = 120;
+/**
+ * How long reading the stalls ({@link STALL_READ_SCRIPT}) may take after a
+ * read whose bursts make the stalls matter; without an answer, none are
+ * known
+ */
+const STALLS_READ_TIMEOUT_MS = 100;
 /** How long collecting waits for the snapshot taken before the action */
 const START_TIMEOUT_MS = 200;
-/** How long a read after the action may take before its part is skipped */
+/**
+ * How long a read after the action may take before its part is skipped. A
+ * read has up to three steps ({@link letDueTimersRun}): setting a timer (up
+ * to this), waiting for it (up to {@link DUE_TIMERS_TIMEOUT_MS}) and reading
+ * (up to this again), so about 600 ms at worst; a DOM that looks busy is
+ * read twice.
+ */
 const READ_TIMEOUT_MS = 250;
+/**
+ * How long a read waits for the timer it set once the page has set it,
+ * before reading anyway: a 0 ms timer waits for the 0 ms tasks queued before
+ * it (measured: under 1 ms on an idle page, 5 ms behind a MessageChannel
+ * scheduler, 50 ms behind ten chains of 5 ms tasks), and throttled timers
+ * may not run for a second
+ */
+const DUE_TIMERS_TIMEOUT_MS = 100;
 /** Second look before claiming "no effect" (late timers, animations) */
 const NO_EFFECT_RECHECK_MS = 300;
 /**
@@ -121,26 +158,67 @@ export function shownElements(shown, messages) {
         .slice(0, MAX_SHOWN_ELEMENTS)
         .map((element) => ({ ...element, text: cutText(element.text) }));
 }
+/**
+ * Bursts of a read within {@link BUSY_WINDOW_MS} that may make the DOM look
+ * busy, else none: at least {@link BUSY_BURSTS} of them, or a single one
+ * older than {@link BUSY_RECENT_MS} (quiet since, unless the page stalled
+ * and its next change could not come).
+ *
+ * @param settle - Signals of the read
+ * @returns Ages of those bursts (ms), or an empty list
+ */
+function recentBursts(settle) {
+    const recent = (settle?.burstAges ?? []).filter((age) => age <= BUSY_WINDOW_MS);
+    if (recent.length >= BUSY_BURSTS)
+        return recent;
+    return recent.length === 1 && (recent[0] ?? 0) > BUSY_RECENT_MS ? recent : [];
+}
+/**
+ * How long the page was quiet between two moments of a read: the time
+ * between them less the stalls in it, during which the page's tasks could
+ * not run, so it could not change the DOM either.
+ *
+ * @param fromAge - Earlier moment, as an age at the read (ms)
+ * @param toAge - Later moment, as an age at the read (ms)
+ * @param stalls - Stalls of the read (they do not overlap)
+ * @returns Quiet time (ms)
+ */
+export function quietMs(fromAge, toAge, stalls = []) {
+    const stalled = stalls.reduce((sum, [began, ended]) => sum + Math.max(0, Math.min(fromAge, began) - Math.max(toAge, ended)), 0);
+    return fromAge - toAge - stalled;
+}
 /**
  * Whether a read's DOM looks busy, worth a second look: at least
  * {@link BUSY_BURSTS} bursts of structural changes within
- * {@link BUSY_WINDOW_MS}, the last within {@link BUSY_RECENT_MS}. Text-only
- * changes (clocks) and style changes (animations) are not bursts.
+ * {@link BUSY_WINDOW_MS}, and quiet for at most {@link BUSY_RECENT_MS} since
+ * the last ({@link quietMs}: stalls do not count). A single burst older than
+ * that counts when the page stalled for most of the time since, quiet for
+ * at most {@link LONE_BURST_QUIET_MS}: on a renderer running the page's
+ * timers late, a page's second step may not have come by the first read.
+ * Text-only changes (clocks) and style changes (animations) are not bursts.
  *
  * @param settle - Signals of the read
  * @returns True when the DOM may still be changing
  */
 export function domLooksBusy(settle) {
-    if (!settle)
+    const recent = recentBursts(settle);
+    if (recent.length === 0)
         return false;
-    const recent = settle.burstAges.filter((age) => age <= BUSY_WINDOW_MS);
-    return recent.length >= BUSY_BURSTS && Math.min(...recent) <= BUSY_RECENT_MS;
+    const limit = recent.length === 1 ? LONE_BURST_QUIET_MS : BUSY_RECENT_MS;
+    return quietMs(Math.min(...recent), 0, settle?.stalls) <= limit;
 }
 /**
- * Whether the DOM kept changing during the second look: at least
- * {@link BUSY_BURSTS} new bursts within the time since the first read (a
- * render that ends in two commits, or a poller updating once a second, does
- * not count).
+ * Whether the DOM kept changing during the second look: at least one new
+ * burst since the first read, and no quiet gap longer than
+ * {@link BUSY_RECENT_MS} from the last burst the first read saw, through the
+ * new ones, to the second read. Stalls in a gap, during which the page's
+ * tasks could not run, are not quiet ({@link quietMs}): a page whose steps
+ * come 250 ms apart around a 200 ms long task, or whose timers a starved
+ * renderer runs 150 ms late, keeps changing. A page changing every 140 ms
+ * keeps changing; changes more than 150 ms apart while the page could run,
+ * a render that ended over 150 ms before the second read and a poller
+ * updating every 300 ms do not. A short render whose last commit came within
+ * 150 ms of the second read counts as changing.
  *
  * @param settle - Signals of the second read
  * @param sinceMs - Time since the first read
@@ -149,7 +227,14 @@ export function domLooksBusy(settle) {
 export function domKeptChanging(settle, sinceMs) {
     if (!settle)
         return false;
-    return settle.burstAges.filter((age) => age < sinceMs).length >= BUSY_BURSTS;
+    const fresh = settle.burstAges.filter((age) => age < sinceMs);
+    if (fresh.length === 0)
+        return false;
+    const seen = settle.burstAges.filter((age) => age >= sinceMs);
+    const times = [...seen.slice(-1), ...fresh, 0];
+    return times
+        .slice(1)
+        .every((age, i) => quietMs(times[i] ?? age, age, settle.stalls) <= BUSY_RECENT_MS);
 }
 /**
  * What the page was still working on when the action returned, or undefined
@@ -230,8 +315,11 @@ export function hadNoEffect(read, effects, activity) {
 }
 /**
  * Start watching an action's effects: listen for main-frame navigations,
- * document statuses, requests and new windows, and send the page snapshot
- * without waiting for it.
+ * document statuses, requests and new windows, send the page snapshot
+ * without waiting for it, and start the stall watch in bdg's world. That
+ * creates bdg's world for the reads now, while the page is idle (created at
+ * the first read, it would wait for a page busy after the action and could
+ * leave the read no time to answer).
  *
  * @param cdp - CDP connection
  * @returns Watch to collect from after the action
@@ -243,7 +331,9 @@ export function watchActionEffects(cdp) {
         start: evaluate(cdp, EFFECTS_START_SCRIPT),
         stopConfirmed: false,
         unresponsive: false,
+        askedLate: false,
     };
+    void evaluateInWorld(watch.cdp, STALL_WATCH_START_SCRIPT, false);
     return {
         collect: (options) => collectEffects(watch, options),
         dispose: () => disposeWatch(watch),
@@ -283,34 +373,99 @@ async function collectEffects(watch, options) {
 }
 /**
  * The snapshot taken before the action, waiting at most
- * {@link START_TIMEOUT_MS}; a snapshot still unanswered then (and no
- * navigation pending) marks the page unresponsive.
+ * {@link START_TIMEOUT_MS} ({@link pageAnswer}); a snapshot still
+ * unanswered then (and no navigation pending) marks the page unresponsive.
  *
  * @param watch - The action's watch
  * @returns The snapshot, or undefined
  */
 async function awaitStart(watch) {
-    const started = await raceTimeout(watch.start.then((value) => ({ value })), START_TIMEOUT_MS);
+    const started = await pageAnswer(watch, watch.start.then((value) => ({ value })), START_TIMEOUT_MS);
     if (!started)
         watch.unresponsive = !watch.listener.navigationPending();
     return started?.value;
 }
+/**
+ * The answer of a page script within a time, or within {@link READ_TIMEOUT_MS}
+ * more when the page only answered late ({@link answeredLate}): the same
+ * script is waited for, not sent again (a read that stopped the page's watch
+ * could not be repeated).
+ *
+ * @param watch - The action's watch
+ * @param answer - The script's answer
+ * @param ms - Time it gets first
+ * @returns The answer, or undefined when the page is busy
+ */
+async function pageAnswer(watch, answer, ms) {
+    const first = await raceTimeout(answer, ms);
+    if (first !== undefined || !(await answeredLate(watch)))
+        return first;
+    return raceTimeout(answer, READ_TIMEOUT_MS);
+}
+/**
+ * Whether a page whose script got no answer in time only answered late: it
+ * answers now, within {@link READ_TIMEOUT_MS}, and ran no long task since
+ * the watch began ({@link LONG_TASKS_READ_SCRIPT}). The renderer ran the
+ * page's tasks late (a starved machine), and CDP runs a page's scripts in
+ * the order sent, so the script that got no answer has run by now; a page
+ * that ran a long task, or still does not answer, is busy. Asked at most
+ * once per action, so a busy or starved page costs at most
+ * {@link READ_TIMEOUT_MS} more; not asked while a main-frame load is
+ * pending.
+ *
+ * @param watch - The action's watch
+ * @returns True when the page is not busy, only slow
+ */
+async function answeredLate(watch) {
+    if (watch.askedLate || watch.listener.navigationPending())
+        return false;
+    watch.askedLate = true;
+    const longTasks = await raceTimeout(evaluateInWorld(watch.cdp, LONG_TASKS_READ_SCRIPT, false), READ_TIMEOUT_MS);
+    const late = longTasks === 0;
+    log.debug(late
+        ? 'Page answered late without a long task (a slow renderer); waiting for its answer'
+        : `Page busy (long tasks: ${longTasks ?? 'no answer'})`);
+    return late;
+}
 /**
  * Whether the DOM is still changing: when the last read looked busy
  * ({@link domLooksBusy}), a second read {@link STILL_CHANGING_RECHECK_MS}
- * later must see it keep changing ({@link domKeptChanging}).
+ * later must see it keep changing ({@link domKeptChanging}). The time
+ * between the reads is the page's own when both have it.
  *
  * @param watch - The action's watch
  * @param snapshot - Last read, if any
  * @returns True when the DOM kept changing
  */
 async function stillChanging(watch, snapshot) {
-    if (!domLooksBusy(snapshot?.settle))
+    const first = snapshot?.settle;
+    if (!domLooksBusy(first))
         return false;
     const firstRead = Date.now();
     await delay(STILL_CHANGING_RECHECK_MS);
-    const recheck = await readPage(watch, { stop: false, reportShown: false });
-    return domKeptChanging(recheck?.settle, Date.now() - firstRead);
+    const recheck = (await readPage(watch, { stop: false, reportShown: false, stalls: true }))
+        ?.settle;
+    const sinceMs = first?.at !== undefined && recheck?.at !== undefined
+        ? Math.round(recheck.at - first.at)
+        : Date.now() - firstRead;
+    const changing = domKeptChanging(recheck, sinceMs);
+    log.debug(`DOM looked busy (burst ages ${first?.burstAges.join(',')} ms, ` +
+        `stalls ${describeStalls(first?.stalls)}); ` +
+        `${sinceMs} ms later ${recheck?.burstAges.join(',') ?? 'no answer'}, ` +
+        `stalls ${describeStalls(recheck?.stalls)}: ` +
+        (changing ? 'still changing' : 'settled'));
+    return changing;
+}
+/**
+ * Stalls for a debug line: each as `began-ended` ms ago.
+ *
+ * @param stalls - Stalls of a read
+ * @returns Description, `none` without any
+ */
+function describeStalls(stalls) {
+    if (!stalls || stalls.length === 0)
+        return 'none';
+    return stalls.map(([began, ended]) => `${began}-${ended}`).join(',');
 }
 /**
  * The page's work as the last read and the CDP events saw it.
@@ -359,36 +514,116 @@ function effectsOf(start, snapshot, events) {
 }
 /**
  * Read the page after the action, unless a main-frame load is pending (the
- * read would wait for the new page). A stopping read that answered stops the
- * page's watch, so disposing need not. A read that got no answer in time
- * marks the page unresponsive.
+ * read would wait for the new page). The page first gets to run a timer that
+ * fell due meanwhile ({@link letDueTimersRun}); the read itself does not wait
+ * for timers. A read whose bursts may make the DOM look busy, and the second
+ * look at a DOM that did (`stalls`: its first look's bursts may have left
+ * the window by then), also gets the stalls up to it ({@link withStalls}).
+ * A stopping read that answered stops the page's watch, so disposing need
+ * not. A page that did not answer in time is marked unresponsive.
  *
  * @param watch - The action's watch
- * @param options - Also stop the page's watch; list shown elements
+ * @param options - Also stop the page's watch; list shown elements; always read stalls
  * @returns The read, or undefined
  */
 async function readPage(watch, options) {
     if (watch.listener.navigationPending())
         return undefined;
     const expression = `(${EFFECTS_READ_SCRIPT})(${options.stop}, ${options.reportShown})`;
-    const answer = await raceTimeout(evaluate(watch.cdp, expression).then((value) => ({ value })), READ_TIMEOUT_MS);
+    const answered = await letDueTimersRun(watch);
+    const answer = answered
+        ? await pageAnswer(watch, evaluate(watch.cdp, expression).then((value) => ({ value })), READ_TIMEOUT_MS)
+        : undefined;
     if (!answer)
         watch.unresponsive = !watch.listener.navigationPending();
     const snapshot = answer?.value;
     if (options.stop && snapshot)
         watch.stopConfirmed = true;
-    return snapshot;
+    return snapshot && withStalls(watch.cdp, snapshot, options.stalls === true);
+}
+/**
+ * A read with the stalls up to it, as ages at the read, when asked to or
+ * when it has enough recent bursts for them to matter
+ * ({@link recentBursts}); other reads (a static page) are returned as they
+ * are, without a further page script. Stalls are read right after the read,
+ * in bdg's world, within {@link STALLS_READ_TIMEOUT_MS}; page times after
+ * the read are cut off.
+ *
+ * @param cdp - CDP connection
+ * @param snapshot - The read
+ * @param always - Read stalls whatever the bursts (the second look at a busy DOM)
+ * @returns The read, with stalls when known
+ */
+async function withStalls(cdp, snapshot, always) {
+    const settle = snapshot.settle;
+    if (settle?.at === undefined || (!always && recentBursts(settle).length === 0))
+        return snapshot;
+    const at = settle.at;
+    const stalls = await raceTimeout(evaluateInWorld(cdp, STALL_READ_SCRIPT, false), STALLS_READ_TIMEOUT_MS);
+    if (!Array.isArray(stalls))
+        return snapshot;
+    const ages = stalls
+        .filter(([due]) => due < at)
+        .map(([due, ran]) => [Math.round(at - due), Math.max(0, Math.round(at - ran))]);
+    return { ...snapshot, settle: { ...settle, stalls: ages } };
+}
+/**
+ * Let the page run a timer that fell due while it was busy, so a read sees
+ * its change: set a 0 ms timer ({@link START_DUE_TIMERS_SCRIPT}), then wait
+ * for it at most {@link DUE_TIMERS_TIMEOUT_MS}. Both run in bdg's world, whose
+ * `setTimeout` the page cannot replace or fake; its timers share the page's
+ * queue. Setting the timer has the read's {@link READ_TIMEOUT_MS}
+ * ({@link pageAnswer}); a page that does not answer by then is busy and not
+ * read. A page that answers just in time, then keeps its timer waiting the
+ * full limit and is slow to read can take about 600 ms (250 + 100 + 250)
+ * before the read is given up, more when it only answered late.
+ *
+ * @param watch - The action's watch
+ * @returns False when the page did not answer in time (busy)
+ */
+async function letDueTimersRun(watch) {
+    const started = await pageAnswer(watch, evaluateInWorld(watch.cdp, START_DUE_TIMERS_SCRIPT, false).then(() => true), READ_TIMEOUT_MS);
+    if (!started)
+        return false;
+    await raceTimeout(evaluateInWorld(watch.cdp, AWAIT_DUE_TIMERS_SCRIPT, true), DUE_TIMERS_TIMEOUT_MS);
+    return true;
+}
+/**
+ * Evaluate one of bdg's page scripts in bdg's world for its value, failures
+ * logged.
+ *
+ * @param cdp - CDP connection
+ * @param expression - Script
+ * @param awaitPromise - Wait for the promise it returns
+ * @returns Its value, or undefined on an exception or a failed call
+ */
+async function evaluateInWorld(cdp, expression, awaitPromise) {
+    try {
+        const reply = await evaluateInBdgWorld(cdp, { expression, awaitPromise, returnByValue: true });
+        if (!reply.exceptionDetails)
+            return reply.result.value;
+        log.debug(`bdg world script failed: ${reply.exceptionDetails.text}`);
+    }
+    catch (error) {
+        log.debug(`bdg world script not run: ${getErrorMessage(error)}`);
+    }
+    return undefined;
 }
 /**
- * Stop listening, and stop the page's watch unless a read did. The stop is
- * sent even when the snapshot never answered: CDP runs it after the
- * snapshot, wherever that ran (the page also stops watching on its own
- * after 30 s).
+ * Stop listening, stop the stall watch and stop the page's watch unless a
+ * read did. The page's stop is sent even when the snapshot never answered:
+ * CDP runs it after the snapshot, wherever that ran (the page also stops
+ * watching on its own after 30 s). The stall watch is not stopped when a new
+ * document committed and bdg's world is gone with the old one: its watch
+ * went with it, and stopping would only make a new world.
  *
  * @param watch - The action's watch
  */
 function disposeWatch(watch) {
+    const documentGone = watch.listener.events.document !== undefined && !hasBdgWorld(watch.cdp);
     watch.listener.dispose();
+    if (!documentGone)
+        void evaluateInWorld(watch.cdp, STALL_WATCH_STOP_SCRIPT, false);
     if (watch.stopConfirmed)
         return;
     void watch.cdp

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

@@ -74,6 +74,19 @@ export declare const UNCERTAIN_JS = "(state, active) => {\n  if (state.copied) r
  * the messages.
  */
 export declare const EFFECTS_START_SCRIPT: string;
+/**
+ * Page-side wait for one turn of the page's timers. A busy or descheduled
+ * renderer (a slow machine) runs a CDP read before a timer that fell due
+ * meanwhile, so a page changing every 100 ms would look like a single
+ * render; Chrome runs the earliest overdue timers before a 0 ms timer posted
+ * after them (a longer delay would wait for every due timer). That order is
+ * Chrome's scheduler behaviour, not a web standard, verified on Chrome 154.
+ */
+export declare const DUE_TIMERS_JS = "() => new Promise((resolve) => setTimeout(resolve, 0))";
+/** Sets the {@link DUE_TIMERS_JS} timer, kept for {@link AWAIT_DUE_TIMERS_SCRIPT} */
+export declare const START_DUE_TIMERS_SCRIPT = "globalThis.__bdgDueTimers = (() => new Promise((resolve) => setTimeout(resolve, 0)))(), true";
+/** Resolves once the timer {@link START_DUE_TIMERS_SCRIPT} set has run */
+export declare const AWAIT_DUE_TIMERS_SCRIPT = "globalThis.__bdgDueTimers";
 /**
  * Read after an action, called with `(stop, shown)`: `stop` also stops
  * watching, `shown` lists the elements the action showed
@@ -85,6 +98,38 @@ export declare const EFFECTS_START_SCRIPT: string;
  * (everything shown is new).
  */
 export declare const EFFECTS_READ_SCRIPT: string;
+/**
+ * Stall watch, run in bdg's world while an action's effects are watched,
+ * left in `globalThis.__bdgStalls`: a timer every {@link STALL_BEAT_MS}
+ * that notes when it ran over {@link STALL_MIN_MS} late, as a stall from
+ * when it was due to when it ran (the last {@link MAX_STALLS}). bdg's world
+ * has its own `setTimeout`, so a page that replaced it is still watched, and
+ * its timers share the page's queue: a stall is time the page's own timers
+ * could not run either (a long task, or a renderer that runs the page's
+ * tasks late). The page cannot see it, except in the main-world fallback
+ * for frame-scoped connections (no bdg world), where `__bdgStalls` is a
+ * global of the page. It also counts the page's long tasks (over 50 ms of
+ * script, style or layout), read by {@link LONG_TASKS_READ_SCRIPT}. It
+ * stops itself after {@link MAX_WATCH_MS}.
+ */
+export declare const STALL_WATCH_START_SCRIPT = "(() => {\n  if (globalThis.__bdgStalls) globalThis.__bdgStalls.stop();\n  const native = String(setTimeout).includes('[native code]');\n  const watch = { stalls: [], due: 0, ticked: native, stopped: false, timer: 0, longTasks: 0 };\n  const observer = typeof PerformanceObserver === 'function' &&\n    (PerformanceObserver.supportedEntryTypes || []).includes('longtask')\n    ? new PerformanceObserver((list) => { watch.longTasks += list.getEntries().length; })\n    : null;\n  if (observer) observer.observe({ type: 'longtask' });\n  watch.longTasksSeen = () => {\n    if (!observer) return null;\n    watch.longTasks += observer.takeRecords().length;\n    return watch.longTasks;\n  };\n  const schedule = () => {\n    watch.due = performance.now() + 20;\n    watch.timer = setTimeout(beat, 20);\n  };\n  const beat = () => {\n    const now = performance.now();\n    watch.ticked = true;\n    if (now - watch.due > 10) {\n      watch.stalls.push([watch.due, now]);\n      if (watch.stalls.length > 50) watch.stalls.shift();\n    }\n    schedule();\n  };\n  watch.stop = () => {\n    watch.stopped = true;\n    clearTimeout(watch.timer);\n    clearTimeout(expiry);\n    if (observer) observer.disconnect();\n  };\n  const expiry = setTimeout(watch.stop, 30000);\n  schedule();\n  globalThis.__bdgStalls = watch;\n  return true;\n})()";
+/**
+ * Reads the stalls {@link STALL_WATCH_START_SCRIPT} noted, as page times
+ * `[due, ran]`, plus the stall still going on (its timer over
+ * {@link STALL_MIN_MS} overdue now) as `[due, now]`; that one only with the
+ * browser's own `setTimeout` or once the timer has run at least once (in the
+ * main world, where bdg's scripts run without bdg's world, a page may have
+ * replaced `setTimeout` with one that never runs). Null without a watch.
+ */
+export declare const STALL_READ_SCRIPT = "(() => {\n  const watch = globalThis.__bdgStalls;\n  if (!watch) return null;\n  const now = performance.now();\n  const ongoing = watch.ticked && !watch.stopped && now - watch.due > 10;\n  return ongoing ? watch.stalls.concat([[watch.due, now]]) : watch.stalls;\n})()";
+/**
+ * Reads how many long tasks the page ran since {@link STALL_WATCH_START_SCRIPT}
+ * started, also those not yet delivered to its observer. Null without a
+ * watch or without long-task support.
+ */
+export declare const LONG_TASKS_READ_SCRIPT = "(() => {\n  const watch = globalThis.__bdgStalls;\n  return watch && watch.longTasksSeen ? watch.longTasksSeen() : null;\n})()";
+/** Stops the watch {@link STALL_WATCH_START_SCRIPT} left */
+export declare const STALL_WATCH_STOP_SCRIPT = "if (globalThis.__bdgStalls) { globalThis.__bdgStalls.stop(); delete globalThis.__bdgStalls; }";
 /** Stops the watch {@link EFFECTS_START_SCRIPT} left (when no read stopped it) */
 export declare const EFFECTS_STOP_SCRIPT = "if (window.__bdgEffects) { window.__bdgEffects.stop(); delete window.__bdgEffects; }";
 //# sourceMappingURL=actionEffectsScripts.d.ts.map

package/dist/runtime/dom/actionEffectsScripts.js

@@ -61,6 +61,12 @@ const MAX_MESSAGE_TEXT = 300;
 const MAX_WATCH_MS = 30000;
 /** Bursts of DOM changes a watch keeps (their times) */
 const MAX_BURSTS = 20;
+/** Delay of the stall watch's timer ({@link STALL_WATCH_START_SCRIPT}, ms) */
+const STALL_BEAT_MS = 20;
+/** How late the stall watch's timer must run to count as a stall (ms) */
+const STALL_MIN_MS = 10;
+/** Stalls a stall watch keeps */
+const MAX_STALLS = 50;
 /**
  * Page-side test whether an element is shown: rendered, not aria-hidden,
  * not `visibility: hidden` and not fully transparent.
@@ -299,14 +305,16 @@ export const UNCERTAIN_JS = `(state, active) => {
 }`;
 /**
  * Page-side signs, at a read, that the page is still working on the
- * action's result: how long ago each recent burst of DOM changes was (ms,
- * newest last), and a loading indicator shown since the start (described).
+ * action's result: the page time of the read, how long ago each recent
+ * burst of DOM changes was (ms, newest last), and a loading indicator shown
+ * since the start (described).
  */
 const SETTLE_JS = `(state) => {
   const now = performance.now();
   const describe = ${ELEMENT_DESCRIPTION_JS};
   const loader = (${LOADERS_JS})().find((el) => !state.loaders.has(el));
   return {
+    at: now,
     burstAges: state.bursts.map((time) => Math.round(now - time)),
     loading: loader ? describe(loader) : null
   };
@@ -392,6 +400,19 @@ export const EFFECTS_START_SCRIPT = `(() => {
   window.__bdgEffects = state;
   return { href: location.href, messages: (${MESSAGES_JS})(ids) };
 })()`;
+/**
+ * Page-side wait for one turn of the page's timers. A busy or descheduled
+ * renderer (a slow machine) runs a CDP read before a timer that fell due
+ * meanwhile, so a page changing every 100 ms would look like a single
+ * render; Chrome runs the earliest overdue timers before a 0 ms timer posted
+ * after them (a longer delay would wait for every due timer). That order is
+ * Chrome's scheduler behaviour, not a web standard, verified on Chrome 154.
+ */
+export const DUE_TIMERS_JS = `() => new Promise((resolve) => setTimeout(resolve, 0))`;
+/** Sets the {@link DUE_TIMERS_JS} timer, kept for {@link AWAIT_DUE_TIMERS_SCRIPT} */
+export const START_DUE_TIMERS_SCRIPT = `globalThis.__bdgDueTimers = (${DUE_TIMERS_JS})(), true`;
+/** Resolves once the timer {@link START_DUE_TIMERS_SCRIPT} set has run */
+export const AWAIT_DUE_TIMERS_SCRIPT = 'globalThis.__bdgDueTimers';
 /**
  * Read after an action, called with `(stop, shown)`: `stop` also stops
  * watching, `shown` lists the elements the action showed
@@ -421,6 +442,84 @@ export const EFFECTS_READ_SCRIPT = `((stop, shown) => {
     shown: shown ? (${SHOWN_ELEMENTS_JS})(state) : undefined
   };
 })`;
+/**
+ * Stall watch, run in bdg's world while an action's effects are watched,
+ * left in `globalThis.__bdgStalls`: a timer every {@link STALL_BEAT_MS}
+ * that notes when it ran over {@link STALL_MIN_MS} late, as a stall from
+ * when it was due to when it ran (the last {@link MAX_STALLS}). bdg's world
+ * has its own `setTimeout`, so a page that replaced it is still watched, and
+ * its timers share the page's queue: a stall is time the page's own timers
+ * could not run either (a long task, or a renderer that runs the page's
+ * tasks late). The page cannot see it, except in the main-world fallback
+ * for frame-scoped connections (no bdg world), where `__bdgStalls` is a
+ * global of the page. It also counts the page's long tasks (over 50 ms of
+ * script, style or layout), read by {@link LONG_TASKS_READ_SCRIPT}. It
+ * stops itself after {@link MAX_WATCH_MS}.
+ */
+export const STALL_WATCH_START_SCRIPT = `(() => {
+  if (globalThis.__bdgStalls) globalThis.__bdgStalls.stop();
+  const native = String(setTimeout).includes('[native code]');
+  const watch = { stalls: [], due: 0, ticked: native, stopped: false, timer: 0, longTasks: 0 };
+  const observer = typeof PerformanceObserver === 'function' &&
+    (PerformanceObserver.supportedEntryTypes || []).includes('longtask')
+    ? new PerformanceObserver((list) => { watch.longTasks += list.getEntries().length; })
+    : null;
+  if (observer) observer.observe({ type: 'longtask' });
+  watch.longTasksSeen = () => {
+    if (!observer) return null;
+    watch.longTasks += observer.takeRecords().length;
+    return watch.longTasks;
+  };
+  const schedule = () => {
+    watch.due = performance.now() + ${STALL_BEAT_MS};
+    watch.timer = setTimeout(beat, ${STALL_BEAT_MS});
+  };
+  const beat = () => {
+    const now = performance.now();
+    watch.ticked = true;
+    if (now - watch.due > ${STALL_MIN_MS}) {
+      watch.stalls.push([watch.due, now]);
+      if (watch.stalls.length > ${MAX_STALLS}) watch.stalls.shift();
+    }
+    schedule();
+  };
+  watch.stop = () => {
+    watch.stopped = true;
+    clearTimeout(watch.timer);
+    clearTimeout(expiry);
+    if (observer) observer.disconnect();
+  };
+  const expiry = setTimeout(watch.stop, ${MAX_WATCH_MS});
+  schedule();
+  globalThis.__bdgStalls = watch;
+  return true;
+})()`;
+/**
+ * Reads the stalls {@link STALL_WATCH_START_SCRIPT} noted, as page times
+ * `[due, ran]`, plus the stall still going on (its timer over
+ * {@link STALL_MIN_MS} overdue now) as `[due, now]`; that one only with the
+ * browser's own `setTimeout` or once the timer has run at least once (in the
+ * main world, where bdg's scripts run without bdg's world, a page may have
+ * replaced `setTimeout` with one that never runs). Null without a watch.
+ */
+export const STALL_READ_SCRIPT = `(() => {
+  const watch = globalThis.__bdgStalls;
+  if (!watch) return null;
+  const now = performance.now();
+  const ongoing = watch.ticked && !watch.stopped && now - watch.due > ${STALL_MIN_MS};
+  return ongoing ? watch.stalls.concat([[watch.due, now]]) : watch.stalls;
+})()`;
+/**
+ * Reads how many long tasks the page ran since {@link STALL_WATCH_START_SCRIPT}
+ * started, also those not yet delivered to its observer. Null without a
+ * watch or without long-task support.
+ */
+export const LONG_TASKS_READ_SCRIPT = `(() => {
+  const watch = globalThis.__bdgStalls;
+  return watch && watch.longTasksSeen ? watch.longTasksSeen() : null;
+})()`;
+/** Stops the watch {@link STALL_WATCH_START_SCRIPT} left */
+export const STALL_WATCH_STOP_SCRIPT = 'if (globalThis.__bdgStalls) { globalThis.__bdgStalls.stop(); delete globalThis.__bdgStalls; }';
 /** Stops the watch {@link EFFECTS_START_SCRIPT} left (when no read stopped it) */
 export const EFFECTS_STOP_SCRIPT = 'if (window.__bdgEffects) { window.__bdgEffects.stop(); delete window.__bdgEffects; }';
 //# sourceMappingURL=actionEffectsScripts.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * The area an element screenshot captures: its border box, grown to what
+ * the element paints beyond it (overflowing descendants, text, shadows,
+ * outline), plus any `--padding`.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { ElementBounds } from '../../types.js';
+/** An element of the page */
+export interface ElementRef {
+    backendNodeId: number;
+}
+/**
+ * The border box of an element (padding and border included), relative to
+ * the viewport.
+ *
+ * @param cdp - Session connection
+ * @param ref - The element
+ * @returns Bounds in CSS px
+ * @throws CommandError (81) when it is not rendered or has no area
+ */
+export declare function getElementBounds(cdp: CDPConnection, ref: ElementRef): Promise<ElementBounds>;
+/**
+ * Area an element screenshot captures: the border box, grown to the content
+ * that overflows it ({@link CONTENT_OVERFLOW_JS}), so floated children are
+ * not cropped away.
+ *
+ * @param cdp - Session connection
+ * @param ref - The element
+ * @param bounds - Border box (DOM.getBoxModel coordinates)
+ * @param padding - Extra space around it (CSS px)
+ * @returns The area, or the border box (with the padding) when nothing
+ *   overflows (or the page cannot be asked)
+ */
+export declare function captureArea(cdp: CDPConnection, ref: ElementRef, bounds: ElementBounds, padding: number): Promise<ElementBounds>;
+//# sourceMappingURL=captureArea.d.ts.map