@cardenelabs/dragon 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/dragon",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Dragon — Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を内部利用。",
   "license": "MIT",
   "author": "cardene777",
@@ -46,15 +46,6 @@
     "node": ">=18"
   },
   "sideEffects": false,
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "cd ../.. && vitest run packages/dragon",
-    "test:watch": "cd ../.. && vitest packages/dragon",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build"
-  },
   "dependencies": {
     "@cardenelabs/cdl": "^0.14.0"
   },
@@ -75,5 +66,14 @@
     "react": "^19.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "test": "cd ../.. && vitest run packages/dragon",
+    "test:watch": "cd ../.. && vitest packages/dragon",
+    "lint": "tsc --noEmit"
   }
-}
+}

package/src/color.ts

@@ -106,11 +106,13 @@ export type StrippedPaint = { path: string; value: string };
 /**
  * 図の中から、 色を塗る位置に入った外部参照を落とす。
  *
- * 対象は 2 種類ある。
+ * 対象は 3 種類ある。
  *
  * - 色を塗る key (`fill` / `stroke` / `bg` 等) の値
  * - 状態の値 (`states[].initial` と、 phase が状態へ入れる値)。 状態は `{名前}` の形で
  *   `fill` に差し込まれるため、 色を塗る位置に届く
+ * - つまみの値 (`inputs[].defaultValue` / `defaultValues` / `options`)。 これらも状態を上書きし、
+ *   同じ形で paint に届く
  *
  * 説明文 (`title` / `subtitle` / `value` / `rows`) は対象外。 文字として出るだけで
  * 属性にはならないため、 URL を書く正当な用途を壊さない。
@@ -119,23 +121,40 @@ export type StrippedPaint = { path: string; value: string };
  */
 export function stripExternalPaint(diagram: unknown): StrippedPaint[] {
   const stripped: StrippedPaint[] = [];
-  walk(diagram, "", false, stripped);
+  walk(diagram, "", false, stripped, false);
   return stripped;
 }
 
+/** つまみから状態値になり得る文字列の欄。 */
+const INPUT_VALUE_KEYS: ReadonlySet<string> = new Set(["defaultvalue", "defaultvalues", "options"]);
+
 /**
  * 図の中を辿って外部参照を落とす。
  *
  * `inStateValue` = 今見ている場所が状態の値かどうか。 状態は key の名前が `initial` や
  * 状態名そのもの (phase の `sets`) になるため、 key の名前だけでは色かどうか分からない。
  * 「状態を入れる箱の中にいる」 ことを引き継いで判断する。
+ * `inInputs` は `inputs` の中にいることを示し、値になる欄だけを `inStateValue` へ合流させる。
  */
-function walk(node: unknown, path: string, inStateValue: boolean, out: StrippedPaint[]): void {
+function walk(
+  node: unknown,
+  path: string,
+  inStateValue: boolean,
+  out: StrippedPaint[],
+  inInputs: boolean,
+): void {
   if (node === null || typeof node !== "object") return;
 
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
-      walk(node[i], `${path}[${i}]`, inStateValue, out);
+      const here = `${path}[${i}]`;
+      const value = node[i];
+      if (inStateValue && typeof value === "string" && pointsOutside(value)) {
+        node[i] = SAFE_PAINT;
+        out.push({ path: here, value });
+      } else {
+        walk(value, here, inStateValue, out, inInputs);
+      }
     }
     return;
   }
@@ -145,7 +164,13 @@ function walk(node: unknown, path: string, inStateValue: boolean, out: StrippedP
     const here = path ? `${path}.${key}` : key;
     const lower = key.toLowerCase();
     // 状態を入れる箱に入ったら、 その中の値はすべて状態の値として扱う
-    const nextInState = inStateValue || lower === "states" || lower === "sets" || lower === "tweens";
+    const nextInState =
+      inStateValue ||
+      lower === "states" ||
+      lower === "sets" ||
+      lower === "tweens" ||
+      (inInputs && INPUT_VALUE_KEYS.has(lower));
+    const nextInInputs = inInputs || lower === "inputs";
 
     if (typeof value === "string") {
       const isPaint = PAINT_KEYS.has(lower) || (nextInState && (lower === "initial" || lower === "to" || lower === "from" || !isReservedStateKey(lower)));
@@ -155,7 +180,7 @@ function walk(node: unknown, path: string, inStateValue: boolean, out: StrippedP
       }
       continue;
     }
-    walk(value, here, nextInState, out);
+    walk(value, here, nextInState, out, nextInInputs);
   }
 }
 

