angular-scan 0.0.1

package/README.md

@@ -0,0 +1,129 @@
+# angular-scan
+
+Automatically detects and highlights Angular components that are re-rendering — the Angular equivalent of [react-scan](https://github.com/aidenybai/react-scan).
+
+- **Yellow flash** — component was checked and its DOM changed (normal re-render)
+- **Red flash** — component was checked but its DOM did **not** change (unnecessary render)
+- **Counter badge** — cumulative render count on each component host element
+- **Toolbar HUD** — floating panel with total checks, wasted renders, and a per-component inspector
+
+Zero overhead in production — the entire library is tree-shaken when `isDevMode()` returns `false`.
+
+Works with both **zone.js** and **zoneless** Angular applications.
+
+---
+
+## Installation
+
+```bash
+npm install angular-scan --save-dev
+```
+
+---
+
+## Usage
+
+### Provider-based (recommended)
+
+Add `provideAngularScan()` to your application providers:
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAngularScan } from 'angular-scan';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAngularScan(),
+  ],
+};
+```
+
+### Imperative API
+
+For micro-frontends or apps where you can't modify providers, call `scan()` before `bootstrapApplication`:
+
+```ts
+// main.ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { scan } from 'angular-scan';
+import { AppComponent } from './app/app.component';
+import { appConfig } from './app/app.config';
+
+scan();
+bootstrapApplication(AppComponent, appConfig);
+```
+
+`scan()` returns a teardown function:
+
+```ts
+const stop = scan();
+// later...
+stop(); // removes overlay and stops tracking
+```
+
+---
+
+## Options
+
+```ts
+provideAngularScan({
+  enabled: true,         // set false to disable entirely (default: true)
+  flashDurationMs: 500,  // how long the flash animation lasts in ms (default: 500)
+  showBadges: true,      // show render count badges on host elements (default: true)
+  showToolbar: true,     // show the floating toolbar HUD (default: true)
+});
+```
+
+The same options are accepted by `scan()`.
+
+---
+
+## How it works
+
+Angular exposes `window.ng.ɵsetProfiler()` in development mode — the same hook used by Angular DevTools in Chrome. `angular-scan` registers a profiler callback to intercept every change detection cycle:
+
+1. **`ChangeDetectionStart`** — a `MutationObserver` begins recording all DOM mutations
+2. **`ChangeDetectionSyncStart/End`** — gates which `TemplateUpdateStart` events count as real renders (excludes the dev-mode `checkNoChanges` pass)
+3. **`TemplateUpdateStart`** — the exact component instance being checked is captured
+4. **`ChangeDetectionEnd`** — `MutationObserver.takeRecords()` flushes synchronously; each captured instance is mapped to its host element via `ng.getHostElement()`; components whose subtree had DOM mutations are marked as **renders**, the rest as **unnecessary renders**
+
+All Angular signal writes are deferred via `queueMicrotask()` to avoid triggering a new CD cycle from inside the profiler callback.
+
+The canvas overlay (`position: fixed`, full viewport, `pointer-events: none`) uses a `requestAnimationFrame` loop to draw and fade rectangles over component host elements. The toolbar is created via `createComponent()` and attached to `ApplicationRef` outside the normal component tree, so its own renders are excluded from tracking.
+
+---
+
+## Interpreting the output
+
+| Signal | Meaning | Common cause |
+|--------|---------|-------------|
+| Yellow flash | Component re-rendered (DOM changed) | Normal update — signal/input changed |
+| Red flash | Component checked but DOM unchanged | Parent uses `Default` CD strategy; child is `OnPush` with no changed inputs |
+| High wasted count on a component | It's being checked unnecessarily on every tick | Wrap it in `OnPush`; ensure parent isn't `Default` CD |
+| Counter badge turns red | More unnecessary than necessary renders | Same as above — component is `OnPush` but still gets walked |
+
+---
+
+## Requirements
+
+- Angular **≥ 20**
+- Must be used in **development mode** (`ng serve` / `ng build --configuration development`)
+- The Angular debug APIs (`window.ng`) are only available in dev mode — `angular-scan` is silently disabled otherwise
+
+---
+
+## Building
+
+```bash
+ng build angular-scan
+```
+
+Output is placed in `dist/angular-scan`.
+
+## Publishing
+
+```bash
+cd dist/angular-scan
+npm publish
+```

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/angular-scan",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "angular-scan",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": ">=20.0.0",
+    "@angular/core": ">=20.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false
+}

package/src/lib/angular-scan.spec.ts

@@ -0,0 +1,22 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { AngularScan } from './angular-scan';
+
+describe('AngularScan', () => {
+  let component: AngularScan;
+  let fixture: ComponentFixture<AngularScan>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [AngularScan],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(AngularScan);
+    component = fixture.componentInstance;
+    await fixture.whenStable();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/src/lib/angular-scan.ts

@@ -0,0 +1,9 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'ngscan-angular-scan',
+  imports: [],
+  template: ` <p>angular-scan works!</p> `,
+  styles: ``,
+})
+export class AngularScan {}

package/src/lib/component-tracker.ts

@@ -0,0 +1,80 @@
+import { Injectable, signal } from '@angular/core';
+import type { ComponentStats, RenderKind } from './types';
+
+@Injectable({ providedIn: 'root' })
+export class ComponentTracker {
+  // WeakMap: component instance → stats. GC-safe: entries are freed when
+  // the component instance is garbage collected after destruction.
+  private readonly byInstance = new WeakMap<object, ComponentStats>();
+
+  // Strong map: host element → component instance. Used for mutation-to-component
+  // lookup. Entries must be manually removed when components are destroyed.
+  private readonly byElement = new Map<Element, object>();
+
+  private readonly _totalRenders = signal(0);
+  private readonly _totalUnnecessary = signal(0);
+  private readonly _trackedComponents = signal<readonly ComponentStats[]>([]);
+
+  readonly totalRenders = this._totalRenders.asReadonly();
+  readonly totalUnnecessary = this._totalUnnecessary.asReadonly();
+  readonly trackedComponents = this._trackedComponents.asReadonly();
+
+  /**
+   * Record a render event for a component.
+   * NOTE: Must be called outside of a profiler callback to avoid triggering CD.
+   * Use queueMicrotask() to defer calls from profiler events.
+   */
+  recordRender(instance: object, hostElement: Element, kind: RenderKind): ComponentStats {
+    let stats = this.byInstance.get(instance);
+
+    if (!stats) {
+      stats = {
+        componentName: instance.constructor.name,
+        hostElement,
+        totalRenders: 0,
+        unnecessaryRenders: 0,
+        lastRenderKind: kind,
+        lastRenderTimestamp: 0,
+      };
+      this.byInstance.set(instance, stats);
+      this.byElement.set(hostElement, instance);
+    }
+
+    stats.totalRenders++;
+    stats.lastRenderKind = kind;
+    stats.lastRenderTimestamp = Date.now();
+
+    if (kind === 'unnecessary') {
+      stats.unnecessaryRenders++;
+      this._totalUnnecessary.update(n => n + 1);
+    }
+
+    this._totalRenders.update(n => n + 1);
+    return stats;
+  }
+
+  /**
+   * Rebuild the trackedComponents signal from the current element map.
+   * Call once per tick after all recordRender() calls.
+   */
+  snapshotTrackedComponents(): void {
+    const list: ComponentStats[] = [];
+    for (const [, instance] of this.byElement) {
+      const stats = this.byInstance.get(instance);
+      if (stats) list.push(stats);
+    }
+    this._trackedComponents.set(list);
+  }
+
+  /** Remove a component from tracking (call when its host element is removed). */
+  unregister(el: Element): void {
+    this.byElement.delete(el);
+  }
+
+  reset(): void {
+    this.byElement.clear();
+    this._totalRenders.set(0);
+    this._totalUnnecessary.set(0);
+    this._trackedComponents.set([]);
+  }
+}

package/src/lib/ng-debug.ts

@@ -0,0 +1,23 @@
+import type { NgDebugApi } from './types';
+
+/**
+ * Returns the Angular debug API (window.ng) if available.
+ * Returns null in SSR, production builds, or when Angular DevTools APIs are absent.
+ *
+ * Safe to call before Angular is bootstrapped — the API is attached to window
+ * by Angular's dev mode runtime.
+ */
+export function getNgDebugApi(): NgDebugApi | null {
+  if (typeof window === 'undefined') return null;
+
+  const ng = (window as unknown as Record<string, unknown>)['ng'];
+  if (!ng || typeof ng !== 'object') return null;
+
+  const api = ng as Partial<NgDebugApi>;
+
+  // ɵsetProfiler is the sentinel for dev mode — absent in production builds
+  if (typeof api.ɵsetProfiler !== 'function') return null;
+  if (typeof api.getHostElement !== 'function') return null;
+
+  return api as NgDebugApi;
+}

package/src/lib/overlay/canvas-overlay.ts

@@ -0,0 +1,121 @@
+import type { RenderKind } from '../types';
+
+interface FlashRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  kind: RenderKind;
+  startTime: number;
+  durationMs: number;
+}
+
+// rgb(...) strings for fill and stroke
+const RENDER_COLOR = '255, 200, 0';       // yellow — normal re-render
+const UNNECESSARY_COLOR = '255, 60, 60';  // red — unnecessary render
+
+export class CanvasOverlay {
+  private canvas: HTMLCanvasElement | null = null;
+  private ctx: CanvasRenderingContext2D | null = null;
+  private rects: FlashRect[] = [];
+  private rafId = 0;
+  private attached = false;
+
+  attach(doc: Document): void {
+    if (this.attached) return;
+
+    const canvas = doc.createElement('canvas');
+    canvas.setAttribute('aria-hidden', 'true');
+    canvas.setAttribute('role', 'presentation');
+    canvas.style.cssText = [
+      'position:fixed',
+      'top:0',
+      'left:0',
+      'width:100%',
+      'height:100%',
+      'pointer-events:none',
+      `z-index:2147483646`,
+    ].join(';');
+
+    doc.body.appendChild(canvas);
+    this.canvas = canvas;
+    this.ctx = canvas.getContext('2d');
+    this.attached = true;
+
+    this.resize();
+    window.addEventListener('resize', this.onResize);
+
+    this.scheduleFrame();
+  }
+
+  detach(): void {
+    if (!this.attached) return;
+    this.attached = false;
+    cancelAnimationFrame(this.rafId);
+    window.removeEventListener('resize', this.onResize);
+    this.canvas?.remove();
+    this.canvas = null;
+    this.ctx = null;
+    this.rects = [];
+  }
+
+  /** Queue a flash animation over an element's bounding rect. */
+  flash(element: Element, kind: RenderKind, durationMs: number): void {
+    if (!this.attached) return;
+
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return;
+
+    this.rects.push({
+      x: rect.left,
+      y: rect.top,
+      width: rect.width,
+      height: rect.height,
+      kind,
+      startTime: performance.now(),
+      durationMs,
+    });
+  }
+
+  private readonly onResize = (): void => this.resize();
+
+  private resize(): void {
+    if (!this.canvas) return;
+    this.canvas.width = window.innerWidth;
+    this.canvas.height = window.innerHeight;
+  }
+
+  private scheduleFrame(): void {
+    if (!this.attached) return;
+    this.rafId = requestAnimationFrame(this.drawFrame);
+  }
+
+  private readonly drawFrame = (now: number): void => {
+    if (!this.ctx || !this.canvas || !this.attached) return;
+
+    this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+
+    // Decay alphas and remove expired rects
+    this.rects = this.rects.filter(r => {
+      const elapsed = now - r.startTime;
+      return elapsed < r.durationMs;
+    });
+
+    for (const r of this.rects) {
+      const elapsed = now - r.startTime;
+      const alpha = Math.max(0, 1 - elapsed / r.durationMs);
+      const color = r.kind === 'render' ? RENDER_COLOR : UNNECESSARY_COLOR;
+
+      // Semi-transparent fill
+      this.ctx!.fillStyle = `rgba(${color}, ${alpha * 0.1})`;
+      this.ctx!.fillRect(r.x, r.y, r.width, r.height);
+
+      // Solid border
+      this.ctx!.strokeStyle = `rgba(${color}, ${alpha * 0.9})`;
+      this.ctx!.lineWidth = 2;
+      this.ctx!.strokeRect(r.x + 1, r.y + 1, r.width - 2, r.height - 2);
+    }
+
+    this.scheduleFrame();
+  };
+}

package/src/lib/overlay/overlay.service.ts

@@ -0,0 +1,85 @@
+import { Injectable, inject, isDevMode, DOCUMENT, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { CanvasOverlay } from './canvas-overlay';
+import { ANGULAR_SCAN_OPTIONS } from '../tokens';
+import type { ComponentStats } from '../types';
+
+@Injectable({ providedIn: 'root' })
+export class OverlayService {
+  private readonly document = inject(DOCUMENT);
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly options = inject(ANGULAR_SCAN_OPTIONS);
+  private readonly canvas = new CanvasOverlay();
+
+  // Badge elements keyed by host element
+  private readonly badges = new Map<Element, HTMLElement>();
+
+  initialize(): void {
+    if (!isDevMode()) return;
+    if (!isPlatformBrowser(this.platformId)) return;
+    if (this.options.enabled === false) return;
+
+    this.canvas.attach(this.document);
+  }
+
+  destroy(): void {
+    this.canvas.detach();
+    for (const badge of this.badges.values()) badge.remove();
+    this.badges.clear();
+  }
+
+  onComponentChecked(stats: ComponentStats): void {
+    const durationMs = this.options.flashDurationMs ?? 500;
+    this.canvas.flash(stats.hostElement, stats.lastRenderKind, durationMs);
+
+    if (this.options.showBadges !== false) {
+      this.updateBadge(stats);
+    }
+  }
+
+  removeBadge(el: Element): void {
+    this.badges.get(el)?.remove();
+    this.badges.delete(el);
+  }
+
+  private updateBadge(stats: ComponentStats): void {
+    let badge = this.badges.get(stats.hostElement);
+
+    if (!badge) {
+      badge = this.document.createElement('div');
+      badge.setAttribute('aria-hidden', 'true');
+      badge.setAttribute('role', 'presentation');
+      badge.style.cssText = [
+        'position:absolute',
+        'top:2px',
+        'right:2px',
+        'z-index:2147483645',
+        'pointer-events:none',
+        'font:bold 9px/13px monospace',
+        'padding:1px 4px',
+        'border-radius:3px',
+        'min-width:16px',
+        'text-align:center',
+        'color:#fff',
+        'white-space:nowrap',
+      ].join(';');
+
+      // Host element must be non-static to contain an absolutely-positioned badge
+      this.ensurePositioned(stats.hostElement);
+      stats.hostElement.appendChild(badge);
+      this.badges.set(stats.hostElement, badge);
+    }
+
+    const isUnnecessary = stats.lastRenderKind === 'unnecessary';
+    badge.style.background = isUnnecessary ? '#f44336' : '#ff9800';
+    badge.textContent = String(stats.totalRenders);
+    badge.title = `${stats.componentName}: ${stats.totalRenders} renders, ${stats.unnecessaryRenders} unnecessary`;
+  }
+
+  private ensurePositioned(el: Element): void {
+    const htmlEl = el as HTMLElement;
+    if (getComputedStyle(htmlEl).position === 'static') {
+      htmlEl.style.position = 'relative';
+    }
+  }
+}

package/src/lib/provide-angular-scan.ts

@@ -0,0 +1,77 @@
+import {
+  EnvironmentProviders,
+  makeEnvironmentProviders,
+  isDevMode,
+  provideEnvironmentInitializer,
+  inject,
+  ApplicationRef,
+  createComponent,
+  EnvironmentInjector,
+} from '@angular/core';
+import { DOCUMENT } from '@angular/common';
+import { ScannerService } from './scanner.service';
+import { OverlayService } from './overlay/overlay.service';
+import { ToolbarComponent } from './toolbar/toolbar.component';
+import { ANGULAR_SCAN_OPTIONS } from './tokens';
+import type { AngularScanOptions } from './types';
+
+/**
+ * Provides angular-scan for development-time render tracking.
+ *
+ * Add to your application providers:
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideAngularScan()]
+ * });
+ * ```
+ *
+ * This is a complete no-op in production builds (`isDevMode() === false`),
+ * so it can safely be left in your app config.
+ */
+export function provideAngularScan(options: AngularScanOptions = {}): EnvironmentProviders {
+  // Return empty providers in production — entire library is tree-shaken
+  if (!isDevMode()) {
+    return makeEnvironmentProviders([]);
+  }
+
+  const resolvedOptions: AngularScanOptions = {
+    enabled: true,
+    flashDurationMs: 500,
+    showBadges: true,
+    showToolbar: true,
+    ...options,
+  };
+
+  return makeEnvironmentProviders([
+    {
+      provide: ANGULAR_SCAN_OPTIONS,
+      useValue: resolvedOptions,
+    },
+    provideEnvironmentInitializer(() => {
+        const overlay = inject(OverlayService);
+        const scanner = inject(ScannerService);
+        const opts = inject(ANGULAR_SCAN_OPTIONS);
+
+        overlay.initialize();
+        scanner.initialize();
+
+        if (opts.showToolbar !== false) {
+          const injector = inject(EnvironmentInjector);
+          const doc = inject(DOCUMENT);
+          const appRef = inject(ApplicationRef);
+
+          // Create the toolbar outside Angular's component tree so it doesn't
+          // appear in CD tracking. Attach it to ApplicationRef so signals work.
+          const toolbarRef = createComponent(ToolbarComponent, {
+            environmentInjector: injector,
+          });
+
+          doc.body.appendChild(toolbarRef.location.nativeElement);
+          appRef.attachView(toolbarRef.hostView);
+
+          // Tell the scanner to ignore the toolbar's own renders
+          scanner.setToolbarInstance(toolbarRef.instance);
+        }
+    }),
+  ]);
+}

