@markuplint/rules 5.0.1 → 5.1.1

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.1.1](https://github.com/markuplint/markuplint/compare/v5.1.0...v5.1.1) (2026-10-09)
+
+### Bug Fixes
+
+- **rules:** check pretenders against content models that include #custom ([d70aa26](https://github.com/markuplint/markuplint/commit/d70aa2666c2318daaab4585aed62db00e5fd9a45))
+
+# [5.1.0](https://github.com/markuplint/markuplint/compare/v5.0.1...v5.1.0) (2026-10-08)
+
+### Bug Fixes
+
+- **rules:** count owned elements rendered by a pretended component in require-owned-elements ([87ae63d](https://github.com/markuplint/markuplint/commit/87ae63d65196829c3908f4c3c74ceffb2fedc60d)), closes [#4068](https://github.com/markuplint/markuplint/issues/4068)
+- **rules:** hold permitted-contents condition cache weakly by specs ([9b3200e](https://github.com/markuplint/markuplint/commit/9b3200e49cab314f978b8753c56463a2025d8bd0))
+- **rules:** skip require-accessible-name when unknown pretender content may be the name ([f82b254](https://github.com/markuplint/markuplint/commit/f82b25451f4e1f1da67a568444fce9d51709378e)), closes [#4069](https://github.com/markuplint/markuplint/issues/4069)
+
+### Features
+
+- **rules:** evaluate pretender slot content in permitted-contents ([1da4b30](https://github.com/markuplint/markuplint/commit/1da4b30d7997ee6e1e7500e3b6602c46ea576548)), closes [#4054](https://github.com/markuplint/markuplint/issues/4054)
+
 ## [5.0.1](https://github.com/markuplint/markuplint/compare/v5.0.0...v5.0.1) (2026-09-22)
 
 ### Bug Fixes

package/lib/helpers.d.ts

@@ -30,6 +30,18 @@ export declare function match(needle: string, pattern: string): boolean;
 export declare const rePCENChar: string;
 export declare function toNormalizedValue(value: string, spec: Attribute): string;
 export declare function accnameMayBeMutable(el: Element<any, any>, document: Document<any, any>): boolean;
+/**
+ * Whether the accessible name of `el` may be rendered by content the pretender
+ * does not know: an unknown entry (`{ dynamic: true }`) in the `contents` of
+ * `el`, of a pretended descendant among the children the name computation
+ * traverses, of an element `aria-labelledby` refers to, or of the owned label.
+ *
+ * Not folded into {@link accnameMayBeMutable}: a component with an unknown
+ * entry and a static name (`aria-label`, static text) is still decidable and
+ * must stay checked (and reported as redundant by `no-redundant-accessible-name`).
+ * Call it only once the static name has been computed and found empty.
+ */
+export declare function accnameMayComeFromUnknownContent(el: Element<any, any>, document: Document<any, any>): boolean;
 export declare const labelable: string[];
 export declare function getOwnedLabel<V extends RuleConfigValue, O extends PlainData>(el: Element<V, O>, document: Document<V, O>): Element<V, O> | null;
 /** `null`/`undefined` items are silently dropped on add. */

package/lib/helpers.js

@@ -1,3 +1,4 @@
+import { escapeCSS } from '@markuplint/ml-spec';
 /** A `null`/`undefined` condition means the attribute applies unconditionally. */
 export function attrMatches(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -119,6 +120,59 @@ document) {
     }
     return false;
 }
+/**
+ * Whether the accessible name of `el` may be rendered by content the pretender
+ * does not know: an unknown entry (`{ dynamic: true }`) in the `contents` of
+ * `el`, of a pretended descendant among the children the name computation
+ * traverses, of an element `aria-labelledby` refers to, or of the owned label.
+ *
+ * Not folded into {@link accnameMayBeMutable}: a component with an unknown
+ * entry and a static name (`aria-label`, static text) is still decidable and
+ * must stay checked (and reported as redundant by `no-redundant-accessible-name`).
+ * Call it only once the static name has been computed and found empty.
+ */
+export function accnameMayComeFromUnknownContent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+document) {
+    if (hasUnknownContent(el)) {
+        return true;
+    }
+    const labelledby = el.getAttribute('aria-labelledby');
+    if (labelledby) {
+        const referenced = labelledby
+            .trim()
+            .split(/\s+/)
+            .map(id => document.querySelector(`#${escapeCSS(id)}`));
+        if (referenced.some(target => target && hasUnknownContent(target))) {
+            return true;
+        }
+    }
+    const ownedLabel = getOwnedLabel(el, document);
+    return !!ownedLabel && hasUnknownContent(ownedLabel);
+}
+/**
+ * Walks the same children the accname resolver of `@markuplint/ml-core` does:
+ * for a pretended element, the children the component renders (`as.childNodes`,
+ * placed into `contents`), so that a nested component contributes its own
+ * `contents`; otherwise the children as written. A hidden child is skipped
+ * because the name computation never reads it (`isHidden` in that resolver).
+ */
+function hasUnknownContent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    const context = el.pretenderContext;
+    if (context?.type === 'pretender' && context.slotContent?.mutable) {
+        return true;
+    }
+    const given = context?.type === 'pretender' ? [...context.as.childNodes] : [...el.childNodes];
+    const children = context?.type === 'pretender' && context.slotContent ? context.slotContent.fill(given) : given;
+    return children.some(child => child.is(child.ELEMENT_NODE) &&
+        child.getAttribute('aria-hidden') !== 'true' &&
+        !child.hasAttribute('hidden') &&
+        hasUnknownContent(child));
+}
 export const labelable = ['button', 'input:not([type=hidden])', 'meter', 'output', 'progress', 'select', 'textarea'];
 export function getOwnedLabel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/permitted-contents/content-model.js

@@ -1,4 +1,5 @@
 import { getContentModel } from '@markuplint/ml-spec';
+import { getContentOwner, getSlotContent } from './slot-content.js';
 import { start } from './start.js';
 /**
  * Top-level entry point for content model validation of a single element.
@@ -17,7 +18,19 @@ import { start } from './start.js';
 export function contentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules, options, mode) {
-    const { model, specs } = createModel(el, rules, mode);
+    const slotContent = getSlotContent(el, mode);
+    if (slotContent && !slotContent.wrapper) {
+        // Several slot wrappers: which one a given child belongs to is unknown.
+        return [
+            {
+                type: 'MATCHED',
+                scope: el,
+                query: '*',
+                hint: {},
+            },
+        ];
+    }
+    const { model, specs } = createModel(getContentOwner(el, mode), rules, mode);
     if (model == null) {
         return [
             {

package/lib/permitted-contents/index.js

@@ -2,6 +2,7 @@ import { createRule } from '@markuplint/ml-core';
 import { contentModel } from './content-model.js';
 import meta from './meta.js';
 import { transparentMode } from './represent-transparent-nodes.js';
+import { getContentOwner, getReportScope, isContentMutable } from './slot-content.js';
 export default createRule({
     meta: meta,
     defaultValue: [],
@@ -37,7 +38,9 @@ export default createRule({
                         }
                         case 'MISSING_NODE_ONE_OR_MORE': {
                             if (scope.rule.options.ignoreHasMutableChildren &&
-                                (!scope.is(scope.ELEMENT_NODE) || scope.hasMutableChildren())) {
+                                (!scope.is(scope.ELEMENT_NODE) ||
+                                    scope.hasMutableChildren() ||
+                                    isContentMutable(el, mode))) {
                                 break;
                             }
                             message =
@@ -55,7 +58,9 @@ export default createRule({
                         }
                         case 'MISSING_NODE_REQUIRED': {
                             if (scope.rule.options.ignoreHasMutableChildren &&
-                                (!scope.is(scope.ELEMENT_NODE) || scope.hasMutableChildren())) {
+                                (!scope.is(scope.ELEMENT_NODE) ||
+                                    scope.hasMutableChildren() ||
+                                    isContentMutable(el, mode))) {
                                 break;
                             }
                             message =
@@ -76,10 +81,10 @@ export default createRule({
                             message =
                                 message ||
                                     (transparentMode.has(scope)
-                                        ? t('{0} is not allowed in {1} through the transparent model in this context', name(not, t, mode), name(el, t, mode))
-                                        : t('{0} is not allowed in {1} in this context', name(not, t, mode), name(el, t, mode)));
+                                        ? t('{0} is not allowed in {1} through the transparent model in this context', name(not, t, mode), name(getContentOwner(el, mode), t, mode))
+                                        : t('{0} is not allowed in {1} in this context', name(not, t, mode), name(getContentOwner(el, mode), t, mode)));
                             report({
-                                scope: not,
+                                scope: getReportScope(not),
                                 message,
                             });
                             break;
@@ -88,7 +93,7 @@ export default createRule({
                             const not = hint.not ?? scope;
                             const tp = hint.transparent ?? el;
                             report({
-                                scope: not,
+                                scope: getReportScope(not),
                                 message: t('{0} is {1} but {2}', name(tp, t, mode), t('a {0}', 'transparent model'), t('also disallows {0} in this context', name(not, t, mode))),
                             });
                             break;

package/lib/permitted-contents/matches-selector.js

@@ -109,7 +109,7 @@ childNode, specs, depth, mode) {
         };
     }
     if (childNode.is(childNode.ELEMENT_NODE)) {
-        if (childNode.elementType !== 'html' && hasCustom) {
+        if (hasCustom && isTreatedAsCustom(childNode, mode)) {
             nodeLog('%s.matches(%s) => CustomElement', childNode.raw, query);
             return {
                 type: 'MATCHED',
@@ -164,6 +164,34 @@ childNode, specs, depth, mode) {
         hint: {},
     };
 }
+/**
+ * Whether an element is accepted by the `#custom` entry of a content model
+ * category without being checked against that category's tag list.
+ *
+ * `elementType` comes from the parser and does not change when the element is
+ * pretended, so a component that stands for `<section>` would still look
+ * authored and slip through `<p>`, `<span>` and `<button>`. In `'pretended'`
+ * mode such an element is judged by what it stands for instead, exactly as if
+ * the user had written that element. The pretender target is always created
+ * with `elementType: 'html'`, so a target that is itself a custom element
+ * (its name contains a hyphen) is recognised by name.
+ *
+ * In `'origin'` mode the pretender context is suppressed while matching (see
+ * {@link matches}) and the element is seen under its authored name, so it stays
+ * accepted as a custom element.
+ */
+function isTreatedAsCustom(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+element, mode) {
+    if (element.elementType === 'html') {
+        return false;
+    }
+    const pretenderContext = element.pretenderContext;
+    if (mode === 'pretended' && pretenderContext?.type === 'pretender') {
+        return pretenderContext.as.localName.includes('-');
+    }
+    return true;
+}
 /**
  * Pre-computed conditions for well-known queries that do not depend on specs.
  */
@@ -190,8 +218,12 @@ const conditionWithoutSpecs = {
 /**
  * Cache of parsed conditions keyed by specs instance and query string.
  * Prevents redundant category expansion for the same query across multiple elements.
+ *
+ * Weakly keyed because each parsed document builds its own specs object: a
+ * strong map would gain one entry per parse and never release it, growing
+ * without bound in long-lived processes (language server, watch mode).
  */
-const optConditionSpecsBaseCaches = new Map();
+const optConditionSpecsBaseCaches = new WeakMap();
 /**
  * Parses a content model query string into a Condition object by expanding
  * content model category references (e.g., `#phrasing`, `:model(flow)`) into

package/lib/permitted-contents/represent-transparent-nodes.js

@@ -1,6 +1,7 @@
 import { resolveContentModel } from './content-model.js';
 import { cmLog } from './debug.js';
 import { order } from './order.js';
+import { expandChildren, getContentOwner, getSlotContent } from './slot-content.js';
 import { Collection, isTransparent, matches } from './utils.js';
 /**
  * A map tracking child nodes that are currently being evaluated through
@@ -96,6 +97,16 @@ childNodes, rules, specs, options, mode) {
             }
             continue;
         }
+        // A component whose children sit inside an inner wrapper element (or one of
+        // several) cannot be looked through as transparent content: the children
+        // belong to the wrapper, not to the outermost element that is being matched.
+        const childSlot = getSlotContent(childNode, mode);
+        if (childSlot && (!childSlot.wrapper || getContentOwner(childNode, mode) !== childNode)) {
+            for (const p of patterns) {
+                p.push(childNode);
+            }
+            continue;
+        }
         const models = resolveContentModel(childNode, rules, specs, mode);
         if (models == null || typeof models === 'boolean') {
             for (const p of patterns) {
@@ -111,8 +122,10 @@ childNodes, rules, specs, options, mode) {
             continue;
         }
         const childNodesPatterns = options.evaluateConditionalChildNodes
-            ? childNode.conditionalChildNodes().map(childNodes => [...childNodes])
-            : [[...childNode.childNodes].filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace()))];
+            ? childNode.conditionalChildNodes().map(childNodes => [...expandChildren(childNode, [...childNodes], mode)])
+            : [
+                [...expandChildren(childNode, [...childNode.childNodes], mode)].filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace())),
+            ];
         const branchGroups = [];
         for (const branchChildNodes of childNodesPatterns) {
             const collection = new Collection([...branchChildNodes]);

package/lib/permitted-contents/slot-content.d.ts

@@ -0,0 +1,40 @@
+import type { Mode } from './types.js';
+import type { PlainData } from '@markuplint/ml-config';
+import type { ChildNode, Element, PretenderSlotContent, RuleConfigValue } from '@markuplint/ml-core';
+/**
+ * Returns the slot-content description of a pretended component, which exists
+ * only in `'pretended'` mode: the `'origin'` mode evaluates user tag rules keyed
+ * on the component name against the children as written at the usage site.
+ *
+ * The helpers in this file are generic over the rule's value and options types
+ * because `require-owned-elements` shares them, so that both rules read a
+ * pretended component the same way.
+ *
+ * @see PretenderSlotContent in `@markuplint/ml-core`
+ */
+export declare function getSlotContent<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, mode: Mode): PretenderSlotContent<Element<T, O>, T, O> | null;
+/**
+ * The element whose content model governs the children of `el`.
+ * It is the slot wrapper element when the pretender declares exactly one, and
+ * `el` itself otherwise (including the outermost virtual element, which `el`
+ * already delegates its name and attributes to).
+ */
+export declare function getContentOwner<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, mode: Mode): Element<T, O>;
+/**
+ * The children of `el` to validate: the nodes given at the usage site, passed
+ * through the pretender's `contents` when it declares any, with the children of
+ * fragment pretenders (`element: '#fragment'`) expanded in place because such a
+ * component contributes its contents directly to its parent.
+ */
+export declare function expandChildren<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, given: readonly ChildNode<T, O>[], mode: Mode): readonly ChildNode<T, O>[];
+/**
+ * Whether a required child of `el` may be rendered by something the pretender
+ * does not know: an unknown entry in its own `contents`, or in the `contents` of
+ * a fragment pretender among its children (which stands in the parent).
+ */
+export declare function isContentMutable<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, mode: Mode): boolean;
+/**
+ * A violation on an element that only the pretender renders (`contents`) is reported
+ * on the component that renders it: the element does not exist in the source.
+ */
+export declare function getReportScope<T extends RuleConfigValue, O extends PlainData>(node: ChildNode<T, O>): ChildNode<T, O>;

package/lib/permitted-contents/slot-content.js

@@ -0,0 +1,87 @@
+/**
+ * Returns the slot-content description of a pretended component, which exists
+ * only in `'pretended'` mode: the `'origin'` mode evaluates user tag rules keyed
+ * on the component name against the children as written at the usage site.
+ *
+ * The helpers in this file are generic over the rule's value and options types
+ * because `require-owned-elements` shares them, so that both rules read a
+ * pretended component the same way.
+ *
+ * @see PretenderSlotContent in `@markuplint/ml-core`
+ */
+export function getSlotContent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, mode) {
+    if (mode !== 'pretended') {
+        return null;
+    }
+    const context = el.pretenderContext;
+    return context?.type === 'pretender' ? (context.slotContent ?? null) : null;
+}
+/**
+ * The element whose content model governs the children of `el`.
+ * It is the slot wrapper element when the pretender declares exactly one, and
+ * `el` itself otherwise (including the outermost virtual element, which `el`
+ * already delegates its name and attributes to).
+ */
+export function getContentOwner(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, mode) {
+    const wrapper = getSlotContent(el, mode)?.wrapper;
+    const context = el.pretenderContext;
+    if (wrapper && context?.type === 'pretender' && wrapper !== context.as) {
+        return wrapper;
+    }
+    return el;
+}
+/**
+ * The children of `el` to validate: the nodes given at the usage site, passed
+ * through the pretender's `contents` when it declares any, with the children of
+ * fragment pretenders (`element: '#fragment'`) expanded in place because such a
+ * component contributes its contents directly to its parent.
+ */
+export function expandChildren(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, given, mode) {
+    const slotContent = getSlotContent(el, mode);
+    const children = slotContent ? slotContent.fill(given) : given;
+    return children.flatMap(child => expandFragment(child, mode));
+}
+/**
+ * Whether a required child of `el` may be rendered by something the pretender
+ * does not know: an unknown entry in its own `contents`, or in the `contents` of
+ * a fragment pretender among its children (which stands in the parent).
+ */
+export function isContentMutable(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, mode) {
+    if (getSlotContent(el, mode)?.mutable) {
+        return true;
+    }
+    return [...el.childNodes].some(child => isFragmentPretender(child, mode) && isContentMutable(child, mode));
+}
+function isFragmentPretender(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node, mode) {
+    return (mode === 'pretended' &&
+        node.is(node.ELEMENT_NODE) &&
+        node.pretenderContext?.type === 'pretender' &&
+        node.localName === '#fragment');
+}
+function expandFragment(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node, mode) {
+    return isFragmentPretender(node, mode) ? expandChildren(node, [...node.childNodes], mode) : [node];
+}
+/**
+ * A violation on an element that only the pretender renders (`contents`) is reported
+ * on the component that renders it: the element does not exist in the source.
+ */
+export function getReportScope(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node) {
+    if (node.is(node.ELEMENT_NODE) && node.pretenderContext?.type === 'origin') {
+        return node.pretenderContext.origin;
+    }
+    return node;
+}

package/lib/permitted-contents/start.js

@@ -1,5 +1,6 @@
 import { order } from './order.js';
 import { representTransparentNodes } from './represent-transparent-nodes.js';
+import { expandChildren } from './slot-content.js';
 /**
  * Entry point for validating an element's child nodes against a content model definition.
  * Handles the three forms of content model: `false` (no content allowed), `true` (any content
@@ -18,9 +19,15 @@ import { representTransparentNodes } from './represent-transparent-nodes.js';
 export function start(contents, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules, specs, options, mode) {
-    const childNodesPatterns = options.evaluateConditionalChildNodes
+    const givenPatterns = options.evaluateConditionalChildNodes
         ? el.conditionalChildNodes().map(childNodes => [...childNodes])
-        : [[...el.childNodes].filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace()))];
+        : [[...el.childNodes]];
+    const childNodesPatterns = givenPatterns.map(given => {
+        const children = expandChildren(el, given, mode);
+        return options.evaluateConditionalChildNodes
+            ? [...children]
+            : children.filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace()));
+    });
     return childNodesPatterns.flatMap(childNodes => {
         if (contents === false) {
             if (childNodes.length > 0) {

package/lib/require-accessible-name/index.js

@@ -1,6 +1,6 @@
 import { createRule, getRoleSpec, getComputedRole } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION, isExposed } from '@markuplint/ml-spec';
-import { accnameMayBeMutable } from '../helpers.js';
+import { accnameMayBeMutable, accnameMayComeFromUnknownContent } from '../helpers.js';
 import meta from './meta.js';
 export default createRule({
     meta: meta,
@@ -25,9 +25,14 @@ export default createRule({
                 return;
             }
             const hasAccessibleName = !!el.getAccessibleName(ariaVersion).trim();
-            if (!hasAccessibleName) {
-                report({ scope: el, message: t('Require {0}', 'accessible name') });
+            if (hasAccessibleName) {
+                return;
+            }
+            // The static scan cannot decide whether the unknown content is the name.
+            if (accnameMayComeFromUnknownContent(el, document)) {
+                return;
             }
+            report({ scope: el, message: t('Require {0}', 'accessible name') });
         });
     },
 });

package/lib/require-owned-elements/index.js

@@ -1,5 +1,6 @@
 import { createRule, getComputedRole, getSpec } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
+import { getContentOwner } from '../permitted-contents/slot-content.js';
 import { checkingRequiredOwnedElements } from '../wai-aria/checkings/required-owned-elements.js';
 import { defaultOptions } from '../wai-aria/default-options.js';
 import meta from './meta.js';
@@ -16,6 +17,17 @@ export default createRule({
             const ariaVersion = el.rule.options?.version ?? document.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
             const computed = getComputedRole(document.specs, el, ariaVersion);
             report(checkingRequiredOwnedElements({ el, role: computed.role }));
+            /**
+             * The slot wrapper of a pretended component is a virtual element that is not in
+             * the document, so the walk never reaches it, yet it is the element that owns
+             * the children given to the component. Its role stands on its own: the
+             * component is the one that places it, so no context is asked of its parent.
+             */
+            const wrapper = getContentOwner(el, 'pretended');
+            if (wrapper !== el) {
+                const wrapperComputed = getComputedRole(document.specs, wrapper, ariaVersion, true);
+                report(checkingRequiredOwnedElements({ el: wrapper, role: wrapperComputed.role }));
+            }
         });
     },
 });

