visual-edit

ビジュアル編集

ユーザーがスタンドアロンの Alpine HTML を生成するのではなく、実際のローカルアプリを視覚的に確認または編集したい場合は、/visual-edit を使用します。信頼できる情報源は、実行中の localhost アプリとそのルート URL です。Design では、それらのルートを無限キャンバス上に iframe で表示します。

エディターは https://design.agent-native.com でホストされています。ローカルで Design を起動しないでください。ローカルで起動するのは対象アプリとブリッジだけです。

オンボーディングフローの実例については、ビジュアル編集ガイドを参照してください。

ローカルでの迅速な起動

• このスキルを対象アプリにインストールしたり、ローカルの Design サーバーを起動したりしないでください。このスキルはコーディングホストに属します。Design は常に上記のホスト型アプリを使用します。
• Agent-Native フレームワークのアプリを自分で起動する必要がある場合は、通常の開発コマンドに AUTH_DISABLED=1 を指定します。これはローカル専用で、ユーザーログインなしでビジュアルエディターにフレームワークの開発用 ID を提供します。
• エージェントが所有するローカルサーバーで、要求した画面が /sign-in にリダイレクトされる場合は、そのサーバーを AUTH_DISABLED=1 を指定して再起動し、Design を開く前にもう一度ルートを確認します。要求された画面としてサインインページを表示しないでください。
• open-visual-edit を呼び出す前に、対象 URL が応答することを確認します。停止している場合は、エージェントが所有する開発サーバーを通常のコマンドで起動し、要求したルートが応答するまで待ってから Design を開きます。キャンバスに応答しない localhost URL を残さないでください。
• 自分が起動していないサーバーはそのまま維持します。既存の認証済みブラウザーセッションを使用するか、Design ではなく対象アプリでログインが必要であることを説明します。
• ユーザーがパスを明示した場合は、ルートの一覧表示を省略し、そのパスを直接配置します。パスが指定されていない場合にのみ、ルートを検出します。

インストール

npx @agent-native/core@latest skills add visual-edit は、スキルとホスト型 Design MCP コネクターをインストールします。npx skills@latest add BuilderIO/agent-native --skill visual-edit は手順のみをインストールします。ページに対応した WebMCP ホストでは、コネクターのインストールは不要です。

チャットの横に Design を配置

チャットの横に Design を表示できるため、open-visual-edit の MCP App を優先してください。プロンプトをコピーを使ってビジュアル編集をコーディングエージェントに渡します。ホストから会話の確認を求められる場合があります。それ以外の場合は、openUrl を認証情報不要の読み取り専用の代替手段として使用します。編集可能であると説明しないでください。

• インラインブラウザー対応のホストでは、https://design.agent-native.com/visual-edit を開き、その open-visual-edit WebMCP ツールを呼び出します。サインインの有無にかかわらず動作します。一度限りの機能トークンは Design アカウントのセッションではありません。ページ対応のブラウザーコントローラーがあれば十分です。そのため、Claude-in-Chrome、Claude Code のブラウザーツール、ChatGPT の Chrome／ブラウザー拡張機能、Puppeteer または Playwright MCP、CDP など、JavaScript 対応の同様のコントローラーでは、ホスト型 MCP コネクターは不要です。
• VS Code では、Design の WebView／ディープリンクを使用します。ページ WebMCP がない場合は、ホスト型 Design MCP コネクターと通常の OAuth／デバイス認証を使用します。どちらの場合も、ローカルの Design サーバーに置き換えないでください。

Design 内で、Cmd K メニューから UI の表示／非表示を選ぶか、Shift \ ショートカットを押すと、編集用 UI をすべて切り替え、キャンバスだけを表示できます。

Browser WebMCP（コネクターなしのデフォルト）

Design MCP に接続していない場合は、メインワールドの JavaScript 評価機能を備えた表示中のブラウザータブを使用してください。ホストのインラインブラウザーを優先し、外部 Chrome は要求された場合、またはインラインブラウザーが利用できない場合にのみ使用してください。 https://design.agent-native.com/visual-edit を開き、ツールが登録されるまで表示したままにして、作業前にタイトルを読み取ってください。パスワード、Cookie、トークン、コードを入力、コピー、要求してはいけません。サインアウト状態でもループバックの visual-edit は動作します。サインインを必須とするその他のページでツールを使うには、サインイン済みのタブが必要です。 ブラウザーが CDP の権限設定に対応している場合は、ページツールを呼び出す前に https://design.agent-native.com に local-network-access を許可してください。対応していない場合は、ページの Connect ボタンを使用し、ブラウザーの権限プロンプトが完了するまで待ってください。

