@cardenelabs/cdl 0.124.0 → 0.125.0

package/src/render/stage.tsx

@@ -3,7 +3,8 @@ import { 折れ線の目盛, type ChartLineScale } from "../kinds/chart-line";
 import { 描く進みに直す } from "../kinds/draw-ratio";
 import { useReducedMotion } from "../anim/react/useReducedMotion";
 import { lifelineStartYs, uniformLifelineEndY } from "../layout/lifeline";
-import { buildDiagramAltText, isRenderedNode } from "../layout/spec";
+import { buildDiagramAltText, isRenderedNode, TIMELINE_NUMBER_STROKE } from "../layout/spec";
+import { STAGE_CARD_TEXT_INSET, STAGE_COLUMN_GAP } from "../layout/tokens";
 import {
   EDGE_HEADS,
   EDGE_HEAD_FILLS,
@@ -13,6 +14,7 @@ import {
   RELATION_FOCUS_DEFAULT,
   type CdlPhase,
   type LaidDiagram,
+  type LaidNode,
 } from "../types";
 import {
   EDGE_HEAD_MUTED_MARKER_ID,
@@ -20,15 +22,23 @@ import {
   edgeHeadMarkerId,
   edgeHeadMarkerName,
   edgeHeadPaint,
+  METRO_RETURN_ARROW_D,
+  metroReturnArrowMarkerId,
 } from "./edge-head";
 import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeEndLabelView, CdlEdgeLabelView } from "./edges";
 import { CdlNodeView } from "./nodes";
+import { CdlLegend } from "./legend";
 import { resolveChartData } from "./payload-binding";
 import { relatedFocusSet } from "./relation-focus";
 import { TONE, TONE_HEX } from "./tone";
-import { computeStateValues } from "./utils";
+import { computeStateValues, interpolate } from "./utils";
 import type { 値の名前の表 } from "../input-option";
 
+const METRO_LANE_BADGE_WIDTH = 200;
+const METRO_LANE_BADGE_HEIGHT = 88;
+const METRO_LANE_BADGE_INSET = 24;
+const METRO_LANE_GUIDE_GAP = 24;
+
 /**
  * その図に描くものがあるか (#923)。
  *
@@ -42,9 +52,17 @@ import type { 値の名前の表 } from "../input-option";
  * 描かれない。 `{signal}` を含む条件は段しだいで出るので、出る側に数える。
  */
 function 描くものがある(laid: LaidDiagram): boolean {
+  if (laid.legend && laid.legend.length > 0) return true;
   if (laid.edges.length > 0) return true;
   if (laid.nodes.some((n) => isRenderedNode(n))) return true;
-  return laid.lanes.some((l) => l.contain === true || l.lifeline === true || Boolean(l.label));
+  return laid.lanes.some(
+    (l) =>
+      l.contain === true ||
+      l.lifeline === true ||
+      Boolean(l.label) ||
+      l.stage !== undefined ||
+      l.metro !== undefined,
+  );
 }
 
 export function CdlStage({
@@ -121,6 +139,8 @@ export function CdlStage({
     [関係を光らせる, 焦点, laid.edges],
   );
   const activeSet = 焦点の集合 ?? new Set(currentPhase?.activate ?? []);
+  const 路線図 = laid.edges.some((edge) => edge.routing === "metro") &&
+    laid.nodes.some((node) => node.kind === "station");
   /** 箱に付ける受け口。 指定を書かない図では `undefined` = DOM も挙動も変わらない */
   const 箱の受け口 = 関係を光らせる
     ? { 触れた, 離れた, 押した, 焦点: 焦点?.id ?? null }
@@ -167,8 +187,15 @@ export function CdlStage({
         if (first === undefined) return false;
         return 今 === first;
       },
+      /** 初出の段より前にある区間だけを、通過前として選べるようにする。 */
+      まだか: (edgeId: string): boolean => {
+        const first = 初出.get(edgeId);
+        return first !== undefined && 今 >= 0 && 今 < first;
+      },
     };
   }, [laid.phases, currentPhase, laid.edgeReveal]);
+  const 線を描く = (edge: (typeof laid.edges)[number]): boolean =>
+    edge.routing === "metro" || 矢印の出番.出るか(edge.id);
   // この phase で左の起点から描き始める node (cdl#512)。 `activate` とは別集合で持つ =
   // 焦点が当たり続ける図で毎 phase 引き直すことになるため、 光っているかを引き金にしない
   const drawSet = new Set(currentPhase?.draw ?? []);
@@ -280,7 +307,56 @@ export function CdlStage({
       ),
     );
   }, [laid]);
