io.github.meta-taro/zumen

**はじめに 1 回叩くこと。** 何をする道具か、何をしないか、**どの口が開いていないか**（試す前に分かる）、版ごとに何が変わったかを返す。ここを読めば、断られる往復が減る。

新しい図を作る。既にファイルがあれば失敗する（上書きの経路にしない）。形式に適合しないものは書かない。既存の図を変えるなら zumen_propose を使うこと。

**この道具に同梱されている見本 189 枚の目次と、その正本**を返す。**何を描くか迷ったら、まずここを見ること。** zumen_spec は「どう書くか」しか渡さない —— zumen の値打ちは書き方ではなく、**歯周チャート・木取り図・舞台の仕込図・中古車の査定図・継手と仕口・点字ブロック**のような、その業界の人が実務で使う図が**どう組まれているか**のほうにある。一行は題名ではなく**その図の決まりごと**（「販売図面（作るための図ではなく、決めるための図）」）。引数なしなら分類と枚数だけ返す。query（「型紙」「歯」「ホーム」など和英どちらでも）で絞る。name を渡すと**その見本の正本（YAML）そのもの**が返るので、**真似て書ける**。**道具の名前でも引ける**（query に views / hatch / chain / openings など）—— 書き方は zumen_spec にあるが、**効いている実物**は見本の中にしかない。**汎用のネットワーク図・フローチャートを量産しないこと** —— 既存の作図ソフトが得意な所を足しても、表現力の証明にならない。

svg（見せる）／**png（自分で見る）**／mermaid（翌日読める）／drawio（翌日編集できる）へ書き出す。落ちるものは、それぞれの書き出しが自分で断る。**png は絵そのものを返す** —— 描いたら必ず 1 枚は png で見ること（数の検査は「読めるか」しか見ていない）。Chrome が要る（無ければ、無いと言う）。

読めるか・要素の数・線の交差・箱の重なり・囲みからのはみ出し・図の大きさ・「9 割」を返す。書いたら必ずこれを見ること。tooTangled は「交差の数が辺の数より多い」という意味で、**それ自体は欠陥ではない**（見本 333 枚で真になる 19 枚は、キーライン図・クモの円網・歯車の基準円・目盛りの格子など、**19 枚とも線が交わること自体が中身**だった）。真のときは、**その図が線の重なりで出来ているのか、ただ絡んでいるのかを自分で見分けること。**hiddenLabels に辺の id があれば、そのラベルは置き場が無くて絵に出ていない（短くするか、辺を減らす）。**kind を必ず見ること** — placement（配置図）では positionsInSource が真で、**置き場所は自分で書く**（nodes[].at に { x, y }）。機械は並べ直さない。**大きさも nodes[].size に書ける**（{ w, h }。構成図でも効く）—— 間取りのように大きさが意味を持つ図では、書かないと全部同じ箱になる。pins は人のものなので書かないこと。tooSmallToProject が真なら、投影すると字が読めない大きさ。**ただし tooSmallToPrint が偽なら、その図は「印刷して読む図」で、投影に向かないだけ**（路線図・査定図・仕込図・積付図はここに入る。見本 95 枚のうち 36 枚がこれ）。**両方が真のときだけ、本当に直すところがある。** 直すときは **文字を大きくしないこと**（図が伸びて比がさらに下がる）。**まず wrap: true を試すこと** —— 横一列に伸びているだけなら、折り返すと収まる（8 個の鎖で比 13.9 → 2.2）。それでも足りなければ、図を分けられないかを人へ聞くこと。crowdedNames に id があれば、その名前は箱に入りきらず、外へ出した先も空いていない（他の箱に重なって出ている）。箱を大きくするか、technology を短くすること。**消してはいない** —— 部屋の名前が消えるのは、重なるより悪いため。adriftNames に id があれば、**幅のある箱から名前が出ていっている**（表の欄なら、値が欄から離れて行が空に見える）。hiddenTags に id があれば、**書いた符号（tag）が印に入りきらず描かれていない** —— 印を大きくするか符号を短くすること（黙って落としている）。crossingEdges に組があれば、**その 2 本の線が交わっている**（crossings は交差の数、crossingEdges はどの辺どうしか）。straddles に組があれば、**その 2 つの箱がはみ出して重なっている**（どちらも相手を含んでいない）。物どうしが同じ場所を取っている状態で、入れ子（overlaps）とは別。ただし伏図の柱・断面の水抜管・盤の上の石のように、**わざと重ねる図もある**。overlappingText に組があれば、**その 2 つの文字が重なって描かれている**（配置図だけ）。箱の重なり（overlaps）は枠の中に節を入れる図では当たり前だが、**文字の重なりはほぼ必ず間違い**。器の名前を器の真ん中に書くと中身の名前に乗るので、**器の名前は端の欄へ出すこと**。doorSwings に組があれば、**開き戸の扇（開くときに通る範囲）に文字か設備が乗っている** —— 開けると当たるか、戸が名前の下に隠れる。hinge（蝶番の側 start / end）・swing（in / out。日本の玄関は外開き）・at を変えるか、乗っている物を動かすこと。roomAccess に部屋があれば、**その部屋へ通り道（廊下・ホール）から入れない**（便所へ居間を横切る、寝室へ浴室を通る）。部屋の種類は名前で読む。建具の位置か部屋の並びを見直すこと。edgesUnderLabels に組があれば、**辺の名札の下を別の辺が通っている**（名札がどちらの線のものか読み違える）。via で回すか、名札を短くすること。edgesThroughBoxes に組があれば、**その線が、両端でも囲みでもない箱の上を通っている**（矢印が別の工程や区画を突き抜けて見える）。via で回すか、中身がそうならそのままでよい。edgesUnderBoxes に組があれば、**その辺は箱の塗りに隠れて描かれない** —— arrows: false は線を箱より先に描くので、枠の中へ引いた線は消える。線を上に出すなら arrows: true にすること。reviewed が偽なら、まだ誰もこ…

