PROJECT.md

Project: AlgoViz Redesign & Enhancement Blueprint

Architecture

AlgoViz is transformed from a collection of ad-hoc setTimeout pages into a modern, decoupled educational algorithm visualization platform built with Next.js 14 App Router, TypeScript, Tailwind CSS, and Vitest.

Core Architecture Layers:

1. Engine Layer (src/engine/):
   • Pure, deterministic algorithm step generators returning immutable snapshots: Step<TState>[].
   • Algorithm logic is decoupled 100% from React rendering and browser timers.
   • Centralized playback controller (usePlaybackEngine) managing step indices, play/pause/resume/restart, step forward/backward, speed scaling, and state restoration without race conditions.
2. Design System & Token Layer (src/styles/ & src/components/ui/):
   • Semantic color tokens via CSS custom properties (--background, --surface, --card, --border, --text-primary, --text-secondary, --primary, --accent-compare, --accent-swap, --accent-sorted, etc.).
   • Dark and Light themes with WCAG AA compliance and zero hardcoded canvas styles.
   • Elimination of 336 lines of brittle !important overrides in globals.css.
   • Reusable primitive components (Button, Input, Slider, Badge, Tabs, Modal, Drawer, Tooltip).
3. Workspace & Educational Layer (src/components/workspace/):
   • Dedicated IDE-style WorkspaceLayout maximizing canvas area.
   • Synchronized pseudocode viewer with real-time active line highlighting derived from currentStep.codeLine.
   • Educational panels: step execution narrative log, multi-language code inspector (JS, Python, C++, Java), and detailed time/space complexity analysis.
   • Collapsible desktop sidebars and responsive mobile drawers/tabs.
4. Specialized Visualizer Presentation Layer (src/components/visualizers/):
   • Sorting: Animated vertical bars with comparing, swapping, sorted, pivot, active states, value indicators, and operation counters.
   • Searching: Array cells with animated low/mid/high pointers and search region elimination.
   • Linked Lists: Node-based blocks with pointer arrows, head/tail badges, animated insertion, deletion, and traversal.
   • Stacks & Queues: Vertical stack with push/pop animations, top pointer; horizontal queue with front/rear pointers.
   • Hierarchical Trees: Dynamic SVG/coordinate layout for BST and B-Tree preventing node overlap and clipping.
   • Interactive Graph: Interactive 2D graph supporting directed/undirected modes, weighted edges, node creation/dragging, BFS, DFS, and Dijkstra's algorithm displaying shortest paths.
5. Testing & QA Layer (src/__tests__/):
   • Vitest unit test suite covering 100% of step generators, playback state transitions, and edge cases (410 tests passed across 10 test suites).

---

Feature Inventory

