@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/writer/string-buf.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
+ *
+ * Kept as a thin alias so existing relative imports (`./string-buf`) within
+ * the word writer continue to work without churn.
+ */
+export { StringBuf } from "../../../utils/string-buf.js";
+export type { StringBufOptions } from "../../../utils/string-buf.js";

package/dist/browser/modules/word/writer/string-buf.js

@@ -0,0 +1,7 @@
+/**
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
+ *
+ * Kept as a thin alias so existing relative imports (`./string-buf`) within
+ * the word writer continue to work without churn.
+ */
+export { StringBuf } from "../../../utils/string-buf.js";

package/dist/browser/modules/word/{writers → writer}/styles-writer.js

@@ -61,12 +61,43 @@ function renderTableStyleCondition(xml, condition) {
             renderShading(xml, condition.cellProperties.shading);
         }
         if (condition.cellProperties.borders) {
-            renderTableBordersInStyle(xml, condition.cellProperties.borders);
+            renderCellBordersInStyle(xml, condition.cellProperties.borders);
         }
         xml.closeNode();
     }
     xml.closeNode();
 }
+/**
+ * Render cell borders inside a style definition (w:tcBorders).
+ * Cell-level border container is `w:tcBorders`, not `w:tblBorders` — using
+ * the wrong wrapper produces invalid styles.xml that Word silently ignores.
+ */
+function renderCellBordersInStyle(xml, borders) {
+    xml.openNode("w:tcBorders");
+    for (const side of [
+        "top",
+        "left",
+        "bottom",
+        "right",
+        "insideH",
+        "insideV",
+        "start",
+        "end",
+        "tl2br",
+        "tr2bl"
+    ]) {
+        const b = borders[side];
+        if (b) {
+            xml.leafNode(`w:${side}`, {
+                "w:val": b.style,
+                "w:sz": String(b.size ?? 4),
+                "w:space": String(b.space ?? 0),
+                "w:color": b.color ?? "auto"
+            });
+        }
+    }
+    xml.closeNode();
+}
 /** Render table borders inside a style definition. */
 function renderTableBordersInStyle(xml, borders) {
     xml.openNode("w:tblBorders");

package/dist/browser/modules/word/{writers → writer}/table-writer.d.ts

@@ -6,5 +6,6 @@
  */
 import type { XmlSink } from "../../xml/types.js";
 import type { Table } from "../types.js";
+import type { RenderHelpers } from "./render-context.js";
 /** Render a w:tbl element. */
-export declare function renderTable(xml: XmlSink, table: Table): void;
+export declare function renderTable(xml: XmlSink, table: Table, helpers?: RenderHelpers): void;

package/dist/browser/modules/word/{writers → writer}/table-writer.js

@@ -322,6 +322,14 @@ function renderTableCellProperties(xml, cPr, insidePropertyChange = false) {
     if (cPr.width) {
         renderTableWidth(xml, "w:tcW", cPr.width);
     }
+    else {
+        // OOXML's CT_TcPr.tcW is technically optional, but Word treats a
+        // missing <w:tcW> as a hard schema violation: it triggers the
+        // "content unreadable" repair dialog and silently drops the table.
+        // Emit a w:type="auto" placeholder so Word lays the cell out using
+        // the table-level grid widths.
+        xml.leafNode("w:tcW", { "w:w": "0", "w:type": "auto" });
+    }
     if (cPr.gridSpan !== undefined && cPr.gridSpan > 1) {
         xml.leafNode("w:gridSpan", { "w:val": String(cPr.gridSpan) });
     }
@@ -412,12 +420,24 @@ function renderTableCellProperties(xml, cPr, insidePropertyChange = false) {
     xml.closeNode();
 }
 /** Render a table cell. */
-function renderTableCell(xml, cell) {
+function renderTableCell(xml, cell, helpers) {
     xml.openNode("w:tc");
+    // OOXML CT_Tc requires a <w:tcPr> with at least <w:tcW> for Word to
+    // accept the cell. If the model didn't supply any cell properties we
+    // synthesise a minimal <w:tcPr><w:tcW w:type="auto"/></w:tcPr>; if it
+    // did, renderTableCellProperties handles the missing-tcW fallback.
     if (cell.properties) {
         renderTableCellProperties(xml, cell.properties);
     }
-    // Cell must contain at least one paragraph
+    else {
+        xml.openNode("w:tcPr");
+        xml.leafNode("w:tcW", { "w:w": "0", "w:type": "auto" });
+        xml.closeNode();
+    }
+    // OOXML §17.4.66 (CT_Tc) requires every table cell to *end* with a
+    // <w:p>. An empty cell needs at least one <w:p>, and a cell whose last
+    // block is a nested <w:tbl> must have a trailing <w:p> after it — Word
+    // (and LibreOffice) reject the document otherwise.
     if (cell.content.length === 0) {
         xml.openNode("w:p");
         xml.closeNode();
@@ -425,17 +445,22 @@ function renderTableCell(xml, cell) {
     else {
         for (const block of cell.content) {
             if (block.type === "paragraph") {
-                renderParagraph(xml, block);
+                renderParagraph(xml, block, helpers);
             }
             else if (block.type === "table") {
-                renderTable(xml, block);
+                renderTable(xml, block, helpers);
             }
         }
+        const last = cell.content[cell.content.length - 1];
+        if (last && last.type === "table") {
+            xml.openNode("w:p");
+            xml.closeNode();
+        }
     }
     xml.closeNode();
 }
 /** Render a table row. */
-function renderTableRow(xml, row) {
+function renderTableRow(xml, row, helpers) {
     xml.openNode("w:tr");
     // Table property exception (w:tblPrEx) must come before w:trPr per schema
     if (row.properties?.tblPrEx) {
@@ -445,7 +470,7 @@ function renderTableRow(xml, row) {
         renderTableRowProperties(xml, row.properties);
     }
     for (const cell of row.cells) {
-        renderTableCell(xml, cell);
+        renderTableCell(xml, cell, helpers);
     }
     xml.closeNode();
 }
@@ -483,21 +508,79 @@ function renderTablePropertiesEx(xml, ex) {
     xml.closeNode();
 }
 /** Render a w:tbl element. */
-export function renderTable(xml, table) {
+export function renderTable(xml, table, helpers) {
     xml.openNode("w:tbl");
     if (table.properties) {
         renderTableProperties(xml, table.properties);
     }
-    // Column grid
+    // Column grid. ECMA-376 §17.4.49 requires <w:tblGrid> with at least one
+    // <w:gridCol>. When the caller did not supply explicit column widths we
+    // synthesise the grid by inferring the column count from the widest row
+    // (counting gridSpan + gridBefore + gridAfter) and dividing the table
+    // width evenly. This keeps the package valid for Word / LibreOffice
+    // even when authors used the convenience builders that don't compute
+    // a grid up front.
+    xml.openNode("w:tblGrid");
     if (table.columnWidths && table.columnWidths.length > 0) {
-        xml.openNode("w:tblGrid");
         for (const w of table.columnWidths) {
             xml.leafNode("w:gridCol", { "w:w": String(w) });
         }
-        xml.closeNode();
     }
+    else {
+        const columnCount = Math.max(1, computeTableColumnCount(table));
+        const totalWidth = inferTableWidthInTwips(table.properties);
+        const colWidth = Math.max(1, Math.floor(totalWidth / columnCount));
+        for (let i = 0; i < columnCount; i++) {
+            xml.leafNode("w:gridCol", { "w:w": String(colWidth) });
+        }
+    }
+    xml.closeNode();
     for (const row of table.rows) {
-        renderTableRow(xml, row);
+        renderTableRow(xml, row, helpers);
     }
     xml.closeNode();
 }
+/**
+ * Count the number of grid columns the table requires.
+ *
+ * Each cell occupies `gridSpan` columns (default 1); each row may also
+ * declare `gridBefore` / `gridAfter` to leave empty grid units on its sides.
+ * The grid must be wide enough for every row, so we take the maximum.
+ */
+function computeTableColumnCount(table) {
+    let max = 1;
+    for (const row of table.rows) {
+        let count = row.properties?.gridBefore ?? 0;
+        for (const cell of row.cells) {
+            count += cell.properties?.gridSpan ?? 1;
+        }
+        count += row.properties?.gridAfter ?? 0;
+        if (count > max) {
+            max = count;
+        }
+    }
+    return max;
+}
+/**
+ * Pick a sensible total width (in twips) for a synthesised tblGrid.
+ *
+ * - If the table specifies a `dxa` width, use it directly.
+ * - If it specifies a `pct` width, treat it as a fraction of a default
+ *   page text area (US Letter minus 1" margins = 9 360 twips). A 5000/pct
+ *   value (= 100%) maps to the full text area.
+ * - Otherwise default to the same 9 360 twips.
+ */
+function inferTableWidthInTwips(props) {
+    const TEXT_AREA_TWIPS = 9360;
+    const w = props?.width;
+    if (!w) {
+        return TEXT_AREA_TWIPS;
+    }
+    if (w.type === "dxa" && typeof w.value === "number" && w.value > 0) {
+        return w.value;
+    }
+    if (w.type === "pct" && typeof w.value === "number" && w.value > 0) {
+        return Math.round((w.value / 5000) * TEXT_AREA_TWIPS);
+    }
+    return TEXT_AREA_TWIPS;
+}

package/dist/browser/modules/xml/types.d.ts

@@ -214,6 +214,28 @@ export interface SaxOptions {
  * Accepts strings or Uint8Array chunks.
  * Compatible with Node.js Writable, browser WritableStream wrappers,
  * and the project's own StreamBuf.
+ *
+ * **Backpressure caveat**: `write()` returns `void`. The XmlStreamWriter
+ * cannot signal or wait for backpressure on the target — it pushes
+ * chunks synchronously as the caller invokes `openNode`/`writeText`/etc.
+ *
+ * If the target is a slow sink (HTTP response, fs stream, etc), the
+ * caller is responsible for ensuring chunks are consumed at a rate
+ * matching production. Two safe patterns:
+ *
+ *   1. Wrap the target so `write()` buffers into a bounded queue and
+ *      pause your XML production loop when the queue is full.
+ *   2. Use a small in-memory buffer as the `WritableTarget`, then ship
+ *      the assembled bytes to the slow sink with proper backpressure
+ *      (e.g. via `pipeline()`).
+ *
+ * `XmlStreamWriter` is used internally by excelts's xlsx writer. The xlsx
+ * writer wraps it in a backpressure-aware zip pipeline that awaits drain
+ * BETWEEN zip entries — so memory grows at most by one entry's worth of
+ * uncompressed XML before the producer is parked. Within a single very
+ * large worksheet entry the synchronous push pattern still applies; that
+ * is the practical bound on how much a slow user sink can buffer behind
+ * the xlsx writer.
  */
 export interface WritableTarget {
     write(chunk: string | Uint8Array): void;

package/dist/browser/utils/crypto.browser.d.ts

@@ -19,7 +19,9 @@ export declare function sha256(input: Uint8Array): Uint8Array;
 export declare function md5(input: Uint8Array): Uint8Array;
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2).
  */
 export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
 /**

package/dist/browser/utils/crypto.browser.js

@@ -510,7 +510,9 @@ export function md5(input) {
 // =============================================================================
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2).
  */
 export function rc4(key, data) {
     const s = new Uint8Array(256);

package/dist/browser/utils/crypto.d.ts

@@ -67,7 +67,10 @@ export declare function aesCbcEncryptRaw(plaintext: Uint8Array, key: Uint8Array,
 export declare function aesEcbEncrypt(block: Uint8Array, key: Uint8Array): Uint8Array;
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2). Modern Node `crypto` no longer
+ * exposes RC4, so this is a pure-JS implementation.
  */
 export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
 /**

package/dist/browser/utils/crypto.js

@@ -124,7 +124,10 @@ export function aesEcbEncrypt(block, key) {
 // =============================================================================
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2). Modern Node `crypto` no longer
+ * exposes RC4, so this is a pure-JS implementation.
  */
 export function rc4(key, data) {
     // Node's crypto doesn't expose RC4 in modern versions, use pure JS

package/dist/browser/utils/font-metrics.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Standard Font Metrics — shared between Word layout and PDF rendering.
+ *
+ * Provides width data for the 14 standard PDF fonts (Helvetica, Times, Courier families).
+ * Used for text measurement without requiring actual font files.
+ *
+ * Character widths are specified in 1/1000 of a text unit. To get the actual width
+ * of a character at a given font size:
+ *   width_in_points = (charWidth / 1000) * fontSize
+ *
+ * @see PDF Reference 1.7, Appendix D - Standard Type 1 Fonts
+ * @see Adobe Font Metrics files (AFM) for canonical widths
+ */
+/**
+ * Get the width of a character in a given font.
+ * @param charCode - Unicode code point (or char code)
+ * @param fontName - PDF standard font name
+ * @returns Width in thousandths of a unit
+ */
+export declare function getCharWidth(charCode: number, fontName: string): number;
+/**
+ * Measure the width of a text string in the given font and size.
+ * @param text - The string to measure
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Width in points
+ */
+export declare function measureTextWidth(text: string, fontName: string, fontSize: number): number;
+/**
+ * Get the font ascent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Ascent in points (positive, distance above baseline)
+ */
+export declare function getFontAscent(fontName: string, fontSize: number): number;
+/**
+ * Get the font descent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Descent in points (positive value representing distance below baseline)
+ */
+export declare function getFontDescent(fontName: string, fontSize: number): number;
+/**
+ * Get the total line height (ascent - descent) for a font.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Line height in points
+ */
+export declare function getLineHeight(fontName: string, fontSize: number): number;
+/**
+ * Check if a font name is a known standard PDF font.
+ */
+export declare function isStandardFont(fontName: string): boolean;
+/**
+ * Get all supported standard font names.
+ */
+export declare function getStandardFontNames(): string[];
+/**
+ * Map common font names (like "Arial", "Calibri") to closest standard font.
+ * Returns the input unchanged if it's already a standard font name.
+ * Falls back to "Helvetica" for unknown fonts.
+ */
+export declare function mapToStandardFont(fontName: string): string;

package/dist/browser/utils/font-metrics.js

@@ -0,0 +1,293 @@
+/**
+ * Standard Font Metrics — shared between Word layout and PDF rendering.
+ *
+ * Provides width data for the 14 standard PDF fonts (Helvetica, Times, Courier families).
+ * Used for text measurement without requiring actual font files.
+ *
+ * Character widths are specified in 1/1000 of a text unit. To get the actual width
+ * of a character at a given font size:
+ *   width_in_points = (charWidth / 1000) * fontSize
+ *
+ * @see PDF Reference 1.7, Appendix D - Standard Type 1 Fonts
+ * @see Adobe Font Metrics files (AFM) for canonical widths
+ */
+// =============================================================================
+// Helvetica Metrics (afm data: Helvetica)
+// =============================================================================
+/**
+ * Character widths for ASCII 32-126.
+ * Values are in thousandths of a unit of text space.
+ */
+// prettier-ignore
+const HELVETICA_WIDTHS = {
+    32: 278, 33: 278, 34: 355, 35: 556, 36: 556, 37: 889, 38: 667, 39: 191, 40: 333, 41: 333,
+    42: 389, 43: 584, 44: 278, 45: 333, 46: 278, 47: 278, 48: 556, 49: 556, 50: 556, 51: 556,
+    52: 556, 53: 556, 54: 556, 55: 556, 56: 556, 57: 556, 58: 278, 59: 278, 60: 584, 61: 584,
+    62: 584, 63: 556, 64: 1015, 65: 667, 66: 667, 67: 722, 68: 722, 69: 667, 70: 611, 71: 778,
+    72: 722, 73: 278, 74: 500, 75: 667, 76: 556, 77: 833, 78: 722, 79: 778, 80: 667, 81: 778,
+    82: 722, 83: 667, 84: 611, 85: 722, 86: 667, 87: 944, 88: 667, 89: 667, 90: 611, 91: 278,
+    92: 278, 93: 278, 94: 469, 95: 556, 96: 333, 97: 556, 98: 556, 99: 500, 100: 556, 101: 556,
+    102: 278, 103: 556, 104: 556, 105: 222, 106: 222, 107: 500, 108: 222, 109: 833, 110: 556,
+    111: 556, 112: 556, 113: 556, 114: 333, 115: 500, 116: 278, 117: 556, 118: 500, 119: 722,
+    120: 500, 121: 500, 122: 500, 123: 334, 124: 260, 125: 334, 126: 584
+};
+// prettier-ignore
+const HELVETICA_BOLD_WIDTHS = {
+    32: 278, 33: 333, 34: 474, 35: 556, 36: 556, 37: 889, 38: 722, 39: 238, 40: 333, 41: 333,
+    42: 389, 43: 584, 44: 278, 45: 333, 46: 278, 47: 278, 48: 556, 49: 556, 50: 556, 51: 556,
+    52: 556, 53: 556, 54: 556, 55: 556, 56: 556, 57: 556, 58: 333, 59: 333, 60: 584, 61: 584,
+    62: 584, 63: 611, 64: 975, 65: 722, 66: 722, 67: 722, 68: 722, 69: 667, 70: 611, 71: 778,
+    72: 722, 73: 278, 74: 556, 75: 722, 76: 611, 77: 833, 78: 722, 79: 778, 80: 667, 81: 778,
+    82: 722, 83: 667, 84: 611, 85: 722, 86: 667, 87: 944, 88: 667, 89: 667, 90: 611, 91: 333,
+    92: 278, 93: 333, 94: 584, 95: 556, 96: 333, 97: 556, 98: 611, 99: 556, 100: 611, 101: 556,
+    102: 333, 103: 611, 104: 611, 105: 278, 106: 278, 107: 556, 108: 278, 109: 889, 110: 611,
+    111: 611, 112: 611, 113: 611, 114: 389, 115: 556, 116: 333, 117: 611, 118: 556, 119: 778,
+    120: 556, 121: 556, 122: 500, 123: 389, 124: 280, 125: 389, 126: 584
+};
+// prettier-ignore
+const TIMES_ROMAN_WIDTHS = {
+    32: 250, 33: 333, 34: 408, 35: 500, 36: 500, 37: 833, 38: 778, 39: 180, 40: 333, 41: 333,
+    42: 500, 43: 564, 44: 250, 45: 333, 46: 250, 47: 278, 48: 500, 49: 500, 50: 500, 51: 500,
+    52: 500, 53: 500, 54: 500, 55: 500, 56: 500, 57: 500, 58: 278, 59: 278, 60: 564, 61: 564,
+    62: 564, 63: 444, 64: 921, 65: 722, 66: 667, 67: 667, 68: 722, 69: 611, 70: 556, 71: 722,
+    72: 722, 73: 333, 74: 389, 75: 722, 76: 611, 77: 889, 78: 722, 79: 722, 80: 556, 81: 722,
+    82: 667, 83: 556, 84: 611, 85: 722, 86: 722, 87: 944, 88: 722, 89: 722, 90: 611, 91: 333,
+    92: 278, 93: 333, 94: 469, 95: 500, 96: 333, 97: 444, 98: 500, 99: 444, 100: 500, 101: 444,
+    102: 333, 103: 500, 104: 500, 105: 278, 106: 278, 107: 500, 108: 278, 109: 778, 110: 500,
+    111: 500, 112: 500, 113: 500, 114: 333, 115: 389, 116: 278, 117: 500, 118: 500, 119: 722,
+    120: 500, 121: 500, 122: 444, 123: 480, 124: 200, 125: 480, 126: 541
+};
+// prettier-ignore
+const TIMES_BOLD_WIDTHS = {
+    32: 250, 33: 333, 34: 555, 35: 500, 36: 500, 37: 1000, 38: 833, 39: 278, 40: 333, 41: 333,
+    42: 500, 43: 570, 44: 250, 45: 333, 46: 250, 47: 278, 48: 500, 49: 500, 50: 500, 51: 500,
+    52: 500, 53: 500, 54: 500, 55: 500, 56: 500, 57: 500, 58: 333, 59: 333, 60: 570, 61: 570,
+    62: 570, 63: 500, 64: 930, 65: 722, 66: 667, 67: 722, 68: 722, 69: 667, 70: 611, 71: 778,
+    72: 778, 73: 389, 74: 500, 75: 778, 76: 667, 77: 944, 78: 722, 79: 778, 80: 611, 81: 778,
+    82: 722, 83: 556, 84: 667, 85: 722, 86: 722, 87: 1000, 88: 722, 89: 722, 90: 667, 91: 333,
+    92: 278, 93: 333, 94: 581, 95: 500, 96: 333, 97: 500, 98: 556, 99: 444, 100: 556, 101: 444,
+    102: 333, 103: 500, 104: 556, 105: 278, 106: 333, 107: 556, 108: 278, 109: 833, 110: 556,
+    111: 500, 112: 556, 113: 556, 114: 444, 115: 389, 116: 333, 117: 556, 118: 500, 119: 722,
+    120: 500, 121: 500, 122: 444, 123: 394, 124: 220, 125: 394, 126: 520
+};
+// Courier is monospaced - every character is 600 units wide
+const COURIER_WIDTH = 600;
+const FONT_DESCRIPTORS = {
+    Helvetica: {
+        ascent: 718,
+        descent: -207,
+        capHeight: 718,
+        avgWidth: 513,
+        widths: HELVETICA_WIDTHS
+    },
+    "Helvetica-Bold": {
+        ascent: 718,
+        descent: -207,
+        capHeight: 718,
+        avgWidth: 535,
+        widths: HELVETICA_BOLD_WIDTHS
+    },
+    "Helvetica-Oblique": {
+        ascent: 718,
+        descent: -207,
+        capHeight: 718,
+        avgWidth: 513,
+        widths: HELVETICA_WIDTHS // same widths as regular
+    },
+    "Helvetica-BoldOblique": {
+        ascent: 718,
+        descent: -207,
+        capHeight: 718,
+        avgWidth: 535,
+        widths: HELVETICA_BOLD_WIDTHS
+    },
+    "Times-Roman": {
+        ascent: 683,
+        descent: -217,
+        capHeight: 662,
+        avgWidth: 478,
+        widths: TIMES_ROMAN_WIDTHS
+    },
+    "Times-Bold": {
+        ascent: 683,
+        descent: -217,
+        capHeight: 676,
+        avgWidth: 505,
+        widths: TIMES_BOLD_WIDTHS
+    },
+    "Times-Italic": {
+        ascent: 683,
+        descent: -217,
+        capHeight: 653,
+        avgWidth: 478,
+        widths: TIMES_ROMAN_WIDTHS // approximate
+    },
+    "Times-BoldItalic": {
+        ascent: 683,
+        descent: -217,
+        capHeight: 669,
+        avgWidth: 505,
+        widths: TIMES_BOLD_WIDTHS // approximate
+    },
+    Courier: {
+        ascent: 629,
+        descent: -157,
+        capHeight: 562,
+        avgWidth: 600,
+        widths: null,
+        monoWidth: COURIER_WIDTH
+    },
+    "Courier-Bold": {
+        ascent: 629,
+        descent: -157,
+        capHeight: 562,
+        avgWidth: 600,
+        widths: null,
+        monoWidth: COURIER_WIDTH
+    },
+    "Courier-Oblique": {
+        ascent: 629,
+        descent: -157,
+        capHeight: 562,
+        avgWidth: 600,
+        widths: null,
+        monoWidth: COURIER_WIDTH
+    },
+    "Courier-BoldOblique": {
+        ascent: 629,
+        descent: -157,
+        capHeight: 562,
+        avgWidth: 600,
+        widths: null,
+        monoWidth: COURIER_WIDTH
+    }
+};
+// =============================================================================
+// Font Name Mapping
+// =============================================================================
+/**
+ * Maps common font family names to the closest standard PDF font.
+ */
+const FONT_FAMILY_MAP = {
+    // Sans-serif → Helvetica
+    helvetica: "Helvetica",
+    arial: "Helvetica",
+    calibri: "Helvetica",
+    "segoe ui": "Helvetica",
+    "trebuchet ms": "Helvetica",
+    verdana: "Helvetica",
+    tahoma: "Helvetica",
+    "gill sans": "Helvetica",
+    "franklin gothic": "Helvetica",
+    "lucida sans": "Helvetica",
+    aptos: "Helvetica",
+    // Serif → Times-Roman
+    "times new roman": "Times-Roman",
+    times: "Times-Roman",
+    georgia: "Times-Roman",
+    garamond: "Times-Roman",
+    "book antiqua": "Times-Roman",
+    palatino: "Times-Roman",
+    "palatino linotype": "Times-Roman",
+    cambria: "Times-Roman",
+    "century schoolbook": "Times-Roman",
+    // Monospace → Courier
+    "courier new": "Courier",
+    courier: "Courier",
+    consolas: "Courier",
+    "lucida console": "Courier",
+    monaco: "Courier",
+    "andale mono": "Courier",
+    "cascadia code": "Courier",
+    "cascadia mono": "Courier",
+    menlo: "Courier"
+};
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get the width of a character in a given font.
+ * @param charCode - Unicode code point (or char code)
+ * @param fontName - PDF standard font name
+ * @returns Width in thousandths of a unit
+ */
+export function getCharWidth(charCode, fontName) {
+    const desc = FONT_DESCRIPTORS[fontName];
+    if (!desc) {
+        // Fall back to Helvetica
+        return getCharWidth(charCode, "Helvetica");
+    }
+    if (desc.monoWidth !== undefined) {
+        return desc.monoWidth;
+    }
+    return desc.widths?.[charCode] ?? desc.avgWidth;
+}
+/**
+ * Measure the width of a text string in the given font and size.
+ * @param text - The string to measure
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Width in points
+ */
+export function measureTextWidth(text, fontName, fontSize) {
+    let totalWidth = 0;
+    for (let i = 0; i < text.length; i++) {
+        totalWidth += getCharWidth(text.charCodeAt(i), fontName);
+    }
+    return (totalWidth / 1000) * fontSize;
+}
+/**
+ * Get the font ascent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Ascent in points (positive, distance above baseline)
+ */
+export function getFontAscent(fontName, fontSize) {
+    const desc = FONT_DESCRIPTORS[fontName] ?? FONT_DESCRIPTORS["Helvetica"];
+    return (desc.ascent / 1000) * fontSize;
+}
+/**
+ * Get the font descent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Descent in points (positive value representing distance below baseline)
+ */
+export function getFontDescent(fontName, fontSize) {
+    const desc = FONT_DESCRIPTORS[fontName] ?? FONT_DESCRIPTORS["Helvetica"];
+    return (desc.descent / 1000) * fontSize;
+}
+/**
+ * Get the total line height (ascent - descent) for a font.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Line height in points
+ */
+export function getLineHeight(fontName, fontSize) {
+    const desc = FONT_DESCRIPTORS[fontName] ?? FONT_DESCRIPTORS["Helvetica"];
+    return ((desc.ascent - desc.descent) / 1000) * fontSize;
+}
+/**
+ * Check if a font name is a known standard PDF font.
+ */
+export function isStandardFont(fontName) {
+    return fontName in FONT_DESCRIPTORS;
+}
+/**
+ * Get all supported standard font names.
+ */
+export function getStandardFontNames() {
+    return Object.keys(FONT_DESCRIPTORS);
+}
+/**
+ * Map common font names (like "Arial", "Calibri") to closest standard font.
+ * Returns the input unchanged if it's already a standard font name.
+ * Falls back to "Helvetica" for unknown fonts.
+ */
+export function mapToStandardFont(fontName) {
+    // If it's already a standard font, return as-is
+    if (fontName in FONT_DESCRIPTORS) {
+        return fontName;
+    }
+    const lower = fontName.toLowerCase().trim();
+    return FONT_FAMILY_MAP[lower] ?? "Helvetica";
+}