@cardenelabs/cdl 0.7.0 → 0.10.0

package/src/render/template-fields.ts

@@ -0,0 +1,212 @@
+import type { CdlNode } from "../types";
+
+/**
+ * node のうち `{名前}` を読む欄の SSOT (#455)。
+ *
+ * 検査側 (`validate.ts`) は以前 `value` と `rows` の 2 つしか見ていなかった。 描画側は他の欄でも
+ * `{名前}` を読むため、 **書いた名前が未定義でも黙って通り**、 逆にその名前が「どこでも参照されて
+ * いない」 と報告されていた (実測)。
+ *
+ * 欄を列挙する形は足し忘れる。 そこで **列挙が `CdlNode` の全 key を覆うことを型で固定する**
+ * (末尾の `_覆えている` / `_余りがない`)。 欄を足して両方の list に入れ忘れると型検査が落ちる。
+ */
+
+/** `{名前}` を読む文字の欄 */
+const TEXT_FIELDS = ["title", "eyebrow", "subtitle", "value", "wBind", "hBind", "visibleIf"] as const;
+
+/** `{名前}` を読む文字の並びの欄 */
+const LIST_FIELDS = ["rows"] as const;
+
+/**
+ * 数を直接書くか `{名前}` を書く欄。
+ *
+ * 数で書かれている時は読む名前が無いので、 文字の時だけ見る。
+ */
+const NUMERIC_FIELDS = ["opacity", "renderOffsetX", "renderOffsetY"] as const;
+
+/**
+ * `{名前}` を読まない欄。
+ *
+ * **理由を持たせるために、 読む欄と同じく明示的に列挙する**。 ここに載っていない欄が増えると
+ * 型検査が落ちるので、 「読むのか読まないのか」 を必ず判断することになる。
+ *
+ * | 欄 | 読まない理由 |
+ * |---|---|
+ * | `id` / `lane` / `kind` / `role` / `tone` | 名前や区分で、 描画側が置換に掛けない |
+ * | `stack` / `w` / `h` / `pos*` / `ganttAxisMax` | 数のみ。 型が `number` で文字を受けない |
+ * | `shape` | 入れ子の構造。 下の `shapeTexts` が中の文字を全部拾う |
+ * | `*Data` | 図表 payload。 入れ子の構造で、 下の `payloadTexts` が中の文字を拾う |
+ */
+type 読まない欄 =
+  | "id"
+  | "lane"
+  | "stack"
+  | "kind"
+  | "w"
+  | "h"
+  | "posX"
+  | "posY"
+  | "posW"
+  | "posH"
+  | "role"
+  | "tone"
+  | "shape"
+  | "chartData"
+  | "ganttData"
+  | "ganttAxisMax"
+  | "mindData"
+  | "funnelData"
+  | "quadrantData"
+  | "treeData"
+  | "journeyData";
+
+type 列挙した欄 =
+  | (typeof TEXT_FIELDS)[number]
+  | (typeof LIST_FIELDS)[number]
+  | (typeof NUMERIC_FIELDS)[number]
+  | 読まない欄;
+
+/** 引数が `never` でなければ型検査が落ちる */
+type 空であること<T extends never> = T;
+
+/** `CdlNode` に列挙し漏れた欄があると落ちる */
+export type _覆えている = 空であること<Exclude<keyof CdlNode, 列挙した欄>>;
+
+/** `CdlNode` に無い欄を列挙していると落ちる */
+export type _余りがない = 空であること<Exclude<列挙した欄, keyof CdlNode>>;
+
+/**
+ * 読む欄と読まない欄が重なっていると落ちる。
+ *
+ * 覆えているかだけを見ると、 同じ欄を両方に入れても union で 1 つに畳まれて通る = 「読むのか
+ * 読まないのか」 を一意に決めた形にならない。
+ */
+export type _重なっていない = 空であること<
+  Extract<
+    | (typeof TEXT_FIELDS)[number]
+    | (typeof LIST_FIELDS)[number]
+    | (typeof NUMERIC_FIELDS)[number],
+    読まない欄
+  >
+>;
+
+/** `shape` のうち `{名前}` を読む欄 */
+const SHAPE_TEMPLATE_FIELDS = ["source", "radius", "fillProgress", "angle", "level", "rotation", "fill"] as const;
+
+/**
+ * `shape` のうち `{名前}` を読まない欄。
+ *
+ * `stroke` はここに入る。 `kinds/dyn-shape.tsx` は `shape.stroke ?? 既定` をそのまま SVG に渡す
+ * (`fill` だけが `interpolateColor` を通る)。 実測で `stroke: "{名前}"` は画面にも書いたまま
+ * 残った。 読む欄に入れると **画面には出ないのに検査だけが通る / 落ちる** ずれが生まれる。
+ *
+ * 残りは数だけを受ける欄 (`fillMax` / `innerRadius` 等) と種類の名前 (`kind`)。
+ */
+type 形の読まない欄 =
+  | "kind"
+  | "fillMax"
+  | "orient"
+  | "stroke"
+  | "innerRadius"
+  | "outerRadius"
+  | "startAngle"
+  | "sweepMax"
+  | "amplitude"
+  | "frequency"
+  | "waveHeight"
+  | "sides";
+
+/** union の全ての枝の key を集める (`keyof` は共通の key しか返さない) */
+type 全ての枝の欄<T> = T extends unknown ? keyof T : never;
+
+type 形の欄 = 全ての枝の欄<NonNullable<CdlNode["shape"]>>;
+type 列挙した形の欄 = (typeof SHAPE_TEMPLATE_FIELDS)[number] | 形の読まない欄;
+
+/** `CdlDynShape` の枝に列挙し漏れた欄があると落ちる */
+export type _形を覆えている = 空であること<Exclude<形の欄, 列挙した形の欄>>;
+
+/** `CdlDynShape` に無い欄を列挙していると落ちる */
+export type _形に余りがない = 空であること<Exclude<列挙した形の欄, 形の欄>>;
+
+/** 読む欄と読まない欄が重なっていると落ちる */
+export type _形が重なっていない = 空であること<
+  Extract<(typeof SHAPE_TEMPLATE_FIELDS)[number], 形の読まない欄>
+>;
+
+/**
+ * `shape` のうち `{名前}` を読む欄の文字を拾う。
+ *
+ * 枝ごとに欄が違うが、 欄の名前は枝をまたいで重ならない (`radius` は `rect` では数だけを
+ * 受けるので、 文字の時だけ拾う形で問題にならない)。 列挙の覆えているかは上の型が固定する。
+ */
+function shapeTexts(shape: CdlNode["shape"]): string[] {
+  if (!shape) return [];
+  const out: string[] = [];
+  const 中身 = shape as Record<string, unknown>;
+  for (const f of SHAPE_TEMPLATE_FIELDS) {
+    const v = 中身[f];
+    if (typeof v === "string" && v) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * 図表 payload のうち `{名前}` を読む欄の文字を拾う。
+ *
+ * 解決するのは `render/payload-binding.ts` で node の欄とは別経路だが、 **未定義の判定と
+ * unused の判定は同じ** = 別扱いにすると、 payload だけで読んでいる状態が「どこでも参照されて
+ * いない」 と報告される (実測)。
+ *
+ * 数と語の欄 (`value` / `count` / `startIdx` / `quadrant` / `emotion` 等) は数や決まった語を
+ * 直接書くこともあるため、 文字の時だけ拾う。
+ */
+function payloadTexts(node: CdlNode): string[] {
+  const out: string[] = [];
+  const 足す = (v: unknown): void => {
+    if (typeof v === "string" && v) out.push(v);
+  };
+  for (const d of node.chartData ?? []) 足す(d.value);
+  for (const s of node.funnelData ?? []) 足す(s.count);
+  for (const t of node.ganttData ?? []) {
+    足す(t.startIdx);
+    足す(t.endIdx);
+  }
+  for (const i of node.quadrantData?.items ?? []) 足す(i.quadrant);
+  for (const s of node.journeyData ?? []) 足す(s.emotion);
+  for (const n of node.treeData ?? []) {
+    足す(n.title);
+    足す(n.subtitle);
+  }
+  if (node.mindData) {
+    足す(node.mindData.rootTitle);
+    for (const b of node.mindData.branches) {
+      足す(b.title);
+      足す(b.subtitle);
+    }
+  }
+  return out;
+}
+
+/**
+ * その node が `{名前}` を読みうる文字を全部返す。
+ *
+ * 返すのは文字だけで、 名前の切り出しは呼ぶ側が `templateRefIds` で行う。 切り出しの式を
+ * 1 箇所に保つため (描画側と別に書くと字種がずれ、 置換されうる名前が検証を素通りする)。
+ */
+export function nodeTemplateTexts(node: CdlNode): string[] {
+  const out: string[] = [];
+  for (const f of TEXT_FIELDS) {
+    const v = node[f];
+    if (typeof v === "string" && v) out.push(v);
+  }
+  for (const f of LIST_FIELDS) {
+    for (const v of node[f] ?? []) if (v) out.push(v);
+  }
+  for (const f of NUMERIC_FIELDS) {
+    const v = node[f];
+    if (typeof v === "string" && v) out.push(v);
+  }
+  out.push(...shapeTexts(node.shape));
+  out.push(...payloadTexts(node));
+  return out;
+}

package/src/render/utils.ts

@@ -50,7 +50,15 @@ export function computeStateValues(
   phaseIdx: number,
   progress: number,
 ): Record<string, string> {
-  const values: Record<string, number | string> = {};
+  // 継承を持たない入れ物に集める (#456)。 通常の object だと 2 つ壊れる。
+  // `__proto__` という名前の状態は代入が黙って捨てられて値を入れても読めず、
+  // `constructor` / `toString` は値を入れていなくても「値がある」 と読まれて
+  // prototype の中身が図に出る (実測 = `{constructor}` が
+  // `function Object() { [native code] }` として描かれた)。
+  //
+  // 読み手側の `Object.hasOwn` は残す = この入れ物は spread や `JSON.parse` を
+  // 通ると通常の object に戻るため、 入れ物だけでは塞ぎ切れない。
+  const values: Record<string, number | string> = Object.create(null);
   for (const s of laid.states) values[s.id] = s.initial;
 
   for (let i = 0; i < laid.phases.length; i++) {
@@ -69,11 +77,33 @@ export function computeStateValues(
       }
     }
   }
-  const out: Record<string, string> = {};
+  const out: Record<string, string> = Object.create(null);
   for (const [k, v] of Object.entries(values)) out[k] = String(v);
   return withDerivedValues(out, laid.derived);
 }
 
+/**
+ * 段の値に、 入力欄 / 式 / 巻き取りの値を重ねる (interactive 経路)。
+ *
+ * 継承を持たない入れ物のまま返す (#456)。 spread (`{ ...base }`) で受けると通常の object に
+ * 戻り、 `constructor` / `toString` が「値がある」 と読まれる状態に戻る。
+ *
+ * 重ねるのは数 / 文字列 / 真偽の 3 種だけ。 それ以外は状態の値として文字にできないため落とす。
+ */
+export function mergeStateValues(
+  base: Record<string, string>,
+  overrides: Record<string, unknown>,
+): Record<string, string> {
+  const merged: Record<string, string> = Object.assign(Object.create(null), base);
+  for (const key of Object.keys(overrides)) {
+    const v = overrides[key];
+    if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") {
+      merged[key] = String(v);
+    }
+  }
+  return merged;
+}
+
 /**
  * template literal `{stateId}` を values map で置換 (未解決は `{id}` のまま)。
  * array signal 拡張 (SSOT): 値が JSON array (例 `"[1,2,3]"`) の signal に対しては、

package/src/render.tsx

@@ -9,7 +9,7 @@ import {
   useInteractiveIntegration,
   type InteractiveHandlerMap,
 } from "./render/interactive-panel";
-import { computeStateValues } from "./render/utils";
+import { computeStateValues, mergeStateValues } from "./render/utils";
 import { visualValidateLaid } from "./visual-validate";
 import type { CdlDiagram, LaidDiagram } from "./types";
 
@@ -153,14 +153,7 @@ export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hi
   // 既存 phase-driven state と衝突しないよう state.id が signal / formula / scroll id と同じ場合のみ上書き。
   const stateValues = useMemo(() => {
     if (!isInteractive) return baseStateValues;
-    const merged: Record<string, string> = { ...baseStateValues };
-    for (const key of Object.keys(interactive.stateOverrides)) {
-      const v = interactive.stateOverrides[key];
-      if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") {
-        merged[key] = String(v);
-      }
-    }
-    return merged;
+    return mergeStateValues(baseStateValues, interactive.stateOverrides);
   }, [isInteractive, baseStateValues, interactive.stateOverrides]);
 
   return (

package/src/types.ts

@@ -209,6 +209,17 @@ export type CdlNode = {
    */
   posW?: number;
   posH?: number;
