From 8f328d5f7e8e6a6ff0d307c211d7aa200ee6dbc6 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 3 Mar 2026 22:20:45 -0300
Subject: [PATCH] Update Swift LiveObjects documentation for apply-on-ACK

This mirrors the changes made for JavaScript in a4f5929, adapted for
Swift now that the Swift SDK also applies operations on
acknowledgement rather than on echo.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../docs/liveobjects/concepts/synchronization.mdx   | 13 +++++++++++--
 src/pages/docs/liveobjects/counter.mdx              |  7 +++++++
 src/pages/docs/liveobjects/map.mdx                  |  7 +++++++
 src/pages/docs/liveobjects/quickstart/swift.mdx     |  2 +-
 4 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/pages/docs/liveobjects/concepts/synchronization.mdx b/src/pages/docs/liveobjects/concepts/synchronization.mdx
index c1c28a28b0..31f7505673 100644
--- a/src/pages/docs/liveobjects/concepts/synchronization.mdx
+++ b/src/pages/docs/liveobjects/concepts/synchronization.mdx
@@ -57,10 +57,19 @@ When a client publishes an operation, the operation is applied to its local obje
 </Aside>
 
 <Aside data-type='important'>
-If you're also developing with the Swift or Java SDKs, note that they currently apply operations when [echoed](/docs/pub-sub/advanced#echo) back from the server rather than on acknowledgment. Apply-on-acknowledgment is coming soon to those SDKs.
+If you're also developing with the Java SDK, note that it currently applies operations when [echoed](/docs/pub-sub/advanced#echo) back from the server rather than on acknowledgment. Apply-on-acknowledgment is coming soon to the Java SDK.
 </Aside>
 </If>
-<If lang="swift,java">
+<If lang="swift">
+<Aside data-type='note'>
+When a client publishes an operation, the operation is applied to its local objects as soon as the operation is acknowledged by the Ably system. This means that when a mutation method returns, the operation has already been applied and you can immediately read the updated state.
+</Aside>
+
+<Aside data-type='important'>
+If you're also developing with the Java SDK, note that it currently applies operations when [echoed](/docs/pub-sub/advanced#echo) back from the server rather than on acknowledgment. Apply-on-acknowledgment is coming soon to the Java SDK.
+</Aside>
+</If>
+<If lang="java">
 <Aside data-type='note'>
 Currently, when a client publishes an operation it is not immediately applied to its local objects. Instead, the client only applies the operation when the operation is [echoed](/docs/pub-sub/advanced#echo) back to the client.
 </Aside>
diff --git a/src/pages/docs/liveobjects/counter.mdx b/src/pages/docs/liveobjects/counter.mdx
index 76d6b6cdf9..fd5385e56b 100644
--- a/src/pages/docs/liveobjects/counter.mdx
+++ b/src/pages/docs/liveobjects/counter.mdx
@@ -302,9 +302,16 @@ System.out.println("Counter value: " + counter.value());
 
 You can subscribe to data updates on a counter to receive realtime changes made by you or other clients.
 
+<If lang="swift">
+<Aside data-type='note'>
+`LiveCounter` mutation methods send operations to the Ably system and apply changes locally as soon as the operations are acknowledged. When a mutation method returns, the operation has been applied and you can immediately read the updated state. You will also be notified via subscription when the counter is updated.
+</Aside>
+</If>
+<If lang="java">
 <Aside data-type='note'>
 `LiveCounter` mutation methods do not directly modify the local counter state. Instead, they send the intended operation to the Ably system, and the change is applied only when the corresponding realtime operation is echoed back to the client. This means that the state retrieved immediately after a mutation may not reflect the latest updates yet. You will be notified via subscription when the counter is updated.
 </Aside>
+</If>
 
 Subscribe to data updates on a counter using the `LiveCounter.subscribe()` method:
 
diff --git a/src/pages/docs/liveobjects/map.mdx b/src/pages/docs/liveobjects/map.mdx
index be3689d525..2aa2de4d5c 100644
--- a/src/pages/docs/liveobjects/map.mdx
+++ b/src/pages/docs/liveobjects/map.mdx
@@ -391,9 +391,16 @@ System.out.println("Value for my-key: " + map.get("my-key").getValue());
 
 You can subscribe to data updates on a map to receive realtime changes made by you or other clients.
 
+<If lang="swift">
+<Aside data-type='note'>
+`LiveMap` mutation methods send operations to the Ably system and apply changes locally as soon as the operations are acknowledged. When a mutation method returns, the operation has been applied and you can immediately read the updated state. You will also be notified via subscription when the map is updated.
+</Aside>
+</If>
+<If lang="java">
 <Aside data-type='note'>
 `LiveMap` mutation methods do not directly modify the local map state. Instead, they send the intended operation to the Ably system, and the change is applied only when the corresponding realtime operation is echoed back to the client. This means that the state retrieved immediately after a mutation may not reflect the latest updates yet. You will be notified via subscription when the map is updated.
 </Aside>
+</If>
 
 Subscribe to data updates on a map using the `LiveMap.subscribe()` method:
 
diff --git a/src/pages/docs/liveobjects/quickstart/swift.mdx b/src/pages/docs/liveobjects/quickstart/swift.mdx
index bfc09fbf15..d4b19d45a5 100644
--- a/src/pages/docs/liveobjects/quickstart/swift.mdx
+++ b/src/pages/docs/liveobjects/quickstart/swift.mdx
@@ -188,7 +188,7 @@ try await reactionsMap.remove(key: "like")
 </Code>
 
 <Aside data-type='note'>
-Mutation methods (such as `LiveMap.set(key:value:)`, `LiveCounter.increment(amount:)`, etc.) do not directly modify the local object state. Instead, they send the intended operation to the Ably system, and the change is applied only when the corresponding realtime operation is echoed back to the client. This means that the state retrieved immediately after a mutation may not reflect the latest updates yet. You will be notified via subscription when the object is updated.
+Mutation methods (such as `LiveMap.set(key:value:)`, `LiveCounter.increment(amount:)`, etc.) send operations to the Ably system and apply changes locally as soon as the operations are acknowledged. When a mutation method returns, the operation has been applied and you can immediately read the updated state. You will also be notified via subscription when the object is updated.
 </Aside>
 
 ## Next steps <a id="step-8"/>