opendevbrowser 0.0.15 → 0.0.17

package/skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md

@@ -0,0 +1,191 @@
+# Command and Channel Reference
+
+## Purpose
+
+Compact operational map of the current OpenDevBrowser surfaces, with the `/canvas` handshake and blocker paths called out explicitly for preflight audits.
+
+## Current coverage snapshot
+
+- CLI commands: `56`
+- Plugin tools: `49`
+- `/ops` command names: `38`
+- `/canvas` command names: `26`
+- Legacy `/cdp` relay: generic CDP forwarding (method-level)
+
+Canonical exhaustive reference: `docs/SURFACE_REFERENCE.md`.
+CLI help mirror: `npx opendevbrowser --help` and `npx opendevbrowser help` (identical inventories).
+
+## Agent skill-sync coverage
+
+Skill-pack installation and discovery are synchronized for:
+- `opencode`: `~/.config/opencode/skill` and `./.opencode/skill`
+- `codex`: `$CODEX_HOME/skills` (fallback `~/.codex/skills`) and `./.codex/skills`
+- `claudecode`: `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
+- `ampcli`: `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (fallback `~/.amp/skills`) and `./.amp/skills`
+
+Legacy aliases `claude` and `amp` remain present in installer target metadata for compatibility.
+
+## CLI surface categories
+
+- Install/runtime: `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `run`, `artifacts`
+- Session/connection/workflow: `launch`, `connect`, `disconnect`, `status`, `cookie-import`, `cookie-list`, `research`, `shopping`, `product-video`
+- Navigation/interaction: `goto`, `wait`, `snapshot`, `click`, `hover`, `press`, `check`, `uncheck`, `type`, `select`, `scroll`, `scroll-into-view`
+- 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`
+- Design canvas: `canvas`
+- Export/diagnostics/power: `clone-page`, `clone-component`, `perf`, `screenshot`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `macro-resolve`, `annotate`, `rpc`
+
+## Tool surface categories
+
+- Runtime parity tools map to the CLI runtime categories, including `opendevbrowser_canvas`.
+- Tool-only: `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, `opendevbrowser_skill_load`.
+- CLI-only: `rpc`.
+
+## Relay channels
+
+### `/ops` (default)
+
+Namespace groups:
+- `session.*`
+- `storage.*`
+- `targets.*`
+- `page.*`
+- `nav.*`
+- `interact.*`
+- `dom.*`
+- `export.*`
+- `devtools.*`
+
+Envelope types:
+- `ops_hello`, `ops_hello_ack`
+- `ops_ping`, `ops_pong`
+- `ops_request`, `ops_response`, `ops_error`
+- `ops_event`, `ops_chunk`
+
+Concurrency policy:
+- `/ops` supports multiple clients and multiple sessions.
+- Reliable parallel execution is session-scoped (`session-per-worker`).
+- Avoid concurrent independent streams that switch targets inside one session.
+
+### `/canvas`
+
+Core command families:
+- Session and governance: `canvas.session.open`, `canvas.session.attach`, `canvas.session.status`, `canvas.session.close`, `canvas.capabilities.get`, `canvas.plan.set`, `canvas.plan.get`
+- Document: `canvas.document.load`, `canvas.document.patch`, `canvas.document.save`, `canvas.document.export`
+- Live targets and overlay: `canvas.tab.open`, `canvas.tab.close`, `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`
+- Preview and feedback: `canvas.preview.render`, `canvas.preview.refresh`, `canvas.feedback.poll`, `canvas.feedback.subscribe`
+- Code sync: `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, `canvas.code.resolve`
+
+Extension runtime subset:
+- `canvas.tab.open`, `canvas.tab.close`, `canvas.tab.sync`
+- `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`, `canvas.overlay.sync`
+
+Envelope types:
+- `canvas_request`, `canvas_response`, `canvas_error`
+- `canvas_event`, `canvas_chunk`
+- `canvas_ping`, `canvas_pong`
+
+Minimum handshake payload shape:
+
+```json
+{
+  "canvasSessionId": "canvas_session_01",
+  "browserSessionId": "browser_session_01",
+  "documentId": "dc_01",
+  "leaseId": "lease_01",
+  "preflightState": "handshake_read",
+  "attachModes": ["observer", "lease_reclaim"],
+  "governanceRequirements": {
+    "requiredBeforeMutation": ["intent", "generationPlan", "designLanguage"],
+    "requiredBeforeSave": ["intent", "generationPlan", "runtimeBudgets"]
+  },
+  "generationPlanRequirements": {
+    "requiredBeforeMutation": ["targetOutcome", "visualDirection", "layoutStrategy"]
+  },
+  "allowedLibraries": {
+    "components": ["shadcn"],
+    "icons": ["lucide"],
+    "styling": ["tailwindcss"]
+  },
+  "mutationPolicy": {
+    "planRequiredBeforePatch": true,
+    "allowedBeforePlan": [
+      "canvas.capabilities.get",
+      "canvas.plan.get",
+      "canvas.plan.set",
+      "canvas.document.load",
+      "canvas.session.attach",
+      "canvas.session.status"
+    ]
+  }
+}
+```
+
+Preflight state machine:
+- `handshake_read`
+- `plan_submitted`
+- `plan_accepted`
+- `patching_enabled`
+
+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"`.
+
+Recommended blocker envelope:
+
+```json
+{
+  "code": "plan_required",
+  "blockingCommand": "canvas.document.patch",
+  "requiredNextCommands": ["canvas.plan.set"],
+  "message": "generationPlan must be accepted before mutation.",
+  "details": { "auditId": "CANVAS-01" }
+}
+```
+
+Feedback contract markers:
+- Poll categories: `render`, `console`, `network`, `validation`, `performance`, `asset`, `export`, `code-sync`, `parity`
+- Feedback items must preserve `documentId`, `pageId`, `prototypeId`, `targetId`, `documentRevision`, `severity`, `class`, and `evidenceRefs`
+- Subscribe event types: `feedback.item`, `feedback.heartbeat`, `feedback.complete`
+
+Current operational constraints:
+- `canvas.feedback.subscribe` returns the initial payload on every public surface. For ongoing events:
+  - CLI: use `opendevbrowser canvas --command canvas.feedback.subscribe --output-format stream-json`
+  - tool/daemon loops: reuse the returned cursor with repeated `canvas.feedback.poll`
+- `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers only.
+- `canvas_html` remains the default preview/export contract; `bound_app_runtime` is valid only when the binding explicitly opts in and runtime preflight succeeds.
+- Library metadata is preserved, but rendered output is still semantic rather than package-faithful.
+- 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.
+
+Operational rule:
+- Read `canvas.session.open` or `canvas.capabilities.get` before mutation.
+- Use `canvas.feedback.poll` after each patch/render loop.
+- Do not save if `governanceRequirements.requiredBeforeSave` still reports missing governance blocks.
+
+### `/cdp` (legacy)
+
+- Opt-in via `--extension-legacy`.
+- Forwards raw CDP command envelopes (`id`, `method`, `params`, optional `sessionId`).
+- Use for compatibility-specific paths only.
+- Treat as a legacy single-writer route, not the primary concurrent path.
+
+## Mode and flag checkpoints
+
+- Managed: `launch --no-extension`
+- Extension default: `launch` or relay-normalized `connect`
+- Extension legacy: `launch --extension-legacy` or `connect --extension-legacy`
+- Direct CDP: `connect --ws-endpoint ...` or `connect --host ... --cdp-port ...`
+
+Required readiness/status checks:
+- `extensionConnected`
+- `extensionHandshakeComplete`
+- `opsConnected`
+- `canvasConnected`
+- `cdpConnected`
+- `pairingRequired`
+
+## Fast verification commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```