ホストがネイティブのブラウザーセッション WebMCP ブリッジを提供している場合は、それを使用してください。list-browser-session-webmcp-tools で一度だけ一覧を取得し、run-browser-session-webmcp-tool で実行するか、list-host-webmcp-tools と run-host-webmcp-tool の組み合わせを使用してください。検出した名前、オリジン、引数は正確に保持してください。それ以外の場合は、ページワールド API を使用してください。Agent-Native のページでは、次のヘルパーを使用できます。

次の例はサインイン済み、または既存のブリッジがある場合を想定しています。新規のサインアウト状態のループバックでは、以下で説明するローカルに保持された bridgeToken を追加する必要があります。

const an = window.__agentNativeWebMcp;
const status = await an.ready({ waitMs: 20_000 });
if (status.state !== "ready") throw new Error(status.error ?? status.state);
const tools = await an.tools("visual-edit");
if (!tools.some((tool) => tool.name === "open-visual-edit")) {
  throw new Error("open-visual-edit is not registered yet");
}
const result = await an.call("open-visual-edit", {
  devServerUrl: "http://localhost:5173",
  paths: ["/"],
  navigate: true,
}, { waitMs: 2_000 });
if (result.state === "pending") {
  // On the next evaluation, read the still-running call without replaying it.
  an.result(result.id);
}

ヘルパーがない場合は、標準の WebMCP を直接使用してください。document.modelContext が標準であり、navigator.modelContext は非推奨です。

const ctx = document.modelContext;
const tool = (await ctx.getTools()).find((candidate) => candidate.name === NAME);
if (!tool) throw new Error(`WebMCP tool not found: ${NAME}`);
const codex = typeof ctx.codexExecuteTool === "function" ||
  typeof ctx.codexGetTools === "function";
const result = await ctx.executeTool(tool, codex ? ARGS : JSON.stringify(ARGS));

ヘルパーは、実行中の検出、部分的なレジストリ、保留中の呼び出しを処理します。呼び出しが state: "pending" を返した場合は、次の評価で an.result(id) を読み取ってください。書き込みを再実行してはいけません。Claude Code または Cowork では、javascript_tool がトップレベルの await を使ってこのページワールドコードを実行します。Codex では、cua.createBrowserTab("iab", url, { visible: true }) でページを開き、その後 awaitPromise: true を指定して CDP の Runtime.evaluate を使用してください。Puppeteer と Playwright MCP では、ページ評価機能を使用できます。Playwright の分離ワールドからは document.modelContext を参照できません。評価結果は小さく保ち、依存する呼び出しはまとめて実行し、バッチの途中でページを移動しないでください。

ツールの記述子はページ内でのみ有効です。ホストにコピーしたり、認証済み HTTP リクエストを手動で構築したり、名前付きツールをクリック、入力、DOM 自動化、スクリーンショットで置き換えたりしてはいけません。名前付きツールがない場合や要求された場合は、キャンバス作業に UI 自動化を使用してもかまいません。1 回の検出と 1 回の独立した評価機能の確認を行っても両方のブリッジを利用できない場合は、状態を変更する前に、ホスト型 MCP または CLI を使用してください。

新規のサインアウト状態のループバック接続では、ブリッジトークンをローカルで生成して、それを使って永続ブリッジを起動し、同じトークンをページツールの bridgeToken として一度だけ渡してください。ページからトークンが返されることはありません。実行中のブリッジが一致している場合は、トークンを使わずに再利用してください。アカウントにひも付く作業や非公開の Design 作業には、サインイン済みセッションまたは認証済み Design MCP コネクターが必要です。キャンバスの編集後、an.call("get-visual-edit-prompt", {}, { waitMs: 2_000 }) を呼び出し、返された引き継ぎ内容を適用してください。ページツールに承認ダイアログが表示された場合は、ユーザーに承認してもらってください。この同意を回避してはいけません。

コアモデル

