@cardenelabs/cdl 0.5.0

package/src/render.tsx

@@ -0,0 +1,221 @@
+import { useEffect, useMemo } from "react";
+import type { JSX } from "react";
+import { useReducedMotion, useTimeline } from "./anim/react";
+import { compile } from "./compile";
+import { CdlHeader } from "./render/header";
+import { CdlStage } from "./render/stage";
+import {
+  hasInteractivePrimitives,
+  useInteractiveIntegration,
+  type InteractiveHandlerMap,
+} from "./render/interactive-panel";
+import { computeStateValues } from "./render/utils";
+import { visualValidateLaid } from "./visual-validate";
+import type { CdlDiagram, LaidDiagram } from "./types";
+
+export type CdlDiagramViewProps = {
+  diagram: CdlDiagram;
+  /**
+   * 配置まで済ませた図。 渡すとここでは組み立て直さない。
+   *
+   * 呼出側が既に `compile` を呼んでいる場合 (組み立ての結果を検査や図枠の原点に使う等)、
+   * ここで測り直すと同じ図の配置を 2 度計算する。 図の規模に比例して重く、 辺 500 本で
+   * 約 300ms かかる (実測)。
+   *
+   * 渡す時は `diagram` と対にする。 別の図の配置を渡すと、 描く内容と位置がずれる。
+   * 対応が取れているかはここでは確かめない (確かめる費用が、 省く費用を上回る)。
+   */
+  laid?: LaidDiagram;
+  hideHeader?: boolean;
+  /**
+   * `hideHeader` 時に下部へ出る phase の小さな指標 (点列 + 現在 phase の題) を出さない。
+   *
+   * 下流が独自の phase UI を持つ場合に使う。 CSS で消す形にすると、 こちらの class 名や
+   * 要素構造が変わった時に黙って効かなくなる (下流の hack が壊れたことに気付けない)。
+   */
+  hideMiniPhaseIndicator?: boolean;
+  focusPhaseId?: string;
+  /** debug mode = engine の bbox + collision を半透明で重ね描き (開発確認用) */
+  debug?: boolean;
+  /**
+   * dev warn mode = 生成時に visualValidate を走らせ warn / error を console に流す。
+   * default = process.env.NODE_ENV === "development" 相当を caller 側で判定して渡す設計。
+   * true 明示指定で production build でも有効化可 (Playwright 実測時など)。
+   */
+  emitGeometryWarn?: boolean;
+  /**
+   * CdlHeader 内 phase title の heading tag level (2 | 3 | 4)、 default 3。
+   * downstream で h1 直後配置なら 2、 h2 直後なら 3 (default)、 h3 直後なら 4 を渡す。
+   * heading order skip を防ぐ用途、 hideHeader=true 時は無視される。
+   */
+  headingLevel?: 2 | 3 | 4;
+  /**
+   * interactive event handler 関数 map (CAR #246 / render integration)。
+   * diagram.eventBindings が非空の時、 handlerId → (event, signals) => void の map で consumer が
+   * signal 更新 etc を実装する。 未指定の場合 event handler は skip される。
+   */
+  interactiveHandlers?: InteractiveHandlerMap;
+};
+
+export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hideMiniPhaseIndicator = false, focusPhaseId, debug = false, emitGeometryWarn = false, headingLevel = 3, interactiveHandlers }: CdlDiagramViewProps): JSX.Element {
+  // 呼出側が組み立て済みの配置を持っているなら、 それを使う。 測り直すと同じ図の配置を
+  // 2 度計算することになる (辺 500 本で約 300ms、 実測)
+  const laid = useMemo(() => laidProp ?? compile(diagram), [diagram, laidProp]);
+  const reduced = useReducedMotion();
+
+  // 生成時 geometry warn = 17 軸 visualValidate を走らせて error / warn を console に流す。
+  // React StrictMode の 2 重 mount で console 二重出力する可能性はあるが、 dev only の情報流用途で許容。
+  useEffect(() => {
+    if (!emitGeometryWarn) return;
+    // 上で組み立てた配置を渡す。 渡さない版は中でもう一度配置を計算するため、
+    // せっかく `laid` を受け取っても警告を出す時だけ計算が戻る
+    const report = visualValidateLaid(laid, diagram);
+    if (report.violations.length === 0) return;
+    const errors = report.violations.filter((v) => v.severity === "error");
+    const warns = report.violations.filter((v) => v.severity === "warn");
+    if (errors.length > 0) {
+      console.error(
+        `[cdl geometry] diagram "${diagram.id}" errors × ${errors.length}:\n` +
+          errors.slice(0, 5).map((v) => `  ${v.axis} — ${v.detail}`).join("\n") +
+          (errors.length > 5 ? `\n  ...+${errors.length - 5} more` : ""),
+      );
+    }
+    if (warns.length > 0) {
+      console.warn(
+        `[cdl geometry] diagram "${diagram.id}" warns × ${warns.length}:\n` +
+          warns.slice(0, 5).map((v) => `  ${v.axis} — ${v.detail}`).join("\n") +
+          (warns.length > 5 ? `\n  ...+${warns.length - 5} more` : ""),
+      );
+    }
+  }, [diagram, laid, emitGeometryWarn]);
+
+  // Timeline phases (description は cdl phase から拾う)
+  const phases = useMemo(
+    () =>
+      laid.phases.map((p) => ({
+        id: p.id,
+        label: p.id,
+        description: p.title,
+        durationMs: p.duration,
+      })),
+    [laid.phases],
+  );
+  const initialIndex = focusPhaseId ? laid.phases.findIndex((p) => p.id === focusPhaseId) : 0;
+  // focusPhaseId 指定時も autoplay + loop は true (= phase 内 state tween / particle は動く)。
+  // ただし phase 進行は engine が指定 phase に戻すことで「単 phase loop」 を擬似実装する。
+  const { timeline, state } = useTimeline(phases, {
+    initialPhaseIndex: initialIndex >= 0 ? initialIndex : 0,
+    autoplay: true,
+    loop: true,
+    // Legacy 並みの「ゆっくり読ませる」 テンポ
+    // = 各 phase の動き 0.9-1.1s + 2s 静止 = 1 phase 3s 前後、 4 phase 全体 ~14s
+    phaseHoldMs: 2000,
+    loopRestartDelayMs: 1800,
+  });
+
+  useEffect(() => {
+    timeline.autostart();
+  }, [timeline]);
+
+  // focusPhaseId 指定時 ... phase が focus 以外に進んだら強制的に戻す = 単 phase loop
+  useEffect(() => {
+    if (!focusPhaseId) return;
+    const focusIdx = laid.phases.findIndex((p) => p.id === focusPhaseId);
+    if (focusIdx < 0) return;
+    if (state.phaseIndex !== focusIdx) {
+      timeline.goto(focusIdx);
+      timeline.play();
+    }
+  }, [focusPhaseId, state.phaseIndex, timeline, laid.phases]);
+
+  const phaseIdx = focusPhaseId
+    ? laid.phases.findIndex((p) => p.id === focusPhaseId)
+    : state.phaseIndex;
+  const currentPhase = laid.phases[Math.max(0, phaseIdx)] ?? laid.phases[0];
+  const progress = reduced ? 1 : state.phaseProgress;
+
+  // state 値を計算 (現在 phase + これまでの phase の最終 tween 値を集約)
+  const baseStateValues = computeStateValues(laid, phaseIdx, progress);
+
+  // interactive integration: diagram に inputs / formulas / scrollTriggers / eventBindings が
+  // 含まれる場合、 signal / computed / scroll を wire up し stateOverrides で state 値を上書きする。
+  // 非 interactive diagram では noop (SSR safe、 signal 生成のみで DOM は触らない)。
+  const isInteractive = hasInteractivePrimitives(diagram);
+  const interactive = useInteractiveIntegration(
+    diagram,
+    {
+      ...(interactiveHandlers ? { handlers: interactiveHandlers } : {}),
+      phaseStateValues: baseStateValues,
+    },
+  );
+
+  // stateValues に signal / computed / scroll progress を merge (interactive 側優先)。
+  // 既存 phase-driven state と衝突しないよう state.id が signal / formula / scroll id と同じ場合のみ上書き。
+  const stateValues = useMemo(() => {
+    if (!isInteractive) return baseStateValues;
+    const merged: Record<string, string> = { ...baseStateValues };
+    for (const key of Object.keys(interactive.stateOverrides)) {
+      const v = interactive.stateOverrides[key];
+      if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") {
+        merged[key] = String(v);
+      }
+    }
+    return merged;
+  }, [isInteractive, baseStateValues, interactive.stateOverrides]);
+
+  return (
+    <div
+      ref={isInteractive ? interactive.containerRef : undefined}
+      data-cdl-diagram={diagram.id}
+      data-cdl-phase-index={phaseIdx}
+      data-cdl-phase-id={currentPhase?.id ?? ""}
+      data-cdl-viewbox={`${laid.viewBox.x} ${laid.viewBox.y} ${laid.viewBox.w} ${laid.viewBox.h}`}
+      className="relative w-full overflow-hidden bg-[var(--cdl-stage-bg,#f8fafc)] text-[color:var(--cdl-text,#0f172a)]"
+      style={{ fontFamily: "Inter, -apple-system, system-ui, sans-serif" }}
+    >
+      {!hideHeader && currentPhase && (
+        <CdlHeader
+          topic={laid.topic}
+          phases={laid.phases}
+          currentPhase={currentPhase}
+          phaseIdx={Math.max(0, phaseIdx)}
+          stateValues={stateValues}
+          states={laid.states}
+          onJumpPhase={(idx) => {
+            timeline.goto(idx);
+            timeline.play();
+          }}
+          headingLevel={headingLevel}
+        />
+      )}
+      {/* 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} />
+      {/* hideHeader + multi-phase 時、 phase indicator が消えると動きが読めないため
+          mini indicator (dot 列 + 現在 phase title + badge) を bottom に追加 */}
+      {hideHeader && !hideMiniPhaseIndicator && currentPhase && laid.phases.length > 1 && (
+        <div className="flex items-center justify-between gap-3 border-t border-[var(--cdl-divider,#d4d4d8)]/40 bg-[var(--cdl-stage-bg,#f1f5f9)]/50 px-3 py-2 text-xs">
+          <div className="flex items-center gap-1.5">
+            {laid.phases.map((p, i) => (
+              <span
+                key={p.id}
+                className={
+                  i === phaseIdx
+                    ? "h-1.5 w-6 rounded-full bg-[color:var(--cdl-text-accent,#2d6a8f)]"
+                    : "h-1.5 w-1.5 rounded-full bg-[color:var(--cdl-line-mute,#a89d8f)]/50"
+                }
+              />
+            ))}
+            <span className="ml-2 font-medium text-[color:var(--cdl-text,#1a1f2a)]">{currentPhase.title}</span>
+          </div>
+          {currentPhase.badge && (
+            <span className="rounded-full px-2 py-0.5 text-[10px] font-semibold" style={{ background: "color-mix(in srgb, var(--cdl-text-accent, #2d6a8f) 15%, transparent)", color: "var(--cdl-text-accent, #2d6a8f)" }}>
+              {currentPhase.badge}
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/scroll-trigger/index.ts

@@ -0,0 +1,109 @@
+import { signal, type Signal } from "../reactive";
+import type { CdlDiagram, CdlScrollTrigger } from "../types";
+import { computeScrollProgress } from "./progress";
+
+/**
+ * 1 scroll trigger 用の progress signal + attach/detach 制御 handle (CAR #245)。
+ */
+export type ScrollProgressHandle = {
+  /** progress signal (0..1)。 attach 前は初期値 0、 attach 後 scroll に追随して更新される。 */
+  readonly progress: Signal<number>;
+  /**
+   * 対象 element に scroll listener + IntersectionObserver を attach、 initial progress を計算する。
+   * 二重 attach は前 element を detach してから再 attach する挙動。
+   */
+  attach: (element: Element) => void;
+  /** 現 element から離脱、 listener + observer を解除。 progress signal は最終値を保持。 */
+  detach: () => void;
+};
+
+/**
+ * diagram の scrollTriggers から progress signal handles を生成 (CAR #245)。
+ * consumer は各 handle の attach(element) を DOM element に対して呼び、 signal.value で progress を read する。
+ *
+ * SSR safe = attach() 呼出前は browser API を触らないので Node.js / SSR 環境でも生成可能。
+ */
+export function createScrollProgressSignals(
+  diagram: CdlDiagram,
+): Record<string, ScrollProgressHandle> {
+  const result = Object.create(null) as Record<string, ScrollProgressHandle>;
+  const triggers = diagram.scrollTriggers ?? [];
+  for (const trigger of triggers) {
+    result[trigger.id] = createScrollProgressHandle(trigger);
+  }
+  return result;
+}
+
+/**
+ * 1 CdlScrollTrigger spec から ScrollProgressHandle を生成。 単体でも export、 動的追加 use case で使う。
+ */
+export function createScrollProgressHandle(spec: CdlScrollTrigger): ScrollProgressHandle {
+  const progress = signal(0);
+  let currentElement: Element | null = null;
+  let scrollListener: (() => void) | null = null;
+  let resizeListener: (() => void) | null = null;
+  let observer: IntersectionObserver | null = null;
+
+  const recompute = () => {
+    if (!currentElement || typeof window === "undefined") return;
+    const rect = currentElement.getBoundingClientRect();
+    try {
+      const p = computeScrollProgress(
+        { top: rect.top, bottom: rect.bottom },
+        window.innerHeight,
+        spec,
+      );
+      if (progress.value !== p) {
+        progress.value = p;
+      }
+    } catch {
+      // viewport 0 等の edge case は silent skip (次 recompute で正常化する想定)
+    }
+  };
+
+  const handle: ScrollProgressHandle = {
+    progress,
+    attach(element) {
+      if (currentElement === element) return;
+      if (currentElement) handle.detach();
+      currentElement = element;
+      if (typeof window === "undefined") return;
+      // IntersectionObserver は viewport in/out 変化時に recompute を trigger するだけの用途 (in-view gate
+      // ではない、 codex Round 3 findings 参照)。 anchor jump / programmatic scroll で observer callback が
+      // 抜けても、 scroll listener が常時 recompute するため progress は正しく追随する。
+      if (typeof IntersectionObserver !== "undefined") {
+        observer = new IntersectionObserver(() => {
+          recompute();
+        });
+        observer.observe(element);
+      }
+      scrollListener = () => {
+        recompute();
+      };
+      resizeListener = () => recompute();
+      window.addEventListener("scroll", scrollListener, { passive: true });
+      window.addEventListener("resize", resizeListener, { passive: true });
+      // 初回 recompute (attach 直後の scroll 位置を反映)
+      recompute();
+    },
+    detach() {
+      if (!currentElement) return;
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+      if (scrollListener && typeof window !== "undefined") {
+        window.removeEventListener("scroll", scrollListener);
+        scrollListener = null;
+      }
+      if (resizeListener && typeof window !== "undefined") {
+        window.removeEventListener("resize", resizeListener);
+        resizeListener = null;
+      }
+      currentElement = null;
+    },
+  };
+  return handle;
+}
+
+export { computeScrollProgress } from "./progress";

package/src/scroll-trigger/progress.ts

@@ -0,0 +1,49 @@
+import type { CdlScrollTrigger } from "../types";
+
+/**
+ * scroll progress 計算 (pure function、 CAR #245)。
+ *
+ * spec.start / spec.end の semantics:
+ * - progress 0 = element top が viewport 相対位置 start に到達した瞬間
+ *   (default start = 1.0 = element top が viewport bottom に到達 = 進捗開始)
+ * - progress 1 = element bottom が viewport 相対位置 end に到達した瞬間
+ *   (default end = 0.0 = element bottom が viewport top に到達 = 進捗完了)
+ *
+ * 中心基準ではなく edge 基準にすることで、 element の height に依存しない一貫した scroll 距離での
+ * 進捗計算になる (codex Round 1 finding fix、 中心基準だと element height の半分だけ range が縮まる)。
+ *
+ * @param elementRect getBoundingClientRect 相当 (top / bottom は viewport 相対座標)
+ * @param viewportHeight window.innerHeight 相当
+ * @param spec CdlScrollTrigger の start / end
+ * @returns 0..1 の progress (clamp 済)
+ */
+export function computeScrollProgress(
+  elementRect: { top: number; bottom: number },
+  viewportHeight: number,
+  spec: Pick<CdlScrollTrigger, "start" | "end">,
+): number {
+  if (viewportHeight <= 0) {
+    throw new Error(`viewport height must be positive (got ${viewportHeight})`);
+  }
+  const start = spec.start ?? 1.0;
+  const end = spec.end ?? 0.0;
+  const elementHeight = elementRect.bottom - elementRect.top;
+  // startPos = element top が progress 0 になる位置 (= start * viewport height)
+  // endPos = element top が progress 1 になる位置 (= end * viewport height - element height、
+  //   element bottom が end * viewport height に来た瞬間を element top 座標で表現)
+  //
+  // 注 = start === end は「center-to-center」 系の valid trigger (element height の scroll 距離で
+  // element top から element bottom まで通過する)。 range は element height。
+  // 但し start === end かつ element height 0 の場合は degenerate case として startPos === endPos で throw。
+  const startPos = start * viewportHeight;
+  const endPos = end * viewportHeight - elementHeight;
+  if (startPos === endPos) {
+    throw new Error(
+      `scroll trigger の progress range が 0 になりました (start ${start} / end ${end} / element height ${elementHeight}、 element に高さがない可能性)`,
+    );
+  }
+  const rawProgress = (startPos - elementRect.top) / (startPos - endPos);
+  if (rawProgress < 0) return 0;
+  if (rawProgress > 1) return 1;
+  return rawProgress;
+}

package/src/thumbnail.tsx

@@ -0,0 +1,114 @@
+import type { JSX } from "react";
+import { useEffect, useState } from "react";
+import { CdlDiagramView, type CdlDiagramViewProps } from "./render";
+
+/**
+ * CdlDiagramThumbnail ... 通常は CdlDiagramView を縮小表示、
+ * クリックでモーダル開いて viewport いっぱい (94vw x 90vh) に拡大表示する。
+ * Escape / 背景クリック / × ボタンで close。
+ */
+export function CdlDiagramThumbnail(props: CdlDiagramViewProps): JSX.Element {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("keydown", onKey);
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        aria-label="拡大表示"
+        data-cdl-diagram={props.diagram.id}
+        style={{
+          display: "block",
+          width: "100%",
+          padding: 0,
+          margin: 0,
+          border: "none",
+          background: "transparent",
+          cursor: "zoom-in",
+          textAlign: "left",
+        }}
+      >
+        <CdlDiagramView {...props} />
+      </button>
+      {open && (
+        <div
+          onClick={() => setOpen(false)}
+          role="dialog"
+          aria-modal="true"
+          aria-label="diagram 拡大表示"
+          style={{
+            position: "fixed",
+            top: 0,
+            left: 0,
+            width: "100vw",
+            height: "100vh",
+            background: "var(--cdl-thumbnail-overlay-bg, rgba(45, 35, 25, 0.78))",
+            backdropFilter: "blur(4px)",
+            zIndex: 1000,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: "3vh 3vw",
+            cursor: "zoom-out",
+          }}
+        >
+          <div
+            onClick={(e) => e.stopPropagation()}
+            style={{
+              position: "relative",
+              maxWidth: "94vw",
+              maxHeight: "94vh",
+              width: "auto",
+              height: "auto",
+              background: "var(--cdl-thumbnail-modal-bg, #ede2d4)",
+              borderRadius: 24,
+              boxShadow: "0 24px 64px rgba(0, 0, 0, 0.35)",
+              overflow: "auto",
+              cursor: "default",
+            }}
+          >
+            <button
+              type="button"
+              onClick={() => setOpen(false)}
+              aria-label="閉じる"
+              style={{
+                position: "absolute",
+                top: 12,
+                right: 16,
+                width: 36,
+                height: 36,
+                borderRadius: 18,
+                border: "none",
+                background: "var(--cdl-thumbnail-close-bg, rgba(61, 50, 41, 0.12))",
+                color: "var(--cdl-text, #1a1f2a)",
+                fontSize: 22,
+                lineHeight: 1,
+                cursor: "pointer",
+                zIndex: 1,
+              }}
+            >
+              ×
+            </button>
+            <div style={{ padding: 24 }}>
+              <CdlDiagramView {...props} hideHeader={false} />
+            </div>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}