@cardenelabs/dragon 0.8.0 → 0.9.0

package/src/v05/parser.ts

@@ -43,7 +43,7 @@
 
 import type { NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
 import { TONES, NODE_KINDS } from "@cardenelabs/cdl";
-import { TONE_ALIAS } from "../keywords";
+import { TONE_ALIAS, NODE_KIND_ALIAS } from "../keywords";
 import { parseRelativePos, orderByDependency } from "../relative-pos";
 import {
   checkValueExpression,
@@ -71,9 +71,7 @@ import type {
   DslViewport,
 } from "../types";
 
-export type V05ParseResult =
-  | { ok: true; doc: DslDocument }
-  | { ok: false; errors: DslError[] };
+export type V05ParseResult = { ok: true; doc: DslDocument } | { ok: false; errors: DslError[] };
 
 /**
  * 記法が受ける top-level の項目 (#1190)。
@@ -83,7 +81,16 @@ export type V05ParseResult =
  * 一覧に 1 件も無い状態で放置されていた)。
  */
 export const TOP_LEVEL_KEYS = [
-  "title", "type", "actors", "flow", "states", "values", "animation", "viewport", "lanes", "groups",
+  "title",
+  "type",
+  "actors",
+  "flow",
+  "states",
+  "values",
+  "animation",
+  "viewport",
+  "lanes",
+  "groups",
   // 図全体を 1 箱にする図種で、 その箱の上に出す小見出し (#1247)
   "eyebrow",
   // 2 軸で仕分ける図の軸の名前 (#1251)
@@ -145,8 +152,14 @@ const NODE_KIND_DEFAULT: NodeKind = "actor";
  * 種類に置き換わるため、 そのまま描画側に渡ることはない。
  */
 const DSL_ONLY_KINDS = [
-  "entity", "state",
-  "contract", "eoa", "multisig", "proxy", "library", "interface",
+  "entity",
+  "state",
+  "contract",
+  "eoa",
+  "multisig",
+  "proxy",
+  "library",
+  "interface",
 ] as const;
 
 /**
@@ -160,17 +173,17 @@ const DSL_ONLY_KINDS = [
  * 保管する役)。 見た目が同じになるが、 役割が同じなので嘘にはならない。
  */
 const INFRA_KIND_ALIAS: Record<string, NodeKind> = {
-  alb: "shape-api-gateway",   // 入口で振り分ける
-  browser: "frontend",         // 画面側
-  ecs: "microservice",         // コンテナ群
-  iam: "admin",                // 権限を守る
-  kms: "admin",                // 鍵を守る
-  lambda: "function",          // 呼ぶと動く
-  rds: "database",             // 表を持つ
-  s3: "storage",               // 置き場
-  secret: "storage",           // 機密の置き場
-  user: "person",              // 人
-  container: "service",        // 動かす単位 (C4 の container)
+  alb: "shape-api-gateway", // 入口で振り分ける
+  browser: "frontend", // 画面側
+  ecs: "microservice", // コンテナ群
+  iam: "admin", // 権限を守る
+  kms: "admin", // 鍵を守る
+  lambda: "function", // 呼ぶと動く
+  rds: "database", // 表を持つ
+  s3: "storage", // 置き場
+  secret: "storage", // 機密の置き場
+  user: "person", // 人
+  container: "service", // 動かす単位 (C4 の container)
 };
 
 /**
@@ -195,7 +208,52 @@ export const NODE_KIND_VALID: ReadonlySet<string> = new Set<string>([
 // 受理する色名は cdl 側の一覧をそのまま使う。 手書きすると cdl に色が増えた時に取り残される。
 const TONE_VALID: ReadonlySet<string> = new Set<string>(TONES);
 
-const STYLE_VALID: ReadonlySet<string> = new Set<string>(["solid", "dotted-flow"]);
+/**
+ * 受理する線種。 `EdgeStyle` は型だけで実体を持たないため、 実行時の一覧はここが唯一の出どころ。
+ *
+ * JSON 経路も同じ集合を読む (#1304)。 別に持つと、 線種が増えた時に片方だけ取り残される。
+ */
+export const STYLE_VALID: ReadonlySet<string> = new Set<string>(["solid", "dotted-flow"]);
+
+/**
+ * 色の名前として書ける語の一覧 (#1304)。 知らせの `hint` に出す。
+ *
+ * 正規の色名 (`TONES`) と別名 (`TONE_ALIAS` の鍵) を合わせる。 手で並べると色が増えた時に
+ * 取り残されるため、 どちらも実装の集合から導く。
+ */
+export function 書ける色名(): string[] {
+  return [...new Set<string>([...TONES, ...Object.keys(TONE_ALIAS)])];
+}
+
+/**
+ * 色名として読めない値を知らせる (#1304)。
+ *
+ * 線種を受ける場所 (矢印) と受けない場所 (箱) で hint を変える。 箱に `solid` と書いても
+ * 効かないため、 使える語として案内しない。
+ *
+ * 矢印の丸括弧には、 説明文の一部が入り込むことがある
+ * (`- A -> B: 呼び出し (非同期)` の `非同期`)。 これまでは黙って捨てられ、 **説明文から
+ * 括弧の中だけが消えた図** が出ていた。 直し方が「別の語に変える」 とは限らないため、
+ * 引用符で囲む道も併せて案内する。
+ */
+function report読めない色(
+  値: string,
+  line: number,
+  errors: DslError[],
+  opts: { 線種も受ける: boolean },
+): void {
+  const 語 = stripQuotes(値.trim());
+  const 使える = opts.線種も受ける ? [...書ける色名(), ...STYLE_VALID] : 書ける色名();
+  errors.push({
+    line,
+    message: opts.線種も受ける
+      ? `色名か線種が読めません: "${語}"`
+      : `色の名前が読めません: "${語}"`,
+    hint: opts.線種も受ける
+      ? `使える値 = ${使える.join(", ")}。 説明文に括弧を含めるなら \`"…"\` で囲む`
+      : `使える値 = ${使える.join(", ")}`,
+  });
+}
 
 type Line = {
   raw: string;
@@ -280,7 +338,7 @@ export function parseTextDslV05(src: string): V05ParseResult {
           errors.push({
             line: entry[0]!.no,
             message: `invalid actor entry: "${entry[0]!.trimmed}"`,
-            hint: 'use `- Client` or `- Client: storage`',
+            hint: "use `- Client` or `- Client: storage`",
           });
           continue;
         }
@@ -294,7 +352,7 @@ export function parseTextDslV05(src: string): V05ParseResult {
       const { items, next } = collectIndentedList(lines, i + 1, line.indent);
       let stepNo = 1;
       for (const it of items) {
-        const step = parseFlowStep(it, stepNo);
+        const step = parseFlowStep(it, stepNo, errors);
         if (step) {
           flow.push(step);
           stepNo += 1;
@@ -327,7 +385,12 @@ export function parseTextDslV05(src: string): V05ParseResult {
       for (const it of items) {
         const st = parseStateEntry(it.trimmed.replace(/^-\s*/, ""), it.no);
         if (st) animate.states.push(st);
-        else errors.push({ line: it.no, message: `invalid state entry: "${it.trimmed}"`, hint: "use `name: initial`" });
+        else
+          errors.push({
+            line: it.no,
+            message: `invalid state entry: "${it.trimmed}"`,
+            hint: "use `name: initial`",
+          });
       }
       i = next;
       continue;
@@ -379,14 +442,7 @@ export function parseTextDslV05(src: string): V05ParseResult {
       if (inline && inline.startsWith("{") && inline.endsWith("}")) {
         const opts = parseInlineMapping(inline.slice(1, -1));
         viewport = {
-          width: numberOrUndef(opts.width),
-          height: numberOrUndef(opts.height),
-          laneWidth: numberOrUndef(opts.laneWidth),
-          gap: numberOrUndef(opts.gap),
-          laneGap: numberOrUndef(opts.laneGap),
-          nodeGap: numberOrUndef(opts.nodeGap),
-          scale: numberOrUndef(opts.scale),
-          labelMargin: numberOrUndef(opts.labelMargin),
+          ...表で読む(VIEWPORT_VALUE_KINDS, opts, "viewport の ", line.no, errors),
           pos: { line: line.no },
         };
         i += 1;
@@ -395,19 +451,24 @@ export function parseTextDslV05(src: string): V05ParseResult {
       // block: viewport:\n  width: 1400\n  height: 900\n  ...
       const { items, next } = collectIndentedList(lines, i + 1, line.indent);
       const opts: Record<string, string> = {};
+      // 知らせは **値を書いた行** を指す (#1306)。 `viewport:` の行を指すと、欄が縦に並ぶ形で
+      // どの行を直せばよいか分からない
+      const optLines: Record<string, number> = {};
       for (const it of items) {
         const m = it.trimmed.match(/^([a-zA-Z][a-zA-Z0-9_]*)\s*:\s*(.+)$/);
-        if (m) opts[m[1]!] = stripQuotes(m[2]!.trim());
+        if (!m) continue;
+        const 欄 = m[1] ?? "";
+        opts[欄] = stripQuotes((m[2] ?? "").trim());
+        optLines[欄] = it.no;
       }
       viewport = {
-        width: numberOrUndef(opts.width),
-        height: numberOrUndef(opts.height),
-        laneWidth: numberOrUndef(opts.laneWidth),
-        gap: numberOrUndef(opts.gap),
-        laneGap: numberOrUndef(opts.laneGap),
-        nodeGap: numberOrUndef(opts.nodeGap),
-        scale: numberOrUndef(opts.scale),
-        labelMargin: numberOrUndef(opts.labelMargin),
+        ...表で読む(
+          VIEWPORT_VALUE_KINDS,
+          opts,
+          "viewport の ",
+          (欄) => optLines[欄] ?? line.no,
+          errors,
+        ),
         pos: { line: line.no },
       };
       i = next;
@@ -463,11 +524,8 @@ export function parseTextDslV05(src: string): V05ParseResult {
           const opts = parseInlineMapping(m[2]!);
           lanesMap[id] = {
             id,
-            x: numberOrUndef(opts.x),
-            width: numberOrUndef(opts.width),
+            ...表で読む(LANE_VALUE_KINDS, opts, `縦列 ${id} の `, it.no, errors),
             label: opts.label,
-            contain: boolOrUndef(opts.contain),
-            lifeline: boolOrUndef(opts.lifeline),
             pos: { line: it.no },
           };
         } else {
@@ -515,8 +573,14 @@ export function parseTextDslV05(src: string): V05ParseResult {
     i += 1;
   }
 
-  if (!title) errors.push({ line: 1, message: "title is required", hint: 'add `title: "..."` at top' });
-  if (!type) errors.push({ line: 1, message: "type is required", hint: "add `type: sequence|flow|swimlane|er|state|topology|solidity|gantt|class|pie|c4|mind`" });
+  if (!title)
+    errors.push({ line: 1, message: "title is required", hint: 'add `title: "..."` at top' });
+  if (!type)
+    errors.push({
+      line: 1,
+      message: "type is required",
+      hint: "add `type: sequence|flow|swimlane|er|state|topology|solidity|gantt|class|pie|c4|mind`",
+    });
 
   if (errors.length > 0) return { ok: false, errors };
 
@@ -590,7 +654,10 @@ function lastTopLevelColon(s: string): number {
       if (c === quote) quote = "";
       continue;
     }
-    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '"' || c === "'") {
+      quote = c;
+      continue;
+    }
     if (c === "[" || c === "{") depth += 1;
     else if (c === "]" || c === "}") depth -= 1;
     else if (c === ":" && depth === 0) last = i;
@@ -615,11 +682,26 @@ function splitValues(s: string): string[] {
       if (c === quote) quote = "";
       continue;
     }
-    if (c === '"' || c === "'") { quote = c; buf += c; continue; }
-    if (c === "[" || c === "{") { depth += 1; buf += c; continue; }
-    if (c === "]" || c === "}") { depth -= 1; buf += c; continue; }
+    if (c === '"' || c === "'") {
+      quote = c;
+      buf += c;
+      continue;
+    }
+    if (c === "[" || c === "{") {
+      depth += 1;
+      buf += c;
+      continue;
+    }
+    if (c === "]" || c === "}") {
+      depth -= 1;
+      buf += c;
+      continue;
+    }
     if (/\s/.test(c) && depth === 0) {
-      if (buf) { out.push(buf); buf = ""; }
+      if (buf) {
+        out.push(buf);
+        buf = "";
+      }
       continue;
     }
     buf += c;
@@ -650,13 +732,16 @@ type ActorValues = {
  * 振り分けは値の形で決まる。 引用符付きは補足 (2 つ目は値)、 角括弧は行、 色名は色、
  * 残りが種類。 形が違うので取り違えない。
  */
-function classifyValues(values: string[]): ActorValues {
+function classifyValues(values: string[], line: number, errors: DslError[]): ActorValues {
   const out: ActorValues = { kind: "" };
   /** 書かれた倍率。 同じ名前が 2 度出たら後の値で上書きする */
   const scaleWritten = new Map<string, string>();
   const kindWords: string[] = [];
   for (const v of values) {
-    if ((v.startsWith('"') && v.endsWith('"') && v.length > 1) || (v.startsWith("'") && v.endsWith("'") && v.length > 1)) {
+    if (
+      (v.startsWith('"') && v.endsWith('"') && v.length > 1) ||
+      (v.startsWith("'") && v.endsWith("'") && v.length > 1)
+    ) {
       // 1 つ目の引用符は補足、 2 つ目は値 (`storage` の右側に出る数値等)
       if (out.subtitle === undefined) out.subtitle = stripQuotes(v);
       else if (out.value === undefined) out.value = stripQuotes(v);
@@ -672,7 +757,11 @@ function classifyValues(values: string[]): ActorValues {
     }
     // `@300,200` は位置。 2 つ揃わないと効かないので、 1 つの値としてまとめて書く
     const at = v.match(/^@(-?\d+(?:\.\d+)?)\s*[,、]\s*(-?\d+(?:\.\d+)?)$/);
-    if (at) { out.posX = Number(at[1]); out.posY = Number(at[2]); continue; }
+    if (at) {
+      out.posX = Number(at[1]);
+      out.posY = Number(at[2]);
+      continue;
+    }
     // `名前=値` は parts の状態の上書き。 状態名は自由なので、 形では見分けられない。
     // 等号を書いてもらう。
     const eq = v.indexOf("=");
@@ -690,12 +779,15 @@ function classifyValues(values: string[]): ActorValues {
         continue;
       }
     }
-    const tone = toneOrUndef(v);
-    if (tone) { out.tone = tone; continue; }
+    const tone = resolveTone(v);
+    if (tone) {
+      out.tone = tone;
+      continue;
+    }
     kindWords.push(v);
   }
   out.kind = kindWords.join(" ").toLowerCase();
-  const s = resolveScale(scaleWritten);
+  const s = resolveScale(scaleWritten, line, errors);
   out.scale = s.scale;
   out.scaleKeys = s.keys;
   return out;
@@ -706,7 +798,7 @@ function classifyValues(values: string[]): ActorValues {
  *
  * 固有名 (`lambda` / `rds` 等) は読み替え表を通す。 それ以外はそのまま返す。
  */
-function resolveKind(raw: string): NodeKind {
+export function resolveNodeKind(raw: string): NodeKind {
   if (raw === "") return NODE_KIND_DEFAULT;
   // `Object.hasOwn` で引く。 素の添字だと `toString` 等の既定の持ち物が引けてしまい、
   // 種類として関数が返る。 呼ぶ前に受理集合で弾いてはいるが、 表を引く側でも閉じておく。
@@ -727,6 +819,157 @@ function boolOrUndef(s: string | undefined): boolean | undefined {
   return undefined;
 }
 
+/**
+ * 欄が期待する値の形 (#1306)。
+ *
+ * 記法の値はすべて文字列なので「型」 は無いが、**欄ごとに読める形は決まっている**
+ * (`posX` は数、`overlay` は真偽)。 その形を表に並べ、読めない値を行番号付きで知らせる。
+ */
+type 値の形 = "数" | "真偽";
+
+/** 表から作る、欄の名前と読んだ結果の対応 */
+type 読んだ結果<T extends Record<string, 値の形>> = {
+  [K in keyof T]: T[K] extends "数" ? number | undefined : boolean | undefined;
+};
+
+/**
+ * 数として読む。 読めない値は行番号付きで知らせる (#1306)。
+ *
+ * `numberOrUndef` は読めない値を黙って `undefined` に落とすため、書いた欄が無かったことに
+ * なる。 誤りも警告も出ないので、書いた人には「書いたのに図が変わらない」 としか見えない。
+ *
+ * 値を書かなかった形 (`posX:` の右が空) は「書かなかった」 と同じ扱いのままにする。
+ * こちらは黙って消えているわけではなく、書いていないものが効かないだけ。
+ */
+function 数として読む(
+  raw: string | undefined,
+  欄: string,
+  line: number,
+  errors: DslError[],
+): number | undefined {
+  if (raw === undefined || raw === "") return undefined;
+  const n = numberOrUndef(raw);
+  if (n !== undefined) return n;
+  errors.push({
+    line,
+    message: `${欄} は数で書きます: "${raw}"`,
+    hint: "`300` / `-8` / `1.5` の形で書く",
+  });
+  return undefined;
+}
+
+/**
+ * 真偽として読む。 読めない値は行番号付きで知らせる (#1306)。
+ *
+ * 受けるのは `true` と `false` だけ。 `yes` / `1` / `はい` は読めないため、使える値を
+ * 添えて知らせる (読めない値を捨てるだけだと、別の綴りを試し続けることになる)。
+ */
+function 真偽として読む(
+  raw: string | undefined,
+  欄: string,
+  line: number,
+  errors: DslError[],
+): boolean | undefined {
+  if (raw === undefined || raw === "") return undefined;
+  const b = boolOrUndef(raw);
+  if (b !== undefined) return b;
+  errors.push({
+    line,
+    message: `${欄} は true か false で書きます: "${raw}"`,
+    hint: "使える値 = true, false",
+  });
+  return undefined;
+}
+
+/**
+ * 表に並べた欄をまとめて読む (#1306)。
+ *
+ * **呼出側に欄名を並べない**。 並べると欄を足した時に知らせだけが漏れる (JSON 入口が
+ * #1304 で踏んだ形と同じ)。 表を 1 つ置き、読む側も検査もそこから導く。
+ *
+ * `接頭` は知らせに出す欄の呼び名の前半 (`viewport.` / `縦列 l1 の `)。 同じ欄名が別の
+ * 場所に出る (`width` は図全体と縦列、`posX` は箱と箱の中の要素) ため、どこの欄かが
+ * 分かる形にする。
+ */
+function 表で読む<T extends Record<string, 値の形>>(
+  表: T,
+  opts: Record<string, string | undefined>,
+  接頭: string,
+  // 欄ごとに行が違う書き方 (縦に並べる形) では関数で渡す。 1 行に収まる書き方 (中括弧) は数で渡す
+  line: number | ((欄: string) => number),
+  errors: DslError[],
+): 読んだ結果<T> {
+  const out: Record<string, number | boolean | undefined> = {};
+  const 行を引く = (欄: string): number => (typeof line === "number" ? line : line(欄));
+  for (const [欄, 形] of Object.entries<値の形>(表)) {
+    out[欄] =
+      形 === "数"
+        ? 数として読む(opts[欄], `${接頭}${欄}`, 行を引く(欄), errors)
+        : 真偽として読む(opts[欄], `${接頭}${欄}`, 行を引く(欄), errors);
+  }
+  return out as 読んだ結果<T>;
+}
+
+/**
+ * 図全体の大きさと間隔の欄 (#1306)。 `DslViewport` の数の欄をすべて覆う。
+ *
+ * `satisfies` で `DslViewport` から欄を導く = 欄を足して表に書き忘れると型検査が落ちる。
+ */
+export const VIEWPORT_VALUE_KINDS = {
+  width: "数",
+  height: "数",
+  scale: "数",
+  laneWidth: "数",
+  gap: "数",
+  laneGap: "数",
+  nodeGap: "数",
+  labelMargin: "数",
+} as const satisfies Record<Exclude<keyof DslViewport, "pos">, 値の形>;
+
+/**
+ * 縦列の欄 (#1306)。 `label` は文字列なので表に載せない (記法の値は全て文字列で、
+ * 文字列の欄には読めない値という状態が無い)。
+ */
+export const LANE_VALUE_KINDS = {
+  x: "数",
+  width: "数",
+  contain: "真偽",
+  lifeline: "真偽",
+} as const satisfies Record<string, 値の形>;
+
+/** 箱の中の要素の欄 (#1306)。 `DslActorNodeOverride` の全欄を覆う */
+export const ACTOR_NODE_VALUE_KINDS = {
+  posX: "数",
+  posY: "数",
+  posW: "数",
+  posH: "数",
+} as const satisfies Record<keyof DslActorNodeOverride, 値の形>;
+
+/** 中括弧の形で箱に書ける、数と真偽の欄 (#1306) */
+export const ACTOR_INLINE_VALUE_KINDS = {
+  stack: "数",
+  initial: "真偽",
+  final: "真偽",
+  posX: "数",
+  posY: "数",
+  posW: "数",
+  posH: "数",
+} as const satisfies Record<string, 値の形>;
+
+/** 縦に並べる形で箱に書ける、数と真偽の欄 (#1306)。 `posW` / `posH` は `大きさ:` が受ける */
+export const ACTOR_BLOCK_VALUE_KINDS = {
+  stack: "数",
+  posX: "数",
+  posY: "数",
+} as const satisfies Record<string, 値の形>;
+
+/** 矢印の中括弧に書ける、数と真偽の欄 (#1306) */
+export const FLOW_INLINE_VALUE_KINDS = {
+  labelOffsetX: "数",
+  labelOffsetY: "数",
+  overlay: "真偽",
+} as const satisfies Record<string, 値の形>;
+
 /**
  * 色名を解決する。 別名 (`成功` / `neutral` 等) も受け付ける。
  *
@@ -736,7 +979,7 @@ function boolOrUndef(s: string | undefined): boolean | undefined {
  * `valueOf` / `__proto__` が JavaScript の既定の持ち物として引けてしまい、 色名として
  * 関数やオブジェクトが通る (実測)。 最後に解決結果が正規の色名かも確かめる。
  */
-function toneOrUndef(s: string | undefined): Tone | undefined {
+export function resolveTone(s: string | undefined): Tone | undefined {
   if (s === undefined) return undefined;
   const raw = stripQuotes(s.trim());
   const lower = raw.toLowerCase();
@@ -846,7 +1089,11 @@ function splitInlineFields(inner: string): string[] {
   return parts;
 }
 
-function collectIndentedList(lines: Line[], start: number, parentIndent: number): { items: Line[]; next: number } {
+function collectIndentedList(
+  lines: Line[],
+  start: number,
+  parentIndent: number,
+): { items: Line[]; next: number } {
   const items: Line[] = [];
   let i = start;
   while (i < lines.length) {
@@ -887,13 +1134,43 @@ function collectIndentedList(lines: Line[], start: number, parentIndent: number)
  * 書く人は「色を変えたい」 としか思わないので、 項目は `色:` 1 つにまとめる。 意味の色
  * (`失敗`) と色番号 (`#f59e0b`) は形で見分ける。 前者は箱の色、 後者はパーツの塗りになる。
  */
-function splitColorValue(raw: string): { tone?: Tone; hex?: string } {
+export function splitColorValue(raw: string): { tone?: Tone; hex?: string } {
   const v = stripQuotes(raw.trim());
   if (v.startsWith("#")) return { hex: v };
-  const tone = toneOrUndef(v);
+  const tone = resolveTone(v);
   return tone ? { tone } : {};
 }
 
+/**
+ * v0.4 で使えた箱の種類の名前 (#1301)。
+ *
+ * v0.5 の受理集合 (`NODE_KIND_VALID`) に無いため、書くと見本 (parts) の名前として扱われ、
+ * 見本帳に無ければ `actor` に潰れて **黙って消えていた**。 見本の名前と区別が付かないので、
+ * 「v0.4 で種類として使えた語」 であることを根拠に誤りとして知らせる。
+ *
+ * 対応は `keywords.ts` の `NODE_KIND_ALIAS` が持つ (日本語 → 英語の種類名)。
+ */
+function v04の種類名(値: string): string | undefined {
+  if (!Object.hasOwn(NODE_KIND_ALIAS, 値)) return undefined;
+  if (NODE_KIND_VALID.has(値)) return undefined; // v0.5 でも受ける名前は対象外
+  return NODE_KIND_ALIAS[値];
+}
+
+/**
+ * 箱の種類に v0.4 の日本語を書いた時に知らせる (#1301)。
+ *
+ * 黙って見本の名前として扱うと、見本帳に無い場合に `actor` へ潰れて手掛かりが残らない。
+ */
+function reportV04Kind(kindRaw: string, line: number, errors: DslError[]): void {
+  const 英語 = v04の種類名(kindRaw);
+  if (英語 === undefined) return;
+  errors.push({
+    line,
+    message: `箱の種類に v0.4 の名前は使えません: "${kindRaw}"`,
+    hint: `v0.5 では英語で書く (\`${英語}\`)`,
+  });
+}
+
 /** `色` / `color` のどちらでも書ける。 */
 const COLOR_KEYS = new Set(["色", "color", "tone"]);
 
@@ -921,11 +1198,20 @@ const SCALE_ORDER = ["scale", "倍率"] as const;
  * `keys` は書かれた名前そのもの。 値が読めたかに関わらず入る。 見本が同じ名前の状態を
  * 持つ時の知らせ (`scale-reserved`) が、値の読めなさに左右されないようにするため。
  */
-function resolveScale(written: Map<string, string>): { scale?: number; keys: string[] } {
+function resolveScale(
+  written: Map<string, string>,
+  line: number | ((key: string) => number),
+  errors: DslError[],
+): { scale?: number; keys: string[] } {
   const keys = [...written.keys()];
   for (const key of SCALE_ORDER) {
     const raw = written.get(key);
-    if (raw !== undefined) return { scale: numberOrUndef(raw), keys };
+    // 読めない値は黙って捨てず知らせる (#1306)。 書かれた名前 (`keys`) は値の読めなさに
+    // 関わらず残す = 見本が同じ名前の状態を持つ時の知らせが消えないようにするため
+    if (raw !== undefined) {
+      const 当該行 = typeof line === "number" ? line : line(key);
+      return { scale: 数として読む(raw, `箱の ${key}`, 当該行, errors), keys };
+    }
   }
   return { keys };
 }
@@ -942,6 +1228,8 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
   let touchedState = false;
   /** 縦に並べて書かれた倍率。 同じ名前が 2 度出たら後の値で上書きする */
   const scaleWritten = new Map<string, string>();
+  /** 倍率を名前ごとに最後に書いた行。 別名の優先順と行番号を取り違えないために保持する。 */
+  const scaleLines = new Map<string, number>();
   /**
    * 縦に並べて書かれた体験の道筋の欄 (#1251)。
    *
@@ -962,6 +1250,7 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
     // 予約の知らせが消え、別名 (`倍率`) に降りて別の値が効いてしまう
     if (SCALE_KEYS.has(key)) {
       scaleWritten.set(key, stripQuotes(raw));
+      scaleLines.set(key, ln.no);
       unknownKeys.push({ key, line: ln.no });
       continue;
     }
@@ -972,14 +1261,18 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
       if (tone) out.tone = tone;
       // 色番号を入れる状態の名前はパーツごとに違う。 組み立て時に解決する
       if (hex) out.colorHex = hex;
+      // 色名としても色番号としても読めない値は黙って捨てない (#1304)。 捨てると
+      // 既定色のまま描かれ、 手掛かりが 1 つも残らない
+      if (!tone && !hex) report読めない色(raw, ln.no, errors, { 線種も受ける: false });
       continue;
     }
     switch (key) {
       case "kind":
       case "種類": {
         const k = stripQuotes(raw).toLowerCase();
+        reportV04Kind(k, ln.no, errors);
         const isPart = k !== "" && !NODE_KIND_VALID.has(k);
-        out.kind = isPart ? NODE_KIND_DEFAULT : resolveKind(k);
+        out.kind = isPart ? NODE_KIND_DEFAULT : resolveNodeKind(k);
         // parts 候補は `kind` を既定に倒して `partId` へ退避するため、 名札に載せる種類としては
         // 「書かなかった」 と同じ扱いにする (#1058)
         out.kindWritten = k !== "" && !isPart;
@@ -996,7 +1289,11 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
         break;
       case "rows":
       case "行":
-        out.rows = raw.replace(/^\[|\]$/g, "").split(/,(?![^[]*\])/).map((x) => stripQuotes(x.trim())).filter(Boolean);
+        out.rows = raw
+          .replace(/^\[|\]$/g, "")
+          .split(/,(?![^[]*\])/)
+          .map((x) => stripQuotes(x.trim()))
+          .filter(Boolean);
         break;
       case "位置":
       case "pos": {
@@ -1025,7 +1322,8 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
         //
         // 負の間隔 (`Web の右 -200`) もここに来る。 向きを書いた上で裏返す指定は、
         // 書いた人の意図と図が食い違うので誤りとして返す
-        const negative = /^(.+?)\s*(?:の\s*(?:右|左|上|下)|\s(?:right|left|above|below))\s*-\s*[\d.]/i.test(value);
+        const negative =
+          /^(.+?)\s*(?:の\s*(?:右|左|上|下)|\s(?:right|left|above|below))\s*-\s*[\d.]/i.test(value);
         errors.push({
           line: ln.no,
           message: negative
@@ -1038,10 +1336,10 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
         break;
       }
       case "posX":
-        out.posX = numberOrUndef(raw);
+        out.posX = 数として読む(raw, "箱の posX", ln.no, errors);
         break;
       case "posY":
-        out.posY = numberOrUndef(raw);
+        out.posY = 数として読む(raw, "箱の posY", ln.no, errors);
         break;
       case "大きさ":
       case "size": {
@@ -1075,7 +1373,7 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
         out.lane = stripQuotes(raw);
         break;
       case "stack":
-        out.stack = numberOrUndef(raw);
+        out.stack = 数として読む(raw, "箱の stack", ln.no, errors);
         break;
       default:
         // 残りはパーツの状態の上書き
@@ -1088,7 +1386,11 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
   // 名前の行と縦に並べた行の両方に倍率がある形では、後に書いた縦の行を採る。
   // 知らせ (`scale-reserved`) は書かれた名前をすべて見るので、名前だけは足し合わせる
   if (scaleWritten.size > 0) {
-    const s = resolveScale(scaleWritten);
+    const s = resolveScale(
+      scaleWritten,
+      (key) => scaleLines.get(key) ?? actor.pos.line,
+      errors,
+    );
     out.scale = s.scale;
     out.scaleKeys = [...new Set([...(actor.scaleKeys ?? []), ...s.keys])];
   }
@@ -1128,18 +1430,30 @@ function applyContinuationLines(actor: DslActor, rest: Line[], errors: DslError[
  */
 export const ACTOR_ITEM_KEYS: ReadonlySet<string> = new Set([
   ...COLOR_KEYS,
-  "kind", "種類",
-  "subtitle", "補足",
-  "value", "値",
-  "rows", "行",
-  "位置", "pos", "posX", "posY",
-  "大きさ", "size",
-  "倍率", "scale",
-  "lane", "stack",
+  "kind",
+  "種類",
+  "subtitle",
+  "補足",
+  "value",
+  "値",
+  "rows",
+  "行",
+  "位置",
+  "pos",
+  "posX",
+  "posY",
+  "大きさ",
+  "size",
+  "倍率",
+  "scale",
+  "lane",
+  "stack",
   // 体験の道筋の欄 (#1251)
-  "touchpoint", "opportunity",
+  "touchpoint",
+  "opportunity",
   // 工程の並びの欄 (#1251)
-  "owner", "end",
+  "owner",
+  "end",
 ]);
 
 /**
@@ -1198,14 +1512,21 @@ function validateRelativePositions(actors: DslActor[], errors: DslError[]): void
   }
 }
 
-function collectActorEntries(lines: Line[], start: number, parentIndent: number): { items: Line[][]; next: number } {
+function collectActorEntries(
+  lines: Line[],
+  start: number,
+  parentIndent: number,
+): { items: Line[][]; next: number } {
   const items: Line[][] = [];
   let cur: Line[] | null = null;
   let headIndent = -1;
   let i = start;
   while (i < lines.length) {
     const ln = lines[i]!;
-    if (!ln.trimmed) { i += 1; continue; }
+    if (!ln.trimmed) {
+      i += 1;
+      continue;
+    }
     if (ln.indent <= parentIndent) break;
     if (ln.trimmed.startsWith("- ")) {
       if (cur) items.push(cur);
@@ -1221,7 +1542,11 @@ function collectActorEntries(lines: Line[], start: number, parentIndent: number)
   return { items, next: i };
 }
 
-function collectAnimationSteps(lines: Line[], start: number, parentIndent: number): { items: Line[][]; next: number } {
+function collectAnimationSteps(
+  lines: Line[],
+  start: number,
+  parentIndent: number,
+): { items: Line[][]; next: number } {
   // 各 `- step: "..."` 開始を 1 block の頭として識別、 後続の同 indent 以下を block 本文として吸収
   const out: Line[][] = [];
   let i = start;
@@ -1233,7 +1558,10 @@ function collectAnimationSteps(lines: Line[], start: number, parentIndent: numbe
       continue;
     }
     if (ln.indent <= parentIndent) break;
-    if (ln.trimmed.startsWith("- step")) {
+    // v0.4 の日本語の段名も block の頭として拾い、parsePhase で英語の `step` を案内する
+    // (#1301)。ここで英語だけに絞ると `- ステップ:` は block 自体が作られず、段全体が
+    // 誤りなしで黙って消える。
+    if (ln.trimmed.startsWith("- step") || ln.trimmed.startsWith("- ステップ")) {
       if (cur) out.push(cur);
       cur = [{ ...ln, trimmed: ln.trimmed.slice(2).trim() }];
     } else if (cur) {
@@ -1288,7 +1616,9 @@ const ACTOR_RESERVED_FIELDS: ReadonlySet<string> = new Set([
   "色",
 ]);
 
-function extractStateOverride(opts: Record<string, string>): Record<string, number | string | boolean> | undefined {
+function extractStateOverride(
+  opts: Record<string, string>,
+): Record<string, number | string | boolean> | undefined {
   const out: Record<string, number | string | boolean> = {};
   let count = 0;
   // 明示 `state: {...}` fallback がある場合はそちらを優先 (nested map parse)
@@ -1317,7 +1647,11 @@ function extractStateOverride(opts: Record<string, string>): Record<string, numb
  * key: sub-map ペアに再 split → 各 sub-map を parseInlineMapping で解いて posX/Y/W/H に coerce」 する。
  * 未 field or 空 object なら undefined 返し (caller は actor.nodes を set しない)。
  */
-function parseActorNodesField(raw: string | undefined): Record<string, DslActorNodeOverride> | undefined {
+function parseActorNodesField(
+  raw: string | undefined,
+  line: number,
+  errors: DslError[],
+): Record<string, DslActorNodeOverride> | undefined {
   if (!raw) return undefined;
   const trimmed = raw.trim();
   if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return undefined;
@@ -1347,12 +1681,7 @@ function parseActorNodesField(raw: string | undefined): Record<string, DslActorN
     const val = p.slice(colonIdx + 1).trim();
     if (!key || !val.startsWith("{") || !val.endsWith("}")) continue;
     const nodeOpts = parseInlineMapping(val.slice(1, -1));
-    out[key] = {
-      posX: numberOrUndef(nodeOpts.posX),
-      posY: numberOrUndef(nodeOpts.posY),
-      posW: numberOrUndef(nodeOpts.posW),
-      posH: numberOrUndef(nodeOpts.posH),
-    };
+    out[key] = 表で読む(ACTOR_NODE_VALUE_KINDS, nodeOpts, `nodes の ${key} の `, line, errors);
   }
   return Object.keys(out).length > 0 ? out : undefined;
 }
@@ -1394,17 +1723,65 @@ function reportScaleOnNonPart(
  * 並べた形) とは別に持つ = 中括弧の形は位置や大きさを未対応にしてあり、 同じ集合にすると
  * 「知らせない」 側がずれる。
  */
+/**
+ * 中括弧の形で読める日本語と、その英語名 (#1301)。
+ *
+ * **英語が中括弧で読める欄だけを載せる**。 `位置` / `大きさ` / `色` は英語側
+ * (`pos` / `size` / `color`) も中括弧では読めないため載せない = 英語で出来ないことを
+ * 日本語で出来るようにはしない。
+ *
+ * 載せる前は、同じ意味の語が縦書きでは通り中括弧では「項目名が読めません」 になっていた。
+ * 書き方によって日本語だけが落ちる状態を無くす。
+ */
+export const INLINE_ACTOR_ALIASES: Record<string, string> = {
+  種類: "kind",
+  補足: "subtitle",
+  値: "value",
+  行: "rows",
+};
+
+/** 中括弧に書かれた日本語の項目名を、同じ意味の英語名に寄せる (#1301) */
+function 中括弧の別名を寄せる(opts: Record<string, string>): Record<string, string> {
+  let 触った = false;
+  const out: Record<string, string> = { ...opts };
+  for (const [日, 英] of Object.entries(INLINE_ACTOR_ALIASES)) {
+    if (!(日 in out)) continue;
+    触った = true;
+    // 英語を併記した時は英語を優先する (縦書き形が後勝ちなのと違い、こちらは 1 行に同居する)
+    if (!(英 in out)) out[英] = out[日]!;
+    delete out[日];
+  }
+  return 触った ? out : opts;
+}
+
 export const INLINE_ACTOR_KEYS: ReadonlySet<string> = new Set([
-  "kind", "subtitle", "eyebrow", "value", "rows", "lane", "stack",
-  "initial", "final", "tone", "nodes",
+  "kind",
+  "subtitle",
+  "eyebrow",
+  "value",
+  "rows",
+  "lane",
+  "stack",
+  "initial",
+  "final",
+  "tone",
+  "nodes",
   // 体験の道筋の欄 (#1251)。 他の図種では組み立て側が知らせる
-  "touchpoint", "opportunity",
+  "touchpoint",
+  "opportunity",
   // 工程の並びの欄 (#1251)
-  "owner", "end",
-  "posX", "posY", "posW", "posH",
+  "owner",
+  "end",
+  "posX",
+  "posY",
+  "posW",
+  "posH",
   // 倍率は別経路 (`reportScaleOnNonPart`) が知らせる。 ここでも読める扱いにしないと
   // 同じ名前で 2 度知らせることになる
-  "scale", "倍率",
+  "scale",
+  "倍率",
+  // 英語が読める欄の日本語別名 (#1301)。 一覧は `INLINE_ACTOR_ALIASES` が持つ
+  ...Object.keys(INLINE_ACTOR_ALIASES),
 ]);
 // `state` はパーツでだけ意味を持つ (`extractStateOverride` がパーツの時しか作らない)。
 // 通常の箱で読める扱いにすると `- A: { state: { foo: 1 } }` が黙って消え、 本 file が塞ごうと
@@ -1422,13 +1799,17 @@ const FLOW_INLINE_READERS = {
   sub: (v: string | undefined) => v,
   guard: (v: string | undefined) => v,
   cardinality: (v: string | undefined) => v,
-  labelOffsetX: (v: string | undefined) => numberOrUndef(v),
-  labelOffsetY: (v: string | undefined) => numberOrUndef(v),
-  overlay: (v: string | undefined) => boolOrUndef(v),
+  // 数と真偽の欄は `FLOW_INLINE_VALUE_KINDS` の表が読む (#1306)。 ここでは名前だけを持つ =
+  // 読める欄の一覧 (`FLOW_INLINE_KEYS`) は本表から導くため、載せないと欄ごと消える
+  labelOffsetX: null,
+  labelOffsetY: null,
+  overlay: null,
 } as const;
 
 /** 矢印の中括弧に書ける欄の名前。 README の一覧と突き合わせる (#1275) */
-export const FLOW_INLINE_KEYS = Object.keys(FLOW_INLINE_READERS) as readonly (keyof typeof FLOW_INLINE_READERS)[];
+export const FLOW_INLINE_KEYS = Object.keys(
+  FLOW_INLINE_READERS,
+) as readonly (keyof typeof FLOW_INLINE_READERS)[];
 
 /**
  * 中括弧に書かれた読めない項目名を知らせる (#1090)。
@@ -1481,18 +1862,28 @@ function parseActor(line: Line, errors: DslError[]): DslActor | null {
   if (mapMatch) {
     const namePart = stripQuotes(mapMatch.name.trim());
     if (!namePart) return null;
-    const opts = parseInlineMapping(mapMatch.inner);
+    // 日本語の項目名を英語名に寄せてから読む (#1301)。 寄せないと、同じ意味の語が
+    // 縦書きでは通り中括弧では落ちる
+    const opts = 中括弧の別名を寄せる(parseInlineMapping(mapMatch.inner));
     const kindRaw = (opts.kind ?? "").toLowerCase();
     // CAR-1657 = kind が既存 NODE_KIND_VALID に無い場合 parts identifier 候補として partId に格納、
     // kind は actor default fallback。 compile 側 partsCatalog lookup で解決する。
     const isPart = kindRaw !== "" && !NODE_KIND_VALID.has(kindRaw);
     // 倍率はパーツにしか効かない。 書いたのに効かない状態を黙って作らない (#1026)。
     // 値が空の形でも名前を残すため、`opts` ではなく中身から直接拾う
-    const inlineScale = resolveScale(writtenScaleFields(mapMatch.inner));
+    const inlineScale = resolveScale(writtenScaleFields(mapMatch.inner), line.no, errors);
     reportScaleOnNonPart(isPart, inlineScale.keys[0], line.no, errors);
     // 中括弧に書いた読めない項目名も知らせる (#1090)。 縦に並べた形だけが知らせていた
     reportUnknownInlineKeys(isPart, mapMatch.inner, line.no, errors);
-    const kind = isPart ? NODE_KIND_DEFAULT : resolveKind(NODE_KIND_VALID.has(kindRaw) ? kindRaw : "");
+    reportV04Kind(kindRaw, line.no, errors);
+    // 中括弧に書いた読めない色名も知らせる (#1304)。 パーツでは `tone` が状態の上書きとして
+    // 意味を持つため対象外 = 色として読もうとしない値を色として叱らない
+    if (!isPart && opts.tone !== undefined && resolveTone(opts.tone) === undefined) {
+      report読めない色(opts.tone, line.no, errors, { 線種も受ける: false });
+    }
+    const kind = isPart
+      ? NODE_KIND_DEFAULT
+      : resolveNodeKind(NODE_KIND_VALID.has(kindRaw) ? kindRaw : "");
     return {
       name: namePart,
       kind,
@@ -1516,23 +1907,17 @@ function parseActor(line: Line, errors: DslError[]): DslActor | null {
             .filter(Boolean)
         : undefined,
       lane: opts.lane,
-      stack: numberOrUndef(opts.stack),
-      initial: boolOrUndef(opts.initial),
-      final: boolOrUndef(opts.final),
+      ...表で読む(ACTOR_INLINE_VALUE_KINDS, opts, "箱の ", line.no, errors),
       // parts では `tone` を状態の上書きとして従来から使えるため、 色として横取りしない
-      tone: isPart ? undefined : toneOrUndef(opts.tone),
+      tone: isPart ? undefined : resolveTone(opts.tone),
       partId: isPart ? kindRaw : undefined,
       stateOverride: isPart ? extractStateOverride(opts) : undefined,
-      // canvas pivot 新 spec = 絶対座標 field を actor に格納、 compile 経由で CDL に受け渡す
-      posX: numberOrUndef(opts.posX),
-      posY: numberOrUndef(opts.posY),
-      posW: numberOrUndef(opts.posW),
-      posH: numberOrUndef(opts.posH),
+      // canvas pivot 新 spec = 絶対座標 field は `ACTOR_INLINE_VALUE_KINDS` の表が読む (#1306)
       // 図形の倍率 (#1026)。 どれが効くかは `resolveScale` が 1 箇所で決める
       scale: inlineScale.scale,
       scaleKeys: inlineScale.keys.length ? inlineScale.keys : undefined,
       // canvas pivot UX 修正 (B1) = sub-node 単位 override map (`nodes: { header: {posX:..., ...}, ...}`)
-      nodes: parseActorNodesField(opts.nodes),
+      nodes: parseActorNodesField(opts.nodes, line.no, errors),
       pos: { line: line.no },
     };
   }
@@ -1547,13 +1932,16 @@ function parseActor(line: Line, errors: DslError[]): DslActor | null {
     //
     // 値は形で見分ける。 引用符付きは補足、 角括弧は行、 色名は色、 残りが種類。
     // 種類と色は語の集合が閉じているので取り違えない。
-    const v = classifyValues(splitValues(rest));
+    const v = classifyValues(splitValues(rest), line.no, errors);
 
     // CAR-1657 = short form (`arc1: arc-gauge`) でも parts kind 対応、 未知 kind は partId 経路
     const isPart = v.kind !== "" && !NODE_KIND_VALID.has(v.kind);
+    reportV04Kind(v.kind, line.no, errors);
     // 倍率はパーツにしか効かない (#1026)
     reportScaleOnNonPart(isPart, v.scaleKeys?.[0], line.no, errors);
-    const kind = isPart ? NODE_KIND_DEFAULT : resolveKind(NODE_KIND_VALID.has(v.kind) ? v.kind : "");
+    const kind = isPart
+      ? NODE_KIND_DEFAULT
+      : resolveNodeKind(NODE_KIND_VALID.has(v.kind) ? v.kind : "");
     return {
       name: namePart,
       kind,
@@ -1579,7 +1967,7 @@ function parseActor(line: Line, errors: DslError[]): DslActor | null {
   return { name: namePart, kind: NODE_KIND_DEFAULT, kindWritten: false, pos: { line: line.no } };
 }
 
-function parseFlowStep(line: Line, no: number): DslStep | null {
+function parseFlowStep(line: Line, no: number, errors: DslError[]): DslStep | null {
   // 形式 (順序自由、 部分省略可):
   // 1. `Client -> API`                            ... label / option なし
   // 2. `Client -> API: "deposit"`                 ... label
@@ -1598,17 +1986,23 @@ function parseFlowStep(line: Line, no: number): DslStep | null {
   const 中括弧: Partial<Record<keyof typeof FLOW_INLINE_READERS, unknown>> = {};
   // inline option (`{ ... }`) を末尾から抽出
   const mapMatch = rest.match(/\s*\{([^}]*)\}\s*$/);
+  let 数と真偽: 読んだ結果<typeof FLOW_INLINE_VALUE_KINDS> | undefined;
   if (mapMatch) {
     const opts = parseInlineMapping(mapMatch[1]!);
-    for (const k of FLOW_INLINE_KEYS) 中括弧[k] = FLOW_INLINE_READERS[k](opts[k]);
+    // 文字列の欄はそのまま入れ、数と真偽の欄は表が読んで読めない値を知らせる (#1306)
+    for (const k of FLOW_INLINE_KEYS) {
+      if (FLOW_INLINE_READERS[k] === null) continue;
+      中括弧[k] = opts[k];
+    }
+    数と真偽 = 表で読む(FLOW_INLINE_VALUE_KINDS, opts, "矢印の ", line.no, errors);
     rest = rest.slice(0, mapMatch.index ?? 0).trim();
   }
   const sub = 中括弧.sub as string | undefined;
   const guard = 中括弧.guard as string | undefined;
   const cardinality = 中括弧.cardinality as string | undefined;
-  const labelOffsetX = 中括弧.labelOffsetX as number | undefined;
-  const labelOffsetY = 中括弧.labelOffsetY as number | undefined;
-  const overlay = 中括弧.overlay as boolean | undefined;
+  const labelOffsetX = 数と真偽?.labelOffsetX;
+  const labelOffsetY = 数と真偽?.labelOffsetY;
+  const overlay = 数と真偽?.overlay;
   // 色と線種を末尾から取る。 括弧 (`(成功)`) と空白区切り (`成功`) の両方を受け付ける。
   //
   // 括弧は従来の書き方で、 catalog が使っている。 空白区切りは登場人物と揃えた形。
@@ -1616,9 +2010,13 @@ function parseFlowStep(line: Line, no: number): DslStep | null {
   if (optMatch) {
     const opts = (optMatch[1] ?? "").split(",").map((s) => s.trim());
     for (const opt of opts) {
-      const resolvedTone = toneOrUndef(opt);
+      const resolvedTone = resolveTone(opt);
       if (resolvedTone !== undefined) tone = resolvedTone;
       else if (STYLE_VALID.has(opt.toLowerCase())) style = opt.toLowerCase() as EdgeStyle;
+      // 丸括弧に書けるのは色名と線種だけ。 読めない語を黙って捨てると、 書いた人には
+      // 「書いたのに色が変わらない」 としか見えない (#1304)。 空の語 (`( )` / `(a,,b)`) は
+      // 書き間違いというより余分な区切りなので知らせない
+      else if (opt !== "") report読めない色(opt, line.no, errors, { 線種も受ける: true });
     }
     rest = rest.slice(0, optMatch.index ?? 0).trim();
   } else {
@@ -1629,9 +2027,17 @@ function parseFlowStep(line: Line, no: number): DslStep | null {
       const last = words[words.length - 1]!;
       // 引用符付きは説明文なので取らない
       if (last.startsWith('"') || last.startsWith("'")) break;
-      const resolvedTone = toneOrUndef(last);
-      if (resolvedTone !== undefined) { tone = resolvedTone; words.pop(); continue; }
-      if (STYLE_VALID.has(last.toLowerCase())) { style = last.toLowerCase() as EdgeStyle; words.pop(); continue; }
+      const resolvedTone = resolveTone(last);
+      if (resolvedTone !== undefined) {
+        tone = resolvedTone;
+        words.pop();
+        continue;
+      }
+      if (STYLE_VALID.has(last.toLowerCase())) {
+        style = last.toLowerCase() as EdgeStyle;
+        words.pop();
+        continue;
+      }
       break;
     }
     rest = words.join(" ");
@@ -1669,7 +2075,8 @@ function parseStateEntry(text: string, lineNo: number): DslState | null {
   const raw = (m[2] ?? "").trim();
   const stripped = stripQuotes(raw);
   const asNum = Number(stripped);
-  const initial: number | string = Number.isFinite(asNum) && stripped !== "" && !isNaN(asNum) ? asNum : stripped;
+  const initial: number | string =
+    Number.isFinite(asNum) && stripped !== "" && !isNaN(asNum) ? asNum : stripped;
   return { name, initial, pos: { line: lineNo } };
 }
 
@@ -1729,11 +2136,21 @@ function parseValueEntry(text: string, lineNo: number, errors: DslError[]): DslV
       for (const issue of issues) errors.push({ line: lineNo, ...issue });
       return null;
     }
-    return { name, trigger: spec.trigger, to: spec.to, durationMs: spec.durationMs, pos: { line: lineNo } };
+    return {
+      name,
+      trigger: spec.trigger,
+      to: spec.to,
+      durationMs: spec.durationMs,
+      pos: { line: lineNo },
+    };
   }
   const expression = stripQuotes(rest);
   if (expression === "") {
-    errors.push({ line: lineNo, message: `empty expression for "${name}"`, hint: '`"{a} + {b}"` のように式を書く' });
+    errors.push({
+      line: lineNo,
+      message: `empty expression for "${name}"`,
+      hint: '`"{a} + {b}"` のように式を書く',
+    });
     return null;
   }
   const issues = checkValueExpression(expression, name);
@@ -1746,7 +2163,10 @@ function parseValueEntry(text: string, lineNo: number, errors: DslError[]): DslV
 
 function splitTopLevelCommas(s: string): string[] {
   // brace 内を考慮 ... 今回は単純 split (動作する範囲)
-  return s.split(",").map((x) => x.trim()).filter(Boolean);
+  return s
+    .split(",")
+    .map((x) => x.trim())
+    .filter(Boolean);
 }
 
 function ensureAnimate(a: DslAnimate | undefined, lineNo: number): DslAnimate {
@@ -1759,14 +2179,22 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
   const head = block[0]!;
   const m = head.trimmed.match(/^step\s*:\s*(.+)$/);
   if (!m) {
-    errors.push({ line: head.no, message: `invalid step header: "${head.trimmed}"`, hint: 'use `- step: "name" 1.5s`' });
+    errors.push({
+      line: head.no,
+      message: `invalid step header: "${head.trimmed}"`,
+      hint: 'use `- step: "name" 1.5s`',
+    });
     return null;
   }
   const headRest = (m[1] ?? "").trim();
   // `"request" 1.5s` 形式 ... quote 後の duration 抽出
   const headParse = parseStepHead(headRest);
   if (!headParse) {
-    errors.push({ line: head.no, message: `invalid step value: "${headRest}"`, hint: 'use `"name" 1.5s` (duration in s)' });
+    errors.push({
+      line: head.no,
+      message: `invalid step value: "${headRest}"`,
+      hint: 'use `"name" 1.5s` (duration in s)',
+    });
     return null;
   }
   const phase: DslPhase = {
@@ -1782,7 +2210,10 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
   while (i < block.length) {
     const ln = block[i]!;
     const t = ln.trimmed;
-    const propMatch = t.match(/^([a-zA-Z][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
+    // **英数字以外の項目名も拾う** (#1301)。 以前は `[a-zA-Z]` で始まる名前しか見ておらず、
+    // 日本語の項目名 (`強調` / `説明` 等) は match そのものが外れて **黙って捨てられていた**。
+    // 拾った上で、知らない名前は下で誤りとして知らせる
+    const propMatch = t.match(/^([^\s:]+)\s*:\s*(.*)$/);
     if (!propMatch) {
       i += 1;
       continue;
@@ -1799,6 +2230,23 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
       i += 1;
       continue;
     }
+    if (key === "draw") {
+      const 語 = stripQuotes(value).trim();
+      // **読めない語を黙って捨てない** (#1304 / #1306 と同じ扱い)。 受ける語は 1 つだけで、
+      // 書き間違いはその段が何も描かない形になって手掛かりが残らない
+      if (!DRAW_WORDS.has(語)) {
+        errors.push({
+          line: ln.no,
+          message: `draw に書けない語です: "${語}"`,
+          hint: `使える語 = ${[...DRAW_WORDS].join(", ")}`,
+        });
+      } else {
+        phase.draw = 語;
+        phase.drawPos = { line: ln.no };
+      }
+      i += 1;
+      continue;
+    }
     if (key === "description" || key === "body") {
       phase.body = stripQuotes(value);
       i += 1;
@@ -1809,7 +2257,12 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
       if (value) {
         const tw = parseTweenLine(value, ln.no);
         if (tw) phase.tweens!.push(tw);
-        else errors.push({ line: ln.no, message: `invalid tween: "${value}"`, hint: "use `tween: name 100 -> 90`" });
+        else
+          errors.push({
+            line: ln.no,
+            message: `invalid tween: "${value}"`,
+            hint: "use `tween: name 100 -> 90`",
+          });
         i += 1;
         continue;
       }
@@ -1821,7 +2274,12 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
         if (nx.indent <= baseIndent) break;
         const tw = parseTweenLine(nx.trimmed, nx.no);
         if (tw) phase.tweens!.push(tw);
-        else errors.push({ line: nx.no, message: `invalid tween entry: "${nx.trimmed}"`, hint: "use `name: 100 -> 90`" });
+        else
+          errors.push({
+            line: nx.no,
+            message: `invalid tween entry: "${nx.trimmed}"`,
+            hint: "use `name: 100 -> 90`",
+          });
         j += 1;
       }
       i = j;
@@ -1846,11 +2304,81 @@ function parsePhase(block: Line[], errors: DslError[]): DslPhase | null {
       i = j;
       continue;
     }
+    // ここに来るのは上のどれにも当たらなかった名前 (#1301)。 黙って捨てると
+    // 「書いたのに段が変わらない」 が手掛かりなしで起きる
+    errors.push({
+      line: ln.no,
+      message: `段の項目名が読めません: "${propMatch[1] ?? ""}"`,
+      hint: 段の項目のヒント(propMatch[1] ?? ""),
+    });
     i += 1;
   }
   return phase;
 }
 
+/**
+ * 段の項目名が読めない時のヒント (#1301)。
+ *
+ * 日本語の名前は v0.4 の記法では使えたため、**同じ意味の英語を勧める**。
+ * 「使えません」 だけだと、書いた人は代わりに何を書けばよいか分からない。
+ */
+function 段の項目のヒント(書いた名前: string): string {
+  const 英語 = 段の項目の日本語[書いた名前];
+  return 英語 !== undefined
+    ? `v0.5 では英語で書く (\`${英語}\`)`
+    : `使える項目 = ${段の項目の英語.join(", ")}`;
+}
+
+/** 段に書ける項目の英語名。 `parsePhase` の分岐から導く一覧 */
+const 段の項目の英語 = ["focus", "badge", "body", "description", "tween", "set", "draw"] as const;
+
+/**
+ * `draw:` に書ける語と、その語が効く図種 (#1312 / #1314)。
+ *
+ * **語と図種の対応をここ 1 箇所で持つ**。 受ける語の一覧 (`DRAW_WORDS`) も、組み立て側が見る
+ * 図種の一覧 (`DRAWABLE_DOC_TYPES`) も、この表から導く。 3 つを別々に並べると、語を足した時に
+ * どれかが古いまま残る (#1310 / #1304 で 3 度直した形)。
+ *
+ * | 語 | 図種 | 起点 |
+ * |---|---|---|
+ * | `line` | `line` | 左端から右へ線が伸びる |
+ * | `bar` | `bar` | 横軸から上へ棒が伸びる |
+ * | `pie` | `pie` | 12 時から時計回りに扇が開く |
+ *
+ * いまは語と図種が同じ綴りだが、**同じものとして扱わない**。 語は書き手が書く名前で、
+ * 図種は `type:` が取る値。 片方だけ別名を足したくなった時に、対応が表に残っている形にする。
+ */
+export const DRAW_TARGETS: ReadonlyMap<string, PresetType> = new Map<string, PresetType>([
+  ["line", "line"],
+  ["bar", "bar"],
+  ["pie", "pie"],
+]);
+
+/** `draw:` に書ける語。 表から導く (#1314) */
+export const DRAW_WORDS: ReadonlySet<string> = new Set(DRAW_TARGETS.keys());
+
+/**
+ * v0.4 で使えた段の項目名と、v0.5 での書き方 (#1301)。
+ *
+ * **`ANIM_SUBKEYS` からは導けない**。 あの表は v0.4 の日本語と v0.4 の英語を組にしており、
+ * v0.5 が使う名前とは一致しない (`強調` の相手は v0.4 では `highlight`、v0.5 では `focus`)。
+ * 2 つの記法の間の翻訳なので、対応は手で書く。
+ *
+ * 表に語が増えた時に取り残されないよう、`ANIM_SUBKEYS` の日本語を全て覆っていることを
+ * 検査が確かめる (`v05-japanese-scope.test.ts`)。
+ */
+export const 段の項目の日本語: Record<string, string> = {
+  強調: "focus",
+  説明: "body",
+  バッジ: "badge",
+  遷移: "tween",
+  切替: "set",
+  // 状態は段の中ではなく最上位に書く (`states:`)
+  状態: "states (最上位に書く)",
+  // 段そのものの名前
+  ステップ: "step",
+};
+
 function parseStepHead(s: string): { name: string; durationMs: number } | null {
   // 例: `"request" 1.5s` / `"step1" 1500ms` / `step1 2s`
   let rest = s.trim();
@@ -1906,7 +2434,7 @@ function parseFocusList(s: string): string[] {
       buf += ch;
       continue;
     }
-    if (ch === "\"" || ch === "'") {
+    if (ch === '"' || ch === "'") {
       // item の途中にある引用符は名前の一部。 空白または区切りの直後だけ囲みを開始する。
       if (!buf || /\s$/.test(buf)) {
         pushFragment(false);
@@ -1926,7 +2454,10 @@ function parseFocusList(s: string): string[] {
   // quote 外 item は依然として space split (旧挙動、 「Client API」 が 2 item として解釈される互換維持)。
   const out: string[] = [];
   for (const fragments of groups) {
-    const whole = fragments.map(({ text }) => text).join("").trim();
+    const whole = fragments
+      .map(({ text }) => text)
+      .join("")
+      .trim();
     if (fragments.every(({ quoted }) => !quoted) && /[-→][>]?/.test(whole) && /\s/.test(whole)) {
       // arrow を含む非引用区間は「A -> B」パターン。 空白で分割しない。
       out.push(whole);
@@ -1973,6 +2504,7 @@ function parseSetLine(s: string, lineNo: number): DslSet | null {
   const raw = (m[2] ?? "").trim();
   const stripped = stripQuotes(raw);
   const asNum = Number(stripped);
-  const value: number | string = Number.isFinite(asNum) && stripped !== "" && !isNaN(asNum) ? asNum : stripped;
+  const value: number | string =
+    Number.isFinite(asNum) && stripped !== "" && !isNaN(asNum) ? asNum : stripped;
   return { state, value, pos: { line: lineNo } };
 }