@surea11y/core 1.5.0 → 1.6.0

package/src/checks/automatic/css-orientation-lock.js

@@ -9,13 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.3.4
  * @applicability
- *   Any accessible (same-document, non-cross-origin) stylesheet — inline
+ *   Any accessible (same-document, non-cross-origin) stylesheet, inline
  *   `<style>` blocks and same-origin `<link>` stylesheets already loaded
  *   into `document.styleSheets`.
  * @expectation
  *   No `@media (orientation: portrait)` or `@media (orientation:
  *   landscape)` block sets a `transform`/`-webkit-transform`/`rotate`
- *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270) —
+ *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270),
  *   the well-known technique for visually forcing one orientation
  *   regardless of the device's actual orientation, which defeats WCAG
  *   1.3.4's requirement that content not restrict its view to a single
@@ -27,14 +27,15 @@
  *   lock. Compute the actual rotation angle and only flag ~90/~270 degrees,
  *   excluding ~0/~180 (a no-op or a flip, neither of which changes
  *   portrait<->landscape).
- * - Only `rotate`/`rotateZ` (transform functions) and the standalone CSS
- *   `rotate` property are parsed for degrees, from the two sources
- *   `style.transform`/`style.rotate`; `matrix()`/`matrix3d()`/`rotate3d()`
- *   are not decomposed into an equivalent angle (deliberately deferred as
- *   the same class of higher-complexity/lower-value work deferred elsewhere,
- *   e.g. `table-th-has-data-cells`'s narrower positional-header algorithm).
+ * - `rotate`/`rotateZ`, the standalone CSS `rotate` property, and
+ *   `rotate3d(x, y, z, angle)`/`matrix()`/`matrix3d()` are all parsed for
+ *   degrees. The matrix forms only yield an angle when they resolve to a
+ *   pure rotation about the Z axis (no scale, skew, translation, or
+ *   rotation combined with another axis). Anything else contributes 0,
+ *   same as an unrecognized value, rather than guessing at an angle a
+ *   general 3D matrix doesn't uniquely have.
  * - Cross-origin stylesheets throw on `.cssRules` access (browser
- *   security model) and are skipped — same class of limitation as any
+ *   security model) and are skipped, same class of limitation as any
  *   check that can only see same-origin/inspectable content (compare
  *   `iframe-focusable-content`).
  * - Not per-element: this is a whole-document/whole-stylesheet concern,
@@ -107,25 +108,98 @@ function runInPage(ctx) {
     return value; // deg
   }
 