package/skills/opendevbrowser-best-practices/artifacts/debug-trace-playbook.md

@@ -0,0 +1,36 @@
+# Debug Trace Playbook
+
+## Purpose
+
+Run a repeatable debug pass and capture enough evidence to diagnose regressions quickly.
+
+## Minimum Trace Bundle
+
+- `requestId` and `sessionId`
+- snapshot output before and after key actions
+- console stream (`opendevbrowser_console_poll`)
+- network stream (`opendevbrowser_network_poll`)
+- screenshot evidence (`opendevbrowser_screenshot`)
+
+## Workflow
+
+1. Launch/connect and record `sessionId`.
+2. Reproduce issue with the smallest action sequence.
+3. Capture snapshot + console + network + screenshot at failure point.
+4. Normalize findings by `requestId` and timestamp.
+5. Re-run once in another mode (`managed` vs `extension` vs `cdpConnect`) to detect mode-specific drift.
+
+## Command Skeleton
+
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+```
+
+## Triage Rules
+
+- If refs fail: re-snapshot and retry one time.
+- If repeated 403/429: pause and apply cooldown/retry policy.
+- If failure reproduces in only one mode: mark as parity defect and gate release.

package/skills/opendevbrowser-best-practices/artifacts/fingerprint-tiers.md

@@ -0,0 +1,36 @@
+# Fingerprint Tiers
+
+## Purpose
+
+Choose the lowest hardening tier that keeps runs reliable; avoid unnecessary complexity.
+
+## Tiers
+
+### Tier 0 — Baseline
+
+- Default runtime behavior.
+- Use for internal pages and low-friction targets.
+
+### Tier 1 — Coherence Profile (default recommendation)
+
+- Consistent profile/session reuse.
+- Stable launch flags and deterministic workflow ordering.
+- Best default for most production automation.
+
+### Tier 2 — Runtime Hardening
+
+- Add stricter runtime controls (timeouts, retries, pacing discipline).
+- Use when targets show intermittent anti-bot or high flakiness.
+
+### Tier 3 — Adaptive Hardening (optional track)
+
+- Dynamic policy adjustments and canary validation loops.
+- Use only when Tier 1/2 cannot achieve target reliability.
+- Treat as opt-in track, not baseline release requirement.
+
+## Selection Heuristic
+
+1. Start Tier 0 for local validation.
+2. Promote to Tier 1 for shared/CI workflows.
+3. Use Tier 2 when failures are environment-dependent.
+4. Use Tier 3 only for sustained high-friction environments.

package/skills/opendevbrowser-best-practices/artifacts/macro-workflows.md

@@ -0,0 +1,43 @@
+# Macro Workflows
+
+## Purpose
+
+Define concise macro entrypoints that expand into repeatable provider workflows.
+
+## Macro Contract
+
+Each macro should declare:
+
+- `macro`: stable name
+- `provider`: `web|community|social`
+- `mode`: `managed|extension|cdpConnect`
+- `policyMode`: `read|write`
+- `requestId`: required correlation id
+
+## Recommended Macros
+
+### `provider.search`
+
+- Expands to launch/connect + goto + wait + snapshot + extract + network poll.
+- Output: normalized result set with provenance fields.
+
+### `provider.crawl`
+
+- Expands to bounded multipage loop (queue + dedupe + depth/page limits).
+- Output: `records[]`, `visited[]`, and crawl stats.
+
+### `qa.debug`
+
+- Expands to snapshot + console poll + network poll + screenshot.
+- Output: trace bundle for triage.
+
+### `safe.post`
+
+- Expands to notice + preview + explicit confirmation + single write action.
+- Output: write result and audit metadata.
+
+## Expansion Rules
+
+- Keep expansions deterministic and minimal.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`, `mode`).
+- Never hide write actions behind implicit macro behavior.

