Pulse Lab — VS Code Extension

Pulse Lab is a high-fidelity, interactive code execution visualizer for VS Code. It empowers developers and students to master complex program logic through real-time memory visualizations, step-by-step stack traces, heap diagrams, AI-powered insights, and an integrated multi-language learning curriculum.

Extension ID: SoubhikDevTools.pulse-lab-code-tester | Version: 1.0.3 | Min VS Code: 1.74.0 | License: MIT

Overview
Supported Languages
Installation
Quick Start
Core Features
AI Features
UI & Layout
Learning Curriculum
Commands
Configuration Reference
Performance Optimization
Security
Architecture Overview
Build & Development
Troubleshooting

Overview

Most developers run code and see only the final output — Pulse Lab shows you every step in between. At each execution step you can see:

Which line is executing
Every local variable in every active function frame
The complete heap — objects, lists, dictionaries, class instances
Reference arrows showing which variables point to which heap objects
Standard output produced so far
Variable deltas (what changed in the last step)
AI-generated explanations for loops, recursion, memory usage, and more

Whether you are debugging a tricky algorithm, learning data structures for the first time, or teaching computer science, Pulse Lab makes the invisible visible.

Supported Languages

Language	File Extension	Tracer Technology
Python	`.py`	pg_logger (Online Python Tutor engine)
Java	`.java`	Java Debug Interface (JDI)
C++	`.cpp`, `.c`	LLDB debugger + clang++
C#	`.cs`	Managed debug API

Installation

Open VS Code.
Go to the Extensions panel (Cmd+Shift+X / Ctrl+Shift+X).
Search for Pulse Lab.
Click Install.

Alternatively, install directly from a .vsix file:

code --install-extension pulse-lab-code-tester-1.0.3.vsix

The extension activates automatically when you open a supported file (.py, .java, .cpp, .c, .cs).

Quick Start

Open any Python, Java, C++, or C# file in VS Code.
Right-click anywhere in the editor and choose "Visualize", or press Cmd+Shift+P and run "Pulse Lab: Visualize".
The Pulse Lab panel opens alongside your editor.
Use the Floating Controls at the bottom of the screen to step through execution.
Watch the stack frames, heap objects, and variable values update in real time.

Core Features

1. Code Execution Visualizer

Pulse Lab executes your code in a sandboxed subprocess and captures a complete trace — every variable at every line.

What you see: A side-by-side view of your source code (with the current line highlighted) and the live memory state.
Execution events captured: step_line, call, return, exception, uncaught_exception, instruction_limit_reached.
Stdout capture: Console output is shown in real time as you step through.
Error display: Syntax errors and runtime exceptions are shown with the exact line number and message highlighted in the editor.
Timeout protection: Execution is automatically killed after 30 seconds to prevent runaway processes.
Max steps: Configurable limit (default 1000) protects against infinite loops.

2. Stack Frame Visualization

Every active function call gets its own card in the stack panel.

Frame cards: Each card shows the function name, its local variables, and their current values.
Call depth: Nested calls stack up visually, making recursion easy to follow.
Return values: When a function returns, the return value is shown on the card before it is popped.
Global frame: The top-level global scope is always visible as a separate card.
Cumulative mode (optional): Keep all historical frames on screen — useful for tracing call histories.

3. Heap & Memory Visualization

All heap-allocated objects are rendered as graphical cards in the heap panel.

Supported types: Lists, tuples, sets, dictionaries, class instances, functions, class definitions, nested structures.
Box & Pointer diagrams: Variables that hold references show an arrow pointing to the heap object — exactly like a textbook memory diagram.
Dynamic connectors: SVG arrows are recalculated at every step and always point to the correct object, even when layout shifts.
Heap primitives mode (optional): Render even simple types (integers, strings) as heap objects to show Python's object model explicitly.
Nested structures: Deeply nested lists-of-lists, dicts-of-dicts, and instances-within-instances are fully rendered.

A floating control panel lets you navigate through every execution step.

