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

package/docs/ml-dom/node.md

@@ -0,0 +1,199 @@
+# MLNode / MLParentNode
+
+## MLNode
+
+**Source:** `src/ml-dom/node/node.ts`
+
+Abstract base class for all markuplint DOM node wrappers. Extends `MLToken` with DOM `Node` interface compliance, tree traversal, rule configuration access, and child node management.
+
+### Node Type Constants
+
+| Constant                        | Value | DOM Standard              |
+| ------------------------------- | ----- | ------------------------- |
+| `ELEMENT_NODE`                  | `1`   | Yes                       |
+| `ATTRIBUTE_NODE`                | `2`   | Yes                       |
+| `TEXT_NODE`                     | `3`   | Yes                       |
+| `CDATA_SECTION_NODE`            | `4`   | Yes                       |
+| `PROCESSING_INSTRUCTION_NODE`   | `7`   | Yes                       |
+| `COMMENT_NODE`                  | `8`   | Yes                       |
+| `DOCUMENT_NODE`                 | `9`   | Yes                       |
+| `DOCUMENT_TYPE_NODE`            | `10`  | Yes                       |
+| `DOCUMENT_FRAGMENT_NODE`        | `11`  | Yes                       |
+| `MARKUPLINT_PREPROCESSOR_BLOCK` | `101` | No (markuplint extension) |
+
+### Tree Structure Properties
+
+| Property                | Type                                                               | Description                                                                     |
+| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `parentNode`            | `MLDocument \| MLDocumentFragment \| MLElement \| null`            | DOM-compliant parent. Transparent `MLBlock` parents are skipped.                |
+| `parentElement`         | `MLElement \| null`                                                | Nearest ancestor that is an `MLElement`                                         |
+| `syntacticalParentNode` | `MLDocument \| MLDocumentFragment \| MLElement \| MLBlock \| null` | Syntactical parent including `MLBlock` nodes                                    |
+| `childNodes`            | `NodeListOf<MLChildNode>`                                          | Child nodes (Element, Text, Comment, Block). Fragment children are inlined.     |
+| `firstChild`            | `MLChildNode \| null`                                              | First child node                                                                |
+| `lastChild`             | `MLChildNode \| null`                                              | Last child node                                                                 |
+| `nextSibling`           | `MLChildNode \| null`                                              | Next sibling with the same `parentNode`                                         |
+| `previousSibling`       | `MLChildNode \| null`                                              | Previous sibling with the same `parentNode`                                     |
+| `nextNode`              | `MLNode \| null`                                                   | Next node in syntactical sibling list (from `syntacticalParentNode.childNodes`) |
+| `prevNode`              | `MLNode \| null`                                                   | Previous node in syntactical sibling list                                       |
+| `prevToken`             | `MLNode \| null`                                                   | Previous node in document-order `nodeList` (skips omitted elements)             |
+| `ownerDocument`         | `any`                                                              | Owner document (DOM-compatible, typed as `any`)                                 |
+| `ownerMLDocument`       | `MLDocument<T, O>`                                                 | Owner document with proper generic types                                        |
+| `isFragment`            | `boolean`                                                          | Whether this node acts as a fragment                                            |
+
+#### `nextNode`/`prevNode` vs `nextSibling`/`previousSibling`
+
+These two pairs serve different purposes:
+
+- **`nextNode`/`prevNode`**: Navigate the syntactical sibling list from `syntacticalParentNode.childNodes` (or `nodeList` if no syntactical parent). These include `MLBlock` nodes and work at the AST level.
+- **`nextSibling`/`previousSibling`**: Navigate siblings sharing the same DOM `parentNode`. These skip over nodes whose `parentNode` differs (e.g., nodes inside non-transparent blocks).
+
+#### `prevToken` and Omitted Elements
+
+`prevToken` walks the document-order `nodeList` but **skips omitted (ghost) elements**. Omitted elements have no corresponding source tokens, so including them would break offset calculations. This is important for indentation analysis and source reconstruction.
+
+### `childNodes` and Fragment Expansion
+
+When a child node has `isFragment === true`, its own children are inlined into the parent's `childNodes`:
+
+```jsx
+// JSX fragment
+<div>
+  <>
+    {' '}
+    {/* isFragment = true */}
+    <p>A</p>
+    <p>B</p>
+  </>
+  <p>C</p>
+</div>
+```
+
+`div.childNodes` yields `[<p>A</p>, <p>B</p>, <p>C</p>]` -- the fragment wrapper is transparent.
+
+### `parentNode` and MLBlock Transparency
+
+The `parentNode` getter handles `MLBlock` transparency:
+
+1. Get the `syntacticalParentNode`
+2. If the parent is an `MLBlock` with `isTransparent === true`: return the block's `parentNode` (recursive skip)
+3. If the parent is an `MLBlock` with `isTransparent === false`: return `null` (the node is "orphaned" from the DOM perspective)
+4. If the parent is a fragment `MLDocument` (i.e., `isFragment === true`): return `null`
+5. Otherwise: return the parent as-is
+
+| Scenario                                      | `syntacticalParentNode` | `parentNode`               |
+| --------------------------------------------- | ----------------------- | -------------------------- |
+| `<div>` inside `<body>`                       | `<body>`                | `<body>`                   |
+| `<span>` inside Pug `if` block inside `<div>` | `#ml-block`             | `<div>` (transparent skip) |
+| `<span>` inside non-transparent block         | `#ml-block`             | `null`                     |
+| Top-level in fragment document                | `#document`             | `null`                     |
+
+```pug
+//- Pug example
+div
+  if foo
+    span
+    //- syntacticalParentNode: #ml-block
+    //- parentNode: <div>  (block is transparent, skipped)
+```
+
+### `conditionalChildNodes()` -- Conditional Branch Pattern Generation
+
+Generates all possible child node combinations from template engine conditional branches. This is used by rules like `permitted-contents` to verify content models against every possible rendering path.
+
+#### Algorithm
+
+1. Walk `childNodes` sequentially
+2. When an `MLBlock` is encountered, determine the branch `mode` from its `blockBehavior?.type`:
+   - `'if'` or `'if:elseif'` → mode `'if'`
+   - `'switch:case'` → mode `'switch'`
+   - `'if:else'`, `'each'`, `'each:empty'`, `'switch:default'`, `'await'`, `'await:catch'`, `'await:then'` → continue in current mode (no new mode set)
+   - Other types → skip (not a conditional branch)
+3. Recursively call `conditionalChildNodes()` on the block to get its sub-patterns
+4. Collect branches; when a non-block child is reached, close the current branch group
+5. Whitespace-only text nodes are skipped
+6. For `'if'` and `'switch'` modes: a `null` sentinel is appended to represent the "empty branch" (the case where nothing is rendered)
+7. Pass the collected branches to `branchesToPatterns()` to generate the Cartesian product of all combinations
+
+#### Example
+
+```html
+<ul>
+  {% if cond %}
+  <li>A</li>
+  {% else %}
+  <li>B</li>
+  {% endif %}
+  <li>C</li>
+</ul>
+```
+
+`ul.conditionalChildNodes()` returns:
+
+- Pattern 1: `[<li>A</li>, <li>C</li>]`
+- Pattern 2: `[<li>B</li>, <li>C</li>]`
+
+The `permitted-contents` rule checks **every** pattern to ensure validity.
+
+### `findSubsequentNodes(selector?)`
+
+Collects nodes appearing after this node in document order:
+
+1. Iterates `ownerMLDocument.nodeList`
+2. Skips nodes whose `endOffset <= this.endOffset`
+3. Skips descendants (via `this.contains(node)`)
+4. If `selector` is provided: only includes elements matching the CSS selector
+5. If no `selector`: includes all subsequent `MLChildNode` instances (Element, Text, Comment, Block)
+
+### Rule Properties
+
+| Property | Type                      | Description                                  |
+| -------- | ------------------------- | -------------------------------------------- |
+| `rules`  | `Record<string, AnyRule>` | Rules mapped to this node by `RuleMapper`    |
+| `rule`   | `RuleInfo<T, O>`          | Current rule's resolved config for this node |
+
+The `rule` getter retrieves the setting for the currently-evaluating rule (via `document.currentRule.name`) from the `rules` record, then resolves it through `optimizeOption()`. It throws an error if no rule is currently being evaluated.
+
+### Type Narrowing with `is()`
+
+The `is()` method returns `this is NodeTypeOf<NType, T, O>`, enabling TypeScript type narrowing:
+
+```typescript
+function processNode(node: MLNode<any, any>) {
+  if (node.is(node.ELEMENT_NODE)) {
+    // node is narrowed to MLElement<any, any>
+    console.log(node.localName);
+  } else if (node.is(node.TEXT_NODE)) {
+    // node is narrowed to MLText<any, any>
+    console.log(node.isWhitespace());
+  } else if (node.is(node.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+    // node is narrowed to MLBlock<any, any>
+    console.log(node.blockBehavior?.type);
+  }
+}
+```
+
+## MLParentNode
+
+**Source:** `src/ml-dom/node/parent-node.ts`
+
+Abstract base class for nodes that can have children (`MLElement`, `MLDocument`, `MLDocumentFragment`). Implements the DOM `ParentNode` mixin.
+
+### Properties
+
+| Property            | Type                          | Description                    |
+| ------------------- | ----------------------------- | ------------------------------ |
+| `children`          | `HTMLCollectionOf<MLElement>` | Element-only children (cached) |
+| `childElementCount` | `number`                      | Number of element children     |
+| `firstElementChild` | `MLElement \| null`           | First child element            |
+| `lastElementChild`  | `MLElement \| null`           | Last child element             |
+
+### Methods
+
+| Method             | Signature                                                    | Description                                                        |
+| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `querySelector`    | `querySelector(selectors: string): MLElement \| null`        | First descendant matching CSS selector                             |
+| `querySelectorAll` | `querySelectorAll(selectors: string): NodeListOf<MLElement>` | All descendants matching CSS selector (cached per selector string) |
+
+### `_descendantsToArray(filter?)`
+
+Protected method that walks the tree recursively via `syncWalk` and returns a filtered array of descendants. Used internally by `querySelectorAll`.

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

