@cardenelabs/cdl 0.5.0

package/src/presets.ts

@@ -0,0 +1,2108 @@
+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 } from "./types";
+
+/**
+ * 図の格子の目 (world unit)。 `grid-alignment` (軸 21) が見る単位と同じ。
+ */
+const GRID_UNIT = 16;
+
+/**
+ * 箱を格子 (16 world) に載せるための帯の幅。
+ *
+ * engine は帯を「箱の幅 + 余白 25 × 2」 まで広げ、 箱を帯の中心に置く。 箱の左端は
+ * `(帯の幅 - 箱の幅) / 2` = 片側の余白そのものなので、 **片側の余白を 16 の倍数に切り上げる**
+ * と左端が格子に載る。 帯の幅を 32 の倍数にするだけでは足りない (箱の幅が 32 の倍数とは
+ * 限らないため、 例 560 では左端が 40 になる)。
+ *
+ * engine の再拡張値 (`箱の幅 + 25 × 2`) より広くなるので、 engine は帯を広げ直さない。
+ * 片側の増分は 32 - 25 = 7 world。
+ */
+function gridAlignedLaneW(canvasW: number): number {
+  const padPerSide = Math.ceil(LANE_PAD_MIN / GRID_UNIT) * GRID_UNIT;
+  return canvasW + padPerSide * 2;
+}
+
+/**
+ * 箱の寸法を格子 (16 world) に合わせて切り上げる。
+ *
+ * `grid-alignment` は箱の 4 辺が格子に載ることを見る。 左上を格子に置いても、 幅や高さが
+ * 16 の倍数でなければ右下が外れる。 著者が `itemWidth` / `stageWidth` に任意の値を渡せる
+ * ため、 組み立て器の側で丸める。
+ *
+ * 切り上げるのは、 縮めると中身の描画領域が指定より狭くなるため。 増分は 16 world 未満。
+ */
+function toGridSize(v: number): number {
+  return Math.ceil(v / GRID_UNIT) * GRID_UNIT;
+}
+
+/**
+ * 状態遷移図の状態 1 個の既定幅 (world unit)。
+ *
+ * `kind: "card"` の既定幅そのものを使う。 `stateWidth` を指定しなければ、
+ * 状態の箱は card の既定と同じ大きさで描かれる。 token 側が変われば追従する。
+ */
+const DEFAULT_STATE_W = NODE_SIZE.card.w;
+
+/**
+ * 状態の箱として受け付ける最小幅 (world unit)。
+ *
+ * これを下回ると描画側が壊れる。 幅 10 未満の箱は `CardNode` が中身を描かずに抜け、
+ * 幅 80 未満は `node-visibility` 軸が「小さすぎて見えない」 と判定する。
+ * 左右の余白 26 × 2 を引いた残りが文字の置き場所になるので、 80 でも題名は数文字しか入らない。
+ */
+const MIN_NODE_BOX_W = 80;
+
+/**
+ * `stateWidth` を検証して返す。 未指定なら既定幅。
+ *
+ * 旧実装では不正な値を渡しても帯の幅にしか渡らず、 engine が箱の幅から帯を広げ直すため
+ * 実害が出なかった。 箱の幅として使うようになった以上、 描画が壊れる値は入口で弾く。
+ *
+ * @throws 有限でない値、 または最小幅を下回る値
+ */
+function resolveStateW(stateWidth: number | undefined, presetName: string): number {
+  if (stateWidth === undefined) return DEFAULT_STATE_W;
+  if (!Number.isFinite(stateWidth)) {
+    throw new Error(`cdl ${presetName}: stateWidth は有限の数値である必要があります (受け取った値 = ${stateWidth})`);
+  }
+  if (stateWidth < MIN_NODE_BOX_W) {
+    throw new Error(
+      `cdl ${presetName}: stateWidth は ${MIN_NODE_BOX_W} 以上である必要があります (受け取った値 = ${stateWidth})`,
+    );
+  }
+  return stateWidth;
+}
+
+/**
+ * 状態の箱を収める帯の幅を返す。
+ *
+ * engine は帯を「箱の幅 + 余白 × 2」 まで広げるので、 宣言も同じ式にしておく。 狭く宣言すると
+ * engine が広げて後続の帯を右へずらし、 宣言座標と実座標がずれる。
+ *
+ * 余白は `LANE_PAD_MIN` を下限として、 実際には隣の帯との間隔から逆算される
+ * (`layout/lanes.ts` の `padFor`)。 preset が作る帯は x を明示しないので間隔は既定の 80 になり、
+ * 余白は下限の 25 に落ち着く。 著者が `viewport.laneGap` を 80 より小さく指定した図では
+ * 余白がこれを超え、 engine が帯を追加で広げる。 その場合も配置の安全性は engine が保つが、
+ * 宣言幅と実幅は一致しなくなる = 本 helper が返すのは「既定の間隔での幅」。
+ */
+function boxLaneW(stateW: number): number {
+  return stateW + LANE_PAD_MIN * 2;
+}
+
+/**
+ * 表形式の箱 (`kind: "storage"`) 1 個の既定幅 (world unit)。
+ *
+ * ER 図の実体とクラス図のクラスが使う。 `storage` の既定幅そのものを取るので、 token 側が
+ * 変われば追従する。
+ */
+const DEFAULT_STORAGE_BOX_W = NODE_SIZE.storage.w;
+
+
+/**
+ * 箱の幅を指す option を検証して返す。 未指定なら既定幅。
+ *
+ * 旧実装では不正な値を渡しても帯の幅にしか渡らず、 engine が箱の幅から帯を広げ直すため
+ * 実害が出なかった。 箱の幅として使うようになった以上、 描画が壊れる値は入口で弾く。
+ *
+ * @throws 有限でない値、 または最小幅を下回る値
+ */
+function resolveStorageBoxW(width: number | undefined, presetName: string, optionName: string): number {
+  if (width === undefined) return DEFAULT_STORAGE_BOX_W;
+  if (!Number.isFinite(width)) {
+    throw new Error(`cdl ${presetName}: ${optionName} は有限の数値である必要があります (受け取った値 = ${width})`);
+  }
+  if (width < MIN_NODE_BOX_W) {
+    throw new Error(
+      `cdl ${presetName}: ${optionName} は ${MIN_NODE_BOX_W} 以上である必要があります (受け取った値 = ${width})`,
+    );
+  }
+  return width;
+}
+
+/**
+ * 行 (`rows`) が収まるところまで箱の幅を広げる。
+ *
+ * 箱の幅を明示しない node は `autoRowsWidth` (`layout/nodes.ts`) が行の実寸まで広げてくれるが、
+ * **`w` を明示した時点でその経路は止まる** (`if (n.w != null) return n.w;`)。 preset が幅を
+ * 指定するようになった以上、 同じ拡張を preset 側で行わないと長い行が箱からはみ出す。
+ *
+ * 指定値は下限として扱う。 「指定した幅より狭くならない」 は守り、 中身が入らない時だけ広げる。
+ * 例外にしない理由は、 著者が行の実寸を事前に計算できないため (font の送り幅に依存する)。
+ */
+function fitRowsWidth(boxW: number, rows: readonly string[] | undefined): number {
+  // 呼出は `er` の実体と `classDiagram` のクラスの 2 箇所で、 どちらも `kind: "storage"` を作る。
+  // 送り幅と列間は種別で違うため、 どの種別として測るかを渡す
+  return Math.max(boxW, requiredRowsWidth(rows ? [...rows] : undefined, "storage"));
+}
+
+/**
+ * 高位 API ... 著者が「lane / node / edge を 1 件ずつ宣言」 する低位 API を簡略化。
+ *
+ * - swimlane({ id, topic, lanes: ["送信元", "コントラクト", "出力"] }) で 3 lane 自動配置
+ * - flow().step("A", "func").step("B", "storage").build() で sequence diagram 風
+ */
+
+// ─── swimlane ──────────────────────────────────────────────────
+
+export type SwimlanePreset = {
+  id: string;
+  topic: string;
+  /** lane label の配列。 各 lane width は固定 (default 400)、 x は auto-layout */
+  lanes: string[];
+  /** lane width (default 400) */
+  laneWidth?: number;
+  /** 各 lane が枠囲み contain か (default false、 true で全 lane contain) */
+  contain?: boolean;
+};
+
+/**
+ * 横並び 複数 lane を 1 行で生成する preset。
+ * 著者は lane label のみ指定、 x / width は engine が自動配置。
+ *
+ * @example
+ * swimlane({ id: "tx", topic: "Tx Flow", lanes: ["送信元", "Contract", "出力"] })
+ *   .node("client", { lane: "send-mototo", stack: 0, kind: "actor", title: "Client" })  // lane id は label を slug 化
+ *   ...
+ */
+/** swimlane の戻り値 ... DiagramBuilder + 各 lane の slug id を取得する getter */
+export type SwimlaneResult = DiagramBuilder & {
+  /** lane label から自動生成された slug id を返す (label 順 0-indexed) */
+  laneId: (indexOrLabel: number | string) => string;
+};
+
+export function swimlane(preset: SwimlanePreset): SwimlaneResult {
+  const w = preset.laneWidth ?? 400;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const labelToId = new Map<string, string>();
+  const idsInOrder: string[] = [];
+  for (const label of preset.lanes) {
+    const id = slugify(label) || `lane-${idsInOrder.length}`;
+    labelToId.set(label, id);
+    idsInOrder.push(id);
+    b.lane(id, { width: w, label, ...(preset.contain ? { contain: true } : {}) });
+  }
+  const result = b as SwimlaneResult;
+  result.laneId = (indexOrLabel) => {
+    if (typeof indexOrLabel === "number") {
+      return idsInOrder[indexOrLabel] ?? "";
+    }
+    return labelToId.get(indexOrLabel) ?? indexOrLabel;
+  };
+  return result;
+}
+
+// ─── flow (sequence diagram 風) ────────────────────────────────
+
+export type FlowStepInput = {
+  id: string;
+  kind: NodeKind;
+  title: string;
+  eyebrow?: string;
+  subtitle?: string;
+};
+
+export type FlowPreset = {
+  id: string;
+  topic: string;
+  /** lane label (1 本のみ、 全 step が縦 stack で並ぶ) */
+  laneLabel?: string;
+  laneWidth?: number;
+  /** edge tone / style の default (各 step → next step の edge) */
+  defaultTone?: Tone;
+  defaultStyle?: EdgeStyle;
+};
+
+export type FlowBuilder = {
+  /** step を順番に追加、 自動で前 step から edge 接続 */
+  step: (node: FlowStepInput, edgeLabel?: string) => FlowBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * flow preset ... 1 lane に縦 stack で node を並べ、 前 step → 次 step の edge を auto 接続。
+ * sequence diagram 風 (mermaid `sequenceDiagram` の cdl 版)。
+ *
+ * @example
+ * flow({ id: "auth", topic: "Auth Flow" })
+ *   .step({ id: "user", kind: "person", title: "User" })
+ *   .step({ id: "api", kind: "api", title: "POST /login" }, "ログイン要求")
+ *   .step({ id: "db", kind: "database", title: "users 表" }, "credential 検証")
+ *   .build();
+ */
+export function flow(preset: FlowPreset): FlowBuilder {
+  const w = preset.laneWidth ?? 400;
+  const b = diagram(preset.id, { topic: preset.topic });
+  b.lane("flow", { width: w, ...(preset.laneLabel ? { label: preset.laneLabel } : {}) });
+  const tone: Tone = preset.defaultTone ?? "accent";
+  const style: EdgeStyle = preset.defaultStyle ?? "dotted-flow";
+  let prevId: string | null = null;
+  let stackIdx = 0;
+  const phaseActivate: string[] = [];
+
+  const api: FlowBuilder = {
+    step(node, edgeLabel) {
+      b.node(node.id, {
+        lane: "flow",
+        stack: stackIdx++,
+        kind: node.kind,
+        title: node.title,
+        ...(node.eyebrow ? { eyebrow: node.eyebrow } : {}),
+        ...(node.subtitle ? { subtitle: node.subtitle } : {}),
+      });
+      phaseActivate.push(node.id);
+      if (prevId !== null) {
+        const edgeId = `e-${prevId}-${node.id}`;
+        b.edge(prevId, node.id, {
+          id: edgeId,
+          label: edgeLabel ?? "→",
+          tone,
+          style,
+        });
+        phaseActivate.push(edgeId);
+      }
+      prevId = node.id;
+      return api;
+    },
+    build() {
+      b.phase(
+        "flow",
+        { duration: 2400, title: preset.topic, body: "全 step 順次実行。" },
+        (p) => p.activate(...phaseActivate).badge("flow"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── sequence (UML sequence diagram 風) ────────────────────────
+
+export type SequenceStep = {
+  /** from actor id (or label slug) */
+  from: string;
+  /** to actor id (or label slug) */
+  to: string;
+  /** message label */
+  label: string;
+  /** 補足 (2 行目、 例 ... POST /login の body 仕様等) */
+  sub?: string;
+  tone?: Tone;
+  style?: EdgeStyle;
+};
+
+export type SequencePreset = {
+  id: string;
+  topic: string;
+  /** actor label の配列 (lifeline、 column 単位) */
+  actors: string[];
+  /** actor の lane width (default 220) */
+  laneWidth?: number;
+  /** lane gap (default 60) */
+  laneGap?: number;
+  /** default edge tone (default accent) */
+  defaultTone?: Tone;
+  /** default edge style (default solid) */
+  defaultStyle?: EdgeStyle;
+};
+
+export type SequenceBuilder = {
+  /** message step を時系列順に追加、 from → to の水平 edge を引く */
+  step: (s: SequenceStep) => SequenceBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * sequence preset ... UML sequence diagram 風。 actors を column 化 (lifeline)、
+ * step({ from, to, label }) で時系列順に message edge を生成。
+ *
+ * @example
+ * sequence({ id: "auth-seq", topic: "Auth Sequence", actors: ["User", "API", "DB"] })
+ *   .step({ from: "User", to: "API", label: "POST /login" })
+ *   .step({ from: "API", to: "DB", label: "SELECT credentials" })
+ *   .step({ from: "DB", to: "API", label: "rows", tone: "success", style: "dotted-flow" })
+ *   .step({ from: "API", to: "User", label: "200 OK", tone: "success" })
+ *   .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 });
+  });
+
+  const phaseActivate: string[] = [...headerNodeIds];
+  let stepIdx = 0;
+  const stepBoxIds: Array<{ from: string; to: string; stack: number }> = [];
+
+  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;
+      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);
+        b.node(footerId, { lane: laneId, stack: footerStack, kind: "card", title: label, w: actorW, h: 72 });
+        phaseActivate.push(footerId);
+      });
+      b.phase(
+        "seq",
+        { duration: 2400, title: preset.topic, body: "sequence の全 message を時系列展開。" },
+        (p) => p.activate(...phaseActivate).badge("sequence"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── topology (構成図 / deployment) ───────────────────────────
+
+export type TopologyContainer = {
+  id: string;
+  kind: NodeKind;
+  title: string;
+  eyebrow?: string;
+};
+
+export type TopologyConnection = {
+  from: string;
+  to: string;
+  label: string;
+  sub?: string;
+  tone?: Tone;
+  style?: EdgeStyle;
+  labelOffsetX?: number;
+  labelOffsetY?: number;
+};
+
+export type TopologyPreset = {
+  id: string;
+  topic: string;
+  /** group の lane width (default 360) */
+  groupWidth?: number;
+  defaultTone?: Tone;
+  defaultStyle?: EdgeStyle;
+};
+
+export type TopologyGroupBuilder = {
+  add: (container: TopologyContainer) => TopologyGroupBuilder;
+};
+
+export type TopologyBuilder = {
+  group: (id: string, opts: { label: string }) => TopologyGroupBuilder;
+  connect: (
+    from: string,
+    to: string,
+    opts: { label: string; sub?: string; tone?: Tone; style?: EdgeStyle; labelOffsetX?: number; labelOffsetY?: number },
+  ) => TopologyBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * topology preset ... 構成図 / deployment diagram 風。
+ * group で container を囲む、 add で内部 element を配置、 connect で element 間 connection。
+ *
+ * @example
+ * topology({ id: "aws", topic: "AWS Deployment" })
+ *   .group("aws", { label: "AWS" })
+ *     .add({ id: "alb", kind: "service", title: "ALB" })
+ *     .add({ id: "ecs", kind: "service", title: "ECS Task" })
+ *     .add({ id: "rds", kind: "database", title: "RDS" })
+ *   .group("client", { label: "Client" })
+ *     .add({ id: "browser", kind: "frontend", title: "Browser" })
+ *   .connect("browser", "alb", { label: "HTTPS" })
+ *   .connect("alb", "ecs", { label: "round-robin" })
+ *   .connect("ecs", "rds", { label: "TCP 5432" })
+ *   .build();
+ */
+export function topology(preset: TopologyPreset): TopologyBuilder {
+  const groupW = preset.groupWidth ?? 460;
+  const tone: Tone = preset.defaultTone ?? "accent";
+  const style: EdgeStyle = preset.defaultStyle ?? "solid";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const groupOrder: string[] = [];
+  const groupStackCount = new Map<string, number>();
+  const phaseActivate: string[] = [];
+  let connIdx = 0;
+
+  const api: TopologyBuilder = {
+    group(groupId, opts) {
+      if (!groupOrder.includes(groupId)) {
+        groupOrder.push(groupId);
+        groupStackCount.set(groupId, 0);
+        b.lane(groupId, { width: groupW, label: opts.label, contain: true });
+      }
+      const groupApi: TopologyGroupBuilder = {
+        add(container) {
+          const stack = groupStackCount.get(groupId) ?? 0;
+          b.node(container.id, {
+            lane: groupId,
+            stack,
+            kind: container.kind,
+            title: container.title,
+            ...(container.eyebrow ? { eyebrow: container.eyebrow } : {}),
+          });
+          groupStackCount.set(groupId, stack + 1);
+          phaseActivate.push(container.id);
+          return groupApi;
+        },
+      };
+      return groupApi;
+    },
+    connect(from, to, opts) {
+      const currentIdx = connIdx++;
+      const edgeId = `c${currentIdx}-${from}-${to}`;
+      // CAR-559 SSOT ... 旧実装は `labelOffsetY: sameLane ? 0 : currentIdx % 2 === 0 ? 90 : -52`
+      // で lane 越え horizontal edge の label を強制的に上下シフトして overlap 解消していた。
+      // CAR-430 で engine 側 fan / parallel offset (PARALLEL_STEP_Y=52 / FAN_STEP=40 in edges.ts) +
+      // chain 伝搬 shift (resolveEdgeLabelOverlapsWithChainAndPropagate) が自動分散する現在、
+      // author 指定 ±90/-52 は engine 分散と二重発火して SSOT LABEL_INIT_CLEARANCE (26 + sub 分岐で
+      // 50) を大幅に上書き、 topology HTTPS edge (sub="TLS 1.3") で pill と edge の距離が
+      // LABEL_TO_PATH_CLEARANCE を変えても SSOT 通り動かず逆挙動する bug (label が edge より下に
+      // 落ちる + CLEARANCE 増加で gap 減少) の直接原因になっていた。
+      // CAR-531 (classDiagram の ±60 除去) と同じ方針で author 指定 offset を削除し、
+      // engine 側 SSOT (LABEL_INIT_CLEARANCE + fan offset + chain shift) に一任する。
+      // 個別 connection で offset を再導入したい author は opts.labelOffsetX/Y で明示的に指定する。
+      const labelOffsetX = opts.labelOffsetX ?? 0;
+      const labelOffsetY = opts.labelOffsetY ?? 0;
+      b.edge(from, to, {
+        id: edgeId,
+        label: opts.label,
+        ...(opts.sub ? { sub: opts.sub } : {}),
+        tone: opts.tone ?? tone,
+        style: opts.style ?? style,
+        labelOffsetX,
+        labelOffsetY,
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "topo",
+        { duration: 2400, title: preset.topic, body: "topology の全 container + connection を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("topology"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── er (ER 図 / Entity Relationship) ─────────────────────────
+
+export type ErEntity = {
+  id: string;
+  /** entity 名 (例 "User") */
+  title: string;
+  /** 列定義 (例 "id: PK", "email: string", "userId: FK") */
+  rows: string[];
+};
+
+export type ErRelationCardinality = "1:1" | "1:N" | "N:1" | "N:M" | "0..1" | "1..*";
+
+export type ErRelation = {
+  from: string;
+  to: string;
+  cardinality: ErRelationCardinality;
+  /** 関係名 (例 "places", "belongs_to") */
+  label?: string;
+  tone?: Tone;
+};
+
+export type ErPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  /**
+   * 実体 1 個の箱の幅 (world unit、 既定 = `storage` の既定幅)。
+   *
+   * 帯ではなく **箱** の幅。 帯は `箱の幅 + 余白 × 2` で宣言する (engine が帯を同じ式まで
+   * 広げるため、 狭く宣言すると宣言座標と実座標がずれる)。
+   */
+  entityWidth?: number;
+};
+
+export type ErBuilder = {
+  entity: (e: ErEntity) => ErBuilder;
+  relation: (r: ErRelation) => ErBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * er preset ... ER 図 (Entity Relationship)。 entity を table 風 node (rows 構造) で配置、
+ * relation を edge で接続、 cardinality は edge label に記法 (1:1 / 1:N / N:M / 0..1 / 1..*) で表記。
+ * mermaid ER 図の cdl 版。
+ *
+ * @example
+ * er({ id: "user-order", topic: "User-Order ER" })
+ *   .entity({ id: "user", title: "User", rows: ["id: PK", "email: string", "createdAt: timestamp"] })
+ *   .entity({ id: "order", title: "Order", rows: ["id: PK", "userId: FK", "total: number"] })
+ *   .relation({ from: "user", to: "order", cardinality: "1:N", label: "places" })
+ *   .build();
+ */
+export function er(preset: ErPreset): ErBuilder {
+  const entityW = resolveStorageBoxW(preset.entityWidth, "er", "entityWidth");
+  const tone: Tone = preset.defaultTone ?? "info";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const entities: string[] = [];
+  const phaseActivate: string[] = [];
+  let relIdx = 0;
+
+  const api: ErBuilder = {
+    entity(e) {
+      const laneId = `lane-${e.id}`;
+      // 帯は実体ごとに決める。 行の長さで箱が広がる実体があるため、 全実体を同じ帯幅で
+      // 宣言すると宣言座標と実座標がずれる。
+      const boxW = fitRowsWidth(entityW, e.rows);
+      b.lane(laneId, { width: boxLaneW(boxW) });
+      b.node(e.id, {
+        lane: laneId,
+        stack: 0,
+        kind: "storage",
+        w: boxW,
+        title: e.title,
+        eyebrow: "エンティティ",
+        rows: e.rows,
+      });
+      entities.push(e.id);
+      phaseActivate.push(e.id);
+      return api;
+    },
+    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;
+      // ER 図の relation label は entity 上に配置 (path 短く entity 隣接なので矢印との視覚関連が強い)。
+      // CAR-430 で label-shift.ts の shift 探索を削除、 edges.ts routePath() init 位置が SSOT。
+      // overlap 発生時は post-pass 2 の resolveEdgeLabelOverlapsWithChain が chain 伝搬で解消する。
+      b.edge(r.from, r.to, {
+        id: edgeId,
+        label,
+        ...(sub ? { sub } : {}),
+        tone: r.tone ?? tone,
+        style: "solid",
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "er",
+        { duration: 2400, title: preset.topic, body: "ER 図の全 entity + relation を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("er"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── stateMachine (FSM / Workflow) ────────────────────────────
+
+export type FsmState = {
+  id: string;
+  title: string;
+  /** initial state (1 つだけ) */
+  initial?: boolean;
+  /** final state (複数可) */
+  final?: boolean;
+};
+
+export type FsmTransition = {
+  from: string;
+  to: string;
+  /** 遷移 trigger (例 "submit" / "success" / "fail") */
+  trigger: string;
+  /** guard 条件 (例 "if validated") */
+  guard?: string;
+  tone?: Tone;
+};
+
+export type StateMachinePreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  /**
+   * 状態 1 個の箱の幅 (world unit、 既定 320 = card の既定幅)。
+   *
+   * 帯の幅ではなく **箱の幅** を指す。 帯は engine が「箱の幅 + 余白 × 2」 まで広げるので、
+   * 帯だけを狭く指定しても図は縮まない (#357 以前はここが帯にしか渡っておらず、
+   * 370 未満の指定が全て無視されていた)。
+   *
+   * 80 未満と有限でない値は例外を投げる。 箱の幅として使う以上、 描画が壊れる値を
+   * 黙って受け取らない。
+   */
+  stateWidth?: number;
+};
+
+export type StateMachineBuilder = {
+  state: (s: FsmState) => StateMachineBuilder;
+  transition: (t: FsmTransition) => StateMachineBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * stateMachine preset ... FSM (Finite State Machine) / workflow。
+ * state を card kind で配置、 transition を edge で接続、 trigger は edge label、 guard は sub。
+ * initial / final state は eyebrow + tone で識別表現。
+ *
+ * @example
+ * stateMachine({ id: "auth-fsm", topic: "Auth FSM" })
+ *   .state({ id: "idle", title: "Idle", initial: true })
+ *   .state({ id: "loading", title: "Loading" })
+ *   .state({ id: "done", title: "Done", final: true })
+ *   .state({ id: "error", title: "Error" })
+ *   .transition({ from: "idle", to: "loading", trigger: "submit" })
+ *   .transition({ from: "loading", to: "done", trigger: "success", tone: "success" })
+ *   .transition({ from: "loading", to: "error", trigger: "fail", tone: "error" })
+ *   .transition({ from: "error", to: "idle", trigger: "retry", guard: "if attempts < 3" })
+ *   .build();
+ */
+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>();
+
+  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,
+      });
+      stateOrder.set(s.id, stateOrder.size);
+      phaseActivate.push(s.id);
+      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);
+      return api;
+    },
+    build() {
+      b.phase(
+        "fsm",
+        { duration: 2400, title: preset.topic, body: "FSM の全 state + transition を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("fsm"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── infrastructure (cloud icon grid + connection) ────────────
+
+export type InfraNode = {
+  id: string;
+  kind: NodeKind;
+  title: string;
+  /** 表示位置 (col, row)、 0-indexed。 grid 上の配置を author が制御 */
+  col: number;
+  row: number;
+  subtitle?: string;
+  eyebrow?: string;
+};
+
+export type InfraConnection = {
+  from: string;
+  to: string;
+  label: string;
+  sub?: string;
+  tone?: Tone;
+  style?: EdgeStyle;
+  /** label の水平方向 fine offset (default 0)、 preset 交互 ±60 を override */
+  labelOffsetX?: number;
+  /** label の垂直方向 fine offset (default 0、 preset 交互 ±60 を override) */
+  labelOffsetY?: number;
+};
+
+export type InfrastructurePreset = {
+  id: string;
+  topic: string;
+  /** col あたりの lane width (default 380) */
+  laneWidth?: number;
+  defaultTone?: Tone;
+  defaultStyle?: EdgeStyle;
+};
+
+export type InfrastructureBuilder = {
+  node: (n: InfraNode) => InfrastructureBuilder;
+  connect: (c: InfraConnection) => InfrastructureBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * infrastructure preset ... AWS / GCP / Azure 等の cloud / system 構成図。
+ * node を col + row の grid で配置、 connect で接続線 + edge label。
+ * topology preset (group + container 包含) と違って flat grid 配置 + 各 node が
+ * 独立 lane を持つので、 BFF / Lambda / CDN 等を散在配置するシステム概要図に適する。
+ *
+ * @example
+ * infrastructure({ id: "saas-infra", topic: "SaaS Architecture" })
+ *   .node({ id: "user", kind: "person", title: "User", col: 0, row: 0 })
+ *   .node({ id: "cdn", kind: "cdn", title: "CloudFront", col: 1, row: 0 })
+ *   .node({ id: "alb", kind: "service", title: "ALB", col: 2, row: 0 })
+ *   .node({ id: "app", kind: "service", title: "App", col: 2, row: 1 })
+ *   .node({ id: "db", kind: "database", title: "RDS", col: 3, row: 1 })
+ *   .connect({ from: "user", to: "cdn", label: "HTTPS" })
+ *   .connect({ from: "cdn", to: "alb", label: "origin" })
+ *   .connect({ from: "alb", to: "app", label: "route" })
+ *   .connect({ from: "app", to: "db", label: "TCP 5432" })
+ *   .build();
+ */
+export function infrastructure(preset: InfrastructurePreset): InfrastructureBuilder {
+  const laneW = preset.laneWidth ?? 380;
+  const tone: Tone = preset.defaultTone ?? "accent";
+  const style: EdgeStyle = preset.defaultStyle ?? "solid";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  // col → laneId、 col の数で lane を auto 作成
+  const colLaneIds = new Map<number, string>();
+  const phaseActivate: string[] = [];
+  let connIdx = 0;
+
+  const api: InfrastructureBuilder = {
+    node(n) {
+      let laneId = colLaneIds.get(n.col);
+      if (!laneId) {
+        laneId = `col-${n.col}`;
+        b.lane(laneId, { width: laneW });
+        colLaneIds.set(n.col, laneId);
+      }
+      b.node(n.id, {
+        lane: laneId,
+        stack: n.row,
+        kind: n.kind,
+        title: n.title,
+        ...(n.eyebrow ? { eyebrow: n.eyebrow } : {}),
+        ...(n.subtitle ? { subtitle: n.subtitle } : {}),
+      });
+      phaseActivate.push(n.id);
+      return api;
+    },
+    connect(c) {
+      const currentIdx = connIdx++;
+      const edgeId = `i${currentIdx}-${c.from}-${c.to}`;
+      // Issue #213 SSOT ... 旧実装は `labelOffsetY = currentIdx % 2 === 0 ? -60 : 60` で
+      // label を縦交互に強制 shift して overlap 解消していた。 基準位置は path の上
+      // LABEL_INIT_CLEARANCE (34) なので、 +60 すると path の下 26 に落ちる。
+      // pill 端 と path の距離は 26 - 18 = 8 world となり LABEL_TO_PATH_CLEARANCE (16) を割り込む。
+      //
+      // topology (CAR-559) / stateMachine (CAR-468) / classDiagram (CAR-531) は同じ理由で
+      // author 指定 offset を撤去し engine 側 SSOT に一任済み。 infrastructure だけが残っていた。
+      // label の分散は engine 側 (parallel / fan offset + chain 伝搬 shift) が担当する。
+      // 個別 connection で offset を再導入したい author は c.labelOffsetX/Y で明示指定する。
+      b.edge(c.from, c.to, {
+        id: edgeId,
+        label: c.label,
+        ...(c.sub ? { sub: c.sub } : {}),
+        tone: c.tone ?? tone,
+        style: c.style ?? style,
+        labelOffsetX: c.labelOffsetX ?? 0,
+        labelOffsetY: c.labelOffsetY ?? 0,
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "infra",
+        { duration: 2400, title: preset.topic, body: "infrastructure 全 node + connection を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("infrastructure"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── classDiagram (UML class + attribute / method / relation) ─
+
+export type ClassRelationType = "extends" | "implements" | "uses" | "aggregates" | "composes";
+
+export type UmlClass = {
+  id: string;
+  title: string;
+  /** 属性 (例 "+name: string" / "-id: number") */
+  attributes?: string[];
+  /** メソッド (例 "+login(): void") */
+  methods?: string[];
+  /** stereotype (例 "abstract" / "interface" / "trait") */
+  stereotype?: string;
+};
+
+export type UmlRelation = {
+  from: string;
+  to: string;
+  type: ClassRelationType;
+  /** 関係 label (default は type 名) */
+  label?: string;
+  /** 多重度 (例 "1..*" / "0..1") */
+  cardinality?: string;
+  tone?: Tone;
+};
+
+export type ClassDiagramPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  /**
+   * クラス 1 個の箱の幅 (world unit、 既定 = `storage` の既定幅)。
+   *
+   * 帯ではなく **箱** の幅。 帯は `箱の幅 + 余白 × 2` で宣言する。
+   */
+  classWidth?: number;
+};
+
+export type ClassDiagramBuilder = {
+  class: (c: UmlClass) => ClassDiagramBuilder;
+  relation: (r: UmlRelation) => ClassDiagramBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * classDiagram preset ... UML クラス図。 attributes + methods を rows で表現、
+ * relation を edge で接続。 extends / implements / uses / aggregates / composes 5 種対応。
+ *
+ * @example
+ * classDiagram({ id: "user-class", topic: "User domain model" })
+ *   .class({ id: "User", title: "User", attributes: ["+name: string", "+email: string"], methods: ["+login(): void"] })
+ *   .class({ id: "Admin", title: "Admin", attributes: ["+permissions: string[]"], methods: ["+banUser(): void"] })
+ *   .relation({ from: "Admin", to: "User", type: "extends" })
+ *   .build();
+ */
+export function classDiagram(preset: ClassDiagramPreset): ClassDiagramBuilder {
+  const classW = resolveStorageBoxW(preset.classWidth, "classDiagram", "classWidth");
+  const tone: Tone = preset.defaultTone ?? "info";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const classes: string[] = [];
+  const phaseActivate: string[] = [];
+  let relIdx = 0;
+
+  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);
+      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",
+        // 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);
+      return api;
+    },
+    build() {
+      b.phase(
+        "class",
+        { duration: 2400, title: preset.topic, body: "UML class 全 class + relation を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("class"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── tree (parent-child + hierarchical) ───────────────────────
+
+export type TreeNode = {
+  id: string;
+  title: string;
+  parent?: string;
+  /** 表示 kind (default "card") */
+  kind?: NodeKind;
+  subtitle?: string;
+  eyebrow?: string;
+};
+
+export type TreePreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  /** depth ごとの lane width (default 320) */
+  nodeWidth?: number;
+};
+
+export type TreeBuilder = {
+  node: (n: TreeNode) => TreeBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * tree preset ... parent-child の階層構造を縦列の lane stack で表現。
+ * 各 node は parent を指定、 親が同 lane stack の上に配置される lane (depth 別) を auto 計算。
+ * 組織図 / file tree / class 階層 / 製品カテゴリ等の階層図に使う。
+ *
+ * @example
+ * tree({ id: "org", topic: "組織図" })
+ *   .node({ id: "ceo", title: "CEO" })
+ *   .node({ id: "cto", title: "CTO", parent: "ceo" })
+ *   .node({ id: "cfo", title: "CFO", parent: "ceo" })
+ *   .node({ id: "eng-mgr", title: "Eng Manager", parent: "cto" })
+ *   .build();
+ */
+export function tree(preset: TreePreset): TreeBuilder {
+  const canvasW = preset.nodeWidth ? preset.nodeWidth * 2 : 720;
+  const canvasH = 480;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const treeNodes: TreeNode[] = [];
+
+  const api: TreeBuilder = {
+    node(n) {
+      treeNodes.push(n);
+      return api;
+    },
+    build() {
+      b.lane("tree", { width: canvasW });
+      const nodeId = `${preset.id}-tree`;
+      b.node(nodeId, {
+        lane: "tree",
+        stack: 0,
+        kind: "tree-hierarchy",
+        title: preset.topic,
+        eyebrow: "tree",
+        w: canvasW,
+        h: canvasH,
+        treeData: treeNodes.map((n) => ({
+          id: n.id,
+          title: n.title,
+          parent: n.parent,
+          subtitle: n.subtitle,
+          eyebrow: n.eyebrow,
+        })),
+      });
+      b.phase(
+        "tree",
+        { duration: 2400, title: preset.topic, body: "tree の全 node + parent-child edge を hierarchical layout で描画。" },
+        (p) => p.activate(nodeId).badge("tree"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── userJourney (step + emotion + touchpoint) ────────────────
+
+export type JourneyEmotion = "delighted" | "happy" | "neutral" | "frustrated" | "angry";
+
+export type JourneyStep = {
+  id: string;
+  title: string;
+  emotion: JourneyEmotion;
+  /** どの touchpoint (例 "Website", "Email", "Support") */
+  touchpoint?: string;
+  /** opportunity (改善余地のメモ) */
+  opportunity?: string;
+};
+
+export type UserJourneyPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  stepWidth?: number;
+};
+
+export type UserJourneyBuilder = {
+  step: (s: JourneyStep) => UserJourneyBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * userJourney preset ... User research / UX research の journey map。
+ * step を時系列に横並びで並べ、 emotion を tone で色分け、 touchpoint / opportunity を subtitle で示す。
+ *
+ * @example
+ * userJourney({ id: "signup", topic: "Signup journey" })
+ *   .step({ id: "land", title: "Land on /", emotion: "neutral", touchpoint: "Website" })
+ *   .step({ id: "form", title: "Fill form", emotion: "frustrated", touchpoint: "Form" })
+ *   .step({ id: "verify", title: "Email verify", emotion: "happy", touchpoint: "Email" })
+ *   .step({ id: "done", title: "Done", emotion: "delighted", touchpoint: "Dashboard" })
+ *   .build();
+ */
+export function userJourney(preset: UserJourneyPreset): UserJourneyBuilder {
+  const canvasW = preset.stepWidth ? preset.stepWidth * 2 : 720;
+  const canvasH = 480;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const steps: JourneyStep[] = [];
+
+  const api: UserJourneyBuilder = {
+    step(s) {
+      steps.push(s);
+      return api;
+    },
+    build() {
+      b.lane("journey", { width: canvasW });
+      const nodeId = `${preset.id}-journey`;
+      b.node(nodeId, {
+        lane: "journey",
+        stack: 0,
+        kind: "journey-map",
+        title: preset.topic,
+        eyebrow: "userJourney",
+        w: canvasW,
+        h: canvasH,
+        journeyData: steps.map((s) => ({
+          id: s.id,
+          title: s.title,
+          emotion: s.emotion,
+          touchpoint: s.touchpoint,
+          opportunity: s.opportunity,
+        })),
+      });
+      b.phase(
+        "journey",
+        { duration: 2400, title: preset.topic, body: "userJourney 全 step を感情曲線 + touchpoint で描画。" },
+        (p) => p.activate(nodeId).badge("journey"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── mindMap (中心 topic + 放射 branch) ────────────────────────
+
+export type MindBranch = {
+  id: string;
+  title: string;
+  /** 親 branch (root の子は parent=root id) */
+  parent: string;
+  /** 色 tone (default は parent の tone を継承) */
+  tone?: Tone;
+  subtitle?: string;
+};
+
+export type MindMapPreset = {
+  id: string;
+  topic: string;
+  /** 中心 topic ID + label */
+  rootId: string;
+  rootTitle: string;
+  branchWidth?: number;
+  defaultTone?: Tone;
+};
+
+export type MindMapBuilder = {
+  branch: (b: MindBranch) => MindMapBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+
+/**
+ * mindMap preset ... 中心 root topic から放射状に branch を伸ばす mind map。
+ * tree との違いは「root は 1 つ固定 + 第 1 階層の branch ごとに tone を auto rotate」。
+ *
+ * @example
+ * mindMap({ id: "ideas", topic: "Project ideas", rootId: "root", rootTitle: "Project" })
+ *   .branch({ id: "feat", title: "Features", parent: "root" })
+ *   .branch({ id: "ui", title: "UI design", parent: "root" })
+ *   .branch({ id: "auth", title: "Auth", parent: "feat" })
+ *   .build();
+ */
+export function mindMap(preset: MindMapPreset): MindMapBuilder {
+  const canvasW = preset.branchWidth ? preset.branchWidth * 2 : 720;
+  const canvasH = 480;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const branches: MindBranch[] = [];
+
+  const api: MindMapBuilder = {
+    branch(br) {
+      branches.push(br);
+      return api;
+    },
+    build() {
+      b.lane("mind", { width: canvasW });
+      const nodeId = `${preset.id}-mind`;
+      b.node(nodeId, {
+        lane: "mind",
+        stack: 0,
+        kind: "mind-map",
+        title: preset.topic,
+        eyebrow: "mindMap",
+        w: canvasW,
+        h: canvasH,
+        mindData: {
+          rootId: preset.rootId,
+          rootTitle: preset.rootTitle,
+          branches: branches.map((br) => ({
+            id: br.id,
+            title: br.title,
+            parent: br.parent,
+            tone: br.tone,
+            subtitle: br.subtitle,
+          })),
+        },
+      });
+      b.phase(
+        "mindmap",
+        { duration: 2400, title: preset.topic, body: "mindMap 全 branch を visible 化、 中心 + 放射で描画。" },
+        (p) => p.activate(nodeId).badge("mindmap"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── funnel (Awareness → Conversion 階層) ──────────────────────
+
+export type FunnelStage = {
+  id: string;
+  title: string;
+  /** この stage の人数 / 件数 */
+  count: number;
+  /** stage 詳細 */
+  subtitle?: string;
+};
+
+export type FunnelPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  stageWidth?: number;
+};
+
+export type FunnelBuilder = {
+  stage: (s: FunnelStage) => FunnelBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * funnel preset ... Sales / marketing funnel。 Awareness → Conversion の階層を縦に並べ、
+ * 各 stage の count と drop rate (前 stage 比) を可視化。
+ *
+ * @example
+ * funnel({ id: "sales", topic: "Sales funnel" })
+ *   .stage({ id: "visit", title: "Visit", count: 10000 })
+ *   .stage({ id: "signup", title: "Sign up", count: 1500 })
+ *   .stage({ id: "trial", title: "Trial", count: 800 })
+ *   .stage({ id: "paid", title: "Paid", count: 200 })
+ *   .build();
+ */
+export function funnel(preset: FunnelPreset): FunnelBuilder {
+  const canvasW = toGridSize(preset.stageWidth ?? 560);
+  const canvasH = 480;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const stages: FunnelStage[] = [];
+
+  const api: FunnelBuilder = {
+    stage(s) {
+      stages.push(s);
+      return api;
+    },
+    build() {
+      b.lane("funnel", { width: gridAlignedLaneW(canvasW) });
+      const nodeId = `${preset.id}-funnel`;
+      b.node(nodeId, {
+        lane: "funnel",
+        stack: 0,
+        kind: "funnel-stages",
+        title: preset.topic,
+        eyebrow: "funnel",
+        w: canvasW,
+        h: canvasH,
+        funnelData: stages.map((s) => ({
+          id: s.id,
+          title: s.title,
+          count: s.count,
+          subtitle: s.subtitle,
+        })),
+      });
+      b.phase(
+        "funnel",
+        { duration: 2400, title: preset.topic, body: "funnel 全 stage を逆三角形 + count で描画。" },
+        (p) => p.activate(nodeId).badge("funnel"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── quadrant (2 軸 マトリクス) ────────────────────────────────
+
+export type QuadrantQuadrantLabel = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+
+export type QuadrantItem = {
+  id: string;
+  title: string;
+  /** どの象限 (4 象限) */
+  quadrant: QuadrantQuadrantLabel;
+  subtitle?: string;
+};
+
+export type QuadrantPreset = {
+  id: string;
+  topic: string;
+  /** x 軸 label (left / right) */
+  xAxis: { left: string; right: string };
+  /** y 軸 label (bottom / top) */
+  yAxis: { bottom: string; top: string };
+  /** 各象限の label */
+  quadrantLabels?: Record<QuadrantQuadrantLabel, string>;
+  defaultTone?: Tone;
+};
+
+export type QuadrantBuilder = {
+  item: (i: QuadrantItem) => QuadrantBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * quadrant preset ... 2 軸 マトリクス (Priority matrix / SWOT / Eisenhower 等)。
+ * 4 象限 (topLeft / topRight / bottomLeft / bottomRight) に item を配置。
+ * lane = 2 col (left / right)、 stack = 2 row (top / bottom)。
+ *
+ * @example
+ * quadrant({ id: "priority", topic: "Priority matrix",
+ *           xAxis: { left: "Low effort", right: "High effort" },
+ *           yAxis: { bottom: "Low value", top: "High value" } })
+ *   .item({ id: "a", title: "Quick win", quadrant: "topLeft" })
+ *   .item({ id: "b", title: "Major project", quadrant: "topRight" })
+ *   .item({ id: "c", title: "Fill in", quadrant: "bottomLeft" })
+ *   .item({ id: "d", title: "Thankless", quadrant: "bottomRight" })
+ *   .build();
+ */
+export function quadrant(preset: QuadrantPreset): QuadrantBuilder {
+  const canvasW = 640;
+  const canvasH = 480;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const items: QuadrantItem[] = [];
+
+  const api: QuadrantBuilder = {
+    item(it) {
+      items.push(it);
+      return api;
+    },
+    build() {
+      const labels = preset.quadrantLabels ?? {
+        topLeft: `${preset.yAxis.top} × ${preset.xAxis.left}`,
+        topRight: `${preset.yAxis.top} × ${preset.xAxis.right}`,
+        bottomLeft: `${preset.yAxis.bottom} × ${preset.xAxis.left}`,
+        bottomRight: `${preset.yAxis.bottom} × ${preset.xAxis.right}`,
+      };
+      b.lane("quadrant", { width: gridAlignedLaneW(canvasW) });
+      const nodeId = `${preset.id}-quadrant`;
+      b.node(nodeId, {
+        lane: "quadrant",
+        stack: 0,
+        kind: "quadrant-matrix",
+        title: preset.topic,
+        eyebrow: "quadrant",
+        w: canvasW,
+        h: canvasH,
+        quadrantData: {
+          xAxis: preset.xAxis,
+          yAxis: preset.yAxis,
+          quadrantLabels: labels,
+          items: items.map((it) => ({
+            id: it.id,
+            title: it.title,
+            quadrant: it.quadrant,
+            subtitle: it.subtitle,
+          })),
+        },
+      });
+      b.phase(
+        "quadrant",
+        { duration: 2400, title: preset.topic, body: "quadrant 十字軸 + 4 象限 + item を描画。" },
+        (p) => p.activate(nodeId).badge("quadrant"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── chart (Pie / Bar / Line 統合) ─────────────────────────────
+
+export type ChartType = "pie" | "bar" | "line";
+
+export type ChartDatum = {
+  id: string;
+  label: string;
+  value: number;
+  /** 個別 tone (default は preset の defaultTone) */
+  tone?: Tone;
+};
+
+export type ChartPreset = {
+  id: string;
+  topic: string;
+  type: ChartType;
+  defaultTone?: Tone;
+  itemWidth?: number;
+};
+
+export type ChartBuilder = {
+  datum: (d: ChartDatum) => ChartBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * chart preset ... 統計チャート (Pie / Bar / Line)、 CAR-994 Phase A で SVG geometry render 導入。
+ *
+ * datum 配列を 1 大 node (kind=chart-line / chart-pie / chart-bar) の chartData payload に
+ * 格納し、 kinds/chart-*.tsx が自己完結で折れ線 / 円 / 棒グラフを SVG 描画する。
+ * layout は 1 lane + 1 node (chart canvas サイズ) で完結、 lane / edge を datum 数だけ増やさない。
+ *
+ * @example
+ * chart({ id: "share", topic: "Market share", type: "pie" })
+ *   .datum({ id: "a", label: "A", value: 45 })
+ *   .datum({ id: "b", label: "B", value: 30 })
+ *   .datum({ id: "c", label: "C", value: 25 })
+ *   .build();
+ */
+export function chart(preset: ChartPreset): ChartBuilder {
+  const canvasW = toGridSize(preset.itemWidth ?? 640);
+  // 高さも格子の倍数にする。 line / bar は 360 だったが 360 % 16 = 8 で下端が格子から外れ、
+  // 箱の 4 辺が載る条件を満たさなかった。
+  const canvasH = toGridSize(preset.type === "pie" ? 320 : 360);
+  const b = diagram(preset.id, { topic: preset.topic });
+  const data: ChartDatum[] = [];
+
+  const kindMap = {
+    line: "chart-line" as const,
+    pie: "chart-pie" as const,
+    bar: "chart-bar" as const,
+  };
+
+  const api: ChartBuilder = {
+    datum(d) {
+      data.push(d);
+      return api;
+    },
+    build() {
+      b.lane("chart", { width: gridAlignedLaneW(canvasW) });
+      const nodeId = `${preset.id}-chart`;
+      b.node(nodeId, {
+        lane: "chart",
+        stack: 0,
+        kind: kindMap[preset.type],
+        title: preset.topic,
+        eyebrow: preset.type,
+        w: canvasW,
+        h: canvasH,
+        chartData: data.map((d) => ({ label: d.label, value: d.value, tone: d.tone })),
+      });
+      b.phase(
+        "chart",
+        { duration: 2400, title: preset.topic, body: `${preset.type} chart の全 datum を visible 化。` },
+        (p) => p.activate(nodeId).badge(preset.type),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── gantt (sprint planning / release timeline) ───────────────
+
+export type GanttTask = {
+  id: string;
+  title: string;
+  /** 開始 (例 "2026-Q1" / "Day 1") */
+  start: string;
+  /** 終了 (例 "2026-Q2") */
+  end: string;
+  /** owner / assignee */
+  owner?: string;
+  /** 依存 task id */
+  dependsOn?: string;
+};
+
+export type GanttPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  laneWidth?: number;
+};
+
+export type GanttBuilder = {
+  task: (t: GanttTask) => GanttBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * gantt preset ... Gantt chart / sprint planning / release timeline。
+ * task ごとに 1 lane を作り、 start - end + owner を subtitle、 dependsOn で前 task → 次 task の edge を auto 生成。
+ *
+ * @example
+ * gantt({ id: "release", topic: "Release timeline" })
+ *   .task({ id: "design", title: "Design", start: "Q1", end: "Q1" })
+ *   .task({ id: "build", title: "Build", start: "Q2", end: "Q2", dependsOn: "design" })
+ *   .task({ id: "test", title: "Test", start: "Q3", end: "Q3", dependsOn: "build" })
+ *   .build();
+ */
+export function gantt(preset: GanttPreset): GanttBuilder {
+  const canvasW = preset.laneWidth ? preset.laneWidth * 2 : 720;
+  const canvasH = 360;
+  const tone: Tone = preset.defaultTone ?? "teal";
+  const b = diagram(preset.id, { topic: preset.topic });
+  const tasks: GanttTask[] = [];
+
+  const api: GanttBuilder = {
+    task(t) {
+      tasks.push(t);
+      return api;
+    },
+    build() {
+      // start / end label を index に変換 (unique label を順に並べる)
+      const labelSeq: string[] = [];
+      for (const t of tasks) {
+        if (!labelSeq.includes(t.start)) labelSeq.push(t.start);
+        if (!labelSeq.includes(t.end)) labelSeq.push(t.end);
+      }
+      b.lane("gantt", { width: canvasW });
+      const nodeId = `${preset.id}-gantt`;
+      b.node(nodeId, {
+        lane: "gantt",
+        stack: 0,
+        kind: "gantt-timeline",
+        title: preset.topic,
+        eyebrow: "gantt",
+        w: canvasW,
+        h: canvasH,
+        ganttData: tasks.map((t) => ({
+          id: t.id,
+          title: t.title,
+          startIdx: labelSeq.indexOf(t.start),
+          endIdx: labelSeq.indexOf(t.end),
+          startLabel: t.start,
+          endLabel: t.end,
+          owner: t.owner,
+          dependsOn: t.dependsOn,
+          tone,
+        })),
+      });
+      b.phase(
+        "gantt",
+        { duration: 2400, title: preset.topic, body: "gantt 全 task を visible 化、 帯状 timeline + 依存 arrow で描画。" },
+        (p) => p.activate(nodeId).badge("gantt"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── flowchart (swimlane + decision + loop) ────────────────────
+
+export type FlowchartNodeShape = "process" | "decision" | "start" | "end" | "loop";
+
+export type FlowchartNode = {
+  id: string;
+  title: string;
+  shape: FlowchartNodeShape;
+  /** swimlane (role) */
+  lane: string;
+};
+
+export type FlowchartEdge = {
+  from: string;
+  to: string;
+  /** decision shape の場合 "true" / "false" / null */
+  label?: string;
+  tone?: Tone;
+};
+
+export type FlowchartPreset = {
+  id: string;
+  topic: string;
+  /** swimlane の lane (role) ラベル */
+  lanes: string[];
+  defaultTone?: Tone;
+  laneWidth?: number;
+};
+
+export type FlowchartBuilder = {
+  node: (n: FlowchartNode) => FlowchartBuilder;
+  edge: (e: FlowchartEdge) => FlowchartBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+const SHAPE_KIND: Record<FlowchartNodeShape, NodeKind> = {
+  process: "function",
+  decision: "card",
+  start: "event",
+  end: "event",
+  loop: "card",
+};
+
+const SHAPE_EYEBROW: Record<FlowchartNodeShape, string> = {
+  process: "process",
+  decision: "decision",
+  start: "start",
+  end: "end",
+  loop: "loop",
+};
+
+/**
+ * flowchart preset ... swimlane + decision diamond + loop 枠を扱うビジネス process diagram。
+ * mermaid flowchart より「lane 別の役割分担」 と「decision / loop」 を明示できる。
+ *
+ * @example
+ * flowchart({ id: "approve", topic: "Approval flow", lanes: ["User", "Manager"] })
+ *   .node({ id: "submit", title: "Submit", shape: "start", lane: "User" })
+ *   .node({ id: "review", title: "Review", shape: "decision", lane: "Manager" })
+ *   .node({ id: "approve", title: "Approve", shape: "end", lane: "Manager" })
+ *   .node({ id: "revise", title: "Revise", shape: "process", lane: "User" })
+ *   .edge({ from: "submit", to: "review" })
+ *   .edge({ from: "review", to: "approve", label: "true" })
+ *   .edge({ from: "review", to: "revise", label: "false" })
+ *   .build();
+ */
+export function flowchart(preset: FlowchartPreset): FlowchartBuilder {
+  const laneW = preset.laneWidth ?? 380;
+  const tone: Tone = preset.defaultTone ?? "accent";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const laneToId = new Map<string, string>();
+  const laneStackCount = new Map<string, number>();
+  for (const label of preset.lanes) {
+    const id = slugify(label) || `lane-${laneToId.size}`;
+    laneToId.set(label, id);
+    laneStackCount.set(id, 0);
+    b.lane(id, { width: laneW, label });
+  }
+  const phaseActivate: string[] = [];
+  let edgeIdx = 0;
+
+  const api: FlowchartBuilder = {
+    node(n) {
+      const laneId = laneToId.get(n.lane) ?? n.lane;
+      const stack = laneStackCount.get(laneId) ?? 0;
+      b.node(n.id, {
+        lane: laneId,
+        stack,
+        kind: SHAPE_KIND[n.shape],
+        title: n.title,
+        eyebrow: SHAPE_EYEBROW[n.shape],
+      });
+      laneStackCount.set(laneId, stack + 1);
+      phaseActivate.push(n.id);
+      return api;
+    },
+    edge(e) {
+      const edgeId = `fc-${edgeIdx++}-${e.from}-${e.to}`;
+      // CAR-549 SSOT ... flowchart の decision condition label (true / false / yes / no) は
+      // edge の semantic (どちらの分岐か) を強調するため path 上に重ねて表示する。
+      // 他 label (通常の process 遷移名) は default (34 world 離す) で読みやすさ優先。
+      const label = e.label ?? "";
+      const isConditionLabel = /^(true|false|yes|no)$/i.test(label.trim());
+      b.edge(e.from, e.to, {
+        id: edgeId,
+        label,
+        tone: e.tone ?? tone,
+        style: "solid",
+        overlay: isConditionLabel,
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "flowchart",
+        { duration: 2400, title: preset.topic, body: "flowchart 全 node + edge を visible 化、 swimlane + decision を表現。" },
+        (p) => p.activate(...phaseActivate).badge("flowchart"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── network (router / switch / firewall) ──────────────────────
+
+export type NetworkDeviceKind = "router" | "switch" | "firewall" | "server" | "client";
+
+export type NetworkDevice = {
+  id: string;
+  title: string;
+  kind: NetworkDeviceKind;
+  segment?: string;
+  /** 表示 col + row */
+  col: number;
+  row: number;
+};
+
+export type NetworkLink = {
+  from: string;
+  to: string;
+  /** プロトコル / VLAN 等 */
+  protocol?: string;
+  tone?: Tone;
+};
+
+export type NetworkPreset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  laneWidth?: number;
+};
+
+export type NetworkBuilder = {
+  device: (d: NetworkDevice) => NetworkBuilder;
+  link: (l: NetworkLink) => NetworkBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+const NET_KIND_MAP: Record<NetworkDeviceKind, NodeKind> = {
+  router: "service",
+  switch: "service",
+  firewall: "service",
+  server: "backend",
+  client: "actor",
+};
+
+/**
+ * network preset ... NW topology (router / switch / firewall / server / client) を col × row 配置、
+ * link で接続 (protocol / VLAN を label)。 On-prem / hybrid NW 構成図向け。
+ *
+ * @example
+ * network({ id: "office-nw", topic: "Office NW" })
+ *   .device({ id: "fw", title: "Firewall", kind: "firewall", col: 0, row: 0 })
+ *   .device({ id: "sw1", title: "Switch A", kind: "switch", col: 1, row: 0 })
+ *   .device({ id: "srv", title: "Server", kind: "server", col: 2, row: 0 })
+ *   .link({ from: "fw", to: "sw1", protocol: "VLAN 10" })
+ *   .link({ from: "sw1", to: "srv", protocol: "TCP 22" })
+ *   .build();
+ */
+export function network(preset: NetworkPreset): NetworkBuilder {
+  const laneW = preset.laneWidth ?? 320;
+  const tone: Tone = preset.defaultTone ?? "info";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const colLaneIds = new Map<number, string>();
+  const phaseActivate: string[] = [];
+  let edgeIdx = 0;
+
+  const api: NetworkBuilder = {
+    device(d) {
+      let laneId = colLaneIds.get(d.col);
+      if (!laneId) {
+        laneId = `n-col-${d.col}`;
+        b.lane(laneId, { width: laneW });
+        colLaneIds.set(d.col, laneId);
+      }
+      const eyebrowParts: string[] = [d.kind];
+      if (d.segment) eyebrowParts.push(d.segment);
+      b.node(d.id, {
+        lane: laneId,
+        stack: d.row,
+        kind: NET_KIND_MAP[d.kind],
+        title: d.title,
+        eyebrow: eyebrowParts.join(" / "),
+      });
+      phaseActivate.push(d.id);
+      return api;
+    },
+    link(l) {
+      const edgeId = `nl-${edgeIdx++}-${l.from}-${l.to}`;
+      b.edge(l.from, l.to, {
+        id: edgeId,
+        label: l.protocol ?? "",
+        tone: l.tone ?? tone,
+        style: "solid",
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "network",
+        { duration: 2400, title: preset.topic, body: "network 全 device + link を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("network"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── stateMachine2 (nested state + guard / action) ─────────────
+
+export type FsmStateNested = {
+  id: string;
+  title: string;
+  initial?: boolean;
+  final?: boolean;
+  /** 親 state (nested state、 例 "loading" の親 "active") */
+  parent?: string;
+  /** entry action (例 "onEnter: startTimer") */
+  entry?: string;
+  /** exit action */
+  exit?: string;
+};
+
+export type FsmTransitionExt = {
+  from: string;
+  to: string;
+  trigger: string;
+  guard?: string;
+  /** action (例 "onTransition: incrementCounter") */
+  action?: string;
+  tone?: Tone;
+};
+
+export type StateMachine2Preset = {
+  id: string;
+  topic: string;
+  defaultTone?: Tone;
+  /**
+   * 状態 1 個の箱の幅 (world unit、 既定 320 = card の既定幅)。
+   *
+   * 帯の幅ではなく **箱の幅** を指す。 帯は engine が「箱の幅 + 余白 × 2」 まで広げるので、
+   * 帯だけを狭く指定しても図は縮まない (#357 以前はここが帯にしか渡っておらず、
+   * 370 未満の指定が全て無視されていた)。
+   *
+   * 80 未満と有限でない値は例外を投げる。 箱の幅として使う以上、 描画が壊れる値を
+   * 黙って受け取らない。
+   */
+  stateWidth?: number;
+};
+
+export type StateMachine2Builder = {
+  state: (s: FsmStateNested) => StateMachine2Builder;
+  transition: (t: FsmTransitionExt) => StateMachine2Builder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * stateMachine2 preset ... 拡張 FSM (UML statechart)。
+ * stateMachine と違って (a) nested state (parent 指定) (b) entry / exit action (c) transition action サポート。
+ * subtitle / sub で action / guard を表示。
+ *
+ * @example
+ * stateMachine2({ id: "auth", topic: "Auth FSM" })
+ *   .state({ id: "idle", title: "Idle", initial: true, entry: "clearForm" })
+ *   .state({ id: "active", title: "Active" })
+ *   .state({ id: "loading", title: "Loading", parent: "active" })
+ *   .state({ id: "done", title: "Done", final: true })
+ *   .transition({ from: "idle", to: "loading", trigger: "submit", action: "startSpinner" })
+ *   .transition({ from: "loading", to: "done", trigger: "success" })
+ *   .build();
+ */
+export function stateMachine2(preset: StateMachine2Preset): StateMachine2Builder {
+  const stateW = resolveStateW(preset.stateWidth, "stateMachine2");
+  const laneW = boxLaneW(stateW);
+  const tone: Tone = preset.defaultTone ?? "accent";
+  const b = diagram(preset.id, { topic: preset.topic });
+
+  const stateOrder = new Map<string, number>();
+  const phaseActivate: string[] = [];
+  let transIdx = 0;
+
+  const api: StateMachine2Builder = {
+    state(s) {
+      const laneId = `lane-${s.id}`;
+      b.lane(laneId, { width: laneW });
+      const eyebrowParts: string[] = [];
+      if (s.initial) eyebrowParts.push("初期");
+      else if (s.final) eyebrowParts.push("最終");
+      else eyebrowParts.push("状態");
+      if (s.parent) eyebrowParts.push(`nested in ${s.parent}`);
+      const subtitleParts: string[] = [];
+      if (s.entry) subtitleParts.push(`entry: ${s.entry}`);
+      if (s.exit) subtitleParts.push(`exit: ${s.exit}`);
+      b.node(s.id, {
+        lane: laneId,
+        stack: 0,
+        kind: "card",
+        w: stateW,
+        title: s.title,
+        eyebrow: eyebrowParts.join(" / "),
+        ...(subtitleParts.length ? { subtitle: subtitleParts.join(" / ") } : {}),
+      });
+      stateOrder.set(s.id, stateOrder.size);
+      phaseActivate.push(s.id);
+      return api;
+    },
+    transition(t) {
+      const currentIdx = transIdx++;
+      const edgeId = `sm2-${currentIdx}-${t.from}-${t.to}`;
+      const subParts: string[] = [];
+      if (t.guard) subParts.push(`[${t.guard}]`);
+      if (t.action) subParts.push(`/${t.action}`);
+      // CAR-468 SSOT ... 旧 labelOffsetY = ±170 の強制上下シフトを廃止、 routePath() SSOT init 位置
+      // (LABEL_INIT_CLEARANCE=34、 CAR-630 で 26 → 34 復帰) をそのまま採用。 分散は engine 側 parallel / fan-in / fan-out logic
+      // (PARALLEL_STEP_Y=52 / FAN_STEP=40) + chain shift が担当。
+      b.edge(t.from, t.to, {
+        id: edgeId,
+        label: t.trigger,
+        ...(subParts.length ? { sub: subParts.join(" ") } : {}),
+        tone: t.tone ?? tone,
+        style: "solid",
+      });
+      phaseActivate.push(edgeId);
+      return api;
+    },
+    build() {
+      b.phase(
+        "sm2",
+        { duration: 2400, title: preset.topic, body: "拡張 FSM (nested + action) を visible 化。" },
+        (p) => p.activate(...phaseActivate).badge("statemachine2"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── mindMapRadial (中心 topic + 8 方向 45 度間隔 放射) ─────────
+
+export type MindMapRadialBranch = {
+  id: string;
+  title: string;
+  /** 色 tone (default は defaultTone)。 8 方向で auto rotate も可 */
+  tone?: Tone;
+  subtitle?: string;
+};
+
+export type MindMapRadialPreset = {
+  id: string;
+  topic: string;
+  /** 中心 node の title (id は builder が "center" で内部生成) */
+  centerTitle: string;
+  /** 中心 node の id override (default "center") */
+  centerId?: string;
+  /** 中心から branch までの距離 (world coord、 default 350) */
+  radius?: number;
+  /** branch node の width (default 260) */
+  branchWidth?: number;
+  /** 中心 node の width (default 260) */
+  centerWidth?: number;
+  defaultTone?: Tone;
+};
+
+export type MindMapRadialBuilder = {
+  branch: (b: MindMapRadialBranch) => MindMapRadialBuilder;
+  build: () => ReturnType<DiagramBuilder["build"]>;
+};
+
+/**
+ * mindMapRadial preset ... 中心 node を軸に 8 方向 (0°/45°/90°/135°/180°/225°/270°/315°)
+ * へ branch を放射状に配置する。 現行 mindMap (左から右へ水平 tree) と使い分ける用途。
+ *
+ * 実装戦略 ... engine の lane × stack grid を活用し、 3 lane (left / center / right) を
+ * radius に基づき explicit x で配置、 3 stack row (top / middle / bottom) を stack index 0/1/2 で
+ * 割当てる。 branch 順は position 順 (E/SE/S/SW/W/NW/N/NE) に固定し、 index → grid cell mapping。
+ *
+ * @example
+ * mindMapRadial({ id: "mr", topic: "Product Radial", centerTitle: "Product" })
+ *   .branch({ id: "users", title: "Users" })      // 0° (right)
+ *   .branch({ id: "road", title: "Roadmap" })     // 45° (bottom-right)
+ *   .branch({ id: "metrics", title: "Metrics" })  // 90° (bottom)
+ *   ...
+ *   .build();
+ */
+export function mindMapRadial(preset: MindMapRadialPreset): MindMapRadialBuilder {
+  const centerId = preset.centerId ?? "center";
+  const canvasW = 640;
+  const canvasH = 640;
+  const b = diagram(preset.id, { topic: preset.topic });
+  const branches: MindMapRadialBranch[] = [];
+
+  const api: MindMapRadialBuilder = {
+    branch(br) {
+      if (branches.length >= 8) {
+        throw new Error(`cdl mindMapRadial: 8 方向配置のため branch は最大 8 件 (preset id "${preset.id}")`);
+      }
+      branches.push(br);
+      return api;
+    },
+    build() {
+      b.lane("radial", { width: canvasW });
+      const nodeId = `${preset.id}-radial`;
+      b.node(nodeId, {
+        lane: "radial",
+        stack: 0,
+        kind: "mind-radial",
+        title: preset.topic,
+        eyebrow: "mindMapRadial",
+        w: canvasW,
+        h: canvasH,
+        mindData: {
+          rootId: centerId,
+          rootTitle: preset.centerTitle,
+          branches: branches.map((br) => ({
+            id: br.id,
+            title: br.title,
+            parent: centerId,
+            tone: br.tone,
+            subtitle: br.subtitle,
+          })),
+        },
+      });
+      b.phase(
+        "mindmap-radial",
+        { duration: 2400, title: preset.topic, body: "mindMapRadial 全 branch を visible 化、 中心 + 8 方向 45 度で描画。" },
+        (p) => p.activate(nodeId).badge("mindmap-radial"),
+      );
+      return b.build();
+    },
+  };
+
+  return api;
+}
+
+// ─── helper ────────────────────────────────────────────────────
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9぀-ゟ゠-ヿ一-龯]+/g, "-")
+    .replace(/^-|-$/g, "");
+}