docs(uniapp): align English message guides with Wasm

Author: Bloomingg

content/docs/chat/sdk/uniapp/file-uploads/upload-file.mdx

@@ -11,21 +11,67 @@ platform: 'uniapp'
 sourcePath: '/sdk/uniapp/file-uploads/upload-file'
 ---
 
+`uploadFile()` is an independent upload operation for avatars, group images, profile attachments, and other business files. It does not create a chat message. It uploads a native-readable local file and returns its URL/URI, UUID, size, and media metadata.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `filepath` | `string` | Yes | Full local path readable by the native layer. |
+| `name` | `string` | Yes | Filename. |
+| `contentType` | `string` | Yes | MIME type. |
+| `uuid` | `string` | Yes | Stable task ID created by your application. |
+| `cancelID` | `string` or `null` | No | Stable ID used to cancel this upload. |
+| `cause` | `string` or `null` | No | Business purpose or reason for the upload. |
+
+Register the progress event before calling `uploadFile()` so a small file cannot complete before the listener exists.
+
 ```uts
-import { uploadFile } from '@/uni_modules/unix-openim-sdk'
+import { off, onUploadFileProgress, uploadFile } from '@/uni_modules/unix-openim-sdk'
+
+const progressSubscription = onUploadFileProgress((event) => {
+  if (event == null) return
+  updateUploadProgress(event.progress)
+})
 
 const result = await uploadFile({
-  filepath: '/data/user/0/app/cache/report.pdf', name: 'report.pdf',
-  contentType: 'application/pdf', uuid: createStableUploadUUID(), cancelID: 'upload-report-1',
+  filepath: '/data/user/0/app/cache/report.pdf',
+  name: 'report.pdf',
+  contentType: 'application/pdf',
+  uuid: createStableUploadUUID(),
+  cancelID: 'upload-report-1',
 })
+
+function removeUploadListener() {
+  off(progressSubscription)
+}
 ```
 
-Use a readable absolute native path. Resolve `unifile://` first and never pass a network URL as `filepath`. Observe progress through `onUploadFileProgress`.
+Resolve `unifile://` to a platform sandbox path and never pass a network URL as `filepath`. Android and iOS temporary directories, grants, and lifetimes differ; do not move or delete the source while native code may still read it.
+
+The Promise resolves to `OpenIMUploadFileResult | null`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `url` | `string` or `null` | Uploaded remote URL. |
+| `uri` | `string` or `null` | Resource URI returned by the server. |
+| `uuid` | `string` or `null` | Upload task identifier. |
+| `size` | `number` or `null` | File size. |
+| `typ` | `number` or `null` | Resource type returned by the server. |
+| `mediaID` | `string` or `null` | Media resource ID. |
+
+Use `result?.url` in a profile update or when creating the appropriate message. Upload success does not update profile data or create/send a chat message; those are separate operations.
+
+## Listen for upload progress
+
+`onUploadFileProgress` returns an `OpenIMSDKEventSubscription`, and its event contains only `progress`. Unlike Wasm completion events, the current uni-app / uni-app x contract does not include a task ID. Do not correlate several concurrent uploads by array position; limit concurrency or track final state through each Promise. Call `removeUploadListener()` when the account or upload store is disposed.
+
+Commercial applications can cancel the matching task with `cancelUpload()` <span className="enterprise-field-badge">Commercial</span>:
 
 ```uts
 import { cancelUpload } from '@/uni_modules/unix-openim-sdk'
 
 await cancelUpload({ cancelID: 'upload-report-1' })
 ```
 
-`cancelUpload()` is <span className="enterprise-field-badge">Commercial</span>. The original upload Promise defines the final state. Do not delete a temporary file while native code may still read it.
+Cancellation is asynchronous; the original upload Promise and error code define the final state. Do not delete a temporary file until the upload completes or cancellation is confirmed.

content/docs/chat/sdk/uniapp/getting-started/install-initialize-and-inspect-sdk.mdx

