typstream

@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/react

With useChat

app/page.tsx
"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

ExportWhat it is
textOfThe document a message holds.
isStreamingWhether more of it is coming.
textStreamA message's text as chunks, from its snapshots.
MessageLike, ChatLikeWhat the functions read of AI SDK messages and chats.
createEditSessionApplies an answer's edits to a document as they stream.
editPrompt, editRequest, selectionRequestThe edit format for the system prompt, and the user turns of an edit request.
editFeedbackWhat to tell the model about the edits that failed.
parseEditsReads an answer's <edit>s as far as they have arrived.
findQuoteWhere a quote matches a document.
blockRange, blockStartsThe 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.

On this page