package/skills/opendevbrowser-best-practices/artifacts/parity-gates.md

@@ -0,0 +1,36 @@
+# Parity Gates
+
+## Purpose
+
+Define hard pass/fail gates so CLI, tool, and runtime surfaces stay aligned.
+
+## Parity Matrix
+
+| Area | Modes | Surfaces | Gate |
+|---|---|---|---|
+| Session lifecycle | managed, extension, cdpConnect | CLI + tools + runtime | `launch/connect/disconnect/status` parity |
+| Navigation + refs loop | managed, extension, cdpConnect | CLI + tools + runtime | `goto/wait/snapshot` parity |
+| Interaction | managed, extension, cdpConnect | CLI + tools + runtime | click/type/select/scroll/press/check/uncheck parity |
+| Targets + pages | managed, extension, cdpConnect | CLI + tools + runtime | target/page command parity |
+| DOM + diagnostics + export | managed, extension, cdpConnect | CLI + tools + runtime | dom/perf/screenshot/console/network/clone parity |
+| Relay channels | extension (default) + extension-legacy | `/ops` + `/cdp` | `/ops` namespace coverage + `/cdp` envelope compatibility |
+
+## Surface Rules
+
+- `rpc` is intentionally CLI-only (internal and unsafe).
+- `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, and `opendevbrowser_skill_load` are intentionally tool-only.
+- Any new stable CLI runtime command must add a matching tool unless explicitly documented as CLI-only.
+- Surface counts and command inventories are verified against `docs/SURFACE_REFERENCE.md`.
+
+## Gate Commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+npm run test -- tests/tools.test.ts tests/daemon-command.test.ts
+npm run test -- tests/providers-performance-gate.test.ts
+```
+
+## Release Requirement
+
+Ship only when parity tests pass and docs (`README.md`, `docs/CLI.md`, `docs/ARCHITECTURE.md`, `docs/SURFACE_REFERENCE.md`) reflect the same surface map.
+Use `docs/RELEASE_PARITY_CHECKLIST.md` as the release gate source of truth.

