# Lantern

> Zero-dependency TypeScript library for building animated, steppable code explainers that render to SVG, text, and JSON traces.

Lantern is an open-source project by Ivar Vong (ivarvong) for explaining code with animation you can step through. A scene is a sequence of named steps, and each step has a shareable link, an SVG frame, a plain-text frame, and a JSON trace of the state it explains. It is a zero-dependency JavaScript/TypeScript port of manim's core model that runs in the browser, Cloudflare Workers, or Node.

## What It Is

Lantern is an animation library and hosted player for code explainers. Authors write a scene as a class with an async `construct()` method, marking steps with `this.step(name)` and recording the explained state in `this.state`. Scenes can also be described as data with `sceneFromDoc`, using a JSON document of nodes, edges, code, and step operations. Diagrams can start as text: `flowchart(mermaidSource)` parses a Mermaid flowchart, lays it out, and returns shapes that can be animated.

## Outputs and Fetch API

Each scene is exposed through a plain GET HTTP API with open CORS and no auth. Endpoints return scene and step listings, per-step state traces, a frame as SVG, or a frame as text, addressed by scene name and either step name or time. A plain-text guide for agents is served at the root and at /llms.txt. In the player, deep links like `?scene=NAME&step=STEP` open a specific step, and keyboard shortcuts handle play/pause, stepping, and copying links.

## How the Engine Works

Shapes are Bézier point buffers, and text is rendered from embedded glyph outlines so output does not depend on installed fonts. Animations are pure functions of time with a fixed time step, so every frame is reproducible and seeking matches a full run. Frames go to sinks that produce live SVG in the DOM, SVG strings, text grids, or state traces. Traces are meant to be checked against the real program behavior.

## Scope Notes

The README lists matching morphs, 3D, boolean path operations, and LaTeX as out of scope for now, and says the library is not yet on npm. Setup is by cloning the repository and running npm scripts for dev server, tests, frame inspection, and deployment to Cloudflare Workers.

## Features
- Steppable animated scenes with named, linkable steps
- SVG, plain-text, and JSON trace output for every step
- Zero-dependency engine for browser, Cloudflare Workers, and Node
- Mermaid flowchart parsing and automatic layout
- Scenes authored as TypeScript classes or JSON documents
- HTTP API for frames, text, traces, and indexes
- Glyph-outline text with Write and morph animations
- Deterministic fixed-step rendering and exact seeking
- Motion verifier, contact-sheet and frame inspection tools
- Agent-readable text guide at /llms.txt

## Integrations
Cloudflare Workers, Node.js, Mermaid, Playwright

## Platforms
WEB, API, JETBRAINS_PLUGIN, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://lantern.ivar.workers.dev
- Documentation: https://lantern.ivar.workers.dev/llms.txt
- Repository: https://github.com/ivarvong/lantern
- EveryDev.ai: https://www.everydev.ai/tools/lantern