@cj-tech-master/excelts 9.4.1 → 9.4.2

package/dist/types/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/types/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/types/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;

package/dist/types/modules/pdf/font/type3-font.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Type3 fallback font builder.
+ *
+ * Produces a PDF Type3 font object that contains vector-drawn glyphs for
+ * Unicode characters that cannot be represented by standard Type1 fonts
+ * (WinAnsi encoding).
+ *
+ * A single Type3 font supports up to 256 glyphs (single-byte encoding).
+ * When more than 256 distinct non-WinAnsi characters appear in a document,
+ * multiple Type3 fonts are created automatically.
+ *
+ * @see PDF Reference 1.7, §5.5.4 — Type 3 Fonts
+ */
+import type { PdfWriter } from "../core/pdf-writer.js";
+/** Result of writing Type3 font(s) to the PDF. */
+export interface Type3FontResult {
+    /** Map from Type3 resource name → PDF object number. */
+    fontObjects: Map<string, number>;
+    /** Map from Unicode code point → { resourceName, charCode }. */
+    encoding: Map<number, {
+        resourceName: string;
+        charCode: number;
+    }>;
+    /** Advance widths: resourceName → Map<charCode, width in 1/1000 em>. */
+    widths: Map<string, Map<number, number>>;
+}
+/**
+ * Build and write Type3 fallback fonts to the PDF for the given code points.
+ *
+ * @param writer - The PdfWriter to add objects to.
+ * @param codePoints - Set of Unicode code points that need Type3 rendering.
+ * @param resourcePrefix - Prefix for resource names (e.g. "T3F").
+ * @returns Encoding and object info for use by FontManager.
+ */
+export declare function writeType3Fonts(writer: PdfWriter, codePoints: Set<number>, resourcePrefix?: string): Type3FontResult;

package/dist/types/modules/pdf/font/type3-glyphs-extended.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Extended Type3 glyph definitions — programmatically generated blocks
+ * and additional hand-crafted symbols.
+ *
+ * This file supplements type3-glyphs.ts with:
+ *  - Box Drawing        (U+2500–U+257F)  128 chars — algorithmic
+ *  - Block Elements     (U+2580–U+259F)   32 chars — algorithmic
+ *  - Braille Patterns   (U+2800–U+28FF)  256 chars — algorithmic
+ *  - Letterlike Symbols  (U+2100–U+214F)  hand-crafted
+ *  - Number Forms        (U+2150–U+218F)  hand-crafted
+ *  - Enclosed Alphanumerics (U+2460–U+24FF) programmatic
+ *  - General Punctuation extras (U+2000–U+206F)
+ *  - Additional Arrows, Math, Dingbats, Misc Symbols, Currency, Technical
+ */
+import type { GlyphDef } from "./type3-glyphs.js";
+export declare const BOX_FULL: Record<number, GlyphDef>;
+export declare const BLOCK_FULL: Record<number, GlyphDef>;
+export declare const BRAILLE: Record<number, GlyphDef>;
+export declare const LETTERLIKE: Record<number, GlyphDef>;
+export declare const NUMBER_FORMS: Record<number, GlyphDef>;
+export declare const ENCLOSED: Record<number, GlyphDef>;
+export declare const PUNCT_EXT: Record<number, GlyphDef>;
+export declare const ARROWS_EXT: Record<number, GlyphDef>;
+export declare const MATH_EXT: Record<number, GlyphDef>;
+export declare const MISC_EXT: Record<number, GlyphDef>;
+export declare const DING_EXT: Record<number, GlyphDef>;
+export declare const TECH_EXT: Record<number, GlyphDef>;
+export declare const CURRENCY_EXT: Record<number, GlyphDef>;
+export declare const MATH_SYM_A: Record<number, GlyphDef>;
+export declare const SUP_ARROWS_A: Record<number, GlyphDef>;
+export declare const GEOMETRIC_EXT: Record<number, GlyphDef>;
+export declare const ROMAN_NUMERALS: Record<number, GlyphDef>;
+export declare const ENCLOSED_EXT: Record<number, GlyphDef>;

