@embedpdf/models 2.5.0 → 2.6.1

package/dist/pdf.d.ts

@@ -913,6 +913,17 @@ export interface PdfAnnotationObjectBase {
      * Rectangle of the annotation
      */
     rect: Rect;
+    /**
+     * Rotation angle in degrees (clockwise).
+     * When set, the annotation is visually rotated around its center.
+     * The rect becomes the axis-aligned bounding box after rotation.
+     */
+    rotation?: number;
+    /**
+     * The original unrotated rectangle of the annotation.
+     * This is stored when rotation is applied, allowing accurate editing.
+     */
+    unrotatedRect?: Rect;
     /**
      * Custom data of the annotation
      */
@@ -1824,11 +1835,11 @@ export interface PdfRedactAnnoObject extends PdfAnnotationObjectBase {
      */
     segmentRects: Rect[];
     /**
-     * Interior color - the preview color shown BEFORE redaction is applied
+     * Interior color (IC) - the fill color used to paint the redacted area after redaction is applied
      */
     color?: string;
     /**
-     * Overlay color - the fill color shown AFTER redaction is applied
+     * Overlay text color - the color of the overlay text displayed on the redacted area
      */
     overlayColor?: string;
     /**
@@ -2163,6 +2174,56 @@ export interface PdfPageGeometry {
      */
     runs: PdfRun[];
 }
+/**
+ * Font information extracted from a PDF text object.
+ *
+ * @public
+ */
+export interface PdfFontInfo {
+    /** PostScript name (e.g. "HOEPNL+Arial,Bold"). */
+    name: string;
+    /** Font family name (e.g. "Arial"). */
+    familyName: string;
+    /** Weight 100-900 (400 = normal, 700 = bold). */
+    weight: number;
+    /** Whether the font is italic. */
+    italic: boolean;
+    /** Whether the font is monospaced (fixed-pitch). */
+    monospaced: boolean;
+    /** Whether the font data is embedded in the PDF. */
+    embedded: boolean;
+}
+/**
+ * A rich text run: consecutive characters sharing the same text object,
+ * font, size, and color.
+ *
+ * @public
+ */
+export interface PdfTextRun {
+    /** The text content (UTF-8). */
+    text: string;
+    /** Bounding box in PDF page coordinates (points). */
+    rect: Rect;
+    /** Font metadata (uniform within the run). */
+    font: PdfFontInfo;
+    /** Font size in points. */
+    fontSize: number;
+    /** Fill color (RGBA). */
+    color: PdfAlphaColor;
+    /** Start character index in the text page. */
+    charIndex: number;
+    /** Number of characters in this run. */
+    charCount: number;
+}
+/**
+ * Rich text runs for a single page.
+ *
+ * @public
+ */
+export interface PdfPageTextRuns {
+    /** Text runs ordered by reading order. */
+    runs: PdfTextRun[];
+}
 /**
  * form field value
  * @public
@@ -2463,6 +2524,12 @@ export interface PdfRenderPageAnnotationOptions extends PdfRenderOptions {
      * Appearance mode normal down or rollover
      */
     mode?: AppearanceMode;
+    /**
+     * When true and annotation.unrotatedRect is present, render using the
+     * unrotated path (ignores AP Matrix rotation). Falls back to normal
+     * rendering if unrotatedRect is not available on the annotation.
+     */
+    unrotated?: boolean;
 }
 export interface PdfRenderThumbnailOptions extends PdfRenderOptions {
     /**
@@ -2628,6 +2695,26 @@ export interface PdfEngine<T = Blob> {
      * @returns task contains the rendered image or error
      */
     renderPageRect: (doc: PdfDocumentObject, page: PdfPageObject, rect: Rect, options?: PdfRenderPageOptions) => PdfTask<T>;
+    /**
+     * Render the specified pdf page and return raw pixel data (ImageDataLike)
+     * without encoding to the output format T. Useful for AI/ML pipelines
+     * that need direct pixel access.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @param options - render options (imageType/imageQuality are ignored)
+     * @returns task contains raw ImageDataLike or error
+     */
+    renderPageRaw: (doc: PdfDocumentObject, page: PdfPageObject, options?: PdfRenderPageOptions) => PdfTask<ImageDataLike>;
+    /**
+     * Render the specified rect of a pdf page and return raw pixel data
+     * (ImageDataLike) without encoding to the output format T.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @param rect - target rect in PDF coordinate space
+     * @param options - render options (imageType/imageQuality are ignored)
+     * @returns task contains raw ImageDataLike or error
+     */
+    renderPageRectRaw: (doc: PdfDocumentObject, page: PdfPageObject, rect: Rect, options?: PdfRenderPageOptions) => PdfTask<ImageDataLike>;
     /**
      * Render the thumbnail of specified pdf page
      * @param doc - pdf document
@@ -2812,6 +2899,13 @@ export interface PdfEngine<T = Blob> {
      * @returns task contains the geometry
      */
     getPageGeometry: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfPageGeometry>;
+    /**
+     * Get rich text runs for a page, grouped by text object with font and color info
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @returns task contains the text runs
+     */
+    getPageTextRuns: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfPageTextRuns>;
     /**
      * Merge multiple pdf documents
      * @param files - all the pdf files
@@ -2957,6 +3051,7 @@ export interface IPdfiumExecutor {
     getTextSlices(doc: PdfDocumentObject, slices: PageTextSlice[]): PdfTask<string[]>;
     getPageGlyphs(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfGlyphObject[]>;
     getPageGeometry(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfPageGeometry>;
+    getPageTextRuns(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfPageTextRuns>;
     merge(files: PdfFile[]): PdfTask<PdfFile>;
     mergePages(mergeConfigs: Array<{
         docId: string;

package/dist/task-sequence.d.ts

@@ -0,0 +1,69 @@
+import { Task } from './task';
+/**
+ * Utility for composing sequential Task operations within an async function,
+ * while preserving abort propagation and optional progress forwarding.
+ *
+ * Bridges the gap between the Task "push" model (callbacks, abort, progress)
+ * and the async/await "pull" model, without losing Task benefits.
+ *
+ * @example
+ * ```ts
+ * function doWork(): Task<Result, MyError, MyProgress> {
+ *   const task = new Task<Result, MyError, MyProgress>();
+ *   const seq = new TaskSequence(task);
+ *
+ *   seq.execute(
+ *     async () => {
+ *       const data = await seq.run(() => fetchDataAsTask());
+ *       const result = await seq.runWithProgress(
+ *         () => processAsTask(data),
+ *         (childProgress) => ({ stage: 'processing', ...childProgress }),
+ *       );
+ *       task.resolve(result);
+ *     },
+ *     (err) => ({ type: 'failed', message: String(err) }),
+ *   );
+ *
+ *   return task;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class TaskSequence<TError, TProgress> {
+    private parentTask;
+    private activeChild;
+    private disposed;
+    constructor(parentTask: Task<any, TError, TProgress>);
+    /**
+     * Execute a child Task and return its result as a Promise.
+     *
+     * If the parent task has been aborted, throws `TaskAbortedError` immediately.
+     * If the parent task is aborted while the child is running, the child is aborted too.
+     */
+    run<R>(factory: () => Task<R, any, any>): Promise<R>;
+    /**
+     * Execute a child Task and return its result as a Promise,
+     * forwarding the child's progress events to the parent task
+     * through the provided mapper function.
+     *
+     * If the parent task has been aborted, throws `TaskAbortedError` immediately.
+     * If the parent task is aborted while the child is running, the child is aborted too.
+     */
+    runWithProgress<R, CP>(factory: () => Task<R, any, CP>, mapProgress: (childProgress: CP) => TProgress): Promise<R>;
+    /**
+     * Execute an async function body that uses `run()` / `runWithProgress()`,
+     * automatically handling abort and error routing to the parent task.
+     *
+     * - If the body throws `TaskAbortedError`, it is silently ignored
+     *   (the parent task was already aborted via the abort override).
+     * - If the body throws `TaskRejectedError` (from a child task rejection
+     *   via `run()` / `runWithProgress()`), its `.reason` is forwarded directly
+     *   to the parent task, bypassing `mapError`.
+     * - Any other thrown error is mapped through `mapError` and used to
+     *   reject the parent task. This handles unexpected runtime exceptions
+     *   in the async body itself.
+     * - On success, the body is responsible for calling `parentTask.resolve()`.
+     */
+    execute(fn: () => Promise<void>, mapError: (err: unknown) => TError): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/models",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "private": false,
   "description": "Shared type definitions, data models, and utility helpers (geometry, tasks, logging, PDF primitives) that underpin every package in the EmbedPDF ecosystem.",
   "type": "module",