@jackgreen2018/pdf-engine 1.0.113 → 1.0.114

package/README.md

@@ -17,6 +17,7 @@ A high-performance PDF processing library for Node.js and the browser. Built wit
 - **PDF Encryption**: Encrypt PDFs with RC4 (V1/V2) or AES-128 (V4) using user/owner passwords
 - **PDF Decryption**: Decrypt password-protected PDFs
 - **Encrypted Detection**: Check if a PDF is encrypted with `isEncrypted()`
+- **Stamp Image**: Overlay PNG/JPEG images onto PDF pages with `stampImage()`
 - **Privacy**: All processing happens in the user's browser or local environment
 - **Performance**: Rust-powered with WASM for maximum speed
 
@@ -73,6 +74,16 @@ const encrypted = await pdfEngine.encrypt(
 // Check if encrypted
 const isEnc = await pdfEngine.isEncrypted(new Uint8Array(arrayBuffer));
 
+// Stamp an image onto a PDF page
+const stampedPdf = await pdfEngine.stampImage(
+  new Uint8Array(arrayBuffer),
+  imageBuffer,
+  100,   // x position
+  100,   // y position
+  50,    // width
+  50,    // height
+);
+
 // Decrypt a password-protected PDF
 const decrypted = await pdfEngine.decrypt(encrypted, "user-password");
 ```
@@ -130,16 +141,18 @@ npm run benchmark
 
 | Operation | pdf-engine (ms) | pdf-lib (ms) |
 |-----------|-----------------|--------------|
-| Page Count | 0.73 | 1.48 |
-| Text Extraction | 0.30 | — |
-| Merge (2 files) | 0.79 | 4.49 |
-| Split (pages [0,1]) | 0.24 | 2.39 |
+| Page Count | 0.72 | 1.59 |
+| Text Extraction | 0.23 | — |
+| Merge (2 files) | 0.80 | 4.06 |
+| Split (pages [0,1]) | 0.24 | 1.77 |
 | Encrypt (V4 AES-128) | 0.79 | — |
-| Decrypt | 0.38 | — |
+| Decrypt | 0.32 | — |
+| Stamp Image (1x1 PNG) | 1.24 | — |
 
 *extractText correctness: PASS — gated via `tests/fixtures/text-fixture.pdf` (FlateDecode-compressed, real-world content stream). v1.0.30 fixes extractText to return actual text instead of "No text extracted."*
+*stampImage: PASS — v1.0.114 fixes empty-page stamping (pages without /Contents now initialize empty content stream before image insertion).*
 
-*Run 2026-08-03 (v1.0.113); raw JSON at benchmark-results.json.*
+*Run 2026-08-04 (v1.0.114); raw JSON at benchmark-results.json.*
 
 ## License
 

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export declare function split(buffer: Uint8Array, pages: number[]): Promise<Uint
 export declare function isEncrypted(buffer: Uint8Array): Promise<boolean>;
 export declare function encrypt(buffer: Uint8Array, userPassword: string, ownerPassword: string, version?: number): Promise<Uint8Array>;
 export declare function decrypt(buffer: Uint8Array, password: string): Promise<Uint8Array>;
+export declare function stampImage(buffer: Uint8Array, imageBuffer: Uint8Array, x: number, y: number, width: number, height: number): Promise<Uint8Array>;
 export declare class PdfEngineImpl {
     constructor();
     private initialized;
@@ -17,6 +18,7 @@ export declare class PdfEngineImpl {
     isEncrypted(buffer: Uint8Array): Promise<boolean>;
     encrypt(buffer: Uint8Array, userPassword: string, ownerPassword: string, version?: number): Promise<Uint8Array>;
     decrypt(buffer: Uint8Array, password: string): Promise<Uint8Array>;
+    stampImage(buffer: Uint8Array, imageBuffer: Uint8Array, x: number, y: number, width: number, height: number): Promise<Uint8Array>;
 }
 declare const pdfEngine: PdfEngineImpl;
 export default pdfEngine;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAErE;AAED,wBAAsB,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAGzE;AAED,wBAAsB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGtF;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtE;AAED,wBAAsB,OAAO,CACzB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,OAAO,SAAI,GACZ,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGvF;AAED,qBAAa,aAAa;IACtB,cAEC;IACD,OAAO,CAAC,WAAW,CAAS;IAEtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAEK,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtD;IAEK,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGrD;IAEK,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAGzD;IAEK,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGtE;IAEK,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtD;IAEK,OAAO,CACT,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,OAAO,SAAI,GACZ,OAAO,CAAC,UAAU,CAAC,CAGrB;IAEK,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGvE;CACJ;AAED,QAAA,MAAM,SAAS,eAAsB,CAAC;eACvB,SAAS"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAErE;AAED,wBAAsB,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAGzE;AAED,wBAAsB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGtF;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtE;AAED,wBAAsB,OAAO,CACzB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,OAAO,SAAI,GACZ,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGvF;AAED,wBAAsB,UAAU,CAC5B,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,UAAU,EACvB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED,qBAAa,aAAa;IACtB,cAEC;IACD,OAAO,CAAC,WAAW,CAAS;IAEtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAEK,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtD;IAEK,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGrD;IAEK,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAGzD;IAEK,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGtE;IAEK,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtD;IAEK,OAAO,CACT,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,OAAO,SAAI,GACZ,OAAO,CAAC,UAAU,CAAC,CAGrB;IAEK,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGvE;IAEK,UAAU,CACZ,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,UAAU,EACvB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAGrB;CACJ;AAED,QAAA,MAAM,SAAS,eAAsB,CAAC;eACvB,SAAS"}

package/dist/index.js

@@ -29,6 +29,10 @@ export async function decrypt(buffer, password) {
     const result = await wasm.decrypt(buffer, password);
     return result;
 }
+export async function stampImage(buffer, imageBuffer, x, y, width, height) {
+    const result = await wasm.stamp_image(buffer, imageBuffer, x, y, width, height);
+    return result;
+}
 export class PdfEngineImpl {
     constructor() {
         this.initialized = false;
@@ -68,6 +72,10 @@ export class PdfEngineImpl {
         await this.init();
         return await decrypt(buffer, password);
     }
+    async stampImage(buffer, imageBuffer, x, y, width, height) {
+        await this.init();
+        return await stampImage(buffer, imageBuffer, x, y, width, height);
+    }
 }
 const pdfEngine = new PdfEngineImpl();
 export default pdfEngine;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackgreen2018/pdf-engine",
-  "version": "1.0.113",
+  "version": "1.0.114",
   "license": "MIT",
   "repository": {
     "type": "git",

package/pkg/README.md

@@ -130,12 +130,12 @@ npm run benchmark
 
 | Operation | pdf-engine (ms) | pdf-lib (ms) |
 |-----------|-----------------|--------------|
-| Page Count | 0.73 | 1.48 |
-| Text Extraction | 0.30 | — |
-| Merge (2 files) | 0.79 | 4.49 |
-| Split (pages [0,1]) | 0.24 | 2.39 |
-| Encrypt (V4 AES-128) | 0.79 | — |
-| Decrypt | 0.38 | — |
+| Page Count | 0.80 | 1.60 |
+| Text Extraction | 0.47 | — |
+| Merge (2 files) | 1.06 | 3.92 |
+| Split (pages [0,1]) | 0.20 | 1.69 |
+| Encrypt (V4 AES-128) | 0.81 | — |
+| Decrypt | 0.35 | — |
 
 *extractText correctness: PASS — gated via `tests/fixtures/text-fixture.pdf` (FlateDecode-compressed, real-world content stream). v1.0.30 fixes extractText to return actual text instead of "No text extracted."*
 

package/pkg/pdf_engine.d.ts

@@ -1,6 +1,28 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Chroma subsampling format
+ */
+export enum ChromaSampling {
+    /**
+     * Both vertically and horizontally subsampled.
+     */
+    Cs420 = 0,
+    /**
+     * Horizontally subsampled.
+     */
+    Cs422 = 1,
+    /**
+     * Not subsampled.
+     */
+    Cs444 = 2,
+    /**
+     * Monochrome.
+     */
+    Cs400 = 3,
+}
+
 export function decrypt(buffer: Uint8Array, password: string): Uint8Array;
 
 export function encrypt(buffer: Uint8Array, user_password: string, owner_password: string, version: number): Uint8Array;
@@ -18,3 +40,16 @@ export function is_encrypted(buffer: Uint8Array): boolean;
 export function merge(pdf_buffers: Array<any>): Uint8Array;
 
 export function split(buffer: Uint8Array, pages: Array<any>): Array<any>;
+
+/**
+ * Stamp (composite) an image onto a single-page PDF.
+ *
+ * `x`, `y` are the bottom-left position in PDF user-space coordinates
+ * (points, origin at bottom-left by default). `width` and `height` are in
+ * the same units. The image is stretched to fill the given rectangle.
+ *
+ * ponytail: uses lopdf::xobject::image_from (embed_image feature) which
+ * supports PNG and JPEG via the image crate; the image crate is
+ * wasm-compatible with the png/jpeg features enabled.
+ */
+export function stamp_image(buffer: Uint8Array, image_buffer: Uint8Array, x: number, y: number, width: number, height: number): Uint8Array;

package/pkg/pdf_engine.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./pdf_engine_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    decrypt, encrypt, extract_text, get_page_count, get_pdf_info, init, is_encrypted, merge, split
+    ChromaSampling, decrypt, encrypt, extract_text, get_page_count, get_pdf_info, init, is_encrypted, merge, split, stamp_image
 } from "./pdf_engine_bg.js";

package/pkg/pdf_engine_bg.js

@@ -1,3 +1,26 @@
+/**
+ * Chroma subsampling format
+ * @enum {0 | 1 | 2 | 3}
+ */
+export const ChromaSampling = Object.freeze({
+    /**
+     * Both vertically and horizontally subsampled.
+     */
+    Cs420: 0, "0": "Cs420",
+    /**
+     * Horizontally subsampled.
+     */
+    Cs422: 1, "1": "Cs422",
+    /**
+     * Not subsampled.
+     */
+    Cs444: 2, "2": "Cs444",
+    /**
+     * Monochrome.
+     */
+    Cs400: 3, "3": "Cs400",
+});
+
 /**
  * @param {Uint8Array} buffer
  * @param {string} password
@@ -147,6 +170,36 @@ export function split(buffer, pages) {
     }
     return takeFromExternrefTable0(ret[0]);
 }
+
+/**
+ * Stamp (composite) an image onto a single-page PDF.
+ *
+ * `x`, `y` are the bottom-left position in PDF user-space coordinates
+ * (points, origin at bottom-left by default). `width` and `height` are in
+ * the same units. The image is stretched to fill the given rectangle.
+ *
+ * ponytail: uses lopdf::xobject::image_from (embed_image feature) which
+ * supports PNG and JPEG via the image crate; the image crate is
+ * wasm-compatible with the png/jpeg features enabled.
+ * @param {Uint8Array} buffer
+ * @param {Uint8Array} image_buffer
+ * @param {number} x
+ * @param {number} y
+ * @param {number} width
+ * @param {number} height
+ * @returns {Uint8Array}
+ */
+export function stamp_image(buffer, image_buffer, x, y, width, height) {
+    const ptr0 = passArray8ToWasm0(buffer, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArray8ToWasm0(image_buffer, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.stamp_image(ptr0, len0, ptr1, len1, x, y, width, height);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
 export function __wbg___wbindgen_number_get_394265ed1e1b84ee(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'number' ? obj : undefined;

package/pkg/pdf_engine_bg.wasm.d.ts

@@ -10,6 +10,7 @@ export const init: () => [number, number];
 export const is_encrypted: (a: number, b: number) => [number, number, number];
 export const merge: (a: any) => [number, number, number];
 export const split: (a: number, b: number, c: any) => [number, number, number];
+export const stamp_image: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
 export const __wbindgen_exn_store: (a: number) => void;
 export const __externref_table_alloc: () => number;
 export const __wbindgen_externrefs: WebAssembly.Table;

package/src/index.ts

@@ -44,6 +44,18 @@ export async function decrypt(buffer: Uint8Array, password: string): Promise<Uin
     return result;
 }
 
+export async function stampImage(
+    buffer: Uint8Array,
+    imageBuffer: Uint8Array,
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+): Promise<Uint8Array> {
+    const result = await wasm.stamp_image(buffer, imageBuffer, x, y, width, height);
+    return result;
+}
+
 export class PdfEngineImpl {
     constructor() {
         this.initialized = false;
@@ -96,6 +108,18 @@ export class PdfEngineImpl {
         await this.init();
         return await decrypt(buffer, password);
     }
+
+    async stampImage(
+        buffer: Uint8Array,
+        imageBuffer: Uint8Array,
+        x: number,
+        y: number,
+        width: number,
+        height: number,
+    ): Promise<Uint8Array> {
+        await this.init();
+        return await stampImage(buffer, imageBuffer, x, y, width, height);
+    }
 }
 
 const pdfEngine = new PdfEngineImpl();

package/src/lib.rs

@@ -376,6 +376,53 @@ pub fn decrypt(buffer: &[u8], password: &str) -> Result<Uint8Array, JsValue> {
     Ok(Uint8Array::new_from_slice(&buf))
 }
 
+/// Stamp (composite) an image onto a single-page PDF.
+///
+/// `x`, `y` are the bottom-left position in PDF user-space coordinates
+/// (points, origin at bottom-left by default). `width` and `height` are in
+/// the same units. The image is stretched to fill the given rectangle.
+///
+/// ponytail: uses lopdf::xobject::image_from (embed_image feature) which
+/// supports PNG and JPEG via the image crate; the image crate is
+/// wasm-compatible with the png/jpeg features enabled.
+#[wasm_bindgen]
+pub fn stamp_image(
+    buffer: &[u8],
+    image_buffer: &[u8],
+    x: f64,
+    y: f64,
+    width: f64,
+    height: f64,
+) -> Result<Uint8Array, JsValue> {
+    let mut doc = Document::load_mem(buffer)
+        .map_err(|e| JsValue::from_str(&format!("PDF load error: {}", e)))?;
+
+    let pages = doc.get_pages();
+    if pages.is_empty() {
+        return Err(JsValue::from_str("PDF has no pages"));
+    }
+    let page_id = *pages.values().next().unwrap();
+
+    // ponytail: pdf-lib creates pages without a /Contents key; insert_image
+    // requires one. Add an empty stream if missing so the page can accept
+    // the image overlay.
+    if doc.get_page_content(page_id).is_empty() {
+        doc.add_page_contents(page_id, Vec::new())
+            .map_err(|e| JsValue::from_str(&format!("Page content init error: {}", e)))?;
+    }
+
+    let img_stream = lopdf::xobject::image_from(image_buffer.to_vec())
+        .map_err(|e| JsValue::from_str(&format!("Image decode error: {}", e)))?;
+
+    doc.insert_image(page_id, img_stream, (x as f32, y as f32), (width as f32, height as f32))
+        .map_err(|e| JsValue::from_str(&format!("Insert image error: {}", e)))?;
+
+    let mut buf = Vec::new();
+    doc.save_to(&mut buf)
+        .map_err(|e| JsValue::from_str(&format!("Save error: {}", e)))?;
+    Ok(Uint8Array::new_from_slice(&buf))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;