@navaramap/font 0.0.0

package/src/FontWorkerClient.ts

@@ -0,0 +1,183 @@
+import type { ConcurrencyManager } from "@navaramap/worker";
+
+import type {
+  ShapeTextResult,
+  FontAtlasData,
+  BatchPrepareTextResult,
+  FontWorkerMemoryStats,
+} from "./types";
+
+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;
+};
+
+/**
+ * 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;
+
+    this._worker = new Worker(workerUrl, {
+      type: import.meta.env.PROD ? undefined : "module",
+    });
+
+    this._worker.onmessage = (e: MessageEvent) => {
+      const { id, type, payload } = e.data;
+      const pending = this._pending.get(id);
+      if (!pending) return;
+      this._pending.delete(id);
+
+      if (type === "error") {
+        pending.reject(new Error(payload.message));
+      } else {
+        pending.resolve(payload);
+      }
+    };
+
+    this._worker.onerror = (e) => {
+      console.error("FontWorkerClient: worker error", e);
+      // Reject all pending requests so callers don't hang indefinitely.
+      this.dispose();
+    };
+
+    // 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();
+  }
+
+  /** Wait for the WASM module to be initialized in the worker. */
+  async ready(): Promise<void> {
+    return this._ready;
+  }
+
+  /** 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). */
+  async loadFont(
+    url: string,
+    data: ArrayBuffer,
+    atlasKey: string | undefined,
+    highQuality: boolean,
+  ): Promise<{ ok: boolean; cmapRanges: Uint32Array | null }> {
+    return this._send("loadFont", { url, data, atlasKey, highQuality }, [
+      data,
+    ]) as Promise<{
+      ok: boolean;
+      cmapRanges: Uint32Array | null;
+    }>;
+  }
+
+  async unloadFont(url: string): Promise<{ ok: boolean }> {
+    return this._send("unloadFont", { url }) as 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 {
+    void this._send("retainGlyphs", { atlasKey, keys }, [keys.buffer]);
+  }
+
+  /** Drop one visible-label reference from each glyph under `atlasKey`. */
+  releaseGlyphs(atlasKey: string, keys: BigUint64Array): void {
+    void this._send("releaseGlyphs", { atlasKey, keys }, [keys.buffer]);
+  }
+
+  /** Shape multiple texts in one worker round-trip. */
+  async prepareTextBatch(
+    fontUrl: string,
+    texts: string[],
+  ): Promise<BatchPrepareTextResult> {
+    type RawAtlas = {
+      data: ArrayBuffer;
+      width: number;
+      height: number;
+      channels: number;
+    };
+    const raw = (await this._send("prepareTextBatch", {
+      fontUrl,
+      texts,
+    })) as {
+      results: { text: string; shapeResult: ShapeTextResult | null }[];
+      atlas: RawAtlas | null;
+      colorAtlas: RawAtlas | null;
+      atlasKey: string;
+      evicted: boolean;
+    };
+
+    const wrap = (raw: RawAtlas | null): FontAtlasData | null =>
+      raw
+        ? {
+            data: new Uint8Array(raw.data),
+            width: raw.width,
+            height: raw.height,
+            channels: raw.channels,
+          }
+        : null;
+
+    return {
+      results: raw.results,
+      atlas: wrap(raw.atlas),
+      colorAtlas: wrap(raw.colorAtlas),
+      atlasKey: raw.atlasKey,
+      evicted: raw.evicted,
+    };
+  }
+
+  /** Snapshot of the worker's WASM heap and font-cache memory usage. */
+  async getMemoryStats(): Promise<FontWorkerMemoryStats> {
+    return this._send(
+      "getMemoryStats",
+      undefined,
+    ) as Promise<FontWorkerMemoryStats>;
+  }
+
+  dispose(): void {
+    this._worker.terminate();
+    for (const pending of this._pending.values()) {
+      pending.reject(new Error("FontWorkerClient disposed"));
+    }
+    this._pending.clear();
+    this._concurrencyManager.decrement();
+  }
+
+  private _send(
+    type: string,
+    payload: unknown,
+    transfers?: Transferable[],
+  ): Promise<unknown> {
+    const id = this._nextId++;
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._worker.postMessage({ id, type, payload }, transfers ?? []);
+    });
+  }
+}