@@ -0,0 +1,120 @@
+# その他のノード型
+
+MLBlock のドキュメントは専用の [MLBlock](./block.ja.md) リファレンスを参照してください。
+
+## MLCharacterData（抽象）
+
+**ソース:** `src/ml-dom/node/character-data.ts`
+
+テキストコンテンツノードの抽象基底クラスです。DOM `CharacterData` インターフェースを実装します。
+
+| プロパティ               | 型                  | 説明                                    |
+| ------------------------ | ------------------- | --------------------------------------- |
+| `data`                   | `string`            | 文字データの内容（現在は `raw` を返す） |
+| `nodeValue`              | `string \| null`    | `data` と同じ                           |
+| `textContent`            | `string`            | `data` と同じ                           |
+| `nextElementSibling`     | `MLElement \| null` | 次の兄弟要素                            |
+| `previousElementSibling` | `MLElement \| null` | 前の兄弟要素                            |
+
+メソッド: `after()`、`before()`、`remove()`、`replaceWith()`。
+
+## MLText
+
+**ソース:** `src/ml-dom/node/text.ts`
+
+テキストノードです。`MLCharacterData` を継承し、DOM `Text` を実装します。
+
+- `nodeName`: `'#text'`
+- `nodeType`: `3`（`TEXT_NODE`）
+
+| プロパティ / メソッド       | 戻り値    | 説明                                               |
+| --------------------------- | --------- | -------------------------------------------------- |
+| `isBogus`                   | `boolean` | 不正な AST ノードから生成されたノードの場合 `true` |
+| `isWhitespace()`            | `boolean` | テキストが `/^\s+$/` にマッチする場合 `true`       |
+| `isRawTextElementContent()` | `boolean` | 親要素が `<script>` または `<style>` の場合 `true` |
+
+## MLComment
+
+**ソース:** `src/ml-dom/node/comment.ts`
+
+コメントノードです。`MLCharacterData` を継承し、DOM `Comment` を実装します。
+
+- `nodeName`: `'#comment'`
+- `nodeType`: `8`（`COMMENT_NODE`）
+- `textContent`: コメントの `data` を返す
+
+## MLDocumentType
+
+**ソース:** `src/ml-dom/node/document-type.ts`
+
+DOCTYPE ノードです。`MLNode` を継承し、DOM `DocumentType` を実装します。
+
+- `nodeType`: `10`（`DOCUMENT_TYPE_NODE`）
+- `nodeName`: `name` と同じ
+- `textContent`: 常に `null`
+
+| プロパティ | 型       | 説明                                 |
+| ---------- | -------- | ------------------------------------ |
+| `name`     | `string` | ドキュメントタイプ名（例: `"html"`） |
+| `publicId` | `string` | パブリック識別子、または空文字列     |
+| `systemId` | `string` | システム識別子、または空文字列       |
+
+## MLElementCloseTag
+
+**ソース:** `src/ml-dom/node/element-close-tag.ts`
+
+対応する開始タグ要素とペアになる閉じタグです。`MLNode` を継承します。閉じタグはドキュメントの `nodeList` の一部**ではなく**、ペアの `MLElement` のサテライトとしてのみ存在します。
+
+MLElementCloseTag は2つの目的で存在します：
+
+1. **構文位置の追跡**: 閉じタグのソース位置（`startLine`、`startCol`、`raw` など）を記録します。`case-sensitive-tag-name` のようなルールは、開始タグではなく閉じタグの正確な位置で違反を報告するためにこれを使用します。
+2. **存在の有無の検出**: 閉じタグが存在しない場合、`MLElement.closeTag` は `null` になります。`end-tag` のようなルールは `el.closeTag != null` で非 void 要素の閉じタグの欠落（省略や漏れ）を検出します。
+
+### プロパティ
+
+| プロパティ | 型          | 説明                                            |
+| ---------- | ----------- | ----------------------------------------------- |
+| `pair`     | `MLElement` | 対応する開始要素                                |
+| `rawName`  | `string`    | ソースに記述されたタグ名（AST `nodeName` から） |
+| `nodeName` | `string`    | ペアの要素の `nodeName` から導出されたタグ名    |
+
+### ルールでの使用例
+
+```typescript
+// end-tag ルール: 閉じタグの欠落を検出
+if (el.closeTag != null) {
+  return; // 閉じタグが存在する → OK
+}
+report({ scope: el, message: t('Missing {0}', t('the {0}', 'end tag')) });
+
+// case-sensitive-tag-name ルール: 閉じタグのソース位置でレポート
+const closeTag = el.closeTag;
+if (closeTag && deny.test(closeTag.raw)) {
+  report({
+    scope: {
+      rule: el.rule,
+      startLine: closeTag.startLine,
+      startCol: closeTag.startCol,
+      raw: closeTag.raw,
+    },
+    message,
+  });
+}
+```
+
+### `toString(fixed?)`
+
+`fixed=true` の場合：
+
+- 要素が仮想要素（`#` で始まる）または省略された要素 → `raw` を返す
+- それ以外：ペアの区切り文字を使って `tagOpenChar` + `/` + タグ名 + `tagCloseChar` を再構築する。タグ名は `pair.fixedNodeName === pair.rawName`（修正なし）の場合は `this.rawName` を使い、それ以外は `pair.fixedNodeName` を使う
+
+## MLDocumentFragment
+
+**ソース:** `src/ml-dom/node/document-fragment.ts`
+
+JSX フラグメント（`<>...</>`）や同様の構文のフラグメントルートノードです。`MLParentNode` を継承し、DOM `DocumentFragment` を実装します。
+
+- `nodeName`: `'#document-fragment'`
+- `nodeType`: `11`（`DOCUMENT_FRAGMENT_NODE`）
+- `textContent`: すべての子ノードのテキストコンテンツの連結