+  /**
+   * 図の中での役割。 位置ではなく **組み立てた側が付ける目印** で、 描画側の分岐に使う。
+   *
+   * `lifeline-footer` = 順序図で lane の末尾に置く下端の名札 (`presets.ts` の `build()` が付ける)。
+   * 一部の `shape-` は絵を箱の下端から上へ積むため、 箱が低いと絵が縦線と重なる。 その回避で
+   * 絵を下げる対象がこの名札に限られる。
+   *
+   * **位置で推測してはいけない** = 手で組んだ図で一番下が名札でない `shape-` の node だと、
+   * その絵が下がってしまう (`#458`)。
+   */
+  role?: "lifeline-footer";
   /**
    * node の主色。 未指定なら kind ごとの既定色。
    *
@@ -269,6 +280,19 @@ export type CdlNode = {
    * kinds/gantt.tsx が縦軸 task lane + 横軸日付 rect bar で SVG 描画する。
    */
   ganttData?: GanttTaskPayload[];
+  /**
+   * gantt-timeline の横軸を何目盛り分にするか (`#483`)。
+   *
+   * 書かない図では今までどおり全 task の最大値から自動で決まる。 書くと尺がその値で固定され、
+   * 状態で動く task があっても他の task の帯の位置と幅が変わらない。
+   *
+   * 位置は 0 から `ganttAxisMax - 1` までで、 そこから外れる task の帯は右端の目盛りに寄せて
+   * 描く (図の外へ出さない、 `kinds/gantt.tsx` SSOT)。
+   *
+   * 有限の正の数でなければ書かなかったものとして扱う = 尺が壊れて帯が図の外へ出るより、
+   * 自動に落ちる方が読める図になる。
+   */
+  ganttAxisMax?: number;
   /**
    * mind-map 専用の branch payload。 tree 構造を 1 node に格納し、
    * kinds/mind-map.tsx が中心 + 放射で SVG 描画する。
@@ -381,13 +405,20 @@ export type QuadrantItemPayload = {
   subtitle?: string;
 };
 
-/** tree-hierarchy kind の 1 node payload */
+/**
+ * tree-hierarchy kind の 1 node payload。
+ *
+ * **上の小ラベル (`eyebrow`) は受けない** (#471)。 箱の高さは段の間隔から出ており
+ * (`Math.min(38, 間隔 * 0.7)`)、 名前と補足で 2 行を使うと 3 行目は入らない。 高さを広げると
+ * 段どうしが近づいて箱が重なる。 受け取って描かない欄は、 書き手から効いていないことが
+ * 読めないため置かない。
+ */
 export type TreeNodePayload = {
   id: string;
   title: string;
   parent?: string;
+  /** 箱の 2 行目に出す補足 */
   subtitle?: string;
-  eyebrow?: string;
 };
 
 /** journey-map の気持ち 5 段階 */