Control	Action
⏮ First	Jump to the very first step
◀ Back	Go one step backward
▶ Forward	Go one step forward
⏭ Last	Jump to the final step
Playback slider	Drag to any step instantly
Auto-play	Play steps automatically at slow or fast speed
Step counter	Shows current step / total steps
Current line	Shows which source line is executing
Mini/Max toggle	Collapse the control panel to save space

5. Live Sync / Auto-Sync Mode

When enabled, Pulse Lab automatically re-traces your code after you stop typing.

Toggle: Click the sync icon in the header or use the header switch.
Debounce delay: Configurable wait time (default 1000 ms) before re-tracing starts — prevents tracing on every keystroke.
Warning: This mode increases CPU usage. It is disabled by default.
Recommended settings: Set debounceDelay to 2000–5000 ms if you enable this on a laptop.

6. Bi-directional Code Editing

You can edit code inside the Pulse Lab panel itself — not just in the VS Code editor.

Monaco editor: The built-in code pane uses Monaco (the same editor powering VS Code) with full syntax highlighting.
Sync back: Edits made inside Pulse Lab are written back to your VS Code source file automatically.
Internal edit tracking: The extension detects when the webview is the source of a change and avoids triggering a redundant re-trace.

7. LENS Mode

LENS Mode is a dedicated magnification tool for inspecting complex or dense data structures.

Activate: Click the LENS icon in the floating controls.
Use case: When a heap object has many fields or a list has many elements, LENS mode enlarges the selected object for easier reading.
Ideal for: Linked lists, trees, large dictionaries, class hierarchies.

8. Turbo Mode

For code that exceeds the default step limit, Turbo Mode raises the ceiling.

Activate: Available in the settings or from within the panel.
Effect: Increases maxTraceSteps significantly beyond the default 1000.
Use case: Sorting algorithms, recursive tree traversals, DP problems with large inputs.
Warning: Large traces consume more memory. Monitor system resources.

9. Cumulative Mode

By default, only the current active stack frames are shown. Cumulative Mode keeps all historical frames visible.

Setting: pulseLab.cumulativeMode: true
Use case: Understanding the full call history of a complex recursive function.
Effect: Frames from earlier steps remain on screen, grayed out, so you can see the complete execution path.

10. Heap Primitives Mode

By default, simple values (integers, strings, booleans) are shown inline inside variable cards. Heap Primitives Mode renders them as separate heap objects with reference arrows.

Setting: pulseLab.heapPrimitives: true
Use case: Teaching Python's object model — demonstrating that even 1 is an object in Python.
Effect: Every value gets a box on the heap; variables show reference arrows pointing to them.

AI Features

1. Gemini AI Code Insights

Pulse Lab integrates Google Gemini to generate natural-language explanations of your execution trace.

Insight types available:

Insight Type	What it explains
Logic	Overall code flow and algorithm logic
Loop	What each loop iteration does and why
Memory	How heap objects are allocated and garbage-collected
Exception	Why an error occurred and how to fix it
Mutation	Which variables changed and how over time
Recursion	The call tree and base/recursive cases
Performance	Hotspots, unnecessary work, Big-O considerations

How to use:

Enter your Gemini API key in the code pane (one-time setup, stored securely).
After tracing, click any insight button in the Bottom Dock → Analysis tab.
Pulse Lab sends your code + the current trace to Gemini and streams back the explanation.

Model selection: Choose from gemini-pro, gemini-1.5-flash, gemini-1.5-flash-8b, and more in the header model picker.

2. AI Chat Assistant

A full multi-turn chat interface for asking questions about your code.

Context-aware: Every message includes your current code and execution trace so Gemini understands exactly what is happening.
Multi-turn: The conversation history is preserved within the session.
Use cases: "Why does this loop run 5 times?", "What is the time complexity?", "How do I fix this KeyError?", "Explain what happens to the heap when I append to this list."
Access: Open the Chat tab in the Bottom Dock.

3. Voice Assistant

