@typstream/ai
typstream with the Vercel AI SDK. An assistant message is a Typst document (textOf, isStreaming, textStream), and an answer that edits one applies its edits as they stream (createEditSession, editPrompt).
@typstream/ai connects typstream to the Vercel AI SDK. When the model answers in Typst, an
assistant message is a document. The package reads two things from the message: its text, and whether more of that
text is coming. They are what <Typstream> (or mountTypstream) takes as source and isStreaming.
When the model changes a document that exists, its answer is a set of edits that quote what they replace. The package's edit session applies them to the document as they stream, then the teacher keeps or undoes them: see Streaming edits.
It reads AI SDK messages by their shape and imports nothing from ai, so it adds no dependency and works with AI SDK 5
and later. It's tested against AI SDK 7. The edit session needs @typstream/heal (for the document's blocks), which
every app that renders has already.
When to use it
Use it when your app streams Typst through the AI SDK: useChat in React, or the SDK's transport and stream reader
without React. On the server, streamText()'s textStream is already a stream of chunks, so you don't need it there.
Install
npm install @typstream/ai typstream ai @ai-sdk/reactWith useChat
"use client";
import { useChat } from "@ai-sdk/react";
import { isStreaming, textOf } from "@typstream/ai";
import { Typstream } from "typstream";
export default function Chat() {
const chat = useChat();
return chat.messages.map((message) =>
message.role === "user" ? (
<p key={message.id}>{textOf(message)}</p>
) : (
<Typstream key={message.id} source={textOf(message)} isStreaming={isStreaming(message, chat)} animated caret />
),
);
}One <Typstream> per assistant message, keyed by the message's id. Next.js and the AI
SDK builds the whole app around it.
Without React
DefaultChatTransport posts the conversation to your route and returns its UI message stream. readUIMessageStream
turns that stream into snapshots of the answer, and textStream turns the snapshots into chunks for mountTypstream's
stream. The document finishes (final mode) when the stream ends. Add the plugins and the math font as Without a
framework shows.
import { mountTypstream } from "@typstream/dom";
import { createEngine, engineWorker } from "@typstream/engine";
import { textStream } from "@typstream/ai";
import { DefaultChatTransport, readUIMessageStream } from "ai";
const engine = createEngine({ spawn: engineWorker() });
const transport = new DefaultChatTransport({ api: "/api/chat" });
const chunks = await transport.sendMessages({
chatId: "worksheet",
messages: [{ id: "1", role: "user", parts: [{ type: "text", text: "A worksheet on fractions" }] }],
trigger: "submit-message",
messageId: undefined,
abortSignal: undefined,
});
mountTypstream(document.querySelector("#answer")!, {
engine,
target: "paged",
stream: textStream(readUIMessageStream({ stream: chunks })),
});API
| Export | What it is |
|---|---|
textOf | The document a message holds. |
isStreaming | Whether more of it is coming. |
textStream | A message's text as chunks, from its snapshots. |
MessageLike, ChatLike | What the functions read of AI SDK messages and chats. |
createEditSession | Applies an answer's edits to a document as they stream. |
editPrompt, editRequest, selectionRequest | The edit format for the system prompt, and the user turns of an edit request. |
editFeedback | What to tell the model about the edits that failed. |
parseEdits | Reads an answer's <edit>s as far as they have arrived. |
findQuote | Where a quote matches a document. |
blockRange, blockStarts | The top-level blocks a range touches, and where blocks start. |
textOf
function textOf(message: MessageLike): string;The message's text parts, joined in order. Reasoning, tool, file, source and data parts aren't part of the document.
Before the first text arrives it's "".
isStreaming
function isStreaming(message: MessageLike, chat: ChatLike): boolean;True while the chat is answering with this message (status is submitted or streaming, and it's the last message)
and the message doesn't end with a text part that has ended: before any text (the model is thinking), while a text
part streams, and after a tool call (a later step may write more). False for user messages and for every earlier
answer. Pass useChat()'s result, or an AI SDK Chat.
The answer finishes as soon as its last text ends, a moment before the chat's status is ready.
Why not the part's own state
A text part's state turns "done" only when the model ends it. When an answer stops early (the user presses stop,
the network fails), the AI SDK leaves it "streaming" and only the chat's status changes. Read from the part
alone, the document would never finish. Read from status === "streaming" alone, every earlier answer would stream
again, and start over, whenever a new one streams.
Text that ends before a tool call doesn't finish the answer: the tool's part comes after it, so the answer streams on
until text ends with nothing after it. If your document is only the text after a tool call (an image search, say),
pass textOf the parts after it: textOf({ ...message, parts: message.parts.slice(i + 1) }).
textStream
function textStream(messages: AsyncIterable<MessageLike>): AsyncGenerator<string>;Yields what each snapshot of a message adds to its text: the chunks stream reads. The snapshots are of one message
as it streams, as readUIMessageStream yields them. A snapshot whose text doesn't extend the previous one throws,
which ends the document's stream.
Types
Prop
Type
Prop
Type
Prop
Type
AI SDK's UIMessage is a MessageLike, and useChat()'s result and Chat are ChatLikes, so you never build them
yourself. AI SDK 4's messages (content, toolInvocations) aren't supported.
The system prompt
The model needs to be told to answer in Typst. buildSystemPrompt from @typstream/edu writes that prompt for
teachers' documents; see Prompting.
Edits
createEditSession
function createEditSession(text: string): EditSession;A session that applies one answer's edits to text, the document the model was given. Open one per answer. Feed it
with update(answer, done) (the answer's text, textOf(message), and whether it has ended), or for a selection edit
write(range, replacement, done). Show getState()'s text, streamingRange and streaming in <Typstream>, and
when phase is review, offer keep() and undo(). userEdit(edit) takes the teacher's own edits while the session
is open, and abort() rolls back the edit being written. Streaming edits walks
through it.
Prop
Type
Prop
Type
Prop
Type
EditStatus is quoting, writing, applied, failed or undone. EditError says why an edit failed:
not-found (its quote matches no place), ambiguous (several), overlap (it touches what an earlier edit of the
answer changed), conflict (the teacher edited that text meanwhile), malformed or incomplete (the answer ended
first).
editPrompt
function editPrompt(): string;
const editPromptRules: readonly string[];
function editRequest(document: string, request: string): string;
function selectionRequest(document: string, range: Range, instruction: string): string;editPrompt() is the edit format and its rules (editPromptRules), with an example, for the end of a system prompt
that already teaches the document's Typst, such as buildSystemPrompt(plugins). editRequest is the user turn: the
document as it is now, then the request. selectionRequest is a selection edit's user turn: the document with the part
to rewrite marked, and the instruction; the model answers with that part's new text only. All @beta: the rules
change only with a new measured run.
editFeedback
function editFeedback(edits: readonly EditResult[]): string | null;What to tell the model about the edits that failed, and why, to send as the next request so it writes them again.
null when every edit applied. @beta.
parseEdits
function parseEdits(answer: string, final?: boolean): ParsedAnswer;Reads an answer as <edit>s and a message, as far as it has arrived: call it again with more, and the edits only
grow. A tag cut at the end (</ne) is held back until final. Lenient where models drift: a code fence around a quote
or new text, a missing </edit>. The session calls it; you need it only to read answers yourself.
Prop
Type
Prop
Type
findQuote
function findQuote(text: string, quote: string): QuoteMatch;Where quote occurs in text: exactly, or else with every whitespace run matching any other. The quote's own leading
and trailing whitespace is ignored. At most two ranges come back: one is a match, two an ambiguous quote.
Prop
Type
blockRange
function blockRange(text: string, range: Range): Range;
function blockStarts(text: string): number[];blockRange widens a range to the top-level blocks it touches, from the first one's start to the end of the last one's
text, without the blank line after it: what a selection edit rewrites. blockStarts (from @typstream/heal, @beta)
is where each top-level block starts.
@typstream/react
React bindings for typstream, with the Typstream component, TypstreamProvider for app-wide settings and the useTypstream() hook.
@typstream/dom
Framework-free renderers for typstream's output (HTML and SVG pages), mountTypstream to show an engine document in an element, and standalone HTML exports.