@cardenelabs/cdl 0.14.0 → 0.16.0

package/src/kinds/draw-ratio.ts

@@ -0,0 +1,44 @@
+/**
+ * 描く速さを phase の長さと別に決める (cdl#570)。
+ *
+ * `CdlPhase.drawRatio` は「`draw` の対象を描き終えるまでに phase の何割を使うか」 を表す。
+ * ここでは進みの引き伸ばしだけを持ち、 誰に掛けるかは `render/stage.tsx` が決める。
+ */
+
+/** 割合を書かない phase の既定。 従来どおり phase の終わりに描き終わる */
+export const DRAW_RATIO_DEFAULT = 1;
+
+/**
+ * 書かれた割合を、 使える値に直す。
+ *
+ * 範囲外 (0 以下 / 1 超 / NaN / Infinity / 未指定) は既定の 1 に落とす。 描く動きは
+ * 見え方であって図の意味ではないので、 書き間違いで図が出なくなる方が損が大きい。
+ * 書き間違いそのものは `validate` が warning で知らせる。
+ *
+ * **0 を通すとゼロ除算になる**。 `Number.isFinite` は 0 を通すため、 下限の判定を
+ * 別に置く必要がある。
+ */
+export function 描く割合を正す(ratio: number | undefined): number {
+  if (ratio === undefined) return DRAW_RATIO_DEFAULT;
+  if (!Number.isFinite(ratio)) return DRAW_RATIO_DEFAULT;
+  if (ratio <= 0 || ratio > 1) return DRAW_RATIO_DEFAULT;
+  return ratio;
+}
+
+/**
+ * phase の進みを、 描く対象から見た進みに直す。
+ *
+ * 割合が 1 なら元の値をそのまま返す = 割合を書かない図では計算が入らない。
+ *
+ * 引き伸ばした結果は 1 で頭打ちにする。 描き終わってから phase が終わるまでの間、
+ * 対象は描き終わった姿のまま留まる。
+ *
+ * 進みが数でない場合は元の値をそのまま返す。 ここで 1 に丸めると、 進みの異常を
+ * 受け取る側 (`進みを畳む`) が持つ落とし方と二重になり、 どちらが効いたか読めなくなる。
+ */
+export function 描く進みに直す(progress: number, ratio: number | undefined): number {
+  const 割合 = 描く割合を正す(ratio);
+  if (割合 === DRAW_RATIO_DEFAULT) return progress;
+  if (!Number.isFinite(progress)) return progress;
+  return Math.min(1, progress / 割合);
+}

package/src/kinds/dyn-shape.tsx