package/skills/opendevbrowser-best-practices/artifacts/provider-workflows.md

@@ -0,0 +1,89 @@
+# Provider Workflows
+
+## Purpose
+
+Codify minimal, repeatable workflows for provider-native automation.
+
+## Inputs
+
+- `sessionMode`: `managed|extension|cdpConnect`
+- `provider`: `web|community|social`
+- `requestId`: unique per workflow run
+- `policyMode`: `read` (default) or `write` (explicit/manual opt-in only)
+
+## Workflow A: Provider Search
+
+1. Launch/connect mode.
+2. Navigate to provider query URL.
+3. Wait for load (`networkidle` preferred).
+4. Snapshot actionables.
+5. Extract result units with refs.
+6. Poll network for request health.
+7. Emit normalized records.
+
+Expected output:
+- `items[]` with `title/url/snippet/source/ts/requestId`
+
+## Workflow B: Provider Fetch
+
+1. Launch/connect mode.
+2. Goto target URL/entity endpoint.
+3. Wait and snapshot.
+4. Extract typed fields.
+5. Poll console/network for anomalies.
+
+Expected output:
+- one normalized entity record + diagnostics metadata
+
+## Workflow C: Multipage Crawl
+
+1. Seed queue with initial URL list.
+2. Process one URL at a time:
+- goto
+- wait
+- snapshot
+- extract
+- collect outgoing links
+3. Canonicalize/dedupe links.
+4. Enqueue until `maxDepth|maxPages` reached.
+5. Persist records with page provenance.
+
+Expected output:
+- `records[]`
+- `visited[]`
+- `frontierStats`
+
+## Workflow D: Social Read-Only Validation (Default)
+
+1. Display read-only policy notice.
+2. Navigate to social target and execute search/read probes only.
+3. Capture `debug-trace-snapshot` + `network-poll`.
+4. Record auth/blocker diagnostics and provider health.
+
+Expected output:
+- `readResult` + `authBlockerDiagnostics`
+
+## Workflow E: Parallel Multipage (Reliable As-Is)
+
+1. Build a bounded frontier/queue in host logic.
+2. Allocate one session per worker (`session-1`, `session-2`, ...).
+3. In each worker session, process URLs serially:
+- goto
+- wait
+- snapshot
+- extract
+- emit records with `sessionId` + page provenance
+4. Never interleave competing `target-use` streams inside a single session.
+5. For managed persistent profiles, assign a unique profile path per worker session.
+6. Merge worker outputs deterministically (stable sort + dedupe key).
+
+Expected output:
+- `records[]` merged across workers
+- `workerStats[]` with `{ sessionId, processed, failures }`
+- `frontierStats` and checkpoint state
+
+## Failure Policy
+
+- stale refs: re-snapshot and retry once
+- repeated 403/429: stop and cooldown
+- inconsistent mode behavior: flag parity failure

