@markuplint/ml-spec 4.10.2 → 5.0.0-alpha.0

package/docs/aria-algorithms.md

@@ -9,7 +9,7 @@ The implementation covers algorithms from the following specifications:
 - **WAI-ARIA 1.1 / 1.2 / 1.3** -- Role definitions, states, and properties
 - **HTML-AAM** (HTML Accessibility API Mappings) -- Implicit role mappings for HTML elements
 - **SVG-AAM** (SVG Accessibility API Mappings) -- Accessibility tree inclusion rules for SVG
-- **AccName 1.1** (Accessible Name and Description Computation) -- Accessible name computation
+- **AccName 1.2** (Accessible Name and Description Computation) -- Accessible name computation
 - **ARIA in HTML** -- Permitted roles and ARIA attribute constraints per element
 
 ### Design Principles
@@ -19,7 +19,7 @@ All ARIA algorithm functions share a consistent design:
 - They operate on the standard DOM `Element` interface, requiring no markuplint-specific node types.
 - They accept an `MLMLSpec` parameter containing the full markup language specification data.
 - They accept an `ARIAVersion` parameter (`'1.1'`, `'1.2'`, or `'1.3'`) to select version-specific behavior.
-- They are pure functions with no side effects (aside from internal caching in `getARIA`).
+- They are pure functions with no side effects (aside from internal caching in `getARIA` and a reentrant guard in `getAccname`).
 
 ## Role Computation Pipeline
 
@@ -39,7 +39,7 @@ flowchart TB
     GCR --> CR{Computed Role}
     CR -->|presentational| PCR["Presentational Roles<br/>Conflict Resolution"]
 
-    PCR --> Check1["1. Required Context Role<br/>validation"]
+    PCR --> Check1["1. Required Accessibility<br/>Parent Role validation"]
     PCR --> Check2["2. SVG accessibility<br/>tree inclusion"]
     PCR --> Check3["3. Interactive element<br/>protection"]
     PCR --> Check4["4. Required owned element<br/>check"]
@@ -86,13 +86,13 @@ The core function of the ARIA algorithm suite. It computes the final ARIA role f
 
 **Conflict Resolution checks (in order):**
 
-1. **Required context role validation** -- If the role has `requiredContextRole` entries, the function checks the parent hierarchy. If no parent element exists, returns `NO_OWNER`. If the parent hierarchy does not satisfy the context role conditions (via `matchesContextRole()`), returns `INVALID_REQUIRED_CONTEXT_ROLE`. Presentational ancestors are traversed transparently via `getNonPresentationalAncestor()`.
+1. **Required context role validation** -- If the role has `requiredAccessibilityParentRole` entries (called `requiredContextRole` in ARIA 1.2), the function checks the parent hierarchy. If no parent element exists, returns `NO_OWNER`. If the parent hierarchy does not satisfy the context role conditions (via `matchesContextRole()`), returns `INVALID_REQUIRED_CONTEXT_ROLE`. Presentational ancestors are traversed transparently via `getNonPresentationalAncestor()`.
 
-2. **SVG accessibility tree inclusion** -- For SVG namespace elements without a valid explicit role, the function checks whether the element has an accessible name (via `getAccname()`) or a `<title>`/`<desc>` child element. If neither exists, the SVG element is excluded from the accessibility tree (returns `role: null`). This implements the SVG-AAM rules for including normally-omitted SVG elements.
+2. **SVG accessibility tree inclusion** -- For SVG namespace elements without a valid explicit role, the function checks whether the element has an accessible name source (via `hasSvgAccessibleNameSource()`) — i.e., `aria-label`, `aria-labelledby`, or a `<title>`/`<desc>` child element. If none exists, the SVG element is excluded from the accessibility tree (returns `role: null`). This implements the SVG-AAM rules for including normally-omitted SVG elements.
 
 3. **Interactive element protection** -- Focusable elements cannot be presentational. The function checks `mayBeFocusable()` and ensures the element is not `disabled`, `inert`, or `hidden` (traversing ancestors for each attribute). If the element is interactive and not disabled/inert/hidden, the presentational role is overridden with the implicit role and `INTERACTIVE_ELEMENT_MUST_NOT_BE_PRESENTATIONAL` error.
 
-4. **Required owned element check** -- If a non-presentational ancestor has `requiredOwnedElements` and the current element's implicit role matches one of those required owned elements, the presentational role is overridden. Returns `REQUIRED_OWNED_ELEMENT_MUST_NOT_BE_PRESENTATIONAL`.
+4. **Required owned element check** -- If a non-presentational ancestor has `allowedAccessibilityChildRoles` (called `requiredOwnedElements` in ARIA 1.2) and the current element's implicit role matches one of those required owned elements, the presentational role is overridden. Returns `REQUIRED_OWNED_ELEMENT_MUST_NOT_BE_PRESENTATIONAL`.
 
 5. **Global ARIA property check** -- If the element has any global ARIA properties (e.g., `aria-label`, `aria-describedby`), the presentational role is overridden with the implicit role. Returns `GLOBAL_PROP_MUST_NOT_BE_PRESENTATIONAL`.
 