@@ -41,8 +41,8 @@ Use `OpenIMPlatformIOS` with `systemType: 'ios'`, or `OpenIMPlatformHarmony` wit
 | `platformID` | `OpenIMPlatform` | One of the exported platform constants. |
 | `apiAddr` | `string` | OpenIMServer HTTP API address. |
 | `wsAddr` | `string` | OpenIMServer WebSocket address. |
-| `dataDir` | `string \| null` (optional) | Core data directory; normally use the platform default. |
-| `logFilePath` | `string \| null` (optional) | Log path following the platform artifact contract. |
+| `dataDir` | `string` or `null` (optional) | Core data directory; normally use the platform default. |
+| `logFilePath` | `string` or `null` (optional) | Log path following the platform artifact contract. |
 | `logLevel` | `OpenIMLogLevel` | For example `OpenIMLogLevelError` or `OpenIMLogLevelInfo`. |
 | `isLogStandardOutput` | `boolean` | Whether SDK logs are emitted to the system console. |
 | `systemType` | `string` | Required system description; never omit it. |

content/docs/chat/sdk/uniapp/getting-started/update-token-and-observe-sdk-session.mdx

@@ -22,7 +22,7 @@ const snapshot : OpenIMSDKSessionSnapshot = await getSDKSessionSnapshot()
 | Field | Type | Description |
 | --- | --- | --- |
 | `loginStatus` | `OpenIMLoginStatus` | Current login state. |
-| `userID` | `string \| null` | Current SDK user, or `null` when logged out. |
+| `userID` | `string` or `null` | Current SDK user, or `null` when logged out. |
 | `sdkSessionEpoch` | `number` | Session generation, incremented after successful lifecycle or account changes. |
 | `sdkVersion` | `string` | Version of the connected Core. |
 

content/docs/chat/sdk/uniapp/message/composing-messages/check-speech-to-text.mdx

@@ -17,4 +17,16 @@ import { getSpeechToTextCapabilities } from '@/uni_modules/unix-openim-sdk'
 const capabilities = await getSpeechToTextCapabilities()
 ```
 
-This <span className="enterprise-field-badge">Commercial</span> query should gate transcription UI. Capability can vary by deployment and account; do not infer it solely from plugin version.
+This is a <span className="enterprise-field-badge">Commercial</span> capability query. The Promise resolves to `OpenIMSpeechToTextCapabilitiesResult | null`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `format` | `string[]` or `null` | Supported audio formats. |
+| `sampleRateHz` | `number[]` or `null` | Supported sample rates in hertz. |
+| `maxRecordTimeMs` | `number` or `null` | Maximum recording duration in milliseconds. |
+| `maxFileSize` | `number` or `null` | Maximum file size in bytes. |
+| `provider` | `string` or `null` | Current speech-recognition provider. |
+| `requestType` | `string` or `null` | Request type required by the service. |
+| `crossDomain` | `boolean` or `null` | Whether cross-domain processing is allowed. |
+
+Query and cache capabilities for the current login session before displaying transcription UI. Validate format, sample rate, duration, and size before sending audio. Capabilities can vary by service, language, and account, so refresh them after login changes. Disable transcription on failure instead of guessing limits. This query does not emit message events.

content/docs/chat/sdk/uniapp/message/composing-messages/get-typing-status.mdx

@@ -14,7 +14,7 @@ sourcePath: '/sdk/uniapp/message/composing-messages/get-typing-status'
 ```uts
 import { getInputStates } from '@/uni_modules/unix-openim-sdk'
 