package/lib/wai-aria/checkings/required-owned-elements.d.ts

@@ -9,6 +9,8 @@ import type { ARIARole } from '@markuplint/ml-spec';
  * For example, a `list` role must own at least one element with the `listitem` role.
  * This checker respects `aria-busy="true"` (which signals that content is still loading),
  * preprocessor blocks, and mutable children from template engines.
+ * For a pretended component, the owned elements are the ones the component renders
+ * itself (`contents`) together with the children given to it, not the usage site alone.
  *
  * @see https://w3c.github.io/aria/#mustContain
  * @param el - The element node to inspect for allowed accessibility child roles.

package/lib/wai-aria/checkings/required-owned-elements.js

@@ -1,4 +1,5 @@
 import { ARIA_RECOMMENDED_VERSION, getComputedRole, isRequiredOwnedElement, isTransparentForOwnership, } from '@markuplint/ml-spec';
+import { expandChildren, isContentMutable } from '../../permitted-contents/slot-content.js';
 /**
  * Checks whether an element with a role that has "Allowed Accessibility Child Roles"
  * (called "Required Owned Elements" in ARIA 1.2) actually contains children
@@ -7,6 +8,8 @@ import { ARIA_RECOMMENDED_VERSION, getComputedRole, isRequiredOwnedElement, isTr
  * For example, a `list` role must own at least one element with the `listitem` role.
  * This checker respects `aria-busy="true"` (which signals that content is still loading),
  * preprocessor blocks, and mutable children from template engines.
+ * For a pretended component, the owned elements are the ones the component renders
+ * itself (`contents`) together with the children given to it, not the usage site alone.
  *
  * @see https://w3c.github.io/aria/#mustContain
  * @param el - The element node to inspect for allowed accessibility child roles.
@@ -38,7 +41,7 @@ export const checkingRequiredOwnedElements = ({ el, role }) => t => {
     // should also be considered as owned elements per the ARIA specification.
     const ariaVersion = el.rule.options?.version ?? el.ownerMLDocument.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
     const children = classifyChildren(el, role, ariaVersion);
-    if (children.some(([, type]) => type === 'BUSY')) {
+    if (children.some(([, type]) => type === 'BUSY' || type === 'UNKNOWN')) {
         return;
     }
     /**
@@ -66,19 +69,21 @@ export const checkingRequiredOwnedElements = ({ el, role }) => t => {
      * </table>
      * ```
      */
