@markuplint/parser-utils 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+**Note:** Version bump only for package @markuplint/parser-utils
+
+
+
+
+
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+* **parser-utils:** map an IDL name by its exact spelling ([3eac033](https://github.com/markuplint/markuplint/commit/3eac033da5d20884bf00f4defeccb3be9c7d44bf))
+* **rules:** tell the namespace of a component's prop by the name as written ([157f434](https://github.com/markuplint/markuplint/commit/157f434b9dc4bb0f51c3fb77b219f38ef4035dd8))
+
+### Features
+
+* **ml-core:** ask whether a name is a prefix of an attribute, and keep suggesting the property ([bd195ef](https://github.com/markuplint/markuplint/commit/bd195ef6ededb80482c642a86360c5f932f8b91b))
+* **parser-utils:** add isComponentName to tell a component name from an element name ([3385e5b](https://github.com/markuplint/markuplint/commit/3385e5b874290ec6c9d23c769d50e8741a0ce8af))
+* **parser-utils:** add the attrNameCaseSensitive parser option ([d494501](https://github.com/markuplint/markuplint/commit/d49450161f5de6dfcd8e035db5b39eeb3815d396)), closes [#4229](https://github.com/markuplint/markuplint/issues/4229)
+* **parser-utils:** let a parser decide which character starts a tag name ([720022f](https://github.com/markuplint/markuplint/commit/720022ff33bd103c20827e232acb16a0da8230bc))
+* **parser-utils:** let a parser own the rule of its component names ([92d5048](https://github.com/markuplint/markuplint/commit/92d5048a174bfa39e0624ece4ec71e0b00a2bae0)), closes [Parser#isComponentName](https://github.com/Parser/issues/isComponentName)
+* **parser-utils:** let a parser say how an attribute name gets into the DOM ([abd81e5](https://github.com/markuplint/markuplint/commit/abd81e5d20f4ffeb0ba878e77fd4122c1a803a9f))
+
+### Performance Improvements
+
+* **parser-utils:** skip debug maps when logging is disabled ([47466b0](https://github.com/markuplint/markuplint/commit/47466b00d5d4c4fc121ed55d22e11540cd1ed0cd))
+* **selector:** read the debug flag once per match and pass it down ([1e99fc0](https://github.com/markuplint/markuplint/commit/1e99fc095aa57c9cadf08a55e109a1f75c0b31ca))
+
+
 # [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
 
 ### Bug Fixes

package/lib/debug.d.ts

@@ -1,5 +1,9 @@
 import type { MLASTNode } from '@markuplint/ml-ast';
 import debug from 'debug';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export declare const log: debug.Debugger;
 export declare function domLog(nodeList: readonly (MLASTNode | null)[]): void;
 export declare class PerformanceTimer {

package/lib/debug.js

@@ -1,7 +1,14 @@
 import debug from 'debug';
 import { nodeListToDebugMaps } from './debugger.js';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export const log = debug('ml-parser');
 export function domLog(nodeList) {
+    if (!log.enabled) {
+        return;
+    }
     log('Parse result: %O', nodeListToDebugMaps(nodeList, true));
 }
 export class PerformanceTimer {

package/lib/decision.d.ts

@@ -1,2 +1,27 @@
 export declare function isSVGElement(nodeName: string): boolean;
 export declare function isPotentialCustomElementName(tagName: string): boolean;
+/**
+ * Whether `name` is a reference to a component, not the name of an element, judged by
+ * its form alone.
+ *
+ * The scanners of `pretenders.auto` / `pretenders.scan` follow what a component
+ * renders until they reach a name they cannot resolve (a component of a package, a
+ * member expression such as `Tabs.Root`, a local variable, a namespace import, a
+ * component past the depth limit), and emit that name unchanged. Such a name is never
+ * an element: the names of HTML, SVG and MathML elements start with a lowercase
+ * letter and have no `.` (the camelCase of `foreignObject` starts with one), and the
+ * `.` is valid only in a custom element name, which a hyphen and a lowercase start
+ * give away. So the form of the name tells, however the chain stopped.
+ *
+ * This is the form that most languages share, and the default of `Parser#isComponentName`.
+ * A parser of a language that names its components otherwise overrides that method, and what asks
+ * (the scanners, `ml-core`, `pretenders`) asks the parser, not this function. It is called by name for a
+ * parser that says nothing and for a file of a language that has no parser to ask.
+ *
+ * The case sensitivity of the document is not part of the criterion, nor is the user's pattern for
+ * authored names (`authoredElementName`): the scanners and ml-core must agree on the rule of the language.
+ *
+ * @param name - A tag name as written, case kept
+ * @returns Whether the name is a component's
+ */
+export declare function isComponentName(name: string): boolean;

package/lib/decision.js

@@ -7,3 +7,30 @@ const isCEN = isCustomElementName();
 export function isPotentialCustomElementName(tagName) {
     return isCEN(tagName);
 }
+/**
+ * Whether `name` is a reference to a component, not the name of an element, judged by
+ * its form alone.
+ *
+ * The scanners of `pretenders.auto` / `pretenders.scan` follow what a component
+ * renders until they reach a name they cannot resolve (a component of a package, a
+ * member expression such as `Tabs.Root`, a local variable, a namespace import, a
+ * component past the depth limit), and emit that name unchanged. Such a name is never
+ * an element: the names of HTML, SVG and MathML elements start with a lowercase
+ * letter and have no `.` (the camelCase of `foreignObject` starts with one), and the
+ * `.` is valid only in a custom element name, which a hyphen and a lowercase start
+ * give away. So the form of the name tells, however the chain stopped.
+ *
+ * This is the form that most languages share, and the default of `Parser#isComponentName`.
+ * A parser of a language that names its components otherwise overrides that method, and what asks
+ * (the scanners, `ml-core`, `pretenders`) asks the parser, not this function. It is called by name for a
+ * parser that says nothing and for a file of a language that has no parser to ask.
+ *
+ * The case sensitivity of the document is not part of the criterion, nor is the user's pattern for
+ * authored names (`authoredElementName`): the scanners and ml-core must agree on the rule of the language.
+ *
+ * @param name - A tag name as written, case kept
+ * @returns Whether the name is a component's
+ */
+export function isComponentName(name) {
+    return /^[A-Z]|\./.test(name) && !isPotentialCustomElementName(name);
+}

package/lib/detect-element-type.js

@@ -20,14 +20,25 @@ function _distinguishAuthoredName(name, patterns) {
         if (typeof pattern === 'function') {
             return pattern(name);
         }
-        const regex = typeof pattern === 'string' ? toRegexp(pattern) : pattern;
-        return regex.test(name);
+        if (typeof pattern === 'string') {
+            const regex = toRegexp(pattern);
+            return regex ? regex.test(name) : name === pattern;
+        }
+        return pattern.test(name);
     });
 }
+/**
+ * A string in the form of a regular expression literal (`/^[A-Z]/i`, with the flags `g` and `i` at most) is that regular
+ * expression. Any other string is a name, and stands for the whole name only: `component`
+ * is `<component>`, not `<my-component>` nor `<components>`, and a character such as `.`
+ * is that character. So a name is written as it is, as in the examples of `authoredElementName`.
+ *
+ * @returns The regular expression, or `null` for a name
+ */
 function toRegexp(pattern) {
     const matched = pattern.match(/^\/(.+)\/([gi]*)$/i);
     if (matched && matched[1]) {
         return new RegExp(matched[1], matched[2]);
     }
-    return new RegExp(pattern);
+    return null;
 }

package/lib/idl-attributes.d.ts

@@ -1,13 +1,28 @@
 /**
  * Searches the IDL-to-content-attribute mapping to find the corresponding
  * IDL property name and content attribute name for a given attribute name.
- * Handles camelCase IDL names, lowercase content attribute names, hyphenated names,
- * and event handler attributes (e.g., `onclick`).
  *
- * @param name - The attribute name to look up (can be IDL, content, or hyphenated form)
+ * A name is mapped by its exact spelling: the IDL property name (`tabIndex`, `strokeWidth`) or the
+ * content attribute name (`tabindex`, `stroke-width`). A spelling in another case (`TABINDEX`) is
+ * another name here, because a framework reads its own property names as they are written (JSX
+ * `onClick` is a JavaScript identifier). Whether such a name is still the same attribute in the DOM is
+ * decided by `MLAttr#isNamedBy` of `@markuplint/ml-core`, not here. An event handler
+ * (`onclick`) is its own name in lower case.
+ *
+ * @param name - The attribute name to look up (the IDL or the content spelling, exactly)
  * @returns An object with the matching `idlPropName` and `contentAttrName`, both undefined if no match is found
  */
 export declare function searchIDLAttribute(name: string): {
     idlPropName: string | undefined;
     contentAttrName: string | undefined;
 };
+/**
+ * Finds the IDL property that a name suggests whatever the case it is written in: `TABINDEX`,
+ * `tab-index` and `tabindex` suggest `tabIndex`. It is for a message that says how the framework
+ * spells the name (a suggestion), not for the name of an attribute: that is
+ * {@link searchIDLAttribute}, which reads a spelling exactly.
+ *
+ * @param name - The attribute name, in any case
+ * @returns The IDL property name, undefined if no name of the mapping is like it
+ */
+export declare function suggestIDLAttribute(name: string): string | undefined;

package/lib/idl-attributes.js

@@ -416,30 +416,64 @@ const idlContentMap = {
     credentialless: 'credentialless',
 };
 const list = Object.entries(idlContentMap);
+// The first entry of a name wins. They are built once: a name is looked up for every attribute of a document.
+const byIdlPropName = new Map();
+const byContentAttrName = new Map();
+for (const entry of list) {
+    if (!byIdlPropName.has(entry[0])) {
+        byIdlPropName.set(entry[0], entry);
+    }
+    if (!byContentAttrName.has(entry[1])) {
+        byContentAttrName.set(entry[1], entry);
+    }
+}
 /**
  * Searches the IDL-to-content-attribute mapping to find the corresponding
  * IDL property name and content attribute name for a given attribute name.
- * Handles camelCase IDL names, lowercase content attribute names, hyphenated names,
- * and event handler attributes (e.g., `onclick`).
  *
- * @param name - The attribute name to look up (can be IDL, content, or hyphenated form)
+ * A name is mapped by its exact spelling: the IDL property name (`tabIndex`, `strokeWidth`) or the
+ * content attribute name (`tabindex`, `stroke-width`). A spelling in another case (`TABINDEX`) is
+ * another name here, because a framework reads its own property names as they are written (JSX
+ * `onClick` is a JavaScript identifier). Whether such a name is still the same attribute in the DOM is
+ * decided by `MLAttr#isNamedBy` of `@markuplint/ml-core`, not here. An event handler
+ * (`onclick`) is its own name in lower case.
+ *
+ * @param name - The attribute name to look up (the IDL or the content spelling, exactly)
  * @returns An object with the matching `idlPropName` and `contentAttrName`, both undefined if no match is found
  */
 export function searchIDLAttribute(name) {
-    const camelizedName = camelize(name);
     const [idlPropName, contentAttrName] = /^on[a-z]/.test(name)
         ? [name.toLowerCase(), name.toLowerCase()]
-        : (list.find(([idlPropName, contentAttrName]) => idlPropName.toLowerCase() === camelizedName.toLowerCase() ||
-            contentAttrName.toLowerCase() === name.toLowerCase() ||
-            hyphenize(idlPropName) === name.toLowerCase()) ?? []);
+        : (byIdlPropName.get(name) ?? byContentAttrName.get(name) ?? []);
     return {
         idlPropName,
         contentAttrName,
     };
 }
-function camelize(str) {
-    return str.replaceAll(/[:-][a-z]/g, $0 => $0[1]?.toUpperCase() ?? '');
+// The IDL property that a name of another spelling suggests, by the lower-case of its IDL name, of its
+// content name, and of its hyphenated form. The first entry of the list wins.
+const suggestions = new Map();
+for (const [idlPropName, contentAttrName] of list) {
+    for (const key of [
+        idlPropName.toLowerCase(),
+        contentAttrName.toLowerCase(),
+        idlPropName.replaceAll(/[A-Z]/g, c => `-${c.toLowerCase()}`),
+    ]) {
+        if (!suggestions.has(key)) {
+            suggestions.set(key, idlPropName);
+        }
+    }
 }
-function hyphenize(str) {
-    return str.replaceAll(/[A-Z]/g, $0 => `-${$0.toLowerCase()}`);
+/**
+ * Finds the IDL property that a name suggests whatever the case it is written in: `TABINDEX`,
+ * `tab-index` and `tabindex` suggest `tabIndex`. It is for a message that says how the framework
+ * spells the name (a suggestion), not for the name of an attribute: that is
+ * {@link searchIDLAttribute}, which reads a spelling exactly.
+ *
+ * @param name - The attribute name, in any case
+ * @returns The IDL property name, undefined if no name of the mapping is like it
+ */
+export function suggestIDLAttribute(name) {
+    const lower = name.toLowerCase();
+    return suggestions.get(lower) ?? suggestions.get(lower.replaceAll(/[:-]/g, ''));
 }

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './debugger.js';
+export * from './decision.js';
 export * from './enums.js';
 export * from './get-namespace.js';
 export * from './idl-attributes.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './debugger.js';
+export * from './decision.js';
 export * from './enums.js';
 export * from './get-namespace.js';
 export * from './idl-attributes.js';

package/lib/parser.d.ts

@@ -1,5 +1,5 @@
 import type { Token, ChildToken, QuoteSet, ParseOptions, ParserOptions, Tokenized, ValueType } from './types.js';
-import type { EndTagType, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTBlockBehavior, MLASTParseError } from '@markuplint/ml-ast';
+import type { AttrNameRoute, EndTagType, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTBlockBehavior, MLASTParseError } from '@markuplint/ml-ast';
 import { AttrState } from './enums.js';
 import { ParserError } from './parser-error.js';
 /**
@@ -73,6 +73,27 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * When false (the default), tag name comparisons are case-insensitive (HTML behavior).
      */
     get tagNameCaseSensitive(): boolean;
+    /**
+     * Whether a component is referred to by any spelling of its name (`<FooBar>`, `<fooBar>`
+     * and `<foo-bar>` are one component). Only Vue resolves a tag so; see
+     * {@link MLParser.componentNameVariants} in `@markuplint/ml-ast`.
+     */
+    get componentNameVariants(): boolean;
+    /**
+     * Whether attribute names are case-sensitive in this language (JSX props such as
+     * `onClick`). Independent of {@link Parser.tagNameCaseSensitive}: Svelte and Astro
+     * distinguish components by tag-name case but lowercase or pass through HTML
+     * attribute names, so they leave this `false`.
+     */
+    get attrNameCaseSensitive(): boolean;
+    /**
+     * How the name of an attribute gets into the DOM of the browser (see `AttrNameRoute`), which decides
+     * whether another spelling of the name is the same attribute. Independent of
+     * {@link Parser.attrNameCaseSensitive}, which is about the style rules: Vue sets its attributes through
+     * the DOM API, but its names are not JavaScript identifiers, so a template is still checked for the
+     * case of a name. The HTML parser of the browser by default.
+     */
+    get attrNameRoute(): AttrNameRoute;
     /**
      * Tokenizes the raw source code into language-specific AST nodes.
      * Subclasses should override this method to provide actual tokenization logic.
@@ -264,7 +285,14 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
     /**
      * Traverses a list of child nodes under the given parent, appending the resulting
      * child AST nodes to the parent and returning any sibling nodes that belong
-     * to ancestor levels. Skips traversal for raw text elements (e.g., `<script>`, `<style>`).
+     * to ancestor levels.
+     *
+     * Children of a raw-text element (`rawTextElements`; `style` and `script` by
+     * default) are dropped on purpose. Their body is CSS or JavaScript, not markup,
+     * so it gets no text node and the element reads as empty downstream
+     * (`textContent === ''`, no `childNodes`, no `Text` visit). A rule that needs the
+     * body reads it from the document source between the element's `endOffset` and
+     * its `closeTag.startOffset`, when a close tag is present.
      *
      * @param children - The language-specific child AST nodes to traverse
      * @param parentNode - The parent markuplint AST node to which children will be appended
@@ -366,10 +394,42 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * given tag name, using the parser's authored element name distinguishing pattern.
      *
      * @param nodeName - The tag name to classify
-     * @param defaultPattern - A fallback pattern if no authored element name pattern is set
+     * @param defaultPattern - A fallback pattern if no authored element name pattern is set: a regular
+     *   expression, a name, or a function (a parser of a language that decides by a rule passes
+     *   `name => this.isComponentName(name)`)
      * @returns The element type classification
      */
     detectElementType(nodeName: string, defaultPattern?: ParserAuthoredElementNameDistinguishing): ElementType;
+    /**
+     * Whether a character can be the first of a tag name, where the tag scanner reads a `<` followed by it as a
+     * start tag. Anything else after a `<` leaves it as text (`a < b`, `<3`).
+     *
+     * The default is an ASCII letter, the rule of the HTML tokenizer ("tag open state") that most
+     * languages share. A parser of a language whose element names start otherwise overrides this
+     * (JSX: `$`, `_` and a letter of any script).
+     *
+     * @param char - The character that follows `<`
+     * @returns Whether it starts a tag name
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
+     */
+    isTagNameStart(char: string): boolean;
+    /**
+     * Whether a name is a reference to a component, not the name of an element, judged by its form
+     * alone in the language this parser reads. The scanners of `pretenders` end a chain of what a
+     * component renders at a name they cannot resolve (`Tabs.Root`, a variable) and emit it as it is,
+     * and a pretender's target (`as.element`) is typed by it, so what the scanners and `ml-core` take
+     * for a component has to be the parser's own answer.
+     *
+     * The default is the form that most languages share: a capital initial or a `.` in a name that
+     * is not that of a custom element (the `isComponentName` function of `./decision.ts`). A parser of a language that
+     * names its components otherwise overrides this, as it overrides {@link detectElementType}; this
+     * class names no language. The user's `authoredElementName` is not part of the answer: it is
+     * the user's choice of what to call an authored element in a document, not the language's rule.
+     *
+     * @param name - A tag name as written, case kept
+     * @returns Whether the name is a component's
+     */
+    isComponentName(name: string): boolean;
     /**
      * Creates a new MLASTToken with a generated UUID.
      * Accepts either a Token object or a raw string with explicit start coordinates.

package/lib/parser.js

@@ -3,6 +3,7 @@ import { isVoidElement as detectVoidElement } from '@markuplint/ml-spec';
 import { attrTokenizer } from './attr-tokenizer.js';
 import { defaultSpaces } from './const.js';
 import { domLog, PerformanceTimer } from './debug.js';
+import { isComponentName } from './decision.js';
 import { detectElementType } from './detect-element-type.js';
 import { AttrState, TagState } from './enums.js';
 import { getEndCol, getEndLine, getOffsetsFromCode, getPosition } from './get-location.js';
@@ -46,6 +47,9 @@ export class Parser {
     #ignoreTags = [];
     #maskChar;
     #tagNameCaseSensitive = false;
+    #componentNameVariants = false;
+    #attrNameCaseSensitive = false;
+    #attrNameRoute = 'html-parser';
     #selfCloseType = 'html';
     #spaceChars = defaultSpaces;
     #rawTextElements = ['style', 'script'];
@@ -86,6 +90,9 @@ export class Parser {
         this.#ignoreTags = options?.ignoreTags ?? this.#ignoreTags;
         this.#maskChar = options?.maskChar ?? this.#maskChar;
         this.#tagNameCaseSensitive = options?.tagNameCaseSensitive ?? this.#tagNameCaseSensitive;
+        this.#componentNameVariants = options?.componentNameVariants ?? this.#componentNameVariants;
+        this.#attrNameCaseSensitive = options?.attrNameCaseSensitive ?? this.#attrNameCaseSensitive;
+        this.#attrNameRoute = options?.attrNameRoute ?? this.#attrNameRoute;
         this.#selfCloseType = options?.selfCloseType ?? this.#selfCloseType;
         this.#spaceChars = options?.spaceChars ?? this.#spaceChars;
         this.#rawTextElements = options?.rawTextElements ?? this.#rawTextElements;
@@ -136,6 +143,33 @@ export class Parser {
     get tagNameCaseSensitive() {
         return this.#tagNameCaseSensitive;
     }
+    /**
+     * Whether a component is referred to by any spelling of its name (`<FooBar>`, `<fooBar>`
+     * and `<foo-bar>` are one component). Only Vue resolves a tag so; see
+     * {@link MLParser.componentNameVariants} in `@markuplint/ml-ast`.
+     */
+    get componentNameVariants() {
+        return this.#componentNameVariants;
+    }
+    /**
+     * Whether attribute names are case-sensitive in this language (JSX props such as
+     * `onClick`). Independent of {@link Parser.tagNameCaseSensitive}: Svelte and Astro
+     * distinguish components by tag-name case but lowercase or pass through HTML
+     * attribute names, so they leave this `false`.
+     */
+    get attrNameCaseSensitive() {
+        return this.#attrNameCaseSensitive;
+    }
+    /**
+     * How the name of an attribute gets into the DOM of the browser (see `AttrNameRoute`), which decides
+     * whether another spelling of the name is the same attribute. Independent of
+     * {@link Parser.attrNameCaseSensitive}, which is about the style rules: Vue sets its attributes through
+     * the DOM API, but its names are not JavaScript identifiers, so a template is still checked for the
+     * case of a name. The HTML parser of the browser by default.
+     */
+    get attrNameRoute() {
+        return this.#attrNameRoute;
+    }
     /**
      * Tokenizes the raw source code into language-specific AST nodes.
      * Subclasses should override this method to provide actual tokenization logic.
@@ -576,7 +610,14 @@ export class Parser {
     /**
      * Traverses a list of child nodes under the given parent, appending the resulting
      * child AST nodes to the parent and returning any sibling nodes that belong
-     * to ancestor levels. Skips traversal for raw text elements (e.g., `<script>`, `<style>`).
+     * to ancestor levels.
+     *
+     * Children of a raw-text element (`rawTextElements`; `style` and `script` by
+     * default) are dropped on purpose. Their body is CSS or JavaScript, not markup,
+     * so it gets no text node and the element reads as empty downstream
+     * (`textContent === ''`, no `childNodes`, no `Text` visit). A rule that needs the
+     * body reads it from the document source between the element's `endOffset` and
+     * its `closeTag.startOffset`, when a close tag is present.
      *
      * @param children - The language-specific child AST nodes to traverse
      * @param parentNode - The parent markuplint AST node to which children will be appended
@@ -896,12 +937,48 @@ export class Parser {
      * given tag name, using the parser's authored element name distinguishing pattern.
      *
      * @param nodeName - The tag name to classify
-     * @param defaultPattern - A fallback pattern if no authored element name pattern is set
+     * @param defaultPattern - A fallback pattern if no authored element name pattern is set: a regular
+     *   expression, a name, or a function (a parser of a language that decides by a rule passes
+     *   `name => this.isComponentName(name)`)
      * @returns The element type classification
      */
     detectElementType(nodeName, defaultPattern) {
         return detectElementType(nodeName, this.#authoredElementName, defaultPattern);
     }
+    /**
+     * Whether a character can be the first of a tag name, where the tag scanner reads a `<` followed by it as a
+     * start tag. Anything else after a `<` leaves it as text (`a < b`, `<3`).
+     *
+     * The default is an ASCII letter, the rule of the HTML tokenizer ("tag open state") that most
+     * languages share. A parser of a language whose element names start otherwise overrides this
+     * (JSX: `$`, `_` and a letter of any script).
+     *
+     * @param char - The character that follows `<`
+     * @returns Whether it starts a tag name
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
+     */
+    isTagNameStart(char) {
+        return /[a-z]/i.test(char);
+    }
+    /**
+     * Whether a name is a reference to a component, not the name of an element, judged by its form
+     * alone in the language this parser reads. The scanners of `pretenders` end a chain of what a
+     * component renders at a name they cannot resolve (`Tabs.Root`, a variable) and emit it as it is,
+     * and a pretender's target (`as.element`) is typed by it, so what the scanners and `ml-core` take
+     * for a component has to be the parser's own answer.
+     *
+     * The default is the form that most languages share: a capital initial or a `.` in a name that
+     * is not that of a custom element (the `isComponentName` function of `./decision.ts`). A parser of a language that
+     * names its components otherwise overrides this, as it overrides {@link detectElementType}; this
+     * class names no language. The user's `authoredElementName` is not part of the answer: it is
+     * the user's choice of what to call an authored element in a document, not the language's rule.
+     *
+     * @param name - A tag name as written, case kept
+     * @returns Whether the name is a component's
+     */
+    isComponentName(name) {
+        return isComponentName(name);
+    }
     createToken(token, offset, line, col) {
         const props = typeof token === 'string'
             ? {
@@ -1251,7 +1328,7 @@ export class Parser {
                     break;
                 }
                 case TagState.FirstCharOfTagName: {
-                    if (/[a-z]/i.test(char)) {
+                    if (this.isTagNameStart(char)) {
                         tagName += char;
                         state = TagState.TagName;
                         break;

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { EndTagType, MLASTParentNode, MLASTParseError, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
+import type { AttrNameRoute, EndTagType, MLASTParentNode, MLASTParseError, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
 /**
  * Configuration options for initializing a Parser instance,
  * controlling how the parser handles tags, attributes, and whitespace.
@@ -9,6 +9,9 @@ export type ParserOptions = {
     readonly ignoreTags?: readonly IgnoreTag[];
     readonly maskChar?: string;
     readonly tagNameCaseSensitive?: boolean;
+    readonly componentNameVariants?: boolean;
+    readonly attrNameCaseSensitive?: boolean;
+    readonly attrNameRoute?: AttrNameRoute;
     readonly selfCloseType?: SelfCloseType;
     readonly spaceChars?: readonly string[];
     readonly rawTextElements?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/parser-utils",
-	"version": "5.2.0",
+	"version": "5.4.0",
 	"description": "Utility module for markuplint parser plugin",
 	"repository": {
 		"type": "git",
@@ -15,12 +15,12 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
 		},
 		"./location": {
-			"import": "./lib/get-location.js",
-			"types": "./lib/get-location.d.ts"
+			"types": "./lib/get-location.d.ts",
+			"default": "./lib/get-location.js"
 		}
 	},
 	"publishConfig": {
@@ -35,16 +35,16 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.1.1",
-		"@markuplint/ml-spec": "5.2.0",
-		"@markuplint/shared": "5.2.0",
-		"@markuplint/types": "5.2.0",
+		"@markuplint/ml-ast": "5.3.0",
+		"@markuplint/ml-spec": "5.4.0",
+		"@markuplint/shared": "5.4.0",
+		"@markuplint/types": "5.4.0",
 		"debug": "^4.4.3",
 		"espree": "^11.2.0",
 		"type-fest": "^5.10.0"
 	},
 	"devDependencies": {
-		"@typescript-eslint/typescript-estree": "8.71.1"
+		"@typescript-eslint/typescript-estree": "8.71.2"
 	},
-	"gitHead": "d8b2feab77c9c862513615bea6b80d2817431878"
+	"gitHead": "ab56aa8e12b67fbf793ddf1267aaba9fda90269d"
 }