@cardenelabs/dragon 0.7.0

package/src/focus.ts

@@ -0,0 +1,46 @@
+/**
+ * 光らせる相手 (`focus:`) の書き方を読む。
+ *
+ * 書き方は 2 通り。 箱の名前 1 つか、 矢印 (`A -> B`) で 2 者を指す形。
+ *
+ * 読み方をここに 1 つだけ置く。 id の形は図種で違う (順序図は縦列の上端 / 下端 / 手順箱、
+ * 流れ図は箱 1 個) ため id への解決は図種ごとに残すが、 「どちらの書き方か」 の判断を
+ * 図種ごとに持つと、 同じ記述が図種によって別の意味になる。
+ *
+ * 以前は図種ごとに判定していて、 順序図と汎用の 2 経路が `-` 1 文字を矢印と見なしていた。
+ * その結果 `api-gateway` のような名前が「api から gateway への矢印」 と読まれ、 順序図では
+ * 光らず、 流れ図では名前に部分一致した別の矢印が光っていた (実測)。
+ */
+
+/** 光らせる相手の指定。 */
+export type FocusEntry =
+  | { kind: "edge"; from: string; to: string }
+  | { kind: "node"; name: string };
+
+/**
+ * 矢印の形。 `->` の 2 文字か `→` の 1 文字だけを矢印と見なす。
+ *
+ * `-` 1 文字を矢印に含めてはいけない。 名前に `-` を使う箱 (`api-gateway` / `shape-api-gateway`)
+ * が矢印として読まれる。
+ */
+const ARROW = /^(.+?)\s*(?:->|→)\s*(.+)$/;
+
+/**
+ * 書かれた 1 件を読む。
+ *
+ * 矢印の両側は 1 文字以上を要求するので、 片側だけの形 (`-> API` / `API ->`) は矢印に
+ * ならず名前として読まれる。
+ *
+ * `knownNames` に一致する名前は矢印より先に名前として読む。 引用符付きで矢印を含む名前
+ * (`"A -> B"`) を書いた箱は実在し得るので、 常に矢印と読むと光らせられない (実測 = 名前が
+ * 一致する箱があるのに何も光らず、 「矢印が流れにありません」 と誤報した)。
+ *
+ * @param knownNames 実在する箱の名前。 渡さない場合は書き方だけで判断する
+ */
+export function parseFocusEntry(raw: string, knownNames?: ReadonlySet<string>): FocusEntry {
+  const item = raw.trim();
+  if (knownNames?.has(item)) return { kind: "node", name: item };
+  const m = item.match(ARROW);
+  if (!m) return { kind: "node", name: item };
+  return { kind: "edge", from: m[1]!.trim(), to: m[2]!.trim() };
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+/**
+ * Dragon — Text DSL public API
+ *
+ * Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を呼出して CdlDiagram を返す。
+ *
+ * 使い方:
+ *   const diagram = textDslToDiagram(source);
+ *   // diagram は @cardenelabs/cdl の CdlDiagram、 そのまま CdlDiagramView 等に渡せる
+ */
+
+export { parseTextDsl } from "./parser";
+export { compileToCdl } from "./compile";
+export type { CompileNotice } from "./compile";
+export { parseTextDslV05 } from "./v05";
+// 記法一覧が「実際に受け付ける値」 を実装から引くための公開。 手書きすると説明と実装がずれる。
+export { PRESET_TYPES } from "./v05/parser";
+export { TONE_ALIAS, NODE_KIND_ALIAS } from "./keywords";
+export { lintDiagram, autoFix } from "./notation-lint";
+export type { LintIssue, LintReport, LintSeverity } from "./notation-lint";
+// canvas pivot 新 spec 図境界計算 helper (§diagram-boundary SSOT)
+export {
+  computeDiagramBoundingBox,
+  rectsOverlap,
+  DIAGRAM_BOUNDARY_PADDING,
+} from "./canvas-bounds";
+export type { DiagramBoundingBox } from "./canvas-bounds";
+// 位置を相対で書くための解決。 組み立て側と画面側の両方が同じ規則を使うために公開する。
+export {
+  parseRelativePos,
+  resolveRelativePos,
+  orderByDependency,
+  RELATIVE_GAP_DEFAULT,
+} from "./relative-pos";
+export type { RelativePos, RelativeDirection, AnchorBox } from "./relative-pos";
+// 光らせる相手の書き方の読み取り。 図種ごとの解決経路が同じ規則を共有する。
+export { parseFocusEntry } from "./focus";
+export type { FocusEntry } from "./focus";
+// 画面で見えている座標を記法に落とすための書込み。 記法を知る側に置く。
+export { writeActorPosition } from "./write-position";
+// 図の上での位置を測る。 editor が現在位置を出すのと、 相対指定を解くので同じ規則を使う。
+export { measureActorBoxes } from "./compile";
+// パーツの見た目の大きさと、 位置を書かなかった時の格子。 画面側と組み立て側で同じ規則を使う。
+// 記法が受理する種類の全体。 画面側が「本文が見本を使っているか」 を判定するのに使う (#1022)。
+export { NODE_KIND_VALID } from "./v05/parser";
+
+// パーツの大きさを測る 3 つ。 用途で使い分ける (取り違えると経路ごとに絵が変わる)。
+//
+// - `partRenderSize` = 図枠。 画面が描く大きさと、 格子が確保する場所に使う
+// - `partBoxInFrame` = 図枠の中の箱 (パーツ自身の座標)。 画面が書いた座標と相対指定を解くのに使う
+// - `partVisualSize` = 箱の外接矩形 (merge の座標)。 組み立て側が取り込んだ後の大きさに使う
+//
+// 格子だけ図枠なのは、 隣と重ならない幅を確保するのが目的で描く大きさそのものが要るため。
+// 座標と間隔は見えている箱で測る (#937 / #1014)。
+// `大きさ:` の倍率は `partTargetScale` が持つ。 画面側も同じ規則で拡大しないと、
+// 書いた見本だけ経路で大きさが変わる (#1018)。
+// `partDrawsInDiagram` = その見本が図の中に描かれる部品を持つか。 実体が操作パネルの
+// 部品だけの見本 (catalog 80 件中 17 件) は重ねても図に出ないため、画面側が知らせる (#1017)。
+// `倍率:` (`scale`) は図形の倍率として予約する (#1026)。 画面と組み立てで意味が違うと、
+// 同じ本文が経路で別の絵になる。 正規化 (`normalizePartScale`) と `大きさ:` との掛け合わせ
+// (`partTargetSize`) を engine 側に置き、画面側も同じ関数を呼ぶ。
+export {
+  partRenderSize,
+  partVisualSize,
+  partBoxInFrame,
+  partTargetScale,
+  partTargetSize,
+  partScaleFactor,
+  normalizePartScale,
+  MAX_PART_SCALE,
+  partDrawsInDiagram,
+  partIsMeasurable,
+  partsGridCenters,
+} from "./compile";
+// 色として読めるかの判定と、 図の外を指す値かの判定。 状態の上書きを受け取る側 / 画面が色欄を
+// 作る側 / 画面が背景色を直接書く側で同じ物差しを使う (別々に持つと、 片方だけ直した時に片方が通す)。
+export { isColorValue, pointsOutside, stripExternalPaint } from "./color";
+// 引用符の外し方 (#1028)。 画面側が本文から見本を抜く時に同じ判定を使う。
+// 別々に持つと、片方だけが読める本文ができる (実測 = `位置: '300,200"` が
+// 画面側では座標 300 として通り、組み立て側では読めない値として知らせが出た)
+export { stripQuotes } from "./v05/parser";
+// 大きすぎる入力を組み立てる前に止める上限 (#1005)。 画面側も同じ物差しで事前に知らせられるよう公開する。
+export {
+  MAX_INPUT_ELEMENTS,
+  MAX_INPUT_BYTES,
+  countDocElements,
+  countDiagramElements,
+  countBytes,
+  describeOversize,
+  describeOversizeSource,
+} from "./input-size";
+export type { InputSize } from "./input-size";
+
+// LLM 向け JSON DSL (Issue #208)
+export { jsonToDiagram, validateDragonJson } from "./json-parser";
+export { diagramJsonSchema } from "./schema";
+export type {
+  DragonJson,
+  JsonActor,
+  JsonStep,
+  JsonPhase,
+  JsonDslError,
+} from "./json-parser";
+export type {
+  DslDocument,
+  DslActor,
+  DslStep,
+  DslAnimate,
+  DslState,
+  DslPhase,
+  DslTween,
+  DslSet,
+  DslError,
+  PresetType,
+  DslLane,
+  DslGroup,
+  DslViewport,
+  // CAR-1693 Phase 1: canvas pivot DSL 表面 pos + layout mode の public 型
+  LayoutPos,
+  LayoutMode,
+} from "./types";
+
+import { parseTextDsl } from "./parser";
+import { parseTextDslV05 } from "./v05";
+import { compileToCdl } from "./compile";
+import { describeOversizeSource } from "./input-size";
+import type { CompileNotice } from "./compile";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+
+/**
+ * CAR-1657 = compile 時 parts identifier lookup 用 catalog。
+ * caller (CdlEditor 等) が loadPartsItems() の結果を Record<partId, CdlDiagram> で inject。
+ * 未渡し時 partId set actor は「未解決」 として skip + console.warn (diagram render は継続)。
+ */
+export interface CompileOpts {
+  partsCatalog?: Record<string, CdlDiagram>;
+  /**
+   * 図は出せるが書いた通りにならなかったことの受け取り口 (`位置: Web の下` が順序図で
+   * 効かない等)。 判定は組み立て側が持ち、 呼出側は受け取って表示するだけにする。
+   */
+  onNotice?: (notice: CompileNotice) => void;
+  /**
+   * edge が DSL のどの行から来たかの受け取り口 (#998)。
+   *
+   * preset によっては書いた step と生成される edge が一致しない (`type: flow` は actor を鎖状に
+   * 繋ぐため `a -> c` と書いても `a -> b` になる)。 edge を起点に本文の行を直す機能 (自動修正の
+   * 書き戻し等) は、 この対応が無いと別の行を書き換える。
+   *
+   * **対応が取れない edge については呼ばれない**。 「対応が無い」 と「行 0」 を区別するため。
+   */
+  onEdgeSource?: (edgeId: string, line: number) => void;
+}
+
+/**
+ * Dragon DSL から CdlDiagram に一発変換。 v0.5 (英語 keyword) / v0.4 (日本語 keyword) を auto-detect。
+ *
+ * 判定 ... src 内に v0.5 専用 syntax (`animation:` block / `- A -> B` flow / `step: "..."` ) を含むなら v0.5、
+ * 含まなければ v0.4 (deprecated、 console.warn を出す)。
+ *
+ * エラー時は throw、 詳細を取りたい場合は parseTextDslV05 / parseTextDsl を直接呼ぶ。
+ * opts.partsCatalog を渡すと CAR-1657 parts kind (arc-gauge 等) の actor が merge 展開される。
+ */
+export function textDslToDiagram(src: string, opts?: CompileOpts): CdlDiagram {
+  // 読み取る前に大きさを見る (#1005)。 要素数の上限は読み取った後にしか分からないため、
+  // 巨大な本文そのものによる待ちと記憶の消費はここでしか防げない
+  const oversize = describeOversizeSource(src);
+  if (oversize) throw new Error(oversize);
+
+  if (isV05Source(src)) {
+    const r = parseTextDslV05(src);
+    if (!r.ok) {
+      const msg = r.errors
+        .map((e) => `  L${e.line}: ${e.message}${e.hint ? `\n         hint: ${e.hint}` : ""}`)
+        .join("\n");
+      throw new Error(`Dragon DSL v0.5 parse error:\n${msg}`);
+    }
+    return compileToCdl(r.doc, opts);
+  }
+  // v0.4 fallback (deprecated)
+  if (typeof console !== "undefined" && console.warn) {
+    console.warn(
+      "[dragon] v0.4 syntax (Japanese keywords) is deprecated. Please migrate to v0.5 (English keywords) by 2026-12-31.",
+    );
+  }
+  const r = parseTextDsl(src);
+  if (!r.ok) {
+    const msg = r.errors
+      .map((e) => `  L${e.line}: ${e.message}${e.hint ? `\n         ヒント: ${e.hint}` : ""}`)
+      .join("\n");
+    throw new Error(`Dragon DSL parse error:\n${msg}`);
+  }
+  return compileToCdl(r.doc, opts);
+}
+
+function isV05Source(src: string): boolean {
+  // CAR-1657 (+ codex-review MAJOR fix) = v0.5 default + v0.4 marker detect。
+  //
+  // v0.4 は 2026-12-31 廃止予定、 新規 source は v0.5 前提で default を v0.5 に倒す。
+  // v0.4 marker (Japanese header + v0.4-specific English syntax) を 1 個でも検出したら v0.4 route。
+  //
+  // codex 指摘 = v0.4 も英語 alias `animate:` / `animation:` を受理するため、 header 名だけでは
+  // 判定不足。 v0.4-specific syntax (`step "..." Xs` = colon なし step / `^\d+\.\s+` = 番号 flow) を
+  // negative marker に追加。
+  const V04_KEYWORDS = [
+    // Japanese v0.4 専用 keyword (v0.5 は英語のみ)
+    /^\s*タイトル\s*[:：]/,     // title (JA)
+    /^\s*種類\s*[:：]/,          // type (JA)
+    /^\s*登場人物\s*[:：]/,      // actors (JA)
+    /^\s*流れ\s*[:：]/,          // flow (JA)
+    /^\s*アニメーション\s*[:：]/,  // animation (JA)
+    /^\s*動作\s*[:：]/,          // step (JA)
+    /^\s*状態\s*[:：]/,          // state (JA)
+    /^\s*ステップ\s*[「『]/,     // step (JA)
+    // v0.4 English-specific syntax = colon なし step (v0.5 は step: 必須)
+    /^\s*step\s+"[^"]+"\s+[\d.]+\s*s\b/,
+    /^\s*step\s+'[^']+'\s+[\d.]+\s*s\b/,
+    // v0.4 numbered flow (`1. A → B`、 v0.5 は `- A -> B`)
+    /^\s*\d+\.\s+\S+\s*(?:→|->)\s*\S+/,
+  ];
+  const lines = src.split("\n");
+  for (const ln of lines) {
+    for (const kw of V04_KEYWORDS) {
+      if (kw.test(ln)) return false; // v0.4 detected → false
+    }
+  }
+  return true; // no v0.4 marker → v0.5 default
+}

