From an existing repo to an interactive canvas

From an existing repo to an interactive canvas

Give the job to an agent that can read and edit your repository and run commands. No existing Storybook or manually prepared screen list is required. Installation alone does not populate the canvas.

Paste this into your 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. Install the shared tool

   Use Node.js 22+ and the project's package manager and lockfile. Install the pinned GitHub release, then its browser. On npm 12, add --allow-git=root only if Git admission blocks this direct dependency; do not change global policy.

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

2. Discover before choosing cases

   Run plan on the whole original application repository. Inspect every file and UI anchor, follow UI-affecting dependencies and cross-check actual navigation. Enumerate semantic screens/states independently of the catalog; keep unresolved UI visible.

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

3. Render the original UI with fixtures

   The agent adds ui-review/canvas.config.mjs, a catalog, synthetic fixtures, a preview entry and checked journeys. The web adapter imports real pages, providers and styles; fixtures replace data and dependencies, not the UI. Reject unknown network requests.

   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 guide

4. Verify states and interactions

   Author the implemented normal, empty, loading, error, denied, dialog and recovery conditions. Check every case and run real controls in continuing flows. Reconcile the inventory, source-linked assertions and route coverage, then pass --ui-complete against the same application root. --complete remains a separate strict all-source audit; its pending work is not a missing-screen count.

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

5. Review and maintain from source

   Run ui:review, inspect the overview and state graph, then play a flow. Ask the agent to edit the actual app source. Existing previews rebuild; new routes and conditions need inventory, fixture and journey updates. Require the complete gate before handover.

   npm run ui:review

What stays in your application

The shared package owns the viewer, CLI and skill. Your repo owns its adapter, fixtures, independent inventory, catalog and interaction checks. Start with the runnable React/Vite reference; use a project-specific adapter for other stacks.

Optional agent skill

Codex and Claude Code can install the bundled skill. Any other coding agent can follow AGENT_GUIDE.md directly. The canvas runtime makes no model calls and requires no model API key. Your chosen agent has its own costs and permissions.

npx agent-canvas install --target both