# @typstream/node

> Typst on the server, to validate and render documents, run the LLM fix loop, and serve the engine protocol over WebSocket.

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

`@typstream/node` runs Typst 0.15.1 on Node's worker threads, for apps that save documents a model wrote. It runs
`@typstream/engine-wasm`, the same build browsers run, so a document that validates on the server renders the same in
the preview. A watchdog stops runaway documents without taking the process down.

## When to use it

Use it on the server, where `@typstream/engine` (a Web Worker) doesn't run:

- **validate** a document before you save it, with lint warnings for Markdown habits;
- **render** it to PDF, HTML or SVG pages;
- turn its diagnostics into a **repair prompt** and run the **fix loop** with your model;
- **serve the engine protocol** over WebSocket to browsers that shouldn't download the 6 MB engine.

For live rendering in the browser, use [`typstream`](/docs/reference/typstream) or
[`@typstream/react`](/docs/reference/react) instead. Node 20 or later is required.

## Install

```npm
npm install @typstream/node
```

## Example

```ts
import { fixLoop, formatDiagnosticsForLLM, render, validate } from "@typstream/node";

const { ok, diagnostics } = await validate(source);
if (!ok) console.log(formatDiagnosticsForLLM(source, diagnostics));

const result = await fixLoop({
  source,
  generate: async ({ prompt, source }) => callYourModel(`${prompt}\n\n${source}`),
});
if (result.ok) {
  const pdf = await render(result.source, "pdf");
  if (pdf.ok) save(pdf.data);
}
```

[Server fix loop](/docs/guides/server-fix-loop) walks through this with a real model.

## Document options

Every compile (`validate`, `render`, `fixLoop`) takes these options. Positions in diagnostics are UTF-16 offsets into
`source`, as everywhere in typstream; a diagnostic inside the preamble carries `file: { path: "<preamble>" }`.

### DocumentOptions

Options every compile takes.

| Prop         | Type                                       | Description                                                                                                       |
| ------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `preamble?`  | `string \| undefined`                      | Typst evaluated before the document (theme, imports). Diagnostics inside it carry `file: { path: "<preamble>" }`. |
| `files?`     | `Record<string, FileContent> \| undefined` | Files the document reads (images, data, other `.typ` files), by path relative to the document.                    |
| `inputs?`    | `Record<string, string> \| undefined`      | `sys.inputs`.                                                                                                     |
| `engine?`    | `NodeEngine \| undefined`                  | Default: defaultEngine.                                                                                           |
| `timeoutMs?` | `number \| undefined`                      | Watchdog budget for this compile; default the engine's `timeoutMs`.                                               |

Documents can't read the server's filesystem or reach the network: they see only the `files` you pass. A file path is
relative to the document (`img/a.png`); paths that escape it (`..`) are rejected. To compile documents written in a
plugin's vocabulary, pass its preamble and files, for example `@typstream/edu`'s:

```ts
import { eduFiles, eduPreamble } from "@typstream/edu";
import { validate } from "@typstream/node";

const result = await validate(source, {
  preamble: eduPreamble,
  files: eduFiles,
  inputs: { showAnswers: "true" }, // the teacher's copy
});
```

Typst Universe packages are not fetched. A document can import one only if you mount its files yourself, under its spec
(`@preview/cetz:0.5.3/lib.typ` and so on).

## API

