opendevbrowser 0.0.16 → 0.0.17

package/extension/dist/services/RelayClient.js

@@ -98,6 +98,9 @@ export class RelayClient {
                         this.handlers.onOpsMessage?.(record);
                         return;
                     }
+                    if (isCanvasEnvelope(record)) {
+                        this.handlers.onCanvasMessage?.(record);
+                    }
                 });
                 this.socket.addEventListener("close", (event) => {
                     if (this.pendingHandshakeAckReject) {
@@ -181,6 +184,9 @@ export class RelayClient {
     sendOpsMessage(message) {
         this.send(message);
     }
+    sendCanvasMessage(message) {
+        this.send(message);
+    }
     async sendHealthCheck(timeoutMs = 1500) {
         return await this.sendPing(timeoutMs);
     }
@@ -272,3 +278,6 @@ const isValidPong = (value) => {
 const isOpsEnvelope = (value) => {
     return typeof value.type === "string" && value.type.startsWith("ops_");
 };
+const isCanvasEnvelope = (value) => {
+    return typeof value.type === "string" && value.type.startsWith("canvas_");
+};

package/extension/dist/services/TabManager.js

@@ -16,33 +16,56 @@ export class TabManager {
         });
     }
     async waitForTabComplete(tabId, timeoutMs = 10000) {
-        const existing = await this.getTab(tabId);
-        if (existing?.status === "complete") {
+        const isComplete = async () => {
+            const current = await this.getTab(tabId);
+            return current?.status === "complete";
+        };
+        if (await isComplete()) {
             return;
         }
         await new Promise((resolve, reject) => {
             let settled = false;
-            const timeoutId = setTimeout(() => {
+            let pollId = null;
+            const settle = (error) => {
                 if (settled)
                     return;
                 settled = true;
+                clearTimeout(timeoutId);
+                if (pollId !== null) {
+                    clearInterval(pollId);
+                }
                 chrome.tabs.onUpdated.removeListener(listener);
-                reject(new Error("Tab load timeout"));
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            };
+            const timeoutId = setTimeout(() => {
+                settle(new Error("Tab load timeout"));
             }, timeoutMs);
-            const listener = (updatedId, changeInfo) => {
+            const listener = (updatedId, changeInfo, tab) => {
                 if (updatedId !== tabId) {
                     return;
                 }
-                if (changeInfo.status === "complete") {
-                    if (settled)
-                        return;
-                    settled = true;
-                    clearTimeout(timeoutId);
-                    chrome.tabs.onUpdated.removeListener(listener);
-                    resolve();
+                if (changeInfo.status === "complete" || tab?.status === "complete") {
+                    settle();
                 }
             };
             chrome.tabs.onUpdated.addListener(listener);
+            const poll = () => {
+                void isComplete()
+                    .then((complete) => {
+                    if (complete) {
+                        settle();
+                    }
+                })
+                    .catch(() => {
+                    // Ignore transient tab lookup failures and let the timeout decide.
+                });
+            };
+            pollId = setInterval(poll, Math.min(250, Math.max(50, Math.floor(timeoutMs / 20))));
+            poll();
         });
     }
     async closeTab(tabId) {

package/extension/dist/types.js

@@ -1,3 +1,5 @@
 export const OPS_PROTOCOL_VERSION = "1";
 export const MAX_OPS_PAYLOAD_BYTES = 12 * 1024 * 1024;
 export const MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+export const CANVAS_PROTOCOL_VERSION = "1";
+export const MAX_CANVAS_PAYLOAD_BYTES = 12 * 1024 * 1024;

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenDevBrowser Relay",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Optional bridge to reuse existing Chrome tabs with OpenDevBrowser.",
   "permissions": [
     "debugger",

package/extension/popup.html

@@ -376,6 +376,51 @@
         gap: 10px;
       }
 
+      .annotation-list {
+        display: grid;
+        gap: 8px;
+        margin-top: 10px;
+        max-height: 180px;
+        overflow: auto;
+      }
+
+      .annotation-item {
+        display: grid;
+        gap: 8px;
+        padding: 10px;
+        border-radius: 12px;
+        border: 1px solid var(--stroke);
+        background: var(--panel-strong);
+      }
+
+      .annotation-item-summary {
+        font-size: 11px;
+        color: var(--text);
+        line-height: 1.4;
+        word-break: break-word;
+      }
+
+      .annotation-item-meta {
+        font-size: 10px;
+        color: var(--muted);
+      }
+
+      .annotation-item-actions {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 8px;
+      }
+
+      .annotation-empty {
+        font-size: 10px;
+        color: var(--muted);
+        text-align: center;
+        padding: 12px;
+        border-radius: 12px;
+        border: 1px dashed var(--stroke);
+        background: rgba(255, 255, 255, 0.03);
+      }
+
       @media (prefers-reduced-motion: reduce) {
         * {
           transition: none !important;
@@ -503,6 +548,13 @@
           <button id="annotationStart" class="secondary">Annotate</button>
           <button id="annotationCopy" class="secondary" disabled>Copy payload</button>
         </div>
+        <div class="button-row">
+          <button id="annotationSend" class="secondary" disabled>Send to agent</button>
+          <button id="annotationRefresh" class="secondary">Refresh payload</button>
+        </div>
+        <div id="annotationItems" class="annotation-list">
+          <div class="annotation-empty">No annotation items available.</div>
+        </div>
       </section>
 
       <button id="toggle" class="primary">Connect</button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendevbrowser",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "OpenCode plugin for browser automation via CDP with snapshot-refs-actions workflow",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "dist",
     "skills",
     "scripts/native",
+    "extension/canvas.html",
     "extension/manifest.json",
     "extension/popup.html",
     "extension/dist",
@@ -41,7 +42,7 @@
     "dev": "tsup src/index.ts src/cli/index.ts --format esm --dts --watch",
     "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run --coverage",
+    "test": "node --input-type=module -e \"import { mkdirSync } from 'node:fs'; mkdirSync('coverage/.tmp', { recursive: true });\" && vitest run --coverage",
     "test:release-gate": "node scripts/release-gate-test-groups.mjs",
     "test:release-gate:g1": "node scripts/release-gate-test-groups.mjs --group 1",
     "test:release-gate:g2": "node scripts/release-gate-test-groups.mjs --group 2",
@@ -50,7 +51,7 @@
     "test:release-gate:g5": "node scripts/release-gate-test-groups.mjs --group 5",
     "extension:sync": "node scripts/sync-extension-version.mjs",
     "extension:build": "npm run extension:sync && tsc -p extension/tsconfig.json && node scripts/copy-extension-assets.mjs",
-    "extension:pack": "cd extension && zip -r ../opendevbrowser-extension.zip manifest.json popup.html dist/ icons/",
+    "extension:pack": "cd extension && zip -r ../opendevbrowser-extension.zip manifest.json popup.html canvas.html dist/ icons/",
     "extension:store": "node scripts/chrome-store-publish.mjs",
     "version:check": "node scripts/verify-versions.mjs",
     "prepack": "npm run version:check && npm run build && npm run extension:build"
@@ -61,7 +62,9 @@
     "async-mutex": "^0.5.0",
     "jsonc-parser": "^3.2.0",
     "playwright-core": "^1.58.2",
+    "typescript": "^5.9.3",
     "ws": "^8.19.0",
+    "yjs": "^13.6.29",
     "zod": "^3.25.76"
   },
   "devDependencies": {
@@ -74,7 +77,6 @@
     "eslint": "^9.39.3",
     "happy-dom": "^20.7.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
 }

package/skills/AGENTS.md

@@ -1,6 +1,6 @@
 # skills/ — Agent Guidelines
 
-Bundled canonical skill packs (8 total). Extends root `AGENTS.md`.
+Bundled canonical OpenDevBrowser skill packs (8 total) plus shared compatibility dirs (`research/`, `shopping/`). Extends root `AGENTS.md`.
 
 ## Structure
 
@@ -13,7 +13,9 @@ skills/
 ├── opendevbrowser-data-extraction/SKILL.md
 ├── opendevbrowser-research/SKILL.md
 ├── opendevbrowser-shopping/SKILL.md
-└── opendevbrowser-product-presentation-asset/SKILL.md
+├── opendevbrowser-product-presentation-asset/SKILL.md
+├── research/      # Empty compatibility alias dir; keep non-canonical
+└── shopping/      # Empty compatibility alias dir; keep non-canonical
 ```
 
 ## SKILL.md Format
@@ -50,6 +52,7 @@ Content organized by topic for filtering.
 - Examples must use `opendevbrowser_*` tool names
 - Never include secrets or page data in content
 - Keep canonical guidance in `opendevbrowser-*` packs; do not add legacy alias directories.
+- Leave `skills/research/` and `skills/shopping/` empty unless a verified migration plan explicitly repurposes them.
 - Match the snapshot → refs → actions flow in `docs/ARCHITECTURE.md` and tool list in `docs/CLI.md`.
 - Note that extension relay requires Chrome 125+ and uses hub-only relay ownership when enabled.
 - Refer to root `AGENTS.md` for connection flag/status semantics (extensionConnected, handshake, cdpConnected, pairingRequired).

package/skills/opendevbrowser-best-practices/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: opendevbrowser-best-practices
 description: This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
-version: 2.3.0
+version: 2.5.0
 ---
 
 # OpenDevBrowser Best Practices
@@ -23,12 +23,17 @@ Use this skill when you need:
 - `artifacts/fingerprint-tiers.md` — hardening tiers and when to use each.
 - `artifacts/macro-workflows.md` — macro design and expansion standards.
 - `artifacts/browser-agent-known-issues-matrix.md` — known browser-agent failure modes mapped to required controls.
-- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/canvas`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `artifacts/canvas-governance-playbook.md` — `/canvas` preflight, blocker, and feedback-evaluation guidance.
 - `assets/templates/mode-flag-matrix.json` — mode + flag verification template.
 - `assets/templates/ops-request-envelope.json` — `/ops` request envelope template.
 - `assets/templates/cdp-forward-envelope.json` — `/cdp` relay envelope template.
 - `assets/templates/robustness-checklist.json` — shared issue-status checklist for workflow robustness audits.
 - `assets/templates/surface-audit-checklist.json` — docs/surface audit checklist template.
+- `assets/templates/canvas-handshake-example.json` — canonical `/canvas` handshake example.
+- `assets/templates/canvas-generation-plan.v1.json` — required `canvas.plan.set` request skeleton.
+- `assets/templates/canvas-feedback-eval.json` — target-attributed feedback evaluation checklist.
+- `assets/templates/canvas-blocker-checklist.json` — machine-readable blocker and warning audit map.
 - `scripts/odb-workflow.sh` — prints codified command sequences by workflow.
 - `scripts/run-robustness-audit.sh` — validates workflow skill coverage against known issue IDs.
 - `scripts/validate-skill-assets.sh` — validates required artifacts/templates.
@@ -53,6 +58,7 @@ Use this skill when you need:
 
 ```bash
 npx opendevbrowser --help
+npx opendevbrowser help
 ```
 
 5. Run robustness coverage checks across workflow skills:
@@ -170,6 +176,8 @@ Use the router script to avoid retyping flows:
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh mode-flag-matrix
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh robustness-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
 ```
 
 ## Modes and Surface Parity
@@ -194,9 +202,69 @@ node scripts/provider-live-matrix.mjs --use-global-env --skip-live-regression --
 ```
 
 Surface inventory source of truth:
-- `docs/SURFACE_REFERENCE.md` (55 CLI commands, 48 tools, 38 `/ops` commands, `/cdp` envelope contracts)
+- `docs/SURFACE_REFERENCE.md` (56 CLI commands, 49 tools, 38 `/ops` commands, 26 `/canvas` commands, `/cdp` envelope contracts; mirrored by `npx opendevbrowser --help` and `npx opendevbrowser help`)
 - `artifacts/command-channel-reference.md` (skill-pack operational digest)
 
+## Canvas Governance Handshake
+
+Use the design-canvas surface when the workflow needs persisted design documents, explicit governance state, preview tabs, or overlay selection.
+
+Recommended command order:
+1. `opendevbrowser_canvas` or `opendevbrowser canvas --command canvas.session.open` to get `canvasSessionId`, `leaseId`, `preflightState`, governance block states, and generation-plan requirements.
+2. Read the handshake before mutating. The handshake is the source of truth for:
+   - `governanceRequirements.requiredBeforeMutation`
+   - `governanceRequirements.requiredBeforeSave`
+   - `generationPlanRequirements.requiredBeforeMutation`
+   - `allowedLibraries`
+   - `mutationPolicy.allowedBeforePlan`
+   - treat `allowedLibraries.components`, `allowedLibraries.icons`, and `allowedLibraries.styling` as separate policy lanes:
+     `components` are reusable UI adapters such as `shadcn`,
+     `icons` are approved icon families,
+     `styling` is for utility/theme adapters such as `tailwindcss`
+3. Submit `canvas.plan.set` with all required non-empty objects:
+   - `targetOutcome`
+   - `visualDirection`
+   - `layoutStrategy`
+   - `contentStrategy`
+   - `componentStrategy`
+   - `motionPosture`
+   - `responsivePosture`
+   - `accessibilityPosture`
+   - `validationTargets`
+4. Only after the plan is accepted, call `canvas.document.patch`.
+5. Use `canvas.preview.render`, `canvas.tab.open`, `canvas.overlay.mount`, and `canvas.overlay.select` when a browser-backed live view is required.
+6. Use `canvas.feedback.poll` between mutation rounds and `canvas.document.save` or `canvas.document.export` to persist artifacts.
+
+Code-sync surface:
+- `canvas.session.attach` joins an existing canvas session as an `observer` or reclaims the write lease with `attachMode=lease_reclaim`.
+- `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, and `canvas.code.resolve` manage TSX-first document bindings when a canvas file is round-tripped to repo code.
+
+Current `/canvas` parity notes:
+- All 26 public `canvas.*` commands are agent-callable through `opendevbrowser_canvas` and `opendevbrowser canvas --command ...`.
+- `canvas.feedback.subscribe` live streaming is public through the CLI only: use `--output-format stream-json` for the built-in polling bridge.
+- Tool-driven agents can achieve the same behavior by calling `canvas.feedback.subscribe` once and then looping on `canvas.feedback.poll` with the returned cursor.
+- `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers, not public commands.
+- `canvas_html` is still the default preview/export contract. `bound_app_runtime` is opt-in and only valid when runtime preflight and app-side instrumentation succeed.
+- Component and icon libraries currently render semantically, not package-faithfully. Treat `shadcn`, `tailwindcss`, `tabler`, `microsoft-fluent-ui-system-icons`, `3dicons`, and `@lobehub/fluent-emoji-3d` as metadata and constrained render lanes, not as general library import/export parity.
+- Annotation remains a separate surface today, but popup and canvas both ship per-item and combined `Copy` / `Send` actions. The remaining gap is that `Send` persists payloads for later `annotate --stored` retrieval instead of proactively injecting them into the active agent chat.
+
+Tailwind usage rule:
+- When `allowedLibraries.styling` includes `tailwindcss`, use it for layout, spacing, responsive, and state styling over canonical tokens/theme variables.
+- Do not treat Tailwind as a component inventory source or mix it into `componentStrategy.approvedLibraries`.
+- Preview/export should materialize a deterministic utility-class layer and stay self-contained; do not depend on a remote Tailwind CDN for canvas preview correctness.
+
+Failure handling:
+- `plan_required`: immediately call `canvas.plan.set`.
+- `revision_conflict`: reload with `canvas.document.load` and replay the patch batch against the latest revision.
+- `unsupported_target` or `restricted_url`: move the preview to a normal http(s) tab or fall back to managed mode.
+
+Operational references:
+- `artifacts/canvas-governance-playbook.md`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`
+
 ## Diagnostics and Traceability
 
 Current diagnostics tools:

package/skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md

@@ -0,0 +1,141 @@
+# Canvas Governance Playbook
+
+## Purpose
+
+Use this playbook before any `/canvas` mutation and during every design-feedback loop. It keeps the runtime handshake, governance state, and evaluation rules aligned with the design-canvas spec.
+
+## Required command order
+
+1. `canvas.session.open`
+2. Read the handshake and confirm `preflightState: "handshake_read"`
+3. `canvas.plan.set`
+4. `canvas.plan.get` or `canvas.capabilities.get` until the runtime reports `plan_accepted`
+5. `canvas.document.patch`
+6. `canvas.preview.render` or `canvas.tab.open`
+7. `canvas.feedback.poll`
+8. `canvas.document.save` or `canvas.document.export`
+
+Mutation is blocked until the handshake has been read and the plan is accepted. A save is still invalid when required governance blocks remain missing in `requiredBeforeSave`.
+
+## Handshake requirements
+
+Every `canvas.session.open` response is the runtime contract. Read these fields before sending a patch:
+
+- `canvasSessionId`
+- `browserSessionId`
+- `documentId`
+- `leaseId`
+- `preflightState`
+- `governanceRequirements.requiredBeforeMutation`
+- `governanceRequirements.requiredBeforeSave`
+- `generationPlanRequirements.requiredBeforeMutation`
+- `allowedLibraries`
+- `allowedBeforePlan`
+
+Interpret `allowedLibraries` by lane:
+- `components` are reusable UI adapters such as `shadcn`
+- `icons` are approved icon families
+- `styling` is for utility/theme adapters such as `tailwindcss`
+- do not mix icon or styling libraries into `componentStrategy.approvedLibraries`
+
+Preflight states:
+- `handshake_read`
+- `plan_submitted`
+- `plan_accepted`
+- `patching_enabled`
+
+## Governance blocks
+
+The document must declare `designGovernance` with at least:
+
+- `intent`
+- `designLanguage`
+- `contentModel`
+- `layoutSystem`
+- `typographySystem`
+- `colorSystem`
+- `surfaceSystem`
+- `iconSystem`
+- `motionSystem`
+- `responsiveSystem`
+- `accessibilityPolicy`
+- `libraryPolicy`
+- `runtimeBudgets`
+
+The first accepted `generationPlan` must include:
+
+- `targetOutcome`
+- `visualDirection`
+- `layoutStrategy`
+- `contentStrategy`
+- `componentStrategy`
+- `motionPosture`
+- `responsivePosture`
+- `accessibilityPosture`
+- `validationTargets`
+
+## Blocker handling
+
+Canonical blocker path:
+
+```json
+{
+  "code": "plan_required",
+  "blockingCommand": "canvas.document.patch",
+  "requiredNextCommands": ["canvas.plan.set"],
+  "details": { "auditId": "CANVAS-01" }
+}
+```
+
+If `canvas.document.patch` or `canvas.document.save` returns a blocker, stop mutating and fix the missing handshake, governance, or plan requirement before retrying.
+
+## Canvas robustness issue classes
+
+| Audit ID | Failure class | Typical signal | Required response |
+|---|---|---|---|
+| `CANVAS-01` | Handshake missing or unread before mutation | `plan_required`, missing `handshake_read` evidence | Re-run `canvas.session.open` or `canvas.capabilities.get`, then `canvas.plan.set` |
+| `CANVAS-02` | Required governance block missing | save blocker, empty `requiredBeforeSave`, validation warning | Fill missing `designGovernance.*` fields before save/export |
+| `CANVAS-03` | Required `generationPlan` field missing or malformed | `canvas.plan.set` rejected or warnings retained | Submit a complete plan and wait for acceptance |
+| `CANVAS-04` | Library or icon-policy violation | validation warning, policy blocker, downgraded export | Adjust component/library choice to match `libraryPolicy` and `iconSystem` |
+| `CANVAS-05` | Unsupported target or overlay mount failure | `unsupported_target`, `restricted_url`, overlay mount error | Move to a normal http(s) preview target or managed mode |
+| `CANVAS-06` | Runtime budget exceeded or preview downgrade ignored | degrade warning, overflowed media/fonts/telemetry budget | Reduce preview cost or accept the downgrade before proceeding |
+| `CANVAS-07` | Feedback missing target attribution or validation metadata | feedback lacks `targetId`, `pageId`, `class`, or `evidenceRefs` | Re-poll or fix the feedback source before trusting the result |
+
+## Feedback evaluation loop
+
+Required categories:
+
+- `render`
+- `console`
+- `network`
+- `validation`
+- `performance`
+- `asset`
+- `export`
+
+Required fields per feedback item:
+
+- `documentId`
+- `pageId`
+- `prototypeId`
+- `targetId`
+- `documentRevision`
+- `severity`
+- `class`
+- `message`
+- `evidenceRefs`
+
+Streaming checks:
+
+- `feedback.item` carries the canonical feedback payload
+- `feedback.heartbeat` proves the subscription is still alive
+- `feedback.complete` explains why the stream ended
+
+## Router and template references
+
+- `scripts/odb-workflow.sh canvas-preflight`
+- `scripts/odb-workflow.sh canvas-feedback-eval`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`