Taliesin Internals

How one saved keystroke becomes one repainted paragraph: the Rust core and its thin clients, the running example, and how to read this book.

How Taliesin works

You change one number in a .tmd file and hit save. The paragraph you touched re-renders in place, and nothing else moves: your scroll position holds, the 3D canvas two sections down keeps spinning, the Jupyter kernel stays warm. This book explains how.

The companion User Guide is about using Taliesin; this one is about how it is built, for contributors, for anyone extending it, and for readers who want the reasoning behind its design decisions.

A Rust core with thin clients

All of the intelligence lives in a Rust core, and every client is thin. The core parses a .tmd into a block model, renders each block to HTML, and speaks a small, stable websocket protocol. The browser preview is a consumer of that protocol (the VS Code companion hosts the same preview), and the build command writes the same blocks to a file, so a new client can be added without a rewrite.

The rest of this book explains what follows from that design:

Click-to-source. Every block carries the source position it came from.
Block-level incremental updates. A save ships only the blocks that changed, so live state survives the edit.
No per-edit startup cost. A warm server and a warm Jupyter kernel, kept across saves.

Our running example

To keep things concrete, the chapters follow one tiny document, post.tmd:

# Cooling coffee

A fresh cup cools toward room temperature, the gap shrinking exponentially:
$T(t) = T_\text{room} + (T_0 - T_\text{room})\,e^{-t/\tau}$.

```{python}
import numpy as np
import matplotlib.pyplot as plt

t = np.linspace(0, 30, 200)
plt.plot(t, 20 + 70 * np.exp(-t / 10))   # tau = 10 minutes
plt.show()
```

post.tmd has three blocks: a heading, a paragraph with a line of math, and a Python cell that draws a cooling curve. It touches every part of the system: prose and a heading to render, math to typeset, code to highlight and to run, and an output to splice back in. Across the book we watch it become blocks, get diffed, cached, and pushed to the browser. When a chapter needs a concrete edit, we change the cooling constant tau from 10 to 12.

This book is built with Taliesin, so Figure 1 is drawn by running post.tmd’s own code as this page renders, through the pipeline the rest of the book describes.

Figure 1: post.tmd’s cooling curve, drawn by running its cell as this page was built.

How to read this book

The chapters build on each other, roughly from the outside in:

Architecture: the crates, the data flow, a save end to end.
The rendering pipeline: raw text to a block model to HTML, with math and highlighting resolved offline.
The block model: the structure the rest of the system depends on, and the websocket contract built on it.
Code execution & the kernel: the warm kernel, the execution plan, the persistent output cache.
Extending Taliesin: the conventions, and the one seam meant to be extended without touching the core.

If you read only one chapter, read Architecture. It frames everything else.