@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta21

package/src/main-api/Inspector.ts

@@ -5,9 +5,61 @@ import {
 } from '../core/CoreNode.js';
 import { type RendererMainSettings } from './Renderer.js';
 import type { AnimationSettings } from '../core/animations/CoreAnimation.js';
-import type { IAnimationController } from '../common/IAnimationController.js';
+import type {
+  IAnimationController,
+  AnimationControllerState,
+} from '../common/IAnimationController.js';
 import { isProductionEnvironment } from '../utils.js';
-import type { CoreTextNode, CoreTextNodeProps } from '../core/CoreTextNode.js';
+import { CoreTextNode, type CoreTextNodeProps } from '../core/CoreTextNode.js';
+
+/**
+ * Inspector Options
+ *
+ * Configuration options for the Inspector's performance monitoring features.
+ */
+export interface InspectorOptions {
+  /**
+   * Enable performance monitoring for setter calls
+   *
+   * @defaultValue true
+   */
+  enablePerformanceMonitoring: boolean;
+
+  /**
+   * Threshold for excessive setter calls before logging a warning
+   *
+   * @defaultValue 100
+   */
+  excessiveCallThreshold: number;
+
+  /**
+   * Time interval in milliseconds to reset the setter call counters
+   *
+   * @defaultValue 5000
+   */
+  resetInterval: number;
+
+  /**
+   * Enable animation monitoring and statistics tracking
+   *
+   * @defaultValue true
+   */
+  enableAnimationMonitoring: boolean;
+
+  /**
+   * Maximum number of animations to keep in history for statistics
+   *
+   * @defaultValue 1000
+   */
+  maxAnimationHistory: number;
+
+  /**
+   * Automatically print animation statistics every X seconds (0 to disable)
+   *
+   * @defaultValue 0
+   */
+  animationStatsInterval: number;
+}
 
 /**
  * Inspector
@@ -48,16 +100,16 @@ const stylePropertyMap: {
   y: (y) => {
     return { prop: 'top', value: `${y}px` };
   },
-  width: (w) => {
+  w: (w) => {
     if (w === 0) {
-      return null;
+      return { prop: 'width', value: 'auto' };
     }
 
     return { prop: 'width', value: `${w}px` };
   },
-  height: (h) => {
+  h: (h) => {
     if (h === 0) {
-      return null;
+      return { prop: 'height', value: 'auto' };
     }
 
     return { prop: 'height', value: `${h}px` };
@@ -79,8 +131,6 @@ const stylePropertyMap: {
   zIndex: () => 'z-index',
   fontFamily: () => 'font-family',
   fontStyle: () => 'font-style',
-  fontWeight: () => 'font-weight',
-  fontStretch: () => 'font-stretch',
   letterSpacing: () => 'letter-spacing',
   textAlign: () => 'text-align',
   overflowSuffix: () => 'overflow-suffix',
@@ -161,23 +211,86 @@ const knownProperties = new Set<string>([
   'src',
   'parent',
   'data',
+  'text',
 ]);
 
 export class Inspector {
   private root: HTMLElement | null = null;
   private canvas: HTMLCanvasElement | null = null;
+  private mutationObserver: MutationObserver = new MutationObserver(() => {});
+  private resizeObserver: ResizeObserver = new ResizeObserver(() => {});
   private height = 1080;
   private width = 1920;
   private scaleX = 1;
   private scaleY = 1;
 
+  // Performance monitoring for frequent setter calls
+  private static setterCallCount = new Map<
+    string,
+    { count: number; lastReset: number; nodeId: number }
+  >();
+
+  // Animation monitoring structures
+  private static activeAnimations = new Map<
+    string,
+    {
+      nodeId: number;
+      animationId: string;
+      startTime: number;
+      props: CoreNodeAnimateProps;
+      settings: AnimationSettings;
+      controller: IAnimationController;
+      state: AnimationControllerState;
+    }
+  >();
+
+  private static animationHistory: Array<{
+    nodeId: number;
+    animationId: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    actualDuration: number;
+    props: CoreNodeAnimateProps;
+    settings: AnimationSettings;
+    completionType: 'finished' | 'stopped' | 'cancelled';
+  }> = [];
+
+  // Performance monitoring settings (configured via constructor)
+  private performanceSettings: InspectorOptions = {
+    enablePerformanceMonitoring: false,
+    excessiveCallThreshold: 100,
+    resetInterval: 5000,
+    enableAnimationMonitoring: false,
+    maxAnimationHistory: 1000,
+    animationStatsInterval: 0,
+  };
+
+  // Animation stats printing timer
+  private animationStatsTimer: number | null = null;
+
   constructor(canvas: HTMLCanvasElement, settings: RendererMainSettings) {
-    if (isProductionEnvironment()) return;
+    if (isProductionEnvironment === true) return;
 
     if (!settings) {
       throw new Error('settings is required');
     }
 
+    // Initialize performance monitoring settings with defaults
+    this.performanceSettings = {
+      enablePerformanceMonitoring:
+        settings.inspectorOptions?.enablePerformanceMonitoring ?? false,
+      excessiveCallThreshold:
+        settings.inspectorOptions?.excessiveCallThreshold ?? 100,
+      resetInterval: settings.inspectorOptions?.resetInterval ?? 5000,
+      enableAnimationMonitoring:
+        settings.inspectorOptions?.enableAnimationMonitoring ?? false,
+      maxAnimationHistory:
+        settings.inspectorOptions?.maxAnimationHistory ?? 1000,
+      animationStatsInterval:
+        settings.inspectorOptions?.animationStatsInterval ?? 0,
+    };
+
     // calc dimensions based on the devicePixelRatio
     this.height = Math.ceil(
       settings.appHeight ?? 1080 / (settings.deviceLogicalPixelRatio ?? 1),
@@ -196,25 +309,395 @@ export class Inspector {
     document.body.appendChild(this.root);
 
     //listen for changes on canvas
-    const mutationObserver = new MutationObserver(
+    this.mutationObserver = new MutationObserver(
       this.setRootPosition.bind(this),
     );
-    mutationObserver.observe(canvas, {
+    this.mutationObserver.observe(canvas, {
       attributes: true,
       childList: false,
       subtree: false,
     });
 
     // Create a ResizeObserver to watch for changes in the element's size
-    const resizeObserver = new ResizeObserver(this.setRootPosition.bind(this));
-    resizeObserver.observe(canvas);
+    this.resizeObserver = new ResizeObserver(this.setRootPosition.bind(this));
+    this.resizeObserver.observe(canvas);
 
     //listen for changes on window
     window.addEventListener('resize', this.setRootPosition.bind(this));
 
+    // Start animation stats timer if enabled
+    this.startAnimationStatsTimer();
+
     console.warn('Inspector is enabled, this will impact performance');
   }
 
+  /**
+   * Track setter calls for performance monitoring
+   * Only active when Inspector is loaded
+   */
+  private trackSetterCall(nodeId: number, setterName: string): void {
+    if (!this.performanceSettings.enablePerformanceMonitoring) {
+      return;
+    }
+
+    const key = `${nodeId}_${setterName}`;
+    const now = Date.now();
+    const existing = Inspector.setterCallCount.get(key);
+
+    if (!existing) {
+      Inspector.setterCallCount.set(key, { count: 1, lastReset: now, nodeId });
+      return;
+    }
+
+    // Reset counter if enough time has passed
+    if (now - existing.lastReset > this.performanceSettings.resetInterval) {
+      existing.count = 1;
+      existing.lastReset = now;
+      return;
+    }
+
+    existing.count++;
+
+    // Log if threshold exceeded
+    if (existing.count === this.performanceSettings.excessiveCallThreshold) {
+      console.warn(
+        `🚨 Inspector Performance Warning: Setter '${setterName}' called ${existing.count} times in ${this.performanceSettings.resetInterval}ms on node ${nodeId}`,
+      );
+    } else if (
+      existing.count > this.performanceSettings.excessiveCallThreshold &&
+      existing.count % 50 === 0
+    ) {
+      console.warn(
+        `🚨 Inspector Performance Warning: Setter '${setterName}' called ${existing.count} times in ${this.performanceSettings.resetInterval}ms on node ${nodeId} (continuing...)`,
+      );
+    }
+  }
+
+  /**
+   * Get current performance monitoring statistics
+   */
+  public static getPerformanceStats(): Array<{
+    nodeId: number;
+    setterName: string;
+    count: number;
+    timeWindow: number;
+  }> {
+    const stats: Array<{
+      nodeId: number;
+      setterName: string;
+      count: number;
+      timeWindow: number;
+    }> = [];
+    const now = Date.now();
+
+    Inspector.setterCallCount.forEach((data, key) => {
+      const parts = key.split('_');
+      const nodeIdStr = parts[0];
+      const setterName = parts[1];
+
+      if (nodeIdStr && setterName) {
+        const timeWindow = now - data.lastReset;
+
+        stats.push({
+          nodeId: parseInt(nodeIdStr, 10),
+          setterName,
+          count: data.count,
+          timeWindow,
+        });
+      }
+    });
+
+    return stats.sort((a, b) => b.count - a.count);
+  }
+
+  /**
+   * Clear performance monitoring statistics
+   */
+  public static clearPerformanceStats(): void {
+    Inspector.setterCallCount.clear();
+  }
+
+  /**
+   * Generate a unique animation ID
+   */
+  private static generateAnimationId(): string {
+    return `anim_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Wrap animation controller with monitoring capabilities
+   */
+  private wrapAnimationController(
+    controller: IAnimationController,
+    nodeId: number,
+    props: CoreNodeAnimateProps,
+    settings: AnimationSettings,
+    div: HTMLElement,
+  ): IAnimationController {
+    if (!this.performanceSettings.enableAnimationMonitoring) {
+      // Just add the basic DOM animation without tracking
+      const originalStart = controller.start.bind(controller);
+      controller.start = () => {
+        this.animateNode(div, props, settings);
+        return originalStart();
+      };
+      return controller;
+    }
+
+    const animationId = Inspector.generateAnimationId();
+
+    // Create wrapper controller
+    const wrappedController: IAnimationController = {
+      start: () => {
+        this.trackAnimationStart(
+          animationId,
+          nodeId,
+          props,
+          settings,
+          controller,
+        );
+        this.animateNode(div, props, settings);
+        return controller.start();
+      },
+
+      stop: () => {
+        this.trackAnimationEnd(animationId, 'stopped');
+        return controller.stop();
+      },
+
+      pause: () => {
+        this.updateAnimationState(animationId, 'paused');
+        return controller.pause();
+      },
+
+      restore: () => {
+        this.trackAnimationEnd(animationId, 'cancelled');
+        return controller.restore();
+      },
+
+      waitUntilStopped: () => {
+        return controller.waitUntilStopped().then(() => {
+          this.trackAnimationEnd(animationId, 'finished');
+        });
+      },
+
+      get state() {
+        return controller.state;
+      },
+
+      // Event emitter methods
+      on: controller.on.bind(controller),
+      off: controller.off.bind(controller),
+      once: controller.once.bind(controller),
+      emit: controller.emit.bind(controller),
+    };
+
+    // Track animation events
+    controller.on('animating', () => {
+      this.updateAnimationState(animationId, 'running');
+    });
+
+    controller.on('stopped', () => {
+      this.trackAnimationEnd(animationId, 'finished');
+    });
+
+    return wrappedController;
+  }
+
+  /**
+   * Track animation start
+   */
+  private trackAnimationStart(
+    animationId: string,
+    nodeId: number,
+    props: CoreNodeAnimateProps,
+    settings: AnimationSettings,
+    controller: IAnimationController,
+  ): void {
+    const startTime = Date.now();
+
+    Inspector.activeAnimations.set(animationId, {
+      nodeId,
+      animationId,
+      startTime,
+      props,
+      settings,
+      controller,
+      state: 'scheduled',
+    });
+  }
+
+  /**
+   * Update animation state
+   */
+  private updateAnimationState(
+    animationId: string,
+    state: AnimationControllerState,
+  ): void {
+    const animation = Inspector.activeAnimations.get(animationId);
+    if (animation) {
+      animation.state = state;
+    }
+  }
+
+  /**
+   * Track animation end
+   */
+  private trackAnimationEnd(
+    animationId: string,
+    completionType: 'finished' | 'stopped' | 'cancelled',
+  ): void {
+    const animation = Inspector.activeAnimations.get(animationId);
+    if (!animation) return;
+
+    const endTime = Date.now();
+    const actualDuration = endTime - animation.startTime;
+    const expectedDuration = animation.settings.duration || 1000;
+
+    // Move to history
+    Inspector.animationHistory.unshift({
+      nodeId: animation.nodeId,
+      animationId: animation.animationId,
+      startTime: animation.startTime,
+      endTime,
+      duration: expectedDuration,
+      actualDuration,
+      props: animation.props,
+      settings: animation.settings,
+      completionType,
+    });
+
+    // Limit history size for performance
+    if (
+      Inspector.animationHistory.length >
+      this.performanceSettings.maxAnimationHistory
+    ) {
+      Inspector.animationHistory.splice(
+        this.performanceSettings.maxAnimationHistory,
+      );
+    }
+
+    // Remove from active animations
+    Inspector.activeAnimations.delete(animationId);
+  }
+
+  /**
+   * Get currently active animations
+   */
+  public static getActiveAnimations(): Array<{
+    nodeId: number;
+    animationId: string;
+    startTime: number;
+    duration: number;
+    elapsedTime: number;
+    props: CoreNodeAnimateProps;
+    settings: AnimationSettings;
+    state: AnimationControllerState;
+  }> {
+    const now = Date.now();
+    const activeAnimations: Array<{
+      nodeId: number;
+      animationId: string;
+      startTime: number;
+      duration: number;
+      elapsedTime: number;
+      props: CoreNodeAnimateProps;
+      settings: AnimationSettings;
+      state: AnimationControllerState;
+    }> = [];
+
+    Inspector.activeAnimations.forEach((animation) => {
+      activeAnimations.push({
+        nodeId: animation.nodeId,
+        animationId: animation.animationId,
+        startTime: animation.startTime,
+        duration: animation.settings.duration || 1000,
+        elapsedTime: now - animation.startTime,
+        props: animation.props,
+        settings: animation.settings,
+        state: animation.state,
+      });
+    });
+
+    return activeAnimations.sort((a, b) => b.startTime - a.startTime);
+  }
+
+  /**
+   * Get animation statistics
+   */
+  public static getAnimationStats(): {
+    totalAnimations: number;
+    activeCount: number;
+    averageDuration: number;
+  } {
+    const totalAnimations = Inspector.animationHistory.length;
+    const activeCount = Inspector.activeAnimations.size;
+
+    // Calculate average duration from finished animations only
+    const finishedAnimations = Inspector.animationHistory.filter(
+      (anim) => anim.completionType === 'finished',
+    );
+
+    const averageDuration =
+      finishedAnimations.length > 0
+        ? finishedAnimations.reduce(
+            (sum, anim) => sum + anim.actualDuration,
+            0,
+          ) / finishedAnimations.length
+        : 0;
+
+    return {
+      totalAnimations,
+      activeCount,
+      averageDuration,
+    };
+  }
+
+  /**
+   * Clear animation monitoring data
+   */
+  public static clearAnimationStats(): void {
+    Inspector.activeAnimations.clear();
+    Inspector.animationHistory.length = 0;
+  }
+
+  /**
+   * Start the animation stats timer if enabled
+   */
+  private startAnimationStatsTimer(): void {
+    console.log(
+      `Starting animation stats timer with interval: ${this.performanceSettings.animationStatsInterval} seconds`,
+    );
+
+    if (this.performanceSettings.animationStatsInterval > 0) {
+      this.animationStatsTimer = setInterval(() => {
+        this.printAnimationStats();
+      }, this.performanceSettings.animationStatsInterval * 1000) as unknown as number;
+    }
+  }
+
+  /**
+   * Stop the animation stats timer
+   */
+  private stopAnimationStatsTimer(): void {
+    if (this.animationStatsTimer) {
+      clearInterval(this.animationStatsTimer);
+      this.animationStatsTimer = null;
+    }
+  }
+
+  /**
+   * Print current animation statistics to console
+   */
+  private printAnimationStats(): void {
+    const stats = Inspector.getAnimationStats();
+
+    console.log(
+      `🎬 Animation Stats: ${stats.activeCount} active, ${
+        stats.totalAnimations
+      } completed, ${Math.round(stats.averageDuration)}ms avg duration`,
+    );
+  }
   setRootPosition() {
     if (this.root === null || this.canvas === null) {
       return;
@@ -259,6 +742,24 @@ export class Inspector {
     return div;
   }
 
+  createNodes(node: CoreNode): boolean {
+    if (this.root === null) {
+      return false;
+    }
+
+    const div = this.root.querySelector(`[id="${node.id}"]`);
+    if (div === null && node instanceof CoreTextNode) {
+      this.createTextNode(node);
+    } else if (div === null && node instanceof CoreNode) {
+      this.createNode(node);
+    }
+
+    for (const child of node.children) {
+      this.createNodes(child);
+    }
+    return true;
+  }
+
   createNode(node: CoreNode): CoreNode {
     const div = this.createDiv(node.id, node.props);
     (div as HTMLElement & { node: CoreNode }).node = node;
@@ -272,10 +773,13 @@ export class Inspector {
     return this.createProxy(node, div);
   }
 
-  createTextNode(node: CoreNode): CoreTextNode {
-    const div = this.createDiv(node.id, node.props);
+  createTextNode(node: CoreTextNode): CoreTextNode {
+    // eslint-disable-next-line
+    // @ts-ignore - textProps is a private property and keeping it that way
+    // but we need it from the inspector to set the initial properties on the div element
+    const div = this.createDiv(node.id, node.textProps);
     (div as HTMLElement & { node: CoreNode }).node = node;
-    (node as CoreNode & { div: HTMLElement }).div = div;
+    (node as CoreTextNode & { div: HTMLElement }).div = div;
 
     return this.createProxy(node, div) as CoreTextNode;
   }
@@ -304,6 +808,9 @@ export class Inspector {
           return originalProp?.get?.call(node);
         },
         set: (value) => {
+          // Track setter call for performance monitoring
+          this.trackSetterCall(node.id, property);
+
           originalProp?.set?.call(node, value);
           this.updateNodeProperty(
             div,
@@ -323,6 +830,7 @@ export class Inspector {
         this.destroyNode(node.id);
         originalDestroy.call(node);
       },
+      configurable: true,
     });
 
     const originalAnimate = node.animate;
@@ -333,21 +841,39 @@ export class Inspector {
       ): IAnimationController => {
         const animationController = originalAnimate.call(node, props, settings);
 
-        const originalStart =
-          animationController.start.bind(animationController);
-        animationController.start = () => {
-          this.animateNode(div, props, settings);
-
-          return originalStart();
-        };
-
-        return animationController;
+        // Wrap animation controller with monitoring
+        return this.wrapAnimationController(
+          animationController,
+          node.id,
+          props,
+          settings,
+          div,
+        );
       },
+      configurable: true,
     });
 
     return node;
   }
 
+  public destroy() {
+    // Stop animation stats timer
+    this.stopAnimationStatsTimer();
+
+    // Remove DOM observers
+    this.mutationObserver.disconnect();
+    this.resizeObserver.disconnect();
+
+    // Remove resize listener
+    window.removeEventListener('resize', this.setRootPosition.bind(this));
+    if (this.root && this.root.parentNode) {
+      this.root.remove();
+    }
+
+    // Clean up animation monitoring data
+    Inspector.clearAnimationStats();
+  }
+
   destroyNode(id: number) {
     const div = document.getElementById(id.toString());
     div?.remove();
@@ -386,9 +912,11 @@ export class Inspector {
     if (property === 'text') {
       div.innerHTML = String(value);
 
-      // hide text because we can't render SDF fonts
-      // it would look weird and obstruct the WebGL rendering
-      div.style.visibility = 'hidden';
+      // Keep DOM text invisible without breaking visibility checks
+      // Use very low opacity (0.001) instead of 0 so Playwright still detects it
+      div.style.opacity = '0.001';
+      div.style.pointerEvents = 'none';
+      div.style.userSelect = 'none';
       return;
     }
 
@@ -430,14 +958,14 @@ export class Inspector {
         let value = mappedStyleResponse.value;
         if (property === 'x') {
           const mount = props.mountX;
-          const width = props.width;
+          const width = props.w;
 
           if (mount) {
             value = `${parseInt(value) - width * mount}px`;
           }
         } else if (property === 'y') {
           const mount = props.mountY;
-          const height = props.height;
+          const height = props.h;
 
           if (mount) {
             value = `${parseInt(value) - height * mount}px`;
@@ -475,6 +1003,19 @@ export class Inspector {
     }
   }
 
+  updateViewport(
+    width: number,
+    height: number,
+    deviceLogicalPixelRatio: number,
+  ) {
+    this.scaleX = deviceLogicalPixelRatio ?? 1;
+    this.scaleY = deviceLogicalPixelRatio ?? 1;
+
+    this.width = width;
+    this.height = height;
+    this.setRootPosition();
+  }
+
   // simple animation handler
   animateNode(
     div: HTMLElement,
@@ -493,8 +1034,8 @@ export class Inspector {
     const {
       x,
       y,
-      width,
-      height,
+      w,
+      h,
       alpha = 1,
       rotation = 0,
       scale = 1,
@@ -506,10 +1047,10 @@ export class Inspector {
     // ignoring loops and repeats for now, as that might be a bit too much for the inspector
     function animate() {
       setTimeout(() => {
-        div.style.top = `${y - height * mountY}px`;
-        div.style.left = `${x - width * mountX}px`;
-        div.style.width = `${width}px`;
-        div.style.height = `${height}px`;
+        div.style.top = `${y - h * mountY}px`;
+        div.style.left = `${x - w * mountX}px`;
+        div.style.width = `${w}px`;
+        div.style.height = `${h}px`;
         div.style.opacity = `${alpha}`;
         div.style.rotate = `${rotation}rad`;
         div.style.scale = `${scale}`;