pagyra-js 0.0.1

package/src/pdf/font/embedder.ts

@@ -0,0 +1,395 @@
+import type { PdfObjectRef, PdfDocument } from "../primitives/pdf-document.js";
+import { parseTtfBuffer } from "./ttf-lite.js";
+import type { FontFaceDef, FontConfig, TtfFontMetrics } from "../../types/fonts.js";
+import { log } from "../../logging/debug.js";
+import { normalizeFontWeight } from "../../css/font-weight.js";
+import { detectFontFormat } from "../../fonts/detector.js";
+import { reconstructTtf } from "../../fonts/utils/ttf-reconstructor.js";
+import { computeWidths } from "./widths.js";
+import { createToUnicodeCMapText } from "./to-unicode.js";
+import { BASE_FONT_ALIASES, GENERIC_FAMILIES } from "./font-config.js";
+
+export { computeWidths } from "./widths.js";
+export { createToUnicodeCMapText } from "./to-unicode.js";
+
+const TYPICAL_STEM_V = 80;
+
+export interface EmbeddedFont {
+  readonly resourceName: string;
+  readonly ref: PdfObjectRef;
+  readonly baseFont: string;
+  readonly metrics: TtfFontMetrics;
+  readonly subset: Uint8Array;
+}
+
+interface FontDescriptor {
+  readonly Type: "/FontDescriptor";
+  readonly FontName: string;
+  readonly Flags: number;
+  readonly FontBBox: readonly [number, number, number, number];
+  readonly ItalicAngle: number;
+  readonly Ascent: number;
+  readonly Descent: number;
+  readonly CapHeight: number;
+  readonly XHeight: number;
+  readonly StemV: number;
+  readonly FontFile2: PdfObjectRef;
+}
+
+interface FontDictionary {
+  readonly Type: "/Font";
+  readonly Subtype: "/Type0";
+  readonly BaseFont: string;
+  readonly Encoding: "/Identity-H";
+  readonly DescendantFonts: readonly [PdfObjectRef];
+  readonly ToUnicode: PdfObjectRef;
+}
+
+interface CIDFontDictionary {
+  readonly Type: "/Font";
+  readonly Subtype: "/CIDFontType2";
+  readonly BaseFont: string;
+  readonly CIDSystemInfo: {
+    readonly Registry: string; // emitted as literal strings "(Adobe)"
+    readonly Ordering: string; // emitted as literal strings "(Identity)"
+    readonly Supplement: 0;
+  };
+  readonly FontDescriptor: PdfObjectRef;
+  readonly DW?: number;
+  readonly W: readonly (number | readonly number[])[];
+  readonly CIDToGIDMap: PdfObjectRef | string;
+}
+
+export class FontEmbedder {
+  private embeddedFonts = new Map<string, EmbeddedFont>();
+  private faceMetrics = new Map<string, TtfFontMetrics>();
+
+  constructor(private readonly config: FontConfig, private readonly doc: PdfDocument) { }
+
+  async initialize(): Promise<void> {
+    for (const face of this.config.fontFaceDefs) {
+      if (!face.data) {
+        log("font", "error", `Missing data for font ${face.name}`);
+        continue;
+      }
+      try {
+        let fontData = new Uint8Array(face.data);
+        const format = detectFontFormat(fontData);
+        let ttfBuffer: ArrayBuffer;
+        if (format === "woff") {
+          const { decodeWoff } = await import("../../fonts/woff/decoder.js");
+          const decoded = await decodeWoff(fontData);
+          ttfBuffer = reconstructTtf(decoded);
+          fontData = new Uint8Array(ttfBuffer);
+          (face as any).data = ttfBuffer;
+        } else if (format === "woff2") {
+          const { decodeWoff2 } = await import("../../fonts/woff2/decoder.js");
+          const decoded = await decodeWoff2(fontData);
+          // Copy into a fresh ArrayBuffer to avoid SharedArrayBuffer unions
+          const ttfCopy = decoded.ttfBuffer.slice();
+          ttfBuffer = ttfCopy.buffer;
+          fontData = new Uint8Array(ttfBuffer);
+          (face as any).data = ttfBuffer;
+        } else {
+          ttfBuffer = face.data!;
+        }
+
+        const metrics = parseTtfBuffer(ttfBuffer);
+        this.faceMetrics.set(face.name, metrics);
+      } catch (error) {
+        log("font", "error", `Failed to load font ${face.name}`, { error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+
+  ensureFont(familyStack: string[], fontWeight?: number, fontStyle?: string): EmbeddedFont | null {
+    const targetWeight = normalizeFontWeight(fontWeight);
+    const wantsItalic = isItalic(fontStyle);
+
+    for (const family of familyStack) {
+      const normalizedFamily = family.toLowerCase().trim();
+      const candidates = this.config.fontFaceDefs.filter((f) => {
+        return (f.family || "").toLowerCase().trim() === normalizedFamily;
+      });
+
+      if (candidates.length === 0) {
+        continue;
+      }
+
+      const face = pickFaceByWeight(candidates, targetWeight, wantsItalic);
+      if (!face) {
+        continue;
+      }
+
+      // Use normalized face name as key to avoid accidental mismatches due to spacing/case
+      const faceKey = (face.name || "").toLowerCase().trim();
+      const existing = this.embeddedFonts.get(face.name) ?? this.embeddedFonts.get(faceKey);
+      if (existing) return existing;
+
+      const embedded = this.embedFont(face);
+      if (embedded) {
+        // store with both canonical and normalized keys for resilient lookups
+        this.embeddedFonts.set(face.name, embedded);
+        this.embeddedFonts.set(faceKey, embedded);
+        return embedded;
+      }
+    }
+
+    return null;
+  }
+
+  private embedFont(face: FontFaceDef): EmbeddedFont | null {
+    const metrics = this.faceMetrics.get(face.name);
+    if (!metrics) return null;
+    const unitsPerEm = metrics.metrics.unitsPerEm;
+    const scaleTo1000 = (v: number) => Math.round((v / unitsPerEm) * 1000);
+
+    let fontBBox: [number, number, number, number];
+    if (metrics.headBBox) {
+      const hb = metrics.headBBox;
+      fontBBox = [scaleTo1000(hb[0]), scaleTo1000(hb[1]), scaleTo1000(hb[2]), scaleTo1000(hb[3])];
+    } else {
+      // Fallback if headBBox is missing
+      fontBBox = [-1000, -1000, 1000, 1000];
+    }
+
+    // Register the font file stream
+    // We need the full font data here. In the initialize method we updated face.data
+    // but here we need to access it.
+    // Since we can't easily change the interface, we'll assume face.data is the source.
+    // If it was converted to TTF in initialize, face.data (casted) holds the TTF buffer.
+    const fullFontData = new Uint8Array(face.data!);
+    // FontFile2 streams require only /Length (PdfDocument adds it); avoid Type1-specific Length1 headers.
+    const fontFileRef = this.doc.registerStream(fullFontData, {});
+
+    const fontDescriptor: FontDescriptor = {
+      Type: "/FontDescriptor",
+      FontName: `/${face.name}`,
+      Flags: computePdfFlagsFromFace(face),
+      FontBBox: fontBBox,
+      ItalicAngle: face.style === "italic" ? -12 : 0,
+      Ascent: scaleTo1000(metrics.metrics.ascender),
+      Descent: scaleTo1000(metrics.metrics.descender),
+      CapHeight: scaleTo1000(metrics.metrics.capHeight),
+      XHeight: scaleTo1000(metrics.metrics.xHeight),
+      StemV: TYPICAL_STEM_V,
+      FontFile2: fontFileRef
+    };
+
+    const fontDescriptorRef = this.doc.register(fontDescriptor);
+
+    // Compute DW and compressed W
+    const { DW, W } = computeWidths(metrics);
+
+    // Create CID font dictionary (include DW)
+    // CID fonts must declare string-valued CIDSystemInfo entries per PDF spec.
+    const cidFontDict: CIDFontDictionary = {
+      Type: "/Font",
+      Subtype: "/CIDFontType2",
+      BaseFont: `/${face.name}`,
+      CIDSystemInfo: {
+        Registry: "(Adobe)",
+        Ordering: "(Identity)",
+        Supplement: 0
+      },
+      FontDescriptor: fontDescriptorRef,
+      DW,
+      W,
+      // Rely on built-in Identity CIDToGID mapping to keep font dictionaries simple/compatible.
+      CIDToGIDMap: "/Identity"
+    };
+
+    const cidFontRef = this.doc.register(cidFontDict);
+
+    // Create Unicode mapping (ToUnicode CMap)
+    const toUnicodeRef = this.createToUnicodeCMap(metrics);
+
+    // Create Type0 font dictionary
+    // Per PDF spec, Type0 BaseFont should include the CMap suffix (e.g. "-Identity-H")
+    // to make the composite font name unambiguous for parsers/renderers.
+    const type0Font: FontDictionary = {
+      Type: "/Font",
+      Subtype: "/Type0",
+      BaseFont: `/${face.name}-Identity-H`,
+      Encoding: "/Identity-H",
+      DescendantFonts: [cidFontRef],
+      ToUnicode: toUnicodeRef
+    };
+
+    const fontRef = this.doc.register(type0Font);
+
+    return {
+      resourceName: `F${this.embeddedFonts.size + 1}`,
+      ref: fontRef,
+      baseFont: face.name,
+      metrics,
+      subset: fullFontData
+    };
+  }
+
+
+
+  private createToUnicodeCMap(metrics: TtfFontMetrics, _uniqueUnicodes: number[] = []): PdfObjectRef {
+    // Build inverse mapping gid -> unicode (pick first unicode when multiple map to same gid)
+    const unicodeMap = metrics.cmap["unicodeMap"] as Map<number, number>;
+    log("font", "debug", "createToUnicodeCMap - unicodeMap size", { size: unicodeMap.size });
+
+    // Sample first few entries for debugging
+    const samples: Array<{ unicode: number, char: string, gid: number }> = [];
+    let count = 0;
+    for (const [unicode, gid] of unicodeMap.entries()) {
+      if (count < 10) {
+        samples.push({ unicode, char: String.fromCodePoint(unicode), gid });
+      }
+      count++;
+    }
+    log("font", "debug", "createToUnicodeCMap - sample entries", { samples });
+
+    const gidToUni = new Map<number, number>();
+    for (const [unicode, gid] of unicodeMap.entries()) {
+      if (!gidToUni.has(gid)) gidToUni.set(gid, unicode);
+    }
+
+    // Debug: log sample gid->unicode mappings
+    const gidSamples: Array<{ gid: number, unicode: number, char: string }> = [];
+    let gidCount = 0;
+    for (const [gid, unicode] of gidToUni.entries()) {
+      if (gidCount < 20) {
+        gidSamples.push({ gid, unicode, char: String.fromCodePoint(unicode) });
+      }
+      gidCount++;
+    }
+    log("font", "debug", "createToUnicodeCMap - gid->unicode sample", { samples: gidSamples });
+
+    const entries = Array.from(gidToUni.entries())
+      .map(([gid, unicode]) => ({ gid, unicode }))
+      .sort((a, b) => a.gid - b.gid);
+
+    const cmapText = createToUnicodeCMapText(entries);
+    return this.doc.registerStream(new TextEncoder().encode(cmapText), {});
+  }
+
+
+  /**
+   * Return parsed TTF metrics for a loaded face by name or family, or null if not available.
+   * Exposed to allow rendering code to access outlines/metrics for embedding masks.
+   * 
+   * The lookup tries:
+   * 1. Exact match by face name (e.g., "Tinos-Bold")
+   * 2. Match by family name (e.g., "Tinos") with weight/style matching
+   * 3. Case-insensitive match by family name
+   * 4. If input contains comma-separated font stack (e.g., "Tinos, serif"), tries each font
+   * 5. Uses BASE_FONT_ALIASES to resolve CSS font names to embedded fonts (e.g., "Times New Roman" → "Tinos")
+   * 
+   * @param faceName - Font family name or font stack
+   * @param fontWeight - Optional font weight (100-900), defaults to 400
+   * @param fontStyle - Optional font style ('normal' | 'italic' | 'oblique'), defaults to 'normal'
+   */
+  public getMetrics(faceName: string, fontWeight: number = 400, fontStyle: string = "normal"): TtfFontMetrics | null {
+    // Try exact match first
+    const exact = this.faceMetrics.get(faceName);
+    if (exact) return exact;
+
+    const wantsItalic = fontStyle === "italic" || fontStyle === "oblique";
+
+    // Handle font-family stacks like "'Times New Roman', Times, serif"
+    const fontStack = faceName.split(",").map(f => f.trim().replace(/^["']|["']$/g, ""));
+    
+    for (const fontName of fontStack) {
+      const normalizedQuery = fontName.toLowerCase().trim();
+      
+      // Try exact match with this font name
+      const exactMatch = this.faceMetrics.get(fontName);
+      if (exactMatch) return exactMatch;
+      
+      // Check if this is an alias that maps to an embedded font
+      const aliasedFont = BASE_FONT_ALIASES.get(normalizedQuery) || GENERIC_FAMILIES.get(normalizedQuery);
+      const targetFamily = aliasedFont ? aliasedFont.toLowerCase() : normalizedQuery;
+      
+      // Collect all faces matching the family
+      const matchingFaces: FontFaceDef[] = [];
+      for (const face of this.config.fontFaceDefs) {
+        const faceFamily = (face.family || "").toLowerCase().trim();
+        if (faceFamily === targetFamily) {
+          matchingFaces.push(face);
+        }
+      }
+      
+      // Pick the best face by weight and style
+      if (matchingFaces.length > 0) {
+        const bestFace = pickFaceByWeight(matchingFaces, fontWeight, wantsItalic);
+        if (bestFace) {
+          const metrics = this.faceMetrics.get(bestFace.name);
+          if (metrics) return metrics;
+        }
+      }
+    }
+
+    return null;
+  }
+}
+
+function pickFaceByWeight(faces: FontFaceDef[], requestedWeight: number, wantsItalic: boolean): FontFaceDef | null {
+  if (faces.length === 0) {
+    return null;
+  }
+  // Prefer faces that match the requested style; if none do, fall back to any style.
+  const styleFiltered = faces.filter((face) => isItalic(face.style) === wantsItalic);
+  const pool = styleFiltered.length > 0 ? styleFiltered : faces;
+
+  let bestFace = pool[0];
+  let bestDiff = Math.abs(normalizeFontWeight(bestFace.weight) - requestedWeight);
+  for (const face of pool) {
+    const normalized = normalizeFontWeight(face.weight);
+    const diff = Math.abs(normalized - requestedWeight);
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      bestFace = face;
+    }
+  }
+  return bestFace;
+}
+
+function isItalic(style: string | undefined): boolean {
+  if (!style) return false;
+  const s = style.toLowerCase();
+  return s === "italic" || s === "oblique";
+}
+
+// Compute PDF Flags based on font family/style heuristics.
+// See AGENTS.md notes for bits: Symbolic vs Nonsymbolic, Serif, Italic, etc.
+function computePdfFlagsFromFace(face: FontFaceDef): number {
+  let flags = 0;
+  const family = (face.family || "").toLowerCase().trim();
+  const name = (face.name || "").toLowerCase().trim();
+  const style = (face.style || "").toLowerCase();
+
+  const isItalic = /italic|oblique/i.test(style);
+  const isSerif = /serif/i.test(family) || /serif/i.test(name);
+  const isSymbol = /symbol|dingbat|dingbats|zapfdingbats/i.test(family) || /symbol|dingbat|dingbats/i.test(name);
+
+  if (isSymbol) flags |= 1 << 2; // Symbolic
+  else flags |= 1 << 5; // Nonsymbolic
+
+  if (isSerif) flags |= 1 << 1; // Serif
+  if (isItalic) flags |= 1 << 6; // Italic
+
+  return flags;
+}
+
+export async function getEmbeddedFont(name: "NotoSans-Regular" | "DejaVuSans", doc: PdfDocument, config: FontConfig): Promise<EmbeddedFont | null> {
+  const embedder = new FontEmbedder(config, doc);
+  const face = config.fontFaceDefs.find(f => f.name === name);
+  if (!face) return null;
+
+  const existing = embedder['embeddedFonts'].get(name);
+  if (existing) return existing;
+
+  // @ts-ignore: TypeScript complains about private method, but this is intentional for testing
+  const embedded = embedder['embedFont'](face);
+  if (embedded) {
+    embedder['embeddedFonts'].set(name, embedded);
+    return embedded;
+  }
+  return null;
+}

package/src/pdf/font/font-config.ts

@@ -0,0 +1,190 @@
+/**
+ * Font configuration and mapping data for PDF font resolution.
+ * 
+ * This module centralizes all font alias mappings, generic family mappings,
+ * and Base14 font variant configurations used throughout the font registry system.
+ */
+
+/**
+ * Base14 variant types supported by PDF standard fonts.
+ */
+export type Base14Variant = "normal" | "italic" | "bold" | "boldItalic";
+
+/**
+ * Base14 font family names.
+ */
+export type Base14Family = "Helvetica" | "Times-Roman" | "Courier";
+
+/**
+ * Variant configuration for a Base14 font family.
+ */
+export interface Base14Variants {
+    normal: string;
+    italic: string;
+    bold: string;
+    boldItalic: string;
+}
+
+/**
+ * Maps common font family names to embedded font aliases.
+ * 
+ * This enables fallback to built-in fonts when requested fonts aren't available.
+ * For example, "Arial" → "Arimo", "Times New Roman" → "Tinos"
+ */
+export const BASE_FONT_ALIASES: ReadonlyMap<string, string> = new Map([
+    // Sans/UI families
+    ["helvetica", "Lato"],
+    ["arial", "Arimo"],
+    ["arial black", "Arimo"],
+    ["segoe ui", "Roboto"],
+    ["open sans", "Lato"],
+    ["calibri", "Roboto"],
+    ["roboto", "Roboto"],
+    ["arimo", "Arimo"],
+    ["lato", "Lato"],
+    ["noto sans", "Noto Sans"],
+    ["notosans-regular", "Noto Sans"],
+    ["dejavu sans", "DejaVu Sans"],
+
+    // Serif
+    ["times", "Tinos"],
+    ["times-roman", "Tinos"],
+    ["times new roman", "Tinos"],
+    ["georgia", "Tinos"],
+    ["garamond", "Tinos"],
+    ["baskerville", "Tinos"],
+
+    // Mono
+    ["courier", "Fira Code"],
+    ["courier new", "Fira Code"],
+    ["consolas", "Fira Code"],
+    ["menlo", "Fira Code"],
+    ["monaco", "Fira Code"],
+    ["source code pro", "Fira Code"],
+
+    // Decorative / cursive
+    ["comic sans", "Caveat"],
+    ["comic sans ms", "Caveat"],
+    ["fantasy", "Cinzel Decorative"],
+    ["cursive", "Caveat"],
+
+    // Emoji / math / symbols
+    ["noto emoji", "Noto Emoji"],
+    ["noto color emoji", "Noto Emoji"],
+    ["segoe ui emoji", "Noto Emoji"],
+    ["apple color emoji", "Noto Emoji"],
+    ["twemoji", "Noto Emoji"],
+    ["cambria math", "STIX Two Math"],
+    ["stix two math", "STIX Two Math"],
+    ["math", "STIX Two Math"],
+    ["symbol", "Symbol"],
+    ["zapfdingbats", "ZapfDingbats"],
+]);
+
+/**
+ * Maps CSS generic font families to specific embedded fonts.
+ * 
+ * Used when no specific font family is requested or as a final fallback.
+ */
+export const GENERIC_FAMILIES: ReadonlyMap<string, string> = new Map([
+    ["serif", "Tinos"],
+    ["sans-serif", "Lato"],
+    ["monospace", "Fira Code"],
+    ["system-ui", "Roboto"],
+    ["cursive", "Caveat"],
+    ["fantasy", "Cinzel Decorative"],
+    ["emoji", "Noto Emoji"],
+    ["math", "STIX Two Math"],
+]);
+
+/**
+ * Maps common font family names to Base14 standard font fallbacks.
+ * 
+ * Used when font embedding is disabled or not available.
+ */
+export const BASE14_FALLBACKS: ReadonlyMap<string, string> = new Map([
+    ["times", "Times-Roman"],
+    ["times-roman", "Times-Roman"],
+    ["times new roman", "Times-Roman"],
+    ["georgia", "Times-Roman"],
+    ["garamond", "Times-Roman"],
+    ["baskerville", "Times-Roman"],
+    ["serif", "Times-Roman"],
+    ["helvetica", "Helvetica"],
+    ["arial", "Helvetica"],
+    ["segoe ui", "Helvetica"],
+    ["open sans", "Helvetica"],
+    ["calibri", "Helvetica"],
+    ["sans-serif", "Helvetica"],
+    ["system-ui", "Helvetica"],
+    ["courier", "Courier"],
+    ["courier new", "Courier"],
+    ["monospace", "Courier"],
+]);
+
+/**
+ * Base14 font family variants mapping.
+ * 
+ * Defines the standard variant names for each Base14 font family.
+ * Used to apply weight/style transformations to Base14 fonts.
+ */
+export const BASE14_FAMILY_VARIANTS: Record<Base14Family, Base14Variants> = {
+    "Helvetica": {
+        normal: "Helvetica",
+        italic: "Helvetica-Oblique",
+        bold: "Helvetica-Bold",
+        boldItalic: "Helvetica-BoldOblique",
+    },
+    "Times-Roman": {
+        normal: "Times-Roman",
+        italic: "Times-Italic",
+        bold: "Times-Bold",
+        boldItalic: "Times-BoldItalic",
+    },
+    "Courier": {
+        normal: "Courier",
+        italic: "Courier-Oblique",
+        bold: "Courier-Bold",
+        boldItalic: "Courier-BoldOblique",
+    },
+} as const;
+
+/**
+ * Reverse lookup map: Base14 variant name → family + variant type.
+ * 
+ * Built automatically from BASE14_FAMILY_VARIANTS.
+ * Used to detect which Base14 family a font belongs to.
+ */
+export const BASE14_VARIANT_LOOKUP: ReadonlyMap<string, { family: Base14Family; variant: Base14Variant }> = (() => {
+    const lookup = new Map<string, { family: Base14Family; variant: Base14Variant }>();
+
+    for (const [family, variants] of Object.entries(BASE14_FAMILY_VARIANTS) as Array<[Base14Family, Record<Base14Variant, string>]>) {
+        for (const [variant, name] of Object.entries(variants) as Array<[Base14Variant, string]>) {
+            lookup.set(name.toLowerCase(), { family, variant });
+        }
+    }
+
+    return lookup;
+})();
+
+/**
+ * Detect the Base14 family for a given font name.
+ * 
+ * @param baseFont - Font name to check
+ * @returns Base14 family name if found, null otherwise
+ */
+export function detectBase14Family(baseFont: string): Base14Family | null {
+    const entry = BASE14_VARIANT_LOOKUP.get(baseFont.toLowerCase());
+    return entry ? entry.family : null;
+}
+
+/**
+ * Classify the variant type of a Base14 font.
+ * 
+ * @param baseFont - Font name to check
+ * @returns Variant type (normal, italic, bold, boldItalic)
+ */
+export function classifyBase14Variant(baseFont: string): Base14Variant {
+    const entry = BASE14_VARIANT_LOOKUP.get(baseFont.toLowerCase());
+    return entry ? entry.variant : "normal";
+}