@cardenelabs/dragon 0.34.0 → 0.35.0

package/src/timeline.ts

@@ -0,0 +1,166 @@
+/**
+ * 段ごとの始まりと長さと、線、運ぶ物、線の名前、段の番号が見える時刻の表。SVG の動きはこの表から組む。
+ *
+ * 段の長さは本文の字数で決め、段で起きることが全部済んでから少し留まる長さを下限にする。
+ * 運ぶ物は主役 (封筒と札は 1 つ、硬貨は別の 1 つ) ごとに途切れず見え続ける。着いた後は
+ * 次の同じ主役が出発するまで着いた先に留まり、次が無ければ終わりまで留まる。
+ * 線の名前はその段の間だけ出し、同じ段に何本あっても同時に見えるのは 2 つまでにする。
+ */
+import { MOTION } from "./look/values";
+import type { Diagram } from "./schema";
+
+/** 秒で表した、見えている間。`end` の時刻は含まない。 */
+export interface Span {
+  start: number;
+  end: number;
+}
+
+/** 線を引いている間。`start` で引き始め、`drawn` で引き終わり、`end` (段の終わり) まで濃く残す。 */
+export interface EdgeTime extends Span {
+  step: number;
+  event: number;
+  drawn: number;
+}
+
+/** 運ぶ物が見えている間。`depart` に出発し `arrive` に着く。出発を待つ間と、着いた先で留まる間も含む。 */
+export interface CarrierTime extends Span {
+  step: number;
+  event: number;
+  who: "main" | "coin";
+  depart: number;
+  arrive: number;
+}
+
+export interface LabelTime extends Span {
+  step: number;
+  event: number;
+}
+
+/** 処理、箱の字の書き換え、中身の帯の値が起きる時刻。 */
+export interface EventTime {
+  step: number;
+  event: number;
+  at: number;
+}
+
+export interface Timeline {
+  /** 1 周の長さ */
+  total: number;
+  /** 繰り返す前に消えていく所の始まり */
+  last: number;
+  steps: Span[];
+  edges: EdgeTime[];
+  carriers: CarrierTime[];
+  labels: LabelTime[];
+  badges: { step: number; appears: number }[];
+  events: EventTime[];
+  /** 段ごとの止め絵の時刻。その段で起きることが全部見えている */
+  stills: number[];
+}
+
+interface Planned {
+  edges: { event: number; a: number; b: number; carries: boolean; coin: boolean; named: boolean }[];
+  events: { event: number; at: number }[];
+  busy: number;
+}
+
+/** 段の中で起きることの時刻 (段の始まりから)。線は少しずつずらして引き、書き換えは直前の線が着いてから起こす。 */
+function plan(step: Diagram["steps"][number]): Planned {
+  const out: Planned = { edges: [], events: [], busy: 0 };
+  let cursor = MOTION.edgeAt;
+  let arrived: number | undefined;
+  let changes = 0;
+  step.events.forEach((event, e) => {
+    if (event.type === "edge") {
+      const carries = event.carry.kind !== "none";
+      const a = cursor;
+      const b = a + (carries ? MOTION.drawCarry : MOTION.draw);
+      out.edges.push({ event: e, a, b, carries, coin: event.carry.kind === "coin", named: event.label !== undefined });
+      cursor = a + MOTION.stagger;
+      arrived = b;
+      changes = 0;
+      out.busy = Math.max(out.busy, b);
+    } else if (event.type === "action") {
+      out.events.push({ event: e, at: cursor });
+      out.busy = Math.max(out.busy, cursor + MOTION.action);
+      cursor += MOTION.action;
+      changes = 0;
+    } else {
+      const at = (arrived ?? cursor) + MOTION.change * changes++;
+      out.events.push({ event: e, at });
+      out.busy = Math.max(out.busy, at);
+    }
+  });
+  return out;
+}
+
+export function buildTimeline(diagram: Diagram): Timeline {
+  const plans = diagram.steps.map(plan);
+  const steps: Span[] = [];
+  let t = MOTION.intro;
+  diagram.steps.forEach((step, s) => {
+    const read = Math.min(MOTION.stepMax, Math.max(MOTION.stepMin, MOTION.stepBase + [...step.body].length * MOTION.perChar));
+    const length = Math.max(read, (plans[s]?.busy ?? 0) + MOTION.dwell);
+    steps.push({ start: t, end: t + length });
+    t += length;
+  });
+  const end = t;
+  const total = Math.ceil(end + MOTION.outro);
+  const last = total - MOTION.tail;
+
+  const edges: EdgeTime[] = [];
+  const labels: LabelTime[] = [];
+  const events: EventTime[] = [];
+  const departures: { step: number; event: number; who: "main" | "coin"; a: number; b: number }[] = [];
+  plans.forEach((p, s) => {
+    const span = steps[s] as Span;
+    const named: LabelTime[] = [];
+    for (const edge of p.edges) {
+      const a = span.start + edge.a;
+      edges.push({ step: s, event: edge.event, start: a, drawn: span.start + edge.b, end: span.end });
+      if (edge.carries) departures.push({ step: s, event: edge.event, who: edge.coin ? "coin" : "main", a, b: span.start + edge.b });
+      if (edge.named) named.push({ step: s, event: edge.event, start: a + MOTION.labelDelay, end: span.end });
+    }
+    // 3 つ目の名前が出る時に 1 つ目を消す
+    named.forEach((label, k) => {
+      const later = named[k + 2];
+      if (later) label.end = Math.min(label.end, later.start);
+    });
+    labels.push(...named);
+    for (const event of p.events) events.push({ step: s, event: event.event, at: span.start + event.at });
+  });
+
+  const first = steps[0]?.start ?? 0;
+  const hasMain = departures.some((d) => d.who === "main");
+  const carriers: CarrierTime[] = [];
+  for (const who of ["main", "coin"] as const) {
+    const list = departures.filter((d) => d.who === who);
+    list.forEach((d, k) => {
+      const next = list[k + 1];
+      // 主役の最初の運ぶ物は、最初の段の始まりから出発点で待つ (何も見えない時間を作らないため)
+      const waits = k === 0 && (who === "main" || !hasMain);
+      carriers.push({
+        step: d.step,
+        event: d.event,
+        who,
+        depart: d.a,
+        arrive: d.b,
+        start: waits ? Math.min(first, d.a) : d.a,
+        end: next ? Math.max(next.a, d.b) : last,
+      });
+    });
+  }
+  carriers.sort((x, y) => x.depart - y.depart);
+
+  return {
+    total,
+    last,
+    steps,
+    edges,
+    carriers,
+    labels,
+    badges: steps.map((span, s) => ({ step: s, appears: span.start })),
+    events,
+    stills: steps.map((span) => span.end - MOTION.still),
+  };
+}