その下にある図（*.zumen.yaml）の道を返す。**まず既にある図を見ること** —— 同じ図が既にあるなら、新しく作らずにそれを直す（id を変えると人の手直しが外れる）。返るのは道だけなので、中身は zumen_read で読む。

画面でその要素を選ぶ。**選ぶだけで、図は何も変わらない。**「どれの話か」を言葉で説明する代わりに使う。

提案を**画面に出すだけ**。正本には入らない。人が「正本へ入れる」を押すまで何も起きない。**あなたに押す口は無い。**wait を渡すと、人が答えるまで待って結果を返す（applied＝人が入れた／discarded＝人がやめた／timeout＝まだ見ていない／gone＝画面が消えた）。**timeout は断られたという意味ではない。**形式に適合しない提案は画面に出さない。

**ディスクではなく画面を読む。**人がさっき動かして、まだ保存していない手直しがここに入っている。zumen_read はディスクを読むので、その手直しが見えない。直す前にこれを読むこと。

デスクトップアプリが線の向こうに居るか、いま何を映しているかを返す。**zumen_live_* を使う前にこれを見ること。**繋がっていなければ、提案はファイルへ入れる口（zumen_propose）を使う。screens が 0 なら、人はこの画面を見ていない。

人が置いた位置・大きさ・ラベル・体裁を返す。読むだけで、書き換える口は無い。ここを避けて構造だけを直すこと。

既にある図へ提案を入れる。提案の pins は読まないので、人の手直しは壊れない。人の指定と食い違うところは適用せず、競合として返す。競合を決めるのは人であって、あなたではない。

正本（*.zumen.yaml）をそのまま返す。**直す前に必ず読むこと** —— 中身を知らずに書き換えると、人が手で入れた pins や、知らないキーを落とす。書き換えるときは zumen_propose へ渡す（直接ファイルを書く口は開いていない）。

図の形式・書ける type と appearance の語・守る規則を返す。図を書く前にこれを読むこと。読まずに書くと当て推量になる。

段（正本の並び）から、動く SVG 1 枚と、紙を揃えた連番の SVG を書き出す。画面録画が要らないので、リモートでも作れる。**符号化器は同梱しない** —— mp4 が要るときの作り方は返り値の recipe に入る。