pagyra-js 0.0.1

package/src/pdf/font/glyph-cache.ts

@@ -0,0 +1,127 @@
+import type { BitmapMask } from "./rasterizer.js";
+import { flattenOutline, rasterizeContours } from "./rasterizer.js";
+import type { TtfFontMetrics } from "../../types/fonts.js";
+import type { GlyphOutlineCmd } from "../../types/fonts.js";
+import { globalGlyphAtlas } from "./glyph-atlas.js";
+import type { AtlasPlacement } from "./glyph-atlas.js";
+import { blurAlpha } from "./blur.js";
+
+/**
+ * Glyph mask cache with simple LRU eviction.
+ *
+ * - Keyed by (unitsPerEm + headBBox) | gid | fontSizePx | supersample
+ * - Stores BitmapMask values (alpha-only or RGBA depending on usage)
+ * - Default maxEntries set to 500 (configurable)
+ *
+ * This keeps the previous helper behavior but adds a bounded cache to limit memory.
+ */
+
+type CacheKey = string;
+
+let maxEntries = 500;
+const glyphMaskCache = new Map<CacheKey, BitmapMask>();
+// store atlas placements per cached key to allow later atlas-based rendering
+const glyphAtlasPlacements = new Map<CacheKey, AtlasPlacement | null>();
+
+export function setGlyphMaskCacheMaxEntries(n: number) {
+  if (!Number.isFinite(n) || n <= 0) return;
+  maxEntries = Math.max(1, Math.floor(n));
+  // Trim if needed
+  trimCacheIfNeeded();
+}
+
+function trimCacheIfNeeded() {
+  while (glyphMaskCache.size > maxEntries) {
+    // Evict oldest entry (Map preserves insertion order)
+    const oldestKey = glyphMaskCache.keys().next().value;
+    if (!oldestKey) break;
+    glyphMaskCache.delete(oldestKey);
+  }
+}
+
+function makeKey(metrics: TtfFontMetrics, gid: number, fontSizePx: number, supersample = 4, blurPx = 0): CacheKey {
+  const uid = `${metrics.metrics.unitsPerEm}-${(metrics.headBBox ? metrics.headBBox.join(",") : "nbb")}`;
+  // Use one-decimal precision for blur in the key to avoid unnecessary cache churn for fractional radii
+  const blurKey = Math.round(Math.max(0, blurPx || 0) * 10) / 10;
+  return `${uid}|gid:${gid}|size:${Math.round(fontSizePx)}|ss:${supersample}|blur:${blurKey}`;
+}
+
+/**
+ * Get or create an alpha mask for a glyph.
+ * Returns null if outline is not available or rasterization failed.
+ */
+export function getGlyphMask(metrics: TtfFontMetrics, gid: number, fontSizePx: number, supersample = 4, blurPx = 0): BitmapMask | null {
+  const key = makeKey(metrics, gid, fontSizePx, supersample, blurPx);
+  const cached = glyphMaskCache.get(key);
+  if (cached) {
+    // LRU: move to most-recently-used (end)
+    glyphMaskCache.delete(key);
+    glyphMaskCache.set(key, cached);
+    return cached;
+  }
+
+  if (!metrics.getGlyphOutline) return null;
+  const cmds: GlyphOutlineCmd[] | null = metrics.getGlyphOutline(gid);
+  if (!cmds || cmds.length === 0) return null;
+
+  const unitsPerEm = metrics.metrics.unitsPerEm || 1000;
+  const scale = fontSizePx / unitsPerEm;
+
+  try {
+    const { contours } = flattenOutline(cmds, scale, 0.5);
+    const mask = rasterizeContours(contours, supersample);
+    if (!mask) return null;
+
+    // If blur requested, apply blur to alpha buffer first
+    let alphaBuf = mask.data;
+    if (blurPx && blurPx > 0) {
+      alphaBuf = blurAlpha(mask.data, mask.width, mask.height, blurPx);
+    }
+
+    // Compute extra padding to reserve space in atlas for blur bleed (more conservative heuristic)
+    // Use a larger multiplier and a small safety margin to avoid clipped blurred glyphs.
+    const extraPadding = blurPx && blurPx > 0 ? Math.ceil(blurPx * 2) + 2 : 0;
+
+    // Attempt to pack into global atlas (best-effort) using alphaBuf and extra padding
+    try {
+      const placement = globalGlyphAtlas.pack(key, alphaBuf, mask.width, mask.height, extraPadding);
+      glyphAtlasPlacements.set(key, placement);
+    } catch {
+      glyphAtlasPlacements.set(key, null);
+    }
+
+    // Cache the final mask (with blurred alpha if applied)
+    // Ensure the stored buffer matches the BitmapMask type (Uint8ClampedArray)
+    const clamped = alphaBuf instanceof Uint8ClampedArray ? alphaBuf : new Uint8ClampedArray(alphaBuf);
+    const finalMask: BitmapMask = {
+      width: mask.width,
+      height: mask.height,
+      data: clamped,
+      offsetX: mask.offsetX,
+      offsetY: mask.offsetY,
+    };
+    glyphMaskCache.set(key, finalMask);
+    trimCacheIfNeeded();
+    return finalMask;
+  } catch {
+    // Defensive: don't throw; return null to let caller fallback
+    return null;
+  }
+}
+
+/** Utility to clear cache (useful for tests) */
+export function clearGlyphMaskCache(): void {
+  glyphMaskCache.clear();
+  glyphAtlasPlacements.clear();
+}
+
+/** Return atlas placement for a cached glyph key (if available) */
+export function getGlyphAtlasPlacement(metrics: TtfFontMetrics, gid: number, fontSizePx: number, supersample = 4, blurPx = 0): AtlasPlacement | null {
+  const key = makeKey(metrics, gid, fontSizePx, supersample, blurPx);
+  return glyphAtlasPlacements.get(key) ?? null;
+}
+
+/** For debugging / introspection */
+export function glyphMaskCacheStats(): { entries: number; maxEntries: number } {
+  return { entries: glyphMaskCache.size, maxEntries };
+}

