@cardenelabs/dragon 0.27.0 → 0.30.0

package/src/json-parser.ts

@@ -6,7 +6,7 @@
  * で確実に生成できるよう、 flat な object array を優先した shape になっている。
  *
  * 使い方 (LLM):
- *   1. `packages/dragon/schemas/diagram.json` の JSON Schema を LLM の tool schema に注入
+ *   1. `packages/dragon/src/schemas/diagram.json` の JSON Schema を LLM の tool schema に注入
  *   2. LLM が JSON を返す
  *   3. `jsonToDiagram(json)` で CdlDiagram に変換
  *   4. validation error は throw、 retry loop で LLM に修正させる
@@ -34,6 +34,8 @@ import {
   部品の組の表,
   つまみの表,
   EVENT_KINDS,
+  EVENT_TARGET_KEYS,
+  EVENT_REQUIRED_KEYS,
   type 図形の定義,
 } from "./v05/parser";
 // 図の配色 (#1553)。 記法の読み手と同じ解決を通す = 別名 (`生成り` / `青磁`) の受け方が
@@ -49,6 +51,7 @@ import type {
   EdgeHead,
   EdgeHeadFill,
   EdgeReveal,
+  RelationFocus,
   ClassRelationType,
   SequenceMessageKind,
 } from "@cardenelabs/cdl";
@@ -70,7 +73,15 @@ import type {
   DslDynShape,
 } from "./types";
 import { checkValueExpression, isValueName, valueNameIssue } from "./value-syntax";
+import { 近い名前 } from "./near-name";
+import { 書いた場所の鍵, type 書いた行の表 } from "./json-line-map";
 import { compileToCdl } from "./compile";
+import {
+  RELATIVE_DIRECTIONS,
+  findRelativeProblems,
+  type RelativeDirection,
+  type RelativePos,
+} from "./relative-pos";
 
 /**
  * LLM 向け JSON DSL の入力 shape。 YAML DSL と 1:1 対応、 top-level は flat な object。
@@ -117,8 +128,11 @@ export interface DragonJson {
    * つまみの値から決まる値 (optional、 #1391)。 記法の最上位 `formulas:` と同じ。
    *
    * 形は `{ 名前: "式" }`。 `values:` と経路が別で、式は名前を中括弧で囲わない。
+   *
+   * 名札を付ける時は `{ 名前: { expression: "式", label: "名札" } }` の組で書く (#1916)。
+   * 描画側は名札を操作部の式の名前に描く (cdl#853)。
    */
-  formulas?: Record<string, string>;
+  formulas?: Record<string, string | { expression: string; label?: string }>;
   /**
    * 押下などの出来事で動く仕掛け (optional、 #1393)。 記法の最上位 `events:` と同じ。
    *
@@ -173,8 +187,8 @@ export interface DragonJson {
       contain?: boolean;
       lifeline?: boolean;
       /**
-       * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = auto layout offset。 未指定は
-       * backward compat、 set 済は Phase 2 の applyPosOffset で lane 位置を shift する。
+       * 縦列の位置のずらし (#1971)。 配置後の縦列の左上を (x, y) だけ動かす。 記法の `offsetX` / `offsetY`
+       * と同じで、読み方は `DslLane.layoutPos` が持つ。
        */
       pos?: LayoutPos;
     }
