tldraw-desktop

tldraw デスクトップキャンバス API

ローカル HTTP API http://localhost:7236 を介して、tldraw デスクトップアプリ上の図をプログラムで作成および変更できます。

重要： API 呼び出しには必ず curl を使用してください。fetch、wget、その他の HTTP クライアントは使用しないでください。

ワークフロー

1. curl -s http://localhost:7236/api/doc                          → list open docs (get DOC_ID)
2. curl -s http://localhost:7236/api/doc/{id}/shapes              → read current shapes
3. curl -s -X POST http://localhost:7236/api/doc/{id}/actions     → create/modify shapes
4. curl -s http://localhost:7236/api/doc/{id}/screenshot -o f.jpg → verify result visually

変更後は必ずスクリーンショットを撮って作業内容を確認してください。小さく段階的に変更することを推奨します。

重なりの確認 — 変更の各バッチ後に必ず実施

図形を作成または変更した後は、必ず次の手順を実施してください。

1. スクリーンショットを撮り、図形の重なり、矢印の交差、テキストの混み具合がないか目視で確認します
2. 重なりや読みづらさが見つかった場合は、place、move、stack、align、distribute を使って修正します
3. もう一度スクリーンショットを撮り、修正を確認します

digraph overlap_check {
    "Make changes" -> "Screenshot";
    "Screenshot" -> "Overlaps or crowding?" [label="inspect"];
    "Overlaps or crowding?" -> "Fix layout" [label="yes"];
    "Fix layout" -> "Screenshot";
    "Overlaps or crowding?" -> "Done" [label="no, clean"];
}

よくある重なりの修正方法：

• 図形が重なっている → gap: 80 を指定して stack を使うか、sideOffset: 80 を指定して place を使います
• 矢印が無関係な図形を通過している → 経路をふさいでいる図形を move で移動するか、直角に経路を描くために kind: "elbow" を使います
• テキストラベルが重なっている → 図形の幅を広げる（resize または幅の大きい w を指定した update）か、図形間の間隔を広げます
• 図が密集している → stack と align を使って行や列に分けるか、distribute で間隔を広げます

クイックリファレンス

エンドポイント

メソッド	エンドポイント	説明
GET	/api/doc	開いているドキュメントの一覧。フィルター：?name=
GET	/api/doc/:id/shapes	現在のページ上にあるすべての図形
GET	/api/doc/:id/screenshot	JPEG キャプチャ。?size=small|medium|large|full
POST	/api/doc/:id/actions	構造化アクション（以下を参照）
POST	/api/doc/:id/exec	tldraw Editor に対して任意の JS を実行

図形の種類

種類	主なプロパティ
rectangle、ellipse、triangle、diamond、hexagon、pill、cloud、star、heart、pentagon、octagon、x-box、check-box、trapezoid、parallelogram-right/left、fat-arrow-right/left/up/down	shapeId, x, y, w, h, color, fill, text, note
text	shapeId, x, y, anchor, color, fontSize, maxWidth, text
arrow	shapeId, fromId, toId, color, kind (arc|elbow), text, bend
line	shapeId, x1, y1, x2, y2, color
note	shapeId, x, y, color, text（付箋）
pen	shapeId, points:[{x,y}], color, style (smooth|straight), closed, fill

色： red、light-red、green、light-green、blue、light-blue、orange、yellow、black、violet、light-violet、grey、white
塗りつぶし： none、tint、background、solid、pattern
アンカー（テキスト）： top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right

アクション

/api/doc/:id/actions に {"actions": [...]} を POST します。1 つのリクエスト内のすべてのアクションは、1 つの取り消しステップになります。

アクション	ペイロード
create	{"_type":"create","shape":{...}}
update	{"_type":"update","shape":{"shapeId":"id","_type":"rect",...changed props}}
delete	{"_type":"delete","shapeId":"id"}
clear	{"_type":"clear"}
label	{"_type":"label","shapeId":"id","text":"new text"}
move	{"_type":"move","shapeId":"id","x":N,"y":N,"anchor":"center"}
place	{"_type":"place","shapeId":"id","referenceShapeId":"ref","side":"right","align":"center","sideOffset":20}
align	{"_type":"align","shapeIds":[...],"alignment":"center-horizontal"}
distribute	{"_type":"distribute","shapeIds":[...],"direction":"horizontal"}
stack	{"_type":"stack","shapeIds":[...],"direction":"vertical","gap":20}
resize	{"_type":"resize","shapeIds":[...],"scaleX":2,"scaleY":1.5}
rotate	{"_type":"rotate","shapeIds":[...],"degrees":45}
bringToFront	{"_type":"bringToFront","shapeIds":[...]}
sendToBack	{"_type":"sendToBack","shapeIds":[...]}
pen	{"_type":"pen","shapeId":"id","points":[{"x":0,"y":0},...],"color":"black","style":"smooth"}

配置する辺： top、bottom、left、right
整列オプション： top、center-vertical、bottom、left、center-horizontal、right

ベストプラクティス

• すべての HTTP 呼び出しには必ず curl を使用してください。 例外はありません。
• デフォルトの図形サイズ： 約 300x200、図形間の間隔は約 200
• 図形は矢印で接続してください： fromId／toId を使用すると、図形を移動しても矢印がつながったままになります。
• 座標を手動で計算するよりも、高レベルのアクション（place、stack、align）を優先してください。
• アクションを 1 つの POST にまとめてください。 取り消し／やり直しをアトミックに実行できます。
• 図形の位置関係を指定するには place を使用してください。 座標を計算する必要がありません。
• デフォルトのスタイル： 黒、中程度、描画スタイル、テキスト中央揃え、塗りつぶしなし。変更する理由がある場合を除きます。
• 塗りつぶしの推奨： 輪郭には none、色付きの背景には solid
• 変更後はスクリーンショットを撮影し、 レイアウトを確認して重なりがないかチェックしてください。
• 参照しやすい、わかりやすい shapeId を割り当ててください（例："auth-box"、"db-node"）。
• 大規模な図（図形 7 個以上）： 段階的に作成してください。まず図形をいくつか作成してスクリーンショットを撮り、レイアウトを調整してから図形を追加します。

例：フローチャートの作成

DOC_ID="your-doc-id"
BASE="http://localhost:7236/api/doc/$DOC_ID"

# Create shapes + connect with arrows in one call
curl -s -X POST "$BASE/actions" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"start","x":100,"y":100,"w":300,"h":200,"text":"Start"}},
      {"_type":"create","shape":{"_type":"diamond","shapeId":"decision","x":100,"y":400,"w":300,"h":200,"text":"Condition?"}},
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"end","x":100,"y":700,"w":300,"h":200,"text":"End"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a1","fromId":"start","toId":"decision"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a2","fromId":"decision","toId":"end","text":"Yes"}}
    ]
  }'

# MANDATORY: Screenshot to check for overlaps
curl -s "$BASE/screenshot?size=medium" -o screenshot.jpg
# Inspect the screenshot — if shapes overlap or arrows cross, fix with place/move/stack

Exec API

構造化アクションで対応していない高度な操作に使用します。

curl -s -X POST "$BASE/exec" \
  -H "Content-Type: application/json" \
  -d '{"code": "return editor.getCurrentPageShapeIds().size"}'

SDK のドキュメント全文は次の場所で確認できます：curl -s http://localhost:7236/api/llms