package/src/compile.ts

@@ -15,6 +15,7 @@ import type {
   DslLane,
   DslPhase,
   DslStep,
+  DslEventBinding,
   DslValue,
   PresetType,
 } from "./types";
@@ -24,6 +25,7 @@ import type {
   ErRelationCardinality,
   FormulaAst,
   LaidDiagram,
+  NodeKind,
 } from "@cardenelabs/cdl";
 import {
   sequence,
@@ -40,9 +42,11 @@ import {
   NODE_KINDS,
   applyDerivedValues,
   parseFormula,
+  extractIdentifiers,
+  inputDefaultValue,
 } from "@cardenelabs/cdl";
 import { parseFocusEntry } from "./focus";
-import { DRAW_TARGETS } from "./v05/parser";
+import { DRAW_TARGETS, DSL_ONLY_KINDS } from "./v05/parser";
 import { isColorValue, pointsOutside, stripExternalPaint } from "./color";
 import {
   MAX_INPUT_ELEMENTS,
@@ -57,6 +61,56 @@ import {
   type RelativeDirection,
 } from "./relative-pos";
 
+/**
+ * 記法だけが持つ種類を、描画できる種類へ読み替える (#1420)。
+ *
+ * 記法は `contract` / `eoa` のような **描画側に無い種類** を受け付ける
+ * (`v05/parser.ts` の `DSL_ONLY_KINDS`)。 図種ごとの役割分け (`solidity` の縦列の並べ替え
+ * など) に使うためで、記法としては正しい。
+ *
+ * **そのまま描画側へ渡すと図の組み立てが落ちる**。 描画側は知らない種類の大きさを引けず、
+ * `Cannot read properties of undefined (reading 'h')` で止まる (実測)。
+ *
+ * `solidity` と `er` は組み立ての中で別の種類に置き換えていたが、`flow` / `swimlane` /
+ * `state` / `topology` は `a.kind` をそのまま渡していた。 記法が受ける値で図が出ない状態
+ * だったので、渡す手前で必ず通す。
+ *
+ * ## 読み替え先
+ *
+ * | 種類 | 読み替え先 | なぜ |
+ * |---|---|---|
+ * | `entity` | `storage` | 表を持つ = ER 図の実体 |
+ * | `state` | `card` | 状態は札で表す |
+ * | `contract` / `proxy` / `library` / `interface` | `card` | 契約は札で表す (`solidity` の置き換え先に合わせた) |
+ * | `eoa` | `person` | 人が持つ財布 |
+ * | `multisig` | `signer` | 複数人で署名する (`solidity` の置き換え先に合わせた) |
+ *
+ * **表は `DSL_ONLY_KINDS` を鍵にして書く**。 種類を足した時に読み替え先が無いと
+ * 型検査が落ちるので、足し忘れが残らない。
+ */
+const 記法だけの種類の読み替え: Readonly<
+  Record<(typeof DSL_ONLY_KINDS)[number], NodeKind>
+> = {
+  entity: "storage",
+  state: "card",
+  contract: "card",
+  proxy: "card",
+  library: "card",
+  interface: "card",
+  eoa: "person",
+  multisig: "signer",
+};
+
+/** 描画側へ渡せる種類にする。 記法だけの種類はここで読み替わる (#1420) */
+function 描ける種別(kind: string | undefined): NodeKind {
+  if (kind === undefined) return "actor";
+  const 読み替え先 = (
+    記法だけの種類の読み替え as Record<string, NodeKind | undefined>
+  )[kind];
+  return 読み替え先 ?? (kind as NodeKind);
+}
+
+
 export interface CompileToCdlOpts {
   /**
    * CAR-1657 = parts identifier lookup catalog、 caller (CdlEditor / test) が inject。
@@ -121,7 +175,11 @@ export type CompileNotice = {
     // 起点から描く動きを持たない図種で段に `draw:` を書いた (#1312)
     | "draw-not-honored"
     // `draw:` の語がその図種と食い違う (`type: bar` に `draw: pie`、 #1314)
-    | "draw-target-mismatch";
+    | "draw-target-mismatch"
+    // 式が、どこにも書かれていない名前を読んだ (#1391)
+    | "formula-unresolved"
+    // 出来事が指す相手が図に無い (#1393)
+    | "event-target-missing";
   /** 対象の名前。 光らせる相手なら書かれた指定そのまま */
   actor: string;
   /** 書かれていた行 */
@@ -315,6 +373,132 @@ export function compileToCdl(doc: DslDocument, opts?: CompileToCdlOpts): CdlDiag
     );
     merged.readouts = [...(merged.readouts ?? []), ...ownReadouts];
   }
+  /*
+   * 読む人が動かすつまみを図に載せる (#1389)。
+   *
+   * 部品と同じく写して載せる = 出口の paint 検査が diagram を直接書き換えるため、doc の
+   * object を共有すると `compileToCdl` の入力まで書き換わって入力不変性が壊れる。
+   */
+  if (doc.inputs && doc.inputs.length > 0) {
+    const ownInputs = doc.inputs.map(
+      (input) => deepRewriteStrings(input, (value) => value) as typeof input,
+    );
+    merged.inputs = [...(merged.inputs ?? []), ...ownInputs];
+  }
+  /*
+   * つまみの値から決まる値を図に載せる (#1391)。
+   *
+   * 部品やつまみと同じく写して載せる。 式の文字列は色を塗る位置に届かないが、
+   * 入力を書き換えない形を 3 経路で揃える方が読み手に説明しやすい。
+   */
+  if (doc.formulas && doc.formulas.length > 0) {
+    const ownFormulas = doc.formulas.map((formula) => ({
+      id: formula.id,
+      expression: formula.expression,
+      line: formula.pos?.line ?? 0,
+    }));
+    /*
+     * 式が読む名前が、どこにも書かれていないことを知らせる (#1391)。
+     *
+     * engine が読める名前は、つまみと **先に宣言した式** だけ。綴り違い、状態、
+     * `values:`、後から宣言する式を渡すと、描画時に未定義参照として例外になる。
+     *
+     * **解けない式は図へ載せない**。 engine は未定義参照や input/formula の同名衝突を
+     * runtime error にするため、残すと図全体が描けない。式以外の図は出し、知らせを返す。
+     */
+    const つまみ = new Map((merged.inputs ?? []).map((input) => [input.id, input]));
+    const 先に書かれた式 = new Set((merged.formulas ?? []).map((formula) => formula.id));
+    const 載せる式 = [...(merged.formulas ?? [])];
+    for (const formula of ownFormulas) {
+      if (つまみ.has(formula.id) || 先に書かれた式.has(formula.id)) {
+        opts?.onNotice?.({
+          kind: "formula-unresolved",
+          actor: formula.id,
+          line: formula.line,
+          message: `式 "${formula.id}" の名前が、先に書かれたつまみまたは式と重なっています`,
+          hint: "`inputs:` と `formulas:` では重ならない名前を使う",
+        });
+        continue;
+      }
+      let 名前たち: Set<string>;
+      try {
+        名前たち = extractIdentifiers(parseFormula(formula.expression));
+      } catch {
+        // 読めない式は記法の読み取りが既に知らせている。 ここで二重に出さない
+        continue;
+      }
+      let 解けない = false;
+      for (const 名 of 名前たち) {
+        if (先に書かれた式.has(名)) continue;
+        const input = つまみ.get(名);
+        if (input) {
+          const 初期値 = inputDefaultValue(input);
+          if (typeof 初期値 === "number" || typeof 初期値 === "boolean") continue;
+          解けない = true;
+          opts?.onNotice?.({
+            kind: "formula-unresolved",
+            actor: formula.id,
+            line: formula.line,
+            message: `式 "${formula.id}" が、数でも真偽でもないつまみ "${名}" を読んでいます`,
+            hint: "式が読めるつまみは slider / number / stepper / timeline / toggle",
+          });
+          continue;
+        }
+        解けない = true;
+        opts?.onNotice?.({
+          kind: "formula-unresolved",
+          actor: formula.id,
+          line: formula.line,
+          message: `式 "${formula.id}" が、つまみまたは先に書かれた式ではない名前 "${名}" を読んでいます`,
+          hint: "`inputs:` に書くか、参照される式をこの式より前に書く",
+        });
+      }
+      if (解けない) continue;
+      載せる式.push({ id: formula.id, expression: formula.expression });
+      先に書かれた式.add(formula.id);
+    }
+    if (載せる式.length > 0) merged.formulas = 載せる式;
+    else delete merged.formulas;
+  }
+  /*
+   * 押下などの出来事で動く仕掛けを図に載せる (#1393)。
+   *
+   * **相手の名前を識別子へ直す**。 記法は識別子を書けないため名前で指す。 指す先が
+   * 見つからない形は載せずに知らせる = 描画側は知らない識別子を黙って無視するため、
+   * 残すと「書いたのに押しても何も起きない」 が手掛かりなしで起きる。
+   *
+   * 識別子は書いた順に `evt-1` から振る (組み立て API と同じ)。
+   */
+  if (doc.events && doc.events.length > 0) {
+    const 載せる: NonNullable<CdlDiagram["eventBindings"]> = [...(merged.eventBindings ?? [])];
+    for (const e of doc.events) {
+      const 相手 = 出来事の相手を解く(merged, doc, e);
+      if (相手 === undefined) {
+        opts?.onNotice?.({
+          kind: "event-target-missing",
+          actor: e.handlerId,
+          line: e.pos.line,
+          message: `出来事 "${e.handlerId}" が指す相手が見つかりません`,
+          hint: "box は箱の名前、 lane は縦列の名前、 arrow は `A -> B` で書く",
+        });
+        continue;
+      }
+      載せる.push({
+        id: `evt-${載せる.length + 1}`,
+        event: e.event,
+        target: 相手,
+        handlerId: e.handlerId,
+      });
+    }
+    if (載せる.length > 0) merged.eventBindings = 載せる;
+  }
+  // 巻き上げに応じて進む値を図に載せる (#1393)。 相手を持たないのでそのまま写す
+  if (doc.scrolls && doc.scrolls.length > 0) {
+    merged.scrollTriggers = [
+      ...(merged.scrollTriggers ?? []),
+      ...doc.scrolls.map((x) => ({ ...x })),
+    ];
+  }
   // 図の外を指す値を、 色を塗る位置から落とす (#1004)。
   //
   // 入口ごとに塞ぐ形は採らない。 状態の上書き / phase が入れる値 / 画面が直接書く背景色 /
@@ -997,6 +1181,26 @@ function disambiguateActorIds(
       const to = 直す(s.to);
       return from === s.from && to === s.to ? s : { ...s, from, to };
     }),
