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

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

@@ -0,0 +1,272 @@
+# MLBlock — プリプロセッサブロックノード
+
+**ソース:** `src/ml-dom/node/block.ts`
+
+## 概要
+
+`MLBlock` はテンプレートエンジンの条件分岐、ループ、その他のプリプロセッサディレクティブを表現する markuplint 固有の DOM ノードです。DOM Standard に対応するものはなく、`nodeType` はカスタム値 `101`（`MARKUPLINT_PREPROCESSOR_BLOCK`）です。
+
+Svelte、Nunjucks、EJS、Pug などのテンプレートエンジンは、HTML コンテンツを非 HTML ブロック（例: `{#if}`、`{#each}`、`{% if %}`）でラップする構文を生成します。パーサーはこれらを `MLASTPreprocessorSpecificBlock` AST ノードに変換し、`MLBlock` がそれをラップします。
+
+MLBlock はテンプレート構文と HTML コンテンツモデル検証の橋渡しをします。条件分岐、イテレーション、その他のフロー制御が、レンダリングされた HTML にどの子ノードが実際に存在するかに影響することを、markuplint が推論できるようにします。
+
+- `nodeName`: `'#ml-block'`
+- `nodeType`: `101`（`MARKUPLINT_PREPROCESSOR_BLOCK`）
+
+## プロパティ
+
+| プロパティ      | 型                           | 説明                                                                                         |
+| --------------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
+| `blockBehavior` | `MLASTBlockBehavior \| null` | ブロックの動作を示す構文の種類（下表参照）、非条件ブロックの場合は `null`                    |
+| `isTransparent` | `boolean`                    | ツリー走査で透過的かどうか。現在は常に `true`（ソースの TODO を参照）                        |
+| `isFragment`    | `boolean`                    | ブロックが透過フラグメントとして機能するか（MLNode から継承、`astNode.isFragment` から設定） |
+
+## blockBehavior の型
+
+`blockBehavior` は、ブロックが条件分岐子ノードパターン生成にどのように参加するかを決定します（後述の[条件分岐子ノード](#条件分岐子ノード)を参照）。`type` プロパティを持つオブジェクト、または非条件ブロックの場合は `null` です。
+
+### 条件グループ
+
+認識された `blockBehavior.type` を持つブロックは条件グループを形成します。各グループは「開始」型で始まり、「分岐」型を含む場合があります：
+
+| グループ   | 開始            | 分岐                            | 終了               |
+| ---------- | --------------- | ------------------------------- | ------------------ |
+| **if**     | `'if'`          | `'if:elseif'`、`'if:else'`      | `'end'` または暗黙 |
+| **each**   | `'each'`        | `'each:empty'`                  | `'end'` または暗黙 |
+| **switch** | `'switch:case'` | `'switch:default'`              | `'end'` または暗黙 |
+| **await**  | `'await'`       | `'await:then'`、`'await:catch'` | `'end'` または暗黙 |
+
+### すべての値
+
+| `blockBehavior.type` | 説明                                             | 役割                                                                              |
+| -------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `'if'`               | 条件ブロックの開始                               | 新しい条件グループを開始                                                          |
+| `'if:elseif'`        | 代替条件分岐                                     | 新しい条件グループを開始（パターン生成では `'if'` と同じ扱い）                    |
+| `'if:else'`          | デフォルト（else）分岐                           | 現在のグループ内の分岐                                                            |
+| `'switch:case'`      | switch の case 分岐                              | 新しい条件グループを開始                                                          |
+| `'switch:default'`   | switch のデフォルト分岐                          | 現在のグループ内の分岐                                                            |
+| `'each'`             | イテレーション（ループ）ブロックの開始           | 新しい条件グループを開始                                                          |
+| `'each:empty'`       | イテレーションブロックの空状態                   | 現在のグループ内の分岐                                                            |
+| `'await'`            | 非同期ブロック（pending 状態）                   | 現在のグループ内の分岐                                                            |
+| `'await:then'`       | 非同期ブロックの resolved 状態                   | 現在のグループ内の分岐                                                            |
+| `'await:catch'`      | 非同期ブロックの rejected 状態                   | 現在のグループ内の分岐                                                            |
+| `'end'`              | ブロック終了マーカー                             | 無視される（switch の `default` でフィルタされる）                                |
+| `null`               | ブロック動作なし（例: `{value}` のような式出力） | 条件グループではない。ミュータブルな子として扱われる（`blockBehavior` が `null`） |
+
+## 透過性
+
+`MLBlock` は常に透過的です（`isTransparent = true`）。透過性は MLBlock を DOM ツリー走査から見えなくしつつ、親子セマンティクスを保持するコア設計原則です。
+
+### `parentNode` への影響
+
+ノードの構文上の親が透過的な MLBlock の場合、`parentNode` はブロックをスキップし、ブロック自身の `parentNode` を再帰的に返します。つまり、テンプレート構文内のノードは、囲んでいる HTML 要素（ブロックではなく）を親として報告します：
+
+```
+ソース:                          parentNode の戻り値:
+<ul>                             ─┐
+  {#if cond}     (MLBlock)        │  ← スキップされる
+    <li>A</li>                    │  → <ul>（MLBlock ではない）
+  {/if}                           │
+</ul>                            ─┘
+```
+
+`MLNode.parentNode` の該当コード：
+
+```typescript
+if (parentNode.is(parentNode.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+  if (parentNode.isTransparent) {
+    return parentNode.parentNode; // 上方に再帰
+  }
+  return null; // 非透過ブロック: 孤立
+}
+```
+
+ブロックが非透過（`isTransparent = false`）の場合、子ノードは `parentNode === null`（孤立）を報告します。現在 `isTransparent` は常に `true` なので、この状況は発生しません。
+
+### `childNodes` への影響
+
+ブロックの子ノードは、`getPureChildNodes()` と `childNodes` の展開パイプラインを通じて親の `childNodes` にインライン化されます：
+
+1. **`getPureChildNodes()`**: `MARKUPLINT_PREPROCESSOR_BLOCK` に対して `ELEMENT_NODE` や `DOCUMENT_FRAGMENT_NODE` と同様に動作します — `astNode.childNodes` を読み取り、`endtag` と `invalid` ノードをフィルタし、MLDOM ノードにマッピングします
+2. **`childNodes`**（親側）: `getPureChildNodes()` を呼び出し、`isFragment === true` の子については、その `childNodes` を再帰的にインライン化します
+
+```
+ソース:                          <ul>.childNodes の戻り値:
+<ul>                             ─┐
+  {#if cond}                      │  ← MLBlock は childNodes に含まれない
+    <li>A</li>                    │  → [<li>A</li>, <li>B</li>]
+    <li>B</li>                    │
+  {/if}                           │
+</ul>                            ─┘
+```
+
+これにより、親子関係を検証するルール（`permitted-contents` など）が、テンプレートエンジンのラッパーではなく、実効的な HTML の子ノードを確認できます。
+
+### `syntacticalParentNode` と `parentNode` の比較
+
+| プロパティ              | 動作                              | 用途                                    |
+| ----------------------- | --------------------------------- | --------------------------------------- |
+| `syntacticalParentNode` | MLBlock を含む直接の AST 親を返す | パースされた生の構造の理解              |
+| `parentNode`            | 透過的な MLBlock ノードをスキップ | リントルール用の DOM ライクなツリー走査 |
+
+## 条件分岐子ノード
+
+`MLNode` の `conditionalChildNodes()` メソッドは、MLBlock の `blockBehavior?.type` を使用して、レンダリングされた出力に現れうるすべての子ノードパターンを列挙します。これはテンプレート分岐がある場合のコンテンツモデル検証に不可欠です。
+
+### アルゴリズム
+
+1. 現在のノードの `childNodes` を走査する
+2. 認識された `blockBehavior?.type` を持つ各 MLBlock 子に対して：
+   - `mode` を判定（`'if'` または `'switch'`）。`'each'` ブロックは新しいモードを開始しない
+   - ブロックに対して再帰的に `conditionalChildNodes()` を呼び出してサブパターンを取得
+   - すべての分岐の代替を `subBranches` 配列に収集
+3. 条件グループ終了後に非ブロックの子が出現したとき：
+   - mode が `'if'` または `'switch'` の場合：`null` をセンチネルとしてプッシュ（どの分岐もレンダリングされない「空」ケースを表現）
+   - 現在のグループを閉じ、`subBranches` を `branches` にプッシュ
+4. 空白のみのテキストノードはスキップ
+5. 非ブロックの子は直接 `branches` に追加
+6. `branches` を `branchesToPatterns()` に渡してデカルト積を計算
+
+### `branchesToPatterns()`
+
+このユーティリティ関数（`@markuplint/shared` から）は分岐の代替のデカルト積を計算します：
+
+- 通常の要素（非配列）はすべてのパターンに出現する
+- 配列の要素は代替を表す — 各要素が別のパターンを生成する
+- `null` 値はフィルタされる（空の分岐を表現）
+
+```
+入力:  [A, [B, C], D]
+出力: [[A, B, D], [A, C, D]]
+
+入力:  [A, [B, null], C]
+出力: [[A, B, C], [A, C]]    ← null はフィルタ = 「分岐がレンダリングされない」
+```
+
+### 例
+
+以下の Svelte テンプレートの場合：
+
+```svelte
+<ul>
+  {#if cond}
+    <li>A</li>
+  {:else}
+    <li>B</li>
+  {/if}
+  <li>C</li>
+</ul>
+```
+
+AST 構造：
+
+```
+MLElement <ul>
+  ├── MLBlock (blockBehavior.type: 'if')
+  │     └── MLElement <li>A</li>
+  ├── MLBlock (blockBehavior.type: 'if:else')
+  │     └── MLElement <li>B</li>
+  └── MLElement <li>C</li>
+```
+
+`<ul>` に対する `conditionalChildNodes()` の結果：
+
+```
+branches = [[<li>A</li>, <li>B</li>, null], <li>C</li>]
+                  ↓ branchesToPatterns()
+パターン 1: [<li>A</li>, <li>C</li>]   ← if 分岐
+パターン 2: [<li>B</li>, <li>C</li>]   ← else 分岐
+パターン 3: [<li>C</li>]               ← 分岐なし（null はフィルタ）
+```
+
+`null` センチネルは、条件グループ（if/else）が何もレンダリングしない可能性があるため追加されます（例: パーサーが分岐が常に実行されるかどうかを判定できない場合）。`permitted-contents` ルールはすべてのパターンを検証し、すべてのケースでコンテンツモデルが満たされることを保証します。
+
+### ネストされた条件分岐
+
+アルゴリズムは再帰的な `conditionalChildNodes()` 呼び出しによって自然にネストを処理します：
+
+```svelte
+<div>
+  {#if a}
+    {#if b}
+      <span>X</span>
+    {:else}
+      <span>Y</span>
+    {/if}
+  {:else}
+    <span>Z</span>
+  {/if}
+</div>
+```
+
+内側の `{#if b}` ブロックは再帰的にパターン `[<span>X</span>]`、`[<span>Y</span>]` を生成し、外側のブロックの `subBranches` に展開されます。
+
+## `hasMutableChildren()` との相互作用
+
+`MLElement.hasMutableChildren()` は `blockBehavior` を使用して MLBlock を2つのカテゴリに区別します：
+
+- **`blockBehavior` を持つブロック**（例: type `'if'`、`'each'`、`'switch:case'`）：スキップ（`continue`）— `conditionalChildNodes()` がすべての可能なパターンを列挙して処理する
+- **`blockBehavior` を持たないブロック**（`null`）：即座に `true` を返す — `{value}` のような式出力やその他の非条件テンプレート構文を表し、内容が静的に決定できない
+
+```typescript
+for (const child of this.getPureChildNodes()) {
+  if (child.is(child.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+    if (child.blockBehavior) {
+      continue; // 条件セマンティクスあり → 別の場所で処理
+    }
+    return true; // 条件セマンティクスなし → 本当にミュータブル
+  }
+  // ...
+}
+```
+
+この区別は重要です：`{#if}` ブロックは決定論的な分岐パターンを生成しますが、`{variable}` ブロックは任意のコンテンツを生成する可能性があります。`permitted-contents` のようなルールは前者を検証できますが、後者はスキップしなければなりません。
+
+## リンティングパイプラインでの役割
+
+MLBlock はリンティングパイプラインの複数のレベルで参加します：
+
+### 1. パースフェーズ
+
+テンプレートエンジンパーサー（Svelte、Nunjucks、EJS、Pug など）が `MLASTPreprocessorSpecificBlock` AST ノードを生成します。各パーサーは以下を担当します：
+
+- `blockBehavior` の適切な設定（例: Svelte `{#if}` → `{ type: 'if' }`、`{#each}` → `{ type: 'each' }`）
+- ブロック内への子 AST ノードのネスト
+- フラグメントコンテナとして機能すべきブロックの `isFragment` 設定
+
+### 2. MLDOM 構築
+
+`createNode()` は `'psblock'` AST タイプを `MLBlock` にマッピングします。ブロックは要素、テキストノード、コメントと並んでドキュメントの `nodeList` に含まれます。
+
+### 3. ツリー走査
+
+透過性により、MLBlock は標準的な DOM 走査から見えなくなります：
+
+- `parentNode` は透過ブロックをスキップする
+- `childNodes` はブロックの子を親にインライン化する
+- `walkOn('Element', ...)` は MLBlock ノードに遭遇しない（要素、テキスト、コメント、属性、閉じタグのみを走査）
+
+### 4. コンテンツモデル検証
+
+`permitted-contents` ルールは `conditionalChildNodes()` を使用してすべての可能なコンテンツパターンを検証します：
+
+```typescript
+const childNodesPatterns = options.evaluateConditionalChildNodes
+  ? el.conditionalChildNodes().map(childNodes => [...childNodes])
+  : [[...el.childNodes].filter(/* ... */)];
+```
+
+各パターンは HTML コンテンツモデル仕様に対して独立に検証されます。
+
+## メソッド
+
+MLBlock は DOM API 互換性のために `ChildNode` インターフェースメソッドを実装しています：
+
+| メソッド      | シグネチャ                                       | 説明                           |
+| ------------- | ------------------------------------------------ | ------------------------------ |
+| `after`       | `after(...nodes: (string \| MLElement)[])`       | このブロックの後にノードを挿入 |
+| `before`      | `before(...nodes: (string \| MLElement)[])`      | このブロックの前にノードを挿入 |
+| `remove`      | `remove()`                                       | 親からこのブロックを削除       |
+| `replaceWith` | `replaceWith(...nodes: (string \| MLElement)[])` | このブロックを他のノードで置換 |
+
+これらのメソッドは `src/ml-dom/manipulations/child-node-methods.ts` の共有実装に委譲します。

package/docs/ml-dom/block.md

@@ -0,0 +1,272 @@
+# MLBlock — Preprocessor Block Node
+
+**Source:** `src/ml-dom/node/block.ts`
+
+## Overview
+
+`MLBlock` is a markuplint-specific DOM node that represents template engine constructs such as conditionals, loops, and other preprocessor directives. It has no DOM Standard equivalent; its `nodeType` is a custom value `101` (`MARKUPLINT_PREPROCESSOR_BLOCK`).
+
+Template engines like Svelte, Nunjucks, EJS, Pug, and others produce constructs (e.g., `{#if}`, `{#each}`, `{% if %}`) that wrap HTML content in non-HTML blocks. The parser translates these into `MLASTPreprocessorSpecificBlock` AST nodes, which `MLBlock` wraps.
+
+MLBlock serves as the bridge between template syntax and HTML content model validation. It enables markuplint to reason about conditional branches, iteration, and other control flow that affects which child nodes are actually present in the rendered HTML.
+
+- `nodeName`: `'#ml-block'`
+- `nodeType`: `101` (`MARKUPLINT_PREPROCESSOR_BLOCK`)
+
+## Properties
+
+| Property        | Type                         | Description                                                                                                 |
+| --------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `blockBehavior` | `MLASTBlockBehavior \| null` | The block behavior describing the type of construct (see table below), or `null` for non-conditional blocks |
+| `isTransparent` | `boolean`                    | Whether the block is transparent in tree traversal; currently always `true` (see source TODO)               |
+| `isFragment`    | `boolean`                    | Whether this block acts as a transparent fragment (inherited from MLNode, set from `astNode.isFragment`)    |
+
+## blockBehavior Types
+
+`blockBehavior` determines how the block participates in conditional child node pattern generation (see [Conditional Child Nodes](#conditional-child-nodes) below). It is an object with a `type` property, or `null` for non-conditional blocks.
+
+### Conditional Groups
+
+Blocks with a recognized `blockBehavior.type` form conditional groups. Each group starts with a "start" type and may include "branch" types:
+
+| Group      | Start           | Branches                        | End                 |
+| ---------- | --------------- | ------------------------------- | ------------------- |
+| **if**     | `'if'`          | `'if:elseif'`, `'if:else'`      | `'end'` or implicit |
+| **each**   | `'each'`        | `'each:empty'`                  | `'end'` or implicit |
+| **switch** | `'switch:case'` | `'switch:default'`              | `'end'` or implicit |
+| **await**  | `'await'`       | `'await:then'`, `'await:catch'` | `'end'` or implicit |
+
+### All Values
+
+| `blockBehavior.type` | Description                                                | Role                                                                              |
+| -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `'if'`               | Start of conditional block                                 | Starts a new conditional group                                                    |
+| `'if:elseif'`        | Alternative conditional branch                             | Starts a new conditional group (treated the same as `'if'` in pattern generation) |
+| `'if:else'`          | Default (else) branch                                      | Branch within current group                                                       |
+| `'switch:case'`      | Switch case branch                                         | Starts a new conditional group                                                    |
+| `'switch:default'`   | Switch default branch                                      | Branch within current group                                                       |
+| `'each'`             | Start of iteration (loop) block                            | Continues in current mode (no new mode set); flattened into `childNodes`          |
+| `'each:empty'`       | Empty state for an iteration block                         | Branch within current group                                                       |
+| `'await'`            | Asynchronous block (pending state)                         | Branch within current group                                                       |
+| `'await:then'`       | Resolved state of async block                              | Branch within current group                                                       |
+| `'await:catch'`      | Rejected state of async block                              | Branch within current group                                                       |
+| `'end'`              | Closing block marker                                       | Ignored (filtered out by `default` in the switch)                                 |
+| `null`               | No block behavior (e.g., expression output like `{value}`) | Not a conditional group; treated as a mutable child (`blockBehavior` is `null`)   |
+
+## Transparency
+
+`MLBlock` is always transparent (`isTransparent = true`). Transparency is the core design principle that makes MLBlock invisible to DOM tree traversal while preserving parent-child semantics.
+
+### Effect on `parentNode`
+
+When a node's syntactical parent is a transparent MLBlock, `parentNode` skips the block and returns the block's own `parentNode` recursively. This means nodes inside template constructs report the enclosing HTML element (not the block) as their parent:
+
+```
+Source:                          parentNode returns:
+<ul>                             ─┐
+  {#if cond}     (MLBlock)        │  ← skipped
+    <li>A</li>                    │  → <ul> (not the MLBlock)
+  {/if}                           │
+</ul>                            ─┘
+```
+
+The relevant code in `MLNode.parentNode`:
+
+```typescript
+if (parentNode.is(parentNode.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+  if (parentNode.isTransparent) {
+    return parentNode.parentNode; // Recurse upward
+  }
+  return null; // Non-transparent block: orphan
+}
+```
+
+If a block were non-transparent (`isTransparent = false`), its children would report `parentNode === null` (orphaned). Currently this does not happen since `isTransparent` is always `true`.
+
+### Effect on `childNodes`
+
+The block's children are inlined into the parent's `childNodes` through the `getPureChildNodes()` and `childNodes` expansion pipeline:
+
+1. **`getPureChildNodes()`**: Works on `MARKUPLINT_PREPROCESSOR_BLOCK` the same way as on `ELEMENT_NODE` and `DOCUMENT_FRAGMENT_NODE` — it reads `astNode.childNodes`, filters out `endtag` and `invalid` nodes, and maps them to MLDOM nodes
+2. **`childNodes`** (on the parent): Calls `getPureChildNodes()`, then for any child with `isFragment === true`, inlines its `childNodes` recursively
+
+```
+Source:                          <ul>.childNodes returns:
+<ul>                             ─┐
+  {#if cond}                      │  ← MLBlock is not in childNodes
+    <li>A</li>                    │  → [<li>A</li>, <li>B</li>]
+    <li>B</li>                    │
+  {/if}                           │
+</ul>                            ─┘
+```
+
+This ensures that rules validating parent-child relationships (like `permitted-contents`) see the effective HTML children, not the template engine wrappers.
+
+### `syntacticalParentNode` vs `parentNode`
+
+| Property                | Behavior                                         | Use case                               |
+| ----------------------- | ------------------------------------------------ | -------------------------------------- |
+| `syntacticalParentNode` | Returns the direct AST parent, including MLBlock | Understanding the raw parsed structure |
+| `parentNode`            | Skips transparent MLBlock nodes                  | DOM-like tree traversal for lint rules |
+
+## Conditional Child Nodes
+
+The `conditionalChildNodes()` method on `MLNode` uses MLBlock's `blockBehavior?.type` to enumerate all possible child node patterns that could appear in the rendered output. This is critical for content model validation in the presence of template branching.
+
+### Algorithm
+
+1. Walk through `childNodes` of the current node
+2. For each MLBlock child with a recognized `blockBehavior?.type`:
+   - Determine the `mode` (`'if'` or `'switch'`); `'each'` blocks do not start a new mode
+   - Recursively call `conditionalChildNodes()` on the block to get its sub-patterns
+   - Collect all branch alternatives into a `subBranches` array
+3. When a non-block child is encountered after a conditional group ends:
+   - If the mode was `'if'` or `'switch'`: push `null` as a sentinel (representing the "empty" case where none of the branches render)
+   - Close the current group and push `subBranches` to `branches`
+4. Skip whitespace-only text nodes
+5. Non-block children are added directly to `branches`
+6. Pass `branches` to `branchesToPatterns()` to compute the Cartesian product
+
+### `branchesToPatterns()`
+
+This utility function (from `@markuplint/shared`) computes the Cartesian product of branch alternatives:
+
+- Regular items (non-array) appear in every pattern
+- Array items represent alternatives — each item produces a separate pattern
+- `null` values are filtered out (representing empty branches)
+
+```
+Input:  [A, [B, C], D]
+Output: [[A, B, D], [A, C, D]]
+
+Input:  [A, [B, null], C]
+Output: [[A, B, C], [A, C]]    ← null filtered out = "no branch rendered"
+```
+
+### Example
+
+Given the following Svelte template:
+
+```svelte
+<ul>
+  {#if cond}
+    <li>A</li>
+  {:else}
+    <li>B</li>
+  {/if}
+  <li>C</li>
+</ul>
+```
+
+The AST structure is:
+
+```
+MLElement <ul>
+  ├── MLBlock (blockBehavior.type: 'if')
+  │     └── MLElement <li>A</li>
+  ├── MLBlock (blockBehavior.type: 'if:else')
+  │     └── MLElement <li>B</li>
+  └── MLElement <li>C</li>
+```
+
+`conditionalChildNodes()` on `<ul>` produces:
+
+```
+branches = [[<li>A</li>, <li>B</li>, null], <li>C</li>]
+                  ↓ branchesToPatterns()
+Pattern 1: [<li>A</li>, <li>C</li>]   ← if branch taken
+Pattern 2: [<li>B</li>, <li>C</li>]   ← else branch taken
+Pattern 3: [<li>C</li>]               ← no branch (null filtered out)
+```
+
+The `null` sentinel is added because the conditional group (if/else) might not render anything at all (e.g., if the parser cannot determine whether a branch always executes). The `permitted-contents` rule validates all patterns to ensure the content model is satisfied in every case.
+
+### Nested Conditionals
+
+The algorithm handles nesting naturally through recursive `conditionalChildNodes()` calls:
+
+```svelte
+<div>
+  {#if a}
+    {#if b}
+      <span>X</span>
+    {:else}
+      <span>Y</span>
+    {/if}
+  {:else}
+    <span>Z</span>
+  {/if}
+</div>
+```
+
+The inner `{#if b}` block recursively generates its patterns `[<span>X</span>]`, `[<span>Y</span>]`, which are then flattened into the outer block's sub-branches.
+
+## Interaction with `hasMutableChildren()`
+
+`MLElement.hasMutableChildren()` uses `blockBehavior` to distinguish between two categories of MLBlock:
+
+- **Blocks WITH `blockBehavior`** (e.g., type `'if'`, `'switch:case'`): Skipped (`continue`) — these are handled by `conditionalChildNodes()` which enumerates all possible patterns. Note that `'each'` and `'end'` blocks are flattened into `childNodes` (their children are inlined), so they do not reach `hasMutableChildren()` as blocks
+- **Blocks WITHOUT `blockBehavior`** (`null`): Return `true` immediately — these represent expression outputs like `{value}` or other non-conditional template constructs whose content cannot be statically determined
+
+```typescript
+for (const child of this.getPureChildNodes()) {
+  if (child.is(child.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+    if (child.blockBehavior) {
+      continue; // Has conditional semantics → handled elsewhere
+    }
+    return true; // No conditional semantics → truly mutable
+  }
+  // ...
+}
+```
+
+This distinction is crucial: an `{#if}` block produces deterministic branch patterns, while a `{variable}` block can produce arbitrary content. Rules like `permitted-contents` can validate the former but must skip the latter.
+
+## Role in the Linting Pipeline
+
+MLBlock participates at multiple levels of the linting pipeline:
+
+### 1. Parsing Phase
+
+Template engine parsers (Svelte, Nunjucks, EJS, Pug, etc.) produce `MLASTPreprocessorSpecificBlock` AST nodes. Each parser is responsible for:
+
+- Setting `blockBehavior` appropriately (e.g., Svelte `{#if}` → `{ type: 'if' }`, `{#each}` → `{ type: 'each' }`)
+- Nesting child AST nodes within the block
+- Setting `isFragment` when the block should act as a fragment container
+
+### 2. MLDOM Construction
+
+`createNode()` maps `'psblock'` AST type to `MLBlock`. The block is included in the document's `nodeList` alongside elements, text nodes, and comments.
+
+### 3. Tree Traversal
+
+Transparency ensures MLBlock is invisible to standard DOM traversal:
+
+- `parentNode` skips transparent blocks
+- `childNodes` inlines block children into the parent
+- `walkOn('Element', ...)` does not encounter MLBlock nodes (only walks elements, text, comments, attrs, and close tags)
+
+### 4. Content Model Validation
+
+The `permitted-contents` rule uses `conditionalChildNodes()` to validate all possible content patterns:
+
+```typescript
+const childNodesPatterns = options.evaluateConditionalChildNodes
+  ? el.conditionalChildNodes().map(childNodes => [...childNodes])
+  : [[...el.childNodes].filter(/* ... */)];
+```
+
+Each pattern is independently validated against the HTML content model specification.
+
+## Methods
+
+MLBlock implements the `ChildNode` interface methods for DOM API compatibility:
+
+| Method        | Signature                                        | Description                         |
+| ------------- | ------------------------------------------------ | ----------------------------------- |
+| `after`       | `after(...nodes: (string \| MLElement)[])`       | Insert nodes after this block       |
+| `before`      | `before(...nodes: (string \| MLElement)[])`      | Insert nodes before this block      |
+| `remove`      | `remove()`                                       | Remove this block from its parent   |
+| `replaceWith` | `replaceWith(...nodes: (string \| MLElement)[])` | Replace this block with other nodes |
+
+These methods delegate to shared implementations in `src/ml-dom/manipulations/child-node-methods.ts`.