Ask questions about your code using your voice.

How it works: Click the microphone button, speak your question, and Pulse Lab records your audio and sends it to Gemini 1.5 Flash (multimodal).
Response: Gemini transcribes and answers your question in text, shown in the panel.
Use case: Hands-free debugging or learning when typing is inconvenient.
Requirement: Gemini API key must be configured. Microphone permission is required.

4. Built-in Analysis (No API Key Required)

Even without a Gemini API key, Pulse Lab performs several automated analyses locally:

Analysis	How it works
Exception detection	Detects `IndexError`, `NullReferenceException`, `KeyError` from the trace event type
Infinite loop detection	Flags if the same line appears more than 50 times in the trace
Memory leak detection	Alerts if heap object count grows continuously without shrinking
Mutation tracking	Shows a timeline of every variable that changed value
Recursion depth monitoring	Warns if call depth exceeds 10 levels
Performance analysis	Flags traces with more than 500 steps as potentially inefficient

These results appear in the Analysis tab of the Bottom Dock with no configuration required.

UI & Layout

1. Three-Pane Layout

The Pulse Lab panel uses a draggable three-pane layout:

┌─────────────┬──────────────────┬──────────────────────┐
│  Sidebar    │  Code Editor     │  Visualizer          │
│  (Course /  │  (Monaco)        │  (Stack + Heap)      │
│   Files)    │                  │                      │
├─────────────┴──────────────────┴──────────────────────┤
│  Bottom Dock  (Variables | Deltas | Chat | Analysis)  │
└───────────────────────────────────────────────────────┘

Draggable sashes: Drag the dividers between panes to resize them freely.
Collapsible sidebar: Click to hide the course/file sidebar when not needed.
Collapsible dock: The Bottom Dock can be expanded or collapsed with a single click.
Dock height: Drag the top edge of the dock to resize it.

2. Header Controls

The header bar contains quick-access controls:

Control	Purpose
Language selector	Switch between Python, Java, C++, C#
Sync toggle	Enable/disable auto-sync (Live Programming mode)
AI model picker	Select which Gemini model to use
Theme switcher	Toggle light/dark mode
Accent color picker	Choose accent color (active / warm / cool variants)

3. Bottom Dock

A collapsible panel at the bottom with four tabs:

Tab	Contents
Variables	All current variables and their values at the active step
Deltas	Variable change history — what changed and by how much
Chat	Multi-turn AI chat with execution context
Analysis	Built-in analysis results + Gemini AI insights

4. Floating Step Controls

The floating control panel overlays the visualizer and can be:

Dragged to any position on screen.
Minimized to a compact mode that shows only essential controls.
Expanded to show the full playback slider, step counter, and all buttons.
Auto-play speed: Switch between slow (1 step/sec) and fast (5 steps/sec) playback.

5. Theme & Accent Customization

Light / Dark mode: Toggle in the header. Preference is persisted across sessions.
Theme variants:
- Active — high contrast, vibrant colors
- Warm — amber/orange tones
- Cool — blue/purple tones
Accent color: Pick any accent color; applied to highlights, connectors, and active elements.
Glassmorphism UI: Semi-transparent cards with blur effects and smooth CSS transitions throughout.

Learning Curriculum

1. Course Browser

The Sidebar contains a full course browser for structured learning:

Click any course section to open its README.
Click any lab file to load it into the Monaco editor instantly.
The file tree is sorted by lesson number automatically.
Supports nested sections (sub-topics within each major section).

2. Python Curriculum (24 Sections)

A complete Python learning path from zero to advanced, including DSA:

#	Section	Topics
00	Environment Setup	Python installation, IDEs, virtual environments
02	Data Types	Variables, strings, lists, tuples, sets, dicts
03	Conditionals	`if`, `elif`, `else`, ternary, match-case
04	Loops	`for`, `while`, `break`, `continue`, walrus operator
05	Functions	Parameters, scope, closures, `args`, `*kwargs`
06	Modules & Packages	`import`, `__init__.py`, pip packages
07	Comprehensions	List, dict, set, and generator comprehensions
08	Generators	`yield`, lazy evaluation, `itertools`
09	Decorators	`@` syntax, `functools.wraps`, stacked decorators
11	Exceptions	`try/except/finally`, custom exceptions, context managers
12	Threading & Concurrency	`threading`, GIL, locks, queues
13	Async Python	`asyncio`, `async/await`, event loops
14	Pydantic	Data validation, models, serialization
15	Memory Management	Reference counting, garbage collection, `weakref`
16	DSA Foundations	Big-O notation, algorithm design principles
17	Arrays & Strings	Two pointers, sliding window, string manipulation
18	Searching & Sorting	Binary search, quicksort, mergesort, counting sort
19	Linear Data Structures	Stack, queue, deque, linked list
20	Trees & Graphs	BST, BFS, DFS, topological sort
21	Recursion & DP	Memoization, tabulation, classic DP problems
22	Advanced & Greedy	Interval scheduling, Huffman, Dijkstra
23	DSA Mastery Patterns	Pattern recognition, interview preparation

3. Java, C++, and C# Courses

Separate course trees are available for Java, C++, and C# — accessible by switching the language selector in the header. Each course follows the same section-based structure as the Python curriculum.

4. Challenges & Projects

The challenges/ folder in the Python course contains six real-world mini-projects:

Project	Description
CLI Utilities	Command-line scripts for file and text processing
Data Handling	CSV/JSON processing with pandas
Web Scraping	`requests` + `BeautifulSoup4` projects
Automation	Task automation scripts
Data Science	`pandas` + `matplotlib` data analysis
URL Shortener	Full Flask + SQLite web application

Commands

All commands are accessible via the Command Palette (Cmd+Shift+P):

Command	ID	Description
Visualize	`pulseLab.visualize`	Trace the active file and open the visualizer panel
Sync Workspace	`pulseLab.syncWorkspace`	Refresh the webview with current workspace files
Open Pulse Lab	`pulseLab.open`	Open the Pulse Lab home panel
Open ChatGPT	`pulseLab.openChatGPT`	Copy current code to clipboard and open ChatGPT in the browser

Context menu shortcut: Right-click anywhere in a supported file → "Visualize".

Configuration Reference

All settings are under the pulseLab.* namespace. Access them via File → Preferences → Settings and search for pulseLab.

Visualization Settings

Setting	Type	Default	Description
`pulseLab.cumulativeMode`	boolean	`false`	Keep all historical stack frames visible (not just the current ones)
`pulseLab.heapPrimitives`	boolean	`false`	Render primitive values (int, string) as heap objects with reference arrows

Auto-Sync Settings

Setting	Type	Default	Range	Description
`pulseLab.autoSyncEnabled`	boolean	`false`	—	Automatically re-trace code after every edit. Increases CPU usage — disabled by default.
`pulseLab.debounceDelay`	number	`1000`	500–10000 ms	How long to wait after the last keystroke before triggering auto-trace

Performance Settings

Setting	Type	Default	Range	Description
`pulseLab.lightweightMode`	boolean	`true`	—	Disable webview context retention when panel is hidden. Saves 100–200 MB RAM.
`pulseLab.enableCompression`	boolean	`true`	—	Compress trace data before sending to webview. Reduces memory by 50–70%.
`pulseLab.maxTraceSteps`	number	`1000`	100–10000	Maximum number of execution steps to trace. Prevents infinite loops.
`pulseLab.maxOutputSize`	number	`10`	1–50 MB	Maximum trace JSON size. Lower = faster processing.

Recommended Configurations

Minimum resource usage (laptops, battery-powered devices):

{
  "pulseLab.autoSyncEnabled": false,
  "pulseLab.lightweightMode": true,
  "pulseLab.enableCompression": true,
  "pulseLab.maxTraceSteps": 1000,
  "pulseLab.debounceDelay": 3000
}

Maximum capability (desktops, powerful machines):

