Lots of documentation and clarity improvements

packages/@glimmer-workspace/benchmark-env/lib/benchmark/render-benchmark.ts

@@ -1,5 +1,5 @@
 import type {
-  CompileTimeCompilationContext,
+  SetupCompilationContext,
   Dict,
   ResolvedComponentDefinition,
   RuntimeArtifacts,
@@ -15,7 +15,7 @@ import { measureRender } from './util';
 
 export default async function renderBenchmark(
   artifacts: RuntimeArtifacts,
-  context: CompileTimeCompilationContext,
+  context: SetupCompilationContext,
   runtimeResolver: RuntimeResolver,
   component: ResolvedComponentDefinition,
   args: Dict,

packages/@glimmer-workspace/benchmark-env/lib/benchmark/util.ts

@@ -1,7 +1,7 @@
-import type { CompileTimeCompilationContext, CompileTimeComponent } from '@glimmer/interfaces';
+import type { SetupCompilationContext, CompileTimeComponent } from '@glimmer/interfaces';
 import { unwrapHandle } from '@glimmer/debug-util';
 
-export function compileEntry(entry: CompileTimeComponent, context: CompileTimeCompilationContext) {
+export function compileEntry(entry: CompileTimeComponent, context: SetupCompilationContext) {
   return unwrapHandle(entry.compilable!.compile(context));
 }
 

packages/@glimmer-workspace/integration-tests/lib/modes/jit/delegate.ts

@@ -1,6 +1,6 @@
 import type {
   CapturedRenderNode,
-  CompileTimeCompilationContext,
+  SetupCompilationContext,
   Cursor,
   Dict,
   DynamicScope,
@@ -60,7 +60,7 @@ import { TestJitRuntimeResolver } from './resolver';
 
 export interface JitTestDelegateContext {
   runtime: RuntimeContext;
-  program: CompileTimeCompilationContext;
+  program: SetupCompilationContext;
 }
 
 export function JitDelegateContext(

packages/@glimmer/debug/lib/vm/snapshot.ts

@@ -0,0 +1 @@
+export class VmSnapshot {}

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

@@ -12,23 +12,35 @@ import type {
   SimpleText,
 } from './simple.js';
 
-export interface LiveBlock extends Bounds {
+/**
+ * `AppendingBlock` is the interface used by the `ElementBuilder` to keep track of which nodes have
+ * been appended to a block. Ultimately, an `AppendingBlock` is finalized and used as a `FixedBlock`
+ * or `ResettableBlock` during the updating phase.
+ */
+export interface AppendingBlock extends Bounds {
   openElement(element: SimpleElement): void;
   closeElement(): void;
   didAppendNode(node: SimpleNode): void;
   didAppendBounds(bounds: Bounds): void;
   finalize(stack: ElementBuilder): void;
 }
 
-export interface SimpleLiveBlock extends LiveBlock {
-  parentElement(): SimpleElement;
-  firstNode(): SimpleNode;
-  lastNode(): SimpleNode;
-}
-
-export type RemoteLiveBlock = SimpleLiveBlock;
-
-export interface UpdatableBlock extends SimpleLiveBlock {
+/**
+ * A `FixedBlock` is a block that is only rendered once, during initial render. Its *children* may
+ * change during the updating phase, and this may cause its *bounds* to change, but the block itself
+ * remains stable.
+ */
+export interface FixedBlock extends AppendingBlock {}
+
+/**
+ * A `ResettableBlock` can be reset during the updating phase and rendered again.
+ *
+ * This occurs for two reasons:
+ *
+ * 1. The block represents an element in a list, and the element has been removed
+ * 2. The block represents a conditional, and the condition has changed
+ */
+export interface ResettableBlock extends FixedBlock {
   reset(env: Environment): Nullable<SimpleNode>;
 }
 
@@ -37,8 +49,8 @@ export interface DOMStack {
     element: SimpleElement,
     guid: string,
     insertBefore: Maybe<SimpleNode>
-  ): RemoteLiveBlock;
-  popRemoteElement(): RemoteLiveBlock;
+  ): FixedBlock;
+  popRemoteElement(): FixedBlock;
   popElement(): void;
   openElement(tag: string, _operations?: ElementOperations): SimpleElement;
   flushElement(modifiers: Nullable<ModifierInstance[]>): void;
@@ -87,12 +99,12 @@ export interface ElementBuilder extends Cursor, DOMStack, TreeOperations {
   element: SimpleElement;
 
   hasBlocks: boolean;
-  debugBlocks(): LiveBlock[];
+  debugBlocks(): AppendingBlock[];
 
-  pushSimpleBlock(): LiveBlock;
-  pushUpdatableBlock(): UpdatableBlock;
-  pushBlockList(list: Bounds[]): LiveBlock;
-  popBlock(): LiveBlock;
+  pushSimpleBlock(): AppendingBlock;
+  pushUpdatableBlock(): ResettableBlock;
+  pushBlockList(list: Bounds[]): AppendingBlock;
+  popBlock(): AppendingBlock;
 
   didAppendBounds(bounds: Bounds): void;
 }

packages/@glimmer/interfaces/lib/program.d.ts

@@ -56,12 +56,10 @@ export interface RuntimeHeap extends OpcodeHeap {
   sizeof(handle: number): number;
 }
 
-export interface CompileTimeCompilationContext {
+export interface CompilationContext {
   // The offsets to stdlib functions
   readonly stdlib: STDLib;
 
-  readonly createOp: CreateRuntimeOp;
-
   // Interned constants
   readonly constants: JitConstants;
 
@@ -70,6 +68,9 @@ export interface CompileTimeCompilationContext {
 
   // The heap that the program is serializing into
   readonly heap: CompileTimeHeap;
+
+  // Create a runtime op from the heap
+  readonly createOp: CreateRuntimeOp;
 }
 
 /**
@@ -78,7 +79,7 @@ export interface CompileTimeCompilationContext {
  * template when compiling blocks nested inside of it.
  */
 export interface TemplateCompilationContext {
-  readonly program: CompileTimeCompilationContext;
+  readonly program: CompilationContext;
   readonly encoder: Encoder;
   readonly meta: BlockMetadata;
 }
@@ -151,5 +152,5 @@ export type JitConstants = CompileTimeConstants & ResolutionTimeConstants & Runt
 
 export interface CompileTimeArtifacts {
   heap: CompileTimeHeap;
-  constants: CompileTimeConstants & ResolutionTimeConstants;
+  constants: JitConstants;
 }

packages/@glimmer/interfaces/lib/runtime.d.ts

@@ -3,8 +3,10 @@ export * from './runtime/debug-render-tree.js';
 export * from './runtime/element.js';
 export * from './runtime/environment.js';
 export * from './runtime/helper.js';
+export * from './runtime/local-debug.js';
 export * from './runtime/modifier.js';
 export * from './runtime/owner.js';
 export * from './runtime/render.js';
 export * from './runtime/runtime.js';
 export * from './runtime/scope.js';
+export * from './runtime/vm-state.js';

packages/@glimmer/interfaces/lib/runtime/local-debug.d.ts

@@ -0,0 +1,66 @@
+import type { JitConstants, RuntimeHeap } from '../program.js';
+import type { Stack } from '../stack.js';
+import type { BlockMetadata } from '../template.js';
+import type { DynamicScope, Scope } from './scope.js';
+import type { UpdatingBlockOpcode, UpdatingOpcode } from './vm.js';
+import type { $fp, $pc, $ra, $s0, $s1, $sp, $t0, $t1, $v0 } from './vm-state.js';
+
+export interface DebugRegisters extends Array<unknown> {
+  [$pc]: number;
+  [$ra]: number;
+  [$fp]: number;
+  [$sp]: number;
+  [$s0]: unknown;
+  [$s1]: unknown;
+  [$t0]: unknown;
+  [$t1]: unknown;
+  [$v0]: unknown;
+}
+
+/**
+ * All parts of `DebugVmState` are _snapshots_. They will not change if the piece of VM state that
+ * they reference changes.
+ */
+export interface DebugVmState {
+  readonly stacks: DebugStacks;
+  readonly destroyableStack: object[];
+  readonly constants: JitConstants;
+
+  /**
+   * These values can change for each opcode
+   */
+  readonly state: {
+    readonly stack: unknown[];
+    readonly registers: DebugRegisters;
+  };
+
+  /**
+   * These values are the same for the entire program
+   */
+  readonly program: {
+    readonly heap: RuntimeHeap;
+  };
+
+  /**
+   * These values change whenever the VM moves to a new block
+   */
+  readonly block: {
+    readonly metadata: BlockMetadata | null;
+  };
+}
+
+export interface DebugStacks {
+  scope: Stack<Scope>;
+  dynamicScope: Stack<DynamicScope>;
+  updating: Stack<UpdatingOpcode[]>;
+  cache: Stack<UpdatingOpcode>;
+  list: Stack<UpdatingBlockOpcode>;
+}
+
+// class Stacks {
+//   readonly scope = new Stack<Scope>();
+//   readonly dynamicScope = new Stack<DynamicScope>();
+//   readonly updating = new Stack<UpdatingOpcode[]>();
+//   readonly cache = new Stack<JumpIfNotModifiedOpcode>();
+//   readonly list = new Stack<ListBlockOpcode>();
+// }

packages/@glimmer/interfaces/lib/runtime/scope.d.ts

@@ -11,28 +11,29 @@ export type BlockValue = ScopeBlock[0 | 1 | 2];
 export type ScopeSlot = Reference | ScopeBlock | null;
 
 export interface Scope {
+  /**
+   * A single program can mix and match multiple owners. This can happen component is curried from a
+   * template with one owner and then rendered in a second owner.
+   *
+   * Note: Owners can change when new root scopes are created (including when rendering a
+   * component), but not in child scopes.
+   */
+  readonly owner: Owner;
   // for debug only
   readonly slots: Array<ScopeSlot>;
-  readonly owner: Owner;
 
   getSelf(): Reference;
   getSymbol(symbol: number): Reference;
   getBlock(symbol: number): Nullable<ScopeBlock>;
   getEvalScope(): Nullable<Dict<ScopeSlot>>;
-  getPartialMap(): Nullable<Dict<Reference>>;
   bind(symbol: number, value: ScopeSlot): void;
   bindSelf(self: Reference): void;
   bindSymbol(symbol: number, value: Reference): void;
   bindBlock(symbol: number, value: Nullable<ScopeBlock>): void;
   bindEvalScope(map: Nullable<Dict<ScopeSlot>>): void;
-  bindPartialMap(map: Dict<Reference>): void;
   child(): Scope;
 }
 
-export interface PartialScope extends Scope {
-  bindEvalScope(scope: Nullable<Dict<ScopeSlot>>): void;
-}
-
 export interface DynamicScope {
   get(key: string): Reference<unknown>;
   set(key: string, reference: Reference<unknown>): Reference<unknown>;

packages/@glimmer/interfaces/lib/runtime/vm-state.d.ts

@@ -0,0 +1,52 @@
+export interface SyscallRegisters extends Array<unknown> {
+  [$pc]: null;
+  [$ra]: null;
+  [$fp]: null;
+  [$sp]: null;
+  [$s0]: unknown;
+  [$s1]: unknown;
+  [$t0]: unknown;
+  [$t1]: unknown;
+  [$v0]: unknown;
+}
+
+/**
+ * Registers
+ *
+ * For the most part, these follows MIPS naming conventions, however the
+ * register numbers are different.
+ */
+
+// $0 or $pc (program counter): pointer into `program` for the next insturction; -1 means exit
+export type $pc = 0;
+declare const $pc: $pc;
+// $1 or $ra (return address): pointer into `program` for the return
+export type $ra = 1;
+declare const $ra: $ra;
+// $2 or $fp (frame pointer): pointer into the `evalStack` for the base of the stack
+export type $fp = 2;
+declare const $fp: $fp;
+// $3 or $sp (stack pointer): pointer into the `evalStack` for the top of the stack
+export type $sp = 3;
+declare const $sp: $sp;
+// $4-$5 or $s0-$s1 (saved): callee saved general-purpose registers
+export type $s0 = 4;
+declare const $s0: $s0;
+export type $s1 = 5;
+declare const $s1: $s1;
+// $6-$7 or $t0-$t1 (temporaries): caller saved general-purpose registers
+export type $t0 = 6;
+declare const $t0: $t0;
+export type $t1 = 7;
+declare const $t1: $t1;
+// $8 or $v0 (return value)
+export type $v0 = 8;
+declare const $v0: $v0;
+
+export type MachineRegister = $pc | $ra | $fp | $sp;
+
+export type SavedRegister = $s0 | $s1;
+export type TemporaryRegister = $t0 | $t1;
+
+export type Register = MachineRegister | SavedRegister | TemporaryRegister | $v0;
+export type SyscallRegister = SavedRegister | TemporaryRegister | $v0;

packages/@glimmer/interfaces/lib/runtime/vm.d.ts

@@ -1,23 +1,7 @@
-import type { Destroyable } from '../core.js';
+import type { Bounds } from '../dom/bounds.js';
 import type { GlimmerTreeChanges } from '../dom/changes.js';
-import type { Reference } from '../references.js';
 import type { Environment } from './environment.js';
-import type { Owner } from './owner.js';
 import type { ExceptionHandler } from './render.js';
-import type { DynamicScope } from './scope.js';
-/**
- * This is used in the Glimmer Embedding API. In particular, embeddings
- * provide helpers through the `CompileTimeLookup` interface, and the
- * helpers they provide implement the `Helper` interface, which is a
- * function that takes a `VM` as a parameter.
- */
-export interface VM<O extends Owner = Owner> {
-  env: Environment;
-  dynamicScope(): DynamicScope;
-  getOwner(): O;
-  getSelf(): Reference;
-  associateDestroyable(child: Destroyable): void;
-}
 
 export interface UpdatingVM {
   env: Environment;
@@ -33,3 +17,5 @@ export interface UpdatingVM {
 export interface UpdatingOpcode {
   evaluate(vm: UpdatingVM): void;
 }
+
+export interface UpdatingBlockOpcode extends UpdatingOpcode, Bounds {}

packages/@glimmer/interfaces/lib/stack.d.ts

@@ -9,4 +9,9 @@ export interface Stack<T> {
   nth(from: number): Nullable<T>;
   isEmpty(): boolean;
   toArray(): T[];
+
+  /**
+   * For debugging
+   */
+  snapshot(): T[];
 }

packages/@glimmer/interfaces/lib/template.d.ts

@@ -3,7 +3,7 @@ import type { EncoderError } from './compile/encoder.js';
 import type { Operand, SerializedInlineBlock, SerializedTemplateBlock } from './compile/index.js';
 import type { Nullable } from './core.js';
 import type { InternalComponentCapabilities } from './managers/internal/component.js';
-import type { CompileTimeCompilationContext, ConstantPool, SerializedHeap } from './program.js';
+import type { SetupCompilationContext, ConstantPool, SerializedHeap } from './program.js';
 import type { Owner } from './runtime.js';
 import type { BlockSymbolTable, ProgramSymbolTable, SymbolTable } from './tier1/symbol-table.js';
 
@@ -101,7 +101,7 @@ export interface CompilerArtifacts {
 export interface CompilableTemplate<S extends SymbolTable = SymbolTable> {
   symbolTable: S;
   meta: BlockMetadata;
-  compile(context: CompileTimeCompilationContext): HandleResult;
+  compile(context: SetupCompilationContext): HandleResult;
 }
 
 export interface BlockMetadata {