{{ config.isEnabled }}`, changeDetection: ChangeDetectionStrategy.OnPush }) export class DashboardComponent { @Input() set systemConfig(value: SystemConfig) { if (value !== this._config) { this._config = value; } } private _config!: SystemConfig; }

### Architecture Decisions and Rationale

- **Why freeze the initial state?** `Object.freeze` prevents accidental property mutation at the first level, enforcing immutability by contract. This catches bugs during development rather than at runtime.
- **Why spread before freezing?** The spread operator creates a shallow copy in the heap, ensuring the wrapper owns its reference. This prevents external code from holding a mutable pointer to the same object.
- **Why avoid deep freezing?** Deep freezing requires recursive traversal, which degrades performance and breaks with circular references or non-serializable values. Shallow immutability combined with reference replacement is more efficient and aligns with framework change detection.
- **Why pair with `OnPush`?** `OnPush` skips change detection cycles unless input references change. By guaranteeing new references on updates, you reduce CPU overhead and eliminate unnecessary DOM reconciliation.

## Pitfall Guide

### 1. The `const` Illusion
**Explanation:** Developers assume `const` creates immutable data. In reality, `const` only locks the stack slot, preventing reassignment. The heap object remains fully mutable.
**Fix:** Treat `const` as a reference-locking mechanism, not a data-locking mechanism. Use `Object.freeze` for shallow immutability, or enforce immutable update patterns at the architecture level.

### 2. Shallow Freeze Blind Spot
**Explanation:** `Object.freeze` only protects the first level of an object. Nested objects, arrays, and class instances remain mutable, leading to silent state corruption.
**Fix:** Avoid relying on `freeze` for complex nested structures. Instead, use immutable update patterns that replace entire branches: `state = { ...state, nested: { ...state.nested, key: newValue } }`.

### 3. Accidental Reference Sharing
**Explanation:** Passing the same object reference to multiple components or services creates hidden coupling. Mutating the object in one location silently affects all consumers.
**Fix:** Clone objects before passing them across component boundaries. Use structural copying or serialization/deserialization for cross-boundary data transfer.

### 4. GC Misconception
**Explanation:** Developers expect memory to be freed immediately when variables go out of scope. JavaScript's garbage collector operates asynchronously and only reclaims memory when no reachable references exist.
**Fix:** Explicitly nullify references in long-lived objects, unsubscribe from observables, and avoid storing DOM nodes or large payloads in global state. Use browser DevTools Memory tab to verify heap snapshots.

### 5. Change Detection Bypass
**Explanation:** Mutating an object's properties instead of replacing the reference causes `OnPush` components to miss updates. The framework sees the same address and skips reconciliation.
**Fix:** Always replace references on state changes. Use immutable update utilities or state management libraries that enforce reference replacement by default.

### 6. Array Mutation Masquerading
**Explanation:** Methods like `push()`, `splice()`, and `sort()` modify arrays in place. The reference address remains unchanged, breaking change detection and causing stale UI.
**Fix:** Use non-mutating array methods: `[...arr, newItem]`, `arr.filter()`, `arr.map()`, or `Array.from()`. These create new heap allocations with updated contents.

### 7. Equality Check Confusion
**Explanation:** Using `===` to compare object contents returns `false` even when properties match, because the operator compares addresses. Developers often write custom deep equality checks unnecessarily.
**Fix:** Reserve `===` for reference tracking. Use structural comparison libraries (e.g., `lodash.isEqual`) only when content comparison is explicitly required. Prefer reference equality for performance-critical paths.

## Production Bundle

### Action Checklist
- [ ] Audit state mutations: Replace all in-place object/array modifications with immutable update patterns.
- [ ] Enforce reference boundaries: Clone objects before passing them across component or service boundaries.
- [ ] Align with change detection: Configure `OnPush` strategy and verify that every state update produces a new reference.
- [ ] Validate freeze usage: Apply `Object.freeze` only to flat configuration objects; avoid deep freezing complex hierarchies.
- [ ] Profile memory allocation: Use Chrome DevTools Memory tab to capture heap snapshots before and after state updates.
- [ ] Eliminate lingering references: Nullify subscriptions, clear caches, and remove event listeners when components destroy.
- [ ] Standardize equality checks: Use `===` for reference tracking and reserve deep equality for explicit validation scenarios.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Flat configuration data | `const` + `Object.freeze` | Prevents accidental mutation; minimal overhead | Negligible |
| Nested entity updates | Immutable spread pattern | Guarantees new reference; aligns with `OnPush` | Low (shallow copy) |
| Cross-component data transfer | Structural clone or serialization | Breaks reference coupling; prevents silent mutations | Moderate (copy overhead) |
| Large list rendering | Reference replacement + trackBy | Minimizes DOM reconciliation; leverages framework diffing | Low (reference check) |
| Long-lived service state | Explicit nullification + weak references | Prevents heap accumulation; reduces GC pressure | Low (manual cleanup) |

### Configuration Template

```typescript
// state-manager.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class AppStateManager {
  private registry = new Map<string, object>();

  public register<T extends object>(key: string, initial: T): void {
    this.registry.set(key, Object.freeze({ ...initial }));
  }

  public get<T extends object>(key: string): Readonly<T> {
    const data = this.registry.get(key);
    if (!data) throw new Error(`State key "${key}" not registered`);
    return data as Readonly<T>;
  }

  public update<T extends object, U extends Partial<T>>(key: string, patch: U): void {
    const current = this.get<T>(key);
    const next = Object.freeze({ ...current, ...patch });
    this.registry.set(key, next);
  }

  public remove(key: string): void {
    this.registry.delete(key);
  }
}

Quick Start Guide

1. Install DevTools Profiling: Open Chrome DevTools → Memory tab → select "Heap snapshot". Capture a baseline before implementing changes.
2. Replace Mutations: Search your codebase for .push(), .splice(), direct property assignment on objects, and Array.sort(). Replace with immutable equivalents.
3. Configure Change Detection: Add changeDetection: ChangeDetectionStrategy.OnPush to leaf components. Verify that state updates trigger re-renders by logging input setter calls.
4. Validate References: Inject AppStateManager into a test component. Call register(), update(), and verify that get() returns a new reference after each update. Compare heap snapshots to confirm no memory accumulation.
5. Enforce in CI: Add a linting rule or custom ESLint plugin to flag direct object mutations and uncloned cross-boundary assignments. Automate reference validation in unit tests.