@@ -242,12 +242,12 @@ The spec-level implementation for computing permitted ARIA roles. Operates on ta
 
 | `permittedRoles` value        | Behavior                                                                                                                 |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `true`                        | All non-abstract roles from the ARIA spec are permitted.                                                                 |
+| `true`                        | All non-abstract roles from the ARIA spec (including DPub roles) are permitted.                                          |
 | `PermittedARIAAAMInfo` object | If `core-aam` is `true`, adds all non-abstract roles. If `graphics-aam` is `true`, adds all non-abstract graphics roles. |
 | Array of strings/objects      | The specific listed roles are permitted.                                                                                 |
 | `false`                       | No roles are permitted (empty list before implicit role).                                                                |
 
-4. Always includes the implicit role in the result. If the implicit role is `"presentation"` or `"none"`, both equivalents are included.
+4. Always includes the implicit role in the result. If the implicit role is `"presentation"` or `"none"`, both equivalents are included. In ARIA 1.3, if the implicit role is `"img"` or `"image"`, both synonyms are included.
 5. Returns the merged, deduplicated list.
 
 ---
@@ -273,9 +273,10 @@ Retrieves the full ARIA role specification for a given role name, including the
 
 1. Searches for the role by name in the ARIA roles list for the given version.
 2. For SVG namespace (`http://www.w3.org/2000/svg`), also searches `graphicsRoles` if not found in core roles.
-3. Recursively traverses super-class roles via the `generalization` property, building the complete inheritance chain.
-4. Normalizes all optional fields to non-undefined defaults (e.g., `!!role.isAbstract`, `role.requiredContextRole ?? []`).
-5. Returns `null` if the role name does not exist in the spec.
+3. If still not found, searches `dpubRoles` (DPub ARIA roles are accepted for all elements regardless of namespace).
+4. Recursively traverses super-class roles via the `generalization` property, building the complete inheritance chain.
+5. Normalizes all optional fields to non-undefined defaults (e.g., `!!role.isAbstract`). Resolves `requiredAccessibilityParentRole` from the schema's `requiredContextRole` (ARIA 1.2 name) or `requiredAccessibilityParentRole` (ARIA 1.3 name), and similarly `allowedAccessibilityChildRoles` from `requiredOwnedElements` or `allowedAccessibilityChildRoles`. Both the new and deprecated property names are populated with the same values.
+6. Returns `null` if the role name does not exist in the spec.
 
 **Normalized fields in the return value:**
 
@@ -284,8 +285,10 @@ Retrieves the full ARIA role specification for a given role name, including the
   name: string;
   isAbstract: boolean;          // default: false
   deprecated: boolean;          // default: false
-  requiredContextRole: string[];     // default: []
-  requiredOwnedElements: string[];   // default: []
+  requiredAccessibilityParentRole: string[];  // default: []
+  allowedAccessibilityChildRoles: string[];   // default: []
+  requiredContextRole: string[];     // @deprecated alias — same as requiredAccessibilityParentRole
+  requiredOwnedElements: string[];   // @deprecated alias — same as allowedAccessibilityChildRoles
   accessibleNameRequired: boolean;   // default: false
   accessibleNameFromAuthor: boolean; // default: false
   accessibleNameFromContent: boolean;// default: false
@@ -322,7 +325,7 @@ Gets the version-resolved ARIA specification for an element, evaluating conditio
 1. Calls `getVersionResolvedARIA()` which:
    - Looks up the element spec by tag name and namespace.
    - Applies `resolveVersion()` to merge version-specific overrides on top of the base ARIA spec.
-   - Optimizes permitted roles: if `"presentation"` is in the permitted roles array, `"none"` is added, and vice versa (per WAI-ARIA 1.2 note on the `none` role).
+   - Optimizes permitted roles: if `"presentation"` is in the permitted roles array, `"none"` is added, and vice versa (per WAI-ARIA 1.2 note on the `none` role). In ARIA 1.3, if `"image"` is present, `"img"` is added, and vice versa (per the ARIA 1.3 `image`/`img` synonym).
    - Caches results by `localName + namespace + version`.
 
 2. Evaluates conditional overrides (the `conditions` block in the ARIA spec):
@@ -386,25 +389,140 @@ Returns an empty record if the element has no computed role.
 
 ---
 
-### 10. `getAccname(el): string`
+### 10. `getAccname(el, specs, version): string`
 
 **Source:** `src/algorithm/aria/accname-computation.ts`
 
-Computes the accessible name for an element using the WAI-ARIA Accessible Name and Description Computation algorithm.
+Computes the accessible name for a DOM element using the HTML-AAM §4.1 algorithm. This is the public facade that creates a DOM-based resolver and delegates to the pure `computeAccessibleName()` function.
 
 **Parameters:**
 
-| Parameter | Type      | Description     |
-| --------- | --------- | --------------- |
-| `el`      | `Element` | The DOM element |
+| Parameter | Type          | Description                                     |
+| --------- | ------------- | ----------------------------------------------- |
+| `el`      | `Element`     | The DOM element                                 |
+| `specs`   | `MLMLSpec`    | The full markup language specification          |
+| `version` | `ARIAVersion` | The ARIA specification version for role queries |
 
 **Returns:** `string` -- the computed accessible name, or an empty string if none is found.
 
