> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Refaktor Plugin Canvas

# Refaktor Plugin Canvas

Canvas jarang digunakan dan bersifat eksperimental. Perlakukan ini sebagai Plugin bawaan, bukan fitur inti. Inti boleh tetap menyimpan plumbing Gateway, Node, HTTP, auth, konfigurasi, dan klien native yang generik, tetapi perilaku khusus Canvas harus berada di bawah `extensions/canvas`.

## Tujuan

Memindahkan kepemilikan Canvas ke `extensions/canvas` sambil mempertahankan perilaku node berpasangan saat ini:

* tool `canvas` yang menghadap agen didaftarkan oleh Plugin Canvas
* perintah node Canvas hanya diizinkan ketika Plugin Canvas mendaftarkannya
* file host/sumber A2UI berada di bawah Plugin Canvas
* materialisasi dokumen Canvas berada di bawah Plugin Canvas
* implementasi perintah CLI berada di bawah Plugin Canvas, atau mendelegasikan melalui barrel runtime milik Plugin
* dokumentasi dan inventaris Plugin mendeskripsikan Canvas sebagai eksperimental dan didukung Plugin

## Bukan tujuan

* Jangan mendesain ulang UI Canvas aplikasi native dalam refaktor ini.
* Jangan menghapus dukungan protokol/klien Canvas dari iOS, Android, atau macOS kecuali keputusan produk terpisah mengatakan Canvas harus dihapus.
* Jangan membangun kerangka kerja layanan Plugin yang luas hanya untuk Canvas kecuali setidaknya satu Plugin bawaan lain membutuhkan seam yang sama.

## Status branch saat ini

Selesai:

* Menambahkan paket Plugin bawaan di `extensions/canvas`.
* Menambahkan `extensions/canvas/openclaw.plugin.json`.
* Memindahkan tool agen `canvas` dari `src/agents/tools/canvas-tool.ts` ke `extensions/canvas/src/tool.ts`.
* Menghapus pendaftaran inti `createCanvasTool` dari `src/agents/openclaw-tools.ts`.
* Memindahkan implementasi host Canvas dari `src/canvas-host` ke `extensions/canvas/src/host`.
* Mempertahankan `extensions/canvas/runtime-api.ts` sebagai barrel kompatibilitas milik Plugin untuk pengujian, pemaketan, dan helper Canvas publik eksternal.
* Memindahkan materialisasi dokumen Canvas dari `src/gateway/canvas-documents.ts` ke `extensions/canvas/src/documents.ts`.
* Memindahkan implementasi CLI Canvas dan helper JSONL A2UI ke `extensions/canvas/src/cli.ts`.
* Memindahkan URL host Canvas dan helper kapabilitas bercakupan ke `extensions/canvas/src`.
* Memindahkan default perintah node Canvas keluar dari daftar inti yang di-hardcode dan masuk ke `nodeInvokePolicies` Plugin.
* Menambahkan konfigurasi host Canvas milik Plugin di `plugins.entries.canvas.config.host`.
* Memindahkan penyajian HTTP Canvas dan A2UI ke balik pendaftaran rute HTTP Plugin Canvas.
* Menambahkan dispatch upgrade WebSocket Plugin generik untuk rute HTTP milik Plugin.
* Mengganti URL host Gateway dan auth kapabilitas node khusus Canvas dengan permukaan Plugin ter-host generik dan helper kapabilitas node.
* Menambahkan resolver media ter-host milik Plugin sehingga URL dokumen Canvas diselesaikan melalui Plugin Canvas, bukan inti yang mengimpor internal dokumen Canvas.
* Menambahkan `api.registerNodeCliFeature(...)` sehingga Canvas dapat mendeklarasikan `openclaw nodes canvas` sebagai fitur node milik Plugin tanpa mengeja jalur perintah induk secara manual.
* Menghapus impor produksi `src/**` dari `extensions/canvas/runtime-api.js`.
* Memindahkan sumber bundel A2UI dari `apps/shared/OpenClawKit/Tools/CanvasA2UI` ke `extensions/canvas/src/host/a2ui-app`.
* Memindahkan implementasi build/salin A2UI ke bawah `extensions/canvas/scripts` dan mengganti wiring build root dengan hook aset Plugin bawaan generik.
* Menghapus alias konfigurasi runtime top-level lama `canvasHost`.
* Mempertahankan migrasi doctor Canvas sehingga `openclaw doctor --fix` menulis ulang konfigurasi lama `canvasHost` menjadi `plugins.entries.canvas.config.host`.
* Menghapus kompatibilitas protokol Canvas agen lama di balik protokol Gateway v4. Klien native dan Gateway sekarang hanya menggunakan `pluginSurfaceUrls.canvas` plus `node.pluginSurface.refresh`; jalur usang `canvasHostUrl`, `canvasCapability`, dan `node.canvas.capability.refresh` sengaja tidak didukung dalam refaktor eksperimental ini.
* Memperbarui inventaris Plugin yang dihasilkan agar menyertakan Canvas.
* Menambahkan dokumentasi referensi Plugin di `docs/plugins/reference/canvas.md`.

