@markuplint/rules 5.0.0-rc.1 → 5.0.0-rc.4

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/rules
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/rules
+
+# [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
+
+### Bug Fixes
+
+- **rules:** allow zeroOrMore to match zero times in countPattern ([f5da340](https://github.com/markuplint/markuplint/commit/f5da340ac264c831ba0c74adfd039a1d0b6ff3fb)), closes [#3592](https://github.com/markuplint/markuplint/issues/3592)
+- **rules:** apply permitted-contents user rule on pretended elements ([04c42d1](https://github.com/markuplint/markuplint/commit/04c42d165aabde754d6544486ca5d39ef4a868bc)), closes [#3739](https://github.com/markuplint/markuplint/issues/3739)
+- **rules:** enforce descendantOf constraint in permitted-contents rule ([5375207](https://github.com/markuplint/markuplint/commit/5375207f169d26c65be6510f28c904d39454d08e))
+- **rules:** preserve role name in permitted-roles message, dedupe with implicit-role ([3123cd6](https://github.com/markuplint/markuplint/commit/3123cd690e140e142a94c09d6948bb9cf0dfd23e)), closes [#3641](https://github.com/markuplint/markuplint/issues/3641) [#3641](https://github.com/markuplint/markuplint/issues/3641) [#3641](https://github.com/markuplint/markuplint/issues/3641)
+- **types:** reject zero and negative srcset descriptors ([5584d20](https://github.com/markuplint/markuplint/commit/5584d2089fe1dfe508d43601fa14aeff4e08b265))
+
+### Features
+
+- **ml-spec:** add ConditionalAttributeType to Attribute.type union ([#3685](https://github.com/markuplint/markuplint/issues/3685)) ([a619a07](https://github.com/markuplint/markuplint/commit/a619a071d93566dd8aa7ab8dee2ed751c2e8756c)), closes [#3598](https://github.com/markuplint/markuplint/issues/3598) [#3189](https://github.com/markuplint/markuplint/issues/3189)
+- **rules:** add #nonEmptyText matching to permitted-contents engine ([4b91cf3](https://github.com/markuplint/markuplint/commit/4b91cf37cb8d54b86e8bfe125276251f2d8cb97b))
+- **rules:** add document uniqueness rules (autofocus, visible-main, charset) ([1befb20](https://github.com/markuplint/markuplint/commit/1befb2051015df7669fbd07da3fea3a0b6542a90))
+- **rules:** check forbiddenAncestors in permitted-contents rule ([0633c05](https://github.com/markuplint/markuplint/commit/0633c05df91a2f51361a72efe8ebb2e604a53918))
+- **rules:** check uniqueAttrs constraint in permitted-contents rule ([6b2cf6b](https://github.com/markuplint/markuplint/commit/6b2cf6b9fc7d5320543acdc9271de12e46677b9f))
+- **rules:** disallow is attribute on autonomous custom elements ([ed7ec78](https://github.com/markuplint/markuplint/commit/ed7ec78c058030caacc8bd23c90c489c77c40b27))
+- **rules:** enforce ARIA naming prohibition on elements without role ([f67bd5d](https://github.com/markuplint/markuplint/commit/f67bd5dcb33f28ef3daf3ecd3b5d30ad4ced7814)), closes [#3630](https://github.com/markuplint/markuplint/issues/3630)
+- **rules:** implement conditional type resolution for input value ([#3598](https://github.com/markuplint/markuplint/issues/3598)) ([d478ce6](https://github.com/markuplint/markuplint/commit/d478ce669387c868dd2e4b81cad32bcccddef7f2))
+- **rules:** split wai-aria into 16 granular sub-rules ([1aded91](https://github.com/markuplint/markuplint/commit/1aded912ca839a75b89d14f3ae6ba30c2701a61b)), closes [#3645](https://github.com/markuplint/markuplint/issues/3645)
+
 # [5.0.0-rc.1](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.0...v5.0.0-rc.1) (2026-03-27)
 
 **Note:** Version bump only for package @markuplint/rules

package/CLAUDE.md

@@ -0,0 +1,27 @@
+# @markuplint/rules
+
+## Test ID Convention (MANDATORY)
+
+Every `test()` block in `src/**/*.spec.ts` MUST have a unique ID prefix:
+
+```
+[rule-name-category-NNN] description
+```
+
+### Categories
+
+| Category     | When to use                                               |
+| ------------ | --------------------------------------------------------- |
+| `valid`      | Test expects 0 violations                                 |
+| `invalid`    | Test expects 1+ violations                                |
+| `fix`        | Test checks `fixedCode` or auto-fix behavior              |
+| `parser`     | Test uses a non-default parser (Vue, React, Pug, etc.)    |
+| `issue-NNNN` | Regression test for a GitHub issue (use the issue number) |
+
+### Rules
+
+- IDs go on `test()` blocks only (not `describe()`)
+- Numbers are sequential per category per file, starting at `001`
+- Multiple tests for the same issue: `[rule-name-issue-NNNN-001]`, `[rule-name-issue-NNNN-002]`
+- When adding a new test, assign the next available number in the appropriate category
+- Run `/list-rule-test` (or `node .claude/commands/scripts/list-rule-test.mjs --no-id`) to check for missing IDs

package/SKILL.md

@@ -58,6 +58,7 @@ const { violations } = await mlRuleTest(rule, '<button role="separator" ...>', {
 - `toStrictEqual` with exact `{ severity, line, col, message, raw }` — **never** loose assertions
 - Always include both valid and invalid cases
 - Some roles need ARIA attributes in HTML: `separator` → `aria-valuenow`, `meter` → `aria-valuenow`
+- **Every `test()` MUST have a unique ID prefix** — see `CLAUDE.md` in this package for the full convention
 
 ## Task: update-test-expectations
 

package/lib/attr-check.d.ts

@@ -34,7 +34,9 @@ type Loc = {
  * 2. Verifies the attribute exists in the spec
  * 3. Checks case-sensitive name matching
  * 4. Checks whether the attribute is marked as `noUse` (disallowed)
- * 5. Validates the attribute value against all declared types
+ * 5. Safety-net fallback for `ConditionalAttributeType[]` (#3685); in normal flow,
+ *    `isValidAttr()` resolves conditional types before calling this function (#3598)
+ * 6. Validates the attribute value against all declared types
  *
  * @param t - The i18n translator for generating localized error messages
  * @param name - The attribute name to check

package/lib/attr-check.js

@@ -1,3 +1,4 @@
+import { isConditionalAttributeTypeArray } from '@markuplint/ml-spec';
 import { toNonNullableArrayFromItemOrArray } from '@markuplint/shared';
 import { check, getCandidate } from '@markuplint/types';
 import { createMessageValueExpected } from './create-message.js';
@@ -11,7 +12,9 @@ import { log } from './debug.js';
  * 2. Verifies the attribute exists in the spec
  * 3. Checks case-sensitive name matching
  * 4. Checks whether the attribute is marked as `noUse` (disallowed)
- * 5. Validates the attribute value against all declared types
+ * 5. Safety-net fallback for `ConditionalAttributeType[]` (#3685); in normal flow,
+ *    `isValidAttr()` resolves conditional types before calling this function (#3598)
+ * 6. Validates the attribute value against all declared types
  *
  * @param t - The i18n translator for generating localized error messages
  * @param name - The attribute name to check
@@ -72,6 +75,12 @@ export function attrCheck(t, name, value, isCustomRule, spec, allAttrNames) {
             message: t('{0} is {1:c}', t('the "{0*}" {1}', name, 'attribute'), 'disallowed'),
         };
     }
+    // Safety net: In normal flow, `isValidAttr()` resolves ConditionalAttributeType[]
+    // before calling this function (#3598). This guard handles direct calls.
+    if (isConditionalAttributeTypeArray(spec.type)) {
+        log('The "%s" attribute uses ConditionalAttributeType[] — unresolved, treating as valid', name);
+        return false;
+    }
     const types = toNonNullableArrayFromItemOrArray(spec.type);
     const invalidMap = new Map();
     for (const type of types) {

package/lib/helpers.js

@@ -1,3 +1,4 @@
+import { isConditionalAttributeTypeArray } from '@markuplint/ml-spec';
 import { attrCheck } from './attr-check.js';
 /**
  * Tests whether an element matches the condition specified in an attribute spec.
@@ -93,8 +94,20 @@ export function isValidAttr(t, name, value, isDynamicValue,
 node, attrSpecs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 log) {
-    const spec = attrSpecs.find(s => s.name.toLowerCase() === name.toLowerCase());
+    let spec = attrSpecs.find(s => s.name.toLowerCase() === name.toLowerCase());
     log?.('Spec of the %s attr: %o', name, spec);
+    // Resolve ConditionalAttributeType[] to a concrete type based on element matching (#3598).
+    if (spec && isConditionalAttributeTypeArray(spec.type)) {
+        const matched = spec.type.find(entry => {
+            const cond = typeof entry.condition === 'string' ? entry.condition : entry.condition.join(',');
+            return node.matches(cond);
+        });
+        log?.('ConditionalAttributeType resolution for %s: %o', name, matched);
+        // Fallback to 'Any' when no condition matches: input types without an explicit
+        // entry (text, search, tel, password, hidden, checkbox, radio, file, submit,
+        // image, reset, button) have no value constraints per the HTML spec.
+        spec = { ...spec, type: matched ? matched.type : 'Any' };
+    }
     const allAttrNames = attrSpecs.map(s => s.name);
     let invalid = attrCheck(t, name, value, false, spec, allAttrNames);
     if (invalid === false &&
@@ -127,6 +140,8 @@ export function toNormalizedValue(value, spec) {
     if (!spec.caseSensitive) {
         normalized = normalized.toLowerCase();
     }
+    // When spec.type is an array (AttributeType[] or ConditionalAttributeType[]),
+    // type-specific normalization is skipped — only caseSensitive applies above.
     if (typeof spec.type === 'string') {
         if (spec.type[0] === '<') {
             normalized = normalized.toLowerCase().trim().replaceAll(/\s+/g, ' ');

package/lib/index.d.ts

@@ -64,7 +64,9 @@ declare const rules: {
     readonly 'no-boolean-attr-value': Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
     readonly 'no-consecutive-br': Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
     readonly 'no-default-value': Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
+    readonly 'no-duplicate-autofocus': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
     readonly 'no-duplicate-dt': Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
+    readonly 'no-duplicate-visible-main': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
     readonly 'no-empty-palpable-content': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, {
         extendsExposableElements?: boolean;
         ignoreIfAriaBusy?: boolean;
@@ -120,5 +122,21 @@ declare const rules: {
         prevCodeBlock?: boolean;
     }>>;
     readonly 'wai-aria': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-abstract-role': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-default-value': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-deprecated-props': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-deprecated-role': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-disallowed-props': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-implicit-props': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-implicit-role': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-interaction-in-hidden': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-no-global-prop': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-non-existent-role': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-permitted-roles': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-presentational-children': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-required-owned-elements': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-required-parent-role': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-required-props': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
+    readonly 'wai-aria-value': Readonly<import("@markuplint/ml-core").RuleSeed<boolean, import("./wai-aria/types.js").Options>>;
 };
 export default rules;

package/lib/index.js

@@ -32,7 +32,9 @@ import NoAmbiguousNavigableTargetNames from './no-ambiguous-navigable-target-nam
 import NoBooleanAttrValue from './no-boolean-attr-value/index.js';
 import NoConsecutiveBr from './no-consecutive-br/index.js';
 import NoDefaultValue from './no-default-value/index.js';
+import NoDuplicateAutofocus from './no-duplicate-autofocus/index.js';
 import NoDuplicateDt from './no-duplicate-dt/index.js';
+import NoDuplicateVisibleMain from './no-duplicate-visible-main/index.js';
 import NoEmptyPalpableContent from './no-empty-palpable-content/index.js';
 import NoHardCodeId from './no-hard-code-id/index.js';
 import NoOrphanedEndTag from './no-orphaned-end-tag/index.js';
@@ -52,6 +54,22 @@ import RequiredH1 from './required-h1/index.js';
 import TableRowColumnAlignment from './table-row-column-alignment/index.js';
 import UseList from './use-list/index.js';
 import WaiAria from './wai-aria/index.js';
+import WaiAriaAbstractRole from './wai-aria-abstract-role/index.js';
+import WaiAriaDefaultValue from './wai-aria-default-value/index.js';
+import WaiAriaDeprecatedProps from './wai-aria-deprecated-props/index.js';
+import WaiAriaDeprecatedRole from './wai-aria-deprecated-role/index.js';
+import WaiAriaDisallowedProps from './wai-aria-disallowed-props/index.js';
+import WaiAriaImplicitProps from './wai-aria-implicit-props/index.js';
+import WaiAriaImplicitRole from './wai-aria-implicit-role/index.js';
+import WaiAriaInteractionInHidden from './wai-aria-interaction-in-hidden/index.js';
+import WaiAriaNoGlobalProp from './wai-aria-no-global-prop/index.js';
+import WaiAriaNonExistentRole from './wai-aria-non-existent-role/index.js';
+import WaiAriaPermittedRoles from './wai-aria-permitted-roles/index.js';
+import WaiAriaPresentationalChildren from './wai-aria-presentational-children/index.js';
+import WaiAriaRequiredOwnedElements from './wai-aria-required-owned-elements/index.js';
+import WaiAriaRequiredParentRole from './wai-aria-required-parent-role/index.js';
+import WaiAriaRequiredProps from './wai-aria-required-props/index.js';
+import WaiAriaValue from './wai-aria-value/index.js';
 /**
  * Registry of all built-in markuplint rules, mapping rule names to their seed definitions.
  * Used by the markuplint core to initialize rule instances during linting.
@@ -83,7 +101,9 @@ const rules = {
     'no-boolean-attr-value': NoBooleanAttrValue,
     'no-consecutive-br': NoConsecutiveBr,
     'no-default-value': NoDefaultValue,
+    'no-duplicate-autofocus': NoDuplicateAutofocus,
     'no-duplicate-dt': NoDuplicateDt,
+    'no-duplicate-visible-main': NoDuplicateVisibleMain,
     'no-empty-palpable-content': NoEmptyPalpableContent,
     'no-hard-code-id': NoHardCodeId,
     'no-orphaned-end-tag': NoOrphanedEndTag,
@@ -103,5 +123,21 @@ const rules = {
     'table-row-column-alignment': TableRowColumnAlignment,
     'use-list': UseList,
     'wai-aria': WaiAria,
+    'wai-aria-abstract-role': WaiAriaAbstractRole,
+    'wai-aria-default-value': WaiAriaDefaultValue,
+    'wai-aria-deprecated-props': WaiAriaDeprecatedProps,
+    'wai-aria-deprecated-role': WaiAriaDeprecatedRole,
+    'wai-aria-disallowed-props': WaiAriaDisallowedProps,
+    'wai-aria-implicit-props': WaiAriaImplicitProps,
+    'wai-aria-implicit-role': WaiAriaImplicitRole,
+    'wai-aria-interaction-in-hidden': WaiAriaInteractionInHidden,
+    'wai-aria-no-global-prop': WaiAriaNoGlobalProp,
+    'wai-aria-non-existent-role': WaiAriaNonExistentRole,
+    'wai-aria-permitted-roles': WaiAriaPermittedRoles,
+    'wai-aria-presentational-children': WaiAriaPresentationalChildren,
+    'wai-aria-required-owned-elements': WaiAriaRequiredOwnedElements,
+    'wai-aria-required-parent-role': WaiAriaRequiredParentRole,
+    'wai-aria-required-props': WaiAriaRequiredProps,
+    'wai-aria-value': WaiAriaValue,
 };
 export default rules;

package/lib/invalid-attr/index.js

@@ -25,6 +25,18 @@ export default createRule({
             if (attr.isDirective) {
                 return;
             }
+            // https://html.spec.whatwg.org/multipage/custom-elements.html#attr-is
+            // "The is attribute must not be specified on an autonomous custom element"
+            if (attr.name === 'is' && attr.ownerElement.elementType === 'web-component') {
+                report({
+                    scope: attr,
+                    line: attr.nameNode?.startLine,
+                    col: attr.nameNode?.startCol,
+                    raw: attr.nameNode?.raw,
+                    message: t('The "{0}" attribute must not be specified on an autonomous custom element', 'is'),
+                });
+                return;
+            }
             const attrSpecs = getAttrSpecs(attr.ownerElement, document.specs);
             const attrName = attr.nameNode;
             const name = attr.name;

package/lib/no-duplicate-autofocus/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ensures no more than one element in a document has the `autofocus` attribute.
+ *
+ * @see https://html.spec.whatwg.org/multipage/interaction.html#the-autofocus-attribute
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
+export default _default;

package/lib/no-duplicate-autofocus/index.js

@@ -0,0 +1,27 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+/**
+ * Ensures no more than one element in a document has the `autofocus` attribute.
+ *
+ * @see https://html.spec.whatwg.org/multipage/interaction.html#the-autofocus-attribute
+ */
+export default createRule({
+    meta: meta,
+    defaultValue: true,
+    defaultOptions: null,
+    async verify({ document, report, t }) {
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        const autofocusElements = [];
+        await document.walkOn('Element', el => {
+            if (el.hasAttribute('autofocus')) {
+                autofocusElements.push(el);
+            }
+        });
+        for (const el of autofocusElements.slice(1)) {
+            report({
+                scope: el,
+                message: t('The "{0}" attribute must be unique in the document', 'autofocus'),
+            });
+        }
+    },
+});

package/lib/no-duplicate-autofocus/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "validation";
+};
+export default _default;

package/lib/no-duplicate-autofocus/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'validation',
+};

package/lib/no-duplicate-visible-main/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ensures no more than one visible `<main>` element exists in a document.
+ * A `<main>` element with the `hidden` attribute is not considered visible.
+ *
+ * @see https://html.spec.whatwg.org/multipage/grouping-content.html#the-main-element
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
+export default _default;

package/lib/no-duplicate-visible-main/index.js

@@ -0,0 +1,28 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+/**
+ * Ensures no more than one visible `<main>` element exists in a document.
+ * A `<main>` element with the `hidden` attribute is not considered visible.
+ *
+ * @see https://html.spec.whatwg.org/multipage/grouping-content.html#the-main-element
+ */
+export default createRule({
+    meta: meta,
+    defaultValue: true,
+    defaultOptions: null,
+    async verify({ document, report, t }) {
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        const visibleMains = [];
+        await document.walkOn('Element', el => {
+            if (el.localName === 'main' && !el.hasAttribute('hidden')) {
+                visibleMains.push(el);
+            }
+        });
+        for (const el of visibleMains.slice(1)) {
+            report({
+                scope: el,
+                message: t('There must not be more than one visible "{0}" element in a document', 'main'),
+            });
+        }
+    },
+});

package/lib/no-duplicate-visible-main/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "validation";
+};
+export default _default;

package/lib/no-duplicate-visible-main/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'validation',
+};

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

@@ -1,4 +1,4 @@
-import type { ChildNode, Options, Result, Specs } from './types.js';
+import type { ChildNode, Mode, Options, Result, Specs, TagRule } from './types.js';
 import type { PermittedContentChoice } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
@@ -13,9 +13,12 @@ import type { ReadonlyDeep } from 'type-fest';
  *
  * @param pattern - The choice pattern containing multiple alternative content model branches.
  * @param childNodes - The child nodes to validate against the choice branches.
+ * @param rules - User-defined tag rules. Threaded through for transparent-model recursion;
+ *                not consulted here directly. See `order` for the rationale.
  * @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.
+ * @param mode - Whether we are evaluating the element's `'origin'` or `'pretended'` identity.
  * @returns A result from the best-matching branch, or the branch that came closest to matching.
  */
-export declare function choice(pattern: ReadonlyDeep<PermittedContentChoice>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;
+export declare function choice(pattern: ReadonlyDeep<PermittedContentChoice>, childNodes: readonly ChildNode[], rules: readonly TagRule[], specs: Specs, options: Options, depth: number, mode: Mode): Result;

package/lib/permitted-contents/choice.js

@@ -18,21 +18,24 @@ const indexes = new WeakMap();
  *
  * @param pattern - The choice pattern containing multiple alternative content model branches.
  * @param childNodes - The child nodes to validate against the choice branches.
+ * @param rules - User-defined tag rules. Threaded through for transparent-model recursion;
+ *                not consulted here directly. See `order` for the rationale.
  * @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.
+ * @param mode - Whether we are evaluating the element's `'origin'` or `'pretended'` identity.
  * @returns A result from the best-matching branch, or the branch that came closest to matching.
  */
 export function choice(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-childNodes, specs, options, depth) {
+childNodes, rules, specs, options, depth, mode) {
     const choiceLog = cmLog.extend(`choice#${depth}`);
     const collection = new Collection(childNodes);
     const unmatchedResults = [];
     let i = 0;
     for (const some of pattern.choice) {
         choiceLog('Patterns[%s]: %s', i, modelLog(some, ''));
-        const result = order(some, collection.unmatched, specs, options, depth + 1);
+        const result = order(some, collection.unmatched, rules, specs, options, depth + 1, mode);
         if (result.type === 'MATCHED' ||
             result.type === 'MATCHED_ZERO' ||
             (result.type === 'UNEXPECTED_EXTRA_NODE' && result.matched.length > 0)) {

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

@@ -1,4 +1,4 @@
-import type { ChildNode, Options, Result, Specs } from './types.js';
+import type { ChildNode, Mode, Options, Result, Specs, TagRule } from './types.js';
 import type { PermittedContentPattern } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
@@ -10,9 +10,12 @@ import type { ReadonlyDeep } from 'type-fest';
  *
  * @param pattern - A single content model pattern to evaluate.
  * @param childNodes - The child nodes to validate against the pattern.
+ * @param rules - User-defined tag rules. Threaded through for transparent-model recursion;
+ *                not consulted here directly. See `order` for the rationale.
  * @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.
+ * @param mode - Whether we are evaluating the element's `'origin'` or `'pretended'` identity.
  * @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;
+export declare function complexBranch(pattern: ReadonlyDeep<PermittedContentPattern>, childNodes: readonly ChildNode[], rules: readonly TagRule[], specs: Specs, options: Options, depth: number, mode: Mode): Result;

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

@@ -11,19 +11,22 @@ import { isChoice, isTransparent } from './utils.js';
  *
  * @param pattern - A single content model pattern to evaluate.
  * @param childNodes - The child nodes to validate against the pattern.
+ * @param rules - User-defined tag rules. Threaded through for transparent-model recursion;
+ *                not consulted here directly. See `order` for the rationale.
  * @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.
+ * @param mode - Whether we are evaluating the element's `'origin'` or `'pretended'` identity.
  * @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
-childNodes, specs, options, depth) {
+childNodes, rules, specs, options, depth, mode) {
     if (isChoice(pattern)) {
-        return choice(pattern, childNodes, specs, options, depth);
+        return choice(pattern, childNodes, rules, specs, options, depth, mode);
     }
     if (isTransparent(pattern)) {
         return transparent(childNodes);
     }
-    return countPattern(pattern, childNodes, specs, options, depth);
+    return countPattern(pattern, childNodes, rules, specs, options, depth, mode);
 }

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

@@ -1,4 +1,6 @@
-import type { ContentModelResult, Element, Options, TagRule } from './types.js';
+import type { ContentModelResult, Element, Mode, Options, Specs, TagRule } from './types.js';
+import type { ContentModel } from '@markuplint/ml-spec';
+import type { ReadonlyDeep } from 'type-fest';
 /**
  * Top-level entry point for content model validation of a single element.
  * Resolves the element's content model from the spec (possibly augmented
@@ -8,6 +10,23 @@ import type { ContentModelResult, Element, Options, TagRule } from './types.js';
  * @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).
+ * @param mode - Which identity to evaluate the element as (`'origin'` consults user
+ *               rules keyed on the pre-pretender AST name; `'pretended'` uses the
+ *               HTML spec for the pretender target).
  * @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[];
+export declare function contentModel(el: Element, rules: readonly TagRule[], options: Options, mode: Mode): ContentModelResult[];
+/**
+ * Resolves the content model for an element while honoring the current
+ * {@link Mode}. In `'origin'` mode for a pretendered element, the lookup
+ * first consults user-defined tag rules keyed on the element's original AST
+ * name (`rawName`); if no such rule exists the returned model is `null`,
+ * which signals the caller to skip validation for this mode. In all other
+ * cases the standard spec lookup (`getContentModel`) is used, which keys on
+ * the visible `localName` — i.e. the pretender target when pretending is
+ * active.
+ *
+ * Exported so that {@link representTransparentNodes} can reuse the same
+ * resolution logic when recursing into child content models.
+ */
+export declare function resolveContentModel(el: Element, rules: readonly TagRule[], specs: Specs, mode: Mode): ReadonlyDeep<ContentModel['contents']> | null;

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

@@ -9,12 +9,15 @@ import { start } from './start.js';
  * @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).
+ * @param mode - Which identity to evaluate the element as (`'origin'` consults user
+ *               rules keyed on the pre-pretender AST name; `'pretended'` uses the
+ *               HTML spec for the pretender target).
  * @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) {
-    const { model, specs } = createModel(el, rules);
+el, rules, options, mode) {
+    const { model, specs } = createModel(el, rules, mode);
     if (model == null) {
         return [
             {
@@ -25,28 +28,51 @@ el, rules, options) {
             },
         ];
     }
-    const result = start(model, el, specs, options);
+    const result = start(model, el, rules, specs, options, mode);
     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.
+ * tag rules, then resolves the content model for the current {@link Mode}.
  *
  * @param el - The element to look up the content model for.
  * @param rules - User-defined tag rules to merge into the spec.
+ * @param mode - Which identity to resolve against.
  * @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) {
+el, rules, mode) {
     const specs = cachedSpecs(el.ownerMLDocument.specs, rules);
-    const model = getContentModel(el, specs.specs);
+    const model = resolveContentModel(el, rules, specs, mode);
     return {
         model,
         specs,
     };
 }
+/**
+ * Resolves the content model for an element while honoring the current
+ * {@link Mode}. In `'origin'` mode for a pretendered element, the lookup
+ * first consults user-defined tag rules keyed on the element's original AST
+ * name (`rawName`); if no such rule exists the returned model is `null`,
+ * which signals the caller to skip validation for this mode. In all other
+ * cases the standard spec lookup (`getContentModel`) is used, which keys on
+ * the visible `localName` — i.e. the pretender target when pretending is
+ * active.
+ *
+ * Exported so that {@link representTransparentNodes} can reuse the same
+ * resolution logic when recursing into child content models.
+ */
+export function resolveContentModel(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, rules, specs, mode) {
+    if (mode === 'origin' && el.pretenderContext?.type === 'pretender') {
+        const userRule = rules.find(r => r.tag === el.rawName);
+        return userRule?.contents ?? null;
+    }
+    return getContentModel(el, specs.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.

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

@@ -1,4 +1,4 @@
-import type { ChildNode, Options, Result, Specs } from './types.js';
+import type { ChildNode, Mode, Options, Result, Specs, TagRule } from './types.js';
 import type { PermittedContentOneOrMore, PermittedContentOptional, PermittedContentRequire, PermittedContentZeroOrMore } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
@@ -12,9 +12,12 @@ import type { ReadonlyDeep } from 'type-fest';
  *
  * @param pattern - A quantified content model pattern (require, optional, oneOrMore, or zeroOrMore).
  * @param childNodes - The child nodes to validate against the repeated pattern.
+ * @param rules - User-defined tag rules. Threaded through for transparent-model recursion;
+ *                not consulted here directly. See `order` for the rationale.
  * @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.
+ * @param mode - Whether we are evaluating the element's `'origin'` or `'pretended'` identity.
  * @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;
+export declare function countPattern(pattern: ReadonlyDeep<PermittedContentOneOrMore> | ReadonlyDeep<PermittedContentOptional> | ReadonlyDeep<PermittedContentRequire> | ReadonlyDeep<PermittedContentZeroOrMore>, childNodes: readonly ChildNode[], rules: readonly TagRule[], specs: Specs, options: Options, depth: number, mode: Mode): Result;