pagyra-js 0.0.1

package/src/pdf/font/builtin-fonts.browser.ts

@@ -0,0 +1,262 @@
+import { log } from "../../logging/debug.js";
+import type { Environment } from "../../environment/environment.js";
+import { BrowserEnvironment } from "../../environment/browser-environment.js";
+import type { FontConfig, FontFaceDef } from "../../types/fonts.js";
+
+type FontSource = "assets" | "google";
+
+type BuiltinFace = Omit<FontFaceDef, "src" | "data"> & { file: string; google?: string };
+
+const BUILTIN_FACES: BuiltinFace[] = [
+  // Sans: primary and UI-friendly
+  { name: "Lato-Regular", family: "Lato", weight: 400, style: "normal", file: "woff2/lato/lato-latin-400-normal.woff2", google: "Lato" },
+  { name: "Lato-Bold", family: "Lato", weight: 700, style: "normal", file: "woff2/lato/lato-latin-700-normal.woff2", google: "Lato" },
+  { name: "Lato-Italic", family: "Lato", weight: 400, style: "italic", file: "woff2/lato/lato-latin-400-italic.woff2", google: "Lato" },
+  { name: "Lato-BoldItalic", family: "Lato", weight: 700, style: "italic", file: "woff2/lato/lato-latin-700-italic.woff2", google: "Lato" },
+  { name: "Roboto-Regular", family: "Roboto", weight: 400, style: "normal", file: "ttf/roboto/Roboto-Regular.ttf", google: "Roboto" },
+  { name: "Roboto-Bold", family: "Roboto", weight: 700, style: "normal", file: "ttf/roboto/Roboto-Bold.ttf", google: "Roboto" },
+  { name: "Roboto-Italic", family: "Roboto", weight: 400, style: "italic", file: "ttf/roboto/Roboto-Italic.ttf", google: "Roboto" },
+  { name: "Roboto-BoldItalic", family: "Roboto", weight: 700, style: "italic", file: "ttf/roboto/Roboto-BoldItalic.ttf", google: "Roboto" },
+  { name: "Arimo-Regular", family: "Arimo", weight: 400, style: "normal", file: "ttf/arimo/Arimo-Regular.ttf", google: "Arimo" },
+  { name: "Arimo-Bold", family: "Arimo", weight: 700, style: "normal", file: "ttf/arimo/Arimo-Bold.ttf", google: "Arimo" },
+  { name: "Arimo-Italic", family: "Arimo", weight: 400, style: "italic", file: "ttf/arimo/Arimo-Italic.ttf", google: "Arimo" },
+  { name: "Arimo-BoldItalic", family: "Arimo", weight: 700, style: "italic", file: "ttf/arimo/Arimo-BoldItalic.ttf", google: "Arimo" },
+  { name: "NotoSans-Regular", family: "Noto Sans", weight: 400, style: "normal", file: "ttf/notosans/NotoSans-Regular.ttf", google: "Noto Sans" },
+  { name: "DejaVuSans-Regular", family: "DejaVu Sans", weight: 400, style: "normal", file: "ttf/dejavu/DejaVuSans.ttf" },
+
+  // Serif / display
+  { name: "Tinos-Regular", family: "Tinos", weight: 400, style: "normal", file: "ttf/tinos/Tinos-Regular.ttf", google: "Tinos" },
+  { name: "Tinos-Bold", family: "Tinos", weight: 700, style: "normal", file: "ttf/tinos/Tinos-Bold.ttf", google: "Tinos" },
+  { name: "Tinos-Italic", family: "Tinos", weight: 400, style: "italic", file: "ttf/tinos/Tinos-Italic.ttf", google: "Tinos" },
+  { name: "Tinos-BoldItalic", family: "Tinos", weight: 700, style: "italic", file: "ttf/tinos/Tinos-BoldItalic.ttf", google: "Tinos" },
+  { name: "CinzelDecorative-Regular", family: "Cinzel Decorative", weight: 400, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Regular.ttf", google: "Cinzel Decorative" },
+  { name: "CinzelDecorative-Bold", family: "Cinzel Decorative", weight: 700, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Bold.ttf", google: "Cinzel Decorative" },
+  { name: "CinzelDecorative-Black", family: "Cinzel Decorative", weight: 900, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Black.ttf", google: "Cinzel Decorative" },
+  { name: "Caveat-Regular", family: "Caveat", weight: 400, style: "normal", file: "woff2/caveat/Caveat-Regular.woff2", google: "Caveat" },
+  { name: "Caveat-Bold", family: "Caveat", weight: 700, style: "normal", file: "woff2/caveat/Caveat-Bold.woff2", google: "Caveat" },
+
+  // Monospace
+  { name: "FiraCode-Light", family: "Fira Code", weight: 300, style: "normal", file: "ttf/firecode/FiraCode-Light.ttf", google: "Fira Code" },
+  { name: "FiraCode-Regular", family: "Fira Code", weight: 400, style: "normal", file: "ttf/firecode/FiraCode-Regular.ttf", google: "Fira Code" },
+  { name: "FiraCode-Medium", family: "Fira Code", weight: 500, style: "normal", file: "ttf/firecode/FiraCode-Medium.ttf", google: "Fira Code" },
+  { name: "FiraCode-SemiBold", family: "Fira Code", weight: 600, style: "normal", file: "ttf/firecode/FiraCode-SemiBold.ttf", google: "Fira Code" },
+  { name: "FiraCode-Bold", family: "Fira Code", weight: 700, style: "normal", file: "ttf/firecode/FiraCode-Bold.ttf", google: "Fira Code" },
+
+  // Emoji
+  { name: "NotoEmoji-Light", family: "Noto Emoji", weight: 300, style: "normal", file: "ttf/notoemoji/NotoEmoji-Light.ttf" },
+  { name: "NotoEmoji-Regular", family: "Noto Emoji", weight: 400, style: "normal", file: "ttf/notoemoji/NotoEmoji-Regular.ttf" },
+  { name: "NotoEmoji-Medium", family: "Noto Emoji", weight: 500, style: "normal", file: "ttf/notoemoji/NotoEmoji-Medium.ttf" },
+  { name: "NotoEmoji-SemiBold", family: "Noto Emoji", weight: 600, style: "normal", file: "ttf/notoemoji/NotoEmoji-SemiBold.ttf" },
+  { name: "NotoEmoji-Bold", family: "Noto Emoji", weight: 700, style: "normal", file: "ttf/notoemoji/NotoEmoji-Bold.ttf" },
+
+  // Math
+  { name: "STIXTwoMath-Regular", family: "STIX Two Math", weight: 400, style: "normal", file: "ttf/stixtwomath/STIXTwoMath-Regular.ttf" },
+];
+
+const DEFAULT_STACK: string[] = [
+  "Lato",
+  "Roboto",
+  "Arimo",
+  "Noto Sans",
+  "DejaVu Sans",
+  "Tinos",
+  "Fira Code",
+  "Caveat",
+  "Cinzel Decorative",
+  "Noto Emoji",
+  "STIX Two Math",
+];
+
+let cachedConfig: FontConfig | null | undefined;
+let cachedSource: FontSource | null = null;
+let loading: Promise<FontConfig | null> | null = null;
+
+export async function loadBuiltinFontConfig(environment: Environment = new BrowserEnvironment()): Promise<FontConfig | null> {
+  const source = resolveFontSource();
+  if (cachedConfig !== undefined && cachedSource === source) {
+    return cachedConfig;
+  }
+  if (loading && cachedSource === source) {
+    return loading;
+  }
+
+  cachedSource = source;
+
+  loading = (async () => {
+    // Try the selected source; if google fails and was explicitly selected, fall back to assets.
+    if (source === "google") {
+      const googleFaces = await loadFromGoogleFonts(environment);
+      if (googleFaces.length) {
+        cachedConfig = { fontFaceDefs: googleFaces, defaultStack: DEFAULT_STACK };
+        return cachedConfig;
+      }
+      log("font", "warn", "Google Fonts requested but none loaded; falling back to bundled assets");
+    }
+
+    const assetFaces = await loadFromAssets(environment);
+    cachedConfig = assetFaces.length ? { fontFaceDefs: assetFaces, defaultStack: DEFAULT_STACK } : null;
+    return cachedConfig;
+  })();
+
+  try {
+    return await loading;
+  } finally {
+    loading = null;
+  }
+}
+
+function computeBaseUrl(): string {
+  const globalBase = (globalThis as any).__PAGYRA_FONT_BASE;
+  if (typeof globalBase === "string" && globalBase.trim().length > 0) {
+    return ensureTrailingSlash(globalBase.trim());
+  }
+  if (typeof window !== "undefined" && window.location) {
+    const origin = window.location.origin.endsWith("/") ? window.location.origin : `${window.location.origin}/`;
+    return `${origin}assets/fonts/`;
+  }
+  try {
+    return new URL("../../assets/fonts/", import.meta.url).toString();
+  } catch {
+    return "/assets/fonts/";
+  }
+}
+
+function ensureTrailingSlash(input: string): string {
+  return input.endsWith("/") ? input : `${input}/`;
+}
+
+function resolveFontSource(): FontSource {
+  const globalSource = (globalThis as any).__PAGYRA_FONT_SOURCE;
+  const legacyGoogle = (globalThis as any).__PAGYRA_USE_GOOGLE_FONTS;
+  if (typeof globalSource === "string") {
+    const normalized = globalSource.toLowerCase();
+    if (normalized === "google") return "google";
+    if (normalized === "assets") return "assets";
+  }
+  if (legacyGoogle === true) {
+    return "google";
+  }
+  return "assets";
+}
+
+async function loadFromAssets(environment: Environment): Promise<FontFaceDef[]> {
+  const baseUrl = computeBaseUrl();
+  const faces: FontFaceDef[] = [];
+  for (const face of BUILTIN_FACES) {
+    const url = new URL(face.file, baseUrl).toString();
+    try {
+      log("font", "debug", "Loading browser font file", { url });
+      const buffer = await environment.loader.load(url);
+      faces.push({
+        name: face.name,
+        family: face.family,
+        weight: face.weight,
+        style: face.style,
+        src: url,
+        data: buffer,
+      });
+    } catch (error) {
+      log("font", "warn", "Failed to load font file", { url, error });
+    }
+  }
+  return faces;
+}
+
+async function loadFromGoogleFonts(environment: Environment): Promise<FontFaceDef[]> {
+  const requestable = BUILTIN_FACES.filter((f) => !!f.google);
+  if (!requestable.length) return [];
+
+  const cssUrl = buildGoogleCssUrl(requestable);
+  if (!cssUrl) return [];
+
+  try {
+    log("font", "debug", "Fetching Google Fonts CSS", { url: cssUrl });
+    const cssBuffer = await environment.loader.load(cssUrl);
+    const cssText = new TextDecoder().decode(cssBuffer);
+    const faceUrls = parseGoogleCss(cssText);
+
+    const faces: FontFaceDef[] = [];
+    for (const face of requestable) {
+      const key = faceKey(face.family, face.weight, face.style);
+      const url = faceUrls.get(key);
+      if (!url) {
+        log("font", "warn", "Google Fonts entry missing", { family: face.family, weight: face.weight, style: face.style });
+        continue;
+      }
+      try {
+        log("font", "debug", "Downloading Google font file", { url, family: face.family, weight: face.weight, style: face.style });
+        const buffer = await environment.loader.load(url);
+        faces.push({
+          name: face.name,
+          family: face.family,
+          weight: face.weight,
+          style: face.style,
+          src: url,
+          data: buffer,
+        });
+      } catch (error) {
+        log("font", "warn", "Failed to download Google font", { url, family: face.family, weight: face.weight, style: face.style, error });
+      }
+    }
+    return faces;
+  } catch (error) {
+    log("font", "warn", "Failed to load Google Fonts CSS", { url: cssUrl, error });
+    return [];
+  }
+}
+
+function buildGoogleCssUrl(faces: BuiltinFace[]): string {
+  const byFamily = new Map<string, Set<string>>();
+  for (const face of faces) {
+    if (!face.google) continue;
+    const key = face.google;
+    let set = byFamily.get(key);
+    if (!set) {
+      set = new Set();
+      byFamily.set(key, set);
+    }
+    const ital = face.style === "italic" ? 1 : 0;
+    set.add(`${ital},${face.weight}`);
+  }
+
+  const families: string[] = [];
+  for (const [family, combos] of byFamily) {
+    const comboList = Array.from(combos).sort();
+    const param = `family=${encodeGoogleFamily(family)}:ital,wght@${comboList.join(";")}`;
+    families.push(param);
+  }
+
+  if (!families.length) return "";
+  return `https://fonts.googleapis.com/css2?${families.join("&")}&display=swap`;
+}
+
+function encodeGoogleFamily(family: string): string {
+  return encodeURIComponent(family.replace(/\s+/g, "+"));
+}
+
+function parseGoogleCss(cssText: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const blockRegex = /@font-face\s*{[^}]*}/g;
+  for (const blockMatch of cssText.matchAll(blockRegex)) {
+    const block = blockMatch[0];
+    const familyMatch = /font-family:\s*['"]?([^'";]+)['"]?/i.exec(block);
+    const weightMatch = /font-weight:\s*([0-9]+)/i.exec(block);
+    const styleMatch = /font-style:\s*(italic|normal)/i.exec(block);
+    const srcMatch = /src:\s*[^;]*url\(([^)]+)\)/i.exec(block);
+    if (!familyMatch || !weightMatch || !styleMatch || !srcMatch) continue;
+
+    const family = familyMatch[1].trim();
+    const weight = Number.parseInt(weightMatch[1], 10);
+    const style = styleMatch[1].toLowerCase() === "italic" ? "italic" : "normal";
+    const url = srcMatch[1].replace(/['"]/g, "").trim();
+    const key = faceKey(family, weight, style);
+    if (!result.has(key)) {
+      result.set(key, url);
+    }
+  }
+  return result;
+}
+
+function faceKey(family: string, weight: number, style: string): string {
+  return `${family.toLowerCase()}@${weight}@${style.toLowerCase()}`;
+}

package/src/pdf/font/builtin-fonts.ts

@@ -0,0 +1,126 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { log, type LogLevel } from "../../logging/debug.js";
+import type { FontConfig, FontFaceDef } from "../../types/fonts.js";
+import type { Environment } from "../../environment/environment.js";
+import { NodeEnvironment } from "../../environment/node-environment.js";
+
+type BuiltinFace = Omit<FontFaceDef, "src" | "data"> & { file: string };
+
+const BUILTIN_FACES: BuiltinFace[] = [
+  // Sans: primary and UI-friendly
+  { name: "Lato-Regular", family: "Lato", weight: 400, style: "normal", file: "woff2/lato/lato-latin-400-normal.woff2" },
+  { name: "Lato-Bold", family: "Lato", weight: 700, style: "normal", file: "woff2/lato/lato-latin-700-normal.woff2" },
+  { name: "Lato-Italic", family: "Lato", weight: 400, style: "italic", file: "woff2/lato/lato-latin-400-italic.woff2" },
+  { name: "Lato-BoldItalic", family: "Lato", weight: 700, style: "italic", file: "woff2/lato/lato-latin-700-italic.woff2" },
+  { name: "Roboto-Regular", family: "Roboto", weight: 400, style: "normal", file: "ttf/roboto/Roboto-Regular.ttf" },
+  { name: "Roboto-Bold", family: "Roboto", weight: 700, style: "normal", file: "ttf/roboto/Roboto-Bold.ttf" },
+  { name: "Roboto-Italic", family: "Roboto", weight: 400, style: "italic", file: "ttf/roboto/Roboto-Italic.ttf" },
+  { name: "Roboto-BoldItalic", family: "Roboto", weight: 700, style: "italic", file: "ttf/roboto/Roboto-BoldItalic.ttf" },
+  { name: "Arimo-Regular", family: "Arimo", weight: 400, style: "normal", file: "ttf/arimo/Arimo-Regular.ttf" },
+  { name: "Arimo-Bold", family: "Arimo", weight: 700, style: "normal", file: "ttf/arimo/Arimo-Bold.ttf" },
+  { name: "Arimo-Italic", family: "Arimo", weight: 400, style: "italic", file: "ttf/arimo/Arimo-Italic.ttf" },
+  { name: "Arimo-BoldItalic", family: "Arimo", weight: 700, style: "italic", file: "ttf/arimo/Arimo-BoldItalic.ttf" },
+  { name: "NotoSans-Regular", family: "Noto Sans", weight: 400, style: "normal", file: "ttf/notosans/NotoSans-Regular.ttf" },
+  { name: "DejaVuSans-Regular", family: "DejaVu Sans", weight: 400, style: "normal", file: "ttf/dejavu/DejaVuSans.ttf" },
+
+  // Serif / display
+  { name: "Tinos-Regular", family: "Tinos", weight: 400, style: "normal", file: "ttf/tinos/Tinos-Regular.ttf" },
+  { name: "Tinos-Bold", family: "Tinos", weight: 700, style: "normal", file: "ttf/tinos/Tinos-Bold.ttf" },
+  { name: "Tinos-Italic", family: "Tinos", weight: 400, style: "italic", file: "ttf/tinos/Tinos-Italic.ttf" },
+  { name: "Tinos-BoldItalic", family: "Tinos", weight: 700, style: "italic", file: "ttf/tinos/Tinos-BoldItalic.ttf" },
+  { name: "CinzelDecorative-Regular", family: "Cinzel Decorative", weight: 400, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Regular.ttf" },
+  { name: "CinzelDecorative-Bold", family: "Cinzel Decorative", weight: 700, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Bold.ttf" },
+  { name: "CinzelDecorative-Black", family: "Cinzel Decorative", weight: 900, style: "normal", file: "ttf/cinzeldecorative/CinzelDecorative-Black.ttf" },
+  { name: "Caveat-Regular", family: "Caveat", weight: 400, style: "normal", file: "woff2/caveat/Caveat-Regular.woff2" },
+  { name: "Caveat-Bold", family: "Caveat", weight: 700, style: "normal", file: "woff2/caveat/Caveat-Bold.woff2" },
+
+  // Monospace
+  { name: "FiraCode-Light", family: "Fira Code", weight: 300, style: "normal", file: "ttf/firecode/FiraCode-Light.ttf" },
+  { name: "FiraCode-Regular", family: "Fira Code", weight: 400, style: "normal", file: "ttf/firecode/FiraCode-Regular.ttf" },
+  { name: "FiraCode-Medium", family: "Fira Code", weight: 500, style: "normal", file: "ttf/firecode/FiraCode-Medium.ttf" },
+  { name: "FiraCode-SemiBold", family: "Fira Code", weight: 600, style: "normal", file: "ttf/firecode/FiraCode-SemiBold.ttf" },
+  { name: "FiraCode-Bold", family: "Fira Code", weight: 700, style: "normal", file: "ttf/firecode/FiraCode-Bold.ttf" },
+
+  // Emoji
+  { name: "NotoEmoji-Light", family: "Noto Emoji", weight: 300, style: "normal", file: "ttf/notoemoji/NotoEmoji-Light.ttf" },
+  { name: "NotoEmoji-Regular", family: "Noto Emoji", weight: 400, style: "normal", file: "ttf/notoemoji/NotoEmoji-Regular.ttf" },
+  { name: "NotoEmoji-Medium", family: "Noto Emoji", weight: 500, style: "normal", file: "ttf/notoemoji/NotoEmoji-Medium.ttf" },
+  { name: "NotoEmoji-SemiBold", family: "Noto Emoji", weight: 600, style: "normal", file: "ttf/notoemoji/NotoEmoji-SemiBold.ttf" },
+  { name: "NotoEmoji-Bold", family: "Noto Emoji", weight: 700, style: "normal", file: "ttf/notoemoji/NotoEmoji-Bold.ttf" },
+
+  // Math
+  { name: "STIXTwoMath-Regular", family: "STIX Two Math", weight: 400, style: "normal", file: "ttf/stixtwomath/STIXTwoMath-Regular.ttf" },
+];
+
+let cachedConfig: FontConfig | null | undefined;
+let loading: Promise<FontConfig | null> | null = null;
+
+export async function loadBuiltinFontConfig(environment: Environment = new NodeEnvironment()): Promise<FontConfig | null> {
+  if (loading) {
+    return loading;
+  }
+  if (!isNodeRuntime()) {
+    cachedConfig = null;
+    return null;
+  }
+
+  loading = (async () => {
+    try {
+      const baseDir = resolveFontsDir();
+      log('font', 'debug', "Builtin font baseDir:", baseDir);
+      const faces: FontFaceDef[] = [];
+      for (const face of BUILTIN_FACES) {
+        const filePath = path.join(baseDir, face.file);
+        log('font', 'debug', "Loading font file:", filePath);
+        try {
+          const buffer = await environment.loader.load(filePath);
+          faces.push({
+            name: face.name,
+            family: face.family,
+            weight: face.weight,
+            style: face.style,
+            src: filePath,
+            data: buffer,
+          });
+        } catch (err) {
+          log('font', 'warn', `Failed to load font file: ${filePath}`, err);
+        }
+      }
+      cachedConfig = {
+        fontFaceDefs: faces,
+        defaultStack: [
+          "Lato",
+          "Roboto",
+          "Arimo",
+          "Noto Sans",
+          "DejaVu Sans",
+          "Tinos",
+          "Fira Code",
+          "Caveat",
+          "Cinzel Decorative",
+          "Noto Emoji",
+          "STIX Two Math",
+        ],
+      };
+      return cachedConfig;
+    } catch (error) {
+      log("font", 'warn', "Unable to load builtin font config", { error });
+      cachedConfig = null;
+      return null;
+    } finally {
+      loading = null;
+    }
+  })();
+
+  return loading;
+}
+
+function resolveFontsDir(): string {
+  const here = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(here), "../../../assets/fonts");
+}
+
+function isNodeRuntime(): boolean {
+  return typeof process !== "undefined" && !!process.versions?.node;
+}

package/src/pdf/font/composite-glyph-parser.ts

@@ -0,0 +1,242 @@
+import type { GlyphOutlineCmd } from "../../types/fonts.js";
+import type { DataViewReader } from "./ttf-table-provider.js";
+import { TransformationMatrix } from "./transformation-matrix.js";
+
+/**
+ * Provider interface for retrieving glyph outlines.
+ * Used to resolve component glyph references in composite glyphs.
+ */
+export interface GlyphOutlineProvider {
+    /**
+     * Gets the outline for a glyph.
+     * @param glyphId - The glyph ID
+     * @param depth - Current recursion depth (for preventing infinite recursion)
+     * @returns Glyph outline commands, or null if not available
+     */
+    getOutline(glyphId: number, depth?: number): GlyphOutlineCmd[] | null;
+}
+
+/**
+ * Component transformation and reference data.
+ */
+interface ComponentData {
+    glyphIndex: number;
+    flags: number;
+    transform: TransformationMatrix;
+    hasMoreComponents: boolean;
+}
+
+/**
+ * Parses composite (component-based) TrueType glyphs.
+ * 
+ * Composite glyphs are built from one or more simple glyphs (components),
+ * each with its own transformation (translation, scale, rotation).
+ */
+export class CompositeGlyphParser {
+    private readonly recursionLimit = 8;
+    private readonly visited: Set<number> = new Set();
+
+    // Component flags
+    private static readonly ARG_1_AND_2_ARE_WORDS = 0x0001;
+    private static readonly WE_HAVE_A_SCALE = 0x0008;
+    private static readonly MORE_COMPONENTS = 0x0020;
+    private static readonly WE_HAVE_AN_X_AND_Y_SCALE = 0x0040;
+    private static readonly WE_HAVE_A_TWO_BY_TWO = 0x0080;
+
+    constructor(private readonly reader: DataViewReader) { }
+
+    /**
+     * Parses a composite glyph.
+     * @param view - DataView containing the composite glyph data
+     * @param provider - Provider for resolving component glyph references
+     * @param depth - Current recursion depth
+     * @returns Array of glyph outline commands, or null if parsing fails
+     */
+    parse(
+        view: DataView,
+        provider: GlyphOutlineProvider,
+        depth: number = 0
+    ): GlyphOutlineCmd[] | null {
+        if (depth > this.recursionLimit) return null;
+
+        // Composite glyph component records start at offset 10 (after header)
+        const cmds = this.parseComponentRecords(view, 10, provider, depth);
+
+        // Clear visited set for next parse
+        this.visited.clear();
+
+        return cmds;
+    }
+
+    /**
+     * Parses component records from a composite glyph.
+     * @param view - DataView containing the glyph data
+     * @param startOffset - Starting offset for component records
+     * @param provider - Provider for resolving component references
+     * @param depth - Current recursion depth
+     * @returns Combined outline commands from all components, or null if parsing fails
+     */
+    private parseComponentRecords(
+        view: DataView,
+        startOffset: number,
+        provider: GlyphOutlineProvider,
+        depth: number
+    ): GlyphOutlineCmd[] | null {
+        if (depth > this.recursionLimit) return null;
+
+        let offset = startOffset;
+        const allCmds: GlyphOutlineCmd[] = [];
+
+        while (true) {
+            const component = this.readComponentData(view, offset);
+            if (!component) return null;
+
+            offset = this.calculateNextOffset(view, offset, component.flags);
+
+            // Prevent infinite recursion cycles
+            if (this.visited.has(component.glyphIndex)) {
+                // Skip this component to avoid cycle
+            } else {
+                this.visited.add(component.glyphIndex);
+
+                // Get component's outline
+                const componentCmds = provider.getOutline(component.glyphIndex, depth + 1);
+                if (componentCmds && componentCmds.length > 0) {
+                    // Transform the component's outline
+                    const transformedCmds = component.transform.applyToCommands(componentCmds);
+
+                    // Ensure proper moveTo at start if needed
+                    if (transformedCmds.length > 0 && transformedCmds[0].type !== "moveTo") {
+                        const firstCoord = this.findFirstCoordinate(transformedCmds);
+                        if (firstCoord) {
+                            allCmds.push({ type: "moveTo", x: firstCoord.x, y: firstCoord.y });
+                        }
+                    }
+
+                    allCmds.push(...transformedCmds);
+                }
+            }
+
+            // Check if there are more components
+            if (!component.hasMoreComponents) break;
+        }
+
+        return allCmds.length > 0 ? allCmds : null;
+    }
+
+    /**
+     * Reads a single component's data from the view.
+     * @param view - DataView containing the glyph data
+     * @param offset - Starting offset for this component
+     * @returns Component data or null if reading fails
+     */
+    private readComponentData(view: DataView, offset: number): ComponentData | null {
+        if (offset + 4 > view.byteLength) return null;
+
+        const flags = this.reader.getUint16(view, offset);
+        const glyphIndex = this.reader.getUint16(view, offset + 2);
+        let p = offset + 4;
+
+        // Read arguments (translation or matching points)
+        let arg1 = 0;
+        let arg2 = 0;
+
+        if (flags & CompositeGlyphParser.ARG_1_AND_2_ARE_WORDS) {
+            // 16-bit signed arguments
+            if (p + 4 > view.byteLength) return null;
+            arg1 = this.reader.getInt16(view, p);
+            arg2 = this.reader.getInt16(view, p + 2);
+            p += 4;
+        } else {
+            // 8-bit signed arguments
+            if (p + 2 > view.byteLength) return null;
+            arg1 = this.reader.getInt8(view, p);
+            arg2 = this.reader.getInt8(view, p + 1);
+            p += 2;
+        }
+
+        // Read transformation matrix
+        let mxx = 1, mxy = 0, myx = 0, myy = 1;
+
+        if (flags & CompositeGlyphParser.WE_HAVE_A_SCALE) {
+            // Uniform scale
+            if (p + 2 > view.byteLength) return null;
+            const scale = this.reader.getInt16(view, p) / (1 << 14);
+            mxx = scale;
+            myy = scale;
+        } else if (flags & CompositeGlyphParser.WE_HAVE_AN_X_AND_Y_SCALE) {
+            // Non-uniform scale
+            if (p + 4 > view.byteLength) return null;
+            const sx = this.reader.getInt16(view, p) / (1 << 14);
+            const sy = this.reader.getInt16(view, p + 2) / (1 << 14);
+            mxx = sx;
+            myy = sy;
+        } else if (flags & CompositeGlyphParser.WE_HAVE_A_TWO_BY_TWO) {
+            // Full 2x2 matrix
+            if (p + 8 > view.byteLength) return null;
+            mxx = this.reader.getInt16(view, p) / (1 << 14);
+            mxy = this.reader.getInt16(view, p + 2) / (1 << 14);
+            myx = this.reader.getInt16(view, p + 4) / (1 << 14);
+            myy = this.reader.getInt16(view, p + 6) / (1 << 14);
+        }
+
+        // Treat args as translation (simplified - spec allows matching points too)
+        const transform = TransformationMatrix.fromComponents(arg1, arg2, mxx, mxy, myx, myy);
+
+        return {
+            glyphIndex,
+            flags,
+            transform,
+            hasMoreComponents: !!(flags & CompositeGlyphParser.MORE_COMPONENTS)
+        };
+    }
+
+    /**
+     * Calculates the next offset after reading a component record.
+     * @param view - DataView containing the glyph data
+     * @param offset - Current offset
+     * @param flags - Component flags
+     * @returns Next offset
+     */
+    private calculateNextOffset(view: DataView, offset: number, flags: number): number {
+        let p = offset + 4; // flags + glyphIndex
+
+        // Skip arguments
+        if (flags & CompositeGlyphParser.ARG_1_AND_2_ARE_WORDS) {
+            p += 4;
+        } else {
+            p += 2;
+        }
+
+        // Skip transformation data
+        if (flags & CompositeGlyphParser.WE_HAVE_A_SCALE) {
+            p += 2;
+        } else if (flags & CompositeGlyphParser.WE_HAVE_AN_X_AND_Y_SCALE) {
+            p += 4;
+        } else if (flags & CompositeGlyphParser.WE_HAVE_A_TWO_BY_TWO) {
+            p += 8;
+        }
+
+        return p;
+    }
+
+    /**
+     * Finds the first coordinate in a list of commands.
+     * @param cmds - Array of glyph outline commands
+     * @returns First coordinate found, or null
+     */
+    private findFirstCoordinate(cmds: GlyphOutlineCmd[]): { x: number; y: number } | null {
+        for (const c of cmds) {
+            if (c.type === "moveTo" || c.type === "lineTo") {
+                return { x: c.x, y: c.y };
+            }
+            if (c.type === "quadTo") {
+                return { x: c.x, y: c.y };
+            }
+            if (c.type === "cubicTo") {
+                return { x: c.x, y: c.y };
+            }
+        }
+        return null;
+    }
+}