feat: ship design canvas runtime and sync surfaces

.gitignore

@@ -58,6 +58,7 @@ sub_continuity.md
 
 # Local planning artifacts
 .sisyphus/
+.factory/
 prd.json
 progress.txt
 

AGENTS.md

@@ -1,6 +1,6 @@
 # OpenDevBrowser - Agent Guidelines
 
-**Generated:** 2026-02-01 | **Commit:** 2869775 | **Branch:** main
+**Generated:** 2026-03-12 | **Commit:** fa2e88a | **Branch:** codex/design-canvas
 
 ## Overview
 
@@ -68,7 +68,7 @@ Tool Call → Zod Validation → Manager/Runner → CDP/Playwright → Response
 | `managed` | `--no-extension` | Fresh Playwright-controlled Chrome |
 | `cdpConnect` | `opendevbrowser_connect` | Attach to existing `--remote-debugging-port` |
 
-Extension relay requires **Chrome 125+** and uses flat CDP sessions with DebuggerSession `sessionId` routing. Annotation relay uses a dedicated `/annotation` websocket channel. When hub mode is enabled, the hub daemon is the sole relay owner and enforces FIFO leases (no local relay fallback).
+Extension relay requires **Chrome 125+** and uses flat CDP sessions with DebuggerSession `sessionId` routing. Annotation relay uses a dedicated `/annotation` websocket channel, and design-canvas relay uses a dedicated `/canvas` websocket channel. When hub mode is enabled, the hub daemon is the sole relay owner and enforces FIFO leases (no local relay fallback).
 
 ### Connection Flags & Status Semantics
 
@@ -77,6 +77,9 @@ Extension relay requires **Chrome 125+** and uses flat CDP sessions with Debugge
 - `--wait-for-extension`: Polls for extension handshake up to `--wait-timeout-ms` (min 3s).
 - `extensionConnected`: Extension WebSocket is connected to relay.
 - `extensionHandshakeComplete`: Extension handshake finished (preferred readiness signal).
+- `annotationConnected`: Annotation relay client attached.
+- `opsConnected`: At least one active `/ops` client.
+- `canvasConnected`: At least one active `/canvas` client.
 - `cdpConnected`: At least one active `/cdp` client; false is normal until a tool/CLI connects.
 - `pairingRequired`: Relay requires pairing token; extension auto-pair should handle this.
 
@@ -85,24 +88,24 @@ Extension relay requires **Chrome 125+** and uses flat CDP sessions with Debugge
 ```
 .
 ├── src/              # Plugin implementation
-│   ├── browser/      # BrowserManager, TargetManager, CDP lifecycle
+│   ├── browser/      # Browser sessions, target orchestration, canvas preview/code-sync
 │   ├── cache/        # Chrome executable resolution
 │   ├── cli/          # CLI commands, daemon, installers
 │   ├── core/         # Bootstrap, runtime wiring, ToolDeps
+│   ├── canvas/       # Design-canvas document store, repo IO, code-sync, export helpers
 │   ├── devtools/     # Console/network trackers with redaction
 │   ├── export/       # DOM capture, React emitter, CSS extraction
 │   ├── relay/        # Extension relay server, protocol types
 │   ├── skills/       # SkillLoader for skill pack discovery
 │   ├── snapshot/     # AX-tree snapshots, ref management
-│   ├── tools/        # 48 opendevbrowser_* tool definitions
+│   ├── tools/        # 49 opendevbrowser_* tool definitions
 │   ├── annotate/     # Annotation transports + output shaping
 │   └── utils/        # Shared utilities
 ├── extension/        # Chrome extension (relay client)
-├── frontend/         # Next.js marketing/docs frontend
 ├── scripts/          # Operational scripts (build/sync/smoke)
-├── skills/           # Bundled skill packs (8 total)
+├── skills/           # 8 canonical skill packs plus compatibility alias dirs
 ├── tests/            # Vitest tests (97% coverage required)
-└── docs/             # Architecture, CLI, extension, frontend, plans
+└── docs/             # Architecture, CLI, extension, plans, and version-scoped evidence
 ```
 
 ## Where to Look
