opendevbrowser 0.0.16 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/README.md +51 -27
  2. package/dist/browser/annotation-manager.d.ts +3 -0
  3. package/dist/browser/annotation-manager.d.ts.map +1 -1
  4. package/dist/browser/browser-manager.d.ts +6 -1
  5. package/dist/browser/browser-manager.d.ts.map +1 -1
  6. package/dist/browser/canvas-client.d.ts +53 -0
  7. package/dist/browser/canvas-client.d.ts.map +1 -0
  8. package/dist/browser/canvas-code-sync-manager.d.ts +79 -0
  9. package/dist/browser/canvas-code-sync-manager.d.ts.map +1 -0
  10. package/dist/browser/canvas-manager.d.ts +94 -0
  11. package/dist/browser/canvas-manager.d.ts.map +1 -0
  12. package/dist/browser/canvas-runtime-preview-bridge.d.ts +20 -0
  13. package/dist/browser/canvas-runtime-preview-bridge.d.ts.map +1 -0
  14. package/dist/browser/canvas-session-sync-manager.d.ts +21 -0
  15. package/dist/browser/canvas-session-sync-manager.d.ts.map +1 -0
  16. package/dist/browser/manager-types.d.ts +13 -1
  17. package/dist/browser/manager-types.d.ts.map +1 -1
  18. package/dist/browser/ops-browser-manager.d.ts +11 -1
  19. package/dist/browser/ops-browser-manager.d.ts.map +1 -1
  20. package/dist/canvas/code-sync/apply-tsx.d.ts +23 -0
  21. package/dist/canvas/code-sync/apply-tsx.d.ts.map +1 -0
  22. package/dist/canvas/code-sync/graph.d.ts +5 -0
  23. package/dist/canvas/code-sync/graph.d.ts.map +1 -0
  24. package/dist/canvas/code-sync/hash.d.ts +3 -0
  25. package/dist/canvas/code-sync/hash.d.ts.map +1 -0
  26. package/dist/canvas/code-sync/import.d.ts +18 -0
  27. package/dist/canvas/code-sync/import.d.ts.map +1 -0
  28. package/dist/canvas/code-sync/manifest.d.ts +5 -0
  29. package/dist/canvas/code-sync/manifest.d.ts.map +1 -0
  30. package/dist/canvas/code-sync/tsx-adapter.d.ts +8 -0
  31. package/dist/canvas/code-sync/tsx-adapter.d.ts.map +1 -0
  32. package/dist/canvas/code-sync/types.d.ts +152 -0
  33. package/dist/canvas/code-sync/types.d.ts.map +1 -0
  34. package/dist/canvas/code-sync/write.d.ts +9 -0
  35. package/dist/canvas/code-sync/write.d.ts.map +1 -0
  36. package/dist/canvas/document-store.d.ts +81 -0
  37. package/dist/canvas/document-store.d.ts.map +1 -0
  38. package/dist/canvas/export.d.ts +12 -0
  39. package/dist/canvas/export.d.ts.map +1 -0
  40. package/dist/canvas/repo-store.d.ts +10 -0
  41. package/dist/canvas/repo-store.d.ts.map +1 -0
  42. package/dist/canvas/surface-palette.d.ts +15 -0
  43. package/dist/canvas/surface-palette.d.ts.map +1 -0
  44. package/dist/canvas/types.d.ts +255 -0
  45. package/dist/canvas/types.d.ts.map +1 -0
  46. package/dist/canvas-runtime-preview-bridge-HBEHXM4T.js +7 -0
  47. package/dist/canvas-runtime-preview-bridge-HBEHXM4T.js.map +1 -0
  48. package/dist/{chunk-ST7CO5FA.js → chunk-5J3IFL3X.js} +11577 -13539
  49. package/dist/chunk-5J3IFL3X.js.map +1 -0
  50. package/dist/chunk-D633UO34.js +8149 -0
  51. package/dist/chunk-D633UO34.js.map +1 -0
  52. package/dist/{chunk-7W3SPXIB.js → chunk-FUSXMW3G.js} +4 -1
  53. package/dist/chunk-TBUCZX4A.js +34 -0
  54. package/dist/chunk-TBUCZX4A.js.map +1 -0
  55. package/dist/chunk-V7KUDHDG.js +276 -0
  56. package/dist/chunk-V7KUDHDG.js.map +1 -0
  57. package/dist/chunk-Y2KL55OG.js +59 -0
  58. package/dist/chunk-Y2KL55OG.js.map +1 -0
  59. package/dist/cli/args.d.ts +3 -3
  60. package/dist/cli/args.d.ts.map +1 -1
  61. package/dist/cli/commands/annotate.d.ts +11 -0
  62. package/dist/cli/commands/annotate.d.ts.map +1 -1
  63. package/dist/cli/commands/canvas.d.ts +45 -0
  64. package/dist/cli/commands/canvas.d.ts.map +1 -0
  65. package/dist/cli/commands/devtools/perf.d.ts.map +1 -1
  66. package/dist/cli/commands/devtools/screenshot.d.ts +1 -0
  67. package/dist/cli/commands/devtools/screenshot.d.ts.map +1 -1
  68. package/dist/cli/commands/dom/attr.d.ts.map +1 -1
  69. package/dist/cli/commands/dom/checked.d.ts.map +1 -1
  70. package/dist/cli/commands/dom/enabled.d.ts.map +1 -1
  71. package/dist/cli/commands/dom/html.d.ts.map +1 -1
  72. package/dist/cli/commands/dom/text.d.ts.map +1 -1
  73. package/dist/cli/commands/dom/value.d.ts.map +1 -1
  74. package/dist/cli/commands/dom/visible.d.ts.map +1 -1
  75. package/dist/cli/commands/export/clone-component.d.ts +9 -0
  76. package/dist/cli/commands/export/clone-component.d.ts.map +1 -1
  77. package/dist/cli/commands/export/clone-page.d.ts +8 -0
  78. package/dist/cli/commands/export/clone-page.d.ts.map +1 -1
  79. package/dist/cli/commands/interact/check.d.ts.map +1 -1
  80. package/dist/cli/commands/interact/click.d.ts.map +1 -1
  81. package/dist/cli/commands/interact/hover.d.ts.map +1 -1
  82. package/dist/cli/commands/interact/press.d.ts.map +1 -1
  83. package/dist/cli/commands/interact/scroll-into-view.d.ts.map +1 -1
  84. package/dist/cli/commands/interact/scroll.d.ts.map +1 -1
  85. package/dist/cli/commands/interact/select.d.ts.map +1 -1
  86. package/dist/cli/commands/interact/type.d.ts.map +1 -1
  87. package/dist/cli/commands/interact/uncheck.d.ts.map +1 -1
  88. package/dist/cli/commands/native.d.ts +12 -1
  89. package/dist/cli/commands/native.d.ts.map +1 -1
  90. package/dist/cli/commands/nav/goto.d.ts.map +1 -1
  91. package/dist/cli/commands/nav/snapshot.d.ts.map +1 -1
  92. package/dist/cli/commands/nav/wait.d.ts.map +1 -1
  93. package/dist/cli/commands/serve.d.ts +5 -0
  94. package/dist/cli/commands/serve.d.ts.map +1 -1
  95. package/dist/cli/commands/session/connect.d.ts.map +1 -1
  96. package/dist/cli/commands/status.d.ts +5 -0
  97. package/dist/cli/commands/status.d.ts.map +1 -1
  98. package/dist/cli/daemon-commands.d.ts.map +1 -1
  99. package/dist/cli/help.d.ts +5 -0
  100. package/dist/cli/help.d.ts.map +1 -1
  101. package/dist/cli/index.js +724 -163
  102. package/dist/cli/index.js.map +1 -1
  103. package/dist/cli/remote-canvas-manager.d.ts +8 -0
  104. package/dist/cli/remote-canvas-manager.d.ts.map +1 -0
  105. package/dist/cli/remote-manager.d.ts +3 -1
  106. package/dist/cli/remote-manager.d.ts.map +1 -1
  107. package/dist/cli/remote-relay.d.ts +2 -0
  108. package/dist/cli/remote-relay.d.ts.map +1 -1
  109. package/dist/cli/utils/parse.d.ts +1 -0
  110. package/dist/cli/utils/parse.d.ts.map +1 -1
  111. package/dist/core/bootstrap.d.ts.map +1 -1
  112. package/dist/core/types.d.ts +2 -0
  113. package/dist/core/types.d.ts.map +1 -1
  114. package/dist/fs-UMRKOBNN.js +7 -0
  115. package/dist/fs-UMRKOBNN.js.map +1 -0
  116. package/dist/index.d.ts.map +1 -1
  117. package/dist/index.js +192 -67
  118. package/dist/index.js.map +1 -1
  119. package/dist/{macros-NUBRM44Y.js → macros-ND2M7LWU.js} +2 -2
  120. package/dist/opendevbrowser.d.ts.map +1 -1
  121. package/dist/opendevbrowser.js +192 -67
  122. package/dist/opendevbrowser.js.map +1 -1
  123. package/dist/providers/index.d.ts.map +1 -1
  124. package/dist/providers/shopping/index.d.ts.map +1 -1
  125. package/dist/providers-G3LRHQXX.js +121 -0
  126. package/dist/providers-G3LRHQXX.js.map +1 -0
  127. package/dist/relay/protocol.d.ts +85 -3
  128. package/dist/relay/protocol.d.ts.map +1 -1
  129. package/dist/relay/relay-server.d.ts +14 -1
  130. package/dist/relay/relay-server.d.ts.map +1 -1
  131. package/dist/relay/relay-types.d.ts +3 -0
  132. package/dist/relay/relay-types.d.ts.map +1 -1
  133. package/dist/runtime-factory-BICHDPE7.js +13 -0
  134. package/dist/runtime-factory-BICHDPE7.js.map +1 -0
  135. package/dist/tools/annotate.d.ts.map +1 -1
  136. package/dist/tools/canvas.d.ts +4 -0
  137. package/dist/tools/canvas.d.ts.map +1 -0
  138. package/dist/tools/check.d.ts.map +1 -1
  139. package/dist/tools/click.d.ts.map +1 -1
  140. package/dist/tools/clone_component.d.ts.map +1 -1
  141. package/dist/tools/clone_page.d.ts.map +1 -1
  142. package/dist/tools/connect.d.ts.map +1 -1
  143. package/dist/tools/deps.d.ts +2 -0
  144. package/dist/tools/deps.d.ts.map +1 -1
  145. package/dist/tools/dom_get_html.d.ts.map +1 -1
  146. package/dist/tools/dom_get_text.d.ts.map +1 -1
  147. package/dist/tools/get_attr.d.ts.map +1 -1
  148. package/dist/tools/get_value.d.ts.map +1 -1
  149. package/dist/tools/goto.d.ts.map +1 -1
  150. package/dist/tools/hover.d.ts.map +1 -1
  151. package/dist/tools/index.d.ts.map +1 -1
  152. package/dist/tools/is_checked.d.ts.map +1 -1
  153. package/dist/tools/is_enabled.d.ts.map +1 -1
  154. package/dist/tools/is_visible.d.ts.map +1 -1
  155. package/dist/tools/launch.d.ts.map +1 -1
  156. package/dist/tools/macro_resolve.d.ts.map +1 -1
  157. package/dist/tools/perf.d.ts.map +1 -1
  158. package/dist/tools/press.d.ts.map +1 -1
  159. package/dist/tools/product_video_run.d.ts.map +1 -1
  160. package/dist/tools/research_run.d.ts.map +1 -1
  161. package/dist/tools/response.d.ts +4 -1
  162. package/dist/tools/response.d.ts.map +1 -1
  163. package/dist/tools/screenshot.d.ts.map +1 -1
  164. package/dist/tools/scroll.d.ts.map +1 -1
  165. package/dist/tools/scroll_into_view.d.ts.map +1 -1
  166. package/dist/tools/select.d.ts.map +1 -1
  167. package/dist/tools/shopping_run.d.ts.map +1 -1
  168. package/dist/tools/snapshot.d.ts.map +1 -1
  169. package/dist/tools/type.d.ts.map +1 -1
  170. package/dist/tools/uncheck.d.ts.map +1 -1
  171. package/dist/tools/wait.d.ts.map +1 -1
  172. package/dist/tools/workflow-runtime.d.ts +1 -2
  173. package/dist/tools/workflow-runtime.d.ts.map +1 -1
  174. package/extension/canvas.html +636 -0
  175. package/extension/dist/annotate-content.css +15 -6
  176. package/extension/dist/annotate-content.js +119 -9
  177. package/extension/dist/annotation-payload.js +163 -0
  178. package/extension/dist/background.js +148 -18
  179. package/extension/dist/canvas/canvas-runtime.js +1061 -0
  180. package/extension/dist/canvas/model.js +213 -0
  181. package/extension/dist/canvas/viewport-fit.js +67 -0
  182. package/extension/dist/canvas-page.js +1801 -0
  183. package/extension/dist/ops/dom-bridge.js +116 -3
  184. package/extension/dist/ops/ops-runtime.js +508 -44
  185. package/extension/dist/ops/ops-session-store.js +21 -114
  186. package/extension/dist/ops/target-session-coordinator.js +157 -0
  187. package/extension/dist/popup.js +155 -31
  188. package/extension/dist/services/ConnectionManager.js +17 -0
  189. package/extension/dist/services/RelayClient.js +9 -0
  190. package/extension/dist/services/TabManager.js +35 -12
  191. package/extension/dist/types.js +2 -0
  192. package/extension/manifest.json +1 -1
  193. package/extension/popup.html +52 -0
  194. package/package.json +6 -4
  195. package/skills/AGENTS.md +5 -2
  196. package/skills/opendevbrowser-best-practices/SKILL.md +71 -3
  197. package/skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md +141 -0
  198. package/skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md +113 -17
  199. package/skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json +70 -0
  200. package/skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json +73 -0
  201. package/skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json +67 -0
  202. package/skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json +126 -0
  203. package/skills/opendevbrowser-best-practices/assets/templates/robustness-checklist.json +57 -0
  204. package/skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json +7 -3
  205. package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh +26 -0
  206. package/skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh +82 -1
  207. package/skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh +225 -84
  208. package/dist/chunk-ST7CO5FA.js.map +0 -1
  209. /package/dist/{chunk-7W3SPXIB.js.map → chunk-FUSXMW3G.js.map} +0 -0
  210. /package/dist/{macros-NUBRM44Y.js.map → macros-ND2M7LWU.js.map} +0 -0