-const state = await getInputStates(conversationID)
+const result = await getInputStates({ conversationID, userID: peerUserID })
 ```
 
-This <span className="enterprise-field-badge">Commercial</span> snapshot can become stale quickly. Combine it with typing events and a local timeout; never use it for authorization or durable presence.
+`getInputStates()` is a <span className="enterprise-field-badge">Commercial</span> snapshot query. Typing state is a short-lived hint, not a durable business fact. Update the UI from events and apply a local expiry timeout so a disconnect cannot leave “typing” visible forever. Never use this snapshot for authorization or durable presence.

content/docs/chat/sdk/uniapp/message/composing-messages/save-local-transcript.mdx

@@ -14,7 +14,7 @@ sourcePath: '/sdk/uniapp/message/composing-messages/save-local-transcript'
 ```uts
 import { setMessageLocalContent } from '@/uni_modules/unix-openim-sdk'
 
-await setMessageLocalContent({ conversationID, clientMsgID, content: transcript })
+await setMessageLocalContent({ conversationID, message: updatedMessage })
 ```
 
-This <span className="enterprise-field-badge">Commercial</span> local-only value is device state and does not edit the server message. Version any structured content and avoid storing unnecessary sensitive transcript data.
+`setMessageLocalContent()` is <span className="enterprise-field-badge">Commercial</span> and stores a complete message object in the specified conversation's local database. Merge the transcript into a copy of the original message first; do not overwrite its `clientMsgID`, routing fields, or unrelated business elems. The change is device-local and must not be treated as a server or multi-device edit. Version structured transcript data and avoid retaining unnecessary sensitive content.

content/docs/chat/sdk/uniapp/message/composing-messages/transcribe-audio.mdx

@@ -14,7 +14,13 @@ sourcePath: '/sdk/uniapp/message/composing-messages/transcribe-audio'
 ```uts
 import { speechToText } from '@/uni_modules/unix-openim-sdk'
 
-const result = await speechToText(soundMessage)
+const result = await speechToText({
+  filename: 'voice.m4a',
+  data: audioBase64,
+})
+if (result?.text != null) setTranscript(result.text)
 ```
 
-This is <span className="enterprise-field-badge">Commercial</span>. Use a complete sound message, expose consent/privacy behavior, and store the returned transcript according to product policy rather than modifying the original media.
+This is <span className="enterprise-field-badge">Commercial</span>. Native files cannot cross the UTS boundary directly; encode the audio as the commercial service protocol requires. The Promise resolves to `OpenIMSpeechToTextResult | null`, whose optional `text` field contains the transcript.
+
+First query [speech-to-text capabilities](/sdk/uniapp/message/composing-messages/check-speech-to-text) and enforce the supported size, format, sample rate, and duration. Do not log complete audio or Base64 content. Transcription neither edits the original audio message nor emits message events. Ask the user to confirm transcripts before high-risk use; to persist one locally, see [Save a local transcript](/sdk/uniapp/message/composing-messages/save-local-transcript).

content/docs/chat/sdk/uniapp/message/composing-messages/update-typing-status.mdx

@@ -11,14 +11,18 @@ platform: 'uniapp'
 sourcePath: '/sdk/uniapp/message/composing-messages/update-typing-status'
 ---
 
-`changeInputStates()` updates typing/input state; commercial `typingStatusUpdate()` provides the legacy compatible route. Receive updates through `onConversationUserInputStatusChanged`.
+Pass `focus: true` when the user starts typing. Pass `false` after sending, when the input loses focus, when switching conversations, or when typing stops. Typing state belongs to `conversationID`; it neither saves a draft nor writes a message.
 
 ```uts
 import { changeInputStates, off, onConversationUserInputStatusChanged } from '@/uni_modules/unix-openim-sdk'
 
