browser-debugger-cli 0.12.0 → 0.13.0

package/dist/ipc/client.d.ts

@@ -178,8 +178,10 @@ export declare function getNetworkHeaders(options?: {
  *
  * @param method - CDP method name (e.g., 'Network.getCookies')
  * @param params - Optional method parameters
+ * @param options - `isolated`: a bdg page script, run in bdg's isolated world
+ *   (`Runtime.evaluate`, `DOM.resolveNode`)
  * @returns Response with CDP method result
- * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated
+ * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated, (107) when the page crashed
  *
  * @example
  * ```typescript
@@ -189,7 +191,21 @@ export declare function getNetworkHeaders(options?: {
  * }
  * ```
  */
-export declare function callCDP(method: string, params?: Record<string, unknown>): Promise<ClientResponse<'cdp_call'>>;
+export declare function callCDP(method: string, params?: Record<string, unknown>, options?: {
+    isolated?: boolean;
+}): Promise<ClientResponse<'cdp_call'>>;
+/**
+ * Send a CDP call for one of bdg's own page scripts: `Runtime.evaluate` and
+ * `DOM.resolveNode` run in bdg's isolated world, so a page that replaced
+ * built-ins (`querySelectorAll`, `JSON.stringify`) cannot change what they
+ * find or return.
+ *
+ * @param method - CDP method name
+ * @param params - Method parameters
+ * @returns Response with the CDP method result
+ * @throws Like {@link callCDP}
+ */
+export declare function callBdgScript(method: string, params?: Record<string, unknown>): Promise<ClientResponse<'cdp_call'>>;
 /**
  * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
  */

package/dist/ipc/client.js

@@ -251,8 +251,10 @@ export async function getNetworkHeaders(options) {
  *
  * @param method - CDP method name (e.g., 'Network.getCookies')
  * @param params - Optional method parameters
+ * @param options - `isolated`: a bdg page script, run in bdg's isolated world
+ *   (`Runtime.evaluate`, `DOM.resolveNode`)
  * @returns Response with CDP method result
- * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated
+ * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated, (107) when the page crashed
  *
  * @example
  * ```typescript
@@ -262,13 +264,32 @@ export async function getNetworkHeaders(options) {
  * }
  * ```
  */
-export async function callCDP(method, params) {
-    const response = await sendCommand('cdp_call', { method, ...(params && { params }) });
-    if (response.status === 'error' && response.exitCode === EXIT_CODES.CDP_TIMEOUT) {
-        throw new CommandError(response.error ?? `${method} timed out`, response.suggestion ? { suggestion: response.suggestion } : {}, EXIT_CODES.CDP_TIMEOUT);
+export async function callCDP(method, params, options = {}) {
+    const response = await sendCommand('cdp_call', {
+        method,
+        ...(params && { params }),
+        ...(options.isolated && { isolated: true }),
+    });
+    const fatal = [EXIT_CODES.CDP_TIMEOUT, EXIT_CODES.PAGE_CRASHED];
+    if (response.status === 'error' && response.exitCode && fatal.includes(response.exitCode)) {
+        throw new CommandError(response.error ?? `${method} failed`, response.suggestion ? { suggestion: response.suggestion } : {}, response.exitCode);
     }
     return response;
 }
+/**
+ * Send a CDP call for one of bdg's own page scripts: `Runtime.evaluate` and
+ * `DOM.resolveNode` run in bdg's isolated world, so a page that replaced
+ * built-ins (`querySelectorAll`, `JSON.stringify`) cannot change what they
+ * find or return.
+ *
+ * @param method - CDP method name
+ * @param params - Method parameters
+ * @returns Response with the CDP method result
+ * @throws Like {@link callCDP}
+ */
+export function callBdgScript(method, params) {
+    return callCDP(method, params, { isolated: true });
+}
 /**
  * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
  */

package/dist/ipc/protocol/auditTypes.d.ts

@@ -19,7 +19,9 @@ export interface AuditContrastItem {
     size: number;
     weight: number;
     inView: boolean;
-    /** Why the ratio is approximate (blend modes, filters) */
+    /** Opacity of the text and its ancestors, when below 1 (the colors are faded by it) */
+    opacity?: number;
+    /** Why the ratio is approximate (blend modes, filters, an element behind or on top, out of view) */
     approximate?: string[];
 }
 /** An image drawn larger than its pixels, or with another aspect ratio */
@@ -51,8 +53,10 @@ export interface AuditResult {
         level: 'AA' | 'AAA';
         /** Text holders checked */
         checked: number;
-        /** How many are below the level */
+        /** How many are below the level (measured exactly) */
         failing: number;
+        /** How many more look below the level but cannot be measured exactly (text over images, blend modes, layers): not listed, `dom inspect` them */
+        uncertain?: number;
         /** The weakest ones, at most `--limit` */
         items: AuditContrastItem[];
     };
@@ -109,6 +113,8 @@ export interface AuditResult {
         /** Identical animations this one stands for (2 or more) */
         count?: number;
     }>;
+    /** Visible `<canvas>` elements: scripts may animate them, which `animations` cannot see */
+    canvases?: number;
 }
 /** A stylesheet line where `css search` found the text */
 export interface CssSearchMatch {

package/dist/ipc/protocol/commands.d.ts

@@ -66,10 +66,14 @@ export interface SessionPeekData {
     }>;
     /** Navigation id of the page currently loaded. */
     currentNavigationId: number;
+    /** When the page's renderer crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: number;
     /** Total number of network requests (for pagination). */
     totalNetwork: number;
     /** Total number of console messages (for pagination). */
     totalConsole: number;
+    /** Console messages dropped at the limit (the oldest; indices start after them) */
+    droppedConsole?: number;
     /** Whether there are more network items available. */
     hasMoreNetwork?: boolean;
     /** Whether there are more console items available. */
@@ -99,6 +103,12 @@ export interface CdpCallCommand {
     method: string;
     /** Optional parameters for the CDP method. */
     params?: Record<string, unknown>;
+    /**
+     * A bdg page script: `Runtime.evaluate` and `DOM.resolveNode` run in bdg's
+     * isolated world, out of reach of built-ins the page replaced (not for
+     * `bdg cdp`, whose calls stay in the page's world)
+     */
+    isolated?: boolean;
 }
 /**
  * CDP call command response data.
@@ -183,6 +193,8 @@ export interface DomEvalData {
     subtype?: string;
     /** URL of the iframe the script ran in (with `frame`; empty when it has none) */
     frame?: string;
+    /** Set when the page replaced built-ins bdg's copy of the result uses */
+    warning?: string;
 }
 /** An iframe of the page, as listed by `bdg dom frames` */
 export interface DomFrame {

package/dist/ipc/protocol/domTypes.d.ts

@@ -96,6 +96,8 @@ export interface ActionEffects {
     settled?: false;
     /** What the page was still working on (with `settled: false`) */
     pending?: PendingChanges;
+    /** All built-ins the page replaced that bdg's action scripts use (when the warning mentions them) */
+    replacedBuiltins?: string[];
 }
 /** A filled field's value differing from the one given */
 export interface FillValueMismatch {
@@ -165,6 +167,11 @@ export interface ClickResult extends ActionEffects {
     method?: 'mouse' | 'dom';
     /** What was done: click, double (click), right (click) or hover */
     action?: 'click' | 'double' | 'right' | 'hover';
+    /** How far the page scrolled to bring the element into view (CSS px; absent when it did not move) */
+    scrolledBy?: {
+        x: number;
+        y: number;
+    };
     /** Exit code for a failure */
     exitCode?: number;
     /** Why the DOM fallback was used (element covered or without size) */
@@ -425,6 +432,11 @@ export interface ElementLayout {
      * `opacity: 0 on div#menu` (`inViewport` still says where it is)
      */
     invisible?: string;
+    /**
+     * A `mask-image` on it or an ancestor, e.g. `mask-image on div.hero`: part
+     * or all of it may not show (how much is not evaluated)
+     */
+    masked?: string;
     /** Inside an `inert` element: shown, but a user cannot interact with it */
     inert?: true;
     computed: LayoutComputedStyle;

package/dist/ipc/protocol/inspectTypes.d.ts

@@ -270,6 +270,8 @@ export interface InspectVisibility {
     coveredBy?: string;
     /** The cover paints nothing there: the element shows, but clicks land on the cover */
     coverTransparent?: true;
+    /** A `mask-image` on it or an ancestor, e.g. `mask-image on div.hero` (how much it hides is not evaluated) */
+    masked?: string;
 }
 /** A property asked for with `--props` */
 export interface InspectProp {

package/dist/ipc/session/types.d.ts

@@ -29,5 +29,7 @@ export interface PageState {
     viewport?: ViewportSize;
     /** `prefers-color-scheme` the page sees (left out when the page did not answer in time). */
     colorScheme?: ColorScheme;
+    /** When the page's renderer crashed (epoch ms); `bdg page reload` brings it back */
+    crashedAt?: number;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -65,6 +65,8 @@ export interface OtherActivity {
     dialogs: number;
     /** A window, tab or download was opened */
     opened: boolean;
+    /** Console messages logged during the action */
+    consoleMessages: number;
 }
 /**
  * Messages that are new after the action: all of them after a new document
@@ -147,7 +149,7 @@ export declare function pageNavigation(startHref: string | undefined, read: Read
  * Whether an action had no visible effect: the page was read before and
  * after in the same document, it counted no DOM change, nothing made the
  * check uncertain, and no navigation, message, shown element, request,
- * dialog or new window happened.
+ * dialog, new window or console message happened.
  *
  * @param read - Page read after the action
  * @param effects - Navigation and messages found
@@ -159,6 +161,8 @@ export declare function hadNoEffect(read: ReadSnapshot | undefined, effects: Act
 export interface CollectOptions {
     /** Dialogs the action opened */
     dialogs: number;
+    /** Console messages logged since the action started, so far */
+    consoleMessages: () => number;
     /** Decide "no effect" (with a second look when nothing seemed to happen) */
     detectNoEffect: boolean;
     /** List the elements the action showed */

package/dist/runtime/dom/actionEffects.js

@@ -208,7 +208,7 @@ export function pageNavigation(startHref, read, events) {
  * Whether an action had no visible effect: the page was read before and
  * after in the same document, it counted no DOM change, nothing made the
  * check uncertain, and no navigation, message, shown element, request,
- * dialog or new window happened.
+ * dialog, new window or console message happened.
  *
  * @param read - Page read after the action
  * @param effects - Navigation and messages found
@@ -225,7 +225,8 @@ export function hadNoEffect(read, effects, activity) {
         (effects.shown ?? []).length === 0 &&
         activity.requests === 0 &&
         activity.dialogs === 0 &&
-        !activity.opened);
+        !activity.opened &&
+        activity.consoleMessages === 0);
 }
 /**
  * Start watching an action's effects: listen for main-frame navigations,
@@ -265,7 +266,11 @@ async function collectEffects(watch, options) {
     const reportShown = options.reportShown === true;
     let snapshot = await readPage(watch, { stop: false, reportShown });
     let effects = effectsOf(start, snapshot, watch.listener.events);
-    const quiet = () => hadNoEffect(snapshot, effects, { ...watch.listener.activity(), dialogs: options.dialogs });
+    const quiet = () => hadNoEffect(snapshot, effects, {
+        ...watch.listener.activity(),
+        dialogs: options.dialogs,
+        consoleMessages: options.consoleMessages(),
+    });
     if (options.detectNoEffect && quiet()) {
         await delay(NO_EFFECT_RECHECK_MS);
         snapshot = await readPage(watch, { stop: true, reportShown });
@@ -325,7 +330,8 @@ function pageWork(watch, snapshot, domChanging = false) {
 }
 /**
  * Navigation, new messages and shown elements from the snapshots and CDP
- * events.
+ * events. Snapshots a page broke (it replaced the built-ins the snapshot
+ * script uses) give the navigation only.
  *
  * @param start - Snapshot before the action, if taken
  * @param snapshot - Read after the action, if taken
@@ -334,16 +340,22 @@ function pageWork(watch, snapshot, domChanging = false) {
  */
 function effectsOf(start, snapshot, events) {
     const navigation = pageNavigation(start?.href, snapshot, events);
-    const { messages, more } = start && snapshot
-        ? newMessages(start.messages, snapshot.messages, snapshot.fresh)
-        : { messages: [], more: 0 };
-    const shown = shownElements(snapshot?.shown ?? [], messages);
-    return {
-        ...(navigation && { navigation }),
-        ...(messages.length > 0 && { messages }),
-        ...(more > 0 && { moreMessages: more }),
-        ...(shown.length > 0 && { shown }),
-    };
+    try {
+        const { messages, more } = start && snapshot
+            ? newMessages(start.messages, snapshot.messages, snapshot.fresh)
+            : { messages: [], more: 0 };
+        const shown = shownElements(snapshot?.shown ?? [], messages);
+        return {
+            ...(navigation && { navigation }),
+            ...(messages.length > 0 && { messages }),
+            ...(more > 0 && { moreMessages: more }),
+            ...(shown.length > 0 && { shown }),
+        };
+    }
+    catch (error) {
+        log.debug(`Page effects not readable (the page replaced built-ins?): ${getErrorMessage(error)}`);
+        return { ...(navigation && { navigation }) };
+    }
 }
 /**
  * Read the page after the action, unless a main-frame load is pending (the

package/dist/runtime/dom/audit.js

@@ -6,6 +6,7 @@ import { CommandError } from '../../errors/index.js';
 import { operationFailedError } from '../../errors/messages.js';
 import { buildAudit } from './auditModel.js';
 import { AUDIT_PAGE_JS } from './auditScripts.js';
+import { evaluateInBdgWorld } from '../page/bdgWorld.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Findings listed per check without `--limit` */
 export const DEFAULT_AUDIT_LIMIT = 20;
@@ -18,10 +19,10 @@ export const DEFAULT_AUDIT_LIMIT = 20;
  * @throws CommandError (91) when the page script fails
  */
 export async function auditPage(cdp, params) {
-    const response = (await cdp.send('Runtime.evaluate', {
+    const response = await evaluateInBdgWorld(cdp, {
         expression: `(${AUDIT_PAGE_JS})(${JSON.stringify(params.checks)})`,
         returnByValue: true,
-    }));
+    });
     const raw = response.result.value;
     if (response.exceptionDetails || !raw) {
         const err = operationFailedError('audit the page', response.exceptionDetails?.exception?.description ?? 'the page script failed');

package/dist/runtime/dom/auditModel.js

@@ -48,6 +48,7 @@ export function buildAudit(raw, options) {
                 ...(animation.scrollDriven && { scrollDriven: true }),
             }))).slice(0, options.limit),
         }),
+        ...(raw.canvases && { canvases: raw.canvases }),
     };
 }
 /**
@@ -59,15 +60,18 @@ export function buildAudit(raw, options) {
  */
 function contrastFindings(raw, options) {
     const checked = (raw.texts ?? []).map((text) => contrastItem(text, raw.canvasDark));
-    const failing = checked
+    const below = checked
         .filter((item) => item !== undefined)
         .filter((item) => item.ratio < requiredRatio(item, options.level))
         .sort((a, b) => a.ratio - b.ratio);
+    const failing = below.filter((item) => !item.approximate);
+    const uncertain = below.length - failing.length;
     return {
         level: options.level,
         checked: checked.length,
         failing: failing.length,
         items: failing.slice(0, options.limit),
+        ...(uncertain > 0 && { uncertain }),
     };
 }
 /**
@@ -95,6 +99,7 @@ function contrastItem(text, canvasDark) {
         size: pxNumber(text.fontSize) ?? 16,
         weight: Number(text.fontWeight) || 400,
         inView: text.inView,
+        ...(contrast.opacity !== undefined && { opacity: contrast.opacity }),
         ...(contrast.approximate && { approximate: contrast.approximate }),
     };
 }

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

@@ -6,7 +6,7 @@
  * that collects what each check needs. Colors and contrast are computed in
  * the daemon ({@link buildAudit}), the same way `dom inspect` computes them.
  */
-import type { RawBackground } from './inspectScripts.js';
+import { type RawBackground } from './inspectScripts.js';
 /** Elements the walk looks at, at most */
 export declare const AUDIT_ELEMENT_CAP = 20000;
 /** A text holder: an element that draws text of its own */
@@ -19,7 +19,11 @@ export interface RawAuditText {
     /** Backgrounds from the element up to the root, each with its own opacity */
     backgrounds: RawBackground[];
     opacity: number;
-    /** Blend modes and filters on it or an ancestor */
+    /**
+     * Why its contrast is approximate: blend modes and filters on it or an
+     * ancestor, an element painted behind or on top of it (in view), or that
+     * only its ancestors were checked (out of view, none of them paints)
+     */
     risks: string[];
     /** Inside the viewport */
     inView: boolean;
@@ -98,10 +102,12 @@ export interface RawAudit {
     }>;
     layers?: RawLayer[];
     animations?: RawAnimation[];
+    /** Visible `<canvas>` elements (their animations are drawn by scripts, not CSS or Web Animations) */
+    canvases?: number;
 }
 /**
  * Page-side audit walk. Arguments: the checks to collect for
  * (`contrast`, `overflow`, `layers`, `animations`).
  */
-export declare const AUDIT_PAGE_JS = "function (checks) {\n  const want = (name) => checks.includes(name);\n  const doc = document;\n  const view = window;\n  const style = (n) => view.getComputedStyle(n);\n  const scroller = doc.scrollingElement || doc.documentElement;\n  const viewport = { width: doc.documentElement.clientWidth, height: view.innerHeight };\n  const label = (n) => n.localName + (n.id ? '#' + n.id : n.classList && n.classList.length ? '.' + n.classList[0] : '');\n  const parentOf = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;\n  const short = (text) => text.replace(/\\s+/g, ' ').trim().slice(0, 60);\n  const ownText = (n) => Array.from(n.childNodes).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ').replace(/\\s+/g, ' ').trim();\n  const inView = (r) => r.bottom > 0 && r.right > 0 && r.top < viewport.height && r.left < viewport.width;\n  const meta = doc.querySelector('meta[name=\"color-scheme\"]');\n  const rootScheme = style(doc.documentElement).colorScheme;\n  const scheme = rootScheme && rootScheme !== 'normal' ? rootScheme : (meta && meta.content) || '';\n  const canvasDark = /dark/.test(scheme) && (!/light/.test(scheme) || view.matchMedia('(prefers-color-scheme: dark)').matches);\n  const result = { viewport: viewport, pixelRatio: view.devicePixelRatio || 1, pageWidth: scroller.scrollWidth, canvasDark: canvasDark, walked: 0, capped: false };\n  const texts = [], wide = [], truncated = [], images = [], layers = [], scrollers = [];\n  const chainOf = (n) => {\n    const backgrounds = [];\n    const risks = [];\n    let opacity = 1;\n    for (let p = n; p && backgrounds.length < 60; p = parentOf(p)) {\n      const s = style(p);\n      const own = Number(s.opacity) || 0;\n      const background = { color: s.backgroundColor, image: s.backgroundImage !== 'none' };\n      backgrounds.push(own < 1 ? Object.assign(background, { opacity: own }) : background);\n      opacity *= own;\n      if (s.mixBlendMode !== 'normal') risks.push('mix-blend-mode ' + s.mixBlendMode + ' on ' + label(p));\n      if (s.filter !== 'none') risks.push('filter on ' + label(p));\n    }\n    return { backgrounds: backgrounds, risks: risks, opacity: opacity };\n  };\n  const visit = (n, fixed) => {\n    if (result.walked >= 20000) { result.capped = true; return; }\n    if (/^(script|style|template|noscript|head|meta|link|title)$/.test(n.localName)) return;\n    const s = style(n);\n    if (s.display === 'none') return;\n    result.walked++;\n    const inFixed = fixed || s.position === 'fixed';\n    const kids = n.shadowRoot ? [...Array.from(n.shadowRoot.children), ...Array.from(n.children)] : Array.from(n.children);\n    const slot = n.localName === 'slot';\n    const box = slot && parentOf(n) ? parentOf(n) : n;\n    const r = box.getBoundingClientRect();\n    const shown = r.width > 0 && r.height > 0 && s.visibility === 'visible';\n    const gradientText = s.backgroundClip === 'text' && /rgba\\(0, 0, 0, 0\\)|transparent/.test(s.webkitTextFillColor);\n    if (shown && want('contrast') && !gradientText) {\n      const text = slot ? short(n.assignedNodes({ flatten: true }).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ')) : n.shadowRoot ? '' : ownText(n);\n      if (text && Number(s.opacity) > 0 && r.width > 2 && r.height > 2) {\n        const chain = chainOf(n);\n        if (chain.opacity > 0) texts.push(Object.assign({ label: label(n), text: short(text), color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, inView: inView(r) }, chain));\n      }\n    }\n    if (shown && want('overflow')) {\n      if (r.right > viewport.width + 1 && !inFixed) wide.push({ label: label(n), right: r.right + view.scrollX, width: r.width });\n      const cut = s.overflowX !== 'visible' && n.scrollWidth > n.clientWidth + 1 ? (s.textOverflow === 'ellipsis' ? 'ellipsis' : 'clip')\n        : s.webkitLineClamp !== 'none' && n.scrollHeight > n.clientHeight + 1 ? 'clamp' : null;\n      const textContent = cut && short(n.innerText || '');\n      const visuallyHidden = r.width <= 2 || r.height <= 2;\n      if (cut && textContent && !visuallyHidden) truncated.push({ label: label(n), text: textContent, kind: cut });\n      const vector = /\\.svg([?#]|$)|^data:image\\/svg/i.test(n.currentSrc || '');\n      if (n.localName === 'img' && n.naturalWidth > 2 && n.naturalHeight > 2 && n.complete && !vector) images.push({ label: label(n), natural: { w: n.naturalWidth, h: n.naturalHeight }, rendered: { w: r.width, h: r.height }, objectFit: s.objectFit });\n    }\n    if (shown && want('overflow') && /^(auto|scroll)$/.test(s.overflowX) && n !== doc.documentElement && n !== doc.body && n.scrollWidth > n.clientWidth + 1) {\n      scrollers.push({ label: label(n), scrollWidth: n.scrollWidth, width: n.clientWidth });\n    }\n    if (want('layers') && shown && (s.position === 'fixed' || s.position === 'sticky')) {\n      layers.push({ label: label(n), position: s.position, zIndex: s.zIndex, rect: { x: r.left, y: r.top, w: r.width, h: r.height }, inView: inView(r) });\n    }\n    if (s.overflowX !== 'visible' && s.overflowX !== 'clip' && n !== doc.documentElement && n !== doc.body) {\n      const wideBefore = wide.length;\n      for (const c of kids) visit(c, inFixed);\n      wide.length = wideBefore;\n      return;\n    }\n    for (const c of kids) visit(c, inFixed);\n  };\n  visit(doc.documentElement, false);\n  if (want('contrast')) result.texts = texts;\n  if (want('overflow')) Object.assign(result, { wide: wide, truncated: truncated, images: images, scrollers: scrollers });\n  if (want('layers')) result.layers = layers;\n  if (want('animations')) {\n    result.animations = doc.getAnimations().filter((a) => a.playState === 'running').slice(0, 200).map((a) => {\n      const timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : {};\n      const target = a.effect && a.effect.target;\n      return {\n        label: target && target.localName ? label(target) : '(none)',\n        name: a.animationName || a.transitionProperty || a.id || 'animation',\n        type: a.constructor.name,\n        duration: typeof timing.duration === 'number' ? timing.duration : String(timing.duration),\n        iterations: timing.iterations === Infinity ? 'infinite' : timing.iterations,\n        scrollDriven: Boolean(a.timeline) && a.timeline !== doc.timeline\n      };\n    });\n  }\n  return result;\n}";
+export declare const AUDIT_PAGE_JS: string;
 //# sourceMappingURL=auditScripts.d.ts.map

package/dist/runtime/dom/auditScripts.js

@@ -6,6 +6,9 @@
  * that collects what each check needs. Colors and contrast are computed in
  * the daemon ({@link buildAudit}), the same way `dom inspect` computes them.
  */
+import { LABEL_CLASSES_JS } from './elementInfo.js';
+import { FLAT_TREE_JS, HIT_EVERYTHING_JS, PAINT_RISKS_JS, } from './inspectScripts.js';
+import { AUDIT_OUT_OF_VIEW_RISK } from '../../ui/messages/commands.js';
 /** Elements the walk looks at, at most */
 export const AUDIT_ELEMENT_CAP = 20000;
 /**
@@ -19,7 +22,8 @@ export const AUDIT_PAGE_JS = `function (checks) {
   const style = (n) => view.getComputedStyle(n);
   const scroller = doc.scrollingElement || doc.documentElement;
   const viewport = { width: doc.documentElement.clientWidth, height: view.innerHeight };
-  const label = (n) => n.localName + (n.id ? '#' + n.id : n.classList && n.classList.length ? '.' + n.classList[0] : '');
+  const firstClass = (n) => (${LABEL_CLASSES_JS})(n)[0];
+  const label = (n) => n.localName + (n.id ? '#' + n.id : firstClass(n) ? '.' + firstClass(n) : '');
   const parentOf = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;
   const short = (text) => text.replace(/\\s+/g, ' ').trim().slice(0, 60);
   const ownText = (n) => Array.from(n.childNodes).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ').replace(/\\s+/g, ' ').trim();
@@ -30,20 +34,42 @@ export const AUDIT_PAGE_JS = `function (checks) {
   const canvasDark = /dark/.test(scheme) && (!/light/.test(scheme) || view.matchMedia('(prefers-color-scheme: dark)').matches);
   const result = { viewport: viewport, pixelRatio: view.devicePixelRatio || 1, pageWidth: scroller.scrollWidth, canvasDark: canvasDark, walked: 0, capped: false };
   const texts = [], wide = [], truncated = [], images = [], layers = [], scrollers = [];
+  let canvases = 0;
+  const tree = (${FLAT_TREE_JS})(view);
+  const paintRisks = ${PAINT_RISKS_JS};
+  const clear = (color) => color === 'transparent' || /^rgba\\(.*,\\s*0\\)$/.test(color) || /\\/\\s*0\\)$/.test(color);
   const chainOf = (n) => {
     const backgrounds = [];
     const risks = [];
     let opacity = 1;
+    let painted = false;
+    let solid = false;
     for (let p = n; p && backgrounds.length < 60; p = parentOf(p)) {
       const s = style(p);
       const own = Number(s.opacity) || 0;
       const background = { color: s.backgroundColor, image: s.backgroundImage !== 'none' };
       backgrounds.push(own < 1 ? Object.assign(background, { opacity: own }) : background);
       opacity *= own;
+      if (p !== doc.documentElement && p !== doc.body && (background.image || !clear(s.backgroundColor))) painted = true;
+      if (p !== doc.documentElement && p !== doc.body && !background.image && /^rgb\\(/.test(s.backgroundColor)) solid = true;
       if (s.mixBlendMode !== 'normal') risks.push('mix-blend-mode ' + s.mixBlendMode + ' on ' + label(p));
       if (s.filter !== 'none') risks.push('filter on ' + label(p));
     }
-    return { backgrounds: backgrounds, risks: risks, opacity: opacity };
+    return { backgrounds: backgrounds, risks: risks, opacity: opacity, painted: painted, solid: solid };
+  };
+  const unhit = [];
+  const painters = [];
+  const markPaintedBehind = () => {
+    for (const text of unhit) {
+      const painter = painters.find((p) => p.el !== text.el && !p.el.contains(text.el) && !text.el.contains(p.el) &&
+        text.x >= p.left && text.x <= p.right && text.y >= p.top && text.y <= p.bottom);
+      if (painter && !text.entry.risks.includes(${JSON.stringify(AUDIT_OUT_OF_VIEW_RISK)})) text.entry.risks.push(label(painter.el) + ' under or over it (out of view, not hit-tested)');
+    }
+  };
+  const risksOf = (n, slot, chain, shown) => {
+    if (!shown) return chain.painted ? chain.risks : chain.risks.concat(${JSON.stringify(AUDIT_OUT_OF_VIEW_RISK)});
+    const text = slot && n.assignedNodes({ flatten: true }).find((c) => c.nodeType === 3 && c.data.trim() !== '');
+    return paintRisks(n, tree, text ? text.parentElement || n : n);
   };
   const visit = (n, fixed) => {
     if (result.walked >= ${AUDIT_ELEMENT_CAP}) { result.capped = true; return; }
@@ -57,14 +83,21 @@ export const AUDIT_PAGE_JS = `function (checks) {
     const box = slot && parentOf(n) ? parentOf(n) : n;
     const r = box.getBoundingClientRect();
     const shown = r.width > 0 && r.height > 0 && s.visibility === 'visible';
-    const gradientText = s.backgroundClip === 'text' && /rgba\\(0, 0, 0, 0\\)|transparent/.test(s.webkitTextFillColor);
+    const gradientText = /rgba\\(0, 0, 0, 0\\)|transparent/.test(s.webkitTextFillColor);
     if (shown && want('contrast') && !gradientText) {
       const text = slot ? short(n.assignedNodes({ flatten: true }).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ')) : n.shadowRoot ? '' : ownText(n);
       if (text && Number(s.opacity) > 0 && r.width > 2 && r.height > 2) {
         const chain = chainOf(n);
-        if (chain.opacity > 0) texts.push(Object.assign({ label: label(n), text: short(text), color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, inView: inView(r) }, chain));
+        const seen = inView(r);
+        if (chain.opacity > 0) {
+          texts.push({ label: label(n), text: short(text), color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, inView: seen, backgrounds: chain.backgrounds, opacity: chain.opacity, risks: risksOf(n, slot, chain, seen) });
+          if (!seen && !chain.solid) unhit.push({ entry: texts[texts.length - 1], el: box, x: (r.left + r.right) / 2 + view.scrollX, y: (r.top + r.bottom) / 2 + view.scrollY });
+        }
       }
     }
+    if (shown && want('contrast') && (/^(img|video|canvas|picture|iframe)$/.test(n.localName) || s.backgroundImage !== 'none')) {
+      painters.push({ el: n, left: r.left + view.scrollX, top: r.top + view.scrollY, right: r.right + view.scrollX, bottom: r.bottom + view.scrollY });
+    }
     if (shown && want('overflow')) {
       if (r.right > viewport.width + 1 && !inFixed) wide.push({ label: label(n), right: r.right + view.scrollX, width: r.width });
       const cut = s.overflowX !== 'visible' && n.scrollWidth > n.clientWidth + 1 ? (s.textOverflow === 'ellipsis' ? 'ellipsis' : 'clip')
@@ -78,6 +111,7 @@ export const AUDIT_PAGE_JS = `function (checks) {
     if (shown && want('overflow') && /^(auto|scroll)$/.test(s.overflowX) && n !== doc.documentElement && n !== doc.body && n.scrollWidth > n.clientWidth + 1) {
       scrollers.push({ label: label(n), scrollWidth: n.scrollWidth, width: n.clientWidth });
     }
+    if (want('animations') && shown && n.localName === 'canvas') canvases++;
     if (want('layers') && shown && (s.position === 'fixed' || s.position === 'sticky')) {
       layers.push({ label: label(n), position: s.position, zIndex: s.zIndex, rect: { x: r.left, y: r.top, w: r.width, h: r.height }, inView: inView(r) });
     }
@@ -89,11 +123,13 @@ export const AUDIT_PAGE_JS = `function (checks) {
     }
     for (const c of kids) visit(c, inFixed);
   };
-  visit(doc.documentElement, false);
+  (${HIT_EVERYTHING_JS})([doc], () => visit(doc.documentElement, false));
+  markPaintedBehind();
   if (want('contrast')) result.texts = texts;
   if (want('overflow')) Object.assign(result, { wide: wide, truncated: truncated, images: images, scrollers: scrollers });
   if (want('layers')) result.layers = layers;
   if (want('animations')) {
+    result.canvases = canvases;
     result.animations = doc.getAnimations().filter((a) => a.playState === 'running').slice(0, 200).map((a) => {
       const timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : {};
       const target = a.effect && a.effect.target;

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

@@ -16,8 +16,9 @@ export interface ElementGeometry {
     rect: LayoutBox;
     /**
      * For a zero-size element whose children show (an inline list around
-     * floated items): the box around those children, which is what can be
-     * seen of it
+     * floated items, a `display: contents` web component whose shadow root
+     * shows a dialog): the box around those children in the flat tree, which
+     * is what can be seen of it
      */
     content?: LayoutBox | null;
     /** Area its iframes and overflow-clipping ancestors leave visible, in the same coordinates */
@@ -33,6 +34,11 @@ export interface ElementGeometry {
      * e.g. `opacity: 0 on div#menu`
      */
     invisible: string | null;
+    /**
+     * Masked by `mask-image` on it or an ancestor ({@link MASKED_BY_JS}), e.g.
+     * `mask-image on div.hero`: part or all of it may not show
+     */
+    masked?: string | null;
     /** Inside an `inert` element: shown, but not interactive */
     inert: boolean;
     /** Fixed to the top-level viewport (it or a container is `position: fixed`): page scroll does not move it */
@@ -126,7 +132,8 @@ export declare const CLIP_RECT_CUTS_ALL_JS = "(position, clip) => {\n  if ((posi
  * top-level viewport coordinates, its clip by ancestors
  * ({@link ANCESTOR_CLIP_JS}) and by the viewports of its iframes, why it
  * cannot be seen at all (not rendered, or inside a clipping container
- * collapsed to zero size), why a rendered one is still invisible
+ * collapsed to zero size; a `display: contents` element is measured by
+ * its children in the flat tree and is hidden only when none shows), why a rendered one is still invisible
  * ({@link INVISIBLE_REASON_JS}), whether it is inert (an `inert` element
  * around it, through shadow roots) or fixed to the top-level viewport, and how
  * far the top-level page can scroll ({@link SCROLL_RANGE_JS}) or what locks

package/dist/runtime/dom/elementGeometry.js

@@ -268,12 +268,28 @@ const INVISIBLE_REASON_JS = `(el, describe) => {
   }
   return null;
 }`;
+/**
+ * Page-side mask over an element: the nearest of it and its ancestors in the
+ * flat tree (slots, shadow hosts, iframes) with a `mask-image`. How much the
+ * mask hides is not evaluated. Null without one.
+ */
+const MASKED_BY_JS = `(el, describe) => {
+  const flatParent = ${FLAT_PARENT_JS};
+  const parentOf = (n) => flatParent(n) || n.ownerDocument.defaultView.frameElement || null;
+  for (let n = el; n; n = parentOf(n)) {
+    const style = n.ownerDocument.defaultView.getComputedStyle(n);
+    const mask = style.maskImage || style.webkitMaskImage;
+    if (mask && mask !== 'none') return n === el ? 'mask-image' : 'mask-image on ' + describe(n);
+  }
+  return null;
+}`;
 /**
  * Page-side measurement of an element ({@link ElementGeometry}): its box in
  * top-level viewport coordinates, its clip by ancestors
  * ({@link ANCESTOR_CLIP_JS}) and by the viewports of its iframes, why it
  * cannot be seen at all (not rendered, or inside a clipping container
- * collapsed to zero size), why a rendered one is still invisible
+ * collapsed to zero size; a `display: contents` element is measured by
+ * its children in the flat tree and is hidden only when none shows), why a rendered one is still invisible
  * ({@link INVISIBLE_REASON_JS}), whether it is inert (an `inert` element
  * around it, through shadow roots) or fixed to the top-level viewport, and how
  * far the top-level page can scroll ({@link SCROLL_RANGE_JS}) or what locks
@@ -292,6 +308,7 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   const scrollRange = ${SCROLL_RANGE_JS};
   const scrollLock = ${SCROLL_LOCK_JS};
   const invisibleReason = ${INVISIBLE_REASON_JS};
+  const maskedBy = ${MASKED_BY_JS};
   const describe = ${ELEMENT_DESCRIPTION_JS};
   const reasons = ${JSON.stringify(LAYOUT_REASONS)};
   const styleOf = (node) => node.ownerDocument.defaultView.getComputedStyle(node);
@@ -311,11 +328,16 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
     }
     return 'not rendered';
   };
+  const flatChildren = (node) =>
+    Array.from((node.shadowRoot || node).children).flatMap((c) => {
+      const shown = c.localName === 'slot' ? c.assignedElements({ flatten: true }) : [c];
+      return shown.flatMap((s) => (styleOf(s).display === 'contents' ? flatChildren(s) : [s]));
+    });
   const shownChildren = (node) => {
     const s = styleOf(node);
     if (s.overflowX !== 'visible' || s.overflowY !== 'visible') return null;
     let union = null;
-    for (const c of Array.from(node.children).slice(0, 50)) {
+    for (const c of flatChildren(node).slice(0, 50)) {
       const r = c.getBoundingClientRect();
       if (r.width <= 0 || r.height <= 0 || styleOf(c).visibility !== 'visible') continue;
       union = union
@@ -326,7 +348,7 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   };
   const hiddenReason = (style, box, content) => {
     if (style.display === 'none') return 'display: none';
-    if (style.display === 'contents') return 'display: contents (no box of its own)';
+    if (style.display === 'contents') return content ? null : 'display: contents (no box of its own)';
     if (el.getClientRects().length === 0) {
       return el.tagName === 'OPTION' ? reasons.option : 'not rendered (an ancestor has display: none)';
     }
@@ -386,9 +408,10 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   while (top.frameElement) top = top.parent;
   const toBox = (r) => r && { x: r.left, y: r.top, width: r.right - r.left, height: r.bottom - r.top };
   const invisible = hidden ? null : invisibleReason(el, describe);
+  const masked = hidden || invisible ? null : maskedBy(el, describe);
   const lock = scrollLock(top, describe);
   if (lock && fixedBy === top.document.body) fixed = false;
-  return { rect: toBox(rect), content: toBox(content), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
+  return { rect: toBox(rect), content: toBox(content), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, masked: masked, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
 }`;
 /**
  * Edges of a box.