@@ -2,21 +2,22 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- Provide a compact, operationally useful map of OpenDevBrowser command surfaces and relay channels for parity checks.
5
+ Compact operational map of the current OpenDevBrowser surfaces, with the `/canvas` handshake and blocker paths called out explicitly for preflight audits.
6
6
 
7
7
  ## Current coverage snapshot
8
8
 
9
- - CLI commands: `55`
10
- - Plugin tools: `48`
9
+ - CLI commands: `56`
10
+ - Plugin tools: `49`
11
11
  - `/ops` command names: `38`
12
+ - `/canvas` command names: `26`
12
13
  - Legacy `/cdp` relay: generic CDP forwarding (method-level)
13
14
 
14
15
  Canonical exhaustive reference: `docs/SURFACE_REFERENCE.md`.
15
- CLI help mirror: `npx opendevbrowser --help` (surfaces CLI + tools + `/ops` + `/cdp` controls).
16
+ CLI help mirror: `npx opendevbrowser --help` and `npx opendevbrowser help` (identical inventories).
16
17
 
17
18
  ## Agent skill-sync coverage
18
19
 
19
- Skill-pack installation/discovery is synchronized for:
20
+ Skill-pack installation and discovery are synchronized for:
20
21
  - `opencode`: `~/.config/opencode/skill` and `./.opencode/skill`
