Ember.js Framework

Glimmer is a low-level, high-performance rendering pipeline designed to build a "live" DOM from a superset of the Handlebars templating language. It is optimized for cheap updates when underlying data changes.

Key features include:

• Handlebars Support: Includes standard features like helpers.
• Components: Built-in support for a powerful component primitive.
• Low-level Hooks: Provides hooks that host environments can use to implement higher-level user-facing features.

The repository is organized as a pnpm workspace. Package locations are defined in pnpm-workspace.yaml.

Package Types

• Code Packages: Located in packages/. They follow a standard structure with index.{ext} as the entry point and lib/**/*.{ext} for supporting source files.
• @glimmer/* Packages: Located in packages/@glimmer/. These are intended for consumers of the Glimmer VM. Some are published to NPM, while others marked with "private": true are inlined into published packages during the build process.
• @glimmer-workspace/* Packages: Located in packages/@glimmer-workspace/. These contain internal development tooling and are not published.
• Test Packages: Located in test/ (as @glimmer-test/* scope) or within the package directory itself.

The Glimmer Reactivity System is a tag-based validation system designed to provide a reliable and consistent reactive programming model. It manages how data changes propagate through the application to ensure UI updates are batched and coherent.

To master the reactivity system, you should study its core components:

• Tag Composition: The formal semantics of how tags are composed to validate state.
• Fundamental Laws of Reactivity: The rules that all reactive abstractions must follow to ensure consistency.
• System Phases: The execution model consisting of _action_, _render_, and _idle_ phases, which allows for batched UI updates.
• Reactive Abstractions: The practical implementations of reactive logic that satisfy the reactivity laws.
• Autotracked Rendering: The interplay between the rendering engine and the autotracking mechanism.

A Reference is a stable object representing the result of a pure (side-effect-free) computation. While the underlying result of the computation might change over time, the Reference object itself remains stable.

Glimmer uses references to represent values in templates so they can be efficiently shared across multiple components and updated efficiently when the underlying value changes.

An element modifier is a special type of helper used in the attribute position of an HTML element. Unlike regular helpers that return values to be inserted into the DOM (as text or attributes), modifiers are used to perform imperative changes to a DOM element directly.

Common use cases include binding DOM events using an on modifier.

<button {{on "click" didClick}}>Click me!</button>

A Reference is the core primitive of the Glimmer runtime. It is an abstract data type representing a stable object that holds the result of a pure (side-effect-free) computation. While the result of the computation can change over time, the reference itself remains stable.

Key characteristics:

• Pull-based: Unlike Functional Reactive Programming (FRP) libraries (like RxJS) that use push-based notifications or subscriptions, Glimmer uses a pull-based system. You request the value when needed.
• No Subscriptions: There is no notion of subscribing to changes or receiving notifications; you simply call .value() to get the current state.
• Variable Bindings as First-Class Values: It allows you to pass variable bindings by reference rather than just passing the current value.

interface Reference<T> {
  value(): T;
}

The constant pool is a data structure containing arrays of JavaScript values that are referred to by a handle (an integer ID). This pool is produced during compilation and serialized to JavaScript for use at runtime.

Its primary purpose is string interning: instead of repeating long strings (like tag names) multiple times in the bytecode, the string is stored once in the pool, and the bytecode uses the integer handle to reference it. This significantly reduces the size of compiled templates.

A Layout refers specifically to a component's own template. This term is used to distinguish the component's internal template from the template of the content passed into it (the block).

For example, if a Wrapper component has a template containing {{yield}}, that template is the layout template.

<div class="wrapper">{{yield}}</div>

The Glimmer compiler follows a multi-step process to transform templates into executable code:

1. Abstract Syntax Tree (AST): The Handlebars parser converts source code into an AST, representing the template structure.
2. Intermediate Representation (IR): The compiler transforms the AST into an IR. The IR is closer to the final output and allows for optimization passes.
3. Bytecode: The final stage where the IR is transformed into a binary encoding of instructions (Opcodes). This bytecode is optimized for efficient evaluation by the Glimmer Virtual Machine (VM).