# Illustmaker

> Browser-based vector illustration editor. SVG/PNG/PDF export. Designed for AI agents.

## For AI Agents

This tool exposes a global JavaScript API `window.IllustMaker` (alias: `window.IM`) for programmatic control. After opening https://asi.co.jp/illustmaker/ in a browser, you can use the methods below directly via the JavaScript console or Chrome DevTools.

**Do not** simulate clicks on hidden file inputs. Use `IM.addSVG(svgString)` instead.

## Quick start

```js
// 1. Create a new 800x600 document
IM.newDocument({width:800, height:600, bg:"#ffffff"});

// 2. Add shapes / text / path
IM.addRect({x:100, y:100, w:200, h:120, fill:"#4a9eff"});
IM.addEllipse({cx:400, cy:160, rx:80, ry:60, fill:"#ef4444"});
IM.addText("Hello", {x:160, y:320, fontSize:48, fill:"#222"});
IM.addPath("M10 10 L100 50 L50 100 Z", {fill:"#22c55e"});

// 3. Load an existing SVG
IM.addSVG("<svg xmlns='http://www.w3.org/2000/svg'><circle cx='50' cy='50' r='40' fill='red'/></svg>");

// 4. Export
const svg = IM.exportSVG();   // returns string
IM.downloadSVG("mylogo.svg"); // triggers browser download
```

## API Reference

### Document
- `IM.newDocument({width, height, bg})` → `{width, height, bg}`
- `IM.getDocument()` → `{width, height, bg, zoom, tool, objectCount, selectedIds}`

### Add Objects (returns object id)
- `IM.addRect({x, y, w, h, fill, stroke, strokeWidth, rotation, name})` → id
- `IM.addEllipse({cx, cy, rx, ry, fill, stroke, strokeWidth, name})` → id
- `IM.addText(text, {x, y, fontSize, fontFamily, fontWeight, fill, stroke, letterSpacing, lineHeight})` → id
- `IM.addPath(svgPathD, {x, y, fill, stroke, strokeWidth})` → id
- `IM.addSVG(svgString, {x, y})` → [ids added]
- `IM.addIconStub(name, {x, y, size})` → [ids] — placeholder icon box with label

### Read / Modify
- `IM.listObjects()` → array of `{id, type, name, x, y, w, h, fill, stroke, strokeWidth}`
- `IM.getObject(id)` → full object (deep clone) or null
- `IM.updateObject(id, patch)` → bool — merges patch into object props
- `IM.deleteObjects(ids)` → bool — accepts single id or array
- `IM.clear()` → bool — remove all objects

### Selection
- `IM.select(ids)` → array of selected ids
- `IM.selectAll()` → array of all ids
- `IM.deselectAll()` → true
- `IM.centerObject(id)` → bool — center on canvas

### Tools
- `IM.setTool(name)` → current tool name
  - Tools: `select`, `direct`, `pen`, `pencil`, `rect`, `ellipse`, `poly`, `star`, `line`, `text`, `brush`, `eraser`, `eyedropper`, `gradient`, `pan`

### Export
- `IM.exportSVG()` → SVG string
- `IM.downloadSVG(filename)` → bool — triggers download

### Introspection
- `IM.version` → "1.0.X"
- `IM.help` → URL to this doc
- `IM.api()` → list of all method names
- `IM_STATE` → raw internal state (read-only intent; `objects`, `selected`, `tool`, `docW`, `docH`)

## URL Parameters

- `?s=<share_id>` — load MCP session (auto-fetches state from /api/mcp.php and renders)

Note: URL action deep links (`?action=loadSVG&svg=...` etc.) were removed in v1.0.21 for security reasons.

## MCP HTTP API (server-side, for AI tools / cron / external systems)

**Endpoint:** `POST https://asi.co.jp/illustmaker/api/mcp.php`
**Content-Type:** `application/json`
**Body:** `{ "method": "<method>", "params": {...}, "session": "<id>" }`

### Methods (30+)

#### Core
1. **`illust.health`** — version check.
2. **`illust.create_session`** `{width?, height?, bg?}` → `{session, open_url}`
3. **`illust.set_document`** `{width?, height?, bg?}`
4. **`illust.open_url`** → `{url}`

