@navaramap/font 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 MapLibre contributors
+
+This project is dual-licensed under either of
+
+- Apache License, Version 2.0 (see LICENSE-APACHE)
+- MIT license (see LICENSE-MIT)
+
+at your option.

package/README.md

@@ -0,0 +1,3 @@
+# @navaramap/font
+
+This is a font module for Navara for Web platform.

package/dist/index.d.ts

@@ -0,0 +1,556 @@
+import { ConcurrencyManager } from '@navaramap/worker';
+import { DataTexture } from 'three';
+
+/**
+ * Pixel range over which a quality's atlas distance field ramps from
+ * "outside" to "inside" (i.e. the value covered by `d - 0.5` in the shader).
+ * Converts an outline-thickness expressed in pixels into a delta on the
+ * sampled distance value.
+ *
+ * SDF: `SDF_RADIUS` (35) in `crates/navara_wasm_font_worker/src/atlas.rs`.
+ * MSDF: `MSDF_RANGE_PX` (8) in `crates/navara_wasm_font_worker/src/msdf.rs`.
+ */
+export declare const atlasRangePx: (highQuality: boolean) => number;
+
+declare type BatchPrepareTextResult = {
+    results: {
+        text: string;
+        shapeResult: ShapeTextResult | null;
+    }[];
+    /** Snapshot of the SDF atlas, if any glyphs were added during the batch. */
+    atlas: FontAtlasData | null;
+    /** Snapshot of the COLRv1 color atlas (RGBA), if any color glyphs were added during the batch. */
+    colorAtlas: FontAtlasData | null;
+    /** The atlas key used for this batch (family name or font URL). */
+    atlasKey: string;
+    /** True if any glyph was evicted during this batch. The reused rects mean
+     *  cached shape results for this atlas may be stale, so the FontManager bumps
+     *  the atlas generation to force a re-shape on next use. Optional only so
+     *  callers needn't construct it (the worker always sends it). */
+    evicted?: boolean;
+};
+
+/**
+ * Pixel size at which COLRv1 color glyphs are rasterized into the color atlas.
+ * Must match `COLOR_GLYPH_PX_SIZE` in `crates/navara_wasm_font_worker/src/color_raster.rs`.
+ */
+export declare const COLOR_GLYPH_PX_SIZE = 64;
+
+/** Create an RGBA color atlas DataTexture for COLRv1 glyphs.
+ *  Pixel data is unpremultiplied sRGB; three.js linearizes on sample. */
+export declare function createColorAtlasTexture(data: Uint8Array, width: number, height: number): DataTexture;
+
+/** Create an SDF/MSDF distance-field atlas DataTexture.
+ *
+ * `channels`: 1 → R8 SDF (sampled as `.r`); 4 → RGBA8 MTSDF (three MSDF
+ * channels + true SDF in alpha, sampled as `median(.rgb)`). RGB8 isn't
+ * supported because three.js dropped `RGBFormat` in r137. */
+export declare function createSdfAtlasTexture(data: Uint8Array, width: number, height: number, channels: number): DataTexture;
+
+/** Filters selecting which `@font-face` blocks of a stylesheet to include. */
+export declare type CssFontFaceFilter = {
+    /**
+     * Only include blocks whose `font-family` matches one of these names
+     * (quotes stripped, case-insensitive). Useful when a stylesheet declares
+     * several families and only some should become faces.
+     *
+     * When given as an array, it also sets face priority: faces are ordered by
+     * their family's position in the array (stable within a family). This
+     * matters for stylesheets like the Google Fonts CSS API that sort
+     * `@font-face` blocks alphabetically regardless of request order — face
+     * order decides which face wins for codepoints covered by several faces,
+     * and `faces[0]` is the fallback for uncovered codepoints.
+     */
+    fontFamily?: string | string[];
+    /** Only include blocks whose `font-weight` matches, e.g. `800` or `"100 900"`. */
+    fontWeight?: string | number;
+    /** Only include blocks whose `font-style` matches, e.g. `"normal"` or `"italic"`. */
+    fontStyle?: string;
+};
+
+export declare type FetchCssFontFamilyOptions = CssFontFaceFilter & {
+    /** Extra `fetch` options (e.g. credentials for a private font host). */
+    requestInit?: RequestInit;
+};
+
+/**
+ * Fetch one or more stylesheets and build a {@link FontFamily} from their
+ * `@font-face` rules — see {@link parseFontFamilyFromCss}. Only the CSS is
+ * downloaded here; font files stay lazily fetched per face as text needs
+ * them.
+ *
+ * Works directly with the Google Fonts CSS API, which declares one
+ * `@font-face` per script subset with `unicode-range` (CJK families are
+ * split into ~100 lazily-loaded slices):
+ *
+ * ```ts
+ * const family = await fetchFontFamilyFromCss(
+ *   "labels",
+ *   "https://fonts.googleapis.com/css2?family=Archivo:wght@800&family=Noto+Sans+JP:wght@800",
+ * );
+ * view.addFontFamily(family);
+ * ```
+ *
+ * When passing multiple URLs, face priority follows URL order, then block
+ * order within each stylesheet.
+ *
+ * @param family Family name to register the faces under.
+ * @param cssUrl Stylesheet URL(s) to fetch.
+ * @param options Optional block filters and fetch options.
+ */
+export declare function fetchFontFamilyFromCss(family: string, cssUrl: string | string[], options?: FetchCssFontFamilyOptions): Promise<FontFamily>;
+
+/** SDF/MSDF atlas texture data.
+ *
+ * `channels` selects the GPU texture format:
+ *  - 1 → R8 (single-channel SDF, sampled as `.r`).
+ *  - 4 → RGBA8. Either MTSDF (three MSDF channels + true SDF in alpha,
+ *    sampled as `median(.rgb)` in the fragment shader) or the COLRv1 color
+ *    atlas — distinguished by which atlas slot the data was placed in, not
+ *    by `channels`.
+ *
+ * 3-channel MSDF (RGB8) isn't used: three.js dropped `RGBFormat` in r137,
+ * and the worker emits MTSDF (4 channels) for the high-quality path.
+ */
+export declare type FontAtlasData = {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    channels: number;
+};
+
+declare type FontFace_2 = {
+    unicodeRanges: UnicodeRange[];
+    url: string;
+};
+export { FontFace_2 as FontFace }
+
+export declare type FontFamily = {
+    family: string;
+    faces: FontFace_2[];
+};
+
+/**
+ * Manages font loading, text shaping, and SDF atlas access.
+ *
+ * Delegates heavy computation (shaping, SDF rasterization, atlas packing)
+ * to a dedicated Web Worker via FontWorkerClient. GPU texture management
+ * (DataTexture creation/update) stays on the main thread.
+ */
+export declare class FontManager {
+    private _workerUrl;
+    private _client;
+    private _clientPromise;
+    private _concurrencyManager;
+    /** Worker cache budget, delivered when the (lazy) client is created. */
+    private _fontBudgetBytes;
+    /** Tracks in-flight fetch promises to avoid duplicate requests. */
+    private _pending;
+    /** Tracks fonts that have been successfully loaded. */
+    private _loaded;
+    /** Cache shaped text results to avoid redundant worker calls (LRU-evicted). */
+    private _shapeCache;
+    /** Cache atlas data per font to avoid redundant copies. */
+    private _atlasCache;
+    /** Cache color atlas data per font (COLRv1 RGBA). */
+    private _colorAtlasCache;
+    /** Tracks whether the atlas cache is stale (new glyphs may have been rasterized). */
+    private _atlasDirty;
+    /** Tracks whether the color atlas cache is stale. */
+    private _colorAtlasDirty;
+    /** Shared GPU texture per font — all meshes using the same font share one DataTexture. */
+    private _textureCache;
+    /** Shared color atlas texture per atlas key (RGBA). */
+    private _colorTextureCache;
+    /** Tracks in-flight prepareText promises to deduplicate. */
+    private _preparePending;
+    /** Microtask batch queue: per-font list of texts awaiting worker dispatch. */
+    private _batchQueue;
+    /** Whether a microtask flush is already scheduled. */
+    private _batchScheduled;
+    private _refCount;
+    /** Registered font families, keyed by family name. */
+    private _families;
+    /** Real cmap coverage per font file URL, reported by the worker when the
+     *  file is first loaded. Declared face ranges can differ from what the
+     *  file contains (e.g. shared per-subset boilerplate in Google Fonts CSS
+     *  claims codepoints the file lacks, which would shape as tofu), so
+     *  registered faces pointing at the URL get their `unicodeRanges` replaced
+     *  with these — once per file, never per shaped text. */
+    private _cmapRanges;
+    /** Maps font URL → atlas key (family name or URL for standalone fonts). */
+    private _atlasKeys;
+    /** Per-atlas generation counter. Bumped when the worker reports it evicted
+     *  glyphs from an atlas; cached shape results carry the generation they were
+     *  built under, so any from before the eviction are re-shaped on next use.
+     *  Visible labels are *normally* unaffected — their glyphs are pinned and not
+     *  evicted — but a large burst can evict a still-in-flight glyph before its
+     *  retain lands; `onAtlasEvicted` lets consumers rebuild such stale meshes. */
+    private _atlasGeneration;
+    /** Eviction listeners keyed by resolved atlas key. Notified (coalesced on a
+     *  microtask) after an eviction bumps an atlas's generation, so visible
+     *  consumers can rebuild meshes whose baked metrics may now be stale. */
+    private _evictListeners;
+    /** Atlas keys with an eviction awaiting notification, plus its schedule flag. */
+    private _pendingEvictNotify;
+    private _evictNotifyScheduled;
+    /** Pending visible-label refcount increments per atlas key (one entry per
+     *  occurrence), flushed to the worker on a microtask. */
+    private _retainQueue;
+    /** Pending visible-label refcount decrements per atlas key. */
+    private _releaseQueue;
+    /** Whether a retain/release flush is already scheduled. */
+    private _refFlushScheduled;
+    constructor(workerUrl: string | URL);
+    setConcurrencyManager(concurrencyManager: ConcurrencyManager): void;
+    /**
+     * Register a font family with multiple faces.
+     * No font files are loaded until text is prepared.
+     */
+    registerFontFamily(family: FontFamily): void;
+    /**
+     * Remove a registered font family. No font resources are unloaded here —
+     * each mesh that used this family tracks its loaded face URLs and unloads
+     * them individually on dispose.
+     */
+    unregisterFontFamily(familyName: string): void;
+    /** Check whether a font identifier is a registered family name. */
+    isFamily(fontIdentifier: string): boolean;
+    /**
+     * Split `text` into runs of consecutive characters that map to the same face.
+     * Each character picks the first face whose unicode ranges contain it,
+     * falling back to face 0. Spaces stick to the current run to avoid breaking
+     * up whitespace.
+     */
+    private _segmentTextByFace;
+    /** First face whose unicode ranges contain `codepoint`, or face 0. */
+    private _findFaceForCodepoint;
+    /** Replace the unicode ranges of every registered face pointing at
+     *  `rawUrl` with the font file's real cmap coverage (see `_cmapRanges`). */
+    private _applyCmapRanges;
+    private _ensureClient;
+    /**
+     * Sets the worker-side cache budget (font data + atlas pixels). Must be
+     * called before the first font loads — the worker is created lazily and
+     * the budget is delivered with its init message.
+     */
+    setMemoryBudget(bytes: number | undefined): void;
+    /**
+     * Snapshot of the font worker's memory usage, or `undefined` while no
+     * worker has been spawned (no fonts in use = zero cost).
+     */
+    memoryStats(): Promise<FontWorkerMemoryStats | undefined>;
+    /**
+     * Load a font from a URL. Fetches the font file and sends it to the worker.
+     * Returns immediately if the font is already loaded. Deduplicates concurrent requests.
+     *
+     * `atlasKey`: optional shared atlas identifier (e.g. font family name).
+     * `highQuality`: which atlas raster path to use. Two materials referencing the
+     * same `url` but different `highQuality` values produce two independent
+     * (font, atlas) entries — both live side-by-side. The browser HTTP cache
+     * makes the second fetch effectively free.
+     */
+    loadFont(url: string, highQuality: boolean, atlasKey?: string): Promise<void>;
+    unloadFont(url: string, highQuality: boolean): Promise<void>;
+    /**
+     * Prepare text for rendering: shapes text and updates atlas in the worker.
+     * Must be called (and awaited) before shapeText() will return data for this text.
+     * Accepts either a font URL or a registered font family name.
+     *
+     * For font families, face URLs are loaded lazily — only the faces whose
+     * unicode ranges cover `text` are fetched. Pass a caller-owned `loadedFaces`
+     * Set to track which URLs were loaded; the caller must call unloadFont() for
+     * each URL in the set on dispose. Passing the same set across multiple calls
+     * ensures each face URL is loaded exactly once per caller.
+     *
+     * For standalone font URLs the font must already be loaded via loadFont().
+     */
+    prepareText(fontIdentifier: string, text: string, highQuality: boolean, loadedFaces?: Set<string>): Promise<void>;
+    /**
+     * Check if text has been prepared (sync).
+     * Accepts either a font URL or a registered font family name.
+     */
+    isTextPrepared(fontIdentifier: string, text: string, highQuality: boolean): boolean;
+    /**
+     * Get shaped text from cache. Returns undefined if not yet prepared.
+     * Call prepareText() first.
+     * Accepts either a font URL or a registered font family name.
+     */
+    shapeText(fontIdentifier: string, text: string, highQuality: boolean): ShapeTextResult | undefined;
+    /** Prepare text for a single standalone font (non-family path). */
+    private _prepareSingleFontText;
+    /** Prepare text for a font family: segment, shape per-face, stitch. */
+    private _prepareFamilyText;
+    /** Combine shaped results from multiple face segments into one result.
+     *
+     * All glyph advances/offsets and bearing values are normalized to the first
+     * segment's unitsPerEm so the consumer can apply a single scale factor.
+     */
+    private _stitchSegments;
+    /**
+     * Get the SDF atlas data for a loaded font from cache.
+     * Accepts either a font URL or a registered font family name.
+     * For families, the atlas is shared across all faces.
+     */
+    getAtlas(fontIdentifier: string, highQuality: boolean): FontAtlasData | undefined;
+    /**
+     * Shared GPU DataTexture for a font's atlas. Returns the same instance
+     * across callers and updates it in-place when the atlas grows. Accepts a
+     * font URL or a family name.
+     */
+    getAtlasTexture(fontIdentifier: string, highQuality: boolean): DataTexture | null;
+    /** Color atlas data for a loaded COLRv1 font. `undefined` for monochrome. */
+    getColorAtlas(fontIdentifier: string, highQuality: boolean): FontAtlasData | undefined;
+    /**
+     * Shared GPU DataTexture for a font's COLRv1 color atlas. `null` when no
+     * color glyphs have been rasterized under this key.
+     */
+    getColorAtlasTexture(fontIdentifier: string, highQuality: boolean): DataTexture | null;
+    /** Shared "get cached texture, create or refresh from atlas data" path.
+     *  When the atlas grew, dispose() releases the GL handle so three.js
+     *  reallocates at the new size on the next render instead of overflowing
+     *  texSubImage2D. The DataTexture instance is preserved so existing meshes
+     *  keep their refs. */
+    private _getOrUpdateTexture;
+    dispose(): void;
+    private _cacheKey;
+    /** Current generation of an atlas. Bumped whenever the atlas evicts glyphs;
+     *  cached shape results stamped with an older generation are treated as
+     *  stale (their metrics may point at reused rects) and re-shaped on next use. */
+    private _currentGen;
+    /** Whether `text` has a cached shape result that is still current for its
+     *  atlas. A result from before the atlas last evicted is treated as not
+     *  prepared, forcing a re-shape that re-rasterizes any evicted glyphs. */
+    private _isPreparedFresh;
+    /**
+     * Subscribe to evictions on the atlas backing `(fontIdentifier, highQuality)`.
+     * The listener fires (coalesced on a microtask) after the worker reports that
+     * atlas evicted glyphs — the cue for a visible consumer to rebuild any mesh
+     * whose baked atlas rects may now be stale. Returns an unsubscribe function.
+     */
+    onAtlasEvicted(fontIdentifier: string, highQuality: boolean, listener: () => void): () => void;
+    /** Queue an eviction notification for `atlasKey`, coalescing a burst of
+     *  per-batch evictions into a single microtask-deferred fan-out. */
+    private _scheduleEvictNotify;
+    private _flushEvictNotify;
+    /**
+     * Add one visible-label reference to each glyph (composite keys) so the
+     * worker keeps them in the atlas while on screen. Call when a label using
+     * these glyphs becomes visible; balance with {@link releaseGlyphs}.
+     */
+    retainGlyphs(fontIdentifier: string, highQuality: boolean, keys: bigint[]): void;
+    /** Drop one visible-label reference from each glyph. Call when a label hides
+     *  or is disposed. */
+    releaseGlyphs(fontIdentifier: string, highQuality: boolean, keys: bigint[]): void;
+    private _enqueueRef;
+    /** Send queued refcount changes to the worker. Retains are sent before
+     *  releases so a glyph hidden and re-shown in the same tick never momentarily
+     *  drops to zero. */
+    private _flushRefs;
+    /** Resolve a (font identifier, quality) pair to its qualified atlas key.
+     *  Family names get a quality suffix and become their own atlas key; font
+     *  URLs are looked up via `_atlasKeys` (already-qualified keys). */
+    private _resolveAtlasKey;
+    /** Fetch + worker-load a font for a single (url, quality) combination.
+     *
+     *  `rawUrl` is the network URL (no `#q=...` fragment). `qUrl` and
+     *  `qAtlasKey` are the qualified identifiers the worker will use as
+     *  FontEntry / atlas keys. The worker side treats `qUrl` as opaque, so the
+     *  same `rawUrl` can be loaded twice (once per quality) without collision.
+     */
+    private _fetchAndLoad;
+    private _flushBatch;
+}
+
+/**
+ * Main-thread client that communicates with the dedicated font Web Worker.
+ * Uses a request/response protocol with incrementing message IDs.
+ */
+export declare class FontWorkerClient {
+    private _worker;
+    private _concurrencyManager;
+    private _nextId;
+    private _pending;
+    private _ready;
+    constructor(workerUrl: string | URL, concurrencyManager: ConcurrencyManager, options?: FontWorkerClientOptions);
+    /** Wait for the WASM module to be initialized in the worker. */
+    ready(): Promise<void>;
+    /** Load a font file into the worker's FontCache. Transfers the ArrayBuffer.
+     *  `atlasKey`: optional shared atlas identifier (e.g. font family name).
+     *  When provided, all fonts loaded with the same key share a single atlas.
+     *  `highQuality`: whether to use the high-quality atlas raster path. The Rust side creates the
+     *  atlas with this mode on the first load; subsequent loads under the same
+     *  `atlasKey` are expected to reuse the same quality (the TS layer
+     *  guarantees this by including the highQuality flag in both `url` and `atlasKey`).
+     *
+     *  On success, `cmapRanges` holds the font's real cmap coverage as
+     *  flattened `[from, to, ...]` inclusive codepoint ranges (empty when the
+     *  face has no parsable unicode cmap — treat as unknown). */
+    loadFont(url: string, data: ArrayBuffer, atlasKey: string | undefined, highQuality: boolean): Promise<{
+        ok: boolean;
+        cmapRanges: Uint32Array | null;
+    }>;
+    unloadFont(url: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Add one visible-label reference to each glyph (composite keys) under
+     *  `atlasKey`. Fire-and-forget; the worker replies so `_pending` is cleared.
+     *  Transfers the key buffer — the caller discards it after this call. */
+    retainGlyphs(atlasKey: string, keys: BigUint64Array): void;
+    /** Drop one visible-label reference from each glyph under `atlasKey`. */
+    releaseGlyphs(atlasKey: string, keys: BigUint64Array): void;
+    /** Shape multiple texts in one worker round-trip. */
+    prepareTextBatch(fontUrl: string, texts: string[]): Promise<BatchPrepareTextResult>;
+    /** Snapshot of the worker's WASM heap and font-cache memory usage. */
+    getMemoryStats(): Promise<FontWorkerMemoryStats>;
+    dispose(): void;
+    private _send;
+}
+
+declare type FontWorkerClientOptions = {
+    /** Memory budget for the worker's font caches (font data + atlas pixels).
+     * Caps further atlas growth; the WASM heap itself never shrinks. */
+    fontBudgetBytes?: number;
+};
+
+/** Snapshot of the font worker's WASM heap and font-cache memory usage. */
+export declare type FontWorkerMemoryStats = {
+    /** Total WASM linear memory of the font worker (never shrinks). */
+    heapBytes: number;
+    fontCount: number;
+    atlasCount: number;
+    glyphCount: number;
+    /** Raw font file bytes held by the cache. */
+    fontBytes: number;
+    /** Monochrome (SDF/MSDF) atlas pixel bytes. */
+    atlasBytes: number;
+    /** COLRv1 color atlas pixel bytes. */
+    colorAtlasBytes: number;
+    /** Configured cache budget; undefined when unlimited. */
+    budgetBytes?: number;
+};
+
+/**
+ * Per-glyph character class used for line breaking during layout.
+ * Must match the `CHAR_CLASS_*` constants in
+ * `crates/navara_wasm_font_worker/src/shaping.rs`.
+ */
+export declare const GlyphCharClass: {
+    readonly Normal: 0;
+    /** Breakable whitespace: a line may wrap here, dropping the glyph. */
+    readonly Whitespace: 1;
+    /** Synthetic hard-break marker (zero advance, no atlas entry). */
+    readonly Newline: 2;
+    /** CJK-style character: a line may break after this glyph. */
+    readonly Ideographic: 3;
+};
+
+/** Glyph metrics from either the SDF or the color atlas. */
+export declare type GlyphMetrics = {
+    glyphId: number;
+    /** Unique font index within the atlas (distinguishes glyphs from different fonts). */
+    fontIndex: number;
+    /** Pre-computed composite key (font_index, glyph_id) from WASM. */
+    compositeKey: bigint;
+    atlasX: number;
+    atlasY: number;
+    atlasW: number;
+    atlasH: number;
+    bearingX: number;
+    bearingY: number;
+    /** True when this glyph lives in the COLRv1 color atlas (RGBA) rather than the SDF atlas (R8). */
+    isColor: boolean;
+};
+
+/**
+ * A Map with a maximum capacity that evicts the least-recently used entries.
+ *
+ * Both `get` and `set` refresh the entry's position, making it the most recent.
+ * When the map exceeds `maxSize`, the least-recently used entries are evicted.
+ */
+export declare class LRUMap<K, V> {
+    private _map;
+    private _maxSize;
+    constructor(maxSize: number);
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+}
+
+export declare type ParseCssFontFamilyOptions = CssFontFaceFilter & {
+    /** Base URL used to resolve relative `src: url(...)` references. */
+    baseUrl?: string;
+};
+
+/**
+ * Parse a CSS `unicode-range` descriptor value (e.g. `"U+0-7F, U+131, U+4??"`)
+ * into inclusive codepoint ranges. Supports single codepoints (`U+26`),
+ * intervals (`U+0102-0103`) and wildcards (`U+4??`).
+ */
+export declare function parseCssUnicodeRange(value: string): UnicodeRange[];
+
+/**
+ * Build a {@link FontFamily} from CSS `@font-face` rules, so faces and their
+ * unicode ranges don't have to be written by hand. Each `@font-face` block
+ * becomes one face: its `src` URL and its `unicode-range` (faces stay
+ * lazily downloaded — a face is only fetched once text actually needs a
+ * codepoint in its ranges). Blocks without a `unicode-range` cover all
+ * codepoints.
+ *
+ * Face priority follows CSS semantics: later `@font-face` rules take
+ * precedence when their unicode-ranges overlap, so faces come out in
+ * reverse stylesheet order (use the `fontFamily` array to order families
+ * explicitly). The resulting first face doubles as the fallback for
+ * codepoints no face covers — same semantics as a hand-written
+ * {@link FontFamily}.
+ *
+ * @param family Family name to register the faces under.
+ * @param cssText Stylesheet text containing `@font-face` rules.
+ * @param options Optional block filters and a `baseUrl` for relative URLs.
+ */
+export declare function parseFontFamilyFromCss(family: string, cssText: string, options?: ParseCssFontFamilyOptions): FontFamily;
+
+/** A single shaped glyph with positioning info. */
+export declare type ShapedGlyph = {
+    glyphId: number;
+    /** Unique font index within the atlas (distinguishes glyphs from different fonts). */
+    fontIndex: number;
+    /** Pre-computed composite key (font_index, glyph_id) from WASM. */
+    compositeKey: bigint;
+    xAdvance: number;
+    yAdvance: number;
+    xOffset: number;
+    yOffset: number;
+    /** One of `GlyphCharClass` (line-break info). */
+    charClass: number;
+};
+
+/** Result from shaping text: glyph positions + atlas metrics. */
+export declare type ShapeTextResult = {
+    glyphs: ShapedGlyph[];
+    metrics: GlyphMetrics[];
+    /** Font units per em (needed for converting font-unit to pixel space) */
+    unitsPerEm: number;
+    /** Ascender in font units (hhea), for multi-line layout. */
+    ascender: number;
+    /** Descender in font units (hhea, negative below baseline). */
+    descender: number;
+    /** Extra line gap in font units (hhea). */
+    lineGap: number;
+    /** FontManager-internal: the atlas generation these metrics were built
+     *  under. When the atlas evicts glyphs its generation bumps, marking older
+     *  cached results stale so they are re-shaped on next use. Unset on results
+     *  fresh from the worker; the FontManager stamps it when caching. */
+    _generation?: number;
+};
+
+/** Inclusive codepoint range covered by a font face. */
+export declare type UnicodeRange = {
+    from: number;
+    to: number;
+};
+
+export { }