+    events: doc.events?.map((event) => {
+      const target = event.target;
+      if (target.kind === "node") {
+        const name = 直す(target.name);
+        return name === target.name ? event : { ...event, target: { ...target, name } };
+      }
+      if (target.kind === "edge") {
+        const from = 直す(target.from);
+        const to = 直す(target.to);
+        return from === target.from && to === target.to
+          ? event
+          : { ...event, target: { ...target, from, to } };
+      }
+      // sequence 系の縦列は登場人物から作るため、同じ名前の読み替えが必要。
+      if (target.kind === "lane" && (doc.type === "sequence" || doc.type === "solidity")) {
+        const name = 直す(target.name);
+        return name === target.name ? event : { ...event, target: { ...target, name } };
+      }
+      return event;
+    }),
   };
   // 光らせる指定と位置の基準も名前で書くので、 同じ表で直す
   if (次.animate) {
@@ -3048,6 +3252,49 @@ function applyEdgeInlineOptions(
   });
 }
 
+/**
+ * 出来事が指す相手を、図の識別子へ直す (#1393)。 見つからなければ `undefined`。
+ *
+ * 箱と縦列は **名前から作った識別子** と **描かれる題** の両方で探す。 記法は名前で書き、
+ * 図の識別子はそこから作られるが、見本を重ねた図など識別子が名前と揃わない形もある。
+ * 矢印は両端の名前から識別子を作って突き合わせる。
+ */
+function 出来事の相手を解く(
+  diagram: CdlDiagram,
+  doc: DslDocument,
+  e: DslEventBinding,
+): NonNullable<CdlDiagram["eventBindings"]>[number]["target"] | undefined {
+  if (e.target.kind === "diagram") return { kind: "diagram" };
+  if (e.target.kind === "edge") {
+    const from = slugify(e.target.from);
+    const to = slugify(e.target.to);
+    let 矢印: CdlEdge | undefined;
+    if (doc.type === "sequence" || doc.type === "solidity") {
+      const stepIdx = doc.flow.findIndex(
+        (step) => slugify(step.from) === from && slugify(step.to) === to,
+      );
+      if (stepIdx >= 0) {
+        矢印 = diagram.edges.find(
+          (x) =>
+            (x.from === `s${stepIdx}-${from}` || x.from === from) &&
+            (x.to === `s${stepIdx}-${to}` || x.from === x.to),
+        );
+      }
+    } else {
+      矢印 = diagram.edges.find((x) => x.from === from && x.to === to);
+    }
+    return 矢印 ? { kind: "edge", id: 矢印.id } : undefined;
+  }
+  const 名 = e.target.name;
+  const slug = slugify(名);
+  if (e.target.kind === "node") {
+    const 箱 = diagram.nodes.find((n) => n.id === slug || n.id === 名 || n.title === 名);
+    return 箱 ? { kind: "node", id: 箱.id } : undefined;
+  }
+  const 列 = (diagram.lanes ?? []).find((l) => l.id === slug || l.id === 名 || l.label === 名);
+  return 列 ? { kind: "lane", id: 列.id } : undefined;
+}
+
 /** 本文に書いた矢印の指定を、対応が取れた矢印へ書き写す。 対応の取り方は呼出側が決める。 */
 function 矢印へ書き写す(target: CdlEdge, s: DslStep, doc: DslDocument): void {
   // **書いた補足が勝つ** (#1275)。 ここで写さないと 2 つ落ちる。 静止した `type: flow` は
@@ -3071,6 +3318,11 @@ function 矢印へ書き写す(target: CdlEdge, s: DslStep, doc: DslDocument): v
   if (s.labelOffsetX !== undefined) target.labelOffsetX = s.labelOffsetX;
   if (s.labelOffsetY !== undefined) target.labelOffsetY = s.labelOffsetY;
   if (s.overlay !== undefined) target.overlay = s.overlay;
+  // 値に追随する 3 欄 (#1396)。 太さ / 色 / 破線の位置が値に合わせて動く。
+  // 通り道そのものは動かないので、配置計算と重なり解消には影響しない
+  if (s.widthBind !== undefined) target.widthBind = s.widthBind;
+  if (s.strokeBind !== undefined) target.strokeBind = s.strokeBind;
+  if (s.dashOffsetBind !== undefined) target.dashOffsetBind = s.dashOffsetBind;
 }
 
 /**
@@ -5129,7 +5381,7 @@ function compileC4(doc: DslDocument): CdlDiagram {
     b.node(x.id, {
       lane: lid,
       stack,
-      kind: x.actor.kind,
+      kind: 描ける種別(x.actor.kind),
       title: x.actor.name,
     });
   }
@@ -5255,7 +5507,13 @@ type 放射で描けない欄 =
   // 箱の中に描く図形 (#1374)。 放射の枝は箱の中に図形を持たない
   | "shape"
   // 出す条件 (#1381)。 放射の枝は個別に出し分けられない
-  | "visibleIf";
+  | "visibleIf"
+  // 値に追随する 5 欄 (#1392)。 放射の枝は大きさも位置も中心からの配置で決まる
+  | "wBind"
+  | "hBind"
+  | "opacity"
+  | "renderOffsetX"
+  | "renderOffsetY";
 
 /** 引数が `never` でなければ型検査が落ちる */
 type 空であること<T extends never> = T;
