@markuplint/ml-spec 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+### Bug Fixes
+
+* **ml-spec:** keep roles that are not permitted and align the accessible name with AccName ([6c38c60](https://github.com/markuplint/markuplint/commit/6c38c60971690edec8b6453e50c76146eb10deb2)), closes [#4408](https://github.com/markuplint/markuplint/issues/4408)
+
+
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+* **ml-spec:** ask the element whether a name is the attribute, and keep the spelling of a directive ([e414513](https://github.com/markuplint/markuplint/commit/e414513598bf068c323dc335b4177c63941d5775))
+* **ml-spec:** keep the results of getSpecByTagName for each list of specs ([3322329](https://github.com/markuplint/markuplint/commit/33223295d7990561a8686a80029706c096e65666))
+
+### Reverts
+
+* **ml-spec:** leave is-exposed as it was on dev ([ce4c5c8](https://github.com/markuplint/markuplint/commit/ce4c5c833ca542bcfef8460d1a8228c2a3144f87))
+
+
 # [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
 
 ### Bug Fixes

package/lib/algorithm/aria/accname/aria-steps.d.ts

@@ -1,4 +1,4 @@
-import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameResolver, AccnameResult } from './types.js';
 /**
  * Implements AccName 1.2 §4.3.2 Step 2B:
  * "If the current node has an `aria-labelledby` attribute that contains
@@ -16,7 +16,19 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  *
  * @see https://www.w3.org/TR/accname-1.2/#comp_labelledby_traversal — AccName 1.2 §4.3.2 Step 2B
  */
-export declare function resolveAriaLabelledby(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult): AccnameResult | null;
+export declare function resolveAriaLabelledby(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn): AccnameResult | null;
+/**
+ * Computes the text alternative of a node directly referenced by
+ * `aria-labelledby` (Step 2B, LabelledBy Traversal).
+ *
+ * Step 2A is skipped for the whole subtree only when the referenced node is
+ * hidden; otherwise its hidden descendants contribute nothing.
+ *
+ * @see https://w3c.github.io/accname/#comp_hidden_not_referenced
+ *
+ * > If the current node is hidden and is: Not part of an aria-labelledby or aria-describedby traversal, where the node directly referenced by that relation was hidden.
+ */
+export declare function computeReferenced(referenced: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn): AccnameResult;
 /**
  * Implements AccName 1.2 §4.3.2 Step 2D:
  * "If the current node has an `aria-label` attribute whose value is

package/lib/algorithm/aria/accname/aria-steps.js

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
-import { flattenText, makeResult } from './helpers.js';
+import { flattenText, makeResult } from './result.js';
 /**
  * Implements AccName 1.2 §4.3.2 Step 2B:
  * "If the current node has an `aria-labelledby` attribute that contains
@@ -52,7 +52,7 @@ export function resolveAriaLabelledby(el, resolver, visited, computeFn) {
         // Each branch gets its own visited set so that one IDREF's
         // traversal doesn't block resolution of a later IDREF.
         const innerVisited = new Set([...newVisited, id]);
-        const result = computeFn(referenced, resolver, true, innerVisited);
+        const result = computeReferenced(referenced, resolver, innerVisited, computeFn);
         if (result.name) {
             parts.push(result.name);
         }
@@ -63,6 +63,26 @@ export function resolveAriaLabelledby(el, resolver, visited, computeFn) {
     }
     return null;
 }
+/**
+ * Computes the text alternative of a node directly referenced by
+ * `aria-labelledby` (Step 2B, LabelledBy Traversal).
+ *
+ * Step 2A is skipped for the whole subtree only when the referenced node is
+ * hidden; otherwise its hidden descendants contribute nothing.
+ *
+ * @see https://w3c.github.io/accname/#comp_hidden_not_referenced
+ *
+ * > If the current node is hidden and is: Not part of an aria-labelledby or aria-describedby traversal, where the node directly referenced by that relation was hidden.
+ */
+export function computeReferenced(referenced, resolver, visited, computeFn) {
+    const traversalResolver = resolver.isHidden(referenced)
+        ? {
+            ...resolver,
+            isHidden: () => false,
+        }
+        : resolver;
+    return computeFn(referenced, traversalResolver, true, visited);
+}
 /**
  * Implements AccName 1.2 §4.3.2 Step 2D:
  * "If the current node has an `aria-label` attribute whose value is

package/lib/algorithm/aria/accname/compute.d.ts

@@ -8,8 +8,9 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  *
  * Control flow (Steps map to AccName 1.2 §4.3.2):
  *
- * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`) and NOT
- *    referenced by `aria-labelledby`, return empty immediately.
+ * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`), return
+ *    empty immediately, unless it is in an `aria-labelledby` traversal whose
+ *    directly referenced node is hidden.
  * 2. **Pre-computed name** — (Implementation-specific extension) If the
  *    resolver provides `getPrecomputedName`, check it before standard steps.
  *    Used by ml-core's Pretender integration for framework components.
@@ -18,7 +19,9 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  *    labelledby traversal (`inLabelledbyTraversal`) to prevent re-entry.
  * 4. **Step 2D — `aria-label`** — Use the `aria-label` attribute value.
  * 5. **Step 2E — Element-specific name** — Dispatch to HTML-AAM §4.1
- *    element-specific rules (label association, alt, value, legend, caption, SVG title).
+ *    element-specific rules (label association, alt, value, legend, caption, SVG title),
+ *    skipped for an element the resolver reports as exposed as presentational
+ *    (`isExposedAsPresentational`).
  * 6. **Step 2F — Name from content** — If the element's role allows
  *    `nameFrom: ["content"]`, or the element is referenced by `aria-labelledby`
  *    (`inLabelledbyTraversal`), recursively collect child text (including
@@ -32,6 +35,35 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation — HTML-AAM §4.1
  */
 export declare function computeAccessibleName(el: AccnameElement, resolver: AccnameResolver): AccnameResult;
+/**
+ * Computes the text alternative of an element as a node referenced by
+ * `aria-labelledby` or `aria-describedby` (the LabelledBy Traversal of Step 2B,
+ * which the description computation also uses).
+ *
+ * @param el - The referenced element
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The computed text alternative and its source
+ * @see https://w3c.github.io/accname/#comp_labelledby_traversal
+ */
+export declare function computeReferencedTextAlternative(el: AccnameElement, resolver: AccnameResolver): AccnameResult;
+/**
+ * Computes the host language text alternative of an element (AccName §4.3.2
+ * Step 2E, HTML-AAM §4.1), such as the `alt` of an image or the `title` of an
+ * SVG element, whether or not the element is exposed as presentational.
+ *
+ * Tells what an explicit `none` or `presentation` role drops from the name:
+ * every source the HTML-AAM rules of Step 2E give (`label`, `alt`, `value`,
+ * `placeholder`, `legend`, `caption`, `svg-title`, and the `default` label of a
+ * submit, reset or image button). The sources that Step 2E shares with other
+ * steps (`content`, the `title` attribute) are not dropped by the role, and give
+ * `null`.
+ *
+ * @param el - The element
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The text alternative and its source, or `null` if the element has none
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ */
+export declare function computeHostLanguageLabel(el: AccnameElement, resolver: AccnameResolver): AccnameResult | null;
 /**
  * @param inLabelledbyTraversal - When true, Step 2B is skipped to prevent re-entry
  *   into `resolveAriaLabelledby`, and Step 2F name-from-content is enabled regardless

package/lib/algorithm/aria/accname/compute.js

@@ -1,7 +1,8 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
-import { resolveAriaLabel, resolveAriaLabelledby } from './aria-steps.js';
+import { computeReferenced, resolveAriaLabel, resolveAriaLabelledby } from './aria-steps.js';
 import { getElementSpecificName } from './element-names.js';
-import { makeResult, resolveNameFromContent } from './helpers.js';
+import { resolveNameFromContent } from './helpers.js';
+import { makeResult } from './result.js';
 const EMPTY_RESULT = { name: '', source: null };
 /**
  * Computes the accessible name for an element.
@@ -12,8 +13,9 @@ const EMPTY_RESULT = { name: '', source: null };
  *
  * Control flow (Steps map to AccName 1.2 §4.3.2):
  *
- * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`) and NOT
- *    referenced by `aria-labelledby`, return empty immediately.
+ * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`), return
+ *    empty immediately, unless it is in an `aria-labelledby` traversal whose
+ *    directly referenced node is hidden.
  * 2. **Pre-computed name** — (Implementation-specific extension) If the
  *    resolver provides `getPrecomputedName`, check it before standard steps.
  *    Used by ml-core's Pretender integration for framework components.
@@ -22,7 +24,9 @@ const EMPTY_RESULT = { name: '', source: null };
  *    labelledby traversal (`inLabelledbyTraversal`) to prevent re-entry.
  * 4. **Step 2D — `aria-label`** — Use the `aria-label` attribute value.
  * 5. **Step 2E — Element-specific name** — Dispatch to HTML-AAM §4.1
- *    element-specific rules (label association, alt, value, legend, caption, SVG title).
+ *    element-specific rules (label association, alt, value, legend, caption, SVG title),
+ *    skipped for an element the resolver reports as exposed as presentational
+ *    (`isExposedAsPresentational`).
  * 6. **Step 2F — Name from content** — If the element's role allows
  *    `nameFrom: ["content"]`, or the element is referenced by `aria-labelledby`
  *    (`inLabelledbyTraversal`), recursively collect child text (including
@@ -38,6 +42,43 @@ const EMPTY_RESULT = { name: '', source: null };
 export function computeAccessibleName(el, resolver) {
     return computeAccessibleNameInternal(el, resolver, false, new Set());
 }
+/**
+ * Computes the text alternative of an element as a node referenced by
+ * `aria-labelledby` or `aria-describedby` (the LabelledBy Traversal of Step 2B,
+ * which the description computation also uses).
+ *
+ * @param el - The referenced element
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The computed text alternative and its source
+ * @see https://w3c.github.io/accname/#comp_labelledby_traversal
+ */
+export function computeReferencedTextAlternative(el, resolver) {
+    return computeReferenced(el, resolver, new Set(el.id ? [el.id] : []), computeAccessibleNameInternal);
+}
+/**
+ * Computes the host language text alternative of an element (AccName §4.3.2
+ * Step 2E, HTML-AAM §4.1), such as the `alt` of an image or the `title` of an
+ * SVG element, whether or not the element is exposed as presentational.
+ *
+ * Tells what an explicit `none` or `presentation` role drops from the name:
+ * every source the HTML-AAM rules of Step 2E give (`label`, `alt`, `value`,
+ * `placeholder`, `legend`, `caption`, `svg-title`, and the `default` label of a
+ * submit, reset or image button). The sources that Step 2E shares with other
+ * steps (`content`, the `title` attribute) are not dropped by the role, and give
+ * `null`.
+ *
+ * @param el - The element
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The text alternative and its source, or `null` if the element has none
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ */
+export function computeHostLanguageLabel(el, resolver) {
+    const result = getElementSpecificName(el, resolver, new Set(), computeAccessibleNameInternal, false);
+    if (!result?.source || result.source === 'content' || result.source === 'title') {
+        return null;
+    }
+    return result;
+}
 /**
  * @param inLabelledbyTraversal - When true, Step 2B is skipped to prevent re-entry
  *   into `resolveAriaLabelledby`, and Step 2F name-from-content is enabled regardless
@@ -45,8 +86,12 @@ export function computeAccessibleName(el, resolver) {
  * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
  */
 export function computeAccessibleNameInternal(el, resolver, inLabelledbyTraversal, visited) {
-    // AccName 1.2 §4.3.2 Step 2A: Hidden elements return empty unless referenced by aria-labelledby
-    if (!inLabelledbyTraversal && resolver.isHidden(el)) {
+    // AccName 1.2 §4.3.2 Step 2A: Hidden elements return empty. In an aria-labelledby
+    // traversal whose referenced node is hidden, `computeReferenced` passes a
+    // resolver that finds nothing hidden.
+    const hidden = resolver.isHidden(el);
+    resolver.onVisit?.(el, { hidden, embeddedControl: false, inLabelledbyTraversal });
+    if (hidden) {
         return EMPTY_RESULT;
     }
     // [Implementation-specific] Pre-computed name (e.g., Pretender integration) — checked after hidden check
@@ -68,8 +113,11 @@ export function computeAccessibleNameInternal(el, resolver, inLabelledbyTraversa
     if (ariaLabelResult) {
         return ariaLabelResult;
     }
-    // AccName 1.2 §4.3.2 Step 2E: Element-specific name (HTML-AAM §4.1)
-    const elementResult = getElementSpecificName(el, resolver, visited, computeAccessibleNameInternal, inLabelledbyTraversal);
+    // AccName 1.2 §4.3.2 Step 2E: Element-specific name (HTML-AAM §4.1),
+    // "unless the current node is exposed as presentational"
+    const elementResult = resolver.isExposedAsPresentational?.(el)
+        ? null
+        : getElementSpecificName(el, resolver, visited, computeAccessibleNameInternal, inLabelledbyTraversal);
     if (elementResult) {
         return elementResult;
     }

package/lib/algorithm/aria/accname/element-names.d.ts

@@ -1,4 +1,4 @@
-import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameResolver, AccnameResult } from './types.js';
 /**
  * Implements AccName 1.2 §4.3.2 Step 2E: for elements that have a native
  * host language text alternative, use that alternative. The specific rules
@@ -10,4 +10,4 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2E
  * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation — HTML-AAM §4.1
  */
-export declare function getElementSpecificName(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): AccnameResult | null;
+export declare function getElementSpecificName(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): AccnameResult | null;

package/lib/algorithm/aria/accname/element-names.js

@@ -1,7 +1,8 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
 import { DEFAULT_IMAGE_LABEL, DEFAULT_RESET_LABEL, DEFAULT_SUBMIT_LABEL, TEXT_INPUT_TYPES, } from '../../../const/index.js';
-import { findChildByLocalName, getInputType, getTextContent, isSvgElement, makeResult, resolveNameFromContent, } from './helpers.js';
+import { findChildByLocalName, getInputType, getTextContent, isSvgElement, resolveNameFromContent } from './helpers.js';
 import { resolveLabelText } from './label-steps.js';
+import { makeResult } from './result.js';
 /**
  * Implements AccName 1.2 §4.3.2 Step 2E: for elements that have a native
  * host language text alternative, use that alternative. The specific rules

package/lib/algorithm/aria/accname/helpers.d.ts

@@ -1,7 +1,5 @@
-import type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameNode, AccnameResolver } from './types.js';
 export { EMBEDDED_CONTROL_ROLES } from '../../../const/index.js';
-export declare function makeResult(name: string, source: AccnameSource | null): AccnameResult;
-export declare function flattenText(text: string): string;
 /**
  * Implements AccName 1.2 §4.3.2 Steps 2F and 2C:
  *
@@ -21,7 +19,19 @@ export declare function flattenText(text: string): string;
  * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2F
  * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
  */
-export declare function resolveNameFromContent(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): string;
+export declare function resolveNameFromContent(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): string;
+/**
+ * The text an embedded control reached by name-from-content recursion
+ * contributes, in the order of AccName §4.3.2: nothing when it is hidden
+ * (Step 2A), the text of its `aria-labelledby` outside an ongoing
+ * `aria-labelledby` traversal (Step 2B), otherwise its value (Step 2C), as its
+ * `aria-label` is ignored (Step 2D).
+ *
+ * @see https://w3c.github.io/accname/#comp_label
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an embedded control, ignore aria-label and skip to rule Embedded Control.
+ */
+export declare function embeddedControlText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): string;
 /**
  * The child nodes to traverse for `el`: what the resolver says it renders,
  * or `el.childNodes` when it says nothing.
@@ -38,6 +48,15 @@ export declare function findAncestorLabel(el: AccnameElement): AccnameElement |
 export declare function resolveLabel(el: AccnameElement, resolver: AccnameResolver): readonly AccnameElement[];
 export declare function getInputType(el: AccnameElement): string;
 export declare function isSvgElement(el: AccnameElement): boolean;
+/**
+ * Whether the element is an SVG `title` or `desc`. They are never rendered,
+ * so their text is not content of the parent: a `title` gives the name only
+ * through Step 2E of its parent (`handleSvgElement`), which an element exposed
+ * as presentational skips.
+ *
+ * @see https://w3c.github.io/svgwg/svg2-draft/struct.html#TermNeverRenderedElement
+ */
+export declare function isSvgDescriptiveElement(el: AccnameElement): boolean;
 /**
  * Escapes a string for safe use inside a CSS selector.
  *

package/lib/algorithm/aria/accname/helpers.js

@@ -1,16 +1,7 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
 import { ELEMENT_NODE, SVG_NAMESPACE, TEXT_NODE, TEXT_LIKE_INPUT_TYPES } from '../../../const/index.js';
+import { resolveAriaLabelledby } from './aria-steps.js';
 export { EMBEDDED_CONTROL_ROLES } from '../../../const/index.js';
-export function makeResult(name, source) {
-    const trimmed = flattenText(name);
-    return {
-        name: trimmed,
-        source: trimmed ? source : null,
-    };
-}
-export function flattenText(text) {
-    return text.replaceAll(/\s+/g, ' ').trim();
-}
 /**
  * Implements AccName 1.2 §4.3.2 Steps 2F and 2C:
  *
@@ -38,9 +29,12 @@ export function resolveNameFromContent(el, resolver, visited, computeFn, inLabel
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
+            if (isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
             if (resolver.isEmbeddedControl(childEl)) {
                 // Step 2C: Embedded controls — use value directly, aria-label is ignored
-                parts.push(getEmbeddedControlValue(childEl, resolver));
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -84,8 +78,11 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
+            if (isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
             if (resolver.isEmbeddedControl(childEl)) {
-                parts.push(getEmbeddedControlValue(childEl, resolver));
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -100,6 +97,31 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
     }
     return parts.join(' ');
 }
+/**
+ * The text an embedded control reached by name-from-content recursion
+ * contributes, in the order of AccName §4.3.2: nothing when it is hidden
+ * (Step 2A), the text of its `aria-labelledby` outside an ongoing
+ * `aria-labelledby` traversal (Step 2B), otherwise its value (Step 2C), as its
+ * `aria-label` is ignored (Step 2D).
+ *
+ * @see https://w3c.github.io/accname/#comp_label
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an embedded control, ignore aria-label and skip to rule Embedded Control.
+ */
+export function embeddedControlText(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const hidden = resolver.isHidden(el);
+    resolver.onVisit?.(el, { hidden, embeddedControl: true, inLabelledbyTraversal });
+    if (hidden) {
+        return '';
+    }
+    if (!inLabelledbyTraversal) {
+        const labelledby = resolveAriaLabelledby(el, resolver, visited, computeFn);
+        if (labelledby) {
+            return labelledby.name;
+        }
+    }
+    return getEmbeddedControlValue(el, resolver);
+}
 /**
  * Implements AccName 1.2 §4.3.2 Step 2C embedded control value resolution:
  * - **Range controls** (slider/spinbutton/input[range]):
@@ -287,6 +309,17 @@ export function getInputType(el) {
 export function isSvgElement(el) {
     return el.namespaceURI === SVG_NAMESPACE;
 }
+/**
+ * Whether the element is an SVG `title` or `desc`. They are never rendered,
+ * so their text is not content of the parent: a `title` gives the name only
+ * through Step 2E of its parent (`handleSvgElement`), which an element exposed
+ * as presentational skips.
+ *
+ * @see https://w3c.github.io/svgwg/svg2-draft/struct.html#TermNeverRenderedElement
+ */
+export function isSvgDescriptiveElement(el) {
+    return isSvgElement(el) && (el.localName === 'title' || el.localName === 'desc');
+}
 /**
  * Escapes a string for safe use inside a CSS selector.
  *

package/lib/algorithm/aria/accname/index.d.ts

@@ -1,4 +1,4 @@
-export { computeAccessibleName } from './compute.js';
+export { computeAccessibleName, computeHostLanguageLabel, computeReferencedTextAlternative } from './compute.js';
 export { escapeCSS } from './helpers.js';
 export { hasSvgAccessibleNameSource } from './svg-helpers.js';
-export type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource } from './types.js';
+export type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource, AccnameVisit, } from './types.js';

package/lib/algorithm/aria/accname/index.js

@@ -1,3 +1,3 @@
-export { computeAccessibleName } from './compute.js';
+export { computeAccessibleName, computeHostLanguageLabel, computeReferencedTextAlternative } from './compute.js';
 export { escapeCSS } from './helpers.js';
 export { hasSvgAccessibleNameSource } from './svg-helpers.js';

package/lib/algorithm/aria/accname/label-steps.d.ts

@@ -1,4 +1,4 @@
-import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameResolver, AccnameResult } from './types.js';
 /**
  * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, the HTML label
  * association is checked before other element-specific rules.
@@ -6,4 +6,4 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2E
  * @see https://www.w3.org/TR/html-aam-1.0/#el-input-text — HTML-AAM label association
  */
-export declare function resolveLabelText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): AccnameResult | null;
+export declare function resolveLabelText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): AccnameResult | null;

package/lib/algorithm/aria/accname/label-steps.js

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
 import { ELEMENT_NODE, TEXT_NODE } from '../../../const/index.js';
-import { flattenText, getChildNodes, makeResult, resolveLabel } from './helpers.js';
+import { embeddedControlText, getChildNodes, isSvgDescriptiveElement, resolveLabel } from './helpers.js';
+import { flattenText, makeResult } from './result.js';
 /**
  * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, the HTML label
  * association is checked before other element-specific rules.
@@ -30,6 +31,10 @@ export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyT
  * Excludes the labeled element itself to prevent circular inclusion. Parts are
  * joined with a space separator, matching the AccName 1.2 concatenation
  * behavior for label text.
+ *
+ * The children are treated as name-from-content recursion treats them
+ * (`resolveNameFromContent`): a hidden one and an SVG `title` or `desc`
+ * contribute nothing, and an embedded control contributes its value.
  */
 function collectLabelText(label, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];
@@ -39,14 +44,18 @@ function collectLabelText(label, labeledElement, resolver, visited, computeFn, i
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
-            if (childEl === labeledElement) {
+            if (childEl === labeledElement || isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
+            if (resolver.isEmbeddedControl(childEl)) {
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
                 continue;
             }
             const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
             if (result.name) {
                 parts.push(result.name);
             }
-            else {
+            else if (!resolver.isHidden(childEl)) {
                 // Transparent traversal: when the child element has no accessible name
                 // (e.g., <span> with role="generic"), recursively collect its descendant text.
                 // This matches the behavior of resolveNameFromContent's fallback.

package/lib/algorithm/aria/accname/result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The result builders of the accessible name computation.
+ *
+ * A module of their own, not part of `helpers.ts`: `aria-steps.ts` builds
+ * results, and `helpers.ts` runs Step 2B for an embedded control through
+ * `aria-steps.ts`, so keeping them in `helpers.ts` would make the two import
+ * each other.
+ *
+ * @module
+ */
+import type { AccnameResult, AccnameSource } from './types.js';
+/**
+ * Builds a result from a name, flattened; an empty name has no source.
+ */
+export declare function makeResult(name: string, source: AccnameSource | null): AccnameResult;
+/**
+ * Makes a flat string: whitespace runs become a single space, and the ends are trimmed.
+ *
+ * @see https://w3c.github.io/accname/#terminology
+ */
+export declare function flattenText(text: string): string;

package/lib/algorithm/aria/accname/result.js

@@ -0,0 +1,28 @@
+/**
+ * The result builders of the accessible name computation.
+ *
+ * A module of their own, not part of `helpers.ts`: `aria-steps.ts` builds
+ * results, and `helpers.ts` runs Step 2B for an embedded control through
+ * `aria-steps.ts`, so keeping them in `helpers.ts` would make the two import
+ * each other.
+ *
+ * @module
+ */
+/**
+ * Builds a result from a name, flattened; an empty name has no source.
+ */
+export function makeResult(name, source) {
+    const trimmed = flattenText(name);
+    return {
+        name: trimmed,
+        source: trimmed ? source : null,
+    };
+}
+/**
+ * Makes a flat string: whitespace runs become a single space, and the ends are trimmed.
+ *
+ * @see https://w3c.github.io/accname/#terminology
+ */
+export function flattenText(text) {
+    return text.replaceAll(/\s+/g, ' ').trim();
+}

package/lib/algorithm/aria/accname/types.d.ts

@@ -42,6 +42,19 @@ export interface AccnameResolver {
      * in name-from-content computation (textbox, combobox, listbox, spinbutton, slider, searchbox).
      */
     isEmbeddedControl(el: AccnameElement): boolean;
+    /**
+     * Checks if an element is exposed with an explicit `none` or `presentation`
+     * role, so that Step 2E does not use its host language text alternative.
+     * When absent, no element is treated so.
+     */
+    isExposedAsPresentational?(el: AccnameElement): boolean;
+    /**
+     * Called for every element the computation reaches, before Step 2A, so that
+     * a caller can tell which attributes of a descendant took part in a name.
+     * An element that the computation does not reach (the subtree of a hidden
+     * element, or of one named before content) is never reported.
+     */
+    onVisit?(el: AccnameElement, visit: AccnameVisit): void;
     /**
      * Returns a pre-computed name for an element, bypassing the standard algorithm.
      * Used by ml-core for Pretender integration where framework components provide
@@ -60,6 +73,32 @@ export interface AccnameResolver {
      */
     getChildNodes?(el: AccnameElement): Iterable<AccnameNode>;
 }
+/**
+ * The recursive entry of the computation (`computeAccessibleNameInternal`),
+ * handed to the steps that compute the text alternative of another node.
+ */
+export type AccnameComputeFn = (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult;
+/**
+ * How the computation reached an element (see `AccnameResolver.onVisit`).
+ */
+export interface AccnameVisit {
+    /**
+     * Whether Step 2A found the element hidden, which ends the computation of
+     * it. Step 2A does not apply inside an `aria-labelledby` traversal whose
+     * directly referenced node is hidden, so no element is found hidden there.
+     */
+    readonly hidden: boolean;
+    /**
+     * Whether the element is an embedded control reached by name-from-content
+     * recursion (Step 2C), whose value is used and whose `aria-label` is ignored.
+     */
+    readonly embeddedControl: boolean;
+    /**
+     * Whether the element is part of an ongoing `aria-labelledby` traversal, in
+     * which Step 2B is not applied.
+     */
+    readonly inLabelledbyTraversal: boolean;
+}
 /**
  * Identifies the source of an element's accessible name per HTML-AAM §4.1.
  * Used for diagnostic purposes (e.g., reporting which source provided the name).

package/lib/algorithm/aria/accname-computation.js

@@ -2,6 +2,7 @@ import { computeAccessibleName } from './accname/compute.js';
 import { EMBEDDED_CONTROL_ROLES, escapeCSS } from './accname/helpers.js';
 import { isNativeEmbeddedControl } from '../../const/index.js';
 import { getComputedRole } from './get-computed-role.js';
+import { isExposedAsPresentational } from './is-presentational.js';
 /**
  * [Implementation-specific] Reentrant guard to prevent infinite recursion when
  * getComputedRole evaluates `:aria(has name)` selectors, which call back into getAccname.
@@ -121,6 +122,11 @@ el, specs, version) {
             // Native HTML embedded controls without explicit role
             return isNativeEmbeddedControl(target);
         },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        isExposedAsPresentational(target) {
+            // TODO: Remove cast when getComputedRole accepts AccnameElement (#3178)
+            return isExposedAsPresentational(getComputedRole(specs, target, version));
+        },
     };
 }
 /**

package/lib/algorithm/aria/get-computed-role.js

@@ -174,7 +174,7 @@ el, version, assumeSingleNode) {
      */
     if (
     // It doesn't been specified a valid explicit role.
-    (explicitRole.role === null || explicitRole.errorType != null) &&
+    explicitRole.role === null &&
         // It is an SVG element.
         el.namespaceURI === SVG_NAMESPACE &&
         !hasSvgAccessibleNameSource(el)) {
@@ -204,10 +204,9 @@ el, version, assumeSingleNode) {
      *
      * 1. It may be focusable
      *
-     * THIS CONDITION IS ALMOST MEANINGLESS.
-     * Because it has already been determined that
-     * the interactive elements can not specify the presentational role
-     * in the previous processing that computes the permitted role (`getExplicitRole`).
+     * ARIA in HTML does not permit the presentational roles on most
+     * interactive elements, but `getExplicitRole` keeps such a role with
+     * `NO_PERMITTED`, as user agents expose it, so this resolves it.
      */
     mayBeFocusable(el, specs) &&
         /**
@@ -264,13 +263,13 @@ el, version, assumeSingleNode) {
      * > and an explicit non-presentational role is applied.
      */
     const { props } = ariaSpecs(specs, version);
-    for (const attr of el.attributes) {
-        if (props.find(p => p.name === attr.name)?.isGlobal) {
-            return {
-                ...implicitRole,
-                errorType: 'GLOBAL_PROP_MUST_NOT_BE_PRESENTATIONAL',
-            };
-        }
+    // Asks the element, not its attribute list: whether `ARIA-LABEL` is `aria-label` is up to the element
+    // (a document of the HTML syntax folds the name, one that sets it under the name written does not).
+    if (props.some(p => p.isGlobal && el.hasAttribute(p.name))) {
+        return {
+            ...implicitRole,
+            errorType: 'GLOBAL_PROP_MUST_NOT_BE_PRESENTATIONAL',
+        };
     }
     return computedRole;
 }

package/lib/algorithm/aria/get-explicit-role.d.ts

@@ -2,6 +2,12 @@ import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
 /**
  * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
+ * The roles that ARIA in HTML does not permit on the element are authoring
+ * errors that the user agent does not correct: such a role is returned with
+ * `errorType: 'NO_PERMITTED'` (Core-AAM §3.2), except on an element that is
+ * never rendered.
+ *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @see https://w3c.github.io/core-aam/#mapping_conflicts
  */
 export declare function getExplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;

package/lib/algorithm/aria/get-explicit-role.js

@@ -1,10 +1,17 @@
+import { XHTML_NAMESPACE } from '../../const/index.js';
 import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getPermittedRoles } from './get-permitted-roles.js';
 /**
  * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
+ * The roles that ARIA in HTML does not permit on the element are authoring
+ * errors that the user agent does not correct: such a role is returned with
+ * `errorType: 'NO_PERMITTED'` (Core-AAM §3.2), except on an element that is
+ * never rendered.
+ *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @see https://w3c.github.io/core-aam/#mapping_conflicts
  */
 export function getExplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -46,13 +53,6 @@ el, version) {
             error = 'ABSTRACT';
             continue;
         }
-        /**
-         * Whether the role is the permitted role according to ARIA in HTML.
-         */
-        if (!permittedRoles.some(r => r.name === roleName)) {
-            error = 'NO_PERMITTED';
-            continue;
-        }
         /**
          * > Certain landmark roles require names from authors.
          * > In situations where an author has not specified names for these landmarks,
@@ -66,6 +66,35 @@ el, version) {
             error = 'INVALID_LANDMARK';
             continue;
         }
+        /**
+         * A role that ARIA in HTML does not permit on the element is an
+         * authoring error, but user agents still expose it, so the role is
+         * kept and the error is reported alongside. An element that is never
+         * rendered is not in the accessibility tree at all (WAI-ARIA §7.1),
+         * so the role is dropped there.
+         *
+         * @see https://w3c.github.io/aria/#tree_exclusion
+         *
+         * > Elements, including their descendent elements, that have host language semantics specifying that the element is not displayed, such as CSS display:none, visibility:hidden, or the HTML hidden attribute.
+         *
+         * @see https://w3c.github.io/core-aam/#mapping_conflicts
+         *
+         * > While conformance checkers might signal an error or warning when a WAI-ARIA role is used on elements with strong native semantics, user agents MUST still use the value of the semantic of the WAI-ARIA role when exposing the element to accessibility APIs.
+         */
+        if (!permittedRoles.some(r => r.name === roleName)) {
+            if (isNeverRendered(el, namespaceURI)) {
+                error = 'NO_PERMITTED';
+                continue;
+            }
+            return {
+                el,
+                role: {
+                    ...spec,
+                    isImplicit: false,
+                },
+                errorType: 'NO_PERMITTED',
+            };
+        }
         /**
          * Otherwise
          */
@@ -83,6 +112,43 @@ el, version) {
         errorType: error,
     };
 }
+/**
+ * HTML elements that the user agent style sheet never renders (`display: none`),
+ * together with `input[type=hidden]` from the same rules (`isNeverRendered`).
+ * `area` is left out: it is rendered through its image map. The rules that
+ * depend on state (`[hidden]`, `noscript` with scripting) are left out too: the
+ * role stays on such an element, as its `hidden` attribute is a matter of the
+ * accessible name computation (Step 2A), not of the role.
+ *
+ * @see https://html.spec.whatwg.org/multipage/rendering.html#hidden-elements
+ */
+const NEVER_RENDERED_HTML_ELEMENTS = new Set([
+    'base',
+    'basefont',
+    'datalist',
+    'head',
+    'link',
+    'meta',
+    'noembed',
+    'noframes',
+    'param',
+    'rp',
+    'script',
+    'style',
+    'template',
+    'title',
+]);
+function isNeverRendered(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, namespaceURI) {
+    if (namespaceURI !== XHTML_NAMESPACE) {
+        return false;
+    }
+    if (NEVER_RENDERED_HTML_ELEMENTS.has(el.localName)) {
+        return true;
+    }
+    return el.localName === 'input' && el.getAttribute('type')?.trim().toLowerCase() === 'hidden';
+}
 function isLandmarkRole(role) {
     return role?.superClassRoles.some(su => su.name === 'landmark');
 }

package/lib/algorithm/aria/is-presentational.d.ts

@@ -1,4 +1,4 @@
-import type { ARIAVersion } from '../../types/index.js';
+import type { ARIAVersion, ComputedRole } from '../../types/index.js';
 /**
  * Determines whether a given role name corresponds to a presentational role
  * (`"presentation"` or `"none"`), which indicates the element should be
@@ -8,6 +8,18 @@ import type { ARIAVersion } from '../../types/index.js';
  * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
  */
 export declare function isPresentational(roleName?: string): boolean;
+/**
+ * Determines whether an element is exposed with the `none` or `presentation`
+ * role that its author specified, after the Presentational Roles Conflict
+ * Resolution. The implicit `presentation` role of `<img alt="">` does not count:
+ * HTML-AAM gives that image no name by its own rule.
+ *
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ *
+ * @param computed - The computed role of the element
+ * @returns `true` if the computed role is an explicit presentational role
+ */
+export declare function isExposedAsPresentational(computed: ComputedRole): boolean;
 /**
  * Determines whether a given role is transparent for ownership traversal.
  *

package/lib/algorithm/aria/is-presentational.js

@@ -12,6 +12,20 @@ export function isPresentational(roleName) {
     }
     return ['presentation', 'none'].includes(roleName);
 }
+/**
+ * Determines whether an element is exposed with the `none` or `presentation`
+ * role that its author specified, after the Presentational Roles Conflict
+ * Resolution. The implicit `presentation` role of `<img alt="">` does not count:
+ * HTML-AAM gives that image no name by its own rule.
+ *
+ * @see https://w3c.github.io/accname/#comp_host_language_label
+ *
+ * @param computed - The computed role of the element
+ * @returns `true` if the computed role is an explicit presentational role
+ */
+export function isExposedAsPresentational(computed) {
+    return !!computed.role && !computed.role.isImplicit && isPresentational(computed.role.name);
+}
 /**
  * Determines whether a given role is transparent for ownership traversal.
  *

package/lib/types/index.d.ts

@@ -329,6 +329,10 @@ export type Matches = (selector: string) => boolean;
  * The result of computing an element's ARIA role, containing the element reference,
  * the resolved role specification (or null if no role applies), and an optional
  * error type indicating issues during role computation.
+ *
+ * An error type does not mean the role was dropped: with `NO_PERMITTED` (a role
+ * ARIA in HTML does not permit on the element) the `role` is the one the author
+ * specified, as user agents still expose it.
  */
 export type ComputedRole = {
     readonly el: Element;

package/lib/utils/directive-resolver.js

@@ -29,7 +29,7 @@ compiledPatterns) {
         }
         let potentialName;
         if (pattern.potentialName != null) {
-            potentialName = pattern.potentialName.replaceAll(/\$(\d+)/g, (_, idx) => (match[Number(idx)] ?? '').toLowerCase());
+            potentialName = pattern.potentialName.replaceAll(/\$(\d+)/g, (_, idx) => match[Number(idx)] ?? '');
         }
         let isDuplicatable;
         if (pattern.isDuplicatable === true) {

package/lib/utils/get-spec-by-tag-name.d.ts

@@ -2,7 +2,8 @@ import type { ElementSpec } from '../types/index.js';
 /**
  * Looks up an element specification by its local tag name and namespace. The tag name
  * is resolved to a namespace-qualified form (e.g., `"svg:circle"`) before searching.
- * Results are cached by the namespace-qualified name for subsequent lookups.
+ * Results are cached by the namespace-qualified name for subsequent lookups in the same
+ * list of specs.
  *
  * @template K - The keys of `ElementSpec` to include in the returned spec object (defaults to all keys)
  * @param specs - The array of element specifications to search

package/lib/utils/get-spec-by-tag-name.js

@@ -1,9 +1,16 @@
 import { resolveNamespace } from './resolve-namespace.js';
-const cache = new Map();
+/**
+ * The results, for each list of specs it was searched in. A list is not told what another has:
+ * `permitted-contents` searches the specs of the document plus the `tag` rules of its option, which
+ * a lookup made in the specs of the document alone must not hide (nor the other way round). A list
+ * that nothing refers to any more takes its results with it.
+ */
+const caches = new WeakMap();
 /**
  * Looks up an element specification by its local tag name and namespace. The tag name
  * is resolved to a namespace-qualified form (e.g., `"svg:circle"`) before searching.
- * Results are cached by the namespace-qualified name for subsequent lookups.
+ * Results are cached by the namespace-qualified name for subsequent lookups in the same
+ * list of specs.
  *
  * @template K - The keys of `ElementSpec` to include in the returned spec object (defaults to all keys)
  * @param specs - The array of element specifications to search
@@ -13,6 +20,11 @@ const cache = new Map();
  */
 export function getSpecByTagName(specs, localName, namespace) {
     const { localNameWithNS } = resolveNamespace(localName, namespace ?? undefined);
+    let cache = caches.get(specs);
+    if (!cache) {
+        cache = new Map();
+        caches.set(specs, cache);
+    }
     let spec = cache.get(localNameWithNS);
     if (spec !== undefined) {
         return spec;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "5.2.0",
+	"version": "5.4.0",
 	"description": "Types and schema that specs of the Markup languages for markuplint",
 	"repository": {
 		"type": "git",
@@ -15,8 +15,8 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
 		}
 	},
 	"publishConfig": {
@@ -36,14 +36,14 @@
 		"schema:aria": "npx json2ts ./schemas/aria.schema.json --cwd ./schemas > ./src/types/aria.ts"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.1.1",
-		"@markuplint/types": "5.2.0",
+		"@markuplint/ml-ast": "5.3.0",
+		"@markuplint/types": "5.4.0",
 		"is-plain-object": "^5.1.0",
 		"type-fest": "^5.10.0"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "5.2.0",
-		"json-schema-to-typescript": "15.0.4"
+		"@markuplint/test-tools": "5.4.0",
+		"json-schema-to-typescript": "16.0.0"
 	},
-	"gitHead": "d8b2feab77c9c862513615bea6b80d2817431878"
+	"gitHead": "ab56aa8e12b67fbf793ddf1267aaba9fda90269d"
 }