package/src/tokenize.ts

@@ -1,289 +1,28 @@
 /**
- * 記法と JSON を画面で色分けするための分解器 (#1310)。
+ * 記法を 1 行ずつに切る。
  *
- * 本文を受けて `[種類, 開始, 終わり]` の並びを返す。 **色は知らない**。 実際の色は
- * 使う側 (画面) が種類名に当てる = 埋め込み先ごとに自分の配色を使えるようにするため。
- *
- * ## なぜ package 側に置くか
- *
- * 「記法をどう切るか」 は parser と同じ知識で、色名の別名と矢印の書き方を `keywords.ts`、
- * 正規の色名を `@cardenelabs/cdl` から直接引ける。 画面側に置くと語彙を写すことになり、
- * 語が増えた時に片方だけ古くなる (#1293 / #1304 / #1306 で 3 度踏んだ形)。
- *
- * ## 何を切るか
- *
- * | 種類 | 例 | 図での意味 |
- * |---|---|---|
- * | `項目名` | `title:` / `kind:` / `- 名前:` | 構造。 色ではなく太さで示す |
- * | `説明文` | `"ログイン"` / `: 検索` | 箱と矢印に出る文字 |
- * | `矢印` | `->` / `→` | 繋がりそのもの |
- * | `色名` | `success` / `成功` / `dotted-flow` | **その色で描く** (`色` に解決後の名前が入る) |
- * | `値の参照` | `{count}` | 段で動く値 |
- * | `注記` | `# ...` | 読み飛ばしてよい部分 |
- *
- * 色名だけ `色` を返すのは、画面が「その色名が図で引く色」 で描けるようにするため。
- * 本文の `(成功)` と図の緑が一致すると、どの語がどの見た目に効くかが読める。
- *
- * ## 重なりを作らない
- *
- * 返す並びは開始位置の昇順で、**互いに重ならない**。 使う側は並びをそのまま
- * `<span>` や装飾に変換するだけでよく、重なりの解決を持たなくて済む。
- *
- * 値の参照は説明文の中にも出る (`value: "{count}"`)。 その場合は説明文を参照の前後で
- * 分割して返す = 参照だけ別の色にできる。
- */
-import { TONE_ALIAS, ARROW_PATTERNS } from "./keywords";
-import { TONES, EDGE_STYLES } from "@cardenelabs/cdl";
-import type { Tone } from "@cardenelabs/cdl";
-
-/** 分解した部分の種類 (#1310) */
-export type トークンの種類 = "項目名" | "説明文" | "矢印" | "色名" | "値の参照" | "注記";
-
-/** 分解した部分 1 つ。 位置は本文の先頭からの文字数 (`slice` にそのまま渡せる) */
-export type トークン = {
-  種類: トークンの種類;
-  開始: number;
-  終わり: number;
-  /** `色名` の時だけ入る、解決後の色の名前。 画面はこれで「その色」 を引く */
-  色?: Tone;
-};
-
-/**
- * 線種の一覧 (#1310 → #1466)。
- *
- * 描画側 (`EDGE_STYLES`) から導く。 手で並べると、描画側が線種を増やした時に書けないままになる
- * (実測 = `dashed` を足した時に 3 箇所のうち 2 箇所が古いままだった)。
- */
-const 線種 = EDGE_STYLES;
-
-/** 色名として読める語 (小文字で引く)。 正規の色名と別名の両方 */
-const 色名の表 = new Map<string, Tone>([
-  ...TONES.map((t) => [t.toLowerCase(), t] as [string, Tone]),
-  ...Object.entries(TONE_ALIAS).map(([k, v]) => [k.toLowerCase(), v] as [string, Tone]),
-]);
-
-/**
- * 矢印の書き方。 並べ替えない。
- *
- * `->` と `->>` は同じ位置から始まるため、どちらを取るかを決める必要がある。 それは
- * `重なりを外す` が「同じ開始なら長い方」 として 1 箇所で決める。 ここでも長い順に
- * 並べると **同じ規則が 2 箇所に分かれ、片方を外しても検査が通る** (実測)。
- */
-const 矢印の表 = [...new Set(ARROW_PATTERNS)];
-
-/**
- * 色名として読める語なら、解決後の名前を返す。
- *
- * 判定は `resolveTone` と同じ (別名を引き、小文字に寄せる) が、引用符は外さない =
- * 分解器は本文の位置を返すため、外した後の文字列を作ってはいけない。
- */
-function 色名として読む(語: string): Tone | undefined {
-  return 色名の表.get(語.toLowerCase());
-}
-
-/** 線種として読める語か */
-function 線種として読むか(語: string): boolean {
-  return (線種 as readonly string[]).includes(語.toLowerCase());
-}
-
-/*
- * 箱の種類 (`service` / `database` 等) は色分けしない (#1310 review r1-f1)。
- *
- * 一度は種類名を `項目名` として扱ったが、**箱の名前まで巻き込む**。 受理する 108 種には
- * `user` / `api` / `actor` / `card` / `state` / `service` が含まれ、`- User` や `- API` の
- * ような普通の名前と衝突する (実測で両方とも項目名になった)。
- *
- * 正しく分けるには「種類の位置に書かれているか」 を見る必要があり、それは 5 種
- * (項目名 / 説明文 / 矢印 / 色名 / 値の参照) の外側になる。 語だけで判定できないものは
- * 色分けしない。
+ * 空行とコメントの行 (`//` で始まる行) は捨てる。行の頭と終わりの空白は意味を持たないので落とし、
+ * 誤りを示すために元の行の番号と、残した字が始まる列を持たせる。
+ * 行と列は 1 から数え、列は字の数で数える (UTF-16 の単位では数えない)。
  */