• 各画面は、コピーした HTML ではなく、URL に紐づく iframe です。
• 各画面には、connectionId、routeId、path、 url、bridgeUrl、タイトル、ビューポートサイズの URL メタデータが保持されます。
• オーナーはローカルブリッジ経由で編集します。共有された /visual-edit/:designId?share=1 リンクには、ルートまたは DOM の変更時に更新される、サニタイズ済みの非アクティブなスナップショットが表示されます。ゲストがオーナーの localhost にアクセスすることはありません。 ゲストによる編集は、オーナーまたはエディターがソースに反映するまで保留されます。
• 非公開デザインの閲覧者およびコメント投稿者として認証されたユーザーは、共有された Visual Edit キャンバスを編集し、デザインファイルに書き込まずに変更を送信できます。 オーナーまたはエディターがその変更をソースに反映します。
• /visual-edit スキルに Design アカウントへのサインインは不要です。 open-visual-edit は、正確な /visual-edit/:designId ローカルエディタールートに対する、5 分間有効で 1 回限りのケイパビリティを発行します。MCP ホストはモデルから見えるテキストの外でこれを引き換え、localhost の編集アクセス権を使って既存のエディターを開きます。 公開モードの公開 /visual-edit/:designId ルートでは、公開 localhost スナップショットをブラウザーのみで DOM 編集できます。変更の引き継ぎは、反映されるまで保留されます。受信者に保留中の変更がある場合、オーナーには 編集を適用 が表示されます。 このケイパビリティはアカウントセッションではありません。/_agent-native/session は引き続きサインアウト状態で、アカウントに紐づく保存、共有、生成の各アクションは引き続き拒否されます。
• ホスト型 MCP では get-visual-edit-pending が使われます。タブを開かずに変更を引き継ぐには、Visual Edit のデザイン ID を渡します。これはリビジョンを返します。変更を反映した後、そのリビジョンを指定して acknowledge-visual-edit-pending を呼び出し、再度取得してください。 empty は変更がないことを意味し、session-ended は変更が失われたことを意味します。 unknown はマーカーを読み取れなかったことを意味し、変更がない証拠ではありません。
• ブラウザーホストでは、ページローカルの get-visual-edit-prompt を使用できます。
• open-visual-edit アクションは Design が所有します。別のアプリから使用する場合は、pnpm action を対象アプリで実行するのではなく、ホスト型 MCP サーバー https://design.agent-native.com/mcp またはページの WebMCP ヘルパーを使用してください。ページ経由の方法は、公開モードのループバックアプリでのみサインアウト状態で動作し、有効期間が短いケイパビリティスコープのプリンシパルを使用します。ホスト型 MCP では通常の OAuth ID が使用されます。
• 通常の公開リンクは引き続き読み取り専用です。公開 /visual-edit/:designId と、認証済みユーザー向けの非公開共有では DOM のみ編集でき、ソースへの書き込みはできません。ゲストの Interact はブロックされます。スナップショットからはアクティブなコンテンツとオーナーのローカルリソースが取り除かれ、永続化される書き込みは引き続きロールによって制限されます。トンネル経由でリモートの呼び出し元がプロキシを利用できるため、ループバックは信頼境界ではありません。
• ライブエディターは、ローカルブリッジプロキシ経由で同一オリジンになります。これにより CSR アプリとルート相対アセットを起動できますが、これは依然として localhost の編集用プロキシです。アプリ独自のオリジンと完全に同等にするには、アプリオリジンの Cookie、WebSocket/HMR、SSE、GET 以外のアプリ API 呼び出しに、将来的な開発サーバーまたはプラグインとの統合が必要になる場合があります。
• キャンバスは編集ビューです。Interact では、レールとデバイスバーを備えた通常の URL が実行されます。Interact ではナビゲーション、スクロール、リンク、コントロールが維持されます。キャンバスではパンとズームができ、フレームのネイティブ操作は抑制されます。
• localhost 画面に保留中のライブビジュアル編集がある間は、ユーザーが編集をソースに適用するか、プレビューを明示的に中止または破棄するまで、Interact に戻さないでください。
• Alt キーを押しながらドラッグすると、localhost フレームとその URL メタデータが複製されます。別の状態を表示するには、複製したフレームのパスまたはクエリを変更してください。名前付きまたは番号付きフローの順序は維持してください。 localhost:1234/onboarding/1 のような省略形は、 http://localhost:1234/onboarding/1 を意味します。

便利なキャンバスセット

デフォルトでは、3～7 個のフレームによる焦点を絞ったバッチを使用します。要求されたルート/クエリ状態ごとに 1 つの順序付けられたフレームを用意し、要求されたデスクトップ/タブレット/モバイルのビューポートでルートを繰り返し、URL で指定可能な空、読み込み中、エラー、モーダル展開、または選択項目の状態を含めます。Screens セクションは読みやすい状態に保ち、編集中も Layers が役立つようにします。ユーザーが網羅的な監査または完全なルート一覧を明示的に求めない限り、7 個のフレームを超えて拡張しないでください。