-**Algorithm:**
+**Architecture:**
+
+The implementation is split into two layers:
+
+- **`accname-computation.ts`** (facade): Creates a DOM-based `AccnameResolver`, handles reentrant guard for `:aria(has name)` selector cycles, and delegates to the pure algorithm.
+- **`accname/compute.ts`** (pure algorithm): Implements Steps 2A–2I of AccName 1.2 §4.3.2 using only the `AccnameElement` and `AccnameResolver` interfaces, with no dependency on the DOM or markuplint types.
+
+**Algorithm (AccName 1.2 §4.3.2):**
+
+1. **Step 2A — Hidden check:** If the element is hidden and not referenced by `aria-labelledby`, return empty.
+2. **Step 2B – `aria-labelledby`:** Resolve referenced elements, compute their names recursively (with cycle prevention via visited set).
+3. **Step 2D – `aria-label`:** Use the `aria-label` attribute value if non-empty.
+4. **Step 2E – Element-specific name:** Apply HTML-AAM §4.1 rules (label association, `<img alt>`, `<input value>`, `<fieldset>` legend, `<table>` caption, SVG `<title>`, etc.).
+5. **Step 2F – Name from content:** If the element's role allows name-from-content, or the element is referenced by `aria-labelledby`, recursively collect text from child nodes (with embedded control value extraction per Step 2C).
+6. **Step 2I – Title fallback:** Use the `title` attribute value.
+
+**Reentrant guard:** `getAccname` uses a `WeakSet<Element>` to prevent infinite recursion when `getComputedRole` evaluates `:aria(has name)` selectors that call back into `getAccname`.
+
+#### AccName Algorithm Control Flow
+
+The following diagram shows the full control flow of the accessible name computation algorithm, mapping each step to its implementation file.
+
+```mermaid
+flowchart TB
+    Start([Element]) --> Facade["getAccname()\n<i>accname-computation.ts</i>"]
+    Facade --> Guard{"Reentrant\nguard?"}
+    Guard -->|"Already computing"| Empty(["Return ''"])
+    Guard -->|"First call"| Resolver["createDomResolver()\n<i>accname-computation.ts</i>"]
+    Resolver --> Compute["computeAccessibleName()\n<i>compute.ts</i>"]
+
+    Compute --> Hidden{"Hidden &\nnot in\nlabelledby?"}
+    Hidden -->|Yes| EmptyResult(["Return empty"])
+    Hidden -->|No| Precomp{"getPrecomputedName?\n<i>[Implementation-specific]</i>"}
+
+    Precomp -->|"Has value"| PrecompResult(["Return precomputed name"])
+    Precomp -->|"No"| Step2B
+
+    subgraph step2b ["Step 2B — aria-labelledby (aria-steps.ts)"]
+        Step2B{"aria-labelledby\npresent &\nnot in labelledby\ntraversal?"}
+        Step2B -->|Yes| SplitIDs["Split IDREFs by whitespace"]
+        SplitIDs --> ForEachID["For each IDREF:\n• Skip visited (allow self-ref)\n• getElementById()\n• Recurse with inLabelledby=true"]
+        ForEachID --> JoinParts["Join parts with space"]
+    end
+
+    Step2B -->|"No / empty"| Step2D
+    JoinParts -->|"Has name"| LabelledbyResult(["Return name\nsource: aria-labelledby"])
+
+    subgraph step2d ["Step 2D — aria-label (aria-steps.ts)"]
+        Step2D{"aria-label\nnon-empty?"}
+    end
+
+    Step2D -->|Yes| AriaLabelResult(["Return name\nsource: aria-label"])
+    Step2D -->|No| Step2E
+
+    subgraph step2e ["Step 2E — Element-specific (element-names.ts)"]
+        Step2E["getElementSpecificName()"]
+        Step2E --> Dispatch{"Element\ntype?"}
+        Dispatch -->|"SVG"| SVGTitle["SVG: title child\n<i>SVG-AAM §8.1</i>"]
+        Dispatch -->|"input"| InputType["Input: branch by type\n<i>HTML-AAM §4.1</i>"]
+        Dispatch -->|"button"| BtnLabel["Label → content\n<i>HTML-AAM §4.1</i>"]
+        Dispatch -->|"fieldset"| Legend["Legend content\n<i>HTML-AAM §4.1</i>"]
+        Dispatch -->|"table"| Caption["Caption content\n<i>HTML-AAM §4.1</i>"]
+        Dispatch -->|"img"| ImgAlt["alt attr\n<i>HTML-AAM §4.1</i>"]
+        Dispatch -->|"Other"| LabelAssoc["label-steps.ts:\nLabel association\n<i>for= / ancestor</i>"]
+    end
+
+    Step2E -->|"Has name"| ElementResult(["Return name\nsource: element-specific"])
+    Step2E -->|"null"| Step2F
+
+    subgraph step2f ["Step 2F/2C — Name from content (helpers.ts)"]
+        Step2F{"Role allows\nnameFrom: content\nOR in labelledby\ntraversal?"}
+        Step2F -->|Yes| WalkChildren["resolveNameFromContent():\nFor each child node:"]
+        WalkChildren --> ChildType{"Node\ntype?"}
+        ChildType -->|"Text"| TextContent["Use textContent"]
+        ChildType -->|"Embedded\ncontrol"| EmbedValue["getEmbeddedControlValue()\n<i>AccName §4.3.2 Step 2C</i>"]
+        ChildType -->|"Element"| RecurseChild["Recurse computeFn();\nif no name → collectTextContent()\n<i>[Implementation-specific]</i>"]
+        TextContent --> JoinSpaces["Join with space"]
+        EmbedValue --> JoinSpaces
+        RecurseChild --> JoinSpaces
+    end
+
+    Step2F -->|"No"| Step2I
+    JoinSpaces -->|"Has name"| ContentResult(["Return name\nsource: content"])
+    JoinSpaces -->|"Empty"| Step2I
+
+    subgraph step2i ["Step 2I — Title fallback"]
+        Step2I{"title attr\nnon-empty?"}
+    end
+
+    Step2I -->|Yes| TitleResult(["Return name\nsource: title"])
+    Step2I -->|No| FinalEmpty(["Return empty"])
+```
+
+#### W3C Specification References
+
+| Spec                                                | Section            | Description                                       |
+| --------------------------------------------------- | ------------------ | ------------------------------------------------- |
+| [AccName 1.2](https://www.w3.org/TR/accname-1.2/)   | §4.3.2             | Computation Steps (Steps 2A–2I)                   |
+| [HTML-AAM 1.0](https://www.w3.org/TR/html-aam-1.0/) | §4.1               | Accessible Name and Description Computation       |
+| [HTML-AAM 1.0](https://www.w3.org/TR/html-aam-1.0/) | §4.1 (per element) | Element-specific name computation rules           |
+| [SVG-AAM 1.0](https://www.w3.org/TR/svg-aam-1.0/)   | §5.1.1, §8.1       | SVG accessibility tree inclusion and name mapping |
+
+#### Implementation-Specific Extensions
+
+The following behaviors extend beyond the strict AccName specification:
 
-1. Delegates to `computeAccessibleName()` from the `dom-accessibility-api` library, which implements the full AccName 1.1 algorithm.
-2. **Fallback for `<input>` elements:** If the computed name is empty (after trimming), returns the `placeholder` attribute value (trimmed).
-3. Returns an empty string if no name is found through any method.
+| Extension                                            | Location                 | Rationale                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pre-computed name (`getPrecomputedName`)             | `compute.ts`             | Supports ml-core's Pretender integration for framework components                                                                                                                                                                                                                                                                            |
+| Transparent text collection (`collectTextContent`)   | `helpers.ts`             | Collects text from intermediate elements (e.g., `<span>` inside `<button>`) whose roles do not include `nameFrom: ["content"]`                                                                                                                                                                                                               |
+| `<select>` selected option (`getSelectedOptionText`) | `helpers.ts`             | Static approximation of selected option text via `selected` attribute. Customizable `<select>` ([#2069](https://github.com/markuplint/markuplint/issues/2069)) will require: (1) `collectOptions` to skip new child types (`<button>`, `<datalist>`, `<selectedcontent>`), (2) evaluate whether `<selectedcontent>` affects name computation |
+| Reentrant guard (`computingElements` WeakSet)        | `accname-computation.ts` | Prevents infinite recursion from `:aria(has name)` pseudo-class in `getComputedRole` → `getARIA` → `matches` chain                                                                                                                                                                                                                           |
+
+#### Known Limitations
+
+| Limitation                                   | AccName Reference | Description                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CSS-generated content (`::before`/`::after`) | §4.3.2 Step 2G    | The AccName spec requires CSS-generated textual content (via the `content` property on `::before`/`::after` pseudo-elements) to be included in the accumulated text. Markuplint performs static HTML analysis without CSS processing, so this content is unavailable at lint time. Elements relying solely on CSS-generated content for their accessible name will not be detected. |
 
 ---
 
@@ -448,19 +566,19 @@ Determines whether an element is included in (exposed to) the Accessibility Tree
 
 **Source:** `src/algorithm/aria/has-required-owned-elements.ts`
 
-Two related functions for validating the "Required Owned Elements" constraint.
+Two related functions for validating the "Allowed Accessibility Child Roles" constraint (called "Required Owned Elements" in ARIA 1.2).
 
 #### `hasRequiredOwnedElement`
 
-Checks whether an element satisfies the required owned elements constraint defined by its computed role.
+Checks whether an element satisfies the "Allowed Accessibility Child Roles" constraint defined by its computed role.
 
 **Algorithm:**
 
 1. If the element has an `aria-owns` attribute, returns `true` (partial support -- the referenced elements are not validated).
 2. Computes the element's role via `getComputedRole()`.
-3. If the role has no `requiredOwnedElements`, returns `true`.
-4. Traverses the element's closest non-presentational descendants (children, transparently passing through presentational elements).
-5. For each required owned element pattern, checks if any descendant matches via `isRequiredOwnedElement()`.
+3. If the role has no `allowedAccessibilityChildRoles`, returns `true`.
+4. Traverses the element's closest non-presentational descendants (children, transparently passing through elements with ownership-transparent roles via `isTransparentForOwnership()`). In ARIA 1.3, `generic` elements are additionally transparent.
+5. For each allowed accessibility child role pattern, checks if any descendant matches via `isRequiredOwnedElement()`.
 
 #### `isRequiredOwnedElement`
 
@@ -478,7 +596,7 @@ Determines whether an element matches a required owned element query.
 
 **Query syntax:** Supports chains with `>` notation. For example, `"group > listitem"` means the element must have role `"group"` and contain a descendant with role `"listitem"`.
 
-**Spec issue:** The WAI-ARIA specification has not decided whether "owned" means child or descendant. This implementation interprets "owned" as **child** (not descendant), to align with HTML semantics. Presentational children are traversed transparently.
+**Ownership traversal:** In ARIA 1.1/1.2, the spec had not decided whether "owned" means child or descendant. This implementation interprets "owned" as **child** (not descendant), to align with HTML semantics. `presentation`/`none` children are traversed transparently. ARIA 1.3 formally resolves this with the definitions of "accessibility child" and "accessibility parent", and additionally makes `generic` elements transparent (via `isTransparentForOwnership()`).
 
 ---
 
@@ -507,6 +625,8 @@ Validates whether an element's parent hierarchy satisfies at least one of the re
 4. For each level, calls `getComputedRole()` with `assumeSingleNode = true` to get the parent's role independently.
 5. Returns `true` if any condition string fully matches the ancestor chain.
 
+**ARIA 1.3 transparency:** In ARIA 1.3+, parent elements with `generic` or `none` roles are transparently skipped during matching (via `isTransparentForOwnership()`). In ARIA 1.1/1.2, parents are matched strictly without skipping.
+
 **Example:** For a `listitem` role with `requiredContextRole: ["list", "list > group"]`:
 
 - `"list"` matches if the parent has the `list` role.
@@ -557,13 +677,39 @@ Traverses the parent element chain to find the nearest ancestor with a non-prese
 
 1. Starts from `el.parentElement`.
 2. For each ancestor, computes the role via `getComputedRole()`.
-3. If the ancestor's role is not presentational, returns that ancestor's computed role.
+3. If the ancestor's role is not transparent for ownership traversal (via `isTransparentForOwnership()`), returns that ancestor's computed role.
 4. Otherwise, continues to the next parent.
 5. If no non-presentational ancestor is found, returns `{ el: null, role: null }`.
 
+**ARIA 1.3 transparency:** In ARIA 1.3, `generic` role elements are additionally skipped (alongside `presentation`/`none`), per the WAI-ARIA definitions of "accessibility child" and "accessibility parent".
+
+---
+
+### 16. `isTransparentForOwnership(roleName, version): boolean`
+
+**Source:** `src/algorithm/aria/is-presentational.ts`
+
+Determines whether a given role is transparent for ownership traversal. Used by `getNonPresentationalAncestor`, `getClosestNonPresentationalDescendants`, and `matchesContextRole` to decide which elements to skip.
+
+**Parameters:**
+
+| Parameter  | Type                  | Description                    |
+| ---------- | --------------------- | ------------------------------ |
+| `roleName` | `string \| undefined` | The ARIA role name to check    |
+| `version`  | `ARIAVersion`         | The ARIA specification version |
+
+**Returns:** `true` if the role should be skipped during ownership traversal.
+
+**Version behavior:**
+
+| ARIA Version     | Transparent roles                 |
+| ---------------- | --------------------------------- |
+| `'1.1'`, `'1.2'` | `presentation`, `none`            |
+| `'1.3'`          | `presentation`, `none`, `generic` |
+
 ---
 
-### 16. `ariaSpecs(specs, version)`
+### 17. `ariaSpecs(specs, version)`
 
 **Source:** `src/algorithm/aria/aria-specs.ts`
 
@@ -576,9 +722,9 @@ A simple accessor function that retrieves the ARIA specification data for a spec
 | `specs`   | `MLMLSpec`    | The full markup language specification |
 | `version` | `ARIAVersion` | The ARIA specification version         |
 
-**Returns:** `{ roles: ARIARoleInSchema[], graphicsRoles: ARIARoleInSchema[], props: ARIAProperty[] }`
+**Returns:** `{ roles: ARIARoleInSchema[], graphicsRoles: ARIARoleInSchema[], dpubRoles: ARIARoleInSchema[], props: ARIAProperty[] }`
 
-**Implementation:** Returns `specs.def['#aria'][version]`, providing direct access to the roles, graphics roles, and properties defined for the requested ARIA version.
+**Implementation:** Returns `specs.def['#aria'][version]`, providing direct access to the roles, graphics roles, DPub roles, and properties defined for the requested ARIA version.
 
 ## RoleComputationError Reference
 
@@ -636,6 +782,8 @@ This design allows the schema to define a base ARIA spec that works across versi
 ### Version Impact on Behavior
 
 - **`getNonPresentationalAncestor`**: In ARIA 1.1/1.2, ancestor role computation uses full context (`assumeSingleNode = false`). In ARIA 1.3+, each ancestor is computed independently (`assumeSingleNode = true`).
+- **`isTransparentForOwnership`**: In ARIA 1.1/1.2, only `presentation`/`none` are transparent. In ARIA 1.3, `generic` is additionally transparent per the WAI-ARIA definitions of "accessibility child" and "accessibility parent".
+- **`matchesContextRole`**: In ARIA 1.1/1.2, parent elements are matched strictly. In ARIA 1.3+, `generic`/`none` parents are transparently skipped.
 - **`namingProhibited`**: Only applicable in ARIA 1.2 and later. Version 1.1 always uses the base value.
 - **Role and property definitions**: The available roles and their properties may differ across versions (e.g., new roles added in 1.2 or 1.3).
 
@@ -646,6 +794,7 @@ The ARIA algorithms implement behavior defined in the following W3C specificatio
 - [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/) -- Accessible Rich Internet Applications, primary reference
 - [WAI-ARIA 1.1](https://www.w3.org/TR/wai-aria-1.1/) -- Previous version, still supported
 - [HTML-AAM 1.0](https://www.w3.org/TR/html-aam-1.0/) -- HTML Accessibility API Mappings (implicit role mappings)
-- [AccName 1.1](https://www.w3.org/TR/accname-1.1/) -- Accessible Name and Description Computation
+- [AccName 1.2](https://www.w3.org/TR/accname-1.2/) -- Accessible Name and Description Computation
 - [SVG-AAM 1.0](https://www.w3.org/TR/svg-aam-1.0/) -- SVG Accessibility API Mappings
+- [DPub-ARIA 1.1](https://w3c.github.io/dpub-aria/) -- Digital Publishing WAI-ARIA Module (DPub roles)
 - [ARIA in HTML](https://www.w3.org/TR/html-aria/) -- Permitted roles and ARIA attribute constraints per HTML element

package/docs/html-algorithms.ja.md

@@ -79,7 +79,7 @@ function getContentModel(
 
 **動作:**
 
-1. ネストされた `Map<Specs, Map<Element, result>>` キャッシュを確認します。指定された specs 参照と要素インスタンスに対するキャッシュ結果が存在すれば、即座に返します。
+1. `WeakMap<Element, result>` キャッシュを確認します。指定された要素インスタンスに対するキャッシュ結果が存在すれば、即座に返します。
 2. `getSpec()` を使用して要素の仕様を検索します。見つからない場合、`null` をキャッシュして返します。
 3. `contentModel.conditional[]`（存在する場合）を走査します。各条件に対して `el.matches(cond.condition)` を呼び出します。
 4. 最初にマッチした条件の `contents` を返します。どの条件にもマッチしない場合、デフォルトの `contentModel.contents` を返します。
@@ -87,7 +87,7 @@ function getContentModel(
 
 **キャッシュ戦略:**
 
-キャッシュは 2 階層の `Map` です。外側のマップは `specs` 配列の参照をキーとし、内側のマップは `Element` インスタンスをキーとします。これにより、specs が変更された場合に結果が正しく無効化される一方、同じ要素に対する冗長な計算を回避できます。
+キャッシュは `Element` インスタンスをキーとする `WeakMap` です。同じ要素に対する冗長な計算を回避しつつ、要素が参照されなくなった場合（例: 再パース後）にキャッシュエントリが自動的にガベージコレクションされます。
 
 ---
 

package/docs/html-algorithms.md

@@ -79,7 +79,7 @@ function getContentModel(
 
 **Behavior:**
 
-1. Checks the nested `Map<Specs, Map<Element, result>>` cache. If a cached result exists for the given specs reference and element instance, returns it immediately.
+1. Checks the `WeakMap<Element, result>` cache. If a cached result exists for the given element instance, returns it immediately.
 2. Looks up the element's spec using `getSpec()`. If not found, caches and returns `null`.
 3. Iterates over `contentModel.conditional[]` (if present). For each condition, calls `el.matches(cond.condition)`.
 4. Returns the first matching condition's `contents`. If no condition matches, returns the default `contentModel.contents`.
@@ -87,7 +87,7 @@ function getContentModel(
 
 **Caching strategy:**
 
-The cache is a two-level `Map`: the outer map is keyed by the `specs` array reference, and the inner map is keyed by the `Element` instance. This ensures results are correctly invalidated when specs change while avoiding redundant computation for the same element.
+The cache is a `WeakMap` keyed by the `Element` instance. This avoids redundant computation for the same element while ensuring cache entries are automatically garbage-collected when elements are no longer referenced (e.g., after a re-parse).
 
 ---
 

package/docs/maintenance.ja.md

@@ -128,12 +128,13 @@ schema:json → schema:content-models → schema:attributes → schema:aria →
 
 ### テストファイル
 
-パッケージには vitest を使用する 15 のテストファイルがあります:
+パッケージには vitest を使用する 18 のテストファイルがあります:
 
-| ディレクトリ          | テストファイル数 | カバレッジ                                                                                                                                                                                                                             |
-| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/algorithm/aria/` | 11               | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
-| `src/utils/`          | 4                | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
+| ディレクトリ                  | テストファイル数 | カバレッジ                                                                                                                                                                                                                             |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/algorithm/aria/`         | 11               | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
+| `src/algorithm/aria/accname/` | 3                | `aria-steps`, `compute`, `element-names`, `label-steps`                                                                                                                                                                                |
+| `src/utils/`                  | 4                | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
 
 ### テストの実行
 
@@ -154,13 +155,12 @@ yarn test packages/@markuplint/ml-spec/src/algorithm/aria/get-computed-role.spec
 
 ### ランタイム依存
 
-| パッケージ              | バージョン | 目的                               | 更新リスク         |
-| ----------------------- | ---------- | ---------------------------------- | ------------------ |
-| `@markuplint/ml-ast`    | 4.4.10     | `NamespaceURI` 型                  | 低（内部）         |
-| `@markuplint/types`     | 4.8.1      | 属性値型の `Type` ユニオン         | 中（スキーマ参照） |
-| `dom-accessibility-api` | 0.7.1      | AccName 計算                       | 中（仕様準拠）     |
-| `is-plain-object`       | 5.0.0      | AAM 情報のプレーンオブジェクト検出 | 低（安定 API）     |
-| `type-fest`             | 4.41.0     | `ReadonlyDeep` ユーティリティ型    | 低（型のみ）       |
+| パッケージ           | バージョン | 目的                               | 更新リスク         |
+| -------------------- | ---------- | ---------------------------------- | ------------------ |
+| `@markuplint/ml-ast` | 4.4.10     | `NamespaceURI` 型                  | 低（内部）         |
+| `@markuplint/types`  | 4.8.1      | 属性値型の `Type` ユニオン         | 中（スキーマ参照） |
+| `is-plain-object`    | 5.0.0      | AAM 情報のプレーンオブジェクト検出 | 低（安定 API）     |
+| `type-fest`          | 4.41.0     | `ReadonlyDeep` ユーティリティ型    | 低（型のみ）       |
 
 ### 開発依存
 
@@ -171,7 +171,6 @@ yarn test packages/@markuplint/ml-spec/src/algorithm/aria/get-computed-role.spec
 
 ### 依存関係の更新
 
-- **`dom-accessibility-api`**: 更新により AccName 計算の動作が変わる場合があります。更新後は `accname-computation.spec.ts` テストを実行してください。
 - **`json-schema-to-typescript`**: メジャーバージョン更新により、生成される型の出力が変わる場合があります（フォーマット、optional の扱い）。更新後は `yarn workspace @markuplint/ml-spec run schema` を実行し、`src/types/*.ts` の差分を確認してください。
 - **`@markuplint/types`**: 更新後は必ず `yarn up:schema` を実行して、スキーマ参照の一貫性を確保してください。
 - **`type-fest`**: 型のみの依存です。自由に更新できますが、ビルドが成功することを確認してください（`yarn build --scope @markuplint/ml-spec`）。
@@ -278,7 +277,7 @@ W3C 仕様が更新された場合（例: WAI-ARIA 1.3 が勧告になった場
 | --------------------------------------------- | ----------------------------------------------- | -------------------------- |
 | `getARIA()` 内部キャッシュ                    | `Map`（`localName + namespace + version` キー） | プロセス再起動時のみクリア |
 | `getSpecByTagName()` キャッシュ               | `Map`（`namespace:localName` キー）             | specs インスタンスごと     |
-| `getContentModel()` キャッシュ                | `Map<Specs, Map<Element, ...>>`                 | ネスト、specs + 要素ごと   |
+| `getContentModel()` キャッシュ                | `WeakMap<Element, ...>`                         | 要素ごと、GC セーフ        |
 | `contentModelCategoryToTagNames()` キャッシュ | モジュールレベル `Map<Category, string[]>`      | グローバル、無効化なし     |
 | `getAttrSpecs()` キャッシュ                   | `WeakSet` + `Map`（スキーマごと）               | 新しいスキーマでリセット   |
 | `resolveNamespace()` キャッシュ               | モジュールレベル `Map`                          | グローバル、無効化なし     |
@@ -310,14 +309,6 @@ W3C 仕様が更新された場合（例: WAI-ARIA 1.3 が勧告になった場
 
 **対処:** 差分を注意深く確認してください。型が意味的に同等であれば、変更をコミットしてください。動作が変わった場合（例: 以前 optional だったフィールドが required になった）、`json-schema-to-typescript` のチェンジログを調査してください。
 
-### `dom-accessibility-api` 更新後のテスト失敗
-
-**症状:** `dom-accessibility-api` の更新後、`accname-computation.spec.ts` が失敗する。
-
-**原因:** ライブラリが AccName アルゴリズムの実装を更新し、計算されるアクセシブル名が変わった。
-
-**対処:** [AccName 1.1 仕様](https://www.w3.org/TR/accname-1.1/)に照らして新しい動作を確認してください。ライブラリがより仕様準拠になった場合は、テストの期待値を更新してください。
-
 ### ビルドエラー: 生成型の不一致
 
 **症状:** `src/types/aria.ts`、`attributes.ts`、`permitted-structures.ts` の型を参照する TypeScript ビルドエラー。

package/docs/maintenance.md

@@ -128,12 +128,13 @@ These files carry "DO NOT MODIFY" headers and are overwritten by the generation
 
 ### Test files
 
-The package has 15 test files using vitest:
+The package has 18 test files using vitest:
 
-| Directory             | Test files | Coverage                                                                                                                                                                                                                               |
-| --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/algorithm/aria/` | 11         | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
-| `src/utils/`          | 4          | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
+| Directory                     | Test files | Coverage                                                                                                                                                                                                                               |
+| ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/algorithm/aria/`         | 11         | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
+| `src/algorithm/aria/accname/` | 3          | `aria-steps`, `compute`, `element-names`, `label-steps`                                                                                                                                                                                |
+| `src/utils/`                  | 4          | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
 
 ### Running tests
 
@@ -154,13 +155,12 @@ Tests depend on `@markuplint/test-tools` (devDependency) which provides HTML par
 
 ### Runtime dependencies
 
-| Package                 | Version | Purpose                                | Update risk               |
-| ----------------------- | ------- | -------------------------------------- | ------------------------- |
-| `@markuplint/ml-ast`    | 4.4.10  | `NamespaceURI` type                    | Low (internal)            |
-| `@markuplint/types`     | 4.8.1   | `Type` union for attribute value types | Medium (schema reference) |
-| `dom-accessibility-api` | 0.7.1   | AccName computation                    | Medium (spec compliance)  |
-| `is-plain-object`       | 5.0.0   | Plain object detection for AAM info    | Low (stable API)          |
-| `type-fest`             | 4.41.0  | `ReadonlyDeep` utility type            | Low (types only)          |
+| Package              | Version | Purpose                                | Update risk               |
+| -------------------- | ------- | -------------------------------------- | ------------------------- |
+| `@markuplint/ml-ast` | 4.4.10  | `NamespaceURI` type                    | Low (internal)            |
+| `@markuplint/types`  | 4.8.1   | `Type` union for attribute value types | Medium (schema reference) |
+| `is-plain-object`    | 5.0.0   | Plain object detection for AAM info    | Low (stable API)          |
+| `type-fest`          | 4.41.0  | `ReadonlyDeep` utility type            | Low (types only)          |
 
 ### Dev dependencies
 
@@ -171,7 +171,6 @@ Tests depend on `@markuplint/test-tools` (devDependency) which provides HTML par
 
 ### Updating dependencies
 
-- **`dom-accessibility-api`**: Updates may change AccName computation behavior. Run `accname-computation.spec.ts` tests after updating.
 - **`json-schema-to-typescript`**: Major version updates may change generated type output (formatting, optional handling). After updating, run `yarn workspace @markuplint/ml-spec run schema` and review diffs in `src/types/*.ts`.
 - **`@markuplint/types`**: Always run `yarn up:schema` after updating to ensure schema references stay consistent.
 - **`type-fest`**: Type-only dependency. Update freely, but verify the build succeeds (`yarn build --scope @markuplint/ml-spec`).
@@ -278,7 +277,7 @@ The package uses several runtime caches that are **never invalidated during a pr
 | ---------------------------------------- | ------------------------------------------------ | ------------------------------- |
 | `getARIA()` internal cache               | `Map` keyed by `localName + namespace + version` | Cleared only on process restart |
 | `getSpecByTagName()` cache               | `Map` keyed by `namespace:localName`             | Per-specs instance              |
-| `getContentModel()` cache                | `Map<Specs, Map<Element, ...>>`                  | Nested, per-specs + per-element |
+| `getContentModel()` cache                | `WeakMap<Element, ...>`                          | Per-element, GC-safe            |
 | `contentModelCategoryToTagNames()` cache | Module-level `Map<Category, string[]>`           | Global, never invalidated       |
 | `getAttrSpecs()` cache                   | `WeakSet` + `Map` per schema                     | New schema resets cache         |
 | `resolveNamespace()` cache               | Module-level `Map`                               | Global, never invalidated       |
@@ -310,14 +309,6 @@ If you add a new algorithm function that computes expensive results, consider ad
 
 **Fix:** Review the diff carefully. If the types are semantically equivalent, commit the changes. If behavior changed (e.g., previously optional fields became required), investigate the `json-schema-to-typescript` changelog.
 
-### Test failures after `dom-accessibility-api` update
-
-**Symptom:** `accname-computation.spec.ts` fails after updating `dom-accessibility-api`.
-
-**Cause:** The library updated its AccName algorithm implementation, changing computed accessible names.
-
-**Fix:** Verify the new behavior against the [AccName 1.1 specification](https://www.w3.org/TR/accname-1.1/). If the library is now more spec-compliant, update the test expectations.
-
 ### Build error: generated type mismatch
 
 **Symptom:** TypeScript build errors referencing types in `src/types/aria.ts`, `attributes.ts`, or `permitted-structures.ts`.