angular-scan 0.0.2 → 0.0.3

package/src/lib/scan.ts

@@ -1,176 +0,0 @@
-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

@@ -1,197 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

@@ -1,66 +0,0 @@
-<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

@@ -1,147 +0,0 @@
-
-: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

@@ -1,29 +0,0 @@
-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

@@ -1,36 +0,0 @@
-/** 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

@@ -1,7 +0,0 @@
-/*
- * 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

@@ -1,13 +0,0 @@
-/* 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

@@ -1,11 +0,0 @@
-/* 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"
-  }
-}