sandbox_draft

画面を作る前にラフを描きます。JSON を送るとサーバーが手描き風のスマホのラフ（最大 3 枚、1 枚にスマホ最大 4 台）を描き、ツールの結果に返すとともに、人のアプリの設計のページにも表示します。人はそこで丸で囲み、話し、文字を書き込んで報告します。ボックスは要りません。

ツールのタイトル（MCP の title。クライアントによってはこれでツールを表示します）は Sketch screens です。注釈は readOnlyHint: false（成功するたびに 1 版保存する）、destructiveHint: false、openWorldHint: false です。

いつ使うか

新しく作るもの・変えるものの作業順は、sandbox_draft（画面）→ sandbox_architecture（サービス）→ sandbox_schema（保存するデータ）→ ボックスで作る → sandbox_review です。作業が触れない段階だけを飛ばします。画面のない変更にはラフはありません。

人がラフ、スケッチ、ワイヤーフレーム、モックアップ（草稿、ラフ）を求めたときは sandbox_draft を使います。新しい画面を作る前、画面を変える前にも使い、人がまずスマホでレイアウトと流れを判断できるようにします。代わりに HTML、SVG、画像ファイルを書いたり、見た目を見せるためにボックスで画面を先に作ったりしないでください。このツールが描き、すべての版を残し、人が答えるための道具も用意します。

既存の画面を変えるときは、描く前に今の画面を見てください（動いているアプリを sandbox_shot で撮る、またはコードを読む）。

ボックス

設計にボックスは要りません。設計は人のアカウントと、それを描いた会話に属します。sandbox_start をしなくても描き、直し、人の報告を受け取れます。ボックスが停止しても、その画像が削除されても、設計は残ります。

id は任意です。この作業のボックスを渡すと、そのボックスのページのラフ、構成図、スキーマのタブにも設計が表示されます。渡さなければ設計は単独で、アプリのその設計のページ（appUrl）と「設計」一覧に表示されます。設計は最後に一緒に渡されたボックスに表示されます。あとの版を id なしで描いてもそのボックスに残り、別のボックスの id を付けて描くとそちらに移ります。このアカウントのボックスではない id を渡すと、呼び出しは失敗します。

描画はボックスではなくサーバーで行います。呼び出しは凍結したボックスを起こさず、ボックスの中で何も実行しません。停止していないボックスを id に渡して成功すると、そのボックスの使用に数えられます。lastUsedAt が更新されてアイドルによる凍結と停止の時刻が後ろにずれ、呼び出した会話がボックスを持つ会話になり（ボックスの状態）、その版はボックスの steps[] に 1 ステップとして残ります。失敗した呼び出しと、id のない呼び出しは、どのボックスも使いません。

何を描くか

人が判断に必要なものだけを描きます。どの画像にも右上に同じ凡例があり、赤は新しいもの・変わるもの、黒と灰色はそのまま残るものです（凡例の文字はアカウントの言語に従います。画像に入る決まった文字を参照）。

• new: true は、今の製品と比べて新しいもの・違うものに付け、赤で描かれます。比べる相手は今の製品で、前の版ではありません。2 版目以降も、今の製品と比べてまだ新しいものには new: true を付けたままにし、前の版から変えたことは note に書きます。
• それ以外には new を付けず、黒と灰色で描かれます。
• 重要でない文字は scribble（灰色の落書き）で置き換え、大事な言葉だけ書きます。
• 画面がそのまま残るスマホには unchanged: true を付けます。渡した部品を描いたうえで、残りを落書きで埋め、「変更なし」のスタンプを押します（スタンプの文字はアカウントの言語に従います）。
• 文字はすべて、人が読む言語で書きます。

フォントにない文字（絵文字など）は四角で描かれ、warnings に挙がります。置き換えて描き直してください。よく使う記号はフォントにあるものへ自動で置き換わります（✓ は √、✕ は ×、➜ は →、⭐ は ★、≈ は ～、≤ は ≦、≥ は ≧、☐ は □、☑ は ■）。