@@ -5312,6 +5570,11 @@ const 放射で描けない欄の名前: Record<放射で描けない欄, string
   layoutPos: "配置のずらし",
   shape: "箱の中の図形",
   visibleIf: "出す条件",
+  wBind: "値に追随する大きさ",
+  hBind: "値に追随する大きさ",
+  opacity: "濃さ",
+  renderOffsetX: "描く時のずらし",
+  renderOffsetY: "描く時のずらし",
 };
 
 /**
@@ -5737,6 +6000,18 @@ function applyV05Extensions(
           if (footer) footer.visibleIf = a.visibleIf;
         }
       }
+      /*
+       * 値に追随する 5 欄 (#1392)。
+       *
+       * **名札と足へは渡さない**。 `visibleIf` は片方だけ隠すと順序図の縦線の頭と足が
+       * 食い違うため揃えるが、こちらは見た目の大きさ / 濃さ / ずらしで、名札まで同じだけ
+       * 動かすと縦線の頭が本体から離れる。 書いた箱にだけ効かせる。
+       */
+      if (a.wBind !== undefined) node.wBind = a.wBind;
+      if (a.hBind !== undefined) node.hBind = a.hBind;
+      if (a.opacity !== undefined) node.opacity = a.opacity;
+      if (a.renderOffsetX !== undefined) node.renderOffsetX = a.renderOffsetX;
+      if (a.renderOffsetY !== undefined) node.renderOffsetY = a.renderOffsetY;
     }
   }
   // 名札の高さを揃える。 kind ごとに高さが変わると縦線の始まる位置がばらけ、 順序図の
