Add integrated debugger DevTools core

docs/docs/command-line-references.md

@@ -152,7 +152,7 @@ Starts the Valdi [hotreloader](./start-about.md#prototype-quickly-with-hot-reloa
 - The `--target` option should be a valid Bazel target (ex: `//:hello_world_hotreload`).
 - The `--module` option will query and run targets in the current workspace which match the module_name.<br></br>
 
-`valdi debugger [--host host] [--port port] [--strict-port] [--json]`\
+`valdi debugger [--host host] [--port port] [--strict-port] [--json] [--web-preview-url url] [--chromium-debugging-port port]`\
 Starts a local browser-based Valdi debugger web interface. The debugger attaches
 to running Valdi daemon targets and exposes live view hierarchy, preview,
 inspector data, element snapshots, heap dumps, input dispatch, and runtime logs. CPU profiling
@@ -164,7 +164,14 @@ uses a separate Hermes debugger connection.
   available port so multiple local debugger sessions can run at once.
 - Use `--strict-port` to fail instead of auto-selecting another port.
 - Use `--json` to print one machine-readable startup object with the selected
-  `url`, `port`, `requestedPort`, and `portWasAutoSelected` fields.<br></br>
+  `url`, `port`, `requestedPort`, and `portWasAutoSelected` fields.
+- Use `--web-preview-url` to attach the integrated Elements and Console panel
+  to one exact loopback web/Owl page. The command prints a temporary unpacked
+  extension directory, adds the explicit Valdi debugger query parameters to
+  the preview URL, and defaults Chromium CDP discovery to port `9222`.
+- Use `--chromium-debugging-port` when Owl/Chromium was launched with a
+  different loopback `--remote-debugging-port`. The target page must provide
+  the opt-in `window.__VALDI_WEB_DEBUGGER__` snapshot/highlight contract.<br></br>
 
 `valdi inspect input <capabilities|query|tap|focus|text|key|scroll> [contextId]`\
 Queries or controls a running debug `valdi_application` through the default,

npm_modules/cli/README.md

@@ -89,6 +89,7 @@ For complete documentation, see:
 - Restricts the server to loopback addresses because debugger snapshots can contain application data
 - Prefers port `8765` and automatically selects the next available port so multiple local sessions can run at once
 - Supports `--json` for automation-friendly startup output
+- Supports exact-page Owl/Chromium attachment with `--web-preview-url` and `--chromium-debugging-port`; this emits a temporary first-party DevTools extension directory and an explicitly opted-in preview URL
 
 **`valdi skills`** - AI assistant skills
 - Installs Valdi context files into Claude Code, Cursor, or GitHub Copilot so AI tools generate correct Valdi code instead of React patterns

npm_modules/cli/debugger/README.md

@@ -10,14 +10,16 @@ the CLI package.
 - `debugger.css`: themes, layout, controls, preview, inspector, and responsive styles.
 - `debugger-state.js`: shared state, DOM references, constants, and action parameter helpers.
 - `debugger-api.js`: fetch helpers, action stream, and development reload stream.
-- `debugger-model.js`: snapshot normalization, tree traversal, bounds, issues, and selection helpers.
+- `debugger-tree-model.js`: transport-neutral hierarchy identity, traversal, lookup, and path helpers shared by both frontends.
+- `debugger-model.js`: snapshot normalization, bounds, issues, and standalone selection helpers.
 - `debugger-preview-html.js`: inert HTML projection of the hot-reloaded snapshot tree.
 - `debugger-render.js`: header, target list, tree, preview overlay, inspector, and export rendering.
 - `debugger-runtime.js`: target discovery, snapshots, runtime log streaming, heap, and copy/export helpers.
 - `debugger-performance.js`: Hermes CPU profile controls.
 - `debugger-actions.js`: UI actions, command prompt handling, auto-refresh, and externally driven debugger actions.
 - `debugger-session.js`: `sessionStorage` restore/persist for reload-friendly debugger state.
 - `debugger-bootstrap.js`: DOM event wiring and boot sequence.
+- `devtools-panel.html`, `devtools-panel.css`, and `devtools-panel.js`: the focused Chromium Elements and Console panel embedded by the generated extension.
 
 Scripts are loaded as classic browser scripts in the order listed in
 `index.html`. There is no module loader or bundler for this frontend; shared
@@ -35,6 +37,8 @@ Important routes:
 - `/api/runtime-logs` and `/api/runtime-logs/stream`: read and stream target logs.
 - `/api/debugger/state`, `/api/debugger/events`, and `/api/debugger/actions`: keep the browser UI and external agents in sync.
 - `/api/performance/profile/*`: list Hermes contexts and capture CPU profiles.
+- `/api/devtools/target`: matches the inspected Chromium page to the exact configured preview origin and path.
+- `/api/devtools/snapshot`, `/api/devtools/highlight`, and `/api/devtools/evaluate`: proxy the explicit web debugger bridge contract through loopback CDP.
 
 Renderer tracing is intentionally not part of this foundation. It requires the
 separate runtime and native renderer-instrumentation stack; land that stack
@@ -43,8 +47,10 @@ profiling uses the existing inspector transport and has no such prerequisite.
 Target input forwarding and data/network provider tabs should likewise land
 with their runtime-side contracts and end-to-end tests rather than as inactive
 browser-only surfaces.
-Web-renderer inspection should land together with its first-party bridge rather
-than expose an inert preview flag from this foundation.
+Web-renderer inspection depends on the target page explicitly exposing
+`window.__VALDI_WEB_DEBUGGER__` with `getSnapshot()`, `highlightNode()`, and
+`clearHighlight()`. The renderer-side adapter is intentionally outside this
+CLI/DevTools core.
 
 Detailed debugger snapshots explicitly opt in to component ViewModel and state
 serialization. That data can be sensitive, is bounded by a per-field and
@@ -53,6 +59,11 @@ tree` requests. Auto-refresh starts disabled so serialization remains a
 deliberate local debugging action. The server rejects non-loopback Host,
 Origin, and cross-site browser API requests.
 
+The normal debugger document and every other static asset use
+`frame-ancestors 'none'` plus `X-Frame-Options: DENY`. Only
+`/devtools-panel.html` permits a Chromium extension ancestor; executable
+DevTools routes additionally require same-origin JSON requests.
+
 ## Development Loop
 
 For an installed CLI:
@@ -69,6 +80,20 @@ npm run build
 node dist/index.js debugger --host 127.0.0.1 --port 8765
 ```
 
+For a manually launched Owl/Chromium web preview:
+
+```bash
+node dist/index.js debugger \
+  --web-preview-url http://127.0.0.1:8080/index.html \
+  --chromium-debugging-port 9222
+```
+
+Start Owl/Chromium with the printed `--remote-debugging-port` and
+`--load-extension` values, then open the exact opted-in preview URL printed by
+the command. Target matching removes only the injected `valdiDebugger` and
+`valdiDevTools` parameters, then requires the same origin, pathname, and
+remaining query parameters.
+
 The synthetic native-tree preview never auto-loads projected HTTP(S) image,
 video, CSS background, or WebView resources. Only `data:` and `blob:` media are
 assigned; WebView contents are represented by an inert placeholder.