@cj-tech-master/excelts 9.4.1 → 9.4.2

package/dist/browser/modules/pdf/builder/document-builder.js

@@ -25,7 +25,7 @@ import { PdfWriter } from "../core/pdf-writer.js";
 import { writePdfAMetadata, writePdfAOutputIntent } from "../core/pdfa.js";
 import { FontManager } from "../font/font-manager.js";
 import { parseTtf } from "../font/ttf-parser.js";
-import { wrapTextLines } from "../render/page-renderer.js";
+import { wrapTextLines, emitTextWithMatrix } from "../render/page-renderer.js";
 import { writeImageXObject } from "./image-utils.js";
 // =============================================================================
 // Constants
@@ -87,8 +87,8 @@ export class PdfPageBuilder {
         const fontFamily = options.fontFamily ?? "Helvetica";
         // Resolve font
         const resourceName = this._fontManager.resolveFont(fontFamily, bold, italic);
-        const encodedText = this._fontManager.encodeText(text, resourceName);
         this._fontManager.trackText(text);
+        const useType3 = this._fontManager.hasType3Fonts() && !this._fontManager.hasEmbeddedFont();
         if (options.maxWidth) {
             // Word-wrap (reuses the shared wrapTextLines from page-renderer)
             const measure = (s) => this._fontManager.measureText(s, resourceName, fontSize);
@@ -96,36 +96,17 @@ export class PdfPageBuilder {
             const leading = fontSize * lineHeightFactor;
             this._stream.save();
             this._stream.setFillColor(color);
-            this._stream.beginText();
-            this._stream.setFont(resourceName, fontSize);
             for (let i = 0; i < lines.length; i++) {
                 const lineY = options.y - i * leading;
-                this._stream.setTextMatrix(1, 0, 0, 1, options.x, lineY);
-                const lineEncoded = this._fontManager.encodeText(lines[i], resourceName);
-                if (lineEncoded) {
-                    this._stream.showTextHex(lineEncoded);
-                }
-                else {
-                    this._stream.showText(lines[i]);
-                }
+                emitTextWithMatrix(this._stream, lines[i], 1, 0, 0, 1, options.x, lineY, resourceName, fontSize, this._fontManager, useType3);
             }
-            this._stream.endText();
             this._stream.restore();
         }
         else {
             // Single line
             this._stream.save();
             this._stream.setFillColor(color);
-            this._stream.beginText();
-            this._stream.setFont(resourceName, fontSize);
-            this._stream.setTextMatrix(1, 0, 0, 1, options.x, options.y);
-            if (encodedText) {
-                this._stream.showTextHex(encodedText);
-            }
-            else {
-                this._stream.showText(text);
-            }
-            this._stream.endText();
+            emitTextWithMatrix(this._stream, text, 1, 0, 0, 1, options.x, options.y, resourceName, fontSize, this._fontManager, useType3);
             this._stream.restore();
         }
         return this;

package/dist/browser/modules/pdf/core/pdf-stream.d.ts

@@ -20,6 +20,11 @@ import type { PdfColor } from "../types.js";
  */
 export declare class PdfContentStream {
     private parts;
+    /**
+     * Append a raw PDF operator string to the content stream.
+     * Use this for operators not covered by the typed API (e.g. `d1` for Type3 glyphs).
+     */
+    raw(operator: string): this;
     /**
      * Save the current graphics state (push onto state stack).
      * Must be balanced with a corresponding restore().
@@ -225,3 +230,13 @@ export declare class PdfContentStream {
      */
     toUint8Array(): Uint8Array;
 }
+/**
+ * Check whether a single code point is representable in WinAnsi encoding.
+ */
+export declare function isWinAnsiCodePoint(cp: number): boolean;
+/**
+ * Check whether a string contains characters outside the WinAnsi repertoire.
+ * When true, standard Type1 fonts cannot render those characters and an
+ * embedded TrueType font is required for correct output.
+ */
+export declare function hasNonWinAnsiChars(text: string): boolean;

package/dist/browser/modules/pdf/core/pdf-stream.js

@@ -26,6 +26,17 @@ export class PdfContentStream {
         this.parts = [];
     }
     // ===========================================================================
+    // Raw Operator
+    // ===========================================================================
+    /**
+     * Append a raw PDF operator string to the content stream.
+     * Use this for operators not covered by the typed API (e.g. `d1` for Type3 glyphs).
+     */
+    raw(operator) {
+        this.parts.push(operator);
+        return this;
+    }
+    // ===========================================================================
     // Graphics State
     // ===========================================================================
     /**
@@ -502,7 +513,9 @@ const UNICODE_TO_WINANSI = new Map([
 ]);
 /**
  * Convert a Unicode code point to a WinAnsi byte value.
- * Returns 0x3F ('?') for unmappable characters.
+ * Returns 0x20 (space) for unmappable characters — standard Type1 fonts
+ * do not contain glyphs outside the WinAnsi repertoire, so a space is
+ * less misleading than a literal '?'.
  */
 function unicodeToWinAnsi(cp) {
     // Direct mapping for Latin-1 range (0x00-0xFF), excluding 0x80-0x9F
@@ -517,6 +530,37 @@ function unicodeToWinAnsi(cp) {
     if (mapped !== undefined) {
         return mapped;
     }
-    // Unmappable — use '?'
-    return 0x3f;
+    // Unmappable — use space instead of '?' to avoid misleading output.
+    // Full Unicode support requires an embedded TrueType font (the `font`
+    // option in PdfExportOptions).
+    return 0x20;
+}
+/**
+ * Check whether a single code point is representable in WinAnsi encoding.
+ */
+export function isWinAnsiCodePoint(cp) {
+    if (cp < 0x80) {
+        return true;
+    }
+    if (cp >= 0xa0 && cp <= 0xff) {
+        return true;
+    }
+    return UNICODE_TO_WINANSI.has(cp);
+}
+/**
+ * Check whether a string contains characters outside the WinAnsi repertoire.
+ * When true, standard Type1 fonts cannot render those characters and an
+ * embedded TrueType font is required for correct output.
+ */
+export function hasNonWinAnsiChars(text) {
+    for (let i = 0; i < text.length; i++) {
+        const cp = text.codePointAt(i);
+        if (cp > 0xffff) {
+            i++;
+        }
+        if (!isWinAnsiCodePoint(cp)) {
+            return true;
+        }
+    }
+    return false;
 }

package/dist/browser/modules/pdf/font/font-manager.d.ts

@@ -1,18 +1,20 @@
 /**
  * Font manager for PDF generation.
  *
- * Manages two kinds of fonts:
+ * Manages three kinds of fonts:
  * 1. **Standard Type1 fonts** (Helvetica, Times, Courier) — always available,
- *    used as fallback for Latin text when no embedded font is provided.
+ *    used for Latin text (WinAnsi repertoire) when no embedded font is provided.
  * 2. **Embedded TrueType fonts** — user-provided .ttf files for full
  *    Unicode support (CJK, Arabic, Hindi, etc.)
+ * 3. **Type3 fallback fonts** — auto-generated vector-drawn glyphs for
+ *    Unicode characters outside WinAnsi when no embedded font is provided.
  *
  * When an embedded font is registered, ALL text uses the embedded font.
- * When no embedded font is provided, the system falls back to standard fonts
- * exactly as before (mapping Calibri→Helvetica, etc.)
+ * When no embedded font is provided, the system uses Type1 for WinAnsi
+ * characters and Type3 for everything else.
  *
  * The manager tracks which Unicode code points are used so the font embedder
- * can create a minimal subset when writing the PDF.
+ * and Type3 builder can create minimal subsets when writing the PDF.
  */
 import type { PdfWriter } from "../core/pdf-writer.js";
 import { type EmbeddedFont } from "./font-embedder.js";
@@ -23,7 +25,8 @@ import type { TtfFont } from "./ttf-parser.js";
 export declare function resolvePdfFontName(fontFamily: string, bold: boolean, italic: boolean): string;
 /**
  * Manages PDF font resources for a document.
- * Supports both standard Type1 fonts and embedded TrueType fonts.
+ * Supports standard Type1 fonts, embedded TrueType fonts, and auto-generated
+ * Type3 fallback fonts for non-WinAnsi Unicode characters.
  */
 export declare class FontManager {
     private type1Map;
@@ -33,6 +36,8 @@ export declare class FontManager {
     private embeddedResourceName;
     private usedCodePoints;
     private nextEmbeddedId;
+    private type3CodePoints;
+    private _type3Result;
     /**
      * Register an embedded TrueType font for use.
      * When set, all text rendering uses this font instead of standard fonts.
@@ -65,8 +70,25 @@ export declare class FontManager {
      * Get the PDF font name for a given resource name.
      */
     getPdfFontName(resourceName: string): string;
+    /**
+     * Check if Type3 fallback fonts are available (after writeFontResources).
+     */
+    hasType3Fonts(): boolean;
+    /**
+     * Resolve the Type3 font resource name and char code for a code point.
+     * Returns null if the code point is not in the Type3 encoding.
+     */
+    resolveType3(codePoint: number): {
+        resourceName: string;
+        charCode: number;
+    } | null;
+    /**
+     * Check if a code point needs Type3 rendering (non-WinAnsi, no embedded font).
+     */
+    needsType3(codePoint: number): boolean;
     /**
      * Measure text width using the correct font metrics.
+     * For mixed Type1/Type3 text, measures each character with the right font.
      */
     measureText(text: string, resourceName: string, fontSize: number): number;
     /**
@@ -85,6 +107,10 @@ export declare class FontManager {
      * Check if a resource name refers to an embedded font.
      */
     isEmbeddedFont(resourceName: string): boolean;
+    /**
+     * Check if a resource name refers to a Type3 fallback font.
+     */
+    isType3Resource(resourceName: string): boolean;
     /**
      * Encode text for the given font resource.
      * For embedded fonts, returns a hex string `<0012003A...>`.
@@ -94,6 +120,11 @@ export declare class FontManager {
      * subset and produces the unicodeToCid mapping.
      */
     encodeText(text: string, resourceName: string): string | null;
+    /**
+     * Encode a single character for a Type3 font.
+     * Returns a hex string `<XX>` suitable for the Tj operator.
+     */
+    encodeType3Char(codePoint: number): string | null;
     /**
      * Write all font resource objects to the PDF.
      * Returns a map from resource name → object number.

package/dist/browser/modules/pdf/font/font-manager.js

@@ -1,23 +1,27 @@
 /**
  * Font manager for PDF generation.
  *
- * Manages two kinds of fonts:
+ * Manages three kinds of fonts:
  * 1. **Standard Type1 fonts** (Helvetica, Times, Courier) — always available,
- *    used as fallback for Latin text when no embedded font is provided.
+ *    used for Latin text (WinAnsi repertoire) when no embedded font is provided.
  * 2. **Embedded TrueType fonts** — user-provided .ttf files for full
  *    Unicode support (CJK, Arabic, Hindi, etc.)
+ * 3. **Type3 fallback fonts** — auto-generated vector-drawn glyphs for
+ *    Unicode characters outside WinAnsi when no embedded font is provided.
  *
  * When an embedded font is registered, ALL text uses the embedded font.
- * When no embedded font is provided, the system falls back to standard fonts
- * exactly as before (mapping Calibri→Helvetica, etc.)
+ * When no embedded font is provided, the system uses Type1 for WinAnsi
+ * characters and Type3 for everything else.
  *
  * The manager tracks which Unicode code points are used so the font embedder
- * can create a minimal subset when writing the PDF.
+ * and Type3 builder can create minimal subsets when writing the PDF.
  */
 import { PdfDict, pdfName, pdfRef } from "../core/pdf-object.js";
+import { hasNonWinAnsiChars, isWinAnsiCodePoint } from "../core/pdf-stream.js";
 import { PdfFontError } from "../errors.js";
 import { embedTtfFont } from "./font-embedder.js";
 import { measureText as measureType1Text, getFontAscent as getType1Ascent, getFontDescent as getType1Descent, getLineHeight as getType1LineHeight } from "./metrics.js";
+import { writeType3Fonts } from "./type3-font.js";
 // =============================================================================
 // Font Name Mapping (Type1 fallback)
 // =============================================================================
@@ -104,7 +108,8 @@ export function resolvePdfFontName(fontFamily, bold, italic) {
 // =============================================================================
 /**
  * Manages PDF font resources for a document.
- * Supports both standard Type1 fonts and embedded TrueType fonts.
+ * Supports standard Type1 fonts, embedded TrueType fonts, and auto-generated
+ * Type3 fallback fonts for non-WinAnsi Unicode characters.
  */
 export class FontManager {
     constructor() {
@@ -117,6 +122,9 @@ export class FontManager {
         this.embeddedResourceName = "";
         this.usedCodePoints = new Set();
         this.nextEmbeddedId = 1;
+        // --- Type3 fallback font tracking ---
+        this.type3CodePoints = new Set();
+        this._type3Result = null;
         /** Stored after writeFontResources is called */
         this._embeddedResult = null;
     }
@@ -149,14 +157,25 @@ export class FontManager {
      * Must be called for every text string before writing the PDF.
      */
     trackText(text) {
-        if (!this.embeddedFont) {
-            return;
+        if (this.embeddedFont) {
+            for (let i = 0; i < text.length; i++) {
+                const cp = text.codePointAt(i);
+                this.usedCodePoints.add(cp);
+                if (cp > 0xffff) {
+                    i++; // skip low surrogate
+                }
+            }
         }
-        for (let i = 0; i < text.length; i++) {
-            const cp = text.codePointAt(i);
-            this.usedCodePoints.add(cp);
-            if (cp > 0xffff) {
-                i++; // skip low surrogate
+        else {
+            // No embedded font — track non-WinAnsi chars for Type3 fallback
+            for (let i = 0; i < text.length; i++) {
+                const cp = text.codePointAt(i);
+                if (cp > 0xffff) {
+                    i++;
+                }
+                if (!isWinAnsiCodePoint(cp)) {
+                    this.type3CodePoints.add(cp);
+                }
             }
         }
     }
@@ -194,17 +213,72 @@ export class FontManager {
         return this.resourceToType1.get(resourceName) ?? "Helvetica";
     }
     // ==========================================================================
+    // Type3 Fallback Font
+    // ==========================================================================
+    /**
+     * Check if Type3 fallback fonts are available (after writeFontResources).
+     */
+    hasType3Fonts() {
+        return this._type3Result !== null && this._type3Result.fontObjects.size > 0;
+    }
+    /**
+     * Resolve the Type3 font resource name and char code for a code point.
+     * Returns null if the code point is not in the Type3 encoding.
+     */
+    resolveType3(codePoint) {
+        if (!this._type3Result) {
+            return null;
+        }
+        return this._type3Result.encoding.get(codePoint) ?? null;
+    }
+    /**
+     * Check if a code point needs Type3 rendering (non-WinAnsi, no embedded font).
+     */
+    needsType3(codePoint) {
+        return !this.embeddedFont && !isWinAnsiCodePoint(codePoint);
+    }
+    // ==========================================================================
     // Text Measurement
     // ==========================================================================
     /**
      * Measure text width using the correct font metrics.
+     * For mixed Type1/Type3 text, measures each character with the right font.
      */
     measureText(text, resourceName, fontSize) {
         if (this.embeddedFont && resourceName === this.embeddedResourceName) {
             return measureEmbeddedText(text, this.embeddedFont, fontSize);
         }
+        // If no Type3 fonts or text has no non-WinAnsi chars, use Type1 directly
+        if (!this._type3Result || !hasNonWinAnsiChars(text)) {
+            const pdfFontName = this.getPdfFontName(resourceName);
+            return measureType1Text(text, pdfFontName, fontSize);
+        }
+        // Mixed text: measure char by char
+        let totalWidth = 0;
         const pdfFontName = this.getPdfFontName(resourceName);
-        return measureType1Text(text, pdfFontName, fontSize);
+        for (let i = 0; i < text.length; i++) {
+            const cp = text.codePointAt(i);
+            if (cp > 0xffff) {
+                i++;
+            }
+            if (isWinAnsiCodePoint(cp)) {
+                totalWidth += measureType1Text(String.fromCodePoint(cp), pdfFontName, fontSize);
+            }
+            else {
+                // Type3 character width
+                const t3 = this._type3Result.encoding.get(cp);
+                if (t3) {
+                    const widthMap = this._type3Result.widths.get(t3.resourceName);
+                    const glyphWidth = widthMap?.get(t3.charCode) ?? 600;
+                    totalWidth += (glyphWidth / 1000) * fontSize;
+                }
+                else {
+                    // Notdef width
+                    totalWidth += (600 / 1000) * fontSize;
+                }
+            }
+        }
+        return totalWidth;
     }
     /**
      * Get the font ascent in points.
@@ -213,7 +287,11 @@ export class FontManager {
         if (this.embeddedFont && resourceName === this.embeddedResourceName) {
             return (this.embeddedFont.ascent / this.embeddedFont.unitsPerEm) * fontSize;
         }
-        return getType1Ascent(this.getPdfFontName(resourceName), fontSize);
+        // Type3 fonts use the same metrics as the base Type1 font
+        const base = this.isType3Resource(resourceName)
+            ? "Helvetica"
+            : this.getPdfFontName(resourceName);
+        return getType1Ascent(base, fontSize);
     }
     /**
      * Get the font descent in points (negative value).
@@ -222,7 +300,10 @@ export class FontManager {
         if (this.embeddedFont && resourceName === this.embeddedResourceName) {
             return (this.embeddedFont.descent / this.embeddedFont.unitsPerEm) * fontSize;
         }
-        return getType1Descent(this.getPdfFontName(resourceName), fontSize);
+        const base = this.isType3Resource(resourceName)
+            ? "Helvetica"
+            : this.getPdfFontName(resourceName);
+        return getType1Descent(base, fontSize);
     }
     /**
      * Get the line height in points.
@@ -232,7 +313,10 @@ export class FontManager {
             const f = this.embeddedFont;
             return ((f.ascent - f.descent) / f.unitsPerEm) * fontSize;
         }
-        return getType1LineHeight(this.getPdfFontName(resourceName), fontSize);
+        const base = this.isType3Resource(resourceName)
+            ? "Helvetica"
+            : this.getPdfFontName(resourceName);
+        return getType1LineHeight(base, fontSize);
     }
     // ==========================================================================
     // Text Encoding
@@ -243,6 +327,12 @@ export class FontManager {
     isEmbeddedFont(resourceName) {
         return this.embeddedFont !== null && resourceName === this.embeddedResourceName;
     }
+    /**
+     * Check if a resource name refers to a Type3 fallback font.
+     */
+    isType3Resource(resourceName) {
+        return this._type3Result?.fontObjects.has(resourceName) ?? false;
+    }
     /**
      * Encode text for the given font resource.
      * For embedded fonts, returns a hex string `<0012003A...>`.
@@ -263,6 +353,21 @@ export class FontManager {
         // writeFontResources not called yet — this is a programming error
         throw new PdfFontError("encodeText called before writeFontResources — subset mapping not available");
     }
+    /**
+     * Encode a single character for a Type3 font.
+     * Returns a hex string `<XX>` suitable for the Tj operator.
+     */
+    encodeType3Char(codePoint) {
+        if (!this._type3Result) {
+            return null;
+        }
+        const entry = this._type3Result.encoding.get(codePoint);
+        if (!entry) {
+            return null;
+        }
+        const hex = entry.charCode.toString(16).toUpperCase().padStart(2, "0");
+        return `<${hex}>`;
+    }
     // ==========================================================================
     // PDF Object Writing
     // ==========================================================================
@@ -290,6 +395,13 @@ export class FontManager {
             // Store the embedding result for text re-encoding
             this._embeddedResult = embedded;
         }
+        // Write Type3 fallback fonts (only when no embedded font)
+        if (!this.embeddedFont && this.type3CodePoints.size > 0) {
+            this._type3Result = writeType3Fonts(writer, this.type3CodePoints);
+            for (const [resourceName, objNum] of this._type3Result.fontObjects) {
+                fontObjectMap.set(resourceName, objNum);
+            }
+        }
         return fontObjectMap;
     }
     /**

package/dist/browser/modules/pdf/font/system-fonts.d.ts

@@ -0,0 +1,41 @@
+/**
+ * System font discovery for PDF generation.
+ *
+ * When no embedded font is provided and the document contains non-WinAnsi
+ * characters, this module searches standard system font directories for a
+ * TrueType font (.ttf or .ttc) with broad Unicode coverage.
+ *
+ * This is a Node.js-only feature — browser environments do not have
+ * file system access and must always provide fonts explicitly.
+ *
+ * .ttc (TrueType Collection) files are supported — parseTtf() extracts
+ * the first font from the collection automatically.
+ *
+ * Results are cached: the filesystem search runs only once per process.
+ */
+/**
+ * Return all discoverable system font candidates, ordered by preference.
+ *
+ * Each entry is the raw font file bytes of a `.ttf` or `.ttc` file.
+ * The caller decides which candidate to use (e.g. by checking cmap coverage).
+ *
+ * Results are cached — the filesystem scan runs only once per process.
+ */
+export declare function discoverSystemFontCandidates(): Uint8Array[];
+/**
+ * Search for a system font suitable for Unicode rendering.
+ *
+ * Returns the raw font file bytes of the highest-priority candidate,
+ * or `null` if no font was found. This is a convenience wrapper around
+ * {@link discoverSystemFontCandidates}.
+ */
+export declare function discoverSystemFont(): Uint8Array | null;
+/**
+ * Reset the cached font discovery result (for testing).
+ */
+export declare function resetFontDiscoveryCache(): void;
+/**
+ * Override the cached candidates with a custom list (for testing).
+ * Call {@link resetFontDiscoveryCache} to clear the override.
+ */
+export declare function _setCandidatesForTest(candidates: Uint8Array[]): void;