jcv — JSON Canvas Viewer

Terminal viewer for JSON Canvas 1.0 files, with live reload.

jcv opens a .canvas file straight in your TTY: pan, zoom, and watch it update in real time as you edit the file in Obsidian (or any other editor). No GUI, no browser, no SSH tunnels.

The demo above is generated by docs/demo.tape — render it locally with vhs docs/demo.tape.

Install

# from crates.io
cargo install jcv

# or grab a prebuilt binary from the latest GitHub release:
#   https://github.com/hgflima/jcv/releases

Pre-built binaries are produced for macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported in v0.

Usage

jcv path/to/file.canvas      # open and watch
jcv --help                   # flags and keymap
jcv --version

While the viewer is open:

Key	Action
h j k l / arrows	Pan the viewport
+ / -	Zoom in / out
Mouse scroll	Pan vertically (Ctrl = horizontal)
Alt + scroll	Zoom in / out
?	Toggle the help overlay
q / Esc	Quit (or close the help overlay)
Ctrl-C	Quit

While jcv is open the terminal captures the mouse, which disables the default click-and-drag text selection. Hold Option/Alt while dragging to bypass the capture and select text the usual way (works in Warp, iTerm2, and most modern terminals).

Warp users: Warp does not propagate keyboard modifiers (Ctrl, Alt, Shift) on mouse-wheel events (warp#1114). Plain scroll for vertical pan still works, but Ctrl+scroll (horizontal pan) and Alt+scroll (zoom) won't reach the app — use the keyboard shortcuts (h/l, +/-) instead, or switch to iTerm2/Ghostty/WezTerm for full mouse support.

The viewer is read-only: jcv never writes to your .canvas file. When the file changes on disk it is re-parsed and re-rendered within ~500 ms; if the new contents are invalid you see an error banner and keep the previous view instead of crashing.

Supported nodes

All four JSON Canvas 1.0 node kinds render:

• text — markdown body rendered inside a bordered box. Supported: ATX headings (H1/H2 underlined), bold, italic, inline code, strikethrough, links (rendered as label (url)), bulleted/ordered/task/nested lists, blockquotes (per-level │ prefix), fenced code blocks, and horizontal rules. Tables, raw HTML, embedded images and syntax highlighting are intentionally out of scope. With NO_COLOR set, structural styling (BOLD, ITALIC, UNDERLINED, CROSSED_OUT) survives but colours are dropped and task markers fall back to ASCII [x] / [ ].
• file — path with a file icon (or [F] when NO_COLOR is set)
• link — URL with an OSC 8 hyperlink where the terminal supports it
• group — dashed border drawn behind its children

Edges route Manhattan-style with one elbow, fall back to ASCII (-|+) when Unicode box-drawing is unavailable, and truncate labels with … when there isn't room.

Environment

• NO_COLOR — disables colour output entirely
• JCV_LOG — tracing env filter (default info); logs go to $XDG_STATE_HOME/jcv/jcv.log (~/.local/state/jcv/jcv.log on Linux, ~/Library/Application Support/jcv/jcv.log on macOS)

Building from source

git clone https://github.com/hgflima/jcv
cd jcv
cargo build --release
./target/release/jcv tests/fixtures/all-node-types.canvas

Requires a stable Rust toolchain (MSRV 1.75).

Status

v0 is a viewer. Editing, PNG export, and a desktop GUI are deferred to later releases — see docs/SPEC.md for the scope and docs/PLAN.md for the roadmap.

License

MIT — see LICENSE.