@lightningtv/renderer 2.16.1 → 3.2.3

package/src/core/Stage.ts

@@ -1,23 +1,10 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { startLoop, getTimeStamp } from './platform.js';
-import { assertTruthy, setPremultiplyMode } from '../utils.js';
+import {
+  assertTruthy,
+  CALCULATE_FPS,
+  isProductionEnvironment,
+  setPremultiplyMode,
+  USE_RTT,
+} from '../utils.js';
 import { AnimationManager } from './animations/AnimationManager.js';
 import {
   UpdateType,
@@ -26,13 +13,14 @@ import {
   type CoreNodeProps,
 } from './CoreNode.js';
 import { CoreTextureManager } from './CoreTextureManager.js';
-import { TrFontManager } from './text-rendering/TrFontManager.js';
-import { CoreShaderManager, type ShaderMap } from './CoreShaderManager.js';
+import { CoreShaderManager } from './CoreShaderManager.js';
 import {
-  TextRenderer,
-  type TextRendererMap,
+  type FontHandler,
+  type FontLoadOptions,
+  type TextRenderer,
+  type TextRenderers,
   type TrProps,
-} from './text-rendering/renderers/TextRenderer.js';
+} from './text-rendering/TextRenderer.js';
 
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
@@ -45,47 +33,32 @@ import {
   TextureMemoryManager,
   type TextureMemoryManagerSettings,
 } from './TextureMemoryManager.js';
-import type { CoreRendererOptions } from './renderers/CoreRenderer.js';
 import { CoreRenderer } from './renderers/CoreRenderer.js';
-import type { WebGlCoreRenderer } from './renderers/webgl/WebGlCoreRenderer.js';
-import type { CanvasCoreRenderer } from './renderers/canvas/CanvasCoreRenderer.js';
-import type { BaseShaderController } from '../main-api/ShaderController.js';
 import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
 import { santizeCustomDataMap } from '../main-api/utils.js';