| Export | What it does |
| --- | --- |
| [`validate(source, options?)`](#validate) | Compiles without exporting and adds lint warnings: `{ ok, diagnostics, pageCount?, ms }`. |
| [`render(source, format, options?)`](#render) | Compiles and exports `"pdf"`, `"html"` or `"svg"`. |
| [`formatDiagnosticsForLLM(source, diagnostics, options?)`](#formatdiagnosticsforllm) | A compact repair prompt in the Typst CLI's layout. |
| [`fixLoop(options)`](#fixloop) | Validate, ask the model for a fix, repeat, and keep the best attempt. |
| [`createEngine(options?)`](#createengine) | A worker pool with its own fonts and budgets. |
| [`defaultEngine()`](#defaultengine) | The shared engine used when you pass none. |
| [`createProtocolServer(options?)`](#createprotocolserver) | The engine protocol, served from Node. |
| [`handleWebSocket(socket, server)`](#handlewebsocket) | Serves one WebSocket connection with a protocol server. |

### validate

```ts
const validate: (source: string, options?: ValidateOptions) => Promise<ValidateResult>;
```

Checks a finished document before it is saved: compiles it without exporting and adds `@typstream/heal`'s lint findings
as warnings (source `"heal"`, the rule id as `code`, with a hint saying what to replace). Those catch Markdown habits
that compile but render wrongly, such as `**bold**` or `$5 and $10`. It never throws for a broken document. `ok` is true
when there are no errors; warnings don't count.

```ts
const { ok, diagnostics, pageCount } = await validate(source, { target: "html" });
```

### ValidateOptions

Options for validate: the document's, plus what to check it for.

| Prop         | Type                                                                           | Description                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `target?`    | `CompileTarget \| undefined`                                                   | Which output to compile for. Default `paged`, what gets printed; `html` also catches problems specific to HTML export.                                                                                             |
| `lint?`      | `boolean \| Partial<Record<LintRuleId, boolean \| LintSeverity>> \| undefined` | Report `@typstream/heal`'s lint findings as warnings (default true). They catch Markdown habits that compile but render wrongly (`**bold**`, `$5 and $10`). Pass heal's `lint` settings to configure single rules. |
| `preamble?`  | `string \| undefined`                                                          | Typst evaluated before the document (theme, imports). Diagnostics inside it carry `file: { path: "<preamble>" }`.                                                                                                  |
| `files?`     | `Record<string, FileContent> \| undefined`                                     | Files the document reads (images, data, other `.typ` files), by path relative to the document.                                                                                                                     |
| `inputs?`    | `Record<string, string> \| undefined`                                          | `sys.inputs`.                                                                                                                                                                                                      |
| `engine?`    | `NodeEngine \| undefined`                                                      | Default: defaultEngine.                                                                                                                                                                                            |
| `timeoutMs?` | `number \| undefined`                                                          | Watchdog budget for this compile; default the engine's `timeoutMs`.                                                                                                                                                |

### ValidateResult

What validate found.

| Prop          | Type                  | Description                                                            |
| ------------- | --------------------- | ---------------------------------------------------------------------- |
| `ok`          | `boolean`             | No errors. Warnings (including lint findings) don't count.             |
| `diagnostics` | `Diagnostic[]`        | Sorted and deduplicated; positions are UTF-16 offsets into the source. |
| `pageCount?`  | `number \| undefined` | Pages of the paged document, when it compiled.                         |
| `ms`          | `number`              | Wall-clock milliseconds.                                               |

### render

```ts
const render: <F extends RenderFormat>(source: string, format: F, options?: DocumentOptions) => Promise<RenderResult<F>>;
type RenderFormat = "pdf" | "html" | "svg";
```

Compiles and exports a document. `data` is PDF bytes (`Uint8Array`) for `"pdf"`, an HTML document (`string`) for
`"html"`, and one SVG string per page (`string[]`) for `"svg"`. Diagnostics are Typst's only (no lint). `ok: false`
means it didn't compile and there is no `data`.

```ts
const pdf = await render(source, "pdf", { preamble: eduPreamble, files: eduFiles });
if (pdf.ok) await writeFile("worksheet.pdf", pdf.data);
else console.error(pdf.diagnostics);
```

```ts
type RenderResult<F extends RenderFormat = RenderFormat> =
  | { ok: true; diagnostics: Diagnostic[]; data: RenderData[F]; pageCount?: number; ms: number }
  | { ok: false; diagnostics: Diagnostic[]; ms: number };

interface RenderData {
  pdf: Uint8Array;
  html: string;
  svg: string[];
}
```

### formatDiagnosticsForLLM

```ts
const formatDiagnosticsForLLM: (source: string, diagnostics: readonly Diagnostic[], options?: FormatOptions) => string;
```

Formats diagnostics as a compact repair prompt: a summary line, then each problem the way the Typst CLI prints it
(message, location, the source line with the span underlined, notes and hints), then instructions. Errors come first,
repeats are dropped, output is capped by `maxDiagnostics` and long lines are clipped, so the prompt stays small for
large documents. With no diagnostics it returns `"The Typst document compiles without problems."`.

```ts
const { diagnostics } = await validate("= Results\n*Total*: #hilight[12]\n");
formatDiagnosticsForLLM(source, diagnostics);
```

```text
The Typst document has 1 error.

error: unknown variable: hilight
 --> line 2, column 11
  |
1 | = Results
2 | *Total*: #hilight[12]
  |           ^^^^^^^
3 |

Fix every error, and the warnings where they point at a real mistake. Reply with the complete corrected Typst document only.
```

### FormatOptions

How formatDiagnosticsForLLM writes its prompt.

| Prop               | Type                   | Description                                                                                  |
| ------------------ | ---------------------- | -------------------------------------------------------------------------------------------- |
| `maxDiagnostics?`  | `number \| undefined`  | Most diagnostics to include, errors first. Default 10.                                       |
| `contextLines?`    | `number \| undefined`  | Source lines shown before and after each problem line. Default 1.                            |
| `includeWarnings?` | `boolean \| undefined` | Include warnings (and lint findings). Default true.                                          |
| `instructions?`    | `string \| undefined`  | Text after the diagnostics. Default asks for the complete corrected document; `""` for none. |

### fixLoop

```ts
const fixLoop: (options: FixLoopOptions) => Promise<FixLoopResult>;
```

Validates `source`; while it has errors, asks `generate` for a corrected document and validates that, for at most
`maxRounds` rounds. It returns the best attempt (fewest errors, then fewest warnings, then the latest), so a reply that
makes things worse never replaces a better one. A Markdown code fence around the model's reply is removed. With
`strict`, documents that only have warnings are repaired too.

`FixLoopOptions` extends [`ValidateOptions`](#validate), so `preamble`, `files`, `inputs`, `target`, `lint` and `engine`
apply to every round.

```ts
const result = await fixLoop({
  source,
  strict: true, // also repair lint warnings such as **bold**
  maxRounds: 2,
  generate: async ({ prompt, source, round }) => {
    const reply = await callYourModel(`${prompt}\n\n${source}`);
    return reply.text;
  },
});
console.log(result.ok, result.attempts.length - 1, "rounds");
```

### FixLoopOptions

What fixLoop repairs and how. The ValidateOptions apply to
every round's validation.

| Prop         | Type                                                                           | Description                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source`     | `string`                                                                       | The document to validate and, if it has errors, repair.                                                                                                                                                            |
| `generate`   | `(request: FixRequest) => string \| Promise<string>`                           | Asks the model for a corrected document. A Markdown code fence (`typst` or `typ`) around the reply is removed.                                                                                                     |
| `maxRounds?` | `number \| undefined`                                                          | Most repair rounds (calls to `generate`). Default 3.                                                                                                                                                               |
| `strict?`    | `boolean \| undefined`                                                         | Also repair documents that only have warnings, until none are left. Default false: errors only.                                                                                                                    |
| `format?`    | `FormatOptions \| undefined`                                                   | How each round's `prompt` is written; passed to formatDiagnosticsForLLM.                                                                                                                                           |
| `preamble?`  | `string \| undefined`                                                          | Typst evaluated before the document (theme, imports). Diagnostics inside it carry `file: { path: "<preamble>" }`.                                                                                                  |
| `files?`     | `Record<string, FileContent> \| undefined`                                     | Files the document reads (images, data, other `.typ` files), by path relative to the document.                                                                                                                     |
| `inputs?`    | `Record<string, string> \| undefined`                                          | `sys.inputs`.                                                                                                                                                                                                      |
| `engine?`    | `NodeEngine \| undefined`                                                      | Default: defaultEngine.                                                                                                                                                                                            |
| `timeoutMs?` | `number \| undefined`                                                          | Watchdog budget for this compile; default the engine's `timeoutMs`.                                                                                                                                                |
| `target?`    | `CompileTarget \| undefined`                                                   | Which output to compile for. Default `paged`, what gets printed; `html` also catches problems specific to HTML export.                                                                                             |
| `lint?`      | `boolean \| Partial<Record<LintRuleId, boolean \| LintSeverity>> \| undefined` | Report `@typstream/heal`'s lint findings as warnings (default true). They catch Markdown habits that compile but render wrongly (`**bold**`, `$5 and $10`). Pass heal's `lint` settings to configure single rules. |

### FixRequest

What fixLoop asks the model to repair.

| Prop          | Type           | Description                                                                        |
| ------------- | -------------- | ---------------------------------------------------------------------------------- |
| `source`      | `string`       | The document as it stands.                                                         |
| `diagnostics` | `Diagnostic[]` | Its diagnostics from validate: Typst's and lint findings, sorted and deduplicated. |
| `prompt`      | `string`       | formatDiagnosticsForLLM of the two above.                                          |
| `round`       | `number`       | 1 for the first repair.                                                            |

### FixLoopResult

What fixLoop ends with: the best attempt, and every attempt it made.

| Prop          | Type           | Description                                                                    |
| ------------- | -------------- | ------------------------------------------------------------------------------ |
| `ok`          | `boolean`      | The best attempt is acceptable (no errors; with `strict`, no warnings either). |
| `source`      | `string`       | The best attempt: fewest errors, then fewest warnings, then the latest.        |
| `diagnostics` | `Diagnostic[]` | The best attempt's diagnostics, lint findings included.                        |
| `attempts`    | `FixAttempt[]` | Every attempt, starting with the original source.                              |

### FixAttempt

One validated version of the document.

| Prop          | Type           | Description                                                                              |
| ------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `source`      | `string`       | The text validated: the original source, or a model's reply with its code fence removed. |
| `diagnostics` | `Diagnostic[]` | What validate reported for `source`, lint findings included.                             |
| `ok`          | `boolean`      | No errors; with `strict`, no warnings either. The loop stops at the first such attempt.  |

### createEngine

```ts
const createEngine: (options?: EngineOptions) => NodeEngine;
```

Creates an engine: a pool of worker threads, each running engine-wasm and compiling one document at a time. Create one
per process and share it; pass it as `engine` to the calls above. Nothing starts until the first compile. Then the wasm
module is compiled once, fonts are loaded, and workers start as needed. Workers keep Typst's caches warm between calls,
and idle workers don't keep the process alive.

```ts
import { createEngine, validate } from "@typstream/node";

const engine = createEngine({
  workers: 4, // most worker threads; default min(4, cores - 1)
  timeoutMs: 10_000, // watchdog per compile
  fontPaths: ["/srv/fonts/noto"], // more fonts, searched recursively (like typst --font-path)
});
await validate(source, { engine });
await engine.close();
```

### EngineOptions

How createEngine sizes its worker pool, budgets compiles, and which fonts it loads.

| Prop              | Type                                         | Description                                                                                                                                                                                                             |
| ----------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workers?`        | `number \| undefined`                        | Most worker threads to run at once, each compiling one document at a time. Default `min(4, cores - 1)`, at least 1.                                                                                                     |
| `timeoutMs?`      | `number \| undefined`                        | Default watchdog budget per compile, in milliseconds. A compile that takes longer is stopped by terminating its worker and reported as an error diagnostic with code `timeout`. Default 10,000 (PLAN §6.3, final mode). |
| `maxMemoryBytes?` | `number \| undefined`                        | Replace a worker once its wasm memory exceeds this many bytes (it never shrinks). Default 1 GiB.                                                                                                                        |
| `typstFonts?`     | `boolean \| undefined`                       | Load Typst's bundled fonts (Libertinus Serif, New Computer Modern, DejaVu Sans Mono). Default true.                                                                                                                     |
| `scriptFonts?`    | `boolean \| undefined`                       | Load engine-wasm's script fonts: Noto Naskh Arabic, Noto Serif Bengali and Noto Serif Devanagari, regular and bold. Default true.                                                                                       |
| `fonts?`          | `Uint8Array<ArrayBufferLike>[] \| undefined` | Font files (TTF, OTF, TTC) as bytes.                                                                                                                                                                                    |
| `fontPaths?`      | `string[] \| undefined`                      | Directories searched recursively for font files, like `typst --font-path`.                                                                                                                                              |

### NodeEngine

Compiles Typst on worker threads. Create one per process and share it;
validate, render and createProtocolServer use a
default one when none is given. Idle workers don't keep the process alive.

| Prop      | Type                  | Description                                                                     |
| --------- | --------------------- | ------------------------------------------------------------------------------- |
| `workers` | `number`              | Workers currently running. They start on demand.                                |
| `close`   | `() => Promise<void>` | Stops every worker. Pending compiles fail; the engine can't be used afterwards. |

**Timeouts and crashes.** A compile over budget is stopped by terminating its worker, and the result is an error
diagnostic with `source: "typstream"` and `code: "timeout"`. A document that exhausts wasm memory (allocations fail at
about 2 GiB in wasm32) comes back as `code: "engine-crashed"`. Either way the worker is replaced and the process is
unaffected. That's why typstream runs Typst as wasm rather than as a native addon, whose compiles can't be interrupted.
A worker whose memory grows past `maxMemoryBytes` is replaced too, since wasm memory never shrinks.

```ts
const { diagnostics } = await validate(source, { timeoutMs: 2_000 });
if (diagnostics.some((d) => d.code === "timeout")) {
  // a loop that never ends, or a document far larger than usual
}
```

**Fonts.** By default the engine loads Typst's bundled fonts (Libertinus Serif, New Computer Modern and DejaVu Sans
Mono, the set `typst compile --ignore-system-fonts` uses) and engine-wasm's script fonts (Noto Naskh Arabic, Noto Serif
Bengali and Noto Serif Devanagari, regular and bold). Unlike the browser, which downloads script fonts when a document
first needs them, the server loads them up front. Add your own with `fonts` (bytes) or `fontPaths` (directories). See
[Fonts and languages](/docs/guides/fonts-and-languages).

### FontOptions

Which fonts the server engine loads, once, on its first compile: Typst's
bundled set and engine-wasm's script fonts by default, plus any you add.
Documents see only these; system fonts aren't searched.

| Prop           | Type                                         | Description                                                                                                                       |
| -------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `typstFonts?`  | `boolean \| undefined`                       | Load Typst's bundled fonts (Libertinus Serif, New Computer Modern, DejaVu Sans Mono). Default true.                               |
| `scriptFonts?` | `boolean \| undefined`                       | Load engine-wasm's script fonts: Noto Naskh Arabic, Noto Serif Bengali and Noto Serif Devanagari, regular and bold. Default true. |
| `fonts?`       | `Uint8Array<ArrayBufferLike>[] \| undefined` | Font files (TTF, OTF, TTC) as bytes.                                                                                              |
| `fontPaths?`   | `string[] \| undefined`                      | Directories searched recursively for font files, like `typst --font-path`.                                                        |

### defaultEngine

```ts
const defaultEngine: () => NodeEngine;
```

The engine `validate`, `render`, `fixLoop` and `createProtocolServer` use when you don't pass one. It is created on
first use with default options.

### createProtocolServer

```ts
const createProtocolServer: (options?: ProtocolServerOptions) => ProtocolServer;
```

Serves typstream's engine protocol (the one `@typstream/core` defines and the browser worker speaks) from Node, so a
browser can render through your server instead of downloading the engine. It is `@typstream/engine`'s own server code,
over an adapter that compiles on this package's worker pool. [Remote engine](/docs/guides/remote-engine) shows the
client side.

```ts
import { WebSocketServer } from "ws";
import { createProtocolServer, handleWebSocket } from "@typstream/node";

const server = createProtocolServer({ timeouts: { streaming: 3_000, final: 10_000 }, maxDocuments: 32 });
new WebSocketServer({ port: 8080, maxPayload: 8 << 20 }).on("connection", (ws) => handleWebSocket(ws, server));
```

- **Sessions.** Each connection is a session with its own documents. Closing it cancels its queued requests and frees
  its documents.
- **What it offers.** The HTML and paged targets (paged with changed-page updates), and PDF and HTML exports. No
  `resolve/*` requests.
- **Untrusted clients.** Messages are checked before the server reads them; malformed requests, too many documents or
  too long a text get an `invalid-params` error. Clients can't make the server fetch packages or load fixer modules, and
  the fonts and packages a client sends in `initialize` or `document/open` are ignored: the server uses its engine's
  fonts.
- **Watchdog.** Documents live on the main thread and workers only compile, so a watchdog kill costs one compile, not
  the session.

### ProtocolServerOptions

Limits and identity for createProtocolServer; every connection gets the same.

| Prop             | Type                                                   | Description                                                                                                           |
| ---------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `engine?`        | `NodeEngine \| undefined`                              | Default: defaultEngine.                                                                                               |
| `timeouts?`      | `{ streaming?: number; final?: number; } \| undefined` | Watchdog budget per compile by `mode`, in ms; exports are `final`. Default 3,000 streaming, 10,000 final (PLAN §6.3). |
| `maxDocuments?`  | `number \| undefined`                                  | Open documents per connection. Default 32.                                                                            |
| `maxTextLength?` | `number \| undefined`                                  | Longest `/main.typ` (preamble and text), in UTF-16 code units. Default 1,000,000 (PLAN §9).                           |
| `serverInfo?`    | `{ name?: string; version?: string; } \| undefined`    | Reported in `initialize`'s `serverInfo`.                                                                              |

### ProtocolServer

The engine protocol served from Node: one session per client connection.

| Prop      | Type                                                             | Description                                                                |
| --------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `connect` | `(send: (message: ServerMessage) => void) => ProtocolConnection` | Starts a session; `send` delivers server messages to the client, in order. |

### ProtocolConnection

One client's session.

| Prop      | Type                         | Description                                                                                              |
| --------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `receive` | `(message: unknown) => void` | Handles a message from the client. Malformed messages are answered (requests) or logged (notifications). |
| `close`   | `() => void`                 | The client went away: drops its queued requests and documents; nothing more is sent.                     |

To serve the protocol over another transport, call `server.connect(send)` yourself and feed each client message to the
connection's `receive`.

### handleWebSocket

```ts
const handleWebSocket: (socket: WebSocketLike, server: ProtocolServer) => ProtocolConnection;
```

Serves one WebSocket. Each text message is a client message in the protocol's wire format: JSON, with bytes as
`{ "$bytes": "<base64>" }` (`serializeMessage` and `deserializeMessage` from `@typstream/core` read and write it).
Replies go back the same way, and the connection closes with the socket. `ws`'s `WebSocket` fits `WebSocketLike`, and
so does anything with the same `on`, `send` and `close`. Cap message sizes on the socket server (`ws`'s `maxPayload`).

### WebSocketLike

The parts of a WebSocket handleWebSocket uses; `ws`'s `WebSocket`
fits, and so does anything with the same `on` / `send` / `close`.

| Prop    | Type                                                               | Description                                                                                           |
| ------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `send`  | `(data: string) => void`                                           | Sends one text message: a server message in core's wire format.                                       |
| `close` | `(code?: number, reason?: string) => void`                         | Closes the socket with a WebSocket close code and reason.                                             |
| `on`    | `(event: string, listener: (...args: never[]) => void) => unknown` | Subscribes to `"message"` (a text frame: string, `Buffer`, `ArrayBuffer` or fragments) and `"close"`. |

## See also

- [Getting started on Node](/docs/getting-started/node): a first validate-and-render script.
- [Server fix loop](/docs/guides/server-fix-loop): validate, repair with a model, render.
- [Remote engine](/docs/guides/remote-engine): browsers that render through your server.
- [Security](/docs/guides/security): what documents can and can't reach.
- [@typstream/engine-wasm](/docs/reference/engine-wasm): the compiler this package runs.
