pagyra-js 0.0.1

package/src/pdf/primitives/pdf-resource-registries.ts

@@ -0,0 +1,255 @@
+import type {
+    PdfObjectRef,
+    PdfFontResource,
+    PdfImageResource,
+    PdfExtGStateResource,
+    PdfShadingResource,
+    PdfPatternResource,
+    PdfRegisteredObject,
+    PdfRegisteredStream,
+} from "./pdf-types.js";
+
+/**
+ * Registry for standard Type1 PDF fonts.
+ * Handles font registration with deduplication by base font name.
+ */
+export class FontRegistry {
+    private readonly fonts = new Map<string, PdfFontResource>();
+
+    register(baseFont: string): PdfObjectRef {
+        const existing = this.fonts.get(baseFont);
+        if (existing) {
+            return existing.objectRef!;
+        }
+        const objectRef: PdfObjectRef = { objectNumber: -1 };
+        this.fonts.set(baseFont, { name: baseFont, baseFont, objectRef });
+        return objectRef;
+    }
+
+    getAll(): PdfFontResource[] {
+        return Array.from(this.fonts.values());
+    }
+}
+
+/**
+ * Registry for image resources.
+ * Handles image registration with deduplication and PNG alpha channel separation.
+ */
+export class ImageRegistry {
+    private readonly images: PdfImageResource[] = [];
+
+    register(image: {
+        src: string;
+        width: number;
+        height: number;
+        format: "jpeg" | "png" | "gif" | "webp";
+        channels: number;
+        bitsPerComponent: number;
+        data: Uint8Array;
+    }): PdfObjectRef {
+        // Deduplicate by src when provided
+        if (image.src) {
+            for (const existing of this.images) {
+                if (
+                    existing.src === image.src &&
+                    existing.width === image.width &&
+                    existing.height === image.height
+                ) {
+                    return existing.ref;
+                }
+            }
+        }
+
+        // Handle PNG with alpha channel - split into RGB + SMask
+        if (image.format === "png" && image.channels === 4) {
+            return this.registerPngWithAlpha(image);
+        }
+
+        // Regular image registration
+        const colorSpace =
+            image.channels === 1
+                ? "DeviceGray"
+                : image.channels === 3
+                    ? "DeviceRGB"
+                    : "DeviceRGB";
+        const filter = image.format === "jpeg" ? "DCTDecode" : undefined;
+        const ref: PdfObjectRef = { objectNumber: -1 };
+
+        this.images.push({
+            ref,
+            src: image.src,
+            width: image.width,
+            height: image.height,
+            colorSpace,
+            bitsPerComponent: image.bitsPerComponent,
+            filter,
+            data: image.data.slice(),
+            sMask: undefined,
+        });
+
+        return ref;
+    }
+
+    private registerPngWithAlpha(image: {
+        src: string;
+        width: number;
+        height: number;
+        data: Uint8Array;
+    }): PdfObjectRef {
+        const rgbData = new Uint8Array(image.width * image.height * 3);
+        const alphaData = new Uint8Array(image.width * image.height);
+
+        for (let i = 0, j = 0, k = 0; i < image.data.length; i += 4, j += 3, k++) {
+            rgbData[j] = image.data[i];
+            rgbData[j + 1] = image.data[i + 1];
+            rgbData[j + 2] = image.data[i + 2];
+            alphaData[k] = image.data[i + 3];
+        }
+
+        // Register alpha mask first
+        const sMaskRef: PdfObjectRef = { objectNumber: -1 };
+        this.images.push({
+            ref: sMaskRef,
+            src: image.src,
+            width: image.width,
+            height: image.height,
+            colorSpace: "DeviceGray",
+            bitsPerComponent: 8,
+            data: alphaData,
+            sMask: undefined,
+        });
+
+        // Register RGB image with reference to alpha mask
+        const ref: PdfObjectRef = { objectNumber: -1 };
+        this.images.push({
+            ref,
+            src: image.src,
+            width: image.width,
+            height: image.height,
+            colorSpace: "DeviceRGB",
+            bitsPerComponent: 8,
+            data: rgbData,
+            sMask: sMaskRef,
+        });
+
+        return ref;
+    }
+
+    getAll(): PdfImageResource[] {
+        return this.images;
+    }
+}
+
+/**
+ * Registry for ExtGState (graphics state) resources.
+ * Handles registration with deduplication by alpha value.
+ */
+export class ExtGStateRegistry {
+    private readonly states = new Map<string, PdfExtGStateResource>();
+
+    register(alpha: number): PdfObjectRef {
+        const normalized = this.clampAlpha(alpha);
+        const key = normalized.toFixed(4);
+        const existing = this.states.get(key);
+
+        if (existing) {
+            return existing.ref;
+        }
+
+        const ref: PdfObjectRef = { objectNumber: -1 };
+        this.states.set(key, { ref, alpha: normalized });
+        return ref;
+    }
+
+    private clampAlpha(value: number): number {
+        if (!Number.isFinite(value)) return 1;
+        if (value <= 0) return 0;
+        if (value >= 1) return 1;
+        return value;
+    }
+
+    getAll(): PdfExtGStateResource[] {
+        return Array.from(this.states.values());
+    }
+}
+
+/**
+ * Registry for shading resources.
+ * Handles registration with deduplication by name.
+ */
+export class ShadingRegistry {
+    private readonly shadings = new Map<string, PdfShadingResource>();
+
+    register(name: string, dict: string): PdfObjectRef {
+        const existing = this.shadings.get(name);
+        if (existing) {
+            return existing.ref;
+        }
+
+        const ref: PdfObjectRef = { objectNumber: -1 };
+        this.shadings.set(name, { ref, dict });
+        return ref;
+    }
+
+    getAll(): PdfShadingResource[] {
+        return Array.from(this.shadings.values());
+    }
+}
+
+/**
+ * Registry for pattern resources.
+ * Handles registration with deduplication by name.
+ */
+export class PatternRegistry {
+    private readonly patterns = new Map<string, PdfPatternResource>();
+
+    register(name: string, dict: string): PdfObjectRef {
+        const existing = this.patterns.get(name);
+        if (existing) {
+            return existing.ref;
+        }
+
+        const ref: PdfObjectRef = { objectNumber: -1 };
+        this.patterns.set(name, { ref, dict });
+        return ref;
+    }
+
+    getAll(): PdfPatternResource[] {
+        return Array.from(this.patterns.values());
+    }
+}
+
+/**
+ * Generic registry for custom PDF objects.
+ * Stores arbitrary values to be serialized later.
+ */
+export class ObjectRegistry {
+    private readonly objects: PdfRegisteredObject[] = [];
+
+    register(value: string | Record<string, unknown> | readonly unknown[] | object): PdfObjectRef {
+        const ref = { objectNumber: -1 };
+        this.objects.push({ ref, value });
+        return ref;
+    }
+
+    getAll(): PdfRegisteredObject[] {
+        return this.objects;
+    }
+}
+
+/**
+ * Registry for stream objects with custom headers.
+ */
+export class StreamRegistry {
+    private readonly streams: PdfRegisteredStream[] = [];
+
+    register(data: Uint8Array, headers: Record<string, string> = {}): PdfObjectRef {
+        const ref = { objectNumber: -1 };
+        this.streams.push({ ref, data, headers });
+        return ref;
+    }
+
+    getAll(): PdfRegisteredStream[] {
+        return this.streams;
+    }
+}