Permukaan Canvas milik inti yang diketahui masih tersisa:

* Handler Canvas aplikasi native di bawah `apps/` masih sengaja mengonsumsi permukaan Plugin Canvas
* handler protokol/klien Canvas aplikasi native di bawah `apps/`
* output artefak terpublikasi masih menggunakan `dist/canvas-host/a2ui` untuk lookup runtime yang kompatibel ke belakang, tetapi langkah penyalinan sekarang dimiliki Plugin

## Bentuk target

`extensions/canvas` harus memiliki:

* manifes Plugin dan metadata paket
* pendaftaran tool agen
* kebijakan perintah invoke node
* host Canvas dan runtime A2UI
* sumber bundel Canvas A2UI dan skrip build/salin aset
* pembuatan dokumen Canvas dan resolusi aset
* implementasi CLI Canvas
* halaman dokumentasi Canvas dan entri inventaris Plugin

Inti hanya boleh memiliki seam generik:

* penemuan dan pendaftaran Plugin
* registry tool agen generik
* registry kebijakan invoke node generik
* HTTP/auth Gateway generik dan dispatch upgrade WebSocket
* resolusi URL permukaan Plugin ter-host generik
* pendaftaran resolver media ter-host generik
* transport kapabilitas node generik
* plumbing konfigurasi generik
* penemuan hook aset Plugin bawaan generik

Aplikasi native boleh mempertahankan handler perintah Canvas sebagai klien protokol. Aplikasi tersebut bukan pemilik runtime Plugin.

## Langkah migrasi

1. Perlakukan `plugins.entries.canvas.config.host` sebagai permukaan konfigurasi milik Plugin.
2. Perbarui dokumentasi sehingga Canvas dideskripsikan sebagai Plugin bawaan eksperimental.
3. Jalankan pengujian Canvas terfokus, pemeriksaan inventaris Plugin, pemeriksaan API SDK Plugin, serta gate build/tipe yang terdampak oleh batas runtime.

## Checklist audit

Sebelum menyatakan refaktor selesai:

* `rg "src/canvas-host|../canvas-host"` tidak mengembalikan impor sumber live.
* `rg "canvas-tool|createCanvasTool" src` tidak menemukan implementasi tool Canvas milik inti.
* `rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway` tidak menemukan default allowlist yang di-hardcode di luar pengujian kebijakan Plugin generik.
* `rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts'` kosong.
* `rg "canvas-documents" src` kosong.
* `rg "registerNodesCanvasCommands|nodes-canvas" src` kosong; Plugin Canvas mendaftarkan `openclaw nodes canvas` melalui metadata CLI Plugin bersarang.
* `rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway` tidak mengembalikan kepemilikan runtime Gateway.
* `rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json` hanya menemukan wrapper kompatibilitas atau jalur milik Plugin.
* `pnpm plugins:inventory:check` berhasil.
* `pnpm plugin-sdk:api:check` berhasil, atau baseline API yang dihasilkan sengaja diperbarui dan ditinjau.
* Pengujian Canvas tertarget berhasil.
* Pengujian changed-lanes berhasil untuk jalur host/A2UI Canvas.
* Isi PR secara eksplisit mengatakan Canvas bersifat eksperimental dan didukung Plugin.

## Perintah verifikasi

Gunakan pemeriksaan lokal tertarget saat iterasi:

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.ts
pnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.ts
pnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.ts
pnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.ts
pnpm tsgo:extensions
pnpm plugins:inventory:check
pnpm plugin-sdk:api:check
```

Jalankan `pnpm build` sebelum push jika barrel runtime, impor lazy, pemaketan, atau permukaan Plugin terpublikasi berubah.