-  // Sums the degrees of every rotate()/rotateZ() function found in a
-  // transform value (a real transform can legitimately compose more than
-  // one, e.g. "translate(-50%) rotate(90deg)").
+  function parseNumberList(argsStr) {
+    return trim(argsStr)
+      .split(',')
+      .map((s) => parseFloat(s.trim()));
+  }
+
+  // A 2D linear map (a, b, c, d) -- the first four arguments of
+  // `matrix(a, b, c, d, e, f)`, or the top-left of `matrix3d`'s 4x4 --
+  // is a pure rotation only when its columns are unit length and
+  // orthogonal (no scale/skew/reflection): a = cos(theta), b = sin(theta),
+  // c = -sin(theta), d = cos(theta). Returns degrees, or null when the
+  // map isn't a pure rotation.
+  function decomposeMatrix2dRotation(a, b, c, d) {
+    const EPS = 1e-3;
+    if (Math.abs(a - d) > EPS || Math.abs(b + c) > EPS) return null;
+    if (Math.abs(a * a + b * b - 1) > EPS) return null;
+    if (Math.abs(a * d - b * c - 1) > EPS) return null;
+    return (Math.atan2(b, a) * 180) / Math.PI;
+  }
+
+  // The 16 column-major values of `matrix3d(...)` represent a pure Z-axis
+  // rotation only when the 3rd/4th columns still match the identity (no
+  // translation, perspective, or rotation around another axis) and the
+  // top-left 2x2 block is a pure 2D rotation.
+  function decomposeMatrix3dZRotation(v) {
+    if (v.length !== 16 || !v.every(Number.isFinite)) return null;
+    const EPS = 1e-3;
+    const near = (x, t) => Math.abs(x - t) < EPS;
+    if (!(near(v[2], 0) && near(v[3], 0) && near(v[6], 0) && near(v[7], 0))) return null;
+    if (!(near(v[8], 0) && near(v[9], 0) && near(v[10], 1) && near(v[11], 0))) return null;
+    if (!(near(v[12], 0) && near(v[13], 0) && near(v[14], 0) && near(v[15], 1))) return null;
+    return decomposeMatrix2dRotation(v[0], v[1], v[4], v[5]);
+  }
+
+  // Sums the degrees of every rotate()/rotateZ()/rotate3d()/matrix()/
+  // matrix3d() function found in a transform value (a real transform can
+  // legitimately compose more than one, e.g. "translate(-50%)
+  // rotate(90deg)"). The matrix forms only contribute when they decompose
+  // to a pure Z rotation; anything else contributes 0, same as no match.
   function rotateDegreesFromTransform(t) {
     if (!t) return 0;
     let total = 0;
-    const re = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
     let m;
-    while ((m = re.exec(t)) !== null) {
+
+    const rotateRe = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
+    while ((m = rotateRe.exec(t)) !== null) {
       total += angleToDegrees(m[1]);
     }
+
+    const rotate3dRe = /rotate3d\s*\(([^)]*)\)/gi;
+    while ((m = rotate3dRe.exec(t)) !== null) {
+      const parts = m[1].split(',');
+      if (parts.length !== 4) continue;
+      const x = parseFloat(parts[0]);
+      const y = parseFloat(parts[1]);
+      const z = parseFloat(parts[2]);
+      const deg = angleToDegrees(parts[3]);
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z) || !deg) continue;
+      const EPS = 1e-3;
+      if (Math.abs(x) < EPS && Math.abs(y) < EPS && Math.abs(Math.abs(z) - 1) < EPS) {
+        total += z < 0 ? -deg : deg;
+      }
+    }
+
+    const matrixRe = /matrix\s*\(([^)]*)\)/gi;
+    while ((m = matrixRe.exec(t)) !== null) {
+      const vals = parseNumberList(m[1]);
+      if (vals.length === 6 && vals.every(Number.isFinite)) {
+        const deg = decomposeMatrix2dRotation(vals[0], vals[1], vals[2], vals[3]);
+        if (deg != null) total += deg;
+      }
+    }
+
+    const matrix3dRe = /matrix3d\s*\(([^)]*)\)/gi;
+    while ((m = matrix3dRe.exec(t)) !== null) {
+      const deg = decomposeMatrix3dZRotation(parseNumberList(m[1]));
+      if (deg != null) total += deg;
+    }
+
     return total;
   }
 
   // Whole-page-orientation-lock detection (see @implementation-notes): a
   // rotation near 0 or 180 degrees (mod 180) is a no-op or a flip, neither
   // of which changes portrait<->landscape, so it's NOT a lock; only a
-  // rotation near 90 or 270 degrees (mod 90, once the 0/180 case is
-  // excluded) is.
+  // rotation near 90 or 270 degrees is. "Near" is a tolerance window, not
+  // exact equality: a `rad`/`grad`/`turn` value converts to a 90-degree
+  // rotation with floating-point remainder (e.g. `1.5708rad` is
+  // 90.0000210...deg, never exactly 90), and ACT's own failed examples
+  // include a -inexact 92.5deg, both must still register as a
+  // lock, which exact-modulo-equality (`% 90 === 0`) never does.
+  const LOCK_TOLERANCE_DEG = 5;
   function isLockingRotation(styleDecl) {
     if (!styleDecl) return false;
     const transformVal =
@@ -141,9 +215,12 @@ function runInPage(ctx) {
 
     if (!degrees) return false;
 
-    const abs = Math.abs(degrees);
-    if (Math.abs(abs - 180) % 180 <= 0) return false; // near 0/180: not a lock
-    return Math.abs(abs - 90) % 90 <= 0; // near 90/270: a lock
+    // Normalize into [0, 180): a rotation and its mirror (rotation + 180)
+    // swap the same two axes, so only the position within one half-turn
+    // matters. A value near the 90-degree midpoint of that range is near
+    // 90 OR 270 in the original full-turn range.
+    const normalized = ((degrees % 180) + 180) % 180;
+    return Math.abs(normalized - 90) <= LOCK_TOLERANCE_DEG;
   }
 
   function isOrientationMedia(mediaText) {

package/src/checks/automatic/definition-list-children-valid.js

@@ -16,17 +16,16 @@
  *   level of wrapping div is allowed, matching how authors commonly group
  *   dt/dd pairs). If the flattened set contains any <dt> or <dd> at all, it
  *   must contain BOTH (an unbalanced dt-without-dd or dd-without-dt is
- *   invalid) — a flattened set with neither is vacuously fine, not a
+ *   invalid). A flattened set with neither is vacuously fine, not a
  *   violation (see implementation-notes). Any other direct or wrapped child
  *   breaks the description-list semantics assistive technologies rely on.
  * @implementation-notes