#### Object CRUD
5. **`illust.add_object`** `{type, x, y, w, h, fill, ...type-specific}`
6. **`illust.add_svg`** `{svg: "<svg>...</svg>"}`
7. **`illust.add_image`** `{href|url, x, y, w, h}` (URL fetch→data URI変換)
8. **`illust.list_objects`** → array of metadata
9. **`illust.get_object`** `{id}` → full object
10. **`illust.update_object`** `{id, patch: {...}}`
11. **`illust.delete_objects`** `{ids}`
12. **`illust.clear_objects`** — 全削除
13. **`illust.duplicate_objects`** `{ids, dx?, dy?}` → `{new_ids}`
14. **`illust.group_objects`** `{ids, name?}` → `{group_id}`
15. **`illust.align_objects`** `{ids, kind: "left|right|center-h|top|bottom|center-v|dist-h|dist-v"}`
16. **`illust.set_layer_order`** `{ids, action: "front|back|forward|backward"}`

#### Session management
17. **`illust.list_sessions`** → `{count, sessions:[{session,docW,docH,objectCount,updated_at}]}`
18. **`illust.session_info`** → metadata
19. **`illust.clone_session`** → `{session: new_id}`
20. **`illust.delete_session`** → `{deleted}`
21. **`illust.copy_to_session`** `{target, ids}` → `{copied, new_ids}`

#### Save / Load projects
22. **`illust.save_project`** → `{project_base64, filename}` (full state JSON)
23. **`illust.load_project`** `{project_base64 | project_json}` (replaces state)

#### Single-shot exports
24. **`illust.export_svg`** → `{svg}`
25. **`illust.export_png`** `{dpi?}` → `{png_base64}`
26. **`illust.export_jpeg`** `{dpi?, quality?}` → `{jpeg_base64}`
27. **`illust.export_pdf`** → `{pdf_base64}` (真のベクター TCPDF)
28. **`illust.export_optimized_svg`** → `{svg, original_size, optimized_size}`

#### Batch (5 modes)
29. **`illust.batch_render`** Variable Data Printing. `output` で5モード選択:
    - `output:"svg"` (default) → `results:[{vars, svg}, ...]`
    - `output:"svg-zip"` → `zip_base64`, `filename` (1ファイル一括)
    - `output:"png"` → `results:[{vars, png_base64, filename}]` (`dpi` 72-600 指定可)
    - `output:"png-zip"` → ZIP base64
    - `output:"pdf-imposition"` → A4面付けPDF base64
      - `imposition:{paper:"A4"|"A3"|"letter", cols, rows, margin_mm, gap_mm}`
    - 共通: `filename_template:"{{name}}"` でZIP内ファイル名を変数生成 (e.g. `濃口醤油.svg`)
    - クライアント側: `IM.batchRender(sid, data, opts)` + `IM.batchSave(resp)` で自動ダウンロード

#### Text helpers
30. **`illust.measure_text`** `{text, fontSize, fontFamily?, letterSpacing?}` → `{width, height, baseline}`
31. **`illust.replace_text`** `{find, replace}` → `{replaced}` (全テキスト一括置換)
32. **`illust.set_text_style`** `{ids?, style: {fontSize, fontFamily, fill, ...}}` → `{applied}`
33. **`illust.text_to_path`** `{ids?}` → `{converted}` (簡易: raw SVG <text> として凍結)
34. **`illust.list_fonts`** → 利用可能フォント名一覧
35. **`illust.set_font`** `{name}` → Google Fontsロード指示 (クライアント側で実ロード)

#### Color / palette
36. **`illust.extract_palette`** → `{palette:[{color, count}]}` (既存オブジェクトから抽出)
37. **`illust.suggest_palette`** `{theme: "warm|cool|pastel|mono|vivid|和|夏|秋|冬|春|natural|tech"}` → 5色配色
38. **`illust.suggest_font`** `{purpose: "logo|heading|body|japanese-logo|casual|serious|tech"}` → 推奨フォント