package/src/pdf/font/loca-reader.ts

@@ -0,0 +1,109 @@
+import type { DataViewReader } from "./ttf-table-provider.js";
+
+/**
+ * Glyph offset range in the glyf table.
+ */
+export interface GlyphOffsetRange {
+    start: number;
+    end: number;
+}
+
+/**
+ * Reads and manages glyph offsets from the TrueType 'loca' table.
+ * 
+ * The loca (location) table maps glyph IDs to byte offsets in the glyf table.
+ * It supports two formats:
+ * - Format 0: Short offsets (uint16), actual offset = value * 2
+ * - Format 1: Long offsets (uint32)
+ */
+export class LocaTableReader {
+    private readonly offsets: number[];
+
+    /**
+     * Creates a new LocaTableReader.
+     * @param locaTable - DataView of the loca table
+     * @param indexToLocFormat - Format: 0 for short offsets, 1 for long offsets
+     * @param reader - Binary data reader
+     */
+    constructor(
+        locaTable: DataView,
+        indexToLocFormat: number,
+        reader: DataViewReader
+    ) {
+        this.offsets = [];
+
+        try {
+            if (indexToLocFormat === 0) {
+                // Short format: uint16 entries, actual offset = entry * 2
+                const entryCount = locaTable.byteLength / 2;
+                for (let i = 0; i < entryCount; i++) {
+                    const v = reader.getUint16(locaTable, i * 2);
+                    this.offsets.push(v * 2);
+                }
+            } else {
+                // Long format: uint32 entries
+                const entryCount = locaTable.byteLength / 4;
+                for (let i = 0; i < entryCount; i++) {
+                    const v = reader.getUint32(locaTable, i * 4);
+                    this.offsets.push(v);
+                }
+            }
+        } catch {
+            // Malformed loca table - leave offsets empty
+            this.offsets = [];
+        }
+    }
+
+    /**
+     * Gets the byte offset range for a glyph in the glyf table.
+     * @param glyphId - The glyph ID
+     * @returns Offset range or null if invalid glyph ID
+     */
+    getGlyphOffset(glyphId: number): GlyphOffsetRange | null {
+        if (glyphId < 0 || glyphId >= this.offsets.length - 1) {
+            return null;
+        }
+
+        const start = this.offsets[glyphId];
+        const end = this.offsets[glyphId + 1];
+
+        // Validate range
+        if (start < 0 || start > end) {
+            return null;
+        }
+
+        return { start, end };
+    }
+
+    /**
+     * Checks if a glyph is empty (has no outline data).
+     * Empty glyphs have start === end in the loca table.
+     * @param glyphId - The glyph ID
+     * @returns True if the glyph is empty, false otherwise
+     */
+    isEmptyGlyph(glyphId: number): boolean {
+        if (glyphId < 0 || glyphId >= this.offsets.length - 1) {
+            return true;
+        }
+
+        return this.offsets[glyphId] === this.offsets[glyphId + 1];
+    }
+
+    /**
+     * Gets the total number of glyphs in the font.
+     * @returns Number of glyphs
+     */
+    getGlyphCount(): number {
+        return Math.max(0, this.offsets.length - 1);
+    }
+
+    /**
+     * Validates that a glyph offset range is within the glyf table bounds.
+     * @param range - The offset range to validate
+     * @param glyfTableSize - Size of the glyf table in bytes
+     * @returns True if valid, false otherwise
+     */
+    validateRange(range: GlyphOffsetRange, glyfTableSize: number): boolean {
+        return range.start >= 0 && range.end <= glyfTableSize && range.start <= range.end;
+    }
+}

