reference-core

---
name: reference-core
description: Explains the mental model and architecture of the code under `packages/core`. You MUST use this skill any time you plan to work with code in `packages/core`
---

# Angular Core (`packages/core`) Mental Model

This document outlines the architecture and mental model for `packages/core`, the heart of the Angular framework.

## 1. High-Level Architecture

`packages/core` contains the runtime logic for Angular. Its primary responsibilities are:

1.  **Rendering (Ivy/Render3)**: Transforming templates into DOM updates.
2.  **Dependency Injection (DI)**: Managing object creation and lifetime.
3.  **Change Detection**: Synchronizing the model with the view.
4.  **Reactivity**: Signals and Zone.js integration.

## 2. Rendering Engine (Ivy / Render3)

The rendering engine (located in `packages/core/src/render3`) uses an **instruction-based** approach.

### Key Concepts

- **Instructions**: The Angular compiler transforms templates into a sequence of instruction calls (e.g., `ɵɵelementStart`, `ɵɵtext`, `ɵɵproperty`). These instructions are executed at runtime to create and update the view.
  - _Location_: `packages/core/src/render3/instructions`

- **LView (Logical View)**: An array containing the _state_ of a specific view instance. It holds:
  - DOM nodes (`RElement`, `RText`).
  - Binding values (for change detection).
  - Directive/Component instances.
  - _Context_: `packages/core/src/render3/interfaces/view.ts`

- **TView (Template View)**: An object describing the _static structure_ of a view; its parallel array is `TView.data`. It is shared across all instances (`LView`s) of the same component/template. It holds:
  - Property names for bindings.
  - Node relationship information.
  - Compiled directive definitions.
  - _Context_: `packages/core/src/render3/interfaces/view.ts`

- **Memory Layout**: `LView` and `TView.data` are parallel arrays. Index `i` in `LView` corresponds to metadata at index `i` in `TView.data`.
  - `HEADER`: Fixed size, contains context (Parent, Host, etc.).
  - `DECLS`: Static nodes (elements, text, pipes).
  - `VARS`: Binding values.
  - `EXPANDO`: Dynamic data (host bindings, injectors).

### The Render Cycle

1.  **Creation Mode**: Instructions create DOM nodes and store them in `LView`.
2.  **Update Mode**: Instructions check current values against previous values stored in `LView`. If changed, they update the DOM.

## 3. Dependency Injection (DI)

DI in Angular is hierarchical and split into two systems that interact:

### Module Injector (`R3Injector`)

- Configured via `@NgModule.providers` or `providedIn: 'root'`.
- Stored in a hierarchy of `R3Injector` instances.
- _Location_: `packages/core/src/di/r3_injector.ts`

### Node Injector

- Configured via `@Component.providers` or `@Directive.providers`.
- **Not a class**, but a data structure embedded in the `LView` ("Expando" section).
- Uses **Bloom Filters** (`TView.data`) to quickly check if a token is present at a specific node index before traversing up the tree.
- Resolves tokens starting from the current node, walking up the view tree (Element Injector hierarchy), and falling back to the Module Injector if not found.

## 4. Change Detection

- **Dirty Checking**: Angular checks if values bound in templates have changed.
- **Strategies**:
  - `OnPush`: The default. Checks when inputs change, events fire, template signals update, or the view is explicitly marked for checking.
  - `Eager`: Checks whenever the change detection traversal reaches the component. (`Default` is the deprecated alias for `Eager`.)
- **Signals**: The new reactivity primitive. Signals notify the scheduler when they change, potentially allowing for fine-grained updates (Zoneless).

## 5. Key Directories to Know

- `src/render3`: The Ivy rendering engine.
  - `instructions`: The runtime instructions called by compiled code.
  - `interfaces`: `LView`, `TView`, `TNode` definitions.
- `src/di`: Dependency injection system.
- `src/change_detection`: Change detection logic.
- `src/zone`: Zone.js integration.
- `src/render3/reactivity`: Signals implementation (`signal`, `computed`, `effect`), built on the reactive graph in `primitives/signals`.

## 6. Conventions & Gotchas

- **Prefixes**: Private/Internal exports often start with `ɵ`.
- **Global State**: Ivy relies heavily on global state (e.g., `getLView()`) during instruction execution to avoid passing context arguments everywhere. This is for performance and code size.
- **Performance**: The code is highly optimized for performance and memory. You will see arrays used instead of objects, bitmasks, and manual memory management patterns. **Respect these patterns.**

## 7. How to Modify Core

1.  **Understand the Instruction**: If modifying runtime behavior, find the corresponding instruction in `src/render3/instructions`.
2.  **Check `LView`/`TView` Impact**: If adding state, understand where it fits in the `LView` array.
3.  **Tests**: Core has extensive tests. Run them using Bazel.