PtrLens

Visual C++ memory tracing for Vix Note.

PtrLens compiles C++ code with debug information, executes it through LLDB, captures stack variables and pointer relationships, builds a visual memory model, and returns an SVG representation to Vix Note.

int value = 42;
int* pointer = &value;

PtrLens turns this relationship into a visual result:

Stack

┌─────────────────────┐
│ value               │◄─────────┐
│ int                 │          │
│ 42                  │          │
└─────────────────────┘          │
                                 │
┌─────────────────────┐          │
│ pointer             │──────────┘
│ int*                │
│ 0x...
└─────────────────────┘

Features

• C++ compilation with debug information;
• LLDB-based source-level tracing;
• stack frame discovery;
• local variable inspection;
• pointer and reference detection;
• resolved and unresolved memory relationships;
• null pointer detection;
• visual memory snapshots;
• SVG output for Vix Note;
• structured diagnostics;
• one-shot Vix Note extension protocol;
• standalone executable runtime.

Current scope

PtrLens 0.1.0 focuses on:

• stack variables;
• primitive values;
• basic pointers;
• references;
• source locations;
• final memory snapshot rendering.

Heap allocation lifetime tracking, delete detection, smart pointers, dangling pointers, memory leaks, animated timelines, and interactive stepping are planned for later versions.

Requirements

PtrLens currently targets Unix-like platforms.

Required tools:

C++20 compiler
CMake 3.20 or newer
LLDB
Vix Note

Recommended compiler:

clang++

Default compiler command:

c++

Default debugger command:

lldb

Repository structure

PtrLens/
├── CMakeLists.txt
├── LICENSE
├── README.md
├── vix.json
├── include/
│   └── ptrlens/
│       ├── compiler_process.hpp
│       ├── debugger_process.hpp
│       ├── error.hpp
│       ├── kernel.hpp
│       ├── memory_model.hpp
│       ├── protocol.hpp
│       ├── ptrlens.hpp
│       ├── request.hpp
│       ├── response.hpp
│       ├── result.hpp
│       ├── svg_renderer.hpp
│       ├── trace.hpp
│       └── version.hpp
├── src/
│   ├── compiler_process.cpp
│   ├── debugger_process.cpp
│   ├── kernel.cpp
│   ├── main.cpp
│   ├── memory_model.cpp
│   ├── protocol.cpp
│   ├── svg_renderer.cpp
│   └── trace.cpp
├── tests/
│   ├── kernel_test.cpp
│   ├── memory_model_test.cpp
│   ├── protocol_test.cpp
│   └── svg_renderer_test.cpp
├── examples/
│   ├── basic_pointer.cpp
│   └── heap_allocation.cpp
└── docs/
    └── protocol.md

Build

Build PtrLens with Vix:

vix build

The executable is generated in the active Vix build directory.

For a release build:

vix build --preset release

Build without tests

vix build -- \
  -DPTRLENS_BUILD_TESTS=OFF

Build examples

vix build --build-target all -- \
  -DPTRLENS_BUILD_EXAMPLES=ON

Run tests

vix tests

Run tests with failure details:

vix tests --output-on-failure

Build all targets before running the tests:

vix build --build-target all
vix tests --output-on-failure

The current test targets are:

ptrlens.protocol
ptrlens.kernel
ptrlens.memory_model
ptrlens.svg_renderer

Install locally

cmake --install build --prefix ~/.local

The executable is installed under:

~/.local/bin/ptrlens

The public headers are installed under:

~/.local/include/ptrlens

Vix Note extension

PtrLens is a normal Vix executable package with an extensions.note declaration.

The package identity is:

softadastra/ptrlens

The runtime command is:

ptrlens

The contributed cell type is:

ptrlens

The visible label in Vix Note is:

C++ Memory

The extension uses:

protocol: vix-note-extension-1
mode: oneshot

Install through Vix

After PtrLens is published to the Vix Registry:

vix registry sync
vix install -g softadastra/ptrlens

Inspect extension discovery:

vix note --list-extensions

Start Vix Note:

vix note

The cell type picker should include C++ Memory.

Manual runtime test

PtrLens reads one JSON request from standard input and writes one JSON response to standard output.

cat <<'JSON' | ./build/ptrlens
{
  "protocol": "vix-note-extension-1",
  "requestId": "manual-test",
  "cellId": "basic-pointer",
  "cellType": "ptrlens",
  "source": "#include <iostream>\n\nint main()\n{\n  int value = 42;\n  int* pointer = &value;\n  std::cout << *pointer << '\\n';\n  return 0;\n}\n",
  "executionCount": 0,
  "workingDirectory": ".",
  "documentPath": "",
  "extensionId": "softadastra/ptrlens",
  "extensionVersion": "0.1.0"
}
JSON

