@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/lib/permitted-contents/complex-branch.d.ts

@@ -2,13 +2,17 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentPattern } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check content condition
+ * Dispatches a single content model pattern to the appropriate handler based on its type.
+ * Acts as a routing layer in the content model validation pipeline:
+ * - Choice patterns (alternation) are delegated to `choice`.
+ * - Transparent patterns are delegated to `transparent`.
+ * - All other quantified patterns (require, optional, oneOrMore, zeroOrMore) are delegated to `countPattern`.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * @param pattern - A single content model pattern to evaluate.
+ * @param childNodes - The child nodes to validate against the pattern.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result indicating whether the child nodes match the pattern.
  */
 export declare function complexBranch(pattern: ReadonlyDeep<PermittedContentPattern>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/complex-branch.js

@@ -3,14 +3,18 @@ import { countPattern } from './count-pattern.js';
 import { transparent } from './transparent.js';
 import { isChoice, isTransparent } from './utils.js';
 /**
- * Check content condition
+ * Dispatches a single content model pattern to the appropriate handler based on its type.
+ * Acts as a routing layer in the content model validation pipeline:
+ * - Choice patterns (alternation) are delegated to `choice`.
+ * - Transparent patterns are delegated to `transparent`.
+ * - All other quantified patterns (require, optional, oneOrMore, zeroOrMore) are delegated to `countPattern`.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * @param pattern - A single content model pattern to evaluate.
+ * @param childNodes - The child nodes to validate against the pattern.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result indicating whether the child nodes match the pattern.
  */
 export function complexBranch(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

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

@@ -1,2 +1,13 @@
 import type { ContentModelResult, Element, Options, TagRule } from './types.js';
+/**
+ * Top-level entry point for content model validation of a single element.
+ * Resolves the element's content model from the spec (possibly augmented
+ * by user-defined tag rules), then delegates to `start` to validate
+ * the element's child nodes against that model.
+ *
+ * @param el - The element whose children are to be validated against its content model.
+ * @param rules - User-defined tag rules that can override or extend built-in content models.
+ * @param options - Validation behavior options (e.g., whether to ignore mutable children).
+ * @returns An array of content model results, one per child node issue found (empty if all valid).
+ */
 export declare function contentModel(el: Element, rules: readonly TagRule[], options: Options): ContentModelResult[];

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

@@ -1,5 +1,16 @@
 import { getContentModel } from '@markuplint/ml-spec';
 import { start } from './start.js';
+/**
+ * Top-level entry point for content model validation of a single element.
+ * Resolves the element's content model from the spec (possibly augmented
+ * by user-defined tag rules), then delegates to `start` to validate
+ * the element's child nodes against that model.
+ *
+ * @param el - The element whose children are to be validated against its content model.
+ * @param rules - User-defined tag rules that can override or extend built-in content models.
+ * @param options - Validation behavior options (e.g., whether to ignore mutable children).
+ * @returns An array of content model results, one per child node issue found (empty if all valid).
+ */
 export function contentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules, options) {
@@ -17,6 +28,15 @@ el, rules, options) {
     const result = start(model, el, specs, options);
     return result;
 }
+/**
+ * Builds the content model and merged specs for a given element.
+ * Combines the element's document-level specs with any user-defined
+ * tag rules, then looks up the content model for the element.
+ *
+ * @param el - The element to look up the content model for.
+ * @param rules - User-defined tag rules to merge into the spec.
+ * @returns An object containing the resolved content model and merged specs.
+ */
 function createModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules) {
@@ -27,7 +47,19 @@ el, rules) {
         specs,
     };
 }
+/**
+ * Cache for merged specs keyed by the JSON-serialized tag rules.
+ * Avoids re-merging the same set of user-defined tag rules on every element check.
+ */
 const caches = new Map();
