Refactor render options to use withForms/withAnnotations

Replaces the 'renderForms' and 'initForms' options with 'withForms' and adds 'withAnnotations' throughout the rendering pipeline, including plugin configuration, engine, and example usage. Moves computeFormDrawParams to a helper file for better modularity.

Author: bobsingor

packages/engines/src/lib/pdfium/engine.ts

@@ -122,7 +122,7 @@ import {
   PdfStampFit,
   PdfAddAttachmentParams,
 } from '@embedpdf/models';
-import { isValidCustomKey, readArrayBuffer, readString } from './helper';
+import { computeFormDrawParams, isValidCustomKey, readArrayBuffer, readString } from './helper';
 import { WrappedPdfiumModule } from '@embedpdf/pdfium';
 import { DocumentContext, PageContext, PdfCache } from './cache';
 import { ImageDataConverter, LazyImageData } from '../converters/types';
@@ -155,63 +155,6 @@ export enum RenderFlag {
   REVERSE_BYTE_ORDER = 0x10, // Set whether render in a reverse Byte order, this flag only.
 }
 
-interface FormDrawParams {
-  startX: number;
-  startY: number;
-  formsWidth: number;
-  formsHeight: number;
-  scaleX: number;
-  scaleY: number;
-}
-
-function computeFormDrawParams(matrix: Matrix, rect: Rect, pageSize: Size, rotation: Rotation): FormDrawParams {
-  const rectLeft = rect.origin.x;
-  const rectBottom = rect.origin.y;
-  const rectRight = rectLeft + rect.size.width;
-  const rectTop = rectBottom + rect.size.height;
-  const pageWidth = pageSize.width;
-  const pageHeight = pageSize.height;
-
-  // Extract the per-axis scale that the render matrix applies.
-  const scaleX = Math.hypot(matrix.a, matrix.b);
-  const scaleY = Math.hypot(matrix.c, matrix.d);
-  const swap = (rotation & 1) === 1;
-
-  const formsWidth = swap
-    ? Math.max(1, Math.round(pageHeight * scaleX))
-    : Math.max(1, Math.round(pageWidth * scaleX));
-  const formsHeight = swap
-    ? Math.max(1, Math.round(pageWidth * scaleY))
-    : Math.max(1, Math.round(pageHeight * scaleY));
-
-  let startX: number;
-  let startY: number;
-  switch (rotation) {
-    case Rotation.Degree0:
-      startX = -Math.round(rectLeft * scaleX);
-      startY = -Math.round(rectBottom * scaleY);
-      break;
-    case Rotation.Degree90:
-      startX = Math.round((rectTop - pageHeight) * scaleX);
-      startY = -Math.round(rectLeft * scaleY);
-      break;
-    case Rotation.Degree180:
-      startX = Math.round((rectRight - pageWidth) * scaleX);
-      startY = Math.round((rectTop - pageHeight) * scaleY);
-      break;
-    case Rotation.Degree270:
-      startX = -Math.round(rectBottom * scaleX);
-      startY = Math.round((rectRight - pageWidth) * scaleY);
-      break;
-    default:
-      startX = -Math.round(rectLeft * scaleX);
-      startY = -Math.round(rectBottom * scaleY);
-      break;
-  }
-
-  return { startX, startY, formsWidth, formsHeight, scaleX, scaleY };
-}
-
 const LOG_SOURCE = 'PDFiumEngine';
 const LOG_CATEGORY = 'Engine';
 
@@ -270,8 +213,8 @@ export const browserImageDataToBlobConverter: ImageDataConverter<Blob> = (
     return Promise.reject(
       new OffscreenCanvasError(
         'OffscreenCanvas is not available in this environment. ' +
-        'This converter is intended for browser use only. ' +
-        'Falling back to WASM-based image encoding.',
+          'This converter is intended for browser use only. ' +
+          'Falling back to WASM-based image encoding.',
       ),
     );
   }
