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

package/dist/{DocumentSecurityService-Df79fgpe.d.cts → DocumentSecurityService-6rhztZlz.d.cts}

@@ -1,4 +1,4 @@
-import { Hs as DocCapability, Us as IdentityClaims, Ys as PdfBits } from "./AnnotationListSnapshot-W0RCsyDE.cjs";
+import { Dc as DocCapability, Oc as IdentityClaims, Pc as PdfBits, cc as CollabTarget } from "./AnnotationListSnapshot-C1U3XUxP.cjs";
 //#region src/promise/AbortablePromise.d.ts
 type AbortableExecutor<T, P> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason: unknown) => void, progress: (p: P) => void, signal: AbortSignal) => void;
 /**
@@ -312,6 +312,37 @@ interface DocumentSecurityService {
    * only to *display* the concrete grants.
    */
   allows(capability: DocCapability): boolean;
+  /**
+   * Per-record annotation authorization mirrors — the SAME resolver the
+   * engine enforces with (`checkCollab`'s narrowing rule: an applicable
+   * `annotations:<action>:<filter>` grant SHADOWS the coarse
+   * `doc.annotate.modify` fallback for that action), over the same
+   * inputs (raw scope + identity claims + PDF bits). `allows()` cannot
+   * answer these: it enumerates capabilities, and a filtered collab
+   * grant is not a capability — whether "update" is allowed depends on
+   * WHOSE annotation you're touching.
+   *
+   * Three surfaces because the questions genuinely differ:
+   *   - create derives its target from the caller's OWN identity
+   *     (`:self` trivially passes; `:group=X` matches the caller's
+   *     default group),
+   *   - update/delete are asked about the TARGET record's stamped
+   *     owner (`userId`/`groupId` from its EMBD metadata; pass `{}`
+   *     when unstamped — matching the engine, which denies unstamped
+   *     targets under any narrowed grant),
+   *   - group assignment is asked about the DESTINATION group
+   *     (`annotations:set-group:` ladder; the caller's own default
+   *     group is always assignable).
+   *
+   * These are a courtesy for UI gating — the engine (and the server,
+   * on cloud) independently enforces every mutation with the same
+   * predicates, so a stale or bypassed answer here never widens
+   * access. Returns false when no scope context exists (legacy local
+   * open without `scope`, cloud open without a token before /access).
+   */
+  allowsAnnotationCreate(): boolean;
+  allowsAnnotationMutation(action: 'update' | 'delete', target: CollabTarget): boolean;
+  allowsAnnotationGroupAssignment(groupId: string): boolean;
   /**
    * Identity of the current caller, or null when anonymous.
    */
@@ -329,4 +360,4 @@ interface DocumentSecurityService {
 }
 //#endregion
 export { DocumentEncryptionState as a, DocumentSecurityState as c, PdfPermissionAdvisory as d, PdfPermissionInfo as f, AbortablePromise as g, AbortableExecutor as h, DocumentAccessReason as i, DocumentUnlockInput as l, passwordPromptFromState as m, CdnAdapter as n, DocumentOpenMode as o, PasswordPrompt as p, DocumentAccessInfo as r, DocumentSecurityService as s, CdnAccessInfo as t, DocumentUnlockResult as u };
-//# sourceMappingURL=DocumentSecurityService-Df79fgpe.d.cts.map
+//# sourceMappingURL=DocumentSecurityService-6rhztZlz.d.cts.map

package/dist/{DocumentSecurityService-B-tULKNY.d.ts → DocumentSecurityService-7nL9aY75.d.ts}

@@ -1,4 +1,4 @@
-import { Hs as DocCapability, Us as IdentityClaims, Ys as PdfBits } from "./AnnotationListSnapshot-W0RCsyDE.js";
+import { Dc as DocCapability, Oc as IdentityClaims, Pc as PdfBits, cc as CollabTarget } from "./AnnotationListSnapshot-C1U3XUxP.js";
 //#region src/promise/AbortablePromise.d.ts
 type AbortableExecutor<T, P> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason: unknown) => void, progress: (p: P) => void, signal: AbortSignal) => void;
 /**
@@ -312,6 +312,37 @@ interface DocumentSecurityService {
    * only to *display* the concrete grants.
    */
   allows(capability: DocCapability): boolean;
