@navaramap/font 0.0.2 → 0.0.3

package/src/cssFontFamily.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach, vi } from "vitest";
+import { describe, it, expect, afterEach, vi, beforeEach } from "vitest";
 
 import {
   fetchFontFamilyFromCss,
@@ -6,182 +6,53 @@ import {
   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;
-}
-`;
+// The @font-face / unicode-range parsing itself lives in Rust (navara_wasm_api)
+// and is covered by that crate's tests. Here the WASM module is mocked so these
+// tests stay WASM-free and focus on the TypeScript orchestration: lazy init,
+// delegation, and the fetch handling in `fetchFontFamilyFromCss`.
+const { initApi, wasmParseCssUnicodeRange, wasmParseFontFamilyFromCss } =
+  vi.hoisted(() => ({
+    initApi: vi.fn(async () => undefined),
+    wasmParseCssUnicodeRange: vi.fn(),
+    wasmParseFontFamilyFromCss: vi.fn(),
+  }));
+
+vi.mock("@navaramap/engine-api", () => ({
+  default: initApi,
+  parseCssUnicodeRange: wasmParseCssUnicodeRange,
+  parseFontFamilyFromCss: wasmParseFontFamilyFromCss,
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
 
 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 },
-    ]);
+  it("initializes the WASM module and delegates", async () => {
+    const ranges = [{ from: 0x26, to: 0x26 }];
+    wasmParseCssUnicodeRange.mockReturnValue(ranges);
+    // First wrapper call of the module: init runs here. Init is memoized
+    // (see `ensureApi`), so later tests share it and don't re-invoke it —
+    // hence the init assertion lives only in this first test.
+    const result = await parseCssUnicodeRange("U+26");
+    expect(initApi).toHaveBeenCalled();
+    expect(wasmParseCssUnicodeRange).toHaveBeenCalledWith("U+26");
+    expect(result).toBe(ranges);
   });
 });
 
 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("delegates to the WASM parser with options", async () => {
+    const family = { family: "labels", faces: [] };
+    wasmParseFontFamilyFromCss.mockReturnValue(family);
+    const options = { fontFamily: "Archivo", baseUrl: "https://a.test/" };
+    const result = await parseFontFamilyFromCss("labels", "css", options);
+    expect(wasmParseFontFamilyFromCss).toHaveBeenCalledWith(
+      "labels",
+      "css",
+      options,
     );
-  });
-
-  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/);
+    expect(result).toBe(family);
   });
 });
 
@@ -192,8 +63,8 @@ describe("fetchFontFamilyFromCss", () => {
 
   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; }`,
+      "https://a.test/fonts.css": "@font-face-a",
+      "https://b.test/fonts.css": "@font-face-b",
     };
     vi.stubGlobal(
       "fetch",
@@ -203,16 +74,53 @@ describe("fetchFontFamilyFromCss", () => {
         text: async () => cssByUrl[url],
       })),
     );
+    // Echo the resolved baseUrl back as the face URL so we can assert both the
+    // per-stylesheet baseUrl threading and the URL-order concatenation.
+    wasmParseFontFamilyFromCss.mockImplementation(
+      (family: string, _cssText: string, options: { baseUrl?: string }) => ({
+        family,
+        faces: [{ url: options.baseUrl, unicodeRanges: [] }],
+      }),
+    );
+
     const family = await fetchFontFamilyFromCss("labels", [
       "https://a.test/fonts.css",
       "https://b.test/fonts.css",
     ]);
+
+    expect(family.family).toBe("labels");
     expect(family.faces.map((f) => f.url)).toEqual([
-      "https://a.test/a.woff2",
-      "https://b.test/b.woff2",
+      "https://a.test/fonts.css",
+      "https://b.test/fonts.css",
     ]);
   });
 
