@solidtv/renderer 1.6.1 → 1.6.2

package/src/core/text-rendering/CanvasFontHandler.ts

@@ -65,37 +65,57 @@ export const loadFont = (
 ): Promise<void> => {
   const { fontFamily, fontUrl, metrics } = options;
 
+  // A single load may register the font under several names. The first entry
+  // is the primary name used to key the in-flight promise; the rest are
+  // aliases registered against the same source URL (the browser dedupes the
+  // download by URL).
+  const names = Array.isArray(fontFamily) ? fontFamily : [fontFamily];
+  const primary = names[0]!;
+
   // If already loaded, return immediately
-  if (fontCache.has(fontFamily) === true) {
+  if (fontCache.has(primary) === true) {
     return Promise.resolve();
   }
 
-  const existingPromise = fontLoadPromises.get(fontFamily);
+  const existingPromise = fontLoadPromises.get(primary);
   // If already loading, return the existing promise
   if (existingPromise !== undefined) {
     return existingPromise;
   }
 
-  const nwff: CoreTextNode[] = (nodesWaitingForFont[fontFamily] = []);
-  // Create and store the loading promise
-  const loadPromise = new FontFace(fontFamily, `url(${fontUrl})`)
-    .load()
-    .then((loadedFont) => {
-      stage.platform.addFont(loadedFont);
-      processFontData(fontFamily, loadedFont, metrics);
-      fontLoadPromises.delete(fontFamily);
-      for (let key in nwff) {
-        nwff[key]!.setUpdateType(UpdateType.Local);
+  for (let i = 0; i < names.length; i++) {
+    nodesWaitingForFont[names[i]!] = [];
+  }
+  // Register a FontFace under every name (all share the same source URL) and
+  // wait for all of them to be ready before waking parked nodes.
+  const loadPromise = Promise.all(
+    names.map((name) =>
+      new FontFace(name, `url(${fontUrl})`).load().then((loadedFont) => {
+        stage.platform.addFont(loadedFont);
+        processFontData(name, loadedFont, metrics);
+      }),
+    ),
+  )
+    .then(() => {
+      fontLoadPromises.delete(primary);
+      for (let i = 0; i < names.length; i++) {
+        const name = names[i]!;
+        const nwff = nodesWaitingForFont[name];
+        if (nwff !== undefined) {
+          for (let key in nwff) {
+            nwff[key]!.setUpdateType(UpdateType.Local);
+          }
+          delete nodesWaitingForFont[name];
+        }
       }
-      delete nodesWaitingForFont[fontFamily];
     })
     .catch((error) => {
-      fontLoadPromises.delete(fontFamily);
-      console.error(`Failed to load font: ${fontFamily}`, error);
+      fontLoadPromises.delete(primary);
+      console.error(`Failed to load font: ${primary}`, error);
       throw error;
     });
 
-  fontLoadPromises.set(fontFamily, loadPromise);
+  fontLoadPromises.set(primary, loadPromise);
   return loadPromise;
 };
 

package/src/core/text-rendering/SdfFontHandler.ts

@@ -309,30 +309,39 @@ export const loadFont = (
   options: FontLoadOptions,
 ): Promise<void> => {
   const { fontFamily, atlasUrl, atlasDataUrl, metrics } = options;
+  // A single load may register the font under several names (the atlas is
+  // fetched once and shared). The first entry is the primary name used to key
+  // the in-flight promise and drive the fetch; the rest are aliases.
+  const names = Array.isArray(fontFamily) ? fontFamily : [fontFamily];
+  const primary = names[0]!;
+
   // Early return if already loaded
-  if (fontCache.get(fontFamily) !== undefined) {
+  if (fontCache.get(primary) !== undefined) {
     return Promise.resolve();
   }
 
   // Early return if already loading
-  const existingPromise = fontLoadPromises.get(fontFamily);
+  const existingPromise = fontLoadPromises.get(primary);
   if (existingPromise !== undefined) {
     return existingPromise;
   }
 
   if (atlasDataUrl === undefined) {
     return Promise.reject(
-      new Error(`Atlas data URL must be provided for SDF font: ${fontFamily}`),
+      new Error(`Atlas data URL must be provided for SDF font: ${primary}`),
     );
   }
 
-  // Reuse an existing waiter list. A previous load attempt for this font may
-  // have failed and left nodes parked here; overwriting the list would strand
-  // them, so a successful retry could never wake them. The list is consumed
-  // (and deleted) on the next successful load.
-  let nwff = nodesWaitingForFont[fontFamily];
-  if (nwff === undefined) {
-    nwff = nodesWaitingForFont[fontFamily] = [];
+  // Ensure every name has a waiter list so nodes requesting an alias can park
+  // and be woken on load. Reuse existing lists — a previous load attempt for a
+  // name may have failed and left nodes parked there; overwriting the list
+  // would strand them, so a successful retry could never wake them. Lists are
+  // consumed (and deleted) on the next successful load.
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i]!;
+    if (nodesWaitingForFont[name] === undefined) {
+      nodesWaitingForFont[name] = [];
+    }
   }
   // One attempt at fetching + decoding the JSON atlas description. A fresh
   // XHR runs per attempt so a transient network/parse failure can recover.
@@ -390,17 +399,34 @@ export const loadFont = (
         premultiplyAlpha: false,
       });
 
-      atlasTexture.setRenderableOwner(fontFamily, true);
+      // Register every name as a renderable owner so the shared atlas stays
+      // alive as long as any of its names is in use.
+      for (let i = 0; i < names.length; i++) {
+        atlasTexture.setRenderableOwner(names[i]!, true);
+      }
       atlasTexture.preventCleanup = true; // Prevent automatic cleanup
 
       const onLoaded = () => {
-        // Process and cache font data
-        processFontData(fontFamily, fontData, atlasTexture, metrics);
+        // Process and cache font data under the primary name...
+        processFontData(primary, fontData, atlasTexture, metrics);
+        // ...then alias the remaining names onto the same cache entry so they
+        // resolve to the identical glyph/kerning/atlas data.
+        const cached = fontCache.get(primary)!;
+        for (let i = 1; i < names.length; i++) {
+          fontCache.set(names[i]!, cached);
+        }
 
-        for (let key in nwff) {
-          nwff[key]!.setUpdateType(UpdateType.Local);
+        // Wake every parked node across all names and clear their lists.
+        for (let i = 0; i < names.length; i++) {
+          const name = names[i]!;
+          const list = nodesWaitingForFont[name];
+          if (list !== undefined) {
+            for (let key in list) {
+              list[key]!.setUpdateType(UpdateType.Local);
+            }
+            delete nodesWaitingForFont[name];
+          }
         }
-        delete nodesWaitingForFont[fontFamily];
         resolve();
       };
 
@@ -419,7 +445,9 @@ export const loadFont = (
       atlasTexture.on('failed', (_target, error: TextureError) => {
         // Drop the failed atlas so a retry builds a fresh texture rather than
         // getting this dead instance back from the createTexture key-cache.
-        atlasTexture.setRenderableOwner(fontFamily, false);
+        for (let i = 0; i < names.length; i++) {
+          atlasTexture.setRenderableOwner(names[i]!, false);
+        }
         stage.txManager.removeTextureFromCache(atlasTexture);
         reject(error);
       });
@@ -434,15 +462,15 @@ export const loadFont = (
         await loadAtlas(await fetchFontData());
         // Success: clear the in-flight marker (the font now lives in fontCache)
         // — parked nodes were already woken inside loadAtlas.
-        fontLoadPromises.delete(fontFamily);
+        fontLoadPromises.delete(primary);
         return;
       } catch (error) {
         lastError = error;
         if (attempt < MAX_FONT_LOAD_RETRIES) {
           console.warn(
-            `SDF font "${fontFamily}" failed to load (attempt ${
-              attempt + 1
-            } of ${MAX_FONT_LOAD_RETRIES + 1}), retrying.`,
+            `SDF font "${primary}" failed to load (attempt ${attempt + 1} of ${
+              MAX_FONT_LOAD_RETRIES + 1
+            }), retrying.`,
             error,
           );
         }
@@ -455,13 +483,15 @@ export const loadFont = (
     // loadFont() (which reuses the list) can still wake them if the font
     // eventually loads. The list shrinks as nodes self-remove via
     // stopWaitingForFont on destroy.
-    fontLoadPromises.delete(fontFamily);
-    fontCache.delete(fontFamily);
-    console.error(`Failed to load SDF font: ${fontFamily}`, lastError);
+    fontLoadPromises.delete(primary);
+    for (let i = 0; i < names.length; i++) {
+      fontCache.delete(names[i]!);
+    }
+    console.error(`Failed to load SDF font: ${primary}`, lastError);
     throw lastError;
   })();
 
-  fontLoadPromises.set(fontFamily, loadPromise);
+  fontLoadPromises.set(primary, loadPromise);
   return loadPromise;
 };
 

package/src/core/text-rendering/TextRenderer.ts

@@ -349,7 +349,16 @@ export interface TextLayout {
 }
 
 export interface FontLoadOptions {
-  fontFamily: string;
+  /**
+   * Font family name to register the font under.
+   *
+   * Pass an array to register the same font under several names in a single
+   * load — the atlas/font resource is fetched once and every name resolves to
+   * the same loaded font. The first entry is the primary name; the rest are
+   * aliases. Useful when one physical font is referenced by multiple families
+   * (e.g. `['Roboto', 'Roboto500']`).
+   */
+  fontFamily: string | string[];
   metrics?: FontMetrics;
   // For Canvas/traditional font loading
   fontUrl?: string;

package/src/core/text-rendering/tests/SdfFontHandler.test.ts

@@ -3,6 +3,7 @@ import {
   loadFont,
   waitingForFont,
   isFontLoaded,
+  getFontData,
   MAX_FONT_LOAD_RETRIES,
 } from '../SdfFontHandler.js';
 import { EventEmitter } from '../../../common/EventEmitter.js';
@@ -71,7 +72,7 @@ function makeStage(): { stage: Stage; textures: FakeTexture[] } {
   return { stage, textures };
 }
 
-const opts = (fontFamily: string) =>
+const opts = (fontFamily: string | string[]) =>
   ({
     fontFamily,
     atlasUrl: 'atlas.png',
@@ -256,3 +257,66 @@ describe('SdfFontHandler loadFont — automatic retry', () => {
     expect(node.setUpdateType).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('SdfFontHandler loadFont — multiple names for one font', () => {
+  let originalXHR: unknown;
+
+  beforeEach(() => {
+    originalXHR = (globalThis as unknown as { XMLHttpRequest: unknown })
+      .XMLHttpRequest;
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      FakeXHR;
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      originalXHR;
+  });
+
+  it('fetches once and registers every name against the same font data', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['Roboto', 'Roboto500', 'RobotoMedium'];
+
+    const promise = loadFont(stage, opts(names));
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    // A single atlas texture was created for all three names.
+    expect(textures.length).toBe(1);
+
+    // Every name reports loaded and resolves to the identical cache entry.
+    const primaryData = getFontData(names[0]!);
+    expect(primaryData).not.toBe(undefined);
+    for (let i = 0; i < names.length; i++) {
+      expect(isFontLoaded(names[i]!)).toBe(true);
+      expect(getFontData(names[i]!)).toBe(primaryData);
+    }
+  });
+
+  it('wakes nodes parked under an alias, not just the primary name', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['MultiWakePrimary', 'MultiWakeAlias'];
+
+    const promise = loadFont(stage, opts(names));
+
+    // Park one node under the primary name and one under the alias.
+    const primaryNode = { id: 1, setUpdateType: vi.fn() };
+    const aliasNode = { id: 2, setUpdateType: vi.fn() };
+    waitingForFont(
+      names[0]!,
+      primaryNode as unknown as Parameters<typeof waitingForFont>[1],
+    );
+    waitingForFont(
+      names[1]!,
+      aliasNode as unknown as Parameters<typeof waitingForFont>[1],
+    );
+
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    expect(primaryNode.setUpdateType).toHaveBeenCalledTimes(1);
+    expect(aliasNode.setUpdateType).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/textures/ImageTexture.test.ts

@@ -2,26 +2,70 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ImageTexture } from './ImageTexture.js';
 import type { CoreTextureManager } from '../CoreTextureManager.js';
 
+const makeTxManager = (
+  imageBitmapSupported: {
+    basic: boolean;
+    options: boolean;
+    full: boolean;
+    premultiplyHonored: boolean | null;
+  },
+  createImageBitmapMock: () => Promise<unknown>,
+) =>
+  ({
+    imageBitmapSupported,
+    platform: {
+      createImageBitmap: createImageBitmapMock,
+    },
+  } as unknown as CoreTextureManager);
+
 describe('ImageTexture.createImageBitmap', () => {
   beforeEach(() => {
     vi.stubGlobal('ImageBitmap', class {});
   });
 
-  it('passes options to createImageBitmap when no crop is requested and options/full are supported', async () => {
+  it('requests a premultiplied bitmap when options are supported and the option is honored', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: true },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
+      premultiplyAlpha: 'premultiply',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+
+    // The bitmap is already premultiplied; WebGL must not premultiply again
+    expect(result.premultiplyAlpha).toBe(false);
+  });
+
+  it('requests a straight bitmap and defers premultiply to WebGL when the option is not honored', async () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: true,
-        full: true,
-        premultiplyHonored: false,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -39,14 +83,13 @@ describe('ImageTexture.createImageBitmap', () => {
       null,
     );
 
-    // It should have called createImageBitmap with the options object
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
       premultiplyAlpha: 'none',
       colorSpaceConversion: 'none',
       imageOrientation: 'none',
     });
 
-    // Since premultiplyHonored is false, useGlPremultiply should be true
+    // Since premultiplyHonored is false, WebGL premultiplies on upload
     expect(result.premultiplyAlpha).toBe(true);
   });
 
@@ -54,17 +97,10 @@ describe('ImageTexture.createImageBitmap', () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: false,
-        full: false,
-        premultiplyHonored: null,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: null },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -85,7 +121,39 @@ describe('ImageTexture.createImageBitmap', () => {
     // It should have called basic createImageBitmap without options
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
 
-    // And premultiplyAlpha should be false (browser default is assumed to premultiply)
+    // The browser default is assumed to premultiply; WebGL must not premultiply again
     expect(result.premultiplyAlpha).toBe(false);
   });
+
+  it('defers premultiply to WebGL on basic-only devices when premultiplyAlphaHonored is false', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    // Still the basic call — no options are supported on these devices
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
+
+    // Device default returns straight alpha; WebGL premultiplies on upload
+    expect(result.premultiplyAlpha).toBe(true);
+  });
 });

package/src/core/textures/ImageTexture.ts

@@ -225,10 +225,12 @@ export class ImageTexture extends Texture {
     ) {
       // basic createImageBitmap without options or crop
       // this is supported for Chrome v50 to v52/54 that doesn't support options.
-      // The browser default premultiplies, so WebGL must not premultiply again.
+      // The browser default premultiplies, so WebGL must not premultiply again —
+      // except on devices whose default returns straight alpha
+      // (premultiplyAlphaHonored: false); there WebGL premultiplies on upload.
       return {
         data: await this.platform.createImageBitmap(blob),
-        premultiplyAlpha: false,
+        premultiplyAlpha: useGlPremultiply,
       };
     }
 

package/src/main-api/Renderer.ts

@@ -654,12 +654,16 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * ignore it, returning straight (non-premultiplied) alpha. This causes edge
    * "ghosting" on images with transparency.
    *
-   * Set to `'auto'` to detect via a cheap startup probe (one 1×1 texture
-   * upload + framebuffer readback). Set to a boolean to force the value. Leave
-   * unset to assume the option is honored — the default, which preserves
-   * existing behavior with no probe overhead.
-   *
-   * @defaultValue `true` (assume honored; no probe)
+   * `'auto'` (the default) detects via a cheap startup probe (one 1×1 PNG
+   * decode + texture upload + framebuffer readback). On devices that honor the
+   * option — the vast majority — the probe returns `true` and behavior is
+   * identical to assuming it honored; only devices that actually ignore it
+   * (e.g. the Movistar STB) switch to the WebGL-side premultiply fallback, so
+   * the change is invisible everywhere it isn't needed. Set to a boolean to
+   * force the value and skip the probe (`false` forces the GL-premultiply
+   * fallback; `true` skips it).
+   *
+   * @defaultValue `'auto'` (probe once at startup)
    */
   premultiplyAlphaHonored?: boolean | 'auto';
 
@@ -821,11 +825,11 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'auto',
-      // undefined -> true (assume honored, no probe); 'auto' -> probe;
-      // explicit boolean -> force the value.
+      // undefined -> 'auto' (probe once at startup); 'auto' -> probe;
+      // explicit boolean -> force the value, skip the probe.
       premultiplyAlphaHonored:
         settings.premultiplyAlphaHonored === undefined
-          ? true
+          ? 'auto'
           : settings.premultiplyAlphaHonored,
       platform: settings.platform || null,
       maxRetryCount: settings.maxRetryCount ?? 5,