@solidtv/renderer 1.6.2 → 1.6.4

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

@@ -0,0 +1,195 @@
+/*
+ * Font prefetching — stage-free.
+ *
+ * Font bytes normally only start moving once a Stage exists, because
+ * `Stage.loadFont()` is the only entry point. That serializes the network
+ * behind the whole synchronous boot (GL context, buffers, shaders, root node)
+ * and, for SDF, behind the texture manager's async init as well.
+ *
+ * Nothing about *fetching* a font needs a Stage: the SDF atlas is a JSON
+ * document plus an image, and a web font is a `FontFace`. This module starts
+ * that work as early as an app can call it — typically before the renderer is
+ * constructed — and parks the results. The font handlers pick them up from
+ * here when `loadFont()` eventually runs, so the round-trip overlaps CPU boot
+ * instead of following it.
+ *
+ * Everything here uses XHR rather than `fetch` to match the rest of the
+ * renderer (Chrome 38 / webOS 3 have no `fetch`).
+ */
+
+import type { FontLoadOptions } from './TextRenderer.js';
+import type { SdfFontData } from './SdfFontHandler.js';
+import { fetchJson } from '../lib/utils.js';
+
+/**
+ * A prefetched SDF font: the parsed atlas description and the atlas image,
+ * fetched concurrently. Either promise resolves to `null` if its request
+ * failed — the handler then falls back to its normal load path rather than
+ * inheriting the failure.
+ */
+export interface PrefetchedSdfFont {
+  data: Promise<SdfFontData | null>;
+  atlas: Promise<Blob | null>;
+}
+
+const sdfPrefetch = new Map<string, PrefetchedSdfFont>();
+const canvasPrefetch = new Map<string, Promise<FontFace[] | null>>();
+
+/**
+ * Options accepted by {@link prefetchFont}. Identical to the options passed to
+ * `Stage.loadFont()`, plus the optional SDF `type` discriminator that
+ * framework layers already carry on their font descriptors.
+ */
+export type FontPrefetchOptions = FontLoadOptions & {
+  type?: 'ssdf' | 'msdf' | 'canvas';
+};
+
+/**
+ * Swallow a rejection into `null` so a prefetch that fails can never surface
+ * as an unhandled rejection. A prefetch is an optimization: when it fails the
+ * handler just does the work itself.
+ */
+const orNull = <T>(promise: Promise<T>): Promise<T | null> =>
+  promise.then(
+    (value) => value,
+    () => null,
+  );
+
+/**
+ * Normalize an atlas description response into usable font data, or `null` if
+ * it is unusable.
+ *
+ * `fetchJson` resolves rather than rejects on a status of 0 (the file://
+ * allowance), so a failed request arrives here as `null`. Engines without
+ * `responseType = 'json'` support hand back the raw string instead of a parsed
+ * object — the SDF handler tolerates both, so this does too.
+ */
+const normalizeSdfData = (response: unknown): SdfFontData | null => {
+  let data = response;
+
+  if (typeof data === 'string') {
+    try {
+      data = JSON.parse(data);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (data === null || typeof data !== 'object') {
+    return null;
+  }
+
+  // Reject anything the handler would reject anyway, so a malformed prefetch
+  // falls back to a fresh fetch instead of failing the load outright.
+  return (data as SdfFontData).chars !== undefined
+    ? (data as SdfFontData)
+    : null;
+};
+
+/**
+ * Start downloading a font before a renderer exists.
+ *
+ * Safe to call more than once for the same font — the first call wins and
+ * later ones are ignored. Never throws and never rejects; failures degrade to
+ * the handler's normal load path.
+ *
+ * The descriptor decides what is fetched: an `atlasDataUrl` means an SDF font
+ * (atlas JSON + atlas image, in parallel), otherwise a `fontUrl` means a web
+ * font (`FontFace.load()`).
+ *
+ * @param options - The same options later passed to `Stage.loadFont()`
+ */
+export const prefetchFont = (options: FontPrefetchOptions): void => {
+  const { fontFamily, fontUrl, atlasUrl, atlasDataUrl } = options;
+  const names = Array.isArray(fontFamily) ? fontFamily : [fontFamily];
+  const primary = names[0];
+
+  if (primary === undefined) {
+    return;
+  }
+
+  // SDF: atlas description and atlas image are independent requests. The
+  // handler fetches them sequentially (it needs the JSON before it knows the
+  // atlas is usable); here there is no such constraint, so overlap them.
+  if (atlasDataUrl !== undefined && options.type !== 'canvas') {
+    if (sdfPrefetch.has(primary) === true) {
+      return;
+    }
+
+    sdfPrefetch.set(primary, {
+      data: orNull(fetchJson(atlasDataUrl, 'json')).then(normalizeSdfData),
+      atlas:
+        atlasUrl !== undefined
+          ? orNull(fetchJson(atlasUrl, 'blob') as Promise<Blob>).then((blob) =>
+              blob instanceof Blob ? blob : null,
+            )
+          : Promise.resolve(null),
+    });
+    return;
+  }
+
+  // Web font: `FontFace.load()` starts the download immediately. The face is
+  // not registered with the document here — that needs the platform, so the
+  // handler does it at attach time.
+  if (fontUrl !== undefined) {
+    if (canvasPrefetch.has(primary) === true) {
+      return;
+    }
+
+    if (typeof FontFace === 'undefined') {
+      return;
+    }
+
+    canvasPrefetch.set(
+      primary,
+      orNull(
+        Promise.all(
+          names.map((name) => new FontFace(name, `url(${fontUrl})`).load()),
+        ),
+      ),
+    );
+  }
+};
+
+/**
+ * Claim a prefetched SDF font, removing it from the pool.
+ *
+ * One-shot by design: a load that fails and retries must go back to the
+ * network rather than replaying a stale (possibly failed) prefetch.
+ *
+ * @param fontFamily - Primary font family name
+ */
+export const takeSdfPrefetch = (
+  fontFamily: string,
+): PrefetchedSdfFont | undefined => {
+  const prefetched = sdfPrefetch.get(fontFamily);
+  if (prefetched !== undefined) {
+    sdfPrefetch.delete(fontFamily);
+  }
+  return prefetched;
+};
+
+/**
+ * Claim prefetched web font faces, removing them from the pool. One-shot for
+ * the same reason as {@link takeSdfPrefetch}.
+ *
+ * @param fontFamily - Primary font family name
+ */
+export const takeCanvasPrefetch = (
+  fontFamily: string,
+): Promise<FontFace[] | null> | undefined => {
+  const prefetched = canvasPrefetch.get(fontFamily);
+  if (prefetched !== undefined) {
+    canvasPrefetch.delete(fontFamily);
+  }
+  return prefetched;
+};
+
+/**
+ * Drop every pending prefetch. Test/teardown helper — in-flight requests are
+ * not aborted, their results are simply no longer claimable.
+ */
+export const clearFontPrefetch = (): void => {
+  sdfPrefetch.clear();
+  canvasPrefetch.clear();
+};

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);
+  });
+});