Angular 19 Signal Primitives, linkedSignal State Derivation, and @defer Viewport Guardrails

--- description: Angular 19 Signal Primitives, linkedSignal State Derivation, and @defer Viewport Guardrails - Enforces modern Angular 19 reactive architectures by replacing side-effecting input synchronization with linkedSignal, and mandating non-collapsing placeholders on @defer viewport blocks to eliminate Cumulative Layout Shift (CLS) and deferred chunk loading cascades. globs: src/**/*.ts, src/**/*.html alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/angular-19-signals-defer-guardrails" --- # Angular 19 Signal Primitives, linkedSignal State Derivation, and @defer Viewport Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Using effect() for Input State Mirroring and Unbounded @defer Blocks Lacking Sized Placeholders ## System Constraints You are a Principal Angular Architect enforcing Angular 19 best practices. Mandate the strict use of signal-based primitives (input, output, model, linkedSignal) and enforce high-performance chunking using @defer with prefetch directives and dimensioned placeholders. ## Strict Guidelines - Engineers MUST ALWAYS use linkedSignal() instead of effect() or ngOnChanges when creating writable local state derived from an input() signal. - Engineers MUST NOT create effects solely to copy or synchronize state between signals, as this causes multi-pass change detection cycles and state tearing. - Components using '@defer (on viewport)' MUST ALWAYS specify a '@placeholder' block with fixed or minimum dimensions matching the projected component size to avoid layout shifts (CLS) and immediate false-positive viewport triggers. - Engineers SHOULD pair '@defer (on viewport)' with 'prefetch on idle' or 'prefetch on immediate' to decouple bundle fetching over the network from scroll interaction. - Deferred components referenced within '@defer' blocks MUST BE standalone to allow build-time bundle splitting and dynamic chunk emission. - Components NEVER use legacy @Input() and @Output() decorators; all public APIs must use input(), input.required(), output(), or model(). ## Bad vs Good Implementations ### Signal Input State Synchronization: effect() anti-pattern vs. linkedSignal #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using effect() with allowSignalWrites to synchronize an upstream input to a local signal introduces asynchronous glitches, breaks unidirectional data flow, and forces an extra change detection cycle. ```typescript import { Component, input, signal, effect } from '@angular/core'; @Component({ standalone: true, template: `<input [value]="currentValue()" (input)="onInput($event)" />` }) export class FilterInputComponent { // BAD: Legacy sync pattern leads to secondary change detection cycle and race conditions initialValue = input.required<string>(); currentValue = signal<string>(''); constructor() { effect(() => { this.currentValue.set(this.initialValue()); }, { allowSignalWrites: true }); } onInput(event: Event): void { this.currentValue.set((event.target as HTMLInputElement).value); } } ``` #### Production Standard (Correct) > **Standard**: Angular 19's linkedSignal seamlessly manages dependent writable state, resetting synchronously whenever the upstream input emits without triggering additional render cycles. ```typescript import { Component, input, linkedSignal } from '@angular/core'; @Component({ standalone: true, template: `<input [value]="currentValue()" (input)="currentValue.set($any($event.target).value)" />` }) export class FilterInputComponent { // GOOD: linkedSignal automatically resets when initialValue changes, while remaining locally writable readonly initialValue = input.required<string>(); readonly currentValue = linkedSignal(() => this.initialValue()); } ``` ### Deferred Viewport Loading: Collapsing Placeholder vs. Sized Placeholder with Prefetch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: An inline <span> placeholder without designated height collapses to a near-zero bounding box. When rendered off-screen, it instantly intersects the viewport, defeating the purpose of deferred loading and triggering Cumulative Layout Shift (CLS). ```typescript import { Component } from '@angular/core'; import { HeavyAnalyticsChartComponent } from './analytics-chart.component'; @Component({ standalone: true, imports: [HeavyAnalyticsChartComponent], template: ` <section class="dashboard-section">  @defer (on viewport) { <app-heavy-analytics-chart /> } @placeholder { <span>Loading chart...</span> } </section> ` }) export class DashboardComponent {} ``` #### Production Standard (Correct) > **Standard**: The placeholder reserves exact vertical space (h-[400px]) to prevent layout shifts. 'prefetch on idle' downloads the chunk ahead of time, ensuring instant rendering when scrolled into view. ```typescript import { Component } from '@angular/core'; import { HeavyAnalyticsChartComponent } from './analytics-chart.component'; @Component({ standalone: true, imports: [HeavyAnalyticsChartComponent], template: ` <section class="dashboard-section">  @defer (on viewport; prefetch on idle) { <app-heavy-analytics-chart /> } @placeholder (minimum 250ms) { <div class="h-[400px] w-full animate-pulse rounded-lg bg-slate-100" aria-hidden="true"></div> } @loading (after 100ms; minimum 200ms) { <div class="h-[400px] w-full flex items-center justify-center font-medium text-slate-500">Fetching analytics...</div> } @error { <div class="h-[400px] w-full flex items-center justify-center text-rose-500">Failed to render chart.</div> } </section> ` }) export class DashboardComponent {} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Angular 19 Signal Primitives, linkedSignal State Derivation, and @defer Viewport Guardrails

Angular 19 Signal Primitives, linkedSignal State Derivation, and @defer Viewport Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces modern Angular 19 reactive architectures by replacing side-effecting input synchronization with linkedSignal, and mandating non-collapsing placeholders on @defer viewport blocks to eliminate Cumulative Layout Shift (CLS) and deferred chunk loading cascades. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Using effect() for Input State Mirroring and Unbounded @defer Blocks Lacking Sized Placeholders Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Using effect() for Input State Mirroring and Unbounded @defer Blocks Lacking Sized Placeholders	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS use linkedSignal() instead of effect() or ngOnChanges when creating writable local state derived from an input() signal.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.