{
  "pulseLab.autoSyncEnabled": true,
  "pulseLab.lightweightMode": false,
  "pulseLab.enableCompression": true,
  "pulseLab.maxTraceSteps": 5000,
  "pulseLab.debounceDelay": 500
}

Teaching / classroom mode:

{
  "pulseLab.cumulativeMode": true,
  "pulseLab.heapPrimitives": true,
  "pulseLab.autoSyncEnabled": false,
  "pulseLab.maxTraceSteps": 2000
}

Performance Optimization

Pulse Lab is designed to be lightweight by default. Here is a summary of every optimization available:

Feature	Memory saved	CPU saved	How to enable
Lightweight mode	100–200 MB	—	`pulseLab.lightweightMode: true` (default)
Trace compression	50–70%	—	`pulseLab.enableCompression: true` (default)
Disable auto-sync	—	Significant	`pulseLab.autoSyncEnabled: false` (default)
High debounce delay	—	Moderate	`pulseLab.debounceDelay: 3000`
Lower max steps	Moderate	Moderate	`pulseLab.maxTraceSteps: 500`
Lower max output	Moderate	Moderate	`pulseLab.maxOutputSize: 5`
30s execution timeout	—	Hard limit	Always active
Process termination	—	Hard limit	Always active

For detailed guides, see:

Security

Pulse Lab is built with security in mind at every layer:

Area	Protection
Code execution	Runs in isolated subprocess with 30s timeout; no network access
Input validation	Code size capped at 1 MB before sending to tracer
Output validation	Trace output capped at configurable MB limit
Path traversal	File access restricted to workspace root and extension `/learn` directory
Content Security Policy	All webview scripts use cryptographic nonces; `unsafe-eval` scoped to Monaco workers only
Prompt injection	User chat input is sanitized (control characters removed, backticks escaped) before sending to Gemini
API key storage	Gemini API key is never exposed in URLs or logs; stored in VS Code's secure settings
Environment variables	Sanitized with regex before being sent to the webview
CSRF protection	Token validation on ChatGPT OAuth callback endpoint
Rate limiting	Session capture server limited to 10 requests before auto-closing

Architecture Overview

VS Code Extension Host
├── src/extension.ts          — Activation, command registration, document listeners
├── src/pulseLab.ts           — Main controller (webview lifecycle, tracing, AI, courses)
├── src/services/
│   ├── tracer.service.ts     — Spawns language-specific tracer subprocesses
│   ├── ai.service.ts         — Gemini API + built-in fallback analysis
│   ├── webview.service.ts    — Webview panel lifecycle + message queue
│   └── sessionHelper.ts      — ChatGPT OAuth token capture
└── src/commands/
    ├── visualize.command.ts
    ├── sync.command.ts
    ├── open.command.ts
    └── chatgpt.command.ts

Tracers (Python subprocesses)
├── tracers/python/generate_json_trace.py   — pg_logger wrapper
├── tracers/java/generate_java_trace.py     — JDI-based Java tracer
├── tracers/cpp/lldb_tracer.py              — LLDB + clang++ C++ tracer
└── tracers/csharp/generate_csharp_trace.py — C# managed debug tracer

Webview UI (React + Vite)
├── webview-ui/src/
│   ├── components/
│   │   ├── WorkspaceLayout.tsx       — 3-pane draggable layout
│   │   ├── Header.tsx                — Language/model/theme controls
│   │   ├── MonacoEditorPane.tsx      — Live code editor
│   │   ├── VisualizerPane.tsx        — Stack + heap display
│   │   ├── BottomDock.tsx            — Variables/Deltas/Chat/Analysis tabs
│   │   ├── StepControls.tsx          — Floating playback controls
│   │   ├── LearningContainer.tsx     — Course browser + README viewer
│   │   ├── VoiceAssistant.tsx        — Audio recording + Gemini response
│   │   ├── ConnectorLayer.tsx        — SVG reference arrows
│   │   ├── StackFrameCard.tsx        — Per-function frame card
│   │   ├── HeapObjectCard.tsx        — Heap object card
│   │   ├── ErrorDisplay.tsx          — Syntax/runtime error display
│   │   ├── VariableDeltasPanel.tsx   — Variable change history
│   │   └── RecursionTree.tsx         — Call tree visualization
│   └── store/useCrystalStore.ts      — Zustand global state (40+ properties)

