@libpdf/core 0.2.2 → 0.2.4

package/README.md

@@ -1,5 +1,12 @@
 # LibPDF
 
+[![npm](https://img.shields.io/npm/v/@libpdf/core)](https://www.npmjs.com/package/@libpdf/core)
+[![npm downloads](https://img.shields.io/npm/dm/@libpdf/core)](https://www.npmjs.com/package/@libpdf/core)
+[![CI](https://github.com/LibPDF-js/core/actions/workflows/ci.yml/badge.svg)](https://github.com/LibPDF-js/core/actions/workflows/ci.yml)
+[![GitHub stars](https://img.shields.io/github/stars/libpdf-js/core?style=flat)](https://github.com/LibPDF-js/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
 A modern PDF library for TypeScript. Parse, modify, and generate PDFs with a clean, intuitive API.
 
 > **Beta Software**: LibPDF is under active development and APIs may change between minor versions, but we use it in production at [Documenso](https://documenso.com) and consider it ready for real-world use.
@@ -8,7 +15,7 @@ A modern PDF library for TypeScript. Parse, modify, and generate PDFs with a cle
 
 LibPDF was born from frustration. At [Documenso](https://documenso.com), we found ourselves wrestling with the JavaScript PDF ecosystem:
 
-- **PDF.js** is excellent for rendering, but it's read-only
+- **PDF.js** is excellent for rendering and even has annotation editing — but it requires a browser
 - **pdf-lib** has a great API, but chokes on slightly malformed documents
 - **pdfkit** only generates, no parsing at all
 
@@ -51,7 +58,7 @@ bun add @libpdf/core
 import { PDF } from "@libpdf/core";
 
 const pdf = await PDF.load(bytes);
-const pages = await pdf.getPages();
+const pages = pdf.getPages();
 
 console.log(`${pages.length} pages`);
 ```
@@ -66,7 +73,7 @@ const pdf = await PDF.load(bytes, { credentials: "password" });
 
 ```typescript
 const pdf = await PDF.load(bytes);
-const form = await pdf.getForm();
+const form = pdf.getForm();
 
 form.fill({
   name: "Jane Doe",

package/dist/index.d.mts

@@ -3732,20 +3732,41 @@ interface FindTextOptions {
   wholeWord?: boolean;
 }
 //#endregion
-//#region src/fonts/standard-14.d.ts
+//#region src/svg/path-executor.d.ts
 /**
- * Standard 14 PDF Fonts
- *
- * These are the 14 fonts that every PDF reader must support.
- * They don't require embedding - the reader provides them.
- *
- * Width tables are stored by glyph name (like pdf.js) which works
- * with any encoding. Use getWidthByGlyphName() for lookup.
- *
- * Widths are in glyph units (1000 units = 1 em).
- *
- * Data extracted from pdf.js metrics.js (Mozilla, Apache 2.0 License)
+ * Options for SVG path execution.
  */
+interface SvgPathExecutorOptions {
+  /**
+   * Flip Y coordinates (negate Y values).
+   *
+   * SVG uses a top-left origin with Y increasing downward.
+   * PDF uses a bottom-left origin with Y increasing upward.
+   *
+   * When true (default), Y coordinates are negated to convert
+   * SVG paths to PDF coordinate space.
+   *
+   * @default true
+   */
+  flipY?: boolean;
+  /**
+   * Scale factor to apply to all coordinates.
+   * @default 1
+   */
+  scale?: number;
+  /**
+   * X offset to add after scaling and flipping.
+   * @default 0
+   */
+  translateX?: number;
+  /**
+   * Y offset to add after scaling and flipping.
+   * @default 0
+   */
+  translateY?: number;
+}
+//#endregion
+//#region src/fonts/standard-14.d.ts
 /**
  * Standard 14 font names.
  */
@@ -3971,6 +3992,65 @@ interface DrawEllipseOptions {
   /** Rotation */
   rotate?: Rotation;
 }
+/**
+ * Options for drawing an SVG path.
+ *
+ * SVG paths are automatically transformed from SVG coordinate space
+ * (Y-down, origin at top-left) to PDF coordinate space (Y-up, origin
+ * at bottom-left). Use `x`, `y`, and `scale` to position and size
+ * the path on the page.
+ */
+interface DrawSvgPathOptions {
+  /**
+   * X position on the page (left edge of the path's bounding box).
+   * @default 0
+   */
+  x?: number;
+  /**
+   * Y position on the page (bottom edge of the path's bounding box after transform).
+   * @default 0
+   */
+  y?: number;
+  /**
+   * Scale factor to apply to the path.
+   * Useful for SVG icons with large viewBox (e.g., 512x512).
+   * A scale of 0.1 would make a 512-unit icon ~51 points.
+   * @default 1
+   */
+  scale?: number;
+  /**
+   * Whether to flip the Y-axis to convert from SVG coordinates (Y-down)
+   * to PDF coordinates (Y-up).
+   *
+   * Set to `true` (default) when using SVG paths from icon libraries.
+   * Set to `false` when using paths already in PDF coordinate space.
+   *
+   * @default true
+   */
+  flipY?: boolean;
+  /** Fill color (default: black; omit to stroke only if borderColor set) */
+  color?: Color;
+  /** Stroke color (omit for no stroke) */
+  borderColor?: Color;
+  /** Stroke width in points (default: 1 if borderColor set) */
+  borderWidth?: number;
+  /** Line cap style */
+  lineCap?: LineCap;
+  /** Line join style */
+  lineJoin?: LineJoin;
+  /** Miter limit for miter joins */
+  miterLimit?: number;
+  /** Dash pattern array */
+  dashArray?: number[];
+  /** Dash pattern phase */
+  dashPhase?: number;
+  /** Fill opacity 0-1 (default: 1) */
+  opacity?: number;
+  /** Stroke opacity 0-1 (default: 1) */
+  borderOpacity?: number;
+  /** Winding rule for fill (default: "nonzero") */
+  windingRule?: "nonzero" | "evenodd";
+}
 /**
  * Options for path painting.
  */
@@ -4010,8 +4090,9 @@ declare function lineJoinToNumber(join: LineJoin): 0 | 1 | 2;
 //#region src/api/drawing/path-builder.d.ts
 /**
  * Callback type for appending content to a page.
+ * Accepts a string (for ASCII-only content) or raw bytes.
  */
-type ContentAppender = (content: string) => void;
+type ContentAppender = (content: string | Uint8Array) => void;
 /**
  * Callback type for registering a graphics state and returning its name.
  */
@@ -4093,6 +4174,40 @@ declare class PathBuilder {
    * Add an ellipse to the current path.
    */
   ellipse(cx: number, cy: number, rx: number, ry: number): this;
+  /**
+   * Append an SVG path string to the current path.
+   *
+   * Parses the SVG path `d` attribute string and adds all commands to this path.
+   * Relative commands (lowercase) are converted to absolute coordinates based on
+   * the current point. Smooth curves (S, T) and arcs (A) are converted to
+   * cubic bezier curves.
+   *
+   * By default, this method does NOT transform coordinates (flipY: false).
+   * Use the options to apply scale, translation, and Y-flip for SVG paths.
+   *
+   * @param pathData - SVG path `d` attribute string
+   * @param options - Execution options (flipY, scale, translate)
+   * @returns This PathBuilder for chaining
+   *
+   * @example
+   * ```typescript
+   * // Simple path (no transform)
+   * page.drawPath()
+   *   .appendSvgPath("M 10 10 L 100 10 L 55 90 Z")
+   *   .fill({ color: rgb(1, 0, 0) });
+   *
+   * // SVG icon with full transform
+   * page.drawPath()
+   *   .appendSvgPath(iconPath, {
+   *     flipY: true,
+   *     scale: 0.1,
+   *     translateX: 100,
+   *     translateY: 500,
+   *   })
+   *   .fill({ color: rgb(0, 0, 0) });
+   * ```
+   */
+  appendSvgPath(pathData: string, options?: SvgPathExecutorOptions): this;
   /**
    * Stroke the path with the given options.
    */
@@ -5204,6 +5319,49 @@ declare class PDFPage {
    * ```
    */
   drawPath(): PathBuilder;
+  /**
+   * Draw an SVG path on the page.
+   *
+   * This is a convenience method that parses an SVG path `d` attribute string
+   * and draws it with the specified options. For more control, use `drawPath()`
+   * with `appendSvgPath()`.
+   *
+   * By default, the path is filled with black. Specify `borderColor` without
+   * `color` to stroke without filling.
+   *
+   * SVG paths are automatically transformed from SVG coordinate space (Y-down)
+   * to PDF coordinate space (Y-up). Use `x`, `y` to position the path, and
+   * `scale` to resize it.
+   *
+   * @param pathData - SVG path `d` attribute string
+   * @param options - Drawing options (x, y, scale, color, etc.)
+   *
+   * @example
+   * ```typescript
+   * // Draw a Font Awesome heart icon at position (100, 500)
+   * // Icon is 512x512 in SVG, scale to ~50pt
+   * page.drawSvgPath(faHeartPath, {
+   *   x: 100,
+   *   y: 500,
+   *   scale: 0.1,
+   *   color: rgb(1, 0, 0),
+   * });
+   *
+   * // Draw a simple triangle at default position (0, 0)
+   * page.drawSvgPath("M 0 0 L 50 0 L 25 40 Z", {
+   *   color: rgb(0, 0, 1),
+   * });
+   *
+   * // Stroke a curve
+   * page.drawSvgPath("M 0 0 C 10 10, 30 10, 40 0", {
+   *   x: 200,
+   *   y: 300,
+   *   borderColor: rgb(0, 0, 0),
+   *   borderWidth: 2,
+   * });
+   * ```
+   */
+  drawSvgPath(pathData: string, options?: DrawSvgPathOptions): void;
   /** Cached annotations for this page */
   private _annotationCache;
   /**
@@ -5492,6 +5650,9 @@ declare class PDFPage {
   private formatNumber;
   /**
    * Create and register a content stream.
+   *
+   * Accepts either a string (for ASCII-only content like operator names and numbers)
+   * or raw bytes (for content that may contain non-ASCII data).
    */
   private createContentStream;
   /**
@@ -5519,6 +5680,9 @@ declare class PDFPage {
   private registerGraphicsStateForOpacity;
   /**
    * Append operators to the page content stream.
+   *
+   * Uses Operator.toBytes() directly to avoid UTF-8 round-trip corruption
+   * of non-ASCII bytes in PdfString operands (e.g., WinAnsi-encoded text).
    */
   private appendOperators;
   /**
@@ -5527,6 +5691,10 @@ declare class PDFPage {
   private addFontResource;
   /**
    * Encode text to a PDF string for the given font.
+   *
+   * Standard 14 fonts use WinAnsiEncoding (or SymbolEncoding/ZapfDingbatsEncoding).
+   * Unencodable characters are substituted with .notdef (byte 0x00).
+   * Embedded fonts use Identity-H encoding with glyph IDs.
    */
   private encodeTextForFont;
   /**
@@ -9260,5 +9428,5 @@ declare function isWidgetAnnotation(dict: PdfDict, registry?: ObjectRegistry): b
  */
 declare function isPopupAnnotation(dict: PdfDict, registry?: ObjectRegistry): boolean;
 //#endregion
-export { AnnotationFlags, type AnnotationSubtype, type AuthenticationResult, type BorderStyle, type BorderStyleType, type ButtonField, type CMYK, type CaretAnnotationOptions, type CaretSymbol, CertificateChainError, type CheckboxField, type CheckboxOptions, type CheckboxSymbol, type CircleAnnotationOptions, type Color, type CopyPagesOptions, CryptoKeySigner, type Degrees, type DestinationType, type DigestAlgorithm, type DocumentMetadata, type DrawCircleOptions, type DrawEllipseOptions, type DrawFieldOptions, type DrawImageOptions, type DrawLineOptions, type DrawPageOptions, type DrawRectangleOptions, type DrawTextOptions, type DropdownField, type DropdownOptions, type EmbedFontOptions, type EmbeddedFont, type EncryptionAlgorithmOption, type ExtractPagesOptions, type FieldOptions, type FieldType, type FieldValue, type FileAttachmentIcon, type FlattenAllOptions, type FlattenAllResult, type FlattenAnnotationsOptions, type FlattenLayersResult, type FlattenOptions, type FontInput, type FormField, type FormProperties, type FreeTextAnnotationOptions, type FreeTextJustification, GoogleKmsSigner, type Grayscale, type HighlightMode, HttpTimestampAuthority, type HttpTimestampAuthorityOptions, type InkAnnotationOptions, type KeyType, KmsSignerError, type LayerInfo, type LayoutResult, type LineAnnotationOptions, type LineCap, type LineEndingStyle, type LineJoin, type LinkAction, type LinkAnnotationOptions, type LinkDestination, type ListBoxField, type ListboxOptions, type LoadOptions, type MergeOptions, P12Signer, type PAdESLevel, PDF, PDFAnnotation, PDFCaretAnnotation, PDFCircleAnnotation, PDFEmbeddedPage, PDFFileAttachmentAnnotation, PDFForm, PDFFreeTextAnnotation, PDFHighlightAnnotation, PDFImage, PDFInkAnnotation, PDFLineAnnotation, PDFLinkAnnotation, PDFMarkupAnnotation, PDFPage, PDFPolygonAnnotation, PDFPolylineAnnotation, PDFPopupAnnotation, PDFSquareAnnotation, PDFSquigglyAnnotation, PDFStampAnnotation, PDFStrikeOutAnnotation, PDFTextAnnotation, PDFTextMarkupAnnotation, PDFUnderlineAnnotation, PDFUnknownAnnotation, PathBuilder, type PathOptions, PdfArray, PdfBool, PdfDict, PdfName, PdfNull, PdfNumber, type PdfObject, PdfRef, PdfStream, PdfString, type PemBlock, PermissionDeniedError, type PermissionOptions, type Permissions, PlaceholderError, type Point, type PolygonAnnotationOptions, type PolylineAnnotationOptions, type PopupOptions, type PositionedWord, type ProtectionOptions, type RGB, type RadioField, type RadioGroupOptions, type RadioSymbol, type Rect, type Rectangle, type RemoveAnnotationsOptions, RevocationError, type RevocationProvider, type Rotation, type RotationOrigin, type RotationOriginName, STANDARD_STAMPS, type SaveOptions, SecurityError, type SecurityInfo, type SetTitleOptions, type SignOptions, type SignResult, type SignWarning, type SignatureAlgorithm, SignatureError, type SignatureField, type SignatureFieldOptions, type Signer, SignerError, type SquareAnnotationOptions, type StampAnnotationOptions, type StampName, Standard14Font, type Standard14FontName, StandardFonts, type SubFilter, type TextAlignment, type TextAnnotationIcon, type TextAnnotationOptions, type TextAnnotationState, type TextAnnotationStateModel, type TextField, type TextFieldOptions, type TextLine, type TextMarkupAnnotationOptions, type TimestampAuthority, TimestampError, type TrappedStatus, black, blue, cmyk, createAnnotation, degrees, grayscale, green, isPopupAnnotation, isWidgetAnnotation, layoutJustifiedLine, layoutText, lineCapToNumber, lineJoinToNumber, measureText, parsePem, rectToQuadPoints, rectsToQuadPoints, red, rgb, version, white };
+export { AnnotationFlags, type AnnotationSubtype, type AuthenticationResult, type BorderStyle, type BorderStyleType, type ButtonField, type CMYK, type CaretAnnotationOptions, type CaretSymbol, CertificateChainError, type CheckboxField, type CheckboxOptions, type CheckboxSymbol, type CircleAnnotationOptions, type Color, type CopyPagesOptions, CryptoKeySigner, type Degrees, type DestinationType, type DigestAlgorithm, type DocumentMetadata, type DrawCircleOptions, type DrawEllipseOptions, type DrawFieldOptions, type DrawImageOptions, type DrawLineOptions, type DrawPageOptions, type DrawRectangleOptions, type DrawSvgPathOptions, type DrawTextOptions, type DropdownField, type DropdownOptions, type EmbedFontOptions, type EmbeddedFont, type EncryptionAlgorithmOption, type ExtractPagesOptions, type FieldOptions, type FieldType, type FieldValue, type FileAttachmentIcon, type FlattenAllOptions, type FlattenAllResult, type FlattenAnnotationsOptions, type FlattenLayersResult, type FlattenOptions, type FontInput, type FormField, type FormProperties, type FreeTextAnnotationOptions, type FreeTextJustification, GoogleKmsSigner, type Grayscale, type HighlightMode, HttpTimestampAuthority, type HttpTimestampAuthorityOptions, type InkAnnotationOptions, type KeyType, KmsSignerError, type LayerInfo, type LayoutResult, type LineAnnotationOptions, type LineCap, type LineEndingStyle, type LineJoin, type LinkAction, type LinkAnnotationOptions, type LinkDestination, type ListBoxField, type ListboxOptions, type LoadOptions, type MergeOptions, P12Signer, type PAdESLevel, PDF, PDFAnnotation, PDFCaretAnnotation, PDFCircleAnnotation, PDFEmbeddedPage, PDFFileAttachmentAnnotation, PDFForm, PDFFreeTextAnnotation, PDFHighlightAnnotation, PDFImage, PDFInkAnnotation, PDFLineAnnotation, PDFLinkAnnotation, PDFMarkupAnnotation, PDFPage, PDFPolygonAnnotation, PDFPolylineAnnotation, PDFPopupAnnotation, PDFSquareAnnotation, PDFSquigglyAnnotation, PDFStampAnnotation, PDFStrikeOutAnnotation, PDFTextAnnotation, PDFTextMarkupAnnotation, PDFUnderlineAnnotation, PDFUnknownAnnotation, PathBuilder, type PathOptions, PdfArray, PdfBool, PdfDict, PdfName, PdfNull, PdfNumber, type PdfObject, PdfRef, PdfStream, PdfString, type PemBlock, PermissionDeniedError, type PermissionOptions, type Permissions, PlaceholderError, type Point, type PolygonAnnotationOptions, type PolylineAnnotationOptions, type PopupOptions, type PositionedWord, type ProtectionOptions, type RGB, type RadioField, type RadioGroupOptions, type RadioSymbol, type Rect, type Rectangle, type RemoveAnnotationsOptions, RevocationError, type RevocationProvider, type Rotation, type RotationOrigin, type RotationOriginName, STANDARD_STAMPS, type SaveOptions, SecurityError, type SecurityInfo, type SetTitleOptions, type SignOptions, type SignResult, type SignWarning, type SignatureAlgorithm, SignatureError, type SignatureField, type SignatureFieldOptions, type Signer, SignerError, type SquareAnnotationOptions, type StampAnnotationOptions, type StampName, Standard14Font, type Standard14FontName, StandardFonts, type SubFilter, type TextAlignment, type TextAnnotationIcon, type TextAnnotationOptions, type TextAnnotationState, type TextAnnotationStateModel, type TextField, type TextFieldOptions, type TextLine, type TextMarkupAnnotationOptions, type TimestampAuthority, TimestampError, type TrappedStatus, black, blue, cmyk, createAnnotation, degrees, grayscale, green, isPopupAnnotation, isWidgetAnnotation, layoutJustifiedLine, layoutText, lineCapToNumber, lineJoinToNumber, measureText, parsePem, rectToQuadPoints, rectsToQuadPoints, red, rgb, version, white };
 //# sourceMappingURL=index.d.mts.map