Render targets
The two ways typstream shows a document, semantic HTML or pages, how each one renders and updates, and which to pick.
Typst compiles one source to two kinds of output, and typstream renders both. HTML is Typst's HTML export: semantic elements and MathML, laid out on pages that look like the paged view's. Paged is pages, laid out exactly as the document prints. You choose with target:
<Typstream source={text} isStreaming={streaming} target="paged" />Switch between them below. The document has a heading, an #align, a #grid of boxes and a display equation.
= Plant cells
#align(center)[_Two parts to label on your diagram._]
#grid(
columns: (1fr, 1fr),
gutter: 12pt,
rect(width: 100%, inset: 8pt)[*Nucleus* \ holds the cell's DNA],
rect(width: 100%, inset: 8pt)[*Chloroplast* \ turns light into sugar],
)
Photosynthesis, balanced:
$ 6 "CO"_2 + 6 "H"_2"O" -> "C"_6"H"_12"O"_6 + 6 "O"_2 $At a glance
HTML ("html") | Paged ("paged") | |
|---|---|---|
| Output | Semantic HTML (h2, p, table, figure) and MathML | One canvas per page (SVG with renderer: "svg") |
| Layout | Pages as the paged view's: the document's page size, margins, headers and footers, lines and page breaks where Typst puts them | As printed: the document's page size, margins, headers and footers |
| Fidelity | The paged view's, with html-compat and Typst's fonts (a few gaps below) | Identical to Typst's own output and the PDF |
| Theme | Pages look like paper | Pages look like paper |
| Text | Real text: selectable, searchable, read by screen readers | An invisible text layer over each page does the same |
| Updates | Only changed blocks are replaced | Only changed pages are redrawn, visible ones first |
| Streaming effects | Word fade-in, caret | None |
| Compile cost | Lower: no page layout | Higher: full page layout |
HTML
The HTML target shows Typst's HTML export: headings, paragraphs, lists, tables, figures with captions, resolved references, footnotes and MathML. Its text is ordinary text, in your page's DOM. With html-compat, the renderer lays it out on pages, as the paged view shows the document: the same fonts, sizes, line breaks, spacing and page breaks, so switching between the targets changes nothing you can see.
Sanitized. The HTML comes from a document a model wrote, so the renderer treats it as untrusted. Each block is parsed in an inert template, cleaned against an allowlist, and those same nodes are moved into the page (nothing is serialized again). Scripts, forms, event handlers and data-* attributes are removed; links may only be http(s), mailto or #fragment, and external ones open in a new tab (linkTarget); images may only be data: or blob: URLs; CSS that loads anything or uses position: fixed is dropped. Ids get a prefix per renderer, so two documents on one page don't clash. See Security.
Block diffing. The artifact is split into top-level blocks as a string, and a block's HTML is its identity. On each update the renderer keeps unchanged blocks, and parses, sanitizes and inserts only new ones. A streamed token usually touches one block, so an update takes about a millisecond, and text you are selecting isn't replaced underneath you.
Source anchors. In HTML compiles, the engine marks where each top-level block starts in the source, and the renderer records it as a data-typstream-src attribute on the block, so a block can be traced back to the text that made it.
Beta
The renderer's methods that read source anchors, blockAt(offset) and sourceRange(node), are @beta and may change.
Layout needs html-compat. Typst 0.15.1's HTML export drops layout elements it can't express, and the text inside them: #grid, #align, #rect, #place, #stack, #columns come out empty. @typstream/html-compat is a Typst prelude that writes the layout Typst gives them on pages (grids placed as Typst places cells, spacing as Typst's flow collapses it, text styles, page geometry, headers and footers) and draws what only a drawing can express (curves, polygons, CeTZ canvases, equations) as inline SVG. The typstream package includes it; with @typstream/react or @typstream/dom, add the htmlCompat plugin. It doesn't change paged output.
Fonts. Text is set in Typst's own fonts, registered with the engine's layout profile as their line box, so lines are as tall as Typst's. typstream registers them, and New Computer Modern Math for MathML; with @typstream/react or @typstream/dom, pass the engine's fonts as fonts and the math font as mathFont (or call registerTypstFonts and registerMathFont).
The HTML renderer lays the document out on pages as the paged view does: page columns, a second set page(…)
mid-document (its numbering, margins and counter(page).update), inside and outside margins, headers, footers and
footnotes included. What HTML still can't show as the pages do:
- Drawings are SVG: their text is in an
aria-label, not selectable. fletcher diagrams stay empty. - Text in a script no engine font covers (CJK by default): the pages show boxes for it, the browser draws it in
a font of its own. Give the engine a font for it and register the same file for the HTML target (
fonts); a document that names it (#set text(font: …)) shows it in both. See Fonts and languages.
Details: @typstream/html-compat.
Paged
The paged target shows each page as Typst lays it out: what you see is what prints, down to the page numbers. Use it wherever the document is a document: worksheets, exams, anything a teacher will print.
Canvas pages. The engine sends each page as drawing operations (glyph outlines, shapes, images, links), and the renderer paints them on a <canvas> per page. A dense page of text and math paints in about a millisecond in Chromium and Safari, and 10–15 ms in Firefox. As inline SVG, the same page took 12–31 ms per update, because the browser styles and lays out one element per glyph. The page is the same as Typst's SVG, pixel for pixel up to antialiasing.
- Sharp at any zoom. Canvases are painted at the screen's pixel density and painted again when it changes (browser zoom, another monitor) and after a pinch zoom settles.
- Memory. A page's pixels take 8–14 MB at a pixel ratio of 2, so only pages near the viewport keep them. A page that scrolls away gives them up a second later and is painted again when it comes back.
- Printing. Before the browser prints, every page is painted, at twice the screen's resolution or more.
exportPdf()prints the vector PDF instead. - SVG where needed. Pages with something the drawing doesn't express yet (gradients, tilings, colour emoji) come as SVG and are drawn as before.
renderer: "svg"makes every page SVG: vector at any zoom, slower to update.
Changed pages only. The engine compares each page with the previous compile and sends only pages that changed, usually the last one or two while streaming. The renderer keeps one element per page and redraws a page only when it differs. Changed pages on screen are drawn at the next frame; offscreen pages and text layers wait for idle time, or are drawn as soon as they scroll into view.
SVG pages: one shadow root each. Typst's SVG repeats glyph definitions under the same ids on every page. Inline in one document, Chromium re-resolves every glyph reference on the page whenever one page changes, which makes long documents slow. Each SVG page lives in its own shadow root, which scopes those ids and keeps your app's CSS off the SVG.
Text layer. Pages draw glyphs as shapes, so invisible HTML text is laid over each page from the engine's text runs, stretched to each run's width. Selection, copy (with line breaks), find-in-page and screen readers use it, and it carries structure: headings with their level, lists, tables with rows and header cells, and the text's language and direction (Arabic reads right to left). The canvas or SVG itself is hidden from assistive technology. textLayer: false turns the layer off.
Links. Only http(s) and mailto links keep their target and open in a new tab. On a canvas page they are links laid over their text. Links within the document (to a heading or a figure) stay inert for now.
Layouts.
layout: "fixed"(default) shows pages at their authored size, scaled down to fit the element.layout: "fit-width"shows the same pages scaled up or down to the element's width, as a PDF viewer's "fit width" does. Resizing only scales them; nothing compiles again.layout: "reflow"lays the document out again on pages as wide as the element, recompiling after a resize (150 ms after it stops), for a narrow panel where a scaled A4 page would be too small to read. Its lines and pages then break elsewhere than in the PDF. It sets the default page size, so a document with its own#set page(paper: …)keeps it. Pages keep A4 proportions by default, so a long document still updates page by page;pageHeight: "auto"makes one page as tall as the content, for short documents.
fixed and fit-width show exactly the PDF's pages (a test compares them pixel by pixel). Exports print at the document's own page size, not the reflow size.
Layout profile
Every page the engine lays out, on screen or in a PDF, follows typstream's layout profile: settings under which Word and other word processors break lines and pages where Typst does, so a DOCX export can match the PDF and the pages on screen. The HTML target doesn't use it. In LibreOffice, a document laid out this way breaks every line and page as Typst does.
- A constant line pitch of 1.3 times the text size, close to Typst's default spacing.
- Ragged right, without hyphenation, lines filled one at a time. Word justifies and hyphenates differently from Typst, so either would move line breaks.
- No hanging punctuation. Typst lets a full stop at the end of a line hang into the margin, Word doesn't: a line that only fit with it would break elsewhere in Word, and a right-aligned or centred line would sit a little off.
- Table rows stay on one page. A row taller than a page runs off it, so long text belongs in paragraphs, not in a table cell.
- Inline math gets at least one line's height.
- Display equations with line breaks keep Typst's default spacing between their lines (the text's is set by the pitch).
The profile's rules win over a document's #set par(justify: true), its #set text(hyphenate: true) or its leading. A document can still set the gaps between paragraphs and headings, its fonts and its sizes. Heal's layout-profile lint rule takes out what would beat the profile: par(justify: true)[…] arguments and the document's own show par: set par(…) rules. It also squares the corners of boxes models draw around text (block(radius: 3pt)[…], a small fixed radius): Word can't draw a rounded frame, so a DOCX export would have to make a picture of the box, its text no longer editable.
Plugins can step outside the profile on purpose with an element's own arguments or a show-set rule of their own. edu's answer lines do, so that written answers sit on the ruled lines.
Which to pick
- A document panel, a print preview, anything that will be printed: paged. It is exactly the PDF, page breaks and all, and it is typstream's primary surface, tested and polished first.
- Short answers inline in a chat: HTML. It flows with the conversation, takes your theme and dark mode, animates words as they arrive, and costs less to compile and draw.
The default target is still "html", so set target="paged" for a document panel; for a panel whose pages should fill its width, add layout="fit-width".
You can switch at any time. Switching keeps the document and its text; the old output stays until the first compile in the new target. Whatever the preview shows, exportPdf() and exportHtml() export the same source (Exports).
Streaming and final mode
The lifecycle of a typstream document, from the first token to the finished answer, its statuses, what final mode changes, and how regenerating and editing work.
The engine
How @typstream/engine compiles streamed Typst in a Web Worker, when it compiles, how the watchdog keeps runaway documents from freezing the page, and its limits.