ユーザーが網羅的な監査を求めない限り、検出されたすべてのルートやすべてのビューポートを展開しないでください。ユーザーのラベルと順序を保持し、キャンバスがユーザーの説明したワークフローのように読めるようにします。

選択と再プロンプト

チャットメッセージが [Reprompt selection] で始まる場合、選択されたサブツリーは厳格な書き込み境界です。唯一の変更経路は propose-node-rewrite であり、design-reprompt-pending:<designId>:<fileId> にキャプチャされた正確な repromptId、ターゲット、および baseVersionHash を指定します。そのリクエストに対して apply-visual-edit、apply-source-edit、write-source、write-local-file、edit-design、またはその他のコンテンツ書き込みアクションを決して使用しないでください。確認の質問は許可されますが、要求された変更は提案のままにしておく必要があります。

デフォルトでは 1 つのバリアントを生成します。指示が選択肢を求めた場合にのみ、2 つまたは 3 つを生成します。再試行には priorProposalId が含まれます。同じターゲットとベースバージョンを維持し、フィードバックを取り込み、再度 propose-node-rewrite を呼び出します。UI は返されたサブツリーをプレビューしますが、永続化はしません。

承認/拒否のライフサイクルには resolve-node-rewrite を使用します。承認は、選択されたバリアントを 1 つのバージョンチェック済みインライン/Yjs コンテンツトランザクションとして適用するため、1 回の undo で以前の構造が復元されます。拒否は、コンテンツを変更せずに提案をクリアします。「2 つ目を適用して」などの会話による解決では、view-screen を呼び出し、アクティブな design.reprompt.proposal を読み取り、その proposalId と 0 から始まる variantIndex を resolve-node-rewrite に渡します。

レビューの品質

実行中のアプリを真実として扱い、そのコンポーネント言語、トークン、ルート状態、およびコンテンツを保持します。要求されたビューポートで視覚的な編集の前後を比較し、意味のある URL、hover、focus、scroll、およびモーダルの状態を確認します。

アカウントと共有モデル

• このケイパビリティは、ライブ iframe 検査、セッションローカルの編集、undo/redo、および Copy prompt を許可します。コピーされた指示はコーディングエージェントに送信され、アカウント所有の Design データを永続化しません。
• 公開 /design/:id リンクは、サインイン済みのオーナー/エディターセッションがない限り読み取り専用のままです。その通常の共有サーフェスをアップグレードするためにローカルケイパビリティを使用しないでください。
• Design アクションによって返されるリンク、または /_agent-native/open ディープリンクを優先してください。_session= トークンを表示したり、ケイパビリティ URL を手動で構築したりしないでください。
• ブラウザケイパビリティでアカウントに裏付けられた書き込みアクションを試みないでください。信頼されたローカルの open-visual-edit CLI 呼び出しは、そのブリッジを登録し、ワークスペース所有のローカルデザインを作成または再利用し、アカウントなしでスクリーンを配置できます。直接のソースファイルアクション書き込み、生成、アカウントへの保存、および共有には、依然として認証されたアクション呼び出し元が必要です。サインアウトした訪問者がこれらの永続的なアカウント操作を希望する場合は、まずフレームワークのサインインリターンフローを通じて送信してください。

必須のローカルブリッジ

ライブ編集ブリッジは共有シークレット（「ブリッジトークン」）でロック解除されます。このトークンは、ローカルブリッジプロセスと、Design 内のユーザーの接続行の両方で一致する必要があります（ブラウザーはこの行を読み取り、/live-edit-bridge、/read-file、/write-file を認可します）。open-visual-edit アクションにトークンを生成させてから、トークンを指定してブリッジを起動することで、一致させます。リモート MCP フローで機能する順序はこれだけです。ブリッジは CLI 認証トークンなしでは自身のトークンをサーバーに送信できないため、サーバーがトークンを生成し、ブリッジがそれを採用します。 connectionId（通常は localhost_...）は行を識別するだけのものです。bridgeToken として渡さないでください。

サインアウト状態のブラウザーフローを新たに開始する場合は、トークンをローカルで生成し、ホストプロセス内に保持して、ページツールのオプションの bridgeToken として一度だけ渡します。ページからトークンが返されることはありません。

BRIDGE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
AGENT_NATIVE_BRIDGE_TOKEN="$BRIDGE_TOKEN" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon

既存の一致する接続を再利用する場合は、bridgeToken を指定しません。ページ WebMCP が利用できない場合、ホスト型 MCP がトークンを生成できます。

対象アプリのリポジトリで、開発サーバーが実行中であることを確認してから、次の操作を行います。

