@markuplint/parser-utils 5.4.0 → 5.6.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.6.0](https://github.com/markuplint/markuplint/compare/v5.5.0...v5.6.0) (2026-11-12)
+
+### Bug Fixes
+
+* **parser-utils:** map the IDL attribute acceptCharset to accept-charset ([6f78de8](https://github.com/markuplint/markuplint/commit/6f78de8f503cb88f4e3e433989318fdff83e18f5)), closes [#4571](https://github.com/markuplint/markuplint/issues/4571)
+
+### Features
+
+* **parser-utils:** let a parser declare slotElement ([c6f97c5](https://github.com/markuplint/markuplint/commit/c6f97c5cd4f190843c00d1d8e89fbff4ca9097db))
+
+
+# [5.5.0](https://github.com/markuplint/markuplint/compare/v5.4.0...v5.5.0) (2026-11-10)
+
+### Bug Fixes
+
+* **parser-utils:** skip a leading BOM before tokenization ([9fa8c85](https://github.com/markuplint/markuplint/commit/9fa8c8584b765667530e1d7224530ff7ce37474d)), closes [#4488](https://github.com/markuplint/markuplint/issues/4488)
+
+### Features
+
+* **parser-utils:** read a literal in the code of an attribute value ([d83b4a0](https://github.com/markuplint/markuplint/commit/d83b4a091b1e78975ab12b81be7096356a95e9c0))
+
+
 # [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

package/lib/idl-attributes.js

@@ -6,7 +6,7 @@
 const idlContentMap = {
     // HTML
     accept: 'accept',
-    acceptCharset: 'acceptcharset',
+    acceptCharset: 'accept-charset',
     accessKey: 'accesskey',
     action: 'action',
     allowFullScreen: 'allowfullscreen',
@@ -402,8 +402,8 @@ const idlContentMap = {
      * PerformanceElementTiming API
      *
      * @experimental
-     * @see https://wicg.github.io/element-timing/#sec-modifications-DOM
-     * @see https://wicg.github.io/element-timing/#sec-elements-exposed
+     * @see https://w3c.github.io/element-timing/#sec-modifications-DOM
+     * @see https://w3c.github.io/element-timing/#sec-elements-exposed
      */
     elementTiming: 'elementtiming',
     /**

package/lib/index.d.ts

@@ -3,6 +3,8 @@ export * from './decision.js';
 export * from './enums.js';
 export * from './get-namespace.js';
 export * from './idl-attributes.js';
+export * from './is-braced-expression.js';
+export * from './parse-literal-expression.js';
 export * from './parser-error.js';
 export * from './parser.js';
 export * from './script-parser.js';

package/lib/index.js

@@ -3,6 +3,8 @@ export * from './decision.js';
 export * from './enums.js';
 export * from './get-namespace.js';
 export * from './idl-attributes.js';
+export * from './is-braced-expression.js';
+export * from './parse-literal-expression.js';
 export * from './parser-error.js';
 export * from './parser.js';
 export * from './script-parser.js';

package/lib/is-braced-expression.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a text is one expression in braces and nothing else (`{false}`, `{ {a: 1} }`), and not
+ * several (`{a}{b}`) or an expression with text around it (`page/{p}`, `{a} text`). Svelte reads an
+ * attribute value in quotes that is one expression as the expression
+ * (`disabled="{false}"` is `disabled={false}`).
+ *
+ * The check is of the braces: the first `{` is closed by the last `}`, so no `}` closes it before
+ * the end. Strings and template literals are read as such, so a brace in them does not count. The
+ * code in the braces is not checked to be valid JavaScript (it may be TypeScript).
+ *
+ * The catch below does not use `isFatalError`, as for `parseLiteralExpression`: espree reports the
+ * author's code by a `SyntaxError`, which here means that the text is not one expression.
+ *
+ * @param raw - The text of an attribute value
+ * @returns `true` if the whole text is one expression in braces
+ */
+export declare function isBracedExpression(raw: string): boolean;

package/lib/is-braced-expression.js

@@ -0,0 +1,52 @@
+import { scriptParser } from './script-parser.js';
+/**
+ * Whether a text is one expression in braces and nothing else (`{false}`, `{ {a: 1} }`), and not
+ * several (`{a}{b}`) or an expression with text around it (`page/{p}`, `{a} text`). Svelte reads an
+ * attribute value in quotes that is one expression as the expression
+ * (`disabled="{false}"` is `disabled={false}`).
+ *
+ * The check is of the braces: the first `{` is closed by the last `}`, so no `}` closes it before
+ * the end. Strings and template literals are read as such, so a brace in them does not count. The
+ * code in the braces is not checked to be valid JavaScript (it may be TypeScript).
+ *
+ * The catch below does not use `isFatalError`, as for `parseLiteralExpression`: espree reports the
+ * author's code by a `SyntaxError`, which here means that the text is not one expression.
+ *
+ * @param raw - The text of an attribute value
+ * @returns `true` if the whole text is one expression in braces
+ */
+export function isBracedExpression(raw) {
+    if (raw.length < 2 || !raw.startsWith('{') || !raw.endsWith('}')) {
+        return false;
+    }
+    const inner = raw.slice(1, -1);
+    if (inner.trim() === '') {
+        return false;
+    }
+    let tokens;
+    try {
+        tokens = scriptParser(inner);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return false;
+        }
+        throw error;
+    }
+    let depth = 0;
+    for (const token of tokens) {
+        if (token.type !== 'Punctuator') {
+            continue;
+        }
+        if (token.value === '{') {
+            depth++;
+        }
+        else if (token.value === '}') {
+            depth--;
+            if (depth < 0) {
+                return false;
+            }
+        }
+    }
+    return depth === 0;
+}

package/lib/parse-literal-expression.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A JavaScript expression that is nothing but a literal, as {@link parseLiteralExpression} reads it.
+ */
+export type LiteralExpression = {
+    readonly type: 'string';
+    readonly value: string;
+    readonly key: string;
+} | {
+    readonly type: 'number';
+    readonly value: number;
+    readonly key: string;
+} | {
+    readonly type: 'boolean';
+    readonly value: boolean;
+    readonly key: 'true' | 'false';
+} | {
+    readonly type: 'null';
+    readonly value: null;
+    readonly key: 'null';
+} | {
+    readonly type: 'undefined';
+    readonly value: undefined;
+    readonly key: 'undefined';
+};
+/**
+ * Reads a JavaScript expression and tells whether it is nothing but a literal: a string, a template
+ * literal without a substitution, a number, `true`, `false`, `null` or `undefined`, with a leading
+ * minus sign for a number, any number of balanced parentheses, and a TypeScript `as` / `satisfies`
+ * assertion after it. An identifier, a call, an object, an array, a template literal with a
+ * substitution, a regular expression, an operator, or `NaN` is not.
+ *
+ * The result carries the value that the code evaluates to, and `key`, the normal form of the literal:
+ * two literals of one value and one type have the same key however they are written (`'x'`, `"x"`
+ * and `` `x` ``; `0x0`, `-0` and `0`), and literals that differ in value or in type do not
+ * (`true` and `"true"`, `0` and `"0"` and `false`). A string's key is its JSON, a number's key is
+ * `String(value)`, and the rest are their keyword. The keys are those of `literalValues` of a spec.
+ *
+ * The code is expected to be an expression that a parser has already read, but a template language
+ * hands over whatever its author wrote (a Vue `:x="a b"`), so a code that is not JavaScript is
+ * `null` as well.
+ *
+ * JavaScript is parsed once and its tree says whether it is a literal. What only TypeScript has (`as` and
+ * `satisfies` after the literal) is not JavaScript, so a code that does not parse is read by its tokens
+ * ({@link parseLiteralByTokens}), which give the same answer for the code that does parse.
+ *
+ * The catches in this file do not use `isFatalError`: espree reports the code that it is given, which is
+ * the author's own, by a `SyntaxError`, and that is the answer "not a literal" here. Anything else is
+ * thrown again.
+ *
+ * @param code - The text of the expression, without the braces or quotes around it
+ * @returns The literal, or `null` when the code is not a literal
+ */
+export declare function parseLiteralExpression(code: string): LiteralExpression | null;
+/**
+ * Reads the code by its tokens: any number of `(`, one literal, any number of `)`, and a TypeScript
+ * `as` / `satisfies` assertion after it, which a parser of JavaScript does not read.
+ *
+ * It is what {@link parseLiteralExpression} falls back on, and is exported to be compared with the reading
+ * of the tree.
+ *
+ * @param code - The text of the expression
+ * @returns The literal, or `null` when the code is not a literal
+ */
+export declare function parseLiteralByTokens(code: string): LiteralExpression | null;

package/lib/parse-literal-expression.js

@@ -0,0 +1,300 @@
+// @ts-ignore
+import { parse } from 'espree';
+import { scriptParser } from './script-parser.js';
+/**
+ * The characters a literal can start with: a quote, a digit, a dot (`.5`), a minus sign, an opening
+ * parenthesis, and the first letters of `true` / `false` / `null` / `undefined`. An expression that
+ * starts with anything else cannot be a literal, which spares the tokenizer for the many that are
+ * identifiers or calls.
+ */
+const LITERAL_START = /^\s*["'`\d.\-(tfnu]/;
+/**
+ * Reads a JavaScript expression and tells whether it is nothing but a literal: a string, a template
+ * literal without a substitution, a number, `true`, `false`, `null` or `undefined`, with a leading
+ * minus sign for a number, any number of balanced parentheses, and a TypeScript `as` / `satisfies`
+ * assertion after it. An identifier, a call, an object, an array, a template literal with a
+ * substitution, a regular expression, an operator, or `NaN` is not.
+ *
+ * The result carries the value that the code evaluates to, and `key`, the normal form of the literal:
+ * two literals of one value and one type have the same key however they are written (`'x'`, `"x"`
+ * and `` `x` ``; `0x0`, `-0` and `0`), and literals that differ in value or in type do not
+ * (`true` and `"true"`, `0` and `"0"` and `false`). A string's key is its JSON, a number's key is
+ * `String(value)`, and the rest are their keyword. The keys are those of `literalValues` of a spec.
+ *
+ * The code is expected to be an expression that a parser has already read, but a template language
+ * hands over whatever its author wrote (a Vue `:x="a b"`), so a code that is not JavaScript is
+ * `null` as well.
+ *
+ * JavaScript is parsed once and its tree says whether it is a literal. What only TypeScript has (`as` and
+ * `satisfies` after the literal) is not JavaScript, so a code that does not parse is read by its tokens
+ * ({@link parseLiteralByTokens}), which give the same answer for the code that does parse.
+ *
+ * The catches in this file do not use `isFatalError`: espree reports the code that it is given, which is
+ * the author's own, by a `SyntaxError`, and that is the answer "not a literal" here. Anything else is
+ * thrown again.
+ *
+ * @param code - The text of the expression, without the braces or quotes around it
+ * @returns The literal, or `null` when the code is not a literal
+ */
+export function parseLiteralExpression(code) {
+    if (!LITERAL_START.test(code)) {
+        return null;
+    }
+    const fromTree = parseLiteralByTree(code);
+    return fromTree === undefined ? parseLiteralByTokens(code) : fromTree;
+}
+/**
+ * Reads the code as a JavaScript expression, in parentheses so that an object literal or a function is an
+ * expression too, and a line comment at the end does not take the parenthesis.
+ *
+ * @returns The literal, `null` when the code is JavaScript and is not a literal, or `undefined` when it is
+ * not JavaScript
+ */
+function parseLiteralByTree(code) {
+    let program;
+    try {
+        program = parse(`(${code}\n)`, { ecmaVersion: 'latest' });
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+    const statement = program.body.length === 1 ? program.body[0] : null;
+    return statement?.type === 'ExpressionStatement' ? literalOfNode(statement.expression) : null;
+}
+function literalOfNode(node) {
+    switch (node.type) {
+        case 'Literal': {
+            return literalOfValue(node, false);
+        }
+        case 'UnaryExpression': {
+            return node.operator === '-' && node.argument.type === 'Literal'
+                ? literalOfValue(node.argument, true)
+                : null;
+        }
+        case 'TemplateLiteral': {
+            const cooked = node.expressions.length === 0 ? node.quasis[0]?.value.cooked : undefined;
+            return typeof cooked === 'string' ? stringLiteral(cooked) : null;
+        }
+        case 'Identifier': {
+            return node.name === 'undefined' ? { type: 'undefined', value: undefined, key: 'undefined' } : null;
+        }
+        default: {
+            return null;
+        }
+    }
+}
+function literalOfValue(node, negative) {
+    const { value } = node;
+    if (node.regex !== undefined) {
+        return null;
+    }
+    if (typeof value === 'number' || typeof value === 'bigint') {
+        return numberLiteral(value, negative);
+    }
+    if (negative) {
+        return null;
+    }
+    switch (typeof value) {
+        case 'string': {
+            return stringLiteral(value);
+        }
+        case 'boolean': {
+            return value
+                ? { type: 'boolean', value: true, key: 'true' }
+                : { type: 'boolean', value: false, key: 'false' };
+        }
+        default: {
+            return value === null ? { type: 'null', value: null, key: 'null' } : null;
+        }
+    }
+}
+/**
+ * Reads the code by its tokens: any number of `(`, one literal, any number of `)`, and a TypeScript
+ * `as` / `satisfies` assertion after it, which a parser of JavaScript does not read.
+ *
+ * It is what {@link parseLiteralExpression} falls back on, and is exported to be compared with the reading
+ * of the tree.
+ *
+ * @param code - The text of the expression
+ * @returns The literal, or `null` when the code is not a literal
+ */
+export function parseLiteralByTokens(code) {
+    let tokens;
+    try {
+        tokens = scriptParser(code);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return null;
+        }
+        throw error;
+    }
+    let index = 0;
+    let opened = 0;
+    while (tokens[index]?.value === '(' && tokens[index]?.type === 'Punctuator') {
+        opened++;
+        index++;
+    }
+    const negative = tokens[index]?.type === 'Punctuator' && tokens[index]?.value === '-';
+    if (negative) {
+        index++;
+    }
+    const token = tokens[index];
+    if (!token) {
+        return null;
+    }
+    index++;
+    const literal = readLiteral(token.type, token.value, negative);
+    if (!literal) {
+        return null;
+    }
+    let closed = 0;
+    while (tokens[index]?.value === ')' && tokens[index]?.type === 'Punctuator') {
+        closed++;
+        index++;
+    }
+    const rest = tokens[index];
+    if (rest) {
+        // Tokens after an `as` / `satisfies` are a type and not an expression, which has to end the code
+        const isAssertion = rest.type === 'Identifier' && (rest.value === 'as' || rest.value === 'satisfies');
+        return isAssertion && isType(tokens.slice(index + 1), opened - closed) ? literal : null;
+    }
+    return closed === opened ? literal : null;
+}
+/**
+ * Tokens that a type is made of: names, keywords, literal types, and the punctuation of unions, generics,
+ * arrays, objects and parentheses. An operator (`+`, `||`, `?`, `,`) makes it code that goes on after the
+ * assertion, which is not a literal. `:` and `;` are the punctuation of an object type, so they are only
+ * inside its braces: `"x" as A : b` is not a type.
+ */
+const TYPE_PUNCTUATORS = new Set(['|', '&', '<', '>', '>>', '[', ']', '.', '{', '}']);
+const OBJECT_TYPE_PUNCTUATORS = new Set([':', ';']);
+/**
+ * @param tokens - The tokens after `as` / `satisfies`
+ * @param depth - The number of parentheses that are still open
+ * @returns `true` if the tokens are a type that closes the parentheses that are open, and nothing else
+ */
+function isType(tokens, depth) {
+    if (tokens.length === 0) {
+        return false;
+    }
+    let open = depth;
+    let braces = 0;
+    for (const token of tokens) {
+        if (token.type !== 'Punctuator') {
+            continue;
+        }
+        if (token.value === '(') {
+            open++;
+        }
+        else if (token.value === ')') {
+            open--;
+            if (open < 0) {
+                return false;
+            }
+        }
+        else if (token.value === '{') {
+            braces++;
+        }
+        else if (token.value === '}') {
+            braces--;
+            if (braces < 0) {
+                return false;
+            }
+        }
+        else if (!TYPE_PUNCTUATORS.has(token.value) && !(braces > 0 && OBJECT_TYPE_PUNCTUATORS.has(token.value))) {
+            return false;
+        }
+    }
+    return open === 0 && braces === 0;
+}
+function readLiteral(type, value, negative) {
+    if (negative) {
+        if (type !== 'Numeric') {
+            return null;
+        }
+        return readNumber(value, true);
+    }
+    switch (type) {
+        case 'String': {
+            const literal = evaluate(value);
+            return typeof literal === 'string' ? stringLiteral(literal) : null;
+        }
+        case 'Template': {
+            // A template literal with a substitution is split into several tokens, and its first one does not end with a backquote
+            if (value.length < 2 || !value.startsWith('`') || !value.endsWith('`')) {
+                return null;
+            }
+            const cooked = evaluate(value);
+            return typeof cooked === 'string' ? stringLiteral(cooked) : null;
+        }
+        case 'Numeric': {
+            return readNumber(value, false);
+        }
+        case 'Boolean': {
+            return value === 'true'
+                ? { type: 'boolean', value: true, key: 'true' }
+                : { type: 'boolean', value: false, key: 'false' };
+        }
+        case 'Null': {
+            return { type: 'null', value: null, key: 'null' };
+        }
+        case 'Identifier': {
+            return value === 'undefined' ? { type: 'undefined', value: undefined, key: 'undefined' } : null;
+        }
+        default: {
+            return null;
+        }
+    }
+}
+function readNumber(source, negative) {
+    const evaluated = evaluate(source);
+    return typeof evaluated === 'number' || typeof evaluated === 'bigint' ? numberLiteral(evaluated, negative) : null;
+}
+function numberLiteral(evaluated, negative) {
+    if (typeof evaluated === 'bigint') {
+        // A BigInt keeps its digits: the number is only the approximation of it
+        const signed = negative ? -evaluated : evaluated;
+        return { type: 'number', value: Number(signed), key: signed.toString() };
+    }
+    const value = negative ? -evaluated : evaluated;
+    // `String(-0)` is `'0'`, which is what the key of `0` is
+    return { type: 'number', value, key: String(value) };
+}
+function stringLiteral(value) {
+    return { type: 'string', value, key: JSON.stringify(value) };
+}
+/**
+ * Evaluates the source of one literal token with the parser of the language, which resolves the
+ * escapes (`\n`, `\x41`, `A`) and the notations of a number (`0x10`, `1e3`, `1_000`).
+ *
+ * The catch does not use `isFatalError`, for the reason that is given at {@link parseLiteralExpression}:
+ * the `SyntaxError` of espree is the answer "not a literal".
+ *
+ * @returns The value of the literal, or `undefined` when the source is not a single literal whose
+ * value the parser could tell (a template literal with an invalid escape has no cooked value)
+ */
+function evaluate(source) {
+    let program;
+    try {
+        program = parse(`(${source})`, { ecmaVersion: 'latest' });
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+    const statement = program.body[0];
+    const expression = statement?.type === 'ExpressionStatement' ? statement.expression : null;
+    if (expression?.type === 'Literal') {
+        return expression.value;
+    }
+    if (expression?.type === 'TemplateLiteral' && expression.expressions.length === 0) {
+        return expression.quasis[0]?.value.cooked ?? undefined;
+    }
+    return undefined;
+}

package/lib/parser.d.ts

@@ -1,5 +1,5 @@
 import type { Token, ChildToken, QuoteSet, ParseOptions, ParserOptions, Tokenized, ValueType } from './types.js';
-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 type { AttrNameRoute, EndTagType, ExpressionLanguage, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTBlockBehavior, MLASTParseError, LiteralValueDeclaration } from '@markuplint/ml-ast';
 import { AttrState } from './enums.js';
 import { ParserError } from './parser-error.js';
 /**
@@ -20,12 +20,25 @@ import { ParserError } from './parser-error.js';
  * - **Direct `Parser` subclass** only when the document structure itself
  *   diverges from HTML (JSX, Vue SFC, Svelte, Pug, Astro).
  *
+ * A framework whose attribute values are code (`{…}`, `:x="…"`) says so for `@markuplint/ml-core`, which
+ * reads a value that is nothing but a literal and renders it as the framework does (`aria-busy={true}`
+ * is `aria-busy="true"`; `disabled={false}` is no attribute). The parser only records what is written
+ * (`isDynamicValue`) and declares the language of that code (`attrExpressionLanguage`); a template language
+ * that an HTML parser reads says it in a `DirectivePattern` of its spec (`expressionLanguage`). How the
+ * framework renders is `literalValues` of its spec, or of its parser when it has no spec package.
+ *
  * Direct subclasses should delegate tokenization to the framework's
  * established parser library rather than hand-rolling one, and those
  * libraries are chosen to span multiple major framework versions (e.g.
  * `vue-eslint-parser` covers both Vue 2 and Vue 3 template syntax) so the
  * parsers keep working across version ranges without frequent updates.
  *
+ * A direct subclass also decides what happens to a leading BOM (`leadingBom` of
+ * {@link ParserOptions}): `'mask'` when its tokenizer takes the BOM for content,
+ * `'strip'` when the library strips it itself or reads a leading space as
+ * meaning something, unset when it already ignores a BOM without moving any
+ * position. Check it with a BOM-prefixed source, positions included.
+ *
  * @template Node - The language-specific AST node type produced by the tokenizer
  * @template State - An optional parser state type that persists across tokenization
  */
@@ -55,6 +68,20 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * In the above, the `aria-hidden` is `true`.
      */
     get booleanish(): boolean;
+    /**
+     * The language of the code that an attribute value is written in when it is written as code.
+     * See {@link MLParser.attrExpressionLanguage}.
+     */
+    get attrExpressionLanguage(): ExpressionLanguage | undefined;
+    /**
+     * How the framework renders a literal in an attribute value, where it differs from the default
+     * of `@markuplint/ml-core`. See {@link MLParser.literalValues}.
+     */
+    get literalValues(): LiteralValueDeclaration | undefined;
+    /**
+     * What the `slot` element is in the language of the parser. See {@link MLParser.slotElement}.
+     */
+    get slotElement(): 'html' | 'framework';
     /**
      * The end tag omittable type.
      *
@@ -112,6 +139,10 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * two hooks must stay symmetric or position reporting for embedded code
      * fragments (e.g., a `<template>` block inside a `.vue` file) breaks.
      *
+     * A leading BOM is handled after this hook (`leadingBom` of {@link ParserOptions}),
+     * and only if the returned code still starts with it: an override that moves or
+     * drops it turns that handling off.
+     *
      * @param rawCode - The raw source code about to be parsed
      * @param options - Parse options that may specify offset positioning
      * @returns The preprocessed source code to be used for tokenization
@@ -122,9 +153,23 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * traversal, flattening, ignore-block restoration, and post-processing.
      * Returns the complete markuplint AST document.
      *
+     * A leading U+FEFF (BOM) is not part of the document: the HTML Standard skips it
+     * before tokenization, so a parser that handed it on would see text before the
+     * doctype (parse5 then opens `<html><head><body>` implicitly) and a Svelte
+     * template would be counted from the character after it. A parser that sets
+     * `leadingBom` (see {@link ParserOptions}) has it replaced with one space
+     * (`'mask'`), or taken away while the positions are moved one character later
+     * afterwards (`'strip'`), so that every offset still points into the source that
+     * `fix` edits; the returned `raw` keeps it. Code that starts at an offset (an
+     * embedded block) does not start a document, and its U+FEFF is a character like
+     * any other. The BOM is handled after {@link Parser.beforeParse}, and only if that
+     * hook left it first.
+     *
      * @param rawCode - The raw source code to parse
      * @param options - Parse options controlling offsets, depth, front matter, and authored element names
      * @returns The parsed AST document containing the node list and fragment flag
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#the-input-byte-stream
+     * > A leading Byte Order Mark (BOM) causes the character encoding argument to be ignored and will itself be skipped.
      */
     parse(rawCode: string, options?: ParseOptions): MLASTDocument;
     /**
@@ -333,7 +378,7 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * Re-parses a text token to discover embedded HTML/XML tags within it,
      * splitting the content into a sequence of tag and text AST nodes.
      * Handles self-closing detection, depth tracking, void element recognition,
-     * and the raw-text element body short-circuit (HTML LS §13.2.5.1).
+     * and the raw-text element body short-circuit (HTML LS §13.1.2.6).
      *
      * Raw-text element handling only covers the elements listed in
      * `rawTextElements` (default `['style', 'script']`). HTML LS *escapable* raw

package/lib/parser.js

@@ -10,9 +10,20 @@ import { getEndCol, getEndLine, getOffsetsFromCode, getPosition } from './get-lo
 import { ignoreBlock, restoreNode } from './ignore-block.js';
 import { ignoreFrontMatter } from './ignore-front-matter.js';
 import { ParserError } from './parser-error.js';
+import { shiftPositions } from './shift-leading-bom.js';
 import { sortNodes } from './sort-nodes.js';
 import { getNamespace } from './get-namespace.js';
 const timer = new PerformanceTimer();
+/** U+FEFF as the first character of a source: a byte order mark, not content. */
+const BOM = '\uFEFF';
+/**
+ * Whether the code of a parse starts the source: no offset places it inside a
+ * larger one (an embedded block). `offsetLine` and `offsetColumn` are 1-based, so
+ * 1 is no offset.
+ */
+function startsAtDocumentHead(options) {
+    return (options?.offsetOffset ?? 0) <= 0 && (options?.offsetLine ?? 1) <= 1 && (options?.offsetColumn ?? 1) <= 1;
+}
 /**
  * Abstract base class for all markuplint parsers. Provides the core parsing pipeline
  * including tokenization, tree traversal, node flattening, and error handling.
@@ -31,17 +42,33 @@ const timer = new PerformanceTimer();
  * - **Direct `Parser` subclass** only when the document structure itself
  *   diverges from HTML (JSX, Vue SFC, Svelte, Pug, Astro).
  *
+ * A framework whose attribute values are code (`{…}`, `:x="…"`) says so for `@markuplint/ml-core`, which
+ * reads a value that is nothing but a literal and renders it as the framework does (`aria-busy={true}`
+ * is `aria-busy="true"`; `disabled={false}` is no attribute). The parser only records what is written
+ * (`isDynamicValue`) and declares the language of that code (`attrExpressionLanguage`); a template language
+ * that an HTML parser reads says it in a `DirectivePattern` of its spec (`expressionLanguage`). How the
+ * framework renders is `literalValues` of its spec, or of its parser when it has no spec package.
+ *
  * Direct subclasses should delegate tokenization to the framework's
  * established parser library rather than hand-rolling one, and those
  * libraries are chosen to span multiple major framework versions (e.g.
  * `vue-eslint-parser` covers both Vue 2 and Vue 3 template syntax) so the
  * parsers keep working across version ranges without frequent updates.
  *
+ * A direct subclass also decides what happens to a leading BOM (`leadingBom` of
+ * {@link ParserOptions}): `'mask'` when its tokenizer takes the BOM for content,
+ * `'strip'` when the library strips it itself or reads a leading space as
+ * meaning something, unset when it already ignores a BOM without moving any
+ * position. Check it with a BOM-prefixed source, positions included.
+ *
  * @template Node - The language-specific AST node type produced by the tokenizer
  * @template State - An optional parser state type that persists across tokenization
  */
 export class Parser {
     #booleanish = false;
+    #attrExpressionLanguage;
+    #literalValues;
+    #slotElement = 'html';
     #defaultState;
     #endTagType = 'omittable';
     #ignoreTags = [];
@@ -53,6 +80,7 @@ export class Parser {
     #selfCloseType = 'html';
     #spaceChars = defaultSpaces;
     #rawTextElements = ['style', 'script'];
+    #leadingBom;
     /**
      * Buffer for parse errors collected from **embedded** parse() calls
      * (e.g., Markdown's inline HTML blocks, Pug's raw HTML lines — these
@@ -86,6 +114,9 @@ export class Parser {
      */
     constructor(options, defaultState) {
         this.#booleanish = options?.booleanish ?? this.#booleanish;
+        this.#attrExpressionLanguage = options?.attrExpressionLanguage ?? this.#attrExpressionLanguage;
+        this.#literalValues = options?.literalValues ?? this.#literalValues;
+        this.#slotElement = options?.slotElement ?? this.#slotElement;
         this.#endTagType = options?.endTagType ?? this.#endTagType;
         this.#ignoreTags = options?.ignoreTags ?? this.#ignoreTags;
         this.#maskChar = options?.maskChar ?? this.#maskChar;
@@ -96,6 +127,7 @@ export class Parser {
         this.#selfCloseType = options?.selfCloseType ?? this.#selfCloseType;
         this.#spaceChars = options?.spaceChars ?? this.#spaceChars;
         this.#rawTextElements = options?.rawTextElements ?? this.#rawTextElements;
+        this.#leadingBom = options?.leadingBom ?? this.#leadingBom;
         this.#defaultState = defaultState ?? null;
         this.state = structuredClone(this.#defaultState);
     }
@@ -119,6 +151,26 @@ export class Parser {
     get booleanish() {
         return this.#booleanish;
     }
+    /**
+     * The language of the code that an attribute value is written in when it is written as code.
+     * See {@link MLParser.attrExpressionLanguage}.
+     */
+    get attrExpressionLanguage() {
+        return this.#attrExpressionLanguage;
+    }
+    /**
+     * How the framework renders a literal in an attribute value, where it differs from the default
+     * of `@markuplint/ml-core`. See {@link MLParser.literalValues}.
+     */
+    get literalValues() {
+        return this.#literalValues;
+    }
+    /**
+     * What the `slot` element is in the language of the parser. See {@link MLParser.slotElement}.
+     */
+    get slotElement() {
+        return this.#slotElement;
+    }
     /**
      * The end tag omittable type.
      *
@@ -193,6 +245,10 @@ export class Parser {
      * two hooks must stay symmetric or position reporting for embedded code
      * fragments (e.g., a `<template>` block inside a `.vue` file) breaks.
      *
+     * A leading BOM is handled after this hook (`leadingBom` of {@link ParserOptions}),
+     * and only if the returned code still starts with it: an override that moves or
+     * drops it turns that handling off.
+     *
      * @param rawCode - The raw source code about to be parsed
      * @param options - Parse options that may specify offset positioning
      * @returns The preprocessed source code to be used for tokenization
@@ -206,25 +262,46 @@ export class Parser {
      * traversal, flattening, ignore-block restoration, and post-processing.
      * Returns the complete markuplint AST document.
      *
+     * A leading U+FEFF (BOM) is not part of the document: the HTML Standard skips it
+     * before tokenization, so a parser that handed it on would see text before the
+     * doctype (parse5 then opens `<html><head><body>` implicitly) and a Svelte
+     * template would be counted from the character after it. A parser that sets
+     * `leadingBom` (see {@link ParserOptions}) has it replaced with one space
+     * (`'mask'`), or taken away while the positions are moved one character later
+     * afterwards (`'strip'`), so that every offset still points into the source that
+     * `fix` edits; the returned `raw` keeps it. Code that starts at an offset (an
+     * embedded block) does not start a document, and its U+FEFF is a character like
+     * any other. The BOM is handled after {@link Parser.beforeParse}, and only if that
+     * hook left it first.
+     *
      * @param rawCode - The raw source code to parse
      * @param options - Parse options controlling offsets, depth, front matter, and authored element names
      * @returns The parsed AST document containing the node list and fragment flag
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#the-input-byte-stream
+     * > A leading Byte Order Mark (BOM) causes the character encoding argument to be ignored and will itself be skipped.
      */
     parse(rawCode, options) {
+        let strippedBom = false;
         try {
             // Initialize raw code
             this.#setRawCode(rawCode, rawCode);
             timer.push('beforeParse');
             const beforeParsedCode = this.beforeParse(this.rawCode, options);
             // Override raw code
-            this.#setRawCode(beforeParsedCode);
+            const bom = this.#leadingBom && startsAtDocumentHead(options) && beforeParsedCode.startsWith(BOM)
+                ? this.#leadingBom
+                : null;
+            const masked = bom === 'mask';
+            strippedBom = bom === 'strip';
+            this.#setRawCode(bom ? (masked ? ' ' : '') + beforeParsedCode.slice(BOM.length) : beforeParsedCode);
             this.#authoredElementName = options?.authoredElementName;
             let frontMatter = null;
             if (options?.ignoreFrontMatter) {
                 timer.push('ignoreFrontMatter');
-                const fm = ignoreFrontMatter(this.rawCode);
-                this.#setRawCode(fm.code);
-                frontMatter = fm.frontMatter;
+                // The masked BOM is part of the front matter's raw, not of what it is looked for in
+                const fm = ignoreFrontMatter(masked ? this.rawCode.slice(BOM.length) : this.rawCode);
+                this.#setRawCode(masked ? ' ' + fm.code : fm.code);
+                frontMatter = fm.frontMatter == null || !masked ? fm.frontMatter : BOM + fm.frontMatter;
             }
             timer.push('ignoreBlock');
             const blocks = ignoreBlock(this.rawCode, this.#ignoreTags, this.#maskChar);
@@ -288,6 +365,10 @@ export class Parser {
             const embeddedErrors = this.embeddedParseErrors;
             const mergedParseErrors = parseErrors || embeddedErrors.length > 0 ? [...(parseErrors ?? []), ...embeddedErrors] : undefined;
             this.#reset();
+            if (strippedBom) {
+                // Everything above counted from the character after the BOM
+                shiftPositions([nodeList, mergedParseErrors], BOM.length);
+            }
             return {
                 raw: rawCode,
                 nodeList,
@@ -296,7 +377,17 @@ export class Parser {
             };
         }
         catch (error) {
-            throw this.parseError(error);
+            const parserError = this.parseError(error);
+            if (strippedBom) {
+                // Only the fields are put back; the message that the library wrote is left as it is.
+                // A column of `0` is a position that is not known.
+                Object.assign(parserError, {
+                    ...(parserError.line === 1 && parserError.col > 0 ? { col: parserError.col + BOM.length } : {}),
+                    // The source an error quotes by default is the one without the BOM
+                    ...(parserError.raw === this.rawCode ? { raw: rawCode } : {}),
+                });
+            }
+            throw parserError;
         }
     }
     /**
@@ -744,7 +835,7 @@ export class Parser {
      * Re-parses a text token to discover embedded HTML/XML tags within it,
      * splitting the content into a sequence of tag and text AST nodes.
      * Handles self-closing detection, depth tracking, void element recognition,
-     * and the raw-text element body short-circuit (HTML LS §13.2.5.1).
+     * and the raw-text element body short-circuit (HTML LS §13.1.2.6).
      *
      * Raw-text element handling only covers the elements listed in
      * `rawTextElements` (default `['style', 'script']`). HTML LS *escapable* raw
@@ -846,10 +937,10 @@ export class Parser {
                 nodes.push(tag);
             }
             /**
-             * Raw-text element body short-circuit (HTML Living Standard §13.2.5.1
-             * — "Restrictions on the contents of raw text and escapable raw text
-             * elements". The spec section anchor is `cdata-rcdata-restrictions`,
-             * where RCDATA stands for "Raw text + Character REF data" — the broader
+             * Raw-text element body short-circuit (HTML Living Standard §13.1.2.6,
+             * Restrictions on the contents of raw text and escapable raw text
+             * elements. The spec section anchor is `cdata-rcdata-restrictions`,
+             * where RCDATA stands for 'Raw text + Character REF data' — the broader
              * class that covers escapable raw text such as `<title>` / `<textarea>`).
              *
              * Per spec, the contents of `<script>` / `<style>` (and any caller-supplied
@@ -1221,7 +1312,7 @@ export class Parser {
     }
     /**
      * The pattern matches `</tagName` followed by a tab/LF/FF/CR/space/`>`/`/`
-     * (HTML LS §13.2.5.1) ASCII-case-insensitively. Caching avoids recompiling the
+     * (HTML LS §13.1.2.6) ASCII-case-insensitively. Caching avoids recompiling the
      * `RegExp` for every `<script>` / `<style>` start tag in large documents.
      */
     #getRawTextCloseTagPattern(tagName) {

package/lib/shift-leading-bom.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Moves every position found in `value` one character later, in place: the
+ * positions a tokenizer reports for a source whose leading BOM it did not see.
+ *
+ * A parser whose library strips the BOM itself (`pug-lexer`, `remark`) counts
+ * from the character after it. Parsing the source without the BOM keeps `raw`
+ * and the slices consistent, and this puts the positions back where the source
+ * that `fix` edits has them. The BOM itself belongs to no node, as the HTML
+ * Standard skips it.
+ *
+ * A token (`offset`, `line`, `col`) and a parse error (`startOffset` … `endCol`)
+ * are recognised by their keys, whatever plain object carries them, so it is only
+ * safe on what the parser itself produced (the node list and the parse errors); an
+ * instance of a class is not entered. The
+ * column moves only for a position on the first line, the one the BOM is on. A
+ * token that several nodes refer to is moved once.
+ *
+ * @param value - A node list, a node, a token or a list of parse errors
+ * @param length - How many characters later the positions move
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#the-input-byte-stream
+ * > A leading Byte Order Mark (BOM) causes the character encoding argument to be ignored and will itself be skipped.
+ */
+export declare function shiftPositions(value: unknown, length?: number): void;

package/lib/shift-leading-bom.js

@@ -0,0 +1,59 @@
+/**
+ * Moves every position found in `value` one character later, in place: the
+ * positions a tokenizer reports for a source whose leading BOM it did not see.
+ *
+ * A parser whose library strips the BOM itself (`pug-lexer`, `remark`) counts
+ * from the character after it. Parsing the source without the BOM keeps `raw`
+ * and the slices consistent, and this puts the positions back where the source
+ * that `fix` edits has them. The BOM itself belongs to no node, as the HTML
+ * Standard skips it.
+ *
+ * A token (`offset`, `line`, `col`) and a parse error (`startOffset` … `endCol`)
+ * are recognised by their keys, whatever plain object carries them, so it is only
+ * safe on what the parser itself produced (the node list and the parse errors); an
+ * instance of a class is not entered. The
+ * column moves only for a position on the first line, the one the BOM is on. A
+ * token that several nodes refer to is moved once.
+ *
+ * @param value - A node list, a node, a token or a list of parse errors
+ * @param length - How many characters later the positions move
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#the-input-byte-stream
+ * > A leading Byte Order Mark (BOM) causes the character encoding argument to be ignored and will itself be skipped.
+ */
+export function shiftPositions(value, length = 1) {
+    walk(value, length, new WeakSet());
+}
+function walk(value, length, seen) {
+    if (typeof value !== 'object' || value === null || seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            walk(item, length, seen);
+        }
+        return;
+    }
+    // A node and a token are plain objects; an instance of a class is state that something else holds
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return;
+    }
+    const record = value;
+    shift(record, 'offset', 'line', 'col', length);
+    shift(record, 'startOffset', 'startLine', 'startCol', length);
+    shift(record, 'endOffset', 'endLine', 'endCol', length);
+    for (const child of Object.values(record)) {
+        walk(child, length, seen);
+    }
+}
+function shift(record, offsetKey, lineKey, colKey, length) {
+    const { [offsetKey]: offset, [lineKey]: line, [colKey]: col } = record;
+    if (typeof offset !== 'number' || typeof line !== 'number' || typeof col !== 'number') {
+        return;
+    }
+    record[offsetKey] = offset + length;
+    if (line === 1) {
+        record[colKey] = col + length;
+    }
+}

package/lib/types.d.ts

@@ -1,10 +1,13 @@
-import type { AttrNameRoute, EndTagType, MLASTParentNode, MLASTParseError, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
+import type { AttrNameRoute, EndTagType, ExpressionLanguage, LiteralValueDeclaration, 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.
  */
 export type ParserOptions = {
     readonly booleanish?: boolean;
+    readonly attrExpressionLanguage?: ExpressionLanguage;
+    readonly literalValues?: LiteralValueDeclaration;
+    readonly slotElement?: 'html' | 'framework';
     readonly endTagType?: EndTagType;
     readonly ignoreTags?: readonly IgnoreTag[];
     readonly maskChar?: string;
@@ -15,6 +18,22 @@ export type ParserOptions = {
     readonly selfCloseType?: SelfCloseType;
     readonly spaceChars?: readonly string[];
     readonly rawTextElements?: readonly string[];
+    /**
+     * What {@link Parser.parse} does with a leading U+FEFF (BOM) before tokenization.
+     * The HTML Standard skips it, so it is not content.
+     *
+     * - `'mask'`: it becomes one space. For a tokenizer that takes the BOM for text
+     *   (parse5) or counts from the character after it (`svelte/compiler`) and that
+     *   does not read a leading space as meaning anything.
+     * - `'strip'`: the tokenizer is given the source without it, and the positions
+     *   are moved one character later afterwards. For a tokenizer that strips the
+     *   BOM itself (`pug-lexer`, `remark`) or reads a leading space as meaning
+     *   something (Pug's indentation, a Markdown front matter), where `'mask'`
+     *   would change the tree.
+     *
+     * Leave it unset when the tokenizer already handles a BOM correctly.
+     */
+    readonly leadingBom?: 'mask' | 'strip';
 };
 /**
  * Options passed to a single parse invocation, extending the base config parser options

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/parser-utils",
-	"version": "5.4.0",
+	"version": "5.6.0",
 	"description": "Utility module for markuplint parser plugin",
 	"repository": {
 		"type": "git",
@@ -26,25 +26,22 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"typedoc": {
-		"entryPoint": "./src/index.ts"
-	},
 	"scripts": {
 		"build": "tsc --project tsconfig.build.json",
 		"dev": "tsc --watch --project tsconfig.build.json",
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-spec": "5.4.0",
-		"@markuplint/shared": "5.4.0",
-		"@markuplint/types": "5.4.0",
+		"@markuplint/ml-ast": "5.6.0",
+		"@markuplint/ml-spec": "5.6.0",
+		"@markuplint/shared": "5.6.0",
+		"@markuplint/types": "5.6.0",
 		"debug": "^4.4.3",
 		"espree": "^11.2.0",
 		"type-fest": "^5.10.0"
 	},
 	"devDependencies": {
-		"@typescript-eslint/typescript-estree": "8.71.2"
+		"@typescript-eslint/typescript-estree": "8.72.1"
 	},
-	"gitHead": "ab56aa8e12b67fbf793ddf1267aaba9fda90269d"
+	"gitHead": "eade3d7202682e567f3c1b6985478f1d4b5c5481"
 }