@namahapdf/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -189,7 +189,11 @@ declare class PDFParser {
      */
     private extractVersion;
     /**
-     * Parse all xref tables (including previous versions for incremental updates)
+     * Parse all xref tables (including previous versions for incremental updates).
+     * Falls back to a full-file brute-force scan when the real xref is missing or
+     * corrupt (missing startxref, malformed entries, unreadable xref stream) or
+     * when it parses but yields no usable /Root — so otherwise-readable PDFs with
+     * a broken cross-reference table still open.
      */
     private parseXRefTables;
     /**
@@ -470,6 +474,30 @@ type RenderTextRun = {
      * embedded family + substitute fallback, or just the substitute family).
      * Lets the inline editor render identical text — no size/width jump. */
     fontFamily?: string;
+    /** PDF text rendering mode (Tr) this run was drawn with. Modes 3 and 7 are
+     * invisible — the run is captured for editing/search but not painted. A page
+     * whose text is predominantly invisible is the hallmark of a scanned/OCR
+     * layer (see editor/scannedTextRecovery). */
+    textRenderMode: number;
+    /** Convenience: true for invisible render modes (3 = invisible, 7 = clip). */
+    invisible: boolean;
+    /** Cap-height (1000-em units) measured from the actual embedded FontFace, when
+     * one was registered. The editor uses it to size substitute-font redraws to
+     * match the original's caps. Measured (not the descriptor's often-wrong
+     * /CapHeight) — see measureRegisteredCapHeight. */
+    fontCapHeight?: number;
+    /** Numeric font weight (100–900) inferred from the base font name + descriptor
+     * (`inferFontWeight`). Lets exporters decide bold from the real weight rather
+     * than re-guessing from the name. ≥600 is effectively bold. */
+    fontWeight?: number;
+    /** Font slant inferred from the base font name + descriptor (`inferFontStyle`).
+     * Lets exporters decide italics from the real style, not a name heuristic. */
+    fontStyle?: 'normal' | 'italic';
+    /** The embedded-font family (npf-<hash>) this run was drawn with, when the PDF
+     * embedded a Unicode-cmap sfnt for it. Keys into
+     * `PageRenderer.getEmbeddedFontPrograms()` so an exporter can embed the real
+     * font bytes (e.g. into a .docx) instead of substituting. */
+    registeredFamily?: string;
 };
 /** A drawn image (XObject or inline), captured for editor selection. */
 type RenderImageBox = {
@@ -518,6 +546,10 @@ declare class PageRenderer {
     /** fontName -> registered FontFace family, populated by preloadEmbeddedFonts
      * before each async render pass. Read by loadFontInfo. */
     private embeddedFamilies;
+    /** family (npf-<hash>) → the embeddable sfnt bytes + PDF base font name.
+     * Captured independent of FontFace registration so it is populated even in
+     * headless/Node renders, and read by exporters (DOCX) to embed real fonts. */
+    private embeddedFontBytes;
     /** Memoized canvas glyph widths keyed by `${ctx.font}|${char}`, cleared per
      * render pass. Avoids a measureText (GPU readback) per glyph for fonts that
      * lack PDF width metrics. */
@@ -535,6 +567,12 @@ declare class PageRenderer {
     private currentPathY;
     private pathStartX;
     private pathStartY;
+    /** True while a path is being constructed (between a paint/clear op and the
+     * next painting op). A PDF path accumulates multiple subpaths (e.g. a glyph
+     * outline + its counter holes) and is only reset by a painting operator — so
+     * `beginPath()` must run once per path, NOT on every `m`/`re`, or all but the
+     * last subpath are discarded (counters/holes vanish, the `i` loses its stem). */
+    private pathOpen;
     private readonly initialTransform;
     private readonly forcedColor;
     private readonly patternDepth;
@@ -608,6 +646,15 @@ declare class PageRenderer {
     private decodeText;
     /** Canvas glyph width, memoized per (current font, text) for the render pass. */
     private measureGlyphWidthCached;
+    /**
+     * Cap-height (in 1000-unit em space) of a registered embedded font, measured
+     * from the actual FontFace via the canvas. This is the reliable source the
+     * editor uses to size substitute-font redraws: a PDF's FontDescriptor
+     * /CapHeight is often wrong (e.g. a Calibri subset declaring 750 when the real
+     * value is ~644), but measuring 'H' at 1000px gives the true cap height of the
+     * glyphs we actually drew. Cached per family; undefined if measurement fails.
+     */
+    private measureRegisteredCapHeight;
     /**
      * Resolve the page's Font dictionary and register each embedded font program
      * (TrueType/OpenType with a Unicode cmap) as a browser FontFace, recording
@@ -615,6 +662,13 @@ declare class PageRenderer {
      * font absent from the map, so loadFontInfo simply falls back to substitution.
      */
     private preloadEmbeddedFonts;
+    /** family (npf-<hash>) → embeddable sfnt bytes + PDF base font name, for every
+     * Unicode-cmap font the page embedded. Exporters embed these to reproduce the
+     * original type. Keyed to match `RenderTextRun.registeredFamily`. */
+    getEmbeddedFontPrograms(): Map<string, {
+        bytes: Uint8Array;
+        baseName: string;
+    }>;
     private getCurrentFontInfo;
     private loadFontInfo;
     private logFontDiagnostic;
@@ -641,9 +695,10 @@ declare class PageRenderer {
     private decodeJbig2;
     /**
      * Decode a CCITTFax (Group 3/4 fax) image stream to packed 1-bpp filter bytes
-     * via pdf.js's `CCITTFaxDecoder`. Polarity (BlackIs1) and the other
-     * parameters come from /DecodeParms; the decoder yields one packed byte per
-     * `readNextChar()`. Returns null on failure.
+     * via the vendored `CCITTFaxDecoder` (see `./ccitt` — pdf.js's
+     * image_decoders bundle doesn't export this class). Polarity (BlackIs1) and
+     * the other parameters come from /DecodeParms; the decoder yields one packed
+     * byte per `readNextChar()`. Returns null on failure.
      */
     private decodeCcitt;
     /** Composite an RGBA ImageData through a scratch canvas onto the page (the
@@ -704,6 +759,10 @@ declare class PageRenderer {
     private applyPatternColor;
     /** Render one tiling-pattern cell with a child renderer in pattern space. */
     private renderTilingCell;
+    /** Begin a fresh canvas path the first time geometry is added after a paint/
+     * clear op. PDF accumulates all subpaths into one path until a painting op
+     * resets it; calling `beginPath()` per `m`/`re` would drop earlier subpaths. */
+    private beginSubpathIfNeeded;
     /** Fill the current path: plain color, or pattern painted in pattern space. */
     private paintFill;
     /**
@@ -890,6 +949,9 @@ type PDFFontSpec = {
     color?: PDFColor;
     lineHeight?: number;
     charSpacing?: number;
+    /** Cap-height (1000-em units) measured from the original embedded font, when
+     * known. Used to size the substitute redraw so its caps match the original's. */
+    capHeight?: number;
 };
 type PdfMatrix = [number, number, number, number, number, number];
 
@@ -1158,6 +1220,26 @@ declare class PDFEditSession {
      * Underline / strikethrough are thin rectangles spanning the drawn width.
      */
     private drawStyledSpans;
+    /**
+     * Resolve the font to redraw an edit with, reporting whether it is a
+     * substitute (`substituted: true`) or the document's own embedded font.
+     *
+     * Option A (keep-original-when-it-fits): prefer the document's embedded font
+     * so an edit keeps the original typeface whenever that font can encode the
+     * typed text — normal-letter edits no longer drift to Helvetica/Times. Fall
+     * back to a standard look-alike (mapped from the PDF font name so weight/
+     * style are kept) only when the embedded subset can't encode the text (e.g.
+     * a brand-new glyph it never contained), which also avoids dropped/garbled
+     * characters. Standard fonts encode with simple WinAnsi and round-trip
+     * reliably through our own renderer.
+     *
+     * The embedded-font check (`fontSupportsText`) layout-probes the text — it
+     * runs fontkit's full OpenType layout, not just cmap/encode — so a subset
+     * font with pruned glyphs (or a GSUB ligature referencing a pruned glyph)
+     * is rejected here and we fall through to the standard look-alike instead of
+     * crashing later inside `drawText`/`widthOfTextAtSize` ("...reading
+     * 'advanceWidth'"). The draw/measure call sites are additionally guarded.
+     */
     private getRenderableFont;
     private supportedCodePoints;
     private unsupportedCount;
@@ -1169,7 +1251,31 @@ declare class PDFEditSession {
      */
     private fitTextToFont;
     private fontSupportsText;
+    /**
+     * True if fontkit can actually lay `text` out with `font`. This runs the
+     * same code path that `drawText`/`widthOfTextAtSize` use, so it catches
+     * subset fonts with GSUB holes that pass the cheaper cmap/encode checks.
+     */
+    private fontCanLayout;
+    /** Measure text width, returning 0 if fontkit layout fails. */
+    private safeWidth;
+    /**
+     * Draw text, falling back to `fallbackFont` if the chosen font throws inside
+     * fontkit. The `fontSupportsText` probe should already prevent this, but a
+     * font layout failure must never escape and fail the whole edit pipeline.
+     * Returns the font actually used so callers can measure with it.
+     */
+    private safeDrawText;
     private getEmbeddedFont;
+    /**
+     * True if `fontBytes` can be embedded and a document containing it saved
+     * without throwing. Run on a throwaway document so a font that crashes
+     * pdf-lib's embedder (e.g. missing name-table records, or a glyph the width
+     * table can't resolve) is rejected here — before it can poison `this.pdfDoc`
+     * and crash `toBlob()`. Cheap and done once per font (the result is cached
+     * via the embeddedFontCache promise).
+     */
+    private embedSurvivesSave;
     private getEmbeddedFontPrograms;
     private ensureFontkitRegistered;
 }
@@ -1255,11 +1361,19 @@ declare class PDFEditProcessor implements IAvniProcessor {
     process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
 }
 
+/**
+ * Pipeline wrapper around the client-side compressor (`src/engine/compress`).
+ *
+ * The real work — decode-any-image → downsample → JPEG re-encode, plus metadata
+ * strip / content-stream Flate / object streams — lives in `compressPdf`. This
+ * processor just adapts it to the `IAvniProcessor` contract so the orchestrator
+ * (and `test-engine`) can drive it. `params.level` accepts a preset id or the
+ * legacy numeric 0–100 value.
+ */
 declare class PDFCompressor implements IAvniProcessor {
     name: string;
     supportedTypes: "pdf"[];
     process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
-    private compressImageInBrowser;
 }
 
 /** Shared license/activation contracts used by both the engine gate and the server. */

package/dist/index.d.ts

@@ -189,7 +189,11 @@ declare class PDFParser {
      */
     private extractVersion;
     /**
-     * Parse all xref tables (including previous versions for incremental updates)
+     * Parse all xref tables (including previous versions for incremental updates).
+     * Falls back to a full-file brute-force scan when the real xref is missing or
+     * corrupt (missing startxref, malformed entries, unreadable xref stream) or
+     * when it parses but yields no usable /Root — so otherwise-readable PDFs with
+     * a broken cross-reference table still open.
      */
     private parseXRefTables;
     /**
@@ -470,6 +474,30 @@ type RenderTextRun = {
      * embedded family + substitute fallback, or just the substitute family).
      * Lets the inline editor render identical text — no size/width jump. */
     fontFamily?: string;
+    /** PDF text rendering mode (Tr) this run was drawn with. Modes 3 and 7 are
+     * invisible — the run is captured for editing/search but not painted. A page
+     * whose text is predominantly invisible is the hallmark of a scanned/OCR
+     * layer (see editor/scannedTextRecovery). */
+    textRenderMode: number;
+    /** Convenience: true for invisible render modes (3 = invisible, 7 = clip). */
+    invisible: boolean;
+    /** Cap-height (1000-em units) measured from the actual embedded FontFace, when
+     * one was registered. The editor uses it to size substitute-font redraws to
+     * match the original's caps. Measured (not the descriptor's often-wrong
+     * /CapHeight) — see measureRegisteredCapHeight. */
+    fontCapHeight?: number;
+    /** Numeric font weight (100–900) inferred from the base font name + descriptor
+     * (`inferFontWeight`). Lets exporters decide bold from the real weight rather
+     * than re-guessing from the name. ≥600 is effectively bold. */
+    fontWeight?: number;
+    /** Font slant inferred from the base font name + descriptor (`inferFontStyle`).
+     * Lets exporters decide italics from the real style, not a name heuristic. */
+    fontStyle?: 'normal' | 'italic';
+    /** The embedded-font family (npf-<hash>) this run was drawn with, when the PDF
+     * embedded a Unicode-cmap sfnt for it. Keys into
+     * `PageRenderer.getEmbeddedFontPrograms()` so an exporter can embed the real
+     * font bytes (e.g. into a .docx) instead of substituting. */
+    registeredFamily?: string;
 };
 /** A drawn image (XObject or inline), captured for editor selection. */
 type RenderImageBox = {
@@ -518,6 +546,10 @@ declare class PageRenderer {
     /** fontName -> registered FontFace family, populated by preloadEmbeddedFonts
      * before each async render pass. Read by loadFontInfo. */
     private embeddedFamilies;
+    /** family (npf-<hash>) → the embeddable sfnt bytes + PDF base font name.
+     * Captured independent of FontFace registration so it is populated even in
+     * headless/Node renders, and read by exporters (DOCX) to embed real fonts. */
+    private embeddedFontBytes;
     /** Memoized canvas glyph widths keyed by `${ctx.font}|${char}`, cleared per
      * render pass. Avoids a measureText (GPU readback) per glyph for fonts that
      * lack PDF width metrics. */
@@ -535,6 +567,12 @@ declare class PageRenderer {
     private currentPathY;
     private pathStartX;
     private pathStartY;
+    /** True while a path is being constructed (between a paint/clear op and the
+     * next painting op). A PDF path accumulates multiple subpaths (e.g. a glyph
+     * outline + its counter holes) and is only reset by a painting operator — so
+     * `beginPath()` must run once per path, NOT on every `m`/`re`, or all but the
+     * last subpath are discarded (counters/holes vanish, the `i` loses its stem). */
+    private pathOpen;
     private readonly initialTransform;
     private readonly forcedColor;
     private readonly patternDepth;
@@ -608,6 +646,15 @@ declare class PageRenderer {
     private decodeText;
     /** Canvas glyph width, memoized per (current font, text) for the render pass. */
     private measureGlyphWidthCached;
+    /**
+     * Cap-height (in 1000-unit em space) of a registered embedded font, measured
+     * from the actual FontFace via the canvas. This is the reliable source the
+     * editor uses to size substitute-font redraws: a PDF's FontDescriptor
+     * /CapHeight is often wrong (e.g. a Calibri subset declaring 750 when the real
+     * value is ~644), but measuring 'H' at 1000px gives the true cap height of the
+     * glyphs we actually drew. Cached per family; undefined if measurement fails.
+     */
+    private measureRegisteredCapHeight;
     /**
      * Resolve the page's Font dictionary and register each embedded font program
      * (TrueType/OpenType with a Unicode cmap) as a browser FontFace, recording
@@ -615,6 +662,13 @@ declare class PageRenderer {
      * font absent from the map, so loadFontInfo simply falls back to substitution.
      */
     private preloadEmbeddedFonts;
+    /** family (npf-<hash>) → embeddable sfnt bytes + PDF base font name, for every
+     * Unicode-cmap font the page embedded. Exporters embed these to reproduce the
+     * original type. Keyed to match `RenderTextRun.registeredFamily`. */
+    getEmbeddedFontPrograms(): Map<string, {
+        bytes: Uint8Array;
+        baseName: string;
+    }>;
     private getCurrentFontInfo;
     private loadFontInfo;
     private logFontDiagnostic;
@@ -641,9 +695,10 @@ declare class PageRenderer {
     private decodeJbig2;
     /**
      * Decode a CCITTFax (Group 3/4 fax) image stream to packed 1-bpp filter bytes
-     * via pdf.js's `CCITTFaxDecoder`. Polarity (BlackIs1) and the other
-     * parameters come from /DecodeParms; the decoder yields one packed byte per
-     * `readNextChar()`. Returns null on failure.
+     * via the vendored `CCITTFaxDecoder` (see `./ccitt` — pdf.js's
+     * image_decoders bundle doesn't export this class). Polarity (BlackIs1) and
+     * the other parameters come from /DecodeParms; the decoder yields one packed
+     * byte per `readNextChar()`. Returns null on failure.
      */
     private decodeCcitt;
     /** Composite an RGBA ImageData through a scratch canvas onto the page (the
@@ -704,6 +759,10 @@ declare class PageRenderer {
     private applyPatternColor;
     /** Render one tiling-pattern cell with a child renderer in pattern space. */
     private renderTilingCell;
+    /** Begin a fresh canvas path the first time geometry is added after a paint/
+     * clear op. PDF accumulates all subpaths into one path until a painting op
+     * resets it; calling `beginPath()` per `m`/`re` would drop earlier subpaths. */
+    private beginSubpathIfNeeded;
     /** Fill the current path: plain color, or pattern painted in pattern space. */
     private paintFill;
     /**
@@ -890,6 +949,9 @@ type PDFFontSpec = {
     color?: PDFColor;
     lineHeight?: number;
     charSpacing?: number;
+    /** Cap-height (1000-em units) measured from the original embedded font, when
+     * known. Used to size the substitute redraw so its caps match the original's. */
+    capHeight?: number;
 };
 type PdfMatrix = [number, number, number, number, number, number];
 
@@ -1158,6 +1220,26 @@ declare class PDFEditSession {
      * Underline / strikethrough are thin rectangles spanning the drawn width.
      */
     private drawStyledSpans;
+    /**
+     * Resolve the font to redraw an edit with, reporting whether it is a
+     * substitute (`substituted: true`) or the document's own embedded font.
+     *
+     * Option A (keep-original-when-it-fits): prefer the document's embedded font
+     * so an edit keeps the original typeface whenever that font can encode the
+     * typed text — normal-letter edits no longer drift to Helvetica/Times. Fall
+     * back to a standard look-alike (mapped from the PDF font name so weight/
+     * style are kept) only when the embedded subset can't encode the text (e.g.
+     * a brand-new glyph it never contained), which also avoids dropped/garbled
+     * characters. Standard fonts encode with simple WinAnsi and round-trip
+     * reliably through our own renderer.
+     *
+     * The embedded-font check (`fontSupportsText`) layout-probes the text — it
+     * runs fontkit's full OpenType layout, not just cmap/encode — so a subset
+     * font with pruned glyphs (or a GSUB ligature referencing a pruned glyph)
+     * is rejected here and we fall through to the standard look-alike instead of
+     * crashing later inside `drawText`/`widthOfTextAtSize` ("...reading
+     * 'advanceWidth'"). The draw/measure call sites are additionally guarded.
+     */
     private getRenderableFont;
     private supportedCodePoints;
     private unsupportedCount;
@@ -1169,7 +1251,31 @@ declare class PDFEditSession {
      */
     private fitTextToFont;
     private fontSupportsText;
+    /**
+     * True if fontkit can actually lay `text` out with `font`. This runs the
+     * same code path that `drawText`/`widthOfTextAtSize` use, so it catches
+     * subset fonts with GSUB holes that pass the cheaper cmap/encode checks.
+     */
+    private fontCanLayout;
+    /** Measure text width, returning 0 if fontkit layout fails. */
+    private safeWidth;
+    /**
+     * Draw text, falling back to `fallbackFont` if the chosen font throws inside
+     * fontkit. The `fontSupportsText` probe should already prevent this, but a
+     * font layout failure must never escape and fail the whole edit pipeline.
+     * Returns the font actually used so callers can measure with it.
+     */
+    private safeDrawText;
     private getEmbeddedFont;
+    /**
+     * True if `fontBytes` can be embedded and a document containing it saved
+     * without throwing. Run on a throwaway document so a font that crashes
+     * pdf-lib's embedder (e.g. missing name-table records, or a glyph the width
+     * table can't resolve) is rejected here — before it can poison `this.pdfDoc`
+     * and crash `toBlob()`. Cheap and done once per font (the result is cached
+     * via the embeddedFontCache promise).
+     */
+    private embedSurvivesSave;
     private getEmbeddedFontPrograms;
     private ensureFontkitRegistered;
 }
@@ -1255,11 +1361,19 @@ declare class PDFEditProcessor implements IAvniProcessor {
     process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
 }
 
+/**
+ * Pipeline wrapper around the client-side compressor (`src/engine/compress`).
+ *
+ * The real work — decode-any-image → downsample → JPEG re-encode, plus metadata
+ * strip / content-stream Flate / object streams — lives in `compressPdf`. This
+ * processor just adapts it to the `IAvniProcessor` contract so the orchestrator
+ * (and `test-engine`) can drive it. `params.level` accepts a preset id or the
+ * legacy numeric 0–100 value.
+ */
 declare class PDFCompressor implements IAvniProcessor {
     name: string;
     supportedTypes: "pdf"[];
     process(doc: AvniDocument, params: Record<string, unknown>): Promise<ProcessorResult>;
-    private compressImageInBrowser;
 }
 
 /** Shared license/activation contracts used by both the engine gate and the server. */