画像に入る決まった文字

ラフと sandbox_architecture の構成図では、画像のいくつかの文字を、あなたが渡したものではなく描画が自分で書きます。これらはアカウントの言語で描かれます（人がアプリのアカウントページで選んだ言語：繁体字中国語、英語、日本語。まだ選んでいなければ繁体字中国語）。あなたが書く文字（title、text、note、notes など）は渡したとおりに描かれ、翻訳されないので、人が読む言語で書いてください。warnings とエラーメッセージは常に英語です。sandbox_schema は画像ではなくテキストで、そのわずかな決まった文字は常に英語です。

boards

board 1 枚が画像 1 枚です。タイトルの前に丸数字が付き、スマホは左から右に並び、その下にメモが書かれます。

スマホごと（すべて任意）：

画面の高さは固定です。入りきらない中身は最後に入る部品のあとで切られ、スマホの下端に入りきらなかった数が書かれ、warnings でも知らされます。別のスマホに移してください。長い文字は折り返し、英語は単語の切れ目で折り返します。title の中に 1 行に入らないほど長い単語があると、タイトル全体の文字をまず小さくし、それでも入らなければ単語の途中で分けます。ボタン、セグメント、タブ、ドロップダウンのような 1 行の部品は、まず文字を小さくし、それでも入らなければ「…」で切ります。

部品：どれも type（必須）と任意の new を持ちます。カードの new は中のものすべてに及びます。インデックス（primary、selected）は 0 から数えます。

その部品が持たないフィールド、綴りを間違えたフィールド、知らない type はすべてエラーになり、使えるフィールドが挙がります。黙って無視されることはありません。上限は文字数で数えます（漢字やかなは 1 文字で 1）。任意の文字列に空文字を渡すと、渡さなかったのと同じです。タブ、制御文字、ゼロ幅文字は取り除かれ、\n が残るのは sub と para の text、そして note だけです。呼び出しのうち id、topic、note 以外が描画の仕様で、JSON で最大 64 KB です。

例

{
  "topic": "ログイン画面",
  "boards": [
    {
      "title": "メールでログイン",
      "phones": [
        {
          "items": [
            { "type": "title", "text": "ログイン" },
            { "type": "input", "label": "メール", "text": "you@example.com", "new": true },
            { "type": "buttons", "items": ["ログイン"], "primary": 0 }
          ],
          "notes": [ { "text": "メール欄を追加", "new": true } ]
        }
      ]
    }
  ]
}

返り値

• 画像は JSON のあとに image content として、board 1 枚につき 1 枚続きます。人に話す前に見てください。そのうえで、どこを見てほしいかを 1 行で伝えます。next も同じことを言います。
• designId（dsg_ で始まる）はその設計で、アカウント内の同じ種類と topic のすべての版が同じ値を持ちます。reviewId（dsn_ で始まる）はこの版の ID です。stdio アダプター parallelsandbox-mcp は reviewId を sandbox_review のラウンドと同じように登録するので、この版への人の報告はこの会話に戻ってきます（自動で戻るための条件）。結果の最後には、報告が自動でこの会話に戻るかどうかを書いたテキストが付きます。
• version はアカウント、種類、topic ごとに数えます。どのボックスを渡したか、渡したかどうかには関係しません。新しい topic は 1、その後 2、3…。
• appUrl は人の ParallelSandbox アプリでのその設計のページ、https://app.parallelsandbox.com/design/<designId> です。サインインなしで開けるので誰にでも渡せます。丸で囲んでフィードバックを送れるのはその人のアカウントだけです。imageUrls は同じ画像のダウンロード URL で、1 時間有効です。
• boxId は id に渡したボックスです。渡さなかったときはありません。
• warnings：描けたものの、直すところがあります。スマホの中身が切れた、フォントにない文字がある、など。

人のアプリでは