1. 永続ブリッジを起動せずにルートを検出する（一度だけ実行し、終了します）。

npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json

これにより、マニフェスト（ルートと機能）が出力されます。これを解析して、次の手順で使う routeManifest を構築します。（ユーザーが配置先のパス／URL をすでに明示している場合は省略してください。）

agent-native モノレポ自体の内部では、npx ではなくワークスペース CLI を使ってください。npx は公開済みの最新の @agent-native/core をインストールしますが、ローカルの変更は含まれず、呼び出すたびに時間のかかるインストールが発生します。

pnpm dev:cli design connect --url http://localhost:5173 --root templates/<app> --json

2. ホスト型 MCP の経路では、open-visual-edit を呼び出します（下記のアクションフローを参照）。 bridgeToken は指定しません。 サーバーがトークンを生成し、ユーザーの接続行に保存して、配置した画面のメタデータにコピーし、bridgeToken として返します。これを取得してください。

3. そのトークンを採用して永続ブリッジを起動します（1 行で実行します。シークレットが ps に表示されないよう、環境変数を使うことを推奨します）。

AGENT_NATIVE_BRIDGE_TOKEN="<bridgeToken from step 2>" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon

（代わりに、--bridge-token <token> を渡すこともできます。）これにより、http://127.0.0.1:7331 でデタッチされたブリッジが起動し、サーバーが生成したトークンを採用します。そのため、ブリッジと接続行のトークンが一致し、自己登録なしでライブ編集の認可が行われます。また、コマンドの終了後もブリッジは稼働し続けます。

実行中のブリッジのヘルスチェック／マニフェストを手動で確認する場合は、次のようにします。

curl http://127.0.0.1:7331/health

/health にはトークンは不要です。/manifest.json の完全なマニフェストはプレビュートークンで保護されているため、認証なしの curl では {"ok":false,"error":"invalid or missing preview token"} が返ります。この応答はブリッジが起動していることを示しており、故障を意味するものではありません。

--json は手順 1 のルートプローブでのみ使用してください。永続ブリッジを起動する手順 3 では、--json、--once、--dry-run を使わないでください。これらはマニフェストを出力して終了するため、Design は編集できないライブ iframe にフォールバックします。

ブリッジは固定ポート（7331）を 1 つだけ使用し、別のアプリに対する 2 つ目の起動を拒否します。ログファイルを作成せずにデタッチされるため、--daemon がタイムアウトを報告した場合は、再試行する前に古いプロセス（lsof -ti:7331）が残っていないか確認してください。

ローカルの Design が PGlite を使用している場合、そのサーバーに対してインプロセス CLI を実行しないでください。両者が同じディレクトリを開くため、2 つ目の所有者は拒否されます。サインアウト状態でローカルテストを行うには、AUTH_DISABLED=1 を指定して Design を起動し、/visual-edit を開いて、登録後に window.__agentNativeWebMcp 経由でサーバーアクション open-visual-edit を呼び出します。これにより、PGlite の所有者を 1 つに保てます。get-visual-edit-prompt は編集後の引き継ぎ専用です。認証が有効な場合は、ホスト型 Design MCP にサインインするか、CLI アクションを使う前に共有 Postgres を使用してください。

アクションフロー

ブラウザーが利用できる場合は、ローカルブリッジを再利用し、Design ページの open-visual-edit WebMCP ツールを呼び出します。サインアウト状態から新たに接続する場合は、 ローカルに保持している bridgeToken を渡します。このツールはプレビューのマニフェストとチャレンジ証明を読み取り、 検証のために両方を送信します。ホストされた Design が 127.0.0.1 にアクセスすることはありません。ページに WebMCP がない場合は、接続済みの Design MCP サーバーまたは通常のホスト型 MCP フォールバックを使用します。

別のアプリからは、以下の JSON 引数を指定して、接続済みの Design MCP ツール mcp__agent-native-design__open-visual-edit を呼び出します。このツールはローカルホストブリッジを登録または更新し、 ブリッジトークンを生成して保存し、Design プロジェクトを作成または再利用し、 URL に基づく画面を配置し、ビジュアル編集コンテキストを保存して、1 回の呼び出しで概要モードに移動します。対象アプリのチェックアウトから pnpm action を実行してはいけません。ローカルレジストリには Design アクションが含まれていないためです。

永続的なブリッジを起動する前に呼び出してください。ブリッジには接続しないため、 サーバーはブリッジが採用できる bridgeToken を生成できます。この入力は省略してください。

