@cardenelabs/dragon 0.7.0 → 0.8.0

package/src/index.ts

@@ -13,7 +13,7 @@ export { compileToCdl } from "./compile";
 export type { CompileNotice } from "./compile";
 export { parseTextDslV05 } from "./v05";
 // 記法一覧が「実際に受け付ける値」 を実装から引くための公開。 手書きすると説明と実装がずれる。
-export { PRESET_TYPES } from "./v05/parser";
+export { PRESET_TYPES, TOP_LEVEL_KEYS } from "./v05/parser";
 export { TONE_ALIAS, NODE_KIND_ALIAS } from "./keywords";
 export { lintDiagram, autoFix } from "./notation-lint";
 export type { LintIssue, LintReport, LintSeverity } from "./notation-lint";
@@ -109,6 +109,9 @@ export type {
   DslPhase,
   DslTween,
   DslSet,
+  // `DslDocument.values` を触る利用者が型を import できるようにする (#1169)。
+  // 兄弟の `DslState` / `DslTween` / `DslSet` は公開されており、これだけ漏れていた
+  DslValue,
   DslError,
   PresetType,
   DslLane,

package/src/input-size.ts

@@ -49,6 +49,9 @@ export interface InputSize {
  * **段の中身 (光らせる相手 / 遷移 / 即時変更) も数える**。 段の数だけを見ると、
  * 1 段に 1,000 件の相手を書いた形が 1 件として通る。 実測ではこの形が組み立ての中で
  * 約 100 万件に展開され、 呼び出しの深さが上限を超えて落ちた。
+ *
+ * **他の値から決まる値 (`values:`) も数える** (#1162)。 これらは毎 frame 解かれるので、
+ * 数に入れないと上限をすり抜けた本文が描画のたびに重さを持つ。
  */
 export function countDocElements(doc: DslDocument): number {
   const phases = doc.animate?.phases ?? [];
@@ -62,6 +65,7 @@ export function countDocElements(doc: DslDocument): number {
     phases.length +
     phaseChildren +
     (doc.animate?.states.length ?? 0) +
+    (doc.values?.length ?? 0) +
     (doc.groups ? Object.keys(doc.groups).length : 0) +
     (doc.lanes ? Object.keys(doc.lanes).length : 0)
   );
@@ -87,6 +91,7 @@ export function countDiagramElements(diagram: {
   formulas?: unknown[];
   scrollTriggers?: unknown[];
   eventBindings?: unknown[];
+  derived?: unknown[];
 }): number {
   const phases = Array.isArray(diagram.phases) ? diagram.phases : [];
   const phaseChildren = phases.reduce((acc: number, p) => {
@@ -111,7 +116,9 @@ export function countDiagramElements(diagram: {
     (diagram.inputs?.length ?? 0) +
     (diagram.formulas?.length ?? 0) +
     (diagram.scrollTriggers?.length ?? 0) +
-    (diagram.eventBindings?.length ?? 0)
+    (diagram.eventBindings?.length ?? 0) +
+    // 他の値から決まる値 (#1162)。 記法側 (`countDocElements`) が数えるので、こちらも揃える
+    (diagram.derived?.length ?? 0)
   );
 }
 

package/src/json-parser.ts

@@ -18,8 +18,11 @@
  *   YAML `animation: [step: "..."]` ⇔ JSON `{animation: [{step: "...", duration: 1.4, focus: [...]}]}`
  */
 
+import { PRESET_TYPES } from "./v05/parser";
+import type { CompileToCdlOpts } from "./compile";
 import type { CdlDiagram, NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
-import type { DslDocument, DslActor, DslStep, DslAnimate, DslPhase, PresetType, LayoutMode, LayoutPos } from "./types";
+import type { DslDocument, DslActor, DslStep, DslAnimate, DslPhase, DslState, PresetType, LayoutMode, LayoutPos } from "./types";
+import { checkValueExpression, isValueName, valueNameIssue } from "./value-syntax";
 import { compileToCdl } from "./compile";
 
 /**
@@ -30,10 +33,35 @@ export interface DragonJson {
   title: string;
   /** preset type (必須): sequence / flow / swimlane / er / state / topology / solidity / gantt / class / pie / c4 / mind */
   type: PresetType;
+  /**
+   * 図表の箱の上に出す小見出し (optional)。 記法の最上位 `eyebrow:` と同じ (#1247)。
+   *
+   * 効くのは図全体を 1 箱にする図種 (`pie` / `bar` / `line` / `funnel` / `tree` / `journey` /
+   * `quadrant` / `mind` / `gantt`) だけ。 箱ごとに分かれる図種では相手が決まらないため、
+   * 組み立て側が知らせを出す。 そちらは `actors[].eyebrow` に書く。
+   */
+  eyebrow?: string;
   /** 登場人物 (必須): 文字列 or { name, kind, ... } object */
   actors: (string | JsonActor)[];
   /** flow step 配列 (必須): { from, to, label, ... } */
   flow: JsonStep[];
+  /**
+   * 状態の初期値 (optional)。 記法の `states:` と同じ (#1181)。
+   *
+   * `{名前}` を箱の文字に置くと、ここに書いた値が描画側で置き換わる。 名前は英数字と `_`
+   * だけ (描画側が置き換える時に見る範囲と揃える)。
+   *
+   * ここに書けるのは初期値まで。 段で動かすのは `animation[].tween` / `animation[].set`
+   * (`#1186` で追加、記法の `tween:` / `set:` と同じ)。
+   */
+  states?: Record<string, number | string>;
+  /**
+   * 他の値から自動で決まる値 (optional)。 記法の `values:` と同じ (#1181)。
+   *
+   * 式には四則 (`+ - * /`) と括弧、比較 (`> >= < <= == !=`)、`min` / `max` が書ける。
+   * 他の値は `{名前}` で読む。 解くのは描画側で、毎 frame 参照から順に決まる。
+   */
+  values?: Record<string, string>;
   /** animation phase 配列 (optional) */
   animation?: JsonPhase[];
   /** viewport (optional): 全体 canvas size / gap */
@@ -114,6 +142,8 @@ export interface JsonStep {
   cardinality?: string;
   labelOffsetX?: number;
   labelOffsetY?: number;
+  /** true で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
+  overlay?: boolean;
   /**
    * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = edge label offset。 未指定は
    * backward compat、 set 済は Phase 2 の applyPosOffset で edge label 位置を shift する。
@@ -132,6 +162,19 @@ export interface JsonPhase {
   body?: string;
   /** badge label */
   badge?: string;
+  /**
+   * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
+   *
+   * 足すまで JSON の入口は `states:` で初期値を書けても **動かす手段が無かった** ため、
+   * 同じ図を記法で書くと動き JSON で書くと静止する状態だった (#1181 で状態を足した時の残り)。
+   */
+  tween?: Record<string, readonly [number, number]>;
+  /**
+   * 段の切替で値を差し替える (#1186)。 記法の `set: name value` と同じ。
+   *
+   * `tween` が段の中を補間するのに対し、こちらは段の切替時に 1 度だけ変える。
+   */
+  set?: Record<string, number | string>;
 }
 
 /**
@@ -155,20 +198,13 @@ const VALID_KIND_SET: ReadonlySet<string> = new Set([
   "contract", "eoa", "multisig", "proxy", "library", "interface",
 ]);
 
-const VALID_PRESETS: readonly PresetType[] = [
-  "sequence",
-  "flow",
-  "swimlane",
-  "er",
-  "state",
-  "topology",
-  "solidity",
-  "gantt",
-  "class",
-  "pie",
-  "c4",
-  "mind",
-] as const;
+/**
+ * 受け付ける図種。 **記法側と同じ集合を使う** (`v05/parser.ts` の `PRESET_TYPES`)。
+ *
+ * 以前はここに一覧を写していたため、 記法に型を足しても JSON 経路が古い一覧のまま弾いた
+ * (`bar` / `line` で実際に起きた)。 型が 3 箇所に散らばると、 必ずどれかが古くなる。
+ */
+const VALID_PRESETS: readonly PresetType[] = [...PRESET_TYPES];
 
 /**
  * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
@@ -193,16 +229,266 @@ function validateLayoutPos(v: unknown, path: string, errors: JsonDslError[]): vo
   }
 }
 
+/**
+ * 写しを作る時の入れ子の深さの上限。
+ *
+ * 枠の並びの長さが入れ子の深さで決まる。 図の入れ子は深くても数段で、 64 に届く形は書けない。
+ */
+const 写しの最大の深さ = 64;
+
+/**
+ * 写しを作る時に触る値の数の上限。
+ *
+ * **書式の規則ではなく、 資源を使い切らないための歯止め**。 図の書式は値の数を制限していないので、
+ * ここで拒むのは「構造としては正しいが大きすぎる」 入力になる。 だから **正当な入力が届かない
+ * 高さ** に置く。
+ *
+ * 500 万は、 記法の入力の大きさの上限 (`input-size.ts` の 512KB) を全て 2 文字の値で埋めても
+ * 届かない数になる。 JSON でも同じ規模の図が 500 万個の値を持つことはない。
+ *
+ * **数を数えないと守れない** (Round 4 の指摘)。 一度は「写しの大きさは元の入力の大きさで決まる
+ * から数える意味が無い」 として外したが、 これは誤りだった。 Proxy は読まれるたびに新しい object
+ * を返せるため、 **小さな入力から枝を生やせる** (実測 = 1 個の Proxy が深さ 6 / 6 分岐で
+ * 55,987 個の object に膨らんだ)。 深さの上限だけでは横の広がりを止められない。
+ */
+const 写しの最大の項目数 = 5_000_000;
+
+/** 写しを作れなかった理由 (path 付き) */
+class 写せない extends Error {
+  constructor(
+    readonly path: string,
+    readonly 理由: string,
+  ) {
+    super(`${path}: ${理由}`);
+  }
+}
+
+/**
+ * 検査の前に 1 度だけ読んで作る、 素のデータの複製 (#1217)。
+ *
+ * 入口は検査する時と図に写す時で同じ項目を 2 度読んでいた。 渡された object が値を返す関数
+ * (getter) を持っていると、 2 度目の読み取りで別の値を返せる = **検査を通った値と図に届く値が
+ * 別物になり、 検査が意味を持たない** (実測 = `animation[0].tween` を 6 回目から
+ * `[NaN, Infinity]` を返す getter にすると、 検査を通って図に `from: null` が届いた)。
+ *
+ * ここで 1 度だけ読んで写しを作り、 以降は写しだけを読む。 各項目の読み取りは 1 回で、
+ * 項目の名前も添字も同じ値を 2 度取りに行かない。
+ *
+ * **`structuredClone` は使わない**。 関数や symbol を含む入力で `DataCloneError` を投げるため、
+ * `validateDragonJson` が約束している「誤りは `{ ok: false, errors }` で返す」 が破れる。
+ * 自前で写せば、 写せない値もそのまま持ち越して検査側の型の判定に落とせる。
+ *
+ * **再帰では書かない** (Round 1 の指摘)。 検査が見ない項目も含めて写すため、 深い入れ子を渡すと
+ * 呼び出しの積み上げが溢れる (実測 = 使わない項目に 20,000 段の入れ子を付けると
+ * `RangeError: Maximum call stack size exceeded`)。 枠を自前で積んで回す。
+ *
+ * **読む順は書いた順のまま、 深さ優先で降りる** (Round 2 / 3 の指摘)。 値を返す関数が副作用を
+ * 持つ入力では読む順が結果に出るため、 再帰で書いた時と同じ順を保つ。 幅優先で回すと、 先に
+ * 書いた兄弟の深い所より後の兄弟の浅い所を先に読む。
+ *
+ * **読み取りの例外も外に出さない** (Round 1 の指摘)。 項目の名前を数える所も値を読む所も、
+ * getter や Proxy が投げれば `validateDragonJson` 自体が throw して約束が破れる。 投げた場所を
+ * path として拾い、 検査の誤りに変える。
+ *
+ * 書き込みは `Object.defineProperty` で行う = `__proto__` を項目名に持つ入力で代入が
+ * prototype の setter に落ちるのを避ける (`JSON.parse` と同じく普通の項目として持つ)。
+ * `__proto__` を書いた時の扱いそのものは `#1184` が持つ。
+ *
+ * 輪 (自分を指す入れ子) は同じ写しを返して止める。 JSON からは作れないが、 object を直接
+ * 渡す経路では作れる。
+ *
+ * ## 守る範囲 (Round 6 で線を引いた)
+ *
+ * この関数が守るのは **自分が確保する量** = 写しの入れ物と、 名前の一覧と、 枠の並び。 いずれも
+ * 上限 (深さ / 数) を見てから作る。
+ *
+ * **渡された側が自分で確保する量は守れない**。 Proxy の `ownKeys` は「名前の並びを返す」 のが
+ * 仕事で、 その並びは trap の中で作られる。 こちらが受け取った時点で既に在るため、 長さを見て
+ * 拒んでも確保そのものは起きた後になる。 これは呼ぶ側の code が確保するもので、 同じ process に
+ * 任意の object を渡せる相手は、 この関数を通さずに同じことができる。
+ *
+ * 線を引くのは、 5 round にわたって「読む前に量を作れる経路」 を潰し続けた末に、 残りが
+ * 呼ぶ側の code の中に移ったため。 潰す対象が自分の外に出た時点で、 この関数の責務ではない。
+ */
+function 素のデータに写す(
+  root: unknown,
+): { ok: true; value: unknown } | { ok: false; error: JsonDslError } {
+  const 写し済 = new WeakMap<object, unknown[] | Record<string, unknown>>();
+  let 項目数 = 0;
+  // 例外を拾った時に「どこを読んでいたか」 を言うために持つ。 投げるのは値を読む所と名前を
+  // 数える所の両方で、 どちらも path を持たないまま外へ出ると `$` としか言えない
+  let 読んでいる場所 = "$";
+
+  /**
+   * まだ中身を埋めていない入れ物と、 その進み具合。
+   *
+   * 配列は名前の並びを持たず長さだけを持つ (Round 6 の指摘)。 添字を文字の並びとして実体化すると、
+   * **上限を見る前にその並びを作ってしまう** (実測 = `new Array(5_000_001)` で 500 万個の添字を
+   * 作ろうとした)。 添字は数から導けるので持つ必要がない。
+   */
+  type 枠 = {
+    元: object;
+    器: unknown[] | Record<string, unknown>;
+    /** object の時だけ持つ。 配列は `長さ` を使う */
+    名前の並び: string[] | null;
+    長さ: number;
+    次: number;
+    深さ: number;
+    path: string;
+  };
+
+  /** 入れ物だけ作る (ここでは降りない)。 新しく作った時だけ枠を返す */
+  const 器を作る = (
+    v: unknown,
+    深さ: number,
+    path: string,
+  ): { 値: unknown; 枠: 枠 | null } => {
+    項目数 += 1;
+    if (項目数 > 写しの最大の項目数) {
+      throw new 写せない(path, `項目が多すぎる (上限 ${写しの最大の項目数})`);
+    }
+    if (v === null || typeof v !== "object") return { 値: v, 枠: null };
+
+    const 既にある = 写し済.get(v);
+    if (既にある !== undefined) return { 値: 既にある, 枠: null };
+
+    if (深さ >= 写しの最大の深さ) {
+      throw new 写せない(path, `入れ子が深すぎる (上限 ${写しの最大の深さ})`);
+    }
+    読んでいる場所 = path;
+    const 並びか = Array.isArray(v);
+    const 器: unknown[] | Record<string, unknown> = 並びか ? [] : {};
+    写し済.set(v, 器);
+
+    if (並びか) {
+      // **長さを先に見てから降りる** (Round 6 の指摘)。 添字を文字の並びとして作ると、 上限を
+      // 見る前にその並びを作ってしまう。 長さは数を読むだけなので何も作らない。
+      //
+      // **長さは正規化してから使う** (Round 7 の指摘)。 `Array.from({ length })` は仕様の
+      // `ToLength` を通しており、 生の値をそのまま使うと 2 つの形で壊れる。
+      //
+      // | `length` が返す値 | 正規化しないと |
+      // |---|---|
+      // | `2.5` | 3 回読む (`Array.from` は 2 要素) |
+      // | `NaN` | 数の合計が `NaN` になり、 上限も終わりも判定できず読み続ける |
+      //
+      // `ToLength` と同じく 0 へ丸め、 0 以上 2^53-1 以下に収める。
+      //
+      // **数に直すのは単項 `+`** (Round 8 の指摘)。 `Number()` は `BigInt` を通してしまうが、
+      // 仕様の `ToNumber` は `TypeError` を投げる = `Array.from({ length: 2n })` は投げる。
+      // 単項 `+` は `ToNumber` そのものなので、 投げる形も含めて元の挙動と揃う (投げた分は
+      // 下の `catch` が検査の誤りに変える)。
+      const 生の長さ = +(v as unknown[]).length;
+      const 長さ = Number.isNaN(生の長さ)
+        ? 0
+        : Math.min(Math.max(Math.trunc(生の長さ), 0), Number.MAX_SAFE_INTEGER);
+      項目数 += 長さ;
+      if (項目数 > 写しの最大の項目数) {
+        throw new 写せない(path, `項目が多すぎる (上限 ${写しの最大の項目数})`);
+      }
+      return { 値: 器, 枠: { 元: v, 器, 名前の並び: null, 長さ, 次: 0, 深さ, path } };
+    }
+
+    // **名前も数に入れる** (Round 5 の指摘)。 値を読む前に名前の一覧を作るため、 値だけを
+    // 数えると「名前が 20,000 個ある段を 63 回降りる」 形で 126 万個を並べられる = 上限を
+    // 見る前に資源を使い切れる
+    const 名前の並び = Object.keys(v as Record<string, unknown>);
+    項目数 += 名前の並び.length;
+    if (項目数 > 写しの最大の項目数) {
+      throw new 写せない(path, `項目が多すぎる (上限 ${写しの最大の項目数})`);
+    }
+    return { 値: 器, 枠: { 元: v, 器, 名前の並び, 長さ: 名前の並び.length, 次: 0, 深さ, path } };
+  };
+
+  try {
+    const 先頭 = 器を作る(root, 0, "$");
+    const 積み: 枠[] = 先頭.枠 ? [先頭.枠] : [];
+
+    while (積み.length > 0) {
+      const 今 = 積み[積み.length - 1]!;
+      if (今.次 >= 今.長さ) {
+        積み.pop();
+        continue;
+      }
+      // 配列は添字をその場で作る (並びとして持たない)
+      const key = 今.名前の並び === null ? String(今.次) : 今.名前の並び[今.次]!;
+      今.次 += 1;
+      const 子のpath = 今.名前の並び === null ? `${今.path}[${key}]` : `${今.path}.${key}`;
+
+      // 読む直前に場所を控える = 値の読み取りそのものが投げるため、 読んだ後では遅い
+      読んでいる場所 = 子のpath;
+      const 生の値 = (今.元 as Record<string, unknown>)[key];
+
+      const 子 = 器を作る(生の値, 今.深さ + 1, 子のpath);
+      if (Array.isArray(今.器)) 今.器.push(子.値);
+      else {
+        Object.defineProperty(今.器, key, {
+          value: 子.値,
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        });
+      }
+      // 深さ優先で降りる = 次の兄弟を読む前に、 この子の中身を全部読む
+      if (子.枠) 積み.push(子.枠);
+    }
+    return { ok: true, value: 先頭.値 };
+  } catch (e) {
+    if (e instanceof 写せない) {
+      return { ok: false, error: { path: e.path, message: e.理由 } };
+    }
+    // getter / Proxy が投げた形。 約束どおり誤りとして返す (throw しない)
+    return {
+      ok: false,
+      error: {
+        path: 読んでいる場所,
+        message: "入力を読み取れない",
+        hint: e instanceof Error ? e.message : String(e),
+      },
+    };
+  }
+}
+
 function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: false; errors: JsonDslError[] } {
   const errors: JsonDslError[] = [];
-  if (!json || typeof json !== "object" || Array.isArray(json)) {
+  // root の形は写しより先に見る = 形が違う入力には従来どおり `root must be a JSON object` を
+  // 返すため。 写した後に見ると、 root が配列の入力で中の getter が先に動き、 別の誤りに化ける
+  // (Round 3 の指摘)。
+  //
+  // ただし `Array.isArray` は失効した Proxy で `TypeError` を投げる (Round 2 の指摘)。 判定
+  // そのものを受けて、 投げた形は「読み取れない」 として返す。
+  let rootがobjectか: boolean;
+  try {
+    rootがobjectか = !!json && typeof json === "object" && !Array.isArray(json);
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path: "$",
+          message: "入力を読み取れない",
+          hint: e instanceof Error ? e.message : String(e),
+        },
+      ],
+    };
+  }
+  if (!rootがobjectか) {
     return { ok: false, errors: [{ path: "$", message: "root must be a JSON object" }] };
   }
-  const j = json as Record<string, unknown>;
+
+  // 以降は写しだけを読む。 元の object には二度と触らない (#1217)
+  const 写し = 素のデータに写す(json);
+  if (!写し.ok) return { ok: false, errors: [写し.error] };
+  const j = 写し.value as Record<string, unknown>;
 
   if (typeof j.title !== "string" || j.title.length === 0) {
     errors.push({ path: "$.title", message: "title must be a non-empty string" });
   }
+  // 図表の箱の上の小見出し (#1247)。 空文字は「書かなかった」 と同じ扱いにするため通す
+  // (記法側の `eyebrow:` と揃える。 落とすのは `jsonToDoc`)
+  if (j.eyebrow !== undefined && typeof j.eyebrow !== "string") {
+    errors.push({ path: "$.eyebrow", message: "eyebrow must be a string if present" });
+  }
   // CAR-1693 Phase 1: diagram-level layout mode の validation (未指定 = auto default で backward compat)
   if (j.layout !== undefined && j.layout !== "auto" && j.layout !== "manual") {
     errors.push({ path: "$.layout", message: 'layout must be "auto" or "manual" if present' });
@@ -290,19 +576,153 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
         if (typeof po.step !== "string" || po.step.length === 0) {
           errors.push({ path: `$.animation[${i}].step`, message: "phase.step must be a non-empty string" });
         }
+        validatePhaseMotion(po, i, errors);
       });
     }
   }
+  validateStates(j.states, errors);
+  validateValues(j.values, errors);
   if (errors.length > 0) return { ok: false, errors };
   return { ok: true, data: j as unknown as DragonJson };
 }
 
+/**
+ * 段の中で値を動かす指定を見る (#1186)。
+ *
+ * 状態名の記法は `states:` と同じ判定を使う。 参照先はこの JSON の `states` だけでは決めない。
+ * 見本や preset が持つ状態を動かす指定もあるためで、記法側と同じく compile 後の図で解決する。
+ */
+function validatePhaseMotion(
+  po: Record<string, unknown>,
+  i: number,
+  errors: JsonDslError[],
+): void {
+  if (po.tween !== undefined) {
+    if (!po.tween || typeof po.tween !== "object" || Array.isArray(po.tween)) {
+      errors.push({
+        path: `$.animation[${i}].tween`,
+        message: "tween must be a plain object of state -> [from, to]",
+      });
+    } else {
+      for (const [name, range] of Object.entries(po.tween as Record<string, unknown>)) {
+        const path = `$.animation[${i}].tween.${name}`;
+        if (!isValueName(name)) errors.push({ path, ...valueNameIssue(name) });
+        if (!Array.isArray(range) || range.length !== 2) {
+          errors.push({ path, message: "tween value must be [from, to]" });
+          continue;
+        }
+        // 補間は数どうしでしか成り立たない。 文字列を通すと描画側が数として読めず
+        // 段の途中が壊れる (記法側も数だけを受ける)
+        for (const v of range) {
+          if (typeof v !== "number" || !Number.isFinite(v)) {
+            errors.push({ path, message: "tween value must be finite numbers", hint: `got ${typeof v}` });
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  if (po.set !== undefined) {
+    if (!po.set || typeof po.set !== "object" || Array.isArray(po.set)) {
+      errors.push({
+        path: `$.animation[${i}].set`,
+        message: "set must be a plain object of state -> value",
+      });
+    } else {
+      for (const [name, value] of Object.entries(po.set as Record<string, unknown>)) {
+        const path = `$.animation[${i}].set.${name}`;
+        if (!isValueName(name)) errors.push({ path, ...valueNameIssue(name) });
+        const t = typeof value;
+        if (t !== "number" && t !== "string") {
+          errors.push({ path, message: "set value must be a number or string", hint: `got ${t}` });
+        } else if (t === "number" && !Number.isFinite(value as number)) {
+          errors.push({ path, message: "set value must be a finite number" });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * 状態の初期値を見る (#1181)。
+ *
+ * 名前の判定は記法と同じものを使う (`value-syntax.ts`)。 別々に持つと、YAML では弾かれる
+ * 名前が JSON では通る形ができ、描画側が `{名前}` を置き換えられない図が生まれる。
+ */
+function validateStates(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({ path: "$.states", message: "states must be a plain object of name -> initial value" });
+    return;
+  }
+  for (const [name, initial] of Object.entries(v as Record<string, unknown>)) {
+    if (!isValueName(name)) {
+      errors.push({ path: `$.states.${name}`, ...valueNameIssue(name) });
+    }
+    const t = typeof initial;
+    if (t !== "number" && t !== "string") {
+      errors.push({
+        path: `$.states.${name}`,
+        message: "state initial must be a number or string",
+        hint: `got ${t}`,
+      });
+    } else if (t === "number" && !Number.isFinite(initial as number)) {
+      // `NaN` / `Infinity` は JSON には書けないが、object を直接渡す経路では届く。
+      // 描画側は文字列に直して式に流すため、そのまま通すと計算が全て壊れる
+      errors.push({ path: `$.states.${name}`, message: "state initial must be a finite number" });
+    }
+  }
+}
+
+/**
+ * 他の値から決まる値を見る (#1181)。
+ *
+ * 名前と式の判定は記法と同じものを使う。 式が文法として正しいかまでは見ない (描画側が
+ * 評価する時に判定して、その値だけを止める = spec § 4.2)。
+ */
+function validateValues(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({ path: "$.values", message: "values must be a plain object of name -> expression" });
+    return;
+  }
+  for (const [name, expression] of Object.entries(v as Record<string, unknown>)) {
+    if (!isValueName(name)) {
+      errors.push({ path: `$.values.${name}`, ...valueNameIssue(name) });
+    }
+    if (typeof expression !== "string" || expression.trim() === "") {
+      errors.push({
+        path: `$.values.${name}`,
+        message: "value expression must be a non-empty string",
+        hint: '`"{inflow} - {done}"` の形で書く',
+      });
+      continue;
+    }
+    for (const issue of checkValueExpression(expression, name)) {
+      errors.push({ path: `$.values.${name}`, ...issue });
+    }
+  }
+}
+
 /**
  * JSON DSL → DslDocument (AST) 変換。 pos は JSON なので line 情報なし、 全て line 0。
  *
  * CAR-1693 Phase 1: DSL 表面 `pos: {x, y}` → 内部 AST `layoutPos:` の 2 層 mapping の実装 core。
  * test で mapping logic を実 execute するため export する (pos-field.test.ts の regression guard)。
  */
+/**
+ * 図表の箱の上の小見出しを、 記法側と同じ形に整える (#1247)。
+ *
+ * 記法は値を `trim()` してから空かどうかを見る。 JSON でも同じ順で見ないと、 空白だけの値が
+ * 入口によって別の意味になる (記法は書かなかった扱い、 JSON は中身のない帯)。
+ */
+function 整えた小見出し(v: string | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  const t = v.trim();
+  return t.length > 0 ? t : undefined;
+}
+
 export function jsonToDoc(json: DragonJson): DslDocument {
   const p0 = { line: 0 };
   const actors: DslActor[] = json.actors.map((a) => {
@@ -345,28 +765,55 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     cardinality: s.cardinality,
     labelOffsetX: s.labelOffsetX,
     labelOffsetY: s.labelOffsetY,
+    overlay: s.overlay,
     // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos
     layoutPos: s.pos,
     pos: p0,
   }));
-  let animate: DslAnimate | undefined;
-  if (json.animation && json.animation.length > 0) {
-    const phases: DslPhase[] = json.animation.map((p) => ({
-      name: p.step,
-      durationMs: Math.round((p.duration ?? 1.4) * 1000),
-      highlight: p.focus,
-      body: p.body,
-      badge: p.badge,
-      pos: p0,
-    }));
-    animate = { states: [], phases, pos: p0 };
-  }
+  // 状態は段が無くても図に載る (#1162 で組み立ての出口が載せる)。 **段の有無で分けない** =
+  // 分けると `states` だけを書いた JSON で値が 1 つも届かない (記法側で起きていた形、 #1181)
+  const states: DslState[] = Object.entries(json.states ?? {}).map(([name, initial]) => ({
+    name,
+    initial,
+    pos: p0,
+  }));
+  const phases: DslPhase[] = (json.animation ?? []).map((p) => ({
+    name: p.step,
+    durationMs: Math.round((p.duration ?? 1.4) * 1000),
+    highlight: p.focus,
+    body: p.body,
+    badge: p.badge,
+    // 段の中で動かす分 (#1186)。 記法側の `tweens` / `sets` と同じ形に写す。
+    // 空の配列を置かないのは、記法側が「無ければ field ごと持たない」 形だから
+    ...(p.tween && Object.keys(p.tween).length > 0
+      ? {
+          tweens: Object.entries(p.tween).map(([state, [from, to]]) => ({ state, from, to, pos: p0 })),
+        }
+      : {}),
+    ...(p.set && Object.keys(p.set).length > 0
+      ? { sets: Object.entries(p.set).map(([state, value]) => ({ state, value, pos: p0 })) }
+      : {}),
+    pos: p0,
+  }));
+  const animate: DslAnimate | undefined =
+    states.length > 0 || phases.length > 0 ? { states, phases, pos: p0 } : undefined;
   return {
     title: json.title,
     type: json.type,
+    // 前後の空白を落としてから見る。 記法側 (`v05/parser.ts`) が `trim()` してから
+    // 空かどうかを判定するため、 揃えないと **空白だけの値で入口ごとに図が変わる**
+    // (記法は書かなかった扱い、 JSON は中身のない帯を描く。 Round 2 の指摘で実測)
+    ...(整えた小見出し(json.eyebrow) !== undefined
+      ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: p0 }
+      : {}),
     actors,
     flow,
     animate,
+    // 他の値から決まる値 (#1181)。 書いた順に並べる = 解く順は参照から決まるので順序に
+    // 意味は無いが、知らせの並びが書いた順になる
+    values: json.values
+      ? Object.entries(json.values).map(([name, expression]) => ({ name, expression, pos: p0 }))
+      : undefined,
     viewport: json.viewport ? { ...json.viewport, pos: p0 } : undefined,
     lanes: json.lanes
       ? Object.fromEntries(
@@ -412,7 +859,10 @@ export function jsonToDoc(json: DragonJson): DslDocument {
  */
 export function jsonToDiagram(
   json: unknown,
-  opts?: { partsCatalog?: Record<string, CdlDiagram> },
+  // **`onNotice` も通す**。 記法経路だけに通知を付けていたため、 同じ型を受ける JSON / YAML
+  // 経路では読めない値や捨てた矢印が利用者へ届かなかった (review 指摘)。 エディタの YAML タブは
+  // ここを通る
+  opts?: { partsCatalog?: Record<string, CdlDiagram>; onNotice?: CompileToCdlOpts["onNotice"] },
 ): CdlDiagram {
   const v = validateJson(json);
   if (!v.ok) {