package/dist/types/modules/pdf/font/type3-glyphs-extended2.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extended Type3 glyph definitions — Part 2
+ *
+ * Additional hand-crafted glyph blocks:
+ *  - Arrows Extended: Harpoons & Paired Arrows (U+21BC–U+21FF)
+ *  - Dingbats Full (U+2700–U+27BF)
+ *  - Misc Symbols Full (U+2600–U+26FF)
+ */
+import type { GlyphDef } from "./type3-glyphs.js";
+export declare const ARROWS_HARPOONS: Record<number, GlyphDef>;
+export declare const DINGBATS_FULL: Record<number, GlyphDef>;
+export declare const MISC_SYMBOLS_FULL: Record<number, GlyphDef>;
+export declare const MISC_TECHNICAL_EXT: Record<number, GlyphDef>;
+export declare const SUP_ARROWS_B: Record<number, GlyphDef>;
+export declare const MISC_MATH_A_EXT: Record<number, GlyphDef>;
+export declare const MISC_SYM_ARROWS_EXT: Record<number, GlyphDef>;

package/dist/types/modules/pdf/font/type3-glyphs-fill.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gap-filling glyph definitions — programmatic batch generation.
+ *
+ * Fills all remaining gaps across Dingbats, Misc Symbols, Misc Symbols & Arrows,
+ * Supplemental Arrows A/B, General Punctuation, and Number Forms.
+ *
+ * Strategy: use helper functions and loops to generate approximations for
+ * characters that share structural patterns (stars, arrows, chess pieces, etc).
+ */
+import type { GlyphDef } from "./type3-glyphs.js";
+export declare const FINAL_FILL: Record<number, GlyphDef>;
+export declare const DINGBATS_FILL: Record<number, GlyphDef>;
+export declare const MISC_SYM_FILL: Record<number, GlyphDef>;
+export declare const MISC_SYM_ARR_FILL: Record<number, GlyphDef>;
+export declare const SUP_ARROWS_FILL: Record<number, GlyphDef>;
+export declare const GEN_PUNCT_FILL: Record<number, GlyphDef>;
+export declare const NUM_FORMS_FILL: Record<number, GlyphDef>;

package/dist/types/modules/pdf/font/type3-glyphs-quality.d.ts

@@ -0,0 +1,28 @@
+/**
+ * High-quality glyph replacements and additions.
+ *
+ * This file:
+ * 1. Defines space characters (U+2000–U+200F) with correct advance widths
+ *    and empty draw callbacks.
+ * 2. Replaces enclosed numbers ①–⑳, Ⓐ–Ⓩ, ❶–❿ with recognisable
+ *    circle + digit/letter shapes drawn purely from paths.
+ * 3. Refines common symbols (✓✗★♥→← etc.) for better visual fidelity.
+ * 4. Adds Supplemental Math Operators (U+2A00–U+2AFF) and
+ *    Misc Math Symbols-B (U+2980–U+29FF).
+ *
+ * Entries here are appended LAST to ALL_TABLES so they override any
+ * earlier, lower-quality definitions for the same code point.
+ */
+import type { GlyphDef } from "./type3-glyphs.js";
+export declare const SPACES: Record<number, GlyphDef>;
+export declare const CIRCLED_DIGITS: Record<number, GlyphDef>;
+export declare const CIRCLED_LETTERS: Record<number, GlyphDef>;
+export declare const CIRCLED_SMALL_LETTERS: Record<number, GlyphDef>;
+export declare const NEG_CIRCLED_DIGITS: Record<number, GlyphDef>;
+export declare const REFINED_SYMBOLS: Record<number, GlyphDef>;
+export declare const SUPP_MATH_OP: Record<number, GlyphDef>;
+export declare const MISC_MATH_B: Record<number, GlyphDef>;
+export declare const MATH_OP_FULL: Record<number, GlyphDef>;
+export declare const LETTERLIKE_FULL: Record<number, GlyphDef>;
+export declare const CURRENCY_REMAINING: Record<number, GlyphDef>;
+export declare const ARROWS_REMAINING: Record<number, GlyphDef>;

