@cardenelabs/dragon 0.8.0 → 0.9.0

package/src/json-parser.ts

@@ -18,10 +18,28 @@
  *   YAML `animation: [step: "..."]` ⇔ JSON `{animation: [{step: "...", duration: 1.4, focus: [...]}]}`
  */
 
-import { PRESET_TYPES } from "./v05/parser";
+import {
+  DRAW_WORDS,
+  NODE_KIND_VALID,
+  PRESET_TYPES,
+  STYLE_VALID,
+  resolveNodeKind,
+  resolveTone,
+  splitColorValue,
+  書ける色名,
+} from "./v05/parser";
 import type { CompileToCdlOpts } from "./compile";
 import type { CdlDiagram, NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
-import type { DslDocument, DslActor, DslStep, DslAnimate, DslPhase, DslState, PresetType, LayoutMode, LayoutPos } from "./types";
+import type {
+  DslDocument,
+  DslActor,
+  DslStep,
+  DslAnimate,
+  DslPhase,
+  DslState,
+  PresetType,
+  LayoutPos,
+} from "./types";
 import { checkValueExpression, isValueName, valueNameIssue } from "./value-syntax";
 import { compileToCdl } from "./compile";
 
@@ -41,6 +59,15 @@ export interface DragonJson {
    * 組み立て側が知らせを出す。 そちらは `actors[].eyebrow` に書く。
    */
   eyebrow?: string;
+  /**
+   * 2 軸で仕分ける図 (`type: quadrant`) の軸の名前 (#1294)。 記法の `axes:` と同じ。
+   *
+   * 書かないと「小さい / 大きい」 のままになり、何を判断する図か読めない。 区画の名前
+   * (`右上` 等) は軸の名前から決まる。
+   *
+   * 他の図種には軸が無いため、書かれていたら組み立て側が知らせる。
+   */
+  axes?: JsonAxes;
   /** 登場人物 (必須): 文字列 or { name, kind, ... } object */
   actors: (string | JsonActor)[];
   /** flow step 配列 (必須): { from, to, label, ... } */
@@ -75,28 +102,29 @@ export interface DragonJson {
     labelMargin?: number;
   };
   /** lanes (optional): topology / swimlane preset で使う lane 宣言 */
-  lanes?: Record<string, {
-    x?: number;
-    width?: number;
-    label?: string;
-    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 する。
-     */
-    pos?: LayoutPos;
-  }>;
+  lanes?: Record<
+    string,
+    {
+      x?: number;
+      width?: number;
+      label?: string;
+      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 する。
+       */
+      pos?: LayoutPos;
+    }
+  >;
   /** groups (optional): topology preset で使う group 宣言 */
-  groups?: Record<string, {
-    label?: string;
-    lanes: string[];
-  }>;
-  /**
-   * canvas pivot (CAR-1693 Phase 1) diagram-level layout mode。 "auto" (default) は catalog 100+
-   * backward compat、 "manual" は Phase 4 で drag → pos: 保存の完全 manual mode として使う予定。
-   */
-  layout?: LayoutMode;
+  groups?: Record<
+    string,
+    {
+      label?: string;
+      lanes: string[];
+    }
+  >;
 }
 
 export interface JsonActor {
@@ -127,8 +155,80 @@ export interface JsonActor {
    * LLM JSON DSL では nested 明示 = `{ "state": { "v": 50 } }` が natural、 human 側の
    * inline 拡散 pattern (`- arc1: { kind: arc-gauge, v: 50 }`) とは記述形式が分岐する
    * (spec § 2.3 分岐設計、 human = YAML 手書き最適 / LLM = JSON structured 最適)。
+   *
+   * 見本でない箱に書くと誤りとして返す (#1294)。 記法側は読めない項目名として行番号付きで
+   * 知らせるため、黙って捨てると入口によって扱いが変わる。
    */
   state?: Record<string, number | string | boolean>;
+  /**
+   * 箱の色 (#1294)。 記法の `tone:` と同じ。
+   *
+   * 色の名前と別名 (`成功` / `success` 等) を受ける。 見本 (parts) では色ではなく状態の
+   * 上書きとして意味を持つため、記法と同じく見本の箱には効かない。
+   */
+  tone?: Tone | (string & {});
+  /**
+   * 色番号または色の名前 (#1294)。 記法の `色:` / `color:` と同じ。
+   *
+   * `#` で始まる値は色番号として `colorHex` に入り、見本の絵の色を変える。 それ以外は
+   * 色の名前として読む (記法の `splitColorValue` と同じ振り分け)。
+   */
+  color?: string;
+  /**
+   * 工程の並び (`type: gantt`) で、その工程の担当 (#1294)。 記法の `owner:` と同じ。
+   */
+  owner?: string;
+  /**
+   * 工程の並び (`type: gantt`) で、その工程が終わる時期 (#1294)。 記法の `end:` と同じ。
+   *
+   * 値は他の工程が書いた時期のどれかに一致させる。 一致しない値は始まりと同じ位置に落ちる
+   * (記法側と同じ扱い)。
+   */
+  end?: string;
+  /**
+   * 体験の道筋 (`type: journey`) で、その段階が起きる場所 (#1294)。 記法の `touchpoint:` と同じ。
+   */
+  touchpoint?: string;
+  /**
+   * 体験の道筋 (`type: journey`) で、その段階の改善の余地 (#1294)。 記法の `opportunity:` と同じ。
+   */
+  opportunity?: string;
+  /**
+   * 箱を置く絶対座標と大きさ (#1294)。 記法の `posX:` / `posY:` / `posW:` / `posH:` と同じ。
+   *
+   * `pos` (ずらし幅) とは別物。 こちらは auto layout を使わずに位置そのものを決める。
+   */
+  posX?: number;
+  posY?: number;
+  posW?: number;
+  posH?: number;
+  /**
+   * 箱の中の要素ごとに位置と大きさを固定する (#1294)。 記法の `nodes:` と同じ。
+   *
+   * key は箱が作る要素の名前 (`header` / `footer` / `spacer` / `s0` 等)。
+   */
+  nodes?: Record<string, JsonActorNodeOverride>;
+  /**
+   * 見本を何倍で描くか (#1294)。 記法の `scale:` / `倍率:` と同じ。
+   *
+   * 見本 (parts) にしか効かない。 見本でない箱に書くと誤りとして返す (記法側も同じく
+   * 読めない項目名として知らせる)。
+   */
+  scale?: number;
+}
+
+/** 2 軸で仕分ける図の軸の名前 (#1294)。 記法の `axes:` と同じ形 */
+export interface JsonAxes {
+  x?: { left?: string; right?: string };
+  y?: { bottom?: string; top?: string };
+}
+
+/** 箱の中の要素 1 つ分の位置と大きさ (#1294)。 記法の `nodes: { header: { ... } }` と同じ */
+export interface JsonActorNodeOverride {
+  posX?: number;
+  posY?: number;
+  posW?: number;
+  posH?: number;
 }
 
 export interface JsonStep {
@@ -136,7 +236,12 @@ export interface JsonStep {
   to: string;
   label: string;
   sub?: string;
-  tone?: Tone;
+  /**
+   * 矢印の色 (#1304)。 記法の `(成功)` と同じく別名 (`成功` / `neutral` 等) も受ける。
+   *
+   * `string & {}` は箱の `tone` と同じ idiom = 正規の色名を補完に出しつつ別名も通す。
+   */
+  tone?: Tone | (string & {});
   style?: EdgeStyle;
   guard?: string;
   cardinality?: string;
@@ -162,6 +267,13 @@ export interface JsonPhase {
   body?: string;
   /** badge label */
   badge?: string;
+  /**
+   * その段で左の起点から描くもの (#1312)。 記法の `draw: line` と同じ。
+   *
+   * 受ける語は `line` だけ (`DRAW_WORDS`)。 折れ線の図で、その段の間に線が左端から
+   * 右へ伸びる。
+   */
+  draw?: string;
   /**
    * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
    *
@@ -187,16 +299,19 @@ export interface JsonDslError {
 }
 
 /**
- * CAR-1657 = 既存 NodeKind list (v05/parser.ts の NODE_KIND_VALID と揃える必要あり)。
- * 未知 kind 値は parts identifier 候補として partId に格納する経路の判定基準。
- * v05 parser との drift 防止のため、 別 PR で共通化検討 (`packages/dragon/src/kinds.ts` etc)。
+ * 受け付ける種類 (`kind`)。 **記法側と同じ集合を使う** (`v05/parser.ts` の `NODE_KIND_VALID`)。
+ *
+ * ここに無い値は見本 (parts) の名前とみなし、`partId` へ退避して箱を `actor` に倒す
+ * (CAR-1657 の unified syntax)。 つまりこの集合が小さいほど、**書いた種類が黙って消える**。
+ *
+ * 以前はここに一覧を写していたため、記法に種類が増えても JSON 経路が古い一覧のまま
+ * 見本の名前として扱った (実測 = 記法が知る 108 種のうち 77 種が該当、`shape-*` は全滅)。
+ * 見本帳に無い名前は `console.warn` にしか残らず `onNotice` を呼ばないため、
+ * 画面には何も出ないまま `actor` の箱が描かれていた (#1293)。
+ *
+ * 型が 2 箇所に散らばると、必ずどちらかが古くなる。 `VALID_PRESETS` (図種) と同じ扱いにする。
  */
-const VALID_KIND_SET: ReadonlySet<string> = new Set([
-  "actor", "function", "storage", "event", "cdn", "service", "database",
-  "cache", "queue", "api", "person", "entity", "state", "container", "card",
-  "lambda", "kms", "secret", "alb", "ecs", "rds", "s3", "iam", "user", "browser",
-  "contract", "eoa", "multisig", "proxy", "library", "interface",
-]);
+const VALID_KIND_SET: ReadonlySet<string> = NODE_KIND_VALID;
 
 /**
  * 受け付ける図種。 **記法側と同じ集合を使う** (`v05/parser.ts` の `PRESET_TYPES`)。
@@ -206,6 +321,520 @@ const VALID_KIND_SET: ReadonlySet<string> = new Set([
  */
 const VALID_PRESETS: readonly PresetType[] = [...PRESET_TYPES];
 
+/**
+ * 受け付ける項目の一覧 (#1295)。 **知らない項目を誤りにする判定と、公開 schema との
+ * 突き合わせが、どちらもここを見る**。
+ *
+ * 一覧を型 / 検査 / schema の 3 箇所に手で置くと必ずどれかが古くなる。 型は TypeScript が
+ * 見る宣言で実行時には残らないため、実行時の判定と schema はこの表を出どころにする。
+ *
+ * 公開している JSON Schema は元から全階層で `additionalProperties: false` を宣言していた。
+ * 知らない項目を弾くのは新しい方針ではなく、parser が自分の契約に追いついていなかった。
+ *
+ * `states` / `values` / `tween` / `set` / `lanes` / `groups` の **鍵は利用者が決める**
+ * (状態の名前 / 縦列の id)。 表が縛るのはその中の値の形で、鍵そのものではない。
+ */
+export const ACCEPTED_KEYS = {
+  root: [
+    "title",
+    "type",
+    "eyebrow",
+    "axes",
+    "actors",
+    "flow",
+    "states",
+    "values",
+    "animation",
+    "viewport",
+    "lanes",
+    "groups",
+  ],
+  actor: [
+    "name",
+    "kind",
+    "subtitle",
+    "eyebrow",
+    "value",
+    "rows",
+    "lane",
+    "stack",
+    "initial",
+    "final",
+    "tone",
+    "color",
+    "owner",
+    "end",
+    "touchpoint",
+    "opportunity",
+    "posX",
+    "posY",
+    "posW",
+    "posH",
+    "nodes",
+    "scale",
+    "state",
+    "pos",
+  ],
+  step: [
+    "from",
+    "to",
+    "label",
+    "sub",
+    "tone",
+    "style",
+    "guard",
+    "cardinality",
+    "labelOffsetX",
+    "labelOffsetY",
+    "overlay",
+    "pos",
+  ],
+  phase: ["step", "duration", "focus", "body", "badge", "tween", "set", "draw"],
+  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"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** 受ける項目を持つ階層の名前 */
+export type 階層 = keyof typeof ACCEPTED_KEYS;
+
+/**
+ * 欄ごとの値の型 (#1304)。 **`ACCEPTED_KEYS` と同じ欄を必ず持つ**。
+ *
+ * 項目名の側は `#1295` で閉じたが、値の側は一部の欄にしか検査が無かった。 実測すると
+ * 20 欄が型違いの値をそのまま通し、`type: sequence` では 17 欄の値が図まで届いていた
+ * (`labelOffsetX: "q"` が矢印の中に `"q"` のまま入る、`tone: "bogus"` がそのまま色として載る)。
+ *
+ * 表を `ACCEPTED_KEYS` の隣に置き、下の `satisfies` で **欄が 1 つでも欠けたら型検査が落ちる**
+ * ようにする。 欄を足した時に「名前は受けるが値は見ない」 状態が作れない。
+ *
+ * ## 誰がどの欄を見るか
+ *
+ * | 型 | 見る場所 |
+ * |---|---|
+ * | 値そのものの型 (文字列 / 数 / 真偽 / 色 / 線種 等) | 本 file の `表で検査` |
+ * | `object` / `並び` | 欄ごとの専用の検査 (`validateViewport` 等) |
+ *
+ * 分けるのは、中身の形が欄ごとに違うから。 外側の形だけを表で見ても中身は見られないので、
+ * 専用の検査に任せて二重に誤りを出さない。 **専用の検査が抜けても表からは分からない** ため、
+ * 検査 (`test/json-value-types.test.ts`) が全欄に型違いの値を入れて誤りが返ることを確かめる。
+ */
+export type 欄の型 =
+  | "必須の非空文字列"
+  | "必須の文字列"
+  | "非空の文字列"
+  | "文字列"
+  | "文字列の並び"
+  | "数"
+  | "必須の数"
+  | "真偽"
+  | "色"
+  | "線種"
+  | "色か色番号"
+  | "描くもの"
+  | "必須の図種"
+  | "object"
+  | "並び"
+  | "必須の並び"
+  | "必須の非空の並び";
+
+export const 欄の型表 = {
+  root: {
+    title: "必須の非空文字列",
+    type: "必須の図種",
+    eyebrow: "文字列",
+    axes: "object",
+    actors: "必須の非空の並び",
+    flow: "必須の並び",
+    states: "object",
+    values: "object",
+    animation: "並び",
+    viewport: "object",
+    lanes: "object",
+    groups: "object",
+  },
+  actor: {
+    name: "必須の非空文字列",
+    kind: "非空の文字列",
+    subtitle: "文字列",
+    eyebrow: "文字列",
+    value: "文字列",
+    rows: "文字列の並び",
+    lane: "文字列",
+    stack: "数",
+    initial: "真偽",
+    final: "真偽",
+    tone: "色",
+    color: "色か色番号",
+    owner: "文字列",
+    end: "文字列",
+    touchpoint: "文字列",
+    opportunity: "文字列",
+    posX: "数",
+    posY: "数",
+    posW: "数",
+    posH: "数",
+    nodes: "object",
+    scale: "数",
+    state: "object",
+    pos: "object",
+  },
+  step: {
+    from: "必須の文字列",
+    to: "必須の文字列",
+    label: "必須の文字列",
+    sub: "文字列",
+    tone: "色",
+    style: "線種",
+    guard: "文字列",
+    cardinality: "文字列",
+    labelOffsetX: "数",
+    labelOffsetY: "数",
+    overlay: "真偽",
+    pos: "object",
+  },
+  phase: {
+    step: "必須の非空文字列",
+    duration: "数",
+    focus: "文字列の並び",
+    body: "文字列",
+    badge: "文字列",
+    tween: "object",
+    set: "object",
+    draw: "描くもの",
+  },
+  viewport: {
+    width: "数",
+    height: "数",
+    scale: "数",
+    laneWidth: "数",
+    gap: "数",
+    laneGap: "数",
+    nodeGap: "数",
+    labelMargin: "数",
+  },
+  lane: {
+    x: "数",
+    width: "数",
+    label: "文字列",
+    contain: "真偽",
+    lifeline: "真偽",
+    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: "必須の数" },
+} as const satisfies {
+  [層 in 階層]: { [欄 in (typeof ACCEPTED_KEYS)[層][number]]: 欄の型 };
+};
+
+/**
+ * 色番号の形 (#1304)。 公開 schema の `pattern` と同じ形を実装側でも 1 箇所に持つ。
+ *
+ * 受けるのは 3 / 4 / 6 / 8 桁 (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`)。 5 桁や 7 桁は
+ * CSS の色として成立しないため通さない。
+ */
+const 色番号の形 = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+/**
+ * JSON で色名として受ける値か (#1304、 review Round 2 の指摘)。
+ *
+ * **記法の `resolveTone` は通さない**。 あちらは前後の空白と引用符を落として小文字に寄せるが、
+ * それは記法の本文から語を切り出すために要る処理で、JSON には要らない。 JSON の値は既に
+ * 切り出された文字列なので、`" success "` や `"\"success\""` は書き手の意図ではなく
+ * 記法の癖が漏れた形になる。
+ *
+ * 公開 schema は色名を `enum` で宣言する。 `enum` は完全一致なので、**parser 側も完全一致に
+ * 揃える**。 揃えないと「schema が拒む値を parser が受ける」 ずれが残り、本 file が閉じようと
+ * している宣言と実装の食い違いを別の形で作ることになる。
+ *
+ * 揃え方は 2 通りあった。 schema を parser に合わせて広げる案は、大文字小文字と空白と引用符を
+ * `pattern` で書くことになり、**色名の一覧が `enum` と `pattern` の 2 か所に写る**。 色が増えた
+ * 時に片方だけ直る形を作るため採らなかった。 同じ理由で、この判定は `tone` (箱と矢印) と
+ * `color` の 3 欄すべてが共有する。
+ */
+function JSONの色名か(v: string): boolean {
+  return 書ける色名().includes(v);
+}
+
+/**
+ * 見本 (parts) にしか効かない欄 (#1294)。
+ *
+ * 普通の箱に書くと `jsonToDoc` が落とすため、書いても何も起きない。 #1294 で誤りにした。
+ *
+ * `見本に効かない欄` (#1308) と対になる。 2 つの表で「どちらの箱にしか効かないか」 を
+ * 両方向から宣言する = 片方だけ増えると鏡の関係が崩れる。
+ */
+export const 見本にしか効かない欄 = ["state", "scale"] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
+
+/**
+ * 普通の箱にしか効かない欄 (#1308)。
+ *
+ * 見本 (parts) の箱に書くと `jsonToDoc` が丸ごと落とす。 検査を通ったうえで値が消えるため、
+ * 書いた人には「書いたのに図が変わらない」 としか見えない (実測 = 5 欄すべてが消えていた)。
+ *
+ * 記法では同じ本文が状態の上書きに入る。 特別扱いしているのではなく、見本の中括弧に書いた
+ * 名前を **すべて** 状態の上書きとして読むため、結果として届いている。 JSON は欄ごとに型を
+ * 宣言する形なので同じ設計を持ち込めない。
+ *
+ * したがって **誤りとして返す**。 #1294 が決めた向き (見本にしか効かない `state` / `scale` を
+ * 普通の箱に書いたら誤り) の鏡になる。 効く書き方は `state` が既に持つため、誤りにしても
+ * 利用者の手段は失われない。
+ *
+ * **この表は検査と組み立ての両方が見る**。 落とす欄と誤りにする欄が別々に並ぶと、片方だけ
+ * 増えた時に「検査は通すが組み立てが捨てる」 状態が戻る。
+ */
+export const 見本に効かない欄 = [
+  "tone",
+  "owner",
+  "end",
+  "touchpoint",
+  "opportunity",
+] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
+
+/**
+ * 表に沿って 1 つの欄の値を見る (#1304)。
+ *
+ * `名前` は知らせの文に出す欄の呼び名 (`actor.tone` / `viewport.width`)。 `path` は直す場所を
+ * 指す JSON pointer 風の文字列で、この 2 つは役割が違う (前者は「何の欄か」、後者は「どこか」)。
+ */
+function 値を検査(
+  v: unknown,
+  型: 欄の型,
+  path: string,
+  名前: string,
+  errors: JsonDslError[],
+): void {
+  const 型違い = (期待: string, 補足?: string): void => {
+    errors.push({
+      path,
+      message: `${名前} must be ${期待}`,
+      hint: 補足 ?? `got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}`,
+    });
+  };
+  switch (型) {
+    case "必須の非空文字列":
+      if (typeof v !== "string" || v.length === 0) 型違い("a non-empty string");
+      return;
+    case "必須の文字列":
+      if (typeof v !== "string") 型違い("a string");
+      return;
+    case "非空の文字列":
+      if (v === undefined) return;
+      if (typeof v !== "string" || v.length === 0) 型違い("a non-empty string if present");
+      return;
+    case "文字列":
+      if (v === undefined) return;
+      if (typeof v !== "string") 型違い("a string if present");
+      return;
+    case "文字列の並び":
+      if (v === undefined) return;
+      if (!Array.isArray(v)) {
+        型違い("an array of strings if present");
+        return;
+      }
+      // 要素の場所まで指す。 並び全体を指すと、どれを直せばよいか読めない
+      v.forEach((要素, i) => {
+        if (typeof 要素 !== "string") {
+          errors.push({
+            path: `${path}[${i}]`,
+            message: `${名前}[${i}] must be a string`,
+            hint: `got ${要素 === null ? "null" : typeof 要素}`,
+          });
+        }
+      });
+      return;
+    case "数":
+      if (v === undefined) return;
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        型違い(
+          "a finite number if present",
+          typeof v === "number" ? `got ${String(v)}` : undefined,
+        );
+      }
+      return;
+    case "必須の数":
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        型違い("a finite number", typeof v === "number" ? `got ${String(v)}` : undefined);
+      }
+      return;
+    case "真偽":
+      if (v === undefined) return;
+      if (typeof v !== "boolean") 型違い("true or false if present");
+      return;
+    case "色":
+      if (v === undefined) return;
+      if (typeof v !== "string") {
+        型違い("a color name if present");
+        return;
+      }
+      // 別名 (`成功` / `neutral`) も受ける。 一覧は engine から取る
+      if (!JSONの色名か(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be a known color name`,
+          hint: `使える値 = ${書ける色名().join(", ")} (got ${JSON.stringify(v)})`,
+        });
+      }
+      return;
+    case "線種":
+      if (v === undefined) return;
+      if (typeof v !== "string" || !STYLE_VALID.has(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${[...STYLE_VALID].join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : `got ${typeof v}`,
+        });
+      }
+      return;
+    case "描くもの":
+      if (v === undefined) return;
+      // 受ける語は記法と同じ一覧を見る (`DRAW_WORDS`)。 写すと語が増えた時に片方だけ古くなる
+      if (typeof v !== "string" || !DRAW_WORDS.has(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${[...DRAW_WORDS].join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : `got ${typeof v}`,
+        });
+      }
+      return;
+    case "色か色番号":
+      if (v === undefined) return;
+      if (typeof v !== "string") {
+        型違い("a color name or a #hex value if present");
+        return;
+      }
+      // 振り分けは記法と同じ (`splitColorValue`)。 `#` で始まれば色番号、それ以外は色の名前
+      if (v.startsWith("#")) {
+        if (!色番号の形.test(v)) {
+          errors.push({
+            path,
+            message: `${名前} must be a #hex color`,
+            hint: `\`#f59e0b\` の形で書く (got ${JSON.stringify(v)})`,
+          });
+        }
+        return;
+      }
+      if (!JSONの色名か(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be a known color name or a #hex value`,
+          hint: `使える値 = ${書ける色名().join(", ")} / \`#f59e0b\` (got ${JSON.stringify(v)})`,
+        });
+      }
+      return;
+    case "必須の図種":
+      if (typeof v !== "string" || !VALID_PRESETS.includes(v as PresetType)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${VALID_PRESETS.join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : undefined,
+        });
+      }
+      return;
+    case "object":
+    case "並び":
+    case "必須の並び":
+    case "必須の非空の並び":
+      // 中身の形が欄ごとに違うため専用の検査が見る (`validateViewport` / `validateStates` 等)。
+      // ここで外側の形も見ると、同じ入力に 2 つ誤りが出てどちらを直せばよいか読めなくなる
+      return;
+  }
+  // 型を足して `case` を書き忘れると、その型の欄が黙って素通りする。 網羅を型検査で固定する
+  型 satisfies never;
+}
+
+/**
+ * 1 つの階層の欄をまとめて見る (#1304)。
+ *
+ * `名前接頭` は知らせの文に出す呼び名の前半 (`actor` / `viewport` / `lanes.web`)。 空文字なら
+ * 欄名だけを出す (最上位の `title` 等)。
+ */
+function 表で検査(
+  o: Record<string, unknown>,
+  層: 階層,
+  path: string,
+  名前接頭: string,
+  errors: JsonDslError[],
+): void {
+  // 表が `ACCEPTED_KEYS` と同じ欄を持つことは `欄の型表` の `satisfies` が固定する。 欄を
+  // 足して型を書き忘れると型検査が落ちるため、ここでは欠落を扱わない
+  for (const [欄, 型] of Object.entries<欄の型>(欄の型表[層])) {
+    値を検査(o[欄], 型, `${path}.${欄}`, 名前接頭 === "" ? 欄 : `${名前接頭}.${欄}`, errors);
+  }
+}
+
+/**
+ * 綴り違いの候補を返す (#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)。
+ *
+ * 対象は plain object だけ。 形が違う入力は呼出側が別に誤りを積むため、ここでは何もしない
+ * (同じ入力に 2 つの誤りを出すと、どちらを直せばよいか読めなくなる)。
+ */
+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>)) {
+    if (受ける.includes(key)) continue;
+    const 候補 = 近い項目名(key, 受ける);
+    errors.push({
+      path: `${path}.${key}`,
+      message: `unknown key "${key}"`,
+      hint: 候補 !== undefined ? `"${候補}" のことですか` : `使える項目 = ${受ける.join(", ")}`,
+    });
+  }
+}
+
 /**
  * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
  * fail-fast ではなく全 error 収集して返す (LLM に一括で修正させるため)。
@@ -221,11 +850,125 @@ function validateLayoutPos(v: unknown, path: string, errors: JsonDslError[]): vo
     return;
   }
   const p = v as Record<string, unknown>;
-  if (typeof p.x !== "number" || !Number.isFinite(p.x)) {
-    errors.push({ path: `${path}.x`, message: "pos.x must be a finite number" });
+  checkUnknownKeys(p, "layoutPos", path, errors);
+  表で検査(p, "layoutPos", path, "pos", errors);
+}
+
+/**
+ * 見本 (parts) の名前として扱う値かどうか (#1294)。
+ *
+ * 判定は `jsonToDoc` と同じにする。 別々に書くと、検査が「見本でない」 と見た箱を
+ * 組み立て側が見本として扱う形ができ、見本にしか効かない項目の誤り判定がずれる。
+ */
+function 見本の名前か(kind: unknown): boolean {
+  if (typeof kind !== "string" || kind.length === 0) return false;
+  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;
   }
-  if (typeof p.y !== "number" || !Number.isFinite(p.y)) {
-    errors.push({ path: `${path}.y`, message: "pos.y must be a finite number" });
+  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)。
+ *
+ * これまで `viewport` は検査そのものが無く、中身を丸ごと写していた
+ * (`{ ...json.viewport }`)。 型にも schema にも無い `scale` が素通しで効いていた一方、
+ * 数でない値を書いても誰も止めなかった。
+ */
+function validateViewport(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({ path: "$.viewport", message: "viewport must be a plain object" });
+    return;
+  }
+  checkUnknownKeys(v, "viewport", "$.viewport", errors);
+  表で検査(v as Record<string, unknown>, "viewport", "$.viewport", "viewport", errors);
+}
+
+/**
+ * 鍵を利用者が決める入れ物 (縦列 / 群) を見る (#1304)。
+ *
+ * `lanes` / `groups` は id を鍵に持つため、鍵そのものは縛れない。 縛れるのは
+ * 「入れ物が plain object か」 と「各 id の中身の項目名と値の型」 の 2 つ。
+ *
+ * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
+ * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
+ */
+function validateIdMap(
+  v: unknown,
+  欄: "lanes" | "groups",
+  層: 階層,
+  errors: JsonDslError[],
+  中身を見る: (o: Record<string, unknown>, id: string, path: string) => void,
+): void {
+  if (v === undefined) return;
+  const path = `$.${欄}`;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({
+      path,
+      message: `${欄} must be a plain object of id -> settings`,
+      hint: `got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}`,
+    });
+    return;
+  }
+  for (const [id, 中] of Object.entries(v as Record<string, unknown>)) {
+    const idPath = `${path}.${id}`;
+    if (!中 || typeof 中 !== "object" || Array.isArray(中)) {
+      errors.push({
+        path: idPath,
+        message: `${欄}.${id} must be a plain object`,
+        hint: `got ${中 === null ? "null" : Array.isArray(中) ? "array" : typeof 中}`,
+      });
+      continue;
+    }
+    const o = 中 as Record<string, unknown>;
+    checkUnknownKeys(o, 層, idPath, errors);
+    中身を見る(o, id, idPath);
+  }
+}
+
+/** 2 軸で仕分ける図の軸の名前を見る (#1294) */
+function validateAxes(v: unknown, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({
+      path: "$.axes",
+      message: "axes must be a plain object like { x: { left, right }, y: { bottom, top } }",
+    });
+    return;
+  }
+  const 軸 = v as Record<string, unknown>;
+  checkUnknownKeys(軸, "axes", "$.axes", errors);
+  const 層の名 = { x: "axesX", y: "axesY" } as const;
+  for (const 名 of ["x", "y"] as const) {
+    const 一方 = 軸[名];
+    if (一方 === undefined) continue;
+    if (!一方 || typeof 一方 !== "object" || Array.isArray(一方)) {
+      errors.push({ path: `$.axes.${名}`, message: `axes.${名} must be a plain object` });
+      continue;
+    }
+    const o = 一方 as Record<string, unknown>;
+    checkUnknownKeys(o, 層の名[名], `$.axes.${名}`, errors);
+    表で検査(o, 層の名[名], `$.axes.${名}`, `axes.${名}`, errors);
   }
 }
 
