docxodus 12.4.1 → 12.5.0

package/dist/embed.iife.js

@@ -251,6 +251,37 @@ var Docxodus = (() => {
     wasmBasePath: () => wasmBasePath
   });
 
+  // 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";
@@ -520,9 +551,23 @@ var Docxodus = (() => {
       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),
@@ -587,10 +632,152 @@ var Docxodus = (() => {
      * 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) => {
@@ -628,16 +815,16 @@ var Docxodus = (() => {
           );
           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.");
@@ -861,7 +1048,27 @@ var Docxodus = (() => {
         } 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();
       }
@@ -1440,6 +1647,18 @@ var Docxodus = (() => {
         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,
@@ -1570,6 +1789,28 @@ var Docxodus = (() => {
     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. */
@@ -1927,7 +2168,16 @@ var Docxodus = (() => {
      * 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)
       );
@@ -2156,6 +2406,7 @@ var Docxodus = (() => {
       return this.wasm.Save(this.handle);
     }
     close() {
+      this.retainedPreviewReceipts.clear();
       this.wasm.CloseSession(this.handle);
     }
     // TypeScript 5.2+ disposable protocol
@@ -2176,6 +2427,129 @@ var Docxodus = (() => {
     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 {
@@ -6565,11 +6939,21 @@ Your current draft and all later versions will be kept.`);
       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,
@@ -6583,7 +6967,7 @@ Your current draft and all later versions will be kept.`);
       Object.fromEntries(
         Object.entries(artifacts).map(([artifactId, bytes]) => [
           artifactId,
-          bytesToBase64(bytes)
+          bytesToBase642(bytes)
         ])
       )
     );
@@ -6814,7 +7198,7 @@ Your current draft and all later versions will be kept.`);
       const bytes = await toBytes(candidates[i].document);
       payload.push({
         name: candidates[i].name ?? String(i),
-        docB64: bytesToBase64(bytes)
+        docB64: bytesToBase642(bytes)
       });
     }
     await yieldToMain();
@@ -6890,7 +7274,7 @@ Your current draft and all later versions will be kept.`);
     }
     return result;
   }
-  function bytesToBase64(bytes) {
+  function bytesToBase642(bytes) {
     if (typeof btoa === "function") {
       let binary = "";
       const chunkSize = 32768;
@@ -6906,7 +7290,7 @@ Your current draft and all later versions will be kept.`);
     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);
@@ -7216,77 +7600,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7392,8 +7706,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7405,18 +7718,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7437,8 +7739,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7506,103 +7807,6 @@ Your current draft and all later versions will be kept.`);
     }
     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();
@@ -7617,8 +7821,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7636,8 +7839,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -7651,8 +7853,7 @@ Your current draft and all later versions will be kept.`);
       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();
@@ -11819,6 +12020,16 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
 `;
     (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";
@@ -12486,7 +12697,64 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
     }
     /** 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,
@@ -12505,25 +12773,100 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
         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);
       }
     }
     /**