どの設計にも、アプリにその設計のページ（appUrl、/design/<designId>）があり、すべての版が見られます。リンクを知っていればサインインなしで誰でも見られます。別のアカウントやサインインしていない人には版だけが見え、フィードバックも、表示されているボックスもありません。ボックス一覧の上には「サンドボックス／設計」の切り替えがあり、「設計」には、アカウントの各設計の最新版が新しい順に並びます。ボックスに表示されているかどうか、そのボックスがどの状態か（停止を含む）には関係しません。「設計」から開くと、その設計のページが開きます。

ボックスの id を付けて渡した設計は、そのボックスのページにも表示されます。どのボックスのページにも、上部に作業順で同じ 4 つのタブが並びます。ラフ、構成図、スキーマ、サンドボックスです。そのボックスにまだない種類もタブは残り、開くとアプリの言語で、まだないことと、どのツールで作ると表示されるかが出ます（「ラフはまだありません。AI が sandbox_draft で描くとここに表示されます。」「構成図はまだありません。AI が sandbox_architecture で描くとここに表示されます。」「スキーマはまだありません。AI が sandbox_schema で書くとここに表示されます。」）。「サンドボックス」から開くと「サンドボックス」の単位が表示されます。

設計のページ、またはボックスの単位で（同じ種類が複数あればどれかを選んだうえで）、人は版を選び（既定は最新）、その版の変更点を読み、各画像の下の「ここを報告」から報告します。画像に丸を描き、話し、文字を書き込んで送ります。ラフの画像を押すと、スマホを 1 台ずつ（その下のメモも一緒に）表示します。押した画像の最初のスマホから始まり、スマホでも拡大せずに読める大きさで、長ければ上下にスクロールします。画面の右半分を押すと次のスマホ、左半分で前のスマホ。1 枚目の画像のスマホを左から右へ見たら 2 枚目の画像に続き、最初と最後で止まります（パソコンでは左右キーでも切り替わり、Esc で閉じます）。1 台ずつ見られるようになる前に描いたラフの版は、画像全体が大きく開きます。構成図の画像は全体が大きく開き、2 本指で拡大縮小できます。スキーマは画像ではなくテキストです（sandbox_schema）。

ボックスのカードには作業の段階が出ます。そのボックスに最後に表示された設計の種類、そのあとに sandbox_review を呼んでいれば確認です。

人の報告

人がある版に報告を（設計のページからでも、ボックスの単位からでも）送ると、その版を描いた会話に、確認のフィードバックと同じように戻ってきます。ボックスがあってもなくても同じです。

• アプリのフィードバックを受け取るよう設定した会話（parallelsandbox-agent で始めた会話、または ParallelSandbox のフィードバック用 hook を入れたクライアント。sandbox_review を参照。設計の版には追加の条件があります。下を参照）では、報告がこの会話を起こします。メッセージは例えば The person sent feedback in the ParallelSandbox app on design version <reviewId>. Call the parallelsandbox sandbox_report tool with exactly {"reportId":"<reportId>"} to read it, change what they asked, then call the same design tool again with the same topic for the next version. です。sandbox_report に reportId だけを渡して（id なしで）読みます。
• それ以外では、この会話が次に設計ツールを呼んだとき（このツールも含み、id の有無は問いません）、またはボックスに対してツールを呼んだときの結果に fromHuman として届きます。人はアプリの受領欄の AI へのメッセージをコピー をここに貼ることもでき、そのメッセージは sandbox_report で報告を読むよう求めます（設計なら { "reportId": "<reportId>" } だけで足ります。ボックスの id を一緒に渡しても問題ありません）。

メッセージにはどの設計の何版かが書かれます：Feedback on draft "ログイン画面" v1: <人が書いたこと>. Read the attached report (annotated images, voice transcript, text written on the image in notes[].labels). Change it as asked, then call sandbox_draft again with the same topic for the next version. 人が何も書かなかったときは、<人が書いたこと> は N annotated notes and M recordings になります。何かを変える前に、囲まれた画像、音声の文字起こし、画像に書き込まれた文字（notes[].labels）を読んでください。報告の reviewId は、人が見た版の reviewId（dsn_ で始まる）です。設計への報告は、待っている sandbox_review のカードを終わらせません。

