docxodus 12.4.1 → 12.5.0

package/dist/embed.bundle.js

@@ -113,6 +113,37 @@ var require_dist = __commonJS({
   }
 });
 
+// src/verification-request.ts
+function serializeVerificationRequest(request) {
+  if (request === null || typeof request !== "object" || Array.isArray(request)) {
+    throw new RangeError("a verification request must be an object");
+  }
+  const { companionArtifacts, ...rest } = request;
+  const wire = { ...rest };
+  if (companionArtifacts !== void 0) {
+    wire.companionArtifacts = companionArtifacts.map(encodeCompanion);
+  }
+  return JSON.stringify(wire);
+}
+function encodeCompanion(artifact) {
+  const { bytes, ...rest } = artifact;
+  const wire = { ...rest };
+  if (bytes !== void 0) wire.bytesB64 = bytesToBase64(bytes);
+  return wire;
+}
+function bytesToBase64(bytes) {
+  if (typeof btoa === "function") {
+    let binary = "";
+    const chunkSize = 32768;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+      const chunk = bytes.subarray(i, i + chunkSize);
+      binary += String.fromCharCode.apply(null, chunk);
+    }
+    return btoa(binary);
+  }
+  return Buffer.from(bytes).toString("base64");
+}
+
 // src/types.ts
 var ProjectionScopes = /* @__PURE__ */ ((ProjectionScopes2) => {
   ProjectionScopes2[ProjectionScopes2["Body"] = 1] = "Body";
@@ -382,9 +413,23 @@ function mutationBatchChangeSet(before, after, key) {
     modified: after.filter((_, index) => modified[index])
   };
 }
+var BATCH_REPLAY_CAVEATS = {
+  revisionDates: "Tracked-revision date attributes may use the execution clock; compare revision ids, authors, types, text, and anchors across separate executions.",
+  commentDates: "Comment date attributes may be generated from the execution clock; supply dates explicitly when byte-identical replay is required.",
+  annotationMetadata: "Auto-generated annotation ids or creation timestamps are execution metadata; supply id and created explicitly when byte-identical replay is required.",
+  createdAnchors: "Created anchors and related OOXML ids may be generated independently on replay; preview/apply equivalence is semantic and packageHash or anchor ids may differ."
+};
+var BATCH_REPLAY_CAVEAT_TEXTS = new Set(Object.values(BATCH_REPLAY_CAVEATS));
+var RETAINED_PREVIEW_RECEIPTS = 8;
 var DocxSession = class _DocxSession {
   /** @internal */
   constructor(handle, wasm) {
+    /**
+     * The receipts this client composed for previews it retained, keyed by previewId. The host
+     * keeps the package and the binding; the step receipts live only here, so a commit can return
+     * the previewed steps and change sets without the host re-parsing a client-composed result.
+     */
+    this.retainedPreviewReceipts = /* @__PURE__ */ new Map();
     // ─── Raw escape hatch ────────────────────────────────────────────────
     this.raw = {
       getXml: (anchorId) => this.wasm.RawGetXml(this.handle, anchorId),
@@ -449,10 +494,152 @@ var DocxSession = class _DocxSession {
    * Execute synchronous mutations atomically by default. Atomic success is one undo/version
    * unit; any failed or thrown step restores the exact package and history checkpoint.
    */
-  executeBatch(steps, mode = "atomic") {
+  executeBatch(steps, mode = "atomic", transaction) {
     if (mode !== "atomic" && mode !== "best_effort") {
       throw new RangeError(`unknown mutation batch mode: ${String(mode)}`);
     }
+    if (transaction === void 0) return this.recorded(steps, mode, void 0, () => this.runBatch(steps, mode));
+    return this.runTransactional(
+      transaction,
+      mode,
+      (identity) => this.recorded(steps, mode, identity, () => this.runBatch(steps, mode))
+    );
+  }
+  /**
+   * What the session's host-owned delivery evidence recorder holds (issue #748). `enabled` is
+   * false, with the reason, unless the session was opened with `captureDeliveryEvidence`.
+   */
+  getDeliveryEvidenceStatus() {
+    if (!this.wasm.GetDeliveryEvidenceStatus) {
+      throw new Error("This WASM bundle predates delivery evidence; rebuild docxodus.");
+    }
+    return JSON.parse(this.wasm.GetDeliveryEvidenceStatus(this.handle));
+  }
+  /**
+   * Build the receipt-bearing delivery of this session through the shared bundle service: the
+   * clean current package (`final-docx`), the source-to-delivered semantic delta, and the change
+   * receipt (`change-receipt`) minted from the captured evidence — verifiable with
+   * `verifyDeliveryReceipt` against the returned artifact bytes. A history that cannot be
+   * attested yields an `incomplete` bundle whose receipt artifact carries the reason, and
+   * `evidence.unavailableReason` says why.
+   */
+  buildDeliveryReceipt(options) {
+    if (!this.wasm.BuildDeliveryReceipt) {
+      throw new Error("This WASM bundle predates delivery evidence; rebuild docxodus.");
+    }
+    const wire = JSON.parse(this.wasm.BuildDeliveryReceipt(this.handle, JSON.stringify(options ?? {})));
+    const decode = (base64) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+    return {
+      status: wire.status,
+      verified: wire.verified,
+      manifest: wire.manifest,
+      manifestBytes: decode(wire.manifestBytes),
+      artifacts: wire.artifacts.map((artifact) => {
+        const { bytes, ...rest } = artifact;
+        return bytes === void 0 ? rest : { ...rest, bytes: decode(bytes) };
+      }),
+      ...wire.evidence ? { evidence: wire.evidence } : {}
+    };
+  }
+  /**
+   * Describe a batch to the session's delivery evidence recorder before running it, and hand
+   * it the step results afterwards, so the version steps the batch produced are recorded under
+   * this description rather than as unlabeled mutations. A bundle without the recorder, or a
+   * session not capturing evidence, simply runs the batch.
+   */
+  recorded(steps, mode, identity, run) {
+    if (!this.wasm.BeginDeliveryEvidence || !this.wasm.CompleteDeliveryEvidence || !this.wasm.AbandonDeliveryEvidence) {
+      return run();
+    }
+    const described = this.wasm.BeginDeliveryEvidence(
+      this.handle,
+      JSON.stringify(steps.map((step) => step.args === void 0 ? { tool: step.tool, action: step.action } : { tool: step.tool, action: step.action, args: step.args })),
+      mode,
+      identity ? JSON.stringify({ transactionId: identity.transactionId, requestFingerprint: identity.requestFingerprint }) : ""
+    );
+    if (!described) return run();
+    let result;
+    try {
+      result = run();
+      return result;
+    } finally {
+      if (result) this.wasm.CompleteDeliveryEvidence(this.handle, JSON.stringify(result.steps));
+      else this.wasm.AbandonDeliveryEvidence(this.handle);
+    }
+  }
+  /**
+   * Make a preview retained by {@link previewBatch} (`retain: true`) the live document exactly
+   * as previewed: the previewed package is restored byte-for-byte as one undo step, so the
+   * generated anchor ids, timestamps and `packageHash` are exactly those the preview reported.
+   * The commit is guarded — it refuses with `preview_stale`, editing nothing, when the session's
+   * version, package content, tracked-changes mode or revision author moved since the preview,
+   * and with `preview_not_found` once the preview expired, was evicted, or was already
+   * committed. A `transaction` makes a retry after a lost response safe, as for
+   * {@link executeBatch}.
+   */
+  commitPreview(previewId, transaction) {
+    if (!this.wasm.CommitPreview) {
+      throw new Error("This WASM bundle predates retained previews; rebuild docxodus.");
+    }
+    const commit = () => {
+      const envelope = JSON.parse(this.wasm.CommitPreview(this.handle, previewId));
+      if (!envelope.success) {
+        if (envelope.failure?.error.code === "preview_not_found") this.retainedPreviewReceipts.delete(previewId);
+        return envelope;
+      }
+      const receipt = this.retainedPreviewReceipts.get(previewId);
+      this.retainedPreviewReceipts.delete(previewId);
+      if (!receipt) return envelope;
+      return {
+        ...receipt,
+        preview: false,
+        html: null,
+        baseVersion: envelope.baseVersion,
+        resultVersion: envelope.resultVersion,
+        packageHash: envelope.packageHash,
+        warnings: receipt.warnings.filter((warning) => !BATCH_REPLAY_CAVEAT_TEXTS.has(warning)),
+        retention: envelope.retention
+      };
+    };
+    if (transaction === void 0) return commit();
+    return this.runTransactional(transaction, "atomic", () => commit());
+  }
+  runTransactional(transaction, mode, body) {
+    if (!this.wasm.BeginMutationTransaction || !this.wasm.CompleteMutationTransaction || !this.wasm.AbandonMutationTransaction) {
+      throw new Error("This WASM bundle predates mutation transactions; rebuild docxodus.");
+    }
+    if (typeof transaction.transactionId !== "string") {
+      throw new RangeError("transactionId must be a string");
+    }
+    if (transaction.request === null || typeof transaction.request !== "object" || Array.isArray(transaction.request)) {
+      throw new RangeError("a mutation transaction needs a request object describing the batch");
+    }
+    const decision = JSON.parse(this.wasm.BeginMutationTransaction(
+      this.handle,
+      transaction.transactionId,
+      JSON.stringify({ ...transaction.request, mode })
+    ));
+    if (decision.response !== null) {
+      return JSON.parse(decision.response);
+    }
+    let completed = false;
+    try {
+      const result = {
+        ...body(decision.transaction),
+        transaction: decision.transaction
+      };
+      this.wasm.CompleteMutationTransaction(
+        this.handle,
+        transaction.transactionId,
+        JSON.stringify(result)
+      );
+      completed = true;
+      return result;
+    } finally {
+      if (!completed) this.wasm.AbandonMutationTransaction(this.handle, transaction.transactionId);
+    }
+  }
+  runBatch(steps, mode) {
     const baseVersion = this.getVersion();
     const observationWarnings = [];
     const inspect = (label, read, fallback) => {
@@ -490,16 +677,16 @@ var DocxSession = class _DocxSession {
         );
         const warnings = [...observationWarnings];
         if ([...revisionChanges.added, ...revisionChanges.modified].some((revision) => revision.date !== void 0 && revision.date !== null)) {
-          warnings.push("Tracked-revision date attributes may use the execution clock; compare revision ids, authors, types, text, and anchors across separate executions.");
+          warnings.push(BATCH_REPLAY_CAVEATS.revisionDates);
         }
         if ([...commentChanges.added, ...commentChanges.modified].some((comment) => comment.date !== void 0 && comment.date !== null)) {
-          warnings.push("Comment date attributes may be generated from the execution clock; supply dates explicitly when byte-identical replay is required.");
+          warnings.push(BATCH_REPLAY_CAVEATS.commentDates);
         }
         if (annotationChanges.added.some((annotation) => annotation.created !== void 0 && annotation.created !== null)) {
-          warnings.push("Auto-generated annotation ids or creation timestamps are execution metadata; supply id and created explicitly when byte-identical replay is required.");
+          warnings.push(BATCH_REPLAY_CAVEATS.annotationMetadata);
         }
         if (result.steps.some((step) => step.results.some((edit) => edit.created.length > 0))) {
-          warnings.push("Created anchors and related OOXML ids may be generated independently on replay; preview/apply equivalence is semantic and packageHash or anchor ids may differ.");
+          warnings.push(BATCH_REPLAY_CAVEATS.createdAnchors);
         }
         if (mode === "best_effort" && !result.success) {
           warnings.push("Best-effort execution retains every successful step despite later failures.");
@@ -723,7 +910,27 @@ var DocxSession = class _DocxSession {
       } catch (error) {
         warnings.push(`Preview HTML could not be generated: ${error instanceof Error ? error.message : String(error)}`);
       }
-      return { ...result, preview: true, warnings, html };
+      let retention;
+      if (options?.retain) {
+        if (!this.wasm.RetainPreview) {
+          throw new Error("This WASM bundle predates retained previews; rebuild docxodus.");
+        }
+        if (!result.success) {
+          warnings.push("The preview did not succeed, so it was not retained for commit.");
+        } else {
+          const retained = JSON.parse(this.wasm.RetainPreview(shadow.handle));
+          warnings.push(...retained.warnings);
+          retention = retained.retention ?? void 0;
+        }
+      }
+      const preview = retention ? { ...result, preview: true, warnings, html, retention } : { ...result, preview: true, warnings, html };
+      if (retention) {
+        if (this.retainedPreviewReceipts.size >= RETAINED_PREVIEW_RECEIPTS) {
+          this.retainedPreviewReceipts.delete(this.retainedPreviewReceipts.keys().next().value);
+        }
+        this.retainedPreviewReceipts.set(retention.previewId, { ...preview, html: null });
+      }
+      return preview;
     } finally {
       shadow.close();
     }
@@ -1302,6 +1509,18 @@ var DocxSession = class _DocxSession {
       imageBytesToBase64(bytes)
     ));
   }
+  /**
+   * Convert an external linked picture into an embedded one using bytes the caller fetched;
+   * the engine never reaches the network itself. Refused for pictures that already embed
+   * their media — see `ImageOccurrence.operations`.
+   */
+  embedLinkedImage(imageId, bytes) {
+    return JSON.parse(this.wasm.EmbedLinkedImage(
+      this.handle,
+      imageId,
+      imageBytesToBase64(bytes)
+    ));
+  }
   setImageDimensions(imageId, dimensions) {
     return JSON.parse(this.wasm.SetImageDimensions(
       this.handle,
@@ -1432,6 +1651,28 @@ var DocxSession = class _DocxSession {
   listRevisions() {
     return JSON.parse(this.wasm.ListRevisions(this.handle));
   }
+  /**
+   * The explicit repairs the registry offers for entries it refuses to resolve (issues
+   * #754–#758): which carriers are defective, whether a unique repair exists, and what it
+   * would do. Read-only; listing, accept and reject never repair.
+   */
+  listRevisionRepairs() {
+    if (!this.wasm.ListRevisionRepairs) {
+      throw new Error("This WASM bundle predates revision repairs; rebuild docxodus.");
+    }
+    return JSON.parse(this.wasm.ListRevisionRepairs(this.handle));
+  }
+  /**
+   * Perform requested repairs atomically as one undo step. A kind the registry did not offer,
+   * a non-repairable proposal, or a wrap-as-deletion without author and date refuses the whole
+   * call (`revision_repair_rejected`) with nothing mutated. Repaired entries get new ids.
+   */
+  repairRevisions(repairs) {
+    if (!this.wasm.RepairRevisions) {
+      throw new Error("This WASM bundle predates revision repairs; rebuild docxodus.");
+    }
+    return JSON.parse(this.wasm.RepairRevisions(this.handle, JSON.stringify(repairs)));
+  }
   /** Accept ONE revision by the id {@link listRevisions} reported — insertions keep
    * their content, deletions are carried out, a move materializes at its destination,
    * a format change keeps the new properties. Undoable. */
@@ -1789,7 +2030,16 @@ var DocxSession = class _DocxSession {
    * With initial projection capture enabled (the default), exact opening bytes are the
    * baseline used for dispositions and semantic/package deltas.
    */
-  verifyDeliverable() {
+  verifyDeliverable(request) {
+    if (request !== void 0) {
+      if (!this.wasm.VerifyDeliverableWithRequest) {
+        throw new Error("This WASM bundle predates full verification requests; rebuild docxodus.");
+      }
+      return JSON.parse(this.wasm.VerifyDeliverableWithRequest(
+        this.handle,
+        serializeVerificationRequest(request)
+      ));
+    }
     return JSON.parse(
       this.wasm.VerifyDeliverable(this.handle)
     );
@@ -2018,6 +2268,7 @@ var DocxSession = class _DocxSession {
     return this.wasm.Save(this.handle);
   }
   close() {
+    this.retainedPreviewReceipts.clear();
     this.wasm.CloseSession(this.handle);
   }
   // TypeScript 5.2+ disposable protocol
@@ -2038,6 +2289,129 @@ function openDocxSession(bytes, wasmExports2, settings) {
   return new DocxSession(handle, bridge);
 }
 
+// src/external-annotation-wire.ts
+function readPawlsPage(p) {
+  return {
+    page: {
+      width: p.Page?.Width ?? p.page?.width,
+      height: p.Page?.Height ?? p.page?.height,
+      index: p.Page?.Index ?? p.page?.index
+    },
+    tokens: (p.Tokens || p.tokens || []).map((t) => ({
+      x: t.X ?? t.x,
+      y: t.Y ?? t.y,
+      width: t.Width ?? t.width,
+      height: t.Height ?? t.height,
+      text: t.Text ?? t.text
+    }))
+  };
+}
+function readAnnotationJson(json) {
+  if (!json) return void 0;
+  if (json.Start !== void 0 || json.start !== void 0) {
+    return {
+      id: json.Id ?? json.id,
+      start: json.Start ?? json.start,
+      end: json.End ?? json.end,
+      text: json.Text ?? json.text
+    };
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(json)) {
+    const v = value;
+    result[key] = {
+      bounds: {
+        top: v.Bounds?.Top ?? v.bounds?.top,
+        bottom: v.Bounds?.Bottom ?? v.bounds?.bottom,
+        left: v.Bounds?.Left ?? v.bounds?.left,
+        right: v.Bounds?.Right ?? v.bounds?.right
+      },
+      tokensJsons: (v.TokensJsons || v.tokensJsons || []).map((t) => ({
+        pageIndex: t.PageIndex ?? t.pageIndex,
+        tokenIndex: t.TokenIndex ?? t.tokenIndex
+      })),
+      rawText: v.RawText ?? v.rawText
+    };
+  }
+  return result;
+}
+function readAnnotation(a) {
+  return {
+    id: a.Id ?? a.id,
+    annotationLabel: a.AnnotationLabel ?? a.annotationLabel,
+    rawText: a.RawText ?? a.rawText,
+    page: a.Page ?? a.page,
+    annotationJson: readAnnotationJson(a.AnnotationJson ?? a.annotationJson),
+    parentId: a.ParentId ?? a.parentId,
+    annotationType: a.AnnotationType ?? a.annotationType,
+    structural: a.Structural ?? a.structural
+  };
+}
+function readRelationship(r) {
+  return {
+    id: r.Id ?? r.id,
+    relationshipLabel: r.RelationshipLabel ?? r.relationshipLabel,
+    sourceAnnotationIds: r.SourceAnnotationIds ?? r.sourceAnnotationIds ?? [],
+    targetAnnotationIds: r.TargetAnnotationIds ?? r.targetAnnotationIds ?? [],
+    structural: r.Structural ?? r.structural
+  };
+}
+function readLabel(l) {
+  return {
+    id: l.Id ?? l.id,
+    color: l.Color ?? l.color,
+    description: l.Description ?? l.description ?? "",
+    icon: l.Icon ?? l.icon ?? "",
+    text: l.Text ?? l.text,
+    labelType: l.LabelType ?? l.labelType ?? "text"
+  };
+}
+function readLabels(raw) {
+  const labels = {};
+  for (const [key, value] of Object.entries(raw || {})) labels[key] = readLabel(value);
+  return labels;
+}
+function readOpenContractExport(parsed) {
+  return {
+    title: parsed.Title ?? parsed.title,
+    content: parsed.Content ?? parsed.content,
+    description: parsed.Description ?? parsed.description,
+    pageCount: parsed.PageCount ?? parsed.pageCount,
+    pawlsFileContent: (parsed.PawlsFileContent || parsed.pawlsFileContent || []).map(readPawlsPage),
+    docLabels: parsed.DocLabels ?? parsed.docLabels ?? [],
+    labelledText: (parsed.LabelledText || parsed.labelledText || []).map(readAnnotation),
+    relationships: (parsed.Relationships || parsed.relationships)?.map(readRelationship)
+  };
+}
+function readExternalAnnotationSet(parsed) {
+  return {
+    documentId: parsed.DocumentId ?? parsed.documentId,
+    documentHash: parsed.DocumentHash ?? parsed.documentHash,
+    createdAt: parsed.CreatedAt ?? parsed.createdAt,
+    updatedAt: parsed.UpdatedAt ?? parsed.updatedAt,
+    version: parsed.Version ?? parsed.version,
+    ...readOpenContractExport(parsed),
+    textLabels: readLabels(parsed.TextLabels || parsed.textLabels),
+    docLabelDefinitions: readLabels(parsed.DocLabelDefinitions || parsed.docLabelDefinitions)
+  };
+}
+function readExternalAnnotationValidation(parsed) {
+  return {
+    isValid: parsed.IsValid ?? parsed.isValid,
+    hashMismatch: parsed.HashMismatch ?? parsed.hashMismatch,
+    issues: (parsed.Issues || parsed.issues || []).map((i) => ({
+      annotationId: i.AnnotationId ?? i.annotationId,
+      issueType: i.IssueType ?? i.issueType,
+      description: i.Description ?? i.description,
+      expectedText: i.ExpectedText ?? i.expectedText,
+      actualText: i.ActualText ?? i.actualText
+    }))
+  };
+}
+function readProjectedHtml(parsed) {
+  return parsed.Html ?? parsed.html;
+}
+
 // src/history.ts
 var MAX_HISTORY_ARCHIVE_BYTES = 64 * 1024 * 1024;
 var DocxHistoryError = class extends Error {
@@ -6426,11 +6800,21 @@ async function generatePackageManifest(document2) {
     exports.DocumentConverter.GeneratePackageManifest(bytes)
   );
 }
-async function verifyDeliverable(document2, baseline) {
+async function verifyDeliverable(document2, baseline, request) {
   const exports = ensureInitialized();
   const bytes = await toBytes(document2);
   const baselineBytes = baseline === void 0 ? void 0 : await toBytes(baseline);
   await yieldToMain();
+  if (request !== void 0) {
+    const requestJson = serializeVerificationRequest(request);
+    const converter = exports.DocumentConverter;
+    if (!converter.VerifyDeliverableWithRequest || !converter.VerifyDeliverableWithBaselineAndRequest) {
+      throw new Error("This WASM bundle predates full verification requests; rebuild docxodus.");
+    }
+    return JSON.parse(
+      baselineBytes === void 0 ? converter.VerifyDeliverableWithRequest(bytes, requestJson) : converter.VerifyDeliverableWithBaselineAndRequest(baselineBytes, bytes, requestJson)
+    );
+  }
   return JSON.parse(
     baselineBytes === void 0 ? exports.DocumentConverter.VerifyDeliverable(bytes) : exports.DocumentConverter.VerifyDeliverableWithBaseline(
       baselineBytes,
@@ -6444,7 +6828,7 @@ async function verifyDeliveryReceipt(receiptJson, artifacts) {
     Object.fromEntries(
       Object.entries(artifacts).map(([artifactId, bytes]) => [
         artifactId,
-        bytesToBase64(bytes)
+        bytesToBase642(bytes)
       ])
     )
   );
@@ -6675,7 +7059,7 @@ async function docxDiffCompareBatch(baseline, candidates, settings, products) {
     const bytes = await toBytes(candidates[i].document);
     payload.push({
       name: candidates[i].name ?? String(i),
-      docB64: bytesToBase64(bytes)
+      docB64: bytesToBase642(bytes)
     });
   }
   await yieldToMain();
@@ -6751,7 +7135,7 @@ async function docxDiffRejectRevisions(redline) {
   }
   return result;
 }
-function bytesToBase64(bytes) {
+function bytesToBase642(bytes) {
   if (typeof btoa === "function") {
     let binary = "";
     const chunkSize = 32768;
@@ -6767,7 +7151,7 @@ async function reviewersJson(reviewers) {
   const arr = await Promise.all(
     reviewers.map(async (r) => ({
       author: r.author,
-      docB64: bytesToBase64(await toBytes(r.document))
+      docB64: bytesToBase642(await toBytes(r.document))
     }))
   );
   return JSON.stringify(arr);
@@ -7077,77 +7461,7 @@ async function exportToOpenContract(document2) {
     const error = parseError(result);
     throw new Error(`Failed to export to OpenContract format: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  const convertPawlsPage = (p) => ({
-    page: {
-      width: p.Page?.Width ?? p.page?.width,
-      height: p.Page?.Height ?? p.page?.height,
-      index: p.Page?.Index ?? p.page?.index
-    },
-    tokens: (p.Tokens || p.tokens || []).map((t) => ({
-      x: t.X ?? t.x,
-      y: t.Y ?? t.y,
-      width: t.Width ?? t.width,
-      height: t.Height ?? t.height,
-      text: t.Text ?? t.text
-    }))
-  });
-  const convertAnnotation = (a) => ({
-    id: a.Id ?? a.id,
-    annotationLabel: a.AnnotationLabel ?? a.annotationLabel,
-    rawText: a.RawText ?? a.rawText,
-    page: a.Page ?? a.page,
-    annotationJson: convertAnnotationJson(a.AnnotationJson ?? a.annotationJson),
-    parentId: a.ParentId ?? a.parentId,
-    annotationType: a.AnnotationType ?? a.annotationType,
-    structural: a.Structural ?? a.structural
-  });
-  const convertAnnotationJson = (json) => {
-    if (!json) return void 0;
-    if (json.Start !== void 0 || json.start !== void 0) {
-      return {
-        id: json.Id ?? json.id,
-        start: json.Start ?? json.start,
-        end: json.End ?? json.end,
-        text: json.Text ?? json.text
-      };
-    }
-    const result2 = {};
-    for (const [key, value] of Object.entries(json)) {
-      const v = value;
-      result2[key] = {
-        bounds: {
-          top: v.Bounds?.Top ?? v.bounds?.top,
-          bottom: v.Bounds?.Bottom ?? v.bounds?.bottom,
-          left: v.Bounds?.Left ?? v.bounds?.left,
-          right: v.Bounds?.Right ?? v.bounds?.right
-        },
-        tokensJsons: (v.TokensJsons || v.tokensJsons || []).map((t) => ({
-          pageIndex: t.PageIndex ?? t.pageIndex,
-          tokenIndex: t.TokenIndex ?? t.tokenIndex
-        })),
-        rawText: v.RawText ?? v.rawText
-      };
-    }
-    return result2;
-  };
-  const convertRelationship = (r) => ({
-    id: r.Id ?? r.id,
-    relationshipLabel: r.RelationshipLabel ?? r.relationshipLabel,
-    sourceAnnotationIds: r.SourceAnnotationIds ?? r.sourceAnnotationIds ?? [],
-    targetAnnotationIds: r.TargetAnnotationIds ?? r.targetAnnotationIds ?? [],
-    structural: r.Structural ?? r.structural
-  });
-  return {
-    title: parsed.Title ?? parsed.title,
-    content: parsed.Content ?? parsed.content,
-    description: parsed.Description ?? parsed.description,
-    pageCount: parsed.PageCount ?? parsed.pageCount,
-    pawlsFileContent: (parsed.PawlsFileContent || parsed.pawlsFileContent || []).map(convertPawlsPage),
-    docLabels: parsed.DocLabels ?? parsed.docLabels ?? [],
-    labelledText: (parsed.LabelledText || parsed.labelledText || []).map(convertAnnotation),
-    relationships: (parsed.Relationships || parsed.relationships)?.map(convertRelationship)
-  };
+  return readOpenContractExport(JSON.parse(result));
 }
 async function convertWmlToMarkdown(document2, settings = {}) {
   const exports = ensureInitialized();
@@ -7253,8 +7567,7 @@ async function createExternalAnnotationSet(document2, documentId) {
     const error = parseError(result);
     throw new Error(`Failed to create external annotation set: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return convertExternalAnnotationSet(parsed);
+  return readExternalAnnotationSet(JSON.parse(result));
 }
 async function validateExternalAnnotations(document2, annotationSet) {
   const exports = ensureInitialized();
@@ -7266,18 +7579,7 @@ async function validateExternalAnnotations(document2, annotationSet) {
     const error = parseError(result);
     throw new Error(`Failed to validate external annotations: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return {
-    isValid: parsed.IsValid ?? parsed.isValid,
-    hashMismatch: parsed.HashMismatch ?? parsed.hashMismatch,
-    issues: (parsed.Issues || parsed.issues || []).map((i) => ({
-      annotationId: i.AnnotationId ?? i.annotationId,
-      issueType: i.IssueType ?? i.issueType,
-      description: i.Description ?? i.description,
-      expectedText: i.ExpectedText ?? i.expectedText,
-      actualText: i.ActualText ?? i.actualText
-    }))
-  };
+  return readExternalAnnotationValidation(JSON.parse(result));
 }
 async function convertDocxToHtmlWithExternalAnnotations(document2, annotationSet, conversionOptions, projectionOptions) {
   const exports = ensureInitialized();
@@ -7298,8 +7600,7 @@ async function convertDocxToHtmlWithExternalAnnotations(document2, annotationSet
     const error = parseError(result);
     throw new Error(`Failed to convert with external annotations: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return parsed.Html ?? parsed.html;
+  return readProjectedHtml(JSON.parse(result));
 }
 async function searchTextOffsets(document2, searchText, maxResults = 100) {
   const exports = ensureInitialized();
@@ -7367,103 +7668,6 @@ function findTextOccurrences(documentText, searchText, maxResults = 100) {
   }
   return results;
 }
-function convertExternalAnnotationSet(parsed) {
-  const convertLabel = (l) => ({
-    id: l.Id ?? l.id,
-    color: l.Color ?? l.color,
-    description: l.Description ?? l.description ?? "",
-    icon: l.Icon ?? l.icon ?? "",
-    text: l.Text ?? l.text,
-    labelType: l.LabelType ?? l.labelType ?? "text"
-  });
-  const convertPawlsPage = (p) => ({
-    page: {
-      width: p.Page?.Width ?? p.page?.width,
-      height: p.Page?.Height ?? p.page?.height,
-      index: p.Page?.Index ?? p.page?.index
-    },
-    tokens: (p.Tokens || p.tokens || []).map((t) => ({
-      x: t.X ?? t.x,
-      y: t.Y ?? t.y,
-      width: t.Width ?? t.width,
-      height: t.Height ?? t.height,
-      text: t.Text ?? t.text
-    }))
-  });
-  const convertAnnotation = (a) => ({
-    id: a.Id ?? a.id,
-    annotationLabel: a.AnnotationLabel ?? a.annotationLabel,
-    rawText: a.RawText ?? a.rawText,
-    page: a.Page ?? a.page,
-    annotationJson: convertAnnotationJson(a.AnnotationJson ?? a.annotationJson),
-    parentId: a.ParentId ?? a.parentId,
-    annotationType: a.AnnotationType ?? a.annotationType,
-    structural: a.Structural ?? a.structural
-  });
-  const convertAnnotationJson = (json) => {
-    if (!json) return void 0;
-    if (json.Start !== void 0 || json.start !== void 0) {
-      return {
-        id: json.Id ?? json.id,
-        start: json.Start ?? json.start,
-        end: json.End ?? json.end,
-        text: json.Text ?? json.text
-      };
-    }
-    const result = {};
-    for (const [key, value] of Object.entries(json)) {
-      const v = value;
-      result[key] = {
-        bounds: {
-          top: v.Bounds?.Top ?? v.bounds?.top,
-          bottom: v.Bounds?.Bottom ?? v.bounds?.bottom,
-          left: v.Bounds?.Left ?? v.bounds?.left,
-          right: v.Bounds?.Right ?? v.bounds?.right
-        },
-        tokensJsons: (v.TokensJsons || v.tokensJsons || []).map((t) => ({
-          pageIndex: t.PageIndex ?? t.pageIndex,
-          tokenIndex: t.TokenIndex ?? t.tokenIndex
-        })),
-        rawText: v.RawText ?? v.rawText
-      };
-    }
-    return result;
-  };
-  const convertRelationship = (r) => ({
-    id: r.Id ?? r.id,
-    relationshipLabel: r.RelationshipLabel ?? r.relationshipLabel,
-    sourceAnnotationIds: r.SourceAnnotationIds ?? r.sourceAnnotationIds ?? [],
-    targetAnnotationIds: r.TargetAnnotationIds ?? r.targetAnnotationIds ?? [],
-    structural: r.Structural ?? r.structural
-  });
-  const textLabels = {};
-  const rawTextLabels = parsed.TextLabels || parsed.textLabels || {};
-  for (const [key, value] of Object.entries(rawTextLabels)) {
-    textLabels[key] = convertLabel(value);
-  }
-  const docLabelDefinitions = {};
-  const rawDocLabelDefs = parsed.DocLabelDefinitions || parsed.docLabelDefinitions || {};
-  for (const [key, value] of Object.entries(rawDocLabelDefs)) {
-    docLabelDefinitions[key] = convertLabel(value);
-  }
-  return {
-    documentId: parsed.DocumentId ?? parsed.documentId,
-    documentHash: parsed.DocumentHash ?? parsed.documentHash,
-    createdAt: parsed.CreatedAt ?? parsed.createdAt,
-    updatedAt: parsed.UpdatedAt ?? parsed.updatedAt,
-    version: parsed.Version ?? parsed.version,
-    title: parsed.Title ?? parsed.title,
-    content: parsed.Content ?? parsed.content,
-    description: parsed.Description ?? parsed.description,
-    pageCount: parsed.PageCount ?? parsed.pageCount,
-    pawlsFileContent: (parsed.PawlsFileContent || parsed.pawlsFileContent || []).map(convertPawlsPage),
-    docLabels: parsed.DocLabels ?? parsed.docLabels ?? [],
-    labelledText: (parsed.LabelledText || parsed.labelledText || []).map(convertAnnotation),
-    relationships: (parsed.Relationships || parsed.relationships)?.map(convertRelationship),
-    textLabels,
-    docLabelDefinitions
-  };
-}
 async function projectAnnotationsOntoHtml(html, annotationSet, projectionOptions) {
   const exports = ensureInitialized();
   await yieldToMain();
@@ -7478,8 +7682,7 @@ async function projectAnnotationsOntoHtml(html, annotationSet, projectionOptions
     const error = parseError(result);
     throw new Error(`Failed to project annotations: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return parsed.Html ?? parsed.html;
+  return readProjectedHtml(JSON.parse(result));
 }
 async function addAnnotationToHtml(html, annotation, label, projectionOptions) {
   const exports = ensureInitialized();
@@ -7497,8 +7700,7 @@ async function addAnnotationToHtml(html, annotation, label, projectionOptions) {
     const error = parseError(result);
     throw new Error(`Failed to add annotation to HTML: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return parsed.Html ?? parsed.html;
+  return readProjectedHtml(JSON.parse(result));
 }
 async function removeAnnotationFromHtml(html, annotationId, cssClassPrefix) {
   const exports = ensureInitialized();
@@ -7512,8 +7714,7 @@ async function removeAnnotationFromHtml(html, annotationId, cssClassPrefix) {
     const error = parseError(result);
     throw new Error(`Failed to remove annotation from HTML: ${error.error}`);
   }
-  const parsed = JSON.parse(result);
-  return parsed.Html ?? parsed.html;
+  return readProjectedHtml(JSON.parse(result));
 }
 async function generateAnnotationVisibilityCss(hiddenLabelIds, cssClassPrefix) {
   const exports = ensureInitialized();
@@ -11680,6 +11881,16 @@ function ensureBlockDragStyles(doc) {
 `;
   (doc.head ?? doc.documentElement).appendChild(style);
 }
+var CHROME_CARRIER_ANCHOR = "chrome-carrier";
+function yieldToEventLoop() {
+  return new Promise((resolve) => {
+    const settle = () => {
+      setTimeout(resolve, 0);
+    };
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(settle);
+    else settle();
+  });
+}
 function trackedChangeWireName(mode) {
   if (mode === 1 /* RenderInline */) return "render_inline";
   if (mode === 2 /* StripDeletions */) return "strip_deletions";
@@ -12347,7 +12558,64 @@ var DocxEditor = class _DocxEditor {
   }
   /** Open a document, render it into `container`, and wire up editing. */
   static open(container, bytes, exports, options = {}) {
-    const opts = {
+    const opts = _DocxEditor.resolveOptions(options);
+    const editor = _DocxEditor.openSession(container, bytes, exports, opts);
+    try {
+      editor.refreshAnchorMap();
+      if (opts.headerFooter) editor.createRegion();
+      const fullHtml = editor.renderFullHtml(bytes);
+      if (opts.paginated) editor.mountPaginated(fullHtml);
+      else editor.mountHtml(fullHtml);
+      editor.finishMount();
+      return editor;
+    } catch (error) {
+      editor.close();
+      throw error;
+    }
+  }
+  /**
+   * Open a document without holding the main thread for the whole mount (issue #776).
+   *
+   * {@link open} renders and wires the entire document in one synchronous task, which on a
+   * long document is the largest single block of a reading-and-editing session. This variant
+   * pays only the session open up front, then mounts the document in windows of body units,
+   * yielding to the event loop between them: the chrome — stylesheet, section wrappers with
+   * their page geometry, footnote and endnote sections — comes from one cheap engine render
+   * that sees no body content, and each window from the engine's block renderer, which lays
+   * units out exactly as the full render does (the plan's border-box grouping is never split).
+   * The DOM that results is the one {@link open} produces; blocks already mounted are editable
+   * while later windows are still landing, and edits made meanwhile are honoured because every
+   * window renders from the live session.
+   *
+   * Paginated mounts assemble the windows off-screen and paginate once at the end, since
+   * pagination is a one-shot flow over the whole document; the main thread is still free
+   * between windows, and `onProgress` lets a host show the fill.
+   *
+   * A bundle that predates the windowed renders mounts synchronously, exactly like {@link open}.
+   */
+  static async openAsync(container, bytes, exports, options = {}) {
+    const bridge = exports.DocxSessionBridge;
+    if (typeof bridge.RenderEditorChromeHtml !== "function" || typeof bridge.RenderEditorRangeHtml !== "function" || typeof bridge.ListRenderedBlocks !== "function") {
+      return _DocxEditor.open(container, bytes, exports, options);
+    }
+    const opts = _DocxEditor.resolveOptions(options);
+    const editor = _DocxEditor.openSession(container, bytes, exports, opts);
+    try {
+      editor.refreshAnchorMap();
+      if (opts.headerFooter) editor.createRegion();
+      await editor.mountWindowed(
+        Math.max(1, Math.floor(options.windowSize ?? 24)),
+        options.onProgress
+      );
+      editor.finishMount();
+      return editor;
+    } catch (error) {
+      editor.close();
+      throw error;
+    }
+  }
+  static resolveOptions(options) {
+    return {
       cssPrefix: options.cssPrefix ?? "docx-",
       fabricateClasses: options.fabricateClasses ?? false,
       editable: options.editable ?? true,
@@ -12366,25 +12634,100 @@ var DocxEditor = class _DocxEditor {
       onStoryChange: options.onStoryChange,
       onCommentsChange: options.onCommentsChange
     };
+  }
+  static openSession(container, bytes, exports, opts) {
     const handle = exports.DocxSessionBridge.OpenSession(bytes, JSON.stringify({
       emitMarkdownPatch: false,
       trackedChanges: trackedChangeWireName(opts.trackedChanges),
       revisionAuthor: opts.revisionAuthor
     }));
-    const editor = new _DocxEditor(container, exports, handle, opts);
-    try {
-      editor.refreshAnchorMap();
-      if (opts.headerFooter) editor.createRegion();
-      const fullHtml = editor.renderFullHtml(bytes);
-      if (opts.paginated) editor.mountPaginated(fullHtml);
-      else editor.mountHtml(fullHtml);
-      editor.syncRegionToBody();
-      editor.setupBlockDrag();
-      if (opts.comments) editor.createGutter();
-      return editor;
-    } catch (error) {
-      editor.close();
-      throw error;
+    return new _DocxEditor(container, exports, handle, opts);
+  }
+  /** The steps every mount ends with once the body is in the DOM. */
+  finishMount() {
+    this.syncRegionToBody();
+    this.setupBlockDrag();
+    if (this.options.comments) this.createGutter();
+  }
+  /**
+   * The windowed mount behind {@link openAsync}: chrome first, then body units in plan order,
+   * a group-aligned window per task. See {@link openAsync} for the contract.
+   */
+  async mountWindowed(windowSize, onProgress) {
+    const bridge = this.exports.DocxSessionBridge;
+    const profile = JSON.stringify({ ...JSON.parse(this.editorRenderProfile()), stampAnchors: true });
+    const chrome = bridge.RenderEditorChromeHtml(this.handle, profile);
+    if (chrome.trimStart().startsWith("{")) {
+      throw new Error(JSON.parse(chrome).error ?? "chrome render failed");
+    }
+    const parsed = new DOMParser().parseFromString(chrome, "text/html");
+    parsed.body.querySelectorAll(`[data-section-index] > [data-anchor="${CHROME_CARRIER_ANCHOR}"]`).forEach((el) => el.remove());
+    const styles = Array.from(parsed.querySelectorAll("style")).map((s) => s.outerHTML).join("");
+    const flow = document.createElement("div");
+    flow.className = "docx-body-flow";
+    flow.innerHTML = parsed.body.innerHTML;
+    const hosts = /* @__PURE__ */ new Map();
+    flow.querySelectorAll("[data-section-index]").forEach((el) => hosts.set(Number(el.getAttribute("data-section-index")), el));
+    const attachNow = !this.options.paginated;
+    const wireNow = attachNow && this.options.editable;
+    if (wireNow) this.wireBlocks(flow);
+    if (attachNow) {
+      this.region?.detachPages();
+      this.container.innerHTML = styles;
+      this.readoptGutter();
+      this.container.appendChild(flow);
+      this.editRoot = flow;
+    }
+    const plan = JSON.parse(this.renderPlanJson());
+    if (plan.error) throw new Error(plan.error);
+    const units = plan.body;
+    const sectionOf = new Map(units.map((u) => [unidOf(u.id), u.section ?? 0]));
+    const mounted = /* @__PURE__ */ new Set();
+    const place = (el, sameHostAs) => {
+      el.removeAttribute("xmlns");
+      const unit = el.hasAttribute("data-anchor") ? el : el.querySelector("[data-anchor]");
+      const unid = unit?.getAttribute("data-anchor") ?? "";
+      const host = sameHostAs ?? hosts.get(sectionOf.get(unid) ?? 0) ?? hosts.values().next().value ?? flow;
+      host.insertBefore(el, host.querySelector(":scope > section.endnotes"));
+      if (wireNow) {
+        if (el.hasAttribute("data-anchor")) this.wireBlock(el);
+        this.wireBlocks(el);
+      }
+      unit && mounted.add(unid);
+      el.querySelectorAll("[data-anchor]").forEach((n) => mounted.add(n.getAttribute("data-anchor")));
+      return host;
+    };
+    for (let start2 = 0; start2 < units.length; ) {
+      let end = Math.min(start2 + windowSize, units.length);
+      while (end < units.length && units[end].group !== void 0 && units[end].group === units[end - 1].group) end++;
+      const window2 = units.slice(start2, end);
+      const rendered = JSON.parse(bridge.RenderEditorRangeHtml(
+        this.handle,
+        JSON.stringify(window2.map((u) => u.id)),
+        profile
+      ));
+      if (!Array.isArray(rendered)) throw new Error(rendered.error ?? "window render failed");
+      for (const html of rendered) {
+        let host;
+        for (const el of Array.from(new DOMParser().parseFromString(html, "text/html").body.children)) {
+          host = place(el, host);
+        }
+      }
+      for (const unit of window2) {
+        if (mounted.has(unidOf(unit.id))) continue;
+        const el = this.renderInto(unit.id);
+        if (el) place(el);
+      }
+      start2 = end;
+      onProgress?.(start2, units.length);
+      if (start2 < units.length) await yieldToEventLoop();
+    }
+    if (attachNow) {
+      this.stampPlanState();
+      if (this.region) this.dockBands(flow);
+      this.viewport.attach(flow, true);
+    } else {
+      this.mountPaginated(parsed.head.innerHTML + flow.innerHTML);
     }
   }
   /**