@@ -119,9 +122,10 @@ Extension relay requires **Chrome 125+** and uses flat CDP sessions with Debugge
 | Extension routing | `extension/src/services/TargetSessionMap.ts` | Root/child session routing |
 | CLI commands | `src/cli/commands/` | Registry-based, daemon mode |
 | Add skill pack | `skills/*/SKILL.md` | Follow naming conventions |
+| Design canvas + code sync | `src/canvas/`, `src/browser/canvas-manager.ts`, `docs/CANVAS_BIDIRECTIONAL_CODE_SYNC_TECHNICAL_SPEC.md` | `canvas.session.attach`, `canvas.code.*`, manifest persistence, runtime preview fallback |
 | Config schema | `src/config.ts` | Zod schema, defaults |
 | DI wiring | `src/core/bootstrap.ts` | Creates ToolDeps, wires managers |
-| Full command/tool/channel inventory | `docs/SURFACE_REFERENCE.md` | Canonical 55 CLI + 48 tools + `/ops` + `/cdp` map |
+| Full command/tool/channel inventory | `docs/SURFACE_REFERENCE.md` | Canonical 56 CLI + 49 tools + `/ops` + `/canvas` + `/cdp` map |
 
 ## Commands
 
@@ -179,7 +183,7 @@ npm run version:check     # Verify version alignment
 - Hostname normalization: lowercase before validation
 - Relay auth: timing-safe token comparison
 - Rate limiting: 5 handshakes/min/IP
-- Origin validation: `/extension` requires `chrome-extension://`; `/cdp`, `/ops`, and `/annotation` accept extension origin or loopback requests without `Origin`
+- Origin validation: `/extension` requires `chrome-extension://`; `/cdp`, `/ops`, `/canvas`, and `/annotation` accept extension origin or loopback requests without `Origin`
 - Export sanitization: strip scripts, handlers, dangerous CSS
 
 ### File Permissions
@@ -193,7 +197,7 @@ Entry: src/index.ts
   └── Exports: { tool, chat.message, experimental.chat.system.transform }
 
 Bootstrap: src/core/bootstrap.ts
-  └── Creates: BrowserManager, ScriptRunner, SkillLoader, RelayServer
+  └── Creates: BrowserManager, AnnotationManager, CanvasManager, ScriptRunner, SkillLoader, providerRuntime, RelayServer
   └── Returns: ToolDeps (injected into all tools)
 
 Config: ~/.config/opencode/opendevbrowser.jsonc
