@markuplint/ml-core 5.0.0-rc.2 → 5.0.0-rc.5

package/lib/ml-dom/helper/accname.js

@@ -1,14 +1,6 @@
 import { computeAccessibleName, escapeCSS, getComputedRole, EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl, } from '@markuplint/ml-spec';
 import { log } from '../../debug.js';
 const accnameLog = log.extend('accname');
-/**
- * Computes the accessible name for an MLElement using the HTML-AAM algorithm.
- * Creates an MLCore-specific resolver that bridges MLElement to the AccnameResolver interface.
- *
- * @param el - The MLElement to compute the accessible name for
- * @param version - The ARIA specification version to use for role resolution
- * @returns The computed accessible name string, or an empty string on error
- */
 export function getAccname(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {
@@ -18,8 +10,13 @@ el, version) {
     // environment differences (e.g., Deno lacking certain DOM APIs).
     // A single element's failure must not abort the entire linting process,
     // so we catch all errors and return an empty name (= "unnamed").
-    // This is an intentional exception to the Tier 1 re-throw policy — see
-    // docs/architectures/ERROR-HANDLING.md § "accname computation errors".
+    // This is an intentional exception to the Tier 1 re-throw policy (see
+    // `isFatalError()` in `@markuplint/shared`): Tier-1-shaped errors here
+    // can be caused by the runtime environment, not only implementation bugs.
+    // The empty-string result is not converted to a violation either — a
+    // single element's accname failure must not create noise across
+    // unrelated rules, and "unnamed" still drives meaningful a11y rule
+    // violations downstream.
     try {
         const resolver = createMLCoreResolver(el, version);
         const result = computeAccessibleName(el, resolver);

package/lib/ml-dom/node/attr.js

@@ -131,7 +131,9 @@ export class MLAttr extends MLNode {
                 this.isDirective = this._astToken.isDirective;
                 this.isDuplicatable = this._astToken.isDuplicatable;
             }
-            // IDL attribute resolution (after directivePatterns)
+            // IDL attribute resolution (after directivePatterns).
+            // Performed in the core, not in each parser: any spec opting in via
+            // `acceptedAttrNames` shares the same IDL-to-content-attribute mapping.
             if (ownElement.ownerMLDocument.specs.acceptedAttrNames && !this.isDirective) {
                 const { contentAttrName, idlPropName } = searchIDLAttribute(this.#potentialName);
                 if (contentAttrName && contentAttrName !== this.#potentialName) {

package/lib/ml-dom/node/block.d.ts

@@ -9,6 +9,12 @@ import { MLNode } from './node.js';
  * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
+ * Serves as the bridge between template syntax and HTML content model
+ * validation: transparency keeps the wrapper invisible to DOM traversal so
+ * rules such as `permitted-contents` see the effective HTML children, while
+ * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
+ * rendering branch.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  */

package/lib/ml-dom/node/block.js

@@ -5,6 +5,12 @@ import { MLNode } from './node.js';
  * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
+ * Serves as the bridge between template syntax and HTML content model
+ * validation: transparency keeps the wrapper invisible to DOM traversal so
+ * rules such as `permitted-contents` see the effective HTML children, while
+ * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
+ * rendering branch.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  */

package/lib/ml-dom/node/child-node.d.ts

@@ -15,13 +15,4 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
  * @see https://dom.spec.whatwg.org/#idl-index
  */
 export type MLChildNode<T extends RuleConfigValue, O extends PlainData = undefined> = MLDocumentType<T, O> | MLCharacterData<T, O> | MLElement<T, O> | MLBlock<T, O>;
-/**
- * Determines whether the given node is a child node type
- * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
- *
- * @template T - The rule configuration value type
- * @template O - The rule options type
- * @param node - The node to check
- * @returns True if the node is one of the child node types
- */
 export declare function isChildNode<T extends RuleConfigValue, O extends PlainData = undefined>(node: MLNode<T, O>): node is MLChildNode<T, O>;

package/lib/ml-dom/node/child-node.js

@@ -1,12 +1,3 @@
-/**
- * Determines whether the given node is a child node type
- * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
- *
- * @template T - The rule configuration value type
- * @template O - The rule options type
- * @param node - The node to check
- * @returns True if the node is one of the child node types
- */
 export function isChildNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node) {

package/lib/ml-dom/node/document.d.ts

@@ -10,7 +10,7 @@ import type { Ruleset } from '../../ruleset/index.js';
 import type { MLSchema } from '../../types.js';
 import type { Walker } from '../helper/walkers.js';
 import type { MLToken } from '../token/token.js';
-import type { EndTagType, MLASTDocument, MLASTNodeTreeItem } from '@markuplint/ml-ast';
+import type { EndTagType, MLASTDocument, MLASTNodeTreeItem, MLASTParseError } from '@markuplint/ml-ast';
 import type { PlainData, Pretender, RuleCommonSettings, RuleConfigValue } from '@markuplint/ml-config';
 import type { ARIAVersion, MLMLSpec } from '@markuplint/ml-spec';
 import { MLParentNode } from './parent-node.js';
@@ -250,6 +250,25 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     get dir(): string;
+    /**
+     * Non-fatal parser conformance errors collected during tokenisation by
+     * the underlying parser (currently `@markuplint/html-parser` and the
+     * template-engine parsers that delegate to it). Empty array when the
+     * parser does not produce events or the source had none.
+     *
+     * Rules that have claimed responsibility for parse5 events via
+     * `meta.mirrorsParseErrorCodes` typically read this array to surface
+     * the corresponding violations themselves. `character-reference` is the
+     * canonical example: its self-detection covers unescaped `<`, `>`, `&`,
+     * `"` (the "missed escape" direction), and reading `parseErrors` adds
+     * coverage for parse5's malformed-reference codes (`&xyz;`, etc.) under
+     * the same rule id.
+     *
+     * ml-core's built-in parse-error channel suppresses the mirrored codes
+     * unconditionally — so the rule that reads them here is the only place
+     * the user sees the violation.
+     */
+    get parseErrors(): readonly MLASTParseError[];
     /**
      * @implements DOM API: `Document`
      */

package/lib/ml-dom/node/document.js

@@ -48,9 +48,6 @@ export class MLDocument extends MLParentNode {
      * @default "omittable"
      */
     endTag;
-    /**
-     * The file path of the source document, if available.
-     */
     #astNodeMap;
     #filename;
     /**
@@ -332,6 +329,27 @@ export class MLDocument extends MLParentNode {
     get dir() {
         throw new UnexpectedCallError('Not supported "dir" property');
     }
+    /**
+     * Non-fatal parser conformance errors collected during tokenisation by
+     * the underlying parser (currently `@markuplint/html-parser` and the
+     * template-engine parsers that delegate to it). Empty array when the
+     * parser does not produce events or the source had none.
+     *
+     * Rules that have claimed responsibility for parse5 events via
+     * `meta.mirrorsParseErrorCodes` typically read this array to surface
+     * the corresponding violations themselves. `character-reference` is the
+     * canonical example: its self-detection covers unescaped `<`, `>`, `&`,
+     * `"` (the "missed escape" direction), and reading `parseErrors` adds
+     * coverage for parse5's malformed-reference codes (`&xyz;`, etc.) under
+     * the same rule id.
+     *
+     * ml-core's built-in parse-error channel suppresses the mirrored codes
+     * unconditionally — so the rule that reads them here is the only place
+     * the user sees the violation.
+     */
+    get parseErrors() {
+        return this._astToken.parseErrors ?? [];
+    }
     /**
      * @implements DOM API: `Document`
      */
@@ -2318,9 +2336,9 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "writeln" method');
     }
     /**
-     * Initializes pretender contexts for all element nodes in the document.
-     *
-     * @param pretenders - Optional pretender configurations from the document options
+     * Must run before `#ruleMapping`: rule selectors (e.g. a `nodeRules`
+     * entry targeting `button`) are matched against the pretender identity,
+     * so the pretender link has to exist when rules are mapped.
      */
     #pretending(pretenders) {
         if (docLog.enabled) {
@@ -2332,13 +2350,6 @@ export class MLDocument extends MLParentNode {
             }
         }
     }
-    /**
-     * Maps the ruleset configuration to each node in the document.
-     * Applies global rules, node-specific rules (by selector), and
-     * child-node rules to build the per-node rule configuration.
-     *
-     * @param ruleset - The ruleset containing rules, nodeRules, and childNodeRules
-     */
     #ruleMapping(ruleset) {
         if (docLog.enabled) {
             docLog('Rule Mapping: %O', Object.keys(ruleset.rules));

package/lib/ml-dom/node/element-close-tag.d.ts

@@ -3,6 +3,18 @@ import type { MLElement } from './element.js';
 import type { MLASTElementCloseTag } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLNode } from './node.js';
+/**
+ * The close tag paired with its opening `MLElement`.
+ *
+ * Close tags are not part of the document's `nodeList`; each instance exists
+ * only as a satellite of its paired element (`MLElement.closeTag`). The class
+ * exists for two purposes:
+ *
+ * 1. Reporting violations at the close tag's own source location instead of
+ *    the open tag (e.g. the `case-sensitive-tag-name` rule).
+ * 2. Detecting close-tag presence: `MLElement.closeTag` is `null` for void,
+ *    self-closing, or omitted end tags (e.g. the `end-tag` rule).
+ */
 export declare class MLElementCloseTag<T extends RuleConfigValue, O extends PlainData = undefined> extends MLNode<T, O, MLASTElementCloseTag> {
     readonly pair: MLElement<T, O>;
     constructor(astNode: MLASTElementCloseTag, document: MLDocument<T, O>, pair: MLElement<T, O>);

package/lib/ml-dom/node/element-close-tag.js

@@ -1,4 +1,16 @@
 import { MLNode } from './node.js';
+/**
+ * The close tag paired with its opening `MLElement`.
+ *
+ * Close tags are not part of the document's `nodeList`; each instance exists
+ * only as a satellite of its paired element (`MLElement.closeTag`). The class
+ * exists for two purposes:
+ *
+ * 1. Reporting violations at the close tag's own source location instead of
+ *    the open tag (e.g. the `case-sensitive-tag-name` rule).
+ * 2. Detecting close-tag presence: `MLElement.closeTag` is `null` for void,
+ *    self-closing, or omitted end tags (e.g. the `end-tag` rule).
+ */
 export class MLElementCloseTag extends MLNode {
     pair;
     constructor(astNode, 

package/lib/ml-dom/node/element.d.ts

@@ -53,6 +53,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
     /**
      * The pretender context if this element is participating in pretender behavior,
      * or null if it is not a pretender or pretended element.
+     *
+     * The virtual element created by `pretending()` is not registered in the
+     * document's `nodeList`; walkers visit only the original element, which
+     * delegates its name and attribute getters to the virtual element.
      */
     pretenderContext: PretenderContext<MLElement<T, O>, T, O> | null;
     /**
@@ -1637,6 +1641,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
     /**
      * Returns the rule configuration for this element, respecting the pretender context.
      * If the element is a pretended origin, returns the rule from the pretending element.
+     * Rules are mapped only to nodes in the document's `nodeList`; the virtual
+     * pretender element never appears there, so it must read the resolved
+     * rules from the original element.
      *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
@@ -1901,6 +1908,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * Gets the attribute value from the original (non-pretended) attributes list,
      * bypassing any pretender context that might be active.
      *
+     * Exists for the pretender ARIA `{ fromAttr }` accessible-name resolution:
+     * the source attribute (e.g. `label` on `<MyButton label="...">`) lives on
+     * the original component element, not on the virtual pretender element.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @param attrName - The attribute name to look up (case-insensitive)
      * @returns The attribute value, or null if the attribute is not found
@@ -2015,6 +2026,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * such as preprocessor-specific blocks, slot elements, or (optionally) elements
      * with dynamic attributes.
      *
+     * Blocks that carry a `blockBehavior` are not treated as mutable because
+     * their branches are deterministically enumerable via
+     * `conditionalChildNodes()`; blocks without one (e.g. expression output
+     * like `{value}`) can produce arbitrary content, so the children are
+     * considered mutable.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @param attr - When true, also considers children with mutable attributes as mutable
      * @returns True if this element has potentially mutable children
@@ -2090,6 +2107,11 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * returning detailed match results. When the element is a pretender,
      * it attempts to match both as the pretender and as the original element.
      *
+     * The two-phase strategy lets both targeting styles work: selectors for
+     * the semantic element (e.g. `button`) match via the pretender identity,
+     * while selectors for the component name (e.g. `MyButton`) still match
+     * the original.
+     *
      * @param selector - The CSS selector string or regex selector to match against
      * @param scope - An optional scope node for scoped selector matching
      * @returns The detailed match result including captured groups from regex selectors

package/lib/ml-dom/node/element.js

@@ -1,5 +1,5 @@
 /* global StylePropertyMap, StylePropertyMapReadOnly */
-import { resolveNamespace } from '@markuplint/ml-spec';
+import { getSpecByTagName, resolveNamespace } from '@markuplint/ml-spec';
 import { matchSelector } from '@markuplint/selector';
 import { getAccname } from '../helper/accname.js';
 import { after, before, nextElementSibling, previousElementSibling, remove, replaceWith, } from '../manipulations/child-node-methods.js';
@@ -49,8 +49,6 @@ export class MLElement extends MLParentNode {
      */
     namespaceURI;
     /**
-     * Memoization cache for the accessible name computation, keyed by ARIA version.
-     *
      * ## Why this cache exists
      *
      * Multiple rules and the `:aria(has name)` selector evaluate the accessible name
@@ -68,14 +66,6 @@ export class MLElement extends MLParentNode {
      * logic is needed. The cache is garbage-collected together with the
      * MLElement instance when the document is released.
      *
-     * ## Consumers that benefit
-     *
-     * - `require-accessible-name` rule (direct call)
-     * - `wai-aria` rule via `:aria(has name)` selector
-     * - `neighbor-popovers` rule
-     * - `landmark-roles` rule
-     * - `MLDocument.getAccessibilityProp()` (accessibility tree builder)
-     *
      * Introduced to resolve {@link https://github.com/markuplint/markuplint/issues/2179 | #2179}
      * (AccName performance bottleneck).
      *
@@ -91,6 +81,10 @@ export class MLElement extends MLParentNode {
     /**
      * The pretender context if this element is participating in pretender behavior,
      * or null if it is not a pretender or pretended element.
+     *
+     * The virtual element created by `pretending()` is not registered in the
+     * document's `nodeList`; walkers visit only the original element, which
+     * delegates its name and attribute getters to the virtual element.
      */
     pretenderContext = null;
     /**
@@ -2125,6 +2119,9 @@ export class MLElement extends MLParentNode {
     /**
      * Returns the rule configuration for this element, respecting the pretender context.
      * If the element is a pretended origin, returns the rule from the pretending element.
+     * Rules are mapped only to nodes in the document's `nodeList`; the virtual
+     * pretender element never appears there, so it must read the resolved
+     * rules from the original element.
      *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
@@ -2501,6 +2498,10 @@ export class MLElement extends MLParentNode {
      * Gets the attribute value from the original (non-pretended) attributes list,
      * bypassing any pretender context that might be active.
      *
+     * Exists for the pretender ARIA `{ fromAttr }` accessible-name resolution:
+     * the source attribute (e.g. `label` on `<MyButton label="...">`) lives on
+     * the original component element, not on the virtual pretender element.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @param attrName - The attribute name to look up (case-insensitive)
      * @returns The attribute value, or null if the attribute is not found
@@ -2692,6 +2693,12 @@ export class MLElement extends MLParentNode {
      * such as preprocessor-specific blocks, slot elements, or (optionally) elements
      * with dynamic attributes.
      *
+     * Blocks that carry a `blockBehavior` are not treated as mutable because
+     * their branches are deterministically enumerable via
+     * `conditionalChildNodes()`; blocks without one (e.g. expression output
+     * like `{value}`) can produce arbitrary content, so the children are
+     * considered mutable.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @param attr - When true, also considers children with mutable attributes as mutable
      * @returns True if this element has potentially mutable children
@@ -2816,6 +2823,11 @@ export class MLElement extends MLParentNode {
      * returning detailed match results. When the element is a pretender,
      * it attempts to match both as the pretender and as the original element.
      *
+     * The two-phase strategy lets both targeting styles work: selectors for
+     * the semantic element (e.g. `button`) match via the pretender identity,
+     * while selectors for the component name (e.g. `MyButton`) still match
+     * the original.
+     *
      * @param selector - The CSS selector string or regex selector to match against
      * @param scope - An optional scope node for scoped selector matching
      * @returns The detailed match result including captured groups from regex selectors
@@ -2850,6 +2862,20 @@ export class MLElement extends MLParentNode {
      * @param pretenders - Optional array of pretender configurations to match against
      */
     pretending(pretenders) {
+        // Pretender must not apply to a recognised standard HTML element (e.g. <marquee>,
+        // <h1>, <button>). Allowing such elements to masquerade as another would silently
+        // mask spec-driven rules — deprecation, ARIA role restrictions, browser support —
+        // keyed on the original tag. See issue #3740.
+        //
+        // Names that the HTML parser cannot distinguish from typos (PascalCase JSX-like
+        // usage in plain HTML such as `<SimpleButton>`) get `elementType === 'html'`
+        // from the parser but have no spec entry; those remain pretender-eligible
+        // (this is what `pretenders.scan` relies on). The legacy "no inline `as=` on
+        // HTML elements" guard is preserved further down for that case.
+        if (this.elementType === 'html' &&
+            getSpecByTagName(this.ownerMLDocument.specs.specs, this.localName, this.namespaceURI) != null) {
+            return;
+        }
         const pretenderConfig = pretenders?.find(option => this.matches(option.selector));
         const asAttrValue = this.getAttribute('as');
         const pretenderElement = pretenderConfig?.as ??

package/lib/ml-dom/node/node-store.d.ts

@@ -8,8 +8,5 @@ declare class NodeStore {
     getNodeByUuid<T extends RuleConfigValue, O extends PlainData = undefined>(uuid: string): MLNode<T, O, any>;
     setNode<A extends MLASTNode, T extends RuleConfigValue, O extends PlainData = undefined>(astNode: A, node: MLNode<T, O, A>): void;
 }
-/**
- * `NodeStore` Singleton
- */
 export declare const nodeStore: NodeStore;
 export {};

package/lib/ml-dom/node/node-store.js

@@ -46,7 +46,4 @@ class NodeStore {
         this.#store.set(astNode.uuid, node);
     }
 }
-/**
- * `NodeStore` Singleton
- */
 export const nodeStore = new NodeStore();

package/lib/ml-dom/node/node.d.ts

@@ -13,6 +13,18 @@ import { MLToken } from '../token/token.js';
  * Extends `MLToken` with DOM `Node` interface compliance, tree traversal,
  * rule configuration access, and child node management.
  *
+ * The `implements Node` declaration is a maintenance strategy: conforming to
+ * the built-in DOM interfaces makes the compiler report errors whenever the
+ * TypeScript DOM type definitions gain new members, so the MLDOM API surface
+ * never drifts from the DOM Standard unnoticed. Members that are meaningless
+ * in static analysis (mutation, events, layout) are stubbed to throw
+ * `UnexpectedCallError` instead of being implemented.
+ *
+ * The `T`/`O` generics exist solely for rule authors using `createRule`:
+ * they propagate through the node tree so that `node.rule` is typed as
+ * `RuleInfo<T, O>` inside `verify()`/`fix()` callbacks. They are a
+ * compile-time-only mechanism — see the `rules` field for the runtime side.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  * @template A - The underlying AST node type
@@ -121,7 +133,9 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     readonly isFragment: boolean;
     /**
-     *
+     * Rules mapped to this node by `RuleMapper`. Deliberately untyped
+     * (`AnyRule`) storage: the `T`/`O` generics are not enforced at runtime —
+     * the `rule` getter recovers the typed `RuleInfo<T, O>` via a cast.
      */
     readonly rules: Record<string, AnyRule>;
     protected _astToken: A;
@@ -169,6 +183,9 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     get lastChild(): MLChildNode<T, O> | null;
     /**
+     * The next node in the syntactical sibling list which, unlike
+     * `nextSibling`, includes `MLBlock` nodes (AST-level traversal).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get nextNode(): MLNode<T, O> | null;
@@ -276,10 +293,18 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     get parentNode(): MLDocument<any, any> | MLDocumentFragment<any, any> | MLElement<T, O> | null;
     /**
+     * The previous node in the syntactical sibling list which, unlike
+     * `previousSibling`, includes `MLBlock` nodes (AST-level traversal).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get prevNode(): MLNode<T, O> | null;
     /**
+     * The previous node in the document-order `nodeList`.
+     * Omitted (ghost) elements are skipped because they have no source tokens;
+     * including them would break offset chains used for indentation analysis
+     * and source reconstruction.
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get prevToken(): MLNode<T, O> | null;
@@ -383,6 +408,14 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      *
      * Note: NodeList doesn't include whitespace nodes.
      *
+     * For `if`/`switch` groups, a `null` sentinel is appended to each branch
+     * group to represent the case where no branch renders at all, so that
+     * content-model rules also validate the "empty branch" pattern
+     * (`branchesToPatterns` filters the `null` out of the generated patterns).
+     * `each` blocks intentionally do not start a conditional mode: their content
+     * is flattened as always-present rather than treated as an alternative
+     * branch, even though a loop may render zero times.
+     *
      * @returns An array of NodeLists representing the conditional child nodes.
      *
      * @experemental

package/lib/ml-dom/node/node.js

@@ -8,6 +8,18 @@ import { nodeStore } from './node-store.js';
  * Extends `MLToken` with DOM `Node` interface compliance, tree traversal,
  * rule configuration access, and child node management.
  *
+ * The `implements Node` declaration is a maintenance strategy: conforming to
+ * the built-in DOM interfaces makes the compiler report errors whenever the
+ * TypeScript DOM type definitions gain new members, so the MLDOM API surface
+ * never drifts from the DOM Standard unnoticed. Members that are meaningless
+ * in static analysis (mutation, events, layout) are stubbed to throw
+ * `UnexpectedCallError` instead of being implemented.
+ *
+ * The `T`/`O` generics exist solely for rule authors using `createRule`:
+ * they propagate through the node tree so that `node.rule` is typed as
+ * `RuleInfo<T, O>` inside `verify()`/`fix()` callbacks. They are a
+ * compile-time-only mechanism — see the `rules` field for the runtime side.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  * @template A - The underlying AST node type
@@ -110,31 +122,18 @@ export class MLNode extends MLToken {
      * @see https://dom.spec.whatwg.org/#interface-node
      */
     TEXT_NODE = 3;
-    /**
-     * Cached `childNodes` property
-     */
     #pureChildNodesCache;
     /**
      * Returns child nodes when parent node access by `childNodes` property.
      */
     isFragment;
-    /**
-     * Owner `Document`
-     *
-     * @implements DOM API: `Node`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-node-ownerdocument
-     */
     #ownerDocument;
-    /**
-     * Cached `prevToken` property
-     */
     #prevToken;
-    /**
-     * Cached `conditionalChildNodes` method
-     */
     #conditionalChildNodes;
     /**
-     *
+     * Rules mapped to this node by `RuleMapper`. Deliberately untyped
+     * (`AnyRule`) storage: the `T`/`O` generics are not enforced at runtime —
+     * the `rule` getter recovers the typed `RuleInfo<T, O>` via a cast.
      */
     rules = {};
     _astToken;
@@ -210,6 +209,9 @@ export class MLNode extends MLToken {
         return this.childNodes[this.childNodes.length - 1] ?? null;
     }
     /**
+     * The next node in the syntactical sibling list which, unlike
+     * `nextSibling`, includes `MLBlock` nodes (AST-level traversal).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get nextNode() {
@@ -369,6 +371,9 @@ export class MLNode extends MLToken {
         return parentNode;
     }
     /**
+     * The previous node in the syntactical sibling list which, unlike
+     * `previousSibling`, includes `MLBlock` nodes (AST-level traversal).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get prevNode() {
@@ -377,6 +382,11 @@ export class MLNode extends MLToken {
         return siblings[index - 1] ?? null;
     }
     /**
+     * The previous node in the document-order `nodeList`.
+     * Omitted (ghost) elements are skipped because they have no source tokens;
+     * including them would break offset chains used for indentation analysis
+     * and source reconstruction.
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get prevToken() {
@@ -549,6 +559,14 @@ export class MLNode extends MLToken {
      *
      * Note: NodeList doesn't include whitespace nodes.
      *
+     * For `if`/`switch` groups, a `null` sentinel is appended to each branch
+     * group to represent the case where no branch renders at all, so that
+     * content-model rules also validate the "empty branch" pattern
+     * (`branchesToPatterns` filters the `null` out of the generated patterns).
+     * `each` blocks intentionally do not start a conditional mode: their content
+     * is flattened as always-present rather than treated as an alternative
+     * branch, even though a loop may render zero times.
+     *
      * @returns An array of NodeLists representing the conditional child nodes.
      *
      * @experemental

package/lib/ml-dom/node/parent-node.js

@@ -8,13 +8,7 @@ import { UnexpectedCallError } from '@markuplint/shared';
  * @see https://dom.spec.whatwg.org/#interface-parentnode
  */
 export class MLParentNode extends MLNode {
-    /**
-     * Cached `children`
-     */
     #children = null;
-    /**
-     * Cached elements that created from `querySelectorAll`
-     */
     #selectedElements = new Map();
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`

package/lib/ml-dom/node/rule-mapper.d.ts

@@ -8,6 +8,14 @@ type MappingLayer = {
     readonly specificity: Specificity;
     readonly rule: AnyRule;
 };
+/**
+ * Accumulates rule-to-node mappings and applies them to each node's `rules`
+ * record. Conflicts for the same rule on the same node are resolved by CSS
+ * selector specificity: higher specificity wins regardless of order, and on
+ * equal specificity the later `set()` call wins — so declaration order in
+ * the config arrays decides. Entries from `childNodeRules` carry the
+ * specificity of the parent's selector, not the child's.
+ */
 export declare class RuleMapper {
     #private;
     constructor(document: MLDocument<any, any>);

package/lib/ml-dom/node/rule-mapper.js

@@ -3,6 +3,14 @@ import { log as coreLog } from '../../debug.js';
 const ruleMapperLog = coreLog.extend('rule-mapper');
 const ruleMapperNodeLog = ruleMapperLog.extend('node');
 const ruleMapperNodeRuleLog = ruleMapperNodeLog.extend('rule');
+/**
+ * Accumulates rule-to-node mappings and applies them to each node's `rules`
+ * record. Conflicts for the same rule on the same node are resolved by CSS
+ * selector specificity: higher specificity wins regardless of order, and on
+ * equal specificity the later `set()` call wins — so declaration order in
+ * the config arrays decides. Entries from `childNodeRules` carry the
+ * specificity of the parent's selector, not the child's.
+ */
 export class RuleMapper {
     #nodeList;
     #ruleMap = new Map();