package/src/pdf/font/managers/font-resource-manager.ts

@@ -0,0 +1,73 @@
+/**
+ * Manages the lifecycle and caching of FontResource objects.
+ * 
+ * This manager is responsible for:
+ * 1. Caching resolved FontResources by family/weight/style.
+ * 2. Caching FontResources by base font name.
+ * 3. Creating and registering standard (Base14) font resources with the PDF document.
+ * 4. Generating unique resource names (aliases) for fonts.
+ */
+
+import { PdfDocument } from "../../primitives/pdf-document.js";
+import type { FontResource } from "../font-registry.js";
+
+export class FontResourceManager {
+    private readonly fontsByFamilyWeight = new Map<string, FontResource>();
+    private readonly fontsByBaseFont = new Map<string, FontResource>();
+    private aliasCounter = 1;
+
+    constructor(private readonly doc: PdfDocument) { }
+
+    /**
+     * Retrieve a cached FontResource by its unique key.
+     */
+    getCached(key: string): FontResource | undefined {
+        return this.fontsByFamilyWeight.get(key);
+    }
+
+    /**
+     * Cache a FontResource by its unique key.
+     */
+    setCached(key: string, resource: FontResource): void {
+        this.fontsByFamilyWeight.set(key, resource);
+    }
+
+    /**
+     * Ensure a FontResource exists for a given base font name.
+     * 
+     * If the resource already exists in the cache, it is returned.
+     * Otherwise, a new standard font resource is registered with the PDF document.
+     */
+    ensureBaseFontResource(baseFont: string): FontResource {
+        const existing = this.fontsByBaseFont.get(baseFont);
+        if (existing) {
+            return existing;
+        }
+
+        const ref = this.doc.registerStandardFont(baseFont);
+        const alias = `F${this.aliasCounter++}`;
+
+        const BASE14_FAMILIES = new Set([
+            "Helvetica",
+            "Helvetica-Bold",
+            "Helvetica-Oblique",
+            "Helvetica-BoldOblique",
+            "Times-Roman",
+            "Times-Bold",
+            "Times-Italic",
+            "Times-BoldItalic",
+            "Courier",
+            "Courier-Bold",
+            "Courier-Oblique",
+            "Courier-BoldOblique",
+            "Symbol",
+            "ZapfDingbats",
+        ]);
+
+        const isBase14 = BASE14_FAMILIES.has(baseFont);
+        const resource: FontResource = { baseFont, resourceName: alias, ref, isBase14 };
+
+        this.fontsByBaseFont.set(baseFont, resource);
+        return resource;
+    }
+}