21
22
  - `codex`: `$CODEX_HOME/skills` (fallback `~/.codex/skills`) and `./.codex/skills`
22
23
  - `claudecode`: `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
@@ -26,17 +27,16 @@ Legacy aliases `claude` and `amp` remain present in installer target metadata fo
26
27
 
27
28
  ## CLI surface categories
28
29
 
29
- - Install/runtime: install, update, uninstall, help, version, serve, daemon, native, run
30
- - Session/connection: launch, connect, disconnect, status, cookie-import, cookie-list
31
- - Navigation: goto, wait, snapshot
32
- - Interaction: click, hover, press, check, uncheck, type, select, scroll, scroll-into-view
33
- - Targets/pages: targets-list, target-use, target-new, target-close, page, pages, page-close
34
- - DOM: dom-html, dom-text, dom-attr, dom-value, dom-visible, dom-enabled, dom-checked
35
- - Export/diagnostics/macro/annotation/power: clone-page, clone-component, perf, screenshot, console-poll, network-poll, debug-trace-snapshot, macro-resolve, annotate, rpc
30
+ - Install/runtime: `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `run`, `artifacts`
31
+ - Session/connection/workflow: `launch`, `connect`, `disconnect`, `status`, `cookie-import`, `cookie-list`, `research`, `shopping`, `product-video`
32
+ - Navigation/interaction: `goto`, `wait`, `snapshot`, `click`, `hover`, `press`, `check`, `uncheck`, `type`, `select`, `scroll`, `scroll-into-view`
33
+ - Targets/pages/DOM: `targets-list`, `target-use`, `target-new`, `target-close`, `page`, `pages`, `page-close`, `dom-html`, `dom-text`, `dom-attr`, `dom-value`, `dom-visible`, `dom-enabled`, `dom-checked`
34
+ - Design canvas: `canvas`
35
+ - Export/diagnostics/power: `clone-page`, `clone-component`, `perf`, `screenshot`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `macro-resolve`, `annotate`, `rpc`
36
36
 
