@embedpdf/engine-core 3.0.0-next.11 → 3.0.0-next.13

package/dist/{Engine-CWnAKccD.d.ts → Engine-DxtpCYcP.d.ts}

@@ -1,5 +1,5 @@
-import { $i as AnnotationUpdateResult, $r as FormEffectsResult, Dr as SearchRequest, Fa as AttachmentDeleteResult, Fn as RedactionApplyScope, Fo as FontKey, Gn as PageDeleteResult, Gr as FormFieldUpdateResult, Ho as AnnotationAppearanceImagesResult, Hr as FormDataExport, Ic as AnnotationRef, Io as FontSpec, Jr as FormSetValueResult, Js as MetadataPatch, Ki as FormFieldRef, Kr as FormImportResult, Mn as MetadataUpdateResult, Ni as FormFieldDTO, Or as SearchSlice, Pa as AttachmentCreateResult, Pn as RedactionApplyResult, Po as FontHandle, Qi as AnnotationMoveResult, Ro as PdfSaveMode, Ts as PageTextSnapshot, Un as PageInsertBlankSpec, Ur as FormFieldCreateResult, Vn as PageFlattenUsage, Vo as AnnotationAppearanceImageOptions, Wn as PageInsertResult, Wr as FormFieldDeleteResult, Ws as PageListSnapshot, Xi as AnnotationCreateResult, Xn as PageMoveResult, Xr as FormEffect, Yo as AnnotationAppearancesResult, Yr as FormWidgetLinkResult, Ys as OpenInput, Za as AttachmentContent, Zi as AnnotationDeleteResult, _i as FormFieldDraft, ai as FormSubmissionRequest, ci as FormFieldValue, di as FormFieldPatch, ds as PageRenderOptions, eo as AttachmentFileSource, fl as PdfRotation, hl as DocumentActionsSnapshot, jl as DocumentMetadata, kl as PageObjectNumber, l as AnnotationPatch, ms as PageRenderViewport, n as AnnotationListSnapshotAllPages, nc as OpenOptions, no as EmbeddedFileRef, o as AnnotationDraft, qi as FormWidgetRef, qn as PageRotateResult, qo as AnnotationAppearanceRenderOptions, qr as FormRepairResult, ri as FormSubmissionReceipt, rs as PageImageOptions, si as FormDataFormat, ss as PageRaster, t as AnnotationListPageSnapshot, to as EmbeddedFileItem, ts as PageImageHandle, vs as PageGeometrySnapshot, wi as FormSnapshot, zn as PageFlattenResult } from "./AnnotationListSnapshot-C1U3XUxP.js";
-import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-7nL9aY75.js";
+import { $n as PageNameResult, $r as FormImportResult, Ac as PageTextSnapshot, Bl as SignaturePrepareInput, Bn as PageDeleteResult, Ca as FormSnapshot, Cc as PageGeometrySnapshot, Cl as BaseVersionInfo, Do as AttachmentCreateResult, Fl as SignatureCompleteInput, Fn as RedactionApplyScope, Fr as SearchSlice, Ga as AnnotationCreateResult, Gs as FontSpec, Hn as PageRotateResult, Hs as FontHandle, Il as SignatureCompleteResult, Ja as AnnotationUpdateResult, Jo as EmbeddedFileItem, Js as PdfSaveMode, Ka as AnnotationDeleteResult, Ma as FormFieldDTO, Mi as AnalyzeInput, Mn as MetadataUpdateResult, Nl as SignatureAbortResult, Oo as AttachmentDeleteResult, Pi as ChangeAnalysis, Pl as SignatureAppearanceInput, Pn as RedactionApplyResult, Pr as SearchRequest, Qi as FormEffectsResult, Qn as PageFlattenUsage, Qr as FormFieldUpdateResult, Rn as PageInsertBlankSpec, Vl as SignaturePrepared, Wl as SignatureSnapshot, Wo as AttachmentContent, Ws as FontKey, Xn as PageFlattenResult, Xr as FormFieldCreateResult, Xs as AnnotationAppearanceImageOptions, Yc as PageListSnapshot, Yi as FormEffect, Yo as EmbeddedFileRef, Yr as FormDataExport, Zr as FormFieldDeleteResult, Zs as AnnotationAppearanceImagesResult, _d as PageObjectNumber, cc as PageImageOptions, ed as PdfRotation, ei as FormRepairResult, er as PageNameInput, eu as FormFieldRef, fc as PageRaster, ga as FormFieldDraft, gc as PageRenderOptions, ia as FormSubmissionRequest, ic as AnnotationAppearancesResult, l as AnnotationPatch, ll as OpenOptions, n as AnnotationListSnapshotAllPages, na as FormSubmissionReceipt, nc as AnnotationAppearanceRenderOptions, ni as FormWidgetLinkResult, nl as OpenInput, o as AnnotationDraft, oa as FormDataFormat, oc as PageImageHandle, qa as AnnotationMoveResult, qn as AnnotationFlattenResult, qo as AttachmentFileSource, rd as DocumentActionsSnapshot, rr as PageMoveResult, sa as FormFieldValue, t as AnnotationListPageSnapshot, ti as FormSetValueResult, tl as MetadataPatch, tr as PageRemoveNameInput, tu as FormWidgetRef, ua as FormFieldPatch, wl as DigestAlgorithm, wu as AnnotationRef, yc as PageRenderViewport, yd as DocumentMetadata, zn as PageInsertResult } from "./AnnotationListSnapshot-D3mFut1e.js";
+import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-_JRjqvoI.js";
 //#region src/engine/DocumentActionsService.d.ts
 /** Lazy, catalog-owned PDF action read. This API extracts; it never executes. */
 interface DocumentActionsService {
@@ -83,6 +83,31 @@ interface DocumentAttachmentsService {
   delete?(ref: EmbeddedFileRef): AbortablePromise<AttachmentDeleteResult>;
 }
 //#endregion
+//#region src/engine/DocumentFontSettings.d.ts
+/**
+ * How much of a registered font's program the appearances authored in this
+ * document carry. `default` subsets annotation text (FreeText, redaction
+ * labels) and embeds form-field text whole; `subset` and `full` apply to
+ * both. A font whose licence forbids subsetting is embedded whole under
+ * every policy; programs already in the document are never re-embedded.
+ */
+type FontEmbeddingPolicy = 'default' | 'subset' | 'full';
+/**
+ * Per-document font and text-layout settings: session state of this
+ * document handle, never written to the file, applied to appearances
+ * generated after the call. Local engine only (`doc.fonts` is undefined on
+ * engines that do not lay text out in-process).
+ */
+interface DocumentFontSettings {
+  setEmbeddingPolicy(policy: FontEmbeddingPolicy): AbortablePromise<void>;
+  /**
+   * Latin typographic features (kerning, ligatures) when shaping rich text.
+   * Off by default: Acrobat's appearances show plain advance widths and no
+   * ligatures, and parity with what Acrobat draws wins.
+   */
+  setTypographicFeatures(enabled: boolean): AbortablePromise<void>;
+}
+//#endregion
 //#region src/engine/DocumentFormsService.d.ts
 /** Options for {@link DocumentFormsService.repair}. */
 interface FormRepairOptions {
@@ -181,6 +206,14 @@ interface DocumentFormsService {
    * `form.fieldUpdated`.
    */
   updateField(ref: FormFieldRef, patch: FormFieldPatch): AbortablePromise<FormFieldUpdateResult>;
+  /**
+   * Draw a PDF page into every widget of an UNSIGNED signature field — the
+   * visual "sign" of a viewer that has no signer. The field's value stays
+   * empty and nothing is sealed; a signed field is refused. Gated by
+   * `doc.forms.fill`. Emits `form.fieldUpdated`. Absent on engines that
+   * cannot draw appearances.
+   */
+  setSignatureAppearance?(ref: FormFieldRef, appearance: SignatureAppearanceInput): AbortablePromise<FormFieldUpdateResult>;
   /**
    * Delete a terminal field and cascade: every widget is removed from its
    * page, the field leaves the tree, and empty ancestors are pruned.
@@ -262,6 +295,25 @@ interface DocumentPagesService {
    * recycled; surviving pages keep their identity and revisions.
    */
   delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;
+  /**
+   * Register `name` → page in the catalog's `/Names /Pages` tree (create,
+   * or replace what an existing key points at); with `replace`, drop that
+   * other key in the same job (rename). Named pages are LAYOUT — read them
+   * back from `list().namedPages` — so this is a page-structure mutation:
+   * `docVersion` + `layoutVersion` advance, per-page pins do not. Gated like
+   * `move` (`doc.pages.assemble`). Optional while transports ship;
+   * feature-detect with `pages.setName !== undefined`.
+   *
+   * Rejects with `InvalidArg` for an empty name and `NotFound` for a page
+   * that is not in the page tree (hidden templates included).
+   */
+  setName?(input: PageNameInput): AbortablePromise<PageNameResult>;
+  /**
+   * Remove one `/Names /Pages` registration; the page itself is untouched.
+   * `NotFound` when no registration has that decoded key. Page DELETION
+   * removes registrations by itself — callers never need to pair the two.
+   */
+  removeName?(input: PageRemoveNameInput): AbortablePromise<PageNameResult>;
   /**
    * Paint eligible annotation appearances into page content and remove only
    * those annotations that were painted. This changes content and annotation
@@ -320,9 +372,12 @@ interface DocumentPagesService {
  * rewrites THIS LAYER's bytes only. The immutable base document still
  * contains the original content — byte-perfect original recovery is a
  * feature of the storage model, not a leak. Redacted content becomes truly
- * unrecoverable only in what leaves the system: a layer download/export, or
- * a local document saved after apply. Surfaces that promise "permanent
- * removal" must scope that promise to the exported artifact.
+ * unrecoverable only in a full-rewrite export after apply. Callers MUST select
+ * `download({ mode: 'rewrite' })` (or the corresponding file/cloud save mode)
+ * before sharing the redacted PDF. The default incremental download preserves
+ * the original content in prior revisions; apply does not change that default.
+ * Surfaces that promise "permanent removal" must scope that promise to the
+ * full-rewrite exported artifact.
  *
  * Applying is irreversible within the layer (no undo). Emits a
  * `redaction.applied` document event; content-scope raster invalidation and
@@ -469,6 +524,64 @@ interface DocumentSearchService {
   query(request: SearchRequest): AbortablePromise<SearchSlice>;
 }
 //#endregion
+//#region src/engine/DocumentSignaturesService.d.ts
+/**
+ * Digital signatures on the document: the read side (what is signed, what
+ * it seals, what it forbids) and the two-phase signing protocol. The
+ * engine does the PDF job — candidate file, digest, sealing — and never
+ * holds a key; the CMS comes from the caller (`@embedpdf/core-signature`
+ * builds one from a raw signer, or a signing service returns it).
+ *
+ * Every read here describes the bytes the document was loaded from
+ * (for a layer document: base + the delta it was opened with). Unsaved
+ * edits are not part of any revision until `prepare` snapshots them.
+ *
+ * Reads ride `doc.forms.read`; `revisionBytes` rides `doc.download`;
+ * `prepare`/`complete`/`abort` ride `doc.sign`, a certification
+ * additionally `doc.sign.certify`.
+ */
+interface DocumentSignaturesService {
+  /** Revisions, every signature field with its signed state, and the protection in force. */
+  list(): AbortablePromise<SignatureSnapshot>;
+  /** The DER `/Contents` of a signed field (exactly `contentsSize` bytes, padding stripped). `NotFound` for an unsigned field. */
+  contents(field: FormFieldRef): AbortablePromise<Uint8Array>;
+  /**
+   * Hash the signed field's `/ByteRange` with `algorithm`, straight from
+   * the loaded bytes. What a CMS verifier compares its message digest to.
+   */
+  digest(field: FormFieldRef, algorithm: DigestAlgorithm): AbortablePromise<Uint8Array>;
+  /** The exact bytes of revision `revisionIndex` (`[0, end)`): what a signature over it signed. */
+  revisionBytes(revisionIndex: number): AbortablePromise<Uint8Array>;
+  /**
+   * What changed after a signature (or after any revision), judged
+   * revision by revision against the restrictions in force: every object
+   * whose cross-reference mapping moved, with its value and every
+   * reference to it in both revisions, and the rule that explains each —
+   * or the reference no rule explains. `until: 'working-copy'` snapshots
+   * unsaved edits as one more revision first. A truncated value is never
+   * permitted; a broken chain is `indeterminate`.
+   */
+  analyze(input: AnalyzeInput): AbortablePromise<ChangeAnalysis>;
+  /**
+   * Build the candidate (unsaved edits become their own revision, the
+   * signature lands in a fresh update over it), seal it, and return the
+   * digest to sign. The live document is untouched and read-only until
+   * `complete` or `abort` (`SigningPending`). Refusals are
+   * `SignatureRefused` with the reason in the message.
+   */
+  prepare(input: SignaturePrepareInput): AbortablePromise<SignaturePrepared>;
+  /**
+   * Write the CMS into the candidate and install the sealed bytes as the
+   * document's new version. `expectedVersion` must be what `prepare`
+   * returned (`SigningVersionMismatch` otherwise). Idempotent: a replay
+   * with the same CMS answers `already-completed`. Emits
+   * `signature.completed` and `document.versioned`.
+   */
+  complete(input: SignatureCompleteInput): AbortablePromise<SignatureCompleteResult>;
+  /** Discard a pending candidate. */
+  abort(signingId: string): AbortablePromise<SignatureAbortResult>;
+}
+//#endregion
 //#region src/engine/MetadataService.d.ts
 interface MetadataService {
   read(): AbortablePromise<DocumentMetadata>;
@@ -539,6 +652,30 @@ interface PageAnnotationsService {
    *                space, in `[0, count - refs.length]`.
    */
   move(refs: AnnotationRef[], toIndex: number): AbortablePromise<AnnotationMoveResult>;
+  /**
+   * Flatten the given annotations of THIS page into its content —
+   * `pages.flatten` for a chosen set. Painted annotations are removed from
+   * the page; ones that are ineligible (hidden for `usage`, Popups, no
+   * usable appearance) stay and report `skipped`, so a caller can say
+   * "2 of 3 flattened". A content + annotation MUTATION of this page: its
+   * content and annotation pins advance, layout does not; a
+   * `annotations.flattened` event is published when anything was applied.
+   * Gated like `pages.flatten` (`doc.pages.modify` + `doc.annotate.modify`).
+   * `InvalidArg` for a ref on another page; `NotFound` for an unknown ref.
+   * Optional while transports ship — feature-detect.
+   */
+  flatten?(refs: AnnotationRef[], usage?: PageFlattenUsage): AbortablePromise<AnnotationFlattenResult>;
+  /**
+   * Flatten the normal appearances of the given annotations of this page
+   * into a NEW single-page PDF sized to their union `/Rect` — vector,
+   * positions preserved, exactly as this page shows them. The same plan as
+   * `flatten` aimed at a fresh page; the source document is untouched. A
+   * derived READ that egresses content, so it is gated by `doc.download`
+   * like `pages.extract`. All-or-nothing: `InvalidArg` when any ref is not
+   * on this page, hidden, or has no appearance (a stamp silently missing a
+   * part would be worse than an error). Optional — feature-detect.
+   */
+  exportAppearance?(refs: AnnotationRef[]): AbortablePromise<Uint8Array>;
 }
 //#endregion
 //#region src/engine/PageGeometryService.d.ts
@@ -745,6 +882,9 @@ type DocumentEvent = ({
   pageObjectNumber: PageObjectNumber;
   origin: EventOrigin;
 } & AnnotationMoveResult) | ({
+  type: 'annotations.flattened';
+  origin: EventOrigin;
+} & AnnotationFlattenResult) | ({
   type: 'pages.moved';
   /** Locally: the moved block. Remotely the audit row only records the
    *  outcome, so this is the full new order — consumers should read
@@ -769,6 +909,13 @@ type DocumentEvent = ({
   destIndex?: number;
   origin: EventOrigin;
 } & PageInsertResult) | ({
+  type: 'pages.named';
+  /** The decoded key that was registered, renamed, or removed. */
+  name: string;
+  /** The page it now points at; `null` when the registration was removed. */
+  pageObjectNumber: PageObjectNumber | null;
+  origin: EventOrigin;
+} & PageNameResult) | ({
   type: 'attachment.created';
   origin: EventOrigin;
 } & AttachmentCreateResult) | ({
@@ -813,6 +960,30 @@ type DocumentEvent = ({
   type: 'redaction.applied';
   origin: EventOrigin;
 } & RedactionApplyResult) | {
+  /** A signing candidate was parked: the document is read-only until it completes or aborts. */
+  type: 'signature.prepared';
+  signingId: string;
+  field: FormFieldRef;
+  origin: EventOrigin;
+} | ({
+  /** The sealed bytes are installed; `version` is what they became. */
+  type: 'signature.completed';
+  signingId: string;
+  origin: EventOrigin;
+} & SignatureCompleteResult) | {
+  type: 'signature.aborted';
+  signingId: string;
+  origin: EventOrigin;
+} | {
+  /**
+   * The session moved to a new saved version (a completed signature,
+   * here or in another session). Byte-level facts — revisions,
+   * coverage, digests, verdicts — must be re-read.
+   */
+  type: 'document.versioned';
+  version: BaseVersionInfo;
+  origin: EventOrigin;
+} | {
   /**
    * Cloud only: the live event stream fell too far behind to replay
    * (the server's SSE `full-refresh`) — state derived from earlier
@@ -883,6 +1054,13 @@ interface DocumentHandle {
   readonly attachments?: DocumentAttachmentsService;
   /** The document's interactive form (AcroForm): fields, values, interchange. */
   readonly forms: DocumentFormsService;
+  /**
+   * Font embedding and text layout settings of this document (session
+   * state). Optional: the local engine implements it; engines that do not
+   * lay text out in-process omit it — feature-detect with
+   * `doc.fonts !== undefined`.
+   */
+  readonly fonts?: DocumentFontSettings;
   /**
    * CATALOG-level `/PieceInfo` private application data (ISO 32000 §14.5)
    * — e.g. a stamp library's display name. Optional: the local engine
@@ -916,6 +1094,13 @@ interface DocumentHandle {
    * ship it — feature-detect with `doc.redaction !== undefined`.
    */
   readonly redaction?: DocumentRedactionService;
+  /**
+   * Digital signatures: the read side (revisions, signed fields, the
+   * protection they impose) and the two-phase signing protocol. Optional
+   * while engines ship it — feature-detect with
+   * `doc.signatures !== undefined`.
+   */
+  readonly signatures?: DocumentSignaturesService;
   /**
    * The document's event stream — every confirmed mutation, exactly once,
    * identical shape on local and cloud engines (see `DocumentEvent`). The
@@ -931,13 +1116,29 @@ interface DocumentHandle {
   download(opts?: {
     mode?: PdfSaveMode;
   }): AbortablePromise<Uint8Array>;
+  /**
+   * Local Node engines only: write the document to a local file without
+   * moving its bytes through JS. An untouched session (no unsaved edits,
+   * incremental mode) is streamed out verbatim — for a signed document,
+   * exactly as sealed. Absent on engines that cannot reach a filesystem.
+   */
+  downloadToFile?(path: string, opts?: {
+    mode?: PdfSaveMode;
+  }): AbortablePromise<void>;
+  /**
+   * The saved version this session is on: SHA-256 and length of the
+   * loaded bytes (for a layer session, of its base). Changes only when
+   * a signature completes. Optional while engines ship it.
+   */
+  version?(): AbortablePromise<BaseVersionInfo>;
   /**
    * Export JUST this document's LAYER as a self-contained artifact (the small
    * overlay diff over the immutable base) — re-openable later via
-   * `OpenInputLayerBytes` with `{ kind: 'artifact', bytes }`. Optional: only the
-   * local engine, opened WITH a layer (`layerBytes`), supports it; the cloud
-   * engine manages layers server-side and omits it. Rejects if the document was
-   * opened without a layer.
+   * `OpenInputLayerBytes` with `{ kind: 'artifact', bytes }`. Optional: the
+   * local engine supports it for every session it opens as a layer (the
+   * default `sessionKind`, and any `layerBytes` open); the cloud engine
+   * manages layers server-side and omits it. Rejects on a session opened
+   * with `sessionKind: 'plain'`.
    */
   downloadLayer?(): AbortablePromise<Uint8Array>;
   close(): AbortablePromise<void>;
@@ -985,6 +1186,13 @@ interface FontService {
   clearFallbacks(): AbortablePromise<void>;
   /** Unregister every font and reset the fallback chain. */
   clear(): AbortablePromise<void>;
+  /**
+   * Assert that the application holds a licence permitting editing with a
+   * preview-and-print font, so FreeText authoring and missing-glyph fallback
+   * may use it. Resolves to the updated handle (`editingAuthorized: true`).
+   * Rejects with `InvalidArg` for an unregistered key.
+   */
+  authorizeEditing(font: FontHandle | FontKey): AbortablePromise<FontHandle>;
   /** Currently registered fonts, in registration order. */
   list(): readonly FontHandle[];
 }
@@ -1052,5 +1260,5 @@ interface Engine {
  */
 type EngineFactory = () => Engine;
 //#endregion
-export { DocumentPagesService as A, CONTINUOUS_RENDER_POLICY as C, snapFullPageViewport as D, snapAppearanceScale as E, WeakAnnotationEditSession as F, DocumentActionsService as I, FormRepairOptions as M, DocumentAttachmentsService as N, snapTileScale as O, DocumentAnnotationsService as P, DocumentSearchService as S, EngineRenderPolicy as T, PageTextService as _, DocumentHandle as a, PageAnnotationsService as b, DocumentEventInit as c, PageHandle as d, PieceInfoService as f, PieceInfoSnapshot as g, PieceInfoPatchValue as h, DocumentCapabilities as i, DocumentFormsService as j, DocumentRedactionService as k, DocumentEventType as l, PieceInfoPatch as m, EngineFactory as n, DocumentEventStream as o, PieceInfoEntry as p, FontService as r, DocumentEvent as s, Engine as t, EventOrigin as u, PageRenderService as v, DocumentRenderService as w, MetadataService as x, PageGeometryService as y };
-//# sourceMappingURL=Engine-CWnAKccD.d.ts.map
+export { DocumentRedactionService as A, DocumentSearchService as C, snapAppearanceScale as D, EngineRenderPolicy as E, FontEmbeddingPolicy as F, DocumentAttachmentsService as I, DocumentAnnotationsService as L, DocumentFormsService as M, FormRepairOptions as N, snapFullPageViewport as O, DocumentFontSettings as P, WeakAnnotationEditSession as R, DocumentSignaturesService as S, DocumentRenderService as T, PageTextService as _, DocumentHandle as a, PageAnnotationsService as b, DocumentEventInit as c, PageHandle as d, PieceInfoService as f, PieceInfoSnapshot as g, PieceInfoPatchValue as h, DocumentCapabilities as i, DocumentPagesService as j, snapTileScale as k, DocumentEventType as l, PieceInfoPatch as m, EngineFactory as n, DocumentEventStream as o, PieceInfoEntry as p, FontService as r, DocumentEvent as s, Engine as t, EventOrigin as u, PageRenderService as v, CONTINUOUS_RENDER_POLICY as w, MetadataService as x, PageGeometryService as y, DocumentActionsService as z };
+//# sourceMappingURL=Engine-DxtpCYcP.d.ts.map

package/dist/{PageInsertBlankInput-CzShuSJI.cjs → PageInsertBlankInput-CqXBmFhN.cjs}

@@ -70,7 +70,42 @@ const EngineErrorCode = {
 	* at all) and `NotFound` (a well-formed page/annotation/etc. simply
 	* doesn't exist).
 	*/
-	MalformedPdf: "MalformedPdf"
+	MalformedPdf: "MalformedPdf",
+	/**
+	* A signing candidate is parked on this session: every mutation is
+	* refused until `signatures.complete` or `signatures.abort`.
+	*/
+	SigningPending: "SigningPending",
+	/** The candidate's TTL elapsed; prepare again. */
+	SigningExpired: "SigningExpired",
+	/**
+	* `complete` presented a version the candidate was not built on (the
+	* document or the layer moved since `prepare`). The CMS cannot be
+	* reused: it signs a digest of bytes that will never be the head.
+	* Prepare again on the current version.
+	*/
+	SigningVersionMismatch: "SigningVersionMismatch",
+	/**
+	* The engine refused to author the signature: the field is signed,
+	* read-only, or locked by an earlier signature; a certification is
+	* requested after a signature exists; the seed value requires what the
+	* engine does not implement; the request is inconsistent. The message
+	* names the reason.
+	*/
+	SignatureRefused: "SignatureRefused",
+	/**
+	* A signature already in the document forbids this change (a
+	* certification's permission, a FieldMDP or `/Lock`, or the approval
+	* baseline). The message names the signature and the restriction. The
+	* engine option `signedDocumentPolicy: 'permit'` disables the guard.
+	*/
+	ProtectedDocument: "ProtectedDocument",
+	/**
+	* The layer is built on a base version that is no longer the
+	* document's head (another signing completed); it can be read and
+	* edited but not signed from.
+	*/
+	StaleBase: "StaleBase"
 };
 //#endregion
 //#region src/annotation/subtype.ts
@@ -411,4 +446,4 @@ Object.defineProperty(exports, "subtypeFromCode", {
 	}
 });
 
-//# sourceMappingURL=PageInsertBlankInput-CzShuSJI.cjs.map
+//# sourceMappingURL=PageInsertBlankInput-CqXBmFhN.cjs.map

package/dist/PageInsertBlankInput-CqXBmFhN.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageInsertBlankInput-CqXBmFhN.cjs","names":[],"sources":["../src/errors/EngineErrorCode.ts","../src/annotation/subtype.ts","../src/text/charmap.ts","../src/mutation/PageInsertBlankInput.ts"],"sourcesContent":["export const EngineErrorCode = {\n  Unknown: 'Unknown',\n  InvalidArg: 'InvalidArg',\n  DocNotOpen: 'DocNotOpen',\n  DocOpenFailed: 'DocOpenFailed',\n  DocPasswordRequired: 'DocPasswordRequired',\n  DocPasswordIncorrect: 'DocPasswordIncorrect',\n  /**\n   * A share-token exchange (`open({ kind: 'share' })`) needs the grant's\n   * passphrase: none was supplied, or the supplied one was rejected —\n   * indistinguishable by design, mirroring the server. Prompt and retry\n   * with `sharePassword`. Distinct from `DocPasswordRequired`, which is\n   * about the PDF's own encryption password.\n   */\n  SharePasswordRequired: 'SharePasswordRequired',\n  Aborted: 'Aborted',\n  Network: 'Network',\n  Unauthenticated: 'Unauthenticated',\n  Forbidden: 'Forbidden',\n  NotFound: 'NotFound',\n  WireFormat: 'WireFormat',\n  RuntimeUnavailable: 'RuntimeUnavailable',\n  /**\n   * Annotation/page reference could not be resolved. Surfaced when:\n   *   - `AnnotationRef.kind === 'objectNumber'` but the document has no\n   *     annotation with that indirect object number on the addressed page\n   *   - `AnnotationRef.kind === 'nm'` but no annotation on the page has\n   *     that `/NM`\n   *   - `AnnotationRef.kind === 'index'` but the supplied `RevisionToken`\n   *     does not match the current per-page generation\n   *   - `AnnotationRef.kind === 'index'` but `index` is out of range for\n   *     the page's current annotation count\n   */\n  InvalidReference: 'InvalidReference',\n  /**\n   * A weak-annotation structural edit (delete/move) was attempted while the\n   * caller does not have sole active edit presence for that page. This is a\n   * collaboration guard for index-addressed annotations; stable pages and\n   * non-shifting annotation updates do not use it.\n   */\n  WeakAnnotationSessionConflict: 'WeakAnnotationSessionConflict',\n  /**\n   * A layer write lost its optimistic-concurrency check: the layer's\n   * durable version advanced (another writer — typically another server\n   * replica — committed) between the operation's prepare and its commit,\n   * and the server exhausted its rebase-and-retry budget. Retryable: the\n   * operation was NOT applied; re-issue it against the new state.\n   */\n  LayerVersionConflict: 'LayerVersionConflict',\n  /**\n   * The requested operation is typed but not yet wired in this engine\n   * version. The wire shape stays valid; clients can detect this with\n   * `EngineError.is(err, EngineErrorCode.NotImplemented)` and degrade\n   * gracefully.\n   */\n  NotImplemented: 'NotImplemented',\n  /**\n   * The PDF was loadable enough for PDFium to parse, but violates a\n   * structural invariant the engine relies on. Surfaced for the rare\n   * spec-violating PDF that ships a direct (non-indirect) page\n   * dictionary in the /Pages tree — see `EPDFPage_GetObjectNumber`\n   * returning `0`. PDFium creation paths (`FPDFPage_New`,\n   * `EPDFPage_CreateAnnot`) always produce indirect objects, so this\n   * error code is intentionally not used for engine-produced state;\n   * it specifically signals \"this input file is broken in a way we\n   * cannot work around without compromising stable identity\".\n   *\n   * Distinct from `DocOpenFailed` (PDFium refused to load the bytes\n   * at all) and `NotFound` (a well-formed page/annotation/etc. simply\n   * doesn't exist).\n   */\n  MalformedPdf: 'MalformedPdf',\n  /**\n   * A signing candidate is parked on this session: every mutation is\n   * refused until `signatures.complete` or `signatures.abort`.\n   */\n  SigningPending: 'SigningPending',\n  /** The candidate's TTL elapsed; prepare again. */\n  SigningExpired: 'SigningExpired',\n  /**\n   * `complete` presented a version the candidate was not built on (the\n   * document or the layer moved since `prepare`). The CMS cannot be\n   * reused: it signs a digest of bytes that will never be the head.\n   * Prepare again on the current version.\n   */\n  SigningVersionMismatch: 'SigningVersionMismatch',\n  /**\n   * The engine refused to author the signature: the field is signed,\n   * read-only, or locked by an earlier signature; a certification is\n   * requested after a signature exists; the seed value requires what the\n   * engine does not implement; the request is inconsistent. The message\n   * names the reason.\n   */\n  SignatureRefused: 'SignatureRefused',\n  /**\n   * A signature already in the document forbids this change (a\n   * certification's permission, a FieldMDP or `/Lock`, or the approval\n   * baseline). The message names the signature and the restriction. The\n   * engine option `signedDocumentPolicy: 'permit'` disables the guard.\n   */\n  ProtectedDocument: 'ProtectedDocument',\n  /**\n   * The layer is built on a base version that is no longer the\n   * document's head (another signing completed); it can be read and\n   * edited but not signed from.\n   */\n  StaleBase: 'StaleBase',\n} as const;\n\nexport type EngineErrorCode = (typeof EngineErrorCode)[keyof typeof EngineErrorCode];\n","/**\n * Closed-world string catalog of annotation subtypes the v3 wire format knows\n * about. The TypeScript discriminated union `AnnotationDTO` is keyed on this\n * literal type. PDFium's integer subtype code is mapped onto these strings\n * by the reader registry.\n *\n * `unsupported` is the forward-compat fallback for any PDF subtype that\n * the engine has not implemented a reader for yet. Unknown subtypes never\n * silently disappear from the wire — they round-trip as\n * `{ subtype: 'unsupported', rawSubtypeCode }`.\n */\nexport const ANNOTATION_SUBTYPES = [\n  'text',\n  'link',\n  'free-text',\n  'line',\n  'square',\n  'circle',\n  'polygon',\n  'polyline',\n  'highlight',\n  'underline',\n  'squiggly',\n  'strikeout',\n  'stamp',\n  'caret',\n  'ink',\n  'popup',\n  'file-attachment',\n  'redact',\n  'widget',\n  'unsupported',\n] as const;\n\nexport type AnnotationSubtype = (typeof ANNOTATION_SUBTYPES)[number];\n\n/**\n * PDFium subtype codes from `FPDFAnnot_GetSubtype`. Mirrors\n * `FPDF_ANNOTATION_SUBTYPE` in `public/fpdf_annot.h`. We keep this here\n * (rather than importing from @embedpdf/engine-runtime) so the engine-core\n * package has zero PDFium dependency.\n */\nexport const PdfAnnotationSubtypeCode = {\n  UNKNOWN: 0,\n  TEXT: 1,\n  LINK: 2,\n  FREETEXT: 3,\n  LINE: 4,\n  SQUARE: 5,\n  CIRCLE: 6,\n  POLYGON: 7,\n  POLYLINE: 8,\n  HIGHLIGHT: 9,\n  UNDERLINE: 10,\n  SQUIGGLY: 11,\n  STRIKEOUT: 12,\n  STAMP: 13,\n  CARET: 14,\n  INK: 15,\n  POPUP: 16,\n  FILEATTACHMENT: 17,\n  SOUND: 18,\n  MOVIE: 19,\n  WIDGET: 20,\n  SCREEN: 21,\n  PRINTERMARK: 22,\n  TRAPNET: 23,\n  WATERMARK: 24,\n  THREED: 25,\n  RICHMEDIA: 26,\n  XFAWIDGET: 27,\n  REDACT: 28,\n} as const;\n\nexport type PdfAnnotationSubtypeCode =\n  (typeof PdfAnnotationSubtypeCode)[keyof typeof PdfAnnotationSubtypeCode];\n\n/**\n * Map from PDFium codes to wire-stable string subtypes. Codes the engine\n * recognises as a v3 subtype (or maps to 'unsupported' if not yet wired).\n */\nexport const PDF_CODE_TO_SUBTYPE: Readonly<Record<number, AnnotationSubtype>> = Object.freeze({\n  [PdfAnnotationSubtypeCode.TEXT]: 'text',\n  [PdfAnnotationSubtypeCode.LINK]: 'link',\n  [PdfAnnotationSubtypeCode.FREETEXT]: 'free-text',\n  [PdfAnnotationSubtypeCode.LINE]: 'line',\n  [PdfAnnotationSubtypeCode.SQUARE]: 'square',\n  [PdfAnnotationSubtypeCode.CIRCLE]: 'circle',\n  [PdfAnnotationSubtypeCode.POLYGON]: 'polygon',\n  [PdfAnnotationSubtypeCode.POLYLINE]: 'polyline',\n  [PdfAnnotationSubtypeCode.HIGHLIGHT]: 'highlight',\n  [PdfAnnotationSubtypeCode.UNDERLINE]: 'underline',\n  [PdfAnnotationSubtypeCode.SQUIGGLY]: 'squiggly',\n  [PdfAnnotationSubtypeCode.STRIKEOUT]: 'strikeout',\n  [PdfAnnotationSubtypeCode.STAMP]: 'stamp',\n  [PdfAnnotationSubtypeCode.CARET]: 'caret',\n  [PdfAnnotationSubtypeCode.INK]: 'ink',\n  [PdfAnnotationSubtypeCode.POPUP]: 'popup',\n  [PdfAnnotationSubtypeCode.FILEATTACHMENT]: 'file-attachment',\n  [PdfAnnotationSubtypeCode.WIDGET]: 'widget',\n  [PdfAnnotationSubtypeCode.REDACT]: 'redact',\n});\n\n/**\n * Reverse map for write paths that need to turn a wire subtype back into the\n * PDFium integer code without importing the zod-backed annotation registry.\n */\nexport const PDF_SUBTYPE_TO_CODE: Readonly<Record<AnnotationSubtype, PdfAnnotationSubtypeCode>> =\n  Object.freeze({\n    text: PdfAnnotationSubtypeCode.TEXT,\n    link: PdfAnnotationSubtypeCode.LINK,\n    'free-text': PdfAnnotationSubtypeCode.FREETEXT,\n    line: PdfAnnotationSubtypeCode.LINE,\n    square: PdfAnnotationSubtypeCode.SQUARE,\n    circle: PdfAnnotationSubtypeCode.CIRCLE,\n    polygon: PdfAnnotationSubtypeCode.POLYGON,\n    polyline: PdfAnnotationSubtypeCode.POLYLINE,\n    highlight: PdfAnnotationSubtypeCode.HIGHLIGHT,\n    underline: PdfAnnotationSubtypeCode.UNDERLINE,\n    squiggly: PdfAnnotationSubtypeCode.SQUIGGLY,\n    strikeout: PdfAnnotationSubtypeCode.STRIKEOUT,\n    stamp: PdfAnnotationSubtypeCode.STAMP,\n    caret: PdfAnnotationSubtypeCode.CARET,\n    ink: PdfAnnotationSubtypeCode.INK,\n    popup: PdfAnnotationSubtypeCode.POPUP,\n    'file-attachment': PdfAnnotationSubtypeCode.FILEATTACHMENT,\n    redact: PdfAnnotationSubtypeCode.REDACT,\n    widget: PdfAnnotationSubtypeCode.WIDGET,\n    unsupported: PdfAnnotationSubtypeCode.UNKNOWN,\n  });\n\nexport function subtypeFromCode(code: number): AnnotationSubtype {\n  return PDF_CODE_TO_SUBTYPE[code] ?? 'unsupported';\n}\n","import type { PageTextSnapshot } from '../dto/PageTextSnapshot';\n\n/**\n * Character↔text index translation — the ONE place the two text index\n * spaces of a page meet.\n *\n * A page has two index spaces:\n *\n *   - CHARACTER space: PDFium's internal character list, the space geometry\n *     runs tile (`PageGeometryRun.charStart`), hit-testing addresses, and\n *     selection ranges live in. Size: `PageTextSnapshot.charCount`.\n *   - TEXT space: UTF-16 code-unit offsets into the extracted string\n *     `PageTextSnapshot.text` — what search matching and slicing operate on.\n *\n * They diverge in exactly two ways, both encoded by `charMap` anchors:\n *   - a non-printing character occupies a character slot but contributes\n *     ZERO text units (PDFium's `char_indices_` skip list);\n *   - a supplementary-plane character contributes TWO text units (a\n *     surrogate pair) once extraction is UTF-16-faithful.\n *\n * `charMap` semantics (see {@link CharMapAnchor}): an implicit head anchor\n * `[0, 0]`; between anchors every character advances the text by exactly one\n * unit; an anchor sits at `i + 1` whenever character `i` contributed\n * something other than one unit. Absent/empty map = identity\n * (`charCount === text.length`). `charMapViolation` is the validator both\n * the wire schema and engine builders share — malformed maps are rejected,\n * never silently repaired.\n *\n * Boundary model: a \"character boundary\" `c` ∈ [0, charCount] sits BEFORE\n * character `c`; `boundaryTextOffset(s, charCount) === text.length` always.\n * All ranges are half-open in both spaces.\n */\n\n/**\n * One anchor of the character→text mapping: from character index `char`\n * onward (until the next anchor), boundary `c` maps to text offset\n * `text + (c - char)`.\n */\nexport type CharMapAnchor = readonly [char: number, text: number];\n\n/** Direction to resolve a text offset that falls on a zero-width plateau —\n *  see {@link charBoundaryAtTextOffset}. */\nexport type CharBoundaryBias = 'start' | 'end';\n\nconst clampInt = (value: number, lo: number, hi: number): number =>\n  Math.min(Math.max(Math.floor(value), lo), hi);\n\n/** The greatest anchor with `anchor.char <= boundary` (implicit head [0,0]). */\nfunction anchorAtOrBefore(map: ReadonlyArray<CharMapAnchor>, boundary: number): CharMapAnchor {\n  let lo = 0;\n  let hi = map.length - 1;\n  let best: CharMapAnchor | null = null;\n  while (lo <= hi) {\n    const mid = (lo + hi) >> 1;\n    if (map[mid][0] <= boundary) {\n      best = map[mid];\n      lo = mid + 1;\n    } else {\n      hi = mid - 1;\n    }\n  }\n  return best ?? [0, 0];\n}\n\n/**\n * Text offset of character boundary `boundary` (clamped into\n * [0, charCount]). For a dropped character this is the offset of the next\n * real text unit — exactly what half-open slicing needs at either end.\n */\nexport function boundaryTextOffset(snapshot: PageTextSnapshot, boundary: number): number {\n  const b = clampInt(boundary, 0, snapshot.charCount);\n  const map = snapshot.charMap;\n  if (!map || map.length === 0) return Math.min(b, snapshot.text.length);\n  const [char, text] = anchorAtOrBefore(map, b);\n  return text + (b - char);\n}\n\n/**\n * The character boundary for a text offset, with explicit plateau bias:\n *\n *   - `'start'`: the GREATEST boundary whose text offset is <= `offset` —\n *     scans forward past zero-width characters, so a range start never\n *     includes a dropped character that precedes its first real unit.\n *   - `'end'`: the SMALLEST boundary whose text offset is >= `offset` —\n *     stops before zero-width characters, so a range end never swallows a\n *     dropped character that follows its last real unit.\n *\n * An offset inside a surrogate pair resolves outward under both biases\n * (start → the pair's character, end → past it), so a clipped astral\n * character is always covered whole. Prefer {@link charRangeForTextOffsets}\n * — the two biases exist to be used as a PAIR.\n */\nexport function charBoundaryAtTextOffset(\n  snapshot: PageTextSnapshot,\n  offset: number,\n  bias: CharBoundaryBias,\n): number {\n  const target = clampInt(offset, 0, snapshot.text.length);\n  let lo = 0;\n  let hi = snapshot.charCount;\n  if (bias === 'start') {\n    // Greatest boundary with B(boundary) <= target. B(0) = 0 <= target always.\n    while (lo < hi) {\n      const mid = lo + Math.ceil((hi - lo) / 2);\n      if (boundaryTextOffset(snapshot, mid) <= target) lo = mid;\n      else hi = mid - 1;\n    }\n    return lo;\n  }\n  // Smallest boundary with B(boundary) >= target. B(charCount) = text.length\n  // >= target always (offset is clamped).\n  while (lo < hi) {\n    const mid = (lo + hi) >> 1;\n    if (boundaryTextOffset(snapshot, mid) >= target) hi = mid;\n    else lo = mid + 1;\n  }\n  return lo;\n}\n\n/**\n * The character range whose text projection is exactly\n * `text.slice(startOffset, endOffset)` — THE inverse used by search-hit\n * conversion and select-by-text. Start is right-biased and end left-biased\n * (see {@link charBoundaryAtTextOffset}), so zero-width characters adjacent\n * to the range fall OUTSIDE it on both sides.\n *\n * A non-empty text range can never invert: `end > start` implies\n * `B(end) >= endOffset > startOffset >= B(start)`, which forces\n * `end > start` by monotonicity. Empty input (`endOffset <= startOffset`)\n * normalizes to the end-rule boundary of `startOffset` on both sides.\n */\nexport function charRangeForTextOffsets(\n  snapshot: PageTextSnapshot,\n  startOffset: number,\n  endOffset: number,\n): { start: number; end: number } {\n  if (endOffset <= startOffset) {\n    const b = charBoundaryAtTextOffset(snapshot, startOffset, 'end');\n    return { start: b, end: b };\n  }\n  return {\n    start: charBoundaryAtTextOffset(snapshot, startOffset, 'start'),\n    end: charBoundaryAtTextOffset(snapshot, endOffset, 'end'),\n  };\n}\n\n/**\n * THE copy primitive: the text projection of the half-open character range\n * `[charStart, charEnd)`. Dropped characters inside the range contribute\n * nothing; a supplementary character contributes its full surrogate pair.\n * `sliceTextByChars(s, 0, s.charCount) === s.text` always.\n */\nexport function sliceTextByChars(\n  snapshot: PageTextSnapshot,\n  charStart: number,\n  charEnd: number,\n): string {\n  if (charEnd <= charStart) return '';\n  return snapshot.text.slice(\n    boundaryTextOffset(snapshot, charStart),\n    boundaryTextOffset(snapshot, charEnd),\n  );\n}\n\n/**\n * First invariant violation of a snapshot's char map, or null when valid.\n * Shared by the wire schema (rejects malformed bodies) and engine builders\n * (dev-mode assertion). The invariants:\n *\n *   1. absent/empty map ⇒ identity, so `charCount === text.length`;\n *   2. anchor chars strictly increasing, each in [1, charCount];\n *   3. step rule: against the previous anchor (implicit head [0, 0]), the\n *      character just before each anchor contributed exactly 0 units\n *      (dropped) or 2 (surrogate pair):\n *      `t₂ - (t₁ + (c₂ - c₁ - 1)) ∈ {0, 2}`;\n *   4. tail: `lastText + (charCount - lastChar) === text.length`\n *      (equivalently `boundaryTextOffset(s, charCount) === text.length`).\n */\nexport function charMapViolation(\n  charCount: number,\n  textLength: number,\n  charMap: ReadonlyArray<CharMapAnchor> | undefined,\n): string | null {\n  if (!charMap || charMap.length === 0) {\n    return charCount === textLength\n      ? null\n      : `identity map requires charCount (${charCount}) === text length (${textLength})`;\n  }\n  let prevChar = 0;\n  let prevText = 0;\n  for (let i = 0; i < charMap.length; i++) {\n    const [char, text] = charMap[i];\n    if (!Number.isInteger(char) || !Number.isInteger(text)) {\n      return `anchor ${i} is not integer-valued`;\n    }\n    if (char <= prevChar) {\n      return `anchor ${i} char ${char} not strictly after ${prevChar}`;\n    }\n    if (char > charCount) {\n      return `anchor ${i} char ${char} outside [1, ${charCount}]`;\n    }\n    const step = text - (prevText + (char - prevChar - 1));\n    if (step !== 0 && step !== 2) {\n      return `anchor ${i} implies a character contributing ${step} text units (expected 0 or 2)`;\n    }\n    prevChar = char;\n    prevText = text;\n  }\n  const tail = prevText + (charCount - prevChar);\n  if (tail !== textLength) {\n    return `map projects charCount to ${tail}, but text length is ${textLength}`;\n  }\n  return null;\n}\n","import type { PdfSize } from '../geometry/primitives';\n\n/**\n * Upper bound on `count` for a single `pages.insertBlank()` call. A CONTRACT\n * cap, enforced identically by every engine (the cloud input schema carries\n * the same number), so a UI never discovers a lower server limit by surprise.\n * Larger batches are a loop at the call site.\n */\nexport const PAGE_INSERT_BLANK_MAX_COUNT = 100;\n\n/**\n * Spec for `pages.insertBlank()`: create `count` blank pages of `size`.\n *\n * `size` is explicit and in PDF points, un-rotated — the same convention as\n * `PageLayout.size`. The \"match my neighbour\" default developers expect is a\n * registry read, so it lives in the page-edit capability, not here: the\n * engine wire never guesses (the `rotateBy` law).\n */\nexport interface PageInsertBlankSpec {\n  /** Page size in PDF points. Both dimensions must be finite and > 0. */\n  size: PdfSize;\n  /** Pages to create, in `[1, PAGE_INSERT_BLANK_MAX_COUNT]`. Default 1. */\n  count?: number;\n}\n"],"mappings":"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"}

package/dist/{PageInsertBlankInput-WKY0tr6S.js → PageInsertBlankInput-cHq9-i-z.js}

@@ -70,7 +70,42 @@ const EngineErrorCode = {
 	* at all) and `NotFound` (a well-formed page/annotation/etc. simply
 	* doesn't exist).
 	*/
-	MalformedPdf: "MalformedPdf"
+	MalformedPdf: "MalformedPdf",
+	/**
+	* A signing candidate is parked on this session: every mutation is
+	* refused until `signatures.complete` or `signatures.abort`.
+	*/
+	SigningPending: "SigningPending",
+	/** The candidate's TTL elapsed; prepare again. */
+	SigningExpired: "SigningExpired",
+	/**
+	* `complete` presented a version the candidate was not built on (the
+	* document or the layer moved since `prepare`). The CMS cannot be
+	* reused: it signs a digest of bytes that will never be the head.
+	* Prepare again on the current version.
+	*/
+	SigningVersionMismatch: "SigningVersionMismatch",
+	/**
+	* The engine refused to author the signature: the field is signed,
+	* read-only, or locked by an earlier signature; a certification is
+	* requested after a signature exists; the seed value requires what the
+	* engine does not implement; the request is inconsistent. The message
+	* names the reason.
+	*/
+	SignatureRefused: "SignatureRefused",
+	/**
+	* A signature already in the document forbids this change (a
+	* certification's permission, a FieldMDP or `/Lock`, or the approval
+	* baseline). The message names the signature and the restriction. The
+	* engine option `signedDocumentPolicy: 'permit'` disables the guard.
+	*/
+	ProtectedDocument: "ProtectedDocument",
+	/**
+	* The layer is built on a base version that is no longer the
+	* document's head (another signing completed); it can be read and
+	* edited but not signed from.
+	*/
+	StaleBase: "StaleBase"
 };
 //#endregion
 //#region src/annotation/subtype.ts
@@ -340,4 +375,4 @@ const PAGE_INSERT_BLANK_MAX_COUNT = 100;
 //#endregion
 export { charRangeForTextOffsets as a, PDF_CODE_TO_SUBTYPE as c, subtypeFromCode as d, EngineErrorCode as f, charMapViolation as i, PDF_SUBTYPE_TO_CODE as l, boundaryTextOffset as n, sliceTextByChars as o, charBoundaryAtTextOffset as r, ANNOTATION_SUBTYPES as s, PAGE_INSERT_BLANK_MAX_COUNT as t, PdfAnnotationSubtypeCode as u };
 
-//# sourceMappingURL=PageInsertBlankInput-WKY0tr6S.js.map
+//# sourceMappingURL=PageInsertBlankInput-cHq9-i-z.js.map

package/dist/PageInsertBlankInput-cHq9-i-z.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageInsertBlankInput-cHq9-i-z.js","names":[],"sources":["../src/errors/EngineErrorCode.ts","../src/annotation/subtype.ts","../src/text/charmap.ts","../src/mutation/PageInsertBlankInput.ts"],"sourcesContent":["export const EngineErrorCode = {\n  Unknown: 'Unknown',\n  InvalidArg: 'InvalidArg',\n  DocNotOpen: 'DocNotOpen',\n  DocOpenFailed: 'DocOpenFailed',\n  DocPasswordRequired: 'DocPasswordRequired',\n  DocPasswordIncorrect: 'DocPasswordIncorrect',\n  /**\n   * A share-token exchange (`open({ kind: 'share' })`) needs the grant's\n   * passphrase: none was supplied, or the supplied one was rejected —\n   * indistinguishable by design, mirroring the server. Prompt and retry\n   * with `sharePassword`. Distinct from `DocPasswordRequired`, which is\n   * about the PDF's own encryption password.\n   */\n  SharePasswordRequired: 'SharePasswordRequired',\n  Aborted: 'Aborted',\n  Network: 'Network',\n  Unauthenticated: 'Unauthenticated',\n  Forbidden: 'Forbidden',\n  NotFound: 'NotFound',\n  WireFormat: 'WireFormat',\n  RuntimeUnavailable: 'RuntimeUnavailable',\n  /**\n   * Annotation/page reference could not be resolved. Surfaced when:\n   *   - `AnnotationRef.kind === 'objectNumber'` but the document has no\n   *     annotation with that indirect object number on the addressed page\n   *   - `AnnotationRef.kind === 'nm'` but no annotation on the page has\n   *     that `/NM`\n   *   - `AnnotationRef.kind === 'index'` but the supplied `RevisionToken`\n   *     does not match the current per-page generation\n   *   - `AnnotationRef.kind === 'index'` but `index` is out of range for\n   *     the page's current annotation count\n   */\n  InvalidReference: 'InvalidReference',\n  /**\n   * A weak-annotation structural edit (delete/move) was attempted while the\n   * caller does not have sole active edit presence for that page. This is a\n   * collaboration guard for index-addressed annotations; stable pages and\n   * non-shifting annotation updates do not use it.\n   */\n  WeakAnnotationSessionConflict: 'WeakAnnotationSessionConflict',\n  /**\n   * A layer write lost its optimistic-concurrency check: the layer's\n   * durable version advanced (another writer — typically another server\n   * replica — committed) between the operation's prepare and its commit,\n   * and the server exhausted its rebase-and-retry budget. Retryable: the\n   * operation was NOT applied; re-issue it against the new state.\n   */\n  LayerVersionConflict: 'LayerVersionConflict',\n  /**\n   * The requested operation is typed but not yet wired in this engine\n   * version. The wire shape stays valid; clients can detect this with\n   * `EngineError.is(err, EngineErrorCode.NotImplemented)` and degrade\n   * gracefully.\n   */\n  NotImplemented: 'NotImplemented',\n  /**\n   * The PDF was loadable enough for PDFium to parse, but violates a\n   * structural invariant the engine relies on. Surfaced for the rare\n   * spec-violating PDF that ships a direct (non-indirect) page\n   * dictionary in the /Pages tree — see `EPDFPage_GetObjectNumber`\n   * returning `0`. PDFium creation paths (`FPDFPage_New`,\n   * `EPDFPage_CreateAnnot`) always produce indirect objects, so this\n   * error code is intentionally not used for engine-produced state;\n   * it specifically signals \"this input file is broken in a way we\n   * cannot work around without compromising stable identity\".\n   *\n   * Distinct from `DocOpenFailed` (PDFium refused to load the bytes\n   * at all) and `NotFound` (a well-formed page/annotation/etc. simply\n   * doesn't exist).\n   */\n  MalformedPdf: 'MalformedPdf',\n  /**\n   * A signing candidate is parked on this session: every mutation is\n   * refused until `signatures.complete` or `signatures.abort`.\n   */\n  SigningPending: 'SigningPending',\n  /** The candidate's TTL elapsed; prepare again. */\n  SigningExpired: 'SigningExpired',\n  /**\n   * `complete` presented a version the candidate was not built on (the\n   * document or the layer moved since `prepare`). The CMS cannot be\n   * reused: it signs a digest of bytes that will never be the head.\n   * Prepare again on the current version.\n   */\n  SigningVersionMismatch: 'SigningVersionMismatch',\n  /**\n   * The engine refused to author the signature: the field is signed,\n   * read-only, or locked by an earlier signature; a certification is\n   * requested after a signature exists; the seed value requires what the\n   * engine does not implement; the request is inconsistent. The message\n   * names the reason.\n   */\n  SignatureRefused: 'SignatureRefused',\n  /**\n   * A signature already in the document forbids this change (a\n   * certification's permission, a FieldMDP or `/Lock`, or the approval\n   * baseline). The message names the signature and the restriction. The\n   * engine option `signedDocumentPolicy: 'permit'` disables the guard.\n   */\n  ProtectedDocument: 'ProtectedDocument',\n  /**\n   * The layer is built on a base version that is no longer the\n   * document's head (another signing completed); it can be read and\n   * edited but not signed from.\n   */\n  StaleBase: 'StaleBase',\n} as const;\n\nexport type EngineErrorCode = (typeof EngineErrorCode)[keyof typeof EngineErrorCode];\n","/**\n * Closed-world string catalog of annotation subtypes the v3 wire format knows\n * about. The TypeScript discriminated union `AnnotationDTO` is keyed on this\n * literal type. PDFium's integer subtype code is mapped onto these strings\n * by the reader registry.\n *\n * `unsupported` is the forward-compat fallback for any PDF subtype that\n * the engine has not implemented a reader for yet. Unknown subtypes never\n * silently disappear from the wire — they round-trip as\n * `{ subtype: 'unsupported', rawSubtypeCode }`.\n */\nexport const ANNOTATION_SUBTYPES = [\n  'text',\n  'link',\n  'free-text',\n  'line',\n  'square',\n  'circle',\n  'polygon',\n  'polyline',\n  'highlight',\n  'underline',\n  'squiggly',\n  'strikeout',\n  'stamp',\n  'caret',\n  'ink',\n  'popup',\n  'file-attachment',\n  'redact',\n  'widget',\n  'unsupported',\n] as const;\n\nexport type AnnotationSubtype = (typeof ANNOTATION_SUBTYPES)[number];\n\n/**\n * PDFium subtype codes from `FPDFAnnot_GetSubtype`. Mirrors\n * `FPDF_ANNOTATION_SUBTYPE` in `public/fpdf_annot.h`. We keep this here\n * (rather than importing from @embedpdf/engine-runtime) so the engine-core\n * package has zero PDFium dependency.\n */\nexport const PdfAnnotationSubtypeCode = {\n  UNKNOWN: 0,\n  TEXT: 1,\n  LINK: 2,\n  FREETEXT: 3,\n  LINE: 4,\n  SQUARE: 5,\n  CIRCLE: 6,\n  POLYGON: 7,\n  POLYLINE: 8,\n  HIGHLIGHT: 9,\n  UNDERLINE: 10,\n  SQUIGGLY: 11,\n  STRIKEOUT: 12,\n  STAMP: 13,\n  CARET: 14,\n  INK: 15,\n  POPUP: 16,\n  FILEATTACHMENT: 17,\n  SOUND: 18,\n  MOVIE: 19,\n  WIDGET: 20,\n  SCREEN: 21,\n  PRINTERMARK: 22,\n  TRAPNET: 23,\n  WATERMARK: 24,\n  THREED: 25,\n  RICHMEDIA: 26,\n  XFAWIDGET: 27,\n  REDACT: 28,\n} as const;\n\nexport type PdfAnnotationSubtypeCode =\n  (typeof PdfAnnotationSubtypeCode)[keyof typeof PdfAnnotationSubtypeCode];\n\n/**\n * Map from PDFium codes to wire-stable string subtypes. Codes the engine\n * recognises as a v3 subtype (or maps to 'unsupported' if not yet wired).\n */\nexport const PDF_CODE_TO_SUBTYPE: Readonly<Record<number, AnnotationSubtype>> = Object.freeze({\n  [PdfAnnotationSubtypeCode.TEXT]: 'text',\n  [PdfAnnotationSubtypeCode.LINK]: 'link',\n  [PdfAnnotationSubtypeCode.FREETEXT]: 'free-text',\n  [PdfAnnotationSubtypeCode.LINE]: 'line',\n  [PdfAnnotationSubtypeCode.SQUARE]: 'square',\n  [PdfAnnotationSubtypeCode.CIRCLE]: 'circle',\n  [PdfAnnotationSubtypeCode.POLYGON]: 'polygon',\n  [PdfAnnotationSubtypeCode.POLYLINE]: 'polyline',\n  [PdfAnnotationSubtypeCode.HIGHLIGHT]: 'highlight',\n  [PdfAnnotationSubtypeCode.UNDERLINE]: 'underline',\n  [PdfAnnotationSubtypeCode.SQUIGGLY]: 'squiggly',\n  [PdfAnnotationSubtypeCode.STRIKEOUT]: 'strikeout',\n  [PdfAnnotationSubtypeCode.STAMP]: 'stamp',\n  [PdfAnnotationSubtypeCode.CARET]: 'caret',\n  [PdfAnnotationSubtypeCode.INK]: 'ink',\n  [PdfAnnotationSubtypeCode.POPUP]: 'popup',\n  [PdfAnnotationSubtypeCode.FILEATTACHMENT]: 'file-attachment',\n  [PdfAnnotationSubtypeCode.WIDGET]: 'widget',\n  [PdfAnnotationSubtypeCode.REDACT]: 'redact',\n});\n\n/**\n * Reverse map for write paths that need to turn a wire subtype back into the\n * PDFium integer code without importing the zod-backed annotation registry.\n */\nexport const PDF_SUBTYPE_TO_CODE: Readonly<Record<AnnotationSubtype, PdfAnnotationSubtypeCode>> =\n  Object.freeze({\n    text: PdfAnnotationSubtypeCode.TEXT,\n    link: PdfAnnotationSubtypeCode.LINK,\n    'free-text': PdfAnnotationSubtypeCode.FREETEXT,\n    line: PdfAnnotationSubtypeCode.LINE,\n    square: PdfAnnotationSubtypeCode.SQUARE,\n    circle: PdfAnnotationSubtypeCode.CIRCLE,\n    polygon: PdfAnnotationSubtypeCode.POLYGON,\n    polyline: PdfAnnotationSubtypeCode.POLYLINE,\n    highlight: PdfAnnotationSubtypeCode.HIGHLIGHT,\n    underline: PdfAnnotationSubtypeCode.UNDERLINE,\n    squiggly: PdfAnnotationSubtypeCode.SQUIGGLY,\n    strikeout: PdfAnnotationSubtypeCode.STRIKEOUT,\n    stamp: PdfAnnotationSubtypeCode.STAMP,\n    caret: PdfAnnotationSubtypeCode.CARET,\n    ink: PdfAnnotationSubtypeCode.INK,\n    popup: PdfAnnotationSubtypeCode.POPUP,\n    'file-attachment': PdfAnnotationSubtypeCode.FILEATTACHMENT,\n    redact: PdfAnnotationSubtypeCode.REDACT,\n    widget: PdfAnnotationSubtypeCode.WIDGET,\n    unsupported: PdfAnnotationSubtypeCode.UNKNOWN,\n  });\n\nexport function subtypeFromCode(code: number): AnnotationSubtype {\n  return PDF_CODE_TO_SUBTYPE[code] ?? 'unsupported';\n}\n","import type { PageTextSnapshot } from '../dto/PageTextSnapshot';\n\n/**\n * Character↔text index translation — the ONE place the two text index\n * spaces of a page meet.\n *\n * A page has two index spaces:\n *\n *   - CHARACTER space: PDFium's internal character list, the space geometry\n *     runs tile (`PageGeometryRun.charStart`), hit-testing addresses, and\n *     selection ranges live in. Size: `PageTextSnapshot.charCount`.\n *   - TEXT space: UTF-16 code-unit offsets into the extracted string\n *     `PageTextSnapshot.text` — what search matching and slicing operate on.\n *\n * They diverge in exactly two ways, both encoded by `charMap` anchors:\n *   - a non-printing character occupies a character slot but contributes\n *     ZERO text units (PDFium's `char_indices_` skip list);\n *   - a supplementary-plane character contributes TWO text units (a\n *     surrogate pair) once extraction is UTF-16-faithful.\n *\n * `charMap` semantics (see {@link CharMapAnchor}): an implicit head anchor\n * `[0, 0]`; between anchors every character advances the text by exactly one\n * unit; an anchor sits at `i + 1` whenever character `i` contributed\n * something other than one unit. Absent/empty map = identity\n * (`charCount === text.length`). `charMapViolation` is the validator both\n * the wire schema and engine builders share — malformed maps are rejected,\n * never silently repaired.\n *\n * Boundary model: a \"character boundary\" `c` ∈ [0, charCount] sits BEFORE\n * character `c`; `boundaryTextOffset(s, charCount) === text.length` always.\n * All ranges are half-open in both spaces.\n */\n\n/**\n * One anchor of the character→text mapping: from character index `char`\n * onward (until the next anchor), boundary `c` maps to text offset\n * `text + (c - char)`.\n */\nexport type CharMapAnchor = readonly [char: number, text: number];\n\n/** Direction to resolve a text offset that falls on a zero-width plateau —\n *  see {@link charBoundaryAtTextOffset}. */\nexport type CharBoundaryBias = 'start' | 'end';\n\nconst clampInt = (value: number, lo: number, hi: number): number =>\n  Math.min(Math.max(Math.floor(value), lo), hi);\n\n/** The greatest anchor with `anchor.char <= boundary` (implicit head [0,0]). */\nfunction anchorAtOrBefore(map: ReadonlyArray<CharMapAnchor>, boundary: number): CharMapAnchor {\n  let lo = 0;\n  let hi = map.length - 1;\n  let best: CharMapAnchor | null = null;\n  while (lo <= hi) {\n    const mid = (lo + hi) >> 1;\n    if (map[mid][0] <= boundary) {\n      best = map[mid];\n      lo = mid + 1;\n    } else {\n      hi = mid - 1;\n    }\n  }\n  return best ?? [0, 0];\n}\n\n/**\n * Text offset of character boundary `boundary` (clamped into\n * [0, charCount]). For a dropped character this is the offset of the next\n * real text unit — exactly what half-open slicing needs at either end.\n */\nexport function boundaryTextOffset(snapshot: PageTextSnapshot, boundary: number): number {\n  const b = clampInt(boundary, 0, snapshot.charCount);\n  const map = snapshot.charMap;\n  if (!map || map.length === 0) return Math.min(b, snapshot.text.length);\n  const [char, text] = anchorAtOrBefore(map, b);\n  return text + (b - char);\n}\n\n/**\n * The character boundary for a text offset, with explicit plateau bias:\n *\n *   - `'start'`: the GREATEST boundary whose text offset is <= `offset` —\n *     scans forward past zero-width characters, so a range start never\n *     includes a dropped character that precedes its first real unit.\n *   - `'end'`: the SMALLEST boundary whose text offset is >= `offset` —\n *     stops before zero-width characters, so a range end never swallows a\n *     dropped character that follows its last real unit.\n *\n * An offset inside a surrogate pair resolves outward under both biases\n * (start → the pair's character, end → past it), so a clipped astral\n * character is always covered whole. Prefer {@link charRangeForTextOffsets}\n * — the two biases exist to be used as a PAIR.\n */\nexport function charBoundaryAtTextOffset(\n  snapshot: PageTextSnapshot,\n  offset: number,\n  bias: CharBoundaryBias,\n): number {\n  const target = clampInt(offset, 0, snapshot.text.length);\n  let lo = 0;\n  let hi = snapshot.charCount;\n  if (bias === 'start') {\n    // Greatest boundary with B(boundary) <= target. B(0) = 0 <= target always.\n    while (lo < hi) {\n      const mid = lo + Math.ceil((hi - lo) / 2);\n      if (boundaryTextOffset(snapshot, mid) <= target) lo = mid;\n      else hi = mid - 1;\n    }\n    return lo;\n  }\n  // Smallest boundary with B(boundary) >= target. B(charCount) = text.length\n  // >= target always (offset is clamped).\n  while (lo < hi) {\n    const mid = (lo + hi) >> 1;\n    if (boundaryTextOffset(snapshot, mid) >= target) hi = mid;\n    else lo = mid + 1;\n  }\n  return lo;\n}\n\n/**\n * The character range whose text projection is exactly\n * `text.slice(startOffset, endOffset)` — THE inverse used by search-hit\n * conversion and select-by-text. Start is right-biased and end left-biased\n * (see {@link charBoundaryAtTextOffset}), so zero-width characters adjacent\n * to the range fall OUTSIDE it on both sides.\n *\n * A non-empty text range can never invert: `end > start` implies\n * `B(end) >= endOffset > startOffset >= B(start)`, which forces\n * `end > start` by monotonicity. Empty input (`endOffset <= startOffset`)\n * normalizes to the end-rule boundary of `startOffset` on both sides.\n */\nexport function charRangeForTextOffsets(\n  snapshot: PageTextSnapshot,\n  startOffset: number,\n  endOffset: number,\n): { start: number; end: number } {\n  if (endOffset <= startOffset) {\n    const b = charBoundaryAtTextOffset(snapshot, startOffset, 'end');\n    return { start: b, end: b };\n  }\n  return {\n    start: charBoundaryAtTextOffset(snapshot, startOffset, 'start'),\n    end: charBoundaryAtTextOffset(snapshot, endOffset, 'end'),\n  };\n}\n\n/**\n * THE copy primitive: the text projection of the half-open character range\n * `[charStart, charEnd)`. Dropped characters inside the range contribute\n * nothing; a supplementary character contributes its full surrogate pair.\n * `sliceTextByChars(s, 0, s.charCount) === s.text` always.\n */\nexport function sliceTextByChars(\n  snapshot: PageTextSnapshot,\n  charStart: number,\n  charEnd: number,\n): string {\n  if (charEnd <= charStart) return '';\n  return snapshot.text.slice(\n    boundaryTextOffset(snapshot, charStart),\n    boundaryTextOffset(snapshot, charEnd),\n  );\n}\n\n/**\n * First invariant violation of a snapshot's char map, or null when valid.\n * Shared by the wire schema (rejects malformed bodies) and engine builders\n * (dev-mode assertion). The invariants:\n *\n *   1. absent/empty map ⇒ identity, so `charCount === text.length`;\n *   2. anchor chars strictly increasing, each in [1, charCount];\n *   3. step rule: against the previous anchor (implicit head [0, 0]), the\n *      character just before each anchor contributed exactly 0 units\n *      (dropped) or 2 (surrogate pair):\n *      `t₂ - (t₁ + (c₂ - c₁ - 1)) ∈ {0, 2}`;\n *   4. tail: `lastText + (charCount - lastChar) === text.length`\n *      (equivalently `boundaryTextOffset(s, charCount) === text.length`).\n */\nexport function charMapViolation(\n  charCount: number,\n  textLength: number,\n  charMap: ReadonlyArray<CharMapAnchor> | undefined,\n): string | null {\n  if (!charMap || charMap.length === 0) {\n    return charCount === textLength\n      ? null\n      : `identity map requires charCount (${charCount}) === text length (${textLength})`;\n  }\n  let prevChar = 0;\n  let prevText = 0;\n  for (let i = 0; i < charMap.length; i++) {\n    const [char, text] = charMap[i];\n    if (!Number.isInteger(char) || !Number.isInteger(text)) {\n      return `anchor ${i} is not integer-valued`;\n    }\n    if (char <= prevChar) {\n      return `anchor ${i} char ${char} not strictly after ${prevChar}`;\n    }\n    if (char > charCount) {\n      return `anchor ${i} char ${char} outside [1, ${charCount}]`;\n    }\n    const step = text - (prevText + (char - prevChar - 1));\n    if (step !== 0 && step !== 2) {\n      return `anchor ${i} implies a character contributing ${step} text units (expected 0 or 2)`;\n    }\n    prevChar = char;\n    prevText = text;\n  }\n  const tail = prevText + (charCount - prevChar);\n  if (tail !== textLength) {\n    return `map projects charCount to ${tail}, but text length is ${textLength}`;\n  }\n  return null;\n}\n","import type { PdfSize } from '../geometry/primitives';\n\n/**\n * Upper bound on `count` for a single `pages.insertBlank()` call. A CONTRACT\n * cap, enforced identically by every engine (the cloud input schema carries\n * the same number), so a UI never discovers a lower server limit by surprise.\n * Larger batches are a loop at the call site.\n */\nexport const PAGE_INSERT_BLANK_MAX_COUNT = 100;\n\n/**\n * Spec for `pages.insertBlank()`: create `count` blank pages of `size`.\n *\n * `size` is explicit and in PDF points, un-rotated — the same convention as\n * `PageLayout.size`. The \"match my neighbour\" default developers expect is a\n * registry read, so it lives in the page-edit capability, not here: the\n * engine wire never guesses (the `rotateBy` law).\n */\nexport interface PageInsertBlankSpec {\n  /** Page size in PDF points. Both dimensions must be finite and > 0. */\n  size: PdfSize;\n  /** Pages to create, in `[1, PAGE_INSERT_BLANK_MAX_COUNT]`. Default 1. */\n  count?: number;\n}\n"],"mappings":"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"}