-
-/** 重なりを持たない並びに整える。 先に入れたものを優先し、後から重なる分は捨てる */
-function 重なりを外す(候補: トークン[]): トークン[] {
-  const out: トークン[] = [];
-  for (const t of [...候補].sort((a, b) => a.開始 - b.開始 || b.終わり - a.終わり)) {
-    if (t.終わり <= t.開始) continue;
-    const 直前 = out[out.length - 1];
-    if (直前 !== undefined && t.開始 < 直前.終わり) continue;
-    out.push(t);
-  }
-  return out;
-}
-
-/** `{名前}` を拾う。 名前は英数字と `_` だけ (描画側が置き換える時に見る範囲と揃える) */
-function 値の参照を拾う(src: string, 起点: number, 本文: string, 積む: (t: トークン) => void): void {
-  for (const m of 本文.matchAll(/\{[A-Za-z_][\w]*\}/g)) {
-    積む({ 種類: "値の参照", 開始: 起点 + m.index, 終わり: 起点 + m.index + m[0].length });
-  }
+export interface SourceLine {
+  line: number;
+  column: number;
+  text: string;
 }
 
-/**
- * 引用符で囲まれた部分を拾い、中に値の参照があれば前後で割る。
- *
- * 割らずに 1 つの説明文として返すと、`value: "{count}"` の参照に色を当てられない。
- */
-function 説明文を拾う(src: string, 起点: number, 本文: string, 積む: (t: トークン) => void): void {
-  for (const m of 本文.matchAll(/"[^"]*"|'[^']*'/g)) {
-    const 開始 = 起点 + m.index;
-    const 終わり = 開始 + m[0].length;
-    const 参照: トークン[] = [];
-    値の参照を拾う(src, 開始, m[0], (t) => 参照.push(t));
-    if (参照.length === 0) {
-      積む({ 種類: "説明文", 開始, 終わり });
-      continue;
-    }
-    let 位置 = 開始;
-    for (const r of 参照.sort((a, b) => a.開始 - b.開始)) {
-      if (r.開始 > 位置) 積む({ 種類: "説明文", 開始: 位置, 終わり: r.開始 });
-      積む(r);
-      位置 = r.終わり;
-    }
-    if (位置 < 終わり) 積む({ 種類: "説明文", 開始: 位置, 終わり });
-  }
+/** `text` の `index` 番目 (UTF-16 の位置) にある字が、行の何列目かを返す。 */
+export function columnOf(source: SourceLine, index: number): number {
+  return source.column + Array.from(source.text.slice(0, index)).length;
 }
 
-/**
- * 記法を分解する (#1310)。
- *
- * 行ごとに見る。 記法は行単位で意味が決まるため、行をまたぐ状態を持たない。
- */
-export function 記法を分解する(src: string): トークン[] {
-  const 候補: トークン[] = [];
-  const 積む = (t: トークン): void => {
-    候補.push(t);
-  };
-  let 起点 = 0;
-  for (const 行 of src.split("\n")) {
-    分解する1行(src, 起点, 行, 積む);
-    起点 += 行.length + 1;
-  }
-  return 重なりを外す(候補);
-}
-
-function 分解する1行(
-  src: string,
-  起点: number,
-  行: string,
-  積む: (t: トークン) => void,
-): void {
-  const 字下げ = 行.length - 行.trimStart().length;
-  const 本体 = 行.trimStart();
-  if (本体 === "") return;
-
-  // 注記は行ごと。 `#` を色番号 (`#f59e0b`) と取り違えないよう、行の頭だけを見る
-  if (本体.startsWith("#")) {
-    積む({ 種類: "注記", 開始: 起点 + 字下げ, 終わり: 起点 + 行.length });
-    return;
-  }
-
-  // 説明文と値の参照を先に取る = 引用符の中の `->` や色名を拾わないため
-  説明文を拾う(src, 起点, 行, 積む);
-  値の参照を拾う(src, 起点, 行, 積む);
-
-  // 項目名 = 行頭 (`- ` の後も含む) の `名前:`
-  const 見出し = 本体.match(/^(-\s*)?([^\s:{}[\]"']+)\s*:/);
-  if (見出し) {
-    const 前 = 見出し[1]?.length ?? 0;
-    const 名 = 見出し[2] ?? "";
-    const 開始 = 起点 + 字下げ + 前;
-    積む({ 種類: "項目名", 開始, 終わり: 開始 + 名.length + 1 });
-  }
-
-  // 矢印
-  for (const 記号 of 矢印の表) {
-    let i = 行.indexOf(記号);
-    while (i >= 0) {
-      積む({ 種類: "矢印", 開始: 起点 + i, 終わり: 起点 + i + 記号.length });
-      i = 行.indexOf(記号, i + 記号.length);
-    }
-  }
-
-  // 色名と線種。 語の切れ目で区切って 1 語ずつ見る = 説明文の一部を拾わないよう、
-  // 引用符の中は上で説明文として先に取ってある (重なりを外す時に落ちる)
-  for (const m of 行.matchAll(/[^\s(),:{}[\]"']+/g)) {
-    const 語 = m[0];
-    const 色 = 色名として読む(語);
-    if (色 !== undefined) {
-      積む({ 種類: "色名", 開始: 起点 + m.index, 終わり: 起点 + m.index + 語.length, 色 });
-      continue;
-    }
-    if (線種として読むか(語)) {
-      積む({ 種類: "色名", 開始: 起点 + m.index, 終わり: 起点 + m.index + 語.length });
-    }
-  }
-}
-
-/**
- * JSON を分解する (#1310)。
- *
- * 記法と違い鍵は英語で、記法の語彙は出ない。 したがって **鍵 / 文字列 / 数を汎用の色で塗る**。
- *
- * 例外は `tone` と `color` の値で、こちらは記法と同じ語彙を持つため色名として扱う。
- * 同じ `"success"` が入口によって別の色になる状態を作らないため。
- */
-export function JSONを分解する(src: string): トークン[] {
-  const 候補: トークン[] = [];
-  // 鍵 (`"name":`) と、その値が色名を取る欄かを見る
-  for (const m of src.matchAll(/"((?:[^"\\]|\\.)*)"(\s*:)?/g)) {
-    const 開始 = m.index;
-    const 終わり = 開始 + m[0].length;
-    if (m[2] !== undefined) {
-      候補.push({ 種類: "項目名", 開始, 終わり });
-      continue;
-    }
-    候補.push({ 種類: "説明文", 開始, 終わり });
-  }
-  // 数値も文字列と同じ「値」の色にする。 JSON の数値文法に合わせ、符号・小数・指数を拾う。
-  // 文字列の中に現れた数字は、先に積んだ説明文と重なるため `重なりを外す` で落ちる。
-  for (const m of src.matchAll(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
-    候補.push({ 種類: "説明文", 開始: m.index, 終わり: m.index + m[0].length });
-  }
-  // 色名を取る欄の値を色名に格上げする
-  for (const m of src.matchAll(/"(tone|color)"\s*:\s*"((?:[^"\\]|\\.)*)"/g)) {
-    const 値の開始 = m.index + m[0].lastIndexOf('"' + m[2] + '"');
-    const 値 = m[2] ?? "";
-    const 色 = 色名として読む(値);
-    if (色 === undefined) continue;
-    const i = 候補.findIndex((t) => t.開始 === 値の開始);
-    if (i >= 0) 候補[i] = { 種類: "色名", 開始: 値の開始, 終わり: 値の開始 + 値.length + 2, 色 };
-  }
-  // 値の参照は文字列の中に出る (`"{count}"`)
-  const 参照: トークン[] = [];
-  値の参照を拾う(src, 0, src, (t) => 参照.push(t));
-  for (const r of 参照) {
-    const i = 候補.findIndex((t) => t.開始 < r.開始 && r.終わり <= t.終わり && t.種類 === "説明文");
-    const 元 = i < 0 ? undefined : 候補[i];
-    if (元 === undefined) continue;
-    候補.splice(
-      i,
-      1,
-      { 種類: "説明文", 開始: 元.開始, 終わり: r.開始 },
-      r,
-      { 種類: "説明文", 開始: r.終わり, 終わり: 元.終わり },
-    );
-  }
-  return 重なりを外す(候補);
-}
-
-/**
- * 分解した並びを、本文を覆う区間の列に広げる (#1310)。
- *
- * 分解器は色が付く部分だけを返すため、間の文字が抜ける。 画面はそのまま並べると本文が
- * 欠けるので、**色の付かない部分も種類なしの区間として挟む**。
- *
- * 返す区間は本文を過不足なく覆う (連結すると元の本文に戻る)。
- */
-export function 区間に広げる(
-  src: string,
-  tokens: トークン[],
-): Array<{ 文字: string; 種類?: トークンの種類; 色?: Tone }> {
-  const out: Array<{ 文字: string; 種類?: トークンの種類; 色?: Tone }> = [];
-  let 位置 = 0;
-  for (const t of tokens) {
-    if (t.開始 > 位置) out.push({ 文字: src.slice(位置, t.開始) });
-    out.push({ 文字: src.slice(t.開始, t.終わり), 種類: t.種類, 色: t.色 });
-    位置 = t.終わり;
-  }
-  if (位置 < src.length) out.push({ 文字: src.slice(位置) });
-  return out;
+export function tokenize(notation: string): SourceLine[] {
+  const lines: SourceLine[] = [];
+  notation.split(/\r?\n/).forEach((raw, index) => {
+    const text = raw.trim();
+    if (text === "" || text.startsWith("//")) return;
+    const lead = raw.length - raw.trimStart().length;
+    lines.push({ line: index + 1, column: Array.from(raw.slice(0, lead)).length + 1, text });
+  });
+  return lines;
 }

package/src/version.ts

@@ -0,0 +1,55 @@
+/**
+ * 原本の形式の版。
+ *
+ * 道具より新しい版の図は描かずに断る。古い版の図は、版を 1 つずつ上げる変換を通して読み、
+ * 原本の file を書き換えるのは移行の命令 (`migrateFile`) だけにする。
+ * 今は版 1 しか無いため、版を上げる変換はまだ持たない。版 2 を作る時に、版 1 から 2 への変換と
+ * 古い版を読んだ時の警告をここに足す。
+ */
+import { FIELD_MESSAGES } from "./field-messages";
+import { type CheckOptions, type Diagram, type FieldError, validateDiagram } from "./schema";
+import type { NotationLang } from "./words";
+
+/** この道具が読める原本の版 */
+export const FORMAT_VERSION = 1;
+
+export type Read = { ok: true; diagram: Diagram; warnings: string[] } | { ok: false; errors: FieldError[] };
+
+export interface Migrated {
+  changed: boolean;
+  from: number;
+  to: number;
+}
+
+function newerThanTool(input: unknown): number | undefined {
+  if (typeof input !== "object" || input === null) return undefined;
+  const version = (input as { version?: unknown }).version;
+  return typeof version === "number" && version > FORMAT_VERSION ? version : undefined;
+}
+
+const newerError = (version: number, lang: NotationLang): FieldError => ({
+  pointer: "/version",
+  message: FIELD_MESSAGES[lang].newer(version, FORMAT_VERSION),
+});
+
+/** 原本を読む。道具より新しい版は描かずに断り、形の誤りは検査の誤りとして返す。誤りの文は `options.lang` (渡さなければ日本語) で出す。 */
+export function readDiagram(input: unknown, options: CheckOptions = {}): Read {
+  const newer = newerThanTool(input);
+  if (newer !== undefined) return { ok: false, errors: [newerError(newer, options.lang ?? "ja")] };
+  const checked = validateDiagram(input, options);
+  if (!checked.ok) return checked;
+  return { ok: true, diagram: input as Diagram, warnings: [] };
+}
+
+/**
+ * 原本の file を今の版へ移す。今の版の file には触れない。
+ *
+ * file を読むので、画面で描く入口からは呼ばない。node の file の命令は呼んだ時に初めて読み込む。
+ */
+export async function migrateFile(path: string): Promise<Migrated> {
+  const { readFile } = await import("node:fs/promises");
+  const input: unknown = JSON.parse(await readFile(path, "utf8"));
+  const read = readDiagram(input);
+  if (!read.ok) throw new Error(`${path} を移せない: ${read.errors.map((error) => `${error.pointer} ${error.message}`).join(" / ")}`);
+  return { changed: false, from: read.diagram.version, to: FORMAT_VERSION };
+}

package/src/view.ts

@@ -0,0 +1,16 @@
+/**
+ * 見せ方を字の大きさで選ぶ。
+ *
+ * 全体を枠の幅へ収めた時の箱の名前の字が 10.5px 以上なら、全体を止めて中だけ動かす (`fixed`)。
+ * 下回るなら、動く所へ寄って追い、隅の全体図で今どこかを示す (`follow`)。
+ * 書き手が原本の `view` で決めた時は、字の大きさに関わらずそれに従う。
+ */
+import { READABLE_PX, TYPE } from "./look/values";
+import type { Rendered } from "./render/svg";
+import type { ViewMode } from "./schema";
+
+export function chooseView(rendered: Pick<Rendered, "layout" | "view">, frameWidth: number): { mode: ViewMode; textPx: number } {
+  const textPx = (Math.max(0, frameWidth) / rendered.layout.width) * TYPE.boxName.size;
+  if (rendered.view) return { mode: rendered.view, textPx };
+  return { mode: textPx >= READABLE_PX ? "fixed" : "follow", textPx };
+}

package/src/words.ts

@@ -0,0 +1,79 @@
+/**
+ * 記法の語。役割ごとに日本語と英語の語を組で持つ (#2997)。
+ *
+ * 英語の語は原本の JSON が使う名前に揃え、記法と JSON で覚える語を 1 組にする。
+ * 1 つの file の言葉は最初の行の図の種類の語で決まり、読む仕組みと書き戻す仕組みは
+ * その言葉の語だけをこの表から引く。
+ *
+ * 型が組の欠けを止める。原本の JSON の値 (図の種類、運ぶ物、見せ方、名前の側) に語が無い時と、
+ * どちらかの言葉の語が無い役割がある時は、型の検査が落ちる。
+ */
+import type { Carry, Diagram, LabelSide, ViewMode } from "./schema";
+
+export type NotationLang = "ja" | "en";
+
+type Pair = Readonly<Record<NotationLang, string>>;
+
+export const WORDS = {
+  /** 最初の行の図の種類 */
+  kind: { sequence: { ja: "時系列図", en: "sequence" }, architecture: { ja: "構成図", en: "architecture" } } satisfies Record<Diagram["kind"], Pair>,
+  /** 段の見出しより前の行の頭 */
+  head: {
+    region: { ja: "区画", en: "region" },
+    strip: { ja: "帯", en: "strip" },
+    view: { ja: "見せ方", en: "view" },
+  } satisfies Record<string, Pair>,
+  /** 行の終わりの `[<鍵> <値>]` の鍵 */
+  attr: {
+    color: { ja: "色", en: "color" },
+    icon: { ja: "印", en: "icon" },
+    region: { ja: "区画", en: "region" },
+    label: { ja: "名前", en: "label" },
+  } satisfies Record<string, Pair>,
+  /** 線の上を走る物 */
+  carry: {
+    envelope: { ja: "封筒", en: "envelope" },
+    tag: { ja: "札", en: "tag" },
+    coin: { ja: "硬貨", en: "coin" },
+    none: { ja: "なし", en: "none" },
+  } satisfies Record<Carry["kind"], Pair>,
+  /** 見せ方の値 */
+  view: { fixed: { ja: "止める", en: "fixed" }, follow: { ja: "寄る", en: "follow" } } satisfies Record<ViewMode, Pair>,
+  /** 線の名前を置く側 */
+  side: {
+    above: { ja: "上", en: "above" },
+    below: { ja: "下", en: "below" },
+    left: { ja: "左", en: "left" },
+    right: { ja: "右", en: "right" },
+  } satisfies Record<LabelSide, Pair>,
+} as const;
+
+export type WordGroup = keyof typeof WORDS;
+
+/** `group` の役割の `value` を、`lang` の言葉の語にする */
+export function wordOf<G extends WordGroup>(group: G, value: keyof (typeof WORDS)[G], lang: NotationLang): string {
+  return ((WORDS[group] as Record<string, Pair>)[value as string] as Pair)[lang];
+}
+
+/** `lang` の言葉の語 `word` が、`group` のどの値を指すか。語でなければ `undefined` */
+export function valueOf<G extends WordGroup>(group: G, word: string, lang: NotationLang): keyof (typeof WORDS)[G] | undefined {
+  const found = Object.entries(WORDS[group] as Record<string, Pair>).find(([, pair]) => pair[lang] === word);
+  return found?.[0] as keyof (typeof WORDS)[G] | undefined;
+}
+
+export const otherLang = (lang: NotationLang): NotationLang => (lang === "ja" ? "en" : "ja");
+
+/** 記法の最初の行 (空行とコメントの行を除く) の図の種類の語から、言葉を決める。決まらなければ `undefined` */
+export function languageOf(headLine: string): NotationLang | undefined {
+  const first = headLine.trim().split(/\s+/)[0] ?? "";
+  return (["ja", "en"] as const).find((lang) => valueOf("kind", first, lang) !== undefined);
+}
+
+/** 記法の言葉。最初の行の図の種類の語で決まり、決まらなければ `undefined` */
+export function notationLanguage(notation: string): NotationLang | undefined {
+  const head = notation
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line !== "" && !line.startsWith("//"));
+  return head === undefined ? undefined : languageOf(head);
+}