- * - Only one level of <div> wrapping is flattened — a <div> nested inside
+ * - Only one level of <div> wrapping is flattened, a <div> nested inside
  *   another wrapping <div> is not flattened further and its contents are
  *   reported invalid.
  * - The dt/dd pairing is only required "when not empty". A flattened set
- *   with NEITHER dt nor dd
- *   — whether from an empty wrapping <div>, only <script>/<template>/
- *   <style> content, or a genuinely childless <dl> — is not flagged; only
+ *   with NEITHER dt nor dd, whether from an empty wrapping <div>, only
+ *   <script>/<template>/<style> content, or a childless <dl>, is not flagged; only
  *   an unbalanced dt/dd pairing is a real structural problem.
  * - Distinct, atomic decision from dlitem-parent-valid (the
  *   inverse relationship: does a given <dt>/<dd> have a valid parent).
@@ -64,7 +63,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const PASSTHROUGH_TAGS = new Set(['dt', 'dd', 'script', 'template', 'style']);
 
@@ -109,8 +108,8 @@ function runInPage(ctx) {
     }
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
-    // The dt/dd pairing is only required "when not empty" — a <dl> with
-    // NEITHER dt nor dd (whether genuinely childless after flattening, only
+    // The dt/dd pairing is only required "when not empty", a <dl> with
+    // NEITHER dt nor dd (whether childless after flattening, only
     // passthrough script/template/style content, or an empty wrapping div)
     // is vacuously fine, not a violation. Only an UNBALANCED pairing (dt
     // present without any dd, or vice versa) is a real structural problem.

package/src/checks/automatic/deprecated-elements-not-used.js

@@ -15,7 +15,7 @@
  *   or hide it.
  * @expectation
  *   Neither element is present. Since their movement can never be paused,
- *   stopped, or hidden by the user, presence is itself the violation — this
+ *   stopped, or hidden by the user, presence is itself the violation. This
  *   rule has no partial-pass case (it reports only when the element is
  *   found).
  * @implementation-notes