A successful response has this general form:

{
  "protocol": "vix-note-extension-1",
  "ok": true,
  "stdout": "PtrLens captured execution steps and generated memory snapshots.\n",
  "outputs": [
    {
      "mime": "image/svg+xml",
      "data": "<svg>...</svg>"
    }
  ]
}

Execution pipeline

Vix Note request
  -> JSON validation
  -> temporary C++ source
  -> debug compilation
  -> LLDB execution
  -> trace parsing
  -> memory model
  -> SVG rendering
  -> Vix Note response

Compiler configuration

Override the compiler with:

PTRLENS_COMPILER=clang++ ./build/ptrlens

Default:

c++

PtrLens currently compiles source with options equivalent to:

-std=c++20
-g
-O0
-fno-omit-frame-pointer
-fno-optimize-sibling-calls

Debugger configuration

Override the debugger with:

PTRLENS_DEBUGGER=lldb ./build/ptrlens

Default:

lldb

The current trace parser expects LLDB-compatible output.

Preserve temporary artifacts

PtrLens normally removes temporary source files, binaries, debugger scripts, and logs after execution.

Preserve them for debugging:

PTRLENS_PRESERVE_ARTIFACTS=1 ./build/ptrlens

Temporary artifacts are stored under:

<working-directory>/.ptrlens/tmp/

or under the system temporary directory when no working directory is provided.

Include the raw debugger trace

PTRLENS_INCLUDE_RAW_TRACE=1 ./build/ptrlens

This adds a text/plain output containing the raw LLDB trace.

Environment variables

Variable	Purpose
PTRLENS_COMPILER	Overrides the C++ compiler command.
PTRLENS_DEBUGGER	Overrides the debugger command.
PTRLENS_PRESERVE_ARTIFACTS	Preserves temporary execution artifacts.
PTRLENS_INCLUDE_RAW_TRACE	Includes raw debugger output in the response.

Enabled boolean values are:

1
true
yes
on

Error responses

Expected failures are returned as structured JSON.

{
  "protocol": "vix-note-extension-1",
  "ok": false,
  "error": {
    "code": "compilation_failed",
    "message": "PtrLens could not compile the C++ source.",
    "details": "program.cpp:4: error: expected expression"
  }
}

Common error codes include:

invalid_request
invalid_protocol
invalid_source
compiler_not_found
compilation_failed
debugger_not_found
debugger_failed
trace_failed
process_failed
timeout
invalid_response
internal_error

Public C++ API

Include the umbrella header:

#include <ptrlens/ptrlens.hpp>

The public API exposes:

• protocol request and response types;
• compiler process;
• debugger process;
• execution trace model;
• memory model;
• SVG renderer;
• execution kernel;
• structured errors and results.

Example:

#include <ptrlens/ptrlens.hpp>

int main()
{
  ptrlens::MemorySnapshot snapshot;

  ptrlens::MemoryObject value;
  value.id = "value";
  value.name = "value";
  value.type = "int";
  value.value = "42";
  value.region = ptrlens::MemoryRegion::stack;

  snapshot.objects.push_back(value);

  ptrlens::SvgRenderer renderer;
  auto result = renderer.render(snapshot);

  return result ? 0 : 1;
}

Limitations

PtrLens currently does not provide:

• a persistent debugger process;
• interactive Step Into or Step Over controls;
• frontend JavaScript contributions;
• custom Vix Note CSS;
• runtime sandboxing;
• heap lifetime instrumentation;
• reliable new and delete event detection;
• dangling pointer detection;
• memory leak detection;
• smart pointer ownership graphs;
• GDB support;
• Windows process support.

The current Vix Note extension API starts one external runtime for each execution.

Security

PtrLens compiles and executes user-provided C++ code locally.

The current implementation does not provide:

• filesystem isolation;
• network isolation;
• process isolation;
• container sandboxing;
• interactive permission approval.

Only execute trusted C++ code.

Roadmap

v0.1.0

• Vix Note protocol;
• C++ debug compilation;
• LLDB execution;
• stack variables;
• pointer relationships;
• SVG final snapshot.

v0.2.0

• improved trace parsing;
• multiple stack frames;
• references and arrays;
• richer source locations;
• multiple SVG snapshots.

v0.3.0

• heap object discovery;
• new and delete events;
• object lifetime tracking;
• released memory visualization.

v0.4.0

• smart pointers;
• ownership relationships;
• dangling pointer diagnostics;
• memory leak diagnostics.

v1.0.0

• complete execution timeline;
• animated SVG export;
• shareable HTML reports;
• stable extension runtime;
• expanded platform support.

Protocol documentation

See:

docs/protocol.md

License

PtrLens is licensed under the MIT License.

Copyright © 2026 Softadastra.