@@ -897,9 +840,9 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
     return ok
       ? PdfTaskHelper.resolve(true)
       : PdfTaskHelper.reject({
-        code: PdfErrorCode.Unknown,
-        message: 'one or more metadata fields could not be written',
-      });
+          code: PdfErrorCode.Unknown,
+          message: 'one or more metadata fields could not be written',
+        });
   }
 
   /**
@@ -1143,9 +1086,9 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
     return ok
       ? PdfTaskHelper.resolve(true)
       : PdfTaskHelper.reject({
-        code: PdfErrorCode.Unknown,
-        message: 'failed to clear bookmarks',
-      });
+          code: PdfErrorCode.Unknown,
+          message: 'failed to clear bookmarks',
+        });
   }
 
   /**
@@ -1643,9 +1586,9 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
     return ok
       ? PdfTaskHelper.resolve<boolean>(true)
       : PdfTaskHelper.reject<boolean>({
-        code: PdfErrorCode.CantSetAnnotContent,
-        message: 'failed to update annotation',
-      });
+          code: PdfErrorCode.CantSetAnnotContent,
+          message: 'failed to update annotation',
+        });
   }
 
   /**
@@ -7015,7 +6958,7 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
     const bytes = stride * hDev;
 
     const pageCtx = ctx.acquirePage(page.index);
-    const shouldRenderForms = options?.renderForms ?? false;
+    const shouldRenderForms = options?.withForms ?? false;
     const formHandle = shouldRenderForms ? pageCtx.getFormHandle() : undefined;
 
     // ---- 2) allocate a BGRA bitmap in WASM
@@ -7842,7 +7785,7 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
 
     let cancelled = false;
     task.wait(
-      () => { },
+      () => {},
       (err) => {
         if (err.type === 'abort') cancelled = true;
       },
@@ -7895,12 +7838,12 @@ export class PdfiumEngine<T = Blob> implements PdfEngine<T> {
 
     // Ensure buffer is freed if caller aborts mid-flight
     task.wait(
-      () => { },
+      () => {},
       (err) => {
         if (err.type === 'abort') {
           try {
             this.memoryManager.free(keywordPtr);
-          } catch { }
+          } catch {}
         }
       },
     );

packages/engines/src/lib/pdfium/helper.ts

@@ -1,3 +1,4 @@
+import { Matrix, Rotation, Rect, Size } from '@embedpdf/models';
 import { PdfiumRuntimeMethods, PdfiumModule } from '@embedpdf/pdfium';
 
 /**
@@ -92,3 +93,65 @@ export function isValidCustomKey(key: string): boolean {
   }
   return true;
 }
+
+interface FormDrawParams {
+  startX: number;
+  startY: number;
+  formsWidth: number;
+  formsHeight: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+export function computeFormDrawParams(
+  matrix: Matrix,
+  rect: Rect,
+  pageSize: Size,
+  rotation: Rotation,
+): FormDrawParams {
+  const rectLeft = rect.origin.x;
+  const rectBottom = rect.origin.y;
+  const rectRight = rectLeft + rect.size.width;
+  const rectTop = rectBottom + rect.size.height;
+  const pageWidth = pageSize.width;
+  const pageHeight = pageSize.height;
+
+  // Extract the per-axis scale that the render matrix applies.
+  const scaleX = Math.hypot(matrix.a, matrix.b);
+  const scaleY = Math.hypot(matrix.c, matrix.d);
+  const swap = (rotation & 1) === 1;
+
+  const formsWidth = swap
+    ? Math.max(1, Math.round(pageHeight * scaleX))
+    : Math.max(1, Math.round(pageWidth * scaleX));
+  const formsHeight = swap
+    ? Math.max(1, Math.round(pageWidth * scaleY))
+    : Math.max(1, Math.round(pageHeight * scaleY));
+
+  let startX: number;
+  let startY: number;
+  switch (rotation) {
+    case Rotation.Degree0:
+      startX = -Math.round(rectLeft * scaleX);
+      startY = -Math.round(rectBottom * scaleY);
+      break;
+    case Rotation.Degree90:
+      startX = Math.round((rectTop - pageHeight) * scaleX);
+      startY = -Math.round(rectLeft * scaleY);
+      break;
+    case Rotation.Degree180:
+      startX = Math.round((rectRight - pageWidth) * scaleX);
+      startY = Math.round((rectTop - pageHeight) * scaleY);
+      break;
+    case Rotation.Degree270:
+      startX = -Math.round(rectBottom * scaleX);
+      startY = Math.round((rectRight - pageWidth) * scaleY);
+      break;
+    default:
+      startX = -Math.round(rectLeft * scaleX);
+      startY = -Math.round(rectBottom * scaleY);
+      break;
+  }
+
+  return { startX, startY, formsWidth, formsHeight, scaleX, scaleY };
+}

packages/models/src/pdf.ts

@@ -2515,7 +2515,7 @@ export interface PdfRenderPageOptions extends PdfRenderOptions {
   /**
    * Whether to render interactive form widgets
    */
-  renderForms?: boolean;
+  withForms?: boolean;
 }
 
 export interface PdfRenderPageAnnotationOptions extends PdfRenderOptions {

packages/plugin-render/src/lib/render-plugin.ts

@@ -16,7 +16,8 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
   static readonly id = 'render' as const;
 
   private readonly refreshPages$ = createEmitter<number[]>();
-  private initForms = false;
+  private withForms = false;
+  private withAnnotations = false;
 
   constructor(id: string, registry: PluginRegistry) {
     super(id, registry);
@@ -27,7 +28,8 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
   }
 
   async initialize(config: RenderPluginConfig): Promise<void> {
-    this.initForms = config.initForms ?? false;
+    this.withForms = config.withForms ?? false;
+    this.withAnnotations = config.withAnnotations ?? false;
   }
 
   protected buildCapability(): RenderCapability {
@@ -55,7 +57,8 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
 
     const mergedOptions = {
       ...(options ?? {}),
-      renderForms: options?.renderForms ?? this.initForms,
+      withForms: options?.withForms ?? this.withForms,
+      withAnnotations: options?.withAnnotations ?? this.withAnnotations,
     };
 
     return this.engine.renderPage(coreState.document, page, mergedOptions);
@@ -75,7 +78,8 @@ export class RenderPlugin extends BasePlugin<RenderPluginConfig, RenderCapabilit
 
     const mergedOptions = {
       ...(options ?? {}),
-      renderForms: options?.renderForms ?? this.initForms,
+      withForms: options?.withForms ?? this.withForms,
+      withAnnotations: options?.withAnnotations ?? this.withAnnotations,
     };
 
     return this.engine.renderPageRect(coreState.document, page, rect, mergedOptions);

packages/plugin-render/src/lib/types.ts

@@ -6,7 +6,12 @@ export interface RenderPluginConfig extends BasePluginConfig {
    * Initialize and draw form widgets during renders.
    * Defaults to `false`.
    */
-  initForms?: boolean;
+  withForms?: boolean;
+  /**
+   * Whether to render annotations
+   * Defaults to `false`.
+   */
+  withAnnotations?: boolean;
 }
 
 export interface RenderPageRectOptions {