@cardenelabs/cdl 0.14.0 → 0.15.0

package/src/presets.ts

@@ -1538,13 +1538,23 @@ export function quadrant(preset: QuadrantPreset): QuadrantBuilder {
 
 // ─── chart (Pie / Bar / Line 統合) ─────────────────────────────
 
-export type ChartType = "pie" | "bar" | "line";
+export type ChartType =
+  | "pie"
+  | "bar"
+  | "line"
+  | "gauge"
+  | "radial"
+  | "stat"
+  | "waffle"
+  | "stacked-bar";
 
 export type ChartDatum = {
   id: string;
   label: string;
   /** 棒 / 折れ線 / 扇の大きさ。 `{名前}` を書くと状態から読む (#468) */
   value: number | BindingRef;
+  /** 前の時点の値 (cdl#551)。 `type: stacked-bar` で書くと帯が 2 本になる */
+  previous?: number | BindingRef;
   /** 個別 tone (default は preset の defaultTone) */
   tone?: Tone;
 };
@@ -1580,7 +1590,17 @@ 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 canvasH = toGridSize(
+    preset.type === "pie" ||
+    preset.type === "gauge" ||
+    preset.type === "radial" ||
+    preset.type === "stat" ||
+    preset.type === "waffle" ||
+    preset.type === "stacked-bar"
+      ? 320
+      : 360,
+  );
   const b = diagram(preset.id, { topic: preset.topic });
   const data: ChartDatum[] = [];
 
@@ -1588,6 +1608,11 @@ export function chart(preset: ChartPreset): ChartBuilder {
     line: "chart-line" as const,
     pie: "chart-pie" as const,
     bar: "chart-bar" as const,
+    gauge: "chart-gauge" as const,
+    radial: "chart-radial" as const,
+    stat: "chart-stat" as const,
+    waffle: "chart-waffle" as const,
+    "stacked-bar": "chart-stacked-bar" as const,
   };
 
   const api: ChartBuilder = {
@@ -1606,7 +1631,12 @@ export function chart(preset: ChartPreset): ChartBuilder {
         eyebrow: preset.type,
         w: canvasW,
         h: canvasH,
-        chartData: data.map((d) => ({ label: d.label, value: d.value, tone: d.tone })),
+        chartData: data.map((d) => ({
+          label: d.label,
+          value: d.value,
+          ...(d.previous === undefined ? {} : { previous: d.previous }),
+          tone: d.tone,
+        })),
       });
       b.phase(
         "chart",

package/src/render/edge-head.ts

@@ -0,0 +1,45 @@
+import { EDGE_HEAD_DEFAULT, type EdgeHead } from "../types";
+
+/**
+ * 関係の端の形の **描き方と marker の名前** (SSOT、 #560)。
+ *
+ * `render/stage.tsx` が marker を定義し、 `render/edges.tsx` がそれを引く。 2 箇所が別々に
+ * 名前を組み立てると、 片方だけ変えた時に線が指す marker が消えて矢頭が出なくなる
+ * (`tone-marker-ref` 軸が拾うが、 拾うまでの間は矢頭が無い絵になる)。
+ */
+
+export type EdgeHeadShape = {
+  /** 10x10 の viewBox に描く path */
+  d: string;
+  /** path の端のどこを線の先端に合わせるか */
+  refX: number;
+  /** 塗るか。 塗らない形は線で描く */
+  filled: boolean;
+};
+
+/**
+ * 4 形の描き方。
+ *
+ * 塗る形 (三角 / 菱) は線の端を隠すので、線をその手前で止める必要は無い = marker は
+ * 線の上に重なって描かれる。 塗らない形 (開いた矢 / 三又) は隠さない。
+ *
+ * 三又だけ `refX` が 10 = 三又は **開いた側が箱に触る** 形で、他の 3 形と前後が逆になる。
+ * 9 にすると開いた側が箱から 1 だけ浮く。
+ */
+export const EDGE_HEAD_SHAPE: Record<EdgeHead, EdgeHeadShape> = {
+  triangle: { d: "M 0 0 L 10 5 L 0 10 z", refX: 9, filled: true },
+  diamond: { d: "M 0 5 L 5 0 L 10 5 L 5 10 z", refX: 9, filled: true },
+  open: { d: "M 1 0 L 9 5 L 1 10", refX: 9, filled: false },
+  crow: { d: "M 10 0 L 0 5 M 10 5 L 0 5 M 10 10 L 0 5", refX: 10, filled: false },
+};
+
+/**
+ * marker の名前を組み立てる。
+ *
+ * **既定の形は名前を変えない** (`cdl-arrow-<tone>` / `cdl-arrow-<tone>-sm`)。
+ * 端の形を書いていない図はすべて既定なので、名前が変わると全図の矢頭が差し替わる。
+ */
+export function edgeHeadMarkerId(tone: string, head: EdgeHead, small: boolean): string {
+  const 小 = small ? "-sm" : "";
+  return head === EDGE_HEAD_DEFAULT ? `cdl-arrow-${tone}${小}` : `cdl-arrow-${tone}-${head}${小}`;
+}

package/src/render/edges.tsx

@@ -1,5 +1,6 @@
 import type { JSX } from "react";
-import type { LaidEdge } from "../types";
+import { EDGE_HEAD_DEFAULT, type LaidEdge } from "../types";
+import { edgeHeadMarkerId } from "./edge-head";
 import { computeLabelBBoxWorld, hasRenderedLabel, LABEL_PILL_PAD_X } from "../layout/spec";
 import { hasTone, toneColor } from "./tone";
 import { EDGE_LABEL_TEXT, fontFamilyAttr, type EdgeLabelLine } from "../label-text";
@@ -43,8 +44,9 @@ export function CdlEdgeView({
   // 1.0 でも 2.92-5.55)。 dragon は edge 用に濃くした色 (#0063a1 等) を CSS で当てており、
   // その色なら 0.9 で 4.51-4.92 と 4.5:1 を満たす (0.8 では 3.69-4.04 で届かない)。
   // 実線と点線で同じ組を使い、 光らせた側が薄くなる逆転を作らない。
+  // 端の形は線の種類と別の軸 (#560)。 書かなければ既定の塗った三角で、名前も従来のまま
   const marker = hasTone(edge.tone)
-    ? `cdl-arrow-${edge.tone}${active ? "" : "-sm"}`
+    ? edgeHeadMarkerId(edge.tone, edge.head ?? EDGE_HEAD_DEFAULT, !active)
     : "cdl-arrow-muted";
 
   const style = edge.style ?? "solid";

package/src/render/interactive-panel.tsx

@@ -4133,7 +4133,6 @@ function SlopeReadout({
   }
   const pad = 20;
   const range = max - min || 1;
-  const w = viewW - pad * 2;
   const h = viewH - pad * 2;
   const xL = pad;
   const xR = viewW - pad;
@@ -8433,7 +8432,8 @@ function VoiceMessageReadout({
   const barsX = 36;
   const barsW = width - barsX - 44;
   const barsH = 30;
-  const barsY = (height - barsH) / 2;
+  // 縦位置は棒ごとに自分の高さから出す (下の `y`)。 まとめて 1 つ持つと、
+  // 高さの違う棒が同じ位置から描かれて中央で揃わない
   const bw = shown.length > 0 ? barsW / shown.length : 0;
   const activeCount = Math.floor(shown.length * p);
   const durMin = Math.floor(duration / 60);

package/src/render/nodes.tsx

@@ -5,9 +5,15 @@ import { EventNode } from "../kinds/event";
 import { FunctionNode } from "../kinds/function";
 import { StorageNode } from "../kinds/storage";
 import { GenericNode } from "../kinds/generic";
+import { MarkStartNode, MarkEndNode } from "../kinds/terminal-mark";
 import { DynShapeNode } from "../kinds/dyn-shape";
 import { ChartLineNode } from "../kinds/chart-line";
 import { ChartPieNode } from "../kinds/chart-pie";
+import { ChartGaugeNode } from "../kinds/chart-gauge";
+import { ChartRadialNode } from "../kinds/chart-radial";
+import { ChartStatNode } from "../kinds/chart-stat";
+import { ChartWaffleNode } from "../kinds/chart-waffle";
+import { ChartStackedBarNode } from "../kinds/chart-stacked-bar";
 import { ChartBarNode } from "../kinds/chart-bar";
 import { GanttNode } from "../kinds/gantt";
 import { MindMapNode } from "../kinds/mind-map";
@@ -179,6 +185,21 @@ export function CdlNodeView({
             progress={progress}
           />
         );
+      case "chart-gauge":
+        // 段の進みで弧が開く動きは持たない (cdl#549 で対象外にした)
+        return <ChartGaugeNode node={resolvedNode} active={active} stateValues={stateValues} />;
+      case "chart-stacked-bar":
+        // 帯を割合で区切る。 前の時点を書けば 2 本になる (cdl#551)
+        return <ChartStackedBarNode node={resolvedNode} active={active} stateValues={stateValues} />;
+      case "chart-waffle":
+        // 1 個 = 1% の印を 100 個。 段の進みで印が埋まる動きは別 Issue (cdl#552 で対象外)
+        return <ChartWaffleNode node={resolvedNode} active={active} stateValues={stateValues} />;
+      case "chart-stat":
+        // 数値が主役で、弧は輪郭だけの補助。 段の進みで数値が動く演出は既存の tween が担う
+        return <ChartStatNode node={resolvedNode} active={active} stateValues={stateValues} />;
+      case "chart-radial":
+        // 段の進みで弧が伸びる動きは持たない (cdl#550 で対象外にした)
+        return <ChartRadialNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "chart-bar":
         return (
           <ChartBarNode
@@ -339,6 +360,10 @@ export function CdlNodeView({
         return <ShapeTraderNode node={resolvedNode} active={active} />;
       case "shape-customer-service":
         return <ShapeCustomerServiceNode node={resolvedNode} active={active} />;
+      case "mark-start":
+        return <MarkStartNode node={resolvedNode} active={active} />;
+      case "mark-end":
+        return <MarkEndNode node={resolvedNode} active={active} />;
       default:
         // 新 NodeKind 25 種は GenericNode で汎用描画 (kind 別 icon / color / shape)
         return <GenericNode node={resolvedNode} active={active} value={node.value} stateValues={stateValues} />;

package/src/render/payload-binding.ts

@@ -44,7 +44,11 @@ export type BindingResult<T> = { value: T; ok: boolean };
 /** 解決できなかった欄を持つ項目に付く印。 kind 側が DOM 属性に写す */
 export type UnresolvedMark = { unresolved?: true };
 
-export type ResolvedChartDatum = Omit<ChartDatumPayload, "value"> & { value: number } & UnresolvedMark;
+export type ResolvedChartDatum = Omit<ChartDatumPayload, "value" | "previous"> & {
+  value: number;
+  /** 前の時点の値。 書かれていない datum では `undefined` のまま */
+  previous?: number;
+} & UnresolvedMark;
 export type ResolvedFunnelStage = Omit<FunnelStagePayload, "count"> & { count: number } & UnresolvedMark;
 export type ResolvedGanttTask = Omit<GanttTaskPayload, "startIdx" | "endIdx"> & {
   startIdx: number;
@@ -139,10 +143,17 @@ export function resolveChartData(
 ): ResolvedChartDatum[] {
   // 全ての値が有限な数なら配列を組み直さない。 状態を読まない図が毎 frame で項目数ぶんの
   // 割当てを払わないようにするための近道で、 同じ配列をそのまま返すので挙動も変わらない。
-  if (!data.some((d) => needsResolve(d.value))) return data as ResolvedChartDatum[];
+  //
+  // **前の時点の値も同じ判定に入れる** (cdl#551)。 入れないと `{名前}` を書いた `previous` が
+  // 近道を素通りし、状態を読まないまま文字列のまま描画へ流れる。
+  if (!data.some((d) => needsResolve(d.value) || (d.previous !== undefined && needsResolve(d.previous))))
+    return data as ResolvedChartDatum[];
   return data.map((d) => {
     const v = resolveBoundNumber(d.value, values, 0);
-    return v.ok ? { ...d, value: v.value } : { ...d, value: v.value, unresolved: true as const };
+    const 前 = d.previous === undefined ? undefined : resolveBoundNumber(d.previous, values, 0);
+    const 解けた = v.ok && (前 === undefined || 前.ok);
+    const 素 = { ...d, value: v.value, previous: 前?.value };
+    return 解けた ? 素 : { ...素, unresolved: true as const };
   });
 }
 

package/src/render/stage.tsx

@@ -1,10 +1,12 @@
 import { useMemo, type JSX } from "react";
-import type { CdlPhase, LaidDiagram } from "../types";
+import { EDGE_HEADS, type CdlPhase, type LaidDiagram } from "../types";
 import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeLabelView } from "./edges";
 import { CdlNodeView } from "./nodes";
 import { TONE, TONE_HEX } from "./tone";
+import { EDGE_HEAD_SHAPE, edgeHeadMarkerId } from "./edge-head";
 import { buildDiagramAltText } from "../layout/spec";
 import { lifelineStartYs, uniformLifelineEndY } from "../layout/lifeline";
+import { 描く進みに直す } from "../kinds/draw-ratio";
 
 export function CdlStage({
   laid,
@@ -28,6 +30,9 @@ export function CdlStage({
   // この phase で左の起点から描き始める node (cdl#512)。 `activate` とは別集合で持つ =
   // 焦点が当たり続ける図で毎 phase 引き直すことになるため、 光っているかを引き金にしない
   const drawSet = new Set(currentPhase?.draw ?? []);
+  // 描く対象から見た進み (cdl#570)。 `drawRatio` を書かない phase では `progress` と同値で、
+  // 描く速さを phase の長さから切り離すためだけに使う
+  const 描く進み = 描く進みに直す(progress, currentPhase?.drawRatio);
   // 縦線の終点は全 lane で 1 つに揃える (等長保証)。 値の決め方と、 1 lane の異常が図全体から
   // 縦線を消していた形の対処は `uniformLifelineEndY` の説明。
   //
@@ -97,21 +102,35 @@ export function CdlStage({
               光っていない edge も tone の色で描くが、 矢頭の大きさは従来通り小さいまま保つ
               (Issue の制約 = 色だけを足す)。 */}
           {Object.entries(TONE).flatMap(([tone, color]) =>
-            ([["", 14], ["-sm", 10]] as const).map(([suffix, size]) => (
-              <marker
-                key={`${tone}${suffix}`}
-                id={`cdl-arrow-${tone}${suffix}`}
-                viewBox="0 0 10 10"
-                refX="9"
-                refY="5"
-                markerWidth={size}
-                markerHeight={size}
-                markerUnits="userSpaceOnUse"
-                orient="auto-start-reverse"
-              >
-                <path data-cdl-role="edge-arrowhead" d="M 0 0 L 10 5 L 0 10 z" fill={color} />
-              </marker>
-            )),
+            ([["", 14], ["-sm", 10]] as const).flatMap(([suffix, size]) =>
+              EDGE_HEADS.map((head) => {
+                const 形 = EDGE_HEAD_SHAPE[head];
+                return (
+                  <marker
+                    key={`${tone}${suffix}-${head}`}
+                    id={edgeHeadMarkerId(tone, head, suffix === "-sm")}
+                    viewBox="0 0 10 10"
+                    refX={形.refX}
+                    refY="5"
+                    markerWidth={size}
+                    markerHeight={size}
+                    markerUnits="userSpaceOnUse"
+                    orient="auto-start-reverse"
+                  >
+                    <path
+                      data-cdl-role="edge-arrowhead"
+                      data-cdl-edge-head={head}
+                      d={形.d}
+                      fill={形.filled ? color : "none"}
+                      stroke={形.filled ? "none" : color}
+                      strokeWidth={形.filled ? undefined : 1.6}
+                      strokeLinecap={形.filled ? undefined : "round"}
+                      strokeLinejoin={形.filled ? undefined : "round"}
+                    />
+                  </marker>
+                );
+              }),
+            ),
           )}
           {/* tone が TONE 定義に無い edge の受け皿。 visual-validate の tone-marker-ref 軸が
               dead ref を検知するが、 検知するまでの間に矢頭が消えないようにする。 */}
@@ -207,12 +226,16 @@ export function CdlStage({
 
         {/* nodes (2nd pass) */}
         {laid.nodes.map((node) => {
+          // 描く対象だけ進みを引き伸ばす (cdl#570)。 同じ phase の他の node と edge、
+          // および `tweens` は元の進みのまま = 「線はゆっくり、 値は短く」 が 1 つの phase で
+          // 両立する。 対象外にも掛けると値の移りまで速くなる
+          const 描く = drawSet.has(node.id);
           const view = (
             <CdlNodeView
               node={node}
               active={activeSet.has(node.id)}
-              drawing={drawSet.has(node.id)}
-              progress={progress}
+              drawing={描く}
+              progress={描く ? 描く進み : progress}
               stateValues={stateValues}
               currentPhaseId={currentPhase?.id}
             />

package/src/render/tone.ts

@@ -30,6 +30,58 @@ export const TONE_HEX: Record<Tone, string> = {
   info: "#5a8ec1",
 };
 
+/**
+ * 図表の系列の色 (cdl#546)。
+ *
+ * `TONE` は **意味付きの色** で、箱や矢印が「これは異常」 「これは成功」 を示すために使う。
+ * 図表の系列に要るのは意味ではなく **並べて見分けられること** で、選び方の基準が違う。
+ *
+ * 使い回していた間、2 つの困りが出ていた。 明るい画面の `warning` (`#a67a2e`) は彩度が低く
+ * 青と青緑の隣で沈み、色相の離れた暖色を置こうとすると `error` (赤) しか無いので装飾の
+ * つもりの色に「異常」 の意味が乗った。
+ *
+ * ## 選び方
+ *
+ * **色相を離す**。 6 色を色相環におおよそ等間隔で置き、隣り合う 2 色が近くならない順に
+ * 並べた。 彩度は `TONE` より高く取る = 図表は面で見せるので、線や字より彩度を上げても
+ * うるさくならない。
+ *
+ * ## 差し替え
+ *
+ * `TONE` と同じく CSS 変数にする。 dragon 側で `--cdl-chart-N` を定義すれば、明暗で別の値を
+ * 持てる。 定義しなければここの既定値が出る。
+ *
+ * datum に `tone` を明示した場合は `TONE` が優先される (意味を示したい図はそのまま書ける)。
+ */
+export const CHART_SERIES: readonly string[] = [
+  "var(--cdl-chart-1, #4338ca)",
+  "var(--cdl-chart-2, #0d9488)",
+  "var(--cdl-chart-3, #f59e0b)",
+  "var(--cdl-chart-4, #be185d)",
+  "var(--cdl-chart-5, #4d7c0f)",
+  "var(--cdl-chart-6, #0369a1)",
+];
+
+/**
+ * 系列の色の hex のみ。 CSS 変数を評価できない環境 (SSR / 検査) で色を比べる時に使う。
+ *
+ * `CHART_SERIES` と **同じ並び / 同じ長さ** であることは検査が見る。 片方だけ足すと、
+ * 実物と計算が別の色を指す。
+ */
+export const CHART_SERIES_HEX: readonly string[] = [
+  "#4338ca",
+  "#0d9488",
+  "#f59e0b",
+  "#be185d",
+  "#4d7c0f",
+  "#0369a1",
+];
+
+/** 系列の色を順に配る。 6 色を超えたら先頭へ戻る */
+export function chartSeriesColor(idx: number): string {
+  return CHART_SERIES[((idx % CHART_SERIES.length) + CHART_SERIES.length) % CHART_SERIES.length]!;
+}
+
 /** TONE に無い tone が来た時に使う色。 */
 export const TONE_FALLBACK = "#2d6a8f";
 

package/src/types.ts

@@ -58,8 +58,13 @@ export const NODE_KINDS = [
   "service", "api", "frontend", "backend", "webhook", "microservice",
   // データ / 判定 (4)
   "signer", "oracle", "merkle-tree", "decision",
-  // Chart 系 (3) ... 1 node に datum 配列を持ち、 kind 内で全 datum を SVG 描画
-  "chart-pie", "chart-line", "chart-bar",
+  // Chart 系 (5) ... 1 node に datum 配列を持ち、 kind 内で全 datum を SVG 描画。
+  // chart-gauge は合計を主役に置く形 (cdl#549)、 chart-radial は弧の長さで比べる形 (cdl#550)、
+  // chart-stat は数値そのものを主役に置く形 (cdl#553)
+  // chart-waffle は 100 個の印で割合を数えて確かめる形 (cdl#552)
+  "chart-pie", "chart-line", "chart-bar", "chart-gauge", "chart-radial", "chart-stat",
+  // chart-stacked-bar は帯を割合で区切り時点を並べる形 (cdl#551)
+  "chart-waffle", "chart-stacked-bar",
   // Timeline / Mind 系 (2、 CAR-994 Phase B) ... 1 node に payload 配列、 SVG geometry render
   "gantt-timeline", "mind-map",
   // Analytic 系 (4、 CAR-994 Phase C) ... 1 node に payload 配列、 SVG geometry render
@@ -89,6 +94,9 @@ export const NODE_KINDS = [
   // Shape-driven people 6 (CAR-1111 Phase 2-D) ... 職種別 person 型 (監査 / 規制 / 公証 / 弁護 / トレーダ / CS)
   "shape-auditor", "shape-regulator", "shape-notary",
   "shape-lawyer", "shape-trader", "shape-customer-service",
+  // 流れの始まりと終わりの印 2 種 (#560) ... 塗った丸と輪で囲んだ丸。
+  // 状態遷移図が使う。 印そのものが意味を持つので文字は描かない
+  "mark-start", "mark-end",
 ] as const;
 
 export type NodeKind = (typeof NODE_KINDS)[number];
@@ -103,6 +111,26 @@ export type Side = "top" | "right" | "bottom" | "left";
  */
 export type EdgeStyle = "solid" | "dotted-flow";
 
+/**
+ * 関係の **端の形** (#560)。 線の種類 (`EdgeStyle`) とは別の軸で、線の先端に何を置くかを決める。
+ *
+ * - `"triangle"` ... 塗った三角。 **既定**。 書かなければこれになる
+ * - `"diamond"` ... 塗った菱。 「持っている」 側を指す
+ * - `"open"` ... 閉じない 2 本の腕。 向きだけを示し、待たない
+ * - `"crow"` ... 三又。 「多」 を示す (ER の鳥の足)
+ *
+ * 線の種類と分けて持つのは、両者が独立に組み合わさるため。 実線 × 三角 (継ぐ) と
+ * 破線 × 三角 (満たす) は線種で分かれ、実線 × 三角 (継ぐ) と実線 × 菱 (持つ) は端で分かれる。
+ * 1 つの欄に畳むと 2 軸の積を名前で列挙することになり、組合せが増えるたびに語が増える。
+ */
+export type EdgeHead = "triangle" | "diamond" | "open" | "crow";
+
+/** 書かなかった時の端の形。 既存の図はすべてこれで描かれている */
+export const EDGE_HEAD_DEFAULT: EdgeHead = "triangle";
+
+/** 端の形の全種。 marker の定義と検査の走査がこの並びを引く (書き写すとずれる) */
+export const EDGE_HEADS: readonly EdgeHead[] = ["triangle", "diamond", "open", "crow"];
+
 export type CdlLane = {
   id: string;
   /** lane の x 座標 (optional、 未指定なら engine が前 lane 右端 + gap で auto 計算) */
@@ -335,6 +363,16 @@ export type ChartDatumPayload = {
   label: string;
   /** 棒 / 折れ線 / 扇の大きさ。 `{signal}` で状態に追随する */
   value: BoundNumber;
+  /**
+   * **前の時点の値** (cdl#551)。 書くと `chart-stacked-bar` が帯を 2 本描き、
+   * 内訳の変化がそのまま見える。 書かない図は 1 本のまま。
+   *
+   * 節を時点ごとに置く案は採らない = 図表は「1 節に datum 配列を持ち、種別が全 datum を
+   * 描く」 構造で揃っており、節を増やすと配置と組み立て器の両方が別経路になる。
+   *
+   * 3 時点以上は持たない (cdl#551 で対象外)。 足す時は欄の形ごと決め直す。
+   */
+  previous?: BoundNumber;
   tone?: Tone;
 };
 
@@ -452,6 +490,8 @@ export type CdlEdge = {
   side?: Side;
   /** visual style、 default "solid" */
   style?: EdgeStyle;
+  /** 端の形、 default "triangle" (#560)。 線の種類とは別の軸 */
+  head?: EdgeHead;
   /**
    * FSM transition の guard 条件 (例 "if validated")。
    * stateMachine preset では sub に併合される、 text-dsl v0.5 では guard 単独で渡せる。
@@ -2158,6 +2198,30 @@ export type CdlPhase = {
    * 書かない phase では従来どおり全長で描く (DOM に dash 属性も付かない)。
    */
   draw?: string[];
+  /**
+   * `draw` の対象を描き終えるまでに、 phase の何割を使うか (cdl#570)。
+   *
+   * 0 より大きく 1 以下の割合で書く。 `0.4` なら phase の進みが 0.4 に達した時点で
+   * 描き終わり、 残りの 0.6 は描き終わった図のまま値だけが動く。 既定 (書かない) は 1 で、
+   * 従来どおり phase の終わりに描き終わる。
+   *
+   * **描く速さと phase の長さを切り離すための欄**。 進みは phase の進みそのものなので、
+   * これが無いと「線はゆっくり引きたいが値の移りは短くしたい」 が書けず、 描く速さのために
+   * phase の長さを動かすことになる。 phase の長さを動かすと同じ phase の `tweens` まで
+   * 遅くなり、 値が移るだけの phase を長くする形の回避が利用側で要る。
+   *
+   * **割合で持ち、 秒数では持たない**。 割合なら phase に収まるので、 再生速度の切替
+   * (0.5x / 2x) がそのまま効き、 phase をはみ出した時の扱いを決めずに済む。 秒数だと
+   * 切替との掛かり方とはみ出しの扱いを新たに決めることになる。
+   *
+   * 掛かる相手は `draw` に載せた node だけ。 同じ phase の他の node と edge、 および
+   * `tweens` は元の進みのまま動く。
+   *
+   * 範囲外 (0 以下 / 1 超 / NaN / Infinity) は **1 として扱う**。 描く動きは見え方であって
+   * 図の意味ではないため、 書き間違いで図が出なくなる方が損が大きい。 書き間違いは
+   * `validate` が warning で知らせる。
+   */
+  drawRatio?: number;
   /** 数値 state の線形補間 (write phase で 100→90 等) */
   tweens: Array<{ stateId: string; from: number; to: number }>;
   /** 任意型 state の即時切替 (この phase に到達したら値を上書き、 lerp なし) */

package/src/validate.ts

@@ -168,11 +168,6 @@ export function validate(diag: CdlDiagram): void {
         `[cdl] unknown-ref: edge "${e.id}" の to "${e.to}" が node に存在しません${suggest(e.to, nodeIds, "node")}\n  → 修正例: .node("${e.to}", { lane: "...", stack: 0, kind: "...", title: "..." }) を edge 宣言前に追加`,
       );
     }
-    if (e.from === e.to) {
-      errors.push(
-        `[cdl] self-loop: edge "${e.id}" の from と to が同じ node "${e.from}" です (self-loop は現状未対応)\n  → 別 node を作って 2 段に分けるか、 後続 PR の self-loop support を待ってください`,
-      );
-    }
   }
 
   // ───────────────────────────────────────────────────────────
@@ -200,6 +195,19 @@ export function validate(diag: CdlDiagram): void {
         );
       }
     }
+    // 描く速さの割合 (cdl#570)。 範囲外は描画側が 1 に落とすので図は出るが、 書いた指定は
+    // 何もしない。 黙って捨てると「書いたのに速さが変わらない」 が手掛かりなしで起きる
+    if (p.drawRatio !== undefined) {
+      if (!Number.isFinite(p.drawRatio) || p.drawRatio <= 0 || p.drawRatio > 1) {
+        warnings.push(
+          `phase "${p.id}" の drawRatio ${p.drawRatio} は範囲外 (0 より大きく 1 以下)。 1 として扱う`,
+        );
+      } else if ((p.draw ?? []).length === 0) {
+        warnings.push(
+          `phase "${p.id}" は drawRatio を持つが draw が空。 描く対象が無いので何も変わらない`,
+        );
+      }
+    }
     for (const t of p.tweens) {
       if (!stateIds.has(t.stateId)) {
         errors.push(`[cdl] unknown-ref: phase "${p.id}" tween 対象 state "${t.stateId}" 未定義`);

package/src/visual-validate.ts

@@ -77,7 +77,7 @@
  * test が無いと、 次に種別を足した時に同じ状態へ戻る。
  * ───────────────────────────────────────────────────────────
  */
-import type { CdlDiagram, LaidDiagram, LaidNode, NodeKind } from "./types";
+import { EDGE_HEADS, type CdlDiagram, type LaidDiagram, type LaidNode, type NodeKind } from "./types";
 import { CLEARANCE_LANE_LABEL, DIST_LABEL_PATH_MAX } from "./layout/clearance-constants";
 import { layout } from "./layout";
 import {
@@ -134,7 +134,9 @@ import {
   computeLabelBBoxWorld,
   hasRenderedLabel,
   isRenderedNode,
+  genericTitleBaselineY,
   rendersRows,
+  TITLE_ROW_MIN_GAP,
   rendersTitleText,
   fitsOwnTitleWidth,
   rowBaselineY,
@@ -238,6 +240,11 @@ export const GRID_ALIGNED_KINDS: ReadonlySet<NodeKind> = new Set([
   "chart-pie",
   "chart-line",
   "chart-bar",
+  "chart-gauge",
+  "chart-radial",
+  "chart-stat",
+  "chart-waffle",
+  "chart-stacked-bar",
   "funnel-stages",
   "quadrant-matrix",
 ]);
@@ -374,6 +381,7 @@ export type VisualAxis =
   | "column-gap-uniform"
   // Axis 68 (#387) = 行を描かない種別に rows が書かれている (書いた内容が画面に出ない)。
   | "rows-not-rendered"
+  | "title-row-overlap"
   // #393 = 検査に渡された図の形自体が壊れている (検査できなかったことを結果として出す)。
   | "malformed-input"
   // #393 = 検査が例外で中断したが、 原因が入力の破綻か検査側の欠陥か **決められない**。
@@ -498,6 +506,7 @@ function emptyCounts(): Record<VisualAxis, number> {
     "row-gap-uniform": 0,
     "column-gap-uniform": 0,
     "rows-not-rendered": 0,
+    "title-row-overlap": 0,
     "malformed-input": 0,
     "validation-interrupted": 0,
   };
@@ -2736,6 +2745,36 @@ function runAxes(
     );
   }
 
+  // ───────────────────────────────────────────────────────────
+  // Axis 69: title-row-overlap (題の字と 1 行目の字が重なる)
+  //
+  // 判定 = 題の baseline から下へ伸びる字形と、 1 行目の baseline から上へ伸びる字形が
+  // 触れるか。 位置は `spec.ts` の 2 関数 (`genericTitleBaselineY` / `rowBaselineY`) から
+  // 取るので、 描画側を変えれば本軸も一緒に動く。
+  //
+  // 題と行の縦位置は形ごとに別々の式で決まっていた時期があり、 円柱と中央寄せの 3 種で
+  // 字が重なっていた (#558)。 軸 4 (`row-format`) と軸 16 (`row-vertical-spacing`) は
+  // 行どうしと枠との関係しか見ないため、 題との関係は誰も見ていなかった。
+  //
+  // `storage` は専用の表組みで題と列の間に区切り線を引いており、 位置の出所が別なので対象外。
+  // ───────────────────────────────────────────────────────────
+  for (const n of diag.nodes) {
+    if (!n.rows || n.rows.length === 0) continue;
+    if (!rendersRows(n.kind)) continue;
+    if (n.kind === "storage") continue;
+    // 高さを取れない node は測らない。 0 に潰すと中央寄せの題が上端に来て誤って重なる判定になる
+    if (typeof n.h !== "number") continue;
+    const 題 = genericTitleBaselineY(n.kind, n.h, true);
+    const 行 = rowBaselineY(n.kind, 0);
+    if (行 === null) continue;
+    const 間 = 行 - 題;
+    if (間 >= TITLE_ROW_MIN_GAP) continue;
+    push(
+      "title-row-overlap",
+      `node "${n.id}" (kind=${n.kind ?? "未指定"}) の題 baseline y=${題.toFixed(0)} と 1 行目 baseline y=${行.toFixed(0)} の間が ${間.toFixed(0)} world で、 見込む字形の高さ ${TITLE_ROW_MIN_GAP.toFixed(0)} に届かない (字が重なる)`,
+    );
+  }
+
   // ───────────────────────────────────────────────────────────
   // Axis 17: group-boundary-clearance (topology group の boundary padding + 外部 clearance)
   //
@@ -3307,6 +3346,14 @@ function runAxes(
         `edge "${e.id}" tone "${e.tone}" が TONE_COLORS 定義に存在しない、 marker "cdl-arrow-${e.tone}" dead ref`,
       );
     }
+    // 端の形も同じ理由で dead ref になる (#560)。 marker は EDGE_HEADS の分しか定義しないので、
+    // 定義外の値が来ると "cdl-arrow-<tone>-<未定義>" を引いて矢頭が消える。
+    if (e.head !== undefined && !EDGE_HEADS.includes(e.head)) {
+      push(
+        "marker-gradient-def-integrity",
+        `edge "${e.id}" head "${e.head}" が EDGE_HEADS 定義に存在しない、 marker "cdl-arrow-${e.tone}-${e.head}" dead ref`,
+      );
+    }
   }
 
   // ───────────────────────────────────────────────────────────