#### External
39. **`illust.import_from_url`** `{url, x?, y?, w?, h?}` → URL からSVG/画像取得して配置

#### Mask / Symbol / Pathfinder / Blend (Phase 1)
40. **`illust.clip_mask`** `{session, mask_id, content_ids}` → マスクオブジェクトの形でコンテンツをクリップ。マスクは削除される。rect/ellipse/path/star全て対応
41. **`illust.release_clip`** `{session, ids}` → クリップ解除
42. **`illust.opacity_mask`** `{session, mask_id, content_ids}` → 不透明マスク。グラデーション透明度OK
43. **`illust.release_opacity_mask`** `{session, ids}` → 解除
44. **`illust.text_on_path`** `{session, text_id, path_id, offset?}` → テキストをパスに沿わせる
45. **`illust.release_text_on_path`** `{session, text_id}` → パス連動解除
46. **`illust.save_symbol`** `{session, ids, name}` → シンボル登録（マスター/インスタンス）
47. **`illust.list_symbols`** `{session}` → シンボル一覧
48. **`illust.create_symbol_instance`** `{session, symbol_id, x, y}` → インスタンス配置
49. **`illust.blend`** `{session, id_a, id_b, steps}` → 2オブジェクト間のN段階補間（Illustratorのブレンド機能相当）。色も補間
50. **`illust.pathfinder`** `{session, ids, op: union|intersect|subtract|exclude}` → ブーリアン演算

#### Print Production (Phase 2)
51. **`illust.export_print_pdf`** `{session, bleed_mm?, trim_marks?, registration_marks?, color_space?}` → 印刷入稿対応PDF。トンボ・塗り足し・センターマーク自動付与
52. **`illust.preflight_check`** `{session, bleed_mm?}` → プリフライト診断。塗り足し漏れ・テキスト未アウトライン・RGB→CMYK警告等を構造化レポート

#### Live Trace (Phase 6)
65. **`illust.live_trace`** `{session, image_id, threshold?, turd_size?, opt_tolerance?, fill?, replace_image?}` → ラスター画像オブジェクトを potrace でベクター化。元画像は置換 or 残留選択可

#### Gradient Mesh (Phase 1-F)
75. **`illust.add_mesh_gradient`** `{session, x, y, w, h, cols?, rows?, detail?, corners?, colors?}` → バイリニア補間による滑らかな2D色グラデーションを生成。4隅色 or N×Mグリッドの全色を指定可能。`detail` (8-60) で滑らかさ調整

#### Brand Kits（ブランドアセット保存）
76. **`illust.brand_save`** `{name, palette[], fonts[], assets[], kit_id?}` → ブランドキット保存（owner_fp ベース）
77. **`illust.brand_list`** → 自分のブランドキット一覧
78. **`illust.brand_delete`** `{kit_id}` → 削除

#### Live Share（ライブ共有）
79. **`illust.share_create`** `{session, mode: view|comment, label?}` → 共有リンク発行（30日有効）。`mode='comment'`なら閲覧者コメント可。返り値 `{token, url}`
80. **`illust.share_list`** → 自分が発行した共有リンク一覧
81. **`illust.share_delete`** `{token}` → 共有リンク無効化
82. **`illust.share_view`** `{token}` → 公開エンドポイント。token から現状SVGを返す（ライブ閲覧ページが3秒polling）

#### Live Share Comments（閲覧者コメント — mode='comment' 限定）
83. **`illust.share_comment_post`** `{token, body, author_name?, x?, y?}` → 閲覧者が座標付きコメントを投稿。20件/時のレート制限
84. **`illust.share_comment_list`** `{token, include_resolved?}` → コメント一覧（公開・認証不要）
85. **`illust.share_comment_resolve`** `{comment_id, resolved}` → オーナーのみ。解決マーク切替
86. **`illust.share_comment_delete`** `{comment_id}` → オーナーのみ。ソフト削除