package/src/lib/scan.ts

@@ -0,0 +1,176 @@
+import { isDevMode } from '@angular/core';
+import { getNgDebugApi } from './ng-debug';
+import { CanvasOverlay } from './overlay/canvas-overlay';
+import type { AngularScanOptions, RenderKind } from './types';
+
+// Profiler event constants
+const TemplateUpdateStart = 2;
+const ChangeDetectionStart = 12;
+const ChangeDetectionEnd = 13;
+const ChangeDetectionSyncStart = 14;
+const ChangeDetectionSyncEnd = 15;
+
+/**
+ * Imperative API for angular-scan.
+ *
+ * Use this when you cannot modify application providers (e.g. micro-frontends,
+ * third-party apps). Call before `bootstrapApplication()`.
+ *
+ * ```ts
+ * // main.ts
+ * import { scan } from 'angular-scan';
+ * scan();
+ * bootstrapApplication(AppComponent, appConfig);
+ * ```
+ *
+ * @returns A teardown function that stops scanning and removes the overlay.
+ */
+export function scan(options: AngularScanOptions = {}): () => void {
+  if (!isDevMode()) return noop;
+  if (typeof window === 'undefined') return noop;
+  if (options.enabled === false) return noop;
+
+  const ng = getNgDebugApi();
+  if (!ng) {
+    console.warn(
+      '[angular-scan] Angular debug APIs (window.ng) not available. ' +
+      'Ensure you are running in development mode.'
+    );
+    return noop;
+  }
+
+  const durationMs = options.flashDurationMs ?? 500;
+  const showBadges = options.showBadges !== false;
+
+  const overlay = new CanvasOverlay();
+  overlay.attach(document);
+
+  // State for the current tick
+  let inTick = false;
+  let inSyncPhase = false;
+  const mutatedNodes = new Set<Node>();
+  const tickInstances = new Set<object>();
+  const renderCounts = new WeakMap<object, number>();
+  const unnecessaryCounts = new WeakMap<object, number>();
+  const badges = new Map<Element, HTMLElement>();
+
+  const observer = new MutationObserver(records => {
+    for (const r of records) {
+      mutatedNodes.add(r.target);
+      r.addedNodes.forEach(n => mutatedNodes.add(n));
+      r.removedNodes.forEach(n => mutatedNodes.add(n));
+    }
+  });
+
+  const removeProfiler = ng.ɵsetProfiler((event, instance) => {
+    switch (event) {
+      case ChangeDetectionStart:
+        if (inTick) break;
+        inTick = true;
+        mutatedNodes.clear();
+        tickInstances.clear();
+        observer.observe(document.body, {
+          subtree: true, childList: true, attributes: true, characterData: true,
+        });
+        break;
+
+      case ChangeDetectionSyncStart:
+        inSyncPhase = true;
+        break;
+
+      case ChangeDetectionSyncEnd:
+        inSyncPhase = false;
+        break;
+
+      case TemplateUpdateStart:
+        if (inSyncPhase && instance) tickInstances.add(instance);
+        break;
+
+      case ChangeDetectionEnd: {
+        if (!inTick) break;
+        inTick = false;
+        inSyncPhase = false;
+
+        const pending = observer.takeRecords();
+        for (const r of pending) {
+          mutatedNodes.add(r.target);
+          r.addedNodes.forEach(n => mutatedNodes.add(n));
+          r.removedNodes.forEach(n => mutatedNodes.add(n));
+        }
+        observer.disconnect();
+
+        // Build mutated host set
+        const mutatedHosts = new Set<Element>();
+        for (const node of mutatedNodes) {
+          let current: Node | null = node;
+          while (current && current !== document.body) {
+            if (current instanceof Element) {
+              try {
+                if (ng.getComponent(current)) { mutatedHosts.add(current); break; }
+              } catch { /* ignore */ }
+            }
+            current = current.parentNode;
+          }
+        }
+
+        // Collect updates without writing to any signals
+        const updates: Array<{ instance: object; hostEl: Element; kind: RenderKind }> = [];
+        for (const inst of tickInstances) {
+          try {
+            const hostEl = ng.getHostElement(inst);
+            if (!hostEl) continue;
+            const kind: RenderKind = mutatedHosts.has(hostEl) ? 'render' : 'unnecessary';
+            updates.push({ instance: inst, hostEl, kind });
+          } catch { /* component destroyed */ }
+        }
+
+        queueMicrotask(() => {
+          for (const { instance, hostEl, kind } of updates) {
+            const count = (renderCounts.get(instance) ?? 0) + 1;
+            renderCounts.set(instance, count);
+
+            if (kind === 'unnecessary') {
+              unnecessaryCounts.set(instance, (unnecessaryCounts.get(instance) ?? 0) + 1);
+            }
+
+            overlay.flash(hostEl, kind, durationMs);
+
+            if (showBadges) updateBadge(hostEl, count, kind);
+          }
+        });
+        break;
+      }
+    }
+  });
+
+  function updateBadge(hostEl: Element, count: number, kind: RenderKind): void {
+    let badge = badges.get(hostEl);
+    if (!badge) {
+      badge = document.createElement('div');
+      badge.setAttribute('aria-hidden', 'true');
+      badge.setAttribute('role', 'presentation');
+      badge.style.cssText = [
+        'position:absolute', 'top:2px', 'right:2px',
+        'z-index:2147483645', 'pointer-events:none',
+        'font:bold 9px/13px monospace', 'padding:1px 4px',
+        'border-radius:3px', 'min-width:16px', 'text-align:center', 'color:#fff',
+      ].join(';');
+      const htmlEl = hostEl as HTMLElement;
+      if (getComputedStyle(htmlEl).position === 'static') htmlEl.style.position = 'relative';
+      hostEl.appendChild(badge);
+      badges.set(hostEl, badge);
+    }
+    badge.style.background = kind === 'unnecessary' ? '#f44336' : '#ff9800';
+    badge.textContent = String(count);
+  }
+
+  return () => {
+    removeProfiler();
+    observer.disconnect();
+    overlay.detach();
+    for (const b of badges.values()) b.remove();
+    badges.clear();
+  };
+}
+
+function noop(): void {}