37
37
  ## Tool surface categories
38
38
 
39
- - Runtime parity tools map to the CLI runtime categories.
39
+ - Runtime parity tools map to the CLI runtime categories, including `opendevbrowser_canvas`.
40
40
  - Tool-only: `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, `opendevbrowser_skill_load`.
41
41
  - CLI-only: `rpc`.
42
42
 
@@ -55,7 +55,7 @@ Namespace groups:
55
55
  - `export.*`
56
56
  - `devtools.*`
57
57
 
58
- Handshake/liveness envelope types:
58
+ Envelope types:
59
59
  - `ops_hello`, `ops_hello_ack`
60
60
  - `ops_ping`, `ops_pong`
61
61
  - `ops_request`, `ops_response`, `ops_error`
@@ -64,14 +64,107 @@ Handshake/liveness envelope types:
64
64
  Concurrency policy:
65
65
  - `/ops` supports multiple clients and multiple sessions.
66
66
  - Reliable parallel execution is session-scoped (`session-per-worker`).
67
- - Avoid concurrent independent streams that switch targets inside one session (`targets.use` races can cross-wire active target state).
67
+ - Avoid concurrent independent streams that switch targets inside one session.
68
+
69
+ ### `/canvas`
70
+
71
+ Core command families:
72
+ - Session and governance: `canvas.session.open`, `canvas.session.attach`, `canvas.session.status`, `canvas.session.close`, `canvas.capabilities.get`, `canvas.plan.set`, `canvas.plan.get`
73
+ - Document: `canvas.document.load`, `canvas.document.patch`, `canvas.document.save`, `canvas.document.export`
74
+ - Live targets and overlay: `canvas.tab.open`, `canvas.tab.close`, `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`
75
+ - Preview and feedback: `canvas.preview.render`, `canvas.preview.refresh`, `canvas.feedback.poll`, `canvas.feedback.subscribe`
76
+ - Code sync: `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, `canvas.code.resolve`
77
+
78
+ Extension runtime subset:
79
+ - `canvas.tab.open`, `canvas.tab.close`, `canvas.tab.sync`
80
+ - `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`, `canvas.overlay.sync`
81
+
82
+ Envelope types:
83
+ - `canvas_request`, `canvas_response`, `canvas_error`
84
+ - `canvas_event`, `canvas_chunk`
85
+ - `canvas_ping`, `canvas_pong`
86
+
87
+ Minimum handshake payload shape:
88
+
89
+ ```json
90
+ {
91
+ "canvasSessionId": "canvas_session_01",
92
+ "browserSessionId": "browser_session_01",
93
+ "documentId": "dc_01",
94
+ "leaseId": "lease_01",
95
+ "preflightState": "handshake_read",
96
+ "attachModes": ["observer", "lease_reclaim"],
97
+ "governanceRequirements": {
98
+ "requiredBeforeMutation": ["intent", "generationPlan", "designLanguage"],
99
+ "requiredBeforeSave": ["intent", "generationPlan", "runtimeBudgets"]
100
+ },
101
+ "generationPlanRequirements": {
102
+ "requiredBeforeMutation": ["targetOutcome", "visualDirection", "layoutStrategy"]
103
+ },
104
+ "allowedLibraries": {
105
+ "components": ["shadcn"],
106
+ "icons": ["lucide"],
107
+ "styling": ["tailwindcss"]
108
+ },
109
+ "mutationPolicy": {
110
+ "planRequiredBeforePatch": true,
111
+ "allowedBeforePlan": [
112
+ "canvas.capabilities.get",
113
+ "canvas.plan.get",
114
+ "canvas.plan.set",
115
+ "canvas.document.load",
116
+ "canvas.session.attach",
117
+ "canvas.session.status"
118
+ ]
119
+ }
120
+ }
121
+ ```
122
+
123
+ Preflight state machine:
124
+ - `handshake_read`
125
+ - `plan_submitted`
126
+ - `plan_accepted`
127
+ - `patching_enabled`
128
+
129
+ The first mutation path must stay blocked until `canvas.plan.set` has been accepted. The canonical blocker is `plan_required` and should carry `details.auditId: "CANVAS-01"`.
130
+
131
+ Recommended blocker envelope:
132
+
133
+ ```json
134
+ {
135
+ "code": "plan_required",
136
+ "blockingCommand": "canvas.document.patch",
137
+ "requiredNextCommands": ["canvas.plan.set"],
138
+ "message": "generationPlan must be accepted before mutation.",
139
+ "details": { "auditId": "CANVAS-01" }
140
+ }
141
+ ```
142
+
143
+ Feedback contract markers:
144
+ - Poll categories: `render`, `console`, `network`, `validation`, `performance`, `asset`, `export`, `code-sync`, `parity`
145
+ - Feedback items must preserve `documentId`, `pageId`, `prototypeId`, `targetId`, `documentRevision`, `severity`, `class`, and `evidenceRefs`
146
+ - Subscribe event types: `feedback.item`, `feedback.heartbeat`, `feedback.complete`
147
+
148
+ Current operational constraints:
149
+ - `canvas.feedback.subscribe` returns the initial payload on every public surface. For ongoing events:
150
+ - CLI: use `opendevbrowser canvas --command canvas.feedback.subscribe --output-format stream-json`
151
+ - tool/daemon loops: reuse the returned cursor with repeated `canvas.feedback.poll`
152
+ - `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers only.
153
+ - `canvas_html` remains the default preview/export contract; `bound_app_runtime` is valid only when the binding explicitly opts in and runtime preflight succeeds.
154
+ - Library metadata is preserved, but rendered output is still semantic rather than package-faithful.
155
+ - Popup and canvas both ship per-item and combined annotation `Copy` / `Send` actions. Today, `Send` stores the payload for later `annotate --stored` retrieval rather than proactively delivering it into the active agent chat.
156
+
157
+ Operational rule:
158
+ - Read `canvas.session.open` or `canvas.capabilities.get` before mutation.
159
+ - Use `canvas.feedback.poll` after each patch/render loop.
160
+ - Do not save if `governanceRequirements.requiredBeforeSave` still reports missing governance blocks.
68
161
 
69
162
  ### `/cdp` (legacy)
70
163
 
71
164
  - Opt-in via `--extension-legacy`.
72
- - Forwards raw CDP commands through relay command envelopes (`id`, `method`, `params`, optional `sessionId`).
165
+ - Forwards raw CDP command envelopes (`id`, `method`, `params`, optional `sessionId`).
73
166
  - Use for compatibility-specific paths only.
74
- - Treat as a legacy/single-writer path; do not use as the primary route for concurrent automation.
167
+ - Treat as a legacy single-writer route, not the primary concurrent path.
75
168
 
76
169
  ## Mode and flag checkpoints
77
170
 
@@ -84,6 +177,7 @@ Required readiness/status checks:
84
177
  - `extensionConnected`
85
178
  - `extensionHandshakeComplete`
86
179
  - `opsConnected`
180
+ - `canvasConnected`
87
181
  - `cdpConnected`
88
182
  - `pairingRequired`
89
183
 
@@ -91,5 +185,7 @@ Required readiness/status checks:
91
185
 
92
186
  ```bash
