@solidtv/renderer 1.6.2 → 1.6.3

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

@@ -13,6 +13,7 @@ import { hasZeroWidthSpace } from './Utils.js';
 import { normalizeFontMetrics } from './TextLayoutEngine.js';
 import { isProductionEnvironment } from '../../utils.js';
 import type { TextureError } from '../TextureError.js';
+import { takeSdfPrefetch } from './FontPrefetch.js';
 
 /**
  * SDF Font Data structure matching msdf-bmfont-xml output
@@ -315,6 +316,11 @@ export const loadFont = (
   const names = Array.isArray(fontFamily) ? fontFamily : [fontFamily];
   const primary = names[0]!;
 
+  // A prefetch started before the renderer existed, if any. Claimed here —
+  // ahead of the early returns — so that a font which turns out to need no
+  // load still releases the prefetched atlas blob rather than pinning it.
+  const prefetched = takeSdfPrefetch(primary);
+
   // Early return if already loaded
   if (fontCache.get(primary) !== undefined) {
     return Promise.resolve();
@@ -380,7 +386,15 @@ export const loadFont = (
   // success it processes + caches the font and wakes parked nodes. On failure
   // it drops the dead atlas texture (createTexture caches by `src`, so the
   // next attempt must evict it to build a fresh one) and rejects.
-  const loadAtlas = (fontData: SdfFontData): Promise<void> => {
+  //
+  // `atlasBlob` is the prefetched atlas image when one was claimed. Passing it
+  // as `src` skips a second download; `key` is set to the atlas URL so the
+  // texture cache key is identical to the one the URL path produces — the two
+  // paths must not produce two cache entries for the same atlas.
+  const loadAtlas = (
+    fontData: SdfFontData,
+    atlasBlob: Blob | null,
+  ): Promise<void> => {
     if (!fontData || !fontData.chars) {
       return Promise.reject(new Error('Invalid SDF font data format'));
     }
@@ -395,7 +409,8 @@ export const loadFont = (
     return new Promise<void>((resolve, reject) => {
       // create new atlas texture using ImageTexture
       const atlasTexture = stage.txManager.createTexture('ImageTexture', {
-        src: atlasUrl,
+        src: atlasBlob !== null ? atlasBlob : atlasUrl,
+        key: atlasUrl,
         premultiplyAlpha: false,
       });
 
@@ -454,15 +469,31 @@ export const loadFont = (
     });
   };
 
-  // Initial attempt plus up to MAX_FONT_LOAD_RETRIES automatic reloads.
+  // Initial attempt plus up to MAX_FONT_LOAD_RETRIES automatic reloads. Only
+  // the first attempt uses the prefetch; a retry goes back to the network
+  // rather than replaying a payload that may be exactly what failed.
   const loadPromise = (async (): Promise<void> => {
     let lastError: unknown;
     for (let attempt = 0; attempt <= MAX_FONT_LOAD_RETRIES; attempt++) {
       try {
-        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(primary);
+        // Both halves of a prefetch are already in flight in parallel; the
+        // fallbacks below are the original sequential path.
+        const fontData =
+          (attempt === 0 && prefetched !== undefined
+            ? await prefetched.data
+            : null) ?? (await fetchFontData());
+
+        const atlasBlob =
+          attempt === 0 && prefetched !== undefined
+            ? await prefetched.atlas
+            : null;
+
+        await loadAtlas(fontData, atlasBlob);
+        // Success: clear the in-flight markers (the font now lives in
+        // fontCache) — parked nodes were already woken inside loadAtlas.
+        for (let i = 0; i < names.length; i++) {
+          fontLoadPromises.delete(names[i]!);
+        }
         return;
       } catch (error) {
         lastError = error;
@@ -477,21 +508,30 @@ export const loadFont = (
       }
     }
 
-    // Every attempt failed. Clear the in-flight marker so the font can be
+    // Every attempt failed. Clear the in-flight markers so the font can be
     // requested again and drop any partial cache entry. nodesWaitingForFont
     // is deliberately kept: nodes parked here must survive so a later
     // 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(primary);
     for (let i = 0; i < names.length; i++) {
+      fontLoadPromises.delete(names[i]!);
       fontCache.delete(names[i]!);
     }
     console.error(`Failed to load SDF font: ${primary}`, lastError);
     throw lastError;
   })();
 
-  fontLoadPromises.set(primary, loadPromise);
+  // Mark the load in flight under *every* name, not just the primary.
+  // `canRenderFont` treats a name with no cache entry and no in-flight promise
+  // as unrenderable, so keying only the primary made an alias unresolvable for
+  // the whole load: the stage would either fall through to the Canvas engine
+  // (permanently, with a substitute face) or, on an SDF-only engine list,
+  // throw "No compatible text renderer found". Registering every name also
+  // makes a later loadFont() for an alias dedupe onto this same load.
+  for (let i = 0; i < names.length; i++) {
+    fontLoadPromises.set(names[i]!, loadPromise);
+  }
   return loadPromise;
 };
 

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

@@ -0,0 +1,341 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  prefetchFont,
+  clearFontPrefetch,
+  takeSdfPrefetch,
+  takeCanvasPrefetch,
+} from '../FontPrefetch.js';
+import { loadFont as loadSdfFont, isFontLoaded } from '../SdfFontHandler.js';
+import {
+  loadFont as loadCanvasFont,
+  isFontLoaded as isCanvasFontLoaded,
+} from '../CanvasFontHandler.js';
+import { EventEmitter } from '../../../common/EventEmitter.js';
+import type { Stage } from '../../Stage.js';
+import type { ImageTextureProps } from '../../textures/ImageTexture.js';
+
+const VALID_FONT_DATA = {
+  chars: [{}],
+  kernings: [],
+  lightningMetrics: {
+    ascender: 800,
+    descender: -200,
+    lineGap: 200,
+    unitsPerEm: 1000,
+  },
+};
+
+// Records every request so tests can assert what was fetched, when, and in
+// what order. Responses are keyed by URL and delivered on demand, letting a
+// test hold a request open to observe concurrency.
+class RecordingXHR {
+  static requests: RecordingXHR[] = [];
+  static responses: Record<string, unknown> = {};
+
+  status = 200;
+  response: unknown = null;
+  responseType = '';
+  url = '';
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onreadystatechange: (() => void) | null = null;
+  readyState = 0;
+
+  open(_method: string, url: string): void {
+    this.url = url;
+  }
+
+  send(): void {
+    RecordingXHR.requests.push(this);
+  }
+
+  /** Deliver the configured response for this request's URL. */
+  respond(status = 200): void {
+    this.status = status;
+    this.response = RecordingXHR.responses[this.url] ?? null;
+    this.readyState = 4;
+    if (this.onreadystatechange !== null) this.onreadystatechange();
+    if (this.onload !== null) this.onload();
+  }
+
+  /** Deliver every outstanding request. */
+  static respondAll(): void {
+    RecordingXHR.requests.forEach((r) => r.respond());
+  }
+
+  static reset(): void {
+    RecordingXHR.requests = [];
+    RecordingXHR.responses = {};
+  }
+}
+
+// `XMLHttpRequest.DONE` is read by fetchJson; the class stand-in must carry it.
+(RecordingXHR as unknown as { DONE: number }).DONE = 4;
+
+function makeFakeTexture() {
+  const tex = new EventEmitter() as unknown as EventEmitter & {
+    state: string;
+    preventCleanup: boolean;
+    setRenderableOwner: (owner: string, val: boolean) => void;
+  };
+  tex.state = 'loading';
+  tex.preventCleanup = false;
+  tex.setRenderableOwner = () => {};
+  return tex;
+}
+
+type FakeTexture = ReturnType<typeof makeFakeTexture>;
+
+// Stage stub that records the props each atlas texture was created with, so
+// tests can assert whether the prefetched blob (or the URL) was used.
+function makeStage(): {
+  stage: Stage;
+  textures: FakeTexture[];
+  textureProps: ImageTextureProps[];
+} {
+  const textures: FakeTexture[] = [];
+  const textureProps: ImageTextureProps[] = [];
+  const stage = {
+    txManager: {
+      createTexture: (_type: string, props: ImageTextureProps) => {
+        textureProps.push(props);
+        const t = makeFakeTexture();
+        textures.push(t);
+        return t;
+      },
+      removeTextureFromCache: () => {},
+    },
+  } as unknown as Stage;
+  return { stage, textures, textureProps };
+}
+
+const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+const sdfOpts = (fontFamily: string) => ({
+  fontFamily,
+  atlasUrl: `${fontFamily}.png`,
+  atlasDataUrl: `${fontFamily}.json`,
+});
+
+describe('FontPrefetch — SDF', () => {
+  let originalXHR: unknown;
+  let originalBlob: unknown;
+
+  beforeEach(() => {
+    originalXHR = (globalThis as unknown as { XMLHttpRequest: unknown })
+      .XMLHttpRequest;
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      RecordingXHR;
+    // jsdom provides Blob; guard for environments that do not.
+    originalBlob = (globalThis as unknown as { Blob: unknown }).Blob;
+    RecordingXHR.reset();
+    clearFontPrefetch();
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      originalXHR;
+    (globalThis as unknown as { Blob: unknown }).Blob = originalBlob;
+    clearFontPrefetch();
+  });
+
+  it('requests the atlas description and the atlas image concurrently', () => {
+    prefetchFont(sdfOpts('ConcurrentFont'));
+
+    // Both are in flight before either has responded — the handler's own path
+    // only starts the image fetch after the JSON resolves.
+    expect(RecordingXHR.requests.map((r) => r.url).sort()).toEqual([
+      'ConcurrentFont.json',
+      'ConcurrentFont.png',
+    ]);
+  });
+
+  it('starts no request for a font it has already prefetched', () => {
+    prefetchFont(sdfOpts('DedupeFont'));
+    expect(RecordingXHR.requests.length).toBe(2);
+
+    prefetchFont(sdfOpts('DedupeFont'));
+    expect(RecordingXHR.requests.length).toBe(2);
+  });
+
+  it('hands the prefetched payload to loadFont instead of refetching', async () => {
+    const font = sdfOpts('PrefetchHit');
+    const blob = new Blob(['atlas-bytes']);
+    RecordingXHR.responses['PrefetchHit.json'] = VALID_FONT_DATA;
+    RecordingXHR.responses['PrefetchHit.png'] = blob;
+
+    prefetchFont(font);
+    RecordingXHR.respondAll();
+    const prefetchRequestCount = RecordingXHR.requests.length;
+
+    const { stage, textures, textureProps } = makeStage();
+    const promise = loadSdfFont(
+      stage,
+      font as Parameters<typeof loadSdfFont>[1],
+    );
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    // No second trip to the network for either resource.
+    expect(RecordingXHR.requests.length).toBe(prefetchRequestCount);
+    // The atlas texture was built from the prefetched bytes...
+    expect(textureProps[0]!.src).toBe(blob);
+    // ...while still keying the texture cache by URL, so the blob path and the
+    // URL path resolve to the same cache entry.
+    expect(textureProps[0]!.key).toBe('PrefetchHit.png');
+    expect(isFontLoaded('PrefetchHit')).toBe(true);
+  });
+
+  it('falls back to fetching when the prefetch failed', async () => {
+    const font = sdfOpts('PrefetchFail');
+    // No responses registered -> fetchJson resolves null -> unusable prefetch.
+    prefetchFont(font);
+    RecordingXHR.respondAll();
+    RecordingXHR.reset();
+
+    RecordingXHR.responses['PrefetchFail.json'] = VALID_FONT_DATA;
+
+    const { stage, textures, textureProps } = makeStage();
+    const promise = loadSdfFont(
+      stage,
+      font as Parameters<typeof loadSdfFont>[1],
+    );
+    // The handler runs its own XHR for the atlas description.
+    await flush();
+    RecordingXHR.respondAll();
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    expect(RecordingXHR.requests.map((r) => r.url)).toEqual([
+      'PrefetchFail.json',
+    ]);
+    // Atlas falls back to the URL rather than a blob.
+    expect(textureProps[0]!.src).toBe('PrefetchFail.png');
+    expect(isFontLoaded('PrefetchFail')).toBe(true);
+  });
+
+  it('rejects a malformed atlas description rather than loading it', async () => {
+    RecordingXHR.responses['Malformed.json'] = { not: 'font data' };
+    prefetchFont(sdfOpts('Malformed'));
+    RecordingXHR.respondAll();
+
+    await expect(takeSdfPrefetch('Malformed')!.data).resolves.toBe(null);
+  });
+
+  it('parses an atlas description that arrives as a string', async () => {
+    RecordingXHR.responses['StringJson.json'] = JSON.stringify(VALID_FONT_DATA);
+    prefetchFont(sdfOpts('StringJson'));
+    RecordingXHR.respondAll();
+
+    await expect(takeSdfPrefetch('StringJson')!.data).resolves.toMatchObject({
+      chars: [{}],
+    });
+  });
+
+  it('claims a prefetch only once', () => {
+    prefetchFont(sdfOpts('OnceOnly'));
+
+    expect(takeSdfPrefetch('OnceOnly')).not.toBe(undefined);
+    expect(takeSdfPrefetch('OnceOnly')).toBe(undefined);
+  });
+
+  it('ignores a canvas-typed descriptor even when it carries atlas urls', () => {
+    prefetchFont({ ...sdfOpts('CanvasTyped'), type: 'canvas' });
+
+    expect(takeSdfPrefetch('CanvasTyped')).toBe(undefined);
+  });
+});
+
+describe('FontPrefetch — web fonts', () => {
+  class FakeFontFace {
+    static created: FakeFontFace[] = [];
+    constructor(public family: string, public source: string) {
+      FakeFontFace.created.push(this);
+    }
+    load(): Promise<FakeFontFace> {
+      return Promise.resolve(this);
+    }
+  }
+
+  let originalFontFace: unknown;
+
+  beforeEach(() => {
+    originalFontFace = (globalThis as unknown as { FontFace: unknown })
+      .FontFace;
+    (globalThis as unknown as { FontFace: unknown }).FontFace = FakeFontFace;
+    FakeFontFace.created = [];
+    clearFontPrefetch();
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { FontFace: unknown }).FontFace =
+      originalFontFace;
+    clearFontPrefetch();
+  });
+
+  it('starts the download for every registered name', async () => {
+    prefetchFont({
+      fontFamily: ['WebPrimary', 'WebAlias'],
+      fontUrl: 'web.woff2',
+    });
+
+    expect(FakeFontFace.created.map((f) => f.family)).toEqual([
+      'WebPrimary',
+      'WebAlias',
+    ]);
+    await expect(takeCanvasPrefetch('WebPrimary')).resolves.toHaveLength(2);
+  });
+
+  it('resolves to null when the download fails, so the handler can retry', async () => {
+    vi.spyOn(FakeFontFace.prototype, 'load').mockRejectedValueOnce(
+      new Error('network'),
+    );
+    prefetchFont({ fontFamily: 'WebFail', fontUrl: 'web.woff2' });
+
+    await expect(takeCanvasPrefetch('WebFail')).resolves.toBe(null);
+  });
+
+  it('does nothing when the engine has no FontFace', () => {
+    (globalThis as unknown as { FontFace: unknown }).FontFace = undefined;
+    prefetchFont({ fontFamily: 'NoFontFace', fontUrl: 'web.woff2' });
+
+    expect(takeCanvasPrefetch('NoFontFace')).toBe(undefined);
+  });
+
+  it('registers prefetched faces with the platform without reloading them', async () => {
+    prefetchFont({ fontFamily: 'CanvasHit', fontUrl: 'web.woff2' });
+    const createdByPrefetch = FakeFontFace.created.length;
+
+    const added: FakeFontFace[] = [];
+    const stage = {
+      platform: { addFont: (f: FakeFontFace) => added.push(f) },
+    } as unknown as Stage;
+
+    await loadCanvasFont(stage, {
+      fontFamily: 'CanvasHit',
+      fontUrl: 'web.woff2',
+    });
+
+    // No extra FontFace was constructed — the prefetched one was used.
+    expect(FakeFontFace.created.length).toBe(createdByPrefetch);
+    expect(added).toEqual(FakeFontFace.created);
+    expect(isCanvasFontLoaded('CanvasHit')).toBe(true);
+  });
+
+  it('loads normally when there is no prefetch to claim', async () => {
+    const added: FakeFontFace[] = [];
+    const stage = {
+      platform: { addFont: (f: FakeFontFace) => added.push(f) },
+    } as unknown as Stage;
+
+    await loadCanvasFont(stage, {
+      fontFamily: 'CanvasMiss',
+      fontUrl: 'web.woff2',
+    });
+
+    expect(FakeFontFace.created.map((f) => f.family)).toEqual(['CanvasMiss']);
+    expect(isCanvasFontLoaded('CanvasMiss')).toBe(true);
+  });
+});

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

