Materialize static template subtrees in one step

A run of statements that only builds static structure -- plus holes where
its dynamic values go -- is described once and materialized by cloning a
cached node, instead of compiling to one opcode per element, static
attribute and static text node.

Measured on a 1000-row krausest create before this change: of ~37ms of
rendering JS, ~14.6ms is that static structure, ~7.4ms of it in DOM calls
(8 createElement, 6 setAttribute, 13 insertBefore per row -- 34 DOM calls
per row, 340k for 10k rows).

The pre-pass runs in `compileStatements`, so it needs no wire-format
change and works on already-published templates. A run is extracted only
when it is an element-rooted subtree of at least two elements whose holes
are dynamic attributes or last-child dynamic content. Components, blocks,
splattributes, modifiers, comments, trusted HTML and mid-child content
holes all end a run; bailing is always safe, since the caller then
compiles the statements the ordinary way. Coverage measured over 766 of
this repo's own test templates: 40% of static structure sits in runs of
two or more elements, and both benchmark rows (krausest and dbmon) are a
single 8-element run covering all of theirs.

Two paths are emitted for each run, chosen at runtime:

- when the tree builder can clone, the subtree is materialized in one step
  and the dynamic values are filled in at their holes
- otherwise the run's original statements execute, in their original order

The second path is not a nicety. Rehydration matches against
server-rendered nodes and the SSR serializer interleaves block markers
with construction, so both need each step in order: filling holes after
the fact sets attributes after their element was flushed, and looks for a
dynamic block's markers after its enclosing elements are already closed.
An earlier attempt to serve both paths from a descriptor walk failed 16
rehydration tests for exactly that reason, leaving stray `%-b:0%` markers.

Cloning also keeps namespaces correct for free -- the cached node is built
with the ordinary DOM operations, in context -- which a serialized HTML
skeleton would not.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Author: NullVoxPopuli

packages/@glimmer/constants/lib/syscall-ops.ts

