@surea11y/core 1.1.2 → 1.2.0

package/src/checks/manual/landmark-no-duplicate-contentinfo-manual.js

@@ -71,25 +71,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — role-aware
+  // (an ancestor's bare TAG only counts when it carries no role attribute
+  // at all; an explicit role="dialog"-style override no longer suppresses)
+  // rather than a local tag-only copy. See that function's header comment
+  // in src/core/aria-helpers.js for the full algorithm and the real page
+  // (handsontable.com's docs-assistant side panel, an
+  // <aside role="dialog"> containing its own <header>) that surfaced this
+  // rule's own former tag-only copy as a false negative.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';

package/src/checks/manual/landmark-one-main-manual.js

@@ -61,6 +61,14 @@ const meta = {
   coverage: {}
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -148,4 +156,4 @@ function runInPage(ctx) {
   };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/manual/landmark-unique-manual.js

@@ -75,46 +75,48 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  // Two distinct ancestor sets, verified 2026-07-20 against a widely-used
-  // reference engine's own implicit-role functions directly rather than
-  // assumed from one shared list: <header>/<footer> use "sectioning content
-  // PLUS <main>" (that engine's getSectioningContentPlusMainSelector) to decide
-  // banner/contentinfo suppression, but <aside> uses PLAIN sectioning
-  // content only (article/aside/nav/section — NOT main) to decide
-  // complementary suppression. The old single SECTIONING_ANCESTORS set
-  // (which included 'main') was correct for header/footer but wrong for
-  // aside — found via a real page: Know Your Meme's two unnamed
-  // <aside class="extra-large-only"> elements are direct children of
-  // <main>, which incorrectly suppressed their implicit "complementary"
-  // role entirely, hiding a real duplicate-landmark violation that
-  // reference engine correctly flags.
-  const SECTIONING_ANCESTORS_PLUS_MAIN = new Set(['article', 'aside', 'main', 'nav', 'section']);
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'nav', 'section']);
-
-  function hasSectioningAncestorFrom(el, set) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (set.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor (role-aware:
+  // an ancestor's bare TAG only counts when it carries no role attribute at
+  // all; an explicit role="dialog"-style override no longer suppresses —
+  // see that function's header comment in src/core/aria-helpers.js) rather
+  // than the two local tag-only Sets this file used to carry. Two distinct
+  // ancestor scopes, verified 2026-07-20 against a widely-used reference
+  // engine's own implicit-role functions directly rather than assumed from
+  // one shared list: <header>/<footer> use "sectioning content PLUS <main>"
+  // (includeMain: true) to decide banner/contentinfo suppression, but
+  // <aside> uses PLAIN sectioning content only — NOT main (includeMain:
+  // false) — to decide complementary suppression. The old single
+  // SECTIONING_ANCESTORS set (which included 'main') was correct for
+  // header/footer but wrong for aside — found via a real page: Know Your
+  // Meme's two unnamed <aside class="extra-large-only"> elements are direct
+  // children of <main>, which incorrectly suppressed their implicit
+  // "complementary" role entirely, hiding a real duplicate-landmark
+  // violation that reference engine correctly flags. The tag-only
+  // (non-role-aware) half of this bug was separately found and fixed
+  // 2026-07-30 via the cross-engine comparisons project, on
+  // handsontable.com's docs-assistant side panel: an <aside role="dialog">
+  // containing its own <header> — role="dialog" isn't one of the four
+  // scoping roles, so the nested <header> keeps "banner" per spec, but a
+  // tag-only check unconditionally suppressed it just because the ancestor
+  // TAG was <aside>.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return hasSectioningAncestorFrom(el, SECTIONING_ANCESTORS_PLUS_MAIN) ? '' : 'banner';
-    if (tag === 'footer') return hasSectioningAncestorFrom(el, SECTIONING_ANCESTORS_PLUS_MAIN) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
       // Per a widely-used reference engine's own `aside` implicit-role function: suppressed by a
       // sectioning-content ancestor ONLY when the <aside> also has no
       // accessible name — a named <aside> is never suppressed, even when
-      // nested. Not yet evidenced by a real page in this corpus, but
-      // implemented to match the verified source exactly rather than
-      // leaving a known partial fix in place.
-      if (!hasSectioningAncestorFrom(el, SECTIONING_ANCESTORS)) return 'complementary';
+      // nested.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';

package/src/checks/manual/meta-viewport-large-manual.js

@@ -43,6 +43,14 @@ const meta = {
   coverage: {}
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -116,4 +124,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/manual/page-has-heading-one-manual.js

@@ -53,6 +53,14 @@ const meta = {
   coverage: {}
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -136,4 +144,4 @@ function runInPage(ctx) {
   };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/manual/page-title-patterns-manual.js

@@ -24,6 +24,14 @@ const meta = {
   coverage: { facetsBySc: { '2.4.2': ['page-title-patterns'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
   const probes = ctx && ctx.inputs && ctx.inputs.probes && typeof ctx.inputs.probes === 'object'
@@ -259,4 +267,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/manual/region-manual.js

@@ -46,6 +46,14 @@ const meta = {
   coverage: {}
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -79,25 +87,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — role-aware
+  // (an ancestor's bare TAG only counts when it carries no role attribute
+  // at all; an explicit role="dialog"-style override no longer suppresses)
+  // rather than a local tag-only copy. See that function's header comment
+  // in src/core/aria-helpers.js for the full algorithm and the real page
+  // (handsontable.com's docs-assistant side panel, an
+  // <aside role="dialog"> containing its own <header>) that surfaced this
+  // rule's own former tag-only copy as a false negative.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';
@@ -180,4 +200,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/manual/scope-attr-valid-manual.js

@@ -39,16 +39,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const VALID_SCOPES = new Set(['row', 'col', 'rowgroup', 'colgroup']);
 
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('[scope]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[scope]') : helpers.queryAll('[scope]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/tabindex-manual.js

@@ -40,14 +40,9 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('[tabindex]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex]') : helpers.queryAll('[tabindex]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/core/aria-helpers.js

@@ -38,6 +38,16 @@ function createAriaHelpers(opts, shared) {
     const trim = (shared && shared.trim) || ((v) => (v == null ? '' : String(v)).trim());
     const lower = (v) => trim(v).toLowerCase();
     const ariaDocument = opts && opts.document;
+    // Same normalization as createDomHelpers's `roots` (src/core/dom-helpers.js)
+    // -- opts.root accepts a single element or an array (multi-region
+    // contextSelector support). Used to bound hasLandmarkScopingAncestor's
+    // ancestor walk to the scanned scope; see that function below.
+    const ariaRoots = (() => {
+        const r = opts && opts.root;
+        if (Array.isArray(r)) return r.filter((x) => x && typeof x === 'object');
+        if (r && typeof r === 'object') return [r];
+        return [];
+    })();
 
     // Existence check for a single ID token — never throws, returns false
     // (not "unknown") when the document isn't available so callers degrade
@@ -75,25 +85,70 @@ function createAriaHelpers(opts, shared) {
         return false;
     }
 
-    // Used for <header>/<footer>'s own conditional implicit role: per the
-    // W3C ARIA-in-HTML spec (matching a widely-used reference engine's own
-    // element-spec table for "header"/"footer" implicit-role functions, which check
-    // getSectioningContentPlusMainSelector — a fixed HTML content-type list,
-    // not a deep accname-style computation), a <header>/<footer> is only a
-    // "banner"/"contentinfo" landmark when it is NOT nested inside sectioning
-    // content (article/aside/nav/section) or <main>; nested, its implicit
-    // role is generic/null instead. Simplified to a tag-name ancestor walk
-    // (skipping that engine's additional role=article/complementary/navigation/
-    // region/main equivalences) — deliberately pragmatic, matching this
-    // table's existing precedent (hasAccessibleNameHint above takes the same
-    // "close enough, tag-based" approach rather than a full spec re-implementation).
-    function hasSectioningAncestor(el) {
+    // Shared "does this element have a landmark-scoping ancestor" primitive
+    // — <header>'s "banner", <footer>'s "contentinfo", and <aside>'s
+    // "complementary" implicit roles are all conditioned on the same W3C
+    // ARIA-in-HTML exclusion: suppressed when nested inside sectioning
+    // content (article/aside/nav/section), and for header/footer only,
+    // also suppressed when nested inside <main> (pass includeMain: true).
+    // <aside> itself omits <main> from its own exclusion list — see the
+    // `aside` case in getElementRoleKey below — so callers must pass the
+    // right includeMain for the role they're computing.
+    //
+    // ROLE-AWARE, not tag-only: an ancestor's bare TAG only counts when it
+    // has NO role attribute at all; once ANY role attribute is present,
+    // only that attribute's own (first-token) value decides membership —
+    // matching a widely-used reference engine's real
+    // getSectioningContentSelector/getSectioningContentPlusMainSelector,
+    // verified 2026-07-30 by reading that engine's source directly:
+    // `${tag}:not([role])` for the tag-based branch, OR'd with a wholly
+    // separate ` [role=article], [role=complementary], [role=navigation],
+    // [role=region]` branch (plus `, main:not([role]), [role=main]` for
+    // the plus-main variant) — never a tag-AND-role intersection.
+    //
+    // This replaced a tag-name-only ancestor walk (used only for <header>,
+    // and separately re-duplicated with the same tag-only bug across 6
+    // manual landmark-check files — see each file's own delegation to
+    // helpers.hasLandmarkScopingAncestor now) that missed a real page:
+    // handsontable.com's docs-assistant side panel is an
+    // <aside role="dialog"> containing its own <header>. role="dialog" is
+    // not one of the four scoping roles, so per spec the nested <header>
+    // DOES keep its implicit "banner" role (confirmed against that
+    // reference engine's real output via a minimal repro) — but the old
+    // tag-only check unconditionally suppressed it purely because the
+    // ancestor TAG was <aside>, regardless of its role override. A real
+    // false negative in landmark-no-duplicate-banner/landmark-unique,
+    // found via the cross-engine comparisons project 2026-07-30.
+    const LANDMARK_SCOPING_TAGS = new Set(['article', 'aside', 'nav', 'section']);
+    const LANDMARK_SCOPING_ROLE_TOKENS = new Set(['article', 'complementary', 'navigation', 'region']);
+
+    function isLandmarkScopingAncestorElement(el, includeMain) {
+        const tag = lower(el.tagName || '');
+        const roleAttr = getAttr(el, 'role');
+        if (roleAttr == null) {
+            // No role attribute at all: falls back to the plain HTML tag.
+            if (LANDMARK_SCOPING_TAGS.has(tag)) return true;
+            return includeMain && tag === 'main';
+        }
+        // A role attribute is present (even empty/invalid) — the element's
+        // bare TAG no longer counts; only an explicit, scoping-relevant
+        // role value does.
+        const token = trim(roleAttr).split(/\s+/)[0].toLowerCase();
+        if (LANDMARK_SCOPING_ROLE_TOKENS.has(token)) return true;
+        return includeMain && token === 'main';
+    }
+
+    function hasLandmarkScopingAncestor(el, opts) {
         if (!isElement(el)) return false;
+        const includeMain = !!(opts && opts.includeMain);
         let cur = el.parentElement;
         let guard = 0;
         while (cur && guard++ < 200) {
-            const t = lower(cur.tagName || '');
-            if (t === 'article' || t === 'aside' || t === 'main' || t === 'nav' || t === 'section') return true;
+            if (isLandmarkScopingAncestorElement(cur, includeMain)) return true;
+            // Don't climb past the scanned scope -- a contextSelector-scoped
+            // (or fragment) scan should never let ancestry OUTSIDE the
+            // analyzed subtree affect a role computed WITHIN it.
+            if (ariaRoots.includes(cur)) break;
             cur = cur.parentElement;
         }
         return false;
@@ -749,14 +804,16 @@ function createAriaHelpers(opts, shared) {
         if (tag === 'header') {
             // <header>'s own implicit role is conditional: "banner" when
             // top-level (not nested inside sectioning content/<main>),
-            // generic/null when nested — see hasSectioningAncestor above.
+            // generic/null when nested — see hasLandmarkScopingAncestor
+            // above (includeMain: true, matching <header>'s real exclusion
+            // list, which does include <main>).
             // role="banner" restated is only a no-op restatement of the
             // native role (and therefore permitted) at the top level; a
             // widely-used reference engine's own allowedRoles array for
             // <header> doesn't include 'banner'
             // at all (reached only via the native-role-match branch), same
             // shape as <section>'s 'region'.
-            return hasSectioningAncestor(el) ? 'header' : 'header[toplevel]';
+            return hasLandmarkScopingAncestor(el, { includeMain: true }) ? 'header' : 'header[toplevel]';
         }
 
         if (tag === 'label') {
@@ -899,7 +956,14 @@ function createAriaHelpers(opts, shared) {
         getRequiredOwnedRoles,
         getRequiredContextRoles,
         isRoleAllowedOnElement,
-        getContainmentRole
+        getContainmentRole,
+
+        // Shared "does this element have a landmark-scoping ancestor"
+        // primitive — see its own header comment above. Re-exported at
+        // helpers' top level too (src/core/dom-helpers.js), matching
+        // getLandmarkNameInfo's precedent, for the manual landmark-check
+        // files that used to each carry their own (buggy, tag-only) copy.
+        hasLandmarkScopingAncestor
     };
 }
 

package/src/core/dom-helpers.js

@@ -120,6 +120,11 @@ function createDomHelpers(opts) {
     // opt out with includeHiddenElements:true.
     const includeHiddenElements = !!(opts && opts.includeHiddenElements === true);
     const excludeSelectors = Array.isArray(opts && opts.excludeSelectors) ? opts.excludeSelectors : [];
+    // Default off: explicit opt-in for "this scan target was never meant to
+    // represent a real page" (e.g. a raw component fragment parsed on its
+    // own), regardless of whether document.documentElement happens to be in
+    // scope. See isWholeDocumentScope() below.
+    const fragment = !!(opts && opts.fragment === true);
 
     // Rule-scoped excludes (engineOptions.rules[ruleId].excludeSelectors), set
     // by dom-runner.js immediately before invoking each rule's applicability/
@@ -4122,6 +4127,22 @@ function createDomHelpers(opts) {
         {trim}
     );
 
+    // For rules whose check is inherently about the WHOLE page (does the
+    // page have a title? a declared language? a way to skip repeated
+    // blocks?) rather than about elements found within a scanned subtree --
+    // these can't be answered correctly by scoping via queryAllSmart/ctx.root
+    // the way per-element checks can, since a subtree that never had (and
+    // was never meant to have) e.g. its own <title> shouldn't be faulted for
+    // lacking one. `false` when `fragment:true` was explicitly set, or when
+    // `contextSelector` scoped this run narrower than the whole document
+    // (roots doesn't include document.documentElement); `true` in the
+    // default/unscoped case, so this is a no-op for the overwhelming
+    // majority of existing (whole-page) scans.
+    function isWholeDocumentScope() {
+        if (fragment) return false;
+        return roots.includes(document.documentElement);
+    }
+
     return {
         // Existing query/snippet utilities
         queryAll,
@@ -4137,6 +4158,7 @@ function createDomHelpers(opts) {
         isExcluded,
         isAccTreeEligible,
         isDomVisibleEligible,
+        isWholeDocumentScope,
 
         // Engine-internal: sets which rule's rule-scoped excludeSelectors
         // (engineOptions.rules[ruleId].excludeSelectors) are currently in
@@ -4161,6 +4183,16 @@ function createDomHelpers(opts) {
         // see getLandmarkNameInfo's own header comment for why this replaced 7 duplicated copies)
         getLandmarkNameInfo,
 
+        // "Does this element have a landmark-scoping ancestor" (role-aware
+        // sectioning-content/<main> check backing <header>/<footer>/<aside>'s
+        // conditional implicit roles) -- re-exported from aria helpers at
+        // this top level, matching getLandmarkNameInfo just above, so the
+        // manual landmark-check files that used to each carry their own
+        // (buggy, tag-only) copy can call helpers.hasLandmarkScopingAncestor
+        // directly. See aria.hasLandmarkScopingAncestor's own header comment
+        // in src/core/aria-helpers.js for the full algorithm and rationale.
+        hasLandmarkScopingAncestor: aria.hasLandmarkScopingAncestor,
+
         // Name / description
         getAccessibleNameInfo,
         getAccessibleDescriptionInfo,

package/src/core/dom-runner.js

@@ -52,6 +52,9 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
     // unless the caller explicitly opts in.
     const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
+    // Default off: explicit opt-in for "this scan target was never meant to
+    // represent a real page" -- see helpers.isWholeDocumentScope().
+    const fragment = !!(engineOptionsResolved && engineOptionsResolved.fragment === true);
 
     const url = pageUrl || (document.location && document.location.href) || null;
     const title = document.title || null;
@@ -83,6 +86,7 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
         includeShadowDom,
         includeHiddenElements,
         excludeSelectors,
+        fragment,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
     });
@@ -219,6 +223,8 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
                 ruleVersion: normalizedMeta.ruleVersion,
                 normative: normalizedMeta.normative,
                 atomic: normalizedMeta.atomic,
+                deprecated: normalizedMeta.deprecated,
+                deprecation: normalizedMeta.deprecation,
                 category: normalizedMeta.category,
                 standard: normalizedMeta.standard,
                 applicability: normalizedMeta.applicability,
@@ -478,6 +484,8 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
                 ruleVersion: '0.0.0',
                 normative: true,
                 atomic: false,
+                deprecated: false,
+                deprecation: null,
                 category: null,
                 standard: null,
                 applicability: '',

package/src/core/rule-meta.js

@@ -80,6 +80,23 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
   const normative = (typeof m.normative === 'boolean') ? m.normative : true;
   const atomic = (typeof m.atomic === 'boolean') ? m.atomic : true;
 
+  // Deprecation signal for the rule catalog (see docs/API_STABILITY.md).
+  // Purely informational -- a deprecated rule still runs and produces
+  // results completely normally; this is a catalog-level migration signal
+  // for integrators, not an automatic exclusion.
+  const deprecated = (typeof m.deprecated === 'boolean') ? m.deprecated : false;
+  const deprecation = (deprecated && m.deprecation && typeof m.deprecation === 'object' && !Array.isArray(m.deprecation))
+      ? {
+          replacedBy: (typeof m.deprecation.replacedBy === 'string' && m.deprecation.replacedBy.trim()) ? m.deprecation.replacedBy.trim() : null,
+          reason: (typeof m.deprecation.reason === 'string') ? m.deprecation.reason.trim() : '',
+          sinceVersion: (typeof m.deprecation.sinceVersion === 'string') ? m.deprecation.sinceVersion.trim() : ''
+        }
+      : null;
+
+  if (deprecated && (!deprecation || !deprecation.reason || !deprecation.sinceVersion)) {
+    throw new Error(`Rule ${ruleId}: meta.deprecated:true requires meta.deprecation.reason and meta.deprecation.sinceVersion`);
+  }
+
   const category = (typeof m.category === 'string' && m.category.trim()) ? m.category.trim() : null;
   const standard = (typeof m.standard === 'string' && m.standard.trim()) ? m.standard.trim() : null;
 
@@ -127,6 +144,8 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
     ruleVersion,
     normative,
     atomic,
+    deprecated,
+    deprecation,
     category,
     standard,
     applicability,