@@ -2093,6 +2124,20 @@ export type CdlPhase = {
   title: string;
   body: string;
   activate: string[];
+  /**
+   * この phase で「左の起点から描き始める」 node の id (cdl#512)。
+   *
+   * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
+   * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
+   * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+   *
+   * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
+   * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら
+   * 描く」 にすると、 値が動くだけの phase でも線を引き直すことになる。
+   *
+   * 書かない phase では従来どおり全長で描く (DOM に dash 属性も付かない)。
+   */
+  draw?: string[];
   /** 数値 state の線形補間 (write phase で 100→90 等) */
   tweens: Array<{ stateId: string; from: number; to: number }>;
   /** 任意型 state の即時切替 (この phase に到達したら値を上書き、 lerp なし) */

package/src/validate.ts

@@ -1,6 +1,7 @@
 import type { CdlDiagram } from "./types";
 import { TONES as TONE_NAMES, NODE_KINDS } from "./types";
 import { templateRefIds } from "./render/utils";
+import { nodeTemplateTexts } from "./render/template-fields";
 import { derivedRefIds } from "./render/derived-values";
 
 const TONES = new Set<string>(TONE_NAMES);
@@ -88,10 +89,26 @@ export function validate(diag: CdlDiagram): void {
   // 2 つを 1 つに畳んではいけない。 畳むと `tween` の宛先に derived を書けてしまい、
   // 「式で決まる値を段が動かす」 という成立しない指定が素通りする (derived は毎 frame
   // 計算し直されるので、 段が入れた値は次の frame で消える)。
-  const readableIds = new Set([...stateIds, ...(diag.derived ?? []).map((d) => d.id)]);
+  //
+  // **描画側で名前になる 3 経路も足す** (#455)。 入力欄 (`inputs`) / 入力欄の式 (`formulas`) /
+  // 巻き取りの進み (`scrollTriggers`) は、 いずれも id をそのまま名前にした signal を作り
+  // (`createInputSignals` / `createFormulaComputeds` / `createScrollProgressSignals`)、
+  // `useInteractiveIntegration` がその値を `stateOverrides` に入れ、 `render.tsx` が描画用の
+  // 値に混ぜる。 足さないと、 実際に読める名前が「未定義」 と報告される (実測 = 図録の
+  // `interactive.cdl.ts:eventVariety` で `{lastEvent}` と `{received}` が偽陽性になった)。
+  //
+  // `readouts` は既にある値を見せる側、 `eventBindings` は受け手の結線で、 どちらも新しい
+  // 名前を作らない。
+  const readableIds = new Set([
+    ...stateIds,
+    ...(diag.derived ?? []).map((d) => d.id),
+    ...(diag.inputs ?? []).map((i) => i.id),
+    ...(diag.formulas ?? []).map((f) => f.id),
+    ...(diag.scrollTriggers ?? []).map((t) => t.id),
+  ]);
 
   // 「もしかして」 サジェスト (typo 検出): edit distance 1 で最も近い候補 1 件
-  const suggest = (target: string, candidates: Set<string>): string => {
+  const suggest = (target: string, candidates: Set<string>, candidateKind: "lane" | "node" = "lane"): string => {
     const list = [...candidates];
     if (list.length === 0) return "";
     let best = "";
@@ -103,7 +120,7 @@ export function validate(diag: CdlDiagram): void {
         best = c;
       }
     }
-    return bestD <= 2 ? ` (もしかして "${best}"?)` : ` (定義済 lane: ${list.slice(0, 5).join(", ")}${list.length > 5 ? "..." : ""})`;
+    return bestD <= 2 ? ` (もしかして "${best}"?)` : ` (定義済 ${candidateKind}: ${list.slice(0, 5).join(", ")}${list.length > 5 ? "..." : ""})`;
   };
   for (const n of diag.nodes) {
     if (!laneIds.has(n.lane)) {
@@ -115,12 +132,12 @@ export function validate(diag: CdlDiagram): void {
   for (const e of diag.edges) {
     if (!nodeIds.has(e.from)) {
       errors.push(
-        `[cdl] unknown-ref: edge "${e.id}" の from "${e.from}" が node に存在しません${suggest(e.from, nodeIds)}\n  → 修正例: .node("${e.from}", { lane: "...", stack: 0, kind: "actor", title: "..." }) を edge 宣言前に追加`,
+        `[cdl] unknown-ref: edge "${e.id}" の from "${e.from}" が node に存在しません${suggest(e.from, nodeIds, "node")}\n  → 修正例: .node("${e.from}", { lane: "...", stack: 0, kind: "actor", title: "..." }) を edge 宣言前に追加`,
       );
     }
     if (!nodeIds.has(e.to)) {
       errors.push(
-        `[cdl] unknown-ref: edge "${e.id}" の to "${e.to}" が node に存在しません${suggest(e.to, nodeIds)}\n  → 修正例: .node("${e.to}", { lane: "...", stack: 0, kind: "...", title: "..." }) を edge 宣言前に追加`,
+        `[cdl] unknown-ref: edge "${e.id}" の to "${e.to}" が node に存在しません${suggest(e.to, nodeIds, "node")}\n  → 修正例: .node("${e.to}", { lane: "...", stack: 0, kind: "...", title: "..." }) を edge 宣言前に追加`,
       );
     }
     if (e.from === e.to) {
@@ -139,6 +156,20 @@ export function validate(diag: CdlDiagram): void {
         errors.push(`[cdl] unknown-ref: phase "${p.id}" の activate "${id}" は node でも edge でもない (typo の可能性)`);
       }
     }
+    // 描き始める対象は node に限る (cdl#512)。 edge は `activate` された phase で自分から
+    // 伸びるため (`render/edges.tsx` の `SolidEdgePath`)、 `draw` で指す相手にならない
+    for (const id of p.draw ?? []) {
+      if (!nodeIds.has(id)) {
+        errors.push(`[cdl] unknown-ref: phase "${p.id}" の draw "${id}" は node ではない (typo の可能性)${suggest(id, nodeIds, "node")}`);
+        continue;
+      }
+      // 描き方を持たない種別を指しても図は出るが、 書いた指定は何もしない。
+      // 黙って捨てると「書いたのに伸びない」 が手掛かりなしで起きる
+      const kind = diag.nodes.find((n) => n.id === id)?.kind;
+      if (kind !== "chart-line") {
+        warnings.push(`phase "${p.id}" の draw "${id}" は kind "${kind}" で、 左から描く動きを持たない (対象は chart-line)`);
+      }
+    }
     for (const t of p.tweens) {
       if (!stateIds.has(t.stateId)) {
         errors.push(`[cdl] unknown-ref: phase "${p.id}" tween 対象 state "${t.stateId}" 未定義`);
@@ -158,13 +189,13 @@ export function validate(diag: CdlDiagram): void {
   }
 
   // ───────────────────────────────────────────────────────────
-  // 6. state 参照 (node.value / node.rows の {stateId}) → 未定義は warning
+  // 6. state 参照 ({名前} を読む欄) → 未定義は warning
   // ───────────────────────────────────────────────────────────
+  // 見る欄は `nodeTemplateTexts` が SSOT (#455)。 以前は `value` と `rows` の 2 つだけを見て
+  // いたが、 描画側は `title` / `visibleIf` / `wBind` 等でも `{名前}` を読むため、 書いた名前が
+  // 未定義でも黙って通っていた
   for (const n of diag.nodes) {
-    const checks: string[] = [];
-    if (n.value) checks.push(n.value);
-    if (n.rows) checks.push(...n.rows);
-    for (const text of checks) {
+    for (const text of nodeTemplateTexts(n)) {
       // 名前の切り出しは描画側と同じ式を使う (`templateRefIds`)。 別に書くと字種がずれ、
       // 置換されうる名前が検証を素通りする
       for (const id of templateRefIds(text)) {
@@ -193,15 +224,16 @@ export function validate(diag: CdlDiagram): void {
       warnings.push(`edge "${e.id}" がどの phase でも activate されていない (unused、 typo の可能性)`);
     }
   }
-  // 使われない state も warn (tween / set / node.value / node.rows のいずれにも参照されない)
+  // 使われない state も warn (tween / set / node の `{名前}` を読む欄 のいずれにも参照されない)
   const stateUsed = new Set<string>();
   for (const p of diag.phases) {
     for (const t of p.tweens) stateUsed.add(t.stateId);
     for (const s of p.sets) stateUsed.add(s.stateId);
   }
   for (const n of diag.nodes) {
-    const texts = [n.value, ...(n.rows ?? [])].filter(Boolean) as string[];
-    for (const text of texts) {
+    // 読む欄は上の 6 と同じ SSOT から取る。 別々に列挙すると、 片方だけに欄が足されたときに
+    // 「未定義として warn しつつ unused としても warn する」 という食い違いが出る (#455)
+    for (const text of nodeTemplateTexts(n)) {
       // 名前の切り出しは描画側と同じ式を使う。 別に書くと字種がずれ、 実際は読まれている
       // 状態が「どこでも参照されていない」 と報告される
       for (const id of templateRefIds(text)) stateUsed.add(id);

package/src/visual-validate.ts

@@ -87,6 +87,7 @@ import {
   segmentsCrossRect,
 } from "./layout/collisions";
 import { measureTextWidth } from "./layout/text-width";
+import { droppedLineIsHidden, labelPlan } from "./kinds/shape-region";
 import { templateRefIds } from "./render/utils";
 import {
   bboxOverlaps,
@@ -129,6 +130,7 @@ import {
   isRenderedNode,
   rendersRows,
   rendersTitleText,
+  fitsOwnTitleWidth,
   rowBaselineY,
   rowGlyphDepth,
   LANE_BORDER_CLEARANCE_TOL,
@@ -327,6 +329,8 @@ export type VisualAxis =
   // Axis 53 (2026-07-03 追加) = node が diagram viewBox 内に収まっているか。
   // 既存 Axis 14 (label-inside-viewbox) の node 版、 clip 検知の直接手段。
   | "node-inside-viewbox"
+  // Axis 67 (`#492` 追加) = 箱が狭くて書いた補いの行が描かれない node を書き手に伝える。
+  | "shape-label-dropped"
   // Axis 54 (2026-07-03 追加) = node bbox が所属 lane 内に収まっているか。
   // Axis 15 (lane-cx-consistency) は中心 x のみ、 本 axis は node 4 辺と lane 4 辺の包含関係を検知。
   | "node-inside-lane"
@@ -471,6 +475,7 @@ function emptyCounts(): Record<VisualAxis, number> {
     "validate-performance-budget": 0,
     "node-inside-viewbox": 0,
     "node-inside-lane": 0,
+    "shape-label-dropped": 0,
     "edge-inside-viewbox": 0,
     "lane-label-inside-viewbox": 0,
     "lane-label-overlap": 0,
@@ -1833,6 +1838,9 @@ function runAxes(
     if (n.id.endsWith("-spacer")) continue;
     // 文字を描かない種別は title が幅を超えて切れることが起きない。
     if (!rendersTitleText(n.kind)) continue;
+    // 自分で幅に合わせて切る種別も同じ。 字数から幅を出す下の近似は字の大きさ 22 を前提に
+    // しており、 それより小さい字で描く種別に当てると偽陽性になる (#469)
+    if (fitsOwnTitleWidth(n.kind)) continue;
     // 常に非表示の node の文字は画面に出ないので、 切れようがない。
     if (!isRenderedNode(n)) continue;
     const titleTrimmed = n.title?.trim() ?? "";
@@ -2231,6 +2239,29 @@ function runAxes(
     }
   }
 
+  // ───────────────────────────────────────────────────────────
+  // Axis 67: shape-label-dropped (箱が狭くて書いた補いの行が描かれない、 #492)
+  //
+  // `shape-` の箱は絵と文字を同じ箱に収める。 箱が狭いと絵に帯を譲るため補いの行 (肩書 →
+  // 説明) を描かない (`#459`)。 **書いたのに図に出ない** ので、 書き手に伝える経路が要る。
+  //
+  // 共有 plan と固有 layout で描く行が種別ごとに違う。 さらに肩書だけを描く種別と説明だけを
+  // 描く種別があるため、 落とした行を 1 行ずつ実際の描画規則と照合する。
+  //
+  // ## 覆えていない範囲
+  //
+  // 共有 plan が行を落とさない高さでは、 固有 layout がその行を描かない種別でも報告されない。
+  // 本軸は箱が狭くて落ちた行だけを扱い、 種別が元から対応しない欄は別の検査範囲とする。
+  for (const n of laid.nodes) {
+    const 落とした = labelPlan(n).落とした.filter((line) => droppedLineIsHidden(n.kind, line));
+    if (落とした.length === 0) continue;
+    push(
+      "shape-label-dropped",
+      `node "${n.id}" (${n.kind}, ${n.w.toFixed(0)}x${n.h.toFixed(0)}) は書いた ${落とした.join(" / ")} が描かれない。 箱を高くするか、 その行を消す`,
+      "warn",
+    );
+  }
+
   // ───────────────────────────────────────────────────────────
   // Axis 55: edge-inside-viewbox (edge path 全 segment 端点が viewBox 内に収まる)
   //
@@ -4264,6 +4295,7 @@ function validateMetaAxes(
     "validate-performance-budget",
     "node-inside-viewbox",
     "node-inside-lane",
+    "shape-label-dropped",
     "edge-inside-viewbox",
     "lane-label-inside-viewbox",
     "lane-label-overlap",
@@ -4332,6 +4364,7 @@ function validateMetaAxes(
     "validate-performance-budget",
     "node-inside-viewbox",
     "node-inside-lane",
+    "shape-label-dropped",
     "edge-inside-viewbox",
     "lane-label-inside-viewbox",
     "lane-label-overlap",
@@ -4367,7 +4400,7 @@ function validateMetaAxes(
   //
   // 削除済 = engine-meta 51 (mermaid-parity、 #366) / 軸 29 (svg-filter-integrity) /
   // 軸 30 (neumorphism-shadow-budget、 どちらも #426 で主題の廃止に伴い削除)。
-  const EXPECTED_AXIS_COUNT = 66;
+  const EXPECTED_AXIS_COUNT = 67;
   if (allAxes.length !== EXPECTED_AXIS_COUNT) {
     out.push({
       axis: "axis-documentation-completeness",

package/src/layout/label-shift.ts

@@ -1,28 +0,0 @@
-import type { LaidEdge, LaidLane, LaidNode } from "../types";
-
-/**
- * Edge label の post-pass shift 探索は CAR-430 で削除済 (no-op passthrough)。
- *
- * 旧実装 (v10 系) は 16 方向 × 26 段階の全探索型 shift + Tier 0-3 fallback +
- * PROXIMITY_HARD_CAP + computeFanTShift 等の場当たり logic で label 位置を再計算していた。
- * CAR-426 chain 伝搬 shift の label 層拡張 (CAR-426-A / CAR-428) 完了で
- * `resolveEdgeLabelOverlapsWithChain` (`layout/collisions.ts`) が label overlap 解消の
- * 単一 SSOT になったため、 本 file の shift 探索は 二重権限 として削除された。
- *
- * label 配置の権限フロー (CAR-430 SSOT)。
- *   1. `edges.ts routePath()` = 初期 label 位置 (path 中点 ± 30 world 等) を SSOT で決定
- *   2. `resolveEdgeLabelOverlapsWithChain` (post-pass 2) = overlap 検出時のみ chain 伝搬 shift
- *   3. 本 function = 通過 no-op (旧 API caller の後方互換のため signature 保持)
- *
- * 後方互換のため export は残置、 内部で input を そのまま返す。
- * caller (`layout.ts` post-pass 1) は CAR-430 同 PR で削除済で、 本 function は
- * pipeline 経由では呼ばれない。 外部 caller (dragon 等の direct import) がある可能性を
- * 考慮して signature のみ維持する。
- */
-export function shiftLabelsAwayFromNodes(
-  edges: LaidEdge[],
-  _nodes: LaidNode[],
-  _lanes: LaidLane[],
-): LaidEdge[] {
-  return edges;
-}