Skip to content

CDP Integration

prjctimg edited this page Aug 5, 2026 · 1 revision

CDP Integration

The CDP panel gives you real Chrome debugging inside Neovim: console, network, eval, breakpoints, performance metrics, and screenshots — all driven through the Chrome DevTools Protocol, proxied by server.py.

Enabling

require("p5").setup({ cdp = { enabled = true } })

Then open the panel with :P5 cdp.

Chrome Isolation

Instead of hijacking your browser session, p5.nvim launches its own Chrome instance:

  • A throwaway --user-data-dir (removed on close when cdp.close_browser_on_close is set)
  • --remote-debugging-address=127.0.0.1 so the debug port is reachable even when regular Chrome is already running
  • --remote-debugging-port from config (9222 by default)

This means the panel never disturbs your personal Chrome tabs and always has a clean, debuggable profile.

Attaching

sequenceDiagram
    participant N as Neovim
    participant S as server.py
    participant C as Chrome (CDP)
    N->>S: POST /api/cdp/connect
    S->>C: GET /json (list targets)
    C-->>S: pages[]
    S->>S: pick page whose url starts with http://localhost:<port>
    S->>C: open WebSocket /devtools/page/...
    S-->>N: {"status":"connected","url":...}
    N->>N: open 6-tab HUD panel
Loading

The page selection prefers the tab served from this project's dev-server origin, so eval, breakpoints, and perf target the right document even when Chrome has several tabs open.

The Panel

Six tabs, switched with keys 1–6 (or mouse):

Tab Key Content
Console 1 JS console output, deduped between the injected hook and CDP
Network 2 Completed requests from Network.loadingFinished
Eval 3 Evaluate expressions in the page
Debug 4 Breakpoints, pause/continue, stepping, paused-frame highlight
Perf 5 Live FPS, JS heap, DOM nodes, listeners, FPS sparkline
Info 6 Project info, live canvas state, LSP symbols

Performance Metrics

Perf metrics come from Chrome's Performance.metrics events — no fabricated values:

  • FPS — delta of the cumulative Frames counter between ~1s events (first sample seeds the baseline and shows no FPS rather than a false 0)
  • JS Heap — used (JSHeapUsedSize) and total (JSHeapTotalSize) reported separately
  • DOM nodes — Nodes counter
  • Listeners — JSEventListeners counter

Debugging

Breakpoints

Set a breakpoint with :P5 cdp break sketch.js:12 (or the b key with the panel focused).

Breakpoints are resolved against the served script URL:

  1. The Debugger.scriptParsed map matches the URL exactly, or the basename.
  2. If a bare filename is given, it is resolved against the page origin before Debugger.setBreakpointByUrl — V8 matches sourceURL exactly, so a raw basename never hits.

Paused state

  • While paused, eval runs on the current call frame via Debugger.evaluateOnCallFrame
  • The paused line is highlighted in the HUD buffer
  • continue, step, stepIn, stepOut, and pauseExceptions (none/uncaught/all) are available

Console capture

The injected console.js posts to /api/console/log; the CDP Runtime.consoleAPICalled path is used while connected. A __P5_CDP_ACTIVE flag on the page disables the injectable hook while CDP is active so messages are captured exactly once.

Other Features

  • Live canvas state — the Info tab evaluates frameRate(), canvas size, frame count, and p5 mode from the live page on connect and on tab switch
  • Screenshots — :P5 cdp screenshot [path] captures the page as a PNG (base64 from Chrome is decoded with vim.base64.decode before writing)
  • Reload — :P5 cdp reload triggers Page.reload with ignoreCache: true, so p5 asset/sketch changes are picked up even when cached
  • Network clear — :P5 cdp network_clear empties the Network tab

Command Reference

:P5 cdp                     # open the panel
:P5 cdp connect             # attach to Chrome (or already-connected)
:P5 cdp disconnect          # detach
:P5 cdp status              # connection state + page URL
:P5 cdp eval <expr>         # evaluate in the page
:P5 cdp break <file:line>   # set breakpoint
:P5 cdp continue            # resume
:P5 cdp pause               # pause execution
:P5 cdp pauseExceptions [none|uncaught|all]
:P5 cdp reload              # Page.reload with ignoreCache
:P5 cdp screenshot [path]   # save PNG screenshot
:P5 cdp step | stepIn | stepOut
:P5 cdp perf                # open the Performance tab
:P5 cdp network_clear       # clear network log

HUD keymaps (cdp.keymaps = false to disable): 1–6 tabs, s screenshot, i/o step/step-out, p/P pause/pause-exceptions, R reload, S symbol list.

Clone this wiki locally