@embedpdf/engine-services 3.0.0-next.1 → 3.0.0-next.11

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { PdfFunctions, PdfRuntimeMemory, PdfRuntimeModule, Ptr } from "@embedpdf/engine-runtime";
-import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometrySnapshot, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
+import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryRun, PageGeometrySnapshot, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNetworkRenderFormat, PageObjectNumber, PageRaster, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfQuad, PdfRect, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
 //#region src/runtime/lifecycle/bootstrap.d.ts
 /**
  * Initialize the thread-confined PDFium runtime for the calling thread. Each
@@ -580,6 +580,15 @@ declare class PagesInserter {
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   insert(bytes: ArrayBuffer, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
+  /**
+   * Create `count` blank pages of `size` at `destIndex`. Same mutation
+   * contract as `insert`, but native creation (`FPDFPage_New`) instead of a
+   * deep copy: no source document, so none of the retain-until-close
+   * lifetime hazard above. Each page gets an empty content stream
+   * (`FPDFPage_GenerateContent`) so the saved PDF renders identically in
+   * third-party viewers.
+   */
+  insertBlank(spec: PageInsertBlankSpec, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
 }
 //#endregion
 //#region src/features/pages/PagesFlattener.d.ts
@@ -626,29 +635,33 @@ declare class RedactionApplier {
    */
   private preflight;
   private applyAllOnPage;
+  private pageHasRedactAnnotations;
   private applyRefsOnPage;
 }
 //#endregion
 //#region src/features/text/PageTextReader.d.ts
 /**
  * Per-page slow-path text reader. Acquires a `pagePtr` from the
- * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
- * extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
- * and releases everything in reverse order.
+ * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+ * the page text, and releases everything in reverse order.
+ *
+ * Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+ * CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+ * `text` is the TEXT projection. The two diverge when a character
+ * contributes zero text units (non-printing) or two (supplementary plane);
+ * `charMap` anchors encode exactly those deviations.
  *
- * Memory model:
- *   - `count` is in UTF-16 code units (FPDFText's "char").
- *   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
- *     trailing NUL terminator).
- *   - `mem.readU16String` walks the buffer up to the NUL and decodes
- *     to a JS string, faithfully preserving surrogate pairs.
+ * Both come from the fork's batched extension calls, which share one
+ * encoding authority (`FX_UTF16Encode`) so text and map can never
+ * disagree:
  *
- * Errors:
- *   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
- *     (raised by `PagePtrPool.acquire`).
- *   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
- *     not happen on a healthy page; treat it as a runtime bug rather
- *     than user error.
+ *   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+ *     characters arrive as surrogate pairs instead of being silently
+ *     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+ *     upper-bound buffer (2 units per character + NUL), so no measure
+ *     round-trip.
+ *   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+ *     anchors is the common (identity) page and skips the fill call.
  */
 declare class PageTextReader {
   private readonly runtime;
@@ -658,21 +671,93 @@ declare class PageTextReader {
 }
 //#endregion
 //#region src/features/geometry/PageGeometryReader.d.ts
+/**
+ * One glyph as read from `EPDFText_GetCharGeometry`, plus the run-grouping
+ * context sampled alongside it. Pure data — no native handles — so the
+ * grouping stage below is a pure function the tests can drive directly.
+ */
+interface RawGeometryGlyphRecord {
+  /** Grouping key: the glyph's text object handle (opaque identity). */
+  objectKey: number | bigint;
+  /** Sampled at each text object's first glyph (run splits inherit it). */
+  fontSize?: number;
+  /**
+   * Wire flags (bit 1 = space, bit 2 = empty). Synthesized-but-visible
+   * glyphs (/ActualText pieces) stay 0, exactly like the legacy reader —
+   * they represent real, selectable text.
+   */
+  flags: number;
+  /** Page-space AABB (zeroed when empty). */
+  looseBox: PdfRect;
+  tightBox?: PdfRect;
+  /** Oriented cells — real glyphs with a usable (non-singular) matrix only. */
+  looseQuad?: PdfQuad;
+  tightQuad?: PdfQuad;
+  /** Native uprightness of the char matrix (empty glyphs: true, inert). */
+  upright: boolean;
+  /** Baseline angle (radians CCW, PDF y-up); 0 when upright. */
+  rotation: number;
+  /** True when the ascent vector maps opposite the rotated +y (det < 0). */
+  ascentFlip: boolean;
+}
 /**
  * Geometry-only text layout reader.
  *
  * Emits geometry in PDF user space (y-up edges) — the canonical engine
  * geometry. The viewer converts to content/view space via the page geometry
  * matrix; this reader applies NO Y-flip or device transform.
+ *
+ * One `EPDFText_GetCharGeometry` call per glyph supplies boxes, oriented
+ * cells, and flags together; `buildRunsFromRawGlyphs` then groups glyphs
+ * into the upright/rotated run union. Upright runs are byte-identical to the
+ * pre-orientation reader (quads the native layer offers are deliberately
+ * dropped — the dominant case never pays for orientation).
  */
 declare class PageGeometryReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageGeometrySnapshot;
-  private buildRunsFromGlyphs;
-  private readGlyphInfo;
+  private readGlyphRaw;
 }