package/src/pdf/primitives/pdf-serializers.ts

@@ -0,0 +1,194 @@
+import type { PdfObjectRef } from "./pdf-types.js";
+import type { PdfMetadata } from "../types.js";
+import { encodeAndEscapePdfText } from "../utils/encoding.js";
+import { log } from "../../logging/debug.js";
+import { concatBytes, encodeBinaryString } from "./pdf-bytes.js";
+
+/**
+ * Pure serialization functions for PDF objects and values.
+ * These functions follow the Single Responsibility Principle and are
+ * easy to test in isolation.
+ */
+
+/**
+ * Serializes a JavaScript value to PDF syntax.
+ */
+export function serializeValue(value: unknown): string {
+    if (typeof value === "number") return formatNumber(value);
+    if (typeof value === "string") return value;
+    if (Array.isArray(value))
+        return `[${value.map((v) => serializeValue(v)).join(" ")}]`;
+    if (typeof value === "object" && value !== null && "objectNumber" in value)
+        return `${(value as { objectNumber: number }).objectNumber} 0 R`;
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value).map(
+            ([k, v]) => `/${k} ${serializeValue(v)}`
+        );
+        return `<< ${entries.join(" ")} >>`;
+    }
+    return "null";
+}
+
+/**
+ * Serializes a Type1 font dictionary.
+ */
+export function serializeType1Font(baseFont: string): string {
+    const body = [
+        "<<",
+        "/Type /Font",
+        "/Subtype /Type1",
+        `/BaseFont /${sanitizeName(baseFont)}`,
+    ];
+    if (!usesSymbolEncoding(baseFont)) {
+        body.push("/Encoding /WinAnsiEncoding");
+    }
+    body.push(">>");
+    return body.join("\n");
+}
+
+/**
+ * Serializes an ExtGState dictionary with alpha values.
+ */
+export function serializeExtGState(alpha: number): string {
+    const safeAlpha = clampUnitAlpha(alpha);
+    const formatted = formatNumber(safeAlpha);
+    return ["<<", "/Type /ExtGState", `/ca ${formatted}`, `/CA ${formatted}`, ">>"].join("\n");
+}
+
+/**
+ * Creates a PDF stream object with the given content and headers.
+ */
+export function serializeStream(
+    content: string | Uint8Array,
+    extraEntries: string[] = []
+): Uint8Array {
+    const encoded = typeof content === "string" ? encodeBinaryString(content) : new Uint8Array(content);
+    const entries = [`/Length ${encoded.length}`, ...extraEntries].join(" ");
+    const header = encodeBinaryString(`<< ${entries} >>\nstream\n`);
+    const footer = encodeBinaryString("\nendstream");
+    return concatBytes([header, encoded, footer]);
+}
+
+/**
+ * Serializes PDF metadata (Info dictionary).
+ */
+export function serializeInfo(meta: PdfMetadata): string {
+    const entries: string[] = [];
+
+    if (meta.title) {
+        const encoded = encodeAndEscapePdfText(meta.title);
+        log("pdf", "debug", "serializing metadata title", {
+            title: meta.title.slice(0, 50),
+            encoded,
+        });
+        entries.push(`/Title (${encoded})`);
+    }
+
+    if (meta.author) {
+        const encoded = encodeAndEscapePdfText(meta.author);
+        log("pdf", "debug", "serializing metadata author", {
+            author: meta.author.slice(0, 50),
+            encoded,
+        });
+        entries.push(`/Author (${encoded})`);
+    }
+
+    if (meta.subject) {
+        const encoded = encodeAndEscapePdfText(meta.subject);
+        log("pdf", "debug", "serializing metadata subject", {
+            subject: meta.subject.slice(0, 50),
+            encoded,
+        });
+        entries.push(`/Subject (${encoded})`);
+    }
+
+    if (meta.keywords?.length) {
+        const keywordsText = meta.keywords.join(", ");
+        const encoded = encodeAndEscapePdfText(keywordsText);
+        log("pdf", "debug", "serializing metadata keywords", {
+            keywords: keywordsText.slice(0, 50),
+            encoded,
+        });
+        entries.push(`/Keywords (${encoded})`);
+    }
+
+    if (meta.producer) {
+        const encoded = encodeAndEscapePdfText(meta.producer);
+        log("pdf", "debug", "serializing metadata producer", {
+            producer: meta.producer.slice(0, 50),
+            encoded,
+        });
+        entries.push(`/Producer (${encoded})`);
+    }
+
+    return `<< ${entries.join(" ")} >>`;
+}
+
+/**
+ * Serializes the PDF trailer dictionary.
+ */
+export function serializeTrailer(
+    size: number,
+    catalogRef: PdfObjectRef,
+    infoRef: PdfObjectRef | null
+): string {
+    const entries = [`/Size ${size}`, `/Root ${catalogRef.objectNumber} 0 R`];
+    if (infoRef) {
+        entries.push(`/Info ${infoRef.objectNumber} 0 R`);
+    }
+    return `<< ${entries.join(" ")} >>`;
+}
+
+/**
+ * Formats a cross-reference table entry.
+ */
+export function formatXref(offset: number): string {
+    return `${offset.toString().padStart(10, "0")} 00000 n \n`;
+}
+
+/**
+ * Formats a number for PDF output, removing trailing zeros from decimals.
+ */
+export function formatNumber(value: number): string {
+    return Number.isInteger(value)
+        ? value.toString()
+        : value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+/**
+ * Sanitizes a PDF name by removing non-printable characters.
+ */
+export function sanitizeName(name: string): string {
+    return name.replace(/[^!-~]/g, "");
+}
+
+/**
+ * Checks if a font uses symbol encoding (Symbol or ZapfDingbats).
+ */
+export function usesSymbolEncoding(baseFont: string): boolean {
+    const normalized = sanitizeName(baseFont).toLowerCase();
+    return normalized === "symbol" || normalized === "zapfdingbats";
+}
+
+/**
+ * Checks if metadata object has any fields set.
+ */
+export function hasMetadata(meta: PdfMetadata): boolean {
+    return Boolean(
+        meta.title ||
+        meta.author ||
+        meta.subject ||
+        meta.keywords?.length ||
+        meta.producer
+    );
+}
+
+/**
+ * Clamps alpha value to [0, 1] range.
+ */
+export function clampUnitAlpha(value: number): number {
+    if (!Number.isFinite(value)) return 1;
+    if (value <= 0) return 0;
+    if (value >= 1) return 1;
+    return value;
+}

package/src/pdf/primitives/pdf-types.ts

@@ -0,0 +1,73 @@
+/**
+ * Core PDF types and interfaces shared across PDF generation components.
+ * These types define the structure of PDF resources and objects.
+ */
+
+export interface PdfObjectRef {
+    objectNumber: number;
+}
+
+export interface PdfFontResource {
+    name: string;
+    baseFont: string;
+    objectRef: PdfObjectRef | null;
+}
+
+export interface PdfImageResource {
+    ref: PdfObjectRef;
+    src?: string;
+    width: number;
+    height: number;
+    colorSpace: string;
+    bitsPerComponent: number;
+    filter?: string;
+    data: Uint8Array;
+    sMask?: PdfObjectRef;
+}
+
+export interface PdfPage {
+    width: number;
+    height: number;
+    contents: string;
+    resources: PdfResources;
+    annotations: string[];
+}
+
+export interface PdfResources {
+    fonts: Map<string, PdfObjectRef>;
+    xObjects: Map<string, PdfObjectRef>;
+    extGStates: Map<string, PdfObjectRef>;
+    shadings: Map<string, PdfObjectRef>;
+    patterns?: Map<string, PdfObjectRef>;
+}
+
+export interface PdfObject {
+    ref: PdfObjectRef;
+    body: Uint8Array;
+}
+
+export interface PdfExtGStateResource {
+    ref: PdfObjectRef;
+    alpha: number;
+}
+
+export interface PdfShadingResource {
+    ref: PdfObjectRef;
+    dict: string;
+}
+
+export interface PdfPatternResource {
+    ref: PdfObjectRef;
+    dict: string;
+}
+
+export interface PdfRegisteredObject {
+    ref: PdfObjectRef;
+    value: unknown;
+}
+
+export interface PdfRegisteredStream {
+    ref: PdfObjectRef;
+    data: Uint8Array;
+    headers: Record<string, string>;
+}