LT-Vis — Linear & Tree Data Structure Visualizer

An interactive playground that turns core data-structure algorithms into step-by-step animations. LT-Vis is designed for teaching and self-paced exploration: every operation produces a timeline of renderer-friendly events you can play, pause, and rewind in the browser.

Project Overview

• Scope: Linked list, stack, binary tree (with traversals), and binary search tree (insert/find/delete) — all implemented from scratch in TypeScript and instrumented with OpStep / VizEvent timelines.
• Architecture: Monorepo managed by pnpm. Pure model logic lives in packages/model-ts, shared contracts in packages/shared, and the React/Vite UI in apps/web.
• Goal: Keep the model layer renderer-agnostic while delivering a smooth classroom-friendly visualization experience.

Workspace Layout

.
├─ apps/web/             # React + Vite client (timeline viewer, demo scenarios)
├─ packages/shared/      # Cross-package TypeScript contracts (Structure, OpStep, VizEvent)
├─ packages/model-ts/    # Data structures + operation → timeline engines
├─ docs/                 # Product requirements and design specs
├─ examples/             # Executable timeline samples mirroring course demos
└─ README.md

Getting Started

1. Install prerequisites

   • Node.js 20 (Volta recommended)
   • pnpm ≥ 9 (corepack enable or npm i -g pnpm)

2. Bootstrap the workspace

   pnpm install

3. Run the demo

   pnpm dev

   Navigate to the printed Vite URL (default http://localhost:5173). Use the scenario selector to explore linked list, stack, binary tree, and BST timelines.

Development Commands

Command	Description
pnpm dev	Start the web app in Vite dev mode
pnpm build	Build web client and compile model package
pnpm test	Placeholder; wire up Vitest/Playwright here
pnpm typecheck	Run tsc across all packages (contracts enforced)

Extending the Model Layer

• Implement new structures inside packages/model-ts/src/structures. Each should emit OpStep[] describing the visualization timeline.
• Register structures with StructureSession to execute operations and collect steps.
• Mirror new operations in apps/web/src/scenarios.ts so the demo can showcase them.

UI & Visualization Notes

• The current renderer is a lightweight SVG snapshot viewer (SnapshotCanvas). Swapping to React Flow or another layout engine only requires consuming the existing VizEvent stream.
• Timeline playback lives in apps/web/src/components/TimelinePlayer.tsx and demonstrates play/pause, scrubbing, and speed changes.

Documentation & Collaboration

• Contributor guidelines live in AGENTS.md.
• Formal requirements and architecture decisions are documented under docs/ (REQUEST.md, DESIGN.md).
• When proposing changes, keep commit messages terse and scoped (e.g. model: add huffman builder) and request reviews from the relevant module owner.

Troubleshooting

• Vite cannot resolve @lt-vis/model-ts: If you see Failed to resolve entry for package "@lt-vis/model-ts", make sure you are running the dev server from the repo root with pnpm dev. The Vite config (apps/web/vite.config.ts) aliases @lt-vis/shared and @lt-vis/model-ts directly to their src/ entrypoints, so no prebuild is required. If the error persists, double-check for local overrides to the Vite config or rebuild the model package with pnpm -C packages/model-ts build or simply pnpm build.