@@ -191,6 +205,8 @@ export interface DragonJson {
   bands?: { actor: string; from: number; to: number }[];
   /** 矢印をいつ出すか (#1470)。 記法の最上位 `reveal:` と同じ */
   reveal?: EdgeReveal;
+  /** 箱に触れると関係する線だけを光らせるか (#1757)。 記法の最上位 `relations:` と同じ */
+  relations?: RelationFocus;
   /** 図の並ぶ向き (#1494)。 記法の最上位 `direction:` と同じ。 JSON は英語の語で書く */
   direction?: "vertical" | "horizontal";
   /**
@@ -205,6 +221,24 @@ export interface DragonJson {
   palette?: DslPalette;
 }
 
+/**
+ * 位置を他の要素からの相対で書く指定の、JSON 側の形 (#2039)。
+ *
+ * 記法の `位置: Web の右 200` を 3 つの欄に開いたもの。 内側の値は `RelativePos` と同じで、
+ * 向きの語も同じ 4 つ (`right` / `left` / `above` / `below`) を使う。
+ *
+ * **向きの語を並べ直さない**。 `RelativeDirection` をそのまま使うことで、本文側に向きを
+ * 足した時に JSON 側が黙って取り残される形を作らない。
+ */
+export interface JsonRelativePos {
+  /** 基準にする相手の名前。 `actors:` に書かれた名前をそのまま書く */
+  anchor: string;
+  /** 基準からどちら側に置くか */
+  dir: RelativeDirection;
+  /** 相手との間隔。 書かなければ `RELATIVE_GAP_DEFAULT` */
+  gap?: number;
+}
+
 export interface JsonActor {
   name: string;
   /**
@@ -233,8 +267,9 @@ export interface JsonActor {
   renderOffsetX?: number | string;
   renderOffsetY?: number | string;
   /**
-   * CAR-1657 unified syntax = 既存 NodeKind (28 個) に加えて parts identifier (arc-gauge 等) を
-   * accept する。 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
+   * CAR-1657 unified syntax = 既存 NodeKind (一覧は `v05/parser.ts` の `NODE_KIND_VALID`) に
+   * 加えて parts identifier (arc-gauge 等) を accept する。
+   * 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
    * LLM structured output の typing 制約を緩めるため union に string 追加。
    * `string & {}` = NodeKind の候補を IDE 補完で提示しつつ任意 string も許容する idiom。
    * 素の `NodeKind | string` は no-redundant-type-constituents に抵触し補完も潰れる (#865)。
@@ -256,10 +291,21 @@ export interface JsonActor {
   initial?: boolean;
   final?: boolean;
   /**
-   * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = auto layout offset。 未指定は
-   * backward compat、 set 済は Phase 2 の applyPosOffset で actor 由来 lane / node の位置を shift。
+   * 箱の位置のずらし (#1971)。 配置後の箱の中心を (x, y) だけ動かす。 記法の `offsetX` / `offsetY`
+   * と同じで、読み方は `DslActor.layoutPos` が持つ。
    */
   pos?: LayoutPos;
+  /**
+   * 位置を他の要素からの相対で書く指定 (#2039)。 記法の `位置: Web の右 200` と同じ。
+   *
+   * 記法は 1 本の文字列に「誰の」「どちら側に」「どれだけ離して」 を詰めるが、JSON では
+   * 3 つの欄に分ける。 文字列を組み立てて渡す形にすると、書く側が記法の並び順と区切りを
+   * 覚える必要が出る = JSON を書くのは主に LLM で、読み取りの規則は欄の名前で示す方が短い。
+   *
+   * 組み立ての段階で基準の実座標から `posX` / `posY` に直すため、解決した後は座標を直接
+   * 書いた時と同じ経路を通る。 `pos` (配置後のずらし幅) とは別の欄。
+   */
+  posRel?: JsonRelativePos;
   /**
    * CAR-1657 parts state override (kind = parts identifier 時のみ有効)。
    * LLM JSON DSL では nested 明示 = `{ "state": { "v": 50 } }` が natural、 human 側の
@@ -312,12 +358,6 @@ export interface JsonActor {
   posY?: number;
   posW?: number;
   posH?: number;
-  /**
-   * 箱の中の要素ごとに位置と大きさを固定する (#1294)。 記法の `nodes:` と同じ。
-   *
-   * key は箱が作る要素の名前 (`header` / `footer` / `spacer` / `s0` 等)。
-   */
-  nodes?: Record<string, JsonActorNodeOverride>;
   /**
    * 見本を何倍で描くか (#1294)。 記法の `scale:` / `倍率:` と同じ。
    *
@@ -325,6 +365,17 @@ export interface JsonActor {
    * 読めない項目名として知らせる)。
    */
   scale?: number;
+  /**
+   * 見本が持つ段を使うか (#2125)。 記法の `{ kind: wave-gauge, phase: false }` と同じ。
+   *
+   * 既定 (書かない) は見本の段を書いた段と番号ごとに並べて再生する。 `false` を書くと
+   * 見本の段の中身 (点灯と値の変化) を空にし、値は書いた段だけが動かす。
+   *
+   * 見本 (parts) にしか効かない。 中身は状態の上書き (`state`) に `phase` として入る =
+   * `"state": { "phase": false }` と同じ所へ届く。 記法が中括弧の中に 1 つの名前として
+   * 書ける以上、JSON でも同じ名前で書けるようにする (入口で書き方が分かれない)。
+   */
+  phase?: boolean;
   /** 行頭の印 (#1466)。 行と対で読む。 語の意味は図の種類が決める */
   marks?: string[];
 }
@@ -335,14 +386,6 @@ export interface JsonAxes {
   y?: { bottom?: string; top?: string };
 }
 
-/** 箱の中の要素 1 つ分の位置と大きさ (#1294)。 記法の `nodes: { header: { ... } }` と同じ */
-export interface JsonActorNodeOverride {
-  posX?: number;
-  posY?: number;
-  posW?: number;
-  posH?: number;
-}
-
 export interface JsonStep {
   from: string;
   to: string;
@@ -353,7 +396,7 @@ export interface JsonStep {
   /**
    * 矢印の先の形 (#1462)。 記法の `{ head: triangle }` と同じ。
    *
-   * 三角 (継ぐ) / 菱 (持つ) / 開いた矢 (使う) / 鳥の足 (多)。
+   * 三角 (継承・実装) / 菱 (集約・コンポジション) / 開いた矢 (関連・依存) / 鳥の足 (多)。
    * 書かなければ従来どおり塗った三角になる。
    */
   head?: EdgeHead;
@@ -361,6 +404,8 @@ export interface JsonStep {
   tailHead?: EdgeHead;
   headFill?: EdgeHeadFill;
   tailHeadFill?: EdgeHeadFill;
+  /** クラス図の出どころ側の多重度 (#1771)。 記法の `{ tailSub: "1" }` と同じ */
+  tailSub?: string;
   /**
    * 辺の役目 (cdl#618)。 記法の `{ role: main }` と同じ。
    *
@@ -394,10 +439,15 @@ export interface JsonStep {
   /** 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 する。
+   * 矢印の位置のずらし (#1971)。 名前のずらし (`labelOffsetX` / `labelOffsetY`) に足して名前を動かす。
    */
   pos?: LayoutPos;
+  /**
+   * 部品の端で矢印を繋ぐ部品の中の要素の id (#1979)。 記法の `{ fromPartNode: rC }` / `{ toPartNode: gC }` と同じ。
+   * 要素を 1 つだけ持つ部品は書かなくてもその要素に繋ぐ
+   */
+  fromPartNode?: string;
+  toPartNode?: string;
 }
 
 export interface JsonPhase {
@@ -452,11 +502,13 @@ export interface JsonDslError {
  * 受け付ける種類 (`kind`)。 **記法側と同じ集合を使う** (`v05/parser.ts` の `NODE_KIND_VALID`)。
  *
  * ここに無い値は見本 (parts) の名前とみなし、`partId` へ退避して箱を `actor` に倒す
- * (CAR-1657 の unified syntax)。 つまりこの集合が小さいほど、**書いた種類が黙って消える**。
+ * (CAR-1657 の unified syntax)。 つまりこの集合が小さいほど、**書いた種類が箱の見た目に効かなくなる**。
+ * 部品を持つ一覧を渡した組み立てでは一覧に無い名前を知らせる (`part-not-found`、#2113) が、
+ * 一覧を渡さない組み立てと部品を持たない一覧の組み立てでは `console.warn` にしか残らない。
  *
  * 以前はここに一覧を写していたため、記法に種類が増えても JSON 経路が古い一覧のまま
  * 見本の名前として扱った (実測 = 記法が知る 108 種のうち 77 種が該当、`shape-*` は全滅)。
- * 見本帳に無い名前は `console.warn` にしか残らず `onNotice` を呼ばないため、
+ * 当時はカタログに無い名前が `console.warn` にしか残らず `onNotice` を呼ばなかったため、
  * 画面には何も出ないまま `actor` の箱が描かれていた (#1293)。
  *
  * 型が 2 箇所に散らばると、必ずどちらかが古くなる。 `VALID_PRESETS` (図種) と同じ扱いにする。
@@ -511,6 +563,8 @@ export const ACCEPTED_KEYS = {
     "bands",
     // 矢印をいつ出すか (#1470)
     "reveal",
+    // 箱に触れると関係する線だけを光らせるか (#1757)
+    "relations",
     // 図の並ぶ向き (#1494)
     "direction",
     // 図の配色 (#1553)
@@ -539,7 +593,6 @@ export const ACCEPTED_KEYS = {
     "posY",
     "posW",
     "posH",
-    "nodes",
     "scale",
     "state",
     "pos",
@@ -557,6 +610,10 @@ export const ACCEPTED_KEYS = {
     "renderOffsetY",
     // 行頭の印 (#1466)。 行ごとに 1 つ、図の種類ごとの語で書く
     "marks",
+    // 位置を他の要素からの相対で書く指定 (#2039)
+    "posRel",
+    // 見本が持つ段を使うか (#2125)
+    "phase",
   ],
   step: [
     "from",
@@ -571,6 +628,8 @@ export const ACCEPTED_KEYS = {
     "tailHead",
     "headFill",
     "tailHeadFill",
+    // クラス図の出どころ側の多重度 (#1771)
+    "tailSub",
     "relation",
     // 辺の役目と名前の下地 (cdl#618)
     "role",
@@ -588,16 +647,20 @@ export const ACCEPTED_KEYS = {
     "labelOffsetY",
     "overlay",
     "pos",
+    // 部品の端で繋ぐ要素の id (#1979)
+    "fromPartNode",
+    "toPartNode",
   ],
   phase: ["step", "duration", "focus", "body", "badge", "tween", "set", "draw", "drawRatio"],
   viewport: ["width", "height", "scale", "laneWidth", "gap", "laneGap", "nodeGap", "labelMargin"],
   lane: ["x", "width", "label", "contain", "lifeline", "pos"],
   group: ["label", "lanes"],
-  actorNode: ["posX", "posY", "posW", "posH"],
   axes: ["x", "y"],
   axesX: ["left", "right"],
   axesY: ["bottom", "top"],
   layoutPos: ["x", "y"],
+  // 位置を他の要素からの相対で書く指定 (#2039)。 間隔は書かなくてよい
+  posRel: ["anchor", "dir", "gap"],
 } as const satisfies Record<string, readonly string[]>;
 
 /** 受ける項目を持つ階層の名前 */
@@ -639,6 +702,8 @@ export type 欄の型 =
   | "線種"
   | "辺"
   | "端の形"
+  // 相対で置く時の向き (#2039)。 書けば必ず要る = 向きが無いとどちら側か決まらない
+  | "必須の向き"
   | "色か色番号"
   | "描くもの"
   | "必須の図種"
@@ -674,6 +739,8 @@ export const 欄の型表 = {
     bands: "並び",
     // 矢印をいつ出すか (#1470)
     reveal: "非空の文字列",
+    // 箱に触れると関係する線だけを光らせるか (#1757)
+    relations: "非空の文字列",
     // 図の並ぶ向き (#1494)
     direction: "非空の文字列",
     // 図の配色 (#1553)
@@ -701,7 +768,6 @@ export const 欄の型表 = {
     posY: "数",
     posW: "数",
     posH: "数",
-    nodes: "object",
     scale: "数",
     state: "object",
     pos: "object",
@@ -719,6 +785,10 @@ export const 欄の型表 = {
     renderOffsetY: "数か文字列",
     // 行頭の印 (#1466)
     marks: "文字列の並び",
+    // 相対で置く指定 (#2039)。 中身の形は `validateRelativePos` が見る
+    posRel: "object",
+    // 見本が持つ段を使うか (#2125)
+    phase: "真偽",
   },
   step: {
     from: "必須の文字列",
@@ -732,6 +802,8 @@ export const 欄の型表 = {
     tailHead: "端の形",
     headFill: "非空の文字列",
     tailHeadFill: "非空の文字列",
+    // クラス図の出どころ側の多重度 (#1771)
+    tailSub: "文字列",
     relation: "非空の文字列",
     // 辺の役目と名前の下地 (cdl#618)
     role: "非空の文字列",
@@ -749,6 +821,9 @@ export const 欄の型表 = {
     labelOffsetY: "数",
     overlay: "真偽",
     pos: "object",
+    // 部品の端で繋ぐ要素の id (#1979)。 空の id は要素を指せないので受けない
+    fromPartNode: "非空の文字列",
+    toPartNode: "非空の文字列",
   },
   phase: {
     step: "必須の非空文字列",
@@ -780,12 +855,13 @@ export const 欄の型表 = {
     pos: "object",
   },
   group: { label: "文字列", lanes: "文字列の並び" },
-  actorNode: { posX: "数", posY: "数", posW: "数", posH: "数" },
   axes: { x: "object", y: "object" },
   axesX: { left: "文字列", right: "文字列" },
   axesY: { bottom: "文字列", top: "文字列" },
   // 位置は書けば x と y の両方が要る。 片方だけでは寄せ幅が決まらない
   layoutPos: { x: "必須の数", y: "必須の数" },
+  // 相対で置く指定 (#2039)。 相手と向きは必ず要り、間隔は書かなければ既定で置く
+  posRel: { anchor: "必須の非空文字列", dir: "必須の向き", gap: "数" },
 } as const satisfies {
   [層 in 階層]: { [欄 in (typeof ACCEPTED_KEYS)[層][number]]: 欄の型 };
 };
@@ -830,6 +906,8 @@ function JSONの色名か(v: string): boolean {
 export const 見本にしか効かない欄 = [
   "state",
   "scale",
+  // 見本が持つ段を使うか (#2125)。 普通の箱は自分の段を持たないので効かない
+  "phase",
 ] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
 
 /**
@@ -988,6 +1066,17 @@ function 値を検査(
         });
       }
       return;
+    case "必須の向き":
+      // 受ける語は記法と同じ一覧を見る (`RELATIVE_DIRECTIONS`)。 写すと向きが増えた時に
+      // 片方だけ古くなる
+      if (typeof v !== "string" || !(RELATIVE_DIRECTIONS as readonly string[]).includes(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${RELATIVE_DIRECTIONS.join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : `got ${v === undefined ? "nothing" : typeof v}`,
+        });
+      }
+      return;
     case "端の形":
       if (v === undefined) return;
       // 受ける語は記法と同じ一覧を見る (`EDGE_HEAD_VALUES`)。 写すと描画側が形を増やした時に
@@ -1077,48 +1166,6 @@ function 表で検査(
   }
 }
 
-/**
- * 綴り違いの候補を返す (#1295)。
- *
- * 「知らない項目です」 だけだと、`animations` と書いた人は正しい綴りを探しに行く必要がある。
- * 1 文字の違い (足りない / 多い / 入れ替わり / 別の字) までを候補とする。
- *
- * 遠い名前は勧めない。 無関係な項目名を勧めると、書いた人がそちらへ直して二度手間になる。
- */
-function 近い項目名(key: string, 候補: readonly string[]): string | undefined {
-  const 小文字 = key.toLowerCase();
-  let 最短: { 名: string; 距離: number } | undefined;
-  for (const c of 候補) {
-    const d = 編集距離(小文字, c.toLowerCase(), 2);
-    if (d <= 2 && (最短 === undefined || d < 最短.距離)) 最短 = { 名: c, 距離: d };
-  }
-  return 最短?.名;
-}
-
-/**
- * 2 つの語の編集距離 (上限付き)。
- *
- * 上限を持つのは、長い語どうしで表を全部埋めないため。 上限を超えた時点で打ち切る。
- */
-function 編集距離(a: string, b: string, 上限: number): number {
-  if (Math.abs(a.length - b.length) > 上限) return 上限 + 1;
-  let 前 = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i += 1) {
-    const 今: number[] = [i];
-    let 行の最小 = i;
-    for (let j = 1; j <= b.length; j += 1) {
-      const 費用 = a[i - 1] === b[j - 1] ? 0 : 1;
-      const v = Math.min(今[j - 1]! + 1, 前[j]! + 1, 前[j - 1]! + 費用);
-      今.push(v);
-      if (v < 行の最小) 行の最小 = v;
-    }
-    // その行の最小が上限を超えたら、以降どう進んでも上限以下にはならない
-    if (行の最小 > 上限) return 上限 + 1;
-    前 = 今;
-  }
-  return 前[b.length]!;
-}
-
 /**
  * 知らない項目を誤りとして積む (#1295)。
  *
@@ -1128,9 +1175,9 @@ function 編集距離(a: string, b: string, 上限: number): number {
 function checkUnknownKeys(v: unknown, 層: 階層, path: string, errors: JsonDslError[]): void {
   if (!v || typeof v !== "object" || Array.isArray(v)) return;
   const 受ける = ACCEPTED_KEYS[層] as readonly string[];
-  for (const key of Object.keys(v as Record<string, unknown>)) {
+  for (const key of Object.keys(v)) {
     if (受ける.includes(key)) continue;
-    const 候補 = 近い項目名(key, 受ける);
+    const 候補 = 近い名前(key, 受ける);
     errors.push({
       path: `${path}.${key}`,
       message: `unknown key "${key}"`,
@@ -1139,13 +1186,9 @@ function checkUnknownKeys(v: unknown, 層: 階層, path: string, errors: JsonDsl
   }
 }
 
-/**
- * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
- * fail-fast ではなく全 error 収集して返す (LLM に一括で修正させるため)。
- */
 /**
  * CAR-1693 Phase 1: DSL 表面 `pos: {x, y}` の型 check helper。 finite number pair を必須にし、
- * `NaN` / `Infinity` / non-number は reject する (Phase 2 の applyPosOffset で数値演算するため)。
+ * `NaN` / `Infinity` / non-number は reject する (組み立ての出口 `applyLayoutOffsets` が配置後の位置に足すため)。
  */
 function validateLayoutPos(v: unknown, path: string, errors: JsonDslError[]): void {
   if (v === undefined) return;
@@ -1158,6 +1201,77 @@ function validateLayoutPos(v: unknown, path: string, errors: JsonDslError[]): vo
   表で検査(p, "layoutPos", path, "pos", errors);
 }
 
+/**
+ * 相対で置く指定の形を見る (#2039)。
+ *
+ * 相手の名前が実在するかはここでは見ない。 組み立て側 (`resolveRelativeDoc`) が figure 全体を
+ * 組んだ後に照合し、いない相手を指した時は知らせを出す。 入口ごとに別の場所で判定すると、
+ * 本文で書いた時と JSON で書いた時で返るものが変わる。
+ */
+function validateRelativePos(v: unknown, path: string, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({ path, message: "posRel must be an object with anchor and dir" });
+    return;
+  }
+  const p = v as Record<string, unknown>;
+  checkUnknownKeys(p, "posRel", path, errors);
+  表で検査(p, "posRel", path, "posRel", errors);
+}
+
+/**
+ * 図全体として相対の指定が解けるかを見る (#2039)。
+ *
+ * 判定は `relative-pos.ts` の `findRelativeProblems` が持つ。 記法側も同じ判定を呼ぶので、
+ * 同じ書き方が入口によって通ったり通らなかったりしない。
+ *
+ * 誤りの文だけをここで作る = 記法側は行番号を、こちらは欄の場所を添えるため。
+ */
+function validateRelativeAnchors(actors: readonly unknown[], errors: JsonDslError[]): void {
+  const items: Array<{ name: string; rel?: RelativePos }> = [];
+  const 場所 = new Map<string, number>();
+  actors.forEach((a, i) => {
+    if (!a || typeof a !== "object" || Array.isArray(a)) return;
+    const o = a as Record<string, unknown>;
+    if (typeof o.name !== "string") return;
+    const rel = o.posRel;
+    // 形の誤りは `validateRelativePos` が既に返している。 ここは形の整った指定だけを見る
+    const 整った =
+      rel !== null &&
+      typeof rel === "object" &&
+      !Array.isArray(rel) &&
+      typeof (rel as Record<string, unknown>).anchor === "string" &&
+      typeof (rel as Record<string, unknown>).dir === "string";
+    items.push({ name: o.name, rel: 整った ? (rel as RelativePos) : undefined });
+    if (!場所.has(o.name)) 場所.set(o.name, i);
+  });
+
+  const named = items.map((i) => i.name);
+  for (const p of findRelativeProblems(items)) {
+    const i = 場所.get(p.name) ?? 0;
+    errors.push({
+      path: `$.actors[${i}].posRel`,
+      ...(p.kind === "self"
+        ? {
+            message: `posRel.anchor must not be the actor itself: "${p.name}"`,
+            hint: "別の登場人物の名前を書く",
+          }
+        : p.kind === "missing-anchor"
+          ? {
+              message: `posRel.anchor must name an actor: "${p.anchor ?? ""}"`,
+              hint:
+                named.length > 0
+                  ? `actors に書かれている名前 = ${named.join(", ")}`
+                  : "actors に基準にする登場人物を書く",
+            }
+          : {
+              message: `posRel.anchor must not form a cycle: "${p.name}"`,
+              hint: "どれか 1 つは posX / posY か自動配置にする",
+            }),
+    });
+  }
+}
+
 /**
  * 見本 (parts) の名前として扱う値かどうか (#1294)。
  *
@@ -1169,28 +1283,6 @@ function 見本の名前か(kind: unknown): boolean {
   return kind !== "actor" && !VALID_KIND_SET.has(kind);
 }
 
-/** 箱の中の要素ごとの位置と大きさを見る (#1294) */
-function validateActorNodes(v: unknown, path: string, errors: JsonDslError[]): void {
-  if (v === undefined) return;
-  if (!v || typeof v !== "object" || Array.isArray(v)) {
-    errors.push({
-      path,
-      message: "actor.nodes must be a plain object of name -> { posX, posY, posW, posH }",
-    });
-    return;
-  }
-  for (const [name, o] of Object.entries(v as Record<string, unknown>)) {
-    const nodePath = `${path}.${name}`;
-    if (!o || typeof o !== "object" || Array.isArray(o)) {
-      errors.push({ path: nodePath, message: "actor.nodes entry must be a plain object" });
-      continue;
-    }
-    const n = o as Record<string, unknown>;
-    checkUnknownKeys(n, "actorNode", nodePath, errors);
-    表で検査(n, "actorNode", nodePath, `nodes.${name}`, errors);
-  }
-}
-
 /**
  * 図全体の大きさと間隔を見る (#1295)。
  *
@@ -1209,14 +1301,69 @@ function validateViewport(v: unknown, errors: JsonDslError[]): void {
 }
 
 /**
- * 鍵を利用者が決める入れ物 (縦列 / 群) を見る (#1304)。
+ * 選択肢の組が受ける項目。 どれも必ず書く (#2258)。
  *
- * `lanes` / `groups` は id を鍵に持つため、鍵そのものは縛れない。 縛れるのは
- * 「入れ物が plain object か」 と「各 id の中身の項目名と値の型」 の 2 つ。
+ * **判定と知らせが同じ集合を読む**。 別々に並べていた間、判定に項目を足しても
+ * 知らせは古い一覧を教え続ける形だった。
+ */
+const 選択肢の項目 = ["value", "label"] as const;
+
+/**
+ * 選択肢の並び (`["green", { "value": "red", "label": "失敗" }]`) を要素ごとに検査する (#1920)。
  *
- * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
- * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
+ * 要素は文字列か、`value` と `label` の 2 項目を持つ組。 誤りは要素の場所 (`options[1].label`) で
+ * 返す = 並び全体の型違いとして返すと、どの組のどの項目を直せばよいかが読み手に届かない。
  */
+function 選択肢の並びを検査する(値: unknown, path: string, errors: JsonDslError[]): void {
+  if (!Array.isArray(値)) {
+    errors.push({
+      path,
+      message: "options must be 選択肢の並び",
+      hint: `got ${値 === null ? "null" : typeof 値}`,
+    });
+    return;
+  }
+  値.forEach((x, i) => {
+    const here = `${path}[${i}]`;
+    if (typeof x === "string") return;
+    if (typeof x !== "object" || x === null || Array.isArray(x)) {
+      errors.push({
+        path: here,
+        message: "option must be a string or { value, label }",
+        hint: `got ${Array.isArray(x) ? "array" : x === null ? "null" : typeof x}`,
+      });
+      return;
+    }
+    const 組 = x as Record<string, unknown>;
+    for (const k of Object.keys(組)) {
+      if ((選択肢の項目 as readonly string[]).includes(k)) continue;
+      errors.push({
+        path: `${here}.${k}`,
+        message: `unknown key "${k}"`,
+        hint: `使える項目 = ${選択肢の項目.join(", ")}`,
+      });
+    }
+    for (const k of 選択肢の項目) {
+      const v = 組[k];
+      if (v === undefined) {
+        errors.push({
+          path: `${here}.${k}`,
+          message: `${k} is required`,
+          hint: `必須の項目 = ${選択肢の項目.join(", ")}`,
+        });
+      } else if (typeof v !== "string") {
+        errors.push({ path: `${here}.${k}`, message: `${k} must be 文字列`, hint: `got ${v === null ? "null" : typeof v}` });
+      } else if (v === "") {
+        errors.push({
+          path: `${here}.${k}`,
+          message: `${k} must not be empty`,
+          hint: k === "label" ? "名前を書かないなら文字列だけを並べる" : "値を 1 文字以上書く",
+        });
+      }
+    }
+  });
+}
+
 /**
  * 図形と部品の中身を、記法と **同じ表** で検査する (#1374)。
  *
@@ -1258,6 +1405,10 @@ function 表で中身を検査する(
       });
       continue;
     }
+    if (形 === "選択肢の並び") {
+      選択肢の並びを検査する(値, `${path}.${欄}`, errors);
+      continue;
+    }
     const 型が合う =
       形 === "数"
         ? typeof 値 === "number" && Number.isFinite(値)
@@ -1305,18 +1456,30 @@ function 表で中身を検査する(
   }
 }
 
+/** 帯に書く相手の項目。 値が文字列で、他の 2 つと型が違う */
+const 帯の相手の項目 = ["actor"] as const;
+/** 帯に書く段の項目。 値が 0 以上の整数 */
+const 帯の段の項目 = ["from", "to"] as const;
 /**
- * 値を見せる部品の並びを検査する (#1374)。
+ * 帯が受ける項目。 判定と知らせの両方がここから作る (#2258)。
  *
- * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
- * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `readouts: 1` が
- * 素通りする。
+ * 公開 schema の `$.bands` も同じ 3 語を閉じた集合として宣言しており、
+ * `closed-level-coverage.test.ts` が両者の一致を見る。
  */
+export const 帯の項目: readonly string[] = [...帯の相手の項目, ...帯の段の項目];
+
 /**
  * 順序図の帯の並びを検査する (#1466)。
  *
  * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
  * 委ねる作りなので、ここで見ないと `bands: 1` が素通りする。
+ *
+ * ## 知らない項目も見る (#2262)
+ *
+ * 書いてある 3 つの型だけを見て、**知らない項目があるかを確かめていなかった**。
+ * 公開 schema は `$.bands` を閉じた階層として宣言しているので、
+ * schema を信じて書いた入力がこちらでは通り、schema 検証器では落ちる状態だった。
+ * 公開 schema が閉じた階層のうち、素通りしていたのはここだけだった。
  */
 function validateBands(v: unknown, errors: JsonDslError[]): void {
   if (v === undefined) return;
@@ -1335,17 +1498,34 @@ function validateBands(v: unknown, errors: JsonDslError[]): void {
       return;
     }
     const o = b as Record<string, unknown>;
-    if (typeof o.actor !== "string" || o.actor === "") {
-      errors.push({ path: `${path}.actor`, message: "band.actor must be a non-empty string" });
+    for (const k of Object.keys(o)) {
+      if (帯の項目.includes(k)) continue;
+      errors.push({
+        path: `${path}.${k}`,
+        message: `unknown key "${k}"`,
+        hint: `使える項目 = ${帯の項目.join(", ")}`,
+      });
     }
-    for (const k of ["from", "to"] as const) {
-      if (typeof o[k] !== "number" || !Number.isInteger(o[k]) || (o[k] as number) < 0) {
+    for (const k of 帯の相手の項目) {
+      if (typeof o[k] !== "string" || o[k] === "") {
+        errors.push({ path: `${path}.${k}`, message: `band.${k} must be a non-empty string` });
+      }
+    }
+    for (const k of 帯の段の項目) {
+      if (typeof o[k] !== "number" || !Number.isInteger(o[k]) || o[k] < 0) {
         errors.push({ path: `${path}.${k}`, message: `band.${k} must be a non-negative integer` });
       }
     }
   });
 }
 
+/**
+ * 値を見せる部品の並びを検査する (#1374)。
+ *
+ * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
+ * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `readouts: 1` が
+ * 素通りする。
+ */
 function validateReadouts(v: unknown, errors: JsonDslError[]): void {
   if (v === undefined) return;
   if (!Array.isArray(v)) {
@@ -1478,12 +1658,15 @@ function validateFormulas(v: unknown, inputs: unknown, errors: JsonDslError[]):
     }
   }
   const 先に書かれた式 = new Set<string>();
-  for (const [名前, 式] of Object.entries(v as Record<string, unknown>)) {
+  for (const [名前, 値] of Object.entries(v as Record<string, unknown>)) {
     const path = `$.formulas.${名前}`;
     if (!isValueName(名前)) {
       errors.push({ path, ...valueNameIssue(名前) });
       continue;
     }
+    const 検査結果 = 式の組を検査する(値, path, errors);
+    if (!検査結果.読めた) continue;
+    const 式 = 検査結果.値;
     if (typeof 式 !== "string" || 式.trim() === "") {
       errors.push({
         path,
@@ -1525,6 +1708,60 @@ function validateFormulas(v: unknown, inputs: unknown, errors: JsonDslError[]):
   }
 }
 
+/**
+ * 式の組を検査した結果 (#1916 / #2006)。
+ *
+ * **読めたかどうかを別の欄に持つ**。 値そのものに合図を混ぜると、`{ a: null }` の `null` が
+ * 合図と区別が付かず、呼び手が「組の誤りは知らせ済み」 と読んで何も知らせずに通してしまう (実測)。
+ *
+ * 印 (`unique symbol`) を値に混ぜる形も採らない。 返す型が `unknown` を含むと印が飲み込まれ、
+ * 呼び手は型で見分けられないまま等値比較に頼ることになる。
+ */
+type 式の検査結果 = { readonly 読めた: true; readonly 値: unknown } | { readonly 読めた: false };
+
+/**
+ * 式の組が受ける項目 (#2258)。 判定と知らせが同じ集合を読む。
+ */
+const 式の組の項目 = ["expression", "label"] as const;
+
+/**
+ * 式の値が組の形 (`{ expression, label }`) なら組を検査し、式の文字列を返す (#1916)。
+ *
+ * 文字列やそれ以外の形は **そのまま返す** = 式の文字列の検査は呼び手が文字列の形と同じ経路で行う。
+ * 組に誤りがあれば知らせて `読めた: false` を返す。
+ */
+function 式の組を検査する(値: unknown, path: string, errors: JsonDslError[]): 式の検査結果 {
+  if (!値 || typeof 値 !== "object" || Array.isArray(値)) return { 読めた: true, 値 };
+  const 組 = 値 as Record<string, unknown>;
+  let 読めた = true;
+  for (const 鍵 of Object.keys(組)) {
+    if ((式の組の項目 as readonly string[]).includes(鍵)) continue;
+    読めた = false;
+    errors.push({
+      path: `${path}.${鍵}`,
+      message: `unknown formula field: ${鍵}`,
+      hint: `使える項目 = ${式の組の項目.join(", ")}`,
+    });
+  }
+  if (typeof 組.expression !== "string" || 組.expression.trim() === "") {
+    読めた = false;
+    errors.push({
+      path: `${path}.expression`,
+      message: "expression must be a non-empty expression string",
+      hint: `got ${組.expression === undefined ? "nothing" : JSON.stringify(組.expression)}`,
+    });
+  }
+  if (組.label !== undefined && (typeof 組.label !== "string" || 組.label.trim() === "")) {
+    読めた = false;
+    errors.push({
+      path: `${path}.label`,
+      message: "label must be a non-empty string",
+      hint: "名札を付けないなら label を書かない",
+    });
+  }
+  return 読めた ? { 読めた: true, 値: 組.expression } : { 読めた: false };
+}
+
 /**
  * 押下などの出来事で動く仕掛けを検査する (#1393)。
  *
@@ -1541,7 +1778,11 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
     });
     return;
   }
-  const 相手の鍵 = ["box", "lane", "arrow", "diagram"];
+  // 相手の指し方は記法の側が 1 か所で決める (#2256)。 同じ 4 語をここにも並べていた間、
+  // 1:1 を名乗りながら受ける項目が両側で別々に決まっていた。
+  // 必ず書く 2 つも同じ定数から取る (#2258) = 知らせが判定と別に並べる形をやめる
+  const 相手の鍵: readonly string[] = EVENT_TARGET_KEYS;
+  const 出来事の項目: readonly string[] = [...EVENT_REQUIRED_KEYS, ...EVENT_TARGET_KEYS];
   v.forEach((e, i) => {
     const path = `$.events[${i}]`;
     if (!e || typeof e !== "object" || Array.isArray(e)) {
@@ -1550,11 +1791,11 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
     }
     const o = e as Record<string, unknown>;
     for (const k of Object.keys(o)) {
-      if (k === "on" || k === "handler" || 相手の鍵.includes(k)) continue;
+      if (出来事の項目.includes(k)) continue;
       errors.push({
         path: `${path}.${k}`,
         message: `unknown key "${k}"`,
-        hint: `使える項目 = on, handler, ${相手の鍵.join(", ")}`,
+        hint: `使える項目 = ${出来事の項目.join(", ")}`,
       });
     }
     if (typeof o.on !== "string" || !(EVENT_KINDS as readonly string[]).includes(o.on)) {
@@ -1592,7 +1833,7 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
       }
       return;
     }
-    if (typeof o[鍵] !== "string" || (o[鍵] as string).trim() === "") {
+    if (typeof o[鍵] !== "string" || o[鍵].trim() === "") {
       errors.push({ path: `${path}.${鍵}`, message: `${鍵} must be a non-empty string` });
       return;
     }
@@ -1609,6 +1850,16 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
   });
 }
 
+/**
+ * 巻き上げに応じて進む値が受ける項目 (#2258)。
+ *
+ * **数を書く項目と文字を書く項目を分けて持つ** = 受け方が違うので判定が分かれるが、
+ * 知らせは 2 つを繋いで 1 つの一覧として出す。 別々に並べていた間、判定が 3 語で
+ * 知らせが 4 語という食い違いが同じ関数の中にあった。
+ */
+const 送りの数の項目 = ["start", "end", "scrub"] as const;
+const 送りの文の項目 = ["label"] as const;
+
 /**
  * 巻き上げに応じて進む値を検査する (#1393)。
  *
@@ -1658,17 +1909,17 @@ function validateScrolls(
       continue;
     }
     for (const [k, x] of Object.entries(spec as Record<string, unknown>)) {
-      if (k === "label") {
+      if ((送りの文の項目 as readonly string[]).includes(k)) {
         if (typeof x !== "string") {
-          errors.push({ path: `${path}.label`, message: "label must be a string" });
+          errors.push({ path: `${path}.${k}`, message: `${k} must be a string` });
         }
         continue;
       }
-      if (k !== "start" && k !== "end" && k !== "scrub") {
+      if (!(送りの数の項目 as readonly string[]).includes(k)) {
         errors.push({
           path: `${path}.${k}`,
           message: `unknown key "${k}"`,
-          hint: "使える項目 = start, end, scrub, label",
+          hint: `使える項目 = ${[...送りの数の項目, ...送りの文の項目].join(", ")}`,
         });
         continue;
       }
@@ -1703,6 +1954,15 @@ function validateActorShape(v: unknown, path: string, errors: JsonDslError[]): v
   表で中身を検査する(v as Record<string, unknown>, 図形の表, path, "shape", errors);
 }
 
+/**
+ * 鍵を利用者が決める入れ物 (縦列 / 群) を見る (#1304)。
+ *
+ * `lanes` / `groups` は id を鍵に持つため、鍵そのものは縛れない。 縛れるのは
+ * 「入れ物が plain object か」 と「各 id の中身の項目名と値の型」 の 2 つ。
+ *
+ * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
+ * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
+ */
 function validateIdMap(
   v: unknown,
   欄: "lanes" | "groups",
@@ -1927,7 +2187,7 @@ export function 素のデータに写す(
     // **名前も数に入れる** (Round 5 の指摘)。 値を読む前に名前の一覧を作るため、 値だけを
     // 数えると「名前が 20,000 個ある段を 63 回降りる」 形で 126 万個を並べられる = 上限を
     // 見る前に資源を使い切れる
-    const 名前の並び = Object.keys(v as Record<string, unknown>);
+    const 名前の並び = Object.keys(v);
     項目数 += 名前の並び.length;
     if (項目数 > 写しの最大の項目数) {
       throw new 写せない(path, `項目が多すぎる (上限 ${写しの最大の項目数})`);
@@ -1984,6 +2244,10 @@ export function 素のデータに写す(
   }
 }
 
+/**
+ * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
+ * fail-fast ではなく全 error 収集して返す (LLM に一括で修正させるため)。
+ */
 function validateJson(
   json: unknown,
 ): { ok: true; data: DragonJson } | { ok: false; errors: JsonDslError[] } {
@@ -2059,6 +2323,7 @@ function validateJson(
       const 代わりに使う欄: Record<(typeof 見本にしか効かない欄)[number], string> = {
         state: "箱の見た目を変えるなら tone / color を使う",
         scale: "大きさを変えるなら posW / posH を使う",
+        phase: "普通の箱は自分の段を持たない。 動かす段は animation に書く",
       };
       if (!見本か) {
         for (const 欄 of 見本にしか効かない欄) {
@@ -2082,9 +2347,8 @@ function validateJson(
           });
         }
       }
-      validateActorNodes(ao.nodes, `$.actors[${i}].nodes`, errors);
-      // codex-review MAJOR fix = state override は plain object + 値は primitive (number / string / boolean) 限定、
-      // `{ v: {} }` 等 nested object や null が流入すると CdlState.initial に不正な型が入り compile 崩れる。
+      // 値の上書き (`state`) は素の object に限り、中の値も数 / 文字 / 真偽のいずれかに限る。
+      // `{ v: {} }` のような入れ子や null を通すと、値の初期値に扱えない型が入って組み立てが崩れる。
       if (ao.state !== undefined) {
         if (!ao.state || typeof ao.state !== "object" || Array.isArray(ao.state)) {
           errors.push({
@@ -2105,7 +2369,11 @@ function validateJson(
       }
       // CAR-1693 Phase 1: actor DSL 表面 pos の validation
       validateLayoutPos(ao.pos, `$.actors[${i}].pos`, errors);
+      // 相対で置く指定 (#2039)
+      validateRelativePos(ao.posRel, `$.actors[${i}].posRel`, errors);
     });
+    // 解けない相対の指定 (#2039)。 欄ごとの形を見た後に、図全体として解けるかを見る
+    validateRelativeAnchors(j.actors, errors);
   }
   if (!Array.isArray(j.flow)) {
     errors.push({ path: "$.flow", message: "flow must be an array" });
@@ -2210,7 +2478,7 @@ function validatePhaseMotion(po: Record<string, unknown>, i: number, errors: Jso
         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)) {
+        } else if (t === "number" && !Number.isFinite(value)) {
           errors.push({ path, message: "set value must be a finite number" });
         }
       }
@@ -2244,7 +2512,7 @@ function validateStates(v: unknown, errors: JsonDslError[]): void {
         message: "state initial must be a number or string",
         hint: `got ${t}`,
       });
-    } else if (t === "number" && !Number.isFinite(initial as number)) {
+    } else if (t === "number" && !Number.isFinite(initial)) {
       // `NaN` / `Infinity` は JSON には書けないが、object を直接渡す経路では届く。
       // 描画側は文字列に直して式に流すため、そのまま通すと計算が全て壊れる
       errors.push({ path: `$.states.${name}`, message: "state initial must be a finite number" });
@@ -2285,12 +2553,6 @@ function validateValues(v: unknown, errors: JsonDslError[]): void {
   }
 }
 
-/**
- * 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)。
  *
@@ -2303,14 +2565,43 @@ function 整えた小見出し(v: string | undefined): string | undefined {
   return t.length > 0 ? t : undefined;
 }
 
-export function jsonToDoc(json: DragonJson): DslDocument {
-  const p0 = { line: 0 };
-  const actors: DslActor[] = json.actors.map((a) => {
+/**
+ * 見本の状態の上書きに、段を使うかどうか (`phase`) を混ぜる (#2125)。
+ *
+ * 組み立て側は段を外す指定を状態の上書きの中の `phase` として読む
+ * (`compile/parts.ts` の `段を外す`)。 記法は中括弧に書いた名前をすべて上書きへ入れるため
+ * `{ kind: wave-gauge, phase: false }` がそのまま届くが、JSON は欄ごとに型を宣言する形なので、
+ * 欄として受けたものを同じ場所へ入れ直す。
+ *
+ * **書かなかった時は欄を作らない**。 `{ phase: undefined }` を混ぜると、上書きの有無で
+ * 分岐する側から見て「書いた」 ことになる。
+ */
+function 段を含めた上書き(a: JsonActor): Record<string, number | string | boolean> | undefined {
+  if (a.phase === undefined) return a.state;
+  return { ...(a.state ?? {}), phase: a.phase };
+}
+
+/**
+ * JSON DSL → DslDocument (AST) 変換。
+ *
+ * 行番号は `行の表` を渡した時だけ入る (#2117)。 JSON そのものは書いた場所を持たないため、
+ * 本文の行が分かる入口 (編集画面の YAML 欄) が場所ごとの行を集めて渡す。 渡さない呼出は
+ * 全ての要素が 0 行になる = 「行が分からない」 ことを 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)。
+ */
+export function jsonToDoc(json: DragonJson, 行の表?: 書いた行の表): DslDocument {
+  // 書いた場所から行を引く。 引けない場所は 0 行 = 表を渡さない呼出と同じ状態になる
+  const 位置 = (...道: readonly (string | number)[]): { line: number } => ({
+    line: 行の表?.get(書いた場所の鍵(...道)) ?? 0,
+  });
+  const actors: DslActor[] = json.actors.map((a, i) => {
     if (typeof a === "string") {
-      return { name: a, kind: "actor" as NodeKind, kindWritten: false, pos: p0 };
+      return { name: a, kind: "actor" as NodeKind, kindWritten: false, pos: 位置("actors", i) };
     }
     // CAR-1657 = kind が既存 NodeKind に無い値なら parts identifier 候補、 partId に格納
-    const kindStr = (a.kind ?? "actor") as string;
+    const kindStr = a.kind ?? "actor";
     const isPart = kindStr !== "actor" && !VALID_KIND_SET.has(kindStr);
     // 色は記法と同じ振り分けを通す (#1294)。 `#` で始まれば色番号、それ以外は色の名前。
     // 別々に書くと、同じ値が入口によって色番号にも色名にもなる
@@ -2355,29 +2646,24 @@ export function jsonToDoc(json: DragonJson): DslDocument {
             opportunity: a.opportunity,
           }),
       colorHex: 色.hex,
+      // 部品に書いた色の名前は効かない。 記法と同じく書いた名前として残し、組み立て側が知らせる (#1973)
+      partColorName: isPart ? 色.tone : undefined,
       // 絶対座標と大きさ (#1294)。 `pos` (ずらし幅) とは別経路
       posX: a.posX,
       posY: a.posY,
       posW: a.posW,
       posH: a.posH,
-      // 箱の中の要素ごとの固定 (#1294)。 写しを作って外から書き換えられないようにする
-      nodes: a.nodes
-        ? Object.fromEntries(
-            Object.entries(a.nodes).map(([id, o]) => [
-              id,
-              { posX: o.posX, posY: o.posY, posW: o.posW, posH: o.posH },
-            ]),
-          )
-        : undefined,
       // 倍率は見本にしか効かない (検査が見本でない箱を弾く)。 書かれた名前は JSON では
       // 常に `scale` で、記法の別名 (`倍率`) は JSON に持ち込まない
       scale: isPart ? a.scale : undefined,
       scaleKeys: isPart && a.scale !== undefined ? ["scale"] : undefined,
       partId: isPart ? kindStr : undefined,
-      stateOverride: isPart ? a.state : undefined,
+      stateOverride: isPart ? 段を含めた上書き(a) : undefined,
       // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos の 2 層 mapping (naming collision 回避)
       layoutPos: a.pos,
-      pos: p0,
+      // 相対で置く指定 (#2039)。 欄の名前が内部と同じなのでそのまま渡す
+      posRel: a.posRel,
+      pos: 位置("actors", i),
     };
   });
   // 図の配色 (#1553)。 解くのは 1 度だけにする
@@ -2389,13 +2675,15 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     to: s.to,
     label: s.label,
     sub: s.sub,
-    side: s.side as "top" | "right" | "bottom" | "left" | undefined,
+    side: s.side,
     // 矢印の先の形 (#1462)。 読めない語は組み立てが落とす
     head: s.head,
     // 端の印の残り 3 欄と、関係の語 / 言づての種類 (#1466)
     tailHead: s.tailHead,
     headFill: s.headFill,
     tailHeadFill: s.tailHeadFill,
+    // クラス図の出どころ側の多重度 (#1771)
+    tailSub: s.tailSub,
     relation: s.relation,
     // 辺の役目と名前の下地 (cdl#618)
     role: s.role,
@@ -2414,9 +2702,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     labelOffsetX: s.labelOffsetX,
     labelOffsetY: s.labelOffsetY,
     overlay: s.overlay,
+    // 部品の端で繋ぐ要素の id (#1979)。 書かない矢印には欄を足さない = 記法と同じ形になる
+    ...(s.fromPartNode !== undefined ? { fromPartNode: s.fromPartNode } : {}),
+    ...(s.toPartNode !== undefined ? { toPartNode: s.toPartNode } : {}),
     // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos
     layoutPos: s.pos,
-    pos: p0,
+    pos: 位置("flow", i),
   }));
   // 状態は段が無くても図に載る (#1162 で組み立ての出口が載せる)。 **段の有無で分けない** =
   // 分けると `states` だけを書いた JSON で値が 1 つも届かない (記法側で起きていた形、 #1181)
@@ -2429,7 +2720,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
    *
    * 相手は名前のまま持ち、識別子への読み替えは組み立てが行う = 2 つの入口で同じ経路を通る。
    */
-  const events: DslEventBinding[] | undefined = json.events?.map((e) => ({
+  const events: DslEventBinding[] | undefined = json.events?.map((e, i) => ({
     event: e.on as DslEventBinding["event"],
     target:
       e.diagram === true
@@ -2444,28 +2735,38 @@ export function jsonToDoc(json: DragonJson): DslDocument {
             ? ({ kind: "lane" as const, name: e.lane } as const)
             : ({ kind: "node" as const, name: e.box ?? "" } as const),
     handlerId: e.handler.trim(),
-    pos: p0,
+    pos: 位置("events", i),
   }));
   const scrolls: DslScrollTrigger[] | undefined = json.scrolls
     ? Object.entries(json.scrolls).map(([id, spec]) => ({ id, ...spec }))
     : undefined;
-  // 式は `{ 名前: "式" }` から並びへ写す (#1391)。 記法側と同じ形にして組み立てを 1 本にする
+  // 式は `{ 名前: "式" }` から並びへ写す (#1391)。 記法側と同じ形にして組み立てを 1 本にする。
+  // 組の形 (`{ expression, label }`) は名札を持ったまま写す (#1916)
   const formulas: DslFormula[] | undefined = json.formulas
-    ? Object.entries(json.formulas).map(([id, expression]) => ({ id, expression, pos: p0 }))
+    ? Object.entries(json.formulas).map(([id, 値]) =>
+        typeof 値 === "string"
+          ? { id, expression: 値, pos: 位置("formulas", id) }
+          : {
+              id,
+              expression: 値.expression,
+              ...(値.label !== undefined ? { label: 値.label } : {}),
+              pos: 位置("formulas", id),
+            },
+      )
     : undefined;
   const states: DslState[] = Object.entries(json.states ?? {}).map(([name, initial]) => ({
     name,
     initial,
-    pos: p0,
+    pos: 位置("states", name),
   }));
-  const phases: DslPhase[] = (json.animation ?? []).map((p) => ({
+  const phases: DslPhase[] = (json.animation ?? []).map((p, i) => ({
     name: p.step,
     durationMs: Math.round((p.duration ?? 1.4) * 1000),
     highlight: p.focus,
     body: p.body,
     badge: p.badge,
     // 書いた段だけが欄を持つ。 空文字を置くと「書いた」 と「書いていない」 が同じ形になる
-    ...(p.draw !== undefined ? { draw: p.draw, drawPos: p0 } : {}),
+    ...(p.draw !== undefined ? { draw: p.draw, drawPos: 位置("animation", i, "draw") } : {}),
     // 割合は `draw` がある段にだけ写す。 単独で書いても描く相手が決まらず何も起きないので、
     // 記法側 (同じ行に書かせる形) と同じ状態に揃える
     ...(p.draw !== undefined && p.drawRatio !== undefined ? { drawRatio: p.drawRatio } : {}),
@@ -2477,17 +2778,27 @@ export function jsonToDoc(json: DragonJson): DslDocument {
             state,
             from,
             to,
-            pos: p0,
+            pos: 位置("animation", i, "tween", state),
           })),
         }
       : {}),
     ...(p.set && Object.keys(p.set).length > 0
-      ? { sets: Object.entries(p.set).map(([state, value]) => ({ state, value, pos: p0 })) }
+      ? {
+          sets: Object.entries(p.set).map(([state, value]) => ({
+            state,
+            value,
+            pos: 位置("animation", i, "set", state),
+          })),
+        }
       : {}),
-    pos: p0,
+    pos: 位置("animation", i),
   }));
   const animate: DslAnimate | undefined =
-    states.length > 0 || phases.length > 0 ? { states, phases, pos: p0 } : undefined;
+    states.length > 0 || phases.length > 0
+      ? // 動きの塊そのものには書いた場所が無い。 段がある文書は `animation`、無い文書は
+        // `states` を指す = どちらも「動きを書き始めた場所」 になる
+        { states, phases, pos: phases.length > 0 ? 位置("animation") : 位置("states") }
+      : undefined;
   return {
     title: json.title,
     type: json.type,
@@ -2495,12 +2806,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     // 空かどうかを判定するため、 揃えないと **空白だけの値で入口ごとに図が変わる**
     // (記法は書かなかった扱い、 JSON は中身のない帯を描く。 Round 2 の指摘で実測)
     ...(整えた小見出し(json.eyebrow) !== undefined
-      ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: p0 }
+      ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: 位置("eyebrow") }
       : {}),
     // 2 軸で仕分ける図の軸の名前 (#1294)。 中身の無い形は「書かなかった」 と同じにする =
     // 空の軸を渡すと、書いていない側の名前が空文字で描かれる (記法側と同じ扱い)
     ...(json.axes && (json.axes.x !== undefined || json.axes.y !== undefined)
-      ? { axes: json.axes, axesPos: p0 }
+      ? { axes: json.axes, axesPos: 位置("axes") }
       : {}),
     actors,
     flow,
@@ -2508,16 +2819,20 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     // 他の値から決まる値 (#1181)。 書いた順に並べる = 解く順は参照から決まるので順序に
     // 意味は無いが、知らせの並びが書いた順になる
     values: json.values
-      ? Object.entries(json.values).map(([name, expression]) => ({ name, expression, pos: p0 }))
+      ? Object.entries(json.values).map(([name, expression]) => ({
+          name,
+          expression,
+          pos: 位置("values", name),
+        }))
       : undefined,
-    viewport: json.viewport ? { ...json.viewport, pos: p0 } : undefined,
+    viewport: json.viewport ? { ...json.viewport, pos: 位置("viewport") } : undefined,
     lanes: json.lanes
       ? Object.fromEntries(
           Object.entries(json.lanes).map(([id, l]) => {
             // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos の 2 層 mapping。
             // JSON input の { pos, x, width, ... } を分離し、 pos のみ layoutPos に rename する。
             const { pos: layoutPos, ...laneRest } = l;
-            return [id, { id, ...laneRest, layoutPos, pos: p0 }];
+            return [id, { id, ...laneRest, layoutPos, pos: 位置("lanes", id) }];
           }),
         )
       : undefined,
@@ -2525,7 +2840,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       ? Object.fromEntries(
           Object.entries(json.groups).map(([id, g]) => [
             id,
-            { id, label: g.label, lanes: g.lanes, pos: p0 },
+            { id, label: g.label, lanes: g.lanes, pos: 位置("groups", id) },
           ]),
         )
       : undefined,
@@ -2538,12 +2853,20 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     bands: json.bands,
     // 矢印をいつ出すか (#1470)
     reveal: json.reveal,
-    // 図の並ぶ向き (#1494)。 JSON は英語で書くので、記法と同じ語に直してから渡す
-    ...(json.direction !== undefined ? { direction: json.direction === "horizontal" ? ("横" as const) : ("縦" as const) } : {}),
+    // 箱に触れると関係する線だけを光らせるか (#1757)
+    relations: json.relations,
+    // 図の並ぶ向き (#1494)。 JSON は英語で書くので、記法と同じ語に直してから渡す。
+    // 書いた行も記法と同じく持つ = 持たないと、向きの知らせが文書の行 (1 行目) を指す
+    ...(json.direction !== undefined
+      ? {
+          direction: json.direction === "horizontal" ? ("横" as const) : ("縦" as const),
+          directionPos: 位置("direction"),
+        }
+      : {}),
     // 図の配色 (#1553)。 記法と同じ解決を通す = 別名 (`生成り` / `青磁`) の受け方がずれない。
     // 読めない語は渡さない = 上流の型検査が語を絞っているので、ここに来るのは書き間違いだけ
     ...(配色 !== null ? { palette: 配色 } : {}),
-    pos: p0,
+    pos: 位置(),
   };
 }
 
@@ -2573,7 +2896,17 @@ export function jsonToDiagram(
   // **`onNotice` も通す**。 記法経路だけに通知を付けていたため、 同じ型を受ける JSON / YAML
   // 経路では読めない値や捨てた矢印が利用者へ届かなかった (review 指摘)。 エディタの YAML タブは
   // ここを通る
-  opts?: { partsCatalog?: Record<string, CdlDiagram>; onNotice?: CompileToCdlOpts["onNotice"] },
+  opts?: {
+    partsCatalog?: Record<string, CdlDiagram>;
+    onNotice?: CompileToCdlOpts["onNotice"];
+    /**
+     * 本文の場所から書いた行を引く表 (#2117)。 渡すと知らせが書いた行を指す。
+     *
+     * JSON そのものは書いた場所を持たないため、本文の行が分かる入口 (編集画面の YAML 欄) が
+     * 集めて渡す。 渡さない呼出は今までどおり全ての知らせが 0 行になる。
+     */
+    行の表?: 書いた行の表;
+  },
 ): CdlDiagram {
   const v = validateJson(json);
   if (!v.ok) {
@@ -2582,7 +2915,7 @@ export function jsonToDiagram(
       .join("\n");
     throw new Error(`Dragon JSON DSL validation error:\n${msg}`);
   }
-  const doc = jsonToDoc(v.data);
+  const doc = jsonToDoc(v.data, opts?.行の表);
   return compileToCdl(doc, opts);
 }