-    if (el.hasMutableChildren(true)) {
+    // A virtual slot wrapper stands for the component, whose nodes are the ones given to it.
+    const component = el.pretenderContext?.type === 'origin' ? el.pretenderContext.origin : el;
+    if (component.hasMutableChildren(true) || isContentMutable(component, 'pretended')) {
         return;
     }
-    if (mayBeBeforeCreated(el)) {
+    if (mayBeBeforeCreated(getOwnedChildNodes(el) ?? [])) {
         return {
-            scope: el,
+            scope: component,
             message: t('{0}. Or, {1}', t('{0} requires {1}', t('the {0}', 'child element'), role.allowedAccessibilityChildRoles.length === 1 && role.allowedAccessibilityChildRoles[0]
                 ? t('the "{0*}" {1}', role.allowedAccessibilityChildRoles[0], 'role')
                 : t('the {0}', 'roles') + `: ${t(role.allowedAccessibilityChildRoles)}`), t('require {0}', 'aria-busy="true"')),
         };
     }
     return {
-        scope: el,
+        scope: component,
         message: t('{0} expects {1}', t('the "{0*}" {1}', role.name, 'role'), role.allowedAccessibilityChildRoles.length === 1 && role.allowedAccessibilityChildRoles[0]
             ? t('the "{0*}" {1}', role.allowedAccessibilityChildRoles[0], 'role')
             : t('the {0}', 'roles') + `: ${t(role.allowedAccessibilityChildRoles)}`),
@@ -91,15 +96,13 @@ export const checkingRequiredOwnedElements = ({ el, role }) => t => {
  * @param el - The element to inspect.
  * @returns `true` if the element is empty or only contains script/template children.
  */
-function mayBeBeforeCreated(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el) {
-    if (el.isEmpty()) {
+function mayBeBeforeCreated(childNodes) {
+    if (childNodes.every(child => child.is(child.TEXT_NODE) && child.textContent?.trim() === '')) {
         return true;
     }
-    return [...el.children].every(child => {
-        return ['script', 'template'].includes(child.localName);
-    });
+    return childNodes
+        .filter(child => child.is(child.ELEMENT_NODE))
+        .every(child => ['script', 'template'].includes(child.localName));
 }
 /**
  * Classifies the child nodes of an element for "Allowed Accessibility Child Roles" validation.
@@ -116,19 +119,34 @@ el) {
 function classifyChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, role, version) {
+    const childNodes = getOwnedChildNodes(el);
+    if (!childNodes) {
+        return [[el, 'UNKNOWN']];
+    }
     const result = [];
-    for (const child of el.childNodes) {
+    for (const child of childNodes) {
         if (child.is(child.ELEMENT_NODE)) {
             if (child.matches('[aria-busy="true" i]')) {
                 result.push([child, 'BUSY']);
                 continue;
             }
-            const computedChild = getComputedRole(child.ownerMLDocument.specs, child, version);
+            /**
+             * The role of a child is resolved against its DOM parent. A child that a pretender
+             * places somewhere other than under its DOM parent (a node given at the usage site
+             * that the component renders inside its slot wrapper, or an element a fragment
+             * component renders in place) would be judged against the wrong parent and lose
+             * its role, so it is resolved on its own.
+             */
+            const computedChild = getComputedRole(child.ownerMLDocument.specs, child, version, child.parentElement !== el);
             if (role.allowedAccessibilityChildRoles.some(ownedRole => isRequiredOwnedElement(computedChild.el, computedChild.role, ownedRole, child.ownerMLDocument.specs, version))) {
                 result.push([child, 'REQUIRED']);
                 continue;
             }
             if (isTransparentForOwnership(computedChild.role?.name, version)) {
+                if (isContentMutable(child, 'pretended')) {
+                    result.push([child, 'UNKNOWN']);
+                    continue;
+                }
                 result.push(...classifyChildren(child, role, version));
                 continue;
             }
@@ -143,3 +161,43 @@ el, role, version) {
     }
     return result;
 }
+/**
+ * The child nodes that `el` owns as the page renders them.
+ *
+ * For a pretended component this is what the component renders, not what is written
+ * at the usage site: the nodes it renders itself (`contents`) around the nodes given
+ * to it, `slotContent.fill(given)`. The nodes "given" are `as.childNodes`, which is
+ * empty when the component never renders its children (`slots: null`).
+ *
+ * - A single slot wrapper that differs from the outermost element sits between them:
+ *   the outermost element owns the wrapper, and the wrapper owns the filled nodes.
+ * - Several slot wrappers leave the owner of each node unknown, so `null` is returned
+ *   and nothing is claimed about the element.
+ *
+ * @param el - The element, or the virtual slot wrapper of a pretended component.
+ * @returns The child nodes, or `null` when they cannot be known.
+ */
+function getOwnedChildNodes(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    const context = el.pretenderContext;
+    if (context?.type === 'pretender') {
+        const wrapper = context.slotContent?.wrapper;
+        if (wrapper === null) {
+            return null;
+        }
+        if (wrapper && wrapper !== context.as) {
+            return [wrapper];
+        }
+        return expandChildren(el, [...context.as.childNodes], 'pretended');
+    }
+    // The virtual slot wrapper has no child nodes of its own.
+    if (context?.type === 'origin') {
+        const origin = context.origin;
+        const originContext = origin.pretenderContext;
+        if (originContext?.type === 'pretender' && originContext.slotContent?.wrapper === el) {
+            return expandChildren(origin, [...originContext.as.childNodes], 'pretended');
+        }
+    }
+    return expandChildren(el, [...el.childNodes], 'pretended');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/rules",
-	"version": "5.0.1",
+	"version": "5.1.1",
 	"description": "Built-in rules of markuplint",
 	"repository": {
 		"type": "git",
@@ -31,13 +31,13 @@
 		"./lib/permitted-contents/debug.js": "./lib/permitted-contents/debug.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/html-spec": "5.0.1",
-		"@markuplint/ml-config": "5.0.1",
-		"@markuplint/ml-core": "5.0.1",
-		"@markuplint/ml-spec": "5.0.1",
-		"@markuplint/selector": "5.0.1",
-		"@markuplint/shared": "5.0.1",
-		"@markuplint/types": "5.0.1",
+		"@markuplint/html-spec": "5.1.1",
+		"@markuplint/ml-config": "5.1.1",
+		"@markuplint/ml-core": "5.1.1",
+		"@markuplint/ml-spec": "5.1.1",
+		"@markuplint/selector": "5.1.1",
+		"@markuplint/shared": "5.1.1",
+		"@markuplint/types": "5.1.1",
 		"@mdn/browser-compat-data": "^7.3.2",
 		"@types/debug": "4.1.13",
 		"ansi-colors": "4.1.3",
@@ -47,5 +47,5 @@
 		"image-size": "^2.0.2",
 		"type-fest": "5.6.0"
 	},
-	"gitHead": "edbaeedca5588fb291ea9d4e21a4ab2bf41fc9cb"
+	"gitHead": "a940c8526e971d590d97395ce924910221208820"
 }