C4 architecture
The compiler/runtime boundary
Read detailed explanation (3 sections)
Purpose and review path
Observed
This snapshot adds a parallel client compilation path: shared template parsing feeds a Vapor IR and DOM-oriented code generation. The generated program creates real DOM blocks and registers reactive work with runtime-vapor. Existing VDOM rendering remains a separate path.
Review the IR before individual directives, then cross the generated-helper boundary into the runtime. Finally inspect shared runtime-core/runtime-dom changes for assumptions about renderer-specific fields.
Sources: packages/compiler-vapor/src/compile.ts:33–68 · packages/compiler-vapor/src/ir/index.ts:1–110 · packages/compiler-vapor/src/generators/block.ts:36–85 · packages/runtime-vapor/src/renderEffect.ts:14–70 · packages/runtime-core/src/renderer.ts:1160–1200
The representation is the contract
Observed
Static HTML, dynamic references, operations, effects and return nodes are separate IR concerns. A static template index names a factory; a dynamic node ID names a generated variable. The generated child traversal depends on which IR children are absent from the template. Those identities must remain consistent when a transform wraps, removes or inserts a node.
Sources: packages/compiler-vapor/src/ir/index.ts:1–110 · packages/compiler-vapor/src/ir/index.ts:239–268 · packages/compiler-vapor/src/transforms/transformChildren.ts:60–111 · packages/compiler-vapor/src/generators/template.ts:41–118
Where to extend
Proposed
Proposed feature path: add or override a transform, define typed IR if existing operations cannot express the behavior, dispatch it in genOperation, expose the runtime helper and test its lifetime. An expression-only feature may belong entirely in expression codegen; a new runtime abstraction is unnecessary when the existing Block contract suffices.
Sources: packages/compiler-vapor/src/compile.ts:33–68 · packages/compiler-vapor/src/compile.ts:76–99 · packages/compiler-vapor/src/generators/operation.ts:30–95 · packages/compiler-vapor/src/generators/expression.ts:120–240 · packages/runtime-vapor/src/block.ts:106–166