#### Live Collaborative Editing（リアルタイム共同編集 — mode='edit' 限定）v5.0
複数人が `/illustmaker/live/{token}` から同時に図形描画・移動・削除できる。HTTP long-polling + LWW（Last-Write-Wins）。
87. **`illust.collab_join`** `{token, actor_name?, actor_color?, actor_id?}` → 共同編集に参加。`actor_id` 払い出し + 初期状態 + `last_seq` を返す
88. **`illust.collab_leave`** `{token, actor_id}` → 離脱
89. **`illust.collab_op_submit`** `{token, actor_id, op_type, payload}` → 操作投稿。`op_type` = `add_object` / `update_object` / `delete_objects` / `set_document` / `reorder_objects` / `cursor` / `selection` / `lock_object` / `unlock_object`
90. **`illust.collab_poll`** `{token, actor_id, since}` → long-poll（最大25秒）。`since` 以降の op 配列、参加者、ロック一覧を返却
91. **`illust.collab_status`** `{token}` → 軽量ステータス（参加者数・op 数・最終 seq）

#### Library (Phase 7)
53. **`illust.library_search`** `{q?, category?, limit?}` → 部品ライブラリ検索（icon/frame/decoration等）
54. **`illust.library_use`** `{session, slug, x, y, w?, h?}` → 部品をセッションに配置
55. **`illust.template_list`** `{category?, limit?}` → テンプレート一覧（名刺/チラシ/ロゴ/バナー等）
56. **`illust.template_render`** `{slug, vars}` → テンプレから新セッション。{{var}} 変数自動置換

#### BYOK AI Integration (Phase 4)
57. **`illust.generate_image`** `{session, prompt, api_key, provider: openai|recraft, model?, size?, x, y, w, h}` → 画像生成AIで画像挿入。**ユーザーのAPIキー必須**（BYOK）。サーバー側はキーを保管しない
58. **`illust.critique`** `{session, api_key, provider: anthropic|openai, model?, criteria?}` → AIビジョンで作品を批評。score/issues/suggested_fixes 構造化返却

#### Logo Factory (Phase 5)
66. **`illust.logo_variations`** `{session, variations:["mono","inverse","gray","orange","blue","red","green","gold"], create_sessions?}` → カラーバリエーション一括生成。各バリアントごとに新セッション作成可
67. **`illust.logo_export_kit`** `{session, sizes?}` → ロゴをマルチサイズ出力。favicon-16/32 / apple-touch / pwa-192/512 / twitter-card 1200×630 / instagram 1080 / master SVG / master-print SVG をZIP一括

#### Session Versioning + Comments (Phase 8)
68. **`illust.session_snapshot`** `{session, label?}` → 現セッションをバージョン保存（最大30）
69. **`illust.session_versions`** `{session}` → バージョン一覧
70. **`illust.session_restore`** `{session, version_id, autosave?}` → バージョン復元（復元前に現状を自動スナップ保持）
71. **`illust.session_comment`** `{session, action: add|list|resolve|delete, body, author, x?, y?, object_id?}` → セッション上のコメント・アノテーション

#### Macros (Phase 8.5)
72. **`illust.macro_save`** `{session, name, steps:[{method, params}]}` → MCP呼出シーケンスをマクロ保存。**ホワイトリスト方式**で安全なメソッドのみ許可（BYOK系・network系は不可）
73. **`illust.macro_list`** `{session}` → マクロ一覧
74. **`illust.macro_run`** `{session, macro_id, vars?}` → マクロ実行。<code>{{var}}</code> 置換対応

#### Gallery (community)
59. **`gallery.submit`** `{session, title, description?, category?, tags?, author_name?, parent_id?}` → セッションを公開ギャラリーに投稿。サーバー側で自動的にSVG/PNG/projectJSONを生成。返り値: `{id, slug, url, png_url}`
60. **`gallery.list`** `{sort?, category?, tag?, q?, limit?}` → 公開作品一覧。`sort:"new"|"popular"`、`category:"icon|logo|illustration|character|ui|pattern|other"`
61. **`gallery.get`** `{slug}` → 作品詳細（タイトル/作者/タグ/PNG/SVG/projectURL等）
62. **`gallery.remix`** `{slug}` → 親作品を読み込んだ新セッションを作成して `{session, open_url, object_count, parent_id}` 返却。そのまま `illust.update_object` 等で改造可能
63. **`gallery.list_comments`** `{slug}` → コメント一覧（parent_id で1階層スレッド構造）
64. **`gallery.comment`** `{slug, body, author_name?, parent_id?}` → コメント投稿。`parent_id` で返信