package/src/input-size.ts

@@ -0,0 +1,154 @@
+import type { DslDocument } from "./types";
+
+/**
+ * 図を組み立てる前に、 大きすぎる入力を止める (#1005)。
+ *
+ * 組み立てにかかる時間は要素数の 2 乗で伸びる。 実測 (要素だけを並べた形)。
+ *
+ * | 要素 | 組み立て |
+ * |---|---|
+ * | 1,000 | 104ms |
+ * | 2,000 | 346ms |
+ * | 5,000 | 1,647ms |
+ * | 10,000 | 7,622ms |
+ *
+ * 待機 (500ms) の後に同じ流れの中で走るため、 この間 editor は操作を受け付けない。
+ * 貼ってしまうと tab を閉じるまで戻らない。
+ *
+ * 見本 (catalog) は 1 図あたり平均 4 要素、 最も多い file でも平均 7 要素。 実用の規模と
+ * 1 秒の境界 (約 3,000 要素) は桁が 2-3 つ違うため、 上限を置いても正当な図には当たらない。
+ *
+ * 既にある `dom-complexity-budget` (400 要素) とは別物。 あちらは組み立てた**後**に
+ * 「見やすさ」 の観点で警告を出すだけで、 組み立て自体は走る。 こちらは組み立てる**前**に
+ * 「固まらない」 ために止める。 400-2,000 の範囲は従来どおり警告が出て図も描ける。
+ */
+
+/** 組み立てを止める要素数。 1 秒を明確に下回る水準に置く (2,000 要素で約 350ms) */
+export const MAX_INPUT_ELEMENTS = 2000;
+
+/**
+ * 組み立てを止める本文の大きさ (byte)。
+ *
+ * 要素数だけでは、 1 要素に極端に長い文字列を持つ形を捉えられない。 読み取り自体は速い
+ * (10,000 要素 98,936 byte で 2ms) ので、 実用の余裕を大きく取って置く。
+ */
+export const MAX_INPUT_BYTES = 512 * 1024;
+
+/** 数えた結果。 超過した時に何がどれだけ超えたかを画面に出すために使う */
+export interface InputSize {
+  elements: number;
+  bytes: number;
+}
+
+/**
+ * 記法の解析結果から要素数を数える。
+ *
+ * 数えるのは組み立ての重さに効くもの = 要素 / 流れ / 段 / 状態 / 段組み。
+ * 図の題名や表示の設定は数に入れない (何件あっても重さが変わらない)。
+ *
+ * **段の中身 (光らせる相手 / 遷移 / 即時変更) も数える**。 段の数だけを見ると、
+ * 1 段に 1,000 件の相手を書いた形が 1 件として通る。 実測ではこの形が組み立ての中で
+ * 約 100 万件に展開され、 呼び出しの深さが上限を超えて落ちた。
+ */
+export function countDocElements(doc: DslDocument): number {
+  const phases = doc.animate?.phases ?? [];
+  const phaseChildren = phases.reduce(
+    (acc, p) => acc + (p.highlight?.length ?? 0) + (p.tweens?.length ?? 0) + (p.sets?.length ?? 0),
+    0,
+  );
+  return (
+    doc.actors.length +
+    doc.flow.length +
+    phases.length +
+    phaseChildren +
+    (doc.animate?.states.length ?? 0) +
+    (doc.groups ? Object.keys(doc.groups).length : 0) +
+    (doc.lanes ? Object.keys(doc.lanes).length : 0)
+  );
+}
+
+/**
+ * 組み立て済みの図から要素数を数える。
+ *
+ * 記法を通らない入口 (本文に埋め込んだ図の定義) 用。 解析結果が無いため、 図の側で数える。
+ *
+ * **段の中身と読み取り部品も数える**。 段を 1 件として数えるだけだと、段の中に 10,000 件の
+ * 光らせる指定を持つ図が「1 要素」 と判定されて素通りする (実測)。 記法側の数え方
+ * (`countDocElements`) は段の中身を足しているので、こちらも揃える。
+ */
+export function countDiagramElements(diagram: {
+  nodes?: unknown[];
+  edges?: unknown[];
+  lanes?: unknown[];
+  states?: unknown[];
+  phases?: unknown[];
+  readouts?: unknown[];
+  inputs?: unknown[];
+  formulas?: unknown[];
+  scrollTriggers?: unknown[];
+  eventBindings?: unknown[];
+}): number {
+  const phases = Array.isArray(diagram.phases) ? diagram.phases : [];
+  const phaseChildren = phases.reduce((acc: number, p) => {
+    const ph = p as { activate?: unknown[]; highlight?: unknown[]; tweens?: unknown[]; sets?: unknown[] };
+    return (
+      acc +
+      (Array.isArray(ph?.activate) ? ph.activate.length : 0) +
+      (Array.isArray(ph?.highlight) ? ph.highlight.length : 0) +
+      (Array.isArray(ph?.tweens) ? ph.tweens.length : 0) +
+      (Array.isArray(ph?.sets) ? ph.sets.length : 0)
+    );
+  }, 0);
+  return (
+    (diagram.nodes?.length ?? 0) +
+    (diagram.edges?.length ?? 0) +
+    (diagram.lanes?.length ?? 0) +
+    (diagram.states?.length ?? 0) +
+    phases.length +
+    phaseChildren +
+    // 図が持てる並びは全部数える。 1 つでも外すと、そこに寄せた図が素通りする
+    (diagram.readouts?.length ?? 0) +
+    (diagram.inputs?.length ?? 0) +
+    (diagram.formulas?.length ?? 0) +
+    (diagram.scrollTriggers?.length ?? 0) +
+    (diagram.eventBindings?.length ?? 0)
+  );
+}
+
+/** 本文の大きさを byte で数える (文字数ではなく実際の大きさ) */
+export function countBytes(src: string): number {
+  // Node にも browser にもある形で数える。 `Buffer` は browser に無い
+  return new TextEncoder().encode(src).length;
+}
+
+/**
+ * 大きすぎる入力なら、 その旨を伝える文を返す。 収まっていれば `null`。
+ *
+ * 投げるのではなく文を返すのは、 呼出側が「誤りとして表示する」 か「別の扱いにする」 かを
+ * 選べるようにするため。
+ *
+ * `bytes` に 0 を渡すと大きさの検査を飛ばす (要素数だけを見たい合流点で使う)。
+ */
+export function describeOversize(size: InputSize): string | null {
+  if (size.elements > MAX_INPUT_ELEMENTS) {
+    return `要素が ${size.elements.toLocaleString()} 件あります。 ${MAX_INPUT_ELEMENTS.toLocaleString()} 件までにしてください (これ以上は組み立てに時間がかかり、 画面が止まります)`;
+  }
+  if (size.bytes > MAX_INPUT_BYTES) {
+    // KB の整数で出す。 MB 小数 1 桁だと、 1 byte 超えただけの時に「0.5MB / 上限 0.5MB」 と
+    // 同じ数字が並び、 制限内なのに拒まれたように読める
+    const kb = Math.ceil(size.bytes / 1024);
+    const limitKb = Math.floor(MAX_INPUT_BYTES / 1024);
+    return `本文が ${kb.toLocaleString()}KB あります。 ${limitKb.toLocaleString()}KB までにしてください (これ以上は読み取りだけで待たされ、 記憶も大きく使います)`;
+  }
+  return null;
+}
+
+/**
+ * 本文が大きすぎるなら、 その旨を伝える文を返す。 収まっていれば `null`。
+ *
+ * **読み取る前に呼ぶ**。 要素数の上限は読み取った後にしか分からないため、 巨大な本文を
+ * 渡された時の読み取り自体 (11.9MB で記憶 200MB) を防げない。
+ */
+export function describeOversizeSource(src: string): string | null {
+  return describeOversize({ elements: 0, bytes: countBytes(src) });
+}