aria-ease 6.8.0 → 6.9.1

package/dist/src/utils/test/{chunk-2TOYEY5L.js → chunk-XERMSYEH.js}

@@ -32,11 +32,13 @@ var ContractReporter = class {
   skipped = 0;
   warnings = 0;
   isPlaywright = false;
+  isCustomContract = false;
   apgUrl = "https://www.w3.org/WAI/ARIA/apg/";
   hasPrintedStaticSection = false;
   hasPrintedDynamicSection = false;
-  constructor(isPlaywright = false) {
+  constructor(isPlaywright = false, isCustomContract = false) {
     this.isPlaywright = isPlaywright;
+    this.isCustomContract = isCustomContract;
   }
   log(message) {
     process.stderr.write(message + "\n");
@@ -197,6 +199,13 @@ ${"\u2500".repeat(60)}`);
     const totalPasses = this.staticPasses + dynamicPasses;
     const totalFailures = this.staticFailures + dynamicFailures;
     const totalRun = totalPasses + totalFailures + this.warnings;
+    const getComponentMessage = () => {
+      const componentDisplayName = `${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)}`;
+      if (this.isCustomContract) {
+        return `${componentDisplayName} component validates against your custom accessibility policy \u2713`;
+      }
+      return `${componentDisplayName} component meets Aria-Ease baseline WAI-ARIA expectations \u2713`;
+    };
     if (failures.length > 0) {
       this.reportFailures(failures);
     }
@@ -208,7 +217,7 @@ ${"\u2550".repeat(60)}`);
 `);
     if (totalFailures === 0 && this.skipped === 0 && this.warnings === 0) {
       this.log(`\u2705 All ${totalRun} tests passed!`);
-      this.log(`   ${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)} component meets WAI-ARIA expectations for Roles, States, Properties, and Keyboard Interactions \u2713`);
+      this.log(`   ${getComponentMessage()}`);
     } else if (totalFailures === 0) {
       this.log(`\u2705 ${totalPasses}/${totalRun} tests passed`);
       if (this.skipped > 0) {
@@ -217,7 +226,7 @@ ${"\u2550".repeat(60)}`);
       if (this.warnings > 0) {
         this.log(`\u26A0\uFE0F ${this.warnings} warning${this.warnings > 1 ? "s" : ""}`);
       }
-      this.log(`   ${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)} component meets WAI-ARIA expectations for Roles, States, Properties, and Keyboard Interactions \u2713`);
+      this.log(`   ${getComponentMessage()}`);
     } else {
       this.log(`\u274C ${totalFailures} test${totalFailures > 1 ? "s" : ""} failed`);
       this.log(`\u2705 ${totalPasses} test${totalPasses > 1 ? "s" : ""} passed`);

package/dist/src/utils/test/{configLoader-LD4RV2WQ.js → configLoader-YE2CYGDG.js}

@@ -55,6 +55,9 @@ function validateConfig(config) {
               if (comp.path !== void 0 && typeof comp.path !== "string") {
                 errors.push(`test.components[${idx}].path must be a string when provided`);
               }
+              if (comp.strategyPath !== void 0 && typeof comp.strategyPath !== "string") {
+                errors.push(`test.components[${idx}].strategyPath must be a string when provided`);
+              }
               if (comp.strictness !== void 0 && !["minimal", "balanced", "strict", "paranoid"].includes(comp.strictness)) {
                 errors.push(`test.components[${idx}].strictness must be one of: minimal, balanced, strict, paranoid`);
               }
@@ -69,6 +72,24 @@ function validateConfig(config) {
       }
     }
   }
