Module: lib/compiler/render/program

The shape of a compiled render program, and the vocabulary the compiler and the runtime agree on.

Why a program at all

The previous rendering contract between the compiler and the runtime was a single string: the compiler handed over a template with {{ }} still in it, and the runtime worked out what that meant on every update. Working it out meant interpolating the whole template into HTML, handing that HTML to DOMParser, and diffing the resulting tree against the live DOM — so the cost of changing one value was proportional to the size of the template, and the runtime had to carry a template engine to pay it.

None of that work depends on runtime values. Which text nodes are dynamic, which attributes are bound, which elements carry an event handler, and which subtrees can never change are all properties of the template, and the compiler already has the template. A render program is the compiler writing those answers down once, so the runtime can stop rediscovering them.

The two halves

A program is a skeleton, a list of ops, and a list of blocks.

The skeleton is the template with every dynamic part removed: interpolations become comment markers, bound attributes are dropped. It is valid HTML that is parsed exactly once per component class and then cloned per instance, so a 2000-node template is parsed once for the life of the page rather than once per update.

An op says what to do and where. { k: 'text', t: 3, x: 'count' } reads "evaluate count, write it to text marker 3". Each op becomes one reactive effect at mount, so a write to count wakes that op and nothing else.

Addressing, and why markers rather than paths

The compiler cannot number nodes by walking its own AST and assume the browser will produce the same tree: HTML parsing inserts implied elements (<tbody>), relocates misplaced content, and closes tags the author left open. A path computed from the compiler's tree can therefore address a different node than the one the compiler meant.

So the compiler emits markers — data-axb="n" on a dynamic element, <!--axt:n--> where dynamic text goes — and the runtime resolves them against the tree the browser actually built. That resolution happens once per component class (module:lib/core/renderer/program/CompiledTemplate), is cached as index paths, and every later instance resolves by path with no search.

What the compiler refuses to compile

A program is emitted only when every construct in the template is one the program runtime implements. Anything else and the component keeps the string renderer, with the reason recorded. Partial compilation is not offered: a template that is half compiled and half diffed has two sources of truth for the same DOM, and they will disagree.

That fallback is visible rather than silent — avenx build reports which components did not compile and why, which is the same house rule Atlas follows when its analysis is incomplete.

The refusal reasons themselves live with the layer that decides them, in module:lib/compiler/ir/nodes. They used to live here, next to a second template compiler that read already-rewritten markup; that compiler has been replaced by the IR and its lowering pass, so this module is now the format and the vocabulary and nothing else.