@markuplint/ml-core 4.13.2 → 5.0.0-alpha.0

package/docs/maintenance.ja.md

@@ -0,0 +1,210 @@
+# メンテナンスガイド
+
+## コマンド
+
+```bash
+# ビルド
+yarn build --scope @markuplint/ml-core
+
+# ウォッチモード
+yarn dev --scope @markuplint/ml-core
+
+# ビルド出力のクリーン
+yarn clean --scope @markuplint/ml-core
+
+# テスト（リポジトリルートから）
+yarn test --scope @markuplint/ml-core
+```
+
+## テスト
+
+### テストファイル
+
+| ファイル            | 用途                                                                               |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `src/test/index.ts` | テストユーティリティエクスポート（`createTestDocument`, `createTestElement` など） |
+
+### テストユーティリティの使用
+
+パッケージは `@markuplint/rules` や他のコンシューマーで一般的に使用されるテストヘルパーを提供します：
+
+```typescript
+import { createTestDocument, createTestElement, dummySchemas } from '@markuplint/ml-core';
+
+// HTML をテスト用 MLDocument にパース
+const doc = createTestDocument('<div class="foo"><p>Hello</p></div>');
+
+// ノードリストにアクセス
+for (const node of doc.nodeList) {
+  console.log(node.nodeName);
+}
+
+// 最初の要素を直接取得
+const el = createTestElement('<button type="submit">Click</button>');
+console.log(el.localName); // 'button'
+console.log(el.getAttribute('type')); // 'submit'
+```
+
+### カスタム設定でのテスト
+
+```typescript
+const doc = createTestDocument('<div></div>', {
+  config: {
+    rules: {
+      'my-rule': true,
+    },
+    nodeRules: [{ selector: 'div', rules: { 'my-rule': 'custom-value' } }],
+  },
+});
+```
+
+### カスタムパーサーでのテスト
+
+```typescript
+import { parser as vueParser } from '@markuplint/vue-parser';
+
+const doc = createTestDocument('<template><div></div></template>', {
+  parser: vueParser,
+});
+```
+
+## レシピ
+
+### 1. MLDOM ノードクラスへのプロパティ追加
+
+1. `src/ml-dom/node/` 内の対象クラスを特定（例：`MLElement` の場合 `element.ts`）
+2. ゲッターまたは readonly フィールドとしてプロパティを追加
+3. プロパティが AST データから派生する場合、`this.#astNode`（プライベート AST 参照）を使用
+4. プロパティが仕様データを必要とする場合、`this.ownerMLDocument.specs` 経由でアクセス
+5. 新しい型を導入する場合、`src/ml-dom/node/types.ts` の型定義を更新
+6. ビルドを検証：`yarn build --scope @markuplint/ml-core`
+
+**例：MLElement に `hasId` プロパティを追加**
+
+```typescript
+// src/ml-dom/node/element.ts 内
+get hasId(): boolean {
+  return this.hasAttribute('id');
+}
+```
+
+### 2. DOM API 更新への対応（TypeScript DOM 型定義の変更）
+
+TypeScript 組み込みの DOM 型定義が更新された場合（例：`Element` や `Node` に新しいプロパティが追加された場合）、それらのインターフェースを `implements` している MLDOM クラスで型エラーが発生します。これは意図的な設計です -- 気づかないうちにギャップが生じることを防ぎます。
+
+**プロセス：**
+
+1. `yarn build --scope @markuplint/ml-core` を実行し、型エラーを収集する
+2. 不足しているプロパティやメソッドごとに判断する：
+   - **実装する**: API がリントルールに有用な場合（例：`querySelector`、`getAttribute`）→ 実際のロジックを実装する
+   - **非サポートにする**: API が静的解析で意味を持たない場合（例：`requestFullscreen`、`animate`）→ `UnexpectedCallError` をスローするスタブを追加する
+3. 非サポートのスタブは既存のパターンに従う：
+
+```typescript
+/**
+ * **IT THROWS AN ERROR WHEN CALLING THIS.**
+ *
+ * @unsupported
+ * @implements DOM API: `Element`
+ */
+someNewMethod(): void {
+  throw new UnexpectedCallError('Not supported "someNewMethod" method');
+}
+```
+
+4. ビルドが通ることを確認する：`yarn build --scope @markuplint/ml-core`
+
+### 3. 新しいリンティングルールの作成
+
+ルールは `@markuplint/rules` に配置されますが、このパッケージの `createRule` API を使用します：
+
+```typescript
+import { createRule } from '@markuplint/ml-core';
+
+export default createRule({
+  defaultSeverity: 'error',
+  defaultValue: true,
+  async verify({ document, report, t }) {
+    await document.walkOn('Element', el => {
+      if (/* 違反条件 */) {
+        report({
+          scope: el,
+          message: t('違反メッセージ'),
+        });
+      }
+    });
+  },
+});
+```
+
+ルールを単体テストする場合、`src/ml-rule/create-test-rule.ts` の `createTestRule` を使用：
+
+```typescript
+import { createRule as createTestRule } from '@markuplint/ml-core/test';
+const rule = createTestRule({ name: 'my-rule', ...seed });
+```
+
+### 4. Pretender 設定の変更
+
+pretender は `MLDocument` コンストラクタ（`src/ml-dom/node/document.ts`）で処理されます：
+
+1. pretender 定義は `MLFabric.pretenders` から取得
+2. ドキュメント構築時に、各要素が pretender セレクタに対してチェックされる
+3. マッチする要素に `pretenderContext` が割り当てられる
+4. pretender の動作を変更するには、`MLDocument` の pretender 初期化ロジックを修正
+5. `createTestDocument` の `pretenders` オプションでテスト
+
+### 5. ルールマッピングロジックの変更（RuleMapper）
+
+`RuleMapper` クラス（`src/ml-dom/node/rule-mapper.ts`）はルールのノードへの適用方法を制御します：
+
+1. `apply()` はグローバルルール、nodeRules、childNodeRules を順に処理
+2. マッチするセレクタごとに、詳細度付きの `MappingLayer` を作成
+3. `set()` はレイヤーを対象ノードに割り当て、詳細度で競合を解決
+4. 新しいマッピングソースを追加するには、`apply()` に新しい反復ブロックを追加し、適切な `from` 値を定義
+
+### 6. walkOn に新しいノードタイプを追加
+
+`walkOn()` は `MLDocument`（`src/ml-dom/node/document.ts`）で定義されています：
+
+1. `type` パラメータのユニオンに新しいケースを追加：`'Element' | 'Text' | 'Comment' | 'Attr' | 'ElementCloseTag' | 'NewType'`
+2. `walkOn()` メソッドに `nodeList` からマッチするノードを選択するフィルタリングロジックを追加
+3. 必要に応じて `src/ml-dom/helper/walkers.ts` の `Walker` 型を更新
+4. `walkOn()` を使用する `@markuplint/rules` の下流コードを更新
+
+## 下流影響チェックリスト
+
+`@markuplint/ml-core` の変更は以下に影響を与える可能性があります：
+
+- [ ] **`@markuplint/rules`** — すべての組み込みルールが MLDOM クラスと `createRule` に依存
+  - ノードのプロパティ/メソッドの変更はそれらにアクセスするルールに影響
+  - `walkOn()` や `MLRuleContext` の変更はすべてのルールに影響
+  - `RuleMapper` の変更はルール設定の解決に影響
+- [ ] **`markuplint`** — CLI と API が `MLCore`, `ViolationCollector`, `convertRuleset` に依存
+  - `MLCore.verify()` のシグネチャや動作の変更は `MLEngine` に影響
+  - `MLFabric` 型の変更はエンジンの初期化に影響
+
+## トラブルシューティング
+
+### ルールが実行されない
+
+1. ルールがルールセット設定（`rules` フィールド）に登録されているか確認
+2. ルール名が完全に一致しているか確認（大文字小文字を区別）
+3. `RuleMapper` の出力を確認：`document.debugMap()` でルールマッピングを確認
+4. ルールの `walkOn` タイプが期待するノードタイプと一致しているか確認
+5. nodeRules/childNodeRules のセレクタがグローバルルールを無効にオーバーライドしていないか確認
+
+### Pretender が効かない
+
+1. pretender セレクタが対象要素にマッチするか確認：`element.matches(selector)` でテスト
+2. pretender 定義が `MLFabric.pretenders` を通じて渡されているか確認
+3. pretender の `as` 値が有効な HTML 要素名であることを確認
+4. ドキュメント構築後に `element.pretenderContext` が `null` でないことを確認
+
+### DOM ツリー構造が不正
+
+1. `document.debugMap()` の出力を期待される構造と比較
+2. パーサー出力を確認：同じソースをパーサーで直接パースして AST を検査
+3. ゴースト要素（暗黙の HTML/head/body）が正しく処理されているか確認
+4. テンプレートエンジンの場合、`blockBehavior` 付きの `MLBlock` ノードが期待される子をラップしているか確認
+5. `document.nodeList` でフラットノードリストを検査し、親子関係を確認

