plogme 2.0.8 → 2.1.0

package/README.md

@@ -7,7 +7,7 @@
 
 [![npm version](https://img.shields.io/npm/v/plogme?style=flat-square)](https://www.npmjs.com/package/plogme)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-10b981?style=flat-square&logo=node.js)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/tests-30%20passing-10b981?style=flat-square)](https://github.com/crysnovax/baileys)
+[![Tests](https://img.shields.io/badge/tests-174%20passing-10b981?style=flat-square)](https://github.com/crysnovax/baileys)
 
 ## Contents
 
@@ -28,8 +28,9 @@
 15. [View-once utilities](#view-once-utilities)
 16. [Connection handling](#connection-handling)
 17. [Security and removed automatic behavior](#security-and-removed-automatic-behavior)
-18. [Development](#development)
-19. [License and support](#license-and-support)
+18. [Complete public API examples](#complete-public-api-examples)
+19. [Development](#development)
+20. [License and support](#license-and-support)
 
 ## Installation
 
@@ -196,6 +197,19 @@ await sock.sendMessage(jid, {
     }
   }
 })
+
+// Solid-color themes use ARGB values internally. Hex strings and numbers are accepted.
+await sock.sendMessage(jid, {
+  chatTheme: {
+    solidColor: {
+      colorLight: '#FFFFFFFF',
+      colorDark: '#FF101010',
+      doodleColorLight: '#FFCCE8FF',
+      doodleColorDark: 0xFF202020,
+      isDoodleEnabled: true
+    }
+  }
+})
 ```
 
 ### Editing and deleting
@@ -251,6 +265,57 @@ await sock.sendMessage(jid, {
   }
 })
 
+// EventInviteMessage supports call links, cover handles, locations, timestamps, and status.
+await sock.sendMessage(jid, {
+  eventInvite: {
+    eventId: 'release-2026',
+    title: 'Plogme release room',
+    text: 'Join the release discussion',
+    startTime: Math.floor(Date.now() / 1000) + 3600,
+    endTime: Math.floor(Date.now() / 1000) + 7200,
+    callLink: 'https://call.whatsapp.com/video/example',
+    coverImageHandle: 'cover-handle-from-whatsapp',
+    locationName: 'Lagos',
+    lastUpdatedTsUsec: Date.now() * 1000,
+    status: 'ACTIVE'
+  }
+})
+
+// Plogme already supports sending a live location through the existing
+// `location` builder by setting `isLive: true`.
+const liveLocationMessage = await sock.sendMessage(jid, {
+  location: {
+    degreesLatitude: 6.5244,
+    degreesLongitude: 3.3792,
+    name: 'Lagos',
+    isLive: true,
+    accuracyInMeters: 10,
+    speedInMps: 0
+  }
+})
+
+// These newer fields are different: they ask the recipient to share a
+// location, or update/cancel a request for an existing live location.
+await sock.sendMessage(jid, { requestLocation: true })
+await sock.sendMessage(jid, {
+  requestLocationUpdate: {
+    key: liveLocationMessage.key,
+    cancel: false,
+    senderTimestampMs: Date.now()
+  }
+})
+await sock.sendMessage(jid, {
+  requestLocationUpdate: { key: liveLocationMessage.key, cancel: true }
+})
+
+// The latest proto also exposes these lower-level fields for forward-compatible relays.
+await sock.relayMessage(jid, {
+  instantImageMessage: { caption: 'Instant image' }
+}, {})
+await sock.relayMessage(groupJid, {
+  botGroupParticipantMessage: {}
+}, {})
+
 await sock.sendMessage(jid, {
   poll: {
     name: 'Release preference',
@@ -263,6 +328,53 @@ await sock.sendMessage(jid, {
 })
 ```
 
+### Latest WAProto additions
+
+The WAProto generation is updated to WhatsApp Web revision
+`2.3000.1049983640`. The following new fields are available through the
+generated `proto` namespace and are preserved during encode/decode:
+
+| Surface | What it represents |
+| --- | --- |
+| `requestLocationMessage` | Ask a chat to share its current location. |
+| `requestLocationUpdateMessage` | Request a live-location update or cancel an existing request. |
+| `instantImageMessage` | Image content using the newer instant-image message slot. |
+| `botGroupParticipantMessage` | Bot participant content for group-addressed protocol messages. |
+| `favoriteStickers` | Favorite sticker metadata in history sync. |
+| `omittedConversations` | Conversations deliberately omitted from a history-sync batch. |
+| `CommunityNestingStateAction` | Community nesting state changes from app-state sync. |
+| ARGB wallpaper fields | Light, dark, and doodle wallpaper colors as fixed ARGB values. |
+| Event-invite fields | Call link, cover handle, location, update timestamp, and status. |
+
+Favorite stickers and omitted conversations arrive through the normal history
+event. `omittedConversationsProvided` tells consumers that the omission list
+was explicitly supplied by WhatsApp, so an incomplete batch is not mistaken
+for a complete history:
+
+```javascript
+sock.ev.on('messaging-history.set', ({ favoriteStickers, omittedConversations, omittedConversationsProvided }) => {
+  if (favoriteStickers?.length) {
+    console.log('favorite stickers:', favoriteStickers.length)
+  }
+  if (omittedConversationsProvided) {
+    console.log('history intentionally omitted:', omittedConversations)
+  }
+})
+```
+
+Community nesting changes arrive through `groups.update`. The update contains
+the raw proto enum and a convenient boolean:
+
+```javascript
+sock.ev.on('groups.update', updates => {
+  for (const update of updates) {
+    if (update.nestingState !== undefined) {
+      console.log('community nested:', update.nested, update.nestingState)
+    }
+  }
+})
+```
+
 ### Forward and edit
 
 ```js
@@ -338,10 +450,10 @@ await sock.sendAlbumMessage(jid, [
     image: {
       sourceUrl: 'https://example.com/two-preview.jpg',
       imageHighResUrl: 'https://example.com/two.jpg',
-      darkModePreviewUrl: 'https://example.com/two-dark-preview.jpg',
-      darkModeHighResUrl: 'https://example.com/two-dark.jpg',
       width: 1200,
-      height: 800
+      height: 800,
+      fullWidth: 2400,
+      fullHeight: 1600
     }
   },
   {
@@ -367,7 +479,7 @@ await sock.sendMessage(jid, {
 })
 ```
 
-`sendAlbumMessage()` accepts fetchable image and video URLs. Local `Buffer`/file inputs are not uploaded by this rich album API. The lower-level `prepareGridImageMessage()` helper remains available when a compact `GRID_IMAGE` layout is specifically required; `sendAlbumMessage()` itself uses a full-width `GenAIVStackLayoutViewModel` presentation for both images and videos. Image primitives explicitly request full-width presentation and carry preview/full URL fallbacks.
+`sendAlbumMessage()` accepts fetchable image and video URLs. Local `Buffer`/file inputs are not uploaded by this rich album API. The lower-level `prepareGridImageMessage()` helper remains available when a compact `GRID_IMAGE` layout is specifically required; `sendAlbumMessage()` itself uses a full-width `GenAIVStackLayoutViewModel` presentation for both images and videos. Vertical image album items intentionally send only `full_image`—without preview or dark-mode slots—so WhatsApp does not render a broken preview placeholder before opening the original. When available, `imageHighResUrl`, `highResUrl`, or `fullUrl` is used as the full asset; provide `fullWidth` and `fullHeight` to preserve the source dimensions. Preview and dark-mode URL fields are not used by this vertical album path.
 
 ### Video grids
 
@@ -534,6 +646,68 @@ await sock.sendMessage(jid, {
 })
 ```
 
+### Native carousel details
+
+The native carousel composer accepts both `sendMessage` and the convenient
+`sendCarousel` socket method. A top-level `text` is optional: cards-only
+messages are valid. The default card type is horizontal scrolling
+(`HSCROLL_CARDS`); use `carouselCardType: 2` or `'album'` only when the
+receiving client supports the album-image card layout.
+
+```js
+await sock.sendCarousel(jid, [
+  {
+    title: 'Documentation',
+    subtitle: 'Read the guide',
+    body: { text: 'Open the latest API documentation.' },
+    image: { url: 'https://cdn.example.com/docs.jpg' },
+    buttons: [
+      { text: 'Open docs', url: 'https://example.com/docs', useWebview: true }
+    ],
+    footer: 'Plogme'
+  },
+  {
+    title: 'Release video',
+    body: 'See what changed in this release.',
+    video: { url: 'https://cdn.example.com/release.mp4' },
+    nativeFlow: [{ text: 'Watch', id: 'watch-release' }]
+  }
+], {
+  carouselCardType: 'horizontal',
+  text: 'Choose an item',
+  footer: 'Swipe to continue'
+})
+```
+
+The equivalent lower-level form is:
+
+```js
+await sock.sendMessage(jid, {
+  cards: [
+    {
+      title: 'First card',
+      body: { text: 'Cards may be sent without a top-level message.' },
+      image: { url: 'https://cdn.example.com/first.jpg' },
+      nativeFlow: [{ text: 'Select', id: 'first-card' }]
+    },
+    {
+      title: 'Second card',
+      caption: 'Use `caption` as a shorthand for body text.',
+      image: { url: 'https://cdn.example.com/second.jpg' }
+    }
+  ],
+  carouselCardType: 1
+})
+```
+
+Carousel media must use the normal fetchable media inputs supported by
+`prepareWAMessageMedia` (for example public URLs or uploaded media objects).
+Each card can contain an image or video header, `title`, `subtitle`, `body`,
+`caption`, `footer`, `thumbnail`, and native-flow buttons. A card that contains
+both body text and media retains its media header; it is not converted into a
+blank text-only card. Button IDs are event values and must be validated by the
+receiving application.
+
 ### Hydrated templates
 
 ```js
@@ -1468,6 +1642,322 @@ Plogme does not automatically follow WhatsApp channels, fingerprint the host mac
 
 The project license still applies. Removing runtime enforcement does not change the license terms.
 
+## Complete public API examples
+
+The examples below provide a call shape for every public method in `lib/index.d.ts`. Replace the placeholder values with data from your application and review the method's TypeScript signature before using account, privacy, interop, or security operations. Methods that change account state, permissions, group membership, or credentials should only be called after your application has obtained the appropriate user authorization.
+
+### Rich, status, and diagnostics
+
+```js
+const jid = '1234567890@s.whatsapp.net'
+const groupJid = '120363000000000000@g.us'
+const userJid = '15551234567@s.whatsapp.net'
+
+// relayMessage: send the raw forwarded GenAI label envelope.
+const labelPayload = {
+  __typename: 'GenAIUnifiedResponse',
+  response_id: 'test123',
+  sections: [{
+    __typename: 'GenAIUnifiedResponseSection',
+    view_model: {
+      __typename: 'GenAISingleLayoutViewModel',
+      primitive: {
+        __typename: 'GenAILabelPrimitive',
+        text: 'Hello goys',
+        variant: 'POSITIVE',
+        background_color_override: '#FF0000FF',
+        text_color_override: '#000000FF'
+      }
+    }
+  }]
+}
+await sock.relayMessage(jid, {
+  botForwardedMessage: {
+    message: {
+      richResponseMessage: {
+        messageType: 1,
+        unifiedResponse: {
+          data: Buffer.from(JSON.stringify(labelPayload)).toString('base64')
+        },
+        contextInfo: { isForwarded: true, forwardOrigin: 4 }
+      }
+    }
+  }
+}, {})
+// sendStatusMentions
+await sock.sendStatusMentions({ text: 'Hello from my status' }, [userJid])
+// sendBotPlanning
+await sock.sendBotPlanning(jid, { text: 'Working through the plan', steps: ['Fetch data', 'Send result'] })
+// sendRichLabelMessage
+await sock.sendRichLabelMessage(jid, {
+  text: 'Hello goys',
+  responseId: 'test123',
+  variant: 'POSITIVE',
+  backgroundColor: '#FF0000FF',
+  textColor: '#000000FF'
+})
+// sendRichGeneration
+await sock.sendRichGeneration(jid, {}, undefined, undefined)
+// getStatusPrivacy
+await sock.getStatusPrivacy()
+// setStatusPrivacy
+await sock.setStatusPrivacy('contacts', [userJid])
+// fetchBroadcastListQuota
+await sock.fetchBroadcastListQuota()
+// getChatBlockingStatus
+await sock.getChatBlockingStatus()
+// updateChatBlockingStatus
+await sock.updateChatBlockingStatus('block')
+// getUserDisclosures
+await sock.getUserDisclosures(0)
+// acceptTosNotice
+await sock.acceptTosNotice(0, {})
+// getOptOutList
+await sock.getOptOutList()
+// sendKeyIndexList
+await sock.sendKeyIndexList()
+```
+
+### Account, privacy, and security
+
+```js
+const jid = '1234567890@s.whatsapp.net'
+const groupJid = '120363000000000000@g.us'
+const userJid = '15551234567@s.whatsapp.net'
+
+// signPrivateCredential
+await sock.signPrivateCredential(Buffer.from('payload'))
+// getPushConfig
+await sock.getPushConfig()
+// setPushConfig
+await sock.setPushConfig({})
+// toggleCallLinkWaitingRoom
+await sock.toggleCallLinkWaitingRoom('example', true, 0)
+// storePrivacyTokens
+await sock.storePrivacyTokens([userJid])
+// updateBioPrivacy
+await sock.updateBioPrivacy('example')
+// blockBot
+await sock.blockBot(jid)
+// unblockBot
+await sock.unblockBot(jid)
+// getBotProfile
+await sock.getBotProfile(jid)
+// fetchABProps
+await sock.fetchABProps('example', 'example', 'example', 'example')
+// removeCompanionDevice
+await sock.removeCompanionDevice(jid, 0)
+// updateKeyIndexList
+await sock.updateKeyIndexList(0, Buffer.from('payload'))
+// fetchMediaConn
+await sock.fetchMediaConn('example')
+// deleteBroadcastList
+await sock.deleteBroadcastList(0)
+// fetchQRCode
+await sock.fetchQRCode('example', 'example')
+// confirmDeviceLogout
+await sock.confirmDeviceLogout(0, true)
+// checkUsername
+await sock.checkUsername('example')
+// checkUsernameMulti
+await sock.checkUsernameMulti([userJid])
+// setUsername
+await sock.setUsername('example', undefined)
+// deleteUsername
+await sock.deleteUsername()
+// getMyUsername
+await sock.getMyUsername()
+// getUsernameRecommendations
+await sock.getUsernameRecommendations()
+// setUsernamePin
+await sock.setUsernamePin('example')
+// findUserByUsername
+await sock.findUserByUsername('example')
+// fetchContactUsernames
+await sock.fetchContactUsernames(jid)
+// getPrivacySettings
+await sock.getPrivacySettings()
+// setPrivacySetting
+await sock.setPrivacySetting(undefined, 'example')
+// updatePrivacyContactList
+await sock.updatePrivacyContactList(undefined, 'example', jid)
+// getPrivacyContactList
+await sock.getPrivacyContactList(undefined)
+// updateTextStatus
+await sock.updateTextStatus(undefined)
+// getTextStatusList
+await sock.getTextStatusList()
+// updateUserStatus
+await sock.updateUserStatus(undefined)
+// fetchUserPictureInfo
+await sock.fetchUserPictureInfo(jid)
+// setProfilePictureMex
+await sock.setProfilePictureMex(jid, Buffer.from('payload'))
+// hasPassword
+await sock.hasPassword()
+// setPassword
+await sock.setPassword('example')
+// checkPassword
+await sock.checkPassword('example')
+// deletePassword
+await sock.deletePassword()
+// passkeyExists
+await sock.passkeyExists()
+// getRegistrationUpsells
+await sock.getRegistrationUpsells()
+// contactsUpload
+await sock.contactsUpload([userJid])
+// submitAge
+await sock.submitAge(0)
+// managedAccountInitiateLinking
+await sock.managedAccountInitiateLinking()
+// managedAccountValidateLinking
+await sock.managedAccountValidateLinking('example')
+// managedAccountAcceptLinking
+await sock.managedAccountAcceptLinking('example')
+// managedAccountCompleteLinking
+await sock.managedAccountCompleteLinking('example')
+// managedAccountRevokeLinking
+await sock.managedAccountRevokeLinking()
+// managedAccountSyncActivities
+await sock.managedAccountSyncActivities()
+// managedAccountUpdatePin
+await sock.managedAccountUpdatePin('example')
+// setAccessToken
+await sock.setAccessToken('example')
+// setWamoAuth
+await sock.setWamoAuth('example')
+// acquireAccessToken
+await sock.acquireAccessToken()
+// executeWWWGraphQL
+await sock.executeWWWGraphQL('example', undefined)
+// executeFacebookGraphQL
+await sock.executeFacebookGraphQL('example', undefined)
+// executeWamoGraphQL
+await sock.executeWamoGraphQL('example', undefined)
+```
+
+### Groups, AI groups, and calls
+
+```js
+const jid = '1234567890@s.whatsapp.net'
+const groupJid = '120363000000000000@g.us'
+const userJid = '15551234567@s.whatsapp.net'
+
+// groupCall
+await sock.groupCall(jid, [userJid], true)
+// cancelGroupCall
+await sock.cancelGroupCall(jid, 'example')
+// aiGroupMetadata
+await sock.aiGroupMetadata(jid)
+// aiGroupCreate
+await sock.aiGroupCreate('example', [userJid], undefined)
+// aiGroupAddBot
+await sock.aiGroupAddBot(jid, undefined)
+// aiGroupLeave
+await sock.aiGroupLeave('example')
+// aiGroupParticipantsUpdate
+await sock.aiGroupParticipantsUpdate(jid, [userJid], 'example')
+// aiGroupUpdateSubject
+await sock.aiGroupUpdateSubject(jid, 'example')
+// aiGroupInviteCode
+await sock.aiGroupInviteCode(jid)
+// aiGroupRevokeInvite
+await sock.aiGroupRevokeInvite(jid)
+// aiGroupAcceptInvite
+await sock.aiGroupAcceptInvite('example')
+// aiGroupSettingUpdate
+await sock.aiGroupSettingUpdate(jid, 'example')
+// aiGroupToggleEphemeral
+await sock.aiGroupToggleEphemeral(jid, 0)
+// groupAcknowledge
+await sock.groupAcknowledge(jid)
+// groupGetLinkedParticipants
+await sock.groupGetLinkedParticipants(jid)
+// groupJoinLinked
+await sock.groupJoinLinked(jid, jid, 'example')
+// groupCreateSubGroupSuggestion
+await sock.groupCreateSubGroupSuggestion(jid, {})
+// groupSubGroupSuggestionsAction
+await sock.groupSubGroupSuggestionsAction(jid, 'example', {})
+```
+
+### Interop
+
+```js
+const jid = '1234567890@s.whatsapp.net'
+const groupJid = '120363000000000000@g.us'
+const userJid = '15551234567@s.whatsapp.net'
+
+// initInterop
+await sock.initInterop()
+// resetInteropSession
+await sock.resetInteropSession()
+// acceptInteropTOS
+await sock.acceptInteropTOS()
+// resolveInteropUser
+await sock.resolveInteropUser(jid)
+// resolveInteropUsers
+await sock.resolveInteropUsers(jid)
+// blockInteropUser
+await sock.blockInteropUser(jid)
+// unblockInteropUser
+await sock.unblockInteropUser(jid)
+// reportInteropSpam
+await sock.reportInteropSpam(jid)
+// trustInteropContact
+await sock.trustInteropContact(jid)
+// createInteropGroup
+await sock.createInteropGroup('example', [userJid])
+// leaveInteropGroup
+await sock.leaveInteropGroup(jid)
+// addParticipantsToInteropGroup
+await sock.addParticipantsToInteropGroup(jid, [userJid])
+// queryInteropGroupInfo
+await sock.queryInteropGroupInfo(jid)
+// queryInteropPrivacySettings
+await sock.queryInteropPrivacySettings()
+// updateInteropPrivacySetting
+await sock.updateInteropPrivacySetting('example', 'example')
+// updateInteropPrivacySettingWithContactList
+await sock.updateInteropPrivacySettingWithContactList('example', 'example', [userJid])
+// getInteropGroupAddPrivacy
+await sock.getInteropGroupAddPrivacy()
+```
+
+### Generic helpers
+
+```js
+const jid = '1234567890@s.whatsapp.net'
+const groupJid = '120363000000000000@g.us'
+const userJid = '15551234567@s.whatsapp.net'
+
+// updateRichGeneration
+await sock.updateRichGeneration(jid, 'example', {}, undefined)
+// aiPrompt
+await sock.aiPrompt(jid, 'example', undefined)
+// getGroupProfilePictures
+await sock.getGroupProfilePictures(jid, 'example')
+// fetchIntegrators
+await sock.fetchIntegrators()
+// optInIntegrators
+await sock.optInIntegrators()
+// optOutIntegrators
+await sock.optOutIntegrators()
+// getReachabilitySettings
+await sock.getReachabilitySettings()
+// setReachabilitySettings
+await sock.setReachabilitySettings('example')
+// get
+await sock.get(undefined)
+// set
+await sock.set(undefined, 'example', 0)
+// delete
+await sock.delete(undefined)
+// keys
+await sock.keys(undefined)
+```
+
 ## Development
 
 ```bash
@@ -2328,14 +2818,66 @@ await sock.cleanDirtyBits('account_sync', timestamp)
 
 Meta AI-style thinking indicators and live reasoning feeds. Works on all WhatsApp clients — no "Update WhatsApp" messages.
 
+### Verified Meta AI prompts and streaming `MESSAGE_EDIT` replies
+
+The Hatch-compatible Meta AI sender routes prompts to the bot endpoint and
+returns the outgoing message ID:
+
+```javascript
+const messageId = await sock.sendMetaAI('Summarize this conversation', {
+  // Defaults to 867051314767696@bot
+  jid: '867051314767696@bot'
+})
+```
+
+Meta AI responses can arrive as a sequence rather than one final message. The
+first message is often a placeholder or partial response. WhatsApp then sends
+`MESSAGE_EDIT` protocol messages whose `protocolMessage.editedMessage` contains
+the newest version of the bot response. Each edit replaces the previous text;
+it is not a separate conversation message.
+
+Plogme's `extractMetaAiText()` checks the edited body first and also handles
+plain text, rich-response submessages, and base64 unified responses:
+
+```javascript
+import { extractMetaAiText } from 'plogme'
+
+sock.ev.on('messages.upsert', ({ messages }) => {
+  for (const message of messages) {
+    const text = extractMetaAiText(message.message)
+    if (text) console.log('latest Meta AI text:', text)
+  }
+})
+```
+
+An incoming edit has the conceptual shape below:
+
+```javascript
+{
+  protocolMessage: {
+    type: 'MESSAGE_EDIT',
+    key: { remoteJid: '867051314767696@bot', id: 'ORIGINAL_ID' },
+    editedMessage: {
+      extendedTextMessage: { text: 'latest streamed response' }
+    }
+  }
+}
+```
+
+For unified responses, the raw payload remains available in
+`unifiedResponse.data`; the decoder adds `decodedData` and flattened `text` in
+place. This makes it possible to render partial edits immediately while still
+retaining the original wire representation.
+
 **Note:** These use plain text placeholders with typing indicators by default, avoiding unsupported-message bubbles. Final code blocks, tables, links, and rich responses are unchanged. Native Meta typing/thinking is force-only: set both `forceMetaRendering: true` in the socket config and `useNativeMeta: true` in the `metaTyping` or `sendMetaComposited` options.
 
 ### Meta Typing Indicator
 
-Show a live thinking indicator that you control. Delete it manually when ready — no "edited" badge ever appears.
+Show a live thinking indicator that you control. It is a real message, so you
+can edit it in place or delete it manually when finished.
 
 ```javascript
-import { metaTyping, buildSteps } from 'plogme'
+import { metaTyping, editMetaMessage, buildSteps } from 'plogme'
 
 const placeholder = await metaTyping(sock, jid, {
   description: 'Thinking…',
@@ -2344,11 +2886,9 @@ const placeholder = await metaTyping(sock, jid, {
 
 // Do your work here…
 
-// Delete the indicator cleanly
-await sock.sendMessage(jid, { delete: placeholder.key })
-
-// Send the real message
-await sock.sendMessage(jid, { text: 'Here is your answer!' })
+// Keep the same message key while streaming progress
+await editMetaMessage(sock, jid, placeholder.key, { text: 'Thinking… I found something.' })
+await editMetaMessage(sock, jid, placeholder.key, { text: 'Here is your answer!' })
 ```
 
 What users see:
@@ -2360,14 +2900,15 @@ _Thinking…_
 ○ Reading your message…
 ○ Writing response…
 
-[auto-deletes]
+_Thinking… I found something._
 
-Here is your answer!
+Here is your answer!  // same message, updated through MESSAGE_EDIT
 ```
 
 ### Meta Compositing
 
-Full flow: indicator shows → auto-deletes → clean final message lands. Works with every rich content type.
+Full flow: initial message → optional `MESSAGE_EDIT` stream frames → final
+`MESSAGE_EDIT` on the same message key. Works with every rich content type.
 
 ```javascript
 import { sendMetaComposited, PlanningStepStatus } from 'plogme'
@@ -2379,6 +2920,11 @@ await sendMetaComposited(
   {
     thinkingMs: 3000,
     description: 'Analyzing…',
+    streamUpdates: [
+      'Thinking…',
+      'Thinking… I found the relevant code.'
+    ],
+    streamUpdateDelayMs: 700,
     steps: [
       { title: 'Reading context…', status: PlanningStepStatus.DONE },
       { title: 'Writing code…', status: PlanningStepStatus.IN_PROGRESS }
@@ -2416,7 +2962,8 @@ await sendMetaComposited(
 
 ### Replay Planning
 
-Live Meta AI-style reasoning feed — each step visibly completes in real time, then the final rich message lands clean.
+Live Meta AI-style reasoning feed — each step visibly completes in real time,
+then the final rich message is written with `MESSAGE_EDIT` on the same key.
 
 ```javascript
 import { replayPlanning, mixedSteps } from 'plogme'