package/src/pdf/font/managers/subset-resource-manager.ts

@@ -0,0 +1,164 @@
+/**
+ * Manages font subsets and their materialization into PDF objects.
+ * 
+ * This manager is responsible for:
+ * 1. Tracking glyph usage via GlyphSubsetRegistry.
+ * 2. Creating and caching SubsetFontResources.
+ * 3. Materializing font subsets (generating FontDescriptor, CIDFont, Type0 dictionaries).
+ * 4. Computing PDF font flags.
+ */
+
+import { PdfDocument, type PdfObjectRef } from "../../primitives/pdf-document.js";
+import { PdfFontRegistry as GlyphSubsetRegistry } from "../../font-subset/font-registry.js";
+import type { PdfFontSubset } from "../font-subset.js";
+import type { GlyphRun } from "../../../layout/text-run.js";
+import type { UnifiedFont } from "../../../fonts/types.js";
+import type { TtfFontMetrics } from "../../../types/fonts.js";
+import type { FontResource } from "../font-registry.js";
+import { computeWidths } from "../widths.js";
+import { log } from "../../../logging/debug.js";
+
+const DEFAULT_STEM_V = 80;
+
+export interface SubsetFontResource {
+    readonly alias: string;
+    readonly subset: PdfFontSubset;
+    readonly ref: PdfObjectRef;
+    readonly font: FontResource;
+}
+
+export class SubsetResourceManager {
+    private readonly glyphSubsetRegistry = new GlyphSubsetRegistry();
+    private readonly subsetResources = new Map<string, SubsetFontResource>();
+
+    constructor(private readonly doc: PdfDocument) { }
+
+    registerGlyphRun(glyphRun: GlyphRun): void {
+        this.glyphSubsetRegistry.registerGlyphRun(glyphRun);
+    }
+
+    ensureSubsetForGlyphRun(glyphRun: GlyphRun, font: FontResource): SubsetFontResource {
+        this.registerGlyphRun(glyphRun);
+        const handle = this.glyphSubsetRegistry.ensureSubsetFor(glyphRun.font as UnifiedFont);
+
+        const baseAlias = handle.subset.name.startsWith("/") ? handle.subset.name.slice(1) : handle.subset.name;
+        const alias = `GS${baseAlias}`;
+        const existing = this.subsetResources.get(alias);
+        const subsetForUse: PdfFontSubset = { ...handle.subset, name: `/${alias}` };
+
+        if (existing && this.subsetMatches(existing.subset, subsetForUse)) {
+            return existing;
+        }
+
+        const ref = this.materializeSubsetFont(subsetForUse, font, handle.unifiedFont);
+        const resource: SubsetFontResource = { alias, subset: subsetForUse, ref, font };
+        this.subsetResources.set(alias, resource);
+        return resource;
+    }
+
+    private subsetMatches(current: PdfFontSubset, next: PdfFontSubset): boolean {
+        if (current.glyphIds.length !== next.glyphIds.length) {
+            return false;
+        }
+        for (let i = 0; i < current.glyphIds.length; i++) {
+            if (current.glyphIds[i] !== next.glyphIds[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private materializeSubsetFont(subset: PdfFontSubset, font: FontResource, unifiedFont: UnifiedFont): PdfObjectRef {
+        const metrics = font.metrics ?? (unifiedFont.metrics as unknown as TtfFontMetrics | undefined);
+        if (!metrics) {
+            return font.ref;
+        }
+
+        const unitsPerEm = metrics.metrics.unitsPerEm;
+        const scaleTo1000 = (v: number) => Math.round((v / unitsPerEm) * 1000);
+        const fontBBox: [number, number, number, number] = metrics.headBBox
+            ? [
+                scaleTo1000(metrics.headBBox[0]),
+                scaleTo1000(metrics.headBBox[1]),
+                scaleTo1000(metrics.headBBox[2]),
+                scaleTo1000(metrics.headBBox[3]),
+            ]
+            : [-1000, -1000, 1000, 1000];
+
+        const fontFile = font.embedded?.subset ?? subset.fontFile;
+        if (!fontFile || fontFile.length === 0) {
+            log("font", "warn", "missing-font-file-for-subset", { baseFont: font.baseFont, alias: subset.name });
+            return font.ref;
+        }
+
+        const { DW, W } = computeWidths(metrics);
+        const subsetTag = subset.name.startsWith("/") ? subset.name.slice(1) : subset.name;
+        const subsetBaseName = `${subsetTag}+${font.baseFont}`;
+
+        const fontFileRef = this.doc.registerStream(fontFile, {});
+        const fontDescriptor = {
+            Type: "/FontDescriptor",
+            FontName: `/${subsetBaseName}`,
+            Flags: this.computePdfFlags(font, unifiedFont),
+            FontBBox: fontBBox,
+            ItalicAngle: unifiedFont.css?.style === "italic" ? -12 : 0,
+            Ascent: scaleTo1000(metrics.metrics.ascender),
+            Descent: scaleTo1000(metrics.metrics.descender),
+            CapHeight: scaleTo1000(metrics.metrics.capHeight ?? metrics.metrics.ascender),
+            XHeight: scaleTo1000(metrics.metrics.xHeight ?? metrics.metrics.ascender / 2),
+            StemV: DEFAULT_STEM_V,
+            FontFile2: fontFileRef,
+        };
+        const fontDescriptorRef = this.doc.register(fontDescriptor);
+
+        const cidFontDict = {
+            Type: "/Font",
+            Subtype: "/CIDFontType2",
+            BaseFont: `/${subsetBaseName}`,
+            CIDSystemInfo: {
+                Registry: "(Adobe)",
+                Ordering: "(Identity)",
+                Supplement: 0,
+            },
+            FontDescriptor: fontDescriptorRef,
+            DW,
+            W,
+            CIDToGIDMap: "/Identity",
+        };
+        const cidFontRef = this.doc.register(cidFontDict);
+
+        const toUnicodeRef = this.doc.registerStream(new TextEncoder().encode(subset.toUnicodeCMap), {});
+        const type0Font = {
+            Type: "/Font",
+            Subtype: "/Type0",
+            BaseFont: `/${subsetBaseName}-Identity-H`,
+            Encoding: "/Identity-H",
+            DescendantFonts: [cidFontRef],
+            ToUnicode: toUnicodeRef,
+        };
+
+        return this.doc.register(type0Font);
+    }
+
+    private computePdfFlags(font: FontResource, unifiedFont: UnifiedFont): number {
+        const family = unifiedFont.css?.family?.toLowerCase() ?? font.baseFont.toLowerCase();
+        const style = unifiedFont.css?.style ?? "";
+        const isItalic = /italic|oblique/i.test(style) || /italic|oblique/i.test(font.baseFont);
+        const isSerif = family.includes("serif");
+        const isSymbol = family.includes("symbol") || family.includes("dingbat") || font.baseFont.toLowerCase().includes("symbol");
+
+        let flags = 0;
+        if (isSymbol) {
+            flags |= 1 << 2;
+        } else {
+            flags |= 1 << 5;
+        }
+        if (isSerif) {
+            flags |= 1 << 1;
+        }
+        if (isItalic) {
+            flags |= 1 << 6;
+        }
+        return flags;
+    }
+}