自動で戻るための条件

• stdio アダプター parallelsandbox-mcp が、id なしで描いた設計には 0.6.0 以降、ボックスの id を付けて描いた設計には 0.5.4 以降必要です。parallelsandbox-agent も同じパッケージに入っており、それで始めた会話も同じ版が必要です。0.6.0 より前の版は設計の版をボックスと一緒にしか登録せず、0.5.4 より前の版は sandbox_review だけを登録するので、その場合、設計への報告は上の 2 つ目の方法（fromHuman、または AI へのメッセージをコピー）でしか戻りません。アダプターを使わず HTTP エンドポイントにつないだ場合も同じです。
• Claude Code と Gemini CLI では、さらに ParallelSandbox のフィードバック用 hook が設計ツールを対象にしている必要があります。0.5.4 より前に入れた hook は sandbox_review（Claude Code では sandbox_review と sandbox_report）にしか反応せず、設計への報告を受け取れません。0.5.4 はこの古い hook を未インストールとして扱い、server instructions と設計ツールの結果にインストールコマンドを付けます。例：npx -y parallelsandbox-mcp install claude-code（Gemini CLI は install gemini。結果に書かれたコマンドをそのまま実行します）。人のユーザー設定を変えるには本人の同意が要ります。この会話で尋ね、同意を得たら 1 回実行します。ParallelSandbox 自身の hook だけを置き換え、ほかの設定と元のファイルのバックアップは残り、何度実行しても安全です。Claude Code はすぐに、Gemini CLI は次の起動から反映されます。Cursor の hook は入れ直す必要がなく（同じパッケージを実行するので、0.5.4 以降なら足ります）、Codex は hook が要りません。
• hook を入れたあとに描いた版だけが、報告で自動的にこの会話を起こします。入れる前に描いた版は自動では戻りません。アダプター 0.5.5 からは結果に付くインストールの案内もそう書きます。0.5.4 の案内にある「reviewId で sandbox_review を呼ぶ」手順は確認カード用で、設計の dsn_ の ID には使わないでください。その版の報告は、人にアプリの AI へのメッセージをコピー をここに貼ってもらい、sandbox_report で読みます。

次の版

承認や確定の手順はありません。人の言うとおりに直し、同じ topic（id を渡していたなら同じ id も。ボックスは必須ではありません）でもう一度 sandbox_draft を呼びます。仕様は変えたところだけでなく全体を渡し、note を付けます。前の版から変えたことを 1 文で書くと、タイトルの下に赤で描かれ（前に「今回の変更：」が付き、アカウントの言語に従います）、アプリで人が最初に読むものになります。その呼び出しが次の版（v2、v3…）で、どのボックスからでも、ボックスなしでもかまいません。新しい topic は v1 から始まります。

エラー

呼び出しは、どのフィールドかを示すメッセージで失敗します。何も保存されず、どのボックスの使用にも数えられません。

• box not found (it must be one of yours; see sandbox_status or GET /v1/boxes)：渡した id がこのアカウントのボックスではありません。ボックスなしで描くなら id を外してください。
• topic is required: …、topic is at most 80 characters、note is at most 300 characters、spec is at most 64 KB。
• 描画が受け付けないものは <パス>: <問題> で返ります。パスは呼び出しの引数そのものです。例：boards[0].phones[0].items[0]: unknown field "lable" (allowed: type, new, text, right, tag, bold)、boards[0].phones[0].tab: "C" is not one of tabs ["A", "B"]、boards[0].phones[0].items[2].primary: is 2 but there are only 1 items (0 = first)。id、topic、note 以外の引数はすべて描画に渡る（描画はそれらをまとめて spec と呼びます）ので、余分な引数や綴りの違う最上位の引数も失敗します：spec: unknown field "board" (allowed: boards)。そのフィールドを直して呼び直してください。
• another version of "<topic>" was saved at the same time; call again。

すべてのツールとトピックはツールリファレンスに並んでいます。