@cardenelabs/cdl 0.16.0 → 0.17.0

package/src/presets.ts

@@ -2,7 +2,16 @@ import { diagram } from "./builder";
 import type { DiagramBuilder } from "./builder";
 import { LANE_PAD_MIN, NODE_SIZE } from "./layout/tokens";
 import { requiredRowsWidth } from "./kinds/row-align";
-import type { NodeKind, Tone, EdgeStyle, EdgeHead, JourneyEmotion, QuadrantKey, BoundNumber } from "./types";
+import {
+  sequenceBoardMetrics,
+  sequenceStepId,
+  type SequenceBoardActor,
+  type SequenceBoardBand,
+  type SequenceBoardData,
+  type SequenceBoardMessage,
+  type SequenceBoardMessageKind,
+} from "./kinds/sequence-board-metrics";
+import type { NodeKind, Tone, EdgeStyle, EdgeHead, EdgeHeadFill, RowMark, JourneyEmotion, QuadrantKey, BoundNumber } from "./types";
 
 /**
  * 状態を読む書き方 (`{名前}`)。
@@ -348,6 +357,30 @@ export function flow(preset: FlowPreset): FlowBuilder {
 
 // ─── sequence (UML sequence diagram 風) ────────────────────────
 
+/**
+ * 言づての種類 (#578)。 **形で 3 つを分ける**。
+ *
+ * | 種類 | 線 | 印 | 意味 |
+ * |---|---|---|---|
+ * | `call` | 実線 | 塗った矢 | 相手にやらせて待つ |
+ * | `return` | 破線 | 開いた矢 | 呼ばれた側から戻る。 新しい仕事ではないので線を切る |
+ * | `fire` | 実線 | 開いた矢 | 返事を待たない。 実線だが矢を閉じないことで待たないと示す |
+ *
+ * 印の形はクラス図の「継ぐ」 と「結ぶ」 で使った形そのもの。 **意味は違う** (あちらは親を
+ * 指す / こちらは返事を待つか) が、形の並びは共有できる。
+ */
+export type SequenceMessageKind = "call" | "return" | "fire";
+
+/** 言づての種類ごとの見た目 (#578)。 種類を足すと 3 つとも要る */
+export const SEQUENCE_MESSAGE_LOOK: Record<
+  SequenceMessageKind,
+  { style: EdgeStyle; head: EdgeHead }
+> = {
+  call: { style: "solid", head: "triangle" },
+  return: { style: "dashed", head: "open" },
+  fire: { style: "solid", head: "open" },
+};
+
 export type SequenceStep = {
   /** from actor id (or label slug) */
   from: string;
@@ -359,13 +392,28 @@ export type SequenceStep = {
   sub?: string;
   tone?: Tone;
   style?: EdgeStyle;
+  /**
+   * 言づての種類 (#578)。 書くと線と印がまとめて決まる (`SEQUENCE_MESSAGE_LOOK`)。
+   *
+   * `style` / `head` を個別に書けばそちらが勝つ。
+   */
+  kind?: SequenceMessageKind;
+  /** 端の形 (#578)。 書かなければ `kind` から決まり、それも無ければ既定の塗った三角 */
+  head?: EdgeHead;
+};
+
+/** 参加者 1 人。 名前だけの文字列でも書ける (#578) */
+export type SequenceActor = {
+  name: string;
+  /** 名前の下に置く日本語の呼び名 (例 "画面" / "受付" / "台帳") */
+  subtitle?: string;
 };
 
 export type SequencePreset = {
   id: string;
   topic: string;
-  /** actor label の配列 (lifeline、 column 単位) */
-  actors: string[];
+  /** actor label の配列 (lifeline、 column 単位)。 呼び名を添えるなら物で書く (#578) */
+  actors: readonly (string | SequenceActor)[];
   /** actor の lane width (default 220) */
   laneWidth?: number;
   /** lane gap (default 60) */
@@ -374,6 +422,13 @@ export type SequencePreset = {
   defaultTone?: Tone;
   /** default edge style (default solid) */
   defaultStyle?: EdgeStyle;
+  /**
+   * 動いている間の帯 (#578)。 段の番号で区間を書く。
+   *
+   * 書かなければ面ごとに「最初に関わった段から最後まで」 の 1 本。 途中で手が空く面を分けたい
+   * 図だけ書く = どこで手が空くかは言づての並びからは決まらない
+   */
+  bands?: readonly { actor: string; from: number; to: number }[];
 };
 
 export type SequenceBuilder = {
@@ -395,84 +450,75 @@ export type SequenceBuilder = {
  *   .build();
  */
 export function sequence(preset: SequencePreset): SequenceBuilder {
-  const laneW = preset.laneWidth ?? 340;
   const tone: Tone = preset.defaultTone ?? "accent";
-  const style: EdgeStyle = preset.defaultStyle ?? "solid";
   const b = diagram(preset.id, { topic: preset.topic });
 
-  // actor 名 → slug id の map
-  const actorIds = new Map<string, string>();
-  const headerNodeIds: string[] = [];
-  preset.actors.forEach((label, i) => {
-    const id = slugify(label) || `actor-${i}`;
-    actorIds.set(label, id);
-    actorIds.set(id, id);
-    b.lane(id, { width: laneW, label, lifeline: true });
-    // 各 lane 先頭に actor header (kind=card) を stack=0 で配置
-    // header/footer 幅を title 長に応じて auto-size (text-readability warning 解消)。
-    // formula = 22px/char + 52px padding (visualValidate text-readability と完全一致)、 min 140 で従来 sample 互換維持。
-    // visualValidate text-readability formula (titleLen * 22 + 52) と完全一致で
-// warning suppress、 ASCII long name (AuthenticationService 21 char) は 514 になり
-// 過大化との trade-off だが 「警告出るのに対応できない」 の user feedback 優先。
-const actorW = Math.max(140, label.length * 22 + 52);
-    const headerId = `${id}-header`;
-    b.node(headerId, { lane: id, stack: 0, kind: "card", title: label, w: actorW, h: 72 });
-    headerNodeIds.push(headerId);
-    // header と最初の step の間に dummy spacer node を挟む (stack=1、 step は stack=2 から)
-    const spacerId = `${id}-spacer`;
-    b.node(spacerId, { lane: id, stack: 1, kind: "card", title: "", w: 2, h: 40 });
+  // 名前だけの文字列と、呼び名を添えた物の両方を受ける (#578)
+  const 面々: SequenceBoardActor[] = preset.actors.map((a) =>
+    typeof a === "string" ? { name: a } : { name: a.name, ...(a.subtitle ? { subtitle: a.subtitle } : {}) },
+  );
+  const 番号 = new Map<string, number>();
+  面々.forEach((a, i) => {
+    番号.set(a.name, i);
+    番号.set(slugify(a.name) || `actor-${i}`, i);
   });
 
-  const phaseActivate: string[] = [...headerNodeIds];
-  let stepIdx = 0;
-  const stepBoxIds: Array<{ from: string; to: string; stack: number }> = [];
+  const 言づて: SequenceBoardMessage[] = [];
+  const 語 = new Map<number, string>();
 
   const api: SequenceBuilder = {
-    step(s) {
-      const fromLaneId = actorIds.get(s.from) ?? s.from;
-      const toLaneId = actorIds.get(s.to) ?? s.to;
-      const stack = stepIdx + 2; // stack=0 は header、 stack=1 は spacer、 step は 2 から
-      // from / to lane に それぞれ invisible activation box (kind=card、 title="") を配置
-      const fromBoxId = `s${stepIdx}-${fromLaneId}`;
-      const toBoxId = `s${stepIdx}-${toLaneId}`;
-      // activation marker (lifeline 上に置く小点)、 edge anchor 用。 w=h=2 で視覚上ほぼ非表示
-      b.node(fromBoxId, { lane: fromLaneId, stack, kind: "card", title: "", w: 2, h: 2 });
-      if (fromLaneId !== toLaneId) {
-        b.node(toBoxId, { lane: toLaneId, stack, kind: "card", title: "", w: 2, h: 2 });
-      }
-      const edgeId = `e${stepIdx}-${fromLaneId}-${toLaneId}`;
-      b.edge(fromBoxId, fromLaneId === toLaneId ? fromBoxId : toBoxId, {
-        id: edgeId,
-        label: s.label,
-        ...(s.sub ? { sub: s.sub } : {}),
-        tone: s.tone ?? tone,
-        style: s.style ?? style,
-      });
-      stepBoxIds.push({ from: fromBoxId, to: toBoxId, stack });
-      phaseActivate.push(fromBoxId);
-      if (fromLaneId !== toLaneId) phaseActivate.push(toBoxId);
-      phaseActivate.push(edgeId);
-      stepIdx += 1;
+    step(s2) {
+      const from = 番号.get(s2.from) ?? 0;
+      const to = 番号.get(s2.to) ?? 0;
+      // 種類を書かない図は **線の種類から読む** (#578)。 点線で書いてあるものは返し、
+      // それ以外は呼び。 既存の図をそのまま新しい骨格へ移すための経路
+      const kind: SequenceBoardMessageKind =
+        s2.kind ?? ((s2.style ?? preset.defaultStyle) === "dotted-flow" ? "return" : "call");
+      言づて.push({ label: s2.label, from, to, kind });
+      if (s2.sub) 語.set(言づて.length - 1, s2.sub);
       return api;
     },
     build() {
-      // 下端 footer ... UML sequence 標準どおり、 各 lifeline 末尾に header と同 box を再描画
-      const footerStack = stepIdx + 2; // 最終 step (stepIdx + 1 の stack) の次 stack
-      preset.actors.forEach((label) => {
-        const laneId = actorIds.get(label) ?? slugify(label);
-        const footerId = `${laneId}-footer`;
-        // visualValidate text-readability formula (titleLen * 22 + 52) と完全一致で
-// warning suppress、 ASCII long name (AuthenticationService 21 char) は 514 になり
-// 過大化との trade-off だが 「警告出るのに対応できない」 の user feedback 優先。
-const actorW = Math.max(140, label.length * 22 + 52);
-        // `role` を付けるのは、 描画側が「どれが下端の名札か」 を位置で推測しないため (#458)
-        b.node(footerId, { lane: laneId, stack: footerStack, kind: "card", title: label, w: actorW, h: 72, role: "lifeline-footer" });
-        phaseActivate.push(footerId);
+      /*
+       * 動いている間の帯 (#578)。
+       *
+       * 書かない図では **最初に関わった段から最後まで** を 1 本にする。 途中で手が空く面を
+       * 分けたい図は `bands` に区間を書く = どこで手が空くかは言づての並びからは決まらない
+       * (返しを受けて終わるのか、後でまた呼ばれるのかが読めない)。
+       */
+      const 帯: SequenceBoardBand[] = preset.bands
+        ? preset.bands.map((x) => ({ actor: 番号.get(x.actor) ?? 0, from: x.from, to: x.to }))
+        : 面々
+            .map((_, i) => {
+              const 出番 = 言づて
+                .map((m, idx) => (m.from === i || m.to === i ? idx : -1))
+                .filter((idx) => idx >= 0);
+              return 出番.length > 0
+                ? { actor: i, from: 出番[0]!, to: 出番[出番.length - 1]! }
+                : null;
+            })
+            .filter((x): x is SequenceBoardBand => x !== null);
+
+      const data: SequenceBoardData = { actors: 面々, messages: 言づて, bands: 帯 };
+      const m = sequenceBoardMetrics(data);
+      const laneId = "seq";
+      b.lane(laneId, { width: m.w + LANE_PAD_MIN * 2 });
+      b.node(preset.id, {
+        lane: laneId,
+        stack: 0,
+        kind: "sequence-board",
+        w: m.w,
+        h: m.h,
+        title: "",
+        sequenceData: data,
+        // 段が進むと濃さが移る。 書かない図では全部を濃く出す
+        sequenceStep: `{${sequenceStepId()}}`,
+        tone,
       });
       b.phase(
-        "seq",
+        "sequence",
         { duration: 2400, title: preset.topic, body: "sequence の全 message を時系列展開。" },
-        (p) => p.activate(...phaseActivate).badge("sequence"),
+        (p) => p.activate(preset.id).badge("sequence"),
       );
       return b.build();
     },
@@ -619,23 +665,90 @@ export function topology(preset: TopologyPreset): TopologyBuilder {
 
 // ─── er (ER 図 / Entity Relationship) ─────────────────────────
 
+/**
+ * 表の列 1 つ (#578)。 行頭の印の 2 軸を、ER の意味に割り当てる。
+ *
+ * | 印 | 意味 |
+ * |---|---|
+ * | 四角を塗る | 空にできないただの列 |
+ * | 四角の外枠だけ | 空を許す列 |
+ * | 山形を塗る | 外を指す列で、相手が必ずいる |
+ * | 山形の外枠だけ | 外を指すが、指さないこともある |
+ *
+ * 主キーは **名前の下線**。 印の 2 軸は埋まっているので、3 つ目の軸を印に足すと 4 通りが
+ * 8 通りになって見分けが付かなくなる。 下線は別の段に載るので、外部キーの山形と重ねられる。
+ */
+export type ErColumn = {
+  name: string;
+  /** 型 (例 "bigint" / "timestamptz")。 箱の右端に薄く右揃えで出る */
+  type: string;
+  /** 外を指す列か (外部キー)。 書かなければただの値 */
+  fk?: boolean;
+  /** 空を許すか。 書かなければ空にできない */
+  optional?: boolean;
+  /** 主キーの一部か。 書くと名前に下線が付き、**鍵の群**として上にまとめられる */
+  pk?: boolean;
+};
+
 export type ErEntity = {
   id: string;
   /** entity 名 (例 "User") */
   title: string;
-  /** 列定義 (例 "id: PK", "email: string", "userId: FK") */
-  rows: string[];
+  /** 表の名前の下に置く日本語の呼び名 (#578)。 `columns` を書いた時だけ出る */
+  subtitle?: string;
+  /**
+   * 列定義 (例 "id: PK", "email: string", "userId: FK")。
+   *
+   * **`columns` を書いた実体では読まない**。 印を付けるには列の意味が要り、字からは導けない
+   * (`"userId: FK"` の `FK` は型の欄に書かれた語であって、外を指すという宣言ではない)。
+   */
+  rows?: string[];
+  /** 列を印つきで書く形 (#578)。 書くと設計の意匠 (行頭の印 + 右端の薄い型) で出る */
+  columns?: ErColumn[];
 };
 
 export type ErRelationCardinality = "1:1" | "1:N" | "N:1" | "N:M" | "0..1" | "1..*";
 
+/**
+ * 個数の書き方から **両端の印** を決める表 (#578)。
+ *
+ * 出どころ側と行き先側で別の印が立つ。 `1:N` なら出どころが「ちょうど 1 つ」、行き先が
+ * 「少なくとも 1 つ」。 端ごとに書きたい図は `tailHead` / `head` で個別に上書きする。
+ */
+export const ER_CARDINALITY_HEAD: Record<
+  ErRelationCardinality,
+  { tail: EdgeHead; head: EdgeHead }
+> = {
+  "1:1": { tail: "one", head: "one" },
+  "1:N": { tail: "one", head: "many" },
+  "N:1": { tail: "many", head: "one" },
+  "N:M": { tail: "many", head: "many" },
+  "0..1": { tail: "one", head: "zero-one" },
+  "1..*": { tail: "one", head: "many" },
+};
+
 export type ErRelation = {
   from: string;
   to: string;
-  cardinality: ErRelationCardinality;
+  /**
+   * 個数。 書かなければ端の印を `tailHead` / `head` で個別に書く。
+   *
+   * 書いた場合は端の印の既定になり、`label` と併せて書いた時だけ字としても出る。
+   */
+  cardinality?: ErRelationCardinality;
   /** 関係名 (例 "places", "belongs_to") */
   label?: string;
   tone?: Tone;
+  /** 出どころ側の端の印 (#578)。 書かなければ `cardinality` から決まる */
+  tailHead?: EdgeHead;
+  /** 行き先側の端の印 (#578)。 書かなければ `cardinality` から決まる */
+  head?: EdgeHead;
+  /**
+   * 線の種類 (#578)。 実線 = 親の鍵が子の鍵に入る (識別する) / 破線 = 子は自分の鍵を持つ。
+   *
+   * 書かなければ実線。
+   */
+  style?: EdgeStyle;
 };
 
 export type ErPreset = {
@@ -681,9 +794,31 @@ export function er(preset: ErPreset): ErBuilder {
   const api: ErBuilder = {
     entity(e) {
       const laneId = `lane-${e.id}`;
+      // 鍵の群を上にまとめ、間を空の行 1 つで開ける (#578)。 区切りの線を引く代わりに余白で
+      // 分けるので、`rowMarks` を持つ箱では描き手が線を引かない
+      const 鍵 = (e.columns ?? []).filter((c) => c.pk === true);
+      const 値 = (e.columns ?? []).filter((c) => c.pk !== true);
+      const 行: string[] = [];
+      const 印: (RowMark | null)[] = [];
+      const 足す = (c: ErColumn): void => {
+        行.push(`${c.name}: ${c.type}`);
+        印.push({
+          shape: c.fk === true ? "chevron" : "square",
+          filled: c.optional !== true,
+          ...(c.pk === true ? { underline: true } : {}),
+        });
+      };
+      鍵.forEach(足す);
+      if (鍵.length > 0 && 値.length > 0) {
+        行.push("");
+        印.push(null);
+      }
+      値.forEach(足す);
+      const 設計の形 = 行.length > 0;
+      const rows = 設計の形 ? 行 : (e.rows ?? []);
       // 帯は実体ごとに決める。 行の長さで箱が広がる実体があるため、 全実体を同じ帯幅で
       // 宣言すると宣言座標と実座標がずれる。
-      const boxW = fitRowsWidth(entityW, e.rows);
+      const boxW = fitRowsWidth(entityW, rows);
       b.lane(laneId, { width: boxLaneW(boxW) });
       b.node(e.id, {
         lane: laneId,
@@ -691,8 +826,12 @@ export function er(preset: ErPreset): ErBuilder {
         kind: "storage",
         w: boxW,
         title: e.title,
-        eyebrow: "エンティティ",
-        rows: e.rows,
+        // 種類の札は設計の形では出さない (#578)。 「エンティティ」 と書いた札は全ての箱に
+        // 同じ字が並ぶだけで、代わりに表の呼び名を題の下へ置く
+        ...(設計の形 ? {} : { eyebrow: "エンティティ" }),
+        ...(設計の形 && e.subtitle ? { subtitle: e.subtitle } : {}),
+        rows,
+        ...(設計の形 ? { rowMarks: 印 } : {}),
       });
       entities.push(e.id);
       phaseActivate.push(e.id);
@@ -701,8 +840,12 @@ export function er(preset: ErPreset): ErBuilder {
     relation(r) {
       const currentIdx = relIdx++;
       const edgeId = `rel-${currentIdx}-${r.from}-${r.to}`;
-      const label = r.label ?? r.cardinality;
-      const sub = r.label ? r.cardinality : undefined;
+      const label = r.label ?? r.cardinality ?? "";
+      // 個数を字でも出すのは **端の印を書かなかった時だけ** (#578)。 印が個数を示すので、
+      // 両方出すと同じことを 2 回言うことになる
+      const 印が示す = r.tailHead !== undefined || r.head !== undefined;
+      const sub = r.label && r.cardinality && !印が示す ? r.cardinality : undefined;
+      const 既定 = r.cardinality ? ER_CARDINALITY_HEAD[r.cardinality] : undefined;
       // ER 図の relation label は entity 上に配置 (path 短く entity 隣接なので矢印との視覚関連が強い)。
       // CAR-430 で label-shift.ts の shift 探索を削除、 edges.ts routePath() init 位置が SSOT。
       // overlap 発生時は post-pass 2 の resolveEdgeLabelOverlapsWithChain が chain 伝搬で解消する。
@@ -711,7 +854,10 @@ export function er(preset: ErPreset): ErBuilder {
         label,
         ...(sub ? { sub } : {}),
         tone: r.tone ?? tone,
-        style: "solid",
+        style: r.style ?? "solid",
+        // 端の印は両端に立つ (#578)。 箱に近い側が個数、その外側が任意か
+        ...(r.head ?? 既定?.head ? { head: r.head ?? 既定!.head } : {}),
+        ...(r.tailHead ?? 既定?.tail ? { tailHead: r.tailHead ?? 既定!.tail } : {}),
       });
       phaseActivate.push(edgeId);
       return api;
@@ -731,6 +877,29 @@ export function er(preset: ErPreset): ErBuilder {
 
 // ─── stateMachine (FSM / Workflow) ────────────────────────────
 
+/**
+ * 状態の中身 1 行 (#578)。 **いつ動くか** の 4 つを、行頭の印の 2 軸に載せる。
+ *
+ * | いつ | 印 |
+ * |---|---|
+ * | `entry` (入る時) | 山形を塗る |
+ * | `exit` (出る時) | 山形の外枠だけ |
+ * | `do` (いる間) | 四角を塗る |
+ * | `internal` (中で受ける) | 四角の外枠だけ |
+ *
+ * 割り当ては「山形 = 出入りの瞬間 / 四角 = 状態の中」「塗り = 続く・入る側 / 外枠 = 瞬間・出る側」。
+ *
+ * **4 つは元々 2 軸に割れていない**。 それでも 2 軸に載せたのは、読み手がクラス図と ER 図で
+ * 覚えた見分け方をそのまま使える方が、正しく分類することより効くと判断したため。
+ */
+export type FsmStateAction = {
+  when: "entry" | "exit" | "do" | "internal";
+  /** すること (例 "在庫を押さえる") */
+  label: string;
+  /** 添え (例 "7 日ごと")。 箱の右端に薄く右揃えで出る */
+  note?: string;
+};
+
 export type FsmState = {
   id: string;
   title: string;
@@ -738,6 +907,47 @@ export type FsmState = {
   initial?: boolean;
   /** final state (複数可) */
   final?: boolean;
+  /** 名前の下に置く日本語の呼び名 (#578) */
+  subtitle?: string;
+  /** 状態の中身 (#578)。 書くと設計の意匠 (行頭の印 + 右端の薄い添え) で出る */
+  actions?: FsmStateAction[];
+  /**
+   * 格子の列 (#578)。 書かなければ **宣言した順に横 1 列** で、従来どおり。
+   *
+   * 1 つでも書いた図は格子に置く。
+   */
+  col?: number;
+  /** 格子の段 (#578)。 `col` と対で書く */
+  row?: number;
+};
+
+/**
+ * 箱ではない節点 (#578)。 始まりは塗った丸、終わりは輪で囲んだ丸。
+ *
+ * **箱として扱えない**。 始まりと終わりは行も名前も持たないので、箱にすると題も呼び名も空で
+ * 寸法が出せない。 描画側は種別 (`mark-start` / `mark-end`) を持っており、そちらを使う。
+ */
+/**
+ * 箱ではない節点の大きさ (#578)。 印は箱の短い辺いっぱいに描かれる (`markRadius`) ので、
+ * ここが丸の直径になる。 状態の箱より十分小さく、線の先が触れる大きさ。
+ */
+export const MARK_BOX = 96;
+
+export type FsmMark = {
+  id: string;
+  kind: "start" | "end";
+  /** 格子の列。 状態と同じ格子に載る */
+  col?: number;
+  /** 格子の段 */
+  row?: number;
+};
+
+/** 状態の中身の「いつ」 から行頭の印を引く表 (#578) */
+export const FSM_ACTION_MARK: Record<FsmStateAction["when"], RowMark> = {
+  entry: { shape: "chevron", filled: true },
+  exit: { shape: "chevron", filled: false },
+  do: { shape: "square", filled: true },
+  internal: { shape: "square", filled: false },
 };
 
 export type FsmTransition = {
@@ -748,6 +958,13 @@ export type FsmTransition = {
   /** guard 条件 (例 "if validated") */
   guard?: string;
   tone?: Tone;
+  /**
+   * 端の形 (#578)。 書かなければ **開いた矢**。
+   *
+   * 状態遷移の線は 1 種類しかない = クラス図は 6 種、ER 図は端 4 種 × 線 2 種あるのに、
+   * ここでは線と印が分かれない。 違いは語の中 (`きっかけ` または `きっかけ [条件]`) に入る。
+   */
+  head?: EdgeHead;
 };
 
 export type StateMachinePreset = {
@@ -769,6 +986,8 @@ export type StateMachinePreset = {
 
 export type StateMachineBuilder = {
   state: (s: FsmState) => StateMachineBuilder;
+  /** 箱ではない節点 (始まり / 終わり) を置く (#578) */
+  mark: (m: FsmMark) => StateMachineBuilder;
   transition: (t: FsmTransition) => StateMachineBuilder;
   build: () => ReturnType<DiagramBuilder["build"]>;
 };
@@ -792,55 +1011,133 @@ export type StateMachineBuilder = {
  */
 export function stateMachine(preset: StateMachinePreset): StateMachineBuilder {
   const stateW = resolveStateW(preset.stateWidth, "stateMachine");
-  const laneW = boxLaneW(stateW);
   const tone: Tone = preset.defaultTone ?? "accent";
   const b = diagram(preset.id, { topic: preset.topic });
 
   const phaseActivate: string[] = [];
-  let transIdx = 0;
   const stateOrder = new Map<string, number>();
+  // 状態と節点は **溜めてから** 組む (#578)。 格子に置く図では、列の帯幅がその列の全ての箱を
+  // 見ないと決まらない
+  const 状態: FsmState[] = [];
+  const 節点: FsmMark[] = [];
+  const 遷移: FsmTransition[] = [];
+  /**
+   * 書いた順 (#578)。 状態と節点を別々に溜めると、箱の並びが「節点が先、状態が後」 に
+   * 固定される = 記法から同じ図を書いた時に並びが合わない (実測)。
+   */
+  const 並び: { 種: "状態" | "節点"; i: number }[] = [];
 
   const api: StateMachineBuilder = {
     state(s) {
-      const laneId = `lane-${s.id}`;
-      b.lane(laneId, { width: laneW });
-      const eyebrow = s.initial ? "初期" : s.final ? "最終" : "状態";
-      b.node(s.id, {
-        lane: laneId,
-        stack: 0,
-        kind: "card",
-        w: stateW,
-        title: s.title,
-        eyebrow,
-      });
+      並び.push({ 種: "状態", i: 状態.length });
+      状態.push(s);
       stateOrder.set(s.id, stateOrder.size);
-      phaseActivate.push(s.id);
+      return api;
+    },
+    mark(m) {
+      並び.push({ 種: "節点", i: 節点.length });
+      節点.push(m);
+      // 節点も並びに数える (#578)。 数えないと、節点へ向かう遷移が「前へ戻る」 と判定されて
+      // 上へ迂回する (実測 = `Paid → 終わり` が図の上へ伸びた)
+      stateOrder.set(m.id, stateOrder.size);
       return api;
     },
     transition(t) {
-      const currentIdx = transIdx++;
-      const edgeId = `t${currentIdx}-${t.from}-${t.to}`;
-      // back transition (state idx 後ろ → 前) は side=top で node 上端から出させ、
-      // 上方経路で detour させて forward path と重ならないようにする。
-      // CAR-468 SSOT ... 旧 labelOffsetY = isBack ? -200 : ±170 (label を強制的に上下シフト) を廃止、
-      // 全 transition で labelOffsetY = 0 とし routePath() の SSOT init 位置 (LABEL_INIT_CLEARANCE=34、 CAR-630 で 26 → 34 復帰) を
-      // そのまま採用する。 複数 transition の label 分散は engine 側 parallel / fan-in / fan-out logic
-      // (PARALLEL_STEP_Y=52 / FAN_STEP=40 in edges.ts) と post-pass 2 chain shift が担当する。
-      const fromIdx = stateOrder.get(t.from) ?? 0;
-      const toIdx = stateOrder.get(t.to) ?? 0;
-      const isBack = toIdx < fromIdx;
-      b.edge(t.from, t.to, {
-        id: edgeId,
-        label: t.trigger,
-        ...(t.guard ? { sub: t.guard } : {}),
-        tone: t.tone ?? tone,
-        style: "solid",
-        ...(isBack ? { routing: "back-detour" as const } : {}),
-      });
-      phaseActivate.push(edgeId);
+      遷移.push(t);
       return api;
     },
     build() {
+      // 設計の形かは **中身を書いたか** で決める (#578)。 書かない図は従来どおり card の
+      // 横 1 列で、1 画素も変わらない
+      const 設計の形 = 状態.some((s) => s.actions !== undefined || s.subtitle !== undefined)
+        || 節点.length > 0;
+      const 格子 = 状態.some((s) => s.col !== undefined) || 節点.some((m) => m.col !== undefined);
+
+      const 中身 = 状態.map((s) => {
+        const 行 = (s.actions ?? []).map((a) => (a.note ? `${a.label}: ${a.note}` : a.label));
+        const 印 = (s.actions ?? []).map((a) => FSM_ACTION_MARK[a.when]);
+        const laneId = 格子 && s.col !== undefined ? `col-${s.col}` : `lane-${s.id}`;
+        const boxW = 設計の形 ? fitRowsWidth(stateW, 行) : stateW;
+        return { s, 行, 印, laneId, boxW, stack: 格子 ? (s.row ?? 0) : 0 };
+      });
+      const 節点の中身 = 節点.map((m) => ({
+        m,
+        laneId: 格子 && m.col !== undefined ? `col-${m.col}` : `lane-${m.id}`,
+        stack: 格子 ? (m.row ?? 0) : 0,
+      }));
+
+      // 帯は **その列でいちばん広い箱** に合わせる
+      const 帯幅 = new Map<string, number>();
+      for (const c of 中身) 帯幅.set(c.laneId, Math.max(帯幅.get(c.laneId) ?? 0, c.boxW));
+      for (const c of 節点の中身) 帯幅.set(c.laneId, Math.max(帯幅.get(c.laneId) ?? 0, MARK_BOX));
+      const 済 = new Set<string>();
+      const 帯を作る = (laneId: string): void => {
+        if (済.has(laneId)) return;
+        済.add(laneId);
+        b.lane(laneId, { width: boxLaneW(帯幅.get(laneId) ?? stateW) });
+      };
+      // 宣言の順で帯を作る = 帯の並びが図の列の並びになる。 節点も同じ格子に載る
+      for (const c of 節点の中身) if (c.stack === 0) 帯を作る(c.laneId);
+      for (const c of 中身) 帯を作る(c.laneId);
+      for (const c of 節点の中身) 帯を作る(c.laneId);
+
+      // 書いた順に置く。 節点と状態を分けて置くと、記法から同じ図を書いた時に並びが合わない
+      for (const o of 並び) {
+        if (o.種 === "節点") {
+          const c = 節点の中身[o.i]!;
+          b.node(c.m.id, {
+            lane: c.laneId,
+            stack: c.stack,
+            kind: c.m.kind === "start" ? "mark-start" : "mark-end",
+            w: MARK_BOX,
+            h: MARK_BOX,
+            title: "",
+          });
+          phaseActivate.push(c.m.id);
+          continue;
+        }
+        const c = 中身[o.i]!;
+        // 初期 / 最終の札は **節点を置いた図では出さない** (#578)。 印そのものが始まりと
+        // 終わりを示すので、札と二重になる
+        const eyebrow = 節点.length > 0
+          ? undefined
+          : c.s.initial ? "初期" : c.s.final ? "最終" : "状態";
+        b.node(c.s.id, {
+          lane: c.laneId,
+          stack: c.stack,
+          kind: 設計の形 ? "storage" : "card",
+          w: c.boxW,
+          title: c.s.title,
+          ...(eyebrow ? { eyebrow } : {}),
+          ...(c.s.subtitle ? { subtitle: c.s.subtitle } : {}),
+          // 行を持たない状態でも欄を書く (#578)。 書かないとその箱だけ従来の意匠に落ち、
+          // 呼び名が消える
+          ...(設計の形 ? { rows: c.行, rowMarks: c.印 } : {}),
+        });
+        phaseActivate.push(c.s.id);
+      }
+
+      遷移.forEach((t, currentIdx) => {
+        const edgeId = `t${currentIdx}-${t.from}-${t.to}`;
+        // back transition (state idx 後ろ → 前) は side=top で node 上端から出させ、
+        // 上方経路で detour させて forward path と重ならないようにする。
+        // CAR-468 SSOT ... label の分散は engine 側 (LABEL_INIT_CLEARANCE + fan offset) に一任する
+        const fromIdx = stateOrder.get(t.from) ?? 0;
+        const toIdx = stateOrder.get(t.to) ?? 0;
+        const isBack = toIdx < fromIdx;
+        b.edge(t.from, t.to, {
+          id: edgeId,
+          label: t.trigger,
+          ...(t.guard ? { sub: t.guard } : {}),
+          tone: t.tone ?? tone,
+          style: "solid",
+          // 遷移の印は 1 種類だけ = 実線に開いた矢 (#578)。 線と印が分かれず、違いは語の中に入る
+          head: t.head ?? "open",
+          ...(isBack ? { routing: "back-detour" as const } : {}),
+        });
+        phaseActivate.push(edgeId);
+      });
+
       b.phase(
         "fsm",
         { duration: 2400, title: preset.topic, body: "FSM の全 state + transition を visible 化。" },
@@ -982,33 +1279,74 @@ export function infrastructure(preset: InfrastructurePreset): InfrastructureBuil
 
 // ─── classDiagram (UML class + attribute / method / relation) ─
 
-export type ClassRelationType = "extends" | "implements" | "uses" | "aggregates" | "composes";
+export type ClassRelationType =
+  | "extends"
+  | "implements"
+  | "uses"
+  | "aggregates"
+  | "composes"
+  | "associates";
 
 /**
- * 関係の種類ごとの端の形 (cdl#574)。
+ * 関係の 6 種の見た目 (cdl#574 / #578)。
  *
- * `#560` で足した端の形は「関係の種類を示す」 ためのもので、この preset が第一の使い手。
- * 表にしないと 5 種とも同じ塗った三角になり、線の種類と語だけで区別することになる。
+ * **線 / 印の形 / 印の塗り / 印が付く側** の 4 つで見分ける。 覚え方は 3 つとも 1 行で言える。
  *
- * | 種類 | 形 | 意味 |
- * |---|---|---|
- * | `extends` / `implements` | 三角 | 継ぐ |
- * | `aggregates` / `composes` | 菱 | 持つ |
- * | `uses` | 開いた矢 | 使う |
+ * - **線** ... 実線 = そのものを持っている / 破線 = 約束と一時の使用
+ * - **印** ... 三角 = 上下の関係 / 菱 = 所有 / 開いた矢 = 向きだけ
+ * - **側** ... 印は「その印が指すもの」 の箱に付く
  *
- * **`extends` と `implements` が同じ形になるのは意図**。 UML では線の種類 (実線 / 破線) で
- * 分ける決まりで、端の形は「継ぐ」 を表す 1 種しかない。 `aggregates` と `composes` も同様に
- * 塗りの有無で分けるので、端の形は同じ菱になる。
+ * | 種類 | 線 | 形 | 塗り | 側 | 意味 |
+ * |---|---|---|---|---|---|
+ * | `extends` | 実線 | 三角 | 白抜き | 行き先 | 継ぐ |
+ * | `implements` | 破線 | 三角 | 白抜き | 行き先 | 満たす |
+ * | `aggregates` | 実線 | 菱 | 白抜き | 出どころ | 持つ |
+ * | `composes` | 実線 | 菱 | 塗る | 出どころ | 抱える |
+ * | `associates` | 実線 | 開いた矢 | — | 行き先 | 結ぶ |
+ * | `uses` | 破線 | 開いた矢 | — | 行き先 | 使う |
  *
- * `Record<ClassRelationType, EdgeHead>` なので、種類を足すと形も要る。
+ * **側が種で割れるのが要点**。 三角は「この先が親」 を指すので行き先に立ち、菱は
+ * 「この箱が持っている」 を指すので出どころに立つ。 1 つの決まりで書こうとするとどちらかが
+ * 必ず逆になり、菱を逆に置くと **持ち主が入れ替わって読める**。
+ *
+ * `Record<ClassRelationType, ...>` なので、種類を足すと 4 つとも要る。
  */
-export const CLASS_RELATION_HEAD: Record<ClassRelationType, EdgeHead> = {
-  extends: "triangle",
-  implements: "triangle",
-  uses: "open",
-  aggregates: "diamond",
-  composes: "diamond",
-};
+export const CLASS_RELATION_LOOK: Record<
+  ClassRelationType,
+  { head: EdgeHead; fill: EdgeHeadFill; tailHead: EdgeHead; tailFill: EdgeHeadFill; style: EdgeStyle }
+> = {
+  extends: { head: "triangle", fill: "hollow", tailHead: "none", tailFill: "solid", style: "solid" },
+  implements: { head: "triangle", fill: "hollow", tailHead: "none", tailFill: "solid", style: "dashed" },
+  aggregates: { head: "none", fill: "solid", tailHead: "diamond", tailFill: "hollow", style: "solid" },
+  composes: { head: "none", fill: "solid", tailHead: "diamond", tailFill: "solid", style: "solid" },
+  associates: { head: "open", fill: "solid", tailHead: "none", tailFill: "solid", style: "solid" },
+  uses: { head: "open", fill: "solid", tailHead: "none", tailFill: "solid", style: "dashed" },
+};
+
+/** 端の形だけを引く経路 (cdl#574 からの名前を残す)。 実体は `CLASS_RELATION_LOOK` */
+export const CLASS_RELATION_HEAD: Record<ClassRelationType, EdgeHead> = Object.fromEntries(
+  Object.entries(CLASS_RELATION_LOOK).map(([k, v]) => [k, v.head]),
+) as Record<ClassRelationType, EdgeHead>;
+
+/**
+ * 公開かどうかを行の頭 1 文字で見る (#578)。 `+` = 公開 / `-` = 非公開 / `#` = 継いだ先まで。
+ *
+ * **書かなければ公開**。 UML の既定に合わせる = 印は塗った側で出る。
+ */
+function isPublic(row: string): boolean {
+  return !row.startsWith("-") && !row.startsWith("#");
+}
+
+/**
+ * 行から公開の記号と呼び出しの括弧を落とす (#578)。
+ *
+ * どちらも **印が担う**ようになったので字では書かない = `+` と `-` は印の塗りが、
+ * `()` は印の形 (山形) が示す。 残すと同じことを 2 回言うことになり、名前の左端も揃わない。
+ */
+function stripAccess(row: string): string {
+  const 本体 = isPublic(row) && !row.startsWith("+") ? row : row.slice(1);
+  return 本体.replace("()", "");
+}
 
 export type UmlClass = {
   id: string;
@@ -1019,6 +1357,15 @@ export type UmlClass = {
   methods?: string[];
   /** stereotype (例 "abstract" / "interface" / "trait") */
   stereotype?: string;
+  /**
+   * 格子の列 (#578)。 書かなければ **宣言した順に横 1 列** で、従来どおり。
+   *
+   * 1 つでも書いた図は格子に置く。 **箱の 1 つの辺には関係を 1 本しか載せられない**ので、
+   * 関係が 3 本以上ある箱を持つ図は段に分けないと線が重なる。
+   */
+  col?: number;
+  /** 格子の段 (#578)。 `col` と対で書く */
+  row?: number;
 };
 
 export type UmlRelation = {
@@ -1031,11 +1378,17 @@ export type UmlRelation = {
   cardinality?: string;
   tone?: Tone;
   /**
-   * 矢印の先の形 (cdl#574)。 書かなければ種類から決まる (`CLASS_RELATION_HEAD`)。
+   * 矢印の先の形 (cdl#574)。 書かなければ種類から決まる (`CLASS_RELATION_LOOK`)。
    *
    * **書いた形が勝つ**。 表と違う形にしたい関係だけを個別に書ける。
    */
   head?: EdgeHead;
+  /** 端の印の塗り (#578)。 書かなければ種類から決まる */
+  headFill?: EdgeHeadFill;
+  /** 出どころ側の端の印 (#578)。 書かなければ種類から決まる */
+  tailHead?: EdgeHead;
+  /** 線の種類 (#578)。 書かなければ種類から決まる */
+  style?: EdgeStyle;
 };
 
 export type ClassDiagramPreset = {
@@ -1074,66 +1427,93 @@ export function classDiagram(preset: ClassDiagramPreset): ClassDiagramBuilder {
 
   const classes: string[] = [];
   const phaseActivate: string[] = [];
-  let relIdx = 0;
+  // 箱と関係は **溜めてから** 組む (#578)。 格子に置く図では、列の帯幅がその列の全ての箱を
+  // 見ないと決まらない = 1 件目を見た時点で `b.lane` を呼ぶと、後から来た広い箱に合わせられない
+  const 箱: UmlClass[] = [];
+  const 関係: UmlRelation[] = [];
 
   const api: ClassDiagramBuilder = {
     class(c) {
-      const laneId = `lane-${c.id}`;
-      // UML クラスは attributes と methods を区切って表示。
-      // v10.5 = 旧 separator "─".repeat(20) は 20 chars × 14px = 280 world で node w 強制拡張、
-      // class-demo の viewBox scale 5.2 倍化で label 過小化の root cause。 separator を短い
-      // "───" (3 chars) に短縮、 視覚区切りは維持しつつ node w 拡張を抑制する。
-      const rows: string[] = [];
-      if (c.attributes && c.attributes.length > 0) {
-        rows.push(...c.attributes);
-      }
-      if (c.methods && c.methods.length > 0) {
-        if (rows.length > 0) rows.push("───");
-        rows.push(...c.methods);
-      }
-      // 帯はクラスごとに決める。 行の長さで箱が広がるクラスがあるため、 全クラスを同じ帯幅で
-      // 宣言すると宣言座標と実座標がずれる。
-      const boxW = fitRowsWidth(classW, rows);
-      b.lane(laneId, { width: boxLaneW(boxW) });
-      b.node(c.id, {
-        lane: laneId,
-        stack: 0,
-        kind: "storage",
-        w: boxW,
-        title: c.title,
-        eyebrow: c.stereotype ?? "クラス",
-        ...(rows.length > 0 ? { rows } : {}),
-      });
-      classes.push(c.id);
-      phaseActivate.push(c.id);
+      箱.push(c);
       return api;
     },
     relation(r) {
-      const currentIdx = relIdx++;
-      const edgeId = `cr-${currentIdx}-${r.from}-${r.to}`;
-      const label = r.label ?? r.type;
-      const sub = r.cardinality;
-      b.edge(r.from, r.to, {
-        id: edgeId,
-        label,
-        ...(sub ? { sub } : {}),
-        tone: r.tone ?? tone,
-        style: "solid",
-        // 関係の種類から端の形を決める (cdl#574)。 書いた形が勝つ
-        head: r.head ?? CLASS_RELATION_HEAD[r.type],
-        // CAR-531 SSOT ... 旧実装は `labelOffsetY: currentIdx % 2 === 0 ? -60 : 60` で
-        // 複数 relation label の path 沿い集中を強制分散していた。 CAR-430 で導入した
-        // engine 側 fan offset (FAN_STEP 40 world) が同 from / to 群を自動分散する現在、
-        // author 指定 ±60 は engine 分散と二重発火して extends label が SSOT
-        // LABEL_INIT_CLEARANCE (34、 CAR-630 で 26 → 34 復帰) を大幅に超える 114 world 離れる bug の直接原因になっていた。
-        // author 指定 offset を削除、 engine 側の LABEL_INIT_CLEARANCE + fan offset に一任する。
-        // 個別 relation で offset を再導入したい author は future extension (UmlRelation に
-        // labelOffsetY? を追加) で明示的に指定する経路を残す。
-      });
-      phaseActivate.push(edgeId);
+      関係.push(r);
       return api;
     },
     build() {
+      // 行頭の印で持ち物と振る舞いを分ける (#578)。 群の間は **空の行** で開ける = 区切りの
+      // 線を引く代わりに余白で分ける。 印を持つ行は描き手が線を引かない
+      const 中身 = 箱.map((c) => {
+        const rows: string[] = [];
+        const rowMarks: (RowMark | null)[] = [];
+        for (const a of c.attributes ?? []) {
+          rows.push(stripAccess(a));
+          rowMarks.push({ shape: "square", filled: isPublic(a) });
+        }
+        if ((c.attributes?.length ?? 0) > 0 && (c.methods?.length ?? 0) > 0) {
+          rows.push("");
+          rowMarks.push(null);
+        }
+        for (const m of c.methods ?? []) {
+          rows.push(stripAccess(m));
+          rowMarks.push({ shape: "chevron", filled: isPublic(m) });
+        }
+        // 帯はクラスごとに決める。 行の長さで箱が広がるクラスがあるため、 全クラスを同じ帯幅で
+        // 宣言すると宣言座標と実座標がずれる。
+        const boxW = fitRowsWidth(classW, rows);
+        // 格子に置くかは `col` を書いたかで決める (#578)。 書かない図は従来どおり横 1 列
+        const laneId = c.col !== undefined ? `col-${c.col}` : `lane-${c.id}`;
+        return { c, rows, rowMarks, boxW, laneId, stack: c.col !== undefined ? (c.row ?? 0) : 0 };
+      });
+
+      // 帯は **その列でいちばん広い箱** に合わせる。 狭い方に合わせると宣言座標と実座標がずれる
+      const 帯幅 = new Map<string, number>();
+      for (const m of 中身) 帯幅.set(m.laneId, Math.max(帯幅.get(m.laneId) ?? 0, m.boxW));
+      // 宣言の順で帯を作る。 帯の並びが図の列の並びになる
+      const 済 = new Set<string>();
+      for (const m of 中身) {
+        if (済.has(m.laneId)) continue;
+        済.add(m.laneId);
+        b.lane(m.laneId, { width: boxLaneW(帯幅.get(m.laneId) ?? m.boxW) });
+      }
+
+      for (const m of 中身) {
+        b.node(m.c.id, {
+          lane: m.laneId,
+          stack: m.stack,
+          kind: "storage",
+          w: m.boxW,
+          title: m.c.title,
+          // 種類の札は **書いた時だけ** 出す (#578)。 「クラス」 と書いた札は箱がクラスで
+          // あることしか言わず、図の中の全ての箱に同じ字が並ぶ
+          ...(m.c.stereotype ? { eyebrow: m.c.stereotype } : {}),
+          ...(m.rows.length > 0 ? { rows: m.rows, rowMarks: m.rowMarks } : {}),
+        });
+        classes.push(m.c.id);
+        phaseActivate.push(m.c.id);
+      }
+
+      関係.forEach((r, currentIdx) => {
+        const edgeId = `cr-${currentIdx}-${r.from}-${r.to}`;
+        const 見た目 = CLASS_RELATION_LOOK[r.type];
+        b.edge(r.from, r.to, {
+          id: edgeId,
+          label: r.label ?? r.type,
+          ...(r.cardinality ? { sub: r.cardinality } : {}),
+          tone: r.tone ?? tone,
+          // 関係の種類から線と端の形を決める (cdl#574 / #578)。 書いた値が勝つ
+          style: r.style ?? 見た目.style,
+          head: r.head ?? 見た目.head,
+          headFill: r.headFill ?? 見た目.fill,
+          tailHead: r.tailHead ?? 見た目.tailHead,
+          tailHeadFill: 見た目.tailFill,
+          // CAR-531 SSOT ... label の分散は engine 側 (LABEL_INIT_CLEARANCE + fan offset) に
+          // 一任する。 author 指定 ±60 は engine 分散と二重発火して label が大きく離れる
+        });
+        phaseActivate.push(edgeId);
+      });
+
       b.phase(
         "class",
         { duration: 2400, title: preset.topic, body: "UML class 全 class + relation を visible 化。" },