typstream

@typstream/universe

The Typst Universe packages typstream allows by default (CeTZ, fletcher, cetz-plot, physica, unify, chemformula, alchemist), vendored with integrity hashes as a plugin.

@typstream/universe vendors the Typst Universe packages typstream allows by default, for diagrams, math and chemistry, with their integrity hashes. It is a plugin: it gives the engine an allowlist of packages documents may import, and gives the prompt kit a rule naming them, so the model imports only what will compile.

When to use it

The typstream package's <Typstream> adds it by default (packages={false} turns it off). Add it yourself when you use @typstream/react, @typstream/dom or @typstream/engine and want documents to import these packages, and pass it to buildSystemPrompt so the model knows about them.

Leave it out if you can't ship LGPL code (see Licenses), or if you want a different set of packages: pass your own allowlist instead. Typst packages covers both.

Install

npm install @typstream/universe

Example

import { universe } from "@typstream/universe";
import { Typstream } from "@typstream/react";

// As a plugin on a document: the engine's allowlist and the prompt rules.
<Typstream source={text} plugins={[universe]} />;
import { createEngine, engineWorker } from "@typstream/engine";
import { universe } from "@typstream/universe";

// Or engine-wide: every document on this engine may import them.
const engine = createEngine({ spawn: engineWorker(), plugins: [universe] });

A document then imports a package as it would with the Typst CLI:

#import "@preview/cetz:0.5.3"

#cetz.canvas({
  import cetz.draw: *
  line((0, 0), (4, 0), (2, 3), close: true)
  content((2, -0.5), [4 cm])
})

Packages

ForPackageImport
Diagrams@preview/cetz:0.5.3#import "@preview/cetz:0.5.3"
Diagrams@preview/fletcher:0.5.8#import "@preview/fletcher:0.5.8": diagram, node, edge
Math@preview/cetz-plot:0.1.4#import "@preview/cetz-plot:0.1.4": plot
Math@preview/physica:0.9.8#import "@preview/physica:0.9.8": *
Math@preview/unify:0.8.1#import "@preview/unify:0.8.1": num, qty, unit
Chemistry@preview/chemformula:0.1.3#import "@preview/chemformula:0.1.3": ch
Chemistry@preview/alchemist:0.2.0#import "@preview/alchemist:0.2.0": *

Their dependencies come too, pinned as the packages pin them: cetz 0.5.2 and 0.3.4, and oxifmt 1.0.0 and 0.2.1.

A document that imports another version of an allowed package gets the closest one (the newest with the same major and minor version, else the newest) and a warning: "package @preview/cetz:0.5.0 isn't available here; using @preview/cetz:0.5.3". A package that isn't allowed fails with "package … is not allowed" and a hint listing the allowed ones.

How packages load

  • Tarballs. The package ships the .tar.gz files exactly as packages.typst.org serves them. Each url is written as new URL("../vendor/…", import.meta.url), which bundlers emit as an asset, so the engine fetches packages from your own origin, not from typst.org. It fetches one only when a document imports it, and keeps it in Cache Storage after that.
  • Integrity. Every tarball is checked against its integrity before use. The hash is the SHA-256 of the uncompressed tar, so it holds even when a server sends the .gz with Content-Encoding: gzip (Vite's dev server does) and the browser hands over the tar.
  • Plugins. CeTZ calls its cetz-core wasm plugin for geometry, so the engine keeps Typst's plugin support.
  • Strict CSP. The tarballs are fetched from your origin, so connect-src 'self' covers them. See Security.

@typstream/node doesn't fetch packages: its documents can import one only if you mount the package's files under its spec yourself.

HTML target

With @typstream/html-compat, CeTZ canvases (cetz, cetz-plot, alchemist) become inline SVG in the HTML target. fletcher diagrams stay empty in HTML: its CeTZ 0.3.4 canvas calls layout where html-compat can't reach. They render in the paged target. See html-compat's known gaps.

Licenses

Each tarball carries its package's own license, unmodified:

LicensePackages
LGPL-3.0-or-latercetz (every version), cetz-plot
MITfletcher, physica, unify, chemformula, alchemist
MIT OR Apache-2.0oxifmt 1.0.0
MIT-0oxifmt 0.2.1

LGPL

cetz and cetz-plot are LGPL-3.0-or-later. An app that can't ship LGPL code should leave this plugin out (with typstream, packages={false}) and pass its own allowlist.

API

ExportWhat it is
universeThe plugin: the engine's package allowlist and prompt rules.
UNIVERSE_PACKAGESEvery vendored package, dependencies included.
UniversePackageA vendored package: a PackageSpec with url and integrity set.
UniverseTopic"diagrams" | "math" | "chemistry".

universe

const universe: {
  key: string;
  engine: { packages: { namespace: string; name: string; version: string; url: string; integrity: string }[] };
  prompt: { rules: string[] };
};

The vendored packages as a typstream plugin, with key "universe". engine.packages is the allowlist: every entry of UNIVERSE_PACKAGES with its URL and integrity. prompt.rules tells the model to import only these packages at exactly these versions, then lists each importable one with its topic, how to import it and a one-line usage example. buildSystemPrompt from @typstream/edu includes them:

import { buildSystemPrompt, edu } from "@typstream/edu";
import { universe } from "@typstream/universe";

const system = buildSystemPrompt([edu, universe]);

UNIVERSE_PACKAGES

const UNIVERSE_PACKAGES: readonly UniversePackage[];

Every vendored package, dependencies included (eleven entries). The packages documents import have a topic and a summary; dependencies don't. Use it to build your own allowlist, for example without the LGPL packages:

import { UNIVERSE_PACKAGES } from "@typstream/universe";

const keep = new Set(["physica", "unify", "chemformula"]);
const permissive = UNIVERSE_PACKAGES.filter((p) => keep.has(p.name));

fletcher, cetz-plot and alchemist import cetz (and cetz imports oxifmt), so dropping cetz means dropping them too. physica, unify and chemformula have no dependencies. To use such a list, put it in a plugin's engine.packages facet (beta in @typstream/core) and pass that instead of universe:

import { definePlugin } from "@typstream/core";
import { Typstream } from "typstream";

const packages = definePlugin({ key: "packages", engine: { packages: permissive } });

<Typstream packages={false} plugins={[packages]} source={text} />;

UniversePackage

Prop

Type

It extends @typstream/core's PackageSpec (beta):

Prop

Type

UniverseTopic is "diagrams" | "math" | "chemistry": what a document imports the package for.

See also

On this page