Vivix

See Inside JavaScript As It Thinks

Instruction-level JavaScript execution with simultaneous heap visualization

Most JavaScript visualizers show you the event loop at a high level. Vivix steps through every individual instruction — subexpression evaluation, heap mutations, stack operations — one tick at a time via the CPU dashboard. No account required, no install, completely free and open source.

What is this?

Most JS tutorials tell you what code does. Vivix shows you.

https://github.com/user-attachments/assets/e122c133-234b-4c5f-b483-c1ffc928f778

You write JavaScript, hit play, and step through execution one instruction at a time watching variables appear in heap memory, call stack frames push and pop, byte sizes update, and the CPU dashboard tick through each operation. It's like having X-ray vision for JavaScript.

No sign-up. No install. Runs entirely in your browser.

🎬 Demo

https://github.com/user-attachments/assets/40b2d503-50bc-45df-bbc6-b1950e017141

What You Get

9 Interactive Modules

Each module teaches a core JavaScript concept with a purpose-built visualization:

Quick Start

git clone https://github.com/HenryOnilude/vivix.git
cd vivix
npm install
npm run dev      # → http://localhost:5173

npm run test     # 332 unit tests
npm run build    # production build + SEO pages

🏗️ How It Works

Your Code → Acorn Parser → AST → Custom Interpreter → Step Array → Visualizer

1. Acorn parses user code into an AST
2. Custom interpreter (interpreter.js) walks the AST and produces an array of execution steps each step captures line index, variables, memory ops, call stack, phase, and output
3. Step controls let you scrub forward/backward through the step array
4. CpuDash renders each step as an SVG CPU visualization (registers, phase, program counter)
5. Module panels render step-specific data (heap cards, scope chains, array cells, etc.)

The interpreter runs in a Web Worker for non-blocking execution, with a 500-step limit to prevent infinite loops.

Key Design Decisions

• No runtime eval — the interpreter walks the AST directly, so we capture every intermediate state
• Shared shell — ModuleShell.svelte handles code editing, step controls, playback, timeline, and keyboard shortcuts; modules only provide the visualization
• Accessibility themes — 3 themes via CSS custom properties (--a11y-*)
• Hash routing — SPA with #/module routes, no server config needed
• Shareable URLs — base64-encoded code + step index in the URL hash

🧰 Tech Stack

📁 Project Structure

src/lib/
  interpreter.js         ← AST walker, step generator (99 + 71 + 62 tests)
  async-executor.js      ← async/await step executor (38 tests)
  shell-logic.js         ← shared step utilities (35 tests)
  url-state.js           ← shareable URL encoding (20 tests)
  a11y-theme.js          ← accessibility theme system
  ModuleShell.svelte     ← shared module layout
  CodeEditor.svelte      ← CodeMirror 6 wrapper
  CpuDash.svelte         ← SVG CPU dashboard
  OnboardingTour.svelte  ← first-run guided tooltips
  Home.svelte            ← landing page with live demo
  Variables.svelte       ← varStore module
  IfGate.svelte          ← ifGate module
  ForLoop.svelte         ← forLoop module
  FnCall.svelte          ← fnCall module
  ArrayFlow.svelte       ← arrayFlow module
  ObjExplorer.svelte     ← objExplorer module
  DataStructures.svelte  ← dataStruct module
  AsyncAwait.svelte      ← asyncFlow module
  Closures.svelte        ← closureScope module
scripts/
  generate-seo-pages.js  ← build-time SEO pages + sitemap

⚠️ Known Limitations

The interpreter is an educational tool, not a full JS engine. A few simplifications:

• Flat scope — let/const inside blocks (if, for, while) share the outer scope. Variables declared in a block are visible outside it. This means the classic "closure in a loop with let" pattern behaves like var (all closures share the final value).
• No this in standalone functions — this is only supported for class method calls, not general this binding.
• Limited built-ins — supports core methods (push, pop, map, filter, reduce, Object.keys, Math.*, etc.) but not the full standard library.
• No prototypes or new (outside classes) — constructor functions with new are not supported; use the class syntax instead.
• 500-step limit — prevents infinite loops but caps very long programs.

These trade-offs keep the visualizations clear and the codebase manageable while covering the concepts that matter most for learning.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a PR.

npm run test     # run before submitting

📄 License

MIT — use it, learn from it, build on it.