@@ -206,8 +210,9 @@ Config: ~/.config/opencode/opendevbrowser.jsonc
 export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
   return {
     opendevbrowser_launch: createLaunchTool(deps),
+    opendevbrowser_canvas: createCanvasTool(deps),
     opendevbrowser_snapshot: createSnapshotTool(deps),
-    // ... 48 tools
+    // ... 49 tools
   };
 }
 ```
@@ -233,7 +238,8 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
 - Surface inventory: `docs/SURFACE_REFERENCE.md`
 - Additional design/plan docs: `docs/` (feature-specific; verify file paths exist before referencing)
 - Keep docs in sync with implementation
-- If tool list or outputs change, update `docs/CLI.md`, `docs/SURFACE_REFERENCE.md`, and this file together.
+- Treat generated CLI help as part of the documentation surface.
+- If tool list, command outputs, or help inventory changes, update `src/cli/help.ts`, `docs/CLI.md`, `docs/SURFACE_REFERENCE.md`, and this file together, then verify both `npx opendevbrowser --help` and `npx opendevbrowser help`.
 
 ## AGENTS.md Governance
 
@@ -244,6 +250,7 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
 Subdirectory guides override this root file:
 - `src/AGENTS.md` — module boundaries, manager patterns
 - `src/browser/AGENTS.md` — browser/session module specifics
+- `src/canvas/AGENTS.md` — canvas document store, repo persistence, code-sync specifics
 - `src/cli/AGENTS.md` — CLI command and daemon conventions
 - `src/providers/AGENTS.md` — provider system (web/social/shopping), tiers, safety
 - `src/relay/AGENTS.md` — relay protocol and security specifics
@@ -252,8 +259,6 @@ Subdirectory guides override this root file:
 - `extension/AGENTS.md` — Chrome extension specifics
 - `extension/src/ops/AGENTS.md` — ops runtime for extension relay
 - `extension/src/services/AGENTS.md` — CDP routing, flat-session handling
-- `frontend/AGENTS.md` — frontend app conventions and generation workflow
-- `frontend/src/AGENTS.md` — frontend source module boundaries
 - `docs/AGENTS.md` — documentation source-of-truth and sync rules
 - `scripts/AGENTS.md` — script safety and output conventions
 - `tests/AGENTS.md` — testing conventions

README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/opendevbrowser.svg?style=flat-square)](https://registry.npmjs.org/opendevbrowser)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 [![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-green.svg?style=flat-square)](https://opencode.ai)
 [![CLI](https://img.shields.io/badge/Interface-CLI-orange.svg?style=flat-square)](docs/CLI.md)
 [![Chrome Extension](https://img.shields.io/badge/Chrome-Extension-blue.svg?style=flat-square)](docs/EXTENSION.md)
@@ -43,12 +43,13 @@ Distribution split (current target state):
 | **Stable refs** | Elements identified by `backendNodeId`, not fragile selectors |
 | **Security by default** | CDP localhost-only, timing-safe auth, HTML sanitization |
 | **3 browser modes** | Managed, CDP connect, or extension relay for logged-in sessions |
-| **Ops + CDP channels** | High-level multi-client `/ops` plus legacy `/cdp` compatibility |
+| **Ops + Canvas + CDP channels** | High-level multi-client `/ops`, dedicated `/canvas`, plus legacy `/cdp` compatibility |
 | **Relay Hub (FIFO leases)** | Single-owner CDP binding with a FIFO queue for multi-client safety |
 | **Flat-session routing** | Extension relay uses DebuggerSession sessionId routing (Chrome 125+) |
+| **Design canvas + code sync** | Persist repo-native design documents, attach same-session observers, round-trip bound TSX files, and drive preview tabs with `canvas_html` or opted-in `bound_app_runtime` reconciliation |
 | **Loop-closure diagnostics** | Console/network polling + unified debug trace snapshots for verification workflows |
-| **8 bundled skill packs** | Best practices plus login, forms, data extraction, research, shopping, and product asset workflows |
-| **48 tools** | Complete browser automation coverage |
+| **10 bundled skill directories** | Best practices plus login, forms, data extraction, research, shopping, and product asset workflows |
+| **49 tools** | Complete browser automation coverage, including the design-canvas command surface |
 | **97% test coverage** | Production-ready with strict TypeScript |
 
 ---
@@ -93,6 +94,7 @@ npx --no-install opendevbrowser help
 
 Full validated flow: [`docs/FIRST_RUN_ONBOARDING.md`](docs/FIRST_RUN_ONBOARDING.md).
 Dependency/runtime inventory: [`docs/DEPENDENCIES.md`](docs/DEPENDENCIES.md).
+Live CLI inventory/help surface: `npx opendevbrowser --help` or `npx opendevbrowser help`.
 
 Use OpenCode only if you want plugin tools. CLI and extension workflows work without OpenCode.
 
@@ -296,9 +298,9 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
 ## Tool Reference
 
-OpenDevBrowser provides **48 tools** organized by category:
+OpenDevBrowser provides **49 tools** organized by category:
 Most runtime actions also have CLI command equivalents (see [docs/CLI.md](docs/CLI.md)).
-Complete source-accurate inventory (tools + CLI + `/ops` + `/cdp`): [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
+Complete source-accurate inventory (tools + CLI + `/ops` + `/canvas` + `/cdp`): [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
 
 ### Session Management
 | Tool | Description |
@@ -371,7 +373,12 @@ Complete source-accurate inventory (tools + CLI + `/ops` + `/cdp`): [docs/SURFAC
 ### Annotation
 | Tool | Description |
 |------|-------------|
-| `opendevbrowser_annotate` | Capture interactive annotations via extension relay |
+| `opendevbrowser_annotate` | Capture interactive annotations via direct (CDP) or relay transport |
+
+### Design Canvas
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_canvas` | Execute typed design-canvas session, attach, code-sync, preview, feedback, and overlay commands |
 
 ### Export & Cloning
 | Tool | Description |