93
187
  npm run test -- tests/parity-matrix.test.ts
188
+ ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
189
+ ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
94
190
  ./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
95
191
  ```
@@ -0,0 +1,70 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "canvasSessionId": "<canvas-session-id>",
4
+ "documentId": "<document-id>",
5
+ "blockers": [
6
+ {
7
+ "auditId": "CANVAS-01",
8
+ "code": "plan_required",
9
+ "blockingCommand": "canvas.document.patch",
10
+ "requiredNextCommands": [
11
+ "canvas.plan.set"
12
+ ],
13
+ "status": "pending"
14
+ },
15
+ {
16
+ "auditId": "CANVAS-02",
17
+ "code": "governance_required",
18
+ "blockingCommand": "canvas.document.save",
19
+ "requiredNextCommands": [
20
+ "canvas.capabilities.get"
21
+ ],
22
+ "status": "pending"
23
+ },
24
+ {
25
+ "auditId": "CANVAS-03",
26
+ "code": "generation_plan_invalid",
27
+ "blockingCommand": "canvas.plan.set",
28
+ "requiredNextCommands": [
29
+ "canvas.plan.set"
30
+ ],
31
+ "status": "pending"
32
+ },
33
+ {
34
+ "auditId": "CANVAS-04",
35
+ "code": "policy_violation",
36
+ "blockingCommand": "canvas.document.patch",
37
+ "requiredNextCommands": [
38
+ "canvas.capabilities.get"
39
+ ],
40
+ "status": "pending"
41
+ },
42
+ {
43
+ "auditId": "CANVAS-05",
44
+ "code": "unsupported_target",
45
+ "blockingCommand": "canvas.overlay.mount",
46
+ "requiredNextCommands": [
47
+ "canvas.tab.open"
48
+ ],
49
+ "status": "pending"
50
+ },
51
+ {
52
+ "auditId": "CANVAS-06",
53
+ "code": "budget_exceeded",
54
+ "blockingCommand": "canvas.preview.render",
55
+ "requiredNextCommands": [
56
+ "canvas.preview.refresh"
57
+ ],
58
+ "status": "pending"
59
+ },
60
+ {
61
+ "auditId": "CANVAS-07",
62
+ "code": "feedback_metadata_missing",
63
+ "blockingCommand": "canvas.feedback.poll",
64
+ "requiredNextCommands": [
65
+ "canvas.feedback.poll"
66
+ ],
67
+ "status": "pending"
68
+ }
69
+ ]
70
+ }
@@ -0,0 +1,73 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "canvasSessionId": "<canvas-session-id>",
4
+ "documentId": "<document-id>",
5
+ "targetIds": [
6
+ "<target-id>"
7
+ ],
8
+ "afterCursor": null,
9
+ "categories": [
10
+ "render",
11
+ "console",
12
+ "network",
13
+ "validation",
14
+ "performance",
15
+ "asset",
16
+ "export"
17
+ ],
18
+ "requiredEventTypes": [
19
+ "feedback.item",
20
+ "feedback.heartbeat",
21
+ "feedback.complete"
22
+ ],
23
+ "requiredFieldsPerItem": [
24
+ "documentId",
25
+ "pageId",
26
+ "prototypeId",
27
+ "targetId",
28
+ "documentRevision",
29
+ "severity",
30
+ "class",
31
+ "message",
32
+ "evidenceRefs"
33
+ ],
34
+ "requiredIssueClasses": [
35
+ "CANVAS-01",
36
+ "CANVAS-02",
37
+ "CANVAS-03",
38
+ "CANVAS-04",
39
+ "CANVAS-05",
40
+ "CANVAS-06",
41
+ "CANVAS-07"
42
+ ],
43
+ "checks": [
44
+ {
45
+ "auditId": "CANVAS-01",
46
+ "description": "Reject feedback-based mutation when handshake evidence is missing."
47
+ },
48
+ {
49
+ "auditId": "CANVAS-02",
50
+ "description": "Carry governance warnings through save/export evaluation."
51
+ },
52
+ {
53
+ "auditId": "CANVAS-03",
54
+ "description": "Treat malformed generation plans as blocking plan validation failures."
55
+ },
56
+ {
57
+ "auditId": "CANVAS-04",
58
+ "description": "Report library or icon-policy violations as structured validation findings."
59
+ },
60
+ {
61
+ "auditId": "CANVAS-05",
62
+ "description": "Capture unsupported target or overlay mount failures with target attribution."
63
+ },
64
+ {
65
+ "auditId": "CANVAS-06",
66
+ "description": "Verify preview downgrade and runtime budget warnings are surfaced."
67
+ },
68
+ {
69
+ "auditId": "CANVAS-07",
70
+ "description": "Require targetId, pageId, class, and evidenceRefs on feedback items."
71
+ }
72
+ ]
73
+ }
@@ -0,0 +1,67 @@
1
+ {
2
+ "requestId": "req_plan_01",
3
+ "canvasSessionId": "<canvas-session-id>",
4
+ "leaseId": "<lease-id>",
5
+ "documentId": "<document-id>",
6
+ "generationPlan": {
7
+ "targetOutcome": {
8
+ "mode": "high-fi-live-edit",
9
+ "summary": "Refine hero hierarchy and CTA clarity"
10
+ },
11
+ "visualDirection": {
12
+ "profile": "cinematic-minimal",
13
+ "styleAxes": {
14
+ "contrast": "high",
15
+ "density": "airy"
16
+ }
17
+ },
18
+ "layoutStrategy": {
19
+ "approach": "hero-led-grid"
20
+ },
21
+ "contentStrategy": {
22
+ "source": "document-context"
23
+ },
24
+ "componentStrategy": {
25
+ "mode": "reuse-first",
26
+ "approvedLibraries": [
27
+ "shadcn"
28
+ ]
29
+ },
30
+ "motionPosture": {
31
+ "level": "subtle",
32
+ "allow3D": false,
33
+ "allowParallax": false,
34
+ "allowCustomSmoothScroll": false
35
+ },
36
+ "responsivePosture": {
37
+ "primaryViewport": "desktop",
38
+ "requiredViewports": [
39
+ "desktop",
40
+ "tablet",
41
+ "mobile"
42
+ ]
43
+ },
44
+ "accessibilityPosture": {
45
+ "target": "WCAG_2_2_AA",
46
+ "reducedMotion": "required",
47
+ "keyboardParity": true
48
+ },
49
+ "validationTargets": {
50
+ "blockOn": [
51
+ "contrast-failure"
52
+ ],
53
+ "warnOn": [
54
+ "responsive-mismatch"
55
+ ]
56
+ }
57
+ },
58
+ "requiredIssueClasses": [
59
+ "CANVAS-01",
60
+ "CANVAS-02",
61
+ "CANVAS-03",
62
+ "CANVAS-04",
63
+ "CANVAS-05",
64
+ "CANVAS-06",
65
+ "CANVAS-07"
66
+ ]
67
+ }
@@ -0,0 +1,126 @@
1
+ {
2
+ "canvasSessionId": "canvas_session_01",
3
+ "browserSessionId": "browser_session_01",
4
+ "documentId": "dc_01",
5
+ "leaseId": "lease_01",
6
+ "preflightState": "handshake_read",
7
+ "attachModes": [
8
+ "observer",
9
+ "lease_reclaim"
10
+ ],
11
+ "governanceRequirements": {
12
+ "requiredBeforeMutation": [
13
+ "intent",
14
+ "generationPlan",
15
+ "designLanguage",
16
+ "contentModel",
17
+ "layoutSystem",
18
+ "typographySystem",
19
+ "motionSystem",
20
+ "responsiveSystem",
21
+ "accessibilityPolicy"
22
+ ],
23
+ "requiredBeforeSave": [
24
+ "intent",
25
+ "generationPlan",
26
+ "designLanguage",
27
+ "contentModel",
28
+ "layoutSystem",
29
+ "typographySystem",
30
+ "colorSystem",
31
+ "surfaceSystem",
32
+ "iconSystem",
33
+ "motionSystem",
34
+ "responsiveSystem",
35
+ "accessibilityPolicy",
36
+ "libraryPolicy",
37
+ "runtimeBudgets"
38
+ ],
39
+ "optionalInherited": [
40
+ "colorSystem",
41
+ "surfaceSystem",
42
+ "iconSystem",
43
+ "libraryPolicy",
44
+ "runtimeBudgets"
45
+ ]
46
+ },
47
+ "generationPlanRequirements": {
48
+ "requiredBeforeMutation": [
49
+ "targetOutcome",
50
+ "visualDirection",
51
+ "layoutStrategy",
52
+ "contentStrategy",
53
+ "componentStrategy",
54
+ "motionPosture",
55
+ "responsivePosture",
56
+ "accessibilityPosture",
57
+ "validationTargets"
58
+ ]
59
+ },
60
+ "allowedLibraries": {
61
+ "icons": [
62
+ "3dicons",
63
+ "tabler",
64
+ "microsoft-fluent-ui-system-icons",
65
+ "@lobehub/fluent-emoji-3d"
66
+ ],
67
+ "components": [
68
+ "shadcn"
69
+ ],
70
+ "styling": [
71
+ "tailwindcss"
72
+ ],
73
+ "motion": [],
74
+ "threeD": []
75
+ },
76
+ "warningAuditIds": [
77
+ "CANVAS-01",
78
+ "CANVAS-02",
79
+ "CANVAS-03",
80
+ "CANVAS-04",
81
+ "CANVAS-05",
82
+ "CANVAS-06",
83
+ "CANVAS-07"
84
+ ],
85
+ "allowedBeforePlan": [
86
+ "canvas.capabilities.get",
87
+ "canvas.plan.get",
88
+ "canvas.plan.set",
89
+ "canvas.document.load",
90
+ "canvas.session.attach",
91
+ "canvas.session.status"
92
+ ],
93
+ "projectionModes": [
94
+ "canvas_html",
95
+ "bound_app_runtime"
96
+ ],
97
+ "annotationDispatch": {
98
+ "popupAndCanvasSend": "storage_backed_retrieval",
99
+ "retrievalCommand": "annotate --stored"
100
+ },
101
+ "documentContext": {
102
+ "status": "existing",
103
+ "existingGovernanceBlocks": [
104
+ "colorSystem",
105
+ "surfaceSystem",
106
+ "iconSystem",
107
+ "libraryPolicy",
108
+ "runtimeBudgets"
109
+ ],
110
+ "missingGovernanceBlocks": [
111
+ "intent",
112
+ "generationPlan",
113
+ "designLanguage",
114
+ "contentModel",
115
+ "layoutSystem",
116
+ "typographySystem",
117
+ "motionSystem",
118
+ "responsiveSystem",
119
+ "accessibilityPolicy"
120
+ ],
121
+ "tokensPresent": true,
122
+ "themesPresent": true,
123
+ "viewportsPresent": true,
124
+ "componentInventoryPresent": false
125
+ }
126
+ }
@@ -2,6 +2,63 @@
2
2
  "schemaVersion": "1.0",
3
3
  "skill": "",
4
4
  "run_id": "",
5
+ "canvas": {
6
+ "enabled": false,
7
+ "canvasSessionId": "",
8
+ "documentId": "",
9
+ "targetIds": [],
10
+ "issueClasses": [
11
+ {
12
+ "auditId": "CANVAS-01",
13
+ "status": "pending",
14
+ "command": "canvas.document.patch",
15
+ "evidence": [],
16
+ "notes": ""
17
+ },
18
+ {
19
+ "auditId": "CANVAS-02",
20
+ "status": "pending",
21
+ "command": "canvas.document.save",
22
+ "evidence": [],
23
+ "notes": ""
24
+ },
25
+ {
26
+ "auditId": "CANVAS-03",
27
+ "status": "pending",
28
+ "command": "canvas.plan.set",
29
+ "evidence": [],
30
+ "notes": ""
31
+ },
32
+ {
33
+ "auditId": "CANVAS-04",
34
+ "status": "pending",
35
+ "command": "canvas.document.patch",
36
+ "evidence": [],
37
+ "notes": ""
38
+ },
39
+ {
40
+ "auditId": "CANVAS-05",
41
+ "status": "pending",
42
+ "command": "canvas.overlay.mount",
43
+ "evidence": [],
44
+ "notes": ""
45
+ },
46
+ {
47
+ "auditId": "CANVAS-06",
48
+ "status": "pending",
49
+ "command": "canvas.preview.render",
50
+ "evidence": [],
51
+ "notes": ""
52
+ },
53
+ {
54
+ "auditId": "CANVAS-07",
55
+ "status": "pending",
56
+ "command": "canvas.feedback.poll",
57
+ "evidence": [],
58
+ "notes": ""
59
+ }
60
+ ]
61
+ },
5
62
  "issues": [
6
63
  {
7
64
  "id": "ISSUE-01",
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "schemaVersion": "1.0",
3
3
  "expectedCounts": {
4
- "cliCommands": 50,
5
- "tools": 44,
6
- "opsCommands": 36
4
+ "cliCommands": 56,
5
+ "tools": 49,
6
+ "opsCommands": 38,
7
+ "canvasCommands": 26
7
8
  },
8
9
  "docsMustCover": [
9
10
  "README.md",
@@ -17,6 +18,9 @@
17
18
  "CLI command names documented by category",
18
19
  "Tool names documented by category",
19
20
  "Ops command namespaces documented",
21
+ "Canvas command names documented",
22
+ "Canvas code-sync surface documented",
23
+ "Annotation send/copy semantics documented",
20
24
  "CDP envelope contract documented",
21
25
  "Global and command-specific flags documented",
22
26
  "Mode semantics documented"
@@ -14,6 +14,8 @@ Workflows:
14
14
  parallel-multipage-safe
15
15
  qa-debug
16
16
  social-readonly-check
17
+ canvas-preflight
18
+ canvas-feedback-eval
17
19
  parity-check
18
20
  surface-audit
19
21
  ops-channel-check
@@ -86,6 +88,30 @@ EOF
86
88
  opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
87
89
  opendevbrowser_debug_trace_snapshot sessionId="<session-id>" maxEvents=50
88
90
  opendevbrowser_network_poll sessionId="<session-id>" max=100
91
+ EOF
92
+ ;;
93
+ canvas-preflight)
94
+ cat <<'EOF'
95
+ cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
96
+ cat skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
97
+ npx opendevbrowser canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
98
+ # Read handshake before any mutation. Require preflightState=handshake_read.
99
+ npx opendevbrowser canvas --command canvas.plan.set --params-file skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
100
+ # Replace placeholders in the plan file with canvasSessionId, leaseId, and documentId from the open response.
101
+ npx opendevbrowser canvas --command canvas.plan.get --params '{"requestId":"req_plan_get_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>"}'
102
+ # Require planStatus=accepted or preflightState=plan_accepted before canvas.document.patch.
103
+ EOF
104
+ ;;
105
+ canvas-feedback-eval)
106
+ cat <<'EOF'
107
+ cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
108
+ cat skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json
109
+ cat skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json
110
+ npx opendevbrowser canvas --command canvas.feedback.poll --params '{"requestId":"req_feedback_01","canvasSessionId":"<canvas-session-id>","documentId":"<document-id>","targetId":"<target-id>","afterCursor":null}'
111
+ # Verify every feedback item is target-attributed and uses approved categories.
112
+ npx opendevbrowser canvas --command canvas.preview.refresh --params '{"requestId":"req_refresh_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","targetId":"<target-id>","refreshMode":"full"}'
113
+ npx opendevbrowser canvas --command canvas.document.save --params '{"requestId":"req_save_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>","repoPath":null}'
114
+ # Save should fail or warn when requiredBeforeSave governance blocks remain unresolved.
89
115
  EOF
90
116
  ;;
91
117
  parity-check)