@surea11y/core 1.0.0

package/src/checks/manual/label-title-only-manual.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * @check label-title-only
+ * @atomic true
+ * @summary Form controls should not rely on the title attribute as their only label
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to labelable form controls (input, excluding
+ *   hidden/submit/reset/button/image; select; textarea) that have a
+ *   non-empty title attribute.
+ * @expectation
+ *   The control also has a real label — a wrapping/associated <label>,
+ *   aria-label, or aria-labelledby — rather than depending on the title
+ *   attribute alone. A title-only tooltip is not reliably exposed by all
+ *   assistive technology and is not visible at all until hover/focus,
+ *   unlike a persistent visible label.
+ * @implementation-notes
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule; see landmark-banner-is-top-level's
+ *   header comment for the shared rationale/precedent.
+ * - Distinct from form-control-programmatic-label-present (that
+ *   rule accepts title as one of several valid presence mechanisms;
+ *   this rule flags the narrower case where title is the ONLY one).
+ */
+
+const id = 'label-title-only';
+
+const meta = {
+  title: 'Form controls should not use title as their only label',
+  description: 'Checks that a form control with a title attribute also has a real label (label element, aria-label, or aria-labelledby).',
+  i18n: {
+    titleKey: 'labelTitleOnly_title',
+    descriptionKey: 'labelTitleOnly_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'forms', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'understandable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const selector = 'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  const labelsByFor = new Map();
+  const allLabels = document.getElementsByTagName ? document.getElementsByTagName('label') : [];
+  for (const lab of allLabels) {
+    if (!lab || !lab.getAttribute) continue;
+    const forValue = String(lab.getAttribute('for') || '').trim();
+    if (!forValue) continue;
+    if (!labelsByFor.has(forValue)) labelsByFor.set(forValue, []);
+    labelsByFor.get(forValue).push(lab);
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const title = String(el.getAttribute('title') || '').trim();
+    if (!title) continue;
+
+    applicableCount += 1;
+
+    const ariaLabel = String(el.getAttribute('aria-label') || '').trim();
+    if (ariaLabel) continue;
+    const ariaLabelledby = String(el.getAttribute('aria-labelledby') || '').trim();
+    if (ariaLabelledby) continue;
+
+    const wrappingLabel = el.closest ? el.closest('label') : null;
+    if (wrappingLabel) continue;
+
+    const controlId = String(el.getAttribute('id') || '').trim();
+    if (controlId && labelsByFor.has(controlId)) continue;
+
+    const tag = el.tagName.toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This form control relies on the title attribute as its only label.',
+      hint: 'Add a visible <label> (or aria-label/aria-labelledby) in addition to, or instead of, the title attribute.',
+      i18n: {
+        summaryKey: 'labelTitleOnly_summary_cantTell',
+        hintKey: 'labelTitleOnly_hint_cantTell',
+        params: { element: tag }
+      },
+      data: {
+        details: { reasonCode: 'LABEL_TITLE_ONLY', element: tag }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/landmark-banner-is-top-level-manual.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * @check landmark-banner-is-top-level
+ * @atomic true
+ * @summary The banner landmark must not be nested inside another landmark
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies whenever the page contains at least one banner landmark
+ *   (explicit role="banner", or an implicit <header> that is not itself
+ *   nested inside <article>/<aside>/<main>/<nav>/<section> — see
+ *   implementation notes).
+ * @expectation
+ *   No banner landmark has an ancestor that is itself any landmark
+ *   region. A banner nested inside another landmark is not a top-level,
+ *   whole-page banner and confuses landmark-based navigation for
+ *   assistive technology users.
+ * @implementation-notes
+ * - Not WCAG-normative (a widely-used reference engine classifies this as "Best Practices," no SC
+ *   tag) — authored as an advisory, cantTell-capped `type: 'manual'`
+ *   rule per ROADMAP.md Tier 1b and the design doc's policy model
+ *   ("Advisory / best-practice rules may exist, but must not produce
+ *   `fail`"). Matches the existing `page-title-patterns-manual.js`
+ *   precedent: deterministic DOM analysis, no human required, but
+ *   capped at `cantTell`/`notApplicable` rather than `fail`/`pass`.
+ * - Landmark detection here models WAI-ARIA APG landmark roles and the
+ *   HTML-AAM implicit-role mapping (header→banner, footer→contentinfo,
+ *   main→main, nav→navigation, aside→complementary, section/form→
+ *   region/form only when accessibly named), not a byte-for-byte port
+ *   of a widely-used reference engine's internal algorithm — verify against upstream if exact
+ *   parity is ever required.
+ */
+
+const id = 'landmark-banner-is-top-level';
+
+const meta = {
+  title: 'Banner landmark must be top-level',
+  description: 'Checks that the banner landmark (role="banner" or a non-nested <header>) is not nested inside another landmark region.',
+  i18n: {
+    titleKey: 'landmarkBannerIsTopLevel_title',
+    descriptionKey: 'landmarkBannerIsTopLevel_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'landmarks', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  // Delegates to the shared helpers.getLandmarkNameInfo (aria-label -> aria-labelledby, via the
+  // target's own accessible name, not raw textContent -> title attribute fallback) rather than a
+  // local copy -- see that function's header comment in src/core/dom-helpers.js for the real bug
+  // (missing title fallback) this replaced across all 7 landmark rule files that had their own
+  // copy of this logic.
+  function getAccessibleLandmarkName(el) {
+    try {
+      if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
+        const info = helpers.getLandmarkNameInfo(el, ctx);
+        if (info && info.present && info.value) return normalizeWs(info.value);
+      }
+    } catch {}
+    return '';
+  }
+
+  function getExplicitRoleToken(el) {
+    const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
+    if (!raw) return '';
+    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;
+  }
+
+  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 === 'main') return 'main';
+    if (tag === 'nav') return 'navigation';
+    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
+    if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
+    return '';
+  }
+
+  const LANDMARK_ROLES = new Set(['banner', 'contentinfo', 'main', 'navigation', 'complementary', 'region', 'form', 'search']);
+
+  function getLandmarkRole(el) {
+    if (!el || !el.getAttribute) return '';
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) return LANDMARK_ROLES.has(explicit) ? explicit : '';
+    return getImplicitLandmarkRole(el);
+  }
+
+  function hasLandmarkAncestor(el) {
+    let p = el.parentElement;
+    while (p) {
+      if (getLandmarkRole(p)) return true;
+      p = p.parentElement;
+    }
+    return false;
+  }
+
+  // queryAllSmart (shadow-DOM-aware) instead of plain document.querySelectorAll -- see
+  // landmark-unique-manual.js's header comment for the real page (Airtable, 2026-07-23)
+  // that surfaced this gap: a third-party shadow-DOM-hosted widget's own landmark is
+  // invisible to a light-DOM-only query.
+  let nodes = [];
+  try {
+    nodes = helpers && typeof helpers.queryAllSmart === 'function'
+      ? helpers.queryAllSmart('header, footer, main, nav, aside, section, form, [role]')
+      : document.querySelectorAll('header, footer, main, nav, aside, section, form, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const banners = [];
+  const seen = new Set();
+  for (const el of nodes) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    if (getLandmarkRole(el) === 'banner') banners.push(el);
+  }
+
+  if (banners.length === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  for (const el of banners) {
+    if (!hasLandmarkAncestor(el)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This banner landmark is nested inside another landmark region.',
+      hint: 'Move the banner landmark (header/role="banner") so it is not contained by another landmark; a banner should be a top-level region of the page.',
+      i18n: {
+        summaryKey: 'landmarkBannerIsTopLevel_summary_cantTell',
+        hintKey: 'landmarkBannerIsTopLevel_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'LANDMARK_BANNER_NOT_TOP_LEVEL' }
+      }
+    });
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/landmark-contentinfo-is-top-level-manual.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * @check landmark-contentinfo-is-top-level
+ * @atomic true
+ * @summary The contentinfo landmark must not be nested inside another landmark
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies whenever the page contains at least one contentinfo landmark
+ *   (explicit role="contentinfo", or an implicit <footer> that is not
+ *   itself nested inside <article>/<aside>/<main>/<nav>/<section> — see
+ *   implementation notes).
+ * @expectation
+ *   No contentinfo landmark has an ancestor that is itself any landmark
+ *   region. A contentinfo nested inside another landmark is not a
+ *   top-level, whole-page footer region and confuses landmark-based
+ *   navigation for assistive technology users.
+ * @implementation-notes
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule; see landmark-banner-is-top-level's
+ *   header comment for the shared rationale/precedent (this rule mirrors
+ *   its structure with contentinfo/footer in place of banner/header).
+ */
+
+const id = 'landmark-contentinfo-is-top-level';
+
+const meta = {
+  title: 'Contentinfo landmark must be top-level',
+  description: 'Checks that the contentinfo landmark (role="contentinfo" or a non-nested <footer>) is not nested inside another landmark region.',
+  i18n: {
+    titleKey: 'landmarkContentinfoIsTopLevel_title',
+    descriptionKey: 'landmarkContentinfoIsTopLevel_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'landmarks', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  // Delegates to the shared helpers.getLandmarkNameInfo (aria-label -> aria-labelledby, via the
+  // target's own accessible name, not raw textContent -> title attribute fallback) rather than a
+  // local copy -- see that function's header comment in src/core/dom-helpers.js for the real bug
+  // (missing title fallback) this replaced across all 7 landmark rule files that had their own
+  // copy of this logic.
+  function getAccessibleLandmarkName(el) {
+    try {
+      if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
+        const info = helpers.getLandmarkNameInfo(el, ctx);
+        if (info && info.present && info.value) return normalizeWs(info.value);
+      }
+    } catch {}
+    return '';
+  }
+
+  function getExplicitRoleToken(el) {
+    const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
+    if (!raw) return '';
+    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;
+  }
+
+  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 === 'main') return 'main';
+    if (tag === 'nav') return 'navigation';
+    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
+    if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
+    return '';
+  }
+
+  const LANDMARK_ROLES = new Set(['banner', 'contentinfo', 'main', 'navigation', 'complementary', 'region', 'form', 'search']);
+
+  function getLandmarkRole(el) {
+    if (!el || !el.getAttribute) return '';
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) return LANDMARK_ROLES.has(explicit) ? explicit : '';
+    return getImplicitLandmarkRole(el);
+  }
+
+  function hasLandmarkAncestor(el) {
+    let p = el.parentElement;
+    while (p) {
+      if (getLandmarkRole(p)) return true;
+      p = p.parentElement;
+    }
+    return false;
+  }
+
+  // queryAllSmart (shadow-DOM-aware) instead of plain document.querySelectorAll -- see
+  // landmark-unique-manual.js's header comment for the real page (Airtable, 2026-07-23)
+  // that surfaced this gap: a third-party shadow-DOM-hosted widget's own landmark is
+  // invisible to a light-DOM-only query.
+  let nodes = [];
+  try {
+    nodes = helpers && typeof helpers.queryAllSmart === 'function'
+      ? helpers.queryAllSmart('header, footer, main, nav, aside, section, form, [role]')
+      : document.querySelectorAll('header, footer, main, nav, aside, section, form, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const contentinfos = [];
+  const seen = new Set();
+  for (const el of nodes) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    if (getLandmarkRole(el) === 'contentinfo') contentinfos.push(el);
+  }
+
+  if (contentinfos.length === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  for (const el of contentinfos) {
+    if (!hasLandmarkAncestor(el)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This contentinfo landmark is nested inside another landmark region.',
+      hint: 'Move the contentinfo landmark (footer/role="contentinfo") so it is not contained by another landmark; contentinfo should be a top-level region of the page.',
+      i18n: {
+        summaryKey: 'landmarkContentinfoIsTopLevel_summary_cantTell',
+        hintKey: 'landmarkContentinfoIsTopLevel_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'LANDMARK_CONTENTINFO_NOT_TOP_LEVEL' }
+      }
+    });
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/landmark-main-is-top-level-manual.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * @check landmark-main-is-top-level
+ * @atomic true
+ * @summary The main landmark must not be nested inside another landmark
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies whenever the page contains at least one main landmark
+ *   (explicit role="main", or an implicit <main> element).
+ * @expectation
+ *   No main landmark has an ancestor that is itself any landmark region.
+ *   A main region nested inside another landmark is not a top-level,
+ *   whole-page main content area and confuses landmark-based navigation
+ *   for assistive technology users.
+ * @implementation-notes
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule; see landmark-banner-is-top-level's
+ *   header comment for the shared rationale/precedent (this rule mirrors
+ *   its structure with main in place of banner/header).
+ */
+
+const id = 'landmark-main-is-top-level';
+
+const meta = {
+  title: 'Main landmark must be top-level',
+  description: 'Checks that the main landmark (role="main" or <main>) is not nested inside another landmark region.',
+  i18n: {
+    titleKey: 'landmarkMainIsTopLevel_title',
+    descriptionKey: 'landmarkMainIsTopLevel_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'landmarks', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  // Delegates to the shared helpers.getLandmarkNameInfo (aria-label -> aria-labelledby, via the
+  // target's own accessible name, not raw textContent -> title attribute fallback) rather than a
+  // local copy -- see that function's header comment in src/core/dom-helpers.js for the real bug
+  // (missing title fallback) this replaced across all 7 landmark rule files that had their own
+  // copy of this logic.
+  function getAccessibleLandmarkName(el) {
+    try {
+      if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
+        const info = helpers.getLandmarkNameInfo(el, ctx);
+        if (info && info.present && info.value) return normalizeWs(info.value);
+      }
+    } catch {}
+    return '';
+  }
+
+  function getExplicitRoleToken(el) {
+    const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
+    if (!raw) return '';
+    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;
+  }
+
+  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 === 'main') return 'main';
+    if (tag === 'nav') return 'navigation';
+    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
+    if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
+    return '';
+  }
+
+  const LANDMARK_ROLES = new Set(['banner', 'contentinfo', 'main', 'navigation', 'complementary', 'region', 'form', 'search']);
+
+  function getLandmarkRole(el) {
+    if (!el || !el.getAttribute) return '';
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) return LANDMARK_ROLES.has(explicit) ? explicit : '';
+    return getImplicitLandmarkRole(el);
+  }
+
+  function hasLandmarkAncestor(el) {
+    let p = el.parentElement;
+    while (p) {
+      if (getLandmarkRole(p)) return true;
+      p = p.parentElement;
+    }
+    return false;
+  }
+
+  // queryAllSmart (shadow-DOM-aware) instead of plain document.querySelectorAll -- see
+  // landmark-unique-manual.js's header comment for the real page (Airtable, 2026-07-23)
+  // that surfaced this gap: a third-party shadow-DOM-hosted widget's own landmark is
+  // invisible to a light-DOM-only query.
+  let nodes = [];
+  try {
+    nodes = helpers && typeof helpers.queryAllSmart === 'function'
+      ? helpers.queryAllSmart('header, footer, main, nav, aside, section, form, [role]')
+      : document.querySelectorAll('header, footer, main, nav, aside, section, form, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const mains = [];
+  const seen = new Set();
+  for (const el of nodes) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    if (getLandmarkRole(el) === 'main') mains.push(el);
+  }
+
+  if (mains.length === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  for (const el of mains) {
+    if (!hasLandmarkAncestor(el)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This main landmark is nested inside another landmark region.',
+      hint: 'Move the main landmark (<main>/role="main") so it is not contained by another landmark; main should be a top-level region of the page.',
+      i18n: {
+        summaryKey: 'landmarkMainIsTopLevel_summary_cantTell',
+        hintKey: 'landmarkMainIsTopLevel_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'LANDMARK_MAIN_NOT_TOP_LEVEL' }
+      }
+    });
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };