Documentation
Build with the GVE v0.1.0 public API.
Introduction
GVE is an MIT-licensed TypeScript engine for interactive algorithm and computer science visualizations. Generate a trace for a specific input, play it in React, or use its visual state in your own UI.
Open the playground to try built-in algorithms and inspect the effects of each event.
Installation
For an existing React 18 or 19 application, install the React visualizer, its stylesheet, and the built-in algorithms.
npm install @gvejs/algorithms@0.1.0 @gvejs/react@0.1.0 @gvejs/themes@0.1.0For a headless TypeScript project, install the packages used by the trace and rendering example.
npm install @gvejs/algorithms@0.1.0 @gvejs/core@0.1.0 @gvejs/runtime@0.1.0 @gvejs/renderers@0.1.0GVE packages ship as ESM with TypeScript declarations. Use an ESM-aware bundler or an ESM Node.js project with NodeNext module resolution.
Quick Start
Add this component to your React project and render the exported SortingLesson component in your app. The supplied input is stable across renders.
import { bubbleSort } from "@gvejs/algorithms";
import { AlgorithmVisualizer } from "@gvejs/react";
import type { Theme } from "@gvejs/themes";
import "@gvejs/themes/style.css";
const exampleInput = [8, 3, 5, 1, 9];
const systemTheme: Theme = { mode: "auto", colors: {} };
export function SortingLesson({
theme = systemTheme,
input = exampleInput,
}: {
theme?: Theme;
input?: number[];
}) {
return (
<AlgorithmVisualizer
algorithm={bubbleSort}
input={input}
theme={theme}
showControls
showCode
showVariables
showInput
/>
);
}Core Concepts
An Algorithm combines metadata, an input type guard, an initial visual state, and an execution generator. Define one with defineAlgorithm. The generator yields events and returns the result. Pseudocode references in events are one-based.
Visual state describes the current cells, nodes, edges, highlights, pointers, and variables. Reducers apply events to that state. Custom events require a namespaced type and a JSON payload guard. Keep custom reducers deterministic and copy any collection they change.
Visualization Traces
generateTrace validates input and events and returns a version 1 trace with version, algorithm, input, events, and result. streamExecution yields validated events one at a time and returns the result when exhausted.
Use serializeTrace to store a recording and parseTrace with the same algorithm and a result guard to load it. Use validateTrace for already parsed data. describeEvent exposes the event and its trace-local identity.
Built-in events cover comparisons, swaps, writes, value replacement, highlights, pointers, nodes, edges, variables, calls, and returns. Events can carry an explanation, a pseudocode line, and JSON metadata.
Playback Runtime
createPlayback takes the algorithm and its trace. Position zero is the initial state. Position N reflects N applied events. Read changes with getSnapshot and subscribe. Treat snapshot data as read-only.
Use stepForward, stepBackward, or seek for manual navigation. resume continues at the current position, pause stops the timer, and reset goes to the start. setSpeed takes a positive finite multiplier. Unsubscribe and call dispose when replacing a session.
Algorithms
Each definition includes a ready-to-use input under metadata.examples.
- Sorting
bubbleSort,selectionSort,insertionSort,mergeSort,quickSorttake finite number arrays.- Searching
linearSearchandbinarySearchtake an object with numericvaluesand a numerictarget. Binary search requires ascending values and can return any matching duplicate.- Graphs
bfsanddfstake an object withvertices, directededges, and astartvertex.- Trees
bstInsertiontakes a finite number array and puts duplicates to the right.- Stacks
stackOperationstakes an array of operations withopset topushorpop. Push operations also require a finite numericvalue. An empty pop leaves the stack unchanged.- Recursion
fibonaccitakes an integer from 0 through 12.
Renderers
layoutCells returns rows of cells for array, stack, queue, and matrix views. layoutDiagram returns positioned nodes and edges for diagram views. formatValue converts JSON values into display labels.
To plug your own view into React, supply RendererRegistration entries through the renderers prop. Each registration identifies a visual state kind and renders a compatible state.
Themes
Import @gvejs/themes/style.css once in your app. Pass light, dark, or auto as the visualizer theme. A Theme object with mode and a colors object lets you override the default palette. Auto follows the system color preference. The stylesheet respects reduced motion.
React Integration
AlgorithmVisualizer combines visualization, playback, and inspection. Use showInput, showCode, and showVariables to enable the relevant panels. Keep the algorithm, initial input, and playback options stable across renders.
Use usePlayback to subscribe to a playback instance in a custom React view. Compose Visualization, PlaybackControls, and Timeline with the individual inspector panels as needed.
Focus the canvas to step with Left or Right and toggle playback with Space. Shift with Left or Right scrolls wide diagrams.
API Reference
@gvejs/coredefineAlgorithm,isJson,isEvent,reduceEvent,serializeTrace,parseTrace,validateTrace,describeEvent,GveError. Public types includeAlgorithm,Trace,VisualState, andRendererRegistration.@gvejs/runtimestreamExecution,generateTrace,createPlayback,Playback,ExecutionLimits,PlaybackOptions,PlaybackSnapshot.@gvejs/renderersformatValue,layoutCells,layoutDiagram,Cell,PositionedNode,Diagram.@gvejs/algorithms- Twelve built-in algorithm definitions.
@gvejs/themesThemeMode,Theme, and the@gvejs/themes/style.cssexport.@gvejs/reactAlgorithmVisualizer,AlgorithmVisualizerProps,usePlayback,Visualization,PlaybackControls,Timeline,InputEditor,CodePanel,VariablesPanel,ExplanationPanel.
Troubleshooting
- The visualization is unstyled
- Import
@gvejs/themes/style.cssin your app entry. - Playback resets on a React render
- Move literal input and options outside the component or memoize values derived from props.
- The editor rejects JSON
- Start with a built-in example and preserve its input shape. For binary search, sort the numeric array first.
- A run reaches an execution limit
- Reduce the input size. Trace generation in the React visualizer runs synchronously, and limits are checked between generator calls.
- A stored trace fails validation
- Check the trace version, algorithm ID, custom event schemas, and result guard.