+  if (cfg.contracts !== void 0) {
+    if (!Array.isArray(cfg.contracts)) {
+      errors.push("contracts must be an array");
+    } else {
+      cfg.contracts.forEach((contract, idx) => {
+        if (typeof contract !== "object" || contract === null) {
+          errors.push(`contracts[${idx}] must be an object`);
+        } else {
+          if (typeof contract.src !== "string") {
+            errors.push(`contracts[${idx}].src is required and must be a string`);
+          }
+          if (contract.out !== void 0 && typeof contract.out !== "string") {
+            errors.push(`contracts[${idx}].out must be a string`);
+          }
+        }
+      });
+    }
+  }
   return { valid: errors.length === 0, errors };
 }
 async function loadConfigFile(filePath) {

package/dist/src/utils/test/{contractTestRunnerPlaywright-IRJOAEMT.js → contractTestRunnerPlaywright-LC5OAVXB.js}

@@ -1,220 +1,158 @@
-import { ContractReporter, normalizeStrictness, contract_default, createTestPage, normalizeLevel, resolveEnforcement } from './chunk-2TOYEY5L.js';
+import { contract_default, ContractReporter, normalizeStrictness, createTestPage, normalizeLevel, resolveEnforcement } from './chunk-XERMSYEH.js';
 import { readFileSync } from 'fs';
+import path2 from 'path';
+import { pathToFileURL } from 'url';
 import { expect } from '@playwright/test';
 
-var ComboboxComponentStrategy = class {
-  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
-    this.mainSelector = mainSelector;
-    this.selectors = selectors;
-    this.actionTimeoutMs = actionTimeoutMs;
-    this.assertionTimeoutMs = assertionTimeoutMs;
-  }
-  async resetState(page) {
-    if (!this.selectors.popup) return;
-    const popupSelector = this.selectors.popup;
-    const popupElement = page.locator(popupSelector).first();
-    const isPopupVisible = await popupElement.isVisible().catch(() => false);
-    if (!isPopupVisible) return;
-    let menuClosed = false;
-    let closeSelector = this.selectors.input;
-    if (!closeSelector && this.selectors.focusable) {
-      closeSelector = this.selectors.focusable;
-    } else if (!closeSelector) {
-      closeSelector = this.selectors.trigger;
-    }
-    if (closeSelector) {
-      const closeElement = page.locator(closeSelector).first();
-      await closeElement.focus();
-      await page.keyboard.press("Escape");
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed && this.selectors.trigger) {
-      const triggerElement = page.locator(this.selectors.trigger).first();
-      await triggerElement.click({ timeout: this.actionTimeoutMs });
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed) {
-      await page.mouse.click(10, 10);
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed) {
-      throw new Error(
-        `\u274C FATAL: Cannot close combobox popup between tests. Popup remains visible after trying:
-  1. Escape key
-  2. Clicking trigger
-  3. Clicking outside
-This indicates a problem with the combobox component's close functionality.`
-      );
-    }
-    if (this.selectors.input) {
-      await page.locator(this.selectors.input).first().clear();
-    }
-  }
-  async shouldSkipTest() {
-    return false;
+var StrategyRegistry = class {
+  builtInStrategies = /* @__PURE__ */ new Map();
+  constructor() {
+    this.registerBuiltInStrategies();
   }
-  getMainSelector() {
-    return this.mainSelector;
-  }
-};
-var AccordionComponentStrategy = class {
-  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
-    this.mainSelector = mainSelector;
-    this.selectors = selectors;
-    this.actionTimeoutMs = actionTimeoutMs;
-    this.assertionTimeoutMs = assertionTimeoutMs;
+  /**
+   * Register built-in strategies
+   */
+  registerBuiltInStrategies() {
+    this.builtInStrategies.set(
+      "menu",
+      () => import('./MenuComponentStrategy-VKZQYLBE.js').then(
+        (m) => m.MenuComponentStrategy
+      )
+    );
+    this.builtInStrategies.set(
+      "accordion",
+      () => import('./AccordionComponentStrategy-WRHZOEN6.js').then(
+        (m) => m.AccordionComponentStrategy
+      )
+    );
+    this.builtInStrategies.set(
+      "combobox",
+      () => import('./ComboboxComponentStrategy-5AECQSRN.js').then(
+        (m) => m.ComboboxComponentStrategy
+      )
+    );
+    this.builtInStrategies.set(
+      "tabs",
+      () => import('./TabsComponentStrategy-BKG53SEV.js').then(
+        (m) => m.TabsComponentStrategy
+      )
+    );
+    this.builtInStrategies.set(
+      "combobox.listbox",
+      () => import('./ComboboxComponentStrategy-5AECQSRN.js').then(
+        (m) => m.ComboboxComponentStrategy
+      )
+    );
   }
-  async resetState(page) {
-    if (!this.selectors.panel || !this.selectors.trigger || this.selectors.popup) {
-      return;
-    }
-    const triggerSelector = this.selectors.trigger;
-    const panelSelector = this.selectors.panel;
-    if (!triggerSelector || !panelSelector) return;
-    const allTriggers = await page.locator(triggerSelector).all();
-    for (const trigger of allTriggers) {
-      const isExpanded = await trigger.getAttribute("aria-expanded") === "true";
-      const triggerPanel = await trigger.getAttribute("aria-controls");
-      if (isExpanded && triggerPanel) {
-        await trigger.click({ timeout: this.actionTimeoutMs });
-        const panel = page.locator(`#${triggerPanel}`);
-        await expect(panel).toBeHidden({ timeout: this.assertionTimeoutMs }).catch(() => {
-        });
+  /**
+   * Load a strategy - either from custom path or built-in registry
+   * @param componentName - Component name (e.g., "menu", "accordion")
+   * @param customStrategyPath - Optional custom strategy file path
+   * @returns Strategy constructor function or null if not found
+   */
+  async loadStrategy(componentName, customStrategyPath, configBaseDir) {
+    try {
+      if (customStrategyPath) {
+        try {
+          const resolvedCustomPath = path2.isAbsolute(customStrategyPath) ? customStrategyPath : path2.resolve(configBaseDir || process.cwd(), customStrategyPath);
+          const customModule = await import(pathToFileURL(resolvedCustomPath).href);
+          const strategy = customModule.default || customModule;
+          if (!strategy) {
+            throw new Error(`No default export found in ${customStrategyPath}`);
+          }
+          return strategy;
+        } catch (error) {
+          throw new Error(
+            `Failed to load custom strategy from ${customStrategyPath}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
       }
-    }
-  }
-  async shouldSkipTest() {
-    return false;
-  }
-  getMainSelector() {
-    return this.mainSelector;
-  }
-};
-var MenuComponentStrategy = class {
-  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
-    this.mainSelector = mainSelector;
-    this.selectors = selectors;
-    this.actionTimeoutMs = actionTimeoutMs;
-    this.assertionTimeoutMs = assertionTimeoutMs;
-  }
-  async resetState(page) {
-    if (!this.selectors.popup) return;
-    const popupSelector = this.selectors.popup;
-    const popupElement = page.locator(popupSelector).first();
-    const isPopupVisible = await popupElement.isVisible().catch(() => false);
-    if (!isPopupVisible) return;
-    let menuClosed = false;
-    let closeSelector = this.selectors.input;
-    if (!closeSelector && this.selectors.focusable) {
-      closeSelector = this.selectors.focusable;
-    } else if (!closeSelector) {
-      closeSelector = this.selectors.trigger;
-    }
-    if (closeSelector) {
-      const closeElement = page.locator(closeSelector).first();
-      await closeElement.focus();
-      await page.keyboard.press("Escape");
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed && this.selectors.trigger) {
-      const triggerElement = page.locator(this.selectors.trigger).first();
-      await triggerElement.click({ timeout: this.actionTimeoutMs });
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed) {
-      await page.mouse.click(10, 10);
-      menuClosed = await expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
-    }
-    if (!menuClosed) {
+      const builtInLoader = this.builtInStrategies.get(componentName);
+      if (!builtInLoader) {
+        return null;
+      }
+      return builtInLoader();
+    } catch (error) {
       throw new Error(
-        `\u274C FATAL: Cannot close menu between tests. Menu remains visible after trying:
-  1. Escape key
-  2. Clicking trigger
-  3. Clicking outside
-This indicates a problem with the menu component's close functionality.`
+        `Strategy loading failed for ${componentName}: ${error instanceof Error ? error.message : String(error)}`
       );
     }
-    if (this.selectors.input) {
-      await page.locator(this.selectors.input).first().clear();
-    }
-    if (this.selectors.trigger) {
-      const triggerElement = page.locator(this.selectors.trigger).first();
-      await triggerElement.focus();
-    }
   }
-  async shouldSkipTest(test, page) {
-    const requiresSubmenu = test.action.some(
-      (act) => act.target === "submenu" || act.target === "submenuTrigger" || act.target === "submenuItems"
-    ) || test.assertions.some(
-      (assertion) => assertion.target === "submenu" || assertion.target === "submenuTrigger" || assertion.target === "submenuItems"
-    );
-    if (!requiresSubmenu) {
-      return false;
-    }
-    const submenuTriggerSelector = this.selectors.submenuTrigger;
-    if (!submenuTriggerSelector) {
-      return true;
-    }
-    const submenuTriggerCount = await page.locator(submenuTriggerSelector).count();
-    return submenuTriggerCount === 0;
-  }
-  getMainSelector() {
-    return this.mainSelector;
+  /**
+   * Check if a strategy exists (either built-in or custom path provided)
+   */
+  has(componentName, customStrategyPath) {
+    return !!customStrategyPath || this.builtInStrategies.has(componentName);
   }
 };
 
-// src/utils/test/src/component-strategies/TabsComponentStrategy.ts
-var TabsComponentStrategy = class {
-  constructor(mainSelector, selectors) {
-    this.mainSelector = mainSelector;
-    this.selectors = selectors;
-  }
-  async resetState() {
+// src/utils/test/src/ComponentDetector.ts
+var ComponentDetector = class {
+  static strategyRegistry = new StrategyRegistry();
+  static isComponentConfig(value) {
+    return typeof value === "object" && value !== null;
   }
-  async shouldSkipTest(test, page) {
-    if (test.isVertical !== void 0 && this.selectors.tablist) {
-      const tablistSelector = this.selectors.tablist;
-      const tablist = page.locator(tablistSelector).first();
-      const orientation = await tablist.getAttribute("aria-orientation");
-      const isVertical = orientation === "vertical";
-      if (test.isVertical !== isVertical) {
-        return true;
-      }
+  /**
+   * Detect and instantiate a component strategy
+   * Supports:
+   * - Built-in strategies (menu, accordion, combobox, tabs)
+   * - Custom strategies via config (strategyPath)
+   * - Custom contract paths via config (path)
+   * @param componentName - Component name
+   * @param componentConfig - Component config from ariaease.config.js
+   * @param actionTimeoutMs - Action timeout in milliseconds
+   * @param assertionTimeoutMs - Assertion timeout in milliseconds
+   * @returns Instantiated ComponentStrategy or null
+   */
+  static async detect(componentName, componentConfig, actionTimeoutMs = 400, assertionTimeoutMs = 400, configBaseDir) {
+    const typedComponentConfig = this.isComponentConfig(componentConfig) ? componentConfig : void 0;
+    let contractPath = typedComponentConfig?.path;
+    if (!contractPath) {
+      const contractTyped = contract_default;
+      contractPath = contractTyped[componentName]?.path;
     }
-    return false;
-  }
-  getMainSelector() {
-    return this.mainSelector;
-  }
-};
-var ComponentDetector = class {
-  static detect(componentName, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
-    const contractTyped = contract_default;
-    const contractPath = contractTyped[componentName]?.path;
     if (!contractPath) {
       throw new Error(`Contract path not found for component: ${componentName}`);
     }
-    const resolvedPath = new URL(contractPath, import.meta.url).pathname;
+    const resolvedPath = (() => {
+      if (path2.isAbsolute(contractPath)) return contractPath;
+      if (configBaseDir) {
+        const configResolved = path2.resolve(configBaseDir, contractPath);
+        try {
+          readFileSync(configResolved, "utf-8");
+          return configResolved;
+        } catch {
+        }
+      }
+      const cwdResolved = path2.resolve(process.cwd(), contractPath);
+      try {
+        readFileSync(cwdResolved, "utf-8");
+        return cwdResolved;
+      } catch {
+        return new URL(contractPath, import.meta.url).pathname;
+      }
+    })();
     const contractData = readFileSync(resolvedPath, "utf-8");
     const componentContract = JSON.parse(contractData);
     const selectors = componentContract.selectors;
-    if (componentName.includes("combobox")) {
-      const mainSelector = selectors.input || selectors.container;
-      return new ComboboxComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
-    }
-    if (componentName === "accordion") {
-      const mainSelector = selectors.trigger || selectors.container;
-      return new AccordionComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
-    }
-    if (componentName === "menu") {
-      const mainSelector = selectors.trigger || selectors.container;
-      return new MenuComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
+    const strategyClass = await this.strategyRegistry.loadStrategy(
+      componentName,
+      typedComponentConfig?.strategyPath,
+      configBaseDir
+    );
+    if (!strategyClass) {
+      return null;
     }
+    const mainSelector = selectors.trigger || selectors.input || selectors.tablist || selectors.container;
     if (componentName === "tabs") {
-      const mainSelector = selectors.tablist || selectors.tab;
-      return new TabsComponentStrategy(mainSelector, selectors);
+      return new strategyClass(mainSelector, selectors);
     }
-    return null;
+    return new strategyClass(
+      mainSelector,
+      selectors,
+      actionTimeoutMs,
+      assertionTimeoutMs
+    );
   }
 };
 
@@ -696,17 +634,42 @@ var AssertionRunner = class {
 };
 
 // src/utils/test/src/contractTestRunnerPlaywright.ts
-async function runContractTestsPlaywright(componentName, url, strictness) {
-  const reporter = new ContractReporter(true);
+async function runContractTestsPlaywright(componentName, url, strictness, config, configBaseDir) {
+  const componentConfig = config?.test?.components?.find((c) => c.name === componentName);
+  const isCustomContract = !!componentConfig?.path;
+  const reporter = new ContractReporter(true, isCustomContract);
   const actionTimeoutMs = 400;
   const assertionTimeoutMs = 400;
   const strictnessMode = normalizeStrictness(strictness);
-  const contractTyped = contract_default;
-  const contractPath = contractTyped[componentName]?.path;
-  const resolvedPath = new URL(contractPath, import.meta.url).pathname;
+  let contractPath = componentConfig?.path;
+  if (!contractPath) {
+    const contractTyped = contract_default;
+    contractPath = contractTyped[componentName]?.path;
+  }
+  if (!contractPath) {
+    throw new Error(`Contract path not found for component: ${componentName}`);
+  }
+  const resolvedPath = (() => {
+    if (path2.isAbsolute(contractPath)) return contractPath;
+    if (configBaseDir) {
+      const configResolved = path2.resolve(configBaseDir, contractPath);
+      try {
+        readFileSync(configResolved, "utf-8");
+        return configResolved;
+      } catch {
+      }
+    }
+    const cwdResolved = path2.resolve(process.cwd(), contractPath);
+    try {
+      readFileSync(cwdResolved, "utf-8");
+      return cwdResolved;
+    } catch {
+      return new URL(contractPath, import.meta.url).pathname;
+    }
+  })();
   const contractData = readFileSync(resolvedPath, "utf-8");
   const componentContract = JSON.parse(contractData);
-  const totalTests = componentContract.static[0].assertions.length + componentContract.dynamic.length;
+  const totalTests = (componentContract.relationships?.length || 0) + (componentContract.static[0]?.assertions.length || 0) + componentContract.dynamic.length;
   const apgUrl = componentContract.meta?.source?.apg;
   const failures = [];
   const warnings = [];
@@ -743,7 +706,7 @@ async function runContractTestsPlaywright(componentName, url, strictness) {
       }
       await page.addStyleTag({ content: `* { transition: none !important; animation: none !important; }` });
     }
-    const strategy = ComponentDetector.detect(componentName, actionTimeoutMs, assertionTimeoutMs);
+    const strategy = await ComponentDetector.detect(componentName, componentConfig, actionTimeoutMs, assertionTimeoutMs, configBaseDir);
     if (!strategy) {
       throw new Error(`Unsupported component: ${componentName}`);
     }
@@ -776,6 +739,105 @@ This usually means:
     let staticPassed = 0;
     let staticFailed = 0;
     let staticWarnings = 0;
+    for (const rel of componentContract.relationships || []) {
+      const relationshipLevel = normalizeLevel(rel.level);
+      if (rel.type === "aria-reference") {
+        const relDescription = `${rel.from}.${rel.attribute} references ${rel.to}`;
+        const fromSelector = componentContract.selectors[rel.from];
+        const toSelector = componentContract.selectors[rel.to];
+        if (!fromSelector || !toSelector) {
+          const outcome = classifyFailure(
+            `Relationship selector missing: from="${rel.from}" or to="${rel.to}" not found in selectors.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const fromTarget = page.locator(fromSelector).first();
+        const toTarget = page.locator(toSelector).first();
+        const fromExists = await fromTarget.count() > 0;
+        const toExists = await toTarget.count() > 0;
+        if (!fromExists || !toExists) {
+          const outcome = classifyFailure(
+            `Relationship target not found: ${!fromExists ? rel.from : rel.to}.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const attrValue = await fromTarget.getAttribute(rel.attribute);
+        const toId = await toTarget.getAttribute("id");
+        if (!toId) {
+          const outcome = classifyFailure(
+            `Relationship target "${rel.to}" must have an id for ${rel.attribute} validation.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const references = (attrValue || "").split(/\s+/).filter(Boolean);
+        const matches = references.includes(toId);
+        if (!matches) {
+          const outcome = classifyFailure(
+            `Expected ${rel.from} ${rel.attribute} to reference id "${toId}", found "${attrValue || ""}".`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        passes.push(`Relationship valid: ${rel.from}.${rel.attribute} -> ${rel.to} (id=${toId}).`);
+        staticPassed += 1;
+        reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+        continue;
+      }
+      if (rel.type === "contains") {
+        const relDescription = `${rel.parent} contains ${rel.child}`;
+        const parentSelector = componentContract.selectors[rel.parent];
+        const childSelector = componentContract.selectors[rel.child];
+        if (!parentSelector || !childSelector) {
+          const outcome = classifyFailure(
+            `Relationship selector missing: parent="${rel.parent}" or child="${rel.child}" not found in selectors.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const parent = page.locator(parentSelector).first();
+        const parentExists = await parent.count() > 0;
+        if (!parentExists) {
+          const outcome = classifyFailure(`Relationship parent target not found: ${rel.parent}.`, rel.level);
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const descendants = parent.locator(childSelector);
+        const descendantCount = await descendants.count();
+        if (descendantCount < 1) {
+          const outcome = classifyFailure(
+            `Expected ${rel.parent} to contain descendant matching selector for ${rel.child}.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        passes.push(`Relationship valid: ${rel.parent} contains ${rel.child}.`);
+        staticPassed += 1;
+        reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+      }
+    }
     const staticAssertionRunner = new AssertionRunner(page, componentContract.selectors, assertionTimeoutMs);
     for (const test of componentContract.static[0]?.assertions || []) {
       if (test.target === "relative") continue;