@cardenelabs/dragon 0.12.0 → 0.14.0

package/src/json-parser.ts

@@ -20,6 +20,7 @@
 
 import {
   DRAW_WORDS,
+  EDGE_SIDE_VALUES,
   NODE_KIND_VALID,
   PRESET_TYPES,
   STYLE_VALID,
@@ -27,9 +28,16 @@ import {
   resolveTone,
   splitColorValue,
   書ける色名,
+  図形の表,
+  部品の表,
+  部品の組の表,
+  つまみの表,
+  EVENT_KINDS,
+  type 図形の定義,
 } from "./v05/parser";
 import type { CompileToCdlOpts } from "./compile";
 import type { CdlDiagram, NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
+import { extractIdentifiers, parseFormula } from "@cardenelabs/cdl";
 import type {
   DslDocument,
   DslActor,
@@ -39,6 +47,12 @@ import type {
   DslState,
   PresetType,
   LayoutPos,
+  DslReadout,
+  DslInput,
+  DslFormula,
+  DslEventBinding,
+  DslScrollTrigger,
+  DslDynShape,
 } from "./types";
 import { checkValueExpression, isValueName, valueNameIssue } from "./value-syntax";
 import { compileToCdl } from "./compile";
@@ -72,6 +86,39 @@ export interface DragonJson {
   actors: (string | JsonActor)[];
   /** flow step 配列 (必須): { from, to, label, ... } */
   flow: JsonStep[];
+  /**
+   * 値を見せる部品 (optional、 #1374)。 記法の最上位 `readouts:` と同じ。
+   *
+   * 箱ではないので縦列に載らない。 図全体に 1 つの並びとして持つ。
+   */
+  readouts?: DslReadout[];
+  /**
+   * 読む人が動かすつまみ (optional、 #1389)。 記法の最上位 `inputs:` と同じ。
+   *
+   * 部品と同じく箱ではないので縦列に載らない。 図全体に 1 つの並びとして持つ。
+   */
+  inputs?: DslInput[];
+  /**
+   * つまみの値から決まる値 (optional、 #1391)。 記法の最上位 `formulas:` と同じ。
+   *
+   * 形は `{ 名前: "式" }`。 `values:` と経路が別で、式は名前を中括弧で囲わない。
+   */
+  formulas?: Record<string, string>;
+  /**
+   * 押下などの出来事で動く仕掛け (optional、 #1393)。 記法の最上位 `events:` と同じ。
+   *
+   * 相手は名前で指す (`box` / `lane` / `arrow` / `diagram` のどれか 1 つ)。
+   */
+  events?: {
+    on: string;
+    handler: string;
+    box?: string;
+    lane?: string;
+    arrow?: string;
+    diagram?: boolean;
+  }[];
+  /** 巻き上げに応じて進む値 (optional、 #1393)。 記法の最上位 `scrolls:` と同じ */
+  scrolls?: Record<string, { start?: number; end?: number; scrub?: number; label?: string }>;
   /**
    * 状態の初期値 (optional)。 記法の `states:` と同じ (#1181)。
    *
@@ -129,6 +176,31 @@ export interface DragonJson {
 
 export interface JsonActor {
   name: string;
+  /**
+   * 箱の中に描く図形 (optional、 #1374)。 記法の `shape:` と同じ。
+   *
+   * 水位や角度を状態で動かす。 形は描画側の型が縛る。
+   */
+  shape?: DslDynShape;
+  /**
+   * その箱を出すかどうかの条件 (optional、 #1381)。 記法の `visibleIf:` と同じ。
+   */
+  visibleIf?: string;
+  /**
+   * 箱に出す題 (optional、 #1381)。 記法の `title:` と同じ。
+   */
+  title?: string;
+  /**
+   * 値に追随する 5 欄 (optional、 #1392)。 記法の `wBind:` / `hBind:` / `opacity:` /
+   * `renderOffsetX:` / `renderOffsetY:` と同じ。
+   *
+   * 大きさは文字列だけ (数を書いても追随のしようが無い)、濃さとずらしは数も受ける。
+   */
+  wBind?: string;
+  hBind?: string;
+  opacity?: number | string;
+  renderOffsetX?: number | string;
+  renderOffsetY?: number | string;
   /**
    * CAR-1657 unified syntax = 既存 NodeKind (28 個) に加えて parts identifier (arc-gauge 等) を
    * accept する。 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
@@ -236,6 +308,8 @@ export interface JsonStep {
   to: string;
   label: string;
   sub?: string;
+  /** 矢印がどの辺から出るか (#1385)。 記法の `side:` と同じ */
+  side?: "top" | "right" | "bottom" | "left";
   /**
    * 矢印の色 (#1304)。 記法の `(成功)` と同じく別名 (`成功` / `neutral` 等) も受ける。
    *
@@ -245,6 +319,13 @@ export interface JsonStep {
   style?: EdgeStyle;
   guard?: string;
   cardinality?: string;
+  /**
+   * 矢印を値に追随させる 3 欄 (optional、 #1396)。 記法の `widthBind:` / `strokeBind:` /
+   * `dashOffsetBind:` と同じ。 描画側は文字列だけを取る。
+   */
+  widthBind?: string;
+  strokeBind?: string;
+  dashOffsetBind?: string;
   labelOffsetX?: number;
   labelOffsetY?: number;
   /** true で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
@@ -347,6 +428,15 @@ export const ACCEPTED_KEYS = {
     "viewport",
     "lanes",
     "groups",
+    // 値を見せる部品 (#1374)
+    "readouts",
+    // 読む人が動かすつまみ (#1389)
+    "inputs",
+    // つまみの値から決まる値 (#1391)
+    "formulas",
+    // 押下などの出来事で動く仕掛けと、巻き上げに応じて進む値 (#1393)
+    "events",
+    "scrolls",
   ],
   actor: [
     "name",
@@ -373,16 +463,34 @@ export const ACCEPTED_KEYS = {
     "scale",
     "state",
     "pos",
+    // 箱の中に描く図形 (#1374)
+    "shape",
+    // その箱を出すかどうかの条件 (#1381)
+    "visibleIf",
+    // 箱に出す題 (#1381)
+    "title",
+    // 値に追随する 5 欄 (#1392)
+    "wBind",
+    "hBind",
+    "opacity",
+    "renderOffsetX",
+    "renderOffsetY",
   ],
   step: [
     "from",
     "to",
     "label",
     "sub",
+    // 矢印がどの辺から出るか (#1385)
+    "side",
     "tone",
     "style",
     "guard",
     "cardinality",
+    // 値に追随する 3 欄 (#1396)
+    "widthBind",
+    "strokeBind",
+    "dashOffsetBind",
     "labelOffsetX",
     "labelOffsetY",
     "overlay",
@@ -431,9 +539,12 @@ export type 欄の型 =
   | "文字列の並び"
   | "数"
   | "必須の数"
+  // 値に追随する欄 (#1392)。 数を直に書く形と、状態の名前を書く形の両方を受ける
+  | "数か文字列"
   | "真偽"
   | "色"
   | "線種"
+  | "辺"
   | "色か色番号"
   | "描くもの"
   | "必須の図種"
@@ -456,6 +567,15 @@ export const 欄の型表 = {
     viewport: "object",
     lanes: "object",
     groups: "object",
+    // 値を見せる部品 (#1374)。 中身は下の検査が種類ごとに見る
+    readouts: "並び",
+    // 読む人が動かすつまみ (#1389)。 部品と同じく中身は下の検査が種類ごとに見る
+    inputs: "並び",
+    // つまみの値から決まる値 (#1391)。 中身は下の検査が式ごとに見る
+    formulas: "object",
+    // 押下と巻き上げ (#1393)。 中身は下の検査が 1 件ずつ見る
+    events: "並び",
+    scrolls: "object",
   },
   actor: {
     name: "必須の非空文字列",
@@ -482,16 +602,34 @@ export const 欄の型表 = {
     scale: "数",
     state: "object",
     pos: "object",
+    // 箱の中に描く図形 (#1374)。 中身は下の検査が種類ごとに見る
+    shape: "object",
+    // その箱を出すかどうかの条件 (#1381)
+    visibleIf: "文字列",
+    // 箱に出す題 (#1381)
+    title: "文字列",
+    // 値に追随する 5 欄 (#1392)。 大きさは文字列だけ、濃さとずらしは数も受ける
+    wBind: "非空の文字列",
+    hBind: "非空の文字列",
+    opacity: "数か文字列",
+    renderOffsetX: "数か文字列",
+    renderOffsetY: "数か文字列",
   },
   step: {
     from: "必須の文字列",
     to: "必須の文字列",
     label: "必須の文字列",
     sub: "文字列",
+    // 矢印がどの辺から出るか (#1385)
+    side: "辺",
     tone: "色",
     style: "線種",
     guard: "文字列",
     cardinality: "文字列",
+    // 値に追随する 3 欄 (#1396)。 描画側は文字列だけを取る
+    widthBind: "非空の文字列",
+    strokeBind: "非空の文字列",
+    dashOffsetBind: "非空の文字列",
     labelOffsetX: "数",
     labelOffsetY: "数",
     overlay: "真偽",
@@ -573,7 +711,10 @@ function JSONの色名か(v: string): boolean {
  * `見本に効かない欄` (#1308) と対になる。 2 つの表で「どちらの箱にしか効かないか」 を
  * 両方向から宣言する = 片方だけ増えると鏡の関係が崩れる。
  */
-export const 見本にしか効かない欄 = ["state", "scale"] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
+export const 見本にしか効かない欄 = [
+  "state",
+  "scale",
+] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
 
 /**
  * 普通の箱にしか効かない欄 (#1308)。
@@ -598,6 +739,18 @@ export const 見本に効かない欄 = [
   "end",
   "touchpoint",
   "opportunity",
+  // 箱の中に描く図形 (#1374)。 見本は自分の形を持つため、外から図形を差し替えられない
+  "shape",
+  // その箱を出すかどうかの条件 (#1381)。 見本は自分の出方を持つ
+  "visibleIf",
+  // 箱に出す題 (#1381)。 見本は自分の題を持つ
+  "title",
+  // 値に追随する 5 欄 (#1392)。 見本は自分の大きさと出方を持つ
+  "wBind",
+  "hBind",
+  "opacity",
+  "renderOffsetX",
+  "renderOffsetY",
 ] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
 
 /**
@@ -629,7 +782,7 @@ function 値を検査(
       return;
     case "非空の文字列":
       if (v === undefined) return;
-      if (typeof v !== "string" || v.length === 0) 型違い("a non-empty string if present");
+      if (typeof v !== "string" || v.trim().length === 0) 型違い("a non-empty string if present");
       return;
     case "文字列":
       if (v === undefined) return;
@@ -666,6 +819,20 @@ function 値を検査(
         型違い("a finite number", typeof v === "number" ? `got ${String(v)}` : undefined);
       }
       return;
+    case "数か文字列":
+      if (v === undefined) return;
+      // 空文字は受けない。 描画側は 0 として読むため、書き忘れが「箱が消える」 形で出る
+      if (typeof v === "string") {
+        if (v.trim().length === 0) 型違い("a non-empty string if present");
+        return;
+      }
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        型違い(
+          "a finite number or a non-empty string if present",
+          typeof v === "number" ? `got ${String(v)}` : undefined,
+        );
+      }
+      return;
     case "真偽":
       if (v === undefined) return;
       if (typeof v !== "boolean") 型違い("true or false if present");
@@ -695,6 +862,16 @@ function 値を検査(
         });
       }
       return;
+    case "辺":
+      if (v === undefined) return;
+      if (typeof v !== "string" || !(EDGE_SIDE_VALUES as readonly string[]).includes(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${EDGE_SIDE_VALUES.join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : `got ${typeof v}`,
+        });
+      }
+      return;
     case "描くもの":
       if (v === undefined) return;
       // 受ける語は記法と同じ一覧を見る (`DRAW_WORDS`)。 写すと語が増えた時に片方だけ古くなる
@@ -912,6 +1089,458 @@ function validateViewport(v: unknown, errors: JsonDslError[]): void {
  * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
  * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
  */
+/**
+ * 図形と部品の中身を、記法と **同じ表** で検査する (#1374)。
+ *
+ * 表を 2 つ持つと片方だけ直してずれる。 記法側 (`v05/parser.ts`) が持つ表をそのまま引く。
+ *
+ * 記法は値が全て文字列で届くため読み替えが要るが、JSON は型のまま届く。 ここでは
+ * 「知らない種類」 「知らない欄」 「足りない必須の欄」 「欄の型違い」 の 4 つを見る。
+ */
+function 表で中身を検査する(
+  o: Record<string, unknown>,
+  表: Record<string, 図形の定義>,
+  path: string,
+  何: string,
+  errors: JsonDslError[],
+): void {
+  // JSON は公開 schema の enum と同じ正規名だけを受ける。 ここだけ小文字化すると、
+  // schema が拒む種類を validator が通した上、種類別の追加検査も回避できてしまう。
+  const kind = typeof o.kind === "string" ? o.kind : "";
+  // 通常の object を表に使うため、継承した名前を own kind として扱わない。
+  const 定義 = Object.hasOwn(表, kind) ? 表[kind] : undefined;
+  if (定義 === undefined) {
+    errors.push({
+      path: `${path}.kind`,
+      // **文字列でない値をそのまま文にしない**。 object を混ぜると `[object Object]` になり、
+      // 何を書いたのかが読み手に届かない
+      message: `unknown ${何} kind ${typeof o.kind === "string" ? `"${o.kind}"` : JSON.stringify(o.kind ?? null)}`,
+      hint: `使える種類 = ${Object.keys(表).join(", ")}`,
+    });
+    return;
+  }
+  for (const [欄, 値] of Object.entries(o)) {
+    if (欄 === "kind" || 欄 === "id") continue;
+    const 形 = 定義.欄[欄];
+    if (形 === undefined) {
+      errors.push({
+        path: `${path}.${欄}`,
+        message: `unknown key "${欄}"`,
+        hint: `使える項目 = ${Object.keys(定義.欄).join(", ")}`,
+      });
+      continue;
+    }
+    const 型が合う =
+      形 === "数"
+        ? typeof 値 === "number" && Number.isFinite(値)
+        : 形 === "数か文字列"
+          ? (typeof 値 === "number" && Number.isFinite(値)) || typeof 値 === "string"
+          : 形 === "文字列の並び"
+            ? Array.isArray(値) && 値.every((x) => typeof x === "string")
+            : 形 === "数の並び"
+              ? Array.isArray(値) && 値.every((x) => typeof x === "number" && Number.isFinite(x))
+              : 形 === "真偽"
+                ? typeof 値 === "boolean"
+                : 形 === "組の並び"
+                  ? Array.isArray(値) &&
+                    値.length > 0 &&
+                    値.every(
+                      (x) =>
+                        typeof x === "object" &&
+                        x !== null &&
+                        !Array.isArray(x) &&
+                        Object.keys(x as object).length > 0 &&
+                        Object.values(x as object).every(
+                          (y) =>
+                            typeof y === "string" || (typeof y === "number" && Number.isFinite(y)),
+                        ),
+                    )
+                  : 形 === "向き"
+                    ? typeof 値 === "string" && ["up", "down", "left", "right"].includes(値)
+                    : typeof 値 === "string";
+    if (!型が合う) {
+      errors.push({
+        path: `${path}.${欄}`,
+        message: `${欄} must be ${形}`,
+        hint: `got ${Array.isArray(値) ? "array" : 値 === null ? "null" : typeof 値}`,
+      });
+    }
+  }
+  for (const 欄 of 定義.必須) {
+    if (o[欄] === undefined) {
+      errors.push({
+        path: `${path}.${欄}`,
+        message: `${欄} is required for ${何} kind "${kind}"`,
+        hint: `必須の項目 = ${定義.必須.join(", ")}`,
+      });
+    }
+  }
+}
+
+/**
+ * 値を見せる部品の並びを検査する (#1374)。
+ *
+ * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
+ * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `readouts: 1` が
+ * 素通りする。
+ */
+function validateReadouts(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!Array.isArray(v)) {
+    errors.push({
+      path: "$.readouts",
+      message: "readouts must be an array of readout objects",
+      hint: `got ${v === null ? "null" : typeof v}`,
+    });
+    return;
+  }
+  v.forEach((r, i) => {
+    const path = `$.readouts[${i}]`;
+    if (!r || typeof r !== "object" || Array.isArray(r)) {
+      errors.push({ path, message: "readout must be a plain object", hint: `got ${typeof r}` });
+      return;
+    }
+    const o = r as Record<string, unknown>;
+    if (typeof o.id !== "string" || o.id === "") {
+      errors.push({ path: `${path}.id`, message: "id is required", hint: "空でない文字列で書く" });
+    }
+    表で中身を検査する(o, 部品の表, path, "readout", errors);
+
+    /*
+     * 組の並びを取る欄の中身を、記法と同じ表で見る (#1385)。
+     *
+     * **種類を手で並べない**。 元は `status-dot` と `status-timeline` を直書きしていたが、
+     * 表は描画側の型定義から生成しており、種類が増えるたびに書き足す形になる。
+     */
+    const 組の定義 = 部品の組の表[String(o.kind)];
+    for (const [欄名, 定義] of Object.entries(組の定義 ?? {})) {
+      if (!Array.isArray(o[欄名])) continue;
+      (o[欄名] as unknown[]).forEach((entry, j) => {
+        const entryPath = `${path}.${欄名}[${j}]`;
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
+        const item = entry as Record<string, unknown>;
+        for (const key of Object.keys(item)) {
+          if (key in 定義.欄) continue;
+          errors.push({
+            path: `${entryPath}.${key}`,
+            message: `${key} is not allowed for readout kind "${String(o.kind)}"`,
+            hint: `使える項目 = ${Object.keys(定義.欄).join(", ")}`,
+          });
+        }
+        for (const key of 定義.必須) {
+          if (item[key] !== undefined) continue;
+          errors.push({
+            path: `${entryPath}.${key}`,
+            message: `${key} is required for readout kind "${String(o.kind)}"`,
+          });
+        }
+        for (const [key, 形] of Object.entries(定義.欄)) {
+          const 値 = item[key];
+          if (値 === undefined) continue;
+          const 合う =
+            形 === "数" ? typeof 値 === "number" && Number.isFinite(値) : typeof 値 === "string";
+          if (合う) continue;
+          errors.push({
+            path: `${entryPath}.${key}`,
+            message: `${key} must be ${形}`,
+            hint: `got ${Array.isArray(値) ? "array" : 値 === null ? "null" : typeof 値}`,
+          });
+        }
+      });
+    }
+  });
+}
+
+/**
+ * 読む人が動かすつまみの並びを検査する (#1389)。
+ *
+ * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
+ * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `inputs: 1` が
+ * 素通りする。
+ *
+ * 種類ごとの欄は記法と同じ表 (`つまみの表`) で見る。 表は描画側の型定義から生成しており、
+ * 種類が増えても書き足す場所が増えない。
+ */
+function validateInputs(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!Array.isArray(v)) {
+    errors.push({
+      path: "$.inputs",
+      message: "inputs must be an array of input objects",
+      hint: `got ${v === null ? "null" : typeof v}`,
+    });
+    return;
+  }
+  v.forEach((r, i) => {
+    const path = `$.inputs[${i}]`;
+    if (!r || typeof r !== "object" || Array.isArray(r)) {
+      errors.push({ path, message: "input must be a plain object", hint: `got ${typeof r}` });
+      return;
+    }
+    const o = r as Record<string, unknown>;
+    if (typeof o.id !== "string" || o.id === "") {
+      errors.push({ path: `${path}.id`, message: "id is required", hint: "空でない文字列で書く" });
+    }
+    表で中身を検査する(o, つまみの表, path, "input", errors);
+  });
+}
+
+/**
+ * つまみの値から決まる値を検査する (#1391)。
+ *
+ * **外側の形もここで見る**。 `欄の型表` は「object」 とだけ宣言するため、
+ * ここで見ないと `formulas: { a: 1 }` が素通りする。
+ *
+ * 式そのものは描画側の parser に通す = 自前で書き方を決めると、通ったのに描画側が
+ * 解けない式を受けてしまう。
+ */
+function validateFormulas(v: unknown, inputs: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({
+      path: "$.formulas",
+      message: "formulas must be an object of name to expression",
+      hint: `got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}`,
+    });
+    return;
+  }
+  const つまみ = new Map<string, string>();
+  if (Array.isArray(inputs)) {
+    for (const input of inputs) {
+      if (input && typeof input === "object" && !Array.isArray(input)) {
+        const candidate = input as { id?: unknown; kind?: unknown };
+        if (typeof candidate.id === "string" && typeof candidate.kind === "string") {
+          つまみ.set(candidate.id, candidate.kind);
+        }
+      }
+    }
+  }
+  const 先に書かれた式 = new Set<string>();
+  for (const [名前, 式] of Object.entries(v as Record<string, unknown>)) {
+    const path = `$.formulas.${名前}`;
+    if (!isValueName(名前)) {
+      errors.push({ path, ...valueNameIssue(名前) });
+      continue;
+    }
+    if (typeof 式 !== "string" || 式.trim() === "") {
+      errors.push({
+        path,
+        message: `${名前} must be a non-empty expression string`,
+        hint: `got ${Array.isArray(式) ? "array" : 式 === null ? "null" : typeof 式}`,
+      });
+      continue;
+    }
+    try {
+      const names = extractIdentifiers(parseFormula(式));
+      if (つまみ.has(名前) || 先に書かれた式.has(名前)) {
+        errors.push({
+          path,
+          message: `${名前} collides with an input or an earlier formula`,
+          hint: "inputs と formulas では重ならない名前を使う",
+        });
+        continue;
+      }
+      let valid = true;
+      for (const name of names) {
+        if (先に書かれた式.has(name)) continue;
+        const kind = つまみ.get(name);
+        if (["slider", "number", "stepper", "timeline", "toggle"].includes(kind ?? "")) continue;
+        valid = false;
+        errors.push({
+          path,
+          message: `${名前} references an unavailable formula identifier`,
+          hint: `${name} は数値/真偽の input にするか、この式より前の formula に書く`,
+        });
+      }
+      if (valid) 先に書かれた式.add(名前);
+    } catch (e) {
+      errors.push({
+        path,
+        message: `${名前} is not a readable expression`,
+        hint: (e as Error).message,
+      });
+    }
+  }
+}
+
+/**
+ * 押下などの出来事で動く仕掛けを検査する (#1393)。
+ *
+ * 相手の指し方は 4 つあり、**ちょうど 1 つだけ書く**。 2 つ書くとどちらを指したのか
+ * 決まらず、0 なら相手がいない。 記法側の読み取りと同じ規則にする。
+ */
+function validateEvents(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!Array.isArray(v)) {
+    errors.push({
+      path: "$.events",
+      message: "events must be an array of event objects",
+      hint: `got ${v === null ? "null" : typeof v}`,
+    });
+    return;
+  }
+  const 相手の鍵 = ["box", "lane", "arrow", "diagram"];
+  v.forEach((e, i) => {
+    const path = `$.events[${i}]`;
+    if (!e || typeof e !== "object" || Array.isArray(e)) {
+      errors.push({ path, message: "event must be a plain object", hint: `got ${typeof e}` });
+      return;
+    }
+    const o = e as Record<string, unknown>;
+    for (const k of Object.keys(o)) {
+      if (k === "on" || k === "handler" || 相手の鍵.includes(k)) continue;
+      errors.push({
+        path: `${path}.${k}`,
+        message: `unknown key "${k}"`,
+        hint: `使える項目 = on, handler, ${相手の鍵.join(", ")}`,
+      });
+    }
+    if (typeof o.on !== "string" || !(EVENT_KINDS as readonly string[]).includes(o.on)) {
+      errors.push({
+        path: `${path}.on`,
+        message: "on must be a known event kind",
+        hint: `使える種類 = ${EVENT_KINDS.join(", ")}`,
+      });
+    }
+    if (typeof o.handler !== "string" || o.handler.trim() === "") {
+      errors.push({
+        path: `${path}.handler`,
+        message: "handler is required",
+        hint: "空でない文字列で書く",
+      });
+    }
+    const 書いた = 相手の鍵.filter((k) => o[k] !== undefined);
+    if (書いた.length !== 1) {
+      errors.push({
+        path,
+        message:
+          書いた.length === 0 ? "event target is required" : "event target must be written once",
+        hint: `${相手の鍵.join(" / ")} のどれか 1 つだけを書く`,
+      });
+      return;
+    }
+    const 鍵 = 書いた[0]!;
+    if (鍵 === "diagram") {
+      if (o.diagram !== true) {
+        errors.push({
+          path: `${path}.diagram`,
+          message: "diagram must be true",
+          hint: "図全体を指す時だけ書く",
+        });
+      }
+      return;
+    }
+    if (typeof o[鍵] !== "string" || (o[鍵] as string).trim() === "") {
+      errors.push({ path: `${path}.${鍵}`, message: `${鍵} must be a non-empty string` });
+      return;
+    }
+    if (鍵 === "arrow") {
+      const 両端 = (o.arrow as string).split("->");
+      if (両端.length !== 2 || 両端.some((x) => x.trim() === "")) {
+        errors.push({
+          path: `${path}.arrow`,
+          message: "arrow must be `A -> B`",
+          hint: "矢印の両端の名前を書く",
+        });
+      }
+    }
+  });
+}
+
+/**
+ * 巻き上げに応じて進む値を検査する (#1393)。
+ *
+ * 形は `{ 名前: { start, end, scrub, label } }`。 名前の規則は状態と揃える。
+ */
+function validateScrolls(
+  v: unknown,
+  inputs: unknown,
+  formulas: unknown,
+  errors: JsonDslError[],
+): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({
+      path: "$.scrolls",
+      message: "scrolls must be an object of name to spec",
+      hint: `got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}`,
+    });
+    return;
+  }
+  const 既に値を作る名前 = new Set<string>();
+  if (Array.isArray(inputs)) {
+    for (const input of inputs) {
+      if (!input || typeof input !== "object" || Array.isArray(input)) continue;
+      const id = (input as { id?: unknown }).id;
+      if (typeof id === "string") 既に値を作る名前.add(id);
+    }
+  }
+  if (formulas && typeof formulas === "object" && !Array.isArray(formulas)) {
+    for (const id of Object.keys(formulas)) 既に値を作る名前.add(id);
+  }
+  for (const [名前, spec] of Object.entries(v as Record<string, unknown>)) {
+    const path = `$.scrolls.${名前}`;
+    if (!isValueName(名前)) {
+      errors.push({ path, ...valueNameIssue(名前) });
+      continue;
+    }
+    if (既に値を作る名前.has(名前)) {
+      errors.push({
+        path,
+        message: `${名前} collides with an input or formula`,
+        hint: "inputs / formulas / scrolls では重ならない名前を使う",
+      });
+    }
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      errors.push({ path, message: `${名前} must be a plain object`, hint: `got ${typeof spec}` });
+      continue;
+    }
+    for (const [k, x] of Object.entries(spec as Record<string, unknown>)) {
+      if (k === "label") {
+        if (typeof x !== "string") {
+          errors.push({ path: `${path}.label`, message: "label must be a string" });
+        }
+        continue;
+      }
+      if (k !== "start" && k !== "end" && k !== "scrub") {
+        errors.push({
+          path: `${path}.${k}`,
+          message: `unknown key "${k}"`,
+          hint: "使える項目 = start, end, scrub, label",
+        });
+        continue;
+      }
+      if (typeof x !== "number" || !Number.isFinite(x)) {
+        errors.push({ path: `${path}.${k}`, message: `${k} must be a finite number` });
+      } else if (x < 0 || x > 1) {
+        errors.push({
+          path: `${path}.${k}`,
+          message: `${k} must be between 0 and 1`,
+          hint: "0 と 1 を含む範囲で書く",
+        });
+      }
+    }
+  }
+}
+
+/**
+ * 箱の中に描く図形を検査する (#1374)。
+ *
+ * `validateReadouts` と同じ理由で外側の形もここで見る。
+ */
+function validateActorShape(v: unknown, path: string, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({
+      path,
+      message: "shape must be a plain object",
+      hint: `got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}`,
+    });
+    return;
+  }
+  表で中身を検査する(v as Record<string, unknown>, 図形の表, path, "shape", errors);
+}
+
 function validateIdMap(
   v: unknown,
   欄: "lanes" | "groups",
@@ -1230,6 +1859,15 @@ function validateJson(
   // 知らない項目を先に見る (#1295)。 綴り違いは「書いた項目が効かない」 形で表に出るため、
   // 個々の型の誤りより先に伝える方が直しやすい
   checkUnknownKeys(j, "root", "$", errors);
+  // 値を見せる部品の中身を、記法と同じ表で見る (#1374)
+  validateReadouts(j.readouts, errors);
+  // 読む人が動かすつまみの中身も、記法と同じ表で見る (#1389)
+  validateInputs(j.inputs, errors);
+  // 式は描画側の parser に通す (#1391)
+  validateFormulas(j.formulas, j.inputs, errors);
+  // 押下と巻き上げ (#1393)
+  validateEvents(j.events, errors);
+  validateScrolls(j.scrolls, j.inputs, j.formulas, errors);
 
   // 値そのものの型は表が見る (#1304)。 図表の箱の上の小見出し (#1247) の空文字は
   // 「書かなかった」 と同じ扱いにするため通す (記法側の `eyebrow:` と揃える。 落とすのは `jsonToDoc`)
@@ -1249,6 +1887,8 @@ function validateJson(
       // 値そのものの型は表が見る (#1304)。 `kind` は見本 (parts) の名前も受けるため
       // 非空の文字列までしか縛らない (CAR-1657 の unified syntax)
       表で検査(ao, "actor", `$.actors[${i}]`, "actor", errors);
+      // 箱の中に描く図形の中身を、記法と同じ表で見る (#1374)
+      validateActorShape(ao.shape, `$.actors[${i}].shape`, errors);
       // 見本 (parts) にしか効かない項目は、見本でない箱に書かれたら誤りにする (#1294)。
       // 記法側は読めない項目名として行番号付きで知らせるため、黙って捨てると入口で扱いが変わる。
       const 見本か = 見本の名前か(ao.kind);
@@ -1526,6 +2166,16 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       stack: a.stack,
       initial: a.initial,
       final: a.final,
+      // 箱の中に描く図形 (#1374)。 見本では状態の上書きが効くため、通常の箱にだけ渡す
+      shape: isPart ? undefined : a.shape,
+      visibleIf: isPart ? undefined : a.visibleIf,
+      title: isPart ? undefined : a.title,
+      // 値に追随する 5 欄 (#1392)。 記法と同じく見本には渡さない
+      wBind: isPart ? undefined : a.wBind,
+      hBind: isPart ? undefined : a.hBind,
+      opacity: isPart ? undefined : a.opacity,
+      renderOffsetX: isPart ? undefined : a.renderOffsetX,
+      renderOffsetY: isPart ? undefined : a.renderOffsetY,
       // 普通の箱にしか効かない欄は見本では落とす。 落とす欄の一覧は `見本に効かない欄` が
       // 唯一の出どころで、検査 (#1308) も同じ表を見る = 「検査は通すが組み立てが捨てる」
       // 状態が作れない
@@ -1570,12 +2220,17 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     to: s.to,
     label: s.label,
     sub: s.sub,
+    side: s.side as "top" | "right" | "bottom" | "left" | undefined,
     // 箱と同じ読み替えを通す (#1304)。 通さないと `tone: "成功"` が色名として解決されないまま
     // 図に届き、同じ値が箱では色になり矢印では色にならない
     tone: resolveTone(s.tone),
     style: s.style,
     guard: s.guard,
     cardinality: s.cardinality,
+    // 値に追随する 3 欄 (#1396)
+    widthBind: s.widthBind,
+    strokeBind: s.strokeBind,
+    dashOffsetBind: s.dashOffsetBind,
     labelOffsetX: s.labelOffsetX,
     labelOffsetY: s.labelOffsetY,
     overlay: s.overlay,
@@ -1585,6 +2240,39 @@ export function jsonToDoc(json: DragonJson): DslDocument {
   }));
   // 状態は段が無くても図に載る (#1162 で組み立ての出口が載せる)。 **段の有無で分けない** =
   // 分けると `states` だけを書いた JSON で値が 1 つも届かない (記法側で起きていた形、 #1181)
+  // 値を見せる部品はそのまま渡す (#1374)。 形は描画側の型が縛る
+  const readouts: DslReadout[] | undefined = json.readouts ? [...json.readouts] : undefined;
+  // つまみもそのまま渡す (#1389)。 形は描画側の型が縛る
+  const inputs: DslInput[] | undefined = json.inputs ? [...json.inputs] : undefined;
+  /*
+   * 押下と巻き上げも記法側と同じ形へ写す (#1393)。
+   *
+   * 相手は名前のまま持ち、識別子への読み替えは組み立てが行う = 2 つの入口で同じ経路を通る。
+   */
+  const events: DslEventBinding[] | undefined = json.events?.map((e) => ({
+    event: e.on as DslEventBinding["event"],
+    target:
+      e.diagram === true
+        ? ({ kind: "diagram" } as const)
+        : e.arrow !== undefined
+          ? ({
+              kind: "edge" as const,
+              from: e.arrow.split("->")[0]?.trim() ?? "",
+              to: e.arrow.split("->")[1]?.trim() ?? "",
+            } as const)
+          : e.lane !== undefined
+            ? ({ kind: "lane" as const, name: e.lane } as const)
+            : ({ kind: "node" as const, name: e.box ?? "" } as const),
+    handlerId: e.handler.trim(),
+    pos: p0,
+  }));
+  const scrolls: DslScrollTrigger[] | undefined = json.scrolls
+    ? Object.entries(json.scrolls).map(([id, spec]) => ({ id, ...spec }))
+    : undefined;
+  // 式は `{ 名前: "式" }` から並びへ写す (#1391)。 記法側と同じ形にして組み立てを 1 本にする
+  const formulas: DslFormula[] | undefined = json.formulas
+    ? Object.entries(json.formulas).map(([id, expression]) => ({ id, expression, pos: p0 }))
+    : undefined;
   const states: DslState[] = Object.entries(json.states ?? {}).map(([name, initial]) => ({
     name,
     initial,
@@ -1658,6 +2346,11 @@ export function jsonToDoc(json: DragonJson): DslDocument {
           ]),
         )
       : undefined,
+    readouts,
+    inputs,
+    formulas,
+    events,
+    scrolls,
     pos: p0,
   };
 }