package/src/checks/automatic/dialog-name-present.js

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check dialog-name-present
+ * @atomic true
+ * @summary Elements with role="dialog"/"alertdialog" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="dialog" or role="alertdialog" (the
+ *   attribute must name one of those roles alone, not a fallback list) that
+ *   are included in the accessibility tree. A native <dialog> without an
+ *   explicit role is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title. Both
+ *   roles are name-from-author-only, so the heading or body text inside the
+ *   dialog is not accepted as its name unless aria-labelledby points at it.
+ */
+
 const id = 'dialog-name-present';
 
 const meta = {
@@ -54,13 +72,13 @@ function runInPage(ctx) {
   function resolveAriaLabelledbyText(document, el, maxRefs) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
-    // Resolve via the shared getTextFromIdRefs helper — computes each
+    // Resolve via the shared getTextFromIdRefs helper, computes each
     // referenced element's own ACCESSIBLE NAME (aria-label, then
     // aria-labelledby, then a value-like name, then content, then title),
     // not just its content text. This matters when aria-labelledby points
     // at an <iframe title="..."> (e.g. BBC News' cookie-consent dialog,
     // pointing at an `<iframe title="SP Consent Message">`), whose only
-    // name source is its title attribute — an iframe's content is
+    // name source is its title attribute, an iframe's content is
     // opaque/cross-origin per HTML-AAM, so "name from content" is always
     // empty. Computing only name-from-content of the referenced node would
     // silently miss the title fallback and report no accessible name at

package/src/checks/automatic/duplicate-id-aria.js

@@ -20,8 +20,10 @@
  *   still computed. Whether that element is the intended target depends on
  *   author intent, which markup does not carry, so the outcome is cantTell.
  * @implementation-notes
- * - Scoped deliberately to ids referenced by ARIA, not the broader/
- *   deprecated page-wide duplicate-id check (see ROADMAP.md's "Skip" list).
+ * - Scoped to ids referenced by ARIA. The page-wide check
+ *   lives in its own rule, `duplicate-id`, mapped to the WCAG 2.0/2.1 SC
+ *   4.1.1 that WCAG 2.2 removed; the two overlap on referenced ids and
+ *   answer different questions there (see that rule's header).
  * - Document-wide by design: id uniqueness and ARIA id references are a
  *   whole-document property, not scoped to a sub-root. Reported occurrences are
  *   limited to the scanned scope.
@@ -59,7 +61,7 @@ const meta = {
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const IDREF_ATTRS = [
     'aria-labelledby',

package/src/checks/automatic/duplicate-id.js

@@ -0,0 +1,198 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check duplicate-id
+ * @atomic true
+ * @summary Every id value must be unique within its own tree
+ * @standard WCAG 2.1
+ * @sc 4.1.1
+ * @applicability
+ *   Applies to any element carrying a non-empty id attribute. Visibility
+ *   is irrelevant. A duplicate id breaks the same lookups whether the
+ *   element renders or not, which is why ACT 3ea0c8 evaluates hidden
+ *   elements too.
+ * @expectation
+ *   No other element in the same tree carries the same id value. Ids are
+ *   scoped per document tree and per shadow tree, so the same id inside
+ *   two different shadow roots is not a duplicate.
+ * @implementation-notes
+ * - WCAG-VERSION SCOPED. SC 4.1.1 Parsing was removed in WCAG 2.2, so this
+ *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`. A
+ *   consumer targeting WCAG 2.2 excludes it with
+ *   `excludeTags: ['wcag22-removed']`; one targeting 2.0 or 2.1 keeps it
+ *   and gets a real 4.1.1 result. The alternative, dropping the SC
+ *   mapping entirely, would have made a genuine 2.0/2.1 failure
+ *   invisible to anyone conformance-testing against those versions. See
+ *   `docs/ENGINE_OPTIONS.md` for the tag, and `docs/DESIGN_CHALLENGES.md`
+ *   for the decision this reverses.
+ * - The defect outlives its Success Criterion: a duplicate id breaks
+ *   `<label for>` association, fragment navigation, `getElementById`, and
+ *   every ID-reference attribute, none of which stopped mattering when
+ *   4.1.1 was retired. The SC was removed because browsers recover from
+ *   malformed markup, not because ids became free-form.
+ * - Scoping is per ROOT NODE, not per document: `getRootNode()` groups
+ *   light DOM against the document and each shadow tree against itself,
+ *   matching the DOM's own id-lookup scope. Two components that each use
+ *   `id="title"` inside their own shadow root are correct markup and are
+ *   not reported.
+ * - Overlaps `duplicate-id-aria` by design, and the two say different
+ *   things. That rule reports a duplicate id that an ARIA attribute
+ *   actually references, as a `cantTell` under 4.1.2, the reference
+ *   resolves to the first match, so whether the right element was named is
+ *   an authoring question. This one is the flat structural fact under
+ *   4.1.1, for every id, referenced or not.
+ * - Detection is document-wide while reporting follows the scanned scope,
+ *   the same split `duplicate-id-aria` uses: a `contextSelector` narrows
+ *   which duplicates get reported, never which ones count as duplicates.
+ */
+
+const id = 'duplicate-id';
+
+const meta = {
+  title: 'IDs must be unique',
+  description:
+    'Checks that every non-empty id attribute value is unique within its own document or shadow tree (WCAG 2.0/2.1 SC 4.1.1, removed in WCAG 2.2).',
+  i18n: {
+    titleKey: 'duplicateId_title',
+    descriptionKey: 'duplicateId_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag411', 'wcag22-removed', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.1'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.1',
+      requirement: '4.1.1',
+      title: 'Parsing',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.1': ['id-unique-page-wide'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // Detection spans the whole document; see the header comment on scope.
+  const all = new Set();
+  try {
+    const nodes = document.querySelectorAll ? document.querySelectorAll('[id]') : [];
+    for (const el of nodes) all.add(el);
+  } catch {
+    // no-throw: fall through to the helper-provided set below
+  }
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+
+  // queryAllSmart reaches into open shadow roots when includeShadowDom is on,
+  // which document.querySelectorAll never does.
+  let inScope = null;
+  if (queryAllSmart) {
+    try {
+      const scoped = queryAllSmart('[id]');
+      const list = Array.isArray(scoped) ? scoped : Array.from(scoped || []);
+      inScope = new Set(list);
+      for (const el of list) all.add(el);
+    } catch {
+      inScope = null;
+    }
+  }
+
+  // Ids resolve within their own tree, so group by root before comparing.
+  function rootOf(el) {
+    try {
+      if (typeof el.getRootNode === 'function') return el.getRootNode();
+    } catch {
+      // fall through
+    }
+    return document;
+  }
+
+  const byRootAndId = new Map(); // root -> Map(idValue -> element[])
+  let applicableCount = 0;
+
+  for (const el of all) {
+    if (!el || el.nodeType !== 1 || !el.getAttribute) continue;
+    const value = String(el.getAttribute('id') || '').trim();
+    if (!value) continue;
+
+    applicableCount += 1;
+
+    const root = rootOf(el);
+    let idMap = byRootAndId.get(root);
+    if (!idMap) {
+      idMap = new Map();
+      byRootAndId.set(root, idMap);
+    }
+    const bucket = idMap.get(value);
+    if (bucket) bucket.push(el);
+    else idMap.set(value, [el]);
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const idMap of byRootAndId.values()) {
+    for (const [value, els] of idMap) {
+      if (els.length <= 1) continue;
+
+      for (const el of els) {
+        if (inScope && !inScope.has(el)) continue;
+
+        const eligInfo = helpers.getEligibilityInfo
+          ? (() => {
+              try {
+                return helpers.getEligibilityInfo(el, ctx, { targetSet: 'dom' });
+              } catch {
+                return null;
+              }
+            })()
+          : null;
+
+        occurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: `The id "${value}" is used on ${els.length} elements in the same tree.`,
+            hint: 'Give each element its own id. A duplicate breaks <label for>, fragment links, getElementById and every ID-reference attribute, all of which resolve to the first match only.',
+            i18n: {
+              summaryKey: 'duplicateId_summary_fail',
+              hintKey: 'duplicateId_hint_fail',
+              params: { id: value, count: String(els.length) }
+            },
+            data: {
+              details: {
+                reasonCode: 'DUPLICATE_ID',
+                id: value,
+                count: els.length
+              },
+              visibilityFilter: eligInfo || { targetSet: 'dom', accEligible: null, reasons: [] }
+            }
+          })
+        );
+      }
+    }
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/embed-text-alternative-present.js

@@ -135,8 +135,8 @@ function runInPage(ctx) {
   }
 
   // `title` is a weaker text-alternative mechanism than aria-label/
-  // aria-labelledby — it is not reliably exposed to assistive technology
-  // in every context (e.g. touch/mobile) — so a pass achieved only via
+  // aria-labelledby, it is not reliably exposed to assistive technology
+  // in every context (e.g. touch/mobile), so a pass achieved only via
   // `title` is reported at reduced confidence rather than the rule's
   // default `high`.
   let anyPassedViaWeakMechanism = false;

package/src/checks/automatic/form-control-programmatic-label-present.js

@@ -13,12 +13,29 @@
  *
  * WCAG mapping: matches technique H44 ("Using label elements to associate
  * text labels with form controls"), which WCAG's own Techniques document
- * lists as sufficient for 1.3.1, 3.3.2, AND 4.1.2 simultaneously — a label
+ * lists as sufficient for 1.3.1, 3.3.2, AND 4.1.2 simultaneously. A label
  * that programmatically associates with a control conveys the
  * relationship (1.3.1), provides the instruction (3.3.2), and exposes the
  * accessible name (4.1.2) all at once. This rule was originally only wired
  * to 4.1.2, even though its own `tags` already listed wcag131/wcag332 and
  * wcag-facets.js already had matching facet ids under those SCs.
+ *
+ * @applicability
+ *   Applies to <input>, <select> and <textarea> elements included in the
+ *   accessibility tree, excluding the input types hidden, submit, reset,
+ *   button and image, which take their name from a value or alt attribute
+ *   rather than from a label. A control carrying
+ *   an explicit ARIA widget role is out of scope, button, checkbox,
+ *   combobox, listbox, textbox, slider and the rest of ROLE_OWNED_ELSEWHERE
+ *   each have a naming rule of their own, and role="presentation"/"none"
+ *   removes a control unless it is still tabbable.
+ * @expectation
+ *   Each applicable control carries a programmatic label by one of the
+ *   mechanisms helpers.getLabelMethod resolves, in its priority order: an
+ *   associated <label>, aria-labelledby, aria-label, title, then
+ *   placeholder. Any of the five satisfies this rule. Whether the weaker two
+ *   are an appropriate primary label is a separate question, asked by
+ *   form-control-programmatic-label-quality.
  */
 
 const id = 'form-control-programmatic-label-present';
@@ -162,7 +179,7 @@ function runInPage(ctx) {
 
   // getLabelMethod is provided by the shared dom-helpers bundle that
   // dom-runner.js always constructs for every rule execution (built-in or
-  // custom) — see createDomHelpers's own getLabelMethod, which implements
+  // custom), see createDomHelpers's own getLabelMethod, which implements
   // this exact <label>/aria-labelledby/aria-label/title/placeholder
   // priority order. No local reimplementation is needed as a fallback.
   function getLabelMethodSafe(el) {

package/src/checks/automatic/form-control-single-label.js

@@ -13,7 +13,7 @@
  *   hidden/submit/reset/button/image; select; textarea).
  * @expectation
  *   At most one <label> that can contribute to the control's accessible name
- *   is associated with it — by wrapping it, or by a <label for="..."> on its
+ *   is associated with it, by wrapping it, or by a <label for="..."> on its
  *   id (a label that both wraps and self-references via for counts once).
  *   Graded by whether the surplus labels actually compete for the name:
  *   - PASS when an override (aria-labelledby / aria-label) supersedes every

package/src/checks/automatic/iframe-focusable-content.js

@@ -11,7 +11,7 @@
  * @applicability
  *   Applies to <iframe>/<frame> elements with an explicit negative
  *   tabindex, whose embedded document is same-origin and reachable via
- *   contentDocument (cross-origin/unreachable frames assert nothing — see
+ *   contentDocument (cross-origin/unreachable frames assert nothing, see
  *   implementation notes).
  * @expectation
  *   The frame's embedded document contains no focusable element. Browsers
@@ -19,14 +19,26 @@
  *   document: Tab can still reach focusable content inside, even though
  *   the frame itself is skipped. An author who set tabindex="-1" intending
  *   to remove the frame from the tab order has not actually done so if the
- *   embedded document contains focusable content.
+ *   embedded document contains focusable content. Exception: an iframe with
+ *   both a `width` and `height` HTML attribute of 2px or less (a common
+ *   "tracking pixel" pattern) cannot render any perceptible content, so
+ *   focusable content inside it never satisfies ACT akn7bn's "visible"
+ *   requirement and doesn't count.
  * @implementation-notes
- * - Deliberately scoped to same-origin, currently-accessible content only
+ * - Scoped to same-origin, currently-accessible content only
  *   (contentDocument access is wrapped in try/catch and treated as "no
- *   constraint asserted" — not counted as applicable — when unreachable),
+ *   constraint asserted", not counted as applicable, when unreachable),
  *   matching this engine's established scope-limiting rationale (see
  *   src/core/aria-helpers.js file header) rather than guessing at
  *   cross-origin content.
+ * - A `srcdoc` iframe's document is same-origin by definition, but some
+ *   environments (notably jsdom, including this library's own Node/jsdom
+ *   integration path, see docs/INTEGRATION.md) never populate
+ *   `contentDocument` from the attribute. When the live document looks
+ *   empty and a `srcdoc` attribute is present, its HTML string is parsed
+ *   directly via DOMParser as a static fallback, no rendering pipeline
+ *   needed, and a real browser's already-loaded contentDocument is always
+ *   preferred untouched.
  * - Focusability inside the embedded document is checked with a small,
  *   self-contained heuristic (native interactive tags + non-negative
  *   tabindex) rather than ctx.helpers.getFocusableInfo, since that helper
@@ -67,15 +79,15 @@ function runInPage(ctx) {
   const { helpers, rule, document } = ctx;
 
   // Self-contained rendering check for the embedded document (a distinct
-  // realm — see this rule's own header comment on why the outer
+  // realm, see this rule's own header comment on why the outer
   // document's shared eligibility helpers can't be reused here).
-  // Deliberately checks only genuine non-rendering (display:none,
+  // Checks only genuine non-rendering (display:none,
   // visibility:hidden, the hidden attribute) via the ancestor chain, NOT
   // aria-hidden: aria-hidden alone does not remove an element from a real
   // browser's native tab order (the same anti-pattern this engine's own
   // aria-hidden-focus rule exists to catch), so an aria-hidden-but-
   // visually-rendered focusable element inside the frame is still
-  // genuinely reachable by keyboard and must stay flagged.
+  // reachable by keyboard and must stay flagged.
   function isRenderedInDoc(doc, el) {
     try {
       const view = doc.defaultView;
@@ -296,6 +308,44 @@ function runInPage(ctx) {
     return !Number.isNaN(n) && n < 0;
   }
 
+  // A `srcdoc` iframe's embedded document is same-origin by definition, but
+  // some environments (jsdom, notably) never populate `contentDocument`
+  // from the attribute at all. Parsing the attribute's own HTML string is a
+  // static, deterministic fallback that needs no rendering pipeline. It
+  // only kicks in when the live document looks empty, so a real browser's
+  // already-loaded contentDocument is always preferred untouched.
+  function parseSrcdocFallback(el) {
+    try {
+      const raw = el.getAttribute('srcdoc');
+      if (raw == null) return null;
+      const view = el.ownerDocument && el.ownerDocument.defaultView;
+      const DOMParserCtor = view && view.DOMParser;
+      if (!DOMParserCtor) return null;
+      return new DOMParserCtor().parseFromString(raw, 'text/html');
+    } catch {
+      return null;
+    }
+  }
+
+  // ACT akn7bn's own Expectation only cares about focusable content that is
+  // also *visible*: a 1x1 (or similar tracking-pixel-sized) iframe cannot
+  // render any perceptible content, whatever's focusable inside it. Scoped
+  // to the iframe's own HTML width/height attributes, a static, always-
+  // readable signal, unlike computed/rendered size, which needs real
+  // layout jsdom doesn't have (see docs/LIMITATIONS.md).
+  function isIframeVisiblyTiny(el) {
+    try {
+      const wAttr = el.getAttribute('width');
+      const hAttr = el.getAttribute('height');
+      if (wAttr == null || hAttr == null) return false;
+      const w = Number(String(wAttr).trim());
+      const h = Number(String(hAttr).trim());
+      return Number.isFinite(w) && Number.isFinite(h) && w <= 2 && h <= 2;
+    } catch {
+      return false;
+    }
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('iframe, frame')
     : helpers.queryAll('iframe, frame');
@@ -314,12 +364,18 @@ function runInPage(ctx) {
     } catch {
       contentDoc = null;
     }
+    const looksEmpty = !contentDoc || !contentDoc.body || !contentDoc.body.hasChildNodes();
+    if (looksEmpty && el.getAttribute('srcdoc') != null) {
+      const parsed = parseSrcdocFallback(el);
+      if (parsed) contentDoc = parsed;
+    }
     if (!contentDoc || !contentDoc.querySelectorAll) continue; // cross-origin/unreachable: no constraint asserted
 
     applicableCount += 1;
 
     const candidates = getFocusableCandidates(contentDoc);
     if (!candidates.length) continue;
+    if (isIframeVisiblyTiny(el)) continue; // ACT akn7bn: no visible content at all
 
     const tag = el.tagName.toLowerCase();
     const shouldProbe = candidates.length === 1;