---
name: mermaid-lexer-safe-characters
description: "Mermaid C4Context / mindmap / flowchart の各 syntax で lexer-unsafe な character list. `#` comment / `∀ ∃ ⊥ ⊤` 量化子 / `—` em-dash / `→` arrow 等を showcase JSON / data file 内 Mermaid string で使うと Lexical error 発生."
metadata: 
  node_type: memory
  type: feedback
  originSessionId: f3963f63-e0c0-4ff9-8d81-c0fb14dcb6f8
---

# Mermaid lexer-safe character protocol

## Rule

Mermaid string を生成する全 file (showcase JSON / mindmap config / hand-written Mermaid in component) では **lexer-unsafe character を避け ASCII + minimal Unicode** に simplify すること.

**Why**: Mermaid parser (mermaid.js v10+) は厳格な lexer を持ち、 一部 character を syntax token として解釈する. 結果 `Lexical error on line X. Unrecognized text.` で render 不能になり Circuit Showcase 等の visual diagram が broken.

**How to apply**: Mermaid string を JSON 等に書く時、 以下 unsafe-character list を avoid + safe substitute へ replace.

## Observed incident (2026-05-19)

`data/circuit-showcase/theory-196-peace-showcase.json` の `c4ContainerMermaid` field:

```
C4Context
    title Theory #196 — system context (numbered callouts)   ← 失敗
    Person(observer, "① Observer", "any input source")
    System_Boundary(rei, "Rei kernel") {
        System(axiom, "② Peace Axiom #196", ...)
        System(rule, "③ enforce-rule", "∀ input → 1")
    }
```

Error: `Lexical error on line 2. Unrecognized text. ...xt    title Theory #196 — system contex ^`

★ 原因: `#` 文字が C4Context `title` 行で **comment 開始 token** として lexer に解釈され、 title parsing 中断.

★ 修正: `#` `∀` `→` `—` を ASCII safe に replace:
- `Theory #196 — system context` → `Theory 196 Peace Axiom system context`
- `② Peace Axiom #196` → `② Peace Axiom 196`
- `∀ input → 1` → `any input to 1`

★ 別 file (wave-4-maya showcase) は `#` 不含で同 incident なし → `#` が確定要因.

## Unsafe character list (確認済 + 推測)

### 確定 unsafe (実 incident で error 観測)

| character | location | Mermaid 解釈 | 安全 substitute |
|---|---|---|---|
| `#` | C4Context `title` 行, mindmap node text | comment 開始 token | 削除 / `No.` / `_` 等 |

### 推測 unsafe (lexer-strict syntax で risk あり, 事前回避推奨)

| character | risk | 安全 substitute |
|---|---|---|
| `∀ ∃ ⊥ ⊤` (量化子 / 論理記号) | flowchart edge label で operator token と衝突可能性 | `forall` / `exists` / `bot` / `top` |
| `→ ← ↔ ⇒ ⇐` (矢印) | flowchart `-->` `==>` syntax と視覚衝突 + lexer 別解釈 risk | `to` / `from` / `iff` / `implies` |
| `—` em-dash (U+2014) | `-` `--` `---` flowchart edge syntax と類似 → confuse risk | 全角空白 + ASCII `-` / `:` |
| `–` en-dash (U+2013) | em-dash 同 | 同上 |
| `"` "smart quotes" (U+201C/U+201D) | "ASCII double quote" との不一致で parser confuse | `"` ASCII double quote のみ |
| `'` smart apostrophe (U+2018/U+2019) | 同上 | `'` ASCII apostrophe のみ |

### 安全確認済 (使って OK)

| character | location | verified |
|---|---|---|
| `① ② ③ ④ ⑤ ⑥ ⑦ ⑧ ⑨ ⑩` (丸数字 U+2460+) | C4Context node label `"..."` 内 | ✅ Theory #196 / Wave 4 両方で動作 |
| `日本語 (CJK)` | node label `"..."` 内 | ✅ 各 showcase で動作 |
| `🟢 🟣 🔬 ⚛️ 🧬` (emoji) | label / title | ✅ 全 lens で動作 |
| `<br/>` | mindmap node text 内改行 | ✅ Theory #196 mindmap で動作 |

## Detection heuristic

新規 / 修正の Mermaid string (showcase JSON / data file / component hand-written) を加える時:

1. **必須**: `#` を含む場合は **C4Context `title` 行 / mindmap node text** で除外
2. **推奨**: `∀ ∃ ⊥ ⊤ — – → ← ↔` を含む場合は ASCII substitute を併用
3. **検証**: dev:build 後 site で render 確認 (component initialization が Lexical error で fail しないか)

## 適用 file 範囲

以下 file pattern で Mermaid string を含む可能性ありを認識:

- `data/circuit-showcase/*.json` (`c4ContainerMermaid`, `theoryMindmapMermaid`, `systemBlockMermaid` field)
- `data/theory-to-circuit/generated*/*.svg` (auto-generated SVG, 通常 safe)
- `src/renderer/components/**/*.tsx` 内 hand-written Mermaid string (rare)
- 将来 mindmap / flowchart 拡張時の new file

## Related memory

- [[dev-build-git-add-protocol]] — `git add -A` protocol (chunk hash rotation 対策) と同 sibling. Mermaid syntax error は chunk hash 問題と別 layer だが、 両方 user-facing site outage を生む.
- [[auto-managed-file-conflict-protocol]] — auto-managed file (generator script 経由) と本 protocol (手動 data file 編集) は scope が異なる. showcase JSON は手動編集なので本 protocol 適用対象.

## Anti-anti-pattern (Antipattern #5 balance)

「だから Mermaid 自体を避けるべき」 は誤った over-reaction. Mermaid は Rei stack の重要 visualization tool (Circuit Showcase / Diagram Tools Hub / Hardware Gallery で使用). **適切な lexer-safe character 選択 + 事前検証で十分対応可能**.

## Bug report fix history

| date | file | unsafe char | fixed to |
|---|---|---|---|
| 2026-05-19 STEP 1156-followup-47 commit `d7b25a02` | `data/circuit-showcase/theory-196-peace-showcase.json` (`c4ContainerMermaid`) | `#` (comment token) + `—` em-dash + `∀` + `→` | ASCII simplify |