ump-plugin-font

UMP Font Plugin — register custom fonts via the web-shaped FontFace API and make fontFamily actually select a typeface at render time.

Install

npm install ump-plugin-font --save

Usage

import { FontFace, fontPlugin } from 'ump-plugin-font'; import { AppRegistry } from 'ump-native';

AppRegistry.use(fontPlugin());

// From an ArrayBuffer (e.g. a bundled asset you already loaded): const face = new FontFace('Inter', buffer, { weight: 'bold', style: 'italic' }); await face.load();

// Or via document.fonts.add() — fires the load asynchronously: const f = new FontFace('Inter', 'url(https://example.com/Inter.ttf)'); document.fonts.add(f);

Once a face is loaded, any <Text style={{ fontFamily: 'Inter' }}> resolves to the registered typeface. Weight and italic descriptors are matched nearest-first: an exact {family, weight, italic} wins, otherwise the closest weight in the same italic class, otherwise the closest weight ignoring italic.

Source forms

FontFace's second argument is the font source:

• ArrayBuffer — raw font bytes. Registered immediately on load().
• 'url(localPath)' or 'url(https://...)' — fetched via the global fetch, then registered. Quotes inside url(...) are optional.

Descriptors

new FontFace(family, source, { weight, style })

• weight: 'normal' (→ 400), 'bold' (→ 700), a numeric string '500', or a number 500. Defaults to 400.
• style: 'normal' or 'italic'. Defaults to 'normal'.

How it works

load() decodes the source to base64 and calls the __ump_font_register host function registered by the runtime (see runtime/reconciler/js_bridge.cpp). The C++ side decodes the bytes into an SkTypeface and stores it in the process-wide FontRegistry (runtime/render/font_registry.cpp), which both text and canvas rendering consult before falling back to a named system family and finally the system default.

When the native bridge is missing — e.g. a harness that loads the JS plugin without the runtime — load() emits a one-shot console.warn and resolves without registering, so app boot is never blocked; fontFamily then falls back to the system default.

H5

On the web the browser already implements FontFace / document.fonts natively and the H5 DOM renderer honors fontFamily directly, so the .h5.ts companion is a thin passthrough that re-exports the platform FontFace. No native bridge is involved.

Plugin authoring

This is a UMP plugin. See docs/superpowers/specs/plugin-authoring-guide.md for the plugin model.