-const typingSubscription = onConversationUserInputStatusChanged((state) => renderTyping(state))
-await changeInputStates({ conversationID, focus: true })
+const typingSubscription = onConversationUserInputStatusChanged((status) => {
+  updateConversationInputStatus(status)
+})
+await changeInputStates({ conversationID, userID: peerUserID, focus: true })
 off(typingSubscription)
 ```
 
-Debounce high-frequency UI changes and expire stale indicators locally.
+Report `true` when the input gains focus and `false` on blur or page exit, and throttle high-frequency changes. Commercial compatibility method `typingStatusUpdate()` <span className="enterprise-field-badge">Commercial</span> uses `recvID` and `msgTip`; do not call both routes for one typing flow. Expire stale indicators locally.
+
+Deduplicate state changes instead of reporting every keyboard event. Promise completion only means the request was accepted; it does not mean a remote interface has already updated. This page is the sole owner of `onConversationUserInputStatusChanged`. Replace the current `platformIDs` snapshot by `conversationID:userID`, and call `off(typingSubscription)` when the component, login, or account scope ends.

content/docs/chat/sdk/uniapp/message/creating-messages/create-card-message.mdx

@@ -11,10 +11,26 @@ platform: 'uniapp'
 sourcePath: '/sdk/uniapp/message/creating-messages/create-card-message'
 ---
 
+## Parameters
+
+`createCardMessage()` accepts `OpenIMCardElem`. Its fields are nullable in the contract, but a useful card should provide a complete snapshot:
+
+| Parameter | Type | Recommendation | Description |
+| --- | --- | --- | --- |
+| `userID` | `string` or `null` | Required | User represented by the card. |
+| `nickname` | `string` or `null` | Required | Display name snapshot. |
+| `faceURL` | `string` or `null` | Required | Avatar URL snapshot. |
+| `ex` | `string` or `null` | Required | Extension data; use an empty string when unused. |
+
 ```uts
 import { createCardMessage } from '@/uni_modules/unix-openim-sdk'
 
-const message = await createCardMessage({ userID: 'user_b', nickname: 'Alice', faceURL: 'https://cdn.example.com/alice.png', ex: '' })
+const message = await createCardMessage({
+  userID: 'user_b',
+  nickname: 'Alex',
+  faceURL: 'https://example.com/avatar.png',
+  ex: '',
+})
 ```
 
-A card is a send-time snapshot. Resolve current profile data by `userID` when opened, and never treat card fields as authenticated identity.
+The Promise creates `OpenIMMessageItem | null` and does not send it. A card is a send-time snapshot and does not track profile changes. Resolve current data by `userID` when opened, and never treat card fields as authenticated identity.

content/docs/chat/sdk/uniapp/message/creating-messages/create-custom-message.mdx

@@ -11,12 +11,28 @@ platform: 'uniapp'
 sourcePath: '/sdk/uniapp/message/creating-messages/create-custom-message'
 ---
 
+Use `createCustomMessage()` for orders, tasks, invitations, polls, or other business messages whose schema is shared by sender and receiver.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `data` | `string` | Yes | Complete business payload, normally serialized JSON. |
+| `extension` | `string` | Yes | Complete business extension string. |
+| `descriptionText` | `string` | Yes | Type description or fallback text for unsupported clients. |
+
 ```uts
 import { createCustomMessage } from '@/uni_modules/unix-openim-sdk'
 
 const message = await createCustomMessage({
-  data: JSON.stringify({ orderID: 'order_123' }), extension: '', descriptionText: 'Order card',
+  data: JSON.stringify({ type: 'task', taskID: 'task_42' }),
+  extension: JSON.stringify({ schemaVersion: 1 }),
+  descriptionText: 'Task card',
 })
 ```
 
-All fields reach the recipient. Version and validate a shared schema and store no secrets. `createAdvancedTextMessage()` creates entity/styled text; reject entity ranges outside the original text.
+All three fields reach the recipient. Never store secrets; validate schema version, size, and fields before mapping to a business model, and never execute untrusted content. The uni-app / uni-app x contract does not include the Wasm commercial `searchText` parameter. The Promise creates `OpenIMMessageItem | null`; sending and custom business events are separate flows.
+
+## Advanced text messages
+
+`createAdvancedTextMessage()` creates entity/styled text from `OpenIMCreateAdvancedTextMessageParams`. Entity ranges must refer to indexes in the original text; reject out-of-range values before calling the SDK. Both APIs only create messages.