@@ -4,11 +4,13 @@ import {
   waitingForFont,
   isFontLoaded,
   getFontData,
+  canRenderFont,
   MAX_FONT_LOAD_RETRIES,
 } from '../SdfFontHandler.js';
 import { EventEmitter } from '../../../common/EventEmitter.js';
 import { TextureError, TextureErrorCode } from '../../TextureError.js';
 import type { Stage } from '../../Stage.js';
+import type { TrProps } from '../TextRenderer.js';
 
 // Minimal XHR stand-in: synchronously delivers valid SDF font JSON so loadFont
 // proceeds to create the atlas texture and attach its event listeners.
@@ -294,6 +296,47 @@ describe('SdfFontHandler loadFont — multiple names for one font', () => {
     }
   });
 
+  it('reports every name as renderable while the font is still loading', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['MidLoadPrimary', 'MidLoadAlias'];
+
+    const promise = loadFont(stage, opts(names));
+
+    // Mid-load: nothing is in fontCache yet, so this is answered purely by the
+    // in-flight markers. An alias that answers `false` here makes the stage
+    // resolve a *different* text renderer for the node — silently substituting
+    // a Canvas face, or throwing "No compatible text renderer found" when SDF
+    // is the only engine. Both names must answer the same.
+    for (let i = 0; i < names.length; i++) {
+      expect(canRenderFont({ fontFamily: names[i]! } as TrProps)).toBe(true);
+    }
+    expect(isFontLoaded(names[1]!)).toBe(false);
+
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    for (let i = 0; i < names.length; i++) {
+      expect(canRenderFont({ fontFamily: names[i]! } as TrProps)).toBe(true);
+      expect(isFontLoaded(names[i]!)).toBe(true);
+    }
+  });
+
+  it('dedupes a load requested under an alias onto the in-flight load', async () => {
+    const { stage, textures } = makeStage();
+
+    const first = loadFont(stage, opts(['DedupePrimary', 'DedupeAlias']));
+    const second = loadFont(stage, opts('DedupeAlias'));
+
+    expect(second).toBe(first);
+
+    await flush();
+    // A single atlas fetch served both calls.
+    expect(textures.length).toBe(1);
+    textures[0]!.emit('loaded');
+    await first;
+  });
+
   it('wakes nodes parked under an alias, not just the primary name', async () => {
     const { stage, textures } = makeStage();
     const names = ['MultiWakePrimary', 'MultiWakeAlias'];

package/src/main-api/Renderer.ts

@@ -654,16 +654,16 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * ignore it, returning straight (non-premultiplied) alpha. This causes edge
    * "ghosting" on images with transparency.
    *
-   * `'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)
+   * Set to `'auto'` to detect 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. Set to a
+   * boolean to force the value (`false` forces the GL-premultiply fallback;
+   * `true` skips it). Leave unset to assume the option is honored — the
+   * default, which preserves existing behavior with no probe overhead.
+   *
+   * @defaultValue `true` (assume honored; no probe)
    */
   premultiplyAlphaHonored?: boolean | 'auto';
 
@@ -825,11 +825,11 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'auto',
-      // undefined -> 'auto' (probe once at startup); 'auto' -> probe;
-      // explicit boolean -> force the value, skip the probe.
+      // undefined -> true (assume honored, no probe); 'auto' -> probe;
+      // explicit boolean -> force the value.
       premultiplyAlphaHonored:
         settings.premultiplyAlphaHonored === undefined
-          ? 'auto'
+          ? true
           : settings.premultiplyAlphaHonored,
       platform: settings.platform || null,
       maxRetryCount: settings.maxRetryCount ?? 5,