Interactive Reversible Debugger

Step through execution forwards and backwards—inspect state, structure, and history in one place.

 

---

Why this exists

Traditional debuggers let you pause and step forward. IRD records execution snapshots so you can rewind as well: compare states, walk back to a suspect line, and pair that with graph views of objects and an optional quantum-circuit teaching mode. It is built as a modern web app with strict TypeScript, automated checks in CI, and a clear boundary around how user-typed code is evaluated.

---

Contents

Features	What you get out of the box
Stack	Libraries and tooling
Quick start	Clone, env, run
Configuration	Env vars and routing
Scripts	npm commands
Quality & CI	Tests and GitHub Actions
Security	Execution model and data
Docs & code map	Architecture and Supabase
Contributing	PRs and guidelines
License	MIT

---

Features

Capability	What it does
Bidirectional stepping	Move forward and backward through recorded execution states (snapshot replay in the UI).
Object graph	Visualize references and structure while you step.
Trace view	See how often lines ran and how state evolved.
Quantum mode	Step through a small educational circuit simulator.
Checkpoints & sessions	Save checkpoints; persist sessions via Supabase when your project has the right tables.

---

Stack

Layer	Choices
Build	Vite 5, TypeScript (strict), ES modules
UI	React 18, Tailwind CSS, shadcn/ui (Radix primitives)
Data & navigation	TanStack Query, React Router
Backend (optional)	Supabase Auth + Postgres for persistence

---

Quick start

Prerequisites: Node.js 20+ (CI uses 22). Use npm with the committed lockfile.

git clone https://github.com/fraware/reversible-execution-lab.git
cd reversible-execution-lab
npm ci
cp .env.example .env          # then edit with your Supabase URL + anon key
npm run dev

The dev server runs on port 8080 (see vite.config.ts). Open the URL shown in the terminal.

Tip: Tests can use .env.test so you do not need a full .env just to run npm run test:run.

---

Configuration

Environment variables

Only names beginning with VITE_ are exposed to client code.

Variable	Required	Meaning
VITE_SUPABASE_URL	yes	Project URL, e.g. https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY	yes	Public anon key from Supabase → Project Settings → API

Copy .env.example to .env or .env.local. Validation runs through src/lib/env.ts. The anon key is meant for the browser, but you should still use Row Level Security on every user table and rotate keys per environment.

Routes

Path	Who can access	Role
/	Signed-in users	Main debugger
/project	Everyone	Landing / project story
/login	Everyone	Sign in or sign up

---

Scripts

Command	Use when…
npm run dev	Local development
npm run build	Production bundle → dist/
npm run build:dev	Build with Vite development mode
npm run preview	Sanity-check the production build locally
npm run lint	Run ESLint
npm run typecheck	Run tsc on the app (no emit)
npm run test	Vitest watch mode
npm run test:run	Vitest once (matches CI)

---

Quality & CI

• Tests: Vitest, jsdom, Testing Library helpers — config in vitest.config.ts, setup in src/test/setup.ts, specs as src/**/*.test.ts.
• Pipeline: On every push and pull request to main, .github/workflows/ci.yml runs install, lint, typecheck, tests, and build. Placeholder VITE_* values are injected so no repo secrets are required for the build step.
• Dependencies: Dependabot proposes npm and GitHub Actions updates on a schedule.

---

Security

• Arithmetic on the right-hand side of assignments is handled by a small safe parser (safeExpression.ts), not eval or new Function.
• Full JavaScript interpretation in the browser is out of scope for this build; optional worker-based numeric evaluation lives in sandboxRunner.ts.
• Any Supabase tables holding user data must use RLS — see docs/SUPABASE.md.

---

Docs & code map

Doc	Topic
docs/ARCHITECTURE.md	Execution pipeline, backends, reversal model
docs/SUPABASE.md	Tables, env, RLS
CONTRIBUTING.md	Branching, checks before PR

Handy entry points in source:

File	Responsibility
src/lib/executionBackend.ts	ExecutionBackend abstraction
src/lib/executionEngine.ts	Line stepping, checkpoints, delay & abort
src/lib/reversibleExecutionModel.ts	Snapshot timeline helpers
src/integrations/supabase/client.ts	Supabase client

---

Contributing

We welcome issues and pull requests. Please read CONTRIBUTING.md, then run lint, typecheck, and tests locally so your PR matches CI.

---

License

Distributed under the MIT License.