+/**
+ * Group per-glyph records into the run union. Pure — exported for tests.
+ *
+ * Runs split on text-object change (the legacy rule) and on orientation
+ * change between classifiable glyphs (θ drift / mixed orientation). A run's
+ * variant is decided by its FIRST classifiable glyph:
+ *   - empty glyphs never classify (they adopt the run's variant);
+ *   - real glyphs WITHOUT an oriented cell (singular matrix, synthesized
+ *     /ActualText pieces) classify as upright — box-only data degrades to
+ *     exactly the legacy behavior;
+ *   - real glyphs with a non-upright matrix classify as rotated.
+ * Runs that never see a classifiable glyph emit as upright (degenerate,
+ * legacy behavior).
+ */
+declare function buildRunsFromRawGlyphs(records: RawGeometryGlyphRecord[]): PageGeometryRun[];
+//#endregion
+//#region src/runtime/memory/structs.d.ts
+/** Generated from `EPDF_CHAR_GEOMETRY`; pinned by native static_asserts. */
+declare const EPDF_CHAR_GEOMETRY_LAYOUT: {
+  readonly bytes: 124;
+  readonly offsets: {
+    readonly looseBox: 0;
+    readonly tightBox: 16;
+    readonly looseQuad: 32;
+    readonly tightQuad: 64;
+    readonly matrix: 96;
+    readonly flags: 120;
+  };
+  readonly flags: {
+    readonly hasTightBox: number;
+    readonly hasLooseQuad: number;
+    readonly hasTightQuad: number;
+    readonly upright: number;
+    readonly space: number;
+    readonly empty: number;
+    readonly synthesized: number;
+  };
+};
 //#endregion
 //#region src/features/render/PageRenderReader.d.ts
 declare class PageRenderReader {
@@ -1311,22 +1396,38 @@ declare class SearchReader {
 }
 //#endregion
 //#region src/features/actions/ActionModelReader.d.ts
-/** Mutable aggregate budget shared by every action model in one read job. */
+/** Mutable aggregate budget shared by every action model in one read job.
+ *  Payload budgets are RESERVED before the backing buffer is allocated. */
 declare class ActionReadBudgetTracker {
   private readonly limits;
   private models;
   private nodes;
   private scriptCodeUnits;
+  private targetEntries;
+  private payloadCodeUnits;
   constructor(limits?: ActionReadBudget);
   addModel(nodeCount: number): void;
   addScript(script: string): void;
+  /** Charge target entries BEFORE the target array is walked. */
+  reserveTargets(count: number): void;
+  /** Charge payload text BEFORE the scratch buffer for it is allocated. */
+  reservePayloadBytes(length: number): void;
   private assertWithinBudget;
 }
 /**
  * Convert and close one detached native action model. This is the only
  * native-model walker used by document, page, field, and annotation reads.
+ *
+ * `docPtr` resolves `goto` destinations (page identity + named-destination
+ * lookup); every caller reads within an open document session.
+ *
+ * Payload rule: a node whose payload cannot be materialised (a goto without
+ * a resolvable destination, a javascript node with no `/JS`, a withheld
+ * target list) degrades to `{ type: 'unknown' }` with its original `/S` on
+ * `subtype`, and the tree gains the `'payload-dropped'` warning — impossible
+ * states stay unrepresentable while malformed documents stay readable.
  */
-declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
+declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, docPtr: Ptr, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
 //#endregion
 //#region src/features/actions/DocumentActionsReader.d.ts
 /** Read catalog-owned actions. Extraction only; no action is executed. */
@@ -1338,6 +1439,29 @@ declare class DocumentActionsReader {
 }
 //#endregion
 //#region src/worker-host/WorkerHost.d.ts
+/** The image a {@link WorkerImageEncoder} produced. `bytes` must OWN its
+ *  buffer (a fresh allocation, not a pooled `Buffer` slab view) — it is
+ *  placed on the transfer manifest and moved zero-copy. */
+interface WorkerEncodedImage {
+  contentType: string;
+  bytes: Uint8Array;
+}
+/**
+ * Injected image-encode capability for the `*.renderEncoded` wire kinds.
+ * Dependency inversion keeps the native encoder OUT of this shared
+ * package: the cloud server's worker entry injects a sharp/libvips
+ * implementation; browser/local entries inject nothing (they encode via
+ * canvas) and the encoded kinds reject with `NotImplemented`.
+ */
+interface WorkerImageEncoder {
+  encode(raster: PageRaster, opts: {
+    format: PageNetworkRenderFormat;
+    quality?: number;
+  }): Promise<WorkerEncodedImage>;
+}
+interface WorkerHostOptions {
+  imageEncoder?: WorkerImageEncoder;
+}
 /**
  * The piece that runs "inside the worker": owns runtime, manages document
  * sessions, dispatches requests to the engine-services synchronous code.
@@ -1359,6 +1483,8 @@ declare class WorkerHost {
    * runs in.
    */
   private readonly post;
+  /** Optional capabilities. See {@link WorkerHostOptions}. */
+  private readonly options;
   private readonly sessions;
   private readonly baseDocuments;
   private readonly aborts;
@@ -1380,7 +1506,9 @@ declare class WorkerHost {
    * pack.transfer)` — the host doesn't know which environment it
    * runs in.
    */
-  post: (pack: WirePack<WorkerResponse>) => void);
+  post: (pack: WirePack<WorkerResponse>) => void,
+  /** Optional capabilities. See {@link WorkerHostOptions}. */
+  options?: WorkerHostOptions);
   /**
    * Register deployment-owned fonts on this worker thread, after init and
    * before serving requests. Server-only: the cloud engine never exposes font
@@ -1410,6 +1538,7 @@ declare class WorkerHost {
   private handleRedactionApply;
   private handlePagesExtract;
   private handlePagesInsert;
+  private handlePagesInsertBlank;
   private handleAttachmentsList;
   private handleAttachmentsReadFile;
   private handleAttachmentsCreate;
@@ -1423,6 +1552,11 @@ declare class WorkerHost {
   private handlePagesGeometry;
   private handleSearchQuery;
   private handlePagesRender;
+  private receiveEncoded;
+  private encodeRaster;
+  private handlePagesRenderEncoded;
+  private handleDocumentRenderPageFileEncoded;
+  private handleAnnotationsRenderAppearancesEncoded;
   private handleDocumentSaveBuffer;
   private handleDocumentSaveFile;
   private handleDocumentSaveLayerBuffer;
@@ -1477,5 +1611,5 @@ declare class WorkerHost {
   private saveLayerArtifact;
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, type ImpactInputs, type LayerSource, LocalRevisionAuthority, MetadataMutator, MetadataReader, type MutationKind, type OpenedPdfDocument, type OpenedPdfDocumentKind, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, type StartupFontSpec, WorkerHost, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, type ImpactInputs, type LayerSource, LocalRevisionAuthority, MetadataMutator, MetadataReader, type MutationKind, type OpenedPdfDocument, type OpenedPdfDocumentKind, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, type RawGeometryGlyphRecord, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, type StartupFontSpec, type WorkerEncodedImage, WorkerHost, type WorkerHostOptions, type WorkerImageEncoder, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometrySnapshot, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
+import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryRun, PageGeometrySnapshot, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNetworkRenderFormat, PageObjectNumber, PageRaster, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfQuad, PdfRect, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
 import { PdfFunctions, PdfRuntimeMemory, PdfRuntimeModule, Ptr } from "@embedpdf/engine-runtime";
 //#region src/runtime/lifecycle/bootstrap.d.ts
 /**
@@ -580,6 +580,15 @@ declare class PagesInserter {
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   insert(bytes: ArrayBuffer, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
+  /**
+   * Create `count` blank pages of `size` at `destIndex`. Same mutation
+   * contract as `insert`, but native creation (`FPDFPage_New`) instead of a
+   * deep copy: no source document, so none of the retain-until-close
+   * lifetime hazard above. Each page gets an empty content stream
+   * (`FPDFPage_GenerateContent`) so the saved PDF renders identically in
+   * third-party viewers.
+   */
+  insertBlank(spec: PageInsertBlankSpec, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
 }
 //#endregion
 //#region src/features/pages/PagesFlattener.d.ts
@@ -626,29 +635,33 @@ declare class RedactionApplier {
    */
   private preflight;
   private applyAllOnPage;
+  private pageHasRedactAnnotations;
   private applyRefsOnPage;
 }
 //#endregion
 //#region src/features/text/PageTextReader.d.ts
 /**
  * Per-page slow-path text reader. Acquires a `pagePtr` from the
- * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
- * extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
- * and releases everything in reverse order.
+ * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+ * the page text, and releases everything in reverse order.
+ *
+ * Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+ * CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+ * `text` is the TEXT projection. The two diverge when a character
+ * contributes zero text units (non-printing) or two (supplementary plane);
+ * `charMap` anchors encode exactly those deviations.
  *
- * Memory model:
- *   - `count` is in UTF-16 code units (FPDFText's "char").
- *   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
- *     trailing NUL terminator).
- *   - `mem.readU16String` walks the buffer up to the NUL and decodes
- *     to a JS string, faithfully preserving surrogate pairs.
+ * Both come from the fork's batched extension calls, which share one
+ * encoding authority (`FX_UTF16Encode`) so text and map can never
+ * disagree:
  *
- * Errors:
- *   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
- *     (raised by `PagePtrPool.acquire`).
- *   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
- *     not happen on a healthy page; treat it as a runtime bug rather
- *     than user error.
+ *   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+ *     characters arrive as surrogate pairs instead of being silently
+ *     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+ *     upper-bound buffer (2 units per character + NUL), so no measure
+ *     round-trip.
+ *   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+ *     anchors is the common (identity) page and skips the fill call.
  */
 declare class PageTextReader {
   private readonly runtime;
@@ -658,21 +671,93 @@ declare class PageTextReader {
 }
 //#endregion
 //#region src/features/geometry/PageGeometryReader.d.ts
+/**
+ * One glyph as read from `EPDFText_GetCharGeometry`, plus the run-grouping
+ * context sampled alongside it. Pure data — no native handles — so the
+ * grouping stage below is a pure function the tests can drive directly.
+ */
+interface RawGeometryGlyphRecord {
+  /** Grouping key: the glyph's text object handle (opaque identity). */
+  objectKey: number | bigint;
+  /** Sampled at each text object's first glyph (run splits inherit it). */
+  fontSize?: number;
+  /**
+   * Wire flags (bit 1 = space, bit 2 = empty). Synthesized-but-visible
+   * glyphs (/ActualText pieces) stay 0, exactly like the legacy reader —
+   * they represent real, selectable text.
+   */
+  flags: number;
+  /** Page-space AABB (zeroed when empty). */
+  looseBox: PdfRect;
+  tightBox?: PdfRect;
+  /** Oriented cells — real glyphs with a usable (non-singular) matrix only. */
+  looseQuad?: PdfQuad;
+  tightQuad?: PdfQuad;
+  /** Native uprightness of the char matrix (empty glyphs: true, inert). */
+  upright: boolean;
+  /** Baseline angle (radians CCW, PDF y-up); 0 when upright. */
+  rotation: number;
+  /** True when the ascent vector maps opposite the rotated +y (det < 0). */
+  ascentFlip: boolean;
+}
 /**
  * Geometry-only text layout reader.
  *
  * Emits geometry in PDF user space (y-up edges) — the canonical engine
  * geometry. The viewer converts to content/view space via the page geometry
  * matrix; this reader applies NO Y-flip or device transform.
+ *
+ * One `EPDFText_GetCharGeometry` call per glyph supplies boxes, oriented
+ * cells, and flags together; `buildRunsFromRawGlyphs` then groups glyphs
+ * into the upright/rotated run union. Upright runs are byte-identical to the
+ * pre-orientation reader (quads the native layer offers are deliberately
+ * dropped — the dominant case never pays for orientation).
  */
 declare class PageGeometryReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageGeometrySnapshot;
-  private buildRunsFromGlyphs;
-  private readGlyphInfo;
+  private readGlyphRaw;
 }
+/**
+ * Group per-glyph records into the run union. Pure — exported for tests.
+ *
+ * Runs split on text-object change (the legacy rule) and on orientation
+ * change between classifiable glyphs (θ drift / mixed orientation). A run's
+ * variant is decided by its FIRST classifiable glyph:
+ *   - empty glyphs never classify (they adopt the run's variant);
+ *   - real glyphs WITHOUT an oriented cell (singular matrix, synthesized
+ *     /ActualText pieces) classify as upright — box-only data degrades to
+ *     exactly the legacy behavior;
+ *   - real glyphs with a non-upright matrix classify as rotated.
+ * Runs that never see a classifiable glyph emit as upright (degenerate,
+ * legacy behavior).
+ */
+declare function buildRunsFromRawGlyphs(records: RawGeometryGlyphRecord[]): PageGeometryRun[];
+//#endregion
+//#region src/runtime/memory/structs.d.ts
+/** Generated from `EPDF_CHAR_GEOMETRY`; pinned by native static_asserts. */
+declare const EPDF_CHAR_GEOMETRY_LAYOUT: {
+  readonly bytes: 124;
+  readonly offsets: {
+    readonly looseBox: 0;
+    readonly tightBox: 16;
+    readonly looseQuad: 32;
+    readonly tightQuad: 64;
+    readonly matrix: 96;
+    readonly flags: 120;
+  };
+  readonly flags: {
+    readonly hasTightBox: number;
+    readonly hasLooseQuad: number;
+    readonly hasTightQuad: number;
+    readonly upright: number;
+    readonly space: number;
+    readonly empty: number;
+    readonly synthesized: number;
+  };
+};
 //#endregion
 //#region src/features/render/PageRenderReader.d.ts
 declare class PageRenderReader {
@@ -1311,22 +1396,38 @@ declare class SearchReader {
 }
 //#endregion
 //#region src/features/actions/ActionModelReader.d.ts
-/** Mutable aggregate budget shared by every action model in one read job. */
+/** Mutable aggregate budget shared by every action model in one read job.
+ *  Payload budgets are RESERVED before the backing buffer is allocated. */
 declare class ActionReadBudgetTracker {
   private readonly limits;
   private models;
   private nodes;
   private scriptCodeUnits;
+  private targetEntries;
+  private payloadCodeUnits;
   constructor(limits?: ActionReadBudget);
   addModel(nodeCount: number): void;
   addScript(script: string): void;
+  /** Charge target entries BEFORE the target array is walked. */
+  reserveTargets(count: number): void;
+  /** Charge payload text BEFORE the scratch buffer for it is allocated. */
+  reservePayloadBytes(length: number): void;
   private assertWithinBudget;
 }
 /**
  * Convert and close one detached native action model. This is the only
  * native-model walker used by document, page, field, and annotation reads.
+ *
+ * `docPtr` resolves `goto` destinations (page identity + named-destination
+ * lookup); every caller reads within an open document session.
+ *
+ * Payload rule: a node whose payload cannot be materialised (a goto without
+ * a resolvable destination, a javascript node with no `/JS`, a withheld
+ * target list) degrades to `{ type: 'unknown' }` with its original `/S` on
+ * `subtype`, and the tree gains the `'payload-dropped'` warning — impossible
+ * states stay unrepresentable while malformed documents stay readable.
  */
-declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
+declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, docPtr: Ptr, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
 //#endregion
 //#region src/features/actions/DocumentActionsReader.d.ts
 /** Read catalog-owned actions. Extraction only; no action is executed. */
@@ -1338,6 +1439,29 @@ declare class DocumentActionsReader {
 }
 //#endregion
 //#region src/worker-host/WorkerHost.d.ts
+/** The image a {@link WorkerImageEncoder} produced. `bytes` must OWN its
+ *  buffer (a fresh allocation, not a pooled `Buffer` slab view) — it is
+ *  placed on the transfer manifest and moved zero-copy. */
+interface WorkerEncodedImage {
+  contentType: string;
+  bytes: Uint8Array;
+}
+/**
+ * Injected image-encode capability for the `*.renderEncoded` wire kinds.
+ * Dependency inversion keeps the native encoder OUT of this shared
+ * package: the cloud server's worker entry injects a sharp/libvips
+ * implementation; browser/local entries inject nothing (they encode via
+ * canvas) and the encoded kinds reject with `NotImplemented`.
+ */
+interface WorkerImageEncoder {
+  encode(raster: PageRaster, opts: {
+    format: PageNetworkRenderFormat;
+    quality?: number;
+  }): Promise<WorkerEncodedImage>;
+}
+interface WorkerHostOptions {
+  imageEncoder?: WorkerImageEncoder;
+}
 /**
  * The piece that runs "inside the worker": owns runtime, manages document
  * sessions, dispatches requests to the engine-services synchronous code.
@@ -1359,6 +1483,8 @@ declare class WorkerHost {
    * runs in.
    */
   private readonly post;
+  /** Optional capabilities. See {@link WorkerHostOptions}. */
+  private readonly options;
   private readonly sessions;
   private readonly baseDocuments;
   private readonly aborts;
@@ -1380,7 +1506,9 @@ declare class WorkerHost {
    * pack.transfer)` — the host doesn't know which environment it
    * runs in.
    */
-  post: (pack: WirePack<WorkerResponse>) => void);
+  post: (pack: WirePack<WorkerResponse>) => void,
+  /** Optional capabilities. See {@link WorkerHostOptions}. */
+  options?: WorkerHostOptions);
   /**
    * Register deployment-owned fonts on this worker thread, after init and
    * before serving requests. Server-only: the cloud engine never exposes font
@@ -1410,6 +1538,7 @@ declare class WorkerHost {
   private handleRedactionApply;
   private handlePagesExtract;
   private handlePagesInsert;
+  private handlePagesInsertBlank;
   private handleAttachmentsList;
   private handleAttachmentsReadFile;
   private handleAttachmentsCreate;
@@ -1423,6 +1552,11 @@ declare class WorkerHost {
   private handlePagesGeometry;
   private handleSearchQuery;
   private handlePagesRender;
+  private receiveEncoded;
+  private encodeRaster;
+  private handlePagesRenderEncoded;
+  private handleDocumentRenderPageFileEncoded;
+  private handleAnnotationsRenderAppearancesEncoded;
   private handleDocumentSaveBuffer;
   private handleDocumentSaveFile;
   private handleDocumentSaveLayerBuffer;
@@ -1477,5 +1611,5 @@ declare class WorkerHost {
   private saveLayerArtifact;
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, type ImpactInputs, type LayerSource, LocalRevisionAuthority, MetadataMutator, MetadataReader, type MutationKind, type OpenedPdfDocument, type OpenedPdfDocumentKind, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, type StartupFontSpec, WorkerHost, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, type ImpactInputs, type LayerSource, LocalRevisionAuthority, MetadataMutator, MetadataReader, type MutationKind, type OpenedPdfDocument, type OpenedPdfDocumentKind, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, type RawGeometryGlyphRecord, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, type StartupFontSpec, type WorkerEncodedImage, WorkerHost, type WorkerHostOptions, type WorkerImageEncoder, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
 //# sourceMappingURL=index.d.ts.map