@surea11y/core 1.2.0 → 1.3.0

package/src/core/frame-messaging.js

@@ -11,7 +11,7 @@
  * loaded directly into a page with no automation driver -- see
  * docs/INTEGRATION.md's "Browser extension context" section). A Playwright-
  * driven scan doesn't need any of this: Playwright reaches cross-origin
- * frames unconditionally via CDP (see surea11y-playwright's ROADMAP.md gap
+ * frames unconditionally via CDP (see @surea11y/playwright's ROADMAP.md gap
  * #1), which is strictly better than what a cooperative postMessage protocol
  * can achieve. This exists for when there IS no automation driver.
  *
@@ -27,79 +27,112 @@
 const FRAME_RPC_CHANNEL = '__frame_rpc_v1__';
 
 function getFrameRpcRegistry(win) {
-    if (!win.__a11yCoreFrameRpc__) {
-        win.__a11yCoreFrameRpc__ = {
-            pending: new Map(),
-            seq: 0,
-            responder: null,
-            listening: false
-        };
-    }
-    return win.__a11yCoreFrameRpc__;
+  if (!win.__a11yCoreFrameRpc__) {
+    win.__a11yCoreFrameRpc__ = {
+      pending: new Map(),
+      seq: 0,
+      responder: null,
+      listening: false
+    };
+  }
+  return win.__a11yCoreFrameRpc__;
 }
 
 function installFrameRpcListener(win, channel) {
-    const registry = getFrameRpcRegistry(win);
-    if (registry.listening) return registry;
-
-    win.addEventListener('message', function a11yCoreFrameRpcListener(event) {
-        const data = event && event.data;
-        if (!data || data.__a11ycore !== true || data.channel !== channel) return;
-
-        if (data.type === 'ping') {
-            try {
-                event.source && event.source.postMessage(
-                    { __a11ycore: true, channel: channel, requestId: data.requestId, type: 'pong' },
-                    '*'
-                );
-            } catch (e) { /* target gone/closed -- nothing to do */ }
-            return;
-        }
-
-        if (data.type === 'run') {
-            const responder = registry.responder;
-            if (typeof responder !== 'function') return; // no responder enabled here: unreachable, same as a widely-used reference engine's own limitation
-            Promise.resolve()
-                .then(function () { return responder(data.payload); })
-                .then(function (result) {
-                    try {
-                        event.source && event.source.postMessage(
-                            { __a11ycore: true, channel: channel, requestId: data.requestId, type: 'result', payload: result },
-                            '*'
-                        );
-                    } catch (e) { /* target gone/closed */ }
-                })
-                .catch(function (err) {
-                    try {
-                        event.source && event.source.postMessage(
-                            { __a11ycore: true, channel: channel, requestId: data.requestId, type: 'error', payload: String(err && err.message ? err.message : err) },
-                            '*'
-                        );
-                    } catch (e) { /* target gone/closed */ }
-                });
-            return;
-        }
-
-        // 'pong' | 'result' | 'error' -- resolve whichever pending request this replies to.
-        const pending = registry.pending.get(data.requestId);
-        if (!pending) return;
-        if (data.type === 'pong') {
-            pending.onPong();
-            return;
-        }
-        registry.pending.delete(data.requestId);
-        if (data.type === 'result') pending.resolve(data.payload);
-        else pending.reject(new Error(typeof data.payload === 'string' ? data.payload : 'surea11y frame RPC error'));
-    });
+  const registry = getFrameRpcRegistry(win);
+  if (registry.listening) return registry;
+
+  win.addEventListener('message', function a11yCoreFrameRpcListener(event) {
+    const data = event && event.data;
+    if (!data || data.__a11ycore !== true || data.channel !== channel) return;
+
+    if (data.type === 'ping') {
+      try {
+        event.source &&
+          event.source.postMessage(
+            { __a11ycore: true, channel: channel, requestId: data.requestId, type: 'pong' },
+            '*'
+          );
+      } catch (e) {
+        /* target gone/closed -- nothing to do */
+      }
+      return;
+    }
+
+    if (data.type === 'run') {
+      const responder = registry.responder;
+      if (typeof responder !== 'function') return; // no responder enabled here: unreachable, same as a widely-used reference engine's own limitation
+      Promise.resolve()
+        .then(function () {
+          return responder(data.payload);
+        })
+        .then(function (result) {
+          try {
+            event.source &&
+              event.source.postMessage(
+                {
+                  __a11ycore: true,
+                  channel: channel,
+                  requestId: data.requestId,
+                  type: 'result',
+                  payload: result
+                },
+                '*'
+              );
+          } catch (e) {
+            /* target gone/closed */
+          }
+        })
+        .catch(function (err) {
+          try {
+            event.source &&
+              event.source.postMessage(
+                {
+                  __a11ycore: true,
+                  channel: channel,
+                  requestId: data.requestId,
+                  type: 'error',
+                  payload: String(err && err.message ? err.message : err)
+                },
+                '*'
+              );
+          } catch (e) {
+            /* target gone/closed */
+          }
+        });
+      return;
+    }
+
+    // 'pong' | 'result' | 'error' -- resolve whichever pending request this replies to.
+    const pending = registry.pending.get(data.requestId);
+    if (!pending) return;
+    if (data.type === 'pong') {
+      pending.onPong();
+      return;
+    }
+    registry.pending.delete(data.requestId);
+    if (data.type === 'result') pending.resolve(data.payload);
+    else
+      pending.reject(
+        new Error(typeof data.payload === 'string' ? data.payload : 'surea11y frame RPC error')
+      );
+  });
 
-    registry.listening = true;
-    return registry;
+  registry.listening = true;
+  return registry;
 }
 
 function nextFrameRpcRequestId(win) {
-    const registry = getFrameRpcRegistry(win);
-    registry.seq += 1;
-    return 'req_' + Date.now().toString(36) + '_' + registry.seq + '_' + Math.random().toString(36).slice(2, 8);
+  const registry = getFrameRpcRegistry(win);
+  registry.seq += 1;
+  return (
+    'req_' +
+    Date.now().toString(36) +
+    '_' +
+    registry.seq +
+    '_' +
+    Math.random().toString(36).slice(2, 8)
+  );
 }
 
 /**
@@ -110,43 +143,46 @@ function nextFrameRpcRequestId(win) {
  * all), not an error.
  */
 function pingFrame(win, targetWindow, pingWaitTime) {
-    installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-    const registry = getFrameRpcRegistry(win);
-    const requestId = nextFrameRpcRequestId(win);
-    const waitMs = typeof pingWaitTime === 'number' ? pingWaitTime : 500;
-
-    return new Promise(function (resolve) {
-        let settled = false;
-        const timeout = setTimeout(function () {
-            if (settled) return;
-            settled = true;
-            registry.pending.delete(requestId);
-            resolve(false);
-        }, waitMs);
-
-        registry.pending.set(requestId, {
-            onPong: function () {
-                if (settled) return;
-                settled = true;
-                clearTimeout(timeout);
-                registry.pending.delete(requestId);
-                resolve(true);
-            },
-            resolve: function () {},
-            reject: function () {}
-        });
+  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
+  const registry = getFrameRpcRegistry(win);
+  const requestId = nextFrameRpcRequestId(win);
+  const waitMs = typeof pingWaitTime === 'number' ? pingWaitTime : 500;
+
+  return new Promise(function (resolve) {
+    let settled = false;
+    const timeout = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      registry.pending.delete(requestId);
+      resolve(false);
+    }, waitMs);
 
-        try {
-            targetWindow.postMessage({ __a11ycore: true, channel: FRAME_RPC_CHANNEL, requestId: requestId, type: 'ping' }, '*');
-        } catch (e) {
-            if (!settled) {
-                settled = true;
-                clearTimeout(timeout);
-                registry.pending.delete(requestId);
-                resolve(false);
-            }
-        }
+    registry.pending.set(requestId, {
+      onPong: function () {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        registry.pending.delete(requestId);
+        resolve(true);
+      },
+      resolve: function () {},
+      reject: function () {}
     });
+
+    try {
+      targetWindow.postMessage(
+        { __a11ycore: true, channel: FRAME_RPC_CHANNEL, requestId: requestId, type: 'ping' },
+        '*'
+      );
+    } catch (e) {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeout);
+        registry.pending.delete(requestId);
+        resolve(false);
+      }
+    }
+  });
 }
 
 /**
@@ -156,31 +192,46 @@ function pingFrame(win, targetWindow, pingWaitTime) {
  * explicit error reply.
  */
 function sendFrameRunCommand(win, targetWindow, payload, frameWaitTime) {
-    installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-    const registry = getFrameRpcRegistry(win);
-    const requestId = nextFrameRpcRequestId(win);
-    const waitMs = typeof frameWaitTime === 'number' ? frameWaitTime : 60000;
-
-    return new Promise(function (resolve, reject) {
-        const timeout = setTimeout(function () {
-            registry.pending.delete(requestId);
-            reject(new Error('surea11y frame RPC timed out waiting for a run result'));
-        }, waitMs);
-
-        registry.pending.set(requestId, {
-            onPong: function () {},
-            resolve: function (result) { clearTimeout(timeout); resolve(result); },
-            reject: function (err) { clearTimeout(timeout); reject(err); }
-        });
+  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
+  const registry = getFrameRpcRegistry(win);
+  const requestId = nextFrameRpcRequestId(win);
+  const waitMs = typeof frameWaitTime === 'number' ? frameWaitTime : 60000;
+
+  return new Promise(function (resolve, reject) {
+    const timeout = setTimeout(function () {
+      registry.pending.delete(requestId);
+      reject(new Error('surea11y frame RPC timed out waiting for a run result'));
+    }, waitMs);
 
-        try {
-            targetWindow.postMessage({ __a11ycore: true, channel: FRAME_RPC_CHANNEL, requestId: requestId, type: 'run', payload: payload }, '*');
-        } catch (e) {
-            clearTimeout(timeout);
-            registry.pending.delete(requestId);
-            reject(e);
-        }
+    registry.pending.set(requestId, {
+      onPong: function () {},
+      resolve: function (result) {
+        clearTimeout(timeout);
+        resolve(result);
+      },
+      reject: function (err) {
+        clearTimeout(timeout);
+        reject(err);
+      }
     });
+
+    try {
+      targetWindow.postMessage(
+        {
+          __a11ycore: true,
+          channel: FRAME_RPC_CHANNEL,
+          requestId: requestId,
+          type: 'run',
+          payload: payload
+        },
+        '*'
+      );
+    } catch (e) {
+      clearTimeout(timeout);
+      registry.pending.delete(requestId);
+      reject(e);
+    }
+  });
 }
 
 /**
@@ -191,20 +242,20 @@ function sendFrameRunCommand(win, targetWindow, payload, frameWaitTime) {
  * later re-enable doesn't need to re-attach it).
  */
 function enableFrameRpcResponder(win, handler) {
-    installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-    const registry = getFrameRpcRegistry(win);
-    registry.responder = handler;
-    return function disable() {
-        if (registry.responder === handler) registry.responder = null;
-    };
+  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
+  const registry = getFrameRpcRegistry(win);
+  registry.responder = handler;
+  return function disable() {
+    if (registry.responder === handler) registry.responder = null;
+  };
 }
 
 module.exports = {
-    FRAME_RPC_CHANNEL,
-    getFrameRpcRegistry,
-    installFrameRpcListener,
-    nextFrameRpcRequestId,
-    pingFrame,
-    sendFrameRunCommand,
-    enableFrameRpcResponder
+  FRAME_RPC_CHANNEL,
+  getFrameRpcRegistry,
+  installFrameRpcListener,
+  nextFrameRpcRequestId,
+  pingFrame,
+  sendFrameRunCommand,
+  enableFrameRpcResponder
 };

package/src/core/frame-scan.js

@@ -5,7 +5,7 @@
  * mode (surea11y loaded directly into a page with no automation driver --
  * see docs/INTEGRATION.md's "Browser extension context" section). A
  * Playwright-driven scan doesn't need any of this (see
- * surea11y-playwright's ROADMAP.md gap #1 -- CDP-level frame access is
+ * @surea11y/playwright's ROADMAP.md gap #1 -- CDP-level frame access is
  * unconditional, strictly better than what a cooperative protocol like this
  * one can achieve). This exists for when there is no automation driver, the
  * same situation a widely-used reference engine itself is built around.
@@ -31,37 +31,41 @@
  * bundle instead.
  */
 
+/* global runCore, resolveContextRoots, resolveEffectiveRunOnly, pingFrame,
+   sendFrameRunCommand, enableFrameRpcResponder, CHECK_DEFS, RULE_IMPLS,
+   ENGINE_TAG, SCHEMA_VERSION, COMPOSITE_RULES */
+
 function findChildFrameElements(roots) {
-    const seen = new Set();
-    const out = [];
-    for (const root of roots) {
-        if (!root || typeof root.querySelectorAll !== 'function') continue;
-        let matches = [];
-        try {
-            matches = root.querySelectorAll('iframe, frame');
-        } catch (e) {
-            matches = [];
-        }
-        for (const el of matches) {
-            if (el && !seen.has(el)) {
-                seen.add(el);
-                out.push(el);
-            }
-        }
+  const seen = new Set();
+  const out = [];
+  for (const root of roots) {
+    if (!root || typeof root.querySelectorAll !== 'function') continue;
+    let matches;
+    try {
+      matches = root.querySelectorAll('iframe, frame');
+    } catch (e) {
+      matches = [];
+    }
+    for (const el of matches) {
+      if (el && !seen.has(el)) {
+        seen.add(el);
+        out.push(el);
+      }
     }
-    return out;
+  }
+  return out;
 }
 
 function getFrameElementUrl(el) {
-    try {
-        if (el.contentWindow && el.contentWindow.location && el.contentWindow.location.href) {
-            return el.contentWindow.location.href;
-        }
-    } catch (e) {
-        // Cross-origin: reading contentWindow.location.href itself throws. Fall
-        // back to the authored src attribute (always readable, any origin).
+  try {
+    if (el.contentWindow && el.contentWindow.location && el.contentWindow.location.href) {
+      return el.contentWindow.location.href;
     }
-    return el.getAttribute ? (el.getAttribute('src') || null) : null;
+  } catch (e) {
+    // Cross-origin: reading contentWindow.location.href itself throws. Fall
+    // back to the authored src attribute (always readable, any origin).
+  }
+  return el.getAttribute ? el.getAttribute('src') || null : null;
 }
 
 /**
@@ -84,60 +88,63 @@ function getFrameElementUrl(el) {
  * @returns {Promise<{ topFrame: object, frames: Array<{url:string|null, topFrame?:object, frames?:Array, error?:string}> }>}
  */
 function runa11yCoreAcrossFrames(pageUrl, contextSelector, engineOptions, runOnly) {
-    const topFrame = runCore(
-        pageUrl,
-        contextSelector,
-        engineOptions,
-        resolveEffectiveRunOnly(engineOptions, runOnly),
-        CHECK_DEFS,
-        RULE_IMPLS,
-        ENGINE_TAG,
-        SCHEMA_VERSION,
-        COMPOSITE_RULES
-    );
+  const topFrame = runCore(
+    pageUrl,
+    contextSelector,
+    engineOptions,
+    resolveEffectiveRunOnly(engineOptions, runOnly),
+    CHECK_DEFS,
+    RULE_IMPLS,
+    ENGINE_TAG,
+    SCHEMA_VERSION,
+    COMPOSITE_RULES
+  );
 
-    const eo = (engineOptions && typeof engineOptions === 'object') ? engineOptions : {};
-    const pingWaitTime = typeof eo.pingWaitTime === 'number' ? eo.pingWaitTime : undefined;
-    const frameWaitTime = typeof eo.frameWaitTime === 'number' ? eo.frameWaitTime : undefined;
+  const eo = engineOptions && typeof engineOptions === 'object' ? engineOptions : {};
+  const pingWaitTime = typeof eo.pingWaitTime === 'number' ? eo.pingWaitTime : undefined;
+  const frameWaitTime = typeof eo.frameWaitTime === 'number' ? eo.frameWaitTime : undefined;
 
-    const { roots } = resolveContextRoots(document, contextSelector);
-    const frameElements = findChildFrameElements(roots);
+  const { roots } = resolveContextRoots(document, contextSelector);
+  const frameElements = findChildFrameElements(roots);
 
-    const framePromises = frameElements.map(function (el) {
-        const url = getFrameElementUrl(el);
-        let targetWindow = null;
-        try {
-            targetWindow = el.contentWindow || null;
-        } catch (e) {
-            targetWindow = null;
-        }
-        if (!targetWindow) {
-            return Promise.resolve({ url: url, error: 'frame has no accessible contentWindow' });
-        }
+  const framePromises = frameElements.map(function (el) {
+    const url = getFrameElementUrl(el);
+    let targetWindow = null;
+    try {
+      targetWindow = el.contentWindow || null;
+    } catch (e) {
+      targetWindow = null;
+    }
+    if (!targetWindow) {
+      return Promise.resolve({ url: url, error: 'frame has no accessible contentWindow' });
+    }
 
-        return pingFrame(window, targetWindow, pingWaitTime).then(function (reachable) {
-            if (!reachable) {
-                return {
-                    url: url,
-                    error: 'no surea11y frame responder detected (that frame never called a11yCoreEnableFrameResponder(), or has not finished loading yet)'
-                };
-            }
-            return sendFrameRunCommand(
-                window,
-                targetWindow,
-                { pageUrl: url, contextSelector: null, engineOptions: eo, runOnly: runOnly },
-                frameWaitTime
-            ).then(function (result) {
-                return { url: url, topFrame: result.topFrame, frames: result.frames };
-            }).catch(function (err) {
-                return { url: url, error: String(err && err.message ? err.message : err) };
-            });
+    return pingFrame(window, targetWindow, pingWaitTime).then(function (reachable) {
+      if (!reachable) {
+        return {
+          url: url,
+          error:
+            'no surea11y frame responder detected (that frame never called a11yCoreEnableFrameResponder(), or has not finished loading yet)'
+        };
+      }
+      return sendFrameRunCommand(
+        window,
+        targetWindow,
+        { pageUrl: url, contextSelector: null, engineOptions: eo, runOnly: runOnly },
+        frameWaitTime
+      )
+        .then(function (result) {
+          return { url: url, topFrame: result.topFrame, frames: result.frames };
+        })
+        .catch(function (err) {
+          return { url: url, error: String(err && err.message ? err.message : err) };
         });
     });
+  });
 
-    return Promise.all(framePromises).then(function (frames) {
-        return { topFrame: topFrame, frames: frames };
-    });
+  return Promise.all(framePromises).then(function (frames) {
+    return { topFrame: topFrame, frames: frames };
+  });
 }
 
 /**
@@ -165,14 +172,19 @@ function runa11yCoreAcrossFrames(pageUrl, contextSelector, engineOptions, runOnl
  * @returns {function(): void} disable() -- stops responding to future scans
  */
 function a11yCoreEnableFrameResponder() {
-    return enableFrameRpcResponder(window, function (payload) {
-        return runa11yCoreAcrossFrames(
-            payload ? payload.pageUrl : null,
-            payload ? payload.contextSelector : null,
-            payload ? payload.engineOptions : {},
-            payload ? payload.runOnly : null
-        );
-    });
+  return enableFrameRpcResponder(window, function (payload) {
+    return runa11yCoreAcrossFrames(
+      payload ? payload.pageUrl : null,
+      payload ? payload.contextSelector : null,
+      payload ? payload.engineOptions : {},
+      payload ? payload.runOnly : null
+    );
+  });
 }
 
-module.exports = { findChildFrameElements, getFrameElementUrl, runa11yCoreAcrossFrames, a11yCoreEnableFrameResponder };
+module.exports = {
+  findChildFrameElements,
+  getFrameElementUrl,
+  runa11yCoreAcrossFrames,
+  a11yCoreEnableFrameResponder
+};