@@ -64,13 +64,13 @@ export function DynShapeNode({
     case "rect":
       return renderRect(shape, x, y, w, h, stateValues, fillColor, strokeColor, activeOpacity, node);
     case "circle":
-      return renderCircle(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity, node);
+      return renderCircle(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
     case "arc":
-      return renderArc(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity, node);
+      return renderArc(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
     case "wave":
       return <WaveShape shape={shape} x={x} y={y} w={w} h={h} stateValues={stateValues} fillColor={fillColor} strokeColor={strokeColor} opacity={activeOpacity} node={node} />;
     case "polygon":
-      return renderPolygon(shape, cx, cy, stateValues, fillColor, strokeColor, activeOpacity, node);
+      return renderPolygon(shape, cx, cy, stateValues, fillColor, strokeColor, activeOpacity);
   }
 }
 
@@ -162,7 +162,6 @@ function renderCircle(
   fillColor: string,
   strokeColor: string,
   opacity: number,
-  node: LaidNode,
 ): JSX.Element {
   const maxR = Math.min(w, h) / 2;
   const r = shape.radius !== undefined ? resolveNumericAttr(shape.radius, stateValues, maxR) : maxR;
@@ -196,7 +195,6 @@ function renderArc(
   fillColor: string,
   strokeColor: string,
   opacity: number,
-  node: LaidNode,
 ): JSX.Element {
   const maxR = Math.min(w, h) / 2;
   const outerR = shape.outerRadius ?? maxR;
@@ -325,7 +323,6 @@ function renderPolygon(
   fillColor: string,
   strokeColor: string,
   opacity: number,
-  node: LaidNode,
 ): JSX.Element {
   const sides = Math.min(12, Math.max(3, shape.sides));
   const r = shape.radius !== undefined ? resolveNumericAttr(shape.radius, stateValues, 40) : 40;

package/src/kinds/generic.tsx

@@ -2,7 +2,12 @@ import type { JSX } from "react";
 import type { LaidNode, NodeKind } from "../types";
 import { toneColor } from "./node-tone";
 import { interpolate } from "../render/utils";
-import { rowBaselineY } from "../layout/spec";
+import {
+  genericTextCentered,
+  genericTextShift,
+  genericTitleBaselineY,
+  rowBaselineY,
+} from "../layout/spec";
 import {
   GENERIC_ROW_LEFT_SIZE_PX,
   rowColumnWidth,
@@ -281,15 +286,22 @@ export function GenericNode({
   // 共通経路は解決できない参照を `{名前}` のまま残すので、 読み手が気付ける。
   const resolvedValue = value !== undefined ? interpolate(value, stateValues) : undefined;
 
-  // shape 別の text 配置 (diamond / cloud は中心揃え、 rect 等は左上揃え)
-  const centered = shape === "diamond" || shape === "cloud";
+  /*
+   * shape 別の text 配置 (diamond / cloud は中心揃え、 rect 等は左上揃え)。
+   *
+   * **行がある時は中心へ寄せない** (#558)。 題を箱の中心に置くと、上端から数える行と必ず
+   * 重なる = 中心に題を置いたまま行を並べる場所が無い。 判定は `spec.ts` が持ち、
+   * 検査軸 (`title-row-overlap`) も同じ関数を引く。
+   */
+  const hasRows = (node.rows?.length ?? 0) > 0;
+  const centered = genericTextCentered(node.kind, hasRows);
   const textAnchor = centered ? ("middle" as const) : ("start" as const);
   const textX = centered ? w / 2 : 20;
-  // cylinder は上 ellipse (ry=14) の下に text を置く必要があるため textY を +28 shift
-  const cylinderShift = shape === "cylinder" ? 28 : 0;
+  // cylinder は上 ellipse (ry=14) の下に text を置く。 ずらし量は `spec.ts` が持つ
+  const cylinderShift = genericTextShift(node.kind);
   // 中心揃え時は h/2 を baseline 中心 (dominantBaseline=middle で計算するため text y を h/2 ベースに統一)
   const eyebrowY = centered ? h / 2 - 26 : 32 + cylinderShift;
-  const titleY = centered ? h / 2 + 4 : 68 + cylinderShift;
+  const titleY = genericTitleBaselineY(node.kind, h, hasRows);
   const subtitleY = centered ? h / 2 + 28 : 96 + cylinderShift;
   // icon 位置 (diamond / cloud は title の真右の少し上、 中心配置に合わせる)
   const iconX = centered ? w / 2 + 40 : w - 48;

package/src/kinds/terminal-mark.tsx

@@ -0,0 +1,96 @@
+import type { JSX } from "react";
+import type { LaidNode } from "../types";
+import { nodeAccent } from "./node-tone";
+
+/**
+ * 流れの **始まりと終わりの印** (#560)。
+ *
+ * 状態遷移図は始まりを塗った丸、終わりを輪で囲んだ丸で示す。 それまでこれに当たる種別が無く、
+ * 箱の小見出しに「初期」「最終」 と書いて代えていた = 印であるべきものが文字になっていた。
+ *
+ * **文字は描かない**。 印そのものが意味を持つので、丸の中に名前を入れても読めない。
+ * `rendersTitleText` はこの 2 種別を「描かない」 側に置いており、全種別を描いて突き合わせる
+ * 検査 (`test/node-title-render.test.tsx`) が実際の描画と一致していることを見る。
+ */
+
+/** 終わりの印の、内側の丸の直径を外側の輪の何割にするか */
+export const MARK_INNER_RATIO = 0.56;
+
+/** 終わりの印の輪の太さ。 光っている時は太くする (他の種別の枠線と同じ考え方) */
+const RING_WIDTH_ACTIVE = 6;
+const RING_WIDTH_IDLE = 4;
+
+/** 印の既定の色。 `tone` を書けばそちらが勝つ */
+const MARK_DEFAULT = "var(--cdl-tone-accent, #2d6a8f)";
+
+/**
+ * 印の半径。 **箱の短い方の辺いっぱい** に描く。
+ *
+ * 線は箱の縁で止まるので、印を箱より小さく描くと矢の先と印の間が空いて線が浮く
+ * (半分の大きさにすると 24 world 空いた)。 縁まで描けば接する。
+ *
+ * 短い方から取るのは、段の高さが全ての段で揃えられるため。 同じ段に背の高い箱があると
+ * 印の箱も背が高くなり、長い方に合わせると印だけ縦長の楕円になる。 その時は横幅のまま
+ * 上下の中央に置く = 上下には隙間が残るが、丸のままで読める側を採る。
+ */
+function markRadius(node: LaidNode): number {
+  return Math.min(node.w, node.h) / 2;
+}
+
+/**
+ * 流れの始まり = 塗った丸。
+ *
+ * **光っても形を変えない**。 他の種別は光った時に枠線を太くするが、塗った丸には太らせる枠が
+ * 無い。 枠を足すと線の中心が半径に乗るぶん丸が箱の外へ出て、線との接点がずれる (実測で
+ * 太さ 4 の枠を足すと外径が 96 から 100 になった)。 色は `tone` で変えられる。
+ */
+export function MarkStartNode({ node }: { node: LaidNode; active: boolean }): JSX.Element {
+  const 色 = nodeAccent(node, MARK_DEFAULT);
+  return (
+    <g transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}>
+      <circle
+        data-cdl-role="node-body"
+        data-cdl-mark="start"
+        cx={node.w / 2}
+        cy={node.h / 2}
+        r={markRadius(node)}
+        fill={色}
+      />
+    </g>
+  );
+}
+
+/**
+ * 流れの終わり = 輪で囲んだ丸。
+ *
+ * 輪と中身は同じ色で描く。 別の色にすると 2 つの意味を持つ印に見えるが、表しているのは
+ * 「ここで終わる」 の 1 つだけ。
+ */
+export function MarkEndNode({ node, active }: { node: LaidNode; active: boolean }): JSX.Element {
+  const 色 = nodeAccent(node, MARK_DEFAULT);
+  const r = markRadius(node);
+  const 輪の太さ = active ? RING_WIDTH_ACTIVE : RING_WIDTH_IDLE;
+  return (
+    <g transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}>
+      <circle
+        data-cdl-role="node-body"
+        data-cdl-mark="end"
+        cx={node.w / 2}
+        cy={node.h / 2}
+        // 輪は線の中心を半径に置くので、外側へ太さの半分だけ出る。 印が箱の短い方の辺に
+        // 収まるよう、その分だけ縮める
+        r={Math.max(0, r - 輪の太さ / 2)}
+        fill="var(--cdl-node-fill, #ffffff)"
+        stroke={色}
+        strokeWidth={輪の太さ}
+      />
+      <circle
+        data-cdl-role="node-inner"
+        cx={node.w / 2}
+        cy={node.h / 2}
+        r={Math.max(0, r * MARK_INNER_RATIO)}
+        fill={色}
+      />
+    </g>
+  );
+}

package/src/layout/edges.ts

@@ -23,6 +23,7 @@ import {
   PARALLEL_EDGE_BOW,
   SYMMETRIC_PAIR_SHIFT,
 } from "./spec";
+import { isSelfLoop, layoutSelfLoops } from "./self-loop";
 import { DEFAULT_LABEL_MARGIN } from "./tokens";
 
 /** 縦 detour が obstacle の外側を通る時の余白 (world unit)。 */
@@ -162,6 +163,10 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
   // 全 4 field 未指定なら従来通り orthogonal L 字 routing で保証。
   const positionedEdges: LaidEdge[] = [];
   const autoEdges: typeof diag.edges = [];
+  // 自分から自分へ戻る辺は、両端が同じ節なので 2 節の位置関係から向きを決める routing が
+  // 使えない (どちら側へ出すかを節の外から決められない)。 専用の経路にまとめて渡す (#560)。
+  // 座標を固定した辺 (`posX1` 等) は書いた人が形を決めているので、そちらを先に取る
+  const selfLoopEdges: typeof diag.edges = [];
   for (const e of diag.edges) {
     if (e.posX1 !== undefined && e.posY1 !== undefined && e.posX2 !== undefined && e.posY2 !== undefined) {
       const from = nmap.get(e.from);
@@ -180,11 +185,12 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
         labelY: midY + (e.labelOffsetY ?? 0),
         labelAnchor: "middle",
       });
+    } else if (isSelfLoop(e)) {
+      selfLoopEdges.push(e);
     } else {
       autoEdges.push(e);
     }
   }
-
   const prepared = autoEdges.map((e) => {
     const from = nmap.get(e.from);
     const to = nmap.get(e.to);
@@ -207,6 +213,28 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
     distributeBySides(list);
   }
 
+  // 輪はここで経路にする (#560)。 どちら側へ出すかは「他の線が使っていない辺」 で決めるので、
+  // 側が確定した後でないと選べない (`distributeBySides` が上で側を書き換える)。
+  //
+  // 起点側と終点側の両方を数える = 入ってくる線も辺を 1 つ塞ぐ。 `back-detour` は routing が
+  // 側を上へ強制するので、その後の値で数える (`routePath` に渡すのと同じ値)。
+  const occupiedBySide = new Map<string, Set<Side>>();
+  const 使う = (nodeId: string, side: Side) => {
+    const s = occupiedBySide.get(nodeId) ?? new Set<Side>();
+    s.add(side);
+    occupiedBySide.set(nodeId, s);
+  };
+  for (const p of prepared) {
+    const backDetour = p.e.routing === "back-detour";
+    使う(p.e.from, backDetour ? "top" : p.fromSide);
+    使う(p.e.to, backDetour ? "top" : p.toSide);
+  }
+  for (const le of positionedEdges) {
+    使う(le.from, le.fromSide);
+    使う(le.to, le.toSide);
+  }
+  const loopEdges = layoutSelfLoops(selfLoopEdges, nmap, occupiedBySide);
+
   // CAR-429 (CAR-426-B) ... 全 edge の起点 / 終点 / L 字 corner は node 辺 Y 中央固定 (offset=0 SSOT)。
   // 旧 fan-in / fan-out / parallel の sidepoint 分散 (±60/±120) は削除済で、
   // path routing (d 属性) は offset=0 固定で描画される (視覚的に起点認識明確化)。
@@ -1090,6 +1118,7 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
   // 元 diag.edges の順序を保持するため id 順で lookup、 positioned は auto より先に列挙。
   const laidById = new Map<string, LaidEdge>();
   for (const le of autoResults) laidById.set(le.id, le);
+  for (const le of loopEdges) laidById.set(le.id, le);
   for (const le of positionedEdges) laidById.set(le.id, le);
   return diag.edges.map((e) => laidById.get(e.id)!).filter((e) => e !== undefined);
 }

package/src/layout/self-loop.ts

@@ -0,0 +1,217 @@
+import type { CdlEdge, LaidEdge, LaidNode, Side } from "../types";
+import { CLEARANCE_LABEL_LABEL } from "./clearance-constants";
+import { computeLabelBoxW, LABEL_TO_PATH_CLEARANCE, labelPillH } from "./spec";
+
+/**
+ * 自分から自分へ戻る関係の経路 (#560)。
+ *
+ * 状態遷移図の自己遷移 (催促する)、シーケンス図の自分宛て (控えを書く)、ER の自己関係
+ * (REPORTS TO) の 3 図が使う。 それまで `validate` が弾いていた。
+ *
+ * 形は **箱の 1 辺から出て、外へ膨らんで、同じ辺へ戻る** 三次曲線 1 本。 折れ線ではなく
+ * 曲線にしたのは、線の傾きを見る検査 (軸 13) が曲線を対象外にしているのと同じ理由で、
+ * 輪の途中の傾きに意味が無いため。 折れ線で描くと「L 字が破綻している」 と読まれる。
+ */
+
+/** 輪が辺から外へ届く距離 (world)。 制御点ではなく、曲線が実際に到達する距離 */
+export const SELF_LOOP_OUT = 72;
+
+/** 出口と入口の間隔 (world)。 辺のどれだけを使うか */
+export const SELF_LOOP_SPAN = 64;
+
+/**
+ * 同じ節に輪が 2 本以上ある時、 2 本目以降を外へずらす幅 (world)。
+ *
+ * `SELF_LOOP_OUT` と揃えて **3 の倍数** にしてある。 制御点の位置は 3 分の 4 倍で求めるので、
+ * 3 の倍数でないと座標が割り切れず、小数点の混じった座標を検査 (軸 33) が拾う。
+ */
+export const SELF_LOOP_STAGGER = 45;
+
+/**
+ * 書かなかった時にどちら側へ出すかを探す順。
+ *
+ * 節は縦に積むので、上下は前後の節との線が先に使う。 右を最初に見る。
+ *
+ * **他の線が使っている辺は避ける**。 同じ辺に出すと 2 つ壊れる = 横へ抜ける線が輪の内側を
+ * 通って重なり、その線の起点と輪の起点が別の高さになって「1 つの節から出ていない」 ように
+ * 見える (検査の軸 2 と軸 61 が両方鳴る、実測した)。 輪は終点を辺の中央付近に置く必要が
+ * あるので (軸 63)、同じ辺の中で高さをずらして避けることはできない。
+ */
+export const SELF_LOOP_SIDE_ORDER: readonly Side[] = ["right", "top", "left", "bottom"];
+
+/** どの辺も塞がっている時に使う辺。 避けきれないので、少なくとも同じ場所に落とす */
+export const SELF_LOOP_SIDE_FALLBACK: Side = "right";
+
+/**
+ * 三次曲線の制御点を辺からどれだけ離すか、を決める比。
+ *
+ * 両端が辺の上にあり、制御点を 2 つとも同じだけ外へ置いた三次曲線は、真ん中 (t=0.5) で
+ * 制御点の **4 分の 3** までしか届かない。 届かせたい距離から逆算する。
+ *
+ * 係数を式で持つのは、`SELF_LOOP_OUT` を変えた時に輪の実寸と語の置き場所が一緒に動く
+ * 必要があるため。 書き写すと片方だけ動いて語が輪の中に入る。
+ */
+export const CUBIC_APEX_RATIO = 0.75;
+
+/** 終点が辺の中央から離れてよい上限を決める余白。 軸 63 の判定と同じ値 */
+const ENDPOINT_CENTER_MARGIN = 8;
+
+/** 出口と入口が重なって輪が線 1 本に潰れない最小の間隔 */
+const SPAN_MIN = 8;
+
+function controlOffset(out: number): number {
+  return out / CUBIC_APEX_RATIO;
+}
+
+/** 辺の中心と、その辺の外向き */
+function sideGeometry(n: LaidNode, side: Side): { x: number; y: number; ux: number; uy: number } {
+  switch (side) {
+    case "right":
+      return { x: n.cx + n.w / 2, y: n.cy, ux: 1, uy: 0 };
+    case "left":
+      return { x: n.cx - n.w / 2, y: n.cy, ux: -1, uy: 0 };
+    case "top":
+      return { x: n.cx, y: n.cy - n.h / 2, ux: 0, uy: -1 };
+    case "bottom":
+      return { x: n.cx, y: n.cy + n.h / 2, ux: 0, uy: 1 };
+  }
+}
+
+/**
+ * 出口と入口の間隔を、その辺に収まる範囲へ丸める。
+ *
+ * 終点が辺の中央から離れすぎると軸 63 (`arrow-endpoint-center`) が「角に刺さっている」 と
+ * 判定する。 判定の境目は辺の半分から 8 を引いた値なので、そこへ収まるまで縮める。
+ * 縮めても最小値は残す = 0 にすると出口と入口が重なって輪が潰れる。
+ */
+export function fitSpan(sideLength: number, wanted: number): number {
+  const 限度 = sideLength - 2 * ENDPOINT_CENTER_MARGIN;
+  return Math.max(SPAN_MIN, Math.min(wanted, 限度));
+}
+
+/**
+ * 1 つの節にある輪 `count` 本に、他の線が使っていない辺を **1 本ずつ配る**。
+ *
+ * 「使っている」 は `occupied` が持つ = 呼出側が、輪でない辺の起点側と終点側の両方を入れる。
+ * 入れ忘れると輪がその線の上に重なるので、呼出側は 2 経路 (自動で引く線と、座標を固定した線)
+ * のどちらも入れる。
+ *
+ * **1 辺に 2 本まとめない**。 同じ辺に重ねると輪が入れ子になり、内側の輪の語を外側の輪の
+ * 外へ出さざるをえない = 語が自分の線から遠のく (検査の軸 7 が「どの線の語か読めない」 と
+ * 判定する。 実測で 3 本を入れ子にすると一番内側が 160 離れて error になった)。
+ *
+ * 空いている辺より輪が多い時だけ、余った分を先頭の辺へ戻して重ねる。 そこは重なる形しか
+ * 残っていないので、少なくとも同じ場所に集める。
+ */
+export function pickFreeSides(occupied: ReadonlySet<Side> | undefined, count: number): Side[] {
+  const 空き = SELF_LOOP_SIDE_ORDER.filter((s) => !occupied?.has(s));
+  const 使う = 空き.length > 0 ? 空き : [SELF_LOOP_SIDE_FALLBACK];
+  return Array.from({ length: count }, (_, i) => 使う[i % 使う.length]!);
+}
+
+/**
+ * 同じ節・同じ辺の輪をまとめて経路にする。
+ *
+ * **語は輪の外 (膨らんだ先) に置く**。 輪の上に載せると曲線が語で隠れ、どちら回りかが読めない。
+ *
+ * 2 本以上ある時、輪は入れ子になる = 内側の輪の外は、外側の輪の **内側** にある。
+ * 輪ごとに「自分の外」 へ語を置くと、内側の語が外側の輪の上に載る。 語は全部
+ * **一番外の輪のさらに外** に揃えて置き、辺に沿って積んで語どうしの重なりを外す。
+ *
+ * 1 本だけの時は積む必要が無いので、辺の中央の真横に 1 つ置くだけになる。
+ */
+export function routeSelfLoopGroup(edges: CdlEdge[], node: LaidNode, side: Side): LaidEdge[] {
+  const horizontal = side === "left" || side === "right";
+  const g = sideGeometry(node, side);
+  const span = fitSpan(horizontal ? node.h : node.w, SELF_LOOP_SPAN);
+  const half = span / 2;
+  // 辺に沿った向き (出口 → 入口)。 横向きの辺なら上から下、縦向きの辺なら左から右
+  const 沿 = horizontal ? { x: 0, y: 1 } : { x: 1, y: 0 };
+
+  // 制御点は曲線より外にあるので、path から囲みを起こす検査は輪を実寸より大きく見る。
+  // 語はその外側に置く = 大きめに見た囲みとも重ならない
+  const 最外 = controlOffset(SELF_LOOP_OUT + (edges.length - 1) * SELF_LOOP_STAGGER);
+  const 語まで = 最外 + LABEL_TO_PATH_CLEARANCE;
+
+  // 積む向きの語の大きさ。 横の辺なら縦に積むので高さ、縦の辺なら横に積むので幅
+  const 語幅 = edges.map((e) =>
+    horizontal ? labelPillH(e.sub) : computeLabelBoxW(e.label, e.sub),
+  );
+  const 位置: number[] = [];
+  let 積 = 0;
+  for (const w of 語幅) {
+    位置.push(積 + w / 2);
+    積 += w + CLEARANCE_LABEL_LABEL;
+  }
+  const 全長 = Math.max(0, 積 - CLEARANCE_LABEL_LABEL);
+
+  return edges.map((edge, index) => {
+    const c = controlOffset(SELF_LOOP_OUT + index * SELF_LOOP_STAGGER);
+    const x1 = g.x - 沿.x * half;
+    const y1 = g.y - 沿.y * half;
+    const x2 = g.x + 沿.x * half;
+    const y2 = g.y + 沿.y * half;
+    const ずれ = 位置[index]! - 全長 / 2;
+    return {
+      ...edge,
+      d: `M ${x1} ${y1} C ${x1 + g.ux * c} ${y1 + g.uy * c} ${x2 + g.ux * c} ${y2 + g.uy * c} ${x2} ${y2}`,
+      fromSide: side,
+      toSide: side,
+      labelX: g.x + g.ux * 語まで + 沿.x * ずれ + (edge.labelOffsetX ?? 0),
+      labelY: g.y + g.uy * 語まで + 沿.y * ずれ + (edge.labelOffsetY ?? 0),
+      labelAnchor: side === "left" ? "end" : side === "right" ? "start" : "middle",
+    } satisfies LaidEdge;
+  });
+}
+
+/** その辺が自分から自分へ戻るか */
+export function isSelfLoop(e: { from: string; to: string }): boolean {
+  return e.from === e.to;
+}
+
+/**
+ * 図の中の輪をまとめて経路にする。
+ *
+ * 同じ節・同じ辺に 2 本以上あると重なるので、その並びの中の順番を渡して外へずらす。
+ * 節が見つからない辺は **落とさずに投げる** = 黙って消すと、書いたのに描かれない線になる。
+ *
+ * @param occupiedBySide 節ごとに、輪でない線が使っている辺。 これを渡さないと輪が既存の線に重なる
+ */
+export function layoutSelfLoops(
+  edges: CdlEdge[],
+  nodes: Map<string, LaidNode>,
+  occupiedBySide: ReadonlyMap<string, ReadonlySet<Side>>,
+): LaidEdge[] {
+  // 辺の割り当ては節ごとに 1 度で決める。 輪を 1 本ずつ処理して選び直すと、2 本目が
+  // 1 本目の辺を「空いている」 と見て同じ場所に重なる
+  const 割当 = new Map<string, Side[]>();
+  for (const edge of edges) {
+    if (edge.side) continue;
+    const list = 割当.get(edge.from) ?? [];
+    list.push("right");
+    割当.set(edge.from, list);
+  }
+  for (const [nodeId, list] of 割当) {
+    割当.set(nodeId, pickFreeSides(occupiedBySide.get(nodeId), list.length));
+  }
+  const 消費 = new Map<string, number>();
+
+  const 束 = new Map<string, { node: LaidNode; side: Side; edges: CdlEdge[] }>();
+  for (const edge of edges) {
+    const node = nodes.get(edge.from);
+    if (!node) throw new Error(`cdl layout: edge "${edge.id}" の from "${edge.from}" が node に無い`);
+    let side = edge.side;
+    if (!side) {
+      const i = 消費.get(edge.from) ?? 0;
+      消費.set(edge.from, i + 1);
+      side = 割当.get(edge.from)![i]!;
+    }
+    const key = `${edge.from}::${side}`;
+    const 既 = 束.get(key);
+    if (既) 既.edges.push(edge);
+    else 束.set(key, { node, side, edges: [edge] });
+  }
+  // 語の置き場所は束の中の並びで決まるので、束ごとにまとめて経路にする。
+  // 返す並びは呼出側が id で引き直すため、ここでは束の順で構わない
+  return [...束.values()].flatMap((b) => routeSelfLoopGroup(b.edges, b.node, b.side));
+}

package/src/layout/spec.ts

@@ -62,9 +62,10 @@ export function hasRenderedLabel(e: { label?: string; sub?: string }): boolean {
 /**
  * `title` を文字として描かない node の種別。
  *
- * 2 群ある。 形だけを描く `dyn-*` 5 種は `DynShapeNode` に回り、 `node.title` を一度も参照しない
+ * 3 群ある。 形だけを描く `dyn-*` 5 種は `DynShapeNode` に回り、 `node.title` を一度も参照しない
  * (描くのは形と数値の小さな label だけ)。 payload を自前 layout する chart / timeline / analytic
- * 10 種は、 描くのが payload 側の label で `title` は使わない。
+ * 10 種は、 描くのが payload 側の label で `title` は使わない。 流れの始まりと終わりの印 2 種は
+ * 印そのものが意味を持ち、 丸の中に名前を入れても読めない (#560)。
  *
  * 一覧は手で持つと描画側とずれるため、 `test/node-title-render.test.tsx` が `NODE_KINDS` を
  * **全件 render** して「title の文字が出るか」 と本述語の返り値の一致を検査する。 新しい種別を
@@ -81,12 +82,20 @@ const KINDS_WITHOUT_TITLE_TEXT: ReadonlySet<string> = new Set([
   "chart-pie",
   "chart-line",
   "chart-bar",
+  "chart-gauge",
+  "chart-radial",
+  "chart-stat",
+  "chart-waffle",
+  "chart-stacked-bar",
   "gantt-timeline",
   "mind-map",
   "funnel-stages",
   "quadrant-matrix",
   "tree-hierarchy",
   "journey-map",
+  // 印そのものが意味を持つ (#560)
+  "mark-start",
+  "mark-end",
 ]);
 
 /**
@@ -189,7 +198,45 @@ export function rowBaselineY(kind: string | undefined, index: number): number |
   if (!rendersRows(kind)) return null;
   return kind === "storage"
     ? ROW_TOP_STORAGE + index * ROW_PITCH_STORAGE
-    : ROW_TOP_GENERIC + index * ROW_PITCH_GENERIC;
+    : ROW_TOP_GENERIC + genericTextShift(kind) + index * ROW_PITCH_GENERIC;
+}
+
+/**
+ * `kinds/generic.tsx` が字の塊を下へずらす量 (SSOT)。
+ *
+ * 円柱は上の楕円 (ry=14) の内側に字を置けないため、題も行もこの分だけ下がる。
+ * **題と行が同じ値を引く** = 別々に持つと片方だけ動いて重なる (#558 で実際に重なっていた)。
+ */
+export function genericTextShift(kind: string | undefined): number {
+  return KINDS_SHAPE_CYLINDER.has(kind ?? "") ? GENERIC_TEXT_SHIFT_CYLINDER : 0;
+}
+
+/** 円柱で描く種別。 `kinds/generic.tsx` の `STYLES` が持つ形と 1 対 1 で対応する */
+const KINDS_SHAPE_CYLINDER: ReadonlySet<string> = new Set(["database"]);
+
+/** 中央に字を寄せる種別 (`cloud` / `decision`)。 同じく `STYLES` の形と対応する */
+const KINDS_TEXT_CENTERED: ReadonlySet<string> = new Set(["cloud", "decision"]);
+
+/**
+ * その node が字を中央へ寄せるか (SSOT)。
+ *
+ * **行を持つ時は寄せない**。 題を箱の中心に置くと、上端から数える行 (`ROW_TOP_GENERIC`) と
+ * 必ず重なる = 中心に題を置いたまま行を並べる場所が無い。 行がある時だけ上揃えに落とす。
+ */
+export function genericTextCentered(kind: string | undefined, hasRows: boolean): boolean {
+  return !hasRows && KINDS_TEXT_CENTERED.has(kind ?? "");
+}
+
+/**
+ * `kinds/generic.tsx` の題の baseline (SSOT)。
+ *
+ * 中央寄せの時だけ箱の高さに依るので `h` を受ける。 検査軸 (`title-row-overlap`) が
+ * 行との間隔を測るために同じ関数を引く。
+ */
+export function genericTitleBaselineY(kind: string | undefined, h: number, hasRows: boolean): number {
+  return genericTextCentered(kind, hasRows)
+    ? h / 2 + GENERIC_TITLE_CENTER_OFFSET
+    : GENERIC_TITLE_TOP + genericTextShift(kind);
 }
 
 /** `kinds/storage.tsx` の 1 行目 baseline と行送り。 */
@@ -200,6 +247,25 @@ export const ROW_PITCH_STORAGE = 56;
 export const ROW_TOP_GENERIC = 100;
 export const ROW_PITCH_GENERIC = 28;
 
+/** 円柱で字の塊を下へずらす量。 上の楕円 (ry=14) の内側を避ける */
+export const GENERIC_TEXT_SHIFT_CYLINDER = 28;
+
+/** `kinds/generic.tsx` の上揃え時の題の baseline と、中央寄せ時の中心からの差 */
+export const GENERIC_TITLE_TOP = 68;
+export const GENERIC_TITLE_CENTER_OFFSET = 4;
+
+/** `kinds/generic.tsx` の題の字の大きさ。 題の字形がどこまで下へ出るかの見積もりに使う */
+export const GENERIC_TITLE_FONT = 20;
+
+/**
+ * 字形の上端を baseline から何割上と **見込むか** (cap 高さの目安)。
+ *
+ * `STORAGE_ROW_DIVIDER_Y` が区切り線の位置を出すのに使っていた 0.72 を、
+ * 題と行の間隔を見る軸 (`title-row-overlap`) と共有する。 別々に持つと片方だけ動く。
+ */
+export const GLYPH_CAP_RATIO = 0.72;
+
+
 /**
  * 行の文字寸法。 `kinds/storage.tsx` は 26px、 `kinds/generic.tsx` は左 18px / 右 21px。
  * descender の見積もりには大きい方を使う。
@@ -220,7 +286,7 @@ export const STORAGE_TITLE_BASELINE = 78;
  * 1 行目の字形の上端は baseline から font size の 0.72 倍だけ上と見込む (cap 高さの目安)。
  */
 export const STORAGE_ROW_DIVIDER_Y = Math.round(
-  (STORAGE_TITLE_BASELINE + (ROW_TOP_STORAGE - ROW_FONT_STORAGE * 0.72)) / 2,
+  (STORAGE_TITLE_BASELINE + (ROW_TOP_STORAGE - ROW_FONT_STORAGE * GLYPH_CAP_RATIO)) / 2,
 );
 
 /**
@@ -242,6 +308,17 @@ export const STORAGE_ROW_DIVIDER_Y = Math.round(
  */
 export const ROW_GLYPH_DEPTH_RATIO = 0.4;
 
+/**
+ * 題の字形の下端と 1 行目の字形の上端が触れないために要ると **見込む** 間隔。
+ *
+ * 題は下へ `GENERIC_TITLE_FONT * ROW_GLYPH_DEPTH_RATIO`、行は上へ
+ * `ROW_FONT_GENERIC * GLYPH_CAP_RATIO` 伸びると見込む。 その和を下限にする。
+ *
+ * 仮定の範囲は `ROW_GLYPH_DEPTH_RATIO` の説明と同じ = preset が出す文字の範囲を押さえる。
+ */
+export const TITLE_ROW_MIN_GAP =
+  GENERIC_TITLE_FONT * ROW_GLYPH_DEPTH_RATIO + ROW_FONT_GENERIC * GLYPH_CAP_RATIO;
+
 /**
  * 最終行の baseline から下に、 字形が枠に触れないために要ると **見込む** 量。
  *

package/src/layout/tokens.ts

@@ -52,6 +52,16 @@ export const TOKENS = {
     "chart-line": { w: 640, h: 360 },
     "chart-pie": { w: 640, h: 320 },
     "chart-bar": { w: 640, h: 360 },
+    // 上半分の弧 + 下段の内訳。 弧が浅いぶん pie より低くて済む (cdl#549)
+    "chart-gauge": { w: 640, h: 320 },
+    // 左に一覧 + 右に同心の弧。 件数ぶん内側へ重なるので pie と同じ高さを取る (cdl#550)
+    "chart-radial": { w: 640, h: 320 },
+    // 件ごとに区画を割り、名前 / 数値 / 弧 / 割合 を縦に積む。 数値を大きく組むので縦が要る (cdl#553)
+    "chart-stat": { w: 640, h: 320 },
+    // 左に一覧 + 右に 10x10 の格子。 格子が正方形なので pie と同じ高さで足りる (cdl#552)
+    "chart-waffle": { w: 640, h: 320 },
+    // 帯を最大 2 本 + 下に一覧。 縦は帯 2 本ぶんで足りる (cdl#551)
+    "chart-stacked-bar": { w: 640, h: 320 },
     // Timeline / Mind 系 (CAR-994 Phase B)
     "gantt-timeline": { w: 720, h: 360 },
     "mind-map": { w: 720, h: 480 },
@@ -123,6 +133,11 @@ export const TOKENS = {
     "shape-lawyer": { w: 280, h: 300 },
     "shape-trader": { w: 300, h: 300 },
     "shape-customer-service": { w: 320, h: 300 },
+    // 流れの始まりと終わりの印 2 種 (#560) ... 正方形にして丸が縦横どちらにも歪まないようにする。
+    // 印は箱いっぱいに描く (線が箱の縁で止まるため) ので、この値が丸の直径になる。
+    // 箱としての最小 (80x40) より大きく、名前を持つ箱 (card 320x150) よりは明らかに小さい
+    "mark-start": { w: 96, h: 96 },
+    "mark-end": { w: 96, h: 96 },
   } as Record<NodeKind, { w: number; h: number }>,
 
   // row gap (stack 間の vertical gap、 lane 内 / 跨ぎ共通)