Introduction
What typstream is, the problem it solves, and which package to start with.
typstream renders Typst while a language model is still writing it. Every token, it turns whatever has arrived into a document that compiles, compiles it with the real Typst compiler in a Web Worker, and updates only what changed on the page. It was built for AI tools that write educational documents: worksheets, quizzes, exams, lesson plans and handouts.
import { Typstream } from "typstream";
<Typstream source={text} isStreaming={status === "streaming"} animated caret />;That is the whole integration in a React app: source is the model's text so far, and isStreaming says whether more
is coming.
#show: quiz.with(title: [Fractions], subject: [Mathematics], grade: [Grade 5])
#question(points: 2)[$1/2 + 1/4 =$ #blank(answer: $3/4$)]
#question(points: 1)[
Which fraction is the largest?
#mcq([$1/2$], [$2/3$], [$3/5$], answer: 2)
]
#question(points: 3)[
Explain how you compare two fractions.
#answer-lines(count: 2, answer: [Rewrite them with a common denominator, then compare the numerators.])
]Press Replay as a stream to watch the document above arrive a few characters at a time, the way a model writes it. Every step renders.
Why Typst, and why it's hard to stream
Markdown degrades gracefully: half a table is still some text. Typst is a typesetting language with real layout,
math, tables, templates and scripting, which makes it a far better format for documents people print. But it is a
compiled language. One unclosed [ or a #table( cut mid-argument and the whole document fails to compile, so a
naive renderer shows nothing until the model is done.
typstream closes that gap in four layers:
- Healing (
@typstream/heal) runs on the main thread on every token. A faithful port of Typst's own parser finds what is still open at the end of the text, closes it or cuts it, and fixes Markdown habits such as**bold**in text that has settled. - Scheduling compiles the newest healed source as often as the engine keeps up, never a stale one, in a worker
with a watchdog, so a runaway
whileloop can't freeze the tab. - Fixers in the worker repair what parses but doesn't compile yet: a reference to a label that hasn't arrived, a package still loading, an argument cut mid-value.
- Fallback keeps something on screen whatever happens: the last good render, the settled text with the tail as plain text, or the one block that fails shown as an error box while the rest renders.
How it works walks through the whole pipeline.
What you get
- Two render targets from one document.
htmlgives semantic HTML and MathML that reflows, themes and animates;pagedgives print-faithful pages, painted on canvases, with a selectable text layer. See Render targets. - The real compiler. Typst 0.15.1 compiled to WebAssembly, the same build in the browser and on the server, so a document that validates on the server renders the same in the preview.
- Safe by default. Documents are untrusted code: no network, no files beyond what you pass, a sanitized DOM, and it runs under a strict Content-Security-Policy. See Security.
- A vocabulary for teachers.
@typstream/eduadds#question,#mcq,#blank, answer keys, rubrics and templates, with answers that only the teacher's copy shows. See Worksheets, quizzes and answer keys. - Exports. PDF, standalone HTML and the healed source, from the engine that renders the preview.
- Server tools. Validate before you save, render to PDF, and repair broken documents with your model in a loop
(
@typstream/node).
Packages
| Package | What it is |
|---|---|
typstream | The one most React apps install: <Typstream> with html-compat, the math font and the vendored Typst packages set up. |
@typstream/react | <Typstream>, TypstreamProvider and useTypstream(), without the defaults. |
@typstream/dom | Framework-free: mountTypstream, the HTML and paged renderers, standalone HTML export. |
@typstream/engine | The compile engine: main-thread client (healing, scheduling, watchdog) and the worker. |
@typstream/heal | Healing on its own: any prefix of streamed Typst in, a source that parses out. |
@typstream/node | Server-side validate, render, repair loop and a WebSocket engine server. |
@typstream/edu | Typst functions and templates for teachers' documents, and the prompt kit. |
@typstream/html-compat | Keeps grids, alignment, boxes and shapes in Typst's HTML export. |
@typstream/universe | The Typst packages allowed by default: CeTZ, fletcher, physica, chemformula and more. |
@typstream/engine-wasm | Typst 0.15.1 compiled to WebAssembly, the low-level compiler. |
@typstream/core | Shared contracts: text edits, diagnostics, the worker protocol, plugins and events. |
For AI agents
These docs are written to be read by coding agents too. Every page has a Markdown version: add .md to its URL
(/docs/concepts/healing.md), or request the page with Accept: text/markdown. /llms.txt indexes them
all, and /llms-full.txt is the whole documentation in one file. The Copy Markdown button at the
top of each page puts the same text on your clipboard.