+  /**
+   * Per-record annotation authorization mirrors — the SAME resolver the
+   * engine enforces with (`checkCollab`'s narrowing rule: an applicable
+   * `annotations:<action>:<filter>` grant SHADOWS the coarse
+   * `doc.annotate.modify` fallback for that action), over the same
+   * inputs (raw scope + identity claims + PDF bits). `allows()` cannot
+   * answer these: it enumerates capabilities, and a filtered collab
+   * grant is not a capability — whether "update" is allowed depends on
+   * WHOSE annotation you're touching.
+   *
+   * Three surfaces because the questions genuinely differ:
+   *   - create derives its target from the caller's OWN identity
+   *     (`:self` trivially passes; `:group=X` matches the caller's
+   *     default group),
+   *   - update/delete are asked about the TARGET record's stamped
+   *     owner (`userId`/`groupId` from its EMBD metadata; pass `{}`
+   *     when unstamped — matching the engine, which denies unstamped
+   *     targets under any narrowed grant),
+   *   - group assignment is asked about the DESTINATION group
+   *     (`annotations:set-group:` ladder; the caller's own default
+   *     group is always assignable).
+   *
+   * These are a courtesy for UI gating — the engine (and the server,
+   * on cloud) independently enforces every mutation with the same
+   * predicates, so a stale or bypassed answer here never widens
+   * access. Returns false when no scope context exists (legacy local
+   * open without `scope`, cloud open without a token before /access).
+   */
+  allowsAnnotationCreate(): boolean;
+  allowsAnnotationMutation(action: 'update' | 'delete', target: CollabTarget): boolean;
+  allowsAnnotationGroupAssignment(groupId: string): boolean;
   /**
    * Identity of the current caller, or null when anonymous.
    */
@@ -329,4 +360,4 @@ interface DocumentSecurityService {
 }
 //#endregion
 export { DocumentEncryptionState as a, DocumentSecurityState as c, PdfPermissionAdvisory as d, PdfPermissionInfo as f, AbortablePromise as g, AbortableExecutor as h, DocumentAccessReason as i, DocumentUnlockInput as l, passwordPromptFromState as m, CdnAdapter as n, DocumentOpenMode as o, PasswordPrompt as p, DocumentAccessInfo as r, DocumentSecurityService as s, CdnAccessInfo as t, DocumentUnlockResult as u };
-//# sourceMappingURL=DocumentSecurityService-B-tULKNY.d.ts.map
+//# sourceMappingURL=DocumentSecurityService-7nL9aY75.d.ts.map

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

