@navaramap/font 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,14 @@
-import { ConcurrencyManager } from '@navaramap/worker';
 import { DataTexture } from 'three';
 
+/**
+ * Pixels of distance field a quality's glyph rect keeps around the outline.
+ * The text shader grows a glyph's quad past it for wider outlines.
+ *
+ * SDF: `SDF_BUFFER` (12) in `crates/navara_wasm_font_worker/src/atlas.rs`.
+ * MSDF: `MSDF_PADDING_PX` (8) in `crates/navara_wasm_font_worker/src/msdf.rs`.
+ */
+export declare const atlasPaddingPx: (highQuality: boolean) => number;
+
 /**
  * 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).
@@ -141,9 +149,10 @@ export declare class FontManager {
     private _workerUrl;
     private _client;
     private _clientPromise;
-    private _concurrencyManager;
     /** Worker cache budget, delivered when the (lazy) client is created. */
     private _fontBudgetBytes;
+    /** Delivered when the (lazy) client is created; see `setWorkerCoreReservation`. */
+    private _reserveWorkerCore;
     /** Tracks in-flight fetch promises to avoid duplicate requests. */
     private _pending;
     /** Tracks fonts that have been successfully loaded. */
@@ -202,7 +211,6 @@ export declare class FontManager {
     /** 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.
@@ -236,6 +244,13 @@ export declare class FontManager {
      * the budget is delivered with its init message.
      */
     setMemoryBudget(bytes: number | undefined): void;
+    /**
+     * Lets the font worker hold a core of the view's worker pool while it
+     * loads fonts or shapes text (see `reserveWorkerCore` in
+     * `@navaramap/worker`). Must be called before the first font loads, like
+     * {@link setMemoryBudget}.
+     */
+    setWorkerCoreReservation(reserve: () => () => void): void;
     /**
      * Snapshot of the font worker's memory usage, or `undefined` while no
      * worker has been spawned (no fonts in use = zero cost).
@@ -369,11 +384,15 @@ export declare class FontManager {
  */
 export declare class FontWorkerClient {
     private _worker;
-    private _concurrencyManager;
     private _nextId;
     private _pending;
     private _ready;
-    constructor(workerUrl: string | URL, concurrencyManager: ConcurrencyManager, options?: FontWorkerClientOptions);
+    /** Heavy requests (init, font loads, text shaping) still in flight. */
+    private _heavyRequests;
+    private _releaseCore;
+    private _releaseCoreTimer;
+    private _reserveWorkerCore;
+    constructor(workerUrl: string | URL, 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.
@@ -405,6 +424,11 @@ export declare class FontWorkerClient {
     /** Snapshot of the worker's WASM heap and font-cache memory usage. */
     getMemoryStats(): Promise<FontWorkerMemoryStats>;
     dispose(): void;
+    /**
+     * Hold a worker-pool core while `request` keeps the font worker busy, so
+     * the pool leaves the worker a core of its own (see `reserveWorkerCore`).
+     */
+    private _holdCore;
     private _send;
 }
 
@@ -412,6 +436,12 @@ 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;
+    /** Holds a worker-pool core while the font worker is busy and returns
+     * its release (`reserveWorkerCore` of the view's worker pool). Passed in
+     * rather than imported: this package bundles its own copy of
+     * `@navaramap/worker`, which would hold a core on a pool that does not
+     * exist. */
+    reserveWorkerCore?: () => () => void;
 };
 
 /** Snapshot of the font worker's WASM heap and font-cache memory usage. */
@@ -446,6 +476,21 @@ export declare const GlyphCharClass: {
     readonly Ideographic: 3;
 };
 
+/**
+ * Direction of the `\n`-separated segment a glyph was shaped in. Must match
+ * the `DIRECTION_*` constants in
+ * `crates/navara_wasm_font_worker/src/shaping.rs`.
+ */
+export declare const GlyphDirection: {
+    /** No character with a script of its own (digits, punctuation, spaces).
+     *  Font-family fallback shapes such runs apart from the letters around
+     *  them, so a line's direction is its first non-neutral glyph's. */
+    readonly Neutral: 0;
+    readonly Ltr: 1;
+    /** The segment's glyphs arrive in visual order (reversed logical order). */
+    readonly Rtl: 2;
+};
+
 /** Glyph metrics from either the SDF or the color atlas. */
 export declare type GlyphMetrics = {
     glyphId: number;
@@ -539,6 +584,11 @@ export declare type ShapedGlyph = {
     yOffset: number;
     /** One of `GlyphCharClass` (line-break info). */
     charClass: number;
+    /** Same shaping cluster as the previous glyph (combining marks, pre-base
+     *  vowels). Letter spacing is inserted only before cluster starts. */
+    continuesCluster?: boolean;
+    /** One of `GlyphDirection`; absent means neutral. */
+    direction?: number;
 };
 
 /** Result from shaping text: glyph positions + atlas metrics. */
@@ -553,6 +603,10 @@ export declare type ShapeTextResult = {
     descender: number;
     /** Extra line gap in font units (hhea). */
     lineGap: number;
+    /** False when letter spacing must not be applied: tracking pulls apart the
+     *  joined letterforms of cursive Arabic, so (like MapLibre) any Arabic
+     *  character disables it for the whole label. */
+    allowsLetterSpacing: boolean;
     /** 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