package/docs/ml-dom/others.md

@@ -0,0 +1,120 @@
+# Other Node Types
+
+For MLBlock documentation, see the dedicated [MLBlock](./block.md) reference.
+
+## MLCharacterData (abstract)
+
+**Source:** `src/ml-dom/node/character-data.ts`
+
+Abstract base class for text content nodes. Implements DOM `CharacterData` interface.
+
+| Property                 | Type                | Description                                      |
+| ------------------------ | ------------------- | ------------------------------------------------ |
+| `data`                   | `string`            | Character data content (currently returns `raw`) |
+| `nodeValue`              | `string \| null`    | Same as `data`                                   |
+| `textContent`            | `string`            | Same as `data`                                   |
+| `nextElementSibling`     | `MLElement \| null` | Next sibling element                             |
+| `previousElementSibling` | `MLElement \| null` | Previous sibling element                         |
+
+Methods: `after()`, `before()`, `remove()`, `replaceWith()`.
+
+## MLText
+
+**Source:** `src/ml-dom/node/text.ts`
+
+Text node. Extends `MLCharacterData` and implements DOM `Text`.
+
+- `nodeName`: `'#text'`
+- `nodeType`: `3` (`TEXT_NODE`)
+
+| Property / Method           | Returns   | Description                                             |
+| --------------------------- | --------- | ------------------------------------------------------- |
+| `isBogus`                   | `boolean` | `true` if this node originated from an invalid AST node |
+| `isWhitespace()`            | `boolean` | `true` if text matches `/^\s+$/`                        |
+| `isRawTextElementContent()` | `boolean` | `true` if parent element is `<script>` or `<style>`     |
+
+## MLComment
+
+**Source:** `src/ml-dom/node/comment.ts`
+
+Comment node. Extends `MLCharacterData` and implements DOM `Comment`.
+
+- `nodeName`: `'#comment'`
+- `nodeType`: `8` (`COMMENT_NODE`)
+- `textContent`: Returns the comment's `data`
+
+## MLDocumentType
+
+**Source:** `src/ml-dom/node/document-type.ts`
+
+DOCTYPE node. Extends `MLNode` and implements DOM `DocumentType`.
+
+- `nodeType`: `10` (`DOCUMENT_TYPE_NODE`)
+- `nodeName`: Same as `name`
+- `textContent`: Always `null`
+
+| Property   | Type     | Description                         |
+| ---------- | -------- | ----------------------------------- |
+| `name`     | `string` | Document type name (e.g., `"html"`) |
+| `publicId` | `string` | Public identifier, or empty string  |
+| `systemId` | `string` | System identifier, or empty string  |
+
+## MLElementCloseTag
+
+**Source:** `src/ml-dom/node/element-close-tag.ts`
+
+Close tag paired with its corresponding open tag element. Extends `MLNode`. Close tags are **not** part of the document `nodeList`; they exist only as satellites of their paired `MLElement`.
+
+MLElementCloseTag exists for two purposes:
+
+1. **Syntax location tracking**: It records the source position (`startLine`, `startCol`, `raw`, etc.) of the close tag. Rules like `case-sensitive-tag-name` use this to report violations at the exact close tag location rather than the open tag.
+2. **Presence/absence detection**: `MLElement.closeTag` is `null` when no close tag exists. Rules like `end-tag` check `el.closeTag != null` to detect missing close tags (omissions or errors) on non-void elements.
+
+### Properties
+
+| Property   | Type        | Description                                           |
+| ---------- | ----------- | ----------------------------------------------------- |
+| `pair`     | `MLElement` | The corresponding opening element                     |
+| `rawName`  | `string`    | Tag name as written in source (from AST `nodeName`)   |
+| `nodeName` | `string`    | Tag name derived from the paired element's `nodeName` |
+
+### Usage in Rules
+
+```typescript
+// end-tag rule: detect missing close tags
+if (el.closeTag != null) {
+  return; // close tag exists → OK
+}
+report({ scope: el, message: t('Missing {0}', t('the {0}', 'end tag')) });
+
+// case-sensitive-tag-name rule: report at the close tag's source position
+const closeTag = el.closeTag;
+if (closeTag && deny.test(closeTag.raw)) {
+  report({
+    scope: {
+      rule: el.rule,
+      startLine: closeTag.startLine,
+      startCol: closeTag.startCol,
+      raw: closeTag.raw,
+    },
+    message,
+  });
+}
+```
+
+### `toString(fixed?)`
+
+When `fixed=true`:
+
+- If the element is a virtual element (starts with `#`) or is omitted → returns `raw`
+- Otherwise: reconstructs `tagOpenChar` + `/` + tag name + `tagCloseChar` using the pair's delimiters. The tag name is determined as: if `pair.fixedNodeName === pair.rawName` (no fix applied), use `this.rawName`; otherwise use `pair.fixedNodeName`
+
+## MLDocumentFragment
+
+**Source:** `src/ml-dom/node/document-fragment.ts`
+
+Fragment root node for JSX fragments (`<>...</>`) and similar constructs. Extends `MLParentNode` and implements DOM `DocumentFragment`.
+
+- `nodeName`: `'#document-fragment'`
+- `nodeType`: `11` (`DOCUMENT_FRAGMENT_NODE`)
+- `textContent`: Concatenation of all child nodes' text content

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

