@solidtv/renderer 1.6.1 → 1.6.3

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

@@ -12,6 +12,7 @@ import {
   defaultFontMetrics,
   normalizeFontMetrics,
 } from './TextLayoutEngine.js';
+import { takeCanvasPrefetch } from './FontPrefetch.js';
 
 interface CanvasFont {
   fontFamily: string;
@@ -65,37 +66,77 @@ 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]!;
+
+  // Faces whose download was started before the renderer existed, if any.
+  // Claimed ahead of the early returns so an unneeded prefetch is released.
+  const prefetched = takeCanvasPrefetch(primary);
+
   // 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. Prefetched
+  // faces are already loaded — they only still need registering with the
+  // platform, which is the one step that required a stage.
+  const loadPromise = Promise.resolve(prefetched)
+    .then((faces) =>
+      faces != null && faces.length === names.length
+        ? faces
+        : Promise.all(
+            names.map((name) => new FontFace(name, `url(${fontUrl})`).load()),
+          ),
+    )
+    .then((faces) => {
+      for (let i = 0; i < names.length; i++) {
+        const loadedFont = faces[i]!;
+        stage.platform.addFont(loadedFont);
+        processFontData(names[i]!, loadedFont, metrics);
+      }
+    })
+    .then(() => {
+      for (let i = 0; i < names.length; i++) {
+        const name = names[i]!;
+        fontLoadPromises.delete(name);
+        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);
+      for (let i = 0; i < names.length; i++) {
+        fontLoadPromises.delete(names[i]!);
+      }
+      console.error(`Failed to load font: ${primary}`, error);
       throw error;
     });
 
-  fontLoadPromises.set(fontFamily, loadPromise);
+  // Keyed under every name so a later loadFont() for an alias dedupes onto
+  // this load rather than starting a second one. (Canvas `canRenderFont` is
+  // unconditionally true, so unlike SDF this does not affect renderer choice.)
+  for (let i = 0; i < names.length; i++) {
+    fontLoadPromises.set(names[i]!, loadPromise);
+  }
   return loadPromise;
 };
 

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
@@ -309,30 +310,44 @@ 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]!;
+
+  // 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(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.
@@ -371,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'));
     }
@@ -386,21 +409,39 @@ 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,
       });
 
-      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,49 +460,78 @@ 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);
       });
     });
   };
 
-  // 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(fontFamily);
+        // 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;
         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,
           );
         }
       }
     }
 
-    // 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(fontFamily);
-    fontCache.delete(fontFamily);
-    console.error(`Failed to load SDF font: ${fontFamily}`, lastError);
+    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(fontFamily, 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/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;