@shibayama/pdgkit 0.1.0

package/docs/spec.md

@@ -0,0 +1,592 @@
+# PatentDSL / pdgkit 仕様書
+
+特許図面のための記述言語 **PatentDSL**(ファイル拡張子 `.pdg`)と、その実装エンジン **pdgkit** の仕様。`.pdg` は Patent Diagram Grammar の略である。
+
+- 対象バージョン: pdgkit v0.1.0(DSL は PatentDSL v1.0.3 と完全互換)
+- npm パッケージ: `@shibayama/pdgkit`(CLI コマンドは `pdgkit` / `pdgkit-mcp`)
+- 拡張子: `.pdg`
+- エンコーディング: UTF-8
+- 改行: `LF` / `CRLF` のいずれも可
+
+本書は **言語仕様(§1–§12)** と **エンジン仕様(§13–§17)** の二部構成です。言語仕様は PatentDSL 本家と同一の挙動を、エンジン仕様は pdgkit 固有のヘッドレス描画・検証・CLI を規定します。
+
+---
+
+## 目次
+
+**言語仕様**
+1. [設計原則](#1-設計原則)
+2. [字句](#2-字句)
+3. [文要素](#3-文要素)
+4. [ラベルと多言語](#4-ラベルと多言語)
+5. [コメント](#5-コメント)
+6. [クォート / エスケープ](#6-クォート--エスケープ)
+7. [図種の自動推論](#7-図種の自動推論)
+8. [形状の自動推論](#8-形状の自動推論)
+9. [描画・レイアウト方針](#9-描画レイアウト方針)
+10. [診断(エラー / 警告)](#10-診断エラー--警告)
+11. [BNF 風文法](#11-bnf-風文法)
+12. [仕様の境界(やらないこと)](#12-仕様の境界やらないこと)
+
+**エンジン仕様(pdgkit 固有)**
+13. [図種アサーション・ディレクティブ](#13-図種アサーションディレクティブ)
+14. [`validate()` の診断](#14-validate-の診断)
+15. [ヘッドレス描画の寸法計算](#15-ヘッドレス描画の寸法計算)
+16. [CLI の入出力と終了コード](#16-cli-の入出力と終了コード)
+17. [出力仕様](#17-出力仕様)
+
+---
+
+# 言語仕様
+
+## 1. 設計原則
+
+- **1 行 = 1 文。** 改行が文の終わり。
+- 文要素は **定義 / 包含 / 接続** の 3 種類のみ。
+- **キーワードを持たない。** 図種は構造から自動推論される。
+- 符号(reference numerals)を直接 ID として扱う。明細書本文と直接照合できる。
+- 日英ラベルを 1 ソースで管理する。
+- 座標指定・色指定を持たない。レイアウトは自動のみ。
+
+---
+
+## 2. 字句
+
+### 2.1 符号(ID)
+
+符号は次のパターン:
+
+```
+ID := [A-Za-z0-9_*]+
+```
+
+| 例 | 用途 |
+|---|---|
+| `10` `20` `100` | 装置クレームでよくある数値符号 |
+| `S100` `S110` | 方法クレームのステップ符号 |
+| `K1` `P2_3` `11a` | 英字+数字、`_` も可 |
+| `*` | 状態遷移の初期/終端マーカ(黒丸で描画) |
+
+ID に使えない記号(予約): `=` `:` `-` `>` `<` `.` `/` `#` `"` `(` `)` および空白。
+
+### 2.2 演算子(接続)
+
+接続演算子は **必ず前後を半角スペース(またはタブ)で囲む**。これは ID と演算子を曖昧さなく分離するための規則である(`11-12` は不可、`11 - 12` は可)。
+
+長い演算子から順にマッチする(`<->` を `<-` `->` より先に判定):
+
+```
+OP := '<->' | '=>' | '->' | '<-' | '.>' | '..' | '-'
+```
+
+### 2.3 文字列リテラル
+
+ダブルクォートで囲まれた任意の文字列。
+
+```
+STRING := '"' (改行と '"' を除く任意の文字)* '"'
+```
+
+文字列内の `"` をエスケープする手段は現バージョン非対応(`\"` 等は未サポート)。
+
+### 2.4 空白・空行
+
+行内の連続する空白(スペース・タブ)は区切り。先頭/末尾の空白は無視。空行(空白のみの行を含む)は無視。
+
+---
+
+## 3. 文要素
+
+各行は(コメント除去後に)次の順で判定される:
+
+1. **定義パターン** にマッチ → 定義
+2. **接続パターン** にマッチ → 接続
+3. **包含パターン** にマッチ → 包含
+4. いずれにもマッチしない → `構文不明` エラー
+
+> 実装注: 接続を包含より先に判定する。これにより `A -> B` は包含(`:` を含まない)ではなく接続として正しく解釈される。
+
+### 3.1 定義
+
+```
+DEF := ID '=' LABEL
+```
+
+符号にラベルを付ける。
+
+```pdg
+10 = 制御装置 / control device
+11 = CPU
+13 = "I/O インターフェース" / "I/O interface"
+10 =                       # ラベルなし定義も可
+```
+
+- `=` の前後の空白は任意。
+- `=` の直後が `>` の場合は接続(`=>`)として扱う(否定先読み `=(?!>)`)。
+- 同じ ID を 2 回定義すると **警告**(後の定義で上書き)。
+
+### 3.2 接続
+
+```
+CONN := ID WS+ OP WS+ ID (WS* ':' WS* LABEL)?
+```
+
+ノード間に線・矢印を描く。
+
+```pdg
+11 -   12          # 単線
+13 ->  20          # 矢印
+30 <-  40          # 逆矢印(= 40 -> 30)
+50 <-> 60          # 双方向
+70 ..  80          # 破線
+70 .>  80          # 破線矢印
+40 =>  50          # 太矢印
+13 ->  20 : 信号 / signal   # ラベル付き
+```
+
+- 演算子の前後は **必ず半角スペース 1 つ以上**。
+- `:` 以降がラベル(任意)。
+- `<-` はパース時に from/to を入れ替えて `->` 相当に正規化される。
+- 接続に登場した未定義 ID は **暗黙ノード** として自動生成される。
+- **連鎖記法 `A -> B -> C` は未対応**(1 行 1 接続に分割)。
+
+#### 演算子セマンティクス
+
+| 演算子 | 線種 | 矢印 | 内部表現(`EdgeOp`) |
+|---|---|---|---|
+| `-` | 単線 | なし | `line` |
+| `->` | 単線 | 終点 | `arrow` |
+| `<-` | 単線 | 始点(正規化後は終点) | `arrow`(reverse) |
+| `<->` | 単線 | 両端 | `bidir` |
+| `..` | 破線 | なし | `dashed` |
+| `.>` | 破線 | 終点 | `dashed-arrow` |
+| `=>` | 太線 | 終点 | `thick` |
+
+### 3.3 包含
+
+```
+CONT := ID WS* ':' WS+ ID (WS+ ID)*
+```
+
+親が子を内包する関係を表す。
+
+```pdg
+100 : 10 20
+10  : 11 12
+20  : 21 22
+```
+
+- 子の符号は **半角スペース区切り**。子が 1 つでも可。
+- ネストは別の包含文として書く(容器自身を別容器の子にする)。
+- 子トークンが ID パターンに反する場合は `包含の子として不正なトークン` エラー。
+- **包含文が 1 つでもあれば、図はブロック図**として描画される(§7)。
+
+---
+
+## 4. ラベルと多言語
+
+```
+LABEL   := SEGMENT (' / ' SEGMENT)?
+SEGMENT := STRING | 生テキスト
+```
+
+- ラベル中の **クォート外の空白付き ` / `**(前後に空白がある `/`)は **日英の区切り**。前=日本語、後=英語。
+- `A/D`、`I/O`、`S/N` のように **語中の `/`** はラベル文字として扱う。
+- クォート内の `/` `:` `=` `#` は文字として扱う。
+- 片言語のみの場合、もう一方の言語モードでも同じ文字列で表示される。
+
+| 入力 | 解釈 |
+|---|---|
+| `10 = 制御部 / control unit` | ja="制御部", en="control unit" |
+| `11 = CPU` | ja="CPU"(両モードで CPU) |
+| `13 = A/D変換部 / A/D converter` | ja="A/D変換部", en="A/D converter" |
+| `14 = "I/O" / "I/O interface"` | ja="I/O", en="I/O interface" |
+| `15 = "比率 1:2" / "ratio 1:2"` | ja="比率 1:2", en="ratio 1:2" |
+
+接続ラベル(`: ` 以降)も同じ規則に従う。
+
+---
+
+## 5. コメント
+
+```
+COMMENT := '#' (改行以外)*
+```
+
+- `#` から行末までは無視される。行頭・行中どこでも可。
+- クォート内の `#` は文字として扱う。
+
+```pdg
+# これはコメント行
+10 = 制御装置    # 行末コメントも可
+20 = "型番 #A100" / "Model #A100"   # クォート内の # はリテラル
+```
+
+> pdgkit はコメントの中に **図種アサーション・ディレクティブ**(§13)を置く。ディレクティブもパーサからは通常のコメントとして無視されるため、本家との互換を壊さない。
+
+---
+
+## 6. クォート / エスケープ
+
+ラベルに予約記号(` / ` `:` `=` `#` `"`)を含めたい場合は `"..."` で囲む。語中の `/` はそのまま書ける。
+
+| 入力 | ラベル |
+|---|---|
+| `13 = "I/O インターフェース"` | `I/O インターフェース` |
+| `14 = "比率 1:2"` | `比率 1:2` |
+| `16 = "y = ax + b"` | `y = ax + b` |
+
+**制限**: クォート内の `"` のエスケープは未対応。
+
+> pdgkit の SVG 出力では、ラベル中の `<` `>` `&` `"` は XML として正しくエスケープされる(§15)。DSL レベルのクォートとは別レイヤの処理である。
+
+---
+
+## 7. 図種の自動推論
+
+ソース構造を見て **上から順に** 判定する(最初に該当した規則で確定):
+
+```
+1. 包含文(:)が 1 つ以上ある                          → ブロック図 (block)
+2. ラベル末尾が '?' の符号がある                       → フローチャート (flow)
+3. 符号 '*' が登場する                                 → 状態遷移図 (state)
+4. '<->' 演算子、または往復ペア(A→B かつ B→A)がある  → シーケンス図 (seq)
+5. 上記以外(片方向接続のみ)                           → フローチャート (flow)
+```
+
+| ソース概略 | 判定 |
+|---|---|
+| `10 : 11 12` がある | block |
+| `S110 = 条件?`(包含なし) | flow |
+| `* -> S1`(包含・? なし) | state |
+| `100 -> 200`, `200 -> 100`(往復) | seq |
+| `100 <-> 200` | seq |
+| `S100 -> S110`, `S110 -> S120`(片方向のみ) | flow |
+
+> **重要(AI 向け):** 図種は宣言ではなく **構造の結果** である。意図せず `:` / `?` / `*` / `<->` を入れると図種が変わる。意図を固定したい場合は §13 の図種アサーションを使う。
+
+---
+
+## 8. 形状の自動推論
+
+### 8.1 フローチャート時
+
+| 条件 | 形状 |
+|---|---|
+| ラベル末尾が `?` | ◆ 菱形(条件分岐) |
+| 入次数 0 | ⬭ 角丸(開始) |
+| 出次数 0 | ⬭ 角丸(終了) |
+| それ以外 | □ 長方形(処理) |
+
+### 8.2 状態遷移図時
+
+| 符号 | 形状 |
+|---|---|
+| `*` | ● 黒丸(初期/終端) |
+| その他 | ⬭ 角丸長方形(状態) |
+
+### 8.3 ブロック図 / シーケンス図
+
+- ブロック図: すべて □ 長方形(包含の親は枠付きコンテナ、子は内側の矩形)。
+- シーケンス図: アクタは □ 長方形 + 下方向の破線ライフライン(自動表示)。
+
+---
+
+## 9. 描画・レイアウト方針
+
+レイアウトは自動のみ。特許のブロック図で典型的な「機能ラベル付きの中空矩形を線で相互接続する」形式を優先する。
+
+### 9.1 ブロック図
+
+- 子が 1〜2 個の包含は縦 1 列。
+- 子が 3 個以上で子同士が直列の処理チェーンを作る場合は縦 1 列。
+- 子が 3 個以上で分岐/並列/スター状の接続の場合は 2〜4 列グリッド寄り。
+- グリッド配置では行ごとの高さを用いる(縦長要素が他行を引き伸ばさない)。
+- 入れ子コンテナは外側から内側へ描画。
+- 同一親コンテナ内の接続は親の外へ逃がさず、内側の余白通路を優先。
+- 外部ブロックは接続先の内部ブロックに近い高さへ自動整列。
+- 外部接続は可視ブロックを横切らない経路を優先。上下に明確にずれる場合は上辺/下辺への接続を優先。
+- 接続ラベルはノード・コンテナのタイトル領域・外枠・既存ラベルとの重なりを避け、長い空き区間や線から少し離した位置を優先。
+
+### 9.2 ブロック図の配線
+
+接続線は **直交線による配線問題** として扱う。単純な最短経路ではなく、禁止領域とペナルティを持つ評価で経路を決定する:
+
+- 実ノード内部を横切らない。
+- 外部接続先コンテナは外枠で接続し、内部を通過しない。
+- 矢印付き接続は終端直前に鏃を描ける直線区間を確保し、線本体は鏃の手前で止める。
+- 既存の矢印鏃・主要線分を後続線の障害物として扱う(候補不足時も強い減点として残す)。
+- 同一ノードから複数線が出る場合、接続点と短いスタブを分散する。
+- 端点から大きく離れた迂回には減点。候補レーン数に上限(密な図でも探索量を抑制)。
+
+### 9.3 フローチャート / 状態遷移図
+
+- 接続関係から BFS でランクを計算し、上から下へ配置。
+- 循環は最初に到達したランクを優先(first-touch wins)し、接続自体は描画。
+- 未接続ノードは下方へ追加配置。
+
+### 9.4 シーケンス図
+
+- アクタは接続に登場した順に左から配置。
+- メッセージはソースの行順に上から下へ配置。
+- ライフラインは破線で描画(矢印マーカなし)。
+
+---
+
+## 10. 診断(エラー / 警告)
+
+パーサは次の診断を発する(`Diagnostic { severity, line, col, message }`)。
+
+| 重大度 | 例 | 意味 |
+|---|---|---|
+| error | `構文不明: "10 == X"` | いずれの文型にもマッチしない行 |
+| error | `包含の子として不正なトークン: "1@1"` | 包含の子が ID パターンに反する |
+| warning | `符号 "10" は再定義されました` | 同一 ID の重複定義(後勝ち) |
+
+**エラーがあっても可能な範囲で描画は続行される**(堅牢性優先)。接続・包含だけに現れた未定義符号は暗黙ノードとして自動生成され、符号表では薄色で表示される。
+
+pdgkit はこれらに加えて §13・§14 の診断を付与する。
+
+---
+
+## 11. BNF 風文法
+
+```ebnf
+document   = { line } ;
+line       = blank | comment | def_line | conn_line | cont_line ;
+
+blank      = WS* CR ;
+comment    = '#' (~CR)* CR ;
+
+def_line   = id WS* '=' (?!'>') WS* label CR ;
+conn_line  = id WS+ op WS+ id (WS* ':' WS* label)? CR ;
+cont_line  = id WS* ':' WS+ id { WS+ id } WS* CR ;
+
+op         = '<->' | '=>' | '->' | '<-' | '.>' | '..' | '-' ;
+
+id         = ID_CHAR+ ;
+ID_CHAR    = 'A'..'Z' | 'a'..'z' | '0'..'9' | '_' | '*' ;
+
+label      = segment (WS+ '/' WS+ segment)? ;
+segment    = string | raw_text ;
+string     = '"' (~'"' & ~CR)* '"' ;
+raw_text   = (~'#' & ~CR)+ ;
+
+WS         = ' ' | '\t' ;
+CR         = '\n' | '\r' '\n' ;
+```
+
+> 注: `def_line` で `=` の直後が `>` の場合は否定先読みで除外する(`=>` は演算子)。判定順は §3 のとおり 定義 → 接続 → 包含。
+
+---
+
+## 12. 仕様の境界(やらないこと)
+
+- 連鎖記法 `A -> B -> C`(各行に分ける)
+- 1 ファイル複数図(1 図 1 ファイル)
+- 任意 SVG の埋め込み・カスタム形状定義
+- 色指定・スタイル指定(特許図面の慣習で黒線のみ)
+- 自由な座標指定(レイアウトは自動のみ)
+- セル / レーン(swimlane)
+- alt / loop / parallel のシーケンス拡張
+- カスタムフォント・配色テーマ
+
+これらは記法を読みやすく保つため意図的に外している。
+
+---
+
+# エンジン仕様(pdgkit 固有)
+
+## 13. 図種アサーション・ディレクティブ
+
+意図する図種をソース内に宣言し、`validate()`(§14)が推論結果(§7)と照合する仕組み。**コメント内に置く**ため、パーサからは通常コメントとして無視され、本家互換を壊さない。
+
+### 13.1 構文
+
+コメント本文(最初の非クォート `#` 以降)が次の正規表現にマッチする最初の行を採用する:
+
+```
+/^\s*!?\s*(?:pdgkit\s*:)?\s*kind\s*[:=]?\s*(block|flow|state|seq)\b/i
+```
+
+受理される表記例(いずれも同義):
+
+```pdg
+#! kind: block        # 正準形(推奨)
+# pdgkit: kind = flow
+# kind seq
+#kind state
+```
+
+### 13.2 セマンティクス
+
+- 宣言された図種が推論図種と **一致** → 問題なし(`kindMatches = true`)。
+- **不一致** → `error` 重大度の診断を 1 件発する。メッセージは宣言・推論の双方と、見直すべき構造目印(`:` / 末尾 `?` / `*` / 往復・`<->`)を含む。
+- 宣言が **ない** → アサーションは行わない(`declaredKind = null`, `kindMatches = null`)。
+
+```pdg
+#! kind: block
+S1 = 条件?        # ← ? によりフローと推論され、宣言 block と不一致 → エラー
+S2 = 次
+S1 -> S2
+```
+
+---
+
+## 14. `validate()` の診断
+
+`validate(source) → ValidateResult` は、§10 のパーサ診断に次を加えて返す。
+
+```ts
+interface ValidateResult {
+  ok: boolean;                       // error 重大度が 0 件
+  kind: DiagramKind;                 // 推論図種
+  declaredKind: DiagramKind | null;  // §13 の宣言
+  kindMatches: boolean | null;
+  diagnostics: Diagnostic[];         // 行・列順にソート
+  counts: { errors; warnings; infos };
+}
+```
+
+付与される pdgkit 独自診断:
+
+| 重大度 | 契機 | メッセージ要旨 |
+|---|---|---|
+| error | 図種アサーション不一致(§13) | 宣言と推論の図種が違う |
+| info | `構文不明` 行に空白付き演算子が 2 つ以上 | 連鎖記法は未対応。1 行 1 接続に分割 |
+| info | `構文不明` 行に演算子が ID に密着 | 演算子の前後に半角スペースが必要 |
+
+`info` は助言であり `ok` を偽にしない。`ok` を偽にするのは `error` のみ(`warning` も `ok` を偽にしない)。
+
+> 推奨運用: ホスト AI は `ok === false` の間、`diagnostics` を AI に返して `.pdg` を再生成させる。`info` も併せて渡すと修正精度が上がる。
+
+---
+
+## 15. ヘッドレス描画の寸法計算
+
+`renderToSvg(source, options)` は `parse → layout → render → 切り出し → シリアライズ` を行う。ブラウザ版の `SVG` 書き出し(`exportSvgFile`)と同じ数値で出力する。
+
+### 15.1 コンテンツボックス(切り出し)
+
+- ブラウザ版は `element.getBBox()` で実描画範囲を求めるが、これはブラウザ専用 API である。
+- pdgkit は生成済み SVG モデルを走査し、各プリミティブ(`rect` / `circle` / `polygon` / `path`(M・L のみ)/ `text` / `line` / `polyline`)の範囲を **解析的に** 合算する。`text` の幅は `layout` と同一の文字幅 heuristic(`estimateTextWidth`)を用いる:
+
+  ```
+  幅(文字) = 空白 → fontSize*0.35 / ASCII → fontSize*0.58 / それ以外(CJK 等) → fontSize*1.0
+  ```
+
+- 合算結果に **余白 `bleed`(既定 3 単位)** を付ける(本家 `RASTER_BLEED` と一致)。
+
+### 15.2 表示寸法
+
+切り出した viewBox に対し、`width` / `height`(px)を次で定める(本家 `svgDisplayDimensionsForViewBox` と一致):
+
+```
+scale  = max(1, targetSide / max(viewBox.width, viewBox.height))   // targetSide 既定 1600
+width  = ceil(viewBox.width  * scale)
+height = ceil(viewBox.height * scale)
+```
+
+これにより、SVG をブラウザで直接開いても極端に小さく表示されない(長辺 ≥ 1600px)。
+
+### 15.3 SVG 文書の属性
+
+ルート `<svg>` に `xmlns`・`version="1.1"`・`viewBox`・`width`・`height`・`preserveAspectRatio="xMidYMid meet"` を設定し、既定で `<?xml version="1.0" encoding="UTF-8"?>` を前置する。ラベル等の `<` `>` `&`、属性値中の `"` は XML として正しくエスケープされる。
+
+### 15.4 オプション
+
+| オプション | 既定 | 意味 |
+|---|---|---|
+| `lang` | `'ja'` | `'ja'` / `'en'` / `'both'`(日英 2 段) |
+| `crop` | `true` | 実描画範囲で切り出し。`false` で全キャンバス |
+| `bleed` | `3` | 切り出し余白(単位) |
+| `targetSide` | `1600` | `width`/`height` の長辺 px 下限 |
+| `xmlDeclaration` | `true` | `<?xml ...?>` を前置 |
+
+### 15.5 決定論
+
+`Date.now()` / `Math.random()` / フォント実測に依存しない。**同じ入力・同じオプション → 同じ SVG(バイト一致)**。回帰テストとキャッシュに適する。
+
+---
+
+## 16. CLI の入出力と終了コード
+
+```text
+pdgkit render   <input> [--to svg|png|jpeg|pdf|pptx] [--lang ja|en|both] [-o file] [--no-crop]
+pdgkit validate <input>
+pdgkit refs     <input> [--format md|csv] [-o file]
+pdgkit samples
+pdgkit version | help
+```
+
+### 16.1 入力の解決順
+
+1. `--sample <id>` があればその内蔵サンプル。
+2. 位置引数がファイルパス(`-` 以外)なら、そのファイル。
+3. それ以外は **標準入力**。
+
+### 16.2 出力
+
+- テキスト形式(svg / md / csv)は `-o` 省略時に標準出力へ。
+- バイナリ形式(png / jpeg / pdf / pptx)は `-o` 必須。
+- 進捗・診断メッセージは **標準エラー出力** へ(標準出力を成果物専用に保つ)。
+
+### 16.3 終了コード
+
+| コード | 意味 |
+|---|---|
+| `0` | 成功(`validate` は error 診断 0 件) |
+| `1` | 検証エラー、または実行時エラー(未実装形式の呼び出しを含む) |
+| `2` | 使い方の誤り(不明なサンプル / ファイル読込不可 / 不正なフラグ) |
+
+### 16.4 例
+
+```bash
+pdgkit render fig1.pdg -o fig1.svg
+pdgkit render --sample block --lang both -o block.svg
+cat fig1.pdg | pdgkit validate -          # 終了コードで成否判定
+pdgkit refs fig1.pdg --format csv -o signs.csv
+```
+
+---
+
+## 17. 出力仕様
+
+`.pdg` から次の形式を出力できる。いずれもブラウザ非依存(Node)で生成する。図種(block / flow / state / seq)に関わらず、どの形式でも出力可能。
+
+| 形式 | 内容 | 生成方法 |
+|---|---|---|
+| SVG | 実描画範囲で切り出したベクタ画像。viewBox と表示寸法は §15 のとおり | 内蔵 SVG シリアライザ(依存なし) |
+| PNG | 既定 8 倍解像度・白背景のラスタ | `@resvg/resvg-js`(IPAex 埋込) |
+| JPEG | 既定 8 倍解像度・白背景のラスタ | resvg + `jpeg-js` |
+| PDF | A4・IPAex 埋込。既定はベクタ(テキスト選択可)、失敗時はラスタにフォールバック | `jsPDF` + `svg2pdf.js`(jsdom) |
+| PPTX | 16:9 スライドに高解像度画像を 1 枚配置 | resvg + Open XML(自前 ZIP) |
+| PPTX(編集) | SVG の各要素を編集可能な PowerPoint 図形・線・文字へ変換 | SVG 走査 + Open XML |
+| 符号 MD | 符号表(符号 / 日本語 / 英語)の Markdown | 純関数 |
+| 符号 CSV | 符号表の CSV(`id,ja,en`) | 純関数 |
+
+### 17.1 共通仕様
+
+- ラスタ倍率は既定 8。一辺 24000px・総画素 1e8 を上限に、超える場合は倍率を自動的に下げる(§15.2)。
+- 画像系(SVG / PNG / JPEG / PPTX 画像)は実描画範囲で切り出し、小さな余白(`bleed`、既定 3 単位)を付ける。
+- 表示言語(`ja` / `en` / `both`)はすべての描画出力に反映される。`both` は日英 2 段表示。
+- ラベル中の `<` `>` `&` `"` は XML/OOXML として正しくエスケープされる。
+- PNG / JPEG の背景は白。JPEG はアルファを持たないため白背景に合成される。
+
+### 17.2 API と CLI の対応
+
+| 形式 | ライブラリ | CLI(§16) |
+|---|---|---|
+| SVG | `renderToSvg(source, opts)` → `{ svg, ... }` | `render --to svg` |
+| PNG | `renderToPng(source, opts)` → `Uint8Array` | `render --to png` |
+| JPEG | `renderToJpeg(source, opts)` → `Uint8Array` | `render --to jpeg` |
+| PDF | `renderToPdf(source, opts)` → `Uint8Array` | `render --to pdf` |
+| PPTX | `renderToPptx(source, opts)` → `Uint8Array` | `render --to pptx` |
+| PPTX(編集) | `renderToPptx(source, { editable: true })` | `render --to pptx --editable` |
+| 符号 MD / CSV | `refsToMarkdown(parse(s))` / `refsToCsv(parse(s))` | `refs --format md` / `refs --format csv` |
+
+主なオプション: `lang`(`ja` / `en` / `both`)、`scale`(ラスタ倍率、既定 8)、`bleed`(余白、既定 3)、`crop`(SVG の切り出し、既定 true)、`vector`(PDF のベクタ優先、既定 true)、`editable`(PPTX、既定 false)。
+
+---
+
+Copyright (c) 2026 しばやま — MIT License。[PatentDSL](https://github.com/shibayamalicht/patent_dsl)(© 2026 しばやま, MIT)を母体とする。

package/examples/01-block.pdg

@@ -0,0 +1,14 @@
+# ブロック図(装置クレーム用)
+#   包含(:)と接続(-, ->)だけで装置構成を表現
+
+10 = 制御装置 / control device
+11 = CPU
+12 = メモリ / memory
+13 = "I/O インターフェース" / "I/O interface"
+20 = 外部機器 / external device
+
+10 : 11 12 13
+
+11 - 12
+11 - 13
+13 -> 20 : 信号 / signal

package/examples/02-flow.pdg

@@ -0,0 +1,14 @@
+# フローチャート(方法クレーム用)
+#   末尾「?」が条件分岐(菱形)に自動推論される
+
+S100 = 開始 / Start
+S110 = 条件A? / "Condition A?"
+S120 = 処理X / Process X
+S130 = 処理Y / Process Y
+S140 = 終了 / End
+
+S100 -> S110
+S110 -> S120 : Yes
+S110 -> S130 : No
+S120 -> S140
+S130 -> S140

package/examples/03-state.pdg

@@ -0,0 +1,13 @@
+# 状態遷移図
+#   * が初期 / 終端のマーカ(黒丸で描画される)
+
+S1 = 待機 / Idle
+S2 = 動作中 / Running
+S3 = エラー / Error
+
+* -> S1
+S1 -> S2 : 起動 / start
+S2 -> S1 : 停止 / stop
+S2 -> S3 : 異常 / fault
+S3 -> S1 : リセット / reset
+S3 -> *

package/examples/04-seq.pdg

@@ -0,0 +1,10 @@
+# シーケンス図(プロトコル系)
+#   包含も?も*もない → 自動的にシーケンスとして描画
+
+100 = クライアント / client
+200 = サーバ / server
+
+100 -> 200 : 認証要求 / auth request
+200 -> 100 : トークン / token
+100 -> 200 : リソース要求 / resource request
+200 -> 100 : リソース応答 / resource response

package/examples/05-system.pdg

@@ -0,0 +1,19 @@
+# システム全体(階層+外部接続)
+
+100 = システム本体 / Main system
+10 = 制御部 / Control
+20 = 通信部 / Comm
+11 = CPU
+12 = メモリ / memory
+21 = 無線部 / wireless
+22 = 有線部 / wired
+30 = 外部サーバ / external server
+40 = 外部端末 / external terminal
+
+100 : 10 20
+10 : 11 12
+20 : 21 22
+
+21 .> 40 : 無線 / wireless
+22 -> 30 : 有線 / wired
+30 <-> 40 : 通信 / comm

package/examples/06-iot-cloud.pdg

@@ -0,0 +1,27 @@
+# IoT/クラウド構成
+
+100 = センサ端末 / sensor terminal
+10 = 検出部 / detector
+11 = 温度センサ / temperature sensor
+12 = 加速度センサ / acceleration sensor
+20 = 処理部 / processor
+21 = 取得部 / acquisition unit
+22 = 判定部 / determination unit
+30 = 通信部 / communication unit
+200 = ゲートウェイ / gateway
+300 = クラウドサーバ / cloud server
+310 = 受信部 / receiver
+320 = 解析部 / analyzer
+330 = 記憶部 / storage
+
+100 : 10 20 30
+10 : 11 12
+20 : 21 22
+300 : 310 320 330
+
+10 -> 20 : センサ値 / sensor value
+20 -> 30 : 送信データ / transmission data
+30 .> 200 : 無線 / wireless
+200 -> 310 : 中継 / relay
+310 -> 320 : データ / data
+320 -> 330 : 結果 / result