@@ -1,5 +1,8 @@
 import type {
   VmAppendDocumentFragment,
+  VmAppendStaticTree,
+  VmEnterHole,
+  VmExitHole,
   VmAppendHTML,
   VmAppendNode,
   VmAppendSafeHTML,
@@ -183,7 +186,16 @@ export const VM_IF_INLINE_OP = 109 satisfies VmIfInline;
 export const VM_NOT_OP = 110 satisfies VmNot;
 export const VM_GET_DYNAMIC_VAR_OP = 111 satisfies VmGetDynamicVar;
 export const VM_LOG_OP = 112 satisfies VmLog;
-export const VM_SYSCALL_SIZE = 113 satisfies VmSize;
+/**
+ * Append a whole static subtree in one step: clone it when the tree builder
+ * can, otherwise walk its descriptor through the ordinary builder calls.
+ */
+export const VM_APPEND_STATIC_TREE_OP = 113 satisfies VmAppendStaticTree;
+/** Position the builder at one of that subtree's dynamic holes. */
+export const VM_ENTER_HOLE_OP = 114 satisfies VmEnterHole;
+/** Leave a hole and restore the builder's position. */
+export const VM_EXIT_HOLE_OP = 115 satisfies VmExitHole;
+export const VM_SYSCALL_SIZE = 116 satisfies VmSize;
 
 export function isOp(value: number): value is VmOp {
   return value >= 16;

packages/@glimmer/interfaces/index.d.ts

@@ -18,6 +18,7 @@ export type * from './lib/runtime.d.ts';
 export type * from './lib/runtime/vm.d.ts';
 export type * from './lib/serialize.d.ts';
 export type * from './lib/stack.d.ts';
+export type * from './lib/static-tree.d.ts';
 export type * from './lib/tags.d.ts';
 export type * from './lib/template.d.ts';
 export type * from './lib/tier1/symbol-table.d.ts';

packages/@glimmer/interfaces/lib/dom/attributes.d.ts

@@ -1,6 +1,7 @@
 import type { Maybe, Nullable } from '../core.js';
 import type { ElementOperations, Environment, ModifierInstance } from '../runtime.js';
 import type { Stack } from '../stack.js';
+import type { StaticTree } from '../static-tree.js';
 import type { Bounds, Cursor } from './bounds.js';
 import type { GlimmerTreeChanges, GlimmerTreeConstruction } from './changes.js';
 import type {
@@ -74,6 +75,16 @@ export interface DOMStack {
   ): AttributeOperation;
 
   closeElement(): Nullable<ModifierInstance[]>;
+
+  /**
+   * Materialize a run of static structure in one step, and remember it so
+   * its dynamic holes can be found by index.
+   */
+  appendStaticTree(tree: StaticTree): boolean;
+  /** Position the builder at hole `index` of the current static tree. */
+  enterHole(index: number): void;
+  /** Restore the position saved by `enterHole`. */
+  exitHole(index: number): void;
 }
 
 export interface TreeOperations {

packages/@glimmer/interfaces/lib/static-tree.d.ts

@@ -0,0 +1,52 @@
+import type { Nullable } from './core.js';
+
+/**
+ * A description of static template structure, shared by the compiler (which
+ * extracts it) and the runtime (which materializes it).
+ *
+ * A run of statements that only builds structure -- plus holes where dynamic
+ * values go -- is described once here rather than compiled to one opcode per
+ * element, attribute and text node. The runtime clones it where the tree
+ * builder allows, and otherwise walks it through the ordinary builder calls
+ * so rehydration and SSR are unaffected.
+ */
+export interface StaticElement {
+  readonly kind: 'element';
+  readonly tag: string;
+  /** `[name, value, namespace]`, in source order */
+  readonly attrs: [string, string, Nullable<string>][];
+  readonly children: StaticNode[];
+}
+
+export interface StaticText {
+  readonly kind: 'text';
+  readonly chars: string;
+}
+
+export type StaticNode = StaticElement | StaticText;
+
+/**
+ * Where a dynamic value goes, as a path of child-node indices from the run's
+ * root element.
+ */
+export interface AttrHole {
+  readonly kind: 'attr';
+  readonly path: readonly number[];
+}
+
+export interface ContentHole {
+  readonly kind: 'content';
+  readonly path: readonly number[];
+}
+
+export type Hole = AttrHole | ContentHole;
+
+export interface StaticTree {
+  readonly root: StaticElement;
+  readonly holes: readonly Hole[];
+  /**
+   * Clone source, filled in by the runtime the first time this tree is
+   * materialized and shared by every later instance.
+   */
+  cached?: unknown;
+}

packages/@glimmer/interfaces/lib/vm-opcodes.d.ts

@@ -109,7 +109,10 @@ export type VmIfInline = 109;
 export type VmNot = 110;
 export type VmGetDynamicVar = 111;
 export type VmLog = 112;
-export type VmSize = 113;
+export type VmAppendStaticTree = 113;
+export type VmEnterHole = 114;
+export type VmExitHole = 115;
+export type VmSize = 116;
 
 export type VmOp =
   | VmHelper
@@ -202,6 +205,9 @@ export type VmOp =
   | VmIfInline
   | VmNot
   | VmGetDynamicVar
-  | VmLog;
+  | VmLog
+  | VmAppendStaticTree
+  | VmEnterHole
+  | VmExitHole;
 
 export type SomeVmOp = VmOp | VmMachineOp;

packages/@glimmer/node/lib/serialize-builder.ts

@@ -99,6 +99,14 @@ class SerializeBuilder extends NewTreeBuilder implements TreeBuilder {
     return super.__appendText(string);
   }
 
+  /**
+   * The serializer interleaves block markers with construction, so it needs
+   * the descriptor walk rather than a cloned subtree.
+   */
+  protected override get supportsCloning(): boolean {
+    return false;
+  }
+
   override closeElement(): Nullable<ModifierInstance[]> {
     if (NEEDS_EXTRA_CLOSE.has(this.element)) {
       NEEDS_EXTRA_CLOSE.delete(this.element);

packages/@glimmer/opcode-compiler/lib/compilable-template.ts

@@ -16,6 +16,12 @@ import type {
   WireFormat,
 } from '@glimmer/interfaces';
 import { IS_COMPILABLE_TEMPLATE } from '@glimmer/constants/lib/brand';
+import { VM_JUMP_OP } from '@glimmer/constants/lib/vm-ops';
+import {
+  VM_APPEND_STATIC_TREE_OP,
+  VM_ENTER_HOLE_OP,
+  VM_EXIT_HOLE_OP,
+} from '@glimmer/constants/lib/syscall-ops';
 import { LOCAL_TRACE_LOGGING } from '@glimmer/local-debug-flags';
 import { EMPTY_ARRAY } from '@glimmer/util/lib/array-utils';
 
@@ -26,6 +32,9 @@ import { templateCompilationContext } from './opcode-builder/context';
 import { encodeOp } from './opcode-builder/encoder';
 import { meta } from './opcode-builder/helpers/shared';
 import { STATEMENTS } from './syntax/statements';
+import { HighLevelBuilderOpcodes } from './opcode-builder/opcodes';
+import { labelOperand } from './opcode-builder/operands';
+import { extractStaticTree } from './static-tree';
 
 export const PLACEHOLDER_HANDLE = -1;
 
@@ -97,8 +106,59 @@ export function compileStatements(
     encodeOp(encoder, evaluation, meta, op as BuilderOp | HighLevelOp);
   }
 
-  for (const statement of statements) {
-    sCompiler.compile(pushOp, statement);
+  for (let i = 0; i < statements.length; i++) {
+    /**
+     * A run of statements that only builds static structure (plus holes for
+     * the dynamic values inside it) is materialized in one step instead of
+     * one opcode per element, attribute and text node. The holes keep their
+     * original opcodes; they just run with the builder positioned at them.
+     */
+    let run = extractStaticTree(statements, i);
+
+    if (run) {
+      /**
+       * Two paths for the same run, chosen at runtime.
+       *
+       * When the tree builder can materialize the subtree in one step, the
+       * dynamic values are then filled in at their holes. When it cannot --
+       * rehydration matches against server-rendered nodes and the SSR
+       * serializer interleaves block markers -- the run's original statements
+       * run instead, in their original order. Order is the whole point:
+       * filling holes after the fact would set attributes after their element
+       * was flushed, and would look for a dynamic block's markers after its
+       * enclosing elements had already been closed.
+       */
+      let handle = syntaxContext.program.constants.value(run.tree);
+
+      pushOp(HighLevelBuilderOpcodes.StartLabels);
+      // the jump target must be op1: label offsets are patched relative to
+      // their own slot, and `goto` resolves them against the opcode address
+      pushOp(VM_APPEND_STATIC_TREE_OP, labelOperand('STATIC_TREE_FALLBACK'), handle);
+
+      for (let h = 0; h < run.holeStatements.length; h++) {
+        pushOp(VM_ENTER_HOLE_OP, h);
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- parallel to holes
+        sCompiler.compile(pushOp, statements[run.holeStatements[h]!]!);
+        pushOp(VM_EXIT_HOLE_OP, h);
+      }
+
+      pushOp(VM_JUMP_OP, labelOperand('STATIC_TREE_END'));
+      pushOp(HighLevelBuilderOpcodes.Label, 'STATIC_TREE_FALLBACK');
+
+      for (let s = i; s < i + run.length; s++) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounds checked
+        sCompiler.compile(pushOp, statements[s]!);
+      }
+
+      pushOp(HighLevelBuilderOpcodes.Label, 'STATIC_TREE_END');
+      pushOp(HighLevelBuilderOpcodes.StopLabels);
+
+      i += run.length - 1;
+      continue;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounds checked
+    sCompiler.compile(pushOp, statements[i]!);
   }
 
   let handle = context.encoder.commit(meta.size);