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.0

For 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.0

GVE 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.

See a headless replay with a saved trace.

Algorithms

Each definition includes a ready-to-use input under metadata.examples.

Sorting
bubbleSort, selectionSort, insertionSort, mergeSort, quickSort take finite number arrays.
Searching
linearSearch and binarySearch take an object with numeric values and a numeric target. Binary search requires ascending values and can return any matching duplicate.
Graphs
bfs and dfs take an object with vertices, directed edges, and a start vertex.
Trees
bstInsertion takes a finite number array and puts duplicates to the right.
Stacks
stackOperations takes an array of operations with op set to push or pop. Push operations also require a finite numeric value. An empty pop leaves the stack unchanged.
Recursion
fibonacci takes 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/core
defineAlgorithm, isJson, isEvent, reduceEvent, serializeTrace, parseTrace, validateTrace, describeEvent, GveError. Public types include Algorithm, Trace, VisualState, and RendererRegistration.
@gvejs/runtime
streamExecution, generateTrace, createPlayback, Playback, ExecutionLimits, PlaybackOptions, PlaybackSnapshot.
@gvejs/renderers
formatValue, layoutCells, layoutDiagram, Cell, PositionedNode, Diagram.
@gvejs/algorithms
Twelve built-in algorithm definitions.
@gvejs/themes
ThemeMode, Theme, and the @gvejs/themes/style.css export.
@gvejs/react
AlgorithmVisualizer, AlgorithmVisualizerProps, usePlayback, Visualization, PlaybackControls, Timeline, InputEditor, CodePanel, VariablesPanel, ExplanationPanel.

Extended v0.1.0 API reference

Troubleshooting

The visualization is unstyled
Import @gvejs/themes/style.css in 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.