Kotlin: Document websocket transport mode

Author: simolus3

client-sdk-references/kotlin-multiplatform.mdx

@@ -339,9 +339,56 @@ Logger.e("Some error");
 
 See [Usage Examples](/client-sdk-references/kotlin-multiplatform/usage-examples) for further examples of the SDK.
 
+## Developer Notes
+
+### Client implementation
+
+The PowerSync service sends encoded instructions about data to sync to connected clients.
+These instructions are decoded by our SDKs, and on Kotlin there are two implementations available for this:
+
+1. **Kotlin (default)**
+   - This is the original implementation method, mostly implemented in Kotlin.
+   - Most upcoming features will not be ported to this implementation, and we intend to remove it eventually.
+2. **Rust (currently experimental)**
+   - This is a newer implementation, mostly implemented in Rust but still using Kotlin for networking.
+   - Apart from newer features, this implementation is also more performant.
+   - We [encourage interested users to try it out](https://releases.powersync.com/announcements/improved-sync-performance-in-our-client-sdks)
+     and report feedback, as we intend to make it the default after a stabilization period.
+
+To enable the Rust client, pass `SyncOptions(newClientImplementation = true)` as a second parameter when
+[connecting](https://powersync-ja.github.io/powersync-kotlin/core/com.powersync/-power-sync-database/connect.html).
+
+### Connection Methods
+
+This SDK supports two methods for streaming sync commands:
+
+1. **WebSocket (currently experimental)**
+   - The implementation leverages RSocket for handling reactive socket streams.
+   - Back-pressure is effectively managed through client-controlled command requests.
+   - Sync commands are transmitted efficiently as BSON (binary) documents.
+   - Enabling websocket support requires the new client implementation.
+2. **HTTP Streaming (default)**
+   - This is the original implementation method.
+   - This method sends data as text (JSON) instead of BSON.
+
+By default, the `PowerSyncDatabase.connect()` method uses HTTP streams.
+You can optionally specify the `connectionMethod` to override this:
+
+```Kotlin
+// HTTP streaming (default)
+powerSync.connect(connector)
+
+// WebSockets (experimental)
+powerSync.connect(connector, SyncOptions(
+    newClientImplementation = true,
+    method = ConnectionMethod.WebSocket(),
+))
+```
+
 ## ORM Support
 
-ORM support is not yet available, we are still investigating options. Please [let us know](/resources/contact-us) what your needs around ORMs are.
+ORM support is not yet available, we are still investigating options to integrate the SDK with Room and SQLDelight.
+Please [let us know](/resources/contact-us) what your needs around ORMs are.
 
 ## Troubleshooting