@cardenelabs/cdl 0.17.0 → 0.18.0

package/dist/{render-Dc5Pdf7e.d.cts → render-Czv0tUon.d.cts}

@@ -162,6 +162,12 @@ type EdgeHeadFill = "solid" | "hollow";
 declare const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill;
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 declare const EDGE_HEAD_FILLS: readonly EdgeHeadFill[];
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+type EdgeReveal = "phase" | "all";
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+declare const EDGE_REVEALS: readonly EdgeReveal[];
+/** 書かなかった時の値 (#582) */
+declare const EDGE_REVEAL_DEFAULT: EdgeReveal;
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2409,6 +2415,22 @@ type CdlDiagram = {
      * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
      */
     structuredData?: "extract" | "exclude";
+    /**
+     * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+     *
+     * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+     * - `"all"` ... 段に関わらず最初から全部描く
+     *
+     * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+     * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+     * ちらついたようにしか見えない)。
+     *
+     * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+     * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+     *
+     * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+     */
+    edgeReveal?: EdgeReveal;
     /**
      * interactive input widgets (v0.5+、 CAR #243)。
      * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2619,6 +2641,8 @@ type LaidDiagram = {
     phases: CdlPhase[];
     /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
     derived?: CdlDerivedValue[];
+    /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+    edgeReveal?: EdgeReveal;
     /**
      * キャンバス全要素の bounding box list。
      * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。
@@ -2786,4 +2810,4 @@ type CdlDiagramViewProps = {
 };
 declare function CdlDiagramView({ diagram, laid: laidProp, hideHeader, hideMiniPhaseIndicator, focusPhaseId, debug, emitGeometryWarn, headingLevel, interactiveHandlers }: CdlDiagramViewProps): JSX.Element;
 
-export { type LaidLane as A, type BBox as B, type CdlDiagram as C, NODE_KINDS as D, type EdgeStyle as E, type ScrollProgressHandle as F, TONES as G, computeEventBindingKey as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, computeFormulaKey as K, type LaidDiagram as L, computeInputSignalKey as M, type NodeKind as N, computeScrollTriggerKey as O, computed as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, createInteractiveSignalsAccessor as U, createScrollProgressHandle as V, createScrollProgressSignals as W, hasInteractivePrimitives as X, sequenceBoardMetrics as Y, sequenceStepId as Z, signal as _, type CdlInput as a, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_STYLES as y, type InteractiveSignalsAccessor as z };
+export { sequenceBoardMetrics as $, EDGE_STYLES as A, type BBox as B, type CdlDiagram as C, type EdgeReveal as D, type EdgeStyle as E, type InteractiveSignalsAccessor as F, type LaidLane as G, NODE_KINDS as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, type ScrollProgressHandle as K, type LaidDiagram as L, TONES as M, type NodeKind as N, computeEventBindingKey as O, computeFormulaKey as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, computeInputSignalKey as U, computeScrollTriggerKey as V, computed as W, createInteractiveSignalsAccessor as X, createScrollProgressHandle as Y, createScrollProgressSignals as Z, hasInteractivePrimitives as _, type CdlInput as a, sequenceStepId as a0, signal as a1, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_REVEALS as y, EDGE_REVEAL_DEFAULT as z };

package/dist/{render-Dc5Pdf7e.d.ts → render-Czv0tUon.d.ts}

@@ -162,6 +162,12 @@ type EdgeHeadFill = "solid" | "hollow";
 declare const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill;
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 declare const EDGE_HEAD_FILLS: readonly EdgeHeadFill[];
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+type EdgeReveal = "phase" | "all";
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+declare const EDGE_REVEALS: readonly EdgeReveal[];
+/** 書かなかった時の値 (#582) */
+declare const EDGE_REVEAL_DEFAULT: EdgeReveal;
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2409,6 +2415,22 @@ type CdlDiagram = {
      * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
      */
     structuredData?: "extract" | "exclude";
+    /**
+     * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+     *
+     * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+     * - `"all"` ... 段に関わらず最初から全部描く
+     *
+     * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+     * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+     * ちらついたようにしか見えない)。
+     *
+     * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+     * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+     *
+     * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+     */
+    edgeReveal?: EdgeReveal;
     /**
      * interactive input widgets (v0.5+、 CAR #243)。
      * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2619,6 +2641,8 @@ type LaidDiagram = {
     phases: CdlPhase[];
     /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
     derived?: CdlDerivedValue[];
+    /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+    edgeReveal?: EdgeReveal;
     /**
      * キャンバス全要素の bounding box list。
      * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。
@@ -2786,4 +2810,4 @@ type CdlDiagramViewProps = {
 };
 declare function CdlDiagramView({ diagram, laid: laidProp, hideHeader, hideMiniPhaseIndicator, focusPhaseId, debug, emitGeometryWarn, headingLevel, interactiveHandlers }: CdlDiagramViewProps): JSX.Element;
 
-export { type LaidLane as A, type BBox as B, type CdlDiagram as C, NODE_KINDS as D, type EdgeStyle as E, type ScrollProgressHandle as F, TONES as G, computeEventBindingKey as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, computeFormulaKey as K, type LaidDiagram as L, computeInputSignalKey as M, type NodeKind as N, computeScrollTriggerKey as O, computed as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, createInteractiveSignalsAccessor as U, createScrollProgressHandle as V, createScrollProgressSignals as W, hasInteractivePrimitives as X, sequenceBoardMetrics as Y, sequenceStepId as Z, signal as _, type CdlInput as a, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_STYLES as y, type InteractiveSignalsAccessor as z };
+export { sequenceBoardMetrics as $, EDGE_STYLES as A, type BBox as B, type CdlDiagram as C, type EdgeReveal as D, type EdgeStyle as E, type InteractiveSignalsAccessor as F, type LaidLane as G, NODE_KINDS as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, type ScrollProgressHandle as K, type LaidDiagram as L, TONES as M, type NodeKind as N, computeEventBindingKey as O, computeFormulaKey as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, computeInputSignalKey as U, computeScrollTriggerKey as V, computed as W, createInteractiveSignalsAccessor as X, createScrollProgressHandle as Y, createScrollProgressSignals as Z, hasInteractivePrimitives as _, type CdlInput as a, sequenceStepId as a0, signal as a1, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_REVEALS as y, EDGE_REVEAL_DEFAULT as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "CDL (Chainome Diagram Language). Mermaid-like declarative DSL that compiles to animated SVG diagrams. Built for blockchain / Solidity flows, generic enough for sequence / flow / state / ER / topology diagrams.",
   "license": "MIT",
   "author": "cardene777",

package/src/index.ts

@@ -284,6 +284,7 @@ export type {
   CdlState,
   EdgeHead,
   EdgeHeadFill,
+  EdgeReveal,
   RowMark,
   EdgeStyle,
   LaidDiagram,
@@ -305,6 +306,8 @@ export {
   EDGE_HEAD_DEFAULT,
   EDGE_HEAD_FILLS,
   EDGE_HEAD_FILL_DEFAULT,
+  EDGE_REVEALS,
+  EDGE_REVEAL_DEFAULT,
   EDGE_STYLES,
 } from "./types";
 

package/src/kinds/sequence-board.tsx

@@ -68,7 +68,15 @@ export function SequenceBoardNode({
     const v = Number.parseInt(interpolate(node.sequenceStep, stateValues ?? {}).trim(), 10);
     return Number.isFinite(v) ? v : null;
   })();
-  const 朱 = "var(--cdl-tone-accent, #2d6a8f)";
+  /*
+   * いまの言づての色 (#580)。
+   *
+   * **意味の 6 色とは別に持つ**。 `--cdl-tone-accent` は「呼び」 のような図の中の意味を
+   * 描き分ける色で、利用側が系統色から取ることがある (実測 = dragon は青)。 ここが指すのは
+   * 意味ではなく「いまどこか」 で、役割は強調した箱の枠と同じ = 利用側の主役色に揃うべき。
+   * 書かれていなければ従来どおり意味の色へ落ちる。
+   */
+  const 朱 = "var(--cdl-now, var(--cdl-tone-accent, #2d6a8f))";
   /** 済んだ言づての色。 薄めるのではなく墨へ移すので、後からでも読める濃さを持つ */
   const 墨 = "var(--cdl-text-2, #4a5162)";
 

package/src/kinds/storage.tsx

@@ -7,6 +7,7 @@ import {
   ROW_TOP_STORAGE,
   STORAGE_ROW_DIVIDER_Y,
   STORAGE_TITLE_BASELINE,
+  STORAGE_TITLE_FONT,
   SUBTITLE_ROW_SHIFT,
   rowBaselineY,
   rowGlyphDepth,
@@ -37,7 +38,7 @@ const ROW_GLYPH_CX = ROW_PAD_X_PX + ROW_GLYPH_HALF + 1;
 const ROW_GLYPH_LEAD = 40;
 
 /** 印を持つ行の型の級。 名前 (26) より 1 段落とし、色も薄くして名前を先に読ませる */
-const ROW_TYPE_FONT = 24;
+const ROW_TYPE_FONT = 22;
 
 /** 印の中心を baseline からどれだけ上へ置くか。 級の 1/3 が字の見た目の中心 */
 const ROW_GLYPH_RISE = 8;
@@ -48,10 +49,10 @@ const ROW_GLYPH_RISE = 8;
  * 題 (78) と 1 行目 (130) の間。 印で分ける箱では区切り線を引かないので、その分の余白が空く。
  * ER の表名や状態の名前は識別子なので、その下に日本語の呼び名を薄く添える。
  */
-const SUBTITLE_BASELINE = 108;
+const SUBTITLE_BASELINE = 118;
 
 /** 呼び名の級。 行の名前 (26) より小さく、型 (24) と同じ */
-const SUBTITLE_FONT = 22;
+const SUBTITLE_FONT = 20;
 
 /** 主キーの下線を名前の baseline からどれだけ下に引くか */
 const UNDERLINE_DROP = 7;
@@ -98,7 +99,7 @@ export function StorageNode({
   const x = node.cx - node.w / 2;
   const y = node.cy - node.h / 2;
   // 小型の箱では名前を中央に置く。 固定の位置のままだと下端をまたぐ (#416)
-  const 名前 = titlePlacement(node, { x: 26, y: STORAGE_TITLE_BASELINE, size: 22 }, { hasEyebrow: Boolean(node.eyebrow) });
+  const 名前 = titlePlacement(node, { x: 26, y: STORAGE_TITLE_BASELINE, size: STORAGE_TITLE_FONT }, { hasEyebrow: Boolean(node.eyebrow) });
   // 全 row を delimiter (`:` / ` = ` / ` → ` / ` -> `) で left / right に分割し、
   // left 列 max 文字数を算出 → 右列の固定 x 位置を決める (DB table / UML class box 風)。
   // 結果として全 row の右列開始 x が揃い、 区切り線がガタつかなくなる。

package/src/layout/nodes.ts

@@ -189,18 +189,19 @@ export function layoutNodes(diag: CdlDiagram, lanes: LaidLane[]): LaidNode[] {
     const 段の芯 = rowCy.get(n.stack)!;
     const 段の高さ = rowH.get(n.stack)!;
     /*
-     * 行頭の印を持つ箱は **自分の高さで、段の上端に揃える** (#578)。
+     * 行頭の印を持つ箱は **自分の高さで、段の芯に揃える** (#578 → #580)。
      *
-     * 既定は段の高さに合わせて伸ばし、芯で揃える = 同じ段の箱の上端も下端も揃う。 行が
-     * 1 つしか無い箱が 4 行の箱と同じ高さになるので、下が空いたまま並ぶ。
+     * 既定は段の高さに合わせて伸ばす = 行が 1 つしか無い箱が 4 行の箱と同じ高さになり、
+     * 下が空いたまま並ぶ。 印を持つ箱は高さを中身から出しているので (`autoStorageHeight`)、
+     * 伸ばすとその値が捨てられる。
      *
-     * 印を持つ箱では高さを中身から出しているので (`autoStorageHeight`)、伸ばすとその値が
-     * 捨てられる。 上端で揃えるのは、読み手が箱の題を横に見比べる順に読むため = 下端は
-     * 中身の量で決まってよい。
+     * **揃える先は芯**。 #578 では上端に揃えていたが、高さの違う箱が横に並ぶと
+     * 図全体が上へ寄って見えた (user 指摘)。 芯で揃えると上端も下端も箱ごとに違うが、
+     * 並びの重心が 1 本に通る。 見た目検査の `row-alignment` もこの前提で書かれている。
      */
     const 自前の高さ = n.rowMarks !== undefined;
     const h = n.h ?? (自前の高さ ? autoStorageHeight(n, size.h) : 段の高さ);
-    const cy = 自前の高さ ? 段の芯 - 段の高さ / 2 + h / 2 : 段の芯;
+    const cy = 段の芯;
     // n.w 明示時は尊重、 未指定で rows[] を持つ node は内容長に合わせて auto 拡張。
     const w = autoRowsWidth(n, size.w);
     out.push({

package/src/layout/spec.ts

@@ -242,8 +242,13 @@ export function genericTitleBaselineY(kind: string | undefined, h: number, hasRo
     : GENERIC_TITLE_TOP + genericTextShift(kind);
 }
 
-/** `kinds/storage.tsx` の 1 行目 baseline と行送り。 */
-export const ROW_TOP_STORAGE = 130;
+/**
+ * `kinds/storage.tsx` の 1 行目 baseline と行送り。
+ *
+ * 1 行目は #1468 で 130 から下げた。 題を 22 から 34 に上げたぶん、題の下に空きが要る
+ * (実測 = 130 のままだと題の descender と 1 行目の cap が 6 まで詰まる)。
+ */
+export const ROW_TOP_STORAGE = 152;
 export const ROW_PITCH_STORAGE = 56;
 
 /** `kinds/generic.tsx` の 1 行目 baseline と行送り。 */
@@ -276,8 +281,21 @@ export const GLYPH_CAP_RATIO = 0.72;
 export const ROW_FONT_STORAGE = 26;
 export const ROW_FONT_GENERIC = 21;
 
-/** `kinds/storage.tsx` の名前 (title) の baseline。 */
-export const STORAGE_TITLE_BASELINE = 78;
+/**
+ * `kinds/storage.tsx` の名前 (title) の baseline。
+ *
+ * #1468 で 78 から下げた。 題が 34 になり、上端から baseline までに cap 分の余白が要る。
+ */
+export const STORAGE_TITLE_BASELINE = 86;
+
+/**
+ * `kinds/storage.tsx` の名前 (title) の字の大きさ (#1468)。
+ *
+ * **行 (`ROW_FONT_STORAGE` = 26) より大きい**。 22 だった間は題の方が小さく、箱の中で
+ * 何が見出しか読み取れなかった (user 指摘)。 題 34 / 行 26 / 型 22 の 3 段にして、
+ * 上から順に読む順序を字の大きさで示す。
+ */
+export const STORAGE_TITLE_FONT = 34;
 
 /**
  * 呼び名を出す箱で、行の群をどれだけ下げるか (#578)。

package/src/layout.ts

@@ -371,6 +371,8 @@ export function layout(diag: CdlDiagram): LaidDiagram {
     states: diag.states,
     phases: diag.phases,
     ...(diag.derived ? { derived: diag.derived } : {}),
+    // 矢印をいつ出すか (#582)。 描き手が読む欄なので、そのまま持ち越す
+    ...(diag.edgeReveal ? { edgeReveal: diag.edgeReveal } : {}),
     bboxes,
     collisions,
     nearCollisions,

package/src/render/stage.tsx

@@ -1,5 +1,12 @@
 import { useMemo, type JSX } from "react";
-import { EDGE_HEADS, EDGE_HEAD_FILLS, EDGE_HEAD_FILL_DEFAULT, type CdlPhase, type LaidDiagram } from "../types";
+import {
+  EDGE_HEADS,
+  EDGE_HEAD_FILLS,
+  EDGE_HEAD_FILL_DEFAULT,
+  EDGE_REVEAL_DEFAULT,
+  type CdlPhase,
+  type LaidDiagram,
+} from "../types";
 import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeLabelView } from "./edges";
 import { CdlNodeView } from "./nodes";
 import { TONE, TONE_HEX } from "./tone";
@@ -27,6 +34,33 @@ export function CdlStage({
   svgRef?: React.RefObject<SVGSVGElement | null>;
 }): JSX.Element {
   const activeSet = new Set(currentPhase?.activate ?? []);
+  /*
+   * まだ出番の来ていない矢印は描かない (#582)。
+   *
+   * 段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が 1 段目から見えていた。 段が進むと
+   * その矢印だけが引き直されるが、既に見えているので「増えた」 ようには読めず、無関係な線が
+   * ちらついたようにしか見えない (user 実機確認)。
+   *
+   * **段のどこかで光る矢印だけを対象にする**。 段が矢印を 1 度も名指ししない図では、矢印は
+   * 図の骨格そのものなので隠す理由が無い。 1 度出たら以降は出したままにする = 消える向きの
+   * 動きは、読み手が「戻った」 と読む。
+   *
+   * 著者が `edgeReveal: "all"` と書いた図では隠さない。
+   */
+  const 出番の来た矢印 = useMemo(() => {
+    // 著者が「最初から全部見せる」 と書いた図では隠さない (#582)
+    if ((laid.edgeReveal ?? EDGE_REVEAL_DEFAULT) === "all") return () => true;
+    const 初出 = new Map<string, number>();
+    laid.phases.forEach((p, i) => {
+      for (const id of p.activate ?? []) if (!初出.has(id)) 初出.set(id, i);
+    });
+    const 今 = currentPhase === undefined ? -1 : laid.phases.findIndex((p) => p.id === currentPhase.id);
+    return (edgeId: string): boolean => {
+      const first = 初出.get(edgeId);
+      if (first === undefined) return true;
+      return 今 < 0 || 今 >= first;
+    };
+  }, [laid.phases, currentPhase]);
   // この phase で左の起点から描き始める node (cdl#512)。 `activate` とは別集合で持つ =
   // 焦点が当たり続ける図で毎 phase 引き直すことになるため、 光っているかを引き金にしない
   const drawSet = new Set(currentPhase?.draw ?? []);
@@ -231,7 +265,7 @@ export function CdlStage({
         ))}
 
         {/* edges (1st pass) */}
-        {laid.edges.map((edge) => (
+        {laid.edges.filter((edge) => 出番の来た矢印(edge.id)).map((edge) => (
           <CdlEdgeView key={edge.id} edge={edge} active={activeSet.has(edge.id)} progress={progress} stateValues={stateValues} />
         ))}
 
@@ -256,13 +290,13 @@ export function CdlStage({
 
         {/* 経由 node 貫通する dotted-flow edge の進行点 glow (3rd pass) */}
         {laid.edges
-          .filter((edge) => Boolean(edge.dThrough))
+          .filter((edge) => Boolean(edge.dThrough) && 出番の来た矢印(edge.id))
           .map((edge) => (
             <CdlEdgeGlowView key={`glow-${edge.id}`} edge={edge} active={activeSet.has(edge.id)} />
           ))}
 
         {/* edge labels (3rd pass) ... 全 edge の label を最前面に描画 */}
-        {laid.edges.map((edge) => (
+        {laid.edges.filter((edge) => 出番の来た矢印(edge.id)).map((edge) => (
           <CdlEdgeLabelView
             key={`label-${edge.id}`}
             edge={edge}

package/src/types.ts

@@ -213,6 +213,15 @@ export const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill = "solid";
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 export const EDGE_HEAD_FILLS: readonly EdgeHeadFill[] = ["solid", "hollow"];
 
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+export type EdgeReveal = "phase" | "all";
+
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+export const EDGE_REVEALS: readonly EdgeReveal[] = ["phase", "all"];
+
+/** 書かなかった時の値 (#582) */
+export const EDGE_REVEAL_DEFAULT: EdgeReveal = "phase";
+
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2480,6 +2489,22 @@ export type CdlDiagram = {
    * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
    */
   structuredData?: "extract" | "exclude";
+  /**
+   * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+   *
+   * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+   * - `"all"` ... 段に関わらず最初から全部描く
+   *
+   * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+   * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+   * ちらついたようにしか見えない)。
+   *
+   * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+   * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+   *
+   * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+   */
+  edgeReveal?: EdgeReveal;
   /**
    * interactive input widgets (v0.5+、 CAR #243)。
    * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2692,6 +2717,8 @@ export type LaidDiagram = {
   phases: CdlPhase[];
   /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
   derived?: CdlDerivedValue[];
+  /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+  edgeReveal?: EdgeReveal;
   /**
    * キャンバス全要素の bounding box list。
    * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。

package/src/visual-validate.ts

@@ -125,6 +125,7 @@ export type { EdgeLabelLine, EdgeLabelTextSpec } from "./label-text";
 import {
   ARROW_ENDPOINT_CENTER_TOL,
   COLUMN_GAP_VARIANCE_TOL,
+  requiredNearClearance,
   DETOUR_CREST_OVERLAP_MIN,
   DETOUR_SLOT_GAP,
   EDGE_STUB_OUT,
@@ -2493,18 +2494,9 @@ function runAxes(
     for (const [stack, group] of byStack) {
       if (group.length < 2) continue;
       const cy0 = group[0]!.cy;
-      /*
-       * **上端で揃える形も認める** (#578 の設計)。
-       *
-       * 高さの違う箱を横に並べる図 (表 / クラス / 状態) では、中心ではなく上端を揃える。
-       * 中心だけを見ると、正しく上端で揃っている行が高さの差の半分だけずれて見える
-       * (実測 = 行数の違う表で 28 の差)。 どちらかで揃っていれば揃っているとみなす。
-       */
-      const top0 = cy0 - (group[0]!.h ?? 0) / 2;
       for (const n of group.slice(1)) {
         const diff = Math.abs(n.cy - cy0);
-        const topDiff = Math.abs(n.cy - (n.h ?? 0) / 2 - top0);
-        if (diff > MIN_ROW_ALIGNMENT_TOLERANCE && topDiff > MIN_ROW_ALIGNMENT_TOLERANCE) {
+        if (diff > MIN_ROW_ALIGNMENT_TOLERANCE) {
           push(
             "row-alignment",
             `stack=${stack} row 内 node "${n.id}" cy=${n.cy.toFixed(1)} が row 基準 cy=${cy0.toFixed(1)} と ${diff.toFixed(1)} world 差 (許容 ${MIN_ROW_ALIGNMENT_TOLERANCE})`,
@@ -4239,24 +4231,37 @@ function runAxes(
       const sorted = [...group].sort((a, b) => a.cy - b.cy);
       const gaps: number[] = [];
       /*
-       * **格子に置く形では上端どうしの間隔で測る** (#578 の設計)。
-       *
-       * 段の位置を著者が決める図 (クラス / 表 / 状態) では、engine が制御しているのは
-       * 段の基準線であって端の間隔ではない。 箱の高さが段ごとに違うと端の間隔は必ずばらつく
-       * (実測 = クラス図の 2 列目で 132 と 300)。 どちらかが揃っていれば揃っているとみなす。
+       * 端の間隔で測る理由は下の Issue #202 の節を参照。
        */
-      const tops: number[] = [];
       for (let i = 1; i < sorted.length; i++) {
         const prev = sorted[i - 1]!;
         const cur = sorted[i]!;
         gaps.push(cur.cy - cur.h / 2 - (prev.cy + prev.h / 2));
-        tops.push(cur.cy - cur.h / 2 - (prev.cy - prev.h / 2));
       }
       const maxGap = Math.max(...gaps);
       const minGap = Math.min(...gaps);
       const variance = maxGap - minGap;
-      const topVariance = Math.max(...tops) - Math.min(...tops);
-      if (variance > COLUMN_GAP_VARIANCE_TOL && topVariance > COLUMN_GAP_VARIANCE_TOL) {
+      /*
+       * **格子に置いた箱では間隔の均一を求めない** (#580)。
+       *
+       * この軸は「engine が縦の間隔を制御している」 ことを前提に、そのばらつきを layout の
+       * 破綻として見る。 行頭の印を持つ箱は前提が違う = 段の位置を著者が `col` / `row` で決め、
+       * 高さは中身から出る (`autoStorageHeight`)。 段ごとに背の高さが違えば、端の間隔も芯の
+       * 間隔も必ずばらつく (実測 = クラス図の 2 列目で端 132/216、芯 528/472)。
+       *
+       * **近づき過ぎだけは見る** (#202)。 間隔の均一を外しても、箱どうしが接する形は通さない
+       * (#202 が実測した形 = 芯の間隔が揃い、端の間隔が 100 と 0)。
+       */
+      const 格子に置く = group.every((n) => n.rowMarks !== undefined);
+      const 端が足りている = minGap >= requiredNearClearance("node", "node");
+      if (格子に置く) {
+        if (!端が足りている) {
+          push(
+            "column-gap-uniform",
+            `lane "${laneId}" 内 node 間の端間 gap ${minGap.toFixed(0)} world が下限 ${requiredNearClearance("node", "node")} を割る`,
+          );
+        }
+      } else if (variance > COLUMN_GAP_VARIANCE_TOL) {
         push(
           "column-gap-uniform",
           `lane "${laneId}" 内 node 間の端間 gap variance ${variance.toFixed(1)} world が spec ${COLUMN_GAP_VARIANCE_TOL} 超過 (min=${minGap.toFixed(0)} max=${maxGap.toFixed(0)})`,