# README

## Content

**DsPdfJS API v9.1.3**

***

# @mescius/ds-pdf

# Document Solutions for PDF JS

[ **Document Solutions for PDF JS (DsPdfJS)** ](https://developer.mescius.com/document-solutions/javascript-pdf-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS) is a powerful PDF library for JavaScript and TypeScript that provides a rich set of APIs for fast, memory-efficient PDF and image processing in modern web and server-side environments.

Powered by **WebAssembly (Wasm)**, DsPdfJS runs in browsers and JavaScript runtimes such as **Node.js, Deno, and Bun**. Its core object model follows the PDF specification, providing programmatic access to PDF elements such as document properties, pages, fonts, annotations, forms, and more.

DsPdfJS also includes high-level APIs for creating PDF documents with complex layouts including formatted text, graphics, images, forms, and advanced document workflows.

## Features include:

* Programmatically create, load, modify, save, or inspect PDF documents
* Support for modern PDF standards
* Export PDF pages to raster or vector image formats
* Merge or split PDF documents
* Draw text, shapes, paths, and images with high-level graphics APIs
* Powerful text formatting and layout engine with wrapping, alignment, spacing, tabs, RTL text (including Kashida), and vertical writing
* Advanced font handling with embedding and subsetting support
* Add raster or vector images including PNG, JPEG, SVG, and SVGZ
* Create, edit, fill, or flatten AcroForm PDF forms
* Work with annotations, links, text markup, and rich media
* Find and replace text with configurable search options and exact match positions
* Programmatically create and apply redactions to permanently remove sensitive content
* Encryption and security APIs
* Image processing APIs for resizing, transforming, filtering, drawing, and bitmap generation
* Designed for efficient memory usage through explicit Wasm object lifecycle management
* TypeScript-ready with modern module support

## Compatibility:

DsPdfJS is compatible with:

* Environments:
  * Modern browsers
  * Node.js, Deno, Bun, other Node‑compatible runtimes
* Module formats:
  * ES Modules
  * CommonJS
  * UMD
* TypeScript (type definitions are included)

---

## Latest changes

## [9.1.3] - 08-Jul-2026
### Fixed
- Fixed an issue where `PdfPage.saveAsPng()` generated incorrect results after calling `savePdf()` more than once on the same document. (DOC-7717)
- Fixed an issue where TrueType (TTC) and WOFF fonts were incorrectly embedded in the generated PDF when `FontEmbedMode` was set to `EmbedFullFont`, causing rendering issues in some browsers. (DOC-7719)
- Fixed several issues discovered during an internal code review of the DsPdfJS codebase. (DOC-7714)

## [9.1.2] - 24-Jun-2026
### Fixed
- Fixed an issue where setting the `SoundAnnotation.icon` property to "Speaker" returned a null value instead of preserving the assigned icon name. (DOC-7618)
- Fixed an issue where a `HatchBrush` fill was not applied in the exported PDF when a page was first saved as PNG before saving as PDF. (DOC-7639)
- Fixed an issue where setting `TextField.text` to an empty string threw an exception after exporting form data via `exportFormDataToFDF`. (DOC-7640)
- Fixed an issue in DsPdfJS where reloading a PDF that contained a `LinkAnnotation` with a JavaScript action caused an exception to be thrown. (DOC-7641)

## [9.1.1] - 04-Jun-2026
### Fixed
- Fixed an issue where `PdfDocument.pages.clone()` did not clone form fields and annotations even when `cloneFields` or `cloneAnnotations` parameters were set to `true`. (DOC-7621)
- Fixed an issue where `importFormDataFromFDF()` failed to import some form field data from FDF files. (DOC-7620)
- Fixed an issue where `getText()` returned incorrect content when extracting text from redacted PDFs. (DOC-7617)
- Fixed an issue with inconsistent graphics rendering when applying `RadialGradientBrush` to shapes. (DOC-7570)
- Fixed an issue where `deleteText()` removed content that should not have been deleted. (DOC-7526)

### Changed
- Changed the default angle units for rotation transforms from **Degrees** to **Radians** (to align with the HTML canvas API). If your code passed degree values, convert them to radians or specify angle units explicitly.

### Added
- Added new properties:
  - `get DrawingContext.width(): number;`
  - `get DrawingContext.height(): number;`
  - `get DrawingContext.resolution(): number;`
  - `FormatProperties.allowFontSbits?: boolean;`
  - `get Format.allowFontSbits(): boolean;`

- Added new method overloads:
  - `BilevelBitmap.clip(x: number, y: number, width: number, height: number, metadataOnly?: boolean): BilevelBitmap;`
  - `GrayscaleBitmap.clip(x: number, y: number, width: number, height: number, metadataOnly?: boolean): GrayscaleBitmap;`
  - `Bitmap.resize(width: number, height: number, interpolationMode?: em.InterpolationMode): Bitmap;`
  - `Bitmap.clip(x: number, y: number, width: number, height: number, metadataOnly?: boolean): Bitmap;`
  - `Layout.append(text: string): void;`
  - `Layout.append(text: string, format: Format): void;`
  - `Layout.append(text: string, font: Font, fontSize: number, foreColor: ds.Color): void;`
  - `Layout.appendLine(text: string): void;`
  - `Layout.appendLine(text: string, format: Format): void;`
  - `Layout.appendLine(text: string, font: Font, fontSize: number, foreColor: ds.Color): void;`

## [9.1.0] - 05-May-2026
### Added
- Initial release.

---

## Installation:

```css
npm install @mescius/ds-pdf
```

---

## Getting Started:

### 1. Set the WebAssembly (Wasm) URL

DsPdfJS uses a WebAssembly module. You must point `DsPdfConfig.wasmUrl` to the shipped `.wasm` file:

```javascript
import { DsPdfConfig } from "@mescius/ds-pdf";
DsPdfConfig.wasmUrl = "/node_modules/@mescius/ds-pdf/assets/DsPdf.wasm";
```

---

### 2. (Optional) Apply a License Key

```javascript
// await DsPdfConfig.setLicenseKey("YOUR_LICENSE_KEY");
```

---

### 3. Connect to DsPdfJS

```javascript
import { connectDsPdf } from "@mescius/ds-pdf";
const connected = await connectDsPdf();
if (!connected) throw new Error("Failed to initialize DsPdfJS.");
```

---

## Usage:

### Browser (ES Modules)

```javascript
import { DsPdfConfig, connectDsPdf, PdfDocument, pushObjectManager, popObjectManager
} from "@mescius/ds-pdf";

DsPdfConfig.wasmUrl = "/node_modules/@mescius/ds-pdf/assets/DsPdf.wasm";
// await DsPdfConfig.setLicenseKey("...");

if (!(await connectDsPdf())) throw new Error("Failed to initialize DsPdfJS.");

pushObjectManager();
try {
  const doc = new PdfDocument();
  const page = doc.pages.addNew();
  const ctx = page.context;

  ctx.drawText({ text: "Hello, World!", fontSize: 20 }, 72, 72);

  const pdfData = doc.savePdf();
  // pdfData is a Uint8Array (or equivalent binary buffer)
  return pdfData;
} finally {
  popObjectManager();
}
```

---

### Browser (Pure JavaScript / UMD)

Include the UMD bundle directly:

```html
<script src="node_modules/@mescius/ds-pdf/umd/ds-pdf.js"></script>
<script>
async function createDocument() {
  // UMD bundle exposes global 'DocSol'
  DocSol.DsPdfConfig.wasmUrl = "/node_modules/@mescius/ds-pdf/assets/DsPdf.wasm";
  // await DocSol.DsPdfConfig.setLicenseKey("...");

  const connected = await DocSol.connectDsPdf();
  if (!connected) throw new Error("Failed to initialize DsPdfJS.");

  // Use an ObjectManager to control native/Wasm-backed object lifetimes:
  const om = new DocSol.ObjectManager();
  try {
    const doc = new DocSol.PdfDocument(om);
    const page = doc.pages.addNew();
    const ctx = page.context;

    ctx.drawText({ text: "Hello, World!", fontSize: 20 }, 72, 72);

    return doc.savePdf();
  } finally {
    om.dispose();
  }
}

createDocument()
  .then(pdfData => console.log("PDF created:", pdfData))
  .catch(err => console.error(err));
</script>
```

---

### Node.js (CommonJS)

```javascript
const { DsPdfConfig, connectDsPdf, PdfDocument, ObjectManager } = require("@mescius/ds-pdf");

// Example: set to the package Wasm (adjust to your environment/pathing)
DsPdfConfig.wasmUrl = "./node_modules/@mescius/ds-pdf/assets/DsPdf.wasm";
// await DsPdfConfig.setLicenseKey("...");

(async () => {
  if (!(await connectDsPdf())) throw new Error("Failed to initialize DsPdfJS.");

  const om = new ObjectManager();
  try {
    const doc = new PdfDocument(om);
    const page = doc.pages.addNew();
    const ctx = page.context;

    ctx.drawText({ text: "Hello, World!", fontSize: 20 }, 72, 72);

    const pdfData = doc.savePdf();
    return pdfData;
  } finally {
    om.dispose();
  }
})();
```

---

## Memory Management: ObjectManager

Many objects are backed by Wasm memory. Use one of these patterns to control memory usage:

* Push/pop: `pushObjectManager(); ... popObjectManager();`
* Explicit: `const om = new ObjectManager(); ... om.dispose();`
* Decorator: `@withObjectManager async pdfSample1() { ... }`

This makes sure that intermediate objects are released when no longer needed.

---

## Notes:

* Coordinate units in PDF drawing contexts are “page units” (points) by default (72 units per inch), but can be changed as needed.
* Coordinate units in image drawing contexts are pixels (96 units per inch).

---

## Resources:

* [DsPdfJS Demos](https://developer.mescius.com/document-solutions/javascript-pdf-api/demos/features?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Getting Started Guide](https://developer.mescius.com/document-solutions/javascript-pdf-api/demos/getting-started?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Online Documentation](https://developer.mescius.com/document-solutions/javascript-pdf-api/docs/overview?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [API Reference](https://developer.mescius.com/document-solutions/javascript-pdf-api/api/README?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [License Information](https://developer.mescius.com/document-solutions/licensing?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Licensing FAQ](https://developer.mescius.com/document-solutions/licensing?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS#how-to)
* [How to Get Trial Keys](https://developer.mescius.com/document-solutions/javascript-pdf-api/docs/licensing-and-redistribution?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)

---

## Other Document Solutions Products:

* [Document Solutions for PDF .NET](https://developer.mescius.com/document-solutions/dot-net-pdf-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Document Solutions for Word .NET](https://developer.mescius.com/document-solutions/dot-net-word-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Document Solutions for Excel .NET](https://developer.mescius.com/document-solutions/dot-net-excel-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Document Solutions for Excel Java](https://developer.mescius.com/document-solutions/java-excel-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [Document Solutions for Imaging .NET](https://developer.mescius.com/document-solutions/dot-net-imaging-api?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)

## Document Solutions JavaScript Viewers:

* [JavaScript PDF Viewer and Editor](https://developer.mescius.com/document-solutions/javascript-pdf-viewer?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [JavaScript Data Viewer](https://developer.mescius.com/document-solutions/javascript-data-viewer?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)
* [JavaScript Image Viewer and Editor](https://developer.mescius.com/document-solutions/javascript-image-viewer?utm_source=nuget&utm_medium=documentsolutions&utm_campaign=DsPdfJS)

---

## License:

A commercial license is required for production use.

Each purchase includes one year of updates and support.
Please contact MESCIUS Sales ([us.sales@mescius.com](mailto:us.sales@mescius.com)) for pricing, trial keys, and licensing options.