@@ -309,8 +1052,14 @@ class 写せない extends Error {
  *
  * 線を引くのは、 5 round にわたって「読む前に量を作れる経路」 を潰し続けた末に、 残りが
  * 呼ぶ側の code の中に移ったため。 潰す対象が自分の外に出た時点で、 この関数の責務ではない。
+ *
+ * **test のために export する** (#1295)。 写しの性質 (深さ / 数の上限 / 読む順 / 値を返す
+ * 関数の扱い) を確かめる検査は、以前は「検査が見ない項目」 に構造をぶら下げて
+ * `validateDragonJson` 越しに見ていた。 知らない項目を誤りにしたことでその足場が無くなり、
+ * かつ写しは検査より前に走るため、検査の結果からは写しの中身を取り出せない。
+ * 検査の対象そのものを直接呼ぶ形にする。
  */
-function 素のデータに写す(
+export function 素のデータに写す(
   root: unknown,
 ): { ok: true; value: unknown } | { ok: false; error: JsonDslError } {
   const 写し済 = new WeakMap<object, unknown[] | Record<string, unknown>>();
@@ -338,11 +1087,7 @@ function 素のデータに写す(
   };
 
   /** 入れ物だけ作る (ここでは降りない)。 新しく作った時だけ枠を返す */
-  const 器を作る = (
-    v: unknown,
-    深さ: number,
-    path: string,
-  ): { 値: unknown; 枠: 枠 | null } => {
+  const 器を作る = (v: unknown, 深さ: number, path: string): { 値: unknown; 枠: 枠 | null } => {
     項目数 += 1;
     if (項目数 > 写しの最大の項目数) {
       throw new 写せない(path, `項目が多すぎる (上限 ${写しの最大の項目数})`);
@@ -449,7 +1194,9 @@ function 素のデータに写す(
   }
 }
 
-function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: false; errors: JsonDslError[] } {
+function validateJson(
+  json: unknown,
+): { ok: true; data: DragonJson } | { ok: false; errors: JsonDslError[] } {
   const errors: JsonDslError[] = [];
   // root の形は写しより先に見る = 形が違う入力には従来どおり `root must be a JSON object` を
   // 返すため。 写した後に見ると、 root が配列の入力で中の getter が先に動き、 別の誤りに化ける
@@ -481,25 +1228,14 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
   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' });
-  }
-  if (typeof j.type !== "string" || !VALID_PRESETS.includes(j.type as PresetType)) {
-    errors.push({
-      path: "$.type",
-      message: `type must be one of: ${VALID_PRESETS.join(", ")}`,
-      hint: typeof j.type === "string" ? `got "${j.type}"` : undefined,
-    });
-  }
+  // 知らない項目を先に見る (#1295)。 綴り違いは「書いた項目が効かない」 形で表に出るため、
+  // 個々の型の誤りより先に伝える方が直しやすい
+  checkUnknownKeys(j, "root", "$", errors);
+
+  // 値そのものの型は表が見る (#1304)。 図表の箱の上の小見出し (#1247) の空文字は
+  // 「書かなかった」 と同じ扱いにするため通す (記法側の `eyebrow:` と揃える。 落とすのは `jsonToDoc`)
+  表で検査(j, "root", "$", "", errors);
+
   if (!Array.isArray(j.actors) || j.actors.length === 0) {
     errors.push({ path: "$.actors", message: "actors must be a non-empty array" });
   } else {
@@ -510,19 +1246,49 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
         return;
       }
       const ao = a as Record<string, unknown>;
-      if (typeof ao.name !== "string" || ao.name.length === 0) {
-        errors.push({ path: `$.actors[${i}].name`, message: "actor.name must be a non-empty string" });
+      checkUnknownKeys(ao, "actor", `$.actors[${i}]`, errors);
+      // 値そのものの型は表が見る (#1304)。 `kind` は見本 (parts) の名前も受けるため
+      // 非空の文字列までしか縛らない (CAR-1657 の unified syntax)
+      表で検査(ao, "actor", `$.actors[${i}]`, "actor", errors);
+      // 見本 (parts) にしか効かない項目は、見本でない箱に書かれたら誤りにする (#1294)。
+      // 記法側は読めない項目名として行番号付きで知らせるため、黙って捨てると入口で扱いが変わる。
+      const 見本か = 見本の名前か(ao.kind);
+      // 見本にしか効かない欄を普通の箱に書いた形 (#1294)。 一覧は表が持つ
+      const 代わりに使う欄: Record<(typeof 見本にしか効かない欄)[number], string> = {
+        state: "箱の見た目を変えるなら tone / color を使う",
+        scale: "大きさを変えるなら posW / posH を使う",
+      };
+      if (!見本か) {
+        for (const 欄 of 見本にしか効かない欄) {
+          if (ao[欄] === undefined) continue;
+          errors.push({
+            path: `$.actors[${i}].${欄}`,
+            message: `actor.${欄} is only for parts (kind must be a parts identifier)`,
+            hint: 代わりに使う欄[欄],
+          });
+        }
       }
-      // CAR-1657 (+ codex-review MAJOR fix) = kind の validation、 non-empty string 必須。
-      // parts identifier or existing NodeKind のどちらかを想定、 空文字 or 非 string は reject。
-      if (ao.kind !== undefined && (typeof ao.kind !== "string" || ao.kind.length === 0)) {
-        errors.push({ path: `$.actors[${i}].kind`, message: "actor.kind must be a non-empty string" });
+      // 逆向きも同じく誤りにする (#1308)。 普通の箱にしか効かない欄を見本に書くと、
+      // `jsonToDoc` が丸ごと落として何も起きない
+      if (見本か) {
+        for (const 欄 of 見本に効かない欄) {
+          if (ao[欄] === undefined) continue;
+          errors.push({
+            path: `$.actors[${i}].${欄}`,
+            message: `actor.${欄} is not for parts (kind is a parts identifier)`,
+            hint: `見本の状態を変えるなら state を使う (\`"state": { "${欄}": ... }\`)`,
+          });
+        }
       }
+      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 崩れる。
       if (ao.state !== undefined) {
         if (!ao.state || typeof ao.state !== "object" || Array.isArray(ao.state)) {
-          errors.push({ path: `$.actors[${i}].state`, message: "actor.state must be a plain object" });
+          errors.push({
+            path: `$.actors[${i}].state`,
+            message: "actor.state must be a plain object",
+          });
         } else {
           for (const [sk, sv] of Object.entries(ao.state as Record<string, unknown>)) {
             const svType = typeof sv;
@@ -548,21 +1314,26 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
         return;
       }
       const so = s as Record<string, unknown>;
-      if (typeof so.from !== "string") errors.push({ path: `$.flow[${i}].from`, message: "step.from must be a string" });
-      if (typeof so.to !== "string") errors.push({ path: `$.flow[${i}].to`, message: "step.to must be a string" });
-      if (typeof so.label !== "string") errors.push({ path: `$.flow[${i}].label`, message: "step.label must be a string" });
+      checkUnknownKeys(so, "step", `$.flow[${i}]`, errors);
+      // 値そのものの型は表が見る (#1304)。 色と線種は engine の一覧と突き合わせる
+      表で検査(so, "step", `$.flow[${i}]`, "step", errors);
       // CAR-1693 Phase 1: step DSL 表面 pos の validation
       validateLayoutPos(so.pos, `$.flow[${i}].pos`, errors);
     });
   }
-  // CAR-1693 Phase 1: lane DSL 表面 pos の validation
-  if (j.lanes !== undefined && j.lanes && typeof j.lanes === "object" && !Array.isArray(j.lanes)) {
-    for (const [laneId, lane] of Object.entries(j.lanes as Record<string, unknown>)) {
-      if (lane && typeof lane === "object" && !Array.isArray(lane)) {
-        validateLayoutPos((lane as Record<string, unknown>).pos, `$.lanes.${laneId}.pos`, errors);
-      }
-    }
-  }
+  validateViewport(j.viewport, errors);
+  // 縦列と群は **鍵を利用者が決める** (id)。 表が縛るのはその中の項目
+  //
+  // #1304 まで外側の形すら見ておらず、`lanes: 5` のような値が誤りにならないまま素通りしていた
+  // (形が違えば中の走査ごと飛ばす書き方だったため)。 形が違う値は黙って捨てない
+  validateIdMap(j.lanes, "lanes", "lane", errors, (lane, laneId, path) => {
+    表で検査(lane, "lane", path, `lanes.${laneId}`, errors);
+    // CAR-1693 Phase 1: lane DSL 表面 pos の validation
+    validateLayoutPos(lane.pos, `${path}.pos`, errors);
+  });
+  validateIdMap(j.groups, "groups", "group", errors, (group, groupId, path) => {
+    表で検査(group, "group", path, `groups.${groupId}`, errors);
+  });
   if (j.animation !== undefined) {
     if (!Array.isArray(j.animation)) {
       errors.push({ path: "$.animation", message: "animation must be an array if present" });
@@ -573,15 +1344,16 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
           return;
         }
         const po = p as Record<string, unknown>;
-        if (typeof po.step !== "string" || po.step.length === 0) {
-          errors.push({ path: `$.animation[${i}].step`, message: "phase.step must be a non-empty string" });
-        }
+        checkUnknownKeys(po, "phase", `$.animation[${i}]`, errors);
+        // 値そのものの型は表が見る (#1304)
+        表で検査(po, "phase", `$.animation[${i}]`, "phase", errors);
         validatePhaseMotion(po, i, errors);
       });
     }
   }
   validateStates(j.states, errors);
   validateValues(j.values, errors);
+  validateAxes(j.axes, errors);
   if (errors.length > 0) return { ok: false, errors };
   return { ok: true, data: j as unknown as DragonJson };
 }
@@ -592,11 +1364,7 @@ function validateJson(json: unknown): { ok: true; data: DragonJson } | { ok: fal
  * 状態名の記法は `states:` と同じ判定を使う。 参照先はこの JSON の `states` だけでは決めない。
  * 見本や preset が持つ状態を動かす指定もあるためで、記法側と同じく compile 後の図で解決する。
  */
-function validatePhaseMotion(
-  po: Record<string, unknown>,
-  i: number,
-  errors: JsonDslError[],
-): void {
+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({
@@ -615,7 +1383,11 @@ function validatePhaseMotion(
         // 段の途中が壊れる (記法側も数だけを受ける)
         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}` });
+            errors.push({
+              path,
+              message: "tween value must be finite numbers",
+              hint: `got ${typeof v}`,
+            });
             break;
           }
         }
@@ -653,7 +1425,10 @@ function validatePhaseMotion(
 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" });
+    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>)) {
@@ -684,7 +1459,10 @@ function validateStates(v: unknown, errors: JsonDslError[]): void {
 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" });
+    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>)) {
@@ -732,9 +1510,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     // CAR-1657 = kind が既存 NodeKind に無い値なら parts identifier 候補、 partId に格納
     const kindStr = (a.kind ?? "actor") as string;
     const isPart = kindStr !== "actor" && !VALID_KIND_SET.has(kindStr);
+    // 色は記法と同じ振り分けを通す (#1294)。 `#` で始まれば色番号、それ以外は色の名前。
+    // 別々に書くと、同じ値が入口によって色番号にも色名にもなる
+    const 色 = a.color !== undefined ? splitColorValue(a.color) : {};
     return {
       name: a.name,
-      kind: isPart ? "actor" as NodeKind : (a.kind ?? "actor") as NodeKind,
+      kind: isPart ? "actor" : resolveNodeKind(kindStr),
       // parts 候補は `kind` を `actor` に倒して `partId` へ退避するため、 名札に載せる種類としては
       // 「書かなかった」 と同じ扱いにする (#1058)
       kindWritten: a.kind !== undefined && !isPart,
@@ -746,6 +1527,37 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       stack: a.stack,
       initial: a.initial,
       final: a.final,
+      // 普通の箱にしか効かない欄は見本では落とす。 落とす欄の一覧は `見本に効かない欄` が
+      // 唯一の出どころで、検査 (#1308) も同じ表を見る = 「検査は通すが組み立てが捨てる」
+      // 状態が作れない
+      ...(isPart
+        ? {}
+        : {
+            tone: resolveTone(a.tone) ?? 色.tone,
+            owner: a.owner,
+            end: a.end,
+            touchpoint: a.touchpoint,
+            opportunity: a.opportunity,
+          }),
+      colorHex: 色.hex,
+      // 絶対座標と大きさ (#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,
       // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos の 2 層 mapping (naming collision 回避)
@@ -759,7 +1571,9 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     to: s.to,
     label: s.label,
     sub: s.sub,
-    tone: s.tone,
+    // 箱と同じ読み替えを通す (#1304)。 通さないと `tone: "成功"` が色名として解決されないまま
+    // 図に届き、同じ値が箱では色になり矢印では色にならない
+    tone: resolveTone(s.tone),
     style: s.style,
     guard: s.guard,
     cardinality: s.cardinality,
@@ -783,11 +1597,18 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     highlight: p.focus,
     body: p.body,
     badge: p.badge,
+    // 書いた段だけが欄を持つ。 空文字を置くと「書いた」 と「書いていない」 が同じ形になる
+    ...(p.draw !== undefined ? { draw: p.draw, drawPos: p0 } : {}),
     // 段の中で動かす分 (#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 })),
+          tweens: Object.entries(p.tween).map(([state, [from, to]]) => ({
+            state,
+            from,
+            to,
+            pos: p0,
+          })),
         }
       : {}),
     ...(p.set && Object.keys(p.set).length > 0
@@ -806,6 +1627,11 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     ...(整えた小見出し(json.eyebrow) !== undefined
       ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: p0 }
       : {}),
+    // 2 軸で仕分ける図の軸の名前 (#1294)。 中身の無い形は「書かなかった」 と同じにする =
+    // 空の軸を渡すと、書いていない側の名前が空文字で描かれる (記法側と同じ扱い)
+    ...(json.axes && (json.axes.x !== undefined || json.axes.y !== undefined)
+      ? { axes: json.axes, axesPos: p0 }
+      : {}),
     actors,
     flow,
     animate,
@@ -827,11 +1653,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       : undefined,
     groups: json.groups
       ? Object.fromEntries(
-          Object.entries(json.groups).map(([id, g]) => [id, { id, label: g.label, lanes: g.lanes, pos: p0 }]),
+          Object.entries(json.groups).map(([id, g]) => [
+            id,
+            { id, label: g.label, lanes: g.lanes, pos: p0 },
+          ]),
         )
       : undefined,
-    // CAR-1693 Phase 1: diagram-level layout mode (auto|manual)、 未指定は undefined = auto default
-    layout: json.layout,
     pos: p0,
   };
 }
@@ -866,7 +1693,9 @@ export function jsonToDiagram(
 ): CdlDiagram {
   const v = validateJson(json);
   if (!v.ok) {
-    const msg = v.errors.map((e) => `  ${e.path}: ${e.message}${e.hint ? ` (${e.hint})` : ""}`).join("\n");
+    const msg = v.errors
+      .map((e) => `  ${e.path}: ${e.message}${e.hint ? ` (${e.hint})` : ""}`)
+      .join("\n");
     throw new Error(`Dragon JSON DSL validation error:\n${msg}`);
   }
   const doc = jsonToDoc(v.data);