為甚麼我建立 Agent Canvas

由現有 Repo 變成完整互動畫布

交給能讀寫 Repo 及執行指令的 coding agent。不需要事先準備 Storybook 或手寫畫面清單；只安裝套件並不會自動填滿畫布。

貼給你的 Coding Agent

Read https://github.com/tombelieber/app-canvas/blob/v0.16.0/AGENT_GUIDE.md and add a completely populated Agent Canvas to this repository. Discover all screens, components, variants, states and navigation from the whole application source. Use original UI code. Create the missing synthetic fixtures and render harnesses. Reconcile an independent source inventory with rendered cases and source-linked runtime checks. Add checked happy, failure and recovery journeys. Group by actual page and feature, connect checked flows, deduplicate repeated captures and resume checkpoints. Run --ui-complete against the original source root; keep the stricter --complete source audit separate and unchanged. Continue until the full landscape is populated and verified; report genuine blockers as incomplete. Keep production sessions, credentials and real user data out of previews.

1. 安裝共用工具

   使用 Node.js 22+，沿用專案的 package manager 與 lockfile。安裝固定版本的 GitHub release，再安裝瀏覽器。npm 12 若阻擋此直接 Git dependency，才加 --allow-git=root；毋須更改全域設定。

   npm install --save-dev github:tombelieber/app-canvas#v0.16.0
   npx agent-canvas browsers

2. 先盤點，再選 Case

   對整個原有 App repository 執行 plan。檢視所有檔案及 UI anchors，追查影響 UI 的依賴，並核對實際導航。獨立列齊畫面及狀態，不能由 catalog 倒推範圍；未解決 UI 必須保留。

   npx agent-canvas plan --source-root . --out ui-review/ui-inventory.json
   npx agent-canvas status --inventory ui-review/ui-inventory.json

3. 用 Fixtures 渲染原有 UI

   Agent 建立 ui-review/canvas.config.mjs、catalog、虛構 fixtures、preview entry 及可檢查 journeys。Web adapter 匯入原有頁面、providers 與樣式；fixtures 只替代資料和依賴，不能重寫 UI。拒絕未知網絡請求。

   ui-review/
     canvas.config.mjs
     catalog.json
     frame.jsx
     fixtures.js
     README.md
   .artifacts/app-canvas/inventory.json

   // package.json → scripts
   "ui:review": "agent-canvas --config ui-review/canvas.config.mjs"

   React/Vite · Agent 指南

4. 驗證狀態與互動

   涵蓋已實作的一般、空白、載入、錯誤、拒絕存取、對話框及復原狀態。每個 case 都要有檢查，流程要操作真實控制項。核對 inventory、來源連結 assertions 與 routes，再對同一 App 根目錄通過 --ui-complete。 --complete 保留為獨立、嚴格的完整來源審查；其待辦數並非漏頁數。

   npx agent-canvas populate --config ui-review/canvas.config.mjs --source-root . --verify

5. 由原始碼維護與檢視

   執行 ui:review，查看總覽及狀態圖，再播放流程。請 Agent 修改真正 App 原始碼；既有 preview 會重建。新 route 或狀態需要更新 inventory、fixture 與 journey，交付前必須通過完整檢查。

   npm run ui:review

哪些東西留在你的 App Repo

共用套件維護 viewer、CLI 及 skill；各 Repo 維護自己的 adapter、fixtures、獨立 inventory、catalog 與互動檢查。可從可執行的 React/Vite 範例開始；其他技術棧使用專屬 adapter。

可選的 Agent Skill

Codex 與 Claude Code 可安裝內附 skill，其他 coding agent 可直接閱讀 AGENT_GUIDE.md。Canvas runtime 不呼叫模型，也不需要模型 API key；你選用的 Agent 有自己的費用與權限。

npx agent-canvas install --target both