#	Feature	Description	Milestone	Status
F01	Existing Baseline Audit	Complete audit of 27 routes, bugs, and architecture	Phase 0	DONE
F02	Design Tokens & System	Semantic CSS variables, dark/light theme, clean globals.css	M1	DONE
F03	UI Component Library	Reusable buttons, inputs, sliders, badges, tabs, modals	M1	DONE
F04	TypeScript Setup	tsconfig.json, core type declarations, mixed TS/JS compilation	M1	DONE
F05	Test Framework Setup	Vitest configuration, test runner scripts in package.json	T1 / M1	DONE
F06	Step Engine Data Contract	Immutable Step interface, step types, metadata, codeLine	M2	DONE
F07	Playback Engine Hook	usePlaybackEngine with play/pause/stepFwd/stepBack/speed/reset	M2	DONE
F08	Custom Input Validation	Parsing, range validation, error toasts and graceful fallbacks	M2	DONE
F09	Workspace Shell Layout	Canvas-first layout, collapsible panels, responsive breakpoints	M3	DONE
F10	Pseudocode Line Sync	Real-time line highlighting synchronized with active step	M3	DONE
F11	Educational Panels	Step narrative log, multi-language code tabs, complexity cards	M3	DONE
F12	Sorting Step Generators	Pure generators for Bubble, Selection, Insertion, Merge, Quick, Heap, Counting, Radix, Bucket	M4	DONE
F13	Sorting Bar Visualizer	Animated vertical bars, state coloring, value tags, stats counter	M4	DONE
F14	Searching Step Generators	Pure generators for Linear, Binary, Jump, Interpolation, Exponential, Ternary, Fibonacci	M4	DONE
F15	Searching Visualizer	Array cells, low/mid/high pointers, search region elimination	M4	DONE
F16	Linked List Visualizer	Node blocks, pointer arrows, head/tail indicators, animated ops	M5	DONE
F17	Stack & Queue Visualizer	Vertical stack (push/pop), horizontal queue (enqueue/dequeue)	M5	DONE
F18	Hierarchical Tree Visualizer	Non-overlapping BST and B-Tree SVG/canvas layout with search/insert	M5	DONE
F19	Interactive Graph Visualizer	Directed/undirected, weighted edges, node dragging, BFS, DFS	M5	DONE
F20	Dijkstra Algorithm	Shortest path finder with distance table, relaxation, and path highlight	M5	DONE
F21	Homepage Redesign	Hero section ("Understand Algorithms. See How They Work."), 5 categories, interactive preview, complete footer	M6	DONE
F22	Category Hubs & Routing	Preserved routes, updated category indices (/sorting, /searching, /basic_dsa)	M6	DONE
F23	ESLint & Bug Fixes	Fixed all 22 exhaustive-deps warnings, modal leaks, queue/tree bugs	M6	DONE
F24	Mobile & Tablet Responsiveness	Responsive down to 375px, touch-friendly controls, zero horizontal scroll	M6	DONE
F25	Sorting & Searching Unit Tests	Vitest tests for Bubble, Selection, Insertion, Merge, Quick, Heap, Linear, Binary	M4 / T1	DONE
F26	DSA & Graph Unit Tests	Vitest tests for Linked List, Stack, Queue, BST, BFS, DFS, Dijkstra	M5 / T1	DONE
F27	Edge-Case Hardening	Tests for empty, single-element, duplicates, negatives, sorted, reverse, missing target	M4 / M5	DONE
F28	Build & Audit Verification	npm run build passes with 0 errors, npm run lint with 0 errors/warnings, forensic audit CLEAN	M7	DONE
F29	Category Hub Modernization	Redesign /basic_dsa and category pages with modern design system tokens and card grid	M8	DONE
F30	Sorting Bar Token Unification	Replace hardcoded bar colors with semantic CSS tokens (--accent-default, --primary, etc.)	M8	DONE
F31	Search & DSA Usability & Auto-Play	Remove duplicate search target headers, auto-play visualization immediately upon operation trigger	M8	DONE
F32	Responsive Layout & Wrap Polish	Prevent awkward toolbar/header wrapping and horizontal scrollbars on desktop/tablet/mobile	M8	DONE
F33	Category Hubs (/sorting & /searching)	Modernize /sorting and /searching main pages to match /basic_dsa design system	M9	DONE
F34	Homepage Hero Demo Polish	Fix bar rendering, container scaling, heights, spacing, and styling in interactive preview	M9	DONE
F35	World-Class Platform Enhancements	Apply platform-wide visualizer and UX polish across AlgoViz	M9	DONE
F36	Array Visualizer Migration	Migrate /basic_dsa/array to WorkspaceLayout with insert shift, delete shift back, search, update	M10	DONE
F37	Educational Detail Article Sections	Comprehensive educational sections below workspace across all algorithms/tools	M10	DONE
F38	Global Navbar Search & Keyboard Nav	Instant fuzzy/partial search across all 30+ algorithms with Enter route and Esc close	M10	DONE
F39	Button & Interaction Animations	Active state indicators on code language selector, smooth tab transitions, feedback	M10	DONE
F40	Smooth Animation Quality	Consistent easing, stable element coordinates, zero jumpiness or flickering	M10	DONE
F41	Semantic Green Design System	Consolidate visualizer palette to green-tint tokens (--viz-*) and remove inconsistent blue	M10	DONE
F42	Mobile & Tablet Viewport Audit	Full responsiveness down to 360px-430px, 768px tablet, and desktop viewports	M10	DONE
F43	Library Additions (Priority Queue, Circular Queue, AVL)	New visualizers for Priority Queue, Circular Queue, and AVL Tree with full step engines	M10	DONE
F44	3-Part Dynamic Step Explanations	Every step explains: What is happening, Why it happens, and What will happen next	M10	DONE
F45	Brand Identity & Vector Asset Suite	High-res SVG logos, symbol marks, full favicon suite, PWA manifest, OG preview	M11	DONE
F46	Technical SEO & Rich Structured Data	Descriptive route metadata, OpenGraph/Twitter tags, sitemap.xml, robots.txt, JSON-LD Schema.org	M11	DONE
F47	Performance & Core Web Vitals	Dynamic code-splitting, skeleton visualizer loaders, ErrorBoundaries, render optimization	M11	DONE
F48	Accessibility (a11y) & Polish	ARIA controls, visible keyboard focus rings, prefers-reduced-motion support, zero warnings	M11	DONE
F49	Responsive Workspace Layout & Toolbar	Dedicated full-width canvas action toolbar with responsive flex-wrapping	M12	DONE
F50	Equal-Width Tabs & Zero Clipping	Tabs.tsx equal-width grid distribution, overflow-hidden, and shortLabel support	M12	DONE
F51	Universal Educational Knowledge Base	educationalKnowledge.ts covering 30+ algorithms and data structures	M12	DONE
F52	100% Educational Coverage	EducationalArticle mounted below canvas on all 42 application routes	M12	DONE
F53	Mobile ControlsDock Wrapping	ControlsDock.tsx centered touch-friendly rows on mobile (<640px)	M12	DONE

