typstream

@typstream/mindmap

Mind maps written as a list, drawn in plain Typst for print and PDF, and interactive in the viewer (pan, zoom, open and close branches); a plugin with its prompt kit and the first render island.

@typstream/mindmap adds mind maps to typstream documents. A model writes one as a list: the centre topic, then its branches, nested by indentation. Typst draws it, and that drawing is what prints, what exportPdf() and standalone HTML contain, and what any renderer without the island shows. In <Typstream>, the interactive map mounts over the drawing: readers pan, zoom, and open and close branches. It is the first render island.

Install

npm install @typstream/mindmap

Example

import { mindmap } from "@typstream/mindmap";
import { mindmapIslands } from "@typstream/mindmap/react";
import { Typstream } from "typstream";

<Typstream source={text} plugins={[mindmap]} islands={mindmapIslands} />;
import { buildSystemPrompt, edu } from "@typstream/edu";
import { mindmap } from "@typstream/mindmap";

// The model learns `#mindmap` and when to use it.
const system = buildSystemPrompt([edu, mindmap]);

Without islands, documents show the drawing: the plugin alone is enough for print, PDF and non-React apps.

idle
#mindmap[
  Photosynthesis
  - Inputs
    - Sunlight
    - Water ($H_2 O$)
    - Carbon dioxide
  - #topic(collapsed: true)[Where]
    - Leaves
    - Chloroplasts
  - Outputs
    - Glucose
    - Oxygen
]

Writing a mind map

The text before the list is the centre. Each - (or +) item is a node; items indented under it are its branches. Labels are content, so $H_2 O$ and *bold* work in the drawing; the interactive map shows them as plain text, with math's sub- and superscripts as Unicode (H₂O).

mindmap

#mindmap(style: "visual", layout: "both", text-size: 1em)[centre and branches]
ParameterDefault
style"visual""visual": a colour per main branch, and images. "text-focused": neutral colours, no images, wider labels, for printing and revision.
layout"both""both": branches on both sides of the centre, the first half on the right. "right": all on one side, which grows in the text's direction (left in Arabic). For narrow columns.
text-sizethe document'sThe main branches' text size; the centre is 1.25 times it and deeper levels 0.9 times.

The drawing scales down to fit the column.

topic

Wrap a label in #topic(...) to set that node's options. Nodes below a coloured one take its colour unless they set their own.

ParameterDefault
colorthe branch'sA Typst colour or a hex string ("#dc2626"): the node's border, tint, and the lines to its children.
sizeby levelText size.
weightbold for the centre and main branches"bold" or "regular".
imagenoneAn image(...) above the label, with alt as its caption. Not shown in text-focused maps.
collapsedfalseIts branches start hidden: the interactive map opens them on a click, and the drawing shows how many there are (+3).
#mindmap(style: "text-focused")[
  #topic(size: 14pt)[Causes of World War I]
  - #topic(color: "#2563eb")[Alliances]
    - Triple Entente
    - Triple Alliance
  - #topic(color: "#dc2626")[Trigger]
    - Assassination of Franz Ferdinand
  - #topic(collapsed: true)[Further reading]
    - Clark, The Sleepwalkers
]

An image is a Typst image call, so it goes through the engine's image handling: nothing is fetched unless your resolveImage allows the URL, and a missing image is a placeholder. The interactive map shows the same bytes the drawing used (IslandProps.file) and never fetches a URL itself.

While it streams

Every cut of a stream leaves something that compiles and draws what has arrived: #mindmap[ draws nothing, a half-typed label is a node, and an option cut mid-value (color: "#16, weight: "bo) falls back to its default. In <Typstream> the interactive map mounts once and grows with the stream; it fits itself to its box until the reader moves it. Its isIncomplete is true while the map's source is still arriving.

Interactivity

  • Pan by dragging. Zoom with a pinch, Ctrl or ⌘ and the wheel, or the buttons (shown when the map is at least 140 px tall). The plain wheel scrolls the page, so a map never traps scrolling.
  • Open and close a branch by clicking its node, or with Enter or Space once it has focus (Tab moves through the nodes). Each node's accessible name says whether it is expanded and how many nodes it hides.
  • Read-only. Nothing the reader does changes the document.

The map lays out the way the drawing does, measuring labels in the page's font, so it looks like what prints. It paints its own background over the drawing (--typstream-island-background, default Canvas), and print shows the drawing.

Paged target

On pages (target="paged"), the map mounts in a box over its drawing on the page: as wide as the column and as tall as the drawing, scaled with the page. The page's canvas keeps the drawing, which is what prints and exports; the island covers it with white, the paper. A map that moves as text before it streams in, or onto the next page, stays mounted.

Cost

React Flow (@xyflow/react, MIT) draws the interactive map. It is about 59 KB gzipped, loaded the first time a document shows a map, not before; the drawing stays visible under the island meanwhile.

A map costs 9–11 ms per compile while streaming in the engine (median; 16–17 ms at p90), against under 5 ms for the same text as a plain list. It is drawn in plain Typst, not with CeTZ, whose first canvas costs 100–260 ms.

API

ExportWhat it is
mindmapThe plugin.
MindMapIsland, mindmapIslandsThe interactive map, from @typstream/mindmap/react.
parseMindMap, mindmapIslandThe check of a marker's data, and the island's spec.
MindMapData, MindMapNodeWhat the marker carries.
mindmapFiles, mindmapPreamble, MINDMAP_ROOT, MINDMAP_VERSIONThe Typst package, mounted as @typstream/mindmap:0.1.0.
mindmapCatalogue, mindmapPromptRules, mindmapExamplesThe prompt kit.
MAX_NODESThe most nodes a map's data may have (2,000); a larger map keeps its drawing.

mindmap

const mindmap: TypstreamPlugin;

The plugin, with key "mindmap":

  • engine.files and engine.preamble: the Typst package, and #import "@typstream/mindmap:0.1.0": mindmap, topic.
  • prompt: the catalogue of mindmap and topic from their doc comments, rules (when to draw a map, short labels in a logical order, colours with a reason, images only on a few key nodes), and two example documents.
  • islands.mindmap: mindmapIsland.

MindMapIsland

const MindMapIsland: (props: IslandProps<MindMapData>) => JSX.Element;

The mindmap island as a React component, for <Typstream islands> and <TypstreamProvider islands>. React Flow and the map's code load lazily, inside its own Suspense.

mindmapIslands

const mindmapIslands: { readonly mindmap: typeof MindMapIsland };

{ mindmap: MindMapIsland }, to pass as islands.

parseMindMap

function parseMindMap(data: unknown): MindMapData | undefined;

Checks a marker's data, which the document wrote and is untrusted: the shape the Typst side writes, colours as hex, sizes and label lengths in range, at most 2,000 nodes and 16 levels. Anything else is undefined, and the drawing stays.

mindmapIsland

const mindmapIsland: IslandSpec<MindMapData>;

The island's spec: its description and parseMindMap.

MindMapData

Prop

Type

Prop

Type

On this page