package/docs/maintenance.md

@@ -0,0 +1,210 @@
+# Maintenance Guide
+
+## Commands
+
+```bash
+# Build
+yarn build --scope @markuplint/ml-core
+
+# Watch mode
+yarn dev --scope @markuplint/ml-core
+
+# Clean build output
+yarn clean --scope @markuplint/ml-core
+
+# Test (from repo root)
+yarn test --scope @markuplint/ml-core
+```
+
+## Testing
+
+### Test Files
+
+| File                | Purpose                                                                |
+| ------------------- | ---------------------------------------------------------------------- |
+| `src/test/index.ts` | Test utility exports (`createTestDocument`, `createTestElement`, etc.) |
+
+### Using Test Utilities
+
+The package provides test helpers commonly used by `@markuplint/rules` and other consumers:
+
+```typescript
+import { createTestDocument, createTestElement, dummySchemas } from '@markuplint/ml-core';
+
+// Parse HTML into an MLDocument for testing
+const doc = createTestDocument('<div class="foo"><p>Hello</p></div>');
+
+// Access the node list
+for (const node of doc.nodeList) {
+  console.log(node.nodeName);
+}
+
+// Get the first element directly
+const el = createTestElement('<button type="submit">Click</button>');
+console.log(el.localName); // 'button'
+console.log(el.getAttribute('type')); // 'submit'
+```
+
+### Test with Custom Config
+
+```typescript
+const doc = createTestDocument('<div></div>', {
+  config: {
+    rules: {
+      'my-rule': true,
+    },
+    nodeRules: [{ selector: 'div', rules: { 'my-rule': 'custom-value' } }],
+  },
+});
+```
+
+### Test with Custom Parser
+
+```typescript
+import { parser as vueParser } from '@markuplint/vue-parser';
+
+const doc = createTestDocument('<template><div></div></template>', {
+  parser: vueParser,
+});
+```
+
+## Recipes
+
+### 1. Add a Property to an MLDOM Node Class
+
+1. Identify the target class in `src/ml-dom/node/` (e.g., `element.ts` for `MLElement`)
+2. Add the property as a getter or readonly field
+3. If the property derives from AST data, use `this.#astNode` (private AST reference)
+4. If the property needs spec data, access it via `this.ownerMLDocument.specs`
+5. Update the type definitions in `src/ml-dom/node/types.ts` if introducing a new type
+6. Verify the build: `yarn build --scope @markuplint/ml-core`
+
+**Example: Adding a `hasId` property to MLElement**
+
+```typescript
+// In src/ml-dom/node/element.ts
+get hasId(): boolean {
+  return this.hasAttribute('id');
+}
+```
+
+### 2. Handle DOM API Updates (TypeScript DOM Type Changes)
+
+When the TypeScript built-in DOM type definitions are updated (e.g., a new property is added to `Element` or `Node`), MLDOM classes that `implements` those interfaces will produce type errors. This is intentional -- it ensures no gaps go unnoticed.
+
+**Process:**
+
+1. Run `yarn build --scope @markuplint/ml-core` and collect the type errors
+2. For each missing property or method, decide:
+   - **Implement**: If the API is useful for lint rules (e.g., `querySelector`, `getAttribute`) → implement the actual logic
+   - **Mark as unsupported**: If the API is not meaningful in static analysis (e.g., `requestFullscreen`, `animate`) → add a stub that throws `UnexpectedCallError`
+3. For unsupported stubs, follow the existing pattern:
+
+```typescript
+/**
+ * **IT THROWS AN ERROR WHEN CALLING THIS.**
+ *
+ * @unsupported
+ * @implements DOM API: `Element`
+ */
+someNewMethod(): void {
+  throw new UnexpectedCallError('Not supported "someNewMethod" method');
+}
+```
+
+4. Verify the build passes: `yarn build --scope @markuplint/ml-core`
+
+### 3. Create a New Linting Rule
+
+Rules live in `@markuplint/rules`, but use the `createRule` API from this package:
+
+```typescript
+import { createRule } from '@markuplint/ml-core';
+
+export default createRule({
+  defaultSeverity: 'error',
+  defaultValue: true,
+  async verify({ document, report, t }) {
+    await document.walkOn('Element', el => {
+      if (/* violation condition */) {
+        report({
+          scope: el,
+          message: t('Violation message'),
+        });
+      }
+    });
+  },
+});
+```
+
+For testing rules in isolation, use `createTestRule` from `src/ml-rule/create-test-rule.ts`:
+
+```typescript
+import { createRule as createTestRule } from '@markuplint/ml-core/test';
+const rule = createTestRule({ name: 'my-rule', ...seed });
+```
+
+### 4. Modify Pretender Configuration
+
+Pretenders are processed in `MLDocument` constructor (`src/ml-dom/node/document.ts`):
+
+1. Pretender definitions come from `MLFabric.pretenders`
+2. During document construction, each element is checked against pretender selectors
+3. Matching elements get a `pretenderContext` assigned
+4. To change pretender behavior, modify the pretender initialization logic in `MLDocument`
+5. Test with `createTestDocument` using the `pretenders` option
+
+### 5. Change Rule Mapping Logic (RuleMapper)
+
+The `RuleMapper` class (`src/ml-dom/node/rule-mapper.ts`) controls how rules are applied to nodes:
+
+1. `apply()` iterates through global rules, nodeRules, and childNodeRules
+2. For each matching selector, it creates a `MappingLayer` with specificity
+3. `set()` assigns the layer to the target node, resolving conflicts by specificity
+4. To add a new mapping source, add a new iteration block in `apply()` and define the appropriate `from` value
+
+### 6. Add a New Node Type to walkOn
+
+`walkOn()` is defined in `MLDocument` (`src/ml-dom/node/document.ts`):
+
+1. Add a new case to the `type` parameter union: `'Element' | 'Text' | 'Comment' | 'Attr' | 'ElementCloseTag' | 'NewType'`
+2. Add the filtering logic in the `walkOn()` method to select matching nodes from `nodeList`
+3. Update the `Walker` type in `src/ml-dom/helper/walkers.ts` if needed
+4. Update downstream code in `@markuplint/rules` that uses `walkOn()`
+
+## Downstream Impact Checklist
+
+Changes to `@markuplint/ml-core` can affect:
+
+- [ ] **`@markuplint/rules`** — All built-in rules depend on MLDOM classes and `createRule`
+  - Changes to node properties/methods affect rules that access them
+  - Changes to `walkOn()` or `MLRuleContext` affect all rules
+  - Changes to `RuleMapper` affect rule configuration resolution
+- [ ] **`markuplint`** — CLI and API depend on `MLCore`, `ViolationCollector`, `convertRuleset`
+  - Changes to `MLCore.verify()` signature or behavior affect `MLEngine`
+  - Changes to `MLFabric` type affect engine initialization
+
+## Troubleshooting
+
+### Rule is not being executed
+
+1. Check if the rule is registered in the ruleset config (`rules` field)
+2. Verify the rule name matches exactly (case-sensitive)
+3. Check `RuleMapper` output: use `document.debugMap()` to see the rule mapping
+4. Verify the rule's `walkOn` type matches the node type you expect
+5. Check if nodeRules/childNodeRules selectors are overriding the global rule to disable it
+
+### Pretender is not taking effect
+
+1. Verify the pretender selector matches the target element: use `element.matches(selector)` to test
+2. Check that pretender definitions are passed through `MLFabric.pretenders`
+3. Ensure the pretender `as` value is a valid HTML element name
+4. Check `element.pretenderContext` is not `null` after document construction
+
+### DOM tree structure is incorrect
+
+1. Compare `document.debugMap()` output with expected structure
+2. Check the parser output: parse the same source with the parser directly and inspect the AST
+3. Verify ghost elements (implicit HTML/head/body) are handled correctly
+4. For template engines, check that `MLBlock` nodes with `blockBehavior` wrap the expected children
+5. Use `document.nodeList` to inspect the flat node list and verify parent-child relationships

