AI assistance: This document was written with AI assistance. The maintainer reviewed it and did not find errors.

marser-trace-viewer

Experimental: UI, CLI, and replay behavior may change between releases without the same stability guarantees as the core marser library. Pin versions and read release notes when upgrading.

Terminal UI for inspecting parser traces (JSON / JSONL). This crate depends on marser-trace-schema and does not depend on marser.

Run

From this workspace:

cargo run -p marser-trace-viewer -- --trace path/to/trace.json --source path/to/input.txt

Install as a binary:

cargo install marser-trace-viewer
marser-trace-viewer --trace path/to/trace.json --source path/to/input.txt

Arguments

• --trace <path> (required): path to JSON or JSONL trace file.
• --source <path> (optional): source input used for span preview.
• --format json|jsonl (optional): force parser format. If omitted, format is auto-detected.

Key bindings

• i: step into (next explicit trace start, including nested markers)
• s: step over (current start -> matching end -> next start)
• u: step out (parent end -> next start after parent end)
• backspace: jump back to previously displayed start
• q: quit

Stepping model

The viewer intentionally prioritizes explicit .trace() markers:

• visible step targets are only marker start events
• each marker has a start/end pair linked by trace_marker_id
• startup jumps to the first visible user marker start

This keeps replay deterministic and aligned with grammar-level trace points.

End-to-end example with marser

Generate a trace from the JSON example:

cargo run -p marser --features "annotate-snippets parser-trace" --example json -- tests/data/json1.json --trace-file /tmp/json-trace.json

Open it in the viewer:

cargo run -p marser-trace-viewer -- --trace /tmp/json-trace.json --source tests/data/json1.json

Related docs

See guide/07-tracing-and-debugging.md for the tracing API (parse_with_trace, parse_with_trace_to_file) and detailed replay semantics.