-import type { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-import type { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
-import {
-  createBound,
-  createPreloadBounds,
-  pointInBound,
-  type Bound,
-} from './lib/utils.js';
+import { pointInBound } from './lib/utils.js';
+import type { CoreShaderNode } from './renderers/CoreShaderNode.js';
+import { Matrix3d } from './lib/Matrix3d.js';
+import { createBound, createPreloadBounds, type Bound } from './lib/utils.js';
 import type { Texture } from './textures/Texture.js';
 import { ColorTexture } from './textures/ColorTexture.js';
-
-export interface StageOptions {
-  appWidth: number;
-  appHeight: number;
+import type { Platform } from './platforms/Platform.js';
+import type { WebPlatform } from './platforms/web/WebPlatform.js';
+import type { RendererMainSettings } from '../main-api/Renderer.js';
+
+export type StageOptions = Omit<
+  RendererMainSettings,
+  'inspector' | 'platform' | 'maxRetryCount'
+> & {
   textureMemory: TextureMemoryManagerSettings;
-  boundsMargin: number | [number, number, number, number];
-  deviceLogicalPixelRatio: number;
-  devicePhysicalPixelRatio: number;
   canvas: HTMLCanvasElement | OffscreenCanvas;
-  clearColor: number;
   fpsUpdateInterval: number;
-  targetFPS: number;
-  enableContextSpy: boolean;
-  forceWebGL2: boolean;
-  numImageWorkers: number;
-  renderEngine: typeof WebGlCoreRenderer | typeof CanvasCoreRenderer;
   eventBus: EventEmitter;
-  quadBufferSize: number;
-  fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[];
+  platform: Platform | WebPlatform;
   inspector: boolean;
-  strictBounds: boolean;
-  textureProcessingTimeLimit: number;
-  createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
-}
+  maxRetryCount: number;
+  enableClear: boolean;
+};
 
 export type StageFpsUpdateHandler = (
   stage: Stage,
@@ -96,12 +69,12 @@ export type StageFrameTickHandler = (
   stage: Stage,
   frameTickData: FrameTickPayload,
 ) => void;
+
 export interface Point {
   x: number;
   y: number;
 }
 
-const bufferMemory = 2e6;
 const autoStart = true;
 
 export class Stage {
@@ -109,18 +82,21 @@ export class Stage {
   public readonly animationManager: AnimationManager;
   public readonly txManager: CoreTextureManager;
   public readonly txMemManager: TextureMemoryManager;
-  public readonly fontManager: TrFontManager;
-  public readonly textRenderers: Partial<TextRendererMap>;
+  public readonly textRenderers: Record<string, TextRenderer> = {};
+  public readonly fontHandlers: Record<string, FontHandler> = {};
   public readonly shManager: CoreShaderManager;
   public readonly renderer: CoreRenderer;
   public readonly root: CoreNode;
   public readonly interactiveNodes: Set<CoreNode> = new Set();
   public boundsMargin: [number, number, number, number];
-  public readonly defShaderCtr: BaseShaderController;
-  public readonly strictBound: Bound;
-  public readonly preloadBound: Bound;
-  public readonly strictBounds: boolean;
+  public readonly defShaderNode: CoreShaderNode | null = null;
+  public strictBound: Bound;
+  public preloadBound: Bound;
   public readonly defaultTexture: Texture | null = null;
+  public pixelRatio: number;
+  public readonly bufferMemory: number = 2e6;
+  public readonly platform: Platform | WebPlatform;
+  public readonly calculateTextureCoord: boolean;
 
   /**
    * Target frame time in milliseconds (calculated from targetFPS)
@@ -143,24 +119,39 @@ export class Stage {
   public readonly eventBus: EventEmitter;
 
   /// State
+  startTime = 0;
   deltaTime = 0;
   lastFrameTime = 0;
   currentFrameTime = 0;
+  elapsedTime = 0;
+  private timedNodes: CoreNode[] = [];
+  private clrColor = 0x00000000;
   private fpsNumFrames = 0;
   private fpsElapsedTime = 0;
   private numQuadsRendered = 0;
   private renderRequested = false;
+  private reprocessFrame = false;
+  private reprocessCallback: (() => void) | null = null;
   private frameEventQueue: [name: string, payload: unknown][] = [];
-  private fontResolveMap: Record<string, CanvasTextRenderer | SdfTextRenderer> =
-    {};
 
-  /// Debug data
+  // Flattened render list optimization
+  public renderList: CoreNode[] = [];
+  public renderListDirty: boolean = true;
+
+  // Font resolve optimisation flags
+  private hasOnlyOneFontEngine: boolean;
+  private hasOnlyCanvasFontEngine: boolean;
+  private hasCanvasEngine: boolean;
+  private singleFontEngine: TextRenderer | null = null;
+  private singleFontHandler: FontHandler | null = null;
+
+  // Debug data
   contextSpy: ContextSpy | null = null;
 
   /**
    * Stage constructor
    */
-  constructor(readonly options: StageOptions) {
+  constructor(public options: StageOptions) {
     const {
       canvas,
       clearColor,
@@ -174,8 +165,19 @@ export class Stage {
       renderEngine,
       fontEngines,
       createImageBitmapSupport,
+      platform,
+      maxRetryCount,
     } = options;
 
+    assertTruthy(
+      platform !== null,
+      'A CorePlatform is not provided in the options',
+    );
+
+    this.platform = platform;
+
+    this.startTime = platform.getTimeStamp();
+
     this.eventBus = options.eventBus;
 
     // Calculate target frame time from targetFPS option
@@ -184,6 +186,7 @@ export class Stage {
     this.txManager = new CoreTextureManager(this, {
       numImageWorkers,
       createImageBitmapSupport,
+      maxRetryCount,
     });
 
     // Wait for the Texture Manager to initialize
@@ -193,10 +196,9 @@ export class Stage {
     });
 
     this.txMemManager = new TextureMemoryManager(this, textureMemory);
-    this.shManager = new CoreShaderManager();
+
     this.animationManager = new AnimationManager();
     this.contextSpy = enableContextSpy ? new ContextSpy() : null;
-    this.strictBounds = options.strictBounds;
 
     let bm = [0, 0, 0, 0] as [number, number, number, number];
     if (boundsMargin) {
@@ -210,65 +212,118 @@ export class Stage {
     this.strictBound = createBound(0, 0, appWidth, appHeight);
     this.preloadBound = createPreloadBounds(this.strictBound, bm);
 
-    const rendererOptions: CoreRendererOptions = {
+    this.clrColor = clearColor;
+
+    this.pixelRatio =
+      options.devicePhysicalPixelRatio * options.deviceLogicalPixelRatio;
+
+    this.renderer = new renderEngine({
       stage: this,
       canvas,
-      pixelRatio:
-        options.devicePhysicalPixelRatio * options.deviceLogicalPixelRatio,
-      clearColor: clearColor ?? 0xff000000,
-      bufferMemory,
-      txManager: this.txManager,
-      txMemManager: this.txMemManager,
-      shManager: this.shManager,
       contextSpy: this.contextSpy,
       forceWebGL2,
-    };
+    });
+
+    this.shManager = new CoreShaderManager(this);
+
+    this.defShaderNode = this.renderer.getDefaultShaderNode();
+    this.calculateTextureCoord = this.renderer.getTextureCoords !== undefined;
 
-    this.renderer = new renderEngine(rendererOptions);
     const renderMode = this.renderer.mode || 'webgl';
 
     this.createDefaultTexture();
-    this.defShaderCtr = this.renderer.getDefShaderCtr();
     setPremultiplyMode(renderMode);
 
     // Must do this after renderer is created
     this.txManager.renderer = this.renderer;
 
     // Create text renderers
-    this.textRenderers = {};
-    fontEngines.forEach((fontEngineConstructor) => {
-      const fontEngineInstance = new fontEngineConstructor(this);
-      const className = fontEngineInstance.type;
+    this.hasOnlyOneFontEngine = fontEngines.length === 1;
+    this.hasOnlyCanvasFontEngine =
+      fontEngines.length === 1 && fontEngines[0]!.type === 'canvas';
+    this.hasCanvasEngine = false;
+    this.singleFontEngine = this.hasOnlyOneFontEngine
+      ? (fontEngines[0] as TextRenderer)
+      : null;
+    this.singleFontHandler = this.hasOnlyOneFontEngine
+      ? (fontEngines[0]?.font as FontHandler)
+      : null;
+
+    if (this.singleFontEngine === null) {
+      // Multiple font engines case
+      // Filter out incompatible engines first
+      const compatibleEngines = fontEngines.filter(
+        (fontEngine: TextRenderer) => {
+          const type = fontEngine.type;
+
+          if (type === 'sdf' && renderMode === 'canvas') {
+            console.warn(
+              'MsdfTextRenderer is not compatible with Canvas renderer. Skipping...',
+            );
+            return false;
+          }
+
+          if (type === 'canvas') {
+            this.hasCanvasEngine = true;
+          }
+
+          return true;
+        },
+      );
+
+      // Sort engines: SDF first, Canvas last, others in between
+      const sortedEngines = compatibleEngines.sort(
+        (a: TextRenderer, b: TextRenderer) => {
+          if (a.type === 'sdf') return -1;
+          if (b.type === 'sdf') return 1;
+          if (a.type === 'canvas') return 1;
+          if (b.type === 'canvas') return -1;
+          return 0;
+        },
+      );
+
+      // Initialize engines in sorted order
+      sortedEngines.forEach((fontEngine: TextRenderer) => {
+        const type = fontEngine.type;
+
+        // Add to map for type-based access
+        this.textRenderers[type] = fontEngine;
+        this.textRenderers[type].init(this);
+
+        this.fontHandlers[type] = fontEngine.font;
+      });
+    } else {
+      // Single font engine case - initialize it directly
+      const fontEngine = this.singleFontEngine;
+      const type = fontEngine.type;
 
-      if (className === 'sdf' && renderMode === 'canvas') {
+      // Check compatibility
+      if (type === 'sdf' && renderMode === 'canvas') {
         console.warn(
-          'SdfTextRenderer is not compatible with Canvas renderer. Skipping...',
+          'MsdfTextRenderer is not compatible with Canvas renderer. Skipping...',
         );
-        return;
-      }
-
-      if (fontEngineInstance instanceof TextRenderer) {
-        if (className === 'canvas') {
-          this.textRenderers['canvas'] =
-            fontEngineInstance as CanvasTextRenderer;
-        } else if (className === 'sdf') {
-          this.textRenderers['sdf'] = fontEngineInstance as SdfTextRenderer;
+      } else {
+        if (type === 'canvas') {
+          this.hasCanvasEngine = true;
         }
+
+        // Add to map for type-based access
+        this.textRenderers[type] = fontEngine;
+        this.fontHandlers[type] = fontEngine.font;
+        this.textRenderers[type].init(this);
       }
-    });
+    }
 
     if (Object.keys(this.textRenderers).length === 0) {
       console.warn('No text renderers available. Your text will not render.');
     }
 
-    this.fontManager = new TrFontManager(this.textRenderers);
-
     // create root node
     const rootNode = new CoreNode(this, {
       x: 0,
       y: 0,
-      width: appWidth,
-      height: appHeight,
+      w: appWidth,
+      h: appHeight,
       alpha: 1,
       autosize: false,
       boundsMargin: null,
@@ -283,7 +338,6 @@ export class Stage {
       colorBl: 0x00000000,
       colorBr: 0x00000000,
       zIndex: 0,
-      zIndexLocked: 0,
       scaleX: 1,
       scaleY: 1,
       mountX: 0,
@@ -296,23 +350,39 @@ export class Stage {
       parent: null,
       texture: null,
       textureOptions: {},
-      shader: this.defShaderCtr,
+      shader: this.defShaderNode,
       rtt: false,
       src: null,
       scale: 1,
-      preventCleanup: false,
-      strictBounds: this.strictBounds,
     });
 
     this.root = rootNode;
 
+    // Initialize root node properties
+    rootNode.updateLocalTransform();
+    rootNode.globalTransform = Matrix3d.copy(rootNode.localTransform!);
+    rootNode.sceneGlobalTransform = Matrix3d.copy(rootNode.localTransform!);
+    rootNode.calculateRenderCoords();
+    rootNode.updateBoundingRect();
+    rootNode.createRenderBounds();
+    rootNode.updateRenderState(CoreNodeRenderState.InViewport);
+    rootNode.updateIsRenderable();
+
+    // Initialize premultiplied colors (default is transparent 0x00000000)
+    rootNode.premultipliedColorTl =
+      rootNode.premultipliedColorTr =
+      rootNode.premultipliedColorBl =
+      rootNode.premultipliedColorBr =
+        0;
+
     // execute platform start loop
-    if (autoStart) {
-      startLoop(this);
+    if (autoStart === true) {
+      this.platform.startLoop(this);
     }
   }
 
   setClearColor(color: number) {
+    this.clearColor = color;
     this.renderer.updateClearColor(color);
     this.renderRequested = true;
   }
@@ -332,9 +402,10 @@ export class Stage {
   }
 
   updateFrameTime() {
-    const newFrameTime = getTimeStamp();
+    const newFrameTime = this.platform.getTimeStamp();
     this.lastFrameTime = this.currentFrameTime;
     this.currentFrameTime = newFrameTime;
+    this.elapsedTime = newFrameTime - this.startTime;
     this.deltaTime = !this.lastFrameTime
       ? 100 / 6
       : newFrameTime - this.lastFrameTime;
@@ -353,7 +424,6 @@ export class Stage {
    * Create default PixelTexture
    */
   createDefaultTexture() {
-    console.log('Creating default texture');
     (this.defaultTexture as ColorTexture) = this.txManager.createTexture(
       'ColorTexture',
       {
@@ -367,7 +437,7 @@ export class Stage {
     // Mark the default texture as ALWAYS renderable
     // This prevents it from ever being cleaned up.
     // Fixes https://github.com/lightning-js/renderer/issues/262
-    this.defaultTexture.setRenderableOwner(this, true);
+    this.defaultTexture.setRenderableOwner('stage', true);
 
     // When the default texture is loaded, request a render in case the
     // RAF is paused. Fixes: https://github.com/lightning-js/renderer/issues/123
@@ -379,13 +449,14 @@ export class Stage {
   /**
    * Update animations
    */
-  updateAnimations() {
+  updateAnimations(): boolean {
     const { animationManager } = this;
     if (!this.root) {
-      return;
+      return false;
     }
     // step animation
     animationManager.update(this.deltaTime);
+    return animationManager.activeAnimations.size > 0;
   }
 
   /**
@@ -402,55 +473,99 @@ export class Stage {
   /**
    * Start a new frame draw
    */
-  drawFrame() {
-    const { renderer, renderRequested } = this;
-    assertTruthy(renderer);
+  drawFrame(hasActiveAnimations: boolean = false) {
+    const { renderer, renderRequested, root } = this;
 
     // Update tree if needed
-    if (this.root.updateType !== 0) {
-      this.root.update(this.deltaTime, this.root.clippingRect);
-    }
+    do {
+      const forceUpdate = this.reprocessFrame;
+      this.reprocessFrame = false;
+
+      if (root.updateType !== 0 || forceUpdate) {
+        root.updateType = 0;
+        const childUpdateType = root.childUpdateType;
+        root.childUpdateType = 0;
+
+        for (let i = 0, length = root.children.length; i < length; i++) {
+          const child = root.children[i] as CoreNode;
+
+          if (childUpdateType !== 0) {
+            child.setUpdateType(childUpdateType);
+          }
+
+          if (child.updateType === 0) {
+            continue;
+          }
+
+          child.update(this.deltaTime, root.clippingRect);
+        }
+      }
+
+      if (this.reprocessCallback !== null) {
+        this.reprocessCallback();
+        this.reprocessCallback = null;
+      }
+    } while (this.reprocessFrame);
 
     // Process some textures asynchronously but don't block the frame
     // Use a background task to prevent frame drops
-    this.txManager
-      .processSome(this.options.textureProcessingTimeLimit)
-      .catch((err) => {
+    if (this.txManager.hasUpdates() === true) {
+      const timeLimit = hasActiveAnimations
+        ? this.options.textureProcessingTimeLimit / 2
+        : this.options.textureProcessingTimeLimit;
+
+      this.txManager.processSome(timeLimit).catch((err) => {
         console.error('Error processing textures:', err);
       });
+    }
 
     // Reset render operations and clear the canvas
     renderer.reset();
 
-    // Check if we need to cleanup textures
-    if (this.txMemManager.criticalCleanupRequested === true) {
-      this.txMemManager.cleanup(false);
-
-      if (this.txMemManager.criticalCleanupRequested === true) {
-        // If we still need to cleanup, request another but aggressive cleanup
-        this.txMemManager.cleanup(true);
-      }
-    }
-
     // If we have RTT nodes draw them first
     // So we can use them as textures in the main scene
-    if (renderer.rttNodes.length > 0) {
+    if (USE_RTT && renderer.rttNodes.length > 0) {
       renderer.renderRTTNodes();
     }
 
-    // Fill quads buffer
-    this.addQuads(this.root);
+    // Update render list if dirty
+    if (this.renderListDirty === true) {
+      this.renderList.length = 0;
+      this.buildRenderList(this.root);
+      this.renderListDirty = false;
+    } else {
+      // Fill quads buffer
+      const renderList = this.renderList;
+      for (let i = 0, len = renderList.length; i < len; i++) {
+        renderList[i]!.renderQuads(renderer);
+      }
+    }
 
     // Perform render pass
-    renderer?.render();
+    renderer.render();
 
-    this.calculateFps();
-    this.calculateQuads();
+    if (CALCULATE_FPS) {
+      this.calculateFps();
+      this.calculateQuads();
+    }
 
     // Reset renderRequested flag if it was set
-    if (renderRequested) {
+    if (renderRequested === true) {
       this.renderRequested = false;
     }
+
+    if (this.timedNodes.length > 0) {
+      for (let key in this.timedNodes) {
+        if (this.timedNodes[key]!.isRenderable === true) {
+          this.requestRender();
+          break;
+        }
+      }
+    }
+    // Check if we need to cleanup textures
+    if (this.txMemManager.criticalCleanupRequested === true) {
+      this.txMemManager.cleanup();
+    }
   }
 
   /**
@@ -519,30 +634,38 @@ export class Stage {
     }
   }
 
-  addQuads(node: CoreNode) {
-    assertTruthy(this.renderer);
+  requestRenderListUpdate() {
+    // Notify the renderer that the render list is structurally changing.
+    // For the WebGL renderer this resets per-node buffer slot assignments
+    // and schedules a full GPU buffer re-upload on the next frame.
+    if (this.renderer.invalidateQuadBuffer !== undefined) {
+      this.renderer.invalidateQuadBuffer();
+    }
+    this.renderListDirty = true;
+    this.requestRender();
+  }
 
-    // If the node is renderable and has a loaded texture, render it
+  buildRenderList(node: CoreNode) {
+    // If the node is renderable and has a loaded texture, add it
     if (node.isRenderable === true) {
       node.renderQuads(this.renderer);
+      this.renderList.push(node);
     }
 
-    for (let i = 0; i < node.children.length; i++) {
-      const child = node.children[i];
-
-      if (child === undefined) {
-        continue;
-      }
+    const children = node.children;
+    const len = children.length;
+    for (let i = 0; i < len; i++) {
+      const child = children[i] as CoreNode;
 
+      // Skip invisible subtrees
       if (
         child.worldAlpha === 0 ||
-        (child.strictBounds === true &&
-          child.renderState === CoreNodeRenderState.OutOfBounds)
+        child.renderState === CoreNodeRenderState.OutOfBounds
       ) {
         continue;
       }
 
-      this.addQuads(child);
+      this.buildRenderList(child);
     }
   }
 
@@ -553,42 +676,11 @@ export class Stage {
     this.renderRequested = true;
   }
 
-  /**
-   * Find all nodes at a given point
-   * @param data
-   */
-  findNodesAtPoint(data: Point): CoreNode[] {
-    const x = data.x / this.options.deviceLogicalPixelRatio;
-    const y = data.y / this.options.deviceLogicalPixelRatio;
-    const nodes: CoreNode[] = [];
-    for (const node of this.interactiveNodes) {
-      if (node.isRenderable === false) {
-        continue;
-      }
-      if (pointInBound(x, y, node.renderBound!) === true) {
-        nodes.push(node);
-      }
+  reprocessUpdates(callback?: () => void) {
+    this.reprocessFrame = true;
+    if (callback) {
+      this.reprocessCallback = callback;
     }
-    return nodes;
-  }
-
-  /**
-   * Find the top node at a given point
-   * @param data
-   * @returns
-   */
-  getNodeFromPosition(data: Point): CoreNode | null {
-    const nodes: CoreNode[] = this.findNodesAtPoint(data);
-    if (nodes.length === 0) {
-      return null;
-    }
-    let topNode = nodes[0] as CoreNode;
-    for (let i = 0; i < nodes.length; i++) {
-      if (nodes[i]!.zIndex > topNode.zIndex) {
-        topNode = nodes[i]!;
-      }
-    }
-    return topNode || null;
   }
 
   /**
@@ -603,86 +695,52 @@ export class Stage {
    */
   resolveTextRenderer(
     trProps: TrProps,
-    textRendererOverride: keyof TextRendererMap | null = null,
+    textRendererOverride: keyof TextRenderers | null = null,
   ): TextRenderer | null {
-    const fontCacheString = `${trProps.fontFamily}${trProps.fontStyle}${
-      trProps.fontWeight
-    }${trProps.fontStretch}${textRendererOverride ? textRendererOverride : ''}`;
+    // If we have an overide, return it
+    if (textRendererOverride !== null) {
+      const overrideKey = String(textRendererOverride);
+      if (this.textRenderers[overrideKey] === undefined) {
+        console.warn(`Text renderer override '${overrideKey}' not found.`);
+        return null;
+      }
 
-    // check our resolve cache first
-    if (this.fontResolveMap[fontCacheString] !== undefined) {
-      return this.fontResolveMap[fontCacheString] as unknown as TextRenderer;
+      return this.textRenderers[overrideKey];
     }
 
-    // Resolve the text renderer
-    let rendererId = textRendererOverride;
-    let overrideFallback = false;
-
-    // Check if the override is valid (if one is provided)
-    if (rendererId) {
-      const possibleRenderer = this.textRenderers[rendererId];
-      if (!possibleRenderer) {
-        console.warn(`Text renderer override '${rendererId}' not found.`);
-        rendererId = null;
-        overrideFallback = true;
-      } else if (!possibleRenderer.canRenderFont(trProps)) {
-        console.warn(
-          `Cannot use override text renderer '${rendererId}' for font`,
-          trProps,
-        );
-        rendererId = null;
-        overrideFallback = true;
+    // If we have only one font engine early return it
+    if (this.singleFontEngine !== null) {
+      // If we have only one font engine and its the canvas engine, we can just return it
+      if (this.hasOnlyCanvasFontEngine === true) {
+        return this.singleFontEngine;
       }
-    }
 
-    if (!rendererId) {
-      // Iterate through the text renderers and find the first one that can render the font
-      for (const [trId, tr] of Object.entries(this.textRenderers)) {
-        if (tr.canRenderFont(trProps)) {
-          rendererId = trId as keyof TextRendererMap;
-          break;
-        }
+      // If we have only one font engine and it can render the font, return it
+      if (this.singleFontHandler?.canRenderFont(trProps) === true) {
+        return this.singleFontEngine;
       }
-      if (!rendererId && this.textRenderers.canvas !== undefined) {
-        // If no renderer can be found, use the canvas renderer
-        rendererId = 'canvas';
-      }
-    }
 
-    if (overrideFallback) {
-      console.warn(`Falling back to text renderer ${String(rendererId)}`);
-    }
+      // If we have only one font engine and it cannot render the font, return null
+      console.warn(`Text renderer cannot render font`, trProps);
 
-    if (!rendererId) {
-      // silently fail if no renderer can be found, the error is already created
-      // at the constructor level
       return null;
     }
 
-    // By now we are guaranteed to have a valid rendererId (at least Canvas);
-    const resolvedTextRenderer = this.textRenderers[rendererId];
-    assertTruthy(resolvedTextRenderer, 'resolvedTextRenderer undefined');
+    // Multi font handling  - If we have multiple font engines, we need to resolve the best one
 
-    // cache the resolved renderer for future use with these trProps
-    this.fontResolveMap[fontCacheString] = resolvedTextRenderer;
+    // First check SDF
+    if (this.fontHandlers['sdf']?.canRenderFont(trProps) === true) {
+      return this.textRenderers.sdf || null;
+    }
 
-    // Need to explicitly cast to TextRenderer because TS doesn't like
-    // the covariant state argument in the setter method map
-    return resolvedTextRenderer as unknown as TextRenderer;
-  }
+    // If we have a canvas engine, we can return it (it can render all fonts)
+    if (this.hasCanvasEngine === true) {
+      return this.textRenderers.canvas || null;
+    }
 
-  /**
-   * Create a shader controller instance
-   *
-   * @param type
-   * @param props
-   * @returns
-   */
-  createShaderCtr(
-    type: keyof ShaderMap,
-    props: Record<string, unknown>,
-  ): BaseShaderController {
-    return this.shManager.loadShader(type, props);
+    // If we have no font engines, return null
+    console.warn('No text renderers available. Your text will not render.');
+    return null;
   }
 
   createNode(props: Partial<CoreNodeProps>) {
@@ -691,34 +749,30 @@ export class Stage {
   }
 
   createTextNode(props: Partial<CoreTextNodeProps>) {
-    const fontSize = props.fontSize ?? 16;
-    const resolvedProps = {
-      ...this.resolveNodeDefaults(props),
-      text: props.text ?? '',
-      textRendererOverride: props.textRendererOverride ?? null,
-      fontSize,
-      fontFamily: props.fontFamily ?? 'sans-serif',
-      fontStyle: props.fontStyle ?? 'normal',
-      fontWeight: props.fontWeight ?? 'normal',
-      fontStretch: props.fontStretch ?? 'normal',
-      textAlign: props.textAlign ?? 'left',
-      contain: props.contain ?? 'none',
-      scrollable: props.scrollable ?? false,
-      scrollY: props.scrollY ?? 0,
-      offsetY: props.offsetY ?? 0,
-      letterSpacing: props.letterSpacing ?? 0,
-      lineHeight: props.lineHeight, // `undefined` is a valid value
-      maxLines: props.maxLines ?? 0,
-      textBaseline: props.textBaseline ?? 'alphabetic',
-      verticalAlign: props.verticalAlign ?? 'middle',
-      overflowSuffix: props.overflowSuffix ?? '...',
-      debug: props.debug ?? {},
-      shaderProps: null,
-    };
+    const fontSize = props.fontSize || 16;
+    const resolvedProps = this.resolveNodeDefaults(props) as CoreTextNodeProps;
+
+    resolvedProps.text = props.text ?? '';
+    resolvedProps.textRendererOverride = props.textRendererOverride ?? null;
+    resolvedProps.fontSize = fontSize;
+    resolvedProps.fontFamily = props.fontFamily || 'sans-serif';
+    resolvedProps.fontStyle = props.fontStyle || 'normal';
+    resolvedProps.textAlign = props.textAlign || 'left';
+    resolvedProps.offsetY = props.offsetY || 0;
+    resolvedProps.letterSpacing = props.letterSpacing || 0;
+    resolvedProps.lineHeight = props.lineHeight || 1.2;
+    resolvedProps.maxLines = props.maxLines || 0;
+    resolvedProps.verticalAlign = props.verticalAlign || 'top';
+    resolvedProps.overflowSuffix = props.overflowSuffix || '...';
+    resolvedProps.wordBreak = props.wordBreak || 'break-word';
+    resolvedProps.contain = props.contain || 'none';
+    resolvedProps.maxWidth = props.maxWidth || 0;
+    resolvedProps.maxHeight = props.maxHeight || 0;
+    resolvedProps.forceLoad = props.forceLoad || false;
 
     const resolvedTextRenderer = this.resolveTextRenderer(
       resolvedProps,
-      props.textRendererOverride,
+      resolvedProps.textRendererOverride as keyof TextRenderers | null,
     );
 
     if (!resolvedTextRenderer) {
@@ -735,7 +789,84 @@ export class Stage {
       ? value
       : [value, value, value, value];
 
-    this.root.setUpdateType(UpdateType.RenderBounds);
+    this.updateViewportBounds();
+  }
+
+  /**
+   * Update the viewport bounds
+   */
+  updateViewportBounds() {
+    const { appWidth, appHeight } = this.options;
+    this.strictBound = createBound(0, 0, appWidth, appHeight);
+    this.preloadBound = createPreloadBounds(
+      this.strictBound,
+      this.boundsMargin,
+    );
+    this.root.setUpdateType(UpdateType.RenderBounds | UpdateType.Children);
+    this.root.childUpdateType |= UpdateType.RenderBounds;
+  }
+
+  /** Find all nodes at a given point
+   * @param data
+   */
+  findNodesAtPoint(data: Point): CoreNode[] {
+    const x = data.x / this.options.deviceLogicalPixelRatio;
+    const y = data.y / this.options.deviceLogicalPixelRatio;
+    const nodes: CoreNode[] = [];
+    for (const node of this.interactiveNodes) {
+      if (node.isRenderable === false) {
+        continue;
+      }
+      if (pointInBound(x, y, node.renderBound!) === true) {
+        nodes.push(node);
+      }
+    }
+    return nodes;
+  }
+
+  /**
+   * Find the top node at a given point
+   * @param data
+   * @returns
+   */
+  getNodeFromPosition(data: Point): CoreNode | null {
+    const nodes: CoreNode[] = this.findNodesAtPoint(data);
+    if (nodes.length === 0) {
+      return null;
+    }
+
+    //get last node in array (as top node)
+    let topNode = nodes[nodes.length - 1] as CoreNode;
+    for (let i = 0; i < nodes.length; i++) {
+      if (nodes[i]!.zIndex > topNode.zIndex) {
+        topNode = nodes[i]!;
+      }
+    }
+    return topNode || null;
+  }
+
+  /**
+   * add node to timeNodes arrays
+   * @param node
+   * @returns
+   */
+  trackTimedNode(node: CoreNode) {
+    if (this.timedNodes[node.id] !== undefined) {
+      return;
+    }
+    this.timedNodes[node.id] = node;
+  }
+
+  /**
+   * remove node from timeNodes arrays
+   * @param node
+   * @returns
+   */
+  untrackTimedNode(node: CoreNode) {
+    if (this.timedNodes[node.id] === undefined) {
+      return;
+    }
+    delete this.timedNodes[node.id];
   }
 
   /**
@@ -751,66 +882,96 @@ export class Stage {
    */
   protected resolveNodeDefaults(props: Partial<CoreNodeProps>): CoreNodeProps {
     const color = props.color ?? 0xffffffff;
-    const colorTl = props.colorTl ?? props.colorTop ?? props.colorLeft ?? color;
-    const colorTr =
-      props.colorTr ?? props.colorTop ?? props.colorRight ?? color;
-    const colorBl =
-      props.colorBl ?? props.colorBottom ?? props.colorLeft ?? color;
-    const colorBr =
-      props.colorBr ?? props.colorBottom ?? props.colorRight ?? color;
-
-    let data = {};
-    if (this.options.inspector === true) {
-      data = santizeCustomDataMap(props.data ?? {});
+    let colorTop = color;
+    let colorBottom = color;
+    let colorLeft = color;
+    let colorRight = color;
+    let colorTl = color;
+    let colorTr = color;
+    let colorBl = color;
+    let colorBr = color;
+
+    // Fast-path: Check if any complex color props are present
+    // We check values directly to avoid destructuring
+    if (
+      props.colorTop !== undefined ||
+      props.colorBottom !== undefined ||
+      props.colorLeft !== undefined ||
+      props.colorRight !== undefined ||
+      props.colorTl !== undefined ||
+      props.colorTr !== undefined ||
+      props.colorBl !== undefined ||
+      props.colorBr !== undefined
+    ) {
+      const {
+        colorTop: top,
+        colorBottom: bottom,
+        colorLeft: left,
+        colorRight: right,
+      } = props;
+
+      colorTop = top ?? color;
+      colorBottom = bottom ?? color;
+      colorLeft = left ?? color;
+      colorRight = right ?? color;
+
+      colorTl = props.colorTl ?? top ?? left ?? color;
+      colorTr = props.colorTr ?? top ?? right ?? color;
+      colorBl = props.colorBl ?? bottom ?? left ?? color;
+      colorBr = props.colorBr ?? bottom ?? right ?? color;
     }
 
+    const scale = props.scale ?? null;
+    const mount = props.mount ?? 0;
+    const pivot = props.pivot ?? 0.5;
+
+    const data =
+      !isProductionEnvironment && this.options.inspector
+        ? santizeCustomDataMap(props.data ?? {})
+        : {};
+
     return {
       x: props.x ?? 0,
       y: props.y ?? 0,
-      width: props.width ?? 0,
-      height: props.height ?? 0,
+      w: props.w ?? 0,
+      h: props.h ?? 0,
       alpha: props.alpha ?? 1,
       autosize: props.autosize ?? false,
       boundsMargin: props.boundsMargin ?? null,
       clipping: props.clipping ?? false,
       color,
-      colorTop: props.colorTop ?? color,
-      colorBottom: props.colorBottom ?? color,
-      colorLeft: props.colorLeft ?? color,
-      colorRight: props.colorRight ?? color,
-      colorBl,
-      colorBr,
+      colorTop,
+      colorBottom,
+      colorLeft,
+      colorRight,
       colorTl,
       colorTr,
+      colorBl,
+      colorBr,
       zIndex: props.zIndex ?? 0,
-      zIndexLocked: props.zIndexLocked ?? 0,
       parent: props.parent ?? null,
       texture: props.texture ?? null,
       textureOptions: props.textureOptions ?? {},
-      shader: props.shader ?? this.defShaderCtr,
-      // Since setting the `src` will trigger a texture load, we need to set it after
-      // we set the texture. Otherwise, problems happen.
+      shader: props.shader ?? this.defShaderNode,
       src: props.src ?? null,
       srcHeight: props.srcHeight,
       srcWidth: props.srcWidth,
       srcX: props.srcX,
       srcY: props.srcY,
-      scale: props.scale ?? null,
-      scaleX: props.scaleX ?? props.scale ?? 1,
-      scaleY: props.scaleY ?? props.scale ?? 1,
-      mount: props.mount ?? 0,
-      mountX: props.mountX ?? props.mount ?? 0,
-      mountY: props.mountY ?? props.mount ?? 0,
-      pivot: props.pivot ?? 0.5,
-      pivotX: props.pivotX ?? props.pivot ?? 0.5,
-      pivotY: props.pivotY ?? props.pivot ?? 0.5,
+      scale,
+      scaleX: props.scaleX ?? scale ?? 1,
+      scaleY: props.scaleY ?? scale ?? 1,
+      mount,
+      mountX: props.mountX ?? mount,
+      mountY: props.mountY ?? mount,
+      pivot,
+      pivotX: props.pivotX ?? pivot,
+      pivotY: props.pivotY ?? pivot,
       rotation: props.rotation ?? 0,
       rtt: props.rtt ?? false,
-      data: data,
-      preventCleanup: props.preventCleanup ?? false,
+      data,
       imageType: props.imageType,
       interactive: props.interactive ?? false,
-      strictBounds: props.strictBounds ?? this.strictBounds,
     };
   }
 
@@ -820,7 +981,50 @@ export class Stage {
    * @remarks
    * This method is used to cleanup orphaned textures that are no longer in use.
    */
-  cleanup(aggressive: boolean) {
-    this.txMemManager.cleanup(aggressive);
+  cleanup(full: boolean = false) {
+    this.txMemManager.cleanup(full);
+  }
+
+  set clearColor(value: number) {
+    this.renderer.updateClearColor(value);
+    this.renderRequested = true;
+    this.clrColor = value;
+  }
+
+  get clearColor() {
+    return this.clrColor;
+  }
+
+  /**
+   * Load a font using a specific text renderer type
+   *
+   * @remarks
+   * This method allows consumers to explicitly load fonts for a specific
+   * text renderer type (e.g., 'canvas', 'sdf'). Consumers must specify
+   * the renderer type to ensure fonts are loaded with the correct pipeline.
+   *
+   * For Canvas fonts, provide fontUrl (e.g., .ttf, .woff, .woff2)
+   * For SDF fonts, provide atlasUrl (image) and atlasDataUrl (JSON glyph data)
+   *
+   * @param rendererType - The type of text renderer ('canvas', 'sdf', etc.)
+   * @param options - Font loading options specific to the renderer type
+   * @returns Promise that resolves when the font is loaded
+   */
+  async loadFont(
+    rendererType: TextRenderers,
+    options: FontLoadOptions,
+  ): Promise<void> {
+    const rendererTypeKey = String(rendererType);
+    const fontHandler = this.fontHandlers[rendererTypeKey];
+
+    if (!fontHandler) {
+      throw new Error(
+        `Font handler for renderer type '${rendererTypeKey}' not found. Available types: ${Object.keys(
+          this.fontHandlers,
+        ).join(', ')}`,
+      );
+    }
+
+    return fontHandler.loadFont(this, options);
   }
 }