The Register Virtual Machine
The DriftJS Virtual Machine is an execution engine that models UI rendering through direct register operations. It exists in two implementations sharing identical bytecode semantics:
DriftClientVM(driftjs-dom): Runs in browser environments, manipulating physical DOM elements, text nodes, and document fragments.DriftServerVM(driftjs-ssr): Runs in Node.js / edge runtime environments, manipulating lightweightServerNodetrees for static serialization.
The 256-Register Bank
Both VMs allocate a pre-sized array of 256 internal registers:
// packages/dom/src/index.ts
export class DriftClientVM {
private static readonly MAX_REGISTERS = 256;
private readonly registers: (Node | any)[] = new Array(DriftClientVM.MAX_REGISTERS);
...
}
Why 256 Registers?
- Bytecode Density: A single byte (
0x00through0xFF) addresses any register in the VM. - Cache Locality: An array of 256 references is compact, predictable, and stays in CPU cache.
- Zero GC Overhead: Registers are initialized once when the VM instance is created. No register objects are pushed or popped onto a heap stack during execution.
Register Allocation Strategy
During compilation, DriftGenerator assigns registers using a high-water mark allocator:
r0is typically reserved as the root node or document fragment returned at the end of execution.- Parent elements hold their assigned register (e.g.
r1for<div class="card">). - Child nodes allocate incremental registers (
r2for<h2>,r3for dynamic text). - Once child nodes are appended into their parent (
APPEND_CHILD r1, r2), those child registers can be reclaimed and reused for subsequent sibling nodes.
Virtual Machine Execution Modes
The client VM operates in three distinct execution modes:
Mount Execution Mode
- Triggered when a component is initially mounted via
mount()orMOUNT_COMPONENT. - The instruction pointer (
pc) starts at index0and steps linearly through bytecode. - DOM elements and text nodes are created, configured with static attributes, and stored in registers.
- Event handlers are registered and bound to elements.
- The instruction
RETURN reghalts execution and returns the finished DOM subtree.
Update Execution Mode
- Triggered by microtask flushing when variables are marked dirty.
- The VM does not re-execute from
pc = 0. - It jumps directly to the bytecode indices recorded in
reactiveBindingsfor the dirty variables. - Registers continue holding the live physical DOM nodes created during the mount phase.
- The VM computes the new value and applies it directly to the target node (e.g.,
textNode.nodeValue = ...).
Hydrate Execution Mode
- Triggered during client hydration via
hydrate()orhydrateIslands(). - The VM pairs bytecode execution with a
HydrationCursorwrapping a browserTreeWalker. - When
CREATE_ELEMENTruns, instead of allocatingdocument.createElement(), the cursor claims the next matching element from server-rendered HTML. - Event listeners are attached without destroying or recreating DOM nodes.
Component Scope Hierarchy
State in DriftJS is stored on a scoped JavaScript object:
- Sub-modules (such as consequent branches of
@ifor row templates of@for) inherit variables from the parent component using standard JavaScript prototype delegation:const childScope = Object.create(parentScope); - Reading outer-scope variables (
user,theme) walks up the prototype chain naturally without copy overhead. - Updates to loop iteration aliases (
item,index) remain isolated on the child scope without polluting parent state.