@@ -6160,7 +6435,7 @@ function compileFlow(doc: DslDocument): CdlDiagram {
     flowBuilder.step(
       {
         id: slugify(a.name) || `n${i}`,
-        kind: a.kind,
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
       },
       edgeLabel,
@@ -6199,7 +6474,7 @@ function compileSwimlane(doc: DslDocument): CdlDiagram {
       swim.node(nodeId, {
         lane: laneId,
         stack,
-        kind: actor?.kind ?? "actor",
+        kind: 描ける種別(actor?.kind),
         title: actorName,
       });
       laneStackCount.set(laneId, stack + 1);
@@ -6230,7 +6505,7 @@ function compileSwimlane(doc: DslDocument): CdlDiagram {
       swim.node(slugify(a.name) || `n${i}`, {
         lane: swim.laneId(a.name),
         stack: 0,
-        kind: a.kind ?? "actor",
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
       });
     });
@@ -6353,7 +6628,7 @@ function compileTopology(doc: DslDocument): CdlDiagram {
   for (const a of doc.actors) {
     groupBuilder.add({
       id: slugify(a.name) || a.name,
-      kind: a.kind,
+      kind: 描ける種別(a.kind),
       title: 箱の題(a),
     });
   }
@@ -6441,24 +6716,64 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
   // lane / node 配置 ... preset kind に応じて切替
   const actorToNodeId = new Map<string, string>();
   if (書いた縦列に置く(kind, doc)) {
-    // **書いた縦列に置く** (#1263)。 縦列を並べるための入れ物として使う図種でだけ効く。
-    // 縦列は書かれた順に作り、同じ縦列の箱は書かれた順に積む
-    const 並び: string[] = [];
+    /*
+     * **書いた縦列に置く** (#1263)。 縦列を並べるための入れ物として使う図種でだけ効く。
+     *
+     * 縦列の並びは **`lanes:` に書いた順** を優先する (#1394)。 箱が最初に使った順で
+     * 並べていた間、`lanes:` で左から順に宣言しても箱の書き順で入れ替わっていた
+     * (実測 = 中心を先に書いた放射の図で、左端の縦列が中心の右へ回った)。
+     *
+     * `lanes:` に無い縦列は、これまでどおり箱が使った順で後ろに続ける。
+     */
+    const 使った: string[] = [];
     for (const a of doc.actors) {
       const lid = a.lane;
-      if (lid !== undefined && !並び.includes(lid)) 並び.push(lid);
+      if (lid !== undefined && !使った.includes(lid)) 使った.push(lid);
     }
+    const 書いた順 = doc.lanes ? Object.keys(doc.lanes) : [];
+    const 並び = [
+      ...書いた順.filter((lid) => 使った.includes(lid)),
+      ...使った.filter((lid) => !書いた順.includes(lid)),
+    ];
     for (const lid of 並び) {
       b.lane(lid, { width: laneWidth, ...(kind === "topology" ? { contain: true } : {}) });
     }
-    const 積んだ数 = new Map<string, number>();
+    /*
+     * 段は **書いた番号をそのまま持つ** (#1394)。
+     *
+     * 書き順で 0 から詰め直していた間、`stack: 1` と書いた箱が 0 へ落ちていた。
+     * 決定木のように「同じ高さに並ばない」 ことが図の意味そのものになる形では、
+     * 詰めた瞬間に別の図になる (実測 = 3 段の木の根が 1 段目へ上がった)。
+     *
+     * 書かなかった箱は、その縦列で **空いている一番小さい段** に置く。 単に数え上げると
+     * 書いた番号と重なり、2 つの箱が同じ段に載る。
+     */
+    const 埋まった段 = new Map<string, Set<number>>();
+    const 埋める = (lid: string, stack: number): void => {
+      const 集合 = 埋まった段.get(lid) ?? new Set<number>();
+      集合.add(stack);
+      埋まった段.set(lid, 集合);
+    };
+    for (const a of doc.actors) {
+      if (a.lane !== undefined && a.stack !== undefined) 埋める(a.lane, a.stack);
+    }
     doc.actors.forEach((a, idx) => {
       const id = slugify(a.name) || `n${idx}`;
       actorToNodeId.set(a.name, id);
       const lid = a.lane!;
-      const stack = 積んだ数.get(lid) ?? 0;
-      積んだ数.set(lid, stack + 1);
-      b.node(id, { lane: lid, stack, kind: a.kind, title: 箱の題(a) });
+      let stack = a.stack;
+      if (stack === undefined) {
+        stack = 0;
+        const 集合 = 埋まった段.get(lid);
+        while (集合?.has(stack)) stack += 1;
+        埋める(lid, stack);
+      }
+      b.node(id, {
+        lane: lid,
+        stack,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
     });
   } else if (kind === "flow" || kind === "topology") {
     // 1 lane に全 actor を縦 stack
@@ -6471,7 +6786,12 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
     doc.actors.forEach((a, idx) => {
       const id = slugify(a.name) || `n${idx}`;
       actorToNodeId.set(a.name, id);
-      b.node(id, { lane: lid, stack: idx, kind: a.kind, title: 箱の題(a) });
+      b.node(id, {
+        lane: lid,
+        stack: idx,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
     });
   } else {
     // swimlane / er / state ... actor ごとに 1 lane (横並び)
@@ -6496,7 +6816,7 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
       b.node(id, {
         lane: lid,
         stack: 0,
-        kind: a.kind,
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
         ...(isInitial ? { eyebrow: "初期" } : {}),
         ...(isFinal ? { eyebrow: "最終" } : {}),

package/src/index.ts

@@ -11,6 +11,17 @@
 export { parseTextDsl } from "./parser";
 export { compileToCdl } from "./compile";
 export type { CompileNotice } from "./compile";
+/**
+ * 組み立てた図の型 (#1415)。
+ *
+ * `textDslToDiagram` が返す型そのもので、実体は `@cardenelabs/cdl` が持つ。 使う側が
+ * 戻り値に型を付けるには必ず要るので、ここから引けるようにする。
+ *
+ * 再 export が無い間、使う側は `@cardenelabs/cdl` を直接の依存に足す必要があった。
+ * 足さずに書くと **型が暗黙の `any` に落ち、その先の `.map((n) => ...)` まで検査が効かなく
+ * なる** (実測 = この 1 件が 39 件の暗黙 `any` を生んでいた)。
+ */
+export type { CdlDiagram } from "@cardenelabs/cdl";
 export { parseTextDslV05 } from "./v05";
 // 記法一覧が「実際に受け付ける値」 を実装から引くための公開。 手書きすると説明と実装がずれる。
 export { DRAW_TARGETS, DRAW_WORDS, PHASE_ITEM_WORDS, PRESET_TYPES, TOP_LEVEL_KEYS } from "./v05/parser";

package/src/input-size.ts

@@ -69,6 +69,18 @@ export function countDocElements(doc: DslDocument): number {
     // 値を見せる部品も描画時に 1 widget ずつ展開される (#1374)。 数えないと、 actors が
     // 少ないまま readouts だけを大量に並べた入力が組み立て前の上限をすり抜ける。
     (doc.readouts?.length ?? 0) +
+    // 読む人が動かすつまみも 1 widget ずつ展開される (#1389)。 readouts と同じ上限で守る。
+    (doc.inputs?.length ?? 0) +
+    /*
+     * 式 (#1391) と、押下 / 巻き上げ (#1393) も数える。
+     *
+     * **図の側 (`countDiagramElements`) は既に数えている**。 記法側だけ数えないと、
+     * 箱が少ないままこれらを大量に並べた入力が組み立て前の上限をすり抜け、
+     * 組み立て終わってから (= 時間をかけてから) 図の側で弾かれる。
+     */
+    (doc.formulas?.length ?? 0) +
+    (doc.events?.length ?? 0) +
+    (doc.scrolls?.length ?? 0) +
     (doc.groups ? Object.keys(doc.groups).length : 0) +
     (doc.lanes ? Object.keys(doc.lanes).length : 0)
   );