### Example: Create logo

```bash
# 1. Create session
curl -X POST https://asi.co.jp/illustmaker/api/mcp.php \
  -H 'Content-Type: application/json' \
  -d '{"method":"illust.create_session","params":{"width":800,"height":600}}'
# → {"session":"abc123def456", "open_url":"https://asi.co.jp/illustmaker/?s=abc123def456"}

# 2. Add objects
curl -X POST https://asi.co.jp/illustmaker/api/mcp.php \
  -H 'Content-Type: application/json' \
  -d '{"method":"illust.add_object","session":"abc123def456",
       "params":{"type":"ellipse","x":200,"y":200,"w":400,"h":200,"fill":"#4a9eff"}}'

# 3. Open in browser → user sees the logo on canvas, can edit further
```

### Example: Batch render food labels

```bash
# 1. Create template session with {{name}} {{net}} {{expiry}} variables
curl -X POST .../api/mcp.php \
  -d '{"method":"illust.add_object","session":"sid",
       "params":{"type":"text","text":"商品名: {{name}}","x":50,"y":50}}'

# 2. Batch render 100 labels
curl -X POST .../api/mcp.php \
  -d '{"method":"illust.batch_render","session":"sid",
       "params":{"data":[
         {"name":"濃口醤油","net":"500ml","expiry":"2026-12"},
         {"name":"薄口醤油","net":"500ml","expiry":"2026-12"}
       ]}}'
# → {"count":2, "results":[{"vars":{...},"svg":"<svg>...</svg>"}, ...]}
```

### Limits

- Max body: 1MB per request
- Max objects per session: 5000
- Max session size: 5MB
- Max batch_render rows: 1000
- Rate limit: 100 req/min per IP

## Object Schema (Internal)

Objects are plain objects in `S.objects` (alias: `IM_STATE.objects`). Common fields:

```js
{
  id: "o1",              // unique
  type: "rect"|"ellipse"|"text"|"path"|"line"|"poly"|"star"|"raw"|"image"|"folder",
  name: "label",         // user-facing layer name
  x: 0, y: 0, w: 100, h: 100,
  rotation: 0,           // degrees
  fill: "#000" | "none" | {stops:[{offset:0,color:"..."},...]},  // gradient object
  stroke: "#000" | "none",
  strokeWidth: 0,
  visible: true,
  locked: false,

  // type-specific:
  // text:    text, fontSize, fontFamily, fontWeight, letterSpacing, lineHeight
  // path:    nodes:[{x,y,hIn,hOut,corner}], closed
  // image:   src (data URL)
  // raw:     rawSvg (SVG fragment)
}
```

## Tips for AI Agents

1. **Always check `IM` exists first**: `if(typeof IM!=='undefined')`. Otherwise you're not on the Illustmaker page.
2. **For complex drawings**, build many `addPath` / `addRect` calls — the editor handles the SVG composition.
3. **To draw a character/icon from scratch**, break it down: body parts → individual shapes → `addEllipse` + `addPath`.
4. **Don't simulate clicks on file inputs** — use `IM.addSVG()` directly with the SVG string.
5. **Use `IM.api()` to list available methods** if unsure.
6. **For drawing complete characters** (e.g., "draw Doraemon"): start with a head ellipse, eyes (2 ellipses), nose (ellipse), mouth (path), body (path), etc. Use `IM.newDocument()` first, then incremental adds.

## Keyboard Shortcuts (for manual use)

- `V` select, `P` pen, `R` rect, `O` ellipse, `T` text, `N` pencil
- `Cmd+Z` undo, `Cmd+S` SVG export, `Cmd+N` new doc
- `Cmd+G` group, `Shift+Cmd+G` ungroup
- `?` show full shortcut list

## Contact

Bug reports / feature requests: feedback form in the app (bottom-right).
Project home: https://asi.co.jp/illustmaker/