{
  "title": "Docs homepage visual edit",
  "devServerUrl": "http://localhost:5173",
  "bridgeUrl": "http://127.0.0.1:7331",
  "rootPath": "/absolute/path/to/app",
  "routeManifest": { "...": "from /manifest.json" },
  "paths": ["/", "/pricing", "/checkout?step=payment"]
}

アクションは designId、connectionId、bridgeToken、screens、 urlPath、および認証情報を含まない openUrl を返します。MCP App のメタデータには、 非表示のワンタイムランチャーが含まれます。後続の操作のために ID を保持し、 トークンを design connect に渡してください。同じ接続を再利用すると、トークンも再利用されます。

デスクトップとモバイルを並べて表示する

viewports を渡すと、要求された各ルートを各ビューポートに 1 回ずつ配置します。フレームは グリッド状にレイアウトされます。ルートごとに 1 行、ビューポートごとに 1 列です。プリセットは desktop（1280x900）、laptop（1440x900）、tablet（834x1112）、および mobile （390x844）です。明示的な { "label": "...", "width": N, "height": N } も使用できます。

{
  "title": "Tasks responsive visual edit",
  "devServerUrl": "http://localhost:5173",
  "bridgeUrl": "http://127.0.0.1:7331",
  "rootPath": "/absolute/path/to/app",
  "paths": ["/tasks", "/inbox"],
  "viewports": ["desktop", "mobile"]
}

defaultWidth／defaultHeight を指定した 2 回の別々の呼び出しよりも、この方法を優先してください。 各ルートのビューポートが同じ行に並び、タイトルも Tasks — Desktop／Tasks — Mobile となるため、 キャンバスを見やすくできます。viewports は defaultWidth／defaultHeight より優先されます。routes／paths を指定しない場合は、ローカルホストのマニフェストにあるすべてのルートが展開されます。通常はユーザーが希望する数を大幅に超えるフレームが表示されるため、パスを指定してください。

画面とブレークポイントを手動で管理する

画面を選択し、右側のレールにある 画面 セクションで、静的 HTML と URL ベースのモードを切り替えたり、 そのルート／パスを編集したり、ローカルホスト接続を選択したり、URL 画面を追加したり、選択中の画面を削除したりできます。URL モードでは iframe がライブ状態に保たれます。静的モードに切り替えると、ページが提供できる場合は現在のクライアント状態を含め、現在のフレームのサニタイズ済みスナップショットが保存されます。 同じ操作は、ページ操作が可能なエージェントから add-localhost-screens、update-screen-source、add-breakpoint、および remove-breakpoint を通じて利用できます。

後からページフレームを追加する

同じ designId と connectionId を指定し、新しいパスだけを含めて、再度 open-visual-edit を呼び出します。 ID がない場合、同じ接続の保存済みプロジェクトが再開されます。newDesign: true を指定すると、別のプロジェクトが作成されます。一致するフレームはその場で更新され、座標が渡されない限り、ユーザーが設定した位置とサイズが維持されます。

{
  "designId": "<existing-design-id>",
  "connectionId": "<existing-connection-id>",
  "devServerUrl": "http://localhost:5173",
  "paths": ["/settings", "/team"],
  "startY": 2200
}

デフォルトのサイズを再指定する目的だけで defaultWidth／defaultHeight を追加してはいけません。 どちらかを指定すると、ビューポートが明示的に要求されたものとして扱われ、キャンバスでユーザーがすでに調整したフレームサイズが上書きされます。

チャットでユーザーが番号付きフローを説明している場合は、ラベルと順序を維持してください。

{
  "designId": "<existing-design-id>",
  "connectionId": "<existing-connection-id>",
  "devServerUrl": "http://localhost:1234",
  "routes": [
    { "url": "localhost:1234/onboarding/1", "title": "Screen 1" },
    { "url": "localhost:1234/onboarding/2", "title": "Screen 2" },
    { "url": "localhost:1234/onboarding/3", "title": "Screen 3" }
  ]
}

routes または paths が指定されていない場合、open-visual-edit はローカルホストのマニフェストにあるすべてのルートを使用します。

フォールバックを使用するのは、open-visual-edit を利用できず、ホスト型 Design MCP が認証済みの場合に限ります。

1. /manifest.json の結果を routeManifest と capabilities として渡し、connect-localhost でブリッジを登録または更新します。
2. create-design で Design プロジェクトを作成または再利用します。
3. add-localhost-screens で URL に基づく画面を配置します。
4. navigate で概要モードに移動します。

フォールバックでも対象は https://design.agent-native.com です。ローカルホストなのはアプリとブリッジの URL のみです。templates/design から pnpm action を実行してはいけません。