@@ -389,7 +396,7 @@ Complete source-accurate inventory (tools + CLI + `/ops` + `/cdp`): [docs/SURFAC
 
 ## Bundled Skills
 
-OpenDevBrowser includes **8 task-specific skill packs**:
+OpenDevBrowser includes **8 OpenDevBrowser-specific skill packs** plus shared `research` and `shopping` compatibility directories that are synced by the installer:
 
 | Skill | Purpose |
 |-------|---------|
@@ -402,6 +409,9 @@ OpenDevBrowser includes **8 task-specific skill packs**:
 | `opendevbrowser-shopping` | Deterministic multi-provider deal comparison workflows |
 | `opendevbrowser-product-presentation-asset` | Product screenshot/copy asset collection for presentation pipelines |
 
+Installer note:
+- `--skills-global` and `--skills-local` copy every directory under `skills/`, including the shared `research/` and `shopping/` packs.
+
 Skills are discovered from (priority order):
 1. `.opencode/skill/` (project)
 2. `~/.config/opencode/skill/` (global)
@@ -431,18 +441,20 @@ Extension relay relies on **flat CDP sessions (Chrome 125+)** and uses DebuggerS
 
 Relay ops endpoint: `ws://127.0.0.1:<relayPort>/ops`.
 The connect command also accepts base relay WS URLs (`ws://127.0.0.1:<relayPort>` or `ws://localhost:<relayPort>`) and normalizes them to `/ops`.
+Relay canvas endpoint: `ws://127.0.0.1:<relayPort>/canvas` for design-canvas editor, session attach/lease flow, code-sync, preview, feedback, and overlay flows.
 Legacy relay `/cdp` remains available with explicit opt-in (`--extension-legacy`).
-When pairing is enabled, both `/ops` and `/cdp` require a relay token (`?token=<relayToken>`). Tools and the CLI auto-fetch relay config and tokens.
+When pairing is enabled, `/ops`, `/canvas`, and `/cdp` require a relay token (`?token=<relayToken>`). Tools and the CLI auto-fetch relay config and tokens.
 
-## Ops vs CDP
+## Relay Channels
 
 | Channel | What It Does | When to Use It |
 |---------|---------------|----------------|
 | **`/ops` (default)** | High-level automation protocol with session ownership, event streaming, and multi-client handling | Preferred extension relay path for modern workflows |
+| **`/canvas`** | Typed design-canvas protocol for session handshakes/attach, live editor sync, TSX code sync, preview tabs, feedback streams, and overlay selection | Use with `opendevbrowser_canvas` or `opendevbrowser canvas` during design-canvas workflows |
 | **`/cdp` (legacy)** | Low-level CDP relay path with compatibility-focused behavior | Opt-in compatibility mode (`--extension-legacy`) |
 | **Direct CDP connect** | Attach to Chrome started with `--remote-debugging-port` | Existing debug/browser setups without extension relay |
 
-For full `/ops` command names, `/cdp` envelope details, and mode/flag matrices, see [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
+For full `/ops` and `/canvas` command names, `/cdp` envelope details, and mode/flag matrices, see [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
 
 ---
 
@@ -600,10 +612,10 @@ All fields are optional. OpenDevBrowser works with sensible defaults.
 
 ## CLI Commands
 
-The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, targets, pages, export, devtools, and annotate).
+The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, targets, pages, export, devtools, annotate, and canvas).
 All commands listed in the CLI reference are implemented and available in the current codebase.
 See [docs/CLI.md](docs/CLI.md) for the full command and flag matrix.
-See [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the source-accurate inventory matrix (CLI commands, 48 tools, `/ops` and `/cdp` channel contracts).
+See [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the source-accurate inventory matrix (CLI commands, 49 tools, `/ops`, `/canvas`, and `/cdp` channel contracts).
 
 ### CLI Category Matrix (core command groups)
 
@@ -615,6 +627,7 @@ See [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the source-accura
 | Interaction | `click`, `hover`, `press`, `check`, `uncheck`, `type`, `select`, `scroll`, `scroll-into-view` |
 | Targets/pages | `targets-list`, `target-use`, `target-new`, `target-close`, `page`, `pages`, `page-close` |
 | DOM | `dom-html`, `dom-text`, `dom-attr`, `dom-value`, `dom-visible`, `dom-enabled`, `dom-checked` |
+| Design canvas | `canvas` |
 | Export/diagnostics/macro/annotation/power | `clone-page`, `clone-component`, `perf`, `screenshot`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `macro-resolve`, `annotate`, `rpc` |
 
 ### Install/Management
@@ -649,6 +662,7 @@ Start the daemon with `npx opendevbrowser serve`, then use:
 | `npx opendevbrowser select` | Select dropdown option by ref |
 | `npx opendevbrowser scroll` | Scroll page or element |
 | `npx opendevbrowser run` | Run a JSON script |
+| `npx opendevbrowser canvas --command canvas.session.open --params '{...}'` | Start or continue a design-canvas workflow through the daemon |
 | `npx opendevbrowser macro-resolve --expression '@media.search("youtube transcript parity", "youtube", 5)' --execute --timeout-ms 120000` | Execute macro plans with extended timeout for slow runs |
 
 Workflow cookie controls (`research run`, `shopping run`, `product-video run`):
@@ -666,7 +680,7 @@ OpenDevBrowser is **secure by default** with defense-in-depth protections:
 |------------|---------|
 | **CDP Localhost-Only** | Remote endpoints blocked; hostname normalized to prevent bypass |
 | **Timing-Safe Auth** | `crypto.timingSafeEqual()` for token comparison |
-| **Origin Validation** | `/extension` requires `chrome-extension://` origin; `/ops`, `/cdp`, `/annotation`, and `/config`/`/status`/`/pair` allow loopback no-Origin requests |
+| **Origin Validation** | `/extension` requires `chrome-extension://` origin; `/ops`, `/canvas`, `/cdp`, `/annotation`, and `/config`/`/status`/`/pair` allow loopback no-Origin requests |
 | **PNA Preflights** | HTTP preflights include `Access-Control-Allow-Private-Network: true` when requested |
 | **Rate Limiting** | 5 handshake attempts/minute per IP, plus HTTP rate limiting for `/config`, `/status`, `/pair` |
 | **Data Redaction** | Tokens, API keys, sensitive paths auto-redacted |
@@ -752,17 +766,18 @@ Tool Call → Zod Validation → Manager/Runner → CDP/Playwright → Response
 │   ├── cache/        # Chrome executable resolution
 │   ├── cli/          # CLI commands, daemon, installers
 │   ├── core/         # Bootstrap, runtime wiring, ToolDeps
+│   ├── canvas/       # Design-canvas document store, repo IO, export helpers
 │   ├── devtools/     # Console/network trackers with redaction
 │   ├── export/       # DOM capture, React emitter, CSS extraction
 │   ├── relay/        # Extension relay server, protocol types
 │   ├── skills/       # SkillLoader for skill pack discovery
 │   ├── snapshot/     # AX-tree snapshots, ref management
-│   ├── tools/        # 48 opendevbrowser_* tool definitions
+│   ├── tools/        # 49 opendevbrowser_* tool definitions
 │   ├── annotate/     # Annotation transports + output shaping
 │   └── utils/        # Shared utilities
 ├── extension/        # Chrome extension (relay client)
 ├── scripts/          # Operational scripts (build/sync/smoke)
-├── skills/           # Bundled skill packs (8 total)
+├── skills/           # Bundled skill directories (10 total; 8 canonical OpenDevBrowser packs + 2 shared compatibility packs)
 ├── tests/            # Vitest tests (97% coverage required)
 └── docs/             # Architecture, CLI, extension, distribution plans
 ```