@cardenelabs/cdl 0.14.0 → 0.16.0

package/src/presets.ts

@@ -2,7 +2,7 @@ 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, JourneyEmotion, QuadrantKey, BoundNumber } from "./types";
+import type { NodeKind, Tone, EdgeStyle, EdgeHead, JourneyEmotion, QuadrantKey, BoundNumber } from "./types";
 
 /**
  * 状態を読む書き方 (`{名前}`)。
@@ -984,6 +984,32 @@ export function infrastructure(preset: InfrastructurePreset): InfrastructureBuil
 
 export type ClassRelationType = "extends" | "implements" | "uses" | "aggregates" | "composes";
 
+/**
+ * 関係の種類ごとの端の形 (cdl#574)。
+ *
+ * `#560` で足した端の形は「関係の種類を示す」 ためのもので、この preset が第一の使い手。
+ * 表にしないと 5 種とも同じ塗った三角になり、線の種類と語だけで区別することになる。
+ *
+ * | 種類 | 形 | 意味 |
+ * |---|---|---|
+ * | `extends` / `implements` | 三角 | 継ぐ |
+ * | `aggregates` / `composes` | 菱 | 持つ |
+ * | `uses` | 開いた矢 | 使う |
+ *
+ * **`extends` と `implements` が同じ形になるのは意図**。 UML では線の種類 (実線 / 破線) で
+ * 分ける決まりで、端の形は「継ぐ」 を表す 1 種しかない。 `aggregates` と `composes` も同様に
+ * 塗りの有無で分けるので、端の形は同じ菱になる。
+ *
+ * `Record<ClassRelationType, EdgeHead>` なので、種類を足すと形も要る。
+ */
+export const CLASS_RELATION_HEAD: Record<ClassRelationType, EdgeHead> = {
+  extends: "triangle",
+  implements: "triangle",
+  uses: "open",
+  aggregates: "diamond",
+  composes: "diamond",
+};
+
 export type UmlClass = {
   id: string;
   title: string;
@@ -1004,6 +1030,12 @@ export type UmlRelation = {
   /** 多重度 (例 "1..*" / "0..1") */
   cardinality?: string;
   tone?: Tone;
+  /**
+   * 矢印の先の形 (cdl#574)。 書かなければ種類から決まる (`CLASS_RELATION_HEAD`)。
+   *
+   * **書いた形が勝つ**。 表と違う形にしたい関係だけを個別に書ける。
+   */
+  head?: EdgeHead;
 };
 
 export type ClassDiagramPreset = {
@@ -1087,6 +1119,8 @@ export function classDiagram(preset: ClassDiagramPreset): ClassDiagramBuilder {
         ...(sub ? { sub } : {}),
         tone: r.tone ?? tone,
         style: "solid",
+        // 関係の種類から端の形を決める (cdl#574)。 書いた形が勝つ
+        head: r.head ?? CLASS_RELATION_HEAD[r.type],
         // CAR-531 SSOT ... 旧実装は `labelOffsetY: currentIdx % 2 === 0 ? -60 : 60` で
         // 複数 relation label の path 沿い集中を強制分散していた。 CAR-430 で導入した
         // engine 側 fan offset (FAN_STEP 40 world) が同 from / to 群を自動分散する現在、
@@ -1538,13 +1572,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 +1624,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 +1642,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 +1665,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}" 未定義`);