package/dist/types/modules/pdf/font/type3-glyphs.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type3 fallback glyph definitions.
+ *
+ * Each glyph is a function that writes PDF content-stream operators into
+ * a 1000×1000 unit glyph coordinate system (matching a FontMatrix of
+ * [0.001 0 0 0.001 0 0]).
+ *
+ * The drawing callbacks receive a simple `GlyphPen` API so they don't
+ * depend on `PdfContentStream` directly — this keeps the module
+ * self-contained and easy to test.
+ *
+ * Coverage strategy:
+ *  1. Geometric Shapes          (U+25A0–U+25FF)
+ *  2. Miscellaneous Symbols     (U+2600–U+26FF)
+ *  3. Dingbats / checkmarks     (U+2700–U+27BF)
+ *  4. Arrows                    (U+2190–U+21FF)
+ *  5. Mathematical Operators    (U+2200–U+22FF)
+ *  6. Box Drawing               (U+2500–U+257F)
+ *  7. Block Elements            (U+2580–U+259F)
+ *  8. Misc Technical            (U+2300–U+23FF)
+ *  9. Enclosed Alphanumerics    (U+2460–U+24FF)
+ * 10. Misc Symbols & Arrows     (U+2B00–U+2BFF)
+ * 11. Ballot / checkbox symbols (U+2610–U+2612)
+ * 12. Supplemental Arrows       (U+27F0–U+27FF)
+ * 13. Braille Patterns          (U+2800–U+28FF)
+ * 14. Squared symbols etc.      (U+29C0–U+29FF)
+ *
+ * Characters not in this table get a generic .notdef glyph (open rectangle).
+ */
+/**
+ * Minimal drawing API used by glyph definitions.
+ * Lines are emitted as raw PDF content-stream operators.
+ */
+export interface GlyphPen {
+    /** Move to (x, y). */
+    M(x: number, y: number): void;
+    /** Line to (x, y). */
+    L(x: number, y: number): void;
+    /** Cubic Bezier curve. */
+    C(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): void;
+    /** Close path. */
+    Z(): void;
+    /** Rectangle (x, y, w, h). */
+    rect(x: number, y: number, w: number, h: number): void;
+    /** Circle at (cx, cy) with radius r using 4 Bezier arcs. */
+    circle(cx: number, cy: number, r: number): void;
+    /** Ellipse at (cx, cy) with radii (rx, ry). */
+    ellipse(cx: number, cy: number, rx: number, ry: number): void;
+    /** Stroke current path. */
+    stroke(): void;
+    /** Fill current path (non-zero winding). */
+    fill(): void;
+    /** Fill then stroke. */
+    fillStroke(): void;
+    /** Set line width. */
+    lineWidth(w: number): void;
+}
+/** A glyph definition: advance width + drawing callback. */
+export interface GlyphDef {
+    /** Advance width in glyph units (0–1000). */
+    width: number;
+    /** Draw the glyph outline using the pen. */
+    draw: (p: GlyphPen) => void;
+}
+/** .notdef: open rectangle — drawn for any character we don't have. */
+export declare const NOTDEF_GLYPH: GlyphDef;
+/**
+ * Look up a glyph definition for a Unicode code point.
+ * Returns the glyph def, or `undefined` if no specific drawing is available.
+ */
+export declare function lookupGlyph(codePoint: number): GlyphDef | undefined;
+/**
+ * Check whether a specific code point has a dedicated vector glyph.
+ */
+export declare function hasGlyph(codePoint: number): boolean;
+/**
+ * Return the total number of defined glyphs (for diagnostics / testing).
+ */
+export declare function glyphCount(): number;

package/dist/types/modules/pdf/render/page-renderer.d.ts

@@ -24,6 +24,15 @@ export interface PageRenderResult {
  * Render a single page to a PDF content stream.
  */
 export declare function renderPage(page: LayoutPage, options: ResolvedPdfOptions, fontManager: FontManager, totalPages: number): PageRenderResult;
+/**
+ * Render a text string with a custom text matrix, using Type3-aware splitting
+ * when needed.  For each sub-run the matrix origin is advanced along the
+ * text direction (cos, sin) by the rendered width.
+ *
+ * When `useType3` is false this collapses to a single BT/ET pair — identical
+ * to the old `emitText()` path but wrapped in begin/end for convenience.
+ */
+export declare function emitTextWithMatrix(stream: PdfContentStream, text: string, a: number, b: number, c: number, d: number, tx: number, ty: number, type1ResourceName: string, fontSize: number, fontManager: FontManager, useType3: boolean): void;
 /**
  * Generate a deterministic ExtGState resource name for a given alpha value.
  * Uses 4 decimal digits to avoid collisions between close alpha values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "9.4.1",
+  "version": "9.4.2",
   "description": "Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.",
   "keywords": [
     "archive",