Skip to content

Architecture

prjctimg edited this page Aug 5, 2026 · 1 revision

Architecture

p5.nvim is split across three runtimes that talk to each other over localhost sockets:

flowchart LR
    NV["Neovim\nlua/p5/*.lua"] -->|"http/curl"| SRV["server.py\nasyncio HTTP + WS"]
    NV -->|"jobstart +\n--remote-debugging-port"| CR["Chrome (isolated)"]
    SRV -->|"http /json\nCDP WebSocket"| CR
    CR -->|"Performance.metrics\nRuntime.evaluate"| SRV
    SRV -->|"SSE /api/console/stream"| NV
    NV -->|"render 6-tab panel"| UI["HUD window"]
    CR -.->|"EventSource /api/console/stream\nWebSocket ws://localhost:12002"| SRV
Loading

Module Map

lua/p5/
β”œβ”€β”€ init.lua      # setup(), config defaults, autocmds
β”œβ”€β”€ commands.lua  # :P5 subcommand dispatch + interactive picker
β”œβ”€β”€ core.lua      # path resolution, caching, utils, Chrome discovery
β”œβ”€β”€ project.lua   # sketchspace scaffolding (p5.json, templates)
β”œβ”€β”€ server.lua    # server lifecycle, port allocation, health checks
β”œβ”€β”€ libraries.lua # p5.js + contrib library management
β”œβ”€β”€ gist.lua      # Gist create/sync/edit, sketchbook cloning
β”œβ”€β”€ cdp.lua       # CDP panel: HUD, tabs, eval, breakpoints, perf
└── health.lua    # :checkhealth p5

Runtime Flow

Server start

sequenceDiagram
    participant N as Neovim
    participant S as server.py
    participant P as Python process
    N->>S: :P5 server (start)
    S->>P: jobstart python3 server.py --port 8000
    P-->>S: stdout lines (URL, port)
    S->>S: polls /api/health until ready
    S->>N: notify "Server running on http://localhost:8000"
Loading

The Lua side spawns server.py as a job, parses its stdout for the actual bound port (requested port may be taken), and keeps the job reference in server.server_job.

Sketch open

:P5 create/:P5 setup writes runtime assets (p5.js, libs.js, p5.d.ts) into assets/libs inside the sketchspace, hydrating from the version cache at ~/.cache/p5.nvim/versions or falling back to a CDN. index.html is generated from a template and injects the runtime + console/livereload scripts.

Data Flow: Console

  1. console.js is injected into the page and hooks console.log/warn/error/info.
  2. Messages are POSTed to /api/console/log (or forwarded via the CDP debugger events when the panel is connected).
  3. Neovim consumes a Server-Sent Events stream at /api/console/stream and appends entries to the Console tab.
  4. While CDP is connected, the injectable hook is bypassed via the __P5_CDP_ACTIVE flag so messages are captured exactly once.

Configuration Propagation

init.lua setup(opts) deep-merges user options into module-level config tables:

flowchart LR
    USR["user opts"] --> SETUP["setup()"]
    SETUP --> CORE["core.config"]
    SETUP --> PRJ["project.config"]
    SETUP --> SRV["server.config"]
    SETUP --> LIB["libraries.config"]
    SETUP --> GIST["gist.config"]
    SETUP --> CDP["cdp.config"]
Loading

The dev server reads the same settings from p5.json and the config passed via CLI flags (--port, --live-reload-port, --cdp-port, …).

Design Decisions

  • No server dependencies β€” server.py uses only asyncio, json, and http.server from the standard library, plus websockets for live reload (a soft import β€” live reload degrades gracefully if it is missing).
  • Isolated Chrome β€” the CDP panel launches Chrome with a throwaway --user-data-dir and binds debugging to 127.0.0.1, so a normal browser session is never disturbed and the port is always available.
  • Non-blocking β€” long-running loops (file watcher, SSE stream, CDP event stream) all run in the server's asyncio event loop; Neovim stays responsive.

Clone this wiki locally