Extract the DevTools browser extension into its own repository and rebuild it on BrowserExtensionTemplate #205

Summary

Move the DevTools browser extension out of this repository into its own project (bQuery/bquery-devtools-extension) and rebuild it from scratch on top of JosunLP/BrowserExtensionTemplate, including proper documentation.

The current extension/ folder is a reference scaffold, not a shippable product: ~330 lines of untyped, unbuilt, untested vanilla JS (manifest.json, background.js, content.js, devtools.js, panel.html, panel.js). It has no build step, no bundler, no TypeScript, no tests, no lint coverage, no packaging, no store listing, and it is not part of the published npm tarball (package.json#files ships dist, src, bin only). It rides along in the framework repo's release cycle even though it has a completely different lifecycle (browser store review, its own versioning, its own CI).

Motivation

• Separate lifecycles. The extension ships to the Chrome Web Store / AMO on its own cadence; the framework ships to npm. Coupling them forces extension fixes through framework releases.
• The protocol is the contract, not the panel. @bquery/bquery/devtools already exposes a stable, versioned bridge (BRIDGE_PROTOCOL_VERSION = 1, BRIDGE_SOURCE, BRIDGE_CAPABILITIES, connectDevtoolsBridge, createBridgeServer, serializeComponentTree). An external extension consuming that contract as a published dependency proves the protocol is genuinely consumer-ready.
• Dogfooding. The template already lists bQuery as a first-class dependency (signals, Web Components, safeHtml, platform/storage). Building our own DevTools extension on it exercises the framework in a real MV3 environment.
• Quality floor. The current panel builds DOM with innerHTML + a hand-rolled esc() helper, relays messages over <all_urls> host permissions with an unauthenticated content-script relay, and has zero automated coverage. A rebuild lets us do this properly instead of patching a scaffold.
• Repo hygiene. Removes a non-published, non-tested, non-linted directory from the framework repo.

Target repository

bQuery/bquery-devtools-extension — seeded from JosunLP/BrowserExtensionTemplate, which already provides:

• TypeScript (strict) + Vite build with code splitting
• SASS + CSS custom properties, Bootstrap, native Web Components
• bQuery.js as a first-class dependency
• MV3 for Chrome/Edge, with automatic MV2 conversion for Firefox
• app.config.json synchronized into package.json / manifest.json via bun run sync
• Packaging scripts: bun run deploy-v3 (Chrome MV3), bun run deploy-v2 (Firefox MV2)
• ESLint + Prettier + bun run validate (typecheck + lint)
• Session handling on bQuery reactive primitives + platform/storage
• CSP plus safeHtml / sanitizeHtml sinks, and an error-boundary system

Scope

1. Bootstrap the new repository

• Create bQuery/bquery-devtools-extension from the template.
• Rename/rebrand: app.config.json, manifest.json (name, description, icons), README, LICENSE (match this repo's license), CODE_OF_CONDUCT, SECURITY, CONTRIBUTING.
• Depend on the published @bquery/bquery package (no relative imports into this repo); document the minimum supported framework version (bridge protocol v1 → >= 1.15.0).
• Extension icon set + store assets.

2. Rebuild the extension (from scratch, in TypeScript)

• Bridge client — typed transport layer speaking protocol v1 (hello / init / request / response / event), reusing the exported types from @bquery/bquery/devtools (BridgeInboundMessage, BridgeOutboundMessage, ComponentTreeNode) instead of re-declaring them.
• Message routing — devtools page → panel ⇄ background service worker ⇄ content script ⇄ inspected page, with per-tab port isolation, reconnect on service-worker sleep, and page navigation/reload handling (the current version silently drops messages when the worker is asleep).
• Panel UI as bQuery Web Components — component tree, signal/store inspection, live timeline; no innerHTML string building, use safeHtml/text sinks throughout.
• Capability negotiation — read capabilities from the init handshake and enable/disable panel features accordingly (signals, stores, components, timeline, time-travel) instead of assuming everything is present.
• Time travel — build on getSnapshot / getTimeline plus exportDevtoolsSnapshot, diffSignals, diffStores. Currently unimplemented despite being an advertised capability.
• Protocol version guard — clear, actionable error when the page's v does not match the panel's supported range.
• Graceful "no bQuery on this page" state and a hint on how to enable the bridge.
• Panel persistence (open sections, filters) via platform/storage.
• Theming that follows the DevTools light/dark theme.

3. Improvements over the current scaffold

• Component tree: search/filter, expand/collapse, attribute inspection, select-in-page / highlight on hover.
• Signals/stores: search, value drill-down for nested objects, copy-to-clipboard, ideally live updates instead of manual refresh.
• Timeline: filter by entry type, pause/resume, clear, configurable buffer size (currently a hard-coded 50-entry cap).
• Drop <all_urls> host permissions in favour of activeTab / opt-in permissions where MV3 allows it, and pin down the CSP.
• Treat every value from the inspected page as untrusted at the type level, not just at the render sink.

4. Quality gates

• Unit tests for the bridge client and message routing (the transport-agnostic createBridgeServer makes this testable without a browser).
• E2E smoke test loading the unpacked extension against a fixture bQuery app (Playwright or equivalent).
• CI: typecheck, lint, test, build MV3 + MV2 on PR.
• Release workflow producing signed/zipped MV3 + MV2 artifacts attached to a GitHub release.

5. Documentation

• README in the new repo: install (store links + unpacked), enable the bridge in an app, panel feature tour, protocol/version compatibility matrix, troubleshooting.
• CONTRIBUTING.md + architecture notes (message flow diagram, folder layout).
• Publishing guide for Chrome Web Store and AMO.

6. Migration in this repository

• Delete extension/.
• Update the references that point at it:
  • docs/guide/devtools.md (lines ~107, ~150, ~577)
  • docs/introduction.md (~63)
  • docs/release-notes/1.15.md (~60)
  • AGENT.md (~73), CHANGELOG.md (~202, historical — leave the past entry, add a new one)
  • src/devtools/index.ts (~10) and extension/README.md links
• Add a release-notes entry announcing the move + the new repo/store links.
• Keep @bquery/bquery/devtools exactly as-is — the bridge protocol stays in this repo and remains the stable contract. Any protocol change needed by the new extension comes back here as its own issue.

Non-goals

• Changing the bridge protocol or bumping BRIDGE_PROTOCOL_VERSION as part of this work.
• Publishing the extension to the stores before it reaches feature parity with the current scaffold plus the improvements above.

Acceptance criteria

1. bQuery/bquery-devtools-extension exists, is built on the template, and produces loadable MV3 (Chrome/Edge) and MV2 (Firefox) builds via deploy-v3 / deploy-v2.
2. The new extension connects over bridge protocol v1 to an app using connectDevtoolsBridge() and renders component tree, signals, stores, and timeline — at or above the current scaffold's capability.
3. CI in the new repo runs typecheck, lint, tests, and both builds on every PR.
4. The new repo is documented (README, contributing, architecture, publishing).
5. extension/ is removed from this repository and every reference in docs/AGENT.md/source comments points at the new repo.

References

• Template: https://github.com/JosunLP/BrowserExtensionTemplate
• Bridge protocol: src/devtools/bridge.ts, DevTools guide
• Original DevTools stability issue: [Feature]: Promote devtools to Stable — ship the browser-extension panel #146