@docx-editor.dev/fonts

defaultFontsfunctionSource ↗

The whole default-font boot, in one call: load the bytes, register the paint-side faces, and hand back the fragment for the editor's fonts prop.

The two halves have to happen together and almost nobody wants them apart — [loadDefaultFonts](loadDefaultFonts) alone measures correctly and paints with whatever the platform substitutes; [installDefaultFontFaces](installDefaultFontFaces) alone paints correctly and paginates wrong. Every host was writing the same six lines to pair them, so this is that pairing.

Failures are WARNED, not thrown: a face that will not load degrades that one family to fixed-width measurement, which is a worse-looking document rather than no document. Pass onFailure to route them somewhere other than the console.

declare function defaultFonts(options?: LoadDefaultFontsOptions & {
    readonly onFailure?: (failure: DefaultFontLoadFailure) => void;
}): Promise<DefaultFontsFragment>;

installDefaultFontFacesfunctionSource ↗

OPTIONAL paint-side fidelity: register the packaged substitutes with the browser's FontFace API under the WORD family names, so painted glyphs use the same metrics layout measured with instead of whatever the platform substitutes for "Calibri". Presentation-only, app-triggered, idempotent per document (overlapping calls included); returns the number of faces registered. No-op outside a DOM environment.

NOT a substitute for [loadDefaultFonts](loadDefaultFonts). This affects painting only — calling it alone leaves the engine measuring on the fixed fallback, which looks right and paginates wrong. Pair it with loadDefaultFonts() fed to the editor's fonts prop.

The return value counts faces THIS call registered, so 0 covers "no DOM environment", "already registered", and "every face failed" alike; treat it as a diagnostic hint rather than a success signal.

declare function installDefaultFontFaces(options?: LoadDefaultFontsOptions & {
    readonly document?: Document;
}): Promise<number>;

loadDefaultFontsfunctionSource ↗

Load the packaged substitute faces for the given Word families (all five by default) and return a configuration fragment: byte-backed sources for the SUBSTITUTE families plus the Word-name → substitute substitution map, so a document naming "Calibri" resolves without the host mapping anything.

Only the requested families' assets are fetched, in parallel. A face that fails to load appears in failures and the rest of the fragment stays usable — compose it anyway and the missing face measures via the engine's fixed fallback.

declare function loadDefaultFonts(options?: LoadDefaultFontsOptions): Promise<DefaultFontsFragment>;

DefaultFontFaceRequestinterfaceSource ↗

A concrete font face request, structurally identical to the editor contract's.

interface DefaultFontFaceRequest

DefaultFontLoadFailureinterfaceSource ↗

One face that did not load. family is the Word name that was asked for, file the packaged asset that failed, and diagnostic a human-readable cause — a missing manifest entry, an HTTP status, a byte-length mismatch against the baked manifest, or a thrown fetch error.

Non-fatal by design: the surrounding fragment stays usable and the affected family falls back to the engine's fixed measurement.

interface DefaultFontLoadFailure

DefaultFontsFragmentinterfaceSource ↗

What loadDefaultFonts resolves to — composes as a FontConfigurationFragment.

interface DefaultFontsFragment

DefaultFontSourceinterfaceSource ↗

A byte-backed source, structurally identical to the editor contract's FontSource.

interface DefaultFontSource

DefaultFontSubstitutioninterfaceSource ↗

One Word-name → substitute redirect, structurally identical to the editor contract's FontSourceSubstitution. from is the proprietary face a document asks for, to is the metric-compatible face this package actually ships.

interface DefaultFontSubstitution

FontAssetManifestEntryinterfaceSource ↗

One packaged font asset, as measured at packaging time.

byteLength and hash are baked here and CI-verified against the shipped files, so a fetched asset is content-checked without hashing at runtime.

interface FontAssetManifestEntry

LoadDefaultFontsOptionsinterfaceSource ↗

Options shared by [loadDefaultFonts](loadDefaultFonts), [installDefaultFontFaces](installDefaultFontFaces) and [defaultFonts](defaultFonts). Both fields are optional, so {} loads all five families over the global fetch.

interface LoadDefaultFontsOptions

WordDefaultFamilytypeSource ↗

The Word default families this package can stand in for.

type WordDefaultFamily = 'Calibri' | 'Cambria' | 'Times New Roman' | 'Arial' | 'Courier New';

ALL_WORD_DEFAULT_FAMILIESconstSource ↗

Every Word family this package substitutes for, and the default when [LoadDefaultFontsOptions.families](LoadDefaultFontsOptions.families) is omitted. Frozen — treat it as a constant rather than a mutable list to filter in place.

ALL_WORD_DEFAULT_FAMILIES: readonly WordDefaultFamily[]

FONT_ASSET_MANIFESTconstSource ↗

Every font asset this package ships, in generator order. Drives both loadDefaultFonts (which looks entries up by filename) and the packaging check that keeps the shipped bytes honest.

FONT_ASSET_MANIFEST: readonly FontAssetManifestEntry[]