Skip to content

Code-first video & image, rendered natively on WebGPU.

fix(preview): components entry, registered font sources, one GPU device

okanaslecfa54438286
diff --git a/packages/framefields/src/font-sources.test.ts b/packages/framefields/src/font-sources.test.ts
new file mode 100644
index 00000000..6ae6b4c6
--- /dev/null
+++ b/packages/framefields/src/font-sources.test.ts
@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { VirtualMediaData } from "@framefields/core";
+import {
+ measureTextAsync,
+ preloadCompositionFonts,
+} from "@framefields/renderers";
+import { SlugFontCache } from "@framefields/webgpu-renderers";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { FontManager } from "./index.js";
+
+// Fonts are kept on disk, not in git (see font-manager.test.ts).
+const INTER = path.resolve(
+ import.meta.dirname,
+ "../../..",
+ "assets/fonts/Inter.ttf",
+);
+const hasInter = existsSync(INTER);
+
+/**
+ * A page as the browser preview runs: fonts are fetched, and every fetch
+ * 404s, as `assets/fonts/<Family>.ttf` does for a font registered from
+ * bytes or from a file named otherwise.
+ */
+function asBrowserPage() {
+ const fetched: string[] = [];
+ const faces: Array<{ family: string; source: unknown }> = [];
+ vi.stubGlobal("window", globalThis);
+ vi.stubGlobal("__IS_HEADLESS_RENDERER__", false);
+ vi.stubGlobal("document", { fonts: { add() {}, ready: Promise.resolve() } });
+ vi.stubGlobal(
+ "FontFace",
+ class {
+ constructor(family: string, source: unknown) {
+ faces.push({ family, source });
+ }
+ load() {
+ return Promise.resolve(this);
+ }
+ },
+ );
+ vi.stubGlobal("fetch", async (url: string) => {
+ fetched.push(String(url));
+ return new Response("missing", { status: 404, statusText: "Not Found" });
+ });
+ return { fetched, faces };
+}
+
+const textIn = (fontFamily: string) =>
+ ({
+ operation: { op: "text", text: "Hello", fontFamily, fontSize: 40 },
+ }) as unknown as VirtualMediaData;
+
+describe.skipIf(!hasInter)(
+ "fonts registered without a conventional path",
+ () => {
+ let bytes: Uint8Array;
+ beforeAll(async () => {
+ bytes = new Uint8Array(await fs.readFile(INTER));
+ });
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ SlugFontCache.clearFailed();
+ });
+
+ it("loads a family registered from bytes without looking it up by name", async () => {
+ await FontManager.register({ family: "BytesOnly", source: bytes });
+ const page = asBrowserPage();
+
+ await preloadCompositionFonts(textIn("BytesOnly"), null);
+ const slug = await SlugFontCache.preloadSlugFont(
+ null,
+ "BytesOnly",
+ "assets/fonts/BytesOnly.ttf",
+ );
+ const measured = await measureTextAsync("Hello", {
+ fontFamily: "BytesOnly",
+ fontSize: 40,
+ });
+
+ expect(slug.unitsPerEm).toBe(2048);
+ expect(page.fetched).toEqual([]);
+ expect(SlugFontCache.isFailed("BytesOnly")).toBe(false);
+ // The page's FontFace gets the bytes, not a guessed URL.
+ expect(page.faces).toEqual([{ family: "BytesOnly", source: bytes }]);
+ expect(measured.width).toBe(
+ Math.ceil(
+ FontManager.measure("Hello", {
+ fontFamily: "BytesOnly",
+ fontSize: 40,
+ }).width,
+ ),
+ );
+ });
+
+ it("loads a family registered from a URL from that URL", async () => {
+ const url = "https://fonts.example/Inter-Variable.ttf";
+ vi.stubGlobal("fetch", async () => new Response(bytes));
+ await FontManager.register({ family: "FromUrl", source: url });
+ const page = asBrowserPage();
+
+ await preloadCompositionFonts(textIn("FromUrl"), null);
+
+ expect(page.fetched).toEqual([]);
+ expect(page.faces).toEqual([
+ { family: "FromUrl", source: `url(${url})` },
+ ]);
+ });
+
+ it("forgets a lookup that missed before the family was registered", async () => {
+ const page = asBrowserPage();
+ await expect(
+ SlugFontCache.preloadSlugFont(null, "Late", "assets/fonts/Late.ttf"),
+ ).rejects.toThrow(/Failed to fetch/);
+ expect(page.fetched).toEqual(["assets/fonts/Late.ttf"]);
+ expect(SlugFontCache.isFailed("Late")).toBe(true);
+
+ await FontManager.register({ family: "Late", source: bytes });
+
+ expect(SlugFontCache.isFailed("Late")).toBe(false);
+ await expect(
+ SlugFontCache.preloadSlugFont(null, "Late", "assets/fonts/Late.ttf"),
+ ).resolves.toBeDefined();
+ expect(page.fetched).toHaveLength(1);
+ });
+ },
+);
diff --git a/packages/framefields/src/fonts/manager.ts b/packages/framefields/src/fonts/manager.ts
index 0d1cc4f8..a4411165 100644
--- a/packages/framefields/src/fonts/manager.ts
+++ b/packages/framefields/src/fonts/manager.ts
@@ -4,6 +4,7 @@ import {
registerHeadlessFont,
SlugFontCache,
SlugGeometry,
+ setRegisteredFontSource,
} from "@framefields/webgpu-renderers";
import * as fontkit from "fontkit";
@@ -456,6 +457,7 @@ export class FontManager {
this.fonts.set(resolvedFamily, registered);
+ setRegisteredFontSource(resolvedFamily, filePath ?? rawSource);
// Populate headless font registries
if (filePath) {
await registerHeadlessFont(resolvedFamily, filePath);
diff --git a/packages/framefields/src/preview/bundle.ts b/packages/framefields/src/preview/bundle.ts
index 3809324f..fa30af1c 100644
--- a/packages/framefields/src/preview/bundle.ts
+++ b/packages/framefields/src/preview/bundle.ts
@@ -37,6 +37,8 @@ const ENTRIES: Record<string, string> = {
"framefields/audio": "audio/index.ts",
"framefields/signals": "signals/index.ts",
"framefields/fonts": "fonts/index.ts",
+ // Installed components import their toolkit from here (`framefields add`).
+ "framefields/components": "components/index.ts",
};
/** Node built-ins with a browser version (shim file names); others are stubbed. */
diff --git a/packages/framefields/src/preview/player.test.ts b/packages/framefields/src/preview/player.test.ts
new file mode 100644
index 00000000..2c6b6b74
--- /dev/null
+++ b/packages/framefields/src/preview/player.test.ts
@@ -0,0 +1,139 @@
+import { resetDeviceInstance } from "@framefields/webgpu-renderers";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { type PreviewPlayer, startPlayer } from "./player.js";
+
+// Everything that draws is stubbed: these tests are about which GPU objects
+// a player makes and frees. The device comes from the real `ensureDevice`.
+const surfaces = vi.hoisted(() => [] as Array<{ device: unknown }>);
+vi.mock("framefields-preview:renderers", () => ({
+ BUILTIN_NODE_RENDERERS: [],
+}));
+vi.mock("@framefields/compositions", () => ({
+ compositionStateStore: { setState: () => {} },
+ drawCompositionTree: async () => {},
+}));
+vi.mock("@framefields/renderers", () => ({
+ preloadCompositionFonts: async () => {},
+}));
+vi.mock("@framefields/vision/web", () => ({
+ setDefaultSessionProvider: () => {},
+ WebGPUProvider: class {},
+}));
+vi.mock("./blit.js", () => ({ Blitter: class {} }));
+vi.mock("@framefields/webgpu-renderers", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@framefields/webgpu-renderers")>()),
+ BrowserSurfaceProvider: class {
+ colorFormat = "bgra8unorm";
+ width = 64;
+ height = 36;
+ destroyed = false;
+ constructor(readonly device: unknown) {
+ surfaces.push(this);
+ }
+ getCurrentTexture() {
+ return texture();
+ }
+ present() {}
+ destroy() {
+ this.destroyed = true;
+ }
+ },
+ getRenderer2D: () => ({
+ getTemporaryTexture: () => texture(),
+ beginFrame: () => ({ end: () => {} }),
+ }),
+ lutStore: { hasPending: () => false, awaitAllPending: async () => {} },
+ SlugFontCache: { hasPending: () => false },
+}));
+
+const textures: Array<{ label?: string; destroy: ReturnType<typeof vi.fn> }> =
+ [];
+function texture(label?: string) {
+ const t = { label, destroy: vi.fn(), createView: () => ({}) };
+ textures.push(t);
+ return t;
+}
+
+const composition = (width: number) => ({
+ film: () => ({
+ fps: 10,
+ toVirtualMedia: () => ({
+ metadata: { width, height: 36, durationMs: 1000 },
+ operation: { op: "compose" },
+ }),
+ }),
+});
+
+function start(mod: Record<string, unknown>): Promise<PreviewPlayer> {
+ startPlayer(mod, "film", { modelsDir: "", ortBase: "/ort/" });
+ return window.framefieldsPlayer as Promise<PreviewPlayer>;
+}
+
+describe("startPlayer", () => {
+ let requestDevice: ReturnType<typeof vi.fn>;
+ beforeEach(() => {
+ resetDeviceInstance();
+ surfaces.length = 0;
+ textures.length = 0;
+ const device = {
+ lost: new Promise(() => {}),
+ createTexture: (d: { label?: string }) => texture(d.label),
+ createCommandEncoder: () => ({
+ copyTextureToTexture: () => {},
+ finish: () => ({}),
+ }),
+ queue: { submit: () => {}, onSubmittedWorkDone: async () => {} },
+ };
+ requestDevice = vi.fn(async () => device);
+ vi.stubGlobal("navigator", {
+ gpu: {
+ requestAdapter: async () => ({
+ features: new Set(),
+ limits: {},
+ requestDevice,
+ }),
+ },
+ });
+ vi.stubGlobal(
+ "window",
+ Object.assign(new EventTarget(), { framefieldsPlayer: undefined }),
+ );
+ const canvas = { width: 0, height: 0 };
+ vi.stubGlobal("document", { getElementById: () => canvas });
+ vi.stubGlobal("GPUTextureUsage", {
+ RENDER_ATTACHMENT: 16,
+ TEXTURE_BINDING: 4,
+ COPY_DST: 2,
+ COPY_SRC: 1,
+ });
+ });
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ resetDeviceInstance();
+ });
+
+ it("replaces the player on the same device and frees the old one's frames", async () => {
+ const first = await start(composition(64));
+ await first.render(0);
+ await first.render(1);
+ const cached = textures.filter((t) => t.label === "preview_frame_cache");
+ expect(cached).toHaveLength(2);
+
+ // A prop change: the page builds the composition again.
+ const second = await start(composition(48));
+ expect(requestDevice).toHaveBeenCalledTimes(1);
+ expect(surfaces.map((s) => s.device)).toEqual([
+ surfaces[0].device,
+ surfaces[0].device,
+ ]);
+ for (const t of cached) expect(t.destroy).toHaveBeenCalled();
+ expect(surfaces[0]).toMatchObject({ destroyed: true });
+
+ expect(second.meta.width).toBe(48);
+ expect(await second.render(3)).toBe(3);
+ // The old player draws no more.
+ const before = textures.length;
+ await first.render(4);
+ expect(textures.length).toBe(before);
+ });
+});
diff --git a/packages/framefields/src/preview/player.ts b/packages/framefields/src/preview/player.ts
index 30ee34b1..84ac2fcc 100644
--- a/packages/framefields/src/preview/player.ts
+++ b/packages/framefields/src/preview/player.ts
@@ -24,8 +24,8 @@ import {
WebGPUProvider,
} from "@framefields/vision/web";
import {
- acquireDevice,
BrowserSurfaceProvider,
+ ensureDevice,
getRenderer2D,
lutStore,
type RenderContextValue,
@@ -67,6 +67,13 @@ export interface PreviewPlayer {
warm(frame: number): Promise<boolean>;
/** A frame at full size as an image, e.g. to attach to a note. */
snapshot(frame: number): Promise<ImageBitmap>;
+ /**
+ * Stops drawing and frees the player's textures (its frame cache among
+ * them). The GPU device stays: players share one, as the text, shader and
+ * LUT caches they draw with are tied to it. `startPlayer` disposes the
+ * player it replaces.
+ */
+ dispose(): Promise<void>;
}
type Renderable = {
@@ -88,6 +95,11 @@ export interface PlayerSettings {
ortBase: string;
}
+/**
+ * Builds the module's composition and makes it the page's player
+ * (`window.framefieldsPlayer`). Called again, e.g. with new props, it
+ * replaces the player on the same canvas and GPU device.
+ */
export function startPlayer(
mod: Record<string, unknown>,
exportName: string,
@@ -111,11 +123,14 @@ export function startPlayer(
},
}),
);
- window.framefieldsPlayer = createPlayer(
- mod,
- exportName,
- BUILTIN_NODE_RENDERERS,
- );
+ const previous = window.framefieldsPlayer;
+ window.framefieldsPlayer = (async () => {
+ await previous?.then(
+ (p) => p.dispose(),
+ () => {},
+ );
+ return createPlayer(mod, exportName, BUILTIN_NODE_RENDERERS);
+ })();
// The page listens for this; a failure is shown there.
window.dispatchEvent(new Event("framefields:player"));
}
@@ -161,7 +176,9 @@ async function createPlayer(
// As the export decides it, so text entrances play the same.
const isVideoMode = vm.operation?.dataType === "Video";
- const device = await acquireDevice();
+ // One device for every player on the page: glyph, shader and LUT caches
+ // are global and keep the GPU objects of the device that made them.
+ const device = await ensureDevice();
const canvas =
(document.getElementById("canvas") as HTMLCanvasElement | null) ??
document.createElement("canvas");
@@ -176,6 +193,7 @@ async function createPlayer(
let wanted: number | null = null;
let wantedCached = true;
let waiters: Array<(f: number) => void> = [];
+ let disposed = false;
let offscreen: GPUTexture | undefined;
@@ -336,7 +354,7 @@ async function createPlayer(
// One frame at a time. Requests made while a frame draws collapse to the
// latest; warm-ups only run when nothing else is drawing.
function pump(): void {
- if (drawing || wanted === null) return;
+ if (disposed || drawing || wanted === null) return;
// `drawing` is set before the loop runs: a frame from the cache is drawn
// without awaiting, so the loop can finish (and clear it) synchronously.
let finished!: () => void;
@@ -380,6 +398,7 @@ async function createPlayer(
lastRenderMs: 0,
hasVision,
render(frame, options) {
+ if (disposed) return Promise.resolve(frame);
wanted = frame;
wantedCached = options?.cache ?? true;
const done = new Promise<number>((resolve) => waiters.push(resolve));
@@ -387,7 +406,7 @@ async function createPlayer(
return done;
},
async warm(frame) {
- if (drawing || wanted !== null) return false;
+ if (disposed || drawing || wanted !== null) return false;
drawing = draw(frame, false).catch((err: unknown) =>
console.warn("[framefields] warm-up of frame", frame, err),
);
@@ -397,6 +416,7 @@ async function createPlayer(
return true;
},
async snapshot(frame) {
+ if (disposed) throw new Error("the player was disposed");
while (drawing) await drawing;
const done = (async () => {
await draw(frame, false);
@@ -414,6 +434,17 @@ async function createPlayer(
pump();
}
},
+ async dispose() {
+ if (disposed) return;
+ disposed = true;
+ wanted = null;
+ while (drawing) await drawing;
+ for (const { tex } of renderCache.values()) tex.destroy();
+ renderCache.clear();
+ offscreen?.destroy();
+ offscreen = undefined;
+ surface.destroy();
+ },
};
return player;
}
diff --git a/packages/framefields/src/preview/preview.test.ts b/packages/framefields/src/preview/preview.test.ts
index 90573b7c..25c160d2 100644
--- a/packages/framefields/src/preview/preview.test.ts
+++ b/packages/framefields/src/preview/preview.test.ts
@@ -3,11 +3,29 @@ import http from "node:http";
import os from "node:os";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
-import { afterEach, describe, expect, it } from "vitest";
-import { buildEngine, prebuiltEngineDir } from "./bundle.js";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+ buildRegistry,
+ writeRegistry,
+} from "../../../components/scripts/build-registry.js";
+import { add } from "../cli/add.js";
+import { openRegistry } from "../cli/registry.js";
+import {
+ buildEngine,
+ bundleProject,
+ ENGINE_URL,
+ prebuiltEngineDir,
+} from "./bundle.js";
import { type PreviewSession, startPreview } from "./index.js";
const entry = new URL("./fixtures/comp.ts", import.meta.url);
+// Fonts are kept on disk, not in git (see font-manager.test.ts).
+const INTER = path.resolve(
+ import.meta.dirname,
+ "../../../..",
+ "assets/fonts/Inter.ttf",
+);
+const hasInter = fs.existsSync(INTER);
describe("startPreview", () => {
const sessions: PreviewSession[] = [];
@@ -311,25 +329,119 @@ describe("startPreview", () => {
});
describe("browser engine", () => {
+ let dir: string;
+ beforeAll(async () => {
+ dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "gf-engine-"));
+ await buildEngine(dir);
+ }, 120_000);
+ afterAll(async () => {
+ await fs.promises.rm(dir, { recursive: true, force: true });
+ });
+
it("loads every entry, with no Node built-ins left unshimmed", async () => {
- const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "gf-engine-"));
- try {
- await buildEngine(dir);
- for (const name of [
- "framefields",
- "effects",
- "audio",
- "signals",
- "fonts",
- "player",
- ]) {
- // Importing runs the module's top-level code, as a browser would.
- await import(pathToFileURL(path.join(dir, `${name}.mjs`)).href);
- }
- } finally {
- await fs.promises.rm(dir, { recursive: true, force: true });
+ for (const name of [
+ "framefields",
+ "effects",
+ "audio",
+ "signals",
+ "fonts",
+ "components",
+ "player",
+ ]) {
+ // Importing runs the module's top-level code, as a browser would.
+ await import(pathToFileURL(path.join(dir, `${name}.mjs`)).href);
}
- }, 120_000);
+ });
+
+ it.skipIf(!hasInter)(
+ "runs installed components on the engine's own toolkit and fonts",
+ async () => {
+ const project = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-components-"),
+ );
+ try {
+ // Installed as `npx framefields add text-reveal` writes it.
+ const registryDir = path.join(project, "registry");
+ writeRegistry(await buildRegistry(), registryDir);
+ await fs.promises.mkdir(path.join(project, "src"));
+ await add(["text-reveal"], {
+ cwd: project,
+ registry: openRegistry(registryDir),
+ });
+ const entry = path.join(project, "src", "film.ts");
+ await fs.promises.writeFile(
+ entry,
+ [
+ 'import { FontManager } from "framefields/fonts";',
+ 'import { TextReveal } from "./components/text-reveal/index.js";',
+ "export async function check(bytes: Uint8Array) {",
+ '\tawait FontManager.register({ family: "Brand", source: bytes });',
+ '\tconst text = { text: "Hello", fontSize: 40 };',
+ '\tconst node = TextReveal({ ...text, fontFamily: "Brand" });',
+ '\tlet unregistered = "";',
+ "\ttry {",
+ '\t\tTextReveal({ ...text, fontFamily: "Nope" });',
+ "\t} catch (err) {",
+ "\t\tunregistered = (err as Error).message;",
+ "\t}",
+ "\treturn {",
+ "\t\twidth: node.width,",
+ '\t\tmeasured: FontManager.measure("Hello", { ...text, fontFamily: "Brand" }).width,',
+ "\t\tunregistered,",
+ "\t};",
+ "}",
+ ].join("\n"),
+ );
+
+ const { code } = await bundleProject({
+ entry,
+ exportName: "check",
+ modelsDir: "",
+ ortBase: "",
+ });
+ // The toolkit comes from the engine, not bundled in again.
+ expect(code).toContain(`${ENGINE_URL}/components.mjs`);
+ expect(code).not.toContain("is not registered. Call");
+ expect(code.length).toBeLessThan(400_000);
+
+ // Run it on the built engine, with the player swapped for a stub
+ // that hands over the module.
+ const engine = pathToFileURL(dir).href;
+ await fs.promises.writeFile(
+ path.join(dir, "player-stub.mjs"),
+ "export function startPlayer(mod) { globalThis.__previewModule = mod; }",
+ );
+ await fs.promises.writeFile(
+ path.join(dir, "project.mjs"),
+ code
+ .replaceAll(`${ENGINE_URL}/player.mjs`, `${engine}/player-stub.mjs`)
+ .replaceAll(ENGINE_URL, engine),
+ );
+ await import(pathToFileURL(path.join(dir, "project.mjs")).href);
+ const mod = (
+ globalThis as { __previewModule?: Record<string, unknown> }
+ ).__previewModule as {
+ check(bytes: Uint8Array): Promise<{
+ width: number;
+ measured: number;
+ unregistered: string;
+ }>;
+ };
+ const result = await mod.check(
+ new Uint8Array(await fs.promises.readFile(INTER)),
+ );
+
+ // One FontManager: the component sees the font the project registered…
+ expect(result.unregistered).toMatch(/Registered: Brand\b/);
+ // …and lays its text out with it.
+ expect(result.width).toBeCloseTo(result.measured, 3);
+ expect(result.width).toBeGreaterThan(0);
+ } finally {
+ await fs.promises.rm(project, { recursive: true, force: true });
+ }
+ },
+ 60_000,
+ );
});
describe("prebuiltEngineDir", () => {
diff --git a/packages/renderers/src/font-source.ts b/packages/renderers/src/font-source.ts
new file mode 100644
index 00000000..35e61c13
--- /dev/null
+++ b/packages/renderers/src/font-source.ts
@@ -0,0 +1,24 @@
+import { GetFontAssetUrl } from "@framefields/client-utils";
+import {
+ getHeadlessFontPath,
+ getRegisteredFontSource,
+} from "@framefields/webgpu-renderers";
+
+/**
+ * Where a family's font loads from: the file, URL or bytes it was registered
+ * with (`FontManager.register`), else the `assets/fonts/<Family>.ttf`
+ * naming convention, which would miss e.g. "Foo-Regular.ttf" or bytes.
+ */
+export function fontSource(family: string): string | Uint8Array {
+ return (
+ getRegisteredFontSource(family) ??
+ getHeadlessFontPath(family) ??
+ GetFontAssetUrl(family)
+ );
+}
+
+/** {@link fontSource} as a URL or path, for loaders that only take one. */
+export function fontUrl(family: string): string {
+ const source = fontSource(family);
+ return typeof source === "string" ? source : GetFontAssetUrl(family);
+}
diff --git a/packages/renderers/src/preload-fonts.ts b/packages/renderers/src/preload-fonts.ts
index 3f415b8f..bb88aa31 100644
--- a/packages/renderers/src/preload-fonts.ts
+++ b/packages/renderers/src/preload-fonts.ts
@@ -1,9 +1,6 @@
-import { GetFontAssetUrl } from "@framefields/client-utils";
import type { VirtualMediaData } from "@framefields/core";
-import {
- getHeadlessFontPath,
- SlugFontCache,
-} from "@framefields/webgpu-renderers";
+import { SlugFontCache } from "@framefields/webgpu-renderers";
+import { fontSource, fontUrl } from "./font-source.js";
import { preloadFont } from "./utils.js";
const EMOJI_REGEX = /\p{Extended_Pictographic}/gu;
@@ -48,12 +45,14 @@ export async function preloadCompositionFonts(
const tasks: Promise<unknown>[] = [];
for (const family of families) {
- // Fonts registered through FontManager carry their real file path; the
- // asset URL is only a naming convention and would miss e.g. "Foo-Regular.ttf".
- const url = getHeadlessFontPath(family) ?? GetFontAssetUrl(family);
+ // A registered family loads from what it was registered with; a family
+ // SlugFontCache has parsed already never fetches `url`.
+ const source = fontSource(family);
+ const url = fontUrl(family);
+ const from = typeof source === "string" ? source : "its registered bytes";
tasks.push(
- preloadFont(family, url).catch((err) =>
- onError(err, `font "${family}" from ${url}`),
+ preloadFont(family, source).catch((err) =>
+ onError(err, `font "${family}" from ${from}`),
),
);
if (device) {
diff --git a/packages/renderers/src/text-measurer.ts b/packages/renderers/src/text-measurer.ts
index 82750a6e..38c30599 100644
--- a/packages/renderers/src/text-measurer.ts
+++ b/packages/renderers/src/text-measurer.ts
@@ -1,6 +1,6 @@
-import { GetFontAssetUrl } from "@framefields/client-utils";
import type { TextSpan } from "@framefields/core";
import { SlugFontCache, SlugGeometry } from "@framefields/webgpu-renderers";
+import { fontUrl } from "./font-source.js";
export interface TextMeasureStyle {
fontFamily?: string;
@@ -69,8 +69,11 @@ export function measureText(
if (!slugFont) {
// Trigger preload for future calls if it hasn't failed yet
if (!SlugFontCache.isFailed(fontFamily)) {
- const fontUrl = GetFontAssetUrl(fontFamily);
- SlugFontCache.preloadSlugFont(null, fontFamily, fontUrl).catch(() => {});
+ SlugFontCache.preloadSlugFont(
+ null,
+ fontFamily,
+ fontUrl(fontFamily),
+ ).catch(() => {});
}
// Fallback estimation with word wrap support
@@ -149,9 +152,7 @@ export function measureTextAsync(
return Promise.resolve(measureText(text, style));
}
- const fontUrl = GetFontAssetUrl(fontFamily);
-
- return SlugFontCache.preloadSlugFont(null, fontFamily, fontUrl)
+ return SlugFontCache.preloadSlugFont(null, fontFamily, fontUrl(fontFamily))
.then(() => measureText(text, style))
.catch(() => measureText(text, style));
}
diff --git a/packages/renderers/src/utils.ts b/packages/renderers/src/utils.ts
index d779c1c9..210871c3 100644
--- a/packages/renderers/src/utils.ts
+++ b/packages/renderers/src/utils.ts
@@ -3,21 +3,29 @@ import { registerHeadlessFont } from "@framefields/webgpu-renderers";
/**
* Preloads a font into the browser or headless environment.
*/
-export async function preloadFont(family: string, url: string): Promise<void> {
+export async function preloadFont(
+ family: string,
+ source: string | Uint8Array,
+): Promise<void> {
if (typeof window !== "undefined" && typeof FontFace !== "undefined") {
+ const from = typeof source === "string" ? source : "its registered bytes";
try {
- const font = new FontFace(family, `url(${url})`);
+ const font = new FontFace(
+ family,
+ typeof source === "string" ? `url(${source})` : source,
+ );
const loadedFace = await font.load();
(document.fonts as any).add(loadedFace);
await document.fonts.ready;
} catch (e) {
console.warn(
- `[preloadFont] Failed to load font "${family}" from ${url}:`,
+ `[preloadFont] Failed to load font "${family}" from ${from}:`,
e,
);
}
} else {
- // Headless / Node.js mode
- await registerHeadlessFont(family, url);
+ // Headless / Node.js mode: bytes have no file to register (FontManager
+ // registers the file of a font it read from one).
+ if (typeof source === "string") await registerHeadlessFont(family, source);
}
}
diff --git a/packages/webgpu-renderers/src/headless-font-loader.ts b/packages/webgpu-renderers/src/headless-font-loader.ts
index 363da7a1..88598929 100644
--- a/packages/webgpu-renderers/src/headless-font-loader.ts
+++ b/packages/webgpu-renderers/src/headless-font-loader.ts
@@ -152,6 +152,33 @@ export function getHeadlessFontPath(family: string): string | undefined {
return fontPaths.get(family);
}
+// Shared by every copy of the engine on a page, as SlugFontCache's maps are.
+const FONT_SOURCES_KEY = Symbol.for("framefields.fontSources");
+const sharedGlobals = globalThis as Record<symbol, unknown>;
+sharedGlobals[FONT_SOURCES_KEY] ??= new Map();
+const fontSources = sharedGlobals[FONT_SOURCES_KEY] as Map<
+ string,
+ string | Uint8Array
+>;
+
+/**
+ * Records where a registered family's font came from (its path or URL, or
+ * its bytes), so loaders use it instead of guessing a file by family name.
+ */
+export function setRegisteredFontSource(
+ family: string,
+ source: string | Uint8Array,
+): void {
+ fontSources.set(family, source);
+}
+
+/** The path, URL or bytes a family was registered from, if it was. */
+export function getRegisteredFontSource(
+ family: string,
+): string | Uint8Array | undefined {
+ return fontSources.get(family);
+}
+
export async function getHeadlessFontData(
family: string,
): Promise<Uint8Array | undefined> {
diff --git a/packages/webgpu-renderers/src/slug/slug-font-cache.ts b/packages/webgpu-renderers/src/slug/slug-font-cache.ts
index e580a38f..9ac7b557 100644
--- a/packages/webgpu-renderers/src/slug/slug-font-cache.ts
+++ b/packages/webgpu-renderers/src/slug/slug-font-cache.ts
@@ -68,6 +68,111 @@ function parseFontBuffer(bytes: Uint8Array): FontkitFont {
return font;
}
+/**
+ * A font file's bytes: read from disk in Node (the URL as a path, then the
+ * font directories by family name), fetched elsewhere.
+ */
+async function loadFontBuffer(
+ fontFamily: string,
+ fontUrl: string,
+): Promise<ArrayBuffer> {
+ let buffer: ArrayBuffer;
+ const isNode =
+ !!(globalThis as Record<string, unknown>).__IS_HEADLESS_RENDERER__ ||
+ typeof window === "undefined" ||
+ typeof globalThis.document === "undefined";
+ const isHttp =
+ fontUrl.startsWith("http://") || fontUrl.startsWith("https://");
+
+ if (isNode && !isHttp) {
+ // Node.js local file environment
+ const fs = await import(/* webpackIgnore: true */ "node:fs/promises");
+ const path = await import(/* webpackIgnore: true */ "node:path");
+ const fontDirs: string[] = [];
+ if (process.env.FONTS_DIR) {
+ fontDirs.push(path.resolve(process.env.FONTS_DIR));
+ }
+ if (process.env.FRAMEFIELDS_FONTS_DIR) {
+ fontDirs.push(path.resolve(process.env.FRAMEFIELDS_FONTS_DIR));
+ }
+
+ // Upward traversal to locate assets/fonts in parent monorepo roots
+ let currentDir = process.cwd();
+ for (let i = 0; i < 5; i++) {
+ fontDirs.push(path.resolve(currentDir, "assets/fonts"));
+ const parent = path.dirname(currentDir);
+ if (parent === currentDir) break;
+ currentDir = parent;
+ }
+
+ const candidates: string[] = [];
+ const addCandidate = (candidatePath: string) => {
+ if (!candidates.includes(candidatePath)) {
+ candidates.push(candidatePath);
+ }
+ };
+
+ if (fontUrl && !fontUrl.startsWith("//api/")) {
+ let fontPath = fontUrl;
+ if (fontUrl.startsWith("file://")) {
+ try {
+ fontPath = new URL(fontUrl).pathname;
+ } catch {
+ fontPath = fontUrl.replace(/^file:\/\//, "");
+ }
+ }
+ addCandidate(fontPath);
+ addCandidate(path.resolve(process.cwd(), fontPath));
+ for (const dir of fontDirs) {
+ addCandidate(path.resolve(dir, path.basename(fontPath)));
+ }
+ }
+ const cleanFamily = fontFamily.replace(/['"]/g, "").trim();
+ const variations = [
+ cleanFamily,
+ cleanFamily.replace(/ /g, ""),
+ cleanFamily.replace(/ /g, "_"),
+ ];
+ for (const dir of fontDirs) {
+ for (const v of variations) {
+ addCandidate(path.resolve(dir, `${v}.ttf`));
+ addCandidate(path.resolve(dir, `${v}.otf`));
+ }
+ }
+ for (const dir of fontDirs) {
+ addCandidate(path.resolve(dir, "Inter.ttf"));
+ addCandidate(path.resolve(dir, "Inter.otf"));
+ }
+
+ let nodeBuffer: Buffer | null = null;
+ for (const c of candidates) {
+ try {
+ nodeBuffer = await fs.readFile(c);
+ if (nodeBuffer && nodeBuffer.length > 0) break;
+ } catch {}
+ }
+ if (!nodeBuffer) {
+ throw new Error(
+ `Could not resolve font file for "${fontFamily}" (${fontUrl})`,
+ );
+ }
+ buffer = nodeBuffer.buffer.slice(
+ nodeBuffer.byteOffset,
+ nodeBuffer.byteOffset + nodeBuffer.byteLength,
+ ) as ArrayBuffer;
+ } else {
+ // Browser/Web or remote URL environment
+ const response = await fetch(fontUrl);
+ if (!response.ok) {
+ throw new Error(
+ `Failed to fetch font from ${fontUrl}: ${response.statusText}`,
+ );
+ }
+ buffer = await response.arrayBuffer();
+ }
+ return buffer;
+}
+
function recreateTextures(device: GPUDevice, slugFont: SlugFont): void {
if (slugFont.curvesTex) return;
uploadSlugTextures(device, slugFont);
@@ -95,6 +200,8 @@ export class SlugFontCache {
/** Register an already parsed font (e.g. by FontManager) under a family name. */
public static setParsed(fontFamily: string, font: FontkitFont): void {
SlugFontCache.parsedFontCache.set(fontFamily, font);
+ // A lookup that missed before the font was registered no longer counts.
+ SlugFontCache.failedFonts.delete(fontFamily);
}
public static getParsed(fontFamily: string): FontkitFont | null {
@@ -645,110 +752,14 @@ export class SlugFontCache {
} else {
activePromise = (async () => {
try {
- let buffer: ArrayBuffer;
- const isNode =
- !!(globalThis as Record<string, unknown>)
- .__IS_HEADLESS_RENDERER__ ||
- typeof window === "undefined" ||
- typeof globalThis.document === "undefined";
- const isHttp =
- fontUrl.startsWith("http://") || fontUrl.startsWith("https://");
-
- if (isNode && !isHttp) {
- // Node.js local file environment
- const fs = await import(
- /* webpackIgnore: true */ "node:fs/promises"
- );
- const path = await import(
- /* webpackIgnore: true */ "node:path"
- );
- const fontDirs: string[] = [];
- if (process.env.FONTS_DIR) {
- fontDirs.push(path.resolve(process.env.FONTS_DIR));
- }
- if (process.env.FRAMEFIELDS_FONTS_DIR) {
- fontDirs.push(
- path.resolve(process.env.FRAMEFIELDS_FONTS_DIR),
- );
- }
-
- // Upward traversal to locate assets/fonts in parent monorepo roots
- let currentDir = process.cwd();
- for (let i = 0; i < 5; i++) {
- fontDirs.push(path.resolve(currentDir, "assets/fonts"));
- const parent = path.dirname(currentDir);
- if (parent === currentDir) break;
- currentDir = parent;
- }
-
- const candidates: string[] = [];
- const addCandidate = (candidatePath: string) => {
- if (!candidates.includes(candidatePath)) {
- candidates.push(candidatePath);
- }
- };
-
- if (fontUrl && !fontUrl.startsWith("//api/")) {
- let fontPath = fontUrl;
- if (fontUrl.startsWith("file://")) {
- try {
- fontPath = new URL(fontUrl).pathname;
- } catch {
- fontPath = fontUrl.replace(/^file:\/\//, "");
- }
- }
- addCandidate(fontPath);
- addCandidate(path.resolve(process.cwd(), fontPath));
- for (const dir of fontDirs) {
- addCandidate(path.resolve(dir, path.basename(fontPath)));
- }
- }
- const cleanFamily = fontFamily.replace(/['"]/g, "").trim();
- const variations = [
- cleanFamily,
- cleanFamily.replace(/ /g, ""),
- cleanFamily.replace(/ /g, "_"),
- ];
- for (const dir of fontDirs) {
- for (const v of variations) {
- addCandidate(path.resolve(dir, `${v}.ttf`));
- addCandidate(path.resolve(dir, `${v}.otf`));
- }
- }
- for (const dir of fontDirs) {
- addCandidate(path.resolve(dir, "Inter.ttf"));
- addCandidate(path.resolve(dir, "Inter.otf"));
- }
-
- let nodeBuffer: Buffer | null = null;
- for (const c of candidates) {
- try {
- nodeBuffer = await fs.readFile(c);
- if (nodeBuffer && nodeBuffer.length > 0) break;
- } catch {}
- }
- if (!nodeBuffer) {
- throw new Error(
- `Could not resolve font file for "${fontFamily}" (${fontUrl})`,
- );
- }
- buffer = nodeBuffer.buffer.slice(
- nodeBuffer.byteOffset,
- nodeBuffer.byteOffset + nodeBuffer.byteLength,
- ) as ArrayBuffer;
- } else {
- // Browser/Web or remote URL environment
- const response = await fetch(fontUrl);
- if (!response.ok) {
- throw new Error(
- `Failed to fetch font from ${fontUrl}: ${response.statusText}`,
- );
- }
- buffer = await response.arrayBuffer();
- }
-
+ // A font registered with FontManager is parsed already: no file to find.
+ const registered = SlugFontCache.parsedFontCache.get(fontFamily);
const startTime = performance.now();
- const font = parseFontBuffer(new Uint8Array(buffer));
+ const font =
+ registered ??
+ parseFontBuffer(
+ new Uint8Array(await loadFontBuffer(fontFamily, fontUrl)),
+ );
const parseTime = performance.now();
SlugFontCache.parsedFontCache.set(fontFamily, font);