+  it("passes requestInit to fetch and filter options (minus requestInit) to the parser", async () => {
+    const requestInit = { credentials: "include" as const };
+    const fetchMock = vi.fn(async (url: string) => ({
+      ok: true,
+      url,
+      text: async () => "css",
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+    wasmParseFontFamilyFromCss.mockReturnValue({ family: "labels", faces: [] });
+
+    await fetchFontFamilyFromCss("labels", "https://a.test/fonts.css", {
+      requestInit,
+      fontFamily: "Archivo",
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://a.test/fonts.css",
+      requestInit,
+    );
+    // requestInit must not leak into the parser options.
+    expect(wasmParseFontFamilyFromCss).toHaveBeenCalledWith("labels", "css", {
+      fontFamily: "Archivo",
+      baseUrl: "https://a.test/fonts.css",
+    });
+  });
+
   it("throws on a failed response", async () => {
     vi.stubGlobal(
       "fetch",

package/src/cssFontFamily.ts

@@ -1,4 +1,9 @@
-import type { FontFace, FontFamily, UnicodeRange } from "./types";
+import initApi, {
+  parseCssUnicodeRange as wasmParseCssUnicodeRange,
+  parseFontFamilyFromCss as wasmParseFontFamilyFromCss,
+} from "@navaramap/engine-api";
+
+import type { FontFamily, UnicodeRange } from "./types";
 
 /** Filters selecting which `@font-face` blocks of a stylesheet to include. */
 export type CssFontFaceFilter = {
@@ -31,136 +36,32 @@ export type FetchCssFontFamilyOptions = CssFontFaceFilter & {
   requestInit?: RequestInit;
 };
 
+// The @font-face / unicode-range parsing lives in Rust (`navara_wasm_api`,
+// published as `@navaramap/engine-api`); these functions are thin wrappers that
+// 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;
+function ensureApi(): Promise<unknown> {
+  return (apiReady ??= initApi());
+}
+
 /**
  * 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??`).
+ *
+ * Backed by WASM, so it resolves once `@navaramap/engine-api` has initialized.
  */
-export function parseCssUnicodeRange(value: string): UnicodeRange[] {
-  const ranges: UnicodeRange[] = [];
-  for (const token of value.split(",")) {
-    const trimmed = token.trim();
-    if (!trimmed) continue;
-    const match = /^u\+([0-9a-f?]{1,6})(?:-([0-9a-f]{1,6}))?$/i.exec(trimmed);
-    if (!match) {
-      throw new Error(`Invalid unicode-range token: "${trimmed}"`);
-    }
-    const [, start, end] = match;
-    let range: UnicodeRange;
-    if (start.includes("?")) {
-      // Wildcard form: `U+4??` means U+400-4FF. A wildcard cannot be
-      // combined with an explicit end.
-      if (end !== undefined) {
-        throw new Error(`Invalid unicode-range token: "${trimmed}"`);
-      }
-      range = {
-        from: parseInt(start.replace(/\?/g, "0"), 16),
-        to: parseInt(start.replace(/\?/g, "f"), 16),
-      };
-    } else {
-      const from = parseInt(start, 16);
-      range = { from, to: end !== undefined ? parseInt(end, 16) : from };
-    }
-    if (range.from > range.to || range.to > 0x10ffff) {
-      throw new Error(`Invalid unicode-range token: "${trimmed}"`);
-    }
-    ranges.push(range);
-  }
-  return ranges;
-}
-
-/** A single parsed `@font-face` block's descriptors. */
-type CssFontFaceBlock = {
-  fontFamily?: string;
-  fontStyle?: string;
-  fontWeight?: string;
-  src?: string;
-  unicodeRange?: string;
-};
-
-/** Covers every codepoint — used when a block declares no `unicode-range`. */
-const FULL_RANGE: UnicodeRange[] = [{ from: 0, to: 0x10ffff }];
-
-function stripQuotes(value: string): string {
-  const first = value[0];
-  if ((first === '"' || first === "'") && value.endsWith(first)) {
-    return value.slice(1, -1);
-  }
-  return value;
-}
-
-/** Extract the font URL from a `src` descriptor, preferring woff2 sources. */
-function parseSrcUrl(src: string): string | undefined {
-  const sources = [
-    ...src.matchAll(
-      /url\(\s*("[^"]*"|'[^']*'|[^)]*?)\s*\)(\s*format\(\s*("[^"]*"|'[^']*'|[^)]*?)\s*\))?/gi,
-    ),
-  ];
-  if (sources.length === 0) return undefined;
-  const woff2 = sources.find(
-    (m) => m[3] && stripQuotes(m[3]).toLowerCase() === "woff2",
-  );
-  return stripQuotes((woff2 ?? sources[0])[1].trim());
-}
-
-function parseFontFaceBlocks(cssText: string): CssFontFaceBlock[] {
-  const withoutComments = cssText.replace(/\/\*[\s\S]*?\*\//g, "");
-  const blocks: CssFontFaceBlock[] = [];
-  for (const [, body] of withoutComments.matchAll(
-    /@font-face\s*\{([^}]*)\}/gi,
-  )) {
-    const block: CssFontFaceBlock = {};
-    for (const declaration of body.split(";")) {
-      const colon = declaration.indexOf(":");
-      if (colon < 0) continue;
-      const property = declaration.slice(0, colon).trim().toLowerCase();
-      const value = declaration.slice(colon + 1).trim();
-      if (property === "font-family") block.fontFamily = stripQuotes(value);
-      else if (property === "font-style") block.fontStyle = value;
-      else if (property === "font-weight") block.fontWeight = value;
-      else if (property === "src") block.src = value;
-      else if (property === "unicode-range") block.unicodeRange = value;
-    }
-    blocks.push(block);
-  }
-  return blocks;
-}
-
-/**
- * Normalize a CSS descriptor value for comparison: CSS keywords are
- * case-insensitive, and whitespace (e.g. in variable-font ranges like
- * `"100 900"`) is insignificant beyond separating tokens.
- */
-function normalizeCssValue(value: string): string {
-  return value.trim().replace(/\s+/g, " ").toLowerCase();
-}
-
-function matchesFilter(
-  block: CssFontFaceBlock,
-  filter: CssFontFaceFilter,
-): boolean {
-  if (filter.fontFamily !== undefined) {
-    const wanted = Array.isArray(filter.fontFamily)
-      ? filter.fontFamily
-      : [filter.fontFamily];
-    const name = block.fontFamily?.toLowerCase();
-    if (!wanted.some((w) => w.toLowerCase() === name)) return false;
-  }
-  if (
-    filter.fontWeight !== undefined &&
-    normalizeCssValue(block.fontWeight ?? "") !==
-      normalizeCssValue(String(filter.fontWeight))
-  ) {
-    return false;
-  }
-  if (
-    filter.fontStyle !== undefined &&
-    normalizeCssValue(block.fontStyle ?? "") !==
-      normalizeCssValue(filter.fontStyle)
-  ) {
-    return false;
-  }
-  return true;
+export async function parseCssUnicodeRange(
+  value: string,
+): Promise<UnicodeRange[]> {
+  await ensureApi();
+  return wasmParseCssUnicodeRange(value) as UnicodeRange[];
 }
 
 /**
@@ -178,57 +79,20 @@ function matchesFilter(
  * codepoints no face covers — same semantics as a hand-written
  * {@link FontFamily}.
  *
+ * The parsing runs in WASM (`@navaramap/engine-api`), so this resolves once
+ * that module has initialized.
+ *
  * @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 function parseFontFamilyFromCss(
+export async function parseFontFamilyFromCss(
   family: string,
   cssText: string,
   options: ParseCssFontFamilyOptions = {},
-): FontFamily {
-  const faces: { face: FontFace; cssFamily: string }[] = [];
-  for (const block of parseFontFaceBlocks(cssText)) {
-    if (!matchesFilter(block, options)) continue;
-    if (block.src === undefined) continue;
-    const rawUrl = parseSrcUrl(block.src);
-    if (rawUrl === undefined) continue;
-    const url = options.baseUrl
-      ? new URL(rawUrl, options.baseUrl).toString()
-      : rawUrl;
-    const unicodeRanges = block.unicodeRange
-      ? parseCssUnicodeRange(block.unicodeRange)
-      : FULL_RANGE;
-    faces.push({
-      face: { url, unicodeRanges },
-      cssFamily: block.fontFamily?.toLowerCase() ?? "",
-    });
-  }
-  if (faces.length === 0) {
-    throw new Error(
-      `parseFontFamilyFromCss: no @font-face rules matched for family "${family}"`,
-    );
-  }
-  // CSS gives LATER @font-face rules precedence when their unicode-ranges
-  // overlap, so reverse the block order. Stylesheets rely on this: e.g.
-  // Google Fonts' `latin-ext` block declares broad ranges (U+0100-024F)
-  // that include codepoints only present in the `latin` file declared
-  // after it — without the reversal those codepoints would route to a face
-  // missing the glyph and shape as tofu.
-  faces.reverse();
-  if (Array.isArray(options.fontFamily)) {
-    // Some stylesheets (e.g. the Google Fonts CSS API) order @font-face
-    // blocks alphabetically, so restore the priority the caller asked for.
-    const priority = options.fontFamily.map((name) => name.toLowerCase());
-    // Families absent from the list rank last, not first (indexOf's -1
-    // would otherwise give them top priority).
-    const rank = (cssFamily: string) => {
-      const index = priority.indexOf(cssFamily);
-      return index === -1 ? priority.length : index;
-    };
-    faces.sort((a, b) => rank(a.cssFamily) - rank(b.cssFamily));
-  }
-  return { family, faces: faces.map(({ face }) => face) };
+): Promise<FontFamily> {
+  await ensureApi();
+  return wasmParseFontFamilyFromCss(family, cssText, options) as FontFamily;
 }
 
 /**
@@ -263,7 +127,7 @@ export async function fetchFontFamilyFromCss(
 ): Promise<FontFamily> {
   const urls = Array.isArray(cssUrl) ? cssUrl : [cssUrl];
   const { requestInit, ...filter } = options;
-  const faces: FontFace[] = [];
+  const faces: FontFamily["faces"] = [];
   const cssTexts = await Promise.all(
     urls.map(async (url) => {
       const response = await fetch(url, requestInit);
@@ -278,9 +142,11 @@ export async function fetchFontFamilyFromCss(
     }),
   );
   for (const { text, baseUrl } of cssTexts) {
-    faces.push(
-      ...parseFontFamilyFromCss(family, text, { ...filter, baseUrl }).faces,
-    );
+    const parsed = await parseFontFamilyFromCss(family, text, {
+      ...filter,
+      baseUrl,
+    });
+    faces.push(...parsed.faces);
   }
   return { family, faces };
 }