package/src/LRUMap.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import { LRUMap } from "./LRUMap";
+
+describe("LRUMap", () => {
+  let lru: LRUMap<string, number>;
+
+  beforeEach(() => {
+    lru = new LRUMap<string, number>(3);
+  });
+
+  describe("set and get", () => {
+    it("should store and retrieve values", () => {
+      lru.set("a", 1);
+      expect(lru.get("a")).toBe(1);
+    });
+
+    it("should return undefined for missing keys", () => {
+      expect(lru.get("missing")).toBeUndefined();
+    });
+
+    it("should overwrite existing keys", () => {
+      lru.set("a", 1);
+      lru.set("a", 2);
+      expect(lru.get("a")).toBe(2);
+      expect(lru.size).toBe(1);
+    });
+  });
+
+  describe("eviction", () => {
+    it("should evict the least recently used entry when exceeding maxSize", () => {
+      lru.set("a", 1);
+      lru.set("b", 2);
+      lru.set("c", 3);
+      lru.set("d", 4); // should evict "a"
+
+      expect(lru.has("a")).toBe(false);
+      expect(lru.get("b")).toBe(2);
+      expect(lru.get("c")).toBe(3);
+      expect(lru.get("d")).toBe(4);
+      expect(lru.size).toBe(3);
+    });
+
+    it("should refresh entry on get, preventing eviction", () => {
+      lru.set("a", 1);
+      lru.set("b", 2);
+      lru.set("c", 3);
+
+      lru.get("a"); // refresh "a", making "b" the oldest
+
+      lru.set("d", 4); // should evict "b"
+
+      expect(lru.has("a")).toBe(true);
+      expect(lru.has("b")).toBe(false);
+      expect(lru.has("d")).toBe(true);
+    });
+
+    it("should refresh entry on set with existing key", () => {
+      lru.set("a", 1);
+      lru.set("b", 2);
+      lru.set("c", 3);
+
+      lru.set("a", 10); // refresh "a", making "b" the oldest
+
+      lru.set("d", 4); // should evict "b"
+
+      expect(lru.get("a")).toBe(10);
+      expect(lru.has("b")).toBe(false);
+    });
+  });
+
+  describe("has", () => {
+    it("should return true for existing keys", () => {
+      lru.set("a", 1);
+      expect(lru.has("a")).toBe(true);
+    });
+
+    it("should return false for missing keys", () => {
+      expect(lru.has("a")).toBe(false);
+    });
+  });
+
+  describe("delete", () => {
+    it("should remove an entry", () => {
+      lru.set("a", 1);
+      expect(lru.delete("a")).toBe(true);
+      expect(lru.has("a")).toBe(false);
+      expect(lru.size).toBe(0);
+    });
+
+    it("should return false when deleting a non-existent key", () => {
+      expect(lru.delete("a")).toBe(false);
+    });
+  });
+
+  describe("clear", () => {
+    it("should remove all entries", () => {
+      lru.set("a", 1);
+      lru.set("b", 2);
+      lru.clear();
+      expect(lru.size).toBe(0);
+      expect(lru.has("a")).toBe(false);
+    });
+  });
+
+  describe("size", () => {
+    it("should reflect the current number of entries", () => {
+      expect(lru.size).toBe(0);
+      lru.set("a", 1);
+      expect(lru.size).toBe(1);
+      lru.set("b", 2);
+      expect(lru.size).toBe(2);
+    });
+
+    it("should not exceed maxSize", () => {
+      lru.set("a", 1);
+      lru.set("b", 2);
+      lru.set("c", 3);
+      lru.set("d", 4);
+      lru.set("e", 5);
+      expect(lru.size).toBe(3);
+    });
+  });
+});

