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

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

@@ -0,0 +1,141 @@
+# MLDocument
+
+**ソース:** `src/ml-dom/node/document.ts`
+
+MLDOM ツリーのルートノードです。`MLParentNode` を継承し、DOM `Document` インターフェースを実装します。
+
+## コンストラクション
+
+コンストラクタは以下を受け取ります：
+
+1. `ast: MLASTDocument` -- パース済みの AST ドキュメント
+2. `ruleset: Ruleset` -- ルール設定
+3. `schemas: MLSchema` -- HTML/ARIA 仕様データ（タプル）
+4. `options?` -- オプション設定：
+   - `filename` -- ソースファイルパス
+   - `endTag` -- `'xml'` | `'omittable'` | `'never'`（デフォルト: `'omittable'`）
+   - `booleanish` -- 省略された boolean 風属性を `true` として扱う（デフォルト: `false`）
+   - `tagNameCaseSensitive` -- タグ名の大文字小文字を区別する比較（デフォルト: `false`）
+   - `pretenders` -- pretender 定義の配列
+
+コンストラクション手順：
+
+1. AST `nodeList` を反復して各非 endtag ノードに対して `createNode()` を呼び出し、フラットな `nodeList` を構築してから配列をフリーズする
+2. すべての要素ノードに対して `_pretending(pretenders)` で pretender コンテキストを初期化する
+3. `RuleMapper` を使って `_ruleMapping(ruleset)` でルール設定をノードに配布する
+
+## `_pretending(pretenders?)`
+
+`nodeList` 内のすべての要素ノードを反復し、各要素に対して `element.pretending(pretenders)` を呼び出します。詳細は [MLElement > Pretender システム](./element.ja.md#pretender-システム)を参照してください。
+
+## `_ruleMapping(ruleset)`
+
+`RuleMapper` を使って `Ruleset` からのルールを個々のノードに配布します。マッピングは3つのレイヤーで行われ、詳細度が増す順に適用されます：
+
+1. **グローバルルール**（`ruleset.rules`）：`#document` と `nodeList` 内のすべてのノードに詳細度 `[0, 0, 0]` で適用
+2. **ノードルール**（`ruleset.nodeRules`）：各 `nodeRule` に対して、`matchMLSelector()` でセレクタを要素にマッチさせる。マッチした場合、グローバルルールとマージしてセレクタの詳細度で適用
+3. **子ノードルール**（`ruleset.childNodeRules`）：各 `childNodeRule` に対して、親セレクタをマッチさせ、直接の子（または `inheritance: true` の場合はすべての子孫）にマージしたルールを適用
+
+`RuleMapper.set()` は CSS 詳細度の比較を使用します -- より高い詳細度のルールがより低い詳細度のルールを上書きします。`RuleMapper.apply()` は内部マップから解決されたルールを各ノードの `rules` レコードに転送します。
+
+ルール解決の完全な詳細は [rule-system.md](../rule-system.md) を参照してください。
+
+## 主要プロパティ
+
+| プロパティ             | 型                         | 説明                                                              |
+| ---------------------- | -------------------------- | ----------------------------------------------------------------- |
+| `nodeList`             | `ReadonlyArray<MLNode>`    | ドキュメント順の全ノードのフリーズされたフラットリスト            |
+| `specs`                | `MLMLSpec`                 | HTML/ARIA 仕様データ                                              |
+| `isFragment`           | `boolean`                  | ドキュメントがフラグメントかどうか（ルート要素が不要）            |
+| `currentRule`          | `Readonly<MLRule> \| null` | 現在評価中のルール、または `null`                                 |
+| `endTag`               | `EndTagType`               | 終了タグの処理モード: `'xml'` \| `'omittable'` \| `'never'`       |
+| `booleanish`           | `boolean`                  | boolean 風属性を boolean として扱うかどうか（デフォルト `false`） |
+| `tagNameCaseSensitive` | `boolean`                  | タグ名の大文字小文字区別（デフォルト `false`）                    |
+| `filename`             | `string \| undefined`      | ソースファイル名                                                  |
+| `doctype`              | `MLDocumentType \| null`   | DOCTYPE ノード（存在する場合）。`nodeList` をスキャンして検出     |
+
+## `walkOn(type, walker, skipWhenRuleIsDisabled?)`
+
+`nodeList` に対して `sequentialWalker` を使い、特定の型のノードを走査します。
+
+**パラメータ：**
+
+- `type` -- 走査するノード型（下表参照）
+- `walker` -- マッチしたノードを受け取るコールバック関数
+- `skipWhenRuleIsDisabled` -- 現在のルールが無効化されているノードをスキップする（デフォルト: `true`）
+
+| 型                  | 走査対象                                                            | walker パラメータ   |
+| ------------------- | ------------------------------------------------------------------- | ------------------- |
+| `'Element'`         | `nodeList` 内の `ELEMENT_NODE` ノード                               | `MLElement`         |
+| `'Text'`            | `nodeList` 内の `TEXT_NODE` ノード                                  | `MLText`            |
+| `'Comment'`         | `nodeList` 内の `COMMENT_NODE` ノード                               | `MLComment`         |
+| `'Attr'`            | `nodeList` 内の各 `ELEMENT_NODE` のすべての属性                     | `MLAttr`            |
+| `'ElementCloseTag'` | `nodeList` 内の各 `ELEMENT_NODE` の `closeTag`（`null` はスキップ） | `MLElementCloseTag` |
+
+`skipWhenRuleIsDisabled` パラメータは現在のルールに対する `node.rule.disabled` をチェックします。`true` の場合、そのノードに対して walker は呼び出されません。これがルールがノードごとの無効化ディレクティブを尊重する仕組みです。
+
+```typescript
+// すべての要素を走査（デフォルトで無効化されたノードはスキップ）
+await document.walkOn('Element', async element => {
+  console.log(element.localName);
+});
+
+// 無効化されたノードを含むすべての属性を走査
+await document.walkOn(
+  'Attr',
+  async attr => {
+    console.log(`${attr.name}="${attr.value}"`);
+  },
+  false,
+);
+```
+
+## `getAccessibilityProp(node, ariaVersion?)`
+
+ノードの ARIA アクセシビリティプロパティを計算します。
+
+**フロー：**
+
+1. `node` が要素でない場合 → `null` を返す
+2. 要素が `<slot>` の場合 → `{ unknown: true }` を返す（コンテンツは実行時に決定される）
+3. `isExposed()` を呼び出して要素がアクセシビリティツリーに公開されているか判定する
+4. 公開されていない場合 → `{ unknown: false, exposedToTree: false }` を返す
+5. `getComputedRole()` で ARIA ロールを計算する
+6. `getAccname()` でアクセシブル名を計算する（pretender コンテキストを含む -- [ヘルパー: accname](./helpers.ja.md#accname) を参照）
+7. ロール定義から `nameRequired` と `nameProhibited` を判定する
+8. `<slot>` の子要素をチェックする -- 存在する場合、名前が不明な可能性がある
+9. `mayBeFocusable()` でフォーカス可能性を計算する
+10. `getComputedAriaProps()` で計算された ARIA プロパティを収集する（必須 + 非デフォルトのプロパティ）
+
+`AccessibilityProperties` を返します（[型ユーティリティ](./helpers.ja.md#型ユーティリティ)を参照）。
+
+## `toString(fixed?)`
+
+トークンリストからソースコードを再構築します。
+
+- `fixed=false`（デフォルト）：元の `raw` 文字列を返す
+- `fixed=true`：オフセット追跡による置換を適用する：
+  1. `getTokenList()` を取得する（`startOffset` でソート済み）
+  2. 各トークンに対して：`toString(true) !== raw` の場合、修正済みコンテンツを文字列にスプライスする
+  3. 正確な位置を維持するために累積オフセット差を追跡する
+
+## `defaultView`
+
+`getComputedStyle()` を提供するモックウィンドウオブジェクトを返します。これは `getPropertyValue()` スタブを持つオブジェクトを返します。これは **Accessible Name and Description Computation** アルゴリズムのインターフェース要件を満たします。すべてのスタイルプロパティ値は空のオブジェクトを返します。
+
+## その他のメソッド
+
+| メソッド               | シグネチャ                                        | 説明                                                                                                 |
+| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `setRule`              | `setRule(rule: MLRule \| null): void`             | 現在評価中のルールを設定/クリアする                                                                  |
+| `getTokenList`         | `getTokenList(): ReadonlyArray<MLToken>`          | ソース再構築用のすべてのトークン。オフセットでソート済み（キャッシュ）。ノードと閉じタグの両方を含む |
+| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | 1始まりのソース位置でノードを検索する                                                                |
+| `debugMap`             | `debugMap(): string[]`                            | ドキュメントツリー構造のデバッグ出力                                                                 |
+
+## endTag モード
+
+| 値            | 動作                                                |
+| ------------- | --------------------------------------------------- |
+| `'omittable'` | HTML モード：特定の終了タグが省略可能（デフォルト） |
+| `'xml'`       | XML モード：すべての要素に明示的な終了タグが必要    |
+| `'never'`     | 終了タグなし（例: Pug, Slim）                       |

package/docs/ml-dom/document.md

@@ -0,0 +1,141 @@
+# MLDocument
+
+**Source:** `src/ml-dom/node/document.ts`
+
+Root node of the MLDOM tree. Extends `MLParentNode` and implements the DOM `Document` interface.
+
+## Construction
+
+The constructor receives:
+
+1. `ast: MLASTDocument` -- The parsed AST document
+2. `ruleset: Ruleset` -- Rule configuration
+3. `schemas: MLSchema` -- HTML/ARIA specification data (tuple)
+4. `options?` -- Optional configuration:
+   - `filename` -- Source file path
+   - `endTag` -- `'xml'` | `'omittable'` | `'never'` (default: `'omittable'`)
+   - `booleanish` -- Treat omitted boolean-like attributes as `true` (default: `false`)
+   - `tagNameCaseSensitive` -- Case-sensitive tag name comparison (default: `false`)
+   - `pretenders` -- Array of pretender definitions
+
+Construction steps:
+
+1. Builds a flat `nodeList` by iterating the AST `nodeList`, calling `createNode()` for each non-endtag node, then freezes the array
+2. Initializes pretender contexts via `_pretending(pretenders)` for all element nodes
+3. Distributes rule configuration to nodes via `_ruleMapping(ruleset)` using `RuleMapper`
+
+## `_pretending(pretenders?)`
+
+Iterates all element nodes in `nodeList` and calls `element.pretending(pretenders)` for each. See [MLElement > Pretender System](./element.md#pretender-system) for details.
+
+## `_ruleMapping(ruleset)`
+
+Distributes rules from the `Ruleset` to individual nodes using `RuleMapper`. The mapping has three layers, applied with increasing specificity:
+
+1. **Global rules** (`ruleset.rules`): Applied to `#document` and every node in `nodeList` with specificity `[0, 0, 0]`
+2. **Node rules** (`ruleset.nodeRules`): For each `nodeRule`, match its selector against elements using `matchMLSelector()`. If matched, merge the rule with the global rule and apply with the selector's specificity
+3. **Child node rules** (`ruleset.childNodeRules`): For each `childNodeRule`, match the parent selector, then apply merged rules to direct children (or all descendants if `inheritance: true`)
+
+`RuleMapper.set()` uses CSS specificity comparison -- a rule with higher specificity overrides one with lower specificity. `RuleMapper.apply()` transfers the resolved rules from the internal map to each node's `rules` record.
+
+See [rule-system.md](../rule-system.md) for full details on rule resolution.
+
+## Key Properties
+
+| Property               | Type                       | Description                                                           |
+| ---------------------- | -------------------------- | --------------------------------------------------------------------- |
+| `nodeList`             | `ReadonlyArray<MLNode>`    | Frozen flat list of all nodes in document order                       |
+| `specs`                | `MLMLSpec`                 | HTML/ARIA specification data                                          |
+| `isFragment`           | `boolean`                  | Whether document is a fragment (no root element required)             |
+| `currentRule`          | `Readonly<MLRule> \| null` | Rule currently being evaluated, or `null`                             |
+| `endTag`               | `EndTagType`               | End tag handling mode: `'xml'` \| `'omittable'` \| `'never'`          |
+| `booleanish`           | `boolean`                  | Whether to treat boolean-like attributes as boolean (default `false`) |
+| `tagNameCaseSensitive` | `boolean`                  | Case sensitivity for tag names (default `false`)                      |
+| `filename`             | `string \| undefined`      | Source filename                                                       |
+| `doctype`              | `MLDocumentType \| null`   | DOCTYPE node if present, found by scanning `nodeList`                 |
+
+## `walkOn(type, walker, skipWhenRuleIsDisabled?)`
+
+Walks nodes of a specific type using `sequentialWalker` over `nodeList`.
+
+**Parameters:**
+
+- `type` -- Node type to walk (see table below)
+- `walker` -- Callback function receiving the matched node
+- `skipWhenRuleIsDisabled` -- Skip nodes where the current rule is disabled (default: `true`)
+
+| Type                | Walked Over                                                    | Walker Parameter    |
+| ------------------- | -------------------------------------------------------------- | ------------------- |
+| `'Element'`         | `ELEMENT_NODE` nodes from `nodeList`                           | `MLElement`         |
+| `'Text'`            | `TEXT_NODE` nodes from `nodeList`                              | `MLText`            |
+| `'Comment'`         | `COMMENT_NODE` nodes from `nodeList`                           | `MLComment`         |
+| `'Attr'`            | All attributes on each `ELEMENT_NODE` in `nodeList`            | `MLAttr`            |
+| `'ElementCloseTag'` | `closeTag` of each `ELEMENT_NODE` in `nodeList` (skips `null`) | `MLElementCloseTag` |
+
+The `skipWhenRuleIsDisabled` parameter checks `node.rule.disabled` for the current rule. If `true`, the walker is not called for that node. This is how rules respect per-node disable directives.
+
+```typescript
+// Walk all elements (skipping disabled nodes by default)
+await document.walkOn('Element', async element => {
+  console.log(element.localName);
+});
+
+// Walk all attributes including disabled nodes
+await document.walkOn(
+  'Attr',
+  async attr => {
+    console.log(`${attr.name}="${attr.value}"`);
+  },
+  false,
+);
+```
+
+## `getAccessibilityProp(node, ariaVersion?)`
+
+Computes ARIA accessibility properties for a node.
+
+**Flow:**
+
+1. If `node` is not an element → return `null`
+2. If the element is a `<slot>` → return `{ unknown: true }` (content is determined at runtime)
+3. Call `isExposed()` to determine if the element is exposed to the accessibility tree
+4. If not exposed → return `{ unknown: false, exposedToTree: false }`
+5. Compute the ARIA role via `getComputedRole()`
+6. Compute the accessible name via `getAccname()` (includes pretender context -- see [Helpers: accname](./helpers.md#accname))
+7. Determine `nameRequired` and `nameProhibited` from the role definition
+8. Check for `<slot>` children -- if present, name may be unknown
+9. Compute focusability via `mayBeFocusable()`
+10. Collect computed ARIA properties via `getComputedAriaProps()` (required + non-default props)
+
+Returns `AccessibilityProperties` (see [Type Utilities](./helpers.md#type-utilities)).
+
+## `toString(fixed?)`
+
+Reconstructs the source code from the token list.
+
+- `fixed=false` (default): Returns the original `raw` string
+- `fixed=true`: Applies offset-tracked replacement:
+  1. Get `getTokenList()` (sorted by `startOffset`)
+  2. For each token: if `toString(true) !== raw`, splice the fixed content into the string
+  3. Track cumulative offset differences to maintain correct positions
+
+## `defaultView`
+
+Returns a mock window object providing `getComputedStyle()` that returns an object with a `getPropertyValue()` stub. This satisfies the **Accessible Name and Description Computation** algorithm interface requirement. All style property values return empty objects.
+
+## Other Methods
+
+| Method                 | Signature                                         | Description                                                                                          |
+| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `setRule`              | `setRule(rule: MLRule \| null): void`             | Set/clear the current rule being evaluated                                                           |
+| `getTokenList`         | `getTokenList(): ReadonlyArray<MLToken>`          | All tokens for source reconstruction, sorted by offset (cached). Includes both nodes and close tags. |
+| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | Find node at a 1-based source position                                                               |
+| `debugMap`             | `debugMap(): string[]`                            | Debug output of document tree structure                                                              |
+
+## endTag Modes
+
+| Value         | Behavior                                             |
+| ------------- | ---------------------------------------------------- |
+| `'omittable'` | HTML mode: certain end tags may be omitted (default) |
+| `'xml'`       | XML mode: all elements must have explicit end tags   |
+| `'never'`     | No end tags (e.g., Pug, Slim)                        |

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

@@ -0,0 +1,176 @@
+# MLElement
+
+**ソース:** `src/ml-dom/node/element.ts`
+
+HTML/SVG/MathML の要素ノードです。`MLParentNode` を継承し、`Element`、`HTMLElement`、`HTMLOrSVGElement` を実装します。MLDOM 階層の中で最も多機能なクラスです。
+
+## 名前プロパティ
+
+要素には異なる目的に使用される複数の名前関連プロパティがあります：
+
+| プロパティ      | HTML `<DIV>`                | SVG `<foreignObject>` | Pretender（`MyButton` → `button`） |
+| --------------- | --------------------------- | --------------------- | ---------------------------------- |
+| `localName`     | `"div"`                     | `"foreignObject"`     | `"button"`                         |
+| `nodeName`      | `"DIV"`                     | `"foreignObject"`     | `"BUTTON"`                         |
+| `rawName`       | `"DIV"`                     | `"foreignObject"`     | `"MyButton"`                       |
+| `fixedNodeName` | `"DIV"`（修正後は `"div"`） | `"foreignObject"`     | `"MyButton"`                       |
+| `tagName`       | `"DIV"`                     | `"foreignObject"`     | `"BUTTON"`                         |
+
+**ルール：**
+
+- **`localName`**: HTML 要素 → 小文字化。外部要素または非 `'html'` の elementType → そのまま。pretender コンテキスト → pretender の `localName`。`tagNameCaseSensitive` が `true` の場合 → 小文字化しない。
+- **`nodeName`**: HTML 要素 → 大文字化（DOM 慣例）。外部要素または非 `'html'` の elementType → AST からそのまま。pretender コンテキスト → pretender の `nodeName`。
+- **`rawName`**: 常に元の AST `nodeName`。正規化なし、pretender の影響なし。
+- **`fixedNodeName`**: 初期値は `rawName`。リント修正がタグ名を変更した場合に `fixNodeName(name)` で更新される。
+- **`tagName`**: `nodeName` と同じ（pretender コンテキストに従う）。
+
+## 要素型の判定
+
+| `elementType`     | 条件                                                           | 例                          |
+| ----------------- | -------------------------------------------------------------- | --------------------------- |
+| `'html'`          | 標準 HTML 要素（HTML 名前空間の既知のタグ名）                  | `<div>`、`<span>`、`<p>`    |
+| `'web-component'` | タグ名にハイフンを含む（Custom Element 慣例）                  | `<my-component>`、`<x-app>` |
+| `'authored'`      | ハイフンを含まない非標準タグ名（フレームワークコンポーネント） | `<MyComponent>`（JSX）      |
+
+`elementType` はパーサーが AST 作成時に決定し、`astNode.elementType` として格納されます。
+
+## 属性アクセス
+
+### `attributes`（MLNamedNodeMap）
+
+`attributes` ゲッターは重複排除された `MLNamedNodeMap` を返します：
+
+1. 属性ソースを選択する：pretender コンテキスト（`type === 'pretender'`）の場合、pretender 要素の属性を使用する。それ以外の場合は元の属性を使用する
+2. 名前で重複排除する：属性を反復し、各名前の最初の出現のみを保持する（[HTML パースエラー: duplicate-attribute](https://html.spec.whatwg.org/#parse-error-duplicate-attribute) 仕様に従う）
+3. `MLNamedNodeMap` でラップし、結果をキャッシュする
+
+### 属性メソッド
+
+| メソッド                | シグネチャ                                            | 説明                                                                      |
+| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
+| `getAttribute`          | `getAttribute(name: string): string \| null`          | 大文字小文字を区別しない名前検索で、最初にマッチした属性の `value` を返す |
+| `getAttributeToken`     | `getAttributeToken(name: string): MLAttr[]`           | 名前にマッチする**すべての** `MLAttr` トークンを返す（重複属性に対応）    |
+| `getAttributeTokens`    | `getAttributeTokens(): ReadonlyArray<MLAttr>`         | すべての属性トークン（pretender コンテキスト → pretender の属性）         |
+| `getAttributePretended` | `getAttributePretended(name: string): string \| null` | pretender コンテキストを**無視**して**元の**要素から属性値を取得する      |
+| `hasAttribute`          | `hasAttribute(name: string): boolean`                 | 大文字小文字を区別しない存在チェック（`getAttribute` に委譲）             |
+
+### `hasMutableAttributes()`
+
+属性が非決定的な場合に `true` を返します：
+
+- `nameNode` を持たない属性がある（つまり `{...props}` のようなスプレッド属性）
+- `isDynamicValue === true` の属性がある（例：テンプレート式）
+
+ルールはこれを使って、属性セットが静的解析時に完全には分からないことを検出します。
+
+## セレクタマッチング
+
+### `matches(selector, scope?)`
+
+`boolean` を返します。`matchMLSelector()` に委譲し、`matched` をチェックします。
+
+### `matchMLSelector(selector, scope?)`
+
+CSS セレクタ文字列と `RegexSelector` オブジェクトの両方をサポートする拡張セレクタマッチングです。`SelectorMatches`（詳細度と正規表現キャプチャデータを含むマッチ結果）を返します。
+
+**pretender 要素の2段階マッチング：**
+
+1. 要素が pretender コンテキスト（`type === 'pretender'`）を持つ場合：
+   - まず **pretender として**マッチングする（例：`<button>` として）
+   - pretender がマッチした場合 → 結果を返す
+2. pretender がマッチしなかった場合：
+   - 一時的に `pretenderContext` を `null` に設定する
+   - **元の要素として**マッチングする（例：`<MyButton>` として）
+   - `pretenderContext` を復元する
+   - 結果を返す
+
+これにより、`button` をターゲットにしたルールが pretender にマッチし、`MyButton` をターゲットにしたルールが引き続き元の要素にマッチすることが保証されます。
+
+### `closest(selectors)`
+
+`this` から `parentElement` チェーンを遡り、`matches(selectors)` が `true` になる最初の要素を返します。
+
+## Pretender システム
+
+Pretender システムのアーキテクチャ、初期化フロー、プロパティ委譲、アクセシブル名の統合についての包括的なドキュメントは、専用の [Pretender システム](./pretender.ja.md)リファレンスを参照してください。
+
+## その他のメソッド
+
+| メソッド                 | シグネチャ                                        | 説明                                                                               |
+| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `fixNodeName`            | `fixNodeName(name: string): void`                 | リント自動修正用に `fixedNodeName` を更新する                                      |
+| `getAccessibleName`      | `getAccessibleName(version: ARIAVersion): string` | `getAccname()` を通じてアクセシブル名を計算する                                    |
+| `toNormalizeString`      | `toNormalizeString(): string`                     | 比較用の正規化された表現を返す（キャッシュ済み）。子要素と属性を再帰的に正規化する |
+| `nextElementSibling`     | `get nextElementSibling: MLElement \| null`       | 次の兄弟要素                                                                       |
+| `previousElementSibling` | `get previousElementSibling: MLElement \| null`   | 前の兄弟要素                                                                       |
+
+## 可変な子要素の検出
+
+### `hasMutableChildren(attr?)`
+
+要素の子が非決定的な場合に `true` を返します。`getPureChildNodes()` を反復します：
+
+- `blockBehavior` を**持たない** `MLBlock` の子が存在する（つまり `blockBehavior` が `null` -- `'if'` や `'each'` のような認識されたブロック動作型を持つブロックは `conditionalChildNodes()` で処理されるためスキップされる）
+- `<slot>` の子要素が存在する（コンテンツは実行時に注入される）
+- `attr` が `true` の場合：子要素のいずれかが `hasMutableAttributes() === true` を持つ
+- 子要素に対して再帰的に `hasMutableChildren()` をチェックする
+
+これは `permitted-contents` などのルールが、子要素が予測不可能な場合に検証をスキップするかどうかを判断するために使用されます。
+
+## `getChildElementsAndTextNodeWithoutWhitespaces()`
+
+省略された要素をフラット化した `MLElement | MLText`（非空白）の子のフラット配列を返します：
+
+1. `childNodes` を反復する
+2. 要素の場合：`isOmitted` なら再帰的にその子を取得し、代わりにそれらを含める（フラット化）
+3. テキストノードの場合：空白でない場合のみ含める
+4. 結果はキャッシュされる
+
+これはコンテンツモデルの検証に使用されます -- 暗黙の `<tbody>` のような省略された要素は、コンテンツモデルの目的では透過的です。
+
+## 省略された（ゴースト）要素
+
+`isOmitted === true` の要素はパーサーによって暗黙的に挿入されたものです（例：HTML パーサーが省略された `<tbody>` を挿入）。これらの要素は：
+
+- 対応するソーストークンを持たない
+- `prevToken` によってスキップされる（有効なオフセットチェーンを維持するため）
+- `toString(fixed)` から `raw` を返す（ソースに修正すべきものがないため修正は適用されない）
+- `getChildElementsAndTextNodeWithoutWhitespaces()` によってフラット化される
+
+## 閉じタグ
+
+| プロパティ | 型                          | 説明                                                                                 |
+| ---------- | --------------------------- | ------------------------------------------------------------------------------------ |
+| `closeTag` | `MLElementCloseTag \| null` | ペアの閉じタグ。void 要素、自己閉じ要素、または `endTag === 'never'` の場合は `null` |
+
+## `toString(fixed?)`
+
+修正を適用して要素のソース文字列を再構築します。
+
+- `fixed=false` または pretender/省略要素/`#` プレフィックスの nodeName → `raw` を返す
+- `fixed=true`:
+  1. 置換可能なノードのリストを構築する：`[tagOpenChar + fixedNodeName, ...overriddenCommentNodes, ...attributes]`
+  2. 各ノードに対して、正しいオフセットで `node.toString(true)` をスプライスする
+  3. 正確な位置決めのために累積オフセット差を追跡する
+
+```
+Original: <DIV class="foo" >
+Fixed:    <div class="foo" >
+          ^^^^              (fixedNodeName が "DIV" から "div" に変更)
+```
+
+## その他のプロパティ
+
+| プロパティ         | 型                           | 説明                                          |
+| ------------------ | ---------------------------- | --------------------------------------------- |
+| `namespaceURI`     | `NamespaceURI`               | 要素の名前空間（HTML, SVG, MathML）           |
+| `isForeignElement` | `boolean`                    | SVG/MathML 要素の場合 `true`                  |
+| `elementType`      | `ElementType`                | `'html'` \| `'web-component'` \| `'authored'` |
+| `isOmitted`        | `boolean`                    | 暗黙的に挿入された要素の場合 `true`           |
+| `blockBehavior`    | `MLASTBlockBehavior \| null` | AST からのブロック動作（存在する場合）        |
+| `classList`        | `MLDomTokenList`             | `class` 属性からの CSS クラスリスト           |
+| `className`        | `string`                     | class 属性値                                  |
+| `id`               | `string`                     | ID 属性値（存在しない場合は空文字列）         |
+| `hasSpreadAttr`    | `boolean`                    | 要素にスプレッド属性があるかどうか            |
+| `tagOpenChar`      | `string`                     | 開始タグ区切り文字（例: `<` または `<%`）     |
+| `tagCloseChar`     | `string`                     | 閉じタグ区切り文字（例: `>` または `%>`）     |

package/docs/ml-dom/element.md

@@ -0,0 +1,176 @@
+# MLElement
+
+**Source:** `src/ml-dom/node/element.ts`
+
+HTML/SVG/MathML element node. Extends `MLParentNode` and implements `Element`, `HTMLElement`, and `HTMLOrSVGElement`. This is the most feature-rich class in the MLDOM hierarchy.
+
+## Name Properties
+
+The element has multiple name-related properties that serve different purposes:
+
+| Property        | HTML `<DIV>`                   | SVG `<foreignObject>` | Pretender (`MyButton` → `button`) |
+| --------------- | ------------------------------ | --------------------- | --------------------------------- |
+| `localName`     | `"div"`                        | `"foreignObject"`     | `"button"`                        |
+| `nodeName`      | `"DIV"`                        | `"foreignObject"`     | `"BUTTON"`                        |
+| `rawName`       | `"DIV"`                        | `"foreignObject"`     | `"MyButton"`                      |
+| `fixedNodeName` | `"DIV"` (or `"div"` after fix) | `"foreignObject"`     | `"MyButton"`                      |
+| `tagName`       | `"DIV"`                        | `"foreignObject"`     | `"BUTTON"`                        |
+
+**Rules:**
+
+- **`localName`**: HTML elements → lowercased. Foreign elements or non-`'html'` elementType → as-is. Pretender context → pretender's `localName`. If `tagNameCaseSensitive` is `true` → no lowercasing.
+- **`nodeName`**: HTML elements → uppercased (DOM convention). Foreign elements or non-`'html'` elementType → as-is from AST. Pretender context → pretender's `nodeName`.
+- **`rawName`**: Always the original AST `nodeName`, with no normalization and no pretender influence.
+- **`fixedNodeName`**: Starts as `rawName`. Updated by `fixNodeName(name)` when a lint fix modifies the tag name.
+- **`tagName`**: Same as `nodeName` (follows pretender context).
+
+## Element Type Resolution
+
+| `elementType`     | Condition                                                  | Examples                    |
+| ----------------- | ---------------------------------------------------------- | --------------------------- |
+| `'html'`          | Standard HTML element (known tag in HTML namespace)        | `<div>`, `<span>`, `<p>`    |
+| `'web-component'` | Tag name contains a hyphen (Custom Element convention)     | `<my-component>`, `<x-app>` |
+| `'authored'`      | Non-standard tag name without hyphen (framework component) | `<MyComponent>` (JSX)       |
+
+The `elementType` is determined by the parser at AST creation time and stored as `astNode.elementType`.
+
+## Attribute Access
+
+### `attributes` (MLNamedNodeMap)
+
+The `attributes` getter returns a deduplicated `MLNamedNodeMap`:
+
+1. Select the attribute source: if in pretender context (`type === 'pretender'`), use the pretender element's attributes; otherwise, use the original attributes
+2. Deduplicate by name: iterate the attributes, keeping only the first occurrence of each name (per the [HTML parse error: duplicate-attribute](https://html.spec.whatwg.org/#parse-error-duplicate-attribute) spec)
+3. Wrap in `MLNamedNodeMap` and cache the result
+
+### Attribute Methods
+
+| Method                  | Signature                                             | Description                                                                            |
+| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `getAttribute`          | `getAttribute(name: string): string \| null`          | Case-insensitive name lookup, returns the first matching attribute's `value`           |
+| `getAttributeToken`     | `getAttributeToken(name: string): MLAttr[]`           | Returns **all** `MLAttr` tokens matching the name (handles duplicate attributes)       |
+| `getAttributeTokens`    | `getAttributeTokens(): ReadonlyArray<MLAttr>`         | All attribute tokens (pretender context → pretender's attributes)                      |
+| `getAttributePretended` | `getAttributePretended(name: string): string \| null` | Gets attribute value from the **original** element, **ignoring** the pretender context |
+| `hasAttribute`          | `hasAttribute(name: string): boolean`                 | Case-insensitive existence check (delegates to `getAttribute`)                         |
+
+### `hasMutableAttributes()`
+
+Returns `true` if any attribute is non-deterministic:
+
+- An attribute has no `nameNode` (i.e., it's a spread attribute like `{...props}`)
+- An attribute has `isDynamicValue === true` (e.g., template expression)
+
+Rules use this to detect that the attribute set is not fully known at static analysis time.
+
+## Selector Matching
+
+### `matches(selector, scope?)`
+
+Returns `boolean`. Delegates to `matchMLSelector()` and checks `matched`.
+
+### `matchMLSelector(selector, scope?)`
+
+Extended selector matching supporting both CSS selector strings and `RegexSelector` objects. Returns `SelectorMatches` (match result with specificity and regex capture data).
+
+**Two-phase matching for pretender elements:**
+
+1. If the element has a pretender context (`type === 'pretender'`):
+   - First, match **as the pretender** (e.g., as `<button>`)
+   - If the pretender matches → return the result
+2. If the pretender did not match:
+   - Temporarily set `pretenderContext` to `null`
+   - Match **as the original element** (e.g., as `<MyButton>`)
+   - Restore the `pretenderContext`
+   - Return the result
+
+This ensures that rules targeting `button` match the pretender, while rules targeting `MyButton` still match the original.
+
+### `closest(selectors)`
+
+Walks up the `parentElement` chain from `this`, returning the first element where `matches(selectors)` is `true`.
+
+## Pretender System
+
+For comprehensive documentation on the pretender system's architecture, initialization flow, property delegation, and accessible name integration, see the dedicated [Pretender System](./pretender.md) reference.
+
+## Other Methods
+
+| Method                   | Signature                                         | Description                                                                                                  |
+| ------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `fixNodeName`            | `fixNodeName(name: string): void`                 | Updates `fixedNodeName` for lint auto-fix of the tag name                                                    |
+| `getAccessibleName`      | `getAccessibleName(version: ARIAVersion): string` | Computes the accessible name via `getAccname()`                                                              |
+| `toNormalizeString`      | `toNormalizeString(): string`                     | Returns a normalized representation for comparison (cached). Recursively normalizes children and attributes. |
+| `nextElementSibling`     | `get nextElementSibling: MLElement \| null`       | Next sibling element                                                                                         |
+| `previousElementSibling` | `get previousElementSibling: MLElement \| null`   | Previous sibling element                                                                                     |
+
+## Mutable Children Detection
+
+### `hasMutableChildren(attr?)`
+
+Returns `true` if the element's children are non-deterministic. Iterates `getPureChildNodes()`:
+
+- An `MLBlock` child exists **without** a `blockBehavior` (i.e., `blockBehavior` is `null` -- blocks with recognized block behavior types like `'if'`, `'each'` are skipped because they are handled by `conditionalChildNodes()`)
+- A `<slot>` child element exists (content is injected at runtime)
+- If `attr` is `true`: any child element has `hasMutableAttributes() === true`
+- Recursively checks `hasMutableChildren()` on child elements
+
+This is used by rules like `permitted-contents` to decide whether to skip validation when the children are unpredictable.
+
+## `getChildElementsAndTextNodeWithoutWhitespaces()`
+
+Returns a flat array of `MLElement | MLText` (non-whitespace) children, with omitted elements flattened:
+
+1. Iterate `childNodes`
+2. For elements: if `isOmitted`, recursively get their children and include them instead (flattening)
+3. For text nodes: include only if not whitespace
+4. Result is cached
+
+This is used for content model validation -- omitted elements like an implicit `<tbody>` are transparent for content model purposes.
+
+## Omitted (Ghost) Elements
+
+Elements with `isOmitted === true` were implicitly inserted by the parser (e.g., HTML parser inserting an omitted `<tbody>`). These elements:
+
+- Have no corresponding source tokens
+- Are skipped by `prevToken` (to maintain valid offset chains)
+- Return `raw` from `toString(fixed)` (no fix is applied since there's nothing in the source to fix)
+- Are flattened by `getChildElementsAndTextNodeWithoutWhitespaces()`
+
+## Close Tag
+
+| Property   | Type                        | Description                                                                                      |
+| ---------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `closeTag` | `MLElementCloseTag \| null` | Paired close tag. `null` for void elements, self-closing elements, or when `endTag === 'never'`. |
+
+## `toString(fixed?)`
+
+Reconstructs the element's source string with fixes applied.
+
+- `fixed=false` or pretender/omitted/`#`-prefixed nodeName → return `raw`
+- `fixed=true`:
+  1. Build a list of replaceable nodes: `[tagOpenChar + fixedNodeName, ...overriddenCommentNodes, ...attributes]`
+  2. For each node, splice `node.toString(true)` at the correct offset
+  3. Track cumulative offset differences for accurate positioning
+
+```
+Original: <DIV class="foo" >
+Fixed:    <div class="foo" >
+          ^^^^              (fixedNodeName changed from "DIV" to "div")
+```
+
+## Other Properties
+
+| Property           | Type                         | Description                                   |
+| ------------------ | ---------------------------- | --------------------------------------------- |
+| `namespaceURI`     | `NamespaceURI`               | Element namespace (HTML, SVG, MathML)         |
+| `isForeignElement` | `boolean`                    | `true` for SVG/MathML elements                |
+| `elementType`      | `ElementType`                | `'html'` \| `'web-component'` \| `'authored'` |
+| `isOmitted`        | `boolean`                    | `true` for implicitly inserted elements       |
+| `blockBehavior`    | `MLASTBlockBehavior \| null` | Block behavior from the AST, if any           |
+| `classList`        | `MLDomTokenList`             | CSS class list from `class` attribute         |
+| `className`        | `string`                     | Class attribute value                         |
+| `id`               | `string`                     | ID attribute value (empty string if absent)   |
+| `hasSpreadAttr`    | `boolean`                    | Whether element has spread attributes         |
+| `tagOpenChar`      | `string`                     | Opening tag delimiter (e.g., `<` or `<%`)     |
+| `tagCloseChar`     | `string`                     | Closing tag delimiter (e.g., `>` or `%>`)     |