@cardenelabs/cdl 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.37.0",
+  "version": "0.38.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/anim/core/timeline.ts

@@ -60,6 +60,8 @@ export class Timeline {
   private rafHandle: number | null = null;
   private phaseIndex = 0;
   private phaseProgress = 0;
+  /** 曲線を通す前の進み (cdl#711)。 経過時間そのものの割合で、 描く動きが読む */
+  private phaseLinearProgress = 0;
   private phaseStartedAt = 0;
   private status: TimelineStatus = "idle";
   /**
@@ -75,7 +77,7 @@ export class Timeline {
    */
   private readonly initialState: {
     phaseIndex: number;
-    phaseProgress: number;
+    phaseLinearProgress: number;
     status: TimelineStatus;
   };
 
@@ -94,12 +96,12 @@ export class Timeline {
     const initial = options.initialPhaseIndex;
     if (initial != null && initial > 0 && initial < phases.length) {
       this.phaseIndex = initial;
-      this.phaseProgress = 1;
+      this.setProgress(1);
       this.status = initial === phases.length - 1 ? "settled" : "paused";
     }
     this.initialState = {
       phaseIndex: this.phaseIndex,
-      phaseProgress: this.phaseProgress,
+      phaseLinearProgress: this.phaseLinearProgress,
       status: this.status,
     };
   }
@@ -133,6 +135,7 @@ export class Timeline {
       cached.status === this.status &&
       cached.phaseIndex === this.phaseIndex &&
       cached.phaseProgress === this.phaseProgress &&
+      cached.phaseLinearProgress === this.phaseLinearProgress &&
       cached.totalPhases === this.phases.length
     ) {
       return cached;
@@ -141,6 +144,7 @@ export class Timeline {
       status: this.status,
       phaseIndex: this.phaseIndex,
       phaseProgress: this.phaseProgress,
+      phaseLinearProgress: this.phaseLinearProgress,
       totalPhases: this.phases.length,
     };
     this.cachedSnapshot = next;
@@ -168,7 +172,7 @@ export class Timeline {
     const clamped = Math.max(0, Math.min(this.phases.length - 1, index));
     this.cancelRaf();
     this.phaseIndex = clamped;
-    this.phaseProgress = 1;
+    this.setProgress(1);
     this.status = clamped === this.phases.length - 1 ? "settled" : "paused";
     this.emit();
   }
@@ -212,7 +216,7 @@ export class Timeline {
     if (this.phaseIndex <= 0) return;
     this.cancelRaf();
     this.phaseIndex -= 1;
-    this.phaseProgress = 1;
+    this.setProgress(1);
     this.status = "paused";
     this.emit();
   }
@@ -220,7 +224,7 @@ export class Timeline {
   reset(): void {
     this.cancelRaf();
     this.phaseIndex = 0;
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.status = "idle";
     this.emit();
   }
@@ -242,7 +246,7 @@ export class Timeline {
     this.subscribers.clear();
     this.status = this.initialState.status;
     this.phaseIndex = this.initialState.phaseIndex;
-    this.phaseProgress = this.initialState.phaseProgress;
+    this.setProgress(this.initialState.phaseLinearProgress);
   }
 
   // ─── internals ───────────────────────────────────────────────
@@ -284,7 +288,7 @@ export class Timeline {
   }
 
   private beginPhaseTransition(): void {
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.phaseStartedAt = performance.now();
     this.cancelRaf();
     const step = (now: number) => {
@@ -292,13 +296,13 @@ export class Timeline {
         this.autoAdvanceMsOverride ?? this.getPhase().durationMs ?? 600;
       const elapsed = now - this.phaseStartedAt;
       const linearT = clamp01(elapsed / duration);
-      this.phaseProgress = this.easing(linearT);
+      this.setProgress(linearT);
       this.emit();
       if (linearT < 1) {
         this.rafHandle = requestAnimationFrame(step);
         return;
       }
-      this.phaseProgress = 1;
+      this.setProgress(1);
       this.emit();
       if (this.status === "playing") {
         // 自動進行中は次 Phase へ
@@ -315,6 +319,20 @@ export class Timeline {
     this.rafHandle = requestAnimationFrame(step);
   }
 
+  /**
+   * 段の進みを 2 つ同時に置く (cdl#711)。
+   *
+   * **代入する場所を 1 つに閉じる**。 曲げた進みと曲げる前の進みを別々に書くと、
+   * どちらかを更新し忘れた経路が「前の段の値のまま」 で残る。
+   *
+   * 両端 (0 と 1) は曲線を通さず、 そのまま置く。 曲線は差し替えられる欄なので、
+   * `easing(1)` が 1 を返す保証がない。 段の始まりと終わりの値は曲線に委ねない。
+   */
+  private setProgress(linear: number): void {
+    this.phaseLinearProgress = linear;
+    this.phaseProgress = linear <= 0 ? 0 : linear >= 1 ? 1 : this.easing(linear);
+  }
+
   private cancelRaf(): void {
     if (this.rafHandle != null) {
       cancelAnimationFrame(this.rafHandle);

package/src/anim/core/types.ts

@@ -37,6 +37,18 @@ export type TimelineState = {
   phaseIndex: number;
   /** 現在 Phase 内の進行度 (0..1)、 視覚要素の補間に使う */
   phaseProgress: number;
+  /**
+   * 曲線を通す前の進行度 (0..1、 cdl#711)。 経過時間そのものの割合。
+   *
+   * `phaseProgress` は既定で `easeOutQuint` を通るため前半に動きが寄る。
+   * **値が落ち着く動きには合うが、 線を引く動きには合わない** =
+   * `1.2s` の段で半分に達するのが 158 ms になり、 折れ線の 5 点のうち 4 点が
+   * 292 ms の間に出てしまう (実測)。
+   *
+   * 描く動き (`draw` の node と伸ばす edge) はこちらを読む。
+   * 両端 (0 と 1) は 2 つとも同じ値になる。
+   */
+  phaseLinearProgress: number;
   /** 全 Phase 数 */
   totalPhases: number;
 };

package/src/render/stage.tsx

@@ -28,6 +28,7 @@ export function CdlStage({
   laid,
   currentPhase,
   progress,
+  drawProgress,
   stateValues,
   debug,
   compact = false,
@@ -36,6 +37,13 @@ export function CdlStage({
   laid: LaidDiagram;
   currentPhase: CdlPhase | undefined;
   progress: number;
+  /**
+   * 描く動きが読む進み (cdl#711)。 曲線を通す前の値で、 経過時間そのものの割合。
+   *
+   * 書かない呼出は `progress` と同じ値になる = 曲線を通した進みで描く従来の形。
+   * 検査から直接呼ぶ経路が既に多数あり、 そこでは 2 つを分ける意味がない。
+   */
+  drawProgress?: number;
   stateValues: Record<string, string>;
   debug: boolean;
   compact?: boolean;
@@ -112,9 +120,15 @@ export function CdlStage({
     }
     return scales;
   }, [laid]);
-  // 描く対象から見た進み (cdl#570)。 `drawRatio` を書かない phase では `progress` と同値で、
+  /**
+   * 描く動きの素の進み (cdl#711)。 渡されなければ従来どおり曲線を通した進みを使う。
+   *
+   * **`??` で受ける** = 0 は正しい進み (段の始まり) なので、 偽としては落とせない。
+   */
+  const 描く素の進み = drawProgress ?? progress;
+  // 描く対象から見た進み (cdl#570)。 `drawRatio` を書かない phase では `描く素の進み` と同値で、
   // 描く速さを phase の長さから切り離すためだけに使う
-  const 描く進み = 描く進みに直す(progress, currentPhase?.drawRatio);
+  const 描く進み = 描く進みに直す(描く素の進み, currentPhase?.drawRatio);
   // 縦線の終点は全 lane で 1 つに揃える (等長保証)。 値の決め方と、 1 lane の異常が図全体から
   // 縦線を消していた形の対処は `uniformLifelineEndY` の説明。
   //
@@ -345,7 +359,7 @@ export function CdlStage({
             edge={edge}
             active={activeSet.has(edge.id)}
             drawing={矢印の出番.伸ばすか(edge.id)}
-            progress={progress}
+            progress={矢印の出番.伸ばすか(edge.id) ? 描く進み : progress}
             stateValues={stateValues}
           />
         ))}

package/src/render.tsx

@@ -133,6 +133,13 @@ export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hi
     : state.phaseIndex;
   const currentPhase = laid.phases[Math.max(0, phaseIdx)] ?? laid.phases[0];
   const progress = reduced ? 1 : state.phaseProgress;
+  /**
+   * 描く動きが読む進み (cdl#711)。 曲線を通さない = 経過時間そのものの割合。
+   *
+   * 線を引く動きに `easeOutQuint` を当てると前半に寄り、 折れ線の 5 点のうち 4 点が
+   * 292 ms の間に出る。 ペンの速さは一定であるほど「1 つずつ現れる」 が読める。
+   */
+  const drawProgress = reduced ? 1 : state.phaseLinearProgress;
 
   // state 値を計算 (現在 phase + これまでの phase の最終 tween 値を集約)
   const baseStateValues = computeStateValues(laid, phaseIdx, progress);
@@ -184,7 +191,7 @@ export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hi
       {/* interactive panel = input widget / formula readout / scroll readout (SVG の上に配置)、
           diagram に interactive primitive がなければ null (SSR / render 影響なし) */}
       {isInteractive && interactive.panel}
-      <CdlStage laid={laid} currentPhase={currentPhase} progress={progress} stateValues={stateValues} debug={debug} compact={hideHeader} svgRef={isInteractive ? interactive.svgRef : undefined} />
+      <CdlStage laid={laid} currentPhase={currentPhase} progress={progress} drawProgress={drawProgress} stateValues={stateValues} debug={debug} compact={hideHeader} svgRef={isInteractive ? interactive.svgRef : undefined} />
       {/* hideHeader + multi-phase 時、 phase indicator が消えると動きが読めないため
           mini indicator (dot 列 + 現在 phase title + badge) を bottom に追加 */}
       {hideHeader && !hideMiniPhaseIndicator && currentPhase && laid.phases.length > 1 && (