---

Milestones

#	Name	Scope	Dependencies	Status
T1	Test Infrastructure & Vitest Suite	Setup Vitest, vitest.config.ts, package.json scripts, test harnesses	none	DONE
M1	Design Tokens, UI System & TypeScript	tsconfig.json, CSS tokens, clean globals.css, theme provider, UI primitives	none	DONE
M2	Deterministic Playback Engine	Pure Step contract, usePlaybackEngine hook, input validation	M1	DONE
M3	Workspace Layout & Educational Panels	WorkspaceLayout, synchronized pseudocode highlighter, multi-language code inspector, metrics	M1, M2	DONE
M4	Sorting & Searching Visualizers	Step generators for all 9 sorting and 7 searching algorithms, specialized visualizers	M2, M3	DONE
M5	Data Structures, Trees & Graph Engine	Linked List, Stack, Queue, BST, B-Tree, interactive Graph with BFS/DFS/Dijkstra	M2, M3	DONE
M6	Homepage, Hubs, Linting & Responsiveness	Homepage redesign, 5 categories, interactive preview, category pages, fix ESLint warnings	M1, M3, M4, M5	DONE
M7	Full Verification, E2E Tests & Hardening	Run full Vitest suite, run build, run lint, adversarial edge case verification, forensic audit	T1, M1-M6	DONE
M8	User Feedback Remediation & UX Polish	Redesign /basic_dsa, unify sorting bar tokens, auto-play search/DSA ops, fix layout wrapping & overflow	M1-M7	DONE
M9	Category Hubs Modernization & Hero Demo Polish	Upgrade /sorting & /searching main pages, fix homepage interactive preview, apply world-class enhancements	M1-M8	DONE
M10	Phase 2 Master Development	Migrate array visualizer, restore educational articles, global search, buttons, green tokens, new tools (PQ, Circular Queue, AVL), 3-part narratives	M1-M9	DONE
M11	Phase 3 Brand, SEO, Performance & A11y	SVG brand suite, full favicon set, OpenGraph image, PWA manifest, SEO metadata, JSON-LD, sitemap, code splitting, skeletons, ErrorBoundary, a11y	M1-M10	DONE
M12	Responsive Layout & Universal Educational Coverage	Responsive canvas toolbar, equal-width tab grid, universal educational articles across 100% of 42 routes	M1-M11	DONE

---

Interface Contracts

1. Step Engine Contract (src/engine/types.ts)

export type StepType = 
  | 'start' 
  | 'compare' 
  | 'swap' 
  | 'move' 
  | 'pivot' 
  | 'partition' 
  | 'split' 
  | 'merge' 
  | 'sorted' 
  | 'found' 
  | 'not_found' 
  | 'insert' 
  | 'delete' 
  | 'traverse' 
  | 'relax' 
  | 'complete';

export interface Step<TState = any> {
  stepIndex: number;
  totalSteps: number;
  type: StepType;
  state: TState;
  activeIndices?: number[];
  secondaryIndices?: number[];
  pointers?: Record<string, number | string | null>;
  codeLine?: number; // 1-based index in pseudocode
  explanation: string;
  metrics: {
    comparisons: number;
    swaps?: number;
    operations: number;
    [key: string]: number | undefined;
  };
}

export interface PlaybackControls {
  isPlaying: boolean;
  currentStepIndex: number;
  totalSteps: number;
  speed: number;
  play: () => void;
  pause: () => void;
  stepForward: () => void;
  stepBackward: () => void;
  restart: () => void;
  reset: () => void;
  setSpeed: (speed: number) => void;
  goToStep: (stepIndex: number) => void;
}

2. Workspace Layout Contract (src/components/workspace/WorkspaceLayout.tsx)

export interface WorkspaceLayoutProps {
  title: string;
  category: 'sorting' | 'searching' | 'data-structures' | 'graphs' | 'trees';
  algorithmKey: string;
  playback: PlaybackControls;
  currentStep: Step;
  pseudocode: string[];
  implementations: Record<string, string>; // { javascript: string, python: string, cpp: string, java: string }
  complexity: {
    time: { best: string; average: string; worst: string; explanation?: string };
    space: { worst: string; explanation?: string };
  };
  description: string;
  useCases: string[];
  controlsPanel?: React.ReactNode;
  children: React.ReactNode; // Canvas element
}