docxodus 12.0.1 → 12.2.0

package/dist/embed.iife.js

@@ -141,8 +141,14 @@ var Docxodus = (() => {
     DocxDiffFormatComparison: () => DocxDiffFormatComparison,
     DocxDiffRevisionGranularity: () => DocxDiffRevisionGranularity,
     DocxEditor: () => DocxEditor,
+    DocxHistoryArchive: () => DocxHistoryArchive,
+    DocxHistoryClient: () => DocxHistoryClient,
+    DocxHistoryDocument: () => DocxHistoryDocument,
+    DocxHistoryError: () => DocxHistoryError,
+    DocxHistoryReader: () => DocxHistoryReader,
     DocxSession: () => DocxSession,
     EmptyParagraphMode: () => EmptyParagraphMode,
+    MAX_HISTORY_ARCHIVE_BYTES: () => MAX_HISTORY_ARCHIVE_BYTES,
     PaginationEngine: () => PaginationEngine,
     PaginationMode: () => PaginationMode,
     PlaceholderKinds: () => PlaceholderKinds,
@@ -166,6 +172,8 @@ var Docxodus = (() => {
     createBlankDocx: () => createBlankDocx,
     createEditor: () => createEditor,
     createExternalAnnotationSet: () => createExternalAnnotationSet,
+    createHistoryViewer: () => createHistoryViewer,
+    createMemoryHistoryStorage: () => createMemoryHistoryStorage,
     createRibbonEditor: () => createRibbonEditor,
     createUnavailablePageMap: () => createUnavailablePageMap,
     createViewer: () => createViewer,
@@ -200,6 +208,7 @@ var Docxodus = (() => {
     getWasmExports: () => getWasmExports,
     hasAnnotations: () => hasAnnotations,
     initialize: () => initialize,
+    installHistoryStorageImports: () => installHistoryStorageImports,
     isDeletion: () => isDeletion,
     isFormatChange: () => isFormatChange,
     isInitialized: () => isInitialized,
@@ -207,6 +216,8 @@ var Docxodus = (() => {
     isMove: () => isMove,
     mountRibbon: () => mountRibbon,
     navigateToPageCitation: () => navigateToPageCitation,
+    openDocxHistory: () => openDocxHistory,
+    openDocxHistoryArchive: () => openDocxHistoryArchive,
     openDocxSession: () => openDocxSession2,
     paginateHtml: () => paginateHtml,
     parseSectionDimensions: () => parseSectionDimensions,
@@ -2161,6 +2172,288 @@ var Docxodus = (() => {
     return new DocxSession(handle, bridge);
   }
 
+  // src/history.ts
+  var MAX_HISTORY_ARCHIVE_BYTES = 64 * 1024 * 1024;
+  var DocxHistoryError = class extends Error {
+    constructor(code, message) {
+      super(message);
+      this.code = code;
+      this.name = "DocxHistoryError";
+    }
+  };
+  var adapters = /* @__PURE__ */ new Map();
+  var nextAdapter = 0;
+  function adapter(id) {
+    const store = adapters.get(id);
+    if (!store) throw new DocxHistoryError("Closed", "History storage adapter is closed.");
+    return store;
+  }
+  function toBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 32768)
+      binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+    return btoa(binary);
+  }
+  function fromBase64(encoded) {
+    const binary = atob(encoded);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  }
+  function installHistoryStorageImports(setModuleImports) {
+    setModuleImports("docxodus.history", {
+      readBlob: async (id, json) => {
+        const reference = JSON.parse(json);
+        const bytes = await adapter(id).readBlob(reference);
+        if (bytes === null) return "";
+        if (bytes.length !== reference.length) throw new DocxHistoryError("PayloadMismatch", "Stored blob length differs from its reference.");
+        return bytes.length === 0 ? "=" : toBase64(bytes);
+      },
+      putBlob: async (id, json, bytes) => adapter(id).putBlob(JSON.parse(json), bytes.slice()),
+      readHead: async (id, documentId) => JSON.stringify(await adapter(id).readHead(documentId)),
+      advanceHead: async (id, documentId, expected, state) => JSON.stringify(await adapter(id).advanceHead(documentId, JSON.parse(expected), JSON.parse(state))),
+      initializeHead: async (id, documentId, head) => {
+        const storage = adapter(id);
+        if (!storage.initializeHead) throw new DocxHistoryError("InitializationUnsupported", "Storage cannot import an exact head.");
+        return JSON.stringify(await storage.initializeHead(documentId, JSON.parse(head)));
+      }
+    });
+  }
+  var DocxHistoryClient = class {
+    constructor(bridge, storage) {
+      this.bridge = bridge;
+      this.closed = false;
+      if (nextAdapter >= 2147483647) throw new Error("History adapter identifiers exhausted.");
+      this.adapterId = ++nextAdapter;
+      adapters.set(this.adapterId, storage);
+      try {
+        this.handle = storage.initializeHead && bridge.OpenWithInitialization ? bridge.OpenWithInitialization(this.adapterId) : bridge.Open(this.adapterId);
+      } catch (error) {
+        adapters.delete(this.adapterId);
+        throw error;
+      }
+    }
+    close() {
+      if (this.closed) return;
+      this.bridge.Close(this.handle);
+      adapters.delete(this.adapterId);
+      this.closed = true;
+    }
+    /** Bind an identity without reading, creating a version, or taking ownership of this client. */
+    document(documentId) {
+      return new DocxHistoryDocument(documentId, (operation, fields, bytes) => this.call(operation, documentId, fields, bytes));
+    }
+    async exportHistoryArchive(documentId) {
+      return fromBase64((await this.call("exportArchive", documentId)).bytes);
+    }
+    async importHistoryArchive(bytes) {
+      checkArchiveSize(bytes);
+      return (await this.call("importArchive", "", {}, bytes)).import;
+    }
+    async read(documentId) {
+      return (await this.call("read", documentId)).view;
+    }
+    /** Host-triggered validated metadata tail; first join starts at the latest checkpoint. */
+    async readChangesSince(documentId, after, maxEntriesToScan = 1e4) {
+      return (await this.call("updates", documentId, { expectedHead: after, maxEntriesToScan })).update;
+    }
+    async readOperationsSince(documentId, after, maxEntriesToScan = 1e4) {
+      return (await this.call("operations", documentId, { expectedHead: after, maxEntriesToScan })).operationUpdate;
+    }
+    async getOperation(documentId, operationId) {
+      return (await this.call("getOperation", documentId, { operationId })).operation;
+    }
+    async exportOperationProposal(documentId, operationId) {
+      return fromBase64((await this.call("exportOperationProposal", documentId, { operationId })).bytes);
+    }
+    async compareVersions(documentId, beforeVersionId, afterVersionId) {
+      return fromBase64((await this.call("compare", documentId, { beforeVersionId, afterVersionId })).bytes);
+    }
+    async createVersion(documentId, expectedHead, bytes, metadata, requestId) {
+      return (await this.call("create", documentId, { expectedHead, metadata, requestId }, bytes)).view;
+    }
+    async listVersions(documentId, cursor = null, limit = 25) {
+      return (await this.call("list", documentId, { versionId: cursor, limit })).page;
+    }
+    async getVersion(documentId, versionId) {
+      return (await this.call("get", documentId, { versionId })).version;
+    }
+    async exportVersion(documentId, versionId) {
+      return fromBase64((await this.call("export", documentId, { versionId })).bytes);
+    }
+    async materialize(documentId, sequence, maxEntriesToScan = 1e4) {
+      return fromBase64((await this.call("materialize", documentId, { sequence, maxEntriesToScan })).bytes);
+    }
+    async replay(documentId, sequence, maxEntriesToScan = 1e4) {
+      return fromBase64((await this.call("replay", documentId, { sequence, maxEntriesToScan })).bytes);
+    }
+    async resolveSequenceAtTime(documentId, cutoff, maxEntriesToScan = 1e4) {
+      return (await this.call("resolveTime", documentId, { cutoff, maxEntriesToScan })).sequence;
+    }
+    async restoreVersion(documentId, expectedHead, versionId, metadata, requestId) {
+      return (await this.call("restore", documentId, { expectedHead, versionId, metadata, requestId })).view;
+    }
+    async call(operation, documentId, fields = {}, bytes = new Uint8Array()) {
+      if (this.closed) throw new DocxHistoryError("Closed", "History client is closed.");
+      return parseResult(await this.bridge.Invoke(
+        this.handle,
+        JSON.stringify({ schemaVersion: 1, operation, documentId, ...fields }),
+        bytes
+      ));
+    }
+  };
+  var DocxHistoryReader = class {
+    /** @internal Obtain through client.document() or openDocxHistoryArchive(). */
+    constructor(documentId, call) {
+      this.call = call;
+      this.#documentId = documentId;
+    }
+    #documentId;
+    get documentId() {
+      return this.#documentId;
+    }
+    async read() {
+      return (await this.call("read")).view;
+    }
+    async listVersions(cursor = null, limit = 25) {
+      return (await this.call("list", { versionId: cursor, limit })).page;
+    }
+    async getVersion(versionId) {
+      return (await this.call("get", { versionId })).version;
+    }
+    /** Omit versionId for latest; pass an ID to keep a UI operation pinned to a captured version. */
+    async exportDocx(versionId = null) {
+      return fromBase64((await this.call("exportDocx", { versionId })).bytes);
+    }
+    async exportHistoryArchive() {
+      return fromBase64((await this.call("exportArchive")).bytes);
+    }
+    async materialize(sequence, maxEntriesToScan = 1e4) {
+      return fromBase64((await this.call("materialize", { sequence, maxEntriesToScan })).bytes);
+    }
+    async replay(sequence, maxEntriesToScan = 1e4) {
+      return fromBase64((await this.call("replay", { sequence, maxEntriesToScan })).bytes);
+    }
+    async resolveSequenceAtTime(cutoff, maxEntriesToScan = 1e4) {
+      return (await this.call("resolveTime", { cutoff, maxEntriesToScan })).sequence;
+    }
+    async readChangesSince(after, maxEntriesToScan = 1e4) {
+      return (await this.call("updates", { expectedHead: after, maxEntriesToScan })).update;
+    }
+    async readOperationsSince(after, maxEntriesToScan = 1e4) {
+      return (await this.call("operations", { expectedHead: after, maxEntriesToScan })).operationUpdate;
+    }
+    async getOperation(operationId) {
+      return (await this.call("getOperation", { operationId })).operation;
+    }
+    async exportOperationProposal(operationId) {
+      return fromBase64((await this.call("exportOperationProposal", { operationId })).bytes);
+    }
+    /** Redlined DOCX through DocxCompare's existing accepted-input revision policy. */
+    async compareVersions(beforeVersionId, afterVersionId) {
+      return fromBase64((await this.call("compare", { beforeVersionId, afterVersionId })).bytes);
+    }
+  };
+  var DocxHistoryDocument = class extends DocxHistoryReader {
+    async createVersion(expectedHead, bytes, metadata, requestId) {
+      requireRequestId(requestId);
+      return (await this.call("create", { expectedHead, metadata, requestId }, bytes)).view;
+    }
+    async restoreVersion(expectedHead, versionId, metadata, requestId) {
+      requireRequestId(requestId);
+      return (await this.call("restore", { expectedHead, versionId, metadata, requestId })).view;
+    }
+  };
+  var DocxHistoryArchive = class _DocxHistoryArchive extends DocxHistoryReader {
+    constructor(bridge, handle, info) {
+      super(info.documentId, async (operation, fields = {}, bytes = new Uint8Array()) => {
+        if (this.closed) throw new DocxHistoryError("Closed", "History archive is closed.");
+        return parseResult(await bridge.Invoke(
+          handle,
+          JSON.stringify({ schemaVersion: 1, operation, documentId: this.documentId, ...fields }),
+          bytes
+        ));
+      });
+      this.bridge = bridge;
+      this.handle = handle;
+      this.info = info;
+      this.closed = false;
+    }
+    /** For custom loaders; normal callers use openDocxHistoryArchive(). */
+    static async open(bridge, bytes) {
+      checkArchiveSize(bytes);
+      if (!bridge.OpenArchive) throw new Error("This WASM build does not include portable history.");
+      const result = parseResult(await bridge.OpenArchive(bytes));
+      return new _DocxHistoryArchive(bridge, result.handle, result.archive);
+    }
+    close() {
+      if (this.closed) return;
+      this.bridge.Close(this.handle);
+      this.closed = true;
+    }
+  };
+  function parseResult(json) {
+    const result = JSON.parse(json);
+    if (!result.success) throw new DocxHistoryError(result.errorCode, result.message);
+    return result;
+  }
+  function checkArchiveSize(bytes) {
+    if (bytes.length > MAX_HISTORY_ARCHIVE_BYTES) throw new DocxHistoryError("ResourceLimit", "History archive exceeds 64 MiB.");
+  }
+  function requireRequestId(requestId) {
+    if (typeof requestId !== "string" || !requestId.trim()) throw new DocxHistoryError("InvalidRequest", "A durable requestId is required.");
+  }
+  function createMemoryHistoryStorage(maxBlobBytes = 256 * 1024 * 1024) {
+    if (!Number.isSafeInteger(maxBlobBytes) || maxBlobBytes <= 0) throw new RangeError("Invalid blob byte limit.");
+    const blobs = /* @__PURE__ */ new Map();
+    const heads = /* @__PURE__ */ new Map();
+    const copy = (value) => JSON.parse(JSON.stringify(value));
+    const key = (reference) => {
+      if (reference.digest.algorithm !== "SHA-256" || !/^[a-f0-9]{64}$/.test(reference.digest.value) || !Number.isSafeInteger(reference.length) || reference.length < 0 || reference.length > maxBlobBytes)
+        throw new DocxHistoryError("InvalidRequest", "Invalid blob reference or byte limit.");
+      return `${reference.digest.value}:${reference.length}`;
+    };
+    const equalReference = (a, b) => a.length === b.length && a.digest.algorithm === b.digest.algorithm && a.digest.value === b.digest.value;
+    const equalHead = (a, b) => a === null || b === null ? a === b : a.revision === b.revision && equalReference(a.state, b.state);
+    return {
+      async readBlob(reference) {
+        return blobs.get(key(reference))?.slice() ?? null;
+      },
+      async putBlob(reference, bytes) {
+        const blobKey = key(reference);
+        const captured = bytes.slice();
+        if (captured.length !== reference.length) throw new DocxHistoryError("PayloadMismatch", "Blob length mismatch.");
+        const digest = Array.from(
+          new Uint8Array(await crypto.subtle.digest("SHA-256", captured)),
+          (n) => n.toString(16).padStart(2, "0")
+        ).join("");
+        if (digest !== blobKey.split(":")[0]) throw new DocxHistoryError("PayloadMismatch", "Blob digest mismatch.");
+        if (!blobs.has(blobKey)) blobs.set(blobKey, captured);
+      },
+      async readHead(documentId) {
+        return copy(heads.get(documentId) ?? null);
+      },
+      async advanceHead(documentId, expected, state) {
+        key(state);
+        const current = heads.get(documentId) ?? null;
+        if (!equalHead(current, expected)) return null;
+        const revision = BigInt(current?.revision ?? "0") + 1n;
+        if (revision > 9223372036854775807n) throw new RangeError("History revision exhausted.");
+        const head = { revision: String(revision), state: copy(state) };
+        heads.set(documentId, head);
+        return copy(head);
+      },
+      async initializeHead(documentId, head) {
+        key(head.state);
+        if (typeof head.revision !== "string" || !/^[1-9][0-9]*$/.test(head.revision) || BigInt(head.revision) > 9223372036854775807n)
+          throw new DocxHistoryError("InvalidRequest", "Imported head revision must be a positive Int64 string.");
+        const existing = heads.get(documentId);
+        if (existing) return { initialized: false, head: copy(existing) };
+        const captured = copy(head);
+        heads.set(documentId, captured);
+        return { initialized: true, head: copy(captured) };
+      }
+    };
+  }
+
   // src/page-number-format.ts
   var ROMAN_ONES = ["", "i", "ii", "iii", "iv", "v", "vi", "vii", "viii", "ix"];
   var ROMAN_TENS = ["", "x", "xx", "xxx", "xl", "l", "lx", "lxx", "lxxx", "xc"];
@@ -5610,11 +5903,11 @@ var Docxodus = (() => {
           if (!this.partUriFor(which, "default")) this.seedStory(which, "default");
           if (!this.partUriFor(which, kind)) this.seedStory(which, kind);
         }
-        const res = parseResult(this.bridge.EnsureHeaderFooterVisible(this.handle, this.bodyAnchorId, kind));
+        const res = parseResult2(this.bridge.EnsureHeaderFooterVisible(this.handle, this.bodyAnchorId, kind));
         if (!res.success) return false;
       } else {
         if (!this.bridge.SetHeaderFooterKindEnabled) return false;
-        const res = parseResult(this.bridge.SetHeaderFooterKindEnabled(this.handle, this.bodyAnchorId, kind, false));
+        const res = parseResult2(this.bridge.SetHeaderFooterKindEnabled(this.handle, this.bodyAnchorId, kind, false));
         if (!res.success) return false;
         for (const which of ["header", "footer"]) {
           if (this.kinds[which] === kind) this.kinds[which] = "default";
@@ -5639,7 +5932,7 @@ var Docxodus = (() => {
      *  Deliberately a PLAIN field (no `\*` switch), exactly as Word inserts one, so it follows the
      *  section's page-number format — see {@link setPageNumbering}. */
     insertPageNumber(which, anchorId, field) {
-      const res = parseResult(this.bridge.InsertPageNumberField(this.handle, anchorId, field, ""));
+      const res = parseResult2(this.bridge.InsertPageNumberField(this.handle, anchorId, field, ""));
       if (!res.success) return false;
       this.refresh(which);
       return true;
@@ -5662,7 +5955,7 @@ var Docxodus = (() => {
     /** Set this section's page numbering (`w:pgNumType`) — Word's *Format Page Numbers…*. */
     setPageNumbering(op) {
       if (!this.bodyAnchorId) return false;
-      const res = parseResult(this.bridge.SetPageNumbering(this.handle, this.bodyAnchorId, JSON.stringify(op)));
+      const res = parseResult2(this.bridge.SetPageNumbering(this.handle, this.bodyAnchorId, JSON.stringify(op)));
       if (!res.success) return false;
       this.reloadSection();
       return true;
@@ -5674,7 +5967,7 @@ var Docxodus = (() => {
     /** Remove this section's page-numbering start/format. */
     clearPageNumbering() {
       if (!this.bodyAnchorId) return false;
-      const res = parseResult(this.bridge.ClearPageNumbering(this.handle, this.bodyAnchorId));
+      const res = parseResult2(this.bridge.ClearPageNumbering(this.handle, this.bodyAnchorId));
       if (!res.success) return false;
       this.reloadSection();
       return true;
@@ -5985,7 +6278,7 @@ var Docxodus = (() => {
     seedStory(which, kind) {
       if (!this.bodyAnchorId) return;
       const set = which === "header" ? this.bridge.SetHeaderText : this.bridge.SetFooterText;
-      const res = parseResult(set(this.handle, this.bodyAnchorId, kind, ""));
+      const res = parseResult2(set(this.handle, this.bodyAnchorId, kind, ""));
       if (!res.success) return;
       this.callbacks.refreshAnchorMap();
       this.sectionInfo = this.readSectionInfo(this.bodyAnchorId);
@@ -6141,7 +6434,7 @@ var Docxodus = (() => {
     const range = d.caretRangeFromPoint?.(x, y);
     return range ? { node: range.startContainer, offset: range.startOffset } : null;
   }
-  function parseResult(json) {
+  function parseResult2(json) {
     try {
       return JSON.parse(json);
     } catch {
@@ -8374,7 +8667,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
     };
   }
   var honeyPotFix = makeHoneyPotFix();
-  var adapter = makeAdapter({
+  var adapter2 = makeAdapter({
     typeKey: "element",
     defaultDropEffect: "move",
     mount: function mount(api2) {
@@ -8463,8 +8756,8 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
     },
     onPostDispatch: honeyPotFix.getOnPostDispatch()
   });
-  var dropTargetForElements = adapter.dropTarget;
-  var monitorForElements = adapter.monitor;
+  var dropTargetForElements = adapter2.dropTarget;
+  var monitorForElements = adapter2.monitor;
   function draggable(args) {
     if (true) {
       if (args.dragHandle && !args.element.contains(args.dragHandle)) {
@@ -8488,7 +8781,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       // this is because you *must* have a draggable element to start a drag
       // but you _might_ not have any drop targets immediately
       // (You might create drop targets async)
-      adapter.registerUsage(),
+      adapter2.registerUsage(),
       addToRegistry(args),
       addAttribute(args.element, {
         attribute: "draggable",
@@ -9571,6 +9864,12 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
     const text = (unit.textContent ?? "").trim().replace(/\s+/g, " ");
     return text.length > 48 ? `${text.slice(0, 48)}\u2026` : text;
   }
+  var BLOCK_HANDLE_WIDTH = 26;
+  var BLOCK_HANDLE_HEIGHT = 28;
+  var BLOCK_HANDLE_GAP = 6;
+  function clampToRange(value, low, high) {
+    return Math.max(low, Math.min(value, high));
+  }
   function ensureBlockDragStyles(doc) {
     if (blockDragStyledDocuments.has(doc)) return;
     blockDragStyledDocuments.add(doc);
@@ -9929,22 +10228,55 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
     const span = trimmedSpan(block, { start: Math.min(start2, end), length: Math.abs(end - start2) });
     return span.length > 0 ? span : null;
   }
-  function selectRange(el, start2, length) {
-    const sel = typeof window !== "undefined" ? window.getSelection() : null;
-    if (!sel || !el.isConnected) return;
-    el.focus();
-    const range = document.createRange();
+  function contentRangeIn(el, start2, length) {
+    if (!el.isConnected) return null;
+    const doc = el.ownerDocument;
+    const range = doc.createRange();
     const from = contentPositionIn(el, start2);
     const to = contentPositionIn(el, start2 + length);
     try {
       range.setStart(from.node, from.offset);
       range.setEnd(to.node, to.offset);
     } catch {
-      return;
+      return null;
     }
+    return range;
+  }
+  function selectRange(el, start2, length) {
+    const sel = typeof window !== "undefined" ? window.getSelection() : null;
+    if (!sel || !el.isConnected) return;
+    el.focus();
+    const range = contentRangeIn(el, start2, length);
+    if (!range) return;
     sel.removeAllRanges();
     sel.addRange(range);
   }
+  var FIND_HIGHLIGHT = "docxodus-find";
+  var FIND_HIGHLIGHT_ACTIVE = "docxodus-find-active";
+  var FIND_PAINT_LIMIT = 500;
+  var findHighlightStyledDocuments = /* @__PURE__ */ new WeakSet();
+  var findPaintOwner = null;
+  function ensureFindHighlightStyles(doc) {
+    if (findHighlightStyledDocuments.has(doc)) return;
+    findHighlightStyledDocuments.add(doc);
+    const style = doc.createElement("style");
+    style.dataset.docxodusFindHighlight = "true";
+    style.textContent = `
+::highlight(${FIND_HIGHLIGHT}) { background-color: rgba(15, 118, 110, .16); }
+::highlight(${FIND_HIGHLIGHT_ACTIVE}) { background-color: rgba(15, 118, 110, .38); }
+`;
+    (doc.head ?? doc.documentElement).appendChild(style);
+  }
+  function highlightRegistry() {
+    if (typeof CSS === "undefined") return null;
+    const registry = CSS.highlights;
+    const ctor = globalThis.Highlight;
+    return registry && typeof ctor === "function" ? registry : null;
+  }
+  function makeHighlight(ranges) {
+    const ctor = globalThis.Highlight;
+    return new ctor(...ranges);
+  }
   function inBorderWrapper(el) {
     const style = el.parentElement?.getAttribute("style") ?? "";
     return /border-(top|bottom|left|right):\s*(?!none)[^;]+/i.test(style);
@@ -10033,6 +10365,10 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       this.blockMoveMenu = null;
       this.blockMoveLive = null;
       this.blockDragSource = null;
+      /** Whether hover or focus currently wants a handle for `blockDragSource`.
+       *  Tracked apart from the handle's `display`, which the viewport clip also drives: a handle
+       *  withdrawn because its block scrolled out of view has to come back when it scrolls in. */
+      this.blockHandleWanted = false;
       this.blockDragCleanup = [];
       /** Block boxes measured at drag start — see `BlockDropZone`. Empty when no drag is in flight. */
       this.dropZones = [];
@@ -10311,6 +10647,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
         document.removeEventListener("mouseup", this.onMouseUp, true);
       }
       this.clearDragSelection();
+      this.clearFindMatches();
       this.teardownBlockDrag();
       this.gutter?.dispose();
       this.gutter = null;
@@ -10429,11 +10766,47 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       }
       return null;
     }
+    /**
+     * The rectangle the floating handle may occupy: the window, narrowed by every ancestor that
+     * clips its overflow.
+     *
+     * The handle is `position: fixed`, so it is placed in viewport coordinates and no ancestor's
+     * overflow clips it for us. But the editor is routinely mounted inside a bounded scroller —
+     * the ribbon puts its surface in one, inside a clipped card — and a block scrolled out of that
+     * scroller has to take its handle with it rather than leave it parked over the host's chrome.
+     *
+     * Gated on the computed `overflow` rather than on whether an element scrolls right now, so the
+     * answer does not depend on how much content happens to be loaded.
+     */
+    blockHandleClipRect() {
+      const view = this.container.ownerDocument.defaultView;
+      const clip = {
+        top: 0,
+        left: 0,
+        right: view?.innerWidth ?? Number.MAX_SAFE_INTEGER,
+        bottom: view?.innerHeight ?? Number.MAX_SAFE_INTEGER
+      };
+      for (let el = this.editRoot; el; el = el.parentElement) {
+        const style = view?.getComputedStyle(el);
+        if (!style || style.overflowX === "visible" && style.overflowY === "visible") continue;
+        const box = el.getBoundingClientRect();
+        if (style.overflowY !== "visible") {
+          clip.top = Math.max(clip.top, box.top);
+          clip.bottom = Math.min(clip.bottom, box.bottom);
+        }
+        if (style.overflowX !== "visible") {
+          clip.left = Math.max(clip.left, box.left);
+          clip.right = Math.min(clip.right, box.right);
+        }
+      }
+      return clip;
+    }
     showBlockHandle(unit) {
       const handle = this.blockDragHandle;
       if (!handle || !this.isMovableBlockUnit(unit)) return;
       const changed = unit !== this.blockDragSource;
       this.blockDragSource = unit;
+      this.blockHandleWanted = true;
       const known = this.blockMoveTargetsFor(unit, { cachedOnly: true });
       if (known?.size === 0) {
         handle.style.display = "none";
@@ -10441,19 +10814,31 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       }
       if (changed && known === void 0) this.prefetchBlockMoveTargets(unit);
       const rect = unit.getBoundingClientRect();
+      const clip = this.blockHandleClipRect();
+      if (rect.bottom <= clip.top || rect.top >= clip.bottom || rect.right <= clip.left || rect.left >= clip.right) {
+        if (!this.blockDragging && this.blockMoveMenu?.style.display !== "block")
+          handle.style.display = "none";
+        return;
+      }
       handle.style.display = "flex";
-      handle.style.left = `${Math.max(4, rect.left - 32)}px`;
-      handle.style.top = `${Math.max(4, rect.top + (unit.tagName === "TABLE" ? 6 : Math.max(0, (rect.height - 28) / 2)))}px`;
+      const top2 = rect.top + (unit.tagName === "TABLE" ? 6 : Math.max(0, (rect.height - BLOCK_HANDLE_HEIGHT) / 2));
+      handle.style.left = `${clampToRange(
+        rect.left - (BLOCK_HANDLE_WIDTH + BLOCK_HANDLE_GAP),
+        clip.left,
+        clip.right - BLOCK_HANDLE_WIDTH
+      )}px`;
+      handle.style.top = `${clampToRange(top2, clip.top, clip.bottom - BLOCK_HANDLE_HEIGHT)}px`;
       const preview = blockPreviewText(unit);
       handle.setAttribute("aria-label", preview ? `Move block: ${preview}` : "Move block");
     }
     hideBlockHandle() {
       if (this.blockDragging || this.blockMoveMenu?.style.display === "block") return;
+      this.blockHandleWanted = false;
       if (this.blockDragHandle) this.blockDragHandle.style.display = "none";
     }
     positionBlockHandle() {
       const source = this.currentBlockDragSource();
-      if (source && this.blockDragHandle?.style.display !== "none") this.showBlockHandle(source);
+      if (source && this.blockHandleWanted) this.showBlockHandle(source);
     }
     /** Draw the drop line on `zone`'s requested edge, or take it away when there is no target. */
     paintDropIndicator(data) {
@@ -10891,6 +11276,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       this.blockMoveMenu = null;
       this.blockMoveLive = null;
       this.blockDragSource = null;
+      this.blockHandleWanted = false;
       this.blockDragging = false;
       this.blockDragPointerDown = false;
     }
@@ -12660,15 +13046,65 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       }
       return out;
     }
-    /** Select a match and scroll it into view. */
+    /**
+     * Select a match, focus its block and scroll it into view — the caret lands on the hit, so
+     * typing continues in the document. A find box that is still being typed into wants
+     * `showFindMatches` instead; this is the commit step (closing the bar, jumping in to edit).
+     */
     selectMatch(match) {
       if (!match.block.isConnected) return;
+      this.clearFindMatches();
       this.activeBlock = match.block;
       selectRange(match.block, match.start, match.length);
       match.block.scrollIntoView({ block: "center", behavior: "smooth" });
     }
-    /** Replace one match's text (formatting of the surrounding run is inherited). */
-    replaceMatch(match, replacement) {
+    /**
+     * Paint `matches` and scroll the one at `activeIndex` into view WITHOUT moving focus or the
+     * caret. This is what a find field calls on every keystroke: the document shows where the hits
+     * are and rides to the current one, while the keyboard stays in the search box.
+     *
+     * Falls back to the document selection where the CSS Custom Highlight API is missing — still
+     * without focusing the block, so the next character typed goes to the search field either way.
+     */
+    showFindMatches(matches, activeIndex) {
+      const active = matches[activeIndex];
+      this.clearFindMatches();
+      if (!active || !active.block.isConnected) return;
+      this.activeBlock = active.block;
+      const activeRange = contentRangeIn(active.block, active.start, active.length);
+      const registry = highlightRegistry();
+      if (registry && activeRange) {
+        ensureFindHighlightStyles(this.container.ownerDocument);
+        const rest = [];
+        for (let i = 0; i < matches.length && rest.length < FIND_PAINT_LIMIT; i++) {
+          if (i === activeIndex) continue;
+          const range = contentRangeIn(matches[i].block, matches[i].start, matches[i].length);
+          if (range) rest.push(range);
+        }
+        if (rest.length > 0) registry.set(FIND_HIGHLIGHT, makeHighlight(rest));
+        registry.set(FIND_HIGHLIGHT_ACTIVE, makeHighlight([activeRange]));
+        findPaintOwner = this;
+      } else if (activeRange) {
+        const sel = this.container.ownerDocument.defaultView?.getSelection();
+        sel?.removeAllRanges();
+        sel?.addRange(activeRange);
+      }
+      active.block.scrollIntoView({ block: "center", behavior: "smooth" });
+    }
+    /** Drop the find painting (closing the find bar, or committing a match to the caret). */
+    clearFindMatches() {
+      if (findPaintOwner !== this) return;
+      const registry = highlightRegistry();
+      registry?.delete(FIND_HIGHLIGHT);
+      registry?.delete(FIND_HIGHLIGHT_ACTIVE);
+      findPaintOwner = null;
+    }
+    /**
+     * Replace one match's text (formatting of the surrounding run is inherited). `focus: false`
+     * leaves the keyboard where it is — a Replace button pressed from the find bar must not drag
+     * the caret into the document mid-search.
+     */
+    replaceMatch(match, replacement, options = {}) {
       const block = match.block;
       if (this.closed || !block.isConnected) return false;
       const unid = block.getAttribute("data-anchor");
@@ -12689,7 +13125,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       );
       if (!res.success) return false;
       const fresh = this.swapBlock(block, unid, res.modified?.[0]);
-      if (fresh) selectRange(fresh, span.start, replacement.length);
+      if (fresh && options.focus !== false) selectRange(fresh, span.start, replacement.length);
       return true;
     }
     /** Replace every occurrence; returns how many were replaced. */
@@ -12708,7 +13144,11 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
         for (const m of list.slice().sort((a, b) => b.start - a.start)) {
           if (!current.isConnected) break;
           const before = current;
-          if (this.replaceMatch({ block: current, start: m.start, length: m.length }, replacement)) {
+          if (this.replaceMatch(
+            { block: current, start: m.start, length: m.length },
+            replacement,
+            { focus: options.focus }
+          )) {
             count++;
             current = this.activeBlock && this.activeBlock !== before ? this.activeBlock : current;
           }
@@ -13390,7 +13830,7 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
   }
 
   // src/ribbon-chrome.ts
-  var RIBBON_STYLE_VERSION = "10";
+  var RIBBON_STYLE_VERSION = "11";
   var RIBBON_STYLE_ATTR = "data-docxodus-ribbon-styles";
   var COMMENT_GUTTER_WIDTH = 264;
   var RIBBON_CSS = `
@@ -13823,9 +14263,11 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
   background: linear-gradient(to top, var(--dxr-desk), transparent);
 }
 .dxr[data-chrome] .dxr-surface { position: relative; margin: 26px auto; padding: 0 16px 96px; }
-/* The comment gutter sits to the right of the sheet; the surface reserves its width so the
-   page shifts left rather than the bubbles covering it \u2014 Word's markup area. */
-.dxr[data-chrome="full"] .dxr-surface[data-comments="on"] { padding-right: calc(var(--dxr-gutter) + 8px); }
+/* Reserve the markup area only while a visible comment or draft needs it. The gutter owns
+   its empty/hidden state, so ordinary documents stay centered without disabling comments. */
+.dxr[data-chrome="full"] .dxr-surface[data-comments="on"]:has(> .docx-comment-gutter:not([data-empty]):not([hidden])) {
+  padding-right: calc(var(--dxr-gutter) + 8px);
+}
 .dxr-surface [contenteditable="true"]:focus {
   outline: 2px solid var(--dxr-accent);
   outline-offset: 2px;
@@ -15976,11 +16418,18 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
         if (!this.live || !text.value) return;
         let count = 0;
         this.run("replace all", () => {
-          count = this.live.replaceAll(text.value, replace.value, { matchCase: matchCase.checked });
+          count = this.live.replaceAll(text.value, replace.value, {
+            matchCase: matchCase.checked,
+            focus: false
+          });
         });
         this.setStatus(`Replaced ${count} occurrence${count === 1 ? "" : "s"}`);
         this.refreshFind(true);
       });
+      for (const id of ["findprev", "findnext", "replaceone", "replaceall"]) {
+        const button = this.control(id);
+        if (button) this.keepSelection(button);
+      }
       bar.hidden = true;
     }
     openFindBar(withReplace) {
@@ -15991,28 +16440,44 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       const text = this.require("findtext");
       text.focus();
       text.select();
-      this.refreshFind(false);
+      this.refreshFind(true);
     }
+    /**
+     * Close the bar and hand the current hit over to the caret: the document is where the user is
+     * going next, and Word leaves the insertion point on the match it stopped at. Until this runs
+     * the match is only PAINTED (see `showFindMatches`), so the search field keeps the keyboard for
+     * as long as the bar is open.
+     */
     closeFindBar() {
       const bar = this.control("findbar");
       if (bar) bar.hidden = true;
+      const match = this.findMatches[this.findIndex];
+      if (match) this.live?.selectMatch(match);
+      else this.live?.clearFindMatches();
       this.findMatches = [];
       this.findIndex = -1;
     }
-    refreshFind(select) {
+    /**
+     * Re-scan for the current query. `show` paints the hits and rides to the first one — it never
+     * focuses the document, so typing the second character of a query that already matched goes on
+     * refining the search instead of being typed into the document.
+     */
+    refreshFind(show) {
       const text = this.require("findtext");
       const matchCase = this.require("findcase").checked;
       this.findMatches = this.live && text.value ? this.live.find(text.value, { matchCase }) : [];
       this.findIndex = this.findMatches.length > 0 ? 0 : -1;
       this.updateFindCount();
-      if (select && this.findIndex >= 0) this.live?.selectMatch(this.findMatches[this.findIndex]);
+      if (!show) return;
+      if (this.findIndex >= 0) this.live?.showFindMatches(this.findMatches, this.findIndex);
+      else this.live?.clearFindMatches();
     }
     stepFind(direction) {
       if (!this.live) return;
       if (this.findMatches.length === 0) this.refreshFind(false);
       if (this.findMatches.length === 0) return;
       this.findIndex = (this.findIndex + direction + this.findMatches.length) % this.findMatches.length;
-      this.live.selectMatch(this.findMatches[this.findIndex]);
+      this.live.showFindMatches(this.findMatches, this.findIndex);
       this.updateFindCount();
     }
     replaceCurrent() {
@@ -16021,12 +16486,12 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
       const match = this.findMatches[this.findIndex];
       if (!match) return;
       const replacement = this.require("replacetext").value;
-      this.run("replace", () => this.live.replaceMatch(match, replacement));
+      this.run("replace", () => this.live.replaceMatch(match, replacement, { focus: false }));
       const keep = this.findIndex;
       this.refreshFind(false);
       if (this.findMatches.length > 0) {
         this.findIndex = Math.min(keep, this.findMatches.length - 1);
-        this.live.selectMatch(this.findMatches[this.findIndex]);
+        this.live.showFindMatches(this.findMatches, this.findIndex);
         this.updateFindCount();
       }
     }
@@ -16458,6 +16923,16 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
 
   // src/index.ts
   var import_meta = {};
+  function openDocxHistory(storage) {
+    const bridge = ensureInitialized().HistoryBridge;
+    if (!bridge) throw new Error("This WASM build does not include history bindings.");
+    return new DocxHistoryClient(bridge, storage);
+  }
+  function openDocxHistoryArchive(bytes) {
+    const bridge = ensureInitialized().HistoryBridge;
+    if (!bridge) throw new Error("This WASM build does not include history bindings.");
+    return DocxHistoryArchive.open(bridge, bytes);
+  }
   function openDocxSession2(bytes, settings) {
     const wasm = ensureInitialized();
     return openDocxSession(bytes, wasm, settings);
@@ -16512,14 +16987,16 @@ span.comment-highlight.docx-comment-active { background: hsl(var(--docx-comment-
         /* @vite-ignore */
         dotnetPath
       );
-      const { getAssemblyExports, getConfig } = await dotnet.withDiagnosticTracing(false).create();
+      const { getAssemblyExports, getConfig, setModuleImports } = await dotnet.withDiagnosticTracing(false).create();
+      installHistoryStorageImports(setModuleImports);
       const config = getConfig();
       const exports = await getAssemblyExports(config.mainAssemblyName);
       wasmExports = {
         DocumentConverter: exports.DocxodusWasm.DocumentConverter,
         DocumentComparer: exports.DocxodusWasm.DocumentComparer,
         DocxDiffBridge: exports.DocxodusWasm.DocxDiffBridge,
-        DocxSessionBridge: exports.DocxodusWasm.DocxSessionBridge
+        DocxSessionBridge: exports.DocxodusWasm.DocxSessionBridge,
+        HistoryBridge: exports.DocxodusWasm.HistoryBridge
       };
       return true;
     } catch {
@@ -17894,6 +18371,20 @@ ${parsed.documentElement.outerHTML}`;
     }
     throw new Error("Docxodus embed: unsupported document source");
   }
+  function scopedDocumentFragment(mount2, html) {
+    const parsed = new DOMParser().parseFromString(html, "text/html");
+    const fragment = document.createDocumentFragment();
+    parsed.querySelectorAll("style").forEach((sourceStyle) => {
+      const style = document.createElement("style");
+      style.textContent = sourceStyle.textContent;
+      scopeStyleElement(style, mount2.selector);
+      fragment.appendChild(style);
+    });
+    const body = document.createElement("template");
+    body.innerHTML = parsed.body.innerHTML;
+    fragment.appendChild(body.content);
+    return fragment;
+  }
   async function createViewer(container, source, options = {}) {
     const el = resolveContainer2(container);
     const { wasmBasePath: wasmBasePath2, ...conversion } = options;
@@ -17906,18 +18397,7 @@ ${parsed.documentElement.outerHTML}`;
         renderFootnotesAndEndnotes: true,
         ...opts
       });
-      const parsed = new DOMParser().parseFromString(lastHtml, "text/html");
-      const fragment = document.createDocumentFragment();
-      parsed.querySelectorAll("style").forEach((sourceStyle) => {
-        const style = document.createElement("style");
-        style.textContent = sourceStyle.textContent;
-        scopeStyleElement(style, mount2.selector);
-        fragment.appendChild(style);
-      });
-      const body = document.createElement("template");
-      body.innerHTML = parsed.body.innerHTML;
-      fragment.appendChild(body.content);
-      mount2.root.replaceChildren(fragment);
+      mount2.root.replaceChildren(scopedDocumentFragment(mount2, lastHtml));
     };
     await render(source, conversion);
     return {
@@ -17931,6 +18411,111 @@ ${parsed.documentElement.outerHTML}`;
       }
     };
   }
+  async function createHistoryViewer(container, history, documentId, options = {}) {
+    const el = resolveContainer2(container);
+    const { wasmBasePath: wasmBasePath2, maxEntriesToScan = 1e4, ...conversion } = options;
+    if (!Number.isSafeInteger(maxEntriesToScan) || maxEntriesToScan <= 0 || maxEntriesToScan > 2147483647)
+      throw new RangeError("Invalid history scan budget.");
+    await ensureWasm(wasmBasePath2);
+    const mount2 = createScopedMount(el);
+    let accepted = null;
+    let acceptedBytes = null;
+    let displayedBytes = null;
+    let shownSequence = "0";
+    let following = true;
+    let closed = false;
+    let html = "";
+    let queue = Promise.resolve();
+    const clone = (value) => JSON.parse(JSON.stringify(value));
+    const assertOpen = () => {
+      if (closed) throw new DocxHistoryError("Closed", "History viewer is destroyed.");
+    };
+    const enqueue = (action) => {
+      const result = queue.then(() => {
+        assertOpen();
+        return action();
+      });
+      queue = result.then(() => void 0, () => void 0);
+      return result;
+    };
+    const sameHead = (a, b) => a.revision === b.revision && a.state.length === b.state.length && a.state.digest.algorithm === b.state.digest.algorithm && a.state.digest.value === b.state.digest.value;
+    const paint = async (bytes, sequence) => {
+      const nextHtml = await convertDocxToHtml(bytes, { renderFootnotesAndEndnotes: true, ...conversion });
+      assertOpen();
+      const fragment = scopedDocumentFragment(mount2, nextHtml);
+      mount2.root.replaceChildren(fragment);
+      html = nextHtml;
+      displayedBytes = bytes;
+      shownSequence = sequence;
+    };
+    const refresh = async (resume = false) => {
+      const update = await history.readChangesSince(documentId, accepted?.view.head ?? null, maxEntriesToScan);
+      assertOpen();
+      const duplicate = accepted !== null && sameHead(accepted.view.head, update.view.head);
+      const bytes = duplicate ? acceptedBytes : await history.exportVersion(documentId, update.view.version.id);
+      assertOpen();
+      const wantLive = following || resume;
+      const changedContent = accepted === null || accepted.view.state.snapshot.contentDigest.value !== update.view.state.snapshot.contentDigest.value || accepted.view.state.epoch !== update.view.state.epoch;
+      if (wantLive && (changedContent || !following)) await paint(bytes, update.view.state.sequence);
+      else if (wantLive) {
+        displayedBytes = bytes;
+        shownSequence = update.view.state.sequence;
+      }
+      assertOpen();
+      accepted = update;
+      acceptedBytes = bytes;
+      if (wantLive) following = true;
+      return clone(update);
+    };
+    const showSequence = async (sequence) => {
+      const bytes = await history.materialize(documentId, sequence, maxEntriesToScan);
+      assertOpen();
+      await paint(bytes, sequence);
+      following = false;
+    };
+    const viewer = {
+      element: el,
+      get html() {
+        return html;
+      },
+      get head() {
+        assertOpen();
+        return clone(accepted.view.head);
+      },
+      get sequence() {
+        return shownSequence;
+      },
+      get following() {
+        return following;
+      },
+      refresh: () => enqueue(() => refresh()),
+      showSequence: (sequence) => enqueue(() => showSequence(sequence)),
+      showTime: (cutoff) => enqueue(async () => {
+        const sequence = await history.resolveSequenceAtTime(documentId, cutoff, maxEntriesToScan);
+        assertOpen();
+        await showSequence(sequence);
+      }),
+      resume: () => enqueue(() => refresh(true)),
+      exportDisplayed: () => {
+        assertOpen();
+        return displayedBytes.slice();
+      },
+      destroy: () => {
+        if (closed) return;
+        closed = true;
+        acceptedBytes = null;
+        displayedBytes = null;
+        mount2.root.remove();
+      }
+    };
+    try {
+      await viewer.refresh();
+      return viewer;
+    } catch (error) {
+      viewer.destroy();
+      throw error;
+    }
+  }
   async function createEditor(container, source, options = {}) {
     const el = resolveContainer2(container);
     const { wasmBasePath: wasmBasePath2, ...editorOptions } = options;