package/src/lib/scanner.service.ts

@@ -0,0 +1,197 @@
+import {
+  Injectable,
+  inject,
+  isDevMode,
+  OnDestroy,
+  PLATFORM_ID,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { ComponentTracker } from './component-tracker';
+import { OverlayService } from './overlay/overlay.service';
+import { ANGULAR_SCAN_OPTIONS } from './tokens';
+import { getNgDebugApi } from './ng-debug';
+import type { NgDebugApi, RenderKind } from './types';
+
+// Angular profiler event IDs (stable contract in dev mode, used by Angular DevTools)
+const TemplateUpdateStart = 2;
+const ChangeDetectionStart = 12;
+const ChangeDetectionEnd = 13;
+const ChangeDetectionSyncStart = 14;
+const ChangeDetectionSyncEnd = 15;
+
+interface PendingUpdate {
+  instance: object;
+  hostElement: Element;
+  kind: RenderKind;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ScannerService implements OnDestroy {
+  private readonly tracker = inject(ComponentTracker);
+  private readonly overlay = inject(OverlayService);
+  private readonly options = inject(ANGULAR_SCAN_OPTIONS);
+  private readonly platformId = inject(PLATFORM_ID);
+
+  private removeProfiler: (() => void) | null = null;
+  private mutationObserver: MutationObserver | null = null;
+
+  // Accumulated during a single CD tick (raw DOM nodes, no signal writes)
+  private mutatedNodes = new Set<Node>();
+  // Component instances visited during the sync (template update) phase
+  private tickInstances = new Set<object>();
+
+  // Tracks which phase of CD we're in
+  private inSyncPhase = false;
+  private inTick = false;
+
+  // The toolbar component instance — excluded from tracking to avoid self-loops
+  private toolbarInstance: object | null = null;
+
+  initialize(): void {
+    if (!isDevMode()) return;
+    if (!isPlatformBrowser(this.platformId)) return;
+    if (this.options.enabled === false) return;
+
+    const ng = getNgDebugApi();
+    if (!ng) {
+      console.warn(
+        '[angular-scan] Angular debug APIs (window.ng) not available. ' +
+        'Ensure you are running in development mode.'
+      );
+      return;
+    }
+
+    this.mutationObserver = new MutationObserver(records => {
+      for (const r of records) {
+        this.mutatedNodes.add(r.target);
+        r.addedNodes.forEach(n => this.mutatedNodes.add(n));
+        r.removedNodes.forEach(n => this.mutatedNodes.add(n));
+      }
+    });
+
+    this.removeProfiler = ng.ɵsetProfiler((event, instance) => {
+      switch (event) {
+        case ChangeDetectionStart:
+          this.onTickStart();
+          break;
+        case ChangeDetectionSyncStart:
+          this.inSyncPhase = true;
+          break;
+        case ChangeDetectionSyncEnd:
+          this.inSyncPhase = false;
+          break;
+        case TemplateUpdateStart:
+          // Only record during the real update phase, not the dev-mode checkNoChanges pass
+          if (this.inSyncPhase && instance && instance !== this.toolbarInstance) {
+            this.tickInstances.add(instance);
+          }
+          break;
+        case ChangeDetectionEnd:
+          this.onTickEnd(ng);
+          break;
+      }
+    });
+  }
+
+  /** Exclude a component instance from render tracking (used for the toolbar). */
+  setToolbarInstance(instance: object): void {
+    this.toolbarInstance = instance;
+  }
+
+  private onTickStart(): void {
+    if (this.inTick) return;
+    this.inTick = true;
+    this.mutatedNodes.clear();
+    this.tickInstances.clear();
+
+    this.mutationObserver?.observe(document.body, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true,
+    });
+  }
+
+  private onTickEnd(ng: NgDebugApi): void {
+    if (!this.inTick) return;
+    this.inTick = false;
+    this.inSyncPhase = false;
+
+    // Synchronously flush pending mutation records before disconnecting
+    const pending = this.mutationObserver?.takeRecords() ?? [];
+    for (const r of pending) {
+      this.mutatedNodes.add(r.target);
+      r.addedNodes.forEach(n => this.mutatedNodes.add(n));
+      r.removedNodes.forEach(n => this.mutatedNodes.add(n));
+    }
+    this.mutationObserver?.disconnect();
+
+    // Build a set of component host elements that had DOM mutations
+    // Walk mutated nodes UP to find their owning component host element
+    const mutatedHosts = this.buildMutatedHosts(ng);
+
+    // Collect updates as pure data — NO signal writes here (would trigger CD)
+    const pendingUpdates: PendingUpdate[] = [];
+
+    for (const instance of this.tickInstances) {
+      try {
+        const hostElement = ng.getHostElement(instance);
+        if (!hostElement) continue;
+
+        const hadMutation = mutatedHosts.has(hostElement);
+        const kind: RenderKind = hadMutation ? 'render' : 'unnecessary';
+
+        pendingUpdates.push({ instance, hostElement, kind });
+      } catch {
+        // Component may have been destroyed during the tick
+      }
+    }
+
+    // Defer all signal writes out of the profiler callback to avoid triggering a new CD cycle
+    queueMicrotask(() => {
+      for (const update of pendingUpdates) {
+        const stats = this.tracker.recordRender(update.instance, update.hostElement, update.kind);
+        this.overlay.onComponentChecked(stats);
+      }
+      this.tracker.snapshotTrackedComponents();
+    });
+  }
+
+  /**
+   * Build a Set of host Elements by walking each mutated node up the DOM tree
+   * until an Angular component boundary is found.
+   * This is O(mutatedNodes × depth) but depth is typically < 20.
+   */
+  private buildMutatedHosts(ng: NgDebugApi): Set<Element> {
+    const hosts = new Set<Element>();
+
+    for (const node of this.mutatedNodes) {
+      let current: Node | null = node;
+
+      while (current && current !== document.body) {
+        if (current instanceof Element) {
+          try {
+            const component = ng.getComponent(current);
+            if (component) {
+              hosts.add(current);
+              break;
+            }
+          } catch {
+            // ignore
+          }
+        }
+        current = current.parentNode;
+      }
+    }
+
+    return hosts;
+  }
+
+  ngOnDestroy(): void {
+    this.removeProfiler?.();
+    this.removeProfiler = null;
+    this.mutationObserver?.disconnect();
+    this.mutationObserver = null;
+    this.overlay.destroy();
+  }
+}

package/src/lib/tokens.ts

@@ -0,0 +1,7 @@
+import { InjectionToken } from '@angular/core';
+import type { AngularScanOptions } from './types';
+
+export const ANGULAR_SCAN_OPTIONS = new InjectionToken<AngularScanOptions>(
+  'ANGULAR_SCAN_OPTIONS',
+  { providedIn: 'root', factory: () => ({}) }
+);

package/src/lib/toolbar/toolbar.component.html

@@ -0,0 +1,66 @@
+<div
+class="toolbar"
+role="complementary"
+aria-label="Angular Scan DevTools"
+>
+<div class="toolbar__header">
+  <span class="toolbar__logo" aria-hidden="true">◉</span>
+  <span class="toolbar__title">angular-scan</span>
+
+  <button
+    class="toolbar__btn"
+    type="button"
+    [attr.aria-pressed]="enabled()"
+    [title]="enabled() ? 'Pause scanning' : 'Resume scanning'"
+    (click)="toggleEnabled()"
+  >{{ enabled() ? '⏸' : '▶' }}</button>
+
+  <button
+    class="toolbar__btn"
+    type="button"
+    [attr.aria-pressed]="expanded()"
+    [title]="expanded() ? 'Collapse inspector' : 'Expand inspector'"
+    (click)="toggleExpanded()"
+  >{{ expanded() ? '▲' : '▼' }}</button>
+</div>
+
+<div class="toolbar__stats">
+  <span class="toolbar__stat" title="Total change detection checks">
+    <span class="toolbar__stat-label">checks</span>
+    <strong class="toolbar__stat-value">{{ tracker.totalRenders() }}</strong>
+  </span>
+  <span
+    class="toolbar__stat"
+    [class.toolbar__stat--warn]="tracker.totalUnnecessary() > 0"
+    title="Unnecessary renders: component was checked but DOM did not change"
+  >
+    <span class="toolbar__stat-label">wasted</span>
+    <strong class="toolbar__stat-value">{{ tracker.totalUnnecessary() }}</strong>
+  </span>
+</div>
+
+@if (expanded()) {
+  <div
+    class="toolbar__inspector"
+    role="list"
+    aria-label="Component render counts"
+  >
+    @for (comp of tracker.trackedComponents(); track comp.hostElement) {
+      <div
+        class="toolbar__component"
+        role="listitem"
+        [class.toolbar__component--warn]="comp.lastRenderKind === 'unnecessary'"
+        [title]="comp.componentName + ' — ' + comp.totalRenders + ' checks, ' + comp.unnecessaryRenders + ' wasted'"
+      >
+        <span class="toolbar__component-name">{{ comp.componentName }}</span>
+        <span class="toolbar__component-count">{{ comp.totalRenders }}</span>
+        @if (comp.unnecessaryRenders > 0) {
+          <span class="toolbar__component-wasted" aria-label="wasted renders">
+            {{ comp.unnecessaryRenders }}W
+          </span>
+        }
+      </div>
+    }
+  </div>
+}
+</div>

package/src/lib/toolbar/toolbar.component.scss

@@ -0,0 +1,147 @@
+
+:host {
+    position: fixed;
+    bottom: 0;
+    right: 0;
+    z-index: 2147483647;
+    font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, monospace;
+    font-size: 11px;
+    line-height: 1.4;
+  }
+
+  .toolbar {
+    background: #0f1117;
+    color: #c9d1d9;
+    border: 1px solid #30363d;
+    border-bottom: none;
+    border-right: none;
+    border-radius: 6px 0 0 0;
+    min-width: 200px;
+    max-width: 300px;
+    box-shadow: -2px -2px 12px rgba(0, 0, 0, 0.5);
+  }
+
+  .toolbar__header {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    padding: 5px 8px;
+    border-bottom: 1px solid #21262d;
+  }
+
+  .toolbar__logo {
+    color: #58a6ff;
+    font-size: 12px;
+  }
+
+  .toolbar__title {
+    font-weight: 600;
+    color: #58a6ff;
+    flex: 1;
+    letter-spacing: 0.02em;
+  }
+
+  .toolbar__btn {
+    background: transparent;
+    border: 1px solid #30363d;
+    color: #8b949e;
+    border-radius: 4px;
+    cursor: pointer;
+    padding: 2px 6px;
+    font-size: 10px;
+    transition: color 0.15s, border-color 0.15s;
+  }
+
+  .toolbar__btn:hover {
+    color: #c9d1d9;
+    border-color: #58a6ff;
+  }
+
+  .toolbar__btn:focus-visible {
+    outline: 2px solid #58a6ff;
+    outline-offset: 2px;
+  }
+
+  .toolbar__stats {
+    display: flex;
+    gap: 12px;
+    padding: 5px 8px;
+  }
+
+  .toolbar__stat {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+  }
+
+  .toolbar__stat-label {
+    color: #8b949e;
+    font-size: 9px;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  .toolbar__stat-value {
+    color: #c9d1d9;
+  }
+
+  .toolbar__stat--warn .toolbar__stat-value {
+    color: #f85149;
+  }
+
+  .toolbar__inspector {
+    max-height: 220px;
+    overflow-y: auto;
+    border-top: 1px solid #21262d;
+  }
+
+  .toolbar__inspector::-webkit-scrollbar {
+    width: 4px;
+  }
+
+  .toolbar__inspector::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .toolbar__inspector::-webkit-scrollbar-thumb {
+    background: #30363d;
+    border-radius: 2px;
+  }
+
+  .toolbar__component {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 3px 8px;
+    border-bottom: 1px solid #161b22;
+    transition: background 0.1s;
+  }
+
+  .toolbar__component:hover {
+    background: #161b22;
+  }
+
+  .toolbar__component--warn {
+    background: rgba(248, 81, 73, 0.06);
+  }
+
+  .toolbar__component-name {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: #8b949e;
+  }
+
+  .toolbar__component-count {
+    font-weight: 600;
+    color: #ffa657;
+    min-width: 20px;
+    text-align: right;
+  }
+
+  .toolbar__component-wasted {
+    color: #f85149;
+    font-size: 9px;
+    font-weight: 600;
+  }

package/src/lib/toolbar/toolbar.component.ts

@@ -0,0 +1,29 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  inject,
+  signal,
+} from '@angular/core';
+import { ComponentTracker } from '../component-tracker';
+
+@Component({
+  selector: 'angular-scan-toolbar',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './toolbar.component.html',
+  styleUrls: ['./toolbar.component.scss'],
+  host: { '[style.display]': '"block"' },
+})
+export class ToolbarComponent {
+  protected readonly tracker = inject(ComponentTracker);
+
+  protected readonly expanded = signal(false);
+  protected readonly enabled = signal(true);
+
+  protected toggleExpanded(): void {
+    this.expanded.update(v => !v);
+  }
+
+  protected toggleEnabled(): void {
+    this.enabled.update(v => !v);
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,36 @@
+/** Whether a render was meaningful (DOM changed) or wasted (DOM unchanged). */
+export type RenderKind = 'render' | 'unnecessary';
+
+/** Accumulated stats for a single component across its lifetime. */
+export interface ComponentStats {
+  componentName: string;
+  hostElement: Element;
+  totalRenders: number;
+  unnecessaryRenders: number;
+  lastRenderKind: RenderKind;
+  lastRenderTimestamp: number;
+}
+
+/** Options for configuring angular-scan. */
+export interface AngularScanOptions {
+  /** Set to false to disable scanning entirely. Default: true. */
+  enabled?: boolean;
+  /** Duration of the canvas flash in milliseconds. Default: 500. */
+  flashDurationMs?: number;
+  /** Show render count badges on component host elements. Default: true. */
+  showBadges?: boolean;
+  /** Show the floating toolbar HUD. Default: true. */
+  showToolbar?: boolean;
+}
+
+/** Shape of the window.ng Angular debug API (dev mode only). */
+export interface NgDebugApi {
+  getComponent: (el: Element) => object | null;
+  getHostElement: (component: object) => Element | null;
+  getRootComponents: (el?: Element) => object[];
+  getOwningComponent: (el: Element) => object | null;
+  getDirectives: (el: Element) => object[];
+  ɵsetProfiler: (
+    callback: ((event: number, instance: object | null, context?: unknown) => void) | null
+  ) => () => void;
+}

package/src/public-api.ts

@@ -0,0 +1,7 @@
+/*
+ * Public API Surface of angular-scan
+ */
+
+export { provideAngularScan } from './lib/provide-angular-scan';
+export { scan } from './lib/scan';
+export type { AngularScanOptions, ComponentStats, RenderKind } from './lib/types';

package/tsconfig.lib.json

@@ -0,0 +1,13 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,10 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
+}