AI-native design editor. Open-source Figma alternative.
/* eslint-disable max-lines -- font loading and registration share FontManager lifecycle state */
import type { CanvasKit, TypefaceFontProvider } from 'canvaskit-wasm'
import { uniq } from 'es-toolkit/array'
import type { FontVariation, SceneGraph } from '@open-pencil/scene-graph'
import {
faceLoadKey,
namesWeight,
normalizeFontFamily,
parseFontStyle
} from '@open-pencil/scene-graph/font-style'
import { DEFAULT_FONT_FAMILY, IS_BROWSER } from '#core/constants'
import {
fallbackDrawsCharacter,
fontFallbackEntry,
type FontFallbackScript
} from '#core/text/fallbacks'
import { BundledFonts, type BundledFontLocator } from '#core/text/font/bundled'
import { FamilyFaceCatalog, type HostFontFamily } from '#core/text/font/catalog'
import {
browserFaceDescriptors,
fontFaceRenderFamily,
type FamilyFace
} from '#core/text/font/faces'
import { loadHarfBuzz } from '#core/text/font/harfbuzz'
import { LocalFonts } from '#core/text/font/local'
import { sameFontFile, SharedReads, withHarfBuzz } from '#core/text/font/reads'
import {
UnsupportedFontFormatError,
type DownloadedFontCache,
type FontFamilyOption,
type FontInfo,
type FontLoadedSource,
type FontUnavailableReason,
type HostFontLoader,
type LocalFontAccessState
} from '#core/text/font/sources'
import { fontStandIn, standInFont } from '#core/text/font/stand-in'
import {
fontAxes,
hasNamedInstance,
namedInstances,
namedInstanceVariations,
type FontAxis,
type NamedInstance
} from '#core/text/font/variation'
import { sfntFont } from '#core/text/font/woff2'
import { collectGraphFontKeys } from '#core/text/requirements/collect'
import { normalizedCoverageText, WebFontResolver } from '#core/text/web-font/resolver'
import type { WebFontFetch, WebFontProviderId } from '#core/text/web-font/resolver'
export type { BundledFontLocator } from '#core/text/font/bundled'
export class FontManager {
private loadedFamilies = new Map<string, ArrayBuffer>()
private loadedFamilySources = new Map<string, FontLoadedSource>()
private unavailableFaces = new Map<string, FontUnavailableReason>()
/** Faces a load looked for everywhere and found nowhere, until one of them loads after all. */
private missingFaces = new Set<string>()
private supplementalFamilyData = new Map<string, ArrayBuffer[]>()
/** The name each file of a family loaded from several files is registered under. */
private fileFamilies = new Map<ArrayBuffer, string>()
/**
* Families a style's file was replaced in, such as a web font fetched again for more characters.
* The old file stays registered first under the family's name, and CanvasKit draws with the
* first file it has for a style, so these draw from each file's own name.
*/
private replacedFamilies = new Set<string>()
/**
* The files each style's own file replaced, by `family|style`. They stay its fallbacks under
* names of their own, never beside the file that replaced them, where CanvasKit would pick
* between the two by the weight each declares.
*/
private replacedFileData = new Map<string, Set<ArrayBuffer>>()
private remoteCoverage = new Map<string, Set<string>>()
private instanceVariations = new WeakMap<ArrayBuffer, Map<string, FontVariation[] | null>>()
private variations = new WeakMap<
ArrayBuffer,
{ axes: FontAxis[]; instances: NamedInstance[] } | null
>()
/** Layers kept off the canvas while their fonts are prepared, by graph, with how many hold each. */
private blockedNodes = new WeakMap<SceneGraph, Map<string, number>>()
private fontProvider: TypefaceFontProvider | null = null
private fontProviders = new Set<TypefaceFontProvider>()
private providerCanvasKits = new WeakMap<TypefaceFontProvider, CanvasKit>()
private registrationGeneration = 0
private providerRegistrations = new WeakMap<TypefaceFontProvider, Map<string, Set<ArrayBuffer>>>()
private downloadedFontCache: DownloadedFontCache | null = null
private fallbackUserAgent: string | undefined
private hostFontLoader: HostFontLoader | null = null
private readonly hostFontRequests = new SharedReads()
private webFonts = new WebFontResolver()
private readonly faceListeners = new Set<(family: string, style: string) => void>()
private readonly bundled = new BundledFonts()
private readonly localFonts = new LocalFonts()
private readonly faces = new FamilyFaceCatalog({
localFonts: () => this.localFonts.list(),
webFaces: (family) => this.webFonts.familyFaces(family),
bundledStyles: (family) => this.bundled.styles(family)
})
private cjkFallbackFamilies: string[] = []
private cjkFallbackPromise: Promise<string[]> | null = null
private arabicFallbackFamilies: string[] = []
private arabicFallbackPromise: Promise<string[]> | null = null
private readonly sharedProviders = new Map<
CanvasKit,
{ provider: TypefaceFontProvider; users: number }
>()
/**
* The provider every renderer and shaper of `canvasKit` draws from. They share one module's
* heap, and a provider holds its own copy of each font file, so a second provider would copy
* every face again: the scene and overlay canvases, and every CJK system font, alike. Each call
* is matched by {@link releaseProvider}; the last release deletes it.
*/
acquireProvider(canvasKit: CanvasKit): TypefaceFontProvider {
const shared = this.sharedProviders.get(canvasKit)
if (shared) {
shared.users++
return shared.provider
}
const provider = canvasKit.TypefaceFontProvider.Make()
this.sharedProviders.set(canvasKit, { provider, users: 1 })
this.attachProvider(canvasKit, provider)
return provider
}
releaseProvider(provider: TypefaceFontProvider): void {
for (const [canvasKit, shared] of this.sharedProviders) {
if (shared.provider !== provider) continue
if (--shared.users > 0) return
this.sharedProviders.delete(canvasKit)
this.detachProvider(provider)
provider.delete()
return
}
}
attachProvider(canvasKit: CanvasKit, provider: TypefaceFontProvider): void {
this.fontProviders.add(provider)
this.providerCanvasKits.set(provider, canvasKit)
this.fontProvider = provider
this.providerRegistrations.set(provider, new Map())
this.registrationGeneration++
for (const [cacheKey, data] of this.loadedFamilies) {
const separator = cacheKey.indexOf('|')
const family = cacheKey.slice(0, separator)
this.registerFontInProvider(provider, family, data)
for (const supplemental of this.supplementalFamilyData.get(cacheKey) ?? []) {
this.registerFontInProvider(provider, family, supplemental)
}
}
}
detachProvider(provider: TypefaceFontProvider): void {
this.fontProviders.delete(provider)
this.providerRegistrations.delete(provider)
if (this.fontProvider === provider) {
this.fontProvider = Array.from(this.fontProviders).at(-1) ?? null
}
}
provider(): TypefaceFontProvider | null {
return this.fontProvider
}
/** The latest attached provider made by `canvasKit`; another build's provider cannot shape with it. */
providerFor(canvasKit: CanvasKit): TypefaceFontProvider | null {
return (
Array.from(this.fontProviders)
.reverse()
.find((provider) => this.providerCanvasKits.get(provider) === canvasKit) ?? null
)
}
generation(): number {
return this.registrationGeneration
}
/**
* Keeps `nodeIds` of `graph` off the canvas until each is unblocked as many times as it was
* blocked, so one preparation that ends does not show text another still prepares.
*/
blockNodesUntilFontsResolve(graph: SceneGraph, nodeIds: readonly string[]): void {
let blocked = this.blockedNodes.get(graph)
if (!blocked) {
blocked = new Map()
this.blockedNodes.set(graph, blocked)
}
for (const nodeId of nodeIds) blocked.set(nodeId, (blocked.get(nodeId) ?? 0) + 1)
}
unblockNodes(graph: SceneGraph, nodeIds: readonly string[]): void {
const blocked = this.blockedNodes.get(graph)
if (!blocked) return
for (const nodeId of nodeIds) {
const holds = blocked.get(nodeId) ?? 0
if (holds > 1) blocked.set(nodeId, holds - 1)
else blocked.delete(nodeId)
}
}
isNodeBlocked(graph: SceneGraph, nodeId: string): boolean {
return this.blockedNodes.get(graph)?.has(nodeId) ?? false
}
localAccessState(): LocalFontAccessState {
return this.localFonts.accessState()
}
setDownloadedFontCache(cache: DownloadedFontCache | null): void {
this.downloadedFontCache = cache
}
setFallbackUserAgent(userAgent: string | undefined): void {
this.fallbackUserAgent = userAgent
}
setHostFontLoader(loader: HostFontLoader | null): void {
this.hostFontLoader = loader
this.hostFontRequests.clear()
}
/** Lets a host that bundles `@open-pencil/core/assets` itself say where each file ended up. */
setBundledFontLocator(locate: BundledFontLocator | null): void {
this.bundled.setLocator(locate)
}
setOnlineFontProviders(settings: Partial<Record<WebFontProviderId, boolean>>): void {
this.webFonts.setEnabled(settings)
this.faces.forget()
}
/** The system fonts a desktop host lists, by family, with the style names of their faces. */
setHostFontCatalog(fonts: readonly HostFontFamily[]): void {
this.faces.setHostCatalog(fonts)
}
/**
* The faces a family has: its installed fonts', else a web provider's, else the bundled ones;
* `null` when nothing says, so a caller offers every weight.
*/
familyFaces(family: string): Promise<FamilyFace[] | null> {
return this.faces.faces(family)
}
/** The faces `familyFaces` found for a family, once it has; `undefined` before. */
loadedFamilyFaces(family: string): FamilyFace[] | null | undefined {
return this.faces.foundFaces(family)
}
/** Whether a family has this face, or nothing found so far says it has not. */
offersFace(family: string, weight: number, italic: boolean): boolean {
return this.faces.offersFace(family, weight, italic)
}
/** Calls the listener whenever the faces found so far are forgotten. */
onFamilyFacesReset(listener: () => void): () => void {
return this.faces.onReset(listener)
}
/** The faces known for a family without asking a provider; see {@link FamilyFaceCatalog}. */
familyFacesSync(family: string): FamilyFace[] | null {
return this.faces.facesSync(family)
}
setWebFontFetch(fetcher: WebFontFetch | null): void {
this.webFonts.setRemoteFetch(fetcher)
}
resetWebFontFailures(family?: string, style?: string): void {
this.webFonts.resetFailures(family, style)
}
enabledOnlineFontProviders(): WebFontProviderId[] {
return this.webFonts.enabledProviders()
}
loadCachedFont(family: string, style = 'Regular', characters = ''): Promise<ArrayBuffer | null> {
return withHarfBuzz(this.restoreCachedFont(family, style, characters))
}
private async restoreCachedFont(
family: string,
style = 'Regular',
characters = ''
): Promise<ArrayBuffer | null> {
const cached = await this.readDownloadedFont(family, style, characters)
if (!cached) return null
const key = `${family}|${style}`
const loadedCoverage = this.remoteCoverage.get(key) ?? new Set<string>()
for (const character of normalizedCoverageText(characters)) loadedCoverage.add(character)
this.remoteCoverage.set(key, loadedCoverage)
return this.registerAndCache(family, style, cached, 'cache')
}
async requestLocalFontAccess(): Promise<FontInfo[]> {
const fonts = await this.localFonts.requestAccess()
this.faces.forget()
return fonts
}
async listFamilies(): Promise<string[]> {
const options = await this.listFamilyOptions()
return options.map((option) => option.family)
}
async listFamilyOptions(): Promise<FontFamilyOption[]> {
const fonts = this.localFonts.list() ?? (await this.requestLocalFontAccess())
const webFontFamilies = await Promise.all(
this.enabledOnlineFontProviders().map(async (provider) => ({
provider,
families: await this.webFonts.listFamilies(provider)
}))
)
const byFamily = new Map<string, FontFamilyOption>()
byFamily.set(DEFAULT_FONT_FAMILY, { family: DEFAULT_FONT_FAMILY, source: 'bundled' })
for (const { provider, families } of webFontFamilies) {
for (const family of families) {
if (!byFamily.has(family)) byFamily.set(family, { family, source: provider })
}
}
for (const font of fonts) byFamily.set(font.family, { family: font.family, source: 'local' })
return [...byFamily.values()].sort((a, b) => a.family.localeCompare(b.family))
}
preloadWebFontFamilies(): void {
this.webFonts.preloadFamilies()
}
/** Reads a bundled font; concurrent loads of one file share a request. */
fetchBundledFont(url: string): Promise<ArrayBuffer | null> {
return this.bundled.fetch(url)
}
loadLocalFont(family: string, style = 'Regular'): Promise<ArrayBuffer | null> {
return withHarfBuzz(this.findLocalOrBundledFont(family, style))
}
private async findLocalOrBundledFont(
family: string,
style = 'Regular'
): Promise<ArrayBuffer | null> {
const loaded = this.loadedFamilies.get(`${family}|${style}`)
if (loaded) {
this.registerFontInCanvasKit(family, loaded)
return loaded
}
return (
(await this.loadInstalledFont(family, style)) ?? (await this.loadBundledFont(family, style))
)
}
/** The face installed on this machine, from the host or the browser's local fonts. */
private async loadInstalledFont(family: string, style: string): Promise<ArrayBuffer | null> {
const hostBuffer = await this.loadHostFont(family, style)
if (hostBuffer) return this.registerAndCache(family, style, hostBuffer, 'local')
const localBuffer = await this.localFonts.read(family, style)
return localBuffer ? this.registerAndCache(family, style, localBuffer, 'local') : null
}
private async loadBundledFont(family: string, style: string): Promise<ArrayBuffer | null> {
const bundledURL = this.bundled.file(family, style)
if (!bundledURL) return null
try {
const buffer = await this.fetchBundledFont(bundledURL)
return buffer ? this.registerAndCache(family, style, buffer, 'bundled') : null
} catch (e) {
console.warn(`Bundled font load failed for "${family}" ${style}:`, e)
return null
}
}
loadRemoteFont(
family: string,
style = 'Regular',
characters = '',
signal?: AbortSignal
): Promise<ArrayBuffer | null> {
return withHarfBuzz(this.downloadFont(family, style, characters, signal))
}
private async downloadFont(
family: string,
style = 'Regular',
characters = '',
signal?: AbortSignal
): Promise<ArrayBuffer | null> {
signal?.throwIfAborted()
if (typeof fetch === 'undefined') return null
const coverage = this.remoteCoverage.get(`${family}|${style}`)
if (
characters &&
coverage &&
Array.from(characters).every((character) => coverage.has(character))
) {
return this.loadedData(family, style)
}
try {
const requestedCharacters = normalizedCoverageText(
`${coverage ? Array.from(coverage).join('') : ''}${characters}`
)
const normalized = normalizeFontFamily(family)
const families = normalized === family ? [family] : [family, normalized]
const resolved = await this.webFonts.fetchFont(families, style, requestedCharacters, signal)
if (!resolved || resolved.buffers.length === 0) return null
const primary = resolved.buffers[0]
// Providers serve faces by weight; a named face comes only from a variable file that has it.
if (!namesWeight(style) && !hasNamedInstance(primary, style)) return null
await this.writeDownloadedFont(family, style, primary, requestedCharacters)
const registered = this.registerAndCache(family, style, primary, resolved.provider)
const loadedCoverage = this.remoteCoverage.get(`${family}|${style}`) ?? new Set<string>()
for (const character of requestedCharacters) loadedCoverage.add(character)
this.remoteCoverage.set(`${family}|${style}`, loadedCoverage)
for (const supplemental of resolved.buffers.slice(1)) {
this.registerSupplemental(family, style, supplemental)
}
return registered
} catch (e) {
if (signal?.aborted) throw e
console.warn(`Web font fetch failed for "${family}" ${style}:`, e)
return null
}
}
loadFont(
family: string,
style = 'Regular',
characters = '',
signal?: AbortSignal
): Promise<ArrayBuffer | null> {
return withHarfBuzz(this.findFont(family, style, characters, signal))
}
private async findFont(
family: string,
style = 'Regular',
characters = '',
signal?: AbortSignal
): Promise<ArrayBuffer | null> {
signal?.throwIfAborted()
const loaded = this.loadedData(family, style)
// A stand-in gives way to the family's own face once it is installed or local access is granted.
if (loaded && this.loadedFontSource(family, style) === 'stand-in') {
const installed = await this.loadInstalledFont(family, style)
if (installed) return installed
this.registerFontInCanvasKit(family, loaded)
return loaded
}
if (loaded) {
this.registerFontInCanvasKit(family, loaded)
return this.withRemoteCoverage(family, style, loaded, characters, signal)
}
// An installed face of the style comes first; otherwise a variable file the family already
// loaded draws it.
const installed = await this.loadInstalledFont(family, style)
if (installed) return installed
const shared = this.sharedVariableFace(family, style)
if (shared) return this.withRemoteCoverage(family, style, shared, characters, signal)
const found =
(await this.loadBundledFont(family, style)) ??
(await this.loadCachedFont(family, style, characters)) ??
(await this.loadRemoteFont(family, style, characters, signal)) ??
(await this.loadStandIn(family, style))
if (!found) this.missingFaces.add(`${family}|${style}`)
return found
}
/**
* Whether a load looked for this face and found it nowhere, so text in it draws in another face,
* as Figma draws a missing font, rather than waiting for it.
*/
isFaceMissing(family: string, style: string): boolean {
return this.missingFaces.has(`${family}|${style}`)
}
/**
* The open font that draws a family nobody may ship, made to the family's widths and line box,
* under the family's own name, so text is laid out and drawn alike wherever it is read from.
*/
private async loadStandIn(family: string, style: string): Promise<ArrayBuffer | null> {
const standIn = fontStandIn(family)
if (!standIn) return null
try {
const file = await this.fetchBundledFont(standIn.file)
if (!file) return null
const font = standInFont(await sfntFont(file), standIn)
return font ? this.registerAndCache(family, style, font, 'stand-in') : null
} catch (e) {
console.warn(`Stand-in font load failed for "${family}" ${style}:`, e)
return null
}
}
/**
* `data`, or a web font fetched again with `characters` when it came from the web without them,
* as a provider cuts a font down to the text it is asked for.
*/
private async withRemoteCoverage(
family: string,
style: string,
data: ArrayBuffer,
characters: string,
signal?: AbortSignal
): Promise<ArrayBuffer> {
const remoteCoverage = this.remoteCoverage.get(`${family}|${style}`)
const missingRemoteCoverage = Boolean(
characters &&
remoteCoverage &&
Array.from(characters).some((character) => !remoteCoverage.has(character))
)
return missingRemoteCoverage
? ((await this.loadRemoteFont(family, style, characters, signal)) ?? data)
: data
}
/**
* A variable font the family loaded for another style in the same slant whose weight axis
* reaches this style's weight, registered for this style too: one file draws every weight.
*/
private sharedVariableFace(family: string, style: string): ArrayBuffer | null {
const { weight, italic } = parseFontStyle(style)
// A face named apart from its weight ("Condensed Bold") is drawn by a file that has it.
const named = !namesWeight(style)
for (const [key, data] of this.loadedFamilies) {
if (!key.startsWith(`${family}|`)) continue
if (parseFontStyle(key.slice(family.length + 1)).italic !== italic) continue
if (named && !hasNamedInstance(data, style)) continue
const wght = fontAxes(data)?.find((axis) => axis.tag === 'wght')
if (!wght || (!named && (weight < wght.min || weight > wght.max))) continue
const coverage = this.remoteCoverage.get(key)
if (coverage) this.remoteCoverage.set(`${family}|${style}`, new Set(coverage))
return this.registerAndCache(family, style, data, this.loadedFamilySources.get(key))
}
return null
}
async ensureNodeFont(family: string, weight: number): Promise<void> {
await this.loadFont(family, faceLoadKey(weight))
}
/** Registers a font the caller already has, resolving once its outlines can be read. */
async markLoaded(
family: string,
style: string,
data: ArrayBuffer,
source: FontLoadedSource = 'registered'
): Promise<void> {
this.registerAndCache(family, style, data, source)
await loadHarfBuzz()
}
loadedFontSource(family: string, style: string): FontLoadedSource | null {
return this.loadedFamilySources.get(`${family}|${style}`) ?? null
}
/** Why the host could not load an installed face, when it reported a reason. */
unavailableReason(family: string, style: string): FontUnavailableReason | null {
return this.unavailableFaces.get(`${family}|${style}`) ?? null
}
isLoaded(family: string): boolean {
return [...this.loadedFamilies.keys()].some((k) => k.startsWith(`${family}|`))
}
isStyleLoaded(family: string, style: string): boolean {
return this.loadedFamilies.has(`${family}|${style}`)
}
remoteStyleNeedsCoverage(family: string, style: string, characters: readonly string[]): boolean {
const coverage = this.remoteCoverage.get(`${family}|${style}`)
return !!coverage && characters.some((character) => !coverage.has(character))
}
loadedData(family: string, style: string): ArrayBuffer | null {
return this.loadedFamilies.get(`${family}|${style}`) ?? null
}
/**
* The variation axes and named instances of a family's variable font, from a face it has loaded,
* in the slant asked for where it has one: `null` when the faces it has loaded are static,
* `undefined` when it has loaded none.
*/
familyVariation(
family: string,
italic?: boolean
): { data: ArrayBuffer; axes: FontAxis[]; instances: NamedInstance[] } | null | undefined {
let loaded = false
let other: { data: ArrayBuffer; axes: FontAxis[]; instances: NamedInstance[] } | null = null
for (const [key, data] of this.loadedFamilies) {
if (!key.startsWith(`${family}|`)) continue
loaded = true
let variation = this.variations.get(data)
if (variation === undefined) {
const axes = fontAxes(data)
variation = axes ? { axes, instances: namedInstances(data) } : null
this.variations.set(data, variation)
}
if (!variation) continue
const slant = parseFontStyle(key.slice(family.length + 1)).italic
if (italic === undefined || slant === italic) return { data, ...variation }
other ??= { data, ...variation }
}
return loaded ? other : undefined
}
/** Axis coordinates for `style` when the loaded face is a variable font, otherwise `null`. */
namedInstanceVariations(family: string, style: string): FontVariation[] | null {
const data = this.loadedData(family, style)
if (!data) return null
let byStyle = this.instanceVariations.get(data)
if (!byStyle) {
byStyle = new Map()
this.instanceVariations.set(data, byStyle)
}
if (!byStyle.has(style)) byStyle.set(style, namedInstanceVariations(data, style))
return byStyle.get(style) ?? null
}
/**
* The family CanvasKit is asked for to draw `style` of `family`. A family loaded from one file
* draws under its own name, with every coverage shard, as some CJK and Arabic faces need to
* paint. Loaded from several files, such as a bundled static face beside a downloaded variable
* one, CanvasKit would pick among them by the weight each file declares, which can tie; each
* style then draws from the file loaded for it, registered with its shards under a name of the
* file's own. So does a family a style's file was replaced in, whose old file CanvasKit would
* keep drawing under the family's name. Only the style's coverage shards join its file under
* that name: a file it replaced, such as a static face cached before a variable one was
* fetched, could declare the weight asked for and be drawn instead of the file it is outlined
* from, so it draws only as a fallback, from `renderShardFamilies`.
*/
renderFamily(family: string, style: string): string {
const data = this.loadedData(family, style)
if (!data || (this.familyFileCount(family) < 2 && !this.replacedFamilies.has(family)))
return family
const name = this.fileFamily(family, data)
const replaced = this.replacedFileData.get(`${family}|${style}`)
for (const shard of this.supplementalFamilyData.get(`${family}|${style}`) ?? [])
if (!replaced?.has(shard)) this.registerFontInCanvasKit(name, shard)
return name
}
/**
* The names CanvasKit draws the other files of `style` of `family` under, such as the coverage
* shards of a web font split by unicode-range. CanvasKit draws a character only from the first
* file registered under a name, so each shard is a family of its own that text falls back to.
*/
renderShardFamilies(family: string, style: string): string[] {
return (this.supplementalFamilyData.get(`${family}|${style}`) ?? []).map((data) =>
this.fileFamily(family, data)
)
}
/** The files of `style` of `family` after its own, such as the shards of a split web font. */
shardData(family: string, style: string): readonly ArrayBuffer[] {
return this.supplementalFamilyData.get(`${family}|${style}`) ?? []
}
/** The name one file of `family` is registered under on its own. */
private fileFamily(family: string, data: ArrayBuffer): string {
let name = this.fileFamilies.get(data)
if (!name) {
name = fontFaceRenderFamily(family, `file ${this.fileFamilies.size + 1}`)
this.fileFamilies.set(data, name)
}
this.registerFontInCanvasKit(name, data)
return name
}
/** How many files the family's loaded styles come from. */
private familyFileCount(family: string): number {
const files = new Set<ArrayBuffer>()
for (const [key, data] of this.loadedFamilies) if (key.startsWith(`${family}|`)) files.add(data)
return files.size
}
collectFontKeys(graph: SceneGraph, nodeIds: string[]): Array<[string, string]> {
return collectGraphFontKeys(graph, nodeIds)
}
async ensureCJKFallback(): Promise<string[]> {
if (this.cjkFallbackFamilies.length > 0) return this.cjkFallbackFamilies
if (this.cjkFallbackPromise) return this.cjkFallbackPromise
this.cjkFallbackPromise = this.ensureFallbackFamilies('cjk', this.cjkFallbackFamilies)
return this.cjkFallbackPromise
}
getCJKFallbackFamilies(): string[] {
return this.cjkFallbackFamilies
}
setCJKFallbackFamily(family: string): void {
if (!this.cjkFallbackFamilies.includes(family)) {
this.cjkFallbackFamilies.push(family)
}
}
async ensureArabicFallback(): Promise<string[]> {
if (this.arabicFallbackFamilies.length > 0) return this.arabicFallbackFamilies
if (this.arabicFallbackPromise) return this.arabicFallbackPromise
this.arabicFallbackPromise = this.ensureFallbackFamilies('arabic', this.arabicFallbackFamilies)
return this.arabicFallbackPromise
}
ensureFallbackPack(
scripts: FontFallbackScript[] = ['cjk', 'arabic'],
characters = '',
signal?: AbortSignal
): Promise<Partial<Record<FontFallbackScript, string[]>>> {
return withHarfBuzz(this.loadFallbackPack(scripts, characters, signal))
}
private async loadFallbackPack(
scripts: FontFallbackScript[] = ['cjk', 'arabic'],
characters = '',
signal?: AbortSignal
): Promise<Partial<Record<FontFallbackScript, string[]>>> {
signal?.throwIfAborted()
const result: Partial<Record<FontFallbackScript, string[]>> = {}
await Promise.all(
scripts.map(async (script) => {
signal?.throwIfAborted()
const target = script === 'arabic' ? this.arabicFallbackFamilies : this.cjkFallbackFamilies
if (signal) {
result[script] = await this.ensureFallbackFamilies(script, target, characters, signal)
} else if (script === 'arabic' && !characters) {
result[script] = await this.ensureArabicFallback()
} else if (script === 'cjk' && !characters) {
result[script] = await this.ensureCJKFallback()
} else {
result[script] = await this.ensureFallbackFamilies(script, target, characters)
}
})
)
signal?.throwIfAborted()
return result
}
getArabicFallbackFamilies(): string[] {
return this.arabicFallbackFamilies
}
setArabicFallbackFamily(family: string): void {
if (!this.arabicFallbackFamilies.includes(family)) {
this.arabicFallbackFamilies.push(family)
}
}
/**
* Loads the fallback faces for `script`. The first installed one of its families comes in, and
* the next only for the characters of its writing system among `characters` that CanvasKit finds
* no glyph for in the fallbacks loaded: each is a whole system face, tens of megabytes for a CJK one, copied
* into CanvasKit. Web fonts come in, cut to the characters, when no installed face covers them.
*/
private async ensureFallbackFamilies(
script: FontFallbackScript,
targetFamilies: string[],
characters = '',
signal?: AbortSignal
): Promise<string[]> {
signal?.throwIfAborted()
const manifest = fontFallbackEntry(script, this.fallbackUserAgent)
const needed = uniq(Array.from(characters)).filter((character) =>
fallbackDrawsCharacter(script, character)
)
// Families only come in, so what one check resolved stays resolved.
let pending = needed
const missing = () => (pending = this.unresolvedCharacters(targetFamilies, pending))
let installed = false
for (const family of manifest.localFamilies) {
if (installed && missing().length === 0) break
signal?.throwIfAborted()
const buffer =
(await this.loadHostFont(family, 'Regular')) ?? (await this.localFonts.read(family))
signal?.throwIfAborted()
if (buffer && this.registerAndCache(family, 'Regular', buffer, 'fallback')) {
if (!targetFamilies.includes(family)) targetFamilies.push(family)
installed = true
}
}
const remoteCharacters = installed ? missing().join('') : characters
if (!installed || remoteCharacters) {
const results = await Promise.allSettled(
manifest.remoteFamilies.map(async (family) => {
signal?.throwIfAborted()
const data = await this.loadRemoteFont(family, 'Regular', remoteCharacters, signal)
signal?.throwIfAborted()
return data ? family : null
})
)
for (const result of results) {
if (
result.status === 'fulfilled' &&
result.value &&
!targetFamilies.includes(result.value)
) {
targetFamilies.push(result.value)
}
}
}
return targetFamilies
}
/**
* The characters CanvasKit finds no glyph for in `families`, shaped with the provider the
* canvas draws from. Without one, as in an export before any canvas or shaper holds it, it
* cannot tell and counts every character missing, so every family loads as it always did.
*/
private unresolvedCharacters(families: readonly string[], characters: string[]): string[] {
if (characters.length === 0) return []
if (families.length === 0) return characters
const shared = this.sharedProviders.entries().next().value
if (!shared) return characters
const [canvasKit, { provider }] = shared
const style = new canvasKit.ParagraphStyle({
textStyle: { fontFamilies: [...families], fontSize: 16 }
})
const builder = canvasKit.ParagraphBuilder.MakeFromFontProvider(style, provider)
try {
builder.addText(characters.join(''))
const paragraph = builder.build()
try {
paragraph.layout(Number.MAX_SAFE_INTEGER)
const unresolved = new Set(paragraph.unresolvedCodepoints())
return characters.filter((character) => unresolved.has(character.codePointAt(0) ?? 0))
} finally {
paragraph.delete()
}
} finally {
builder.delete()
}
}
private loadHostFont(family: string, style: string): Promise<ArrayBuffer | null> {
const loader = this.hostFontLoader
if (!loader) return Promise.resolve(null)
return this.hostFontRequests.read(`${family}|${style}`, () =>
this.readHostFont(loader, family, style)
)
}
private async readHostFont(
loader: HostFontLoader,
family: string,
style: string
): Promise<ArrayBuffer | null> {
const key = `${family}|${style}`
try {
const data = await loader(family, style)
// A read that started under a loader the host has replaced must not register its bytes.
if (this.hostFontLoader !== loader) return null
if (data) this.unavailableFaces.delete(key)
return data
} catch (e) {
// A failure from a replaced loader says nothing about the face the new loader serves.
if (this.hostFontLoader !== loader) return null
if (e instanceof UnsupportedFontFormatError) {
this.unavailableFaces.set(key, e.reason)
return null
}
console.warn(`Host fallback font load failed for "${family}" ${style}:`, e)
return null
}
}
private async readDownloadedFont(
family: string,
style: string,
characters = ''
): Promise<ArrayBuffer | null> {
if (!this.downloadedFontCache) return null
try {
return await this.downloadedFontCache.read(family, style, characters)
} catch (e) {
console.warn(`Downloaded font cache read failed for "${family}" ${style}:`, e)
return null
}
}
private async writeDownloadedFont(
family: string,
style: string,
data: ArrayBuffer,
characters = ''
): Promise<void> {
if (!this.downloadedFontCache) return
try {
await this.downloadedFontCache.write(family, style, data, characters)
} catch (e) {
console.warn(`Downloaded font cache write failed for "${family}" ${style}:`, e)
}
}
/** Adds `buffer` to the files of `style` after its own, returning the copy of it they keep. */
private registerSupplemental(
family: string,
style: string,
buffer: ArrayBuffer,
source?: FontLoadedSource
): ArrayBuffer {
const key = `${family}|${style}`
const supplemental = this.supplementalFamilyData.get(key) ?? []
const kept = supplemental.find((file) => sameFontFile(file, buffer))
if (kept) return kept
supplemental.push(buffer)
this.supplementalFamilyData.set(key, supplemental)
this.registerFontInCanvasKit(family, buffer)
if (!pageDrawsByName(source)) this.registerFontInBrowser(family, style, buffer)
return buffer
}
private registerAndCache(
family: string,
style: string,
buffer: ArrayBuffer,
source?: FontLoadedSource
): ArrayBuffer | null {
const key = `${family}|${style}`
this.missingFaces.delete(key)
const existing = this.loadedFamilies.get(key)
if (existing && sameFontFile(existing, buffer)) {
if (source) this.loadedFamilySources.set(key, source)
this.registerFontInCanvasKit(family, existing)
return existing
}
if (existing) {
const replaced = this.replacedFileData.get(key) ?? new Set<ArrayBuffer>()
replaced.add(
this.registerSupplemental(family, style, existing, this.loadedFamilySources.get(key))
)
this.replacedFileData.set(key, replaced)
this.replacedFamilies.add(family)
}
this.loadedFamilies.set(key, buffer)
if (source) this.loadedFamilySources.set(key, source)
this.registerFontInCanvasKit(family, buffer)
if (!pageDrawsByName(source)) this.registerFontInBrowser(family, style, buffer)
for (const listener of this.faceListeners) listener(family, style)
return buffer
}
/**
* Calls the listener with each face once its file is registered, by whatever path it loaded:
* a paste, a script, a retry, or the renderer.
*/
onFaceLoaded(listener: (family: string, style: string) => void): () => void {
this.faceListeners.add(listener)
return () => this.faceListeners.delete(listener)
}
private registerFontInCanvasKit(family: string, data: ArrayBuffer): boolean {
let registered = false
for (const provider of this.fontProviders) {
registered = this.registerFontInProvider(provider, family, data) || registered
}
return registered
}
private registerFontInProvider(
provider: TypefaceFontProvider,
family: string,
data: ArrayBuffer
): boolean {
if (data.byteLength < 4) return false
const registrations = this.providerRegistrations.get(provider) ?? new Map()
const registeredData = registrations.get(family)
if (registeredData?.has(data)) return true
try {
provider.registerFont(data, family)
const familyRegistrations = registeredData ?? new Set<ArrayBuffer>()
familyRegistrations.add(data)
registrations.set(family, familyRegistrations)
this.providerRegistrations.set(provider, registrations)
this.registrationGeneration++
return true
} catch {
return false
}
}
/** Makes a face available to the page's own text, such as fields over canvas labels. */
registerFontInBrowser(family: string, style: string, data: ArrayBuffer) {
if (!IS_BROWSER) return
const face = new FontFace(family, data, browserFaceDescriptors(style, data))
face
.load()
.then(() => document.fonts.add(face))
.catch(() => {
console.warn(`Failed to load font "${family}" (${style})`)
})
}
}
/**
* Whether the page draws a face from `source` by itself: it draws installed fonts by name and
* falls back to the system's. A browser face would copy a whole system file, and one under an
* installed family's name stands in for all of that family's faces: WebView2 draws their bold
* and italic text in it.
*/
function pageDrawsByName(source: FontLoadedSource | undefined): boolean {
return source === 'local' || source === 'fallback'
}
export const fontManager = new FontManager()