+  const metroReturnArrowMarkers = useMemo(() => {
+    const tones = new Set(
+      laid.edges
+        .filter((edge) => edge.metroReturn === true)
+        .map((edge) => edge.tone),
+    );
+    return [...tones].map((tone) => (
+      <marker
+        key={tone}
+        id={metroReturnArrowMarkerId(tone)}
+        viewBox="0 -9.5 21 19"
+        refX="0"
+        refY="0"
+        markerWidth="21"
+        markerHeight="19"
+        markerUnits="userSpaceOnUse"
+        orient="auto"
+      >
+        <path
+          data-cdl-role="edge-arrowhead"
+          data-cdl-mark="metro-return-arrow"
+          d={METRO_RETURN_ARROW_D}
+          fill={TONE[tone]}
+        />
+      </marker>
+    ));
+  }, [laid.edges]);
   const diagramScale = laid.diagramScale ?? 1;
+  const stageLaneIds = new Set(
+    laid.lanes.filter((lane) => lane.stage !== undefined).map((lane) => lane.id),
+  );
+  const stageNoteNodes = laid.nodes.filter(
+    (node): node is LaidNode & { subtitle: string } =>
+      node.kind === "card" &&
+      (stageLaneIds.has(node.lane) || node.leaderTo !== undefined) &&
+      isRenderedNode(node) &&
+      Boolean(node.subtitle),
+  );
+  const stageNoteNodeIds = new Set(stageNoteNodes.map((node) => node.id));
+  const nodesById = new Map(laid.nodes.map((node) => [node.id, node]));
+  const metroDecisionIds = new Set<string>();
+  const stationNamesRight = new Set<string>();
+  for (const edge of laid.edges) {
+    if (edge.routing !== "metro") continue;
+    if (nodesById.get(edge.from)?.kind === "decision") metroDecisionIds.add(edge.from);
+    if (nodesById.get(edge.to)?.kind === "decision") metroDecisionIds.add(edge.to);
+    if (edge.toSide === "top" && nodesById.get(edge.to)?.kind === "station") {
+      stationNamesRight.add(edge.to);
+    }
+  }
   // 描くものが 1 つも無い図は面を取らない (#923)。
   // 札 (`interactive-panel`) は `render.tsx` が別に出すので、題と札は残る。
   // hook は全て上で呼び終えているので、ここで返しても呼ぶ順は変わらない。