デザイン画面を開く

• Design アクションから返された link、deepLink、または MCP App の埋め込みを使用して、ユーザーにキャンバスを表示します。MCP App を優先してください。ホストランチャーにはワンタイム機能が含まれています。認証情報を必要としない openUrl は読み取り専用の代替手段です。
• 手作業で作成した /design/:id?_session=... URL を返したり、開いたりしないでください。
• ユーザーが VS Code を使用している場合、Agent-Native 拡張機能から同じ URL を vscode://builder.agent-native/open?url=<encoded-design-url> 経由で開けます。また、Agent-Native: Open Design Canvas コマンドを実行すると、ローカルブリッジが起動し、VS Code のサイドパネルにホストされた Design が開きます。
• open-visual-edit が想定される screenCount を返したら、リンクを渡して終了します。ブラウザー自動化ツールで自分から開き、スクリーンショットを撮ったり、レンダリングされるまでポーリングしたりしないでください。起動直後の開発サーバーは、誰が確認していても 10～30 秒かかることがあり、その待ち時間で応答にすでに含まれている確認結果以上のものは得られません。ユーザーから後でキャンバスが動作しないと報告された場合に限り、ブラウザー自動化を使用してください。

ビジュアル編集をソースに反映する

Design を閉じた状態で、ホストされた Design MCP の強調表示された get-visual-edit-pending をデザイン ID に対して呼び出します。返された引き継ぎ内容とリビジョンを確認します。適用されたソースを検証し、そのリビジョンを確認したうえで、再度取得します。MCP を利用できない場合は、ローカルブリッジを読み取ります。

npx @agent-native/core@latest design pending --root . --design-id <design-id-from-visual-edit-url>

Design URL の visual-edit の後に ID を渡します。CLI はそのデザインのプロンプトを出力します（空の場合は null）。

localhost の画面上で行ったキャンバス編集が、ソースに直接書き込まれることはありません。コーディングエージェントが get-visual-edit-pending またはコピーしたプロンプトを使って取得し、ソースに書き込むまで保留状態になります。キャンバスには独立した［適用］ボタンはありません。MCP App はホストまたはローカル Design エージェント経由でプロンプトを送信します。それ以外の場合は、Copy prompt to your agent を使用してください。

ChatGPT と Claude Code では、変更を取得して適用し、確認したうえで再度取得してください。ブラウザー WebMCP ホストでは get-visual-edit-prompt を呼び出せます。ソースの変更を適用する前に、確認を行わないでください。

• スタイル、テキスト、ドラッグ＆ドロップの編集は、1 回の適用にまとめられた保留中のバッチに集約されます。
• 書き込みが反映されると、対象アプリ自身の開発サーバーの HMR によってフレームが更新されます。手動で再読み込みする必要はありません。フレームが更新されない場合は、書き込みが反映されていません。反映されたと決めつけず、その旨を伝えてください。
• ディスクアイコンの別個の［Apply to source］ボタンは、ファイル全体を書き込む HTML/CSS 用の確実な手段です。コンパイル済みの .jsx/.tsx ルートでは意図的に無効になっています。これらは上記のエージェント経由の手順で処理する必要があります。

URL の編集

localhost の画面は URL ファイルと screenMetadata[fileId] の組み合わせのままにしてください。ユーザーから固定スナップショットを明示的に求められない限り、コピーした srcdoc HTML に置き換えないでください。状態を変更するには、新しいパスやクエリで open-visual-edit を再実行するか、［Screen settings］セクションを使用するか、update-screen-source を呼び出すか、画面を複製して複製した画面の URL メタデータを更新してください。

コードタブのローカルファイル

接続を登録すると、デザインエディターのコードパネル（左側のレール → コード、または navigate --view editor --designId <id> --leftPanel code）に、その接続用のローカルファイルワークスペースルートが、デザイン自体のファイルと並んで表示されます。このルートは、接続先プロジェクトディレクトリを開いた VS Code のように扱ってください。ファイルツリー、検索、ファイルのオープン／編集、保存は、実際のローカルファイルを対象とします。接続されたアプリのテキスト／コードファイルがブリッジ経由で一覧表示されます（list-local-files / read-local-file）。ビルド出力、node_modules、.git、および秘密情報を含むと思われるパス（.env*、鍵ファイル）は常に除外されます。