+/**
+ * Returns a Specs object that merges the base ML spec with user-defined
+ * tag rules. Results are cached by the serialized rules to avoid redundant merging.
+ *
+ * @param specs - The base ML spec from the document.
+ * @param rules - User-defined tag rules to merge.
+ * @returns The merged Specs, either from cache or freshly computed.
+ */
 function cachedSpecs(specs, rules) {
     if (rules.length === 0) {
         return specs;

package/lib/permitted-contents/count-pattern.d.ts

@@ -2,13 +2,19 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentOneOrMore, PermittedContentOptional, PermittedContentRequire, PermittedContentZeroOrMore } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check count
+ * Validates a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * against a list of child nodes. Repeatedly applies the inner pattern via `recursiveBranch`
+ * until the minimum count is satisfied and no more nodes match, or until the maximum count
+ * is exceeded.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Implements the repetition/quantifier semantics of content models (e.g., "one or more
+ * flow content elements", "optionally a `<caption>`", "exactly one `<tbody>`").
+ *
+ * @param pattern - A quantified content model pattern (require, optional, oneOrMore, or zeroOrMore).
+ * @param childNodes - The child nodes to validate against the repeated pattern.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result indicating whether the required count of matches was achieved.
  */
 export declare function countPattern(pattern: ReadonlyDeep<PermittedContentOneOrMore> | ReadonlyDeep<PermittedContentOptional> | ReadonlyDeep<PermittedContentRequire> | ReadonlyDeep<PermittedContentZeroOrMore>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/count-pattern.js

@@ -3,14 +3,20 @@ import { recursiveBranch } from './recursive-branch.js';
 import { Collection, mergeHints, modelLog, normalizeModel } from './utils.js';
 const cLog = cmLog.extend('countCompereResult');
 /**
- * Check count
+ * Validates a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * against a list of child nodes. Repeatedly applies the inner pattern via `recursiveBranch`
+ * until the minimum count is satisfied and no more nodes match, or until the maximum count
+ * is exceeded.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Implements the repetition/quantifier semantics of content models (e.g., "one or more
+ * flow content elements", "optionally a `<caption>`", "exactly one `<tbody>`").
+ *
+ * @param pattern - A quantified content model pattern (require, optional, oneOrMore, or zeroOrMore).
+ * @param childNodes - The child nodes to validate against the repeated pattern.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result indicating whether the required count of matches was achieved.
  */
 export function countPattern(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -139,6 +145,16 @@ childNodes, specs, options, depth) {
         return compereResult(matchedResult, barelyResult);
     }
 }
+/**
+ * Compares two results and returns the one that represents the best diagnostic outcome.
+ * When the primary result is a match or an unexpected-extra-node, it is preferred.
+ * Otherwise, the result with more barely-matched elements (closer to success) is chosen
+ * to provide the most helpful error message.
+ *
+ * @param a - The primary (current iteration) result.
+ * @param b - The barely-matched result from a previous successful partial match, or null.
+ * @returns The result that should be reported to the user.
+ */
 function compereResult(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 a, 
@@ -151,6 +167,6 @@ b) {
     if (a.type === 'MATCHED' || a.type === 'MATCHED_ZERO' || a.type === 'UNEXPECTED_EXTRA_NODE') {
         return a;
     }
-    const result = [a, b].sort((a, b) => (b.hint.missing?.barelyMatchedElements ?? 0) - (a.hint.missing?.barelyMatchedElements ?? 0))[0] ?? a;
+    const result = [a, b].toSorted((a, b) => (b.hint.missing?.barelyMatchedElements ?? 0) - (a.hint.missing?.barelyMatchedElements ?? 0))[0] ?? a;
     return result;
 }

package/lib/permitted-contents/debug.browser.d.ts

@@ -1,29 +1,41 @@
 import type { Log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module (browser build).
+ * Extends the parent rule logger with a `content-model` namespace.
+ * In the browser environment, color helpers are no-op stubs.
+ */
 export declare const cmLog: Log;
+/** No-op color stub for browser environments: green background. */
 export declare const bgGreen: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: green foreground. */
 export declare const green: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: red background. */
 export declare const bgRed: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: blue background. */
 export declare const bgBlue: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: blue foreground. */
 export declare const blue: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: magenta background. */
 export declare const bgMagenta: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: cyan foreground. */
 export declare const cyan: {
     (): void;
     bold(): void;

package/lib/permitted-contents/debug.browser.js

@@ -1,11 +1,23 @@
 import { log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module (browser build).
+ * Extends the parent rule logger with a `content-model` namespace.
+ * In the browser environment, color helpers are no-op stubs.
+ */
 export const cmLog = log.extend('content-model');
 const fn = () => { };
 fn.bold = () => { };
+/** No-op color stub for browser environments: green background. */
 export const bgGreen = fn;
+/** No-op color stub for browser environments: green foreground. */
 export const green = fn;
+/** No-op color stub for browser environments: red background. */
 export const bgRed = fn;
+/** No-op color stub for browser environments: blue background. */
 export const bgBlue = fn;
+/** No-op color stub for browser environments: blue foreground. */
 export const blue = fn;
+/** No-op color stub for browser environments: magenta background. */
 export const bgMagenta = fn;
+/** No-op color stub for browser environments: cyan foreground. */
 export const cyan = fn;

package/lib/permitted-contents/debug.d.ts

@@ -1,10 +1,22 @@
 import type { Log } from '../debug.js';
 import color from 'ansi-colors';
+/**
+ * Debug logger scoped to the content-model validation module.
+ * Extends the parent rule logger with a `content-model` namespace
+ * for structured debug output during content model evaluation.
+ */
 export declare const cmLog: Log;
+/** ANSI color helper: green background for highlighting locked-and-matched nodes in debug output. */
 export declare const bgGreen: color.StyleFunction;
+/** ANSI color helper: green foreground for highlighting matched nodes in debug output. */
 export declare const green: color.StyleFunction;
+/** ANSI color helper: red background for highlighting unexpected/extra nodes in debug output. */
 export declare const bgRed: color.StyleFunction;
+/** ANSI color helper: blue background for highlighting locked-and-matched transparent nodes in debug output. */
 export declare const bgBlue: color.StyleFunction;
+/** ANSI color helper: blue foreground for highlighting matched transparent nodes in debug output. */
 export declare const blue: color.StyleFunction;
+/** ANSI color helper: magenta background for highlighting unexpected transparent nodes in debug output. */
 export declare const bgMagenta: color.StyleFunction;
+/** ANSI color helper: cyan foreground for highlighting unmatched transparent nodes in debug output. */
 export declare const cyan: color.StyleFunction;

package/lib/permitted-contents/debug.js

@@ -1,10 +1,22 @@
 import color from 'ansi-colors';
 import { log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module.
+ * Extends the parent rule logger with a `content-model` namespace
+ * for structured debug output during content model evaluation.
+ */
 export const cmLog = log.extend('content-model');
+/** ANSI color helper: green background for highlighting locked-and-matched nodes in debug output. */
 export const bgGreen = color.bgGreen;
+/** ANSI color helper: green foreground for highlighting matched nodes in debug output. */
 export const green = color.green;
+/** ANSI color helper: red background for highlighting unexpected/extra nodes in debug output. */
 export const bgRed = color.bgRed;
+/** ANSI color helper: blue background for highlighting locked-and-matched transparent nodes in debug output. */
 export const bgBlue = color.bgBlue;
+/** ANSI color helper: blue foreground for highlighting matched transparent nodes in debug output. */
 export const blue = color.blue;
+/** ANSI color helper: magenta background for highlighting unexpected transparent nodes in debug output. */
 export const bgMagenta = color.bgMagenta;
+/** ANSI color helper: cyan foreground for highlighting unmatched transparent nodes in debug output. */
 export const cyan = color.cyan;

package/lib/permitted-contents/index.d.ts

@@ -1,3 +1,15 @@
 import type { Options, TagRule } from './types.js';
+/**
+ * The `permitted-contents` rule validates that each element's child nodes conform
+ * to the HTML content model specification. It is the most complex rule in markuplint,
+ * implementing a full content model validation engine that handles ordered sequences,
+ * quantified patterns (require, optional, oneOrMore, zeroOrMore), choice alternations,
+ * transparent content models, and conditional child node branches.
+ *
+ * For each element, it resolves the applicable content model (from the HTML spec or
+ * user-defined tag rules), evaluates the element's children against that model, and
+ * reports violations such as unexpected elements, missing required elements, or
+ * disallowed content through transparent models.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<TagRule[], Options>>;
 export default _default;

package/lib/permitted-contents/index.js

@@ -2,6 +2,18 @@ import { createRule } from '@markuplint/ml-core';
 import { contentModel } from './content-model.js';
 import meta from './meta.js';
 import { transparentMode } from './represent-transparent-nodes.js';
+/**
+ * The `permitted-contents` rule validates that each element's child nodes conform
+ * to the HTML content model specification. It is the most complex rule in markuplint,
+ * implementing a full content model validation engine that handles ordered sequences,
+ * quantified patterns (require, optional, oneOrMore, zeroOrMore), choice alternations,
+ * transparent content models, and conditional child node branches.
+ *
+ * For each element, it resolves the applicable content model (from the HTML spec or
+ * user-defined tag rules), evaluates the element's children against that model, and
+ * reports violations such as unexpected elements, missing required elements, or
+ * disallowed content through transparent models.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [],
@@ -91,6 +103,15 @@ export default createRule({
         });
     },
 });
+/**
+ * Generates a localized, human-readable name for a child node based on its type.
+ * Used in error messages to describe the offending node (e.g., 'the "div" element',
+ * 'the text node', 'the comment', 'the doctype', 'the code block').
+ *
+ * @param scope - The child node to generate a name for.
+ * @param t - The translator function for localized message formatting.
+ * @returns A localized string describing the node.
+ */
 function name(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 scope, t) {

package/lib/permitted-contents/matches-selector.d.ts

@@ -1,3 +1,22 @@
 import type { ChildNode, Result, Specs } from './types.js';
+/**
+ * Extended result type for selector matching that includes additional
+ * intermediate states: a selector that did not match but allows empty content,
+ * a missing node, or unmatched selectors with partial matches.
+ */
 export type SelectorResult = Result<'UNMATCHED_SELECTOR_BUT_MAY_EMPTY' | 'MISSING_NODE' | 'UNMATCHED_SELECTORS'>;
+/**
+ * Tests whether a single child node matches a content model query selector.
+ * Handles special node types (text nodes, preprocessor blocks, custom elements)
+ * and delegates standard element matching to the CSS selector engine.
+ *
+ * The query string may reference content model categories (e.g., `#phrasing`)
+ * which are expanded to concrete tag selectors via `optCondition`.
+ *
+ * @param query - The content model query string (e.g., `"div"`, `"#phrasing"`, `":model(flow)"`).
+ * @param childNode - The child node to test, or undefined if no node is available.
+ * @param specs - The resolved spec data for category-to-tag-name expansion.
+ * @param depth - The current recursion depth, used for debug logging namespacing.
+ * @returns A selector result indicating match status with diagnostic hints.
+ */
 export declare function matchesSelector(query: string, childNode: ChildNode | undefined, specs: Specs, depth: number): SelectorResult;

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

@@ -1,6 +1,20 @@
 import { contentModelCategoryToTagNames } from '@markuplint/ml-spec';
 import { cmLog } from './debug.js';
 import { cleanObject, matches } from './utils.js';
+/**
+ * Tests whether a single child node matches a content model query selector.
+ * Handles special node types (text nodes, preprocessor blocks, custom elements)
+ * and delegates standard element matching to the CSS selector engine.
+ *
+ * The query string may reference content model categories (e.g., `#phrasing`)
+ * which are expanded to concrete tag selectors via `optCondition`.
+ *
+ * @param query - The content model query string (e.g., `"div"`, `"#phrasing"`, `":model(flow)"`).
+ * @param childNode - The child node to test, or undefined if no node is available.
+ * @param specs - The resolved spec data for category-to-tag-name expansion.
+ * @param depth - The current recursion depth, used for debug logging namespacing.
+ * @returns A selector result indicating match status with diagnostic hints.
+ */
 export function matchesSelector(query, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNode, specs, depth) {
@@ -127,6 +141,9 @@ childNode, specs, depth) {
         hint: {},
     };
 }
+/**
+ * Pre-computed conditions for well-known queries that do not depend on specs.
+ */
 const conditionWithoutSpecs = {
     '#custom': {
         selector: '#custom',
@@ -139,7 +156,23 @@ const conditionWithoutSpecs = {
         hasText: true,
     },
 };
+/**
+ * Cache of parsed conditions keyed by specs instance and query string.
+ * Prevents redundant category expansion for the same query across multiple elements.
+ */
 const optConditionSpecsBaseCaches = new Map();
+/**
+ * Parses a content model query string into a Condition object by expanding
+ * content model category references (e.g., `#phrasing`, `:model(flow)`) into
+ * concrete CSS `:is(...)` selectors. Also detects whether the query implicitly
+ * includes custom elements or text nodes.
+ *
+ * Results are cached per specs instance and query string.
+ *
+ * @param query - The raw content model query string to parse.
+ * @param specs - The spec data used to resolve category names to tag lists.
+ * @returns A readonly Condition with the resolved selector and flags.
+ */
 function optCondition(query, specs) {
     const condWithoutSpecs = conditionWithoutSpecs[query];
     if (condWithoutSpecs) {

package/lib/permitted-contents/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `permitted-contents` validation rule. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/permitted-contents/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `permitted-contents` validation rule. */
 export default {
     category: 'validation',
 };

package/lib/permitted-contents/order.d.ts

@@ -2,13 +2,20 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentPattern } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check ordered array
+ * Validates an ordered sequence of content model patterns against a list of child nodes.
+ * Each pattern in the `contents` array is matched in order against the remaining unmatched
+ * child nodes, consuming nodes as they match. This implements the sequential composition
+ * semantics of HTML content models (e.g., "a `<caption>` followed by zero or more `<colgroup>`s
+ * followed by a `<thead>`...").
  *
- * @param contents
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Supports backtracking: when a pattern matches zero nodes (zeroMatch), the algorithm
+ * can backtrack to try the next pattern from the previous position if the current pattern fails.
+ *
+ * @param contents - An ordered array of content model patterns to match sequentially.
+ * @param childNodes - The child nodes to validate against the patterns.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested pattern matching.
+ * @returns A result indicating overall match status and the matched/unmatched node partitioning.
  */
 export declare function order(contents: ReadonlyDeep<PermittedContentPattern[]>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/order.js

@@ -3,14 +3,21 @@ import { complexBranch } from './complex-branch.js';
 import { cmLog } from './debug.js';
 import { Collection, mergeHints, modelLog } from './utils.js';
 /**
- * Check ordered array
+ * Validates an ordered sequence of content model patterns against a list of child nodes.
+ * Each pattern in the `contents` array is matched in order against the remaining unmatched
+ * child nodes, consuming nodes as they match. This implements the sequential composition
+ * semantics of HTML content models (e.g., "a `<caption>` followed by zero or more `<colgroup>`s
+ * followed by a `<thead>`...").
  *
- * @param contents
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Supports backtracking: when a pattern matches zero nodes (zeroMatch), the algorithm
+ * can backtrack to try the next pattern from the previous position if the current pattern fails.
+ *
+ * @param contents - An ordered array of content model patterns to match sequentially.
+ * @param childNodes - The child nodes to validate against the patterns.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested pattern matching.
+ * @returns A result indicating overall match status and the matched/unmatched node partitioning.
  */
 export function order(contents, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -37,7 +44,7 @@ childNodes, specs, options, depth) {
                 afterBacktrack = true;
                 continue;
             }
-            const barelyMatchedResult = unmatchedResults.sort((a, b) => b.matched.length - a.matched.length)[0];
+            const barelyMatchedResult = unmatchedResults.toSorted((a, b) => b.matched.length - a.matched.length)[0];
             if (!barelyMatchedResult) {
                 throw new Error('Unreachable code');
             }

package/lib/permitted-contents/recursive-branch.d.ts

@@ -2,4 +2,21 @@ import type { SelectorResult } from './matches-selector.js';
 import type { ChildNode, Options, Specs } from './types.js';
 import type { PermittedContentPattern, Model } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Evaluates a model or nested pattern array against child nodes at the leaf level
+ * of the content model tree. If the input is a nested pattern array (not a terminal model),
+ * it recurses back into `order` for sequential evaluation. If it is a terminal model
+ * (a single selector string or an array of selector strings representing alternatives),
+ * it tests the first unmatched child node against each selector via `matchesSelector`.
+ *
+ * For array-of-selectors models, the selectors act as alternatives (logical OR): the first
+ * selector to match the child node produces the result.
+ *
+ * @param model - Either a terminal model (selector string or array of selector strings) or a nested pattern array.
+ * @param childNodes - The child nodes to validate against the model.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A selector result indicating whether the first unmatched child node matches the model.
+ */
 export declare function recursiveBranch(model: ReadonlyDeep<Model | PermittedContentPattern[]>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): SelectorResult;

package/lib/permitted-contents/recursive-branch.js

@@ -1,6 +1,23 @@
 import { matchesSelector } from './matches-selector.js';
 import { order } from './order.js';
 import { Collection, isModel } from './utils.js';
+/**
+ * Evaluates a model or nested pattern array against child nodes at the leaf level
+ * of the content model tree. If the input is a nested pattern array (not a terminal model),
+ * it recurses back into `order` for sequential evaluation. If it is a terminal model
+ * (a single selector string or an array of selector strings representing alternatives),
+ * it tests the first unmatched child node against each selector via `matchesSelector`.
+ *
+ * For array-of-selectors models, the selectors act as alternatives (logical OR): the first
+ * selector to match the child node produces the result.
+ *
+ * @param model - Either a terminal model (selector string or array of selector strings) or a nested pattern array.
+ * @param childNodes - The child nodes to validate against the model.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A selector result indicating whether the first unmatched child node matches the model.
+ */
 export function recursiveBranch(model, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options, depth) {

package/lib/permitted-contents/represent-transparent-nodes.d.ts

@@ -1,8 +1,62 @@
 import type { ChildNode, Options, Result, Specs } from './types.js';
+/**
+ * A map tracking child nodes that are currently being evaluated through
+ * a transparent content model. Used to prevent infinite recursion and
+ * to enable special handling in error messages and debug output.
+ */
 export declare const transparentMode: Map<ChildNode, true>;
+/**
+ * Represents a possible resolution of transparent content model nodes,
+ * containing the flattened list of child nodes to validate and any
+ * errors detected during transparent model resolution.
+ */
 type TransparentNode = {
     nodes: ChildNode[];
     errors: Result[];
 };
+/**
+ * Resolves transparent content model elements by replacing them with their
+ * children for validation purposes. In HTML, elements like `<a>`, `<ins>`, and `<del>`
+ * have transparent content models, meaning their children must be valid in the
+ * parent's content model as if the transparent element were not present.
+ *
+ * This function:
+ * 1. Identifies child elements with transparent content models.
+ * 2. Filters out children that match non-transparent parts of the element's content model.
+ * 3. Replaces the transparent element with its remaining (unmatched) children.
+ * 4. Validates that each remaining child satisfies the transparent model's condition selector.
+ * 5. Recursively resolves parent-level transparent nodes to propagate errors up the tree.
+ * 6. Builds patterns incrementally, capping cross-products to avoid exponential blowup.
+ *
+ * ### Algorithm — incremental pattern building
+ *
+ * Patterns are built incrementally as each child node is visited:
+ *
+ * - **Non-transparent child**: appended to every existing pattern.
+ *   Pattern count stays the same.
+ * - **Single-branch transparent child** (non-conditional, or
+ *   `evaluateConditionalChildNodes` disabled): all unmatched children
+ *   are spread into every pattern. Pattern count stays the same.
+ * - **Multi-branch transparent child** (conditional, e.g. `v-if`/`v-else`):
+ *   a cross-product of existing patterns × branch groups is computed,
+ *   capped at {@link MAX_PATTERNS}. If the cap would be exceeded, a
+ *   conservative fallback merges all branch children into every pattern.
+ *
+ * ### Complexity
+ *
+ * - **Previous algorithm** (`branchesToPatterns` Cartesian product):
+ *   O(K^N) time and space, where N = number of transparent elements,
+ *   K = average branch count per element. 12 elements with 2 children
+ *   each produced 4096 patterns and took 30+ seconds.
+ * - **Current algorithm**: O(N × K × min(|patterns|, MAX_PATTERNS))
+ *   time; O(MAX_PATTERNS × P) space where P = average pattern length.
+ *   The same 12-element case now produces 1 pattern in <100 ms.
+ *
+ * @param childNodes - The child nodes of the element being validated, some of which may be transparent.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @returns An array of possible transparent node resolutions, each with flattened nodes and accumulated errors.
+ * @see https://github.com/markuplint/markuplint/issues/3249
+ */
 export declare function representTransparentNodes(childNodes: readonly ChildNode[], specs: Specs, options: Options): TransparentNode[];
 export {};