Taliesin Internals

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. No flash, no reload, no cold start. This book is how that works.

The companion User Guide is about using Taliesin; this one is about how it is built, for contributors, for anyone extending it, and for the curious reader who would rather see the design decisions than take them on faith.

The one idea

Everything here follows from a single architectural choice: 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, the build command, and the VS Code companion extension are all just consumers of that protocol; the next client is a new consumer, not a rewrite. Nothing clever lives in the client.

Three properties fall out of that design, and they are what the rest of this book explains in detail:

• 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()
```

Three blocks: a heading, a paragraph with a line of math, and a Python cell that draws a cooling curve. It is barely a document, yet 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 turn one knob: the cooling constant tau, from 10 to 12.

And because this book is itself built with Taliesin, that cell is not a screenshot: Figure 1 is drawn by running post.tmd’s own code as this page renders, through the very pipeline the rest of the book describes.

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 load-bearing structure and the websocket contract that rides 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.