@@ -0,0 +1,102 @@
+# MLDOM 概要
+
+## 概要
+
+MLDOM は DOM Standard に準拠した抽象化レイヤーで、`@markuplint/ml-ast` の AST ノードを DOM インターフェース実装クラスにラップします。各 MLDOM クラスは対応する DOM API（`Node`、`Element`、`Document` など）を提供しつつ、ルール格納、トークンレベルのソース追跡、アクセシブル名の計算など markuplint 固有の機能で拡張しています。
+
+すべての MLDOM クラスは2つの型パラメータを持つジェネリクスです：
+
+- `T extends RuleConfigValue` -- ルール設定値の型
+- `O extends PlainData` -- ルールオプションの型
+
+これらのジェネリクスは **`createRule` のためだけに存在**します。ノードツリー全体に伝播することで、サードパーティのルール作成者が `verify()` / `fix()` コールバック内で `node.rule` に型安全にアクセスできるようにしています：
+
+```typescript
+// サードパーティルール -- T = 'always' | 'never', O = { allow: string[] }
+export default createRule<'always' | 'never', { allow: string[] }>({
+  defaultValue: 'always',
+  defaultOptions: { allow: [] },
+  async verify({ document, report, t }) {
+    await document.walkOn('Element', el => {
+      // el.rule の型は RuleInfo<'always' | 'never', { allow: string[] }>
+      const { value, options } = el.rule;
+      //      ^'always'|'never'  ^{ allow: string[] }
+    });
+  },
+});
+```
+
+型の伝播経路: `createRule<T, O>` → `RuleSeed<T, O>` → `MLRuleContext<T, O>` → `MLDocument<T, O>` → `walkOn` ウォーカー → `MLElement<T, O>` → `el.rule: RuleInfo<T, O>`
+
+#### ランタイムの実態: 意図的に dirty な実装
+
+ジェネリクスはすべての MLDOM クラスに存在しますが、**ランタイム実装は型安全性を完全にバイパス**しています。これは意図的で実用的な設計上の選択です：
+
+1. **`node.rules` は型なし**: `Record<string, AnyRule>` として宣言（`node.ts` 190行目）
+2. **`RuleMapper` は `<any, any>` を使用**: マッパーは `MLNode<any, any>` を受け取り、型制約なしでルールを代入（`rule-mapper.ts` 47行目: `node.rules[ruleName] = rule.rule`）
+3. **型安全性はキャストで回復**: `node.rule` ゲッターが格納されたルールを `as Rule<T, O>` でキャストし、型付きの `RuleInfo<T, O>` を生成（`node.ts` 514行目: `settingRule as Rule<T, O>`）
+
+```
+コンパイル時:  MLNode<T, O>  →  node.rule: RuleInfo<T, O>  ← ルール作成者にとって型安全
+                   ↕
+ランタイム:    node.rules = Record<string, AnyRule>  ← 型なしストレージ
+               RuleMapper は <any, any> でルールを代入  ← ジェネリクスを無視
+               node.rule ゲッターが `as Rule<T, O>` でキャスト  ← 型を回復
+```
+
+初めてコードベースを見る開発者は、すべての MLDOM クラスに `<T, O>` が存在するのにランタイムで実際に制約されている箇所が見つからず困惑するかもしれません。答えは：ランタイムでは制約されていません。ジェネリクスは `createRule` を使用するサードパーティのルール作成者の DX のためだけに存在する、コンパイル時のみのメカニズムです。
+
+### UnexpectedCallError
+
+MLDOM クラスは TypeScript 組み込みの DOM 型インターフェース（例: `MLNode implements Node`、`MLElement implements Element`）を実装しています。この `implements` 宣言は**メンテナンス戦略**です。DOM インターフェースへの準拠を宣言することで、TypeScript の型チェッカーが MLDOM クラスを DOM API サーフェスと同期させ続けることを保証します。組み込み DOM 型定義が更新された場合（例: `Element` に新しいプロパティが追加された場合）、コンパイラがエラーを報告し、気づかないうちにギャップが生じることを防ぎます。
+
+静的解析のコンテキストでは意味を持たない DOM メソッド（markuplint のルールやカスタムルールで使用される可能性が低いもの）は、呼び出されると `UnexpectedCallError` をスローします。これにはミューテーションメソッド（`appendChild`、`removeChild`）、イベントメソッド（`addEventListener`、`dispatchEvent`）、レイアウト依存プロパティ（`clientHeight`、`offsetWidth`）が含まれます。
+
+## クラス階層
+
+```
+MLToken<A extends MLASTToken>
+  └── MLNode<T, O, A extends MLASTNode>  (abstract, implements Node)
+        ├── MLAttr<T, O>  (implements Attr)
+        ├── MLCharacterData<T, O, A>  (abstract, implements CharacterData)
+        │     ├── MLText<T, O>  (implements Text)
+        │     └── MLComment<T, O>  (implements Comment)
+        ├── MLDocumentType<T, O>  (implements DocumentType)
+        ├── MLBlock<T, O>
+        ├── MLElementCloseTag<T, O>
+        └── MLParentNode<T, O, A>  (abstract, implements ParentNode)
+              ├── MLElement<T, O>  (implements Element, HTMLElement)
+              ├── MLDocumentFragment<T, O>  (implements DocumentFragment)
+              └── MLDocument<T, O>  (implements Document)
+```
+
+## MLToken
+
+**ソース:** `src/ml-dom/token/token.ts`
+
+基底トークンクラスで、`MLASTToken` を位置情報でラップし、元の文字列（raw）と修正済み（fixed）の文字列表現を提供します。これはすべての MLDOM ノードの基盤です。
+
+### プロパティ
+
+| プロパティ    | 型       | 説明                                                                          |
+| ------------- | -------- | ----------------------------------------------------------------------------- |
+| `uuid`        | `string` | このトークンの一意な識別子                                                    |
+| `raw`         | `string` | 元のソーステキスト（不変）                                                    |
+| `fixed`       | `string` | 修正済みのソーステキスト。初期値は `raw` と同じ。`fix()` メソッドで更新される |
+| `startLine`   | `number` | 1始まりの開始行番号                                                           |
+| `endLine`     | `number` | 1始まりの終了行番号                                                           |
+| `startCol`    | `number` | 1始まりの開始列番号                                                           |
+| `endCol`      | `number` | 1始まりの終了列番号                                                           |
+| `startOffset` | `number` | 0始まりの開始文字オフセット                                                   |
+| `endOffset`   | `number` | 0始まりの終了文字オフセット                                                   |
+
+### メソッド
+
+| メソッド   | シグネチャ                          | 説明                                                        |
+| ---------- | ----------------------------------- | ----------------------------------------------------------- |
+| `fix`      | `fix(raw: string): void`            | リント自動修正用に `fixed` を修正内容で更新する             |
+| `toString` | `toString(fixed?: boolean): string` | `true` の場合 `fixed` の内容を、そうでなければ `raw` を返す |
+
+### 座標系
+
+オフセットは0始まり（0からカウント）、行と列は1始まり（1からカウント）です。これはほとんどのテキストエディタやエラーレポーターで使用される慣例に一致しています。