@@ -1,5 +1,5 @@
-import { Aa as EmbeddedFileItem, Ai as AnnotationCreateResult, Ao as PageImageHandle, Ar as FormFieldDeleteResult, Bo as PageRenderOptions, Di as FormWidgetRef, Ea as AttachmentContent, Ei as FormFieldRef, Fn as RedactionApplyScope, Fr as FormWidgetLinkResult, Gn as PageRotateResult, Gr as FormFieldPatch, Hn as PageInsertResult, Hr as FormFieldValue, Io as PageRaster, Ir as FormEffect, Jn as PageMoveResult, Jo as PageTextSnapshot, Mc as DocumentActionsSnapshot, Mi as AnnotationMoveResult, Mn as MetadataUpdateResult, Mo as PageImageOptions, Mr as FormImportResult, Ni as AnnotationUpdateResult, Nr as FormRepairResult, Or as FormDataExport, Pn as RedactionApplyResult, Pr as FormSetValueResult, So as AnnotationAppearanceRenderOptions, Tr as SearchSlice, Un as PageDeleteResult, Uo as PageRenderViewport, Vc as DocumentMetadata, Vn as PageFlattenUsage, Vr as FormDataFormat, Zr as FormFieldDraft, Zs as AnnotationRef, _o as AnnotationAppearanceImagesResult, _s as OpenOptions, do as FontSpec, ds as OpenInput, ec as PageObjectNumber, go as AnnotationAppearanceImageOptions, ii as FormSnapshot, ja as EmbeddedFileRef, ji as AnnotationDeleteResult, jr as FormFieldUpdateResult, ka as AttachmentFileSource, kc as PdfRotation, kr as FormFieldCreateResult, l as AnnotationPatch, la as AttachmentCreateResult, lo as FontHandle, n as AnnotationListSnapshotAllPages, o as AnnotationDraft, os as PageListSnapshot, pi as FormFieldDTO, po as PdfSaveMode, qo as PageGeometrySnapshot, t as AnnotationListPageSnapshot, ua as AttachmentDeleteResult, uo as FontKey, us as MetadataPatch, wo as AnnotationAppearancesResult, wr as SearchRequest, zn as PageFlattenResult, zr as FormEffectsResult } from "./AnnotationListSnapshot-W0RCsyDE.js";
-import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-B-tULKNY.js";
+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";
 //#region src/engine/DocumentActionsService.d.ts
 /** Lazy, catalog-owned PDF action read. This API extracts; it never executes. */
 interface DocumentActionsService {
@@ -139,6 +139,18 @@ interface DocumentFormsService {
    * skipped and any landed state is finalized as one artifact/event/version.
    */
   applyEffects?(effects: FormEffect[]): AbortablePromise<FormEffectsResult>;
+  /**
+   * Deliver a resolved form submission to the document's HOME. Present only
+   * where the document HAS a home that accepts submissions — the cloud
+   * engine when the deployment advertises the capability; the local engine
+   * truthfully lacks it (an in-process document has no home, and this
+   * contract is never a callback trampoline). Gated by `doc.forms.submit`
+   * (grant-minted; no PDF permission bit exists for submission), asserted
+   * at the home's boundary where enforcement is real. The home stores the
+   * dataset with the declared intent as metadata and derives WHO submitted
+   * from its own verified session — it never fetches the PDF's URL.
+   */
+  submit?(request: FormSubmissionRequest): AbortablePromise<FormSubmissionReceipt>;
   /**
    * Serialize the form data for interchange. Defaults to `'xfdf'` (the
    * XML sibling; UTF-8, friendliest to web pipelines) — pass `'fdf'` for
@@ -262,27 +274,37 @@ interface DocumentPagesService {
    * the source document is untouched — no revisions bump, no event is
    * published. This is how a page becomes a portable asset (a vector
    * stamp, a signature) that re-enters a document as a stamp draft's
-   * `source` bytes.
+   * `source` bytes. Gated by `doc.download` (it egresses content), not
+   * `doc.pages.assemble`.
    *
-   * Optional while the cloud endpoint ships (the `downloadLayer?`
-   * pattern): the local engine implements it; the cloud engine omits it
-   * until the server exposes extraction. Feature-detect with
-   * `pages.extract !== undefined`.
+   * REQUIRED-parity, delivered: the local engine runs it in the worker,
+   * the cloud engine as POST /pages/extract.
    */
-  extract?(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<Uint8Array>;
+  extract(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<Uint8Array>;
   /**
    * Insert every page of a standalone PDF (`bytes`) at `destIndex`
    * (omitted → append). The pages are COPIED in; the inserted copies get
    * fresh object numbers, returned in insertion order. Bytes are a call
    * ARGUMENT (the same law as annotation binaries): the local engine
-   * transfers them to its worker, the cloud engine will ship them as a
-   * multipart mutation.
+   * transfers them to its worker, the cloud engine ships them as a
+   * multipart mutation (POST /pages/insert).
    *
-   * Slated REQUIRED-parity (a cloud viewer must be able to add pages);
-   * optional only until the server endpoint ships — feature-detect with
-   * `pages.insert !== undefined`.
+   * REQUIRED-parity, delivered — a cloud viewer must be able to add pages,
+   * so this is a mandatory member: any engine implements it or is not a
+   * conforming engine.
    */
-  insert?(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise<PageInsertResult>;
+  insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise<PageInsertResult>;
+  /**
+   * Create `spec.count` (default 1) blank pages of `spec.size` (PDF points)
+   * at `destIndex` (omitted → append). The blank-page sibling of `insert`:
+   * same gate (`doc.pages.assemble`), same result shape, same
+   * `pages.inserted` event — it is a separate verb because its wire is pure
+   * parameters where `insert`'s is a binary payload (cloud: JSON
+   * POST /pages/insert-blank). The new pages get fresh, never-recycled
+   * object numbers; every pre-existing page keeps its identity and
+   * revisions. Mandatory, like `insert`.
+   */
+  insertBlank(spec: PageInsertBlankSpec, destIndex?: number): AbortablePromise<PageInsertResult>;
 }
 //#endregion
 //#region src/engine/DocumentRedactionService.d.ts
@@ -439,7 +461,7 @@ declare function snapTileScale(policy: EngineRenderPolicy, scale: number): numbe
  * layer is unfindable, and a cursor issued before a content mutation is
  * rejected rather than resumed over stale pages.
  *
- * Matches carry merged line rects from the same line-merge as text
+ * Matches carry canonical visual-line segments from the same layout as text
  * selection (never per-glyph boxes) and text-page character offsets that
  * join the selection/geometry subsystem directly.
  */
@@ -790,12 +812,33 @@ type DocumentEvent = ({
 } & PageFlattenResult) | ({
   type: 'redaction.applied';
   origin: EventOrigin;
-} & RedactionApplyResult);
+} & RedactionApplyResult) | {
+  /**
+   * Cloud only: the live event stream fell too far behind to replay
+   * (the server's SSE `full-refresh`) — state derived from earlier
+   * events or snapshots may be stale, and the gap's mutations will
+   * NEVER arrive as events. Consumers must re-read the snapshots they
+   * keep fresh from this stream (`doc.annotations.listRawAll()`,
+   * `doc.forms.list()`, …).
+   *
+   * Carries no `EventOrigin`: it is a transport notice, not a
+   * document mutation — the exactly-once / results-ride-verbatim
+   * invariants above apply to mutation events only. The local engine
+   * never emits it.
+   */
+  type: 'stream.desynced';
+  reason: 'backlog-overflow';
+  ts: number;
+};
 type DocumentEventType = DocumentEvent['type'];
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /** A `DocumentEvent` before provenance is stamped — what mutation paths
- *  hand to their engine's publisher, which adds `origin`. */
-type DocumentEventInit = DistributiveOmit<DocumentEvent, 'origin'>;
+ *  hand to their engine's publisher, which adds `origin`. Transport
+ *  notices (`stream.desynced`) are excluded: they are published directly
+ *  by the remote channel, never through a mutation publisher. */
+type DocumentEventInit = DistributiveOmit<Exclude<DocumentEvent, {
+  type: 'stream.desynced';
+}>, 'origin'>;
 //#endregion
 //#region src/events/DocumentEventStream.d.ts
 /**
@@ -1010,4 +1053,4 @@ 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-B7Oe7f5i.d.ts.map
+//# sourceMappingURL=Engine-CWnAKccD.d.ts.map

package/dist/{Engine-D9loFZc1.d.cts → Engine-D3868xIU.d.cts}

@@ -1,5 +1,5 @@
-import { Aa as EmbeddedFileItem, Ai as AnnotationCreateResult, Ao as PageImageHandle, Ar as FormFieldDeleteResult, Bo as PageRenderOptions, Di as FormWidgetRef, Ea as AttachmentContent, Ei as FormFieldRef, Fn as RedactionApplyScope, Fr as FormWidgetLinkResult, Gn as PageRotateResult, Gr as FormFieldPatch, Hn as PageInsertResult, Hr as FormFieldValue, Io as PageRaster, Ir as FormEffect, Jn as PageMoveResult, Jo as PageTextSnapshot, Mc as DocumentActionsSnapshot, Mi as AnnotationMoveResult, Mn as MetadataUpdateResult, Mo as PageImageOptions, Mr as FormImportResult, Ni as AnnotationUpdateResult, Nr as FormRepairResult, Or as FormDataExport, Pn as RedactionApplyResult, Pr as FormSetValueResult, So as AnnotationAppearanceRenderOptions, Tr as SearchSlice, Un as PageDeleteResult, Uo as PageRenderViewport, Vc as DocumentMetadata, Vn as PageFlattenUsage, Vr as FormDataFormat, Zr as FormFieldDraft, Zs as AnnotationRef, _o as AnnotationAppearanceImagesResult, _s as OpenOptions, do as FontSpec, ds as OpenInput, ec as PageObjectNumber, go as AnnotationAppearanceImageOptions, ii as FormSnapshot, ja as EmbeddedFileRef, ji as AnnotationDeleteResult, jr as FormFieldUpdateResult, ka as AttachmentFileSource, kc as PdfRotation, kr as FormFieldCreateResult, l as AnnotationPatch, la as AttachmentCreateResult, lo as FontHandle, n as AnnotationListSnapshotAllPages, o as AnnotationDraft, os as PageListSnapshot, pi as FormFieldDTO, po as PdfSaveMode, qo as PageGeometrySnapshot, t as AnnotationListPageSnapshot, ua as AttachmentDeleteResult, uo as FontKey, us as MetadataPatch, wo as AnnotationAppearancesResult, wr as SearchRequest, zn as PageFlattenResult, zr as FormEffectsResult } from "./AnnotationListSnapshot-W0RCsyDE.cjs";
-import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-Df79fgpe.cjs";
+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.cjs";
+import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-6rhztZlz.cjs";
 //#region src/engine/DocumentActionsService.d.ts
 /** Lazy, catalog-owned PDF action read. This API extracts; it never executes. */
 interface DocumentActionsService {
@@ -139,6 +139,18 @@ interface DocumentFormsService {
    * skipped and any landed state is finalized as one artifact/event/version.
    */
   applyEffects?(effects: FormEffect[]): AbortablePromise<FormEffectsResult>;
+  /**
+   * Deliver a resolved form submission to the document's HOME. Present only
+   * where the document HAS a home that accepts submissions — the cloud
+   * engine when the deployment advertises the capability; the local engine
+   * truthfully lacks it (an in-process document has no home, and this
+   * contract is never a callback trampoline). Gated by `doc.forms.submit`
+   * (grant-minted; no PDF permission bit exists for submission), asserted
+   * at the home's boundary where enforcement is real. The home stores the
+   * dataset with the declared intent as metadata and derives WHO submitted
+   * from its own verified session — it never fetches the PDF's URL.
+   */
+  submit?(request: FormSubmissionRequest): AbortablePromise<FormSubmissionReceipt>;
   /**
    * Serialize the form data for interchange. Defaults to `'xfdf'` (the
    * XML sibling; UTF-8, friendliest to web pipelines) — pass `'fdf'` for
@@ -262,27 +274,37 @@ interface DocumentPagesService {
    * the source document is untouched — no revisions bump, no event is
    * published. This is how a page becomes a portable asset (a vector
    * stamp, a signature) that re-enters a document as a stamp draft's
-   * `source` bytes.
+   * `source` bytes. Gated by `doc.download` (it egresses content), not
+   * `doc.pages.assemble`.
    *
-   * Optional while the cloud endpoint ships (the `downloadLayer?`
-   * pattern): the local engine implements it; the cloud engine omits it
-   * until the server exposes extraction. Feature-detect with
-   * `pages.extract !== undefined`.
+   * REQUIRED-parity, delivered: the local engine runs it in the worker,
+   * the cloud engine as POST /pages/extract.
    */
-  extract?(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<Uint8Array>;
+  extract(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<Uint8Array>;
   /**
    * Insert every page of a standalone PDF (`bytes`) at `destIndex`
    * (omitted → append). The pages are COPIED in; the inserted copies get
    * fresh object numbers, returned in insertion order. Bytes are a call
    * ARGUMENT (the same law as annotation binaries): the local engine
-   * transfers them to its worker, the cloud engine will ship them as a
-   * multipart mutation.
+   * transfers them to its worker, the cloud engine ships them as a
+   * multipart mutation (POST /pages/insert).
    *
-   * Slated REQUIRED-parity (a cloud viewer must be able to add pages);
-   * optional only until the server endpoint ships — feature-detect with
-   * `pages.insert !== undefined`.
+   * REQUIRED-parity, delivered — a cloud viewer must be able to add pages,
+   * so this is a mandatory member: any engine implements it or is not a
+   * conforming engine.
    */
-  insert?(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise<PageInsertResult>;
+  insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise<PageInsertResult>;
+  /**
+   * Create `spec.count` (default 1) blank pages of `spec.size` (PDF points)
+   * at `destIndex` (omitted → append). The blank-page sibling of `insert`:
+   * same gate (`doc.pages.assemble`), same result shape, same
+   * `pages.inserted` event — it is a separate verb because its wire is pure
+   * parameters where `insert`'s is a binary payload (cloud: JSON
+   * POST /pages/insert-blank). The new pages get fresh, never-recycled
+   * object numbers; every pre-existing page keeps its identity and
+   * revisions. Mandatory, like `insert`.
+   */
+  insertBlank(spec: PageInsertBlankSpec, destIndex?: number): AbortablePromise<PageInsertResult>;
 }
 //#endregion
 //#region src/engine/DocumentRedactionService.d.ts
@@ -439,7 +461,7 @@ declare function snapTileScale(policy: EngineRenderPolicy, scale: number): numbe
  * layer is unfindable, and a cursor issued before a content mutation is
  * rejected rather than resumed over stale pages.
  *
- * Matches carry merged line rects from the same line-merge as text
+ * Matches carry canonical visual-line segments from the same layout as text
  * selection (never per-glyph boxes) and text-page character offsets that
  * join the selection/geometry subsystem directly.
  */
@@ -790,12 +812,33 @@ type DocumentEvent = ({
 } & PageFlattenResult) | ({
   type: 'redaction.applied';
   origin: EventOrigin;
-} & RedactionApplyResult);
+} & RedactionApplyResult) | {
+  /**
+   * Cloud only: the live event stream fell too far behind to replay
+   * (the server's SSE `full-refresh`) — state derived from earlier
+   * events or snapshots may be stale, and the gap's mutations will
+   * NEVER arrive as events. Consumers must re-read the snapshots they
+   * keep fresh from this stream (`doc.annotations.listRawAll()`,
+   * `doc.forms.list()`, …).
+   *
+   * Carries no `EventOrigin`: it is a transport notice, not a
+   * document mutation — the exactly-once / results-ride-verbatim
+   * invariants above apply to mutation events only. The local engine
+   * never emits it.
+   */
+  type: 'stream.desynced';
+  reason: 'backlog-overflow';
+  ts: number;
+};
 type DocumentEventType = DocumentEvent['type'];
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /** A `DocumentEvent` before provenance is stamped — what mutation paths
- *  hand to their engine's publisher, which adds `origin`. */
-type DocumentEventInit = DistributiveOmit<DocumentEvent, 'origin'>;
+ *  hand to their engine's publisher, which adds `origin`. Transport
+ *  notices (`stream.desynced`) are excluded: they are published directly
+ *  by the remote channel, never through a mutation publisher. */
+type DocumentEventInit = DistributiveOmit<Exclude<DocumentEvent, {
+  type: 'stream.desynced';
+}>, 'origin'>;
 //#endregion
 //#region src/events/DocumentEventStream.d.ts
 /**
@@ -1010,4 +1053,4 @@ 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-D9loFZc1.d.cts.map
+//# sourceMappingURL=Engine-D3868xIU.d.cts.map

package/dist/{subtype-qejjVr6h.cjs → PageInsertBlankInput-CzShuSJI.cjs}

@@ -6,6 +6,14 @@ const EngineErrorCode = {
 	DocOpenFailed: "DocOpenFailed",
 	DocPasswordRequired: "DocPasswordRequired",
 	DocPasswordIncorrect: "DocPasswordIncorrect",
+	/**
+	* A share-token exchange (`open({ kind: 'share' })`) needs the grant's
+	* passphrase: none was supplied, or the supplied one was rejected —
+	* indistinguishable by design, mirroring the server. Prompt and retry
+	* with `sharePassword`. Distinct from `DocPasswordRequired`, which is
+	* about the PDF's own encryption password.
+	*/
+	SharePasswordRequired: "SharePasswordRequired",
 	Aborted: "Aborted",
 	Network: "Network",
 	Unauthenticated: "Unauthenticated",
@@ -191,6 +199,145 @@ function subtypeFromCode(code) {
 	return PDF_CODE_TO_SUBTYPE[code] ?? "unsupported";
 }
 //#endregion
+//#region src/text/charmap.ts
+const clampInt = (value, lo, hi) => Math.min(Math.max(Math.floor(value), lo), hi);
+/** The greatest anchor with `anchor.char <= boundary` (implicit head [0,0]). */
+function anchorAtOrBefore(map, boundary) {
+	let lo = 0;
+	let hi = map.length - 1;
+	let best = null;
+	while (lo <= hi) {
+		const mid = lo + hi >> 1;
+		if (map[mid][0] <= boundary) {
+			best = map[mid];
+			lo = mid + 1;
+		} else hi = mid - 1;
+	}
+	return best ?? [0, 0];
+}
+/**
+* Text offset of character boundary `boundary` (clamped into
+* [0, charCount]). For a dropped character this is the offset of the next
+* real text unit — exactly what half-open slicing needs at either end.
+*/
+function boundaryTextOffset(snapshot, boundary) {
+	const b = clampInt(boundary, 0, snapshot.charCount);
+	const map = snapshot.charMap;
+	if (!map || map.length === 0) return Math.min(b, snapshot.text.length);
+	const [char, text] = anchorAtOrBefore(map, b);
+	return text + (b - char);
+}
+/**
+* The character boundary for a text offset, with explicit plateau bias:
+*
+*   - `'start'`: the GREATEST boundary whose text offset is <= `offset` —
+*     scans forward past zero-width characters, so a range start never
+*     includes a dropped character that precedes its first real unit.
+*   - `'end'`: the SMALLEST boundary whose text offset is >= `offset` —
+*     stops before zero-width characters, so a range end never swallows a
+*     dropped character that follows its last real unit.
+*
+* An offset inside a surrogate pair resolves outward under both biases
+* (start → the pair's character, end → past it), so a clipped astral
+* character is always covered whole. Prefer {@link charRangeForTextOffsets}
+* — the two biases exist to be used as a PAIR.
+*/
+function charBoundaryAtTextOffset(snapshot, offset, bias) {
+	const target = clampInt(offset, 0, snapshot.text.length);
+	let lo = 0;
+	let hi = snapshot.charCount;
+	if (bias === "start") {
+		while (lo < hi) {
+			const mid = lo + Math.ceil((hi - lo) / 2);
+			if (boundaryTextOffset(snapshot, mid) <= target) lo = mid;
+			else hi = mid - 1;
+		}
+		return lo;
+	}
+	while (lo < hi) {
+		const mid = lo + hi >> 1;
+		if (boundaryTextOffset(snapshot, mid) >= target) hi = mid;
+		else lo = mid + 1;
+	}
+	return lo;
+}
+/**
+* The character range whose text projection is exactly
+* `text.slice(startOffset, endOffset)` — THE inverse used by search-hit
+* conversion and select-by-text. Start is right-biased and end left-biased
+* (see {@link charBoundaryAtTextOffset}), so zero-width characters adjacent
+* to the range fall OUTSIDE it on both sides.
+*
+* A non-empty text range can never invert: `end > start` implies
+* `B(end) >= endOffset > startOffset >= B(start)`, which forces
+* `end > start` by monotonicity. Empty input (`endOffset <= startOffset`)
+* normalizes to the end-rule boundary of `startOffset` on both sides.
+*/
+function charRangeForTextOffsets(snapshot, startOffset, endOffset) {
+	if (endOffset <= startOffset) {
+		const b = charBoundaryAtTextOffset(snapshot, startOffset, "end");
+		return {
+			start: b,
+			end: b
+		};
+	}
+	return {
+		start: charBoundaryAtTextOffset(snapshot, startOffset, "start"),
+		end: charBoundaryAtTextOffset(snapshot, endOffset, "end")
+	};
+}
+/**
+* THE copy primitive: the text projection of the half-open character range
+* `[charStart, charEnd)`. Dropped characters inside the range contribute
+* nothing; a supplementary character contributes its full surrogate pair.
+* `sliceTextByChars(s, 0, s.charCount) === s.text` always.
+*/
+function sliceTextByChars(snapshot, charStart, charEnd) {
+	if (charEnd <= charStart) return "";
+	return snapshot.text.slice(boundaryTextOffset(snapshot, charStart), boundaryTextOffset(snapshot, charEnd));
+}
+/**
+* First invariant violation of a snapshot's char map, or null when valid.
+* Shared by the wire schema (rejects malformed bodies) and engine builders
+* (dev-mode assertion). The invariants:
+*
+*   1. absent/empty map ⇒ identity, so `charCount === text.length`;
+*   2. anchor chars strictly increasing, each in [1, charCount];
+*   3. step rule: against the previous anchor (implicit head [0, 0]), the
+*      character just before each anchor contributed exactly 0 units
+*      (dropped) or 2 (surrogate pair):
+*      `t₂ - (t₁ + (c₂ - c₁ - 1)) ∈ {0, 2}`;
+*   4. tail: `lastText + (charCount - lastChar) === text.length`
+*      (equivalently `boundaryTextOffset(s, charCount) === text.length`).
+*/
+function charMapViolation(charCount, textLength, charMap) {
+	if (!charMap || charMap.length === 0) return charCount === textLength ? null : `identity map requires charCount (${charCount}) === text length (${textLength})`;
+	let prevChar = 0;
+	let prevText = 0;
+	for (let i = 0; i < charMap.length; i++) {
+		const [char, text] = charMap[i];
+		if (!Number.isInteger(char) || !Number.isInteger(text)) return `anchor ${i} is not integer-valued`;
+		if (char <= prevChar) return `anchor ${i} char ${char} not strictly after ${prevChar}`;
+		if (char > charCount) return `anchor ${i} char ${char} outside [1, ${charCount}]`;
+		const step = text - (prevText + (char - prevChar - 1));
+		if (step !== 0 && step !== 2) return `anchor ${i} implies a character contributing ${step} text units (expected 0 or 2)`;
+		prevChar = char;
+		prevText = text;
+	}
+	const tail = prevText + (charCount - prevChar);
+	if (tail !== textLength) return `map projects charCount to ${tail}, but text length is ${textLength}`;
+	return null;
+}
+//#endregion
+//#region src/mutation/PageInsertBlankInput.ts
+/**
+* Upper bound on `count` for a single `pages.insertBlank()` call. A CONTRACT
+* cap, enforced identically by every engine (the cloud input schema carries
+* the same number), so a UI never discovers a lower server limit by surprise.
+* Larger batches are a loop at the call site.
+*/
+const PAGE_INSERT_BLANK_MAX_COUNT = 100;
+//#endregion
 Object.defineProperty(exports, "ANNOTATION_SUBTYPES", {
 	enumerable: true,
 	get: function() {
@@ -203,6 +350,12 @@ Object.defineProperty(exports, "EngineErrorCode", {
 		return EngineErrorCode;
 	}
 });
+Object.defineProperty(exports, "PAGE_INSERT_BLANK_MAX_COUNT", {
+	enumerable: true,
+	get: function() {
+		return PAGE_INSERT_BLANK_MAX_COUNT;
+	}
+});
 Object.defineProperty(exports, "PDF_CODE_TO_SUBTYPE", {
 	enumerable: true,
 	get: function() {
@@ -221,6 +374,36 @@ Object.defineProperty(exports, "PdfAnnotationSubtypeCode", {
 		return PdfAnnotationSubtypeCode;
 	}
 });
+Object.defineProperty(exports, "boundaryTextOffset", {
+	enumerable: true,
+	get: function() {
+		return boundaryTextOffset;
+	}
+});
+Object.defineProperty(exports, "charBoundaryAtTextOffset", {
+	enumerable: true,
+	get: function() {
+		return charBoundaryAtTextOffset;
+	}
+});
+Object.defineProperty(exports, "charMapViolation", {
+	enumerable: true,
+	get: function() {
+		return charMapViolation;
+	}
+});
+Object.defineProperty(exports, "charRangeForTextOffsets", {
+	enumerable: true,
+	get: function() {
+		return charRangeForTextOffsets;
+	}
+});
+Object.defineProperty(exports, "sliceTextByChars", {
+	enumerable: true,
+	get: function() {
+		return sliceTextByChars;
+	}
+});
 Object.defineProperty(exports, "subtypeFromCode", {
 	enumerable: true,
 	get: function() {
@@ -228,4 +411,4 @@ Object.defineProperty(exports, "subtypeFromCode", {
 	}
 });
 
-//# sourceMappingURL=subtype-qejjVr6h.cjs.map
+//# sourceMappingURL=PageInsertBlankInput-CzShuSJI.cjs.map