# @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).

Source: https://typstream.vercel.app/docs/reference/ai

`@typstream/ai` connects typstream to the [Vercel AI SDK](https://ai-sdk.dev). 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](/docs/guides/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
npm install @typstream/ai typstream ai @ai-sdk/react
```

## With useChat

```tsx title="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](/docs/getting-started/nextjs-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](/docs/getting-started/vanilla) shows.

```ts
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`](#textof) | The document a message holds. |
| [`isStreaming`](#isstreaming) | Whether more of it is coming. |
| [`textStream`](#textstream) | A message's text as chunks, from its snapshots. |
| [`MessageLike`, `ChatLike`](#types) | What the functions read of AI SDK messages and chats. |
| [`createEditSession`](#createeditsession) | Applies an answer's edits to a document as they stream. |
| [`editPrompt`, `editRequest`, `selectionRequest`](#editprompt) | The edit format for the system prompt, and the user turns of an edit request. |
| [`editFeedback`](#editfeedback) | What to tell the model about the edits that failed. |
| [`parseEdits`](#parseedits) | Reads an answer's `<edit>`s as far as they have arrived. |
| [`findQuote`](#findquote) | Where a quote matches a document. |
| [`blockRange`, `blockStarts`](#blockrange) | The top-level blocks a range touches, and where blocks start. |

### textOf

```ts
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

```ts
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`.

<Callout type="warn" title="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.
</Callout>

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

```ts
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

### MessageLike

What typstream reads of an AI SDK `UIMessage`.

| Prop    | Type                         | Description                                                               |
| ------- | ---------------------------- | ------------------------------------------------------------------------- |
| `id`    | `string`                     | Unique in the chat: isStreaming compares it with the chat's last message. |
| `role`  | `string`                     | `"user"`, `"assistant"` or `"system"`.                                    |
| `parts` | `readonly MessagePartLike[]` | In the order they arrived.                                                |

### MessagePartLike

A part of an AI SDK `UIMessage`. Only text parts (`type: "text"`) are read;
reasoning, tool, file, source and data parts aren't the document.

| Prop     | Type                  | Description                                                   |
| -------- | --------------------- | ------------------------------------------------------------- |
| `type`   | `string`              | `"text"`, `"reasoning"`, `"tool-…"`, `"data-…"`, …            |
| `text?`  | `string \| undefined` | A text part's text so far.                                    |
| `state?` | `string \| undefined` | A text part's `"streaming"` or `"done"` (AI SDK 5 and later). |

### ChatLike

What typstream reads of a chat: `useChat()`'s result, or an AI SDK `Chat`.

| Prop       | Type                     | Description                                                           |
| ---------- | ------------------------ | --------------------------------------------------------------------- |
| `status`   | `string`                 | `"submitted"`, `"streaming"`, `"ready"` or `"error"`.                 |
| `messages` | `readonly MessageLike[]` | The conversation, oldest first; the answer being written is the last. |

AI SDK's `UIMessage` is a `MessageLike`, and `useChat()`'s result and `Chat` are `ChatLike`s, 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](/docs/guides/prompting).

## Edits

### createEditSession

```ts
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](/docs/guides/streaming-edits) walks
through it.

### EditSession

Applies one answer's edits to a document as the answer streams:
createEditSession.

| Prop        | Type                                                          | Description                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update`    | `(answer: string, done?: boolean) => void`                    | The model's answer so far, with its `<edit>` tags (an AI SDK message's textOf); `done` once it is complete. Call it as the answer grows.                                                                                     |
| `write`     | `(range: Range, replacement: string, done?: boolean) => void` | A selection edit: the model's replacement so far for `range`, which the app picked (the teacher's highlight), widened to whole blocks (blockRange). The replacement is plain Typst with no tags; `done` once it is complete. |
| `abort`     | `() => void`                                                  | The stream stopped (the teacher pressed stop, a network error): rolls back the edit being written.                                                                                                                           |
| `userEdit`  | `(edit: TextEdit) => void`                                    | An edit the teacher made to EditSessionState.text while the session is open.                                                                                                                                                 |
| `keep`      | `() => void`                                                  | Keeps the answer's edits: the session closes, the text stays.                                                                                                                                                                |
| `undo`      | `() => void`                                                  | Undoes the answer's edits: the document goes back to the snapshot. After edits of the teacher's, each of the answer's edits goes back to the text it replaced, and one the teacher has edited since stays as it is.          |
| `getState`  | `() => EditSessionState`                                      | The current state; the same object until it changes.                                                                                                                                                                         |
| `subscribe` | `(listener: (state: EditSessionState) => void) => () => void` | Calls `listener` after every change; returns the unsubscribe function.                                                                                                                                                       |

### EditSessionState

An edit session's state: EditSession.getState.

| Prop             | Type                                            | Description                                                                                                                                         |
| ---------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`           | `string`                                        | The document with the answer's edits so far: `<Typstream source>`.                                                                                  |
| `streamingRange` | `Range \| null`                                 | The block being written, if one is: `<Typstream streamingRange>`.                                                                                   |
| `streaming`      | `boolean`                                       | Whether the block in `streamingRange` is still being written: `<Typstream isStreaming>`.                                                            |
| `message`        | `string`                                        | The answer's text outside its edits, for the teacher.                                                                                               |
| `edits`          | `readonly EditResult[]`                         | One result per edit of the answer, in its order.                                                                                                    |
| `phase`          | `"kept" \| "review" \| "streaming" \| "undone"` | `streaming` while the answer arrives; `review` once it has ended (show Keep / Undo); `kept` or `undone` after EditSession.keep or EditSession.undo. |

### EditResult

One edit of an answer, as the session applied it.

| Prop     | Type                     | Description                                                                                                                                                                                       |
| -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `EditStatus`             | `quoting`, `writing`, `applied`, `failed` or `undone`.                                                                                                                                            |
| `error?` | `EditError \| undefined` | Why it failed, with `status: "failed"`.                                                                                                                                                           |
| `quote`  | `string`                 | The quote, as the model wrote it.                                                                                                                                                                 |
| `range`  | `Range \| null`          | Where it is in the session's current text: while quoting, the text the quote matches so far (when it matches one place); while writing and once applied, the new text. `null` when there is none. |
| `loose`  | `boolean`                | Whether the quote matched only with whitespace evened out.                                                                                                                                        |

`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

```ts
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

```ts
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

```ts
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.

### EditOp

One `<edit>` of a model's answer, as far as it has arrived.

| Prop         | Type                   | Description                                                                 |
| ------------ | ---------------------- | --------------------------------------------------------------------------- |
| `quote`      | `string`               | The quoted text the edit replaces (`<old>`), so far.                        |
| `quoteDone`  | `boolean`              | Whether the quote is complete (`</old>` arrived).                           |
| `text`       | `string`               | The text that replaces it (`<new>`), so far.                                |
| `done`       | `boolean`              | Whether the new text is complete (`</new>` arrived).                        |
| `malformed?` | `boolean \| undefined` | Set when the edit isn't written as `<edit><old>…</old><new>…</new></edit>`. |

### ParsedAnswer

A model's answer read as edits: parseEdits's result.

| Prop      | Type       | Description                                                                |
| --------- | ---------- | -------------------------------------------------------------------------- |
| `edits`   | `EditOp[]` | The edits, in the order the model wrote them.                              |
| `message` | `string`   | The text outside the tags, for the teacher: trimmed, blank runs collapsed. |

### findQuote

```ts
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.

### QuoteMatch

Where a quote matches a text: findQuote's result.

| Prop     | Type      | Description                                                                               |
| -------- | --------- | ----------------------------------------------------------------------------------------- |
| `ranges` | `Range[]` | The matched ranges, at most two (two say the quote is ambiguous).                         |
| `exact`  | `boolean` | Whether they match exactly; `false` when only whitespace-insensitive matching found them. |

### blockRange

```ts
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.