package/docs/ml-dom/overview.md

@@ -0,0 +1,102 @@
+# MLDOM Overview
+
+## Overview
+
+MLDOM is a DOM Standard-conforming abstraction layer that wraps `@markuplint/ml-ast` AST nodes into DOM interface implementation classes. Each MLDOM class provides the corresponding DOM API (`Node`, `Element`, `Document`, etc.) while extending it with markuplint-specific features like rule storage, token-level source tracking, and accessible name computation.
+
+All MLDOM classes are generic over two type parameters:
+
+- `T extends RuleConfigValue` -- The rule configuration value type
+- `O extends PlainData` -- The rule options type
+
+These generics exist **solely for `createRule`**. They propagate through the entire node tree so that 3rd party rule authors get type-safe access to `node.rule` within `verify()` and `fix()` callbacks:
+
+```typescript
+// 3rd party rule -- T = 'always' | 'never', O = { allow: string[] }
+export default createRule<'always' | 'never', { allow: string[] }>({
+  defaultValue: 'always',
+  defaultOptions: { allow: [] },
+  async verify({ document, report, t }) {
+    await document.walkOn('Element', el => {
+      // el.rule is typed as RuleInfo<'always' | 'never', { allow: string[] }>
+      const { value, options } = el.rule;
+      //      ^'always'|'never'  ^{ allow: string[] }
+    });
+  },
+});
+```
+
+The type flow is: `createRule<T, O>` → `RuleSeed<T, O>` → `MLRuleContext<T, O>` → `MLDocument<T, O>` → `walkOn` walker → `MLElement<T, O>` → `el.rule: RuleInfo<T, O>`.
+
+#### Runtime Reality: Intentionally Dirty Implementation
+
+Despite the generics appearing on every MLDOM class, the **runtime implementation bypasses type safety entirely**. This is a deliberate, pragmatic design choice:
+
+1. **`node.rules` is untyped**: declared as `Record<string, AnyRule>` (`node.ts` line 190)
+2. **`RuleMapper` uses `<any, any>`**: the mapper accepts `MLNode<any, any>` and assigns rules without type constraints (`rule-mapper.ts` line 47: `node.rules[ruleName] = rule.rule`)
+3. **Type safety is recovered via cast**: the `node.rule` getter casts the stored rule with `as Rule<T, O>` to produce a typed `RuleInfo<T, O>` (`node.ts` line 514: `settingRule as Rule<T, O>`)
+
+```
+Compile time:  MLNode<T, O>  →  node.rule: RuleInfo<T, O>  ← type-safe for rule authors
+                   ↕
+Runtime:       node.rules = Record<string, AnyRule>  ← untyped storage
+               RuleMapper assigns rules as <any, any>  ← ignores generics
+               node.rule getter casts `as Rule<T, O>`  ← recovers type
+```
+
+This approach may confuse first-time contributors who see `<T, O>` on every MLDOM class but cannot find where these types are actually constrained at runtime. The answer is: they are not. The generics are a compile-time-only mechanism that exists entirely for the DX of 3rd party rule authors using `createRule`.
+
+### UnexpectedCallError
+
+MLDOM classes implement TypeScript's built-in DOM type interfaces (e.g., `MLNode implements Node`, `MLElement implements Element`). This `implements` declaration is a **maintenance strategy**: by declaring conformance to the DOM interfaces, TypeScript's type checker ensures that MLDOM classes keep up with the DOM API surface. When the built-in DOM type definitions are updated (e.g., new properties added to `Element`), the compiler reports errors, preventing unnoticed gaps.
+
+DOM methods that are not meaningful in a static analysis context (i.e., unlikely to be used by markuplint rules or custom rules) throw `UnexpectedCallError` when called. This includes mutation methods (`appendChild`, `removeChild`), event methods (`addEventListener`, `dispatchEvent`), and layout-dependent properties (`clientHeight`, `offsetWidth`).
+
+## Class Hierarchy
+
+```
+MLToken<A extends MLASTToken>
+  └── MLNode<T, O, A extends MLASTNode>  (abstract, implements Node)
+        ├── MLAttr<T, O>  (implements Attr)
+        ├── MLCharacterData<T, O, A>  (abstract, implements CharacterData)
+        │     ├── MLText<T, O>  (implements Text)
+        │     └── MLComment<T, O>  (implements Comment)
+        ├── MLDocumentType<T, O>  (implements DocumentType)
+        ├── MLBlock<T, O>
+        ├── MLElementCloseTag<T, O>
+        └── MLParentNode<T, O, A>  (abstract, implements ParentNode)
+              ├── MLElement<T, O>  (implements Element, HTMLElement)
+              ├── MLDocumentFragment<T, O>  (implements DocumentFragment)
+              └── MLDocument<T, O>  (implements Document)
+```
+
+## MLToken
+
+**Source:** `src/ml-dom/token/token.ts`
+
+Base token class that wraps an `MLASTToken` with positional information and provides both raw and fixed (corrected) string representations. This is the foundation for all MLDOM nodes.
+
+### Properties
+
+| Property      | Type     | Description                                                                       |
+| ------------- | -------- | --------------------------------------------------------------------------------- |
+| `uuid`        | `string` | Unique identifier for this token                                                  |
+| `raw`         | `string` | Original source text (immutable)                                                  |
+| `fixed`       | `string` | Fixed (modified) source text; initially equals `raw`. Updated via `fix()` method. |
+| `startLine`   | `number` | One-based start line number                                                       |
+| `endLine`     | `number` | One-based end line number                                                         |
+| `startCol`    | `number` | One-based start column number                                                     |
+| `endCol`      | `number` | One-based end column number                                                       |
+| `startOffset` | `number` | Zero-based start character offset                                                 |
+| `endOffset`   | `number` | Zero-based end character offset                                                   |
+
+### Methods
+
+| Method     | Signature                           | Description                                                  |
+| ---------- | ----------------------------------- | ------------------------------------------------------------ |
+| `fix`      | `fix(raw: string): void`            | Updates `fixed` with corrected content for lint auto-fix     |
+| `toString` | `toString(fixed?: boolean): string` | Returns `fixed` content when `true`, otherwise returns `raw` |
+
+### Coordinate System
+
+Offsets are zero-based (counting from 0), while lines and columns are one-based (counting from 1). This matches the conventions used by most text editors and error reporters.