@cardenelabs/cdl 0.6.1 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,401 @@
+# Changelog
+
+CDL (Chainome Diagram Language) の主要変更履歴。
+[Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) format + [Semantic Versioning](https://semver.org/lang/ja/) 準拠。
+
+## [Unreleased]
+
+予定 ... feedback を反映した patch / minor。
+
+## [0.9.0] - 2026-08-20
+
+`0.8.0` は tag を打った後 npm に公開されないまま 17 commit が載った。 同じ番号で公開すると
+tag の中身と公開物が食い違うため、番号を進めて 1 回だけ公開する。 `0.8.0` は npm に存在
+しない番号として残る。
+
+### Added
+
+- **箱が狭くて描かれない文字を書き手に伝えるようにした** (#497)
+
+  箱の幅に対して文字が長いと、描画側が黙って切り落とす。 書き手には図を見るまで伝わらない。
+  検査の層で幅と文字数を突き合わせ、収まらない文字を知らせる。
+
+- **工程表の横軸の範囲を書き手が宣言できるようにした** (#491)
+
+  従来は帯の位置から自動で決めていたため、帯が 1 本しかない図では目盛りが 1 本に縮んだ。
+  `ganttAxisMax` を足し、有限の正の数だけを採る。 壊れた値では自動に落とす。
+
+- **1 行で作る書き方の入口でも値を状態から取れるようにした** (#484)
+
+  図表の中身の型は `{名前}` を受ける形で宣言されているのに、組み立ての入口は数と語しか
+  受けなかった。 入口の型を中身に揃えた。
+
+  併せて工程の帯の位置を整える処理を入れた。 始まりが負なら 0 に寄せ、終わりが始まりより
+  手前なら始まりに揃える。 落とさず整えるのは、状態が動く途中で一瞬だけ逆転する形が
+  あるため (帯が消えるより潰れて見える方がよい)。
+
+### Fixed
+
+- **字幅の見積りを実描画と突き合わせ、足りない分を直した** (#494)
+- **小さい箱で絵に帯を譲り、補いの行を落とすようにした** (#493)
+- **値の入れ物を継承なしに揃えた** (#490)
+
+  `{constructor}` のような名前が「値がある」 と読まれ、prototype の中身が図に出ていた。
+
+- **下げた名札の座標を実際の描画に合わせた** (#489)
+- **1 lane の名札の異常で図の全 lane から縦線が消えないようにした** (#488)
+- **`{名前}` を読む欄と検査する欄を一致させた** (#487)
+
+  読み手と書ける側で名前の字種の定義がずれると、定義はできるのにどの箱からも読めない
+  名前ができる。 定義を 1 か所に集めた。
+
+- **連鎖の箱が書き手の題と副題を読むようにした** (#486)
+- **木と放射の箱に補足を描き、上の小ラベルを型から外した** (#485)
+- **工程表の目盛りの裸の数字を消し、象限図の枠を名前の幅に合わせた** (#482)
+- **下端の名札を位置でなく構造上の目印で判定するようにした** (#480)
+- **変更履歴を公開物に入れ、版から commit を辿れるようにした** (#477)
+- **実時間で測る検査を負荷に強くした** (#496)
+
+### Changed
+
+- **`no-op` になっていた `label-shift.ts` を消した** (#498)
+- **工程の帯の丸めを守る検査を足した** (#500)
+
+  丸めは #484 で入っていたが、外して全 5286 件を回しても 0 件しか落ちなかった。
+  幅の下限を `>= 0` から `> 0` に上げ、帯が消えた状態を「壊れていない」 と読まないようにした。
+
+## [0.8.0] - 2026-08-17
+
+### Added
+
+- **`flow()` preset で矢印を宣言できるようにした** (#474)
+
+  `flow()` は矢印を `step()` の並び順から自動生成するだけで、呼び手が矢印を宣言する口が
+  無かった。 そのため `a` から `c` へ直接繋ぎ `b` を経由しない図が作れなかった。
+
+  `FlowPreset.autoChain` (既定 `true`) と `FlowBuilder.edge()` を足した。
+
+  ```ts
+  flow({ id: "fl", topic: "T", autoChain: false })
+    .step({ id: "a", kind: "card", title: "A" })
+    .step({ id: "b", kind: "card", title: "B" })
+    .step({ id: "c", kind: "card", title: "C" })
+    .edge("a", "c", { label: "飛ばす" })
+    .build();
+  ```
+
+  `autoChain: false` にすると `step()` は node だけを置き、矢印は `edge()` で宣言する。
+  枠 / 配置 / 段は preset のまま保たれる。
+
+  `edge()` は preset の既定の `tone` / `style` を引き継ぎ、第 3 引数で個別に上書きできる。
+  `edge()` で作った矢印も `build()` が作る段の点灯対象に載る (載せないと動きの中で光らず、
+  自動生成分と見た目が揃わない)。
+
+  **`autoChain` の既定は `true` なので、既存の呼び出しは 1 行も変えずに同じ図になる**。
+  既定を `false` に変える変異で既存の検査 4 件が落ちることを確認済。
+
+## [0.7.0] - 2026-08-17
+
+### Changed
+
+- **木と放射の名前が状態を読むようになった** (#467)
+
+  `tree-hierarchy` と `mind-map` の名前 (木は `treeData[].title`、放射は `mindData.rootTitle` と
+  `branches[].title`) に `{名前}` を書くと、段ごとに解決するようになった。
+
+  この 2 種は「動かせる数を持たない」 という理由で解決層から外していた。 実際には
+  **この 2 種が持つのは数ではなく構造と名前** で、名前の側は動かせる。 利用側では
+  この 2 種だけが段を付けられず静止したまま残っていた。
+
+  **既存の図の見え方が変わる場合がある**。 木や放射の名前に `{...}` を含むテキストを
+  そのまま出していた図は、これまで書いた形のまま描かれていたが、今後は状態として解決を
+  試みる。 解決できない場合は書いた形のまま残り、`data-cdl-unresolved` が付く。
+  同じ性質の変更は図表 7 種で 0.6.0 に入っている。
+
+  解決できない名前は **書いたまま残す**。 数の欄は既定値 (0 等) に落とせるが、名前は
+  落とす先が無く、空にすると項目の存在まで図から消える。
+
+  解決しない範囲が 2 つある。 親子の繋がり (`parent`) は状態で繋ぎ替えると木の形そのものが
+  変わり、配置の計算と印の付け方が別問題になるため。 補足 (`subtitle`) はこの 2 種が
+  そもそも描いていないため = 解決だけ通すと、画面は何も変わらないのに解決できない時だけ
+  印が付く状態になる (描く方を足すかは #471)。
+
+## [0.6.1] - 2026-08-16
+
+### Added
+
+- **段ごとの実効値を出す 2 つを公開した** (#465)
+
+  `computeStateValues` (段と進みから状態の値を組み立てる) と `interpolate`
+  (`{名前}` を値で置き換える) を `index.ts` から輸出した。
+
+  公開しない間、 利用者はこの 2 つに `src/render/utils` の相対 path で届くしかなかった。
+  `exports` は `.` と `./react` しか開いていないので package 経由では引けず、 隣に cdl を
+  checkout している前提の import になる。 実際 dragon の見本の検査がその形で、
+  **隣に cdl が無いと型検査も test も通らない**状態を作っていた (cardene777/dragon#1166)。
+
+  自前で書き直す形も採れない。 `computeStateValues` は同じ段の中で `set` を順に当ててから
+  `tween` が上書きする順序を持ち、 組み直すと描画とずれる。 `interpolate` が受ける名前の
+  字種は `template-name.ts` が 1 箇所で決めており、 別に書くと「読めるが書けない」 名前が
+  できる。
+
+## [0.6.0] - 2026-08-16
+
+図表が状態を読んで動くようになった版。 併せて動かせない種別 (放射状の図) を 1 つ落とした。
+
+0.5.0 からの破壊的変更は **放射状の図の削除 1 件だけ**。 見た目の主題 (`CdlTheme`) と
+検査軸 2 件の削除は 0.5.0 で既に出ており、 記録が漏れていたものを本版で `[0.5.0]` 節へ
+書き足した。
+
+### Added
+
+- **図表 7 種の欄が `{signal}` を取れるようになった** (#451)
+
+  `chart-bar` / `chart-line` / `chart-pie` / `funnel-stages` / `gantt-timeline` の数の欄と、
+  `quadrant-matrix` / `journey-map` の語の欄で、 値の代わりに段の状態名を書けるようになった。
+  これまでは配列を受け取って一度描くだけで状態を読む経路が無く、 図表は永久に静止していた。
+
+  解決は `render/payload-binding.ts` に集約し、 各 kind は描画の直前に 1 回呼ぶ。
+  解決できない欄は **項目を落とさず** 既定値で描き、 `data-cdl-unresolved="true"` を付ける
+  (落とすと配列の長さが変わって図の形が別物になり、 どこが壊れたか読み取れなくなる)。
+
+  数を直接書いた図の描画は変わらない。 解決層が配列を組み直さないため、 描くものも
+  配列の同一性もそのまま。
+
+  `mind-map` / `tree-hierarchy` は動かせる数を持たないため配線していない。
+
+- **他の値から決まる値を毎 frame 解く `derived` を足した** (#453)
+
+  `CdlDiagram` に `derived` を持たせ、 段の値を出した後に参照順で解いて `stateValues` に
+  載せる。 毎 frame ここを通るので、 掛け算 / 割り算 / 比較 / `min` / `max` のような
+  端点 2 点では表せない関係も、 段の補間の途中で正しい値になる。
+
+  式は既存の `formula/` を使う。 波括弧で囲んだ名前 (`{waiting}`) は図の他の場所と同じ
+  書き方で参照できる。 許可済の `Math` 関数は接頭辞なしでも書ける (`min(a, b)`)。
+
+  **名前に使えるのは英数字と `_` だけ** (`template-name.ts` の `TEMPLATE_NAME_CHARS` が
+  `\w+`)。 日本語の名前は `derived` の `id` に置くと `invalid-id` の通知が返り、
+  `{待ち}` のように参照しても `parse-error` になる。
+
+  併せて 6 つを輸出した。 値を解く `applyDerivedValues` と、 段の値に重ねる
+  `withDerivedValues`、 型の `CdlDerivedValue` / `DerivedResult` / `DerivedNotice` /
+  `DerivedNoticeKind`。
+
+  **組み立て器からは宣言できない**。 `formulas` には `.formula(id, expression)` があるが、
+  `derived` に対応する method はまだ無く、 `CdlDiagram` を直接組む経路でしか渡せない。
+
+### Removed (破壊的変更)
+
+- **放射状の図 (`mindMapRadial` / `mind-radial`) を削除した** (#460)
+
+  中心から 45 度間隔で 8 方向へ枝を配る図で、 数を持たず構造だけを持つため段の値
+  (`{signal}`) を解けない「動かせない種別」 だった。 engine を「状態を読んで動く図」 に
+  寄せる方針 (#451 / #453) の下で、 動かせないまま保守を続ける根拠が無くなった。
+
+  | 消えたもの | 代わりに使うもの |
+  |---|---|
+  | `mindMapRadial()` builder (`index.ts` から輸出) | `mindMap()`。 **同じ絵にはならない** (下記) |
+  | `MindMapRadialPreset` / `MindMapRadialBuilder` / `MindMapRadialBranch` 型 | `MindMapPreset` / `MindMapBuilder` / `MindBranch` |
+  | `NODE_KINDS` の `"mind-radial"` | `"mind-map"` |
+  | `CdlRole` の `"mind-radial-halo"` | 無し。 当てていた CSS は削除する |
+
+  **絵の形は変わる**。 `mind-radial` は第 1 階層を 45 度間隔の 8 方向へ放射状に置いたが、
+  `mind-map` は第 1 階層を左右 2 列に振り分けて縦に並べる (`computeMindMapLayout`)。
+  8 方向の放射状という見た目自体に代わりは無い。
+
+  **書き換えは名前の置換では済まない**。 2 つの組み立て器は引数の形が違う。
+
+  | | `mindMapRadial` (0.5.0) | `mindMap` (0.6.0) |
+  |---|---|---|
+  | 中心の指定 | `centerTitle` (id は `centerId`、 既定 `"center"`) | `rootId` と `rootTitle` の 2 つが必須 |
+  | 距離の指定 | `radius` (既定 350) | 無し (canvas から導く) |
+  | 枝の親 | 省略可 (中心に繋がる) | `parent` が必須 |
+
+  したがって呼出は次のように書き換える。
+
+  ```ts
+  // 0.5.0
+  mindMapRadial({ id: "mr", topic: "...", centerTitle: "Product" })
+    .branch({ id: "users", title: "Users" })
+
+  // 0.6.0
+  mindMap({ id: "mr", topic: "...", rootId: "root", rootTitle: "Product" })
+    .branch({ id: "users", title: "Users", parent: "root" })
+  ```
+
+  名前だけ置換すると型検査で落ちる (`'centerTitle' does not exist in type 'MindMapPreset'`
+  と `Property 'parent' is missing`)。 落ちるので黙って壊れることは無いが、 全ての呼出と
+  全ての `.branch()` に手を入れる必要がある。
+
+  枝の数の上限も外れる。 `mindMapRadial().branch()` は 9 本目で投げ、 描画も第 1 階層を
+  8 本で切っていた。 `mindMap()` に上限は無く、 配置は再帰で降りる。 深さ数千段の payload を
+  機械で作って渡すと `RangeError: Maximum call stack size exceeded` になる (実測 = 深さ
+  1000 は 2.5ms で通り、 5000 で投げる)。 人が書く図では届かない深さだが、 生成した payload を
+  流し込む場合は深さを見ておく。
+
+  `[data-cdl-role="mind-radial-halo"]` および `[data-cdl-role="mind-radial-edge"]` に
+  当てていた CSS は、 一致する要素が無くなるため削除する。
+
+
+## [0.5.0] - 2026-06-28
+
+本節の `Removed (破壊的変更)` と `Changed` の後半 3 項目は **公開後に書き足した**。
+0.5.0 を公開した時点で CHANGELOG に記録し漏らしており、 0.6.0 を切る時に公開済の中身と
+突き合わせて気付いた (`npm pack @cardenelabs/cdl@0.5.0` を展開して確認)。 一度 0.6.0 の
+変更として書いたが、 実際には 0.5.0 で既に出ていたため本節へ移した。
+
+### Added
+
+Initial OSS release.
+
+- **12 preset** ... sequence / flow / swimlane / er / state / topology / solidity / gantt / class / pie / c4 / mind
+- **29 NodeKind** ... actor / function / storage / event / service / database / cache / queue / wallet / validator / 他
+- **8 EdgeStyle** ... solid / dotted / dashed / dotted-flow / 他
+- **6 Tone** ... accent / teal / success / error / warning / info
+- **phase / state / tween / set / badge** ... 時系列 animation を宣言的に
+- **Text DSL v0.5** ... mermaid 感覚の 5 ブロック箇条書き DSL (parser + compiler、 JA / EN i18n)
+- **Visual Editor** (`apps/playground`) ... GUI 編集 + live preview + SVG export
+- **Catalog** ... 12 preset × animation の visual 一覧
+- **Docs site** ... 全 16 概念 × JA / EN、 humans tab + LLM tab、 Diátaxis 準拠
+- **Pagefind 全文検索** ... Cmd+K で全 docs 高速 lookup
+- **React + Astro 両対応** ... static / SSR / hybrid どこでも動く
+- **CdlDiagramThumbnail** ... thumbnail + viewport いっぱいのモーダル拡大
+- **CdlDiagramView** ... phase autoplay / focusPhaseId / hideHeader / debug props
+- **Performance optimization** ... spatial hash 採用、 1000 node でも 60ms 以下の layout
+- **TypeScript strict 全面 ON** + zod runtime validation
+- **OSS 公開準備** ... README / CONTRIBUTING / SECURITY / ISSUE_TEMPLATE / PR_TEMPLATE 整備
+- **380 件のテスト** ... unit + integration + visual screenshot diff + e2e
+
+### Changed
+
+- chainome monorepo から独立 OSS lib として分離 (旧 `chainome/packages/cdl` + `chainome/packages/anim` + `chainome/apps/web` の cdl 関連を移植)
+- repo URL を `git@github.com:cardene777/cdl.git` に変更
+- playground (旧 `apps/web`) を `apps/playground` に rename
+
+- **`stateMachine` / `stateMachine2` の `stateWidth` が状態の箱の幅を指すようになった** (#357)
+
+  これまでは帯の幅にしか渡っておらず、 engine が帯を「箱の幅 320 + 余白 25 × 2 = 370」 まで広げ直すため、 **370 未満の指定は全て無視されていた** (260 / 300 / 340 のどれを指定しても図が 1 world も変わらない状態)。 option の名前が指すとおり箱の幅として扱うようにした。
+
+  既定値は 360 → 320 (`kind: "card"` の既定幅) に変えている。 これにより **`stateWidth` を指定しない図の座標は従来と完全に一致する** (帯は 320 + 50 = 370 を宣言し、 engine の再拡張も 370 で一致するため)。
+
+  **320 以外を明示していた図は全て変わる**。 値の範囲で内訳が違う。
+
+  | 明示値 | 従来 | 今後 |
+  |---|---|---|
+  | 320 | 無視 (帯 370 / 箱 320) | 同じ (帯 370 / 箱 320) |
+  | 80-319 | 無視 (帯 370 / 箱 320) | 効く (箱が指定値まで狭まり図が縮む) |
+  | 321-370 | 無視 (帯 370 / 箱 320) | 効く (箱が指定値まで広がり図が伸びる) |
+  | 371 以上 | 帯の幅として効く (箱は 320 のまま) | 箱の幅として効く (帯は指定値 + 50) |
+
+  370 以下は元から効いていなかったので、 今回初めて指定が反映される (option が名前どおりに働くようになった側)。 従来と同じ見た目に戻すなら `stateWidth: 320` を明示する。
+
+  371 以上を指定していた図は意味が変わる。 従来の「箱 320 を広い帯に置く」 形は preset では表現できなくなるため、 その見た目が要る場合は低位 API (`diagram().lane().node()`) で帯と箱を個別に宣言する。 3 状態の実測 = `stateWidth: 400` で `viewBox.w` 1440 → 1605。
+
+  併せて、 80 未満と有限でない値は例外を投げるようにした。 箱の幅として使う以上、 描画が壊れる値を黙って受け取らない。
+
+- **`er` の `entityWidth` と `classDiagram` の `classWidth` が箱の幅を指すようになった** (#359)
+
+  #357 と同じ構造が 2 つ残っていた。 どちらも帯の幅にしか渡っておらず、 engine が帯を「箱の幅 400 + 余白 25 × 2 = 450」 まで広げ直すため、 **450 以下の指定は全て無視されていた** (200 / 300 / 450 のどれを指定しても図が 1 world も変わらない状態)。
+
+  既定値はどちらも `kind: "storage"` の既定幅 (400) から導く。 帯は `400 + 50 = 450` を宣言する。
+
+  | preset | 従来の帯 | 今後の帯 | 既定の図 |
+  |---|---|---|---|
+  | `classDiagram` | 420 宣言 → engine が 450 に拡張 | 450 宣言 | 変わらない |
+  | `er` | 460 宣言 (engine の 450 を上回るのでそのまま) | 450 宣言 | **10 world 狭くなる** |
+
+  `er` だけ既定の見た目が変わる。 従来の 460 は `storage` の既定幅とも他の preset とも揃っていない値で、 doc には 360 と書かれていて実装 (460) とも食い違っていた。 箱は 400 のままなので、 変わるのは帯の左右の余白が 30 → 25 になる分だけ (他の preset は全て 25)。 従来と同じ幅に戻すなら `entityWidth: 410` を明示する。
+
+  450 以下を明示していた図は全て変わる (今回初めて指定が反映される側)。 451 以上を指定していた図は意味が変わり、 従来の「箱 400 を広い帯に置く」 形は preset では表現できなくなる。 その見た目が要る場合は低位 API (`diagram().lane().node()`) で帯と箱を個別に宣言する。
+
+  併せて、 80 未満と有限でない値は例外を投げるようにした。
+
+### Removed (破壊的変更)
+
+- **見た目の主題 (`CdlTheme`) を型ごと削除した** (#426)
+
+  主題は SVG の根に `data-cdl-theme` を出すだけの素通しの札で、 描画の判断には使っていなかった。
+  唯一の利用者が主題という概念を廃止したため、 型と欄と属性の出力をまとめて外した。
+
+  | 消えたもの | 代わりに使うもの |
+  |---|---|
+  | `CdlTheme` 型 (`index.ts` / `builder.ts` から輸出) | 無し。 見た目は consumer 側の CSS が決める |
+  | `diagram(id, { theme })` の `theme` 欄 | 無し。 渡していた場合は削除する |
+  | `CdlDiagram.theme` / `LaidDiagram.theme` | 無し |
+  | SVG の根の `data-cdl-theme` 属性 | `[data-cdl-role="<role>"]` selector で見た目を当てる |
+
+  `[data-cdl-theme="x"] [data-cdl-role="y"]` の形で CSS を書いていた場合は、
+  前半を外して `[data-cdl-role="y"]` にする。 明暗の切替は consumer 側の仕組み
+  (`html` の class 等) で行う。
+
+- **`VisualAxis` から 2 軸を削除した** (#426)
+
+  | 消えた軸 | 理由 |
+  |---|---|
+  | `svg-filter-integrity` | 前提にしていた filter (`cdl-nm-raised-soft`) が既に存在せず、 何も検査していなかった |
+  | `neumorphism-shadow-budget` | 主題固有の影 (6 world) を前提とする軸で、 主題の廃止で根拠が消えた。 隣接の間隔は `node-vertical-clearance` (40 world) と near-collision (70 world) が引き続き見る |
+
+  軸名を集計 / 比較している consumer は、 この 2 つを一覧から外す。
+
+## [0.4.0] - 2026-06-27
+
+### Added
+
+- **Text DSL v0.4** ... 残 5 preset (flow / swimlane / er / state / topology) animation 拡張
+- catalog の Text DSL demo page (`/catalog/text-dsl`) ... 6 preset × animation の visual 確認
+- 全 docs code block への preview 強制 (48 件、 lint script による品質保証)
+- integration test 21 件追加 (Permit / Topology / edge case / regression / 6 preset × animation)
+
+## [0.3.0] - 2026-06-27
+
+### Added
+
+- **Text DSL v0.3** ... sequence preset で `アニメーション:` ブロック full compile
+- DSL の `状態` / `ステップ` / `強調` / `遷移` / `切替` / `バッジ` / `説明` を実 phase / state / tween / set / activate / badge / body に注入
+- highlight 解決 ... actor 名 → `header` + `footer` + `step box` を active 化、 `A→B` 矢印 → edge id を active 化
+- アーキテクチャ ... animation あり時 builder 直接経路、 なし時 preset 経由 (v0.2 互換)
+- test 6 件 (v0.3 機能)
+
+## [0.2.0] - 2026-06-27
+
+### Added
+
+- **Text DSL v0.2** ... 6 preset 全対応 (sequence + flow + swimlane + er + state + topology)
+- cardinality 自動解析 (1:1 / 1:N / N:M / 0..1 / 1..*)
+- ER preset で entity 自動生成 + relation 自動 cardinality
+- state preset で最初 actor = initial、 最後 = final 自動付与
+- topology preset で 1 group 内 container 配置
+- test 8 件 (5 preset 動作確認)
+
+## [0.1.0] - 2026-06-27
+
+### Added
+
+- **Text DSL v0.1** ... 「タイトル / 種類 / 登場人物 / 流れ / アニメーション」 の 5 ブロック箇条書き DSL
+- parser + compiler (sequence preset only) ... 行ベース parser + AST + LaidDiagram 変換
+- 日本語 + 英語両対応 (キーワード i18n)
+- 矢印正規化 (→ / -> / => / >>)
+- duration 解析 (1.5 秒 / 1500ms / 2s)
+- エラー親切 (行番号 + hint + 修正提案)
+- LLM 生成ガイド + 5 few-shot 例
+- ChatGPT/Claude/Cursor 即用 system prompt
+- preview 強制 lint script (`pnpm lint:docs-preview`)
+- text-dsl-spec.md + text-dsl-llm-guide.md (docs site 統合)
+- test 11 件 (parse + compile + アニメーション parse)
+
+## 版と commit の対応
+
+各版の見出しから、 その版を公開した commit までの差分を辿れる。 `0.4.0` 以前はこの repo を
+切り出す前 (旧 monorepo) の版で、 対応する commit がこの repo に無いため link を持たない。
+
+最古の `0.5.0` だけ `/tree/` を指す (それ以前と比べる相手が無いため)。 `/releases/tag/` は
+使わない = annotated tag を push しても GitHub Release は作られず、 Release を作っていない版で
+行き止まりになる。
+
+[Unreleased]: https://github.com/cardene777/cdl/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/cardene777/cdl/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/cardene777/cdl/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/cardene777/cdl/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/cardene777/cdl/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/cardene777/cdl/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/cardene777/cdl/tree/v0.5.0

package/SPEC.md

@@ -144,9 +144,12 @@ phase が定義されると自動的に。
 6. **edge label** は path 中点から「path 進行方向の垂直方向」 に 50-80px 離して配置、 lane / node bbox との overlap を計算で避ける
 7. **viewBox** は cdl が auto 計算 (全 lane の右端 + 余白 80px、 全 node の下端 + 余白 80px)
 
-## Routing v8 (fan-in / fan-out / label auto shift SSOT)
+## Routing v8-v10.1 (historical)
 
-著者は座標 / offset / path 迂回を書かない。 以下 5 保証は全て engine が担う (`packages/cdl/src/layout/edges.ts` + `label-shift.ts` + `collisions.ts` 集約)。
+CAR-430 より前の routing v8-v10.1 では、 著者が座標 / offset / path 迂回を書かず、
+`packages/cdl/src/layout/edges.ts` + 旧 `label-shift.ts` + `collisions.ts` が以下の配置を担っていた。
+本節は係数と不具合の変遷を残す履歴資料であり、 **現行 pipeline の SSOT ではない**。
+現行の権限フローは後節の「Chain 伝搬 shift + spec 固定化 SSOT」を参照する。
 
 1. **fan-in 分散** ... 同 to node に集約する複数 edge を to 側 sidepoint offset で分散、 path 重複 0
 2. **fan-out 分散** ... 同 from node からの複数 edge を to の cy 順で offset 分散、 交差 0
@@ -171,15 +174,16 @@ border case sweep test (`dragon apps/playground/tests/visual/overlap-detector.sp
 10. **detour gap 拡張 (44 → 94、 +50)** ... label-shift v10 が detour path から NORMAL 100 world 上に label を置く挙動と組み合わせると、 obstacle.bottom + clearance 32 world では label bottom が obstacle と 24 world 割り込む (pattern-rollback e3 の label × commit 20 px² overlap の root cause、 cdl PR #58)。 gap +50 で label 位置が obstacle bottom から 66 world (DOM ~16 px) 離れる。
 11. **fan-in slot 別 detour Y 分散** ... 同 to node の複数 detour edge (pattern-rollback の e3 + e5 が両方 → db) が同 y 帯集約して label × label collision する問題を解消。 `slotFromCenter = Math.round(offset / fanGap)` で slot index を復元、 slot 0 起点で obstacle 側から離れる方向にのみ 0..fanGap の絶対値 shift。 上迂回 case は逆方向 (上方) にのみ shift、 detour Y 符号に合わせて分散方向を決定 (`edges.ts` `isDownDetour ? +detourYAdjustAbs : -detourYAdjustAbs` SSOT)。
 
-### routing SSOT 前提 (壊れると再検証必要)
+### 旧 routing 実測の前提
 
-以下の 3 前提を維持する限り上記 11 保証が有効:
+上記の旧 routing v8-v10.1 を評価した時点では、 以下の 3 前提を実測に使った。
 
 - **dragon CdlDiagramThumbnail の display 幅** ... 490 px 相当 (SVG viewBox 1820 world unit と scale 0.269 で対応)
 - **diagram viewBox 幅** ... 1500-2000 world unit 相当 (author lane 定数 SSOT の慣例値)
 - **font family** ... Inter / Newsreader (measureTextWidth の pt 想定と一致)
 
-これらが変更されたら `WORLD_SCALE = 4.0` (v8 の 3 番) と `TARGET_DIST = 100` (v10 の 9 番) の実測 SSOT を再測定して係数を再チューニングする (`edges.ts` v8 SSOT comment + `label-shift.ts` v10 SSOT comment 参照)。
+これらが変更されたら、 現行値は `packages/cdl/src/layout/edges.ts` +
+`packages/cdl/src/layout/spec.ts` + `packages/cdl/src/layout/clearance-constants.ts` を起点に再測定する。
 
 ## Chain 伝搬 shift + spec 固定化 SSOT (CAR-418 系)
 
@@ -194,32 +198,43 @@ layout constants は 2 種類の SSOT で管理する、 いずれも `packages/
 | **positive spec** | engine が満たすべき正しい配置目標値 | `visualValidateLaid` axes / dragon pixel-perfect gate | `SPEC_CLEARANCE_POLICY` |
 | **near-collision** | 「これ以下は誤読」 の下限 | `detectNearCollisions` (`collisions.ts`) | `NEAR_COLLISION_POLICY` |
 
-primitive 定数 (`CLEARANCE_NODE_LABEL` / `CLEARANCE_LANE_LABEL` / `CLEARANCE_LABEL_LABEL` / `CLEARANCE_PATH_LABEL` / `TARGET_LABEL_PATH_DIST` 等) は `packages/cdl/src/layout/clearance-constants.ts` に置き、 spec.ts / collisions.ts / label-shift.ts / edges.ts の全 downstream が import で参照する。 CAR-424 で `edges.ts` / `label-shift.ts` の module-local 定数を全削除、 `clearance-constants.ts` を 1 箇所 SSOT に集約した。
+primitive 定数 (`CLEARANCE_NODE_LABEL` / `CLEARANCE_LANE_LABEL` / `CLEARANCE_LABEL_LABEL` / `CLEARANCE_PATH_LABEL` / `TARGET_LABEL_PATH_DIST` 等) は `packages/cdl/src/layout/clearance-constants.ts` に置き、 spec.ts / collisions.ts / edges.ts の全 downstream が import で参照する。 CAR-424 で旧 `edges.ts` / `label-shift.ts` の module-local 定数を全削除、 `clearance-constants.ts` を 1 箇所 SSOT に集約した。
 
 ### 現行 pipeline と CAR-418 移行状態
 
-現在 (2026-07-04) の `layout()` pipeline (`packages/cdl/src/layout.ts`) は以下 6 phase を走る。
+現在 (2026-08-19) の `layout()` pipeline (`packages/cdl/src/layout.ts`) は以下 7 phase を走る。
 
-1. `layoutLanes` → `layoutNodes` → `expandLanesForNodes` (lane / node 静的配置)
-2. `layoutEdges` (edge routing、 fan-in / fan-out offset 分散 + orthogonal routing + 水平大回り detour + midX/midY retreat)
+1. `layoutLanes` → `layoutNodes` → `expandLanesForNodes` → `expandLaneGapsForEdgeLabels` (lane / node 静的配置 + label 収納 gap 確保)
+2. `layoutEdges` (edge routing + 初期 label 位置を決定)
 3. `detectCollisions` → `resolveOverlaps` (node-node 後勝ち一発 shift)
-4. `layoutEdges` (moved node で edge 再 route)
-5. `shiftLabelsAwayFromNodes` (label auto shift、 16 方向 × 26 段階 + 中央 anchor Tier)
-6. `computeViewBox` (viewport 決定)
+4. node が動いた場合の `layoutEdges` 再 route
+5. `resolveEdgeLabelOverlapsWithChainAndPropagate` (edge label を起点に label / node / edge-path の chain 伝搬 shift を算出・反映。 lane-label は obstacle として扱うが、 返却された lane-label shift は現行 `layout()` では未適用)
+6. `bowSharedStraightPaths` → `repositionParallelLabels` (共有直線 path を確定後、 parallel label の `labelY` を最終配置)
+7. `detectCollisions` / `detectNearCollisions` → `computeViewBox` (最終検証 + viewport 決定)
 
-CAR-421 で `resolveOverlapsWithChain(nodes, minClearance, maxIter)` を新設し、 node-node overlap の chain 伝搬 shift を実装した (`packages/cdl/src/layout/collisions.ts`)。 単体 API として export 済、 実 pipeline `layout()` は現状 `resolveOverlaps` のまま (sequence preset の lifeline 等の既存 snapshot 保持のため opt-in で呼ぶ設計、 全 preset での有効化は将来 Issue で段階展開)。
+label 位置は段階的に確定する。 `edges.ts routePath()` が初期位置を返し、 `layoutEdges` が
+author 指定 offset / margin と parallel / fan-in / fan-out label 分散を加えて暫定位置を決める。
+次に `resolveEdgeLabelOverlapsWithChainAndPropagate` が overlap / near-collision 発生時のみ
+chain 伝搬で動かす。 node が chain shift された場合は `layoutEdges` を再実行して endpoint を追従させ、
+最後に `repositionParallelLabels` が共有 node pair の label を兄弟 path に合わせて置き直す。
+旧 `label-shift.ts` の 16 方向 × 26 段階探索は CAR-430 で削除済みで、 現行 pipeline には含まれない。
 
-edge 路線分散 (fan-in / fan-out offset) と label auto shift (16 方向 × 26 段階) は現在も稼働している。 これらを chain 伝搬に一本化する構想は CAR-418 で提示済だが、 label / edge の chain 伝搬 shift 実装は node-node の resolveOverlapsWithChain より複雑 (obstacle chain が edge path / label bbox / fan slot の 3 軸で干渉する)、 段階的 PR で扱う (段階展開 SSOT は CAR-418 親 Issue)。
+CAR-421 で新設した `resolveOverlapsWithChain(nodes, minClearance, maxIter)` は単体 API として残る。
+実 pipeline の node-node 解消は、 既存 snapshot との互換性のため引き続き `resolveOverlaps` が担う。
 
-### CAR-424 の完了範囲 (二層 SSOT 集約 + SPEC 明文化)
+### CAR-424 の完了範囲 (履歴)
 
-CAR-424 は「PR 3 = 旧場当たり logic 除去 + SPEC.md 更新」 の scope だが、 現行 routing v8 / v10 系は border case sweep test (dragon overlap-detector) + 15+ preset の snapshot で品質保証されている。 場当たり logic の一括削除は「chain 伝搬 shift を label / edge にも展開」 が完了してからでないと preset 品質を落とすため、 本 PR では以下 3 点に scope を限定する。
+CAR-424 時点では、 routing v8 / v10 系の一括削除を避け、 以下 3 点に scope を限定した。
+後続の CAR-429 / CAR-430 で edge path の sidepoint 分散と旧 label 探索の段階削除が完了しているため、
+以下は現行状態ではなく当時の完了範囲を示す。
 
 - **module-local 重複定数の集約** ... `edges.ts` `CLEARANCE_NODE_LABEL = 32` と `label-shift.ts` の 4 clearance 定数を `clearance-constants.ts` import に置換 (dedup)
 - **`CLEARANCE_POLICY` の SSOT 集約** ... `collisions.ts` module-local `CLEARANCE_POLICY` dict を `spec.ts` `NEAR_COLLISION_POLICY` に移管、 `collisions.ts requiredClearance` は `requiredNearClearance` に委譲する薄い adapter に縮小
 - **本 SPEC.md 「Chain 伝搬 shift + spec 固定化 SSOT」 セクション追加** ... 二層 SSOT (positive spec / near-collision) 分離、 現行 pipeline の CAR-418 移行状態、 CAR-424 完了範囲を明文化
 
-`edges.ts` fan-in / fan-out offset 分散 の削除 + `label-shift.ts` shift 探索 削除 は「chain 伝搬 shift を label / edge にも展開」 が別 Issue で完了してから段階削除、 現行の場当たり logic の SSOT comment (`edges.ts` v8 SSOT + `label-shift.ts` v10 SSOT) は据え置き。
+当時は `edges.ts` fan-in / fan-out path の sidepoint offset 分散削除 + `label-shift.ts` shift 探索削除を
+後続 Issue に送った。 これらは CAR-429 / CAR-430 で完了済み。 label 自体の parallel / fan-in /
+fan-out 分散は `layoutEdges` 内の暫定位置決定として現行でも稼働する。
 
 ### 参照