Supported Word for Mac API for lifetime-safe conditional text replacement

No supported Word for Mac API documented for build 16.112.4 provides either the requested compare-and-replace transaction or an owner-scoped fence covering UI, VBA, add-ins, coauthors, lifecycle changes, and stale requests.

Why the existing APIs do not satisfy either contract

Word.run and context.sync() are not a conditional transaction. Office.js queues proxy-object commands and dispatches them asynchronously at context.sync(). The documented contract says that commands run as a batch, but it does not provide:

• an opaque document-lifetime/all-edit version token;
• an atomic “compare token, then replace or make no change” primitive;
• transaction rollback or a zero-mutation guarantee if one command fails;
• fencing across task-pane reload, close/reopen, Save As, host restart, or lost responses;
• an authoritative operation-status query for reconciling unknown completion.

Consequently, placing a read and insertText in one batch does not establish compare-and-swap semantics, and separate sync() calls necessarily leave an admission interval between observation and mutation.^1^

Tracked ranges are references, not state tokens or locks. Tracking keeps a proxy object usable and adjusts it around surrounding document changes; it does not attest that no intervening edit occurred or prevent another writer from editing.^2^

Events cannot implement the required fence or token. Word events may be triggered by UI edits, JavaScript add-ins, VBA, and remote coauthors, but handlers are destroyed when the add-in is refreshed, reloaded, or closed. Events are notifications after host activity, not synchronous admission controls, and are not persisted in the file.^3^

The new coauthoring-lock API is not a solution

CoauthoringLockCollection.add(options) can add a lock for a specified range, with lock types including Reservation and Ephemeral. A lock exposes its range, owner, and type, and can be removed with unlock(); the collection can remove ephemeral locks.^4^ ^5^ ^6^

However, its documented scope is decisive:

• It belongs to production requirement set WordApiDesktop 1.4 on Word for Mac.
• It works only with legacy coauthoring locks.
• It does not apply to modern OneDrive or SharePoint coauthoring.
• Calling it on a modern document fails with GeneralException.^7^

Even in a legacy-lock document, the public contract does not specify the required lease duration, renewal, stale-owner fencing, ABA prevention, atomic authority revocation, crash semantics, copy/reopen behavior, or participation by every relevant writer. It also permits unlock() to remove a lock belonging to another user, which is not the requested owner-only release model.^5^

Therefore, the API should not be elevated into the proposed lifetime-safe critical section without a stronger attributable support contract.

Version and runtime admission

Word for Mac 16.112.4 is newer than the documented minimum for WordApiDesktop 1.4, which is version 16.100.4 (25090553). That establishes potential requirement-set availability, not the stronger concurrency semantics and not loaded-runtime support.^8^

The supported runtime admission check is:

const available = Office.context.requirements.isSetSupported(
  "WordApiDesktop",
  "1.4"
);

if (!available) {
  throw new Error("WordApiDesktop 1.4 is unavailable in this runtime.");
}

Desktop-only sets cannot be activation requirements in an add-in-only XML manifest; a unified manifest can declare them under requirements.capabilities.^9^

This check answers only whether the requirement set is exposed. It cannot determine whether a document uses legacy rather than modern coauthoring, nor convert the lock into the requested contract.

Supported architectural conclusion

For a live, independently editable Word document, client-side Office.js checks can provide optimistic detection only. They cannot provide the stated safety guarantee. Restricting content to plain text, disabling tracking, or validating formatting reduces replacement complexity but does not close the concurrency and lifetime gaps.

A design requiring this guarantee must move mutation admission to a system that owns all writes and offers a documented transaction or compare-and-swap primitive. If users, VBA, other add-ins, or Word coauthoring may bypass that authority, the guarantee no longer holds.

For a normative Word-team statement covering unpublished semantics, open an SLA-backed Microsoft 365 support request for a business-critical dependency. API bugs belong in the Office JavaScript API GitHub repository; feature requests belong in the Microsoft 365 Developer Platform channel.^10^ Request written confirmation specifically addressing atomic rollback, legacy-lock writer coverage, lease/fencing behavior, lifecycle identity, and unknown-completion reconciliation; absence of such a contract should be treated as unsupported rather than inferred through testing.

References

1. Application-specific API model
2. Word.Coauthoring class-Remarks
3. Work with events using the Word JavaScript API
4. Word.CoauthoringLockCollection class
5. Word.CoauthoringLock class-Remarks
6. Word.CoauthoringLockType enum-Remarks
7. Word.CoauthoringLockCollection class-Remarks
8. Word JavaScript API requirement sets
9. Word JavaScript API desktop-only requirement set 1.4
10. Office Add-ins additional resources