package/src/LRUMap.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 class LRUMap<K, V> {
+  private _map = new Map<K, V>();
+  private _maxSize: number;
+
+  constructor(maxSize: number) {
+    this._maxSize = maxSize;
+  }
+
+  get size(): number {
+    return this._map.size;
+  }
+
+  has(key: K): boolean {
+    return this._map.has(key);
+  }
+
+  get(key: K): V | undefined {
+    const value = this._map.get(key);
+    if (value !== undefined) {
+      // Touch: move to end (most recently used)
+      this._map.delete(key);
+      this._map.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // Delete first so re-insertion moves it to the end (most recent)
+    if (this._map.has(key)) {
+      this._map.delete(key);
+    }
+
+    this._map.set(key, value);
+
+    // Evict oldest entries if over capacity
+    while (this._map.size > this._maxSize) {
+      const oldest = this._map.keys().next();
+      if (!oldest.done) {
+        this._map.delete(oldest.value);
+      }
+    }
+  }
+
+  delete(key: K): boolean {
+    return this._map.delete(key);
+  }
+
+  clear(): void {
+    this._map.clear();
+  }
+}

package/src/cssFontFamily.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+
+import {
+  fetchFontFamilyFromCss,
+  parseCssUnicodeRange,
+  parseFontFamilyFromCss,
+} from "./cssFontFamily";
+
+// Trimmed-down Google Fonts CSS API response: two subsets of one family plus
+// a second family, each block with its own unicode-range.
+const GOOGLE_FONTS_CSS = `
+/* vietnamese */
+@font-face {
+  font-family: 'Archivo';
+  font-style: normal;
+  font-weight: 800;
+  font-stretch: 125%;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/archivo/v25/viet.woff2) format('woff2');
+  unicode-range: U+0102-0103, U+0110-0111, U+1EA0-1EF9, U+20AB;
+}
+/* latin */
+@font-face {
+  font-family: 'Archivo';
+  font-style: normal;
+  font-weight: 800;
+  font-stretch: 125%;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/archivo/v25/latin.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+2000-206F;
+}
+/* [58] */
+@font-face {
+  font-family: 'Noto Sans JP';
+  font-style: normal;
+  font-weight: 800;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/notosansjp/v56/slice.58.woff2) format('woff2');
+  unicode-range: U+4E00-4EFF;
+}
+`;
+
+describe("parseCssUnicodeRange", () => {
+  it("parses single codepoints, intervals, and wildcards", () => {
+    expect(parseCssUnicodeRange("U+26")).toEqual([{ from: 0x26, to: 0x26 }]);
+    expect(parseCssUnicodeRange("U+0102-0103, U+20AB")).toEqual([
+      { from: 0x102, to: 0x103 },
+      { from: 0x20ab, to: 0x20ab },
+    ]);
+    expect(parseCssUnicodeRange("U+4??")).toEqual([{ from: 0x400, to: 0x4ff }]);
+    expect(parseCssUnicodeRange("u+1ea0-1ef9")).toEqual([
+      { from: 0x1ea0, to: 0x1ef9 },
+    ]);
+  });
+
+  it("rejects malformed tokens", () => {
+    expect(() => parseCssUnicodeRange("0102-0103")).toThrow();
+    expect(() => parseCssUnicodeRange("U+GGGG")).toThrow();
+    expect(() => parseCssUnicodeRange("U+4??-4FF")).toThrow();
+  });
+
+  it("rejects ranges whose end precedes their start", () => {
+    expect(() => parseCssUnicodeRange("U+200-100")).toThrow();
+  });
+
+  it("rejects codepoints beyond U+10FFFF", () => {
+    expect(() => parseCssUnicodeRange("U+110000")).toThrow();
+    expect(() => parseCssUnicodeRange("U+10FFFF-110000")).toThrow();
+    expect(() => parseCssUnicodeRange("U+??????")).toThrow();
+    expect(parseCssUnicodeRange("U+10FFFF")).toEqual([
+      { from: 0x10ffff, to: 0x10ffff },
+    ]);
+  });
+});
+
+describe("parseFontFamilyFromCss", () => {
+  it("builds one face per @font-face block, in reverse stylesheet order", () => {
+    const family = parseFontFamilyFromCss("labels", GOOGLE_FONTS_CSS);
+    expect(family.family).toBe("labels");
+    expect(family.faces).toHaveLength(3);
+    // CSS gives later @font-face rules precedence on range overlap, so
+    // blocks come out reversed: Archivo's latin block ends up before its
+    // latin-ext/vietnamese ones. Use the fontFamily array to order families.
+    expect(family.faces[0].url).toContain("notosansjp");
+    expect(family.faces[1]).toEqual({
+      url: "https://fonts.gstatic.com/s/archivo/v25/latin.woff2",
+      unicodeRanges: [
+        { from: 0x0, to: 0xff },
+        { from: 0x2000, to: 0x206f },
+      ],
+    });
+    expect(family.faces[2].url).toContain("viet");
+  });
+
+  it("routes overlap-declared codepoints to the later (more specific) block", () => {
+    // Mimics Google Fonts: latin-ext declares a broad range including
+    // U+0131, but the glyph only exists in the latin file declared after it.
+    const css = `
+      @font-face { font-family: A; font-style: normal; font-weight: 800; src: url(latin-ext.woff2); unicode-range: U+0100-024F; }
+      @font-face { font-family: A; font-style: normal; font-weight: 800; src: url(latin.woff2); unicode-range: U+0000-00FF, U+0131; }
+    `;
+    const family = parseFontFamilyFromCss("labels", css);
+    expect(family.faces.map((f) => f.url)).toEqual([
+      "latin.woff2",
+      "latin-ext.woff2",
+    ]);
+  });
+
+  it("filters blocks by font-family name", () => {
+    const family = parseFontFamilyFromCss("labels", GOOGLE_FONTS_CSS, {
+      fontFamily: "Noto Sans JP",
+    });
+    expect(family.faces).toHaveLength(1);
+    expect(family.faces[0].url).toContain("notosansjp");
+  });
+
+  it("orders faces by fontFamily array position, not stylesheet order", () => {
+    // Google Fonts sorts blocks alphabetically; the caller's array wins.
+    const family = parseFontFamilyFromCss("labels", GOOGLE_FONTS_CSS, {
+      fontFamily: ["Noto Sans JP", "Archivo"],
+    });
+    expect(family.faces.map((f) => f.url)).toEqual([
+      "https://fonts.gstatic.com/s/notosansjp/v56/slice.58.woff2",
+      "https://fonts.gstatic.com/s/archivo/v25/latin.woff2",
+      "https://fonts.gstatic.com/s/archivo/v25/viet.woff2",
+    ]);
+  });
+
+  it("filters blocks by weight and style", () => {
+    const css = `
+      @font-face { font-family: A; font-style: italic; font-weight: 400; src: url(a-italic.woff2); }
+      @font-face { font-family: A; font-style: normal; font-weight: 700; src: url(a-bold.woff2); }
+    `;
+    const family = parseFontFamilyFromCss("labels", css, {
+      fontStyle: "normal",
+      fontWeight: 700,
+    });
+    expect(family.faces).toHaveLength(1);
+    expect(family.faces[0].url).toBe("a-bold.woff2");
+  });
+
+  it("normalizes whitespace and case in weight/style filters", () => {
+    const css = `
+      @font-face { font-family: A; font-style: normal; font-weight: 100  900; src: url(a-var.woff2); }
+    `;
+    const family = parseFontFamilyFromCss("labels", css, {
+      fontStyle: "Normal",
+      fontWeight: " 100 900 ",
+    });
+    expect(family.faces).toHaveLength(1);
+    expect(family.faces[0].url).toBe("a-var.woff2");
+  });
+
+  it("covers all codepoints when a block has no unicode-range", () => {
+    const css = `@font-face { font-family: A; src: url(a.woff2); }`;
+    const family = parseFontFamilyFromCss("labels", css);
+    expect(family.faces[0].unicodeRanges).toEqual([{ from: 0, to: 0x10ffff }]);
+  });
+
+  it("resolves relative src URLs against baseUrl", () => {
+    const css = `@font-face { font-family: A; src: url(./fonts/a.woff2); unicode-range: U+0-7F; }`;
+    const family = parseFontFamilyFromCss("labels", css, {
+      baseUrl: "https://example.com/styles/fonts.css",
+    });
+    expect(family.faces[0].url).toBe(
+      "https://example.com/styles/fonts/a.woff2",
+    );
+  });
+
+  it("prefers the woff2 source when src lists several formats", () => {
+    const css = `@font-face {
+      font-family: A;
+      src: url("a.eot") format("embedded-opentype"), url('a.woff2') format('woff2'), url(a.ttf) format(truetype);
+    }`;
+    const family = parseFontFamilyFromCss("labels", css);
+    expect(family.faces[0].url).toBe("a.woff2");
+  });
+
+  it("throws when no block matches", () => {
+    expect(() =>
+      parseFontFamilyFromCss("labels", GOOGLE_FONTS_CSS, {
+        fontFamily: "Nope",
+      }),
+    ).toThrow(/no @font-face rules matched/);
+  });
+});
+
+describe("fetchFontFamilyFromCss", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("fetches stylesheets and concatenates faces in URL order", async () => {
+    const cssByUrl: Record<string, string> = {
+      "https://a.test/fonts.css": `@font-face { font-family: A; src: url(/a.woff2); unicode-range: U+0-7F; }`,
+      "https://b.test/fonts.css": `@font-face { font-family: B; src: url(/b.woff2); unicode-range: U+4E00-9FFF; }`,
+    };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => ({
+        ok: true,
+        url,
+        text: async () => cssByUrl[url],
+      })),
+    );
+    const family = await fetchFontFamilyFromCss("labels", [
+      "https://a.test/fonts.css",
+      "https://b.test/fonts.css",
+    ]);
+    expect(family.faces.map((f) => f.url)).toEqual([
+      "https://a.test/a.woff2",
+      "https://b.test/b.woff2",
+    ]);
+  });
+
+  it("throws on a failed response", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({
+        ok: false,
+        status: 403,
+        url: "",
+        text: async () => "",
+      })),
+    );
+    await expect(
+      fetchFontFamilyFromCss("labels", "https://a.test/fonts.css"),
+    ).rejects.toThrow(/403/);
+  });
+});