package/docs/ml-dom/attr.ja.md

@@ -0,0 +1,103 @@
+# MLAttr
+
+**ソース:** `src/ml-dom/node/attr.ts`
+
+属性ノードです。`MLNode` を継承し、DOM `Attr` インターフェースを実装します。各属性は細粒度の検査と修正のために個々のトークンに分解されます。
+
+## プロパティ
+
+| プロパティ     | 型               | 説明                                               |
+| -------------- | ---------------- | -------------------------------------------------- |
+| `name`         | `string`         | 修飾された属性名（`#potentialName` から解決）      |
+| `localName`    | `string`         | 属性名のローカル部分（名前空間プレフィックスなし） |
+| `namespaceURI` | `string \| null` | 属性の名前空間 URI                                 |
+| `value`        | `string`         | 属性値（`#potentialValue` から解決）               |
+| `nodeValue`    | `string`         | `value` と同じ                                     |
+| `textContent`  | `string`         | `value` と同じ                                     |
+| `specified`    | `true`           | 常に `true`（DOM `Attr` インターフェース要件）     |
+| `ownerElement` | `MLElement`      | この属性を所有する要素                             |
+
+## `#potentialName` / `#potentialValue`
+
+パーサーは、ソース構文が有効なセマンティクスと異なる属性に対して、解決済みの「potential」名と値を提供する場合があります。例えば、テンプレートエンジンが属性名や値を変換することがあります。
+
+- `astToken.potentialName` が存在する場合 → `name` として使用する。そうでなければ `nameNode.raw` を使用する
+- `astToken.potentialValue` が存在する場合 → `value` として使用する。そうでなければ `valueNode.raw` を使用する
+
+### ディレクティブパターン解決
+
+パーサーが `astToken.potentialName` を設定していない場合、`MLAttr` コンストラクタは spec（例: `@markuplint/vue-spec`、`@markuplint/svelte-spec`）からの `directivePatterns` をチェックします。パターンが存在する場合、生の属性名とコンパイル済みパターンで `resolveDirective()` が呼び出されます。最初にマッチしたパターンが `potentialName`、`isDynamicValue`、`isDirective`、`isDuplicatable` を決定します。
+
+### IDL 属性名解決
+
+ディレクティブパターン解決の後、spec が `useIDLAttributeNames: true` を設定しており（例: `@markuplint/react-spec`、`@markuplint/svelte-spec`）、属性がディレクティブでない場合、コンストラクタは `@markuplint/parser-utils` の `searchIDLAttribute()` を呼び出して IDL プロパティ名を HTML コンテンツ属性名にマッピングします（例: `className` → `class`、`htmlFor` → `for`）。これはパーサーレベルではなくコアレベルの関心事です。
+
+## トークン分解
+
+各属性は個々の `MLToken` インスタンスに分解されます：
+
+```
+ ·class="container"
+ ^     ^^         ^
+ |     ||         └── endQuote (raw: '"')
+ |     |└── valueNode (raw: 'container')
+ |     └── startQuote (raw: '"')
+ |        equal (raw: '=')
+ └── spacesBeforeName (raw: ' ')
+    nameNode (raw: 'class')
+```
+
+| トークンプロパティ  | 型                | 説明                                          |
+| ------------------- | ----------------- | --------------------------------------------- |
+| `spacesBeforeName`  | `MLToken \| null` | 属性名の前の空白                              |
+| `nameNode`          | `MLToken \| null` | 属性名トークン（スプレッド属性の場合は null） |
+| `spacesBeforeEqual` | `MLToken \| null` | 名前と `=` の間の空白                         |
+| `equal`             | `MLToken \| null` | `=` 記号トークン                              |
+| `spacesAfterEqual`  | `MLToken \| null` | `=` と値の間の空白                            |
+| `startQuote`        | `MLToken \| null` | 開始引用符トークン                            |
+| `valueNode`         | `MLToken \| null` | 属性値トークン                                |
+| `endQuote`          | `MLToken \| null` | 終了引用符トークン                            |
+
+## スプレッド属性
+
+スプレッド属性（例：JSX の `{...props}`）の場合、`MLAttr` は最小限のプロパティで作成されます：
+
+| プロパティ                 | 値                           |
+| -------------------------- | ---------------------------- |
+| `localName`                | `'#spread'`                  |
+| `valueType`                | `'code'`                     |
+| `isDirective`              | `true`                       |
+| `isDynamicValue`           | `true`                       |
+| `isDuplicatable`           | `true`                       |
+| すべてのトークンプロパティ | `null`                       |
+| `fix()`                    | No-op（即座に return）       |
+| `value`                    | スプレッド式のソーステキスト |
+
+## `tokenList`（MLDomTokenList）
+
+スペース区切りの属性値（例：`class` 属性）に対する `MLDomTokenList` を返します：
+
+- `isDynamicValue` の場合 → `null` を返す（動的式はトークン化できない）
+- それ以外の場合 → `new MLDomTokenList(this.value, [this])`
+
+## `rule` ゲッター
+
+`ownerElement.rule` に委譲します -- 属性はそれを所有する要素からルール設定を継承します。
+
+## メタデータプロパティ
+
+| プロパティ       | 型                                            | 説明                                         |
+| ---------------- | --------------------------------------------- | -------------------------------------------- |
+| `isDynamicValue` | `true \| undefined`                           | 値に動的式が含まれているかどうか             |
+| `isDirective`    | `true \| undefined`                           | 属性がフレームワークのディレクティブかどうか |
+| `isDuplicatable` | `boolean`                                     | 属性が複数回出現可能かどうか                 |
+| `valueType`      | `'string' \| 'number' \| 'boolean' \| 'code'` | 値の型分類                                   |
+| `candidate`      | `string \| undefined`                         | パーサーが提案する修正候補値                 |
+
+## メソッド
+
+| メソッド            | シグネチャ                          | 説明                                                                                 |
+| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ |
+| `fix`               | `fix(raw: string): void`            | `valueNode` の修正済みコンテンツを更新する。スプレッド属性の場合は No-op             |
+| `toNormalizeString` | `toNormalizeString(): string`       | 余分な空白を除去した正規化された表現                                                 |
+| `toString`          | `toString(fixed?: boolean): string` | raw または fixed の文字列。`fixed=true` の場合、各トークンの修正済み値から再構築する |

