Skip to content

Server and API

prjctimg edited this page Aug 5, 2026 · 1 revision

Server and API

server.py is a zero-dependency asyncio HTTP server (Python 3, standard library only) that serves sketchspaces and mediates between Neovim and Chrome.

Starting

From Neovim:

:P5 server start
:P5 server status
:P5 server stop

Or directly:

python3 server.py --port 8000

Static Serving

  • index.html, sketch.js, and anything else under the sketchspace root are served with cache-friendly headers
  • assets/libs/p5.js is served with long-lived caching keyed by the pinned p5.js version
  • Missing p5.js files are hydrated on demand from ~/.cache/p5.nvim/versions or the configured CDN sources

Endpoints

Console relay

Method Path Purpose
POST /api/console/log Injectable console.js posts log entries here
GET /api/console/stream Server-Sent Events stream consumed by the CDP Console tab

Health

Method Path Purpose
GET /api/health Liveness check; returns JSON { "status": "ok" }

CDP proxy

Method Path Purpose
POST /api/cdp/connect Attach to Chrome; prefers the page served from this server's origin
DELETE /api/cdp/connect Detach
GET /api/cdp/status Connection state + page URL
GET /api/cdp/stream SSE stream of CDP events (Runtime.consoleAPICalled, Debugger.paused, perf metrics, …)
POST /api/cdp/evaluate Evaluate JS in the page (expression); uses Debugger.evaluateOnCallFrame while paused
POST /api/cdp/debug/break Set a breakpoint (location, e.g. sketch.js:12)
POST /api/cdp/debug/continue Resume execution
POST /api/cdp/debug/pause Pause execution
POST /api/cdp/debug/pauseExceptions state = none | uncaught | all
POST /api/cdp/debug/step / stepIn / stepOut Single-stepping
DELETE /api/cdp/network Clear the network log
POST /api/cdp/page/reload Page.reload with ignoreCache: true
GET /api/cdp/page/screenshot Page.captureScreenshot, returns base64 PNG

WebSockets

The live-reload server runs a WebSocket on ws://localhost:12002:

Message Direction Meaning
{ "type": "connected" } server → page Reload channel established
{ "type": "reload", "path": "..." } server → page A watched file changed; reload the page

File Watcher

A background asyncio task watches the sketchspace with a debounce:

  • Extensions watched: .js, .css, .html, .json (configurable)
  • Directories excluded: .git, node_modules, dist, build (configurable)
  • Changes trigger a reload message on the live-reload socket, or a CDP Page.reload when the panel is connected
sequenceDiagram
    participant W as File watcher
    participant S as server.py
    participant P as Page (livereload.js)
    W->>S: file changed (debounced)
    S-->>P: ws reload message
    P-->>P: location.reload()
Loading

Clone this wiki locally