package/skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": "1.0",
+  "canvasSessionId": "<canvas-session-id>",
+  "documentId": "<document-id>",
+  "blockers": [
+    {
+      "auditId": "CANVAS-01",
+      "code": "plan_required",
+      "blockingCommand": "canvas.document.patch",
+      "requiredNextCommands": [
+        "canvas.plan.set"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-02",
+      "code": "governance_required",
+      "blockingCommand": "canvas.document.save",
+      "requiredNextCommands": [
+        "canvas.capabilities.get"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-03",
+      "code": "generation_plan_invalid",
+      "blockingCommand": "canvas.plan.set",
+      "requiredNextCommands": [
+        "canvas.plan.set"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-04",
+      "code": "policy_violation",
+      "blockingCommand": "canvas.document.patch",
+      "requiredNextCommands": [
+        "canvas.capabilities.get"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-05",
+      "code": "unsupported_target",
+      "blockingCommand": "canvas.overlay.mount",
+      "requiredNextCommands": [
+        "canvas.tab.open"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-06",
+      "code": "budget_exceeded",
+      "blockingCommand": "canvas.preview.render",
+      "requiredNextCommands": [
+        "canvas.preview.refresh"
+      ],
+      "status": "pending"
+    },
+    {
+      "auditId": "CANVAS-07",
+      "code": "feedback_metadata_missing",
+      "blockingCommand": "canvas.feedback.poll",
+      "requiredNextCommands": [
+        "canvas.feedback.poll"
+      ],
+      "status": "pending"
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": "1.0",
+  "canvasSessionId": "<canvas-session-id>",
+  "documentId": "<document-id>",
+  "targetIds": [
+    "<target-id>"
+  ],
+  "afterCursor": null,
+  "categories": [
+    "render",
+    "console",
+    "network",
+    "validation",
+    "performance",
+    "asset",
+    "export"
+  ],
+  "requiredEventTypes": [
+    "feedback.item",
+    "feedback.heartbeat",
+    "feedback.complete"
+  ],
+  "requiredFieldsPerItem": [
+    "documentId",
+    "pageId",
+    "prototypeId",
+    "targetId",
+    "documentRevision",
+    "severity",
+    "class",
+    "message",
+    "evidenceRefs"
+  ],
+  "requiredIssueClasses": [
+    "CANVAS-01",
+    "CANVAS-02",
+    "CANVAS-03",
+    "CANVAS-04",
+    "CANVAS-05",
+    "CANVAS-06",
+    "CANVAS-07"
+  ],
+  "checks": [
+    {
+      "auditId": "CANVAS-01",
+      "description": "Reject feedback-based mutation when handshake evidence is missing."
+    },
+    {
+      "auditId": "CANVAS-02",
+      "description": "Carry governance warnings through save/export evaluation."
+    },
+    {
+      "auditId": "CANVAS-03",
+      "description": "Treat malformed generation plans as blocking plan validation failures."
+    },
+    {
+      "auditId": "CANVAS-04",
+      "description": "Report library or icon-policy violations as structured validation findings."
+    },
+    {
+      "auditId": "CANVAS-05",
+      "description": "Capture unsupported target or overlay mount failures with target attribution."
+    },
+    {
+      "auditId": "CANVAS-06",
+      "description": "Verify preview downgrade and runtime budget warnings are surfaced."
+    },
+    {
+      "auditId": "CANVAS-07",
+      "description": "Require targetId, pageId, class, and evidenceRefs on feedback items."
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json

@@ -0,0 +1,67 @@
+{
+  "requestId": "req_plan_01",
+  "canvasSessionId": "<canvas-session-id>",
+  "leaseId": "<lease-id>",
+  "documentId": "<document-id>",
+  "generationPlan": {
+    "targetOutcome": {
+      "mode": "high-fi-live-edit",
+      "summary": "Refine hero hierarchy and CTA clarity"
+    },
+    "visualDirection": {
+      "profile": "cinematic-minimal",
+      "styleAxes": {
+        "contrast": "high",
+        "density": "airy"
+      }
+    },
+    "layoutStrategy": {
+      "approach": "hero-led-grid"
+    },
+    "contentStrategy": {
+      "source": "document-context"
+    },
+    "componentStrategy": {
+      "mode": "reuse-first",
+      "approvedLibraries": [
+        "shadcn"
+      ]
+    },
+    "motionPosture": {
+      "level": "subtle",
+      "allow3D": false,
+      "allowParallax": false,
+      "allowCustomSmoothScroll": false
+    },
+    "responsivePosture": {
+      "primaryViewport": "desktop",
+      "requiredViewports": [
+        "desktop",
+        "tablet",
+        "mobile"
+      ]
+    },
+    "accessibilityPosture": {
+      "target": "WCAG_2_2_AA",
+      "reducedMotion": "required",
+      "keyboardParity": true
+    },
+    "validationTargets": {
+      "blockOn": [
+        "contrast-failure"
+      ],
+      "warnOn": [
+        "responsive-mismatch"
+      ]
+    }
+  },
+  "requiredIssueClasses": [
+    "CANVAS-01",
+    "CANVAS-02",
+    "CANVAS-03",
+    "CANVAS-04",
+    "CANVAS-05",
+    "CANVAS-06",
+    "CANVAS-07"
+  ]
+}