package/docs/ml-dom/attr.md

@@ -0,0 +1,103 @@
+# MLAttr
+
+**Source:** `src/ml-dom/node/attr.ts`
+
+Attribute node. Extends `MLNode` and implements the DOM `Attr` interface. Each attribute is decomposed into individual tokens for fine-grained inspection and fixing.
+
+## Properties
+
+| Property       | Type             | Description                                               |
+| -------------- | ---------------- | --------------------------------------------------------- |
+| `name`         | `string`         | Qualified attribute name (resolved from `#potentialName`) |
+| `localName`    | `string`         | Local part of attribute name (without namespace prefix)   |
+| `namespaceURI` | `string \| null` | Attribute namespace URI                                   |
+| `value`        | `string`         | Attribute value (resolved from `#potentialValue`)         |
+| `nodeValue`    | `string`         | Same as `value`                                           |
+| `textContent`  | `string`         | Same as `value`                                           |
+| `specified`    | `true`           | Always `true` (DOM `Attr` interface requirement)          |
+| `ownerElement` | `MLElement`      | Element that owns this attribute                          |
+
+## `#potentialName` / `#potentialValue`
+
+The parser may provide resolved "potential" names and values for attributes where the source syntax differs from the effective semantics. For example, a template engine might transform attribute names or values.
+
+- If `astToken.potentialName` exists → use it as `name`; otherwise use `nameNode.raw`
+- If `astToken.potentialValue` exists → use it as `value`; otherwise use `valueNode.raw`
+
+### Directive Pattern Resolution
+
+When `astToken.potentialName` is not set by the parser, the `MLAttr` constructor checks for `directivePatterns` from the spec (e.g., `@markuplint/vue-spec`, `@markuplint/svelte-spec`). If patterns exist, `resolveDirective()` is called with the raw attribute name and the compiled patterns. The first matching pattern determines `potentialName`, `isDynamicValue`, `isDirective`, and `isDuplicatable`.
+
+### IDL Attribute Name Resolution
+
+After directive pattern resolution, if the spec sets `useIDLAttributeNames: true` (e.g., `@markuplint/react-spec`, `@markuplint/svelte-spec`) and the attribute is not a directive, the constructor calls `searchIDLAttribute()` from `@markuplint/parser-utils` to map IDL property names to HTML content attribute names (e.g., `className` -> `class`, `htmlFor` -> `for`). This is a core-level concern, not a parser-level one.
+
+## Token Decomposition
+
+Each attribute is decomposed into individual `MLToken` instances:
+
+```
+ ·class="container"
+ ^     ^^         ^
+ |     ||         └── endQuote (raw: '"')
+ |     |└── valueNode (raw: 'container')
+ |     └── startQuote (raw: '"')
+ |        equal (raw: '=')
+ └── spacesBeforeName (raw: ' ')
+    nameNode (raw: 'class')
+```
+
+| Token Property      | Type              | Description                                       |
+| ------------------- | ----------------- | ------------------------------------------------- |
+| `spacesBeforeName`  | `MLToken \| null` | Whitespace before the attribute name              |
+| `nameNode`          | `MLToken \| null` | Attribute name token (null for spread attributes) |
+| `spacesBeforeEqual` | `MLToken \| null` | Whitespace between name and `=`                   |
+| `equal`             | `MLToken \| null` | The `=` sign token                                |
+| `spacesAfterEqual`  | `MLToken \| null` | Whitespace between `=` and value                  |
+| `startQuote`        | `MLToken \| null` | Opening quote token                               |
+| `valueNode`         | `MLToken \| null` | Attribute value token                             |
+| `endQuote`          | `MLToken \| null` | Closing quote token                               |
+
+## Spread Attributes
+
+For spread attributes (e.g., `{...props}` in JSX), the `MLAttr` is created with minimal properties:
+
+| Property             | Value                                        |
+| -------------------- | -------------------------------------------- |
+| `localName`          | `'#spread'`                                  |
+| `valueType`          | `'code'`                                     |
+| `isDirective`        | `true`                                       |
+| `isDynamicValue`     | `true`                                       |
+| `isDuplicatable`     | `true`                                       |
+| All token properties | `null`                                       |
+| `fix()`              | No-op (returns immediately)                  |
+| `value`              | The raw source text of the spread expression |
+
+## `tokenList` (MLDomTokenList)
+
+Returns a `MLDomTokenList` for space-separated attribute values (e.g., `class` attribute):
+
+- If `isDynamicValue` → returns `null` (cannot tokenize a dynamic expression)
+- Otherwise → `new MLDomTokenList(this.value, [this])`
+
+## `rule` Getter
+
+Delegates to `ownerElement.rule` -- an attribute inherits its rule configuration from the element that owns it.
+
+## Metadata Properties
+
+| Property         | Type                                          | Description                                 |
+| ---------------- | --------------------------------------------- | ------------------------------------------- |
+| `isDynamicValue` | `true \| undefined`                           | Whether value contains a dynamic expression |
+| `isDirective`    | `true \| undefined`                           | Whether attribute is a framework directive  |
+| `isDuplicatable` | `boolean`                                     | Whether attribute may appear multiple times |
+| `valueType`      | `'string' \| 'number' \| 'boolean' \| 'code'` | Value type classification                   |
+| `candidate`      | `string \| undefined`                         | Fix candidate value suggested by the parser |
+
+## Methods
+
+| Method              | Signature                           | Description                                                                        |
+| ------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
+| `fix`               | `fix(raw: string): void`            | Updates the `valueNode` fixed content. No-op for spread attributes.                |
+| `toNormalizeString` | `toNormalizeString(): string`       | Normalized representation stripping extraneous whitespace                          |
+| `toString`          | `toString(fixed?: boolean): string` | Raw or fixed string. For `fixed=true`, reconstructs from each token's fixed value. |