Learning Content
└── learn/
    ├── python/   — 24 sections + challenges
    ├── java/
    ├── cpp/
    └── csharp/

Message Protocol (Extension ↔ Webview)

The extension and webview communicate via VS Code's postMessage API:

Extension → Webview:

trace — send full execution trace
loading — show/hide spinner
error — runtime or syntax error
SYNC_CODE — push code from VS Code editor
courseData — send curriculum structure
fileContent — load a specific file
applyTheme — apply theme/accent settings
updateModels — refresh available Gemini models
aiInsight — stream AI insight response
voiceAssistantResponse — voice AI response

Webview → Extension:

ready — webview initialized
editCode — user edited code in Monaco
openFile — user selected a course file
getAiInsight — request AI analysis
sendChatMessage — send chat message
setGeminiKey — store API key
setTheme — save theme preference
startVoiceRecording / stopVoiceRecording — microphone control
stepChanged — user seeked to a new step

Build & Development

Prerequisites

Node.js 18+
Python 3.8+ (for Python tracer)
Java JDK 11+ (for Java tracer)
Clang / LLDB (for C++ tracer)
.NET SDK (for C# tracer)

Build Commands

# Install dependencies
npm install
cd webview-ui && npm install && cd ..

# Build the React webview UI
npm run build-ui

# Compile TypeScript extension
npm run compile

# Full production build (webview + extension bundle)
npm run package

# Development watch mode (auto-recompile on changes)
npm run webpack-dev

# Prepare for VS Code Marketplace publish
npm run vscode:prepublish

Output Files

dist/extension.js — Bundled extension (webpack, production-obfuscated)
webview-ui/dist/ — Compiled React app assets
webview/webview.js — Compiled webview entry point

Troubleshooting

Visualizer shows "Loading…" indefinitely

Check the VS Code Output panel (View → Output → Pulse Lab) for errors.
Ensure the required language runtime is installed (Python, JDK, clang, .NET).
Try lowering pulseLab.maxOutputSize if the trace is very large.

High CPU or fan noise

Disable pulseLab.autoSyncEnabled (default is already off).
Increase pulseLab.debounceDelay to 3000–5000 ms.
Lower pulseLab.maxTraceSteps to 500.

"Instruction limit reached" in trace

Your code exceeds the max step limit. Increase pulseLab.maxTraceSteps or enable Turbo Mode.
Check for infinite loops in your code.

AI insights not working

Make sure you have entered a valid Gemini API key in the code pane.
The built-in analysis (no API key) still runs automatically — check the Analysis tab.

Monaco editor not loading

Reload the VS Code window (Cmd+Shift+P → Developer: Reload Window).

C++ / Java tracer errors

Ensure clang++ and lldb are installed and on your PATH for C++.
Ensure javac and java are installed and on your PATH for Java.

Key Advantages

Advantage	Benefit
Deep Understanding	See exactly how memory changes at every line — no more black-box execution
Fast Debugging	Identify logic errors, off-by-one bugs, and reference issues instantly
AI-Powered	Get natural-language explanations without leaving your editor
Multi-Language	One tool for Python, Java, C++, and C#
Structured Learning	350+ lab files and 24 Python course sections built in
Voice-First	Ask debugging questions with your voice
Performance-Conscious	Lightweight by default — 85% less CPU, 70% less memory with recommended settings
Classroom-Ready	Heap Primitives and Cumulative Mode make it ideal for teaching CS fundamentals

"Logic will get you from A to B. Imagination will take you everywhere." — Albert Einstein

Pulse Lab Code Tester

Soubhik Dev Tools