• 閲覧と読み取りに必要なのは、デザインへのエディターアクセスと実行中のブリッジだけです。
• 保存には write-local-file を使用します。初回の保存時に書き込み同意ダイアログが開き（フォルダー単位で8時間有効な許可）、許可されると自動的に一度再試行します。書き込み可能なのはテキスト／コードファイルのみです。秘密情報を含むパスは常にブロックされます。
• エージェントが（UIからの保存ではなく）write-local-file を直接呼び出し、「no write-consent grant」エラーで失敗した場合は、request-localhost-write-consent を呼び出してください。エディターで書き込み同意ダイアログが開くか、すでに許可がある場合は alreadyGranted が返されます。許可できるのは人間だけです。grant-localhost-write-consent はエージェントからは非表示のため、自分で承認することはできません。ユーザーに「書き込みを許可」をクリックするよう伝えてから、write-local-file を一度再試行してください。むやみに再試行し続けないでください。ユーザーが承認するまで、書き込みはブロックされたままです。
• 保存時には、ディスク上のファイルのバージョンとの競合がチェックされます。読み取り後に変更されたファイルは上書きされず、バージョン競合として失敗します。

React ソースへの書き戻し

• コンパイラー／デバッグの来歴情報（プロジェクト相対のファイル、行、列、コンポーネント、ランタイムでの出現数）を使って、React/TSX のソースを特定してください。これは証拠として扱い、汎用的な AST 構造変換を行う許可とはみなさないでください。
• アンカーの line／column を信頼する前に、必ず positionPrecision を確認してください。authored は実際の JSX 座標を意味します。transformed は開発サーバー自身の出力座標を意味します。React 19 では _debugSource が削除され、オーナースタックのみが公開されるため、Vite/Next の開発サーバーではこれが通常の状態であり、行番号はファイルと一致しません。unknown は、精度の区分が報告されていないことを意味します。authored 以外の場合は、ファイルとコンポーネントを使って JSX の形状から要素を特定し、読み取ったファイルをもとに行番号を改めて割り出してください。報告された行で編集してはいけません。
• 単一インスタンスのリーフテキスト編集、リテラルの className／class 編集、またはフラットなリテラル style={{ ... }} プロパティの編集には、local-file ソースと完全な target.sourceAnchor を指定して apply-visual-edit を使用できます。アンカーの positionPrecision も渡してください。そうしないと、編集後のファイルでは別の意味を持つ行を探すのではなく、status: "needsAgent" として transformed アンカーを拒否します。まずプレビューし（persist を省略）、proposedDiff を確認してから、persist: true を指定して呼び出してください。
• 親子関係の変更、グループ化／グループ解除、ラッパー、動的な式、繰り返しの .map() インスタンス、共有コンポーネント、ブレークポイント単位の編集、ファイルをまたぐ変更は、完全なサブジェクト／ターゲットアンカーとランタイム上の関係性を指定して、コーディングエージェントを通じて行ってください。apply-visual-edit は推測せず、これらの操作を status: "needsAgent" として拒否します。
• 書き込みのたびに、ファイルを読み取り、その正確な versionHash を requireExpectedVersionHash: true とともに write-local-file に渡してください。競合が発生した場合は、ファイルを再読み込みして計画を立て直してください。HMR／ランタイムで結果が確認されるまでは、楽観的プレビューを維持してください。人間による書き込み同意は引き続き必須であり、エージェントは許可できません。

検証

「このアプリを開いて」という単純なリクエストでは、open-visual-edit 自体の応答が検証になります。「デザイン画面を開く」を参照してください。以下のチェックは、実際の報告内容を診断する場合、または編集が反映されたことを確認する場合にのみ行ってください。

• list-localhost-connections が想定どおりの接続とルートを返します。
• デザインエディターが概要モードで開きます。
• リクエストされたすべての画面に意図した localhost URL が表示され、読み込み中のスピナーが延々と回り続けるのではなく、実際のアプリのコンテンツが表示されます。
• 画面の iframe に src があり、srcdoc ではありません。localhost の画面に srcdoc が設定されている場合、読み込みが遅いのではなくバグです。キャンバスが正常に動作していると報告する前に、ブラウザーの開発者ツールで確認してください。
• 画面を Alt キーを押しながらドラッグすると、インライン HTML の複製ではなく、URL に紐付いたフレームがコピーされます。
• クエリまたはパスの編集によって変更されるのは、対象画面の URL メタデータと iframe のみです。
• get-visual-edit-pending はタブを使わない引き継ぎ方法です。適用後にそのリビジョンを確認してください。get-visual-edit-prompt はブラウザー上で同等の操作を行う方法です。
• コードタブに接続のローカルファイルルートが表示され、ファイルを開けます。