@cardenelabs/cdl 0.5.0

package/src/render/stage.tsx

@@ -0,0 +1,377 @@
+import { useMemo, type JSX } from "react";
+import type { CdlPhase, LaidDiagram } from "../types";
+import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeLabelView } from "./edges";
+import { CdlNodeView } from "./nodes";
+import { TONE, TONE_HEX } from "./tone";
+import { buildDiagramAltText } from "../layout/spec";
+import { footerShapeDropsOf, lifelineFooterNodes } from "../layout/footer-shape";
+
+export function CdlStage({
+  laid,
+  currentPhase,
+  progress,
+  stateValues,
+  debug,
+  compact = false,
+  svgRef,
+}: {
+  laid: LaidDiagram;
+  currentPhase: CdlPhase | undefined;
+  progress: number;
+  stateValues: Record<string, string>;
+  debug: boolean;
+  compact?: boolean;
+  /** interactive integration (CAR #246) 用 SVG ref、 caller が event handler attach に使う */
+  svgRef?: React.RefObject<SVGSVGElement | null>;
+}): JSX.Element {
+  const activeSet = new Set(currentPhase?.activate ?? []);
+  // 全 lifeline lane 横断で uniform y2 (footer.top の min) を事前計算して等長保証。
+  // 単一 node lane も同じ y2 を使う (mixed 構成での分岐回避、 Round 2 major fix)。
+  // footer.top を集めた配列を作り、 min を uniformFooterTop とする。 配列空 (全 lane が
+  // 1 node 以下 or 0 node) の場合、 最初の lifeline lane の (lane.y + lane.height) を fallback。
+  const lifelineLanes = laid.lanes.filter((l) => l.lifeline);
+  // 下端の名札は 2 つの用途に使う。 縦線の終点 (uniformFooterTop) と、 絵を下げる量の表。
+  //
+  // `shape-` の一部は中身を箱の下端から固定の距離で組み立てるため、 箱が低いと絵が上へ出る
+  // (`SHAPE_DRAW_UP_EXTENT` の説明)。 縦線は箱の上端で止まるので、 出た分だけ縦線が絵の中を通る。
+  //
+  // 名札を集める処理は 1 度だけ行い、 配置が変わらない限り作り直さない。 この component は
+  // 動きの 1 コマごとに描き直されるため、 毎コマ集め直すと lane 数 × node 数を毎コマ払う
+  const { footerTops, footerDropById } = useMemo(() => {
+    const footers = lifelineFooterNodes(laid.lanes, laid.nodes);
+    return {
+      footerTops: footers.map((f) => f.cy - f.h / 2),
+      footerDropById: footerShapeDropsOf(footers),
+    };
+  }, [laid]);
+  const uniformFooterTop = footerTops.length > 0
+    ? Math.min(...footerTops)
+    : (lifelineLanes[0] ? lifelineLanes[0].y + lifelineLanes[0].height : 0);
+  const diagramScale = laid.diagramScale ?? 1;
+  return (
+    <div className={compact ? "px-3 py-3" : "px-6 py-6"} style={compact ? undefined : { minHeight: 460 }}>
+      <svg
+        ref={svgRef}
+        viewBox={`${laid.viewBox.x} ${laid.viewBox.y} ${laid.viewBox.w} ${laid.viewBox.h}`}
+        preserveAspectRatio="xMidYMid meet"
+        className="block h-auto w-full"
+        // 図全体の倍率は **表示幅** で表す。 高さは viewBox の縦横比から決まる
+        // (SVG の intrinsic sizing、 CSS を一切与えなくても同じ)。
+        // field の仕様は `CdlViewport.scale` の JSDoc、 ここには選ばなかった実装とその理由を
+        // 書く。
+        //
+        // cdl は Tailwind を依存にも同梱にも持たないので、 ここの class 名が実際に効くかは
+        // consumer の CSS 設定次第。 幅に関しては効かなくても `<svg>` の既定が 100% なので
+        // 結果は変わらないが、 それ以外の class に同じ保証は無い。 JSDoc 側では CSS の
+        // 結果を断定しない。
+        //
+        // 却下 1 = viewBox と中身の両方に同じ k を掛ける。 恒等変換で画面上は何も変わらない。
+        // viewBox を k 倍すると表示倍率が 1/k になり、 中身の scale(k) と厳密に打ち消し合う。
+        //
+        //   device_x = offsetX + (k·p − k·x0) × W/(k·w) = offsetX + (p − x0) × W/w
+        //
+        // k が約分で消える (実測 = k=1/3/0.5 で device 座標が完全一致)。
+        //
+        // 却下 2 = viewBox の実寸に k を掛けた px を width に置く。 倍率 1 が相対幅
+        // (class `w-full` = 親幅基準) なのに倍率 k だけ絶対幅 (viewBox 基準) になり、 基準が
+        // 食い違う。 親幅と viewBox 幅が一致しない限り「k 倍」 にならず、 親が viewBox より
+        // 広ければ `scale: 1.2` が `scale: 1` より小さくなる (親 3000px / viewBox 1086px で
+        // 0.43 倍 = 拡大指定で縮む)。
+        //
+        // 採用 = 倍率 1 と同じ親幅基準に揃えて `width: {k × 100}%` を置く。
+        style={diagramScale === 1
+          ? { maxWidth: "100%" }
+          : { width: `${diagramScale * 100}%`, maxWidth: "none" }}
+        role="img"
+        aria-label={buildDiagramAltText(laid.topic, currentPhase)}
+        // 図を描く `<svg>` はこれ 1 つ、 という目印。 interactive panel は widget ごとに
+        // `<svg>` を持ち (readout ring / gauge / sparkline 等)、 DOM 順では panel が先に来る。
+        // 「最初の `<svg>`」 で拾うと panel の widget を掴む (cdl#336)。
+        data-cdl-stage=""
+        // 倍率は SVG 要素そのものに載せる。 中身を包む `<g>` を作らないので、
+        // 倍率 1 / 未指定の DOM は従来と 1 byte も変わらない。
+        data-cdl-scale={diagramScale === 1 ? undefined : diagramScale}
+      >
+        <defs>
+          {/* CAR-643 = cdl は geometry only。 shadow / border effect の filter は cdl SVG 内に
+              持たず、 consumer app (dragon 等) が独自 filter を CSS 経由で data-cdl-role selector
+              に適用する。 marker (cdl-arrow-*) は edge routing の SSOT なので cdl 内に維持。 */}
+          {/* 光っている edge 用 (14) と光っていない edge 用 (10) を tone ごとに用意する。
+              光っていない 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>
+            )),
+          )}
+          {/* tone が TONE 定義に無い edge の受け皿。 visual-validate の tone-marker-ref 軸が
+              dead ref を検知するが、 検知するまでの間に矢頭が消えないようにする。 */}
+          <marker
+            id="cdl-arrow-muted"
+            viewBox="0 0 10 10"
+            refX="9"
+            refY="5"
+            markerWidth="10"
+            markerHeight="10"
+            markerUnits="userSpaceOnUse"
+            orient="auto-start-reverse"
+          >
+            <path data-cdl-role="edge-arrowhead" d="M 0 0 L 10 5 L 0 10 z" fill="var(--cdl-line-mute, #a89d8f)" />
+          </marker>
+        </defs>
+        {/* lanes (contain なら boundary 描く + label、 lifeline なら lane 中央 x に縦点線) */}
+        {laid.lanes.map((lane) => (
+          <g
+            key={lane.id}
+            data-cdl-lane={lane.id}
+            data-cdl-lane-x={lane.x}
+            data-cdl-lane-y={lane.y}
+            data-cdl-lane-w={lane.width}
+            data-cdl-lane-h={lane.height}
+          >
+            {/* lane bbox を <g> の boundingBox に anchor するための invisible rect (lane.contain=false でも常に存在) */}
+            <rect
+              x={lane.x}
+              y={lane.y}
+              width={lane.width}
+              height={lane.height}
+              fill="none"
+              stroke="none"
+              pointerEvents="none"
+            />
+            {lane.contain && (
+              <rect
+                data-cdl-role="lane-container"
+                x={lane.x}
+                y={lane.y}
+                width={lane.width}
+                height={lane.height}
+                rx={24}
+                fill="var(--cdl-stage-bg, #fafafa)"
+                stroke="var(--cdl-divider, #d4d4d8)"
+                strokeWidth={1.5}
+                strokeDasharray="8 6"
+                opacity={0.7}
+              />
+            )}
+            {lane.lifeline && (() => {
+              // lifeline は header (topmost node) の bottom edge から uniformFooterTop
+              // (全 lifeline lane 共通、 CdlStage 冒頭で事前計算) までを結ぶ。 単一 node lane も
+              // multi-node lane も同じ y2 を使うことで mixed 構成の等長保証を守る (Round 2 major fix)。
+              const laneNodes = laid.nodes.filter((n) => n.lane === lane.id);
+              if (laneNodes.length === 0) return null;
+              const sortedByCy = laneNodes.slice().sort((a, b) => a.cy - b.cy);
+              const header = sortedByCy[0]!;
+              const y1 = header.cy + header.h / 2;
+              const y2 = uniformFooterTop;
+              if (y2 <= y1) return null;
+              return (
+                <line
+                  data-cdl-role="lane-lifeline"
+                  x1={lane.x + lane.width / 2}
+                  y1={y1}
+                  x2={lane.x + lane.width / 2}
+                  y2={y2}
+                  stroke="var(--cdl-line-mute, #a89d8f)"
+                  strokeWidth={1.5}
+                  strokeDasharray="6 6"
+                  opacity={0.7}
+                />
+              );
+            })()}
+            {lane.label && (
+              <text
+                data-cdl-role="lane-label"
+                x={lane.x + 24}
+                y={lane.y + 26}
+                fontSize={20}
+                fontWeight={700}
+                letterSpacing={2}
+                fill="var(--cdl-text-mute, #8a8678)"
+              >
+                {lane.label}
+              </text>
+            )}
+          </g>
+        ))}
+
+        {/* edges (1st pass) */}
+        {laid.edges.map((edge) => (
+          <CdlEdgeView key={edge.id} edge={edge} active={activeSet.has(edge.id)} progress={progress} stateValues={stateValues} />
+        ))}
+
+        {/* nodes (2nd pass) */}
+        {laid.nodes.map((node) => {
+          const view = (
+            <CdlNodeView
+              node={node}
+              active={activeSet.has(node.id)}
+              progress={progress}
+              stateValues={stateValues}
+              currentPhaseId={currentPhase?.id}
+            />
+          );
+          const dy = footerDropById.get(node.id);
+          // 下端の名札で絵が上へ出る種別だけ、 絵の上端が箱の上端に来るまで下げる。
+          // node の座標そのものは動かさない = 矢印の接続先や当たり判定は箱のままにする
+          return dy === undefined ? (
+            <g key={node.id}>{view}</g>
+          ) : (
+            <g key={node.id} transform={`translate(0, ${dy})`}>{view}</g>
+          );
+        })}
+
+        {/* 経由 node 貫通する dotted-flow edge の進行点 glow (3rd pass) */}
+        {laid.edges
+          .filter((edge) => Boolean(edge.dThrough))
+          .map((edge) => (
+            <CdlEdgeGlowView key={`glow-${edge.id}`} edge={edge} active={activeSet.has(edge.id)} />
+          ))}
+
+        {/* edge labels (3rd pass) ... 全 edge の label を最前面に描画 */}
+        {laid.edges.map((edge) => (
+          <CdlEdgeLabelView
+            key={`label-${edge.id}`}
+            edge={edge}
+            active={activeSet.has(edge.id)}
+          />
+        ))}
+
+        {/* debug overlay = engine が把握している bbox + collision を半透明で重ね描き */}
+        {debug && (
+          <g pointerEvents="none">
+            {laid.bboxes.map((bbox, idx) => {
+              const color =
+                bbox.kind === "node"
+                  ? "#3b82f6"
+                  : bbox.kind === "lane-label"
+                  ? "#a855f7"
+                  : bbox.kind === "edge-label"
+                  ? "#10b981"
+                  : "#f59e0b";
+              return (
+                <g key={`${bbox.kind}-${bbox.id}-${idx}`}>
+                  <rect
+                    x={bbox.x}
+                    y={bbox.y}
+                    width={bbox.w}
+                    height={bbox.h}
+                    fill={color}
+                    fillOpacity={0.08}
+                    stroke={color}
+                    strokeWidth={1}
+                    strokeDasharray="4 3"
+                  />
+                  <text
+                    x={bbox.x + 4}
+                    y={bbox.y + 14}
+                    fontSize={10}
+                    fill={color}
+                    fontFamily="monospace"
+                  >
+                    {bbox.kind}#{bbox.id}
+                  </text>
+                </g>
+              );
+            })}
+            {laid.collisions.map((c, idx) => {
+              const xMin = Math.max(c.a.x, c.b.x);
+              const yMin = Math.max(c.a.y, c.b.y);
+              const xMax = Math.min(c.a.x + c.a.w, c.b.x + c.b.w);
+              const yMax = Math.min(c.a.y + c.a.h, c.b.y + c.b.h);
+              return (
+                <rect
+                  key={`collision-${idx}`}
+                  x={xMin}
+                  y={yMin}
+                  width={xMax - xMin}
+                  height={yMax - yMin}
+                  fill="#ef4444"
+                  fillOpacity={0.35}
+                  stroke="#ef4444"
+                  strokeWidth={2}
+                />
+              );
+            })}
+            {laid.nearCollisions.map((nc, idx) => {
+              const xMin = Math.min(nc.a.x, nc.b.x);
+              const yMin = Math.min(nc.a.y, nc.b.y);
+              const xMax = Math.max(nc.a.x + nc.a.w, nc.b.x + nc.b.w);
+              const yMax = Math.max(nc.a.y + nc.a.h, nc.b.y + nc.b.h);
+              return (
+                <g key={`near-${idx}`}>
+                  <rect
+                    x={xMin - 2}
+                    y={yMin - 2}
+                    width={xMax - xMin + 4}
+                    height={yMax - yMin + 4}
+                    fill="none"
+                    stroke="#eab308"
+                    strokeWidth={2}
+                    strokeDasharray="6 4"
+                    opacity={0.75}
+                  />
+                  <text
+                    x={xMin}
+                    y={yMin - 6}
+                    fontSize={10}
+                    fill="#a16207"
+                    fontFamily="monospace"
+                  >
+                    near {Math.round(nc.gap)}/{nc.required}px
+                  </text>
+                </g>
+              );
+            })}
+          </g>
+        )}
+      </svg>
+      {debug && (
+        <div className="mt-2 px-6 text-xs text-[color:var(--cdl-text-dim,#5a6270)]">
+          <div>
+            <strong>cdl debug</strong> ... bboxes: {laid.bboxes.length}、 collisions:{" "}
+            <span style={{ color: laid.collisions.length > 0 ? TONE_HEX.error : TONE_HEX.success }}>
+              {laid.collisions.length}
+            </span>
+            、 near-collisions:{" "}
+            <span style={{ color: laid.nearCollisions.length > 0 ? TONE_HEX.warning : TONE_HEX.success }}>
+              {laid.nearCollisions.length}
+            </span>
+          </div>
+          {laid.collisions.length > 0 && (
+            <ul className="mt-1 list-disc pl-4">
+              {laid.collisions.map((c, idx) => (
+                <li key={`c-${idx}`} style={{ color: "#ef4444" }}>
+                  collision ... {c.a.kind}#{c.a.id} ∩ {c.b.kind}#{c.b.id} ={" "}
+                  {Math.round(c.overlap_area)}px²
+                </li>
+              ))}
+            </ul>
+          )}
+          {laid.nearCollisions.length > 0 && (
+            <ul className="mt-1 list-disc pl-4">
+              {laid.nearCollisions.map((nc, idx) => (
+                <li key={`nc-${idx}`} style={{ color: "#a16207" }}>
+                  near ... {nc.a.kind}#{nc.a.id} ↔ {nc.b.kind}#{nc.b.id} ={" "}
+                  {Math.round(nc.gap)}px (need {nc.required}px)
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/render/tone.ts

@@ -0,0 +1,64 @@
+import type { Tone } from "../types";
+
+/**
+ * Tone (= edge / node の意味付き色) の RGB マッピング SSOT。
+ * cdl の全 render 経路で同じ色を使う。
+ *
+ * v0.9+: CSS variable 経由化。 downstream (dragon / chainome) 側で
+ * --cdl-tone-{name} を dark theme 用に override 可能。
+ * fallback として従来の hex 値を保持、 downstream 未対応時は従来動作。
+ */
+export const TONE: Record<Tone, string> = {
+  accent: "var(--cdl-tone-accent, #2d6a8f)",
+  teal: "var(--cdl-tone-teal, #2f8770)",
+  success: "var(--cdl-tone-success, #4ea36a)",
+  error: "var(--cdl-tone-error, #c15a4a)",
+  warning: "var(--cdl-tone-warning, #a67a2e)",
+  info: "var(--cdl-tone-info, #5a8ec1)",
+};
+
+/**
+ * TONE の hex 値のみ SSOT (contrast / opacity 計算等で raw hex が必要な場合用)。
+ * runtime で CSS variable を評価できない環境 (SSR / test) では本 map を参照。
+ */
+export const TONE_HEX: Record<Tone, string> = {
+  accent: "#2d6a8f",
+  teal: "#2f8770",
+  success: "#4ea36a",
+  error: "#c15a4a",
+  warning: "#a67a2e",
+  info: "#5a8ec1",
+};
+
+/** TONE に無い tone が来た時に使う色。 */
+export const TONE_FALLBACK = "#2d6a8f";
+
+/**
+ * tone が TONE に定義されているかを返す。
+ *
+ * `TONE[tone]` の真偽で見てはいけない。 `TONE` は object literal なので `toString` /
+ * `constructor` 等の prototype 由来の key が truthy になり、 関数が色として扱われる
+ * (実測 = tone "toString" で stroke が落ち、 存在しない marker を指した)。
+ */
+export function hasTone(tone: string): boolean {
+  return Object.hasOwn(TONE, tone);
+}
+
+/** tone の色。 TONE に無い tone は既定色に落とす。 */
+export function toneColor(tone: string): string {
+  return hasTone(tone) ? TONE[tone as Tone] : TONE_FALLBACK;
+}
+
+/**
+ * tone の色を透過付きで塗るための SVG 属性を返す。
+ *
+ * 背景の淡い塗りに使う。 色を直書きすると、 元の色を直した時に背景だけ古い色で残る
+ * (実際に mind-map 系と quadrant で起きていた)。
+ *
+ * `rgba()` の 1 文字列ではなく `fill` と `fillOpacity` に分けて返す。 `rgba()` は数値の hex から
+ * 組み立てるしかなく、 consumer が `--cdl-tone-*` を上書きしても効かない (下流の dark 化で
+ * 淡い背景だけ元の色のまま残る)。 分ければ色は CSS 変数のまま渡せる。
+ */
+export function toneFill(tone: Tone, alpha: number): { fill: string; fillOpacity: number } {
+  return { fill: TONE[tone], fillOpacity: alpha };
+}

package/src/render/utils.ts

@@ -0,0 +1,238 @@
+import { lerp } from "../anim";
+import type { LaidDiagram } from "../types";
+
+/**
+ * 全 state の現時点 value を計算 (現在 phase + これまでの phase の最終 tween 値を集約)。
+ * - set = 即時切替 (phase 到達で value 上書き、 lerp なし)
+ * - tween = 数値補間 (現 phase 中は progress で lerp、 過去 phase は to 固定)
+ */
+export function computeStateValues(
+  laid: LaidDiagram,
+  phaseIdx: number,
+  progress: number,
+): Record<string, string> {
+  const values: Record<string, number | string> = {};
+  for (const s of laid.states) values[s.id] = s.initial;
+
+  for (let i = 0; i < laid.phases.length; i++) {
+    const phase = laid.phases[i];
+    if (!phase) continue;
+    if (i <= phaseIdx) {
+      for (const s of phase.sets) {
+        values[s.stateId] = s.value;
+      }
+    }
+    for (const t of phase.tweens) {
+      if (i < phaseIdx) {
+        values[t.stateId] = t.to;
+      } else if (i === phaseIdx) {
+        values[t.stateId] = Math.round(lerp(t.from, t.to, progress));
+      }
+    }
+  }
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(values)) out[k] = String(v);
+  return out;
+}
+
+/**
+ * template literal `{stateId}` を values map で置換 (未解決は `{id}` のまま)。
+ * array signal 拡張 (SSOT): 値が JSON array (例 `"[1,2,3]"`) の signal に対しては、
+ *   `{sig[0]}` = 要素 0 の値、 `{sig.length}` = 要素数、
+ *   `{sig.sum}` / `{sig.max}` / `{sig.min}` / `{sig.avg}` = 数値集約 (非数値 element は 0 扱い)。
+ * array 記法対象外 signal は従来通り `{sig}` で単純置換。
+ */
+export function interpolate(template: string, values: Record<string, string>): string {
+  return template.replace(/\{(\w+)(\.length|\.sum|\.max|\.min|\.avg|\[\d+\])?\}/g, (_, id: string, accessor?: string) => {
+    const raw = values[id];
+    if (raw === undefined) return `{${id}${accessor ?? ""}}`;
+    if (!accessor) return raw;
+    const arr = parseArraySignal(raw);
+    if (!arr) return `{${id}${accessor}}`;
+    if (accessor === ".length") return String(arr.length);
+    const nums = arr.map((v) => (Number.isFinite(Number(v)) ? Number(v) : 0));
+    if (accessor === ".sum") return String(nums.reduce((s, v) => s + v, 0));
+    if (accessor === ".max") return nums.length ? String(nums.reduce((a, b) => (a > b ? a : b), nums[0]!)) : "0";
+    if (accessor === ".min") return nums.length ? String(nums.reduce((a, b) => (a < b ? a : b), nums[0]!)) : "0";
+    if (accessor === ".avg") {
+      if (!nums.length) return "0";
+      const sum = nums.reduce((s, v) => s + v, 0);
+      return String(Math.round((sum / nums.length) * 100) / 100);
+    }
+    if (accessor.startsWith("[")) {
+      const idx = Number(accessor.slice(1, -1));
+      if (Number.isInteger(idx) && idx >= 0 && idx < arr.length) return String(arr[idx]);
+      return `{${id}${accessor}}`;
+    }
+    return raw;
+  });
+}
+
+function parseArraySignal(raw: string): (string | number)[] | null {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) return parsed as (string | number)[];
+  } catch {
+    // 数値 CSV のみ fallback (`[1,2,3]` 等)、 garbage は不正 array として null 返却
+    // → interpolate に `{sig[0]}` そのまま残し, ArrayBarReadout で silent 0 化を防ぐ (author bug 検知)
+    const inner = trimmed.slice(1, -1).trim();
+    if (!inner) return [];
+    if (/^[\s\d.,+\-eE]+$/.test(inner)) return inner.split(",").map((s) => Number(s.trim()));
+  }
+  return null;
+}
+
+/**
+ * numeric attribute (node.w / h / opacity 等) を template + fallback で解決する SSOT
+ * (visual binding foundation)。
+ *
+ * value が number ならそのまま返す。 string の場合、 全体が `{signal-id}` の pure template なら
+ * signal 値を Number 解釈、 一部だけ template を含む string は interpolate で置換後 Number 解釈。
+ * 解決失敗時は fallback を返す。
+ *
+ * 用途例:
+ *   node.w = 120 → 120 (直接 numeric)
+ *   node.w = "{barW}" → parseFloat(values.barW ?? "120") で signal 追随
+ *   node.opacity = "{fade}" → 0..1 の signal 値で fade animation
+ */
+export function resolveNumericAttr(
+  value: number | string | undefined,
+  values: Record<string, string>,
+  fallback: number,
+): number {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return fallback;
+  const trimmed = value.trim();
+  if (trimmed === "") return fallback;
+  const resolved = interpolate(trimmed, values);
+  const parsed = Number(resolved);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/**
+ * SVG path d 文字列の末尾を shrinkPx だけ手前で切り、 末端で描画される dot を隠す。
+ * dotted-flow style で「path 末端に visible になる小 dot」 を消すために使用。
+ */
+export function shrinkPathEnd(d: string, shrinkPx: number): string {
+  const commandRegex = /([MLCQZmlcqz])([^MLCQZmlcqz]*)/g;
+  const matches: Array<{ cmd: string; args: number[] }> = [];
+  let m: RegExpExecArray | null;
+  while ((m = commandRegex.exec(d)) !== null) {
+    const cmd = m[1]!;
+    const args = (m[2] ?? "").trim().split(/[\s,]+/).filter(Boolean).map(parseFloat);
+    matches.push({ cmd, args });
+  }
+  if (matches.length < 2) return d;
+
+  let prevEnd: { x: number; y: number } = { x: 0, y: 0 };
+  for (let i = 0; i < matches.length - 1; i++) {
+    const { cmd, args } = matches[i]!;
+    if (cmd === "M" || cmd === "L") {
+      prevEnd = { x: args[0]!, y: args[1]! };
+    } else if (cmd === "Q") {
+      prevEnd = { x: args[2]!, y: args[3]! };
+    } else if (cmd === "C") {
+      prevEnd = { x: args[4]!, y: args[5]! };
+    }
+  }
+
+  const last = matches[matches.length - 1]!;
+  let endX: number, endY: number;
+  if (last.cmd === "L" || last.cmd === "M") {
+    endX = last.args[0]!;
+    endY = last.args[1]!;
+  } else if (last.cmd === "Q") {
+    endX = last.args[2]!;
+    endY = last.args[3]!;
+  } else if (last.cmd === "C") {
+    endX = last.args[4]!;
+    endY = last.args[5]!;
+  } else {
+    return d;
+  }
+
+  const dx = endX - prevEnd.x;
+  const dy = endY - prevEnd.y;
+  const len = Math.hypot(dx, dy);
+  if (len < shrinkPx + 1) return d;
+  const ratio = (len - shrinkPx) / len;
+  const newEndX = prevEnd.x + dx * ratio;
+  const newEndY = prevEnd.y + dy * ratio;
+
+  const tokens = d.trim().split(/\s+/);
+  if (tokens.length < 2) return d;
+  tokens[tokens.length - 2] = newEndX.toFixed(1);
+  tokens[tokens.length - 1] = newEndY.toFixed(1);
+  return tokens.join(" ");
+}
+
+/**
+ * SVG path d (M / L のみ対応) を progress (0-1) で切り詰めた新 d を返す。
+ * cdl の routePath は直線 + L-bend (M x y L x y [L x y]) のみを返すため、
+ * 累積セグメント length で progress * total が属するセグメントを特定し、
+ * その上で線形補間して新終点を計算 → `M ... L ... L ...` 形式の部分 path を返す。
+ *
+ * これにより SVG <path d={subD} markerEnd="..."> で marker が path 末端 (= 進行先端) に
+ * SVG renderer が atomic に描画する = 線と矢頭の同期ずれが構造的に発生しない。
+ */
+export function pathSubpath(d: string, progress: number): string {
+  if (progress >= 1) return d;
+  if (progress <= 0) {
+    const first = d.trim().match(/^M\s+([-\d.]+)\s+([-\d.]+)/);
+    if (!first) return d;
+    return `M ${first[1]} ${first[2]}`;
+  }
+
+  const tokens = d.trim().split(/\s+/);
+  const points: Array<{ x: number; y: number }> = [];
+  let i = 0;
+  while (i < tokens.length) {
+    const t = tokens[i]!;
+    if (t === "M" || t === "L") {
+      const x = parseFloat(tokens[i + 1]!);
+      const y = parseFloat(tokens[i + 2]!);
+      if (!Number.isFinite(x) || !Number.isFinite(y)) return d;
+      points.push({ x, y });
+      i += 3;
+    } else {
+      return d;
+    }
+  }
+  if (points.length < 2) return d;
+
+  const segLens: number[] = [];
+  let total = 0;
+  for (let k = 1; k < points.length; k++) {
+    const dx = points[k]!.x - points[k - 1]!.x;
+    const dy = points[k]!.y - points[k - 1]!.y;
+    const len = Math.hypot(dx, dy);
+    segLens.push(len);
+    total += len;
+  }
+  if (total === 0) return d;
+
+  const target = total * progress;
+  let acc = 0;
+  for (let k = 0; k < segLens.length; k++) {
+    const segLen = segLens[k]!;
+    if (acc + segLen >= target) {
+      const remain = target - acc;
+      const ratio = segLen === 0 ? 0 : remain / segLen;
+      const sx = points[k]!.x;
+      const sy = points[k]!.y;
+      const ex = points[k + 1]!.x;
+      const ey = points[k + 1]!.y;
+      const tx = sx + (ex - sx) * ratio;
+      const ty = sy + (ey - sy) * ratio;
+      const head = points
+        .slice(0, k + 1)
+        .map((p, idx) => `${idx === 0 ? "M" : "L"} ${p.x} ${p.y}`)
+        .join(" ");
+      return `${head} L ${tx.toFixed(1)} ${ty.toFixed(1)}`;
+    }
+    acc += segLen;
+  }
+  return d;
+}