Adds USPs to chat docs

src/components/Layout/mdx/Admonition.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import cn from '@ably/ui/core/utils/cn';
 import Aside from '../../blocks/dividers/Aside';
 
-const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'public-preview'];
+const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'see-evidence'];
 
 type AdmonitionVariant = 'neutral' | 'note' | 'further-reading' | 'important' | 'warning';
 
@@ -51,7 +51,7 @@ const Admonition: React.FC<AdmonitionProps> = ({ 'data-type': dataType = 'note',
     return <Aside attribs={{ 'data-type': dataType }}>{children}</Aside>;
   }
 
-  const { borderColor, backgroundColor, title } = admonitionConfig[dataType];
+  const { borderColor, backgroundColor, title } = admonitionConfig[dataType] || admonitionConfig.note;
 
   return (
     <aside

src/components/blocks/dividers/Aside.tsx

@@ -1,4 +1,5 @@
 import Icon from '@ably/ui/core/Icon';
+import * as styles from './dividers.module.css';
 import {
   inlineGridParagraph,
   inlineContentContainer,
@@ -44,6 +45,14 @@ const Aside = ({ children, attribs }: AsideProps) => {
             <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">Further Reading</span>
           </strong>
         </>
+      ) : attribs && attribs[`data-type`] === `see-evidence` ? (
+        <>
+          <span className={`${leftSideElement} ${styles['see-evidence-element']}`}>&nbsp;</span>
+          <strong className={tipTitleElement}>
+            <span className="mr-3 text-3xl">🔎</span>
+            <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">See evidence</span>
+          </strong>
+        </>
       ) : attribs && isVersioningInfo ? (
         <>
           <span

src/components/blocks/dividers/dividers.module.css

@@ -21,6 +21,9 @@ span.left-side-element {
 .further-reading-element {
   background-color: #08fe13;
 }
+.see-evidence-element {
+  background-color: #14b8a6;
+}
 
 strong.tip-title-element {
   margin-left: var(--spacing-16);

src/pages/docs/chat/connect.mdx

@@ -20,6 +20,10 @@ A connection can have any of the following statuses:
 | closed | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically. No connection state is preserved by the service or the library. |
 | failed | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. |
 
+<Aside data-type='see-evidence'>
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [See evidence here 🕵️](/docs/platform/architecture/edge-network)
+</Aside>
+
 <If lang="javascript,swift,kotlin">
 Use the <If lang="javascript">[`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)</If><If lang="swift">[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)</If><If lang="kotlin">[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html)</If> property to check which status a connection is currently in:
 </If>

src/pages/docs/chat/index.mdx

@@ -17,6 +17,8 @@ The Chat SDK contains a set of purpose-built APIs that abstract away the complex
 * [Getting started: Chat in Kotlin (JVM)](/docs/chat/getting-started/jvm)
 * [Getting started: Chat in Swift](/docs/chat/getting-started/swift)
 
+<Aside data-type='see-evidence'>Ably monitors resource headroom and triggers automatic scaling when load approaches capacity, absorbing traffic spikes without degradation. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)</Aside>
+
 ## Chat features <a id="features"/>
 
 Ably Chat provides the following key features:

src/pages/docs/chat/integrations.mdx

@@ -36,6 +36,8 @@ Be aware that message actions are numeric values over the realtime channels, Pub
 
 If possible, use an Ably Pub/Sub SDK with `fromEncoded()` or `fromEncodedArray()` to decode the message. This will ensure that the message is decoded correctly and all the fields are present, as well as convert things like numerical action values to their string representations. Details on how to do this are available in the [platform integrations documentation](/docs/platform/integrations/webhooks). Then you can apply the mapping from the table above to get a Chat message form the Pub/Sub message.
 
+<Aside data-type='see-evidence'>Ably delivers over 500 billion messages monthly, demonstrating large throughput capability. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)</Aside>
+
 ### Is this message new, updated, or deleted?
 
 To determine if a message is new, updated, or deleted, you can use the `action` field.

src/pages/docs/chat/react-ui-kit/index.mdx

@@ -16,9 +16,13 @@ Some of the benefits include:
 * **Tried and tested** – rely on components that are already fully covered by a suite of tests.
 * **Chat-centric design** – layouts, interactions, and accessibility are built with chat workflows in mind.
 
-
 ![Ably Chat React App](../../../../images/examples/chat-ui-app.png)
 
+<Aside data-type='see-evidence'>
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery)
+</Aside>
+
+
 ## Components and Providers
 
 The React UI Kit is organized into two main categories:

src/pages/docs/chat/rooms/history.mdx

@@ -4,9 +4,6 @@ meta_description: "Retrieve previously sent messages from history."
 ---
 
 The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support).
-
-## Retrieve previously sent messages <a id="history"/>
-
 <If lang="javascript,swift,kotlin">
 Use the <If lang="javascript">[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)</If><If lang="swift">[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))</If><If lang="kotlin">[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html)</If> method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages.
 </If>
@@ -82,6 +79,10 @@ The following optional parameters can be passed when retrieving previously sent
 | orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. |
 | limit | Maximum number of messages to be retrieved per page, up to 1,000. |
 
+<Aside data-type='see-evidence'>
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery)
+</Aside>
+
 ## Retrieve messages sent prior to subscribing <a id="subscribe"/>
 
 Users can also retrieve historical messages that were sent to a room before the point that they registered a listener by [subscribing](/docs/chat/rooms/messages#subscribe). The order of messages returned is from most recent, to oldest. This is useful for providing conversational context when a user first joins a room, or when they subsequently rejoin it later on. It also ensures that the message history they see is continuous, without any overlap of messages being returned between their subscription and their history call.

src/pages/docs/chat/rooms/index.mdx

@@ -162,6 +162,10 @@ By default the `ChatRoomProvider` will automatically call [`release()`](https://
 
 To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions.
 
+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions. All messages are received in correct order with zero message loss. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery)
+</Aside>
+
 <If lang="javascript,swift,kotlin">
 Once an instance of a room has been created using `rooms.get()`, clients attach to it to start receiving messages and events from the room.
 

src/pages/docs/chat/rooms/media.mdx

@@ -8,6 +8,10 @@ Share media such as images, videos and files with users in a chat room.
 
 Upload the media to your own storage service, such as AWS S3, and then use the `metadata` field to reference the location of the media when a user [sends a message](/docs/chat/rooms/messages#send). On the receiving end, display the media to [subscribers](/docs/chat/rooms/messages#subscribe) that received the message.
 
+<Aside data-type='see-evidence'>
+Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [See evidence here 🕵️](/docs/platform/architecture/fault-tolerance#core-layer)
+</Aside>
+
 ## Access control
 
 Ensure that you add a layer of authentication server-side if the media shouldn't be publicly available.

src/pages/docs/chat/rooms/message-reactions.mdx

@@ -5,6 +5,10 @@ meta_description: "React to chat messages"
 
 Send, remove and display message reactions in a chat room. Users can react to messages, typically with emojis but can be any string, and others can see the reactions to the message. Message reactions can be sent and removed and a summary of the reactions is persisted with the message.
 
+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+</Aside>
+
 The reaction `name` represents the reaction itself, for example an emoji. Reactions are aggregated by `name` and the aggregation method including how many reactions a user can place for a message is controlled by the reaction `type`. The `count` is an optional parameter that can be set when sending a reaction of type `Multiple`.
 
 The reaction `name` can be any string. Summaries are aggregated based on unique `name` values. UTF-8 emojis are a common use case, but any string can be used as long as they are consistent across all front-ends of your app. Examples of common reaction names are `👍`, `❤️`, `:like:`, `like`, `+1`, and so on. How those are presented to the user is entirely up to the app.

src/pages/docs/chat/rooms/messages.mdx

@@ -95,7 +95,13 @@ The following are the properties of a message:
 | | `description`:  Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | String or undefined |
 | | `metadata`:  Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | Object or undefined |
 
-See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application.
+Each message contains a `serial` property that provides deterministic global ordering. See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application.
+
+<Aside data-type='see-evidence'>
+Messages are delivered to all subscribers in the same order, with each message assigned a unique serial number that enables consistent ordering. [See evidence here 🕵️](/docs/platform/architecture/message-ordering#message-ordering-guarantees).
+</Aside>
+
+
 
 ### Unsubscribe from messages <a id="unsubscribe"/>
 

src/pages/docs/chat/rooms/presence.mdx

@@ -122,6 +122,10 @@ unsubscribe()
 
 Users can enter and leave the presence set of a room to indicate when they are online or offline. They can also set user data when entering and leaving the set, such as their current status. Presence is also linked to a user's [connection status](/docs/chat/connect). For example, if a user goes offline then a leave event will be emitted for them.
 
+<Aside data-type='see-evidence'>
+Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence here 🕵️](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+</Aside>
+
 <Aside data-type='important'>
 Users must be identified to enter into the presence set. This means that they must set a `clientId` when [instantiating their client](/docs/chat/setup#instantiate).
 </Aside>

src/pages/docs/chat/rooms/reactions.mdx

@@ -7,6 +7,10 @@ Users can send reactions to the entire chat room to show their sentiment as to w
 
 Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.
 
+<Aside data-type='see-evidence'>
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>
+
 ## Subscribe to room reactions <a id="subscribe"/>
 
 <If lang="javascript,swift,kotlin">

src/pages/docs/chat/rooms/replies.mdx

@@ -8,6 +8,10 @@ Reply to messages that have been previously sent in the chat room.
 
 Message replies are implemented using the `metadata` field when you [send a message](/docs/chat/rooms/messages#send).
 
+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+</Aside>
+
 ## Send a reply <a id="send-reply"/>
 
 Use the [`metadata`](/docs/chat/rooms/messages#structure) field of a message to store the reply when you [send a message](/docs/chat/rooms/messages#send).

src/pages/docs/chat/rooms/typing.mdx

@@ -89,6 +89,10 @@ The following are the properties of a typing event:
 
 You can use the size of the `currentlyTyping` set to decide whether to display individual user names, or that multiple people are typing in your user interface.
 
+<Aside data-type='see-evidence'>
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>
+
 ### Unsubscribe from typing events <a id="unsubscribe"/>
 
 <If lang="javascript,kotlin">

src/pages/docs/chat/setup.mdx

@@ -41,6 +41,10 @@ When setting the capabilities for Chat, you can apply them to specific chat room
 
 For more guidance, see the [capabilities documentation](/docs/auth/capabilities).
 
+<Aside data-type='see-evidence'>
+Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence here 🕵️](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+</Aside>
+
 ## Install <a id="install"/>
 
 The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably.

src/pages/docs/guides/chat/build-livestream.mdx

@@ -14,6 +14,8 @@ This guide explains the architectural decisions, technical challenges, and uniqu
 
 Ably is trusted by organizations delivering chat to millions of users in realtime. Its platform is engineered around the four pillars of dependability:
 
+<Aside data-type='see-evidence'>Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)</Aside>
+
 * **[Performance](/docs/platform/architecture/performance):** Ultra-low latency messaging, even at global scale.
 * **[Integrity](/docs/platform/architecture/message-ordering):** Guaranteed message ordering and delivery, with no duplicates or data loss.
 * **[Reliability](/docs/platform/architecture/fault-tolerance):** 99.999% uptime SLA, with automatic failover and seamless re-connection.
@@ -58,6 +60,8 @@ Livestream chat is defined by high message rates and unpredictable spikes. Ably
 * **Server-side batching:** Reduce costs and network overhead by grouping messages before delivery. As shown in the [example](#server-side-batching), [batching messages](#server-side-batching) reduces the number of outbound messages such that it increases linearly with the number of users in the chatroom.
 * **Rate limiting:** Control the flow of messages per user to maintain readability and prevent spam. Choose between per-connection rate limits or global throttling.
 
+<Aside data-type='see-evidence'>With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)</Aside>
+
 Decisions that you need to make around throughput and rates:
 
 * What is the maximum message rate you want users to experience on average?