@navaramap/font 0.2.0 → 0.3.0

package/src/FontManager.ts

@@ -1,4 +1,3 @@
-import type { ConcurrencyManager } from "@navaramap/worker";
 import {
   DataTexture,
   LinearFilter,
@@ -92,9 +91,10 @@ export class FontManager {
   private _workerUrl: string | URL;
   private _client: FontWorkerClient | undefined;
   private _clientPromise: Promise<FontWorkerClient> | undefined;
-  private _concurrencyManager: ConcurrencyManager | undefined;
   /** Worker cache budget, delivered when the (lazy) client is created. */
   private _fontBudgetBytes: number | undefined;
+  /** Delivered when the (lazy) client is created; see `setWorkerCoreReservation`. */
+  private _reserveWorkerCore: (() => () => void) | undefined;
   /** Tracks in-flight fetch promises to avoid duplicate requests. */
   private _pending = new Map<string, Promise<void>>();
   /** Tracks fonts that have been successfully loaded. */
@@ -167,10 +167,6 @@ export class FontManager {
     this._workerUrl = workerUrl;
   }
 
-  setConcurrencyManager(concurrencyManager: ConcurrencyManager) {
-    this._concurrencyManager = concurrencyManager;
-  }
-
   /**
    * Register a font family with multiple faces.
    * No font files are loaded until text is prepared.
@@ -282,15 +278,10 @@ export class FontManager {
   private _ensureClient(): Promise<FontWorkerClient> {
     if (this._client) return Promise.resolve(this._client);
     if (this._clientPromise) return this._clientPromise;
-    if (!this._concurrencyManager) {
-      return Promise.reject(
-        new Error("FontManager: concurrencyManager not set"),
-      );
-    }
-    const cm = this._concurrencyManager;
     this._clientPromise = (async () => {
-      const client = new FontWorkerClient(this._workerUrl, cm, {
+      const client = new FontWorkerClient(this._workerUrl, {
         fontBudgetBytes: this._fontBudgetBytes,
+        reserveWorkerCore: this._reserveWorkerCore,
       });
       await client.ready();
       this._client = client;
@@ -311,6 +302,16 @@ export class FontManager {
     this._fontBudgetBytes = bytes;
   }
 
+  /**
+   * 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 {
+    this._reserveWorkerCore = reserve;
+  }
+
   /**
    * Snapshot of the font worker's memory usage, or `undefined` while no
    * worker has been spawned (no fonts in use = zero cost).
@@ -604,6 +605,9 @@ export class FontManager {
     let ascender = 0;
     let descender = 0;
     let lineGap = 0;
+    // Each face run reports on its own substring, so the label allows spacing
+    // only when every run does.
+    let allowsLetterSpacing = true;
 
     for (const seg of segments) {
       const result = this._shapeCache
@@ -624,6 +628,7 @@ export class FontManager {
         lineGap = result.lineGap;
       }
       const scale = targetUnitsPerEm / result.unitsPerEm;
+      allowsLetterSpacing &&= result.allowsLetterSpacing;
 
       for (const g of result.glyphs) {
         allGlyphs.push(
@@ -659,6 +664,7 @@ export class FontManager {
         ascender: 800,
         descender: -200,
         lineGap: 0,
+        allowsLetterSpacing,
       };
     }
 
@@ -669,6 +675,7 @@ export class FontManager {
       ascender,
       descender,
       lineGap,
+      allowsLetterSpacing,
     };
   }
 

package/src/FontWorkerClient.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+import { FontWorkerClient } from "./FontWorkerClient";
+
+const mocks = vi.hoisted(() => ({
+  reserveWorkerCore: vi.fn(),
+  release: vi.fn(),
+}));
+
+type Message = { id: number; type: string };
+
+/** A worker that answers only when a test tells it to. */
+class MockWorker {
+  static last: MockWorker;
+  onmessage: ((e: MessageEvent) => void) | null = null;
+  onerror: ((e: unknown) => void) | null = null;
+  received: Message[] = [];
+  constructor() {
+    MockWorker.last = this;
+  }
+  postMessage(message: Message) {
+    this.received.push(message);
+  }
+  terminate() {}
+  /** Answer the oldest unanswered request of `type`. */
+  reply(type: string) {
+    const index = this.received.findIndex((m) => m.type === type);
+    const [message] = this.received.splice(index, 1);
+    this.onmessage?.({
+      data: { id: message.id, type: "ok", payload: { ok: true, results: [] } },
+    } as MessageEvent);
+  }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("Worker", MockWorker);
+  mocks.reserveWorkerCore.mockReset().mockReturnValue(mocks.release);
+  mocks.release.mockReset();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+it("holds one pool core while heavy requests run and releases it after a short idle", async () => {
+  const client = new FontWorkerClient("font-worker.js", {
+    reserveWorkerCore: mocks.reserveWorkerCore,
+  });
+  const worker = MockWorker.last;
+  expect(mocks.reserveWorkerCore).toHaveBeenCalledOnce();
+
+  const shaping = client.prepareTextBatch("font.ttf", ["a"]);
+  worker.reply("init");
+  await vi.advanceTimersByTimeAsync(200);
+  // Shaping is still in flight.
+  expect(mocks.release).not.toHaveBeenCalled();
+
+  worker.reply("prepareTextBatch");
+  await shaping;
+  await vi.advanceTimersByTimeAsync(50);
+  // A request within the delay keeps the same reservation.
+  const loading = client.loadFont(
+    "b.ttf",
+    new ArrayBuffer(1),
+    undefined,
+    false,
+  );
+  worker.reply("loadFont");
+  await loading;
+  await vi.advanceTimersByTimeAsync(99);
+  expect(mocks.release).not.toHaveBeenCalled();
+  expect(mocks.reserveWorkerCore).toHaveBeenCalledOnce();
+
+  await vi.advanceTimersByTimeAsync(1);
+  expect(mocks.release).toHaveBeenCalledOnce();
+
+  client.dispose();
+  expect(mocks.release).toHaveBeenCalledOnce();
+});
+
+it("does not hold a core for glyph reference updates", async () => {
+  const client = new FontWorkerClient("font-worker.js", {
+    reserveWorkerCore: mocks.reserveWorkerCore,
+  });
+  const worker = MockWorker.last;
+  worker.reply("init");
+  await vi.advanceTimersByTimeAsync(100);
+  expect(mocks.release).toHaveBeenCalledOnce();
+
+  client.retainGlyphs("atlas", new BigUint64Array([1n]));
+  expect(mocks.reserveWorkerCore).toHaveBeenCalledOnce();
+  worker.reply("retainGlyphs");
+  client.dispose();
+});
+
+it("holds no core without a reservation function", () => {
+  const client = new FontWorkerClient("font-worker.js");
+  MockWorker.last.reply("init");
+  client.dispose();
+  expect(mocks.reserveWorkerCore).not.toHaveBeenCalled();
+});
+
+it("releases the core at once when disposed", async () => {
+  const client = new FontWorkerClient("font-worker.js", {
+    reserveWorkerCore: mocks.reserveWorkerCore,
+  });
+  // The unanswered init is rejected by the dispose.
+  const ready = client.ready().catch(() => undefined);
+  client.dispose();
+  expect(mocks.release).toHaveBeenCalledOnce();
+  await ready;
+});

package/src/FontWorkerClient.ts

@@ -1,5 +1,3 @@
-import type { ConcurrencyManager } from "@navaramap/worker";
-
 import type {
   ShapeTextResult,
   FontAtlasData,
@@ -11,29 +9,38 @@ export 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;
 };
 
+/** How long the worker's core stays held after its last heavy request, so a
+ * burst of requests does not flip the reservation per request. */
+const CORE_RELEASE_DELAY_MS = 100;
+
 /**
  * Main-thread client that communicates with the dedicated font Web Worker.
  * Uses a request/response protocol with incrementing message IDs.
  */
 export class FontWorkerClient {
   private _worker: Worker;
-  private _concurrencyManager: ConcurrencyManager;
   private _nextId = 0;
   private _pending = new Map<
     number,
     { resolve: (value: unknown) => void; reject: (reason: unknown) => void }
   >();
   private _ready: Promise<void>;
-
-  constructor(
-    workerUrl: string | URL,
-    concurrencyManager: ConcurrencyManager,
-    options?: FontWorkerClientOptions,
-  ) {
-    this._concurrencyManager = concurrencyManager;
-
+  /** Heavy requests (init, font loads, text shaping) still in flight. */
+  private _heavyRequests = 0;
+  private _releaseCore: (() => void) | undefined;
+  private _releaseCoreTimer: ReturnType<typeof setTimeout> | undefined;
+  private _reserveWorkerCore: (() => () => void) | undefined;
+
+  constructor(workerUrl: string | URL, options?: FontWorkerClientOptions) {
+    this._reserveWorkerCore = options?.reserveWorkerCore;
     this._worker = new Worker(workerUrl, {
       type: import.meta.env.PROD ? undefined : "module",
     });
@@ -59,10 +66,11 @@ export class FontWorkerClient {
 
     // Trigger WASM init and resolve once the worker is ready; the init
     // payload also delivers the memory budget.
-    this._ready = this._send("init", {
-      fontBudgetBytes: options?.fontBudgetBytes,
-    }).then(() => undefined);
-    this._concurrencyManager.increment();
+    this._ready = this._holdCore(
+      this._send("init", {
+        fontBudgetBytes: options?.fontBudgetBytes,
+      }),
+    ).then(() => undefined);
   }
 
   /** Wait for the WASM module to be initialized in the worker. */
@@ -87,9 +95,9 @@ export class FontWorkerClient {
     atlasKey: string | undefined,
     highQuality: boolean,
   ): Promise<{ ok: boolean; cmapRanges: Uint32Array | null }> {
-    return this._send("loadFont", { url, data, atlasKey, highQuality }, [
-      data,
-    ]) as Promise<{
+    return this._holdCore(
+      this._send("loadFont", { url, data, atlasKey, highQuality }, [data]),
+    ) as Promise<{
       ok: boolean;
       cmapRanges: Uint32Array | null;
     }>;
@@ -122,10 +130,12 @@ export class FontWorkerClient {
       height: number;
       channels: number;
     };
-    const raw = (await this._send("prepareTextBatch", {
-      fontUrl,
-      texts,
-    })) as {
+    const raw = (await this._holdCore(
+      this._send("prepareTextBatch", {
+        fontUrl,
+        texts,
+      }),
+    )) as {
       results: { text: string; shapeResult: ShapeTextResult | null }[];
       atlas: RawAtlas | null;
       colorAtlas: RawAtlas | null;
@@ -161,12 +171,41 @@ export class FontWorkerClient {
   }
 
   dispose(): void {
+    if (this._releaseCoreTimer !== undefined) {
+      clearTimeout(this._releaseCoreTimer);
+      this._releaseCoreTimer = undefined;
+    }
+    this._releaseCore?.();
+    this._releaseCore = undefined;
     this._worker.terminate();
     for (const pending of this._pending.values()) {
       pending.reject(new Error("FontWorkerClient disposed"));
     }
     this._pending.clear();
-    this._concurrencyManager.decrement();
+  }
+
+  /**
+   * 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(request: Promise<unknown>): Promise<unknown> {
+    if (this._releaseCoreTimer !== undefined) {
+      clearTimeout(this._releaseCoreTimer);
+      this._releaseCoreTimer = undefined;
+    }
+    this._releaseCore ??= this._reserveWorkerCore?.();
+    this._heavyRequests++;
+    const settle = () => {
+      this._heavyRequests--;
+      if (this._heavyRequests > 0 || !this._releaseCore) return;
+      this._releaseCoreTimer = setTimeout(() => {
+        this._releaseCoreTimer = undefined;
+        this._releaseCore?.();
+        this._releaseCore = undefined;
+      }, CORE_RELEASE_DELAY_MS);
+    };
+    request.then(settle, settle);
+    return request;
   }
 
   private _send(

package/src/cssFontFamily.ts

@@ -41,13 +41,19 @@ export type FetchCssFontFamilyOptions = CssFontFaceFilter & {
 // initialize that WASM module and delegate. Parsing correctness is covered by
 // the crate's Rust tests; the TS tests here cover the fetch orchestration.
 //
-// The WASM module is instantiated lazily and at most once — the promise is
-// memoized so concurrent callers share a single init (`__wbg_init` itself is
-// idempotent once resolved, but memoizing avoids a redundant instantiate while
-// the first is still in flight).
-let apiReady: Promise<unknown> | undefined;
+// The WASM module is instantiated lazily and at most once. `__wbg_init` is
+// idempotent only once resolved, and a second instantiation while the first
+// is in flight replaces the module other callers' objects live in, so every
+// caller, including @navaramap/three-api's `initNavaraApi`, shares one
+// promise under a global key.
+const API_READY = Symbol.for("@navaramap/engine-api/init");
+type ApiReadyHolder = { [API_READY]?: Promise<unknown> };
 function ensureApi(): Promise<unknown> {
-  return (apiReady ??= initApi());
+  const holder = globalThis as ApiReadyHolder;
+  return (holder[API_READY] ??= initApi().catch((e: unknown) => {
+    holder[API_READY] = undefined;
+    throw e;
+  }));
 }
 
 /**

package/src/fontWorker.ts

@@ -32,6 +32,8 @@ function convertGlyphs(glyphs: WasmShapedGlyph[]) {
       xOffset: g.x_offset,
       yOffset: g.y_offset,
       charClass: g.char_class,
+      continuesCluster: g.continues_cluster,
+      direction: g.direction,
     };
     g.free();
     return out;
@@ -66,6 +68,7 @@ function convertShapeResult(sr: WasmShapeTextResult | undefined) {
     ascender: sr.ascender,
     descender: sr.descender,
     lineGap: sr.line_gap,
+    allowsLetterSpacing: sr.allows_letter_spacing,
   };
   sr.free();
   return result;

package/src/index.ts

@@ -18,7 +18,9 @@ export { LRUMap } from "./LRUMap";
 export {
   COLOR_GLYPH_PX_SIZE,
   GlyphCharClass,
+  GlyphDirection,
   SDF_PX_SIZE,
+  atlasPaddingPx,
   atlasRangePx,
 } from "./types";
 export type {

package/src/types.ts

@@ -23,6 +23,16 @@ export const SDF_PX_SIZE = 64.0;
 export const atlasRangePx = (highQuality: boolean): number =>
   highQuality ? 16.0 : 35.0;
 
+/**
+ * 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 const atlasPaddingPx = (highQuality: boolean): number =>
+  highQuality ? 8.0 : 12.0;
+
 /** Glyph metrics from either the SDF or the color atlas. */
 export type GlyphMetrics = {
   glyphId: number;
@@ -55,6 +65,21 @@ export const GlyphCharClass = {
   Ideographic: 3,
 } as const;
 
+/**
+ * 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 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. */
+  Neutral: 0,
+  Ltr: 1,
+  /** The segment's glyphs arrive in visual order (reversed logical order). */
+  Rtl: 2,
+} as const;
+
 /** A single shaped glyph with positioning info. */
 export type ShapedGlyph = {
   glyphId: number;
@@ -68,6 +93,11 @@ export 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. */
@@ -82,6 +112,10 @@ export 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