@@ -343,6 +419,7 @@ export function CdlStage({
               に適用する。 marker (cdl-arrow-*) は edge routing の SSOT なので cdl 内に維持。 */}
           {/* 大小は phase ごとに入れ替わるため、配置が参照する両方を保持する。 */}
           {edgeHeadMarkers}
+          {metroReturnArrowMarkers}
           {/* tone が TONE 定義に無い edge の受け皿。 visual-validate の tone-marker-ref 軸が
               dead ref を検知するが、 検知するまでの間に矢頭が消えないようにする。 */}
           <marker
@@ -378,7 +455,53 @@ export function CdlStage({
               stroke="none"
               pointerEvents="none"
             />
-            {lane.contain && (
+            {lane.stage && (
+              <>
+                <rect
+                  data-cdl-role="stage-column"
+                  x={lane.x + STAGE_COLUMN_GAP / 2}
+                  y={lane.y}
+                  width={lane.width - STAGE_COLUMN_GAP}
+                  height={lane.height}
+                  rx={16}
+                  fill="var(--cdl-stage-bg, #fafafa)"
+                  fillOpacity={0.5}
+                  stroke="var(--cdl-text-mute, #8a8678)"
+                  strokeWidth={1.5}
+                />
+                <text
+                  data-cdl-role="stage-number"
+                  x={lane.x + STAGE_COLUMN_GAP / 2 + 20}
+                  y={lane.y + 24}
+                  fontSize={14}
+                  fontWeight={500}
+                  letterSpacing={1.5}
+                  fill="var(--cdl-text-mute, #8a8678)"
+                >
+                  {`段階 ${lane.stage.number}`}
+                </text>
+                <text
+                  data-cdl-role="stage-name"
+                  x={lane.x + STAGE_COLUMN_GAP / 2 + 20}
+                  y={lane.y + 55}
+                  fontSize={22}
+                  fontWeight={700}
+                  fill="var(--cdl-text, #1a1f2a)"
+                >
+                  {lane.stage.name}
+                </text>
+                <line
+                  data-cdl-role="stage-divider"
+                  x1={lane.x + STAGE_COLUMN_GAP / 2}
+                  y1={lane.y + 72}
+                  x2={lane.x + lane.width - STAGE_COLUMN_GAP / 2}
+                  y2={lane.y + 72}
+                  stroke="var(--cdl-divider, #d4d4d8)"
+                  strokeWidth={1.5}
+                />
+              </>
+            )}
+            {lane.contain && lane.stage === undefined && (
               <rect
                 data-cdl-role="lane-container"
                 x={lane.x}
@@ -414,7 +537,76 @@ export function CdlStage({
                 />
               );
             })()}
-            {lane.label && (
+            {lane.timelineAxis && (() => {
+              const ys = laid.nodes
+                .filter((node) => node.lane === lane.id && isRenderedNode(node))
+                .map((node) => node.cy);
+              if (ys.length < 2) return null;
+              const y1 = Math.min(...ys);
+              const y2 = Math.max(...ys);
+              if (y2 <= y1) return null;
+              return (
+                <line
+                  data-cdl-role="timeline-axis"
+                  x1={lane.x + lane.width / 2}
+                  y1={y1}
+                  x2={lane.x + lane.width / 2}
+                  y2={y2}
+                  stroke="var(--cdl-tone-accent, #2d6a8f)"
+                  strokeWidth={TIMELINE_NUMBER_STROKE}
+                />
+              );
+            })()}
+            {lane.metro !== undefined && (
+              <>
+                <line
+                  data-cdl-role="metro-lane-guide"
+                  x1={lane.x + METRO_LANE_BADGE_INSET + METRO_LANE_BADGE_WIDTH + METRO_LANE_GUIDE_GAP}
+                  y1={lane.y + lane.height / 2}
+                  x2={lane.x + lane.width - METRO_LANE_BADGE_INSET}
+                  y2={lane.y + lane.height / 2}
+                  stroke="var(--cdl-line-mute, #a89d8f)"
+                  strokeWidth={2}
+                  strokeDasharray="22 7 5 7"
+                  opacity={0.45}
+                />
+                <g
+                  data-cdl-role="metro-lane-badge"
+                  transform={`translate(${lane.x + METRO_LANE_BADGE_INSET} ${lane.y + lane.height / 2 - METRO_LANE_BADGE_HEIGHT / 2})`}
+                >
+                  <rect
+                    width={METRO_LANE_BADGE_WIDTH}
+                    height={METRO_LANE_BADGE_HEIGHT}
+                    rx={12}
+                    fill="var(--cdl-node-fill, #ffffff)"
+                    stroke="var(--cdl-tone-accent, #2d6a8f)"
+                    strokeWidth={1.25}
+                  />
+                  <text
+                    x={METRO_LANE_BADGE_WIDTH / 2}
+                    y={lane.metro.subtitle ? 37 : 53}
+                    fontSize={26}
+                    fontWeight={700}
+                    fill="var(--cdl-text, #1a1f2a)"
+                    textAnchor="middle"
+                  >
+                    {lane.label}
+                  </text>
+                  {lane.metro.subtitle && (
+                    <text
+                      x={METRO_LANE_BADGE_WIDTH / 2}
+                      y={67}
+                      fontSize={18}
+                      fill="var(--cdl-text-dim, #5a6270)"
+                      textAnchor="middle"
+                    >
+                      {lane.metro.subtitle}
+                    </text>
+                  )}
+                </g>
+              </>
+            )}
+            {lane.label && lane.metro === undefined && (
               <text
                 data-cdl-role="lane-label"
                 x={lane.x + 24}
@@ -430,8 +622,35 @@ export function CdlStage({
           </g>
         ))}
 
+        {/* 補助線は札と番号の下に敷き、edge の矢頭や配置には参加させない。 */}
+        {laid.nodes.map((node) => {
+          if (node.leaderTo === undefined) return null;
+          const target = nodesById.get(node.leaderTo);
+          if (target === undefined) return null;
+          if (!isRenderedNode(node) || !isRenderedNode(target)) return null;
+          const targetIsRight = target.cx >= node.cx;
+          const x1 = node.cx + (targetIsRight ? node.w / 2 : -node.w / 2);
+          const x2 = target.cx + (targetIsRight ? -target.w / 2 : target.w / 2);
+          if (targetIsRight ? x2 <= x1 : x1 <= x2) return null;
+          return (
+            <line
+              key={`timeline-leader-${node.id}`}
+              data-cdl-role="timeline-leader"
+              data-cdl-leader-from={node.id}
+              data-cdl-leader-to={node.leaderTo}
+              x1={x1}
+              y1={node.cy}
+              x2={x2}
+              y2={target.cy}
+              stroke="var(--cdl-line-mute, #a89d8f)"
+              strokeWidth={1.5}
+              strokeDasharray="2 4"
+              strokeLinecap="round"
+            />
+          );
+        })}
         {/* edges (1st pass) */}
-        {laid.edges.filter((edge) => 矢印の出番.出るか(edge.id)).map((edge) => (
+        {laid.edges.filter(線を描く).map((edge) => (
           <CdlEdgeView
             key={edge.id}
             edge={edge}
@@ -440,6 +659,7 @@ export function CdlStage({
             drawing={矢印の出番.伸ばすか(edge.id)}
             progress={矢印の出番.伸ばすか(edge.id) ? 描く進み : progress}
             stateValues={stateValues}
+            pending={edge.routing === "metro" && 矢印の出番.まだか(edge.id)}
           />
         ))}
 
@@ -449,9 +669,11 @@ export function CdlStage({
           // および `tweens` は元の進みのまま = 「線はゆっくり、 値は短く」 が 1 つの phase で
           // 両立する。 対象外にも掛けると値の移りまで速くなる
           const 描く = drawSet.has(node.id);
+          const 段階の補足 = stageNoteNodeIds.has(node.id);
           const view = (
             <CdlNodeView
-              node={node}
+              node={段階の補足 ? { ...node, subtitle: undefined } : node}
+              compactTitleInset={段階の補足 ? STAGE_CARD_TEXT_INSET : undefined}
               active={activeSet.has(node.id)}
               // 描画側の固定の字の言語 (#847)。 `layout` が既定以外の時だけ `lang` を持たせる
               lang={laid.lang}
@@ -463,20 +685,41 @@ export function CdlStage({
               値の名前={値の名前}
               currentPhaseId={currentPhase?.id}
               chartLineScale={chartLineScales.get(node.id)}
+              metroDiagram={路線図}
+              metroDecision={metroDecisionIds.has(node.id)}
+              stationNameRight={stationNamesRight.has(node.id)}
             />
           );
           return <g key={node.id}>{view}</g>;
         })}
 
+        {/* 段階列か補助線を持つ札は、既存の subtitle 入力を名前と同じ行の右端へ置く。 */}
+        {stageNoteNodes.map((node) => (
+          <text
+            key={`stage-note-${node.id}`}
+            data-cdl-role="stage-note"
+            data-cdl-stage-node={node.id}
+            x={node.cx + node.w / 2 - STAGE_CARD_TEXT_INSET}
+            y={node.cy + 1}
+            fontSize={14}
+            fontWeight={500}
+            textAnchor="end"
+            dominantBaseline="middle"
+            fill="var(--cdl-text-mute, #8a8678)"
+          >
+            {interpolate(node.subtitle, stateValues, 値の名前)}
+          </text>
+        ))}
+
         {/* 経由 node 貫通する dotted-flow edge の進行点 glow (3rd pass) */}
         {laid.edges
-          .filter((edge) => Boolean(edge.dThrough) && 矢印の出番.出るか(edge.id))
+          .filter((edge) => Boolean(edge.dThrough) && 線を描く(edge))
           .map((edge) => (
             <CdlEdgeGlowView key={`glow-${edge.id}`} edge={edge} active={activeSet.has(edge.id)} />
           ))}
 
         {/* edge labels (3rd pass) ... 全 edge の label を最前面に描画 */}
-        {laid.edges.filter((edge) => 矢印の出番.出るか(edge.id)).map((edge) => (
+        {laid.edges.filter(線を描く).map((edge) => (
           <CdlEdgeLabelView
             key={`label-${edge.id}`}
             edge={edge}
@@ -487,7 +730,7 @@ export function CdlStage({
 
         {/* 線の端に添える字 (#821 / #825)。 札と同じ最前面の pass */}
         {laid.edges
-          .filter((edge) => (edge.headLabel || edge.tailLabel) && 矢印の出番.出るか(edge.id))
+          .filter((edge) => (edge.headLabel || edge.tailLabel) && 線を描く(edge))
           .flatMap((edge) =>
             (["head", "tail"] as const).map((端) => (
               <CdlEdgeEndLabelView
@@ -500,6 +743,8 @@ export function CdlStage({
             )),
           )}
 
+        {laid.legend && <CdlLegend items={laid.legend} />}
+
         {/* debug overlay = engine が把握している bbox + collision を半透明で重ね描き */}
         {debug && (
           <g pointerEvents="none">

package/src/render/template-fields.ts

@@ -51,6 +51,8 @@ type 読まない欄 =
   | "posH"
   | "role"
   | "tone"
+  // 補助線の行き先は node id で、描画側が字の差し込みに掛けない。
+  | "leaderTo"
   | "shape"
   | "chartData"
   | "chartFillUnder"

package/src/types.ts

@@ -30,7 +30,7 @@ export type Tone = (typeof TONES)[number];
 export type CdlTextMetrics = "proportional" | "monospace";
 
 /**
- * cdl SVG に付与される data-cdl-role attribute の SSOT 型 (現在 12 role)。
+ * cdl SVG に付与される data-cdl-role attribute の SSOT 型。
  * consumer app (dragon 等) は `[data-cdl-role="<role>"]` selector で CSS を宛てる。 role を追加する時は本 union と該当 render 箇所 (kinds/*.tsx、
  * render/edges.tsx、 render/stage.tsx) を同時に更新する。
  *
@@ -54,6 +54,21 @@ export type CdlTextMetrics = "proportional" | "monospace";
  *   - "lane-container"  ... lane.contain=true の boundary rect
  *   - "lane-lifeline"   ... lane.lifeline=true の縦点線 line
  *   - "lane-label"      ... lane 見出し text
+ *   - "metro-lane-badge" ... 路線用 lane の担当を示す名札
+ *   - "metro-lane-guide" ... 路線用 lane の名札から右へ伸びる案内線
+ *   - "mark-start"      ... 路線図の始まりの印
+ *   - "mark-end"        ... 路線図の終わりの印
+ *   - "legend"          ... 図の下へ横一列に置く凡例全体
+ *   - "legend-item"     ... 凡例の 1 項目
+ *   - "legend-mark"     ... 凡例項目の印
+ *   - "legend-text"     ... 凡例項目の文字
+ *   - "stage-column"    ... lane.stage を持つ段階列の面
+ *   - "stage-number"    ... 段階列の見出しに出す番号
+ *   - "stage-name"      ... 段階列の見出しに出す名前
+ *   - "stage-divider"   ... 段階列の見出しと中身を分ける線
+ *   - "stage-note"      ... 段階列にある札か、補助線を持つ札の右側へ置く補足
+ *   - "timeline-axis"   ... lane.timelineAxis=true の縦実線
+ *   - "timeline-leader" ... node.leaderTo で札から時間軸の番号へ結ぶ矢印なしの補助線
  */
 export type CdlRole =
   | "node-body"
@@ -67,7 +82,44 @@ export type CdlRole =
   | "edge-label"
   | "lane-container"
   | "lane-lifeline"
-  | "lane-label";
+  | "lane-label"
+  | "metro-lane-badge"
+  | "metro-lane-guide"
+  | "mark-start"
+  | "mark-end"
+  | "legend"
+  | "legend-item"
+  | "legend-mark"
+  | "legend-text"
+  | "stage-column"
+  | "stage-number"
+  | "stage-name"
+  | "stage-divider"
+  | "stage-note"
+  | "timeline-axis"
+  | "timeline-leader";
+
+/** 凡例に描ける印。 配置・描画・検査はこの 1 つの列を出所にする。 */
+export const LEGEND_MARKS = [
+  "diamond",
+  "filled-circle",
+  "double-circle",
+  "dotted-line",
+  "solid-line",
+  "curved-line",
+  "rounded-label",
+  "numbered-circle",
+  "station",
+  "arrow",
+] as const;
+
+export type LegendMark = (typeof LEGEND_MARKS)[number];
+
+/** 図の下へ置く凡例の 1 項目。 */
+export type CdlLegendItem = {
+  mark: LegendMark;
+  text: string;
+};
 
 /** 描画できる箱の種類。 検査・記法一覧・型はこの 1 つの列を出所にする。 */
 export const NODE_KINDS = [
@@ -191,12 +243,14 @@ export const NODE_KINDS = [
   "shape-lawyer",
   "shape-trader",
   "shape-customer-service",
-  // 流れの始まりと終わりの印 2 種 (#560) ... 塗った丸と輪で囲んだ丸。
-  // 状態遷移図が使う。 印そのものが意味を持つので文字は描かない
+  // 流れの始まりと終わりの印 2 種 (#560) ... 始点と終点は線の端から推測せず、著者が
+  // `kind: "mark-start"` / `kind: "mark-end"` の node を明示する。印は文字を描かない
   "mark-start",
   "mark-end",
   // 路線図の駅 (#996) ... 線路上の点を小さな丸で示し、名前と説明は丸の外に置く
   "station",
+  // 時間軸の番号 (#1017) ... 実線の軸上に番号を入れた丸を置く。路線図の駅とは別の意味を持つ。
+  "timeline-number",
   // 時系列のやり取り (#578) ... 1 つの箱が図を丸ごと描く。 縦が時間で、参加者は箱を持たない
   "sequence-board",
 ] as const;
@@ -225,7 +279,9 @@ export type EdgeStyle = "solid" | "dotted-flow" | "dashed";
  * - `"back-detour"` ... 箱の上を回って前の箱へ戻り、途中の箱と交わる時は外側を回る
  * - `"curve"` ... 始点から水平に出て終点へ水平に入る 3 次曲線。 途中の箱は避けず、
  *   2 点が同じ高さなら直線になる。 終点の矢印は水平を向く
- * - `"metro"` ... 横線と傾き ±1 の斜線だけで結び、角を半径 r の円弧で丸める。
+ * - `"metro"` ... 通常は横線と傾き ±1 の斜線で結び、角を円弧で丸める。
+ *   `decision` からの枝は、行き先が同じ横位置なら上下の角から真っ直ぐ、右にあれば右の角から出て曲がる。
+ *   左へ戻る `dashed` は行き先側へ横に出して駅の上下へ入る。
  *   途中の箱は避けず、2 点が同じ高さなら横 1 本になる
  */
 export type EdgeRouting = "default" | "back-detour" | "curve" | "metro";
@@ -407,7 +463,29 @@ export type CdlLane = {
    */
   width: number;
   label?: string;
+  /**
+   * 路線図の担当として描く lane。 `label` を名札の名前、`subtitle` をその補足に使う。
+   *
+   * 書いた lane だけが名札と案内線を出す。書かない lane の出力は変わらない。
+   */
+  metro?: {
+    subtitle?: string;
+  };
   contain?: boolean;
+  /**
+   * lane を同じ上端・高さの段階列として描く時の見出し。
+   *
+   * `number` と `name` は別の SVG text に出るため、利用側は `stage-number` と `stage-name` を
+   * 個別に選べる。この lane にある `card` node の `subtitle` は、札の右側へ `stage-note` として
+   * 描き、通常の card の補足位置には出さない。
+   * `leaderTo` を持つ `card` も、段階列の内外にかかわらず同じ `stage-note` を使う。
+   *
+   * 書かない lane は既存の縦列のままで、`lane-container` / `lane-label` の入力と出力は変わらない。
+   */
+  stage?: {
+    number: string;
+    name: string;
+  };
   /**
    * この lane を何のために置いているか (既定 = `"column"`)。
    *
@@ -427,6 +505,12 @@ export type CdlLane = {
   role?: "column" | "overlay";
   /** UML sequence diagram の lifeline (= lane の中央 x に縦の点線を描画) */
   lifeline?: boolean;
+  /**
+   * lane の中央 x に時間軸の実線を描く。線はこの lane にある描画対象 node の中心間を結ぶ。
+   *
+   * `lifeline` の点線とは独立しており、両方を書いた lane では両方を描く。
+   */
+  timelineAxis?: boolean;
   /**
    * 明示指定した座標。 `posX` と `posY` の **両方**が揃った lane は「置いた位置に置く」
    * 扱いになる。 片方だけでは何も変わらない。
@@ -453,6 +537,11 @@ export type CdlNode = {
   title: string;
   eyebrow?: string;
   subtitle?: string;
+  /**
+   * この箱から指定した node へ矢印なしの補助線を引く。edge ではないため `laid.edges` には入らない。
+   * `card` の `subtitle` は札の右側へ `stage-note` として描き、通常の補足位置には出さない。
+   */
+  leaderTo?: string;
   /** mono 数値表示用、 `{stateId}` を含めれば state 値で動的置換 */
   value?: string;
   /** kind=storage 時の行 (各 mono、 state 参照可) */
@@ -2783,6 +2872,8 @@ export type CdlDiagram = {
    * 種類を書いていない図にも当たる。
    */
   type?: string;
+  /** SVG 内の図の下へ、指定順の横一列で置く凡例。 */
+  legend?: readonly CdlLegendItem[];
   /**
    * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
    *
@@ -2973,6 +3064,14 @@ export type LaidEdge = CdlEdge & {
   labelX: number;
   labelY: number;
   labelAnchor: "start" | "middle" | "end";
+  /** 前の station へ戻る metro 線だけが持つ、専用の点線と矢印を描く目印。 */
+  metroReturn?: true;
+};
+
+export type LaidLegendItem = CdlLegendItem & {
+  x: number;
+  /** 文字の baseline。 印はこの値を基準に同じ行へ揃える。 */
+  y: number;
 };
 
 /**
@@ -3008,6 +3107,8 @@ export type LaidDiagram = {
   textMetrics?: "monospace";
   /** どの種類の図か (#645)。 `CdlDiagram.type` をそのまま持ち越す */
   type?: string;
+  /** 指定がある図だけが持つ、配置済みの凡例。 */
+  legend?: readonly LaidLegendItem[];
   viewBox: { x: number; y: number; w: number; h: number };
   /**
    * 図全体の倍率 (`CdlViewport.scale` を正規化した値)。

package/src/validate.ts

@@ -191,6 +191,11 @@ export function validate(diag: CdlDiagram): void {
         `[cdl] unknown-ref: node "${n.id}" の lane "${n.lane}" が未定義です${suggest(n.lane, laneIds)}\n  → 修正例: .lane("${n.lane}", { x: 0, width: 400 }) を node 宣言前に追加`,
       );
     }
+    if (n.leaderTo !== undefined && !nodeIds.has(n.leaderTo)) {
+      errors.push(
+        `[cdl] unknown-ref: node "${n.id}" の leaderTo "${n.leaderTo}" が node に存在しません${suggest(n.leaderTo, nodeIds, "node")}`,
+      );
+    }
   }
   for (const e of diag.edges) {
     if (!nodeIds.has(e.from)) {

package/src/visual-validate.ts

@@ -151,11 +151,10 @@ import {
   rendersTitleText,
   fitsOwnTitleWidth,
   skipsNodeTitleWidthCheck,
-  drawsTitleOutsideBox,
   titleScalesToFit,
   MIN_TITLE_FONT_SIZE,
   titleFontSize,
-  TITLE_BOX_PADDING,
+  titleUsableWidth,
   rowBaselineY,
   rowGlyphDepth,
   laneVerticalRange,
@@ -2007,8 +2006,10 @@ function runAxes(
   const LIFELINE_W_THRESHOLD = 8;
   for (const n of laid.nodes) {
     if (n.w < LIFELINE_W_THRESHOLD) continue;
-    // 駅は文字を収める箱ではなく線路上の印なので、箱向けの最小寸法を要求しない。
-    if (n.kind === "station") continue;
+    // 駅と丸い番号は文字を収める箱ではなく軸上の印なので、箱向けの最小寸法を要求しない。
+    // 丸い番号は見本の半径 24 と縁 4 から大きさが決まり、80×40 を求めると軸より太くなる。
+    // 番号の字が読めるかは軸 3 (text-readability) が引き続き見る。
+    if (n.kind === "station" || n.kind === "timeline-number") continue;
     if (n.w < MIN_NODE_W || n.h < MIN_NODE_H) {
       push(
         "node-visibility",
@@ -2065,8 +2066,7 @@ function runAxes(
     //
     // 箱の内側の余白 (52) は、題を箱の中に描く種別にだけ足す。 箱の外に描く種別 (`dyn-*` の
     // 名前と図表の題) は内側の余白に縛られないので、足すと収まっている題まで挙がる。
-    const 余白 = drawsTitleOutsideBox(n.kind) ? 0 : TITLE_BOX_PADDING;
-    const 使える幅 = n.w - 余白;
+    const 使える幅 = titleUsableWidth(n.kind, n.w, n.h);
     const 実幅 = measureTextWidth(titleTrimmed, {
       fontSize: titleFontSize(n.kind),
       bound: "drawn",
@@ -2089,7 +2089,7 @@ function runAxes(
       push(
         "text-readability",
         // 字ごとの実幅は小数になるので、読む人に出す時だけ丸める (判定は丸めない)
-        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${Math.round(実幅 + 余白)}px)`,
+        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${Math.round(実幅 + (n.w - 使える幅))}px)`,
         "warn",
       );
     }