plogme 2.1.0 → 2.1.2

package/lib/Utils/rich-message-utils.js

@@ -1,3 +1,15 @@
+/**
+ * @crysnpvax
+ *
+ * File: lib/Utils/rich-message-utils.js
+ * About: Rich message utils module for the Plogme WhatsApp protocol client.
+ * Important exports: tokenizeCode, normalizeNewReel, normalizeNewRichImage, prepareNewRichMediaCompatibility, toUnified, buildImaginePrimitive, prepareRichGenerationMessage, buildAdditionalBotMetadataContext; …
+ * Directions: Import the listed exports and preserve protocol, validation, and compatibility invariants when modifying.
+ *
+ * Copyright and attribution notice.
+ * Do not copy, reproduce, redistribute, modify, or create derivative works
+ * from this source without explicit written permission.
+ */
 /**
  * Lia@Changes 09-04-26 [WIP]
  * Adds support for tables and code blocks with richResponseMessage (wrapped inside botForwardedMessage).
@@ -11,6 +23,7 @@ import { LANGUAGE_KEYWORDS } from '../WABinary/constants.js';
 import { CodeHighlightType, RichSubMessageType } from '../Types/RichType.js';
 import { proto } from '../../WAProto/index.js';
 import { unixTimestampSeconds } from './generics.js';
+import { generateTableContent } from './message-composer.js';
 const NOOP = new Set([]);
 export const tokenizeCode = (code, language = 'javascript') => {
     const keywords = LANGUAGE_KEYWORDS[language] || NOOP;
@@ -47,6 +60,14 @@ export const tokenizeCode = (code, language = 'javascript') => {
 };
 const firstImageValue = (...values) => values.find(value => value !== undefined && value !== null && String(value).length > 0);
 
+const inferImageMimeType = (url = '') => {
+    const path = String(url).split('?')[0].toLowerCase();
+    if (path.endsWith('.jpg') || path.endsWith('.jpeg')) return 'image/jpeg';
+    if (path.endsWith('.webp')) return 'image/webp';
+    if (path.endsWith('.gif')) return 'image/gif';
+    return 'image/png';
+};
+
 /** Normalize album image variants without downgrading full-size URLs to previews. */
 const buildRichImagePrimitive = (image = {}, expiration = String(Date.now() + 30 * 24 * 60 * 60 * 1000)) => {
     const previewUrl = firstImageValue(image.imagePreviewUrl, image.previewUrl, image.preview_url, image.sourceUrl, image.source_url, image.url) || '';
@@ -59,13 +80,7 @@ const buildRichImagePrimitive = (image = {}, expiration = String(Date.now() + 30
     const fullHeight = Number(image.fullHeight || image.full_height || image.highResHeight || image.high_res_height || image.height || height);
     const darkWidth = Number(image.darkWidth || image.dark_width || fullWidth);
     const darkHeight = Number(image.darkHeight || image.dark_height || fullHeight);
-    const mimeType = image.mimeType || image.mime_type || (() => {
-        const value = String(fullUrl || previewUrl).split('?')[0].toLowerCase();
-        if (value.endsWith('.jpg') || value.endsWith('.jpeg')) return 'image/jpeg';
-        if (value.endsWith('.webp')) return 'image/webp';
-        if (value.endsWith('.gif')) return 'image/gif';
-        return 'image/png';
-    })();
+    const mimeType = image.mimeType || image.mime_type || inferImageMimeType(fullUrl || previewUrl);
     const media = (url, mediaWidth, mediaHeight) => ({
         url,
         url_fallback: url,
@@ -86,6 +101,54 @@ const buildRichImagePrimitive = (image = {}, expiration = String(Date.now() + 30
     primitive.dark_mode_full_image = media(darkFullUrl, darkWidth, darkHeight);
     return primitive;
 };
+
+/** Normalize the field names used by New compatibility's Meta/reels helpers. */
+export const normalizeNewReel = (reel = {}) => ({
+    reels_url: reel.videoUrl || reel.video_url || reel.reels_url || reel.reelsUrl || reel.url || '',
+    thumbnail_url: reel.thumbnailUrl || reel.thumbnail_url || reel.thumbnail || '',
+    creator: reel.creator || reel.username || reel.title || '',
+    avatar_url: reel.profileIconUrl || reel.avatar_url || reel.avatar || reel.icon || '',
+    reels_title: reel.title || reel.reels_title || reel.reelsTitle || '',
+    likes_count: reel.likesCount ?? reel.likes_count ?? reel.likes ?? 0,
+    comments_count: reel.commentsCount ?? reel.comments_count ?? reel.comments ?? 0,
+    shares_count: reel.sharesCount ?? reel.shares_count ?? reel.shares ?? 0,
+    view_count: reel.viewCount ?? reel.view_count ?? reel.views ?? 0,
+    reel_source: reel.reelSource || reel.reel_source || reel.source || 'IG',
+    is_verified: !!(reel.isVerified ?? reel.is_verified ?? reel.verified),
+    orientation: reel.orientation || reel.ratio || 'LANDSCAPE',
+    post_type: reel.postType || reel.post_type || 'VIDEO',
+    is_carousel: reel.isCarousel ?? reel.is_carousel ?? false
+});
+
+/** Build the New-compatible image/post shape without replacing native image data. */
+export const normalizeNewRichImage = (image = {}) => ({
+    thumbnail_url: image.thumbnailUrl || image.thumbnail_url || image.thumbnail || image.previewUrl || image.preview_url || '',
+    image_url: image.imageUrl || image.image_url || image.fullUrl || image.full_url || image.url || '',
+    source_url: image.sourceUrl || image.source_url || image.url || '',
+    title: image.title || image.caption || '',
+    creator: image.creator || image.username || '',
+    avatar_url: image.profileIconUrl || image.avatar_url || image.avatar || '',
+    is_verified: !!(image.isVerified ?? image.is_verified ?? image.verified),
+    post_caption: image.postCaption || image.post_caption || image.caption || '',
+    likes_count: image.likesCount ?? image.likes_count ?? image.likes ?? 0,
+    comments_count: image.commentsCount ?? image.comments_count ?? image.comments ?? 0,
+    shares_count: image.sharesCount ?? image.shares_count ?? image.shares ?? 0,
+    orientation: image.orientation || image.ratio || 'LANDSCAPE',
+    post_type: image.postType || image.post_type || 'IMAGE',
+    is_carousel: image.isCarousel ?? image.is_carousel ?? false
+});
+
+/** Create the second New-shaped representation beside native AIRich sections. */
+export const prepareNewRichMediaCompatibility = (content = {}) => {
+    const reels = (Array.isArray(content.reels) ? content.reels : []).map(normalizeNewReel);
+    const images = (Array.isArray(content.images) ? content.images : content.image ? [content.image] : []).map(normalizeNewRichImage);
+    const posts = (Array.isArray(content.posts) ? content.posts : content.post ? [content.post] : []).map(normalizeNewRichImage);
+    const sections = [];
+    if (reels.length) sections.push({ view_model: { primitives: reels.map(item => ({ ...item, __typename: 'GenAIReelPrimitive' })), __typename: 'GenAIHScrollLayoutViewModel' } });
+    if (images.length) sections.push({ view_model: { primitives: images.map(item => ({ ...item, __typename: 'GenAIImagePrimitive' })), __typename: 'GenAIHScrollLayoutViewModel' } });
+    if (posts.length) sections.push({ view_model: { primitives: posts.map(item => ({ ...item, __typename: 'GenAIPostPrimitive' })), __typename: 'GenAIHScrollLayoutViewModel' } });
+    return { compatibility: 'new-rich-media', reels, images, posts, sections };
+};
 // Lia@Changes 09-04-26 --- Inject buffer into unifiedResponse.data to support proper rendering of rich messages (ex: tables and code blocks)
 export const toUnified = (submessages, uuid) => ({
     response_id: uuid || randomUUID(),
@@ -138,8 +201,24 @@ export const toUnified = (submessages, uuid) => ({
             }
             case RichSubMessageType.INLINE_IMAGE: {
                 const image = submessage.imageMetadata || {};
-                const media = mediaPrimitive({ url: image.imageUrl || image.url, mime_type: image.mimeType || image.mime_type, width: image.width, height: image.height });
-                return media ? { view_model: { primitive: media, __typename: 'GenAISingleLayoutViewModel' } } : {};
+                const rawImage = image.imageUrl || image.url || image.image;
+                const imageData = typeof rawImage === 'string'
+                    ? { ...image, url: rawImage }
+                    : { ...image, ...(rawImage || {}) };
+                const primitive = buildRichImagePrimitive({
+                    ...imageData,
+                    mimeType: imageData.mimeType || imageData.mime_type,
+                });
+                return primitive.full_image.url
+                    ? {
+                        view_model: {
+                            primitives: [{ ...primitive, display_mode: 'FULL_WIDTH', full_width: true }],
+                            display_mode: 'FULL_WIDTH',
+                            full_width: true,
+                            __typename: 'GenAIVStackLayoutViewModel'
+                        }
+                    }
+                    : {};
             }
             case RichSubMessageType.LATEX: {
                 const metadata = submessage.latexMetadata || {};
@@ -842,23 +921,20 @@ export const prepareRichQuoteMessage = (options = {}) => {
  * @returns {Object} Wrapped botForwardedMessage ready for relayMessage
  */
 export const prepareRichImageMessage = (options = {}) => {
-    const { url = '', mimeType = 'image/png', verificationMetadata } = options;
-    const media = {
-        __typename: 'GenAIMediaItem',
-        mime_type: mimeType,
-        url,
-        url_fallback: url,
+    const { url = '', mimeType, verificationMetadata } = options;
+    const primitive = {
+        ...buildRichImagePrimitive({ url, mimeType }),
+        display_mode: 'FULL_WIDTH',
+        full_width: true,
     };
     const sections = [
         {
             __typename: 'GenAIUnifiedResponseSection',
             view_model: {
-                __typename: 'GenAISingleLayoutViewModel',
-                primitive: {
-                    __typename: 'GenAIImagePrimitive',
-                    preview_image: media,
-                    full_image: media,
-                },
+                __typename: 'GenAIVStackLayoutViewModel',
+                primitives: [primitive],
+                display_mode: 'FULL_WIDTH',
+                full_width: true,
             },
         },
     ];
@@ -1320,8 +1396,61 @@ export const prepareBotPttTranscriptMessage = ({ text = '', transcript = '', ver
     return envelope;
 };
 
-export const prepareRichResponseMessage = (content) => {
-    const { alignment, code, contentText, disclaimerText, footerText, headerText, imageText, inlineImage, inlineVideo, items, language, latex, links, noDonation, noHeading, posts, products, reels, sources: sourceInputs, suggested, richResponse, table, tapLinkUrl, title, verificationMetadata } = content;
+const buildFoaHtmlSection = (html, trustedSources = []) => ({
+    __typename: 'GenAIUnifiedResponseSection',
+    view_model: {
+        __typename: 'GenAISingleLayoutViewModel',
+        primitive: {
+            __typename: 'FOAHtmlPrimitiveDemoDONOTUSE',
+            trusted_sources: Array.isArray(trustedSources) ? trustedSources : [],
+            payload: String(html ?? '').trim()
+        }
+    }
+});
+
+const buildRichHtmlScreen = (options = {}) => {
+    const {
+        html = '',
+        trustedSources = [],
+        url = '',
+        title = 'Preview',
+        tabHeader = 'HTML',
+        tabs
+    } = options;
+    const tabItems = Array.isArray(tabs) && tabs.length
+        ? tabs
+        : [{ id: 'tab_0', tab_header: tabHeader, html }];
+    const embeddedTabs = tabItems.map((tab, index) => ({
+        id: tab.id || `tab_${index}`,
+        tab_header: tab.tab_header || tab.title || `HTML ${index + 1}`,
+        sections: [{
+            __typename: 'GenAIUnifiedResponseSection',
+            view_model: {
+                __typename: 'GenAISingleLayoutViewModel',
+                primitive: {
+                    __typename: 'GenAIaeacdsnwHtmlPrimitive',
+                    payload: String(tab.html ?? tab.payload ?? html).trim(),
+                    url: tab.url || url,
+                    trusted_sources: tab.trustedSources || trustedSources
+                }
+            }
+        }],
+        step_entries: []
+    }));
+    return {
+        title,
+        embeddedScreen: {
+            title,
+            content: [{
+                __typename: 'FOAIDNixelButtonSheets',
+                tabs: embeddedTabs
+            }]
+        }
+    };
+};
+
+const prepareRichResponseMessageFixedOrder = (content) => {
+    const { alignment, code, compatibility, contentText, disclaimerText, footerText, headerText, html, richHtml, trustedSources, imageText, image, images, inlineImage, inlineVideo, items, language, latex, links, noDonation, noHeading, posts, products, reels, sources: sourceInputs, suggested, richResponse, table, tapLinkUrl, title, verificationMetadata, sections: rawSections, richSections, copyButton, copyToClipboard, copyText, copyLabel, richText, quote, richImage, richLinks, richMap, map, dynamicMedia, richDynamicMedia, socialEntity, socialProfile, richMenu, airichCommandMenu, unifiedResponse, gridImages, verticalAlbum, videoGrid, richGeneration, richLabel, suggestedPrompt, botSources, botPttTranscript } = content;
     let submessages = [];
     const extraSections = [];
     if (Array.isArray(richResponse)) {
@@ -1456,28 +1585,34 @@ export const prepareRichResponseMessage = (content) => {
             });
         }
         if (inlineImage) {
+            const image = typeof inlineImage === 'string' ? { url: inlineImage } : (inlineImage || {});
             submessages.push({
                 messageType: RichSubMessageType.INLINE_IMAGE,
                 imageMetadata: {
-                    imageUrl: inlineImage,
+                    ...image,
+                    imageUrl: image.url || image.imageUrl || image.image || '',
                     imageText,
                     alignment,
-                    tapLinkUrl
+                    tapLinkUrl,
+                    mimeType: image.mimeType || image.mime_type,
+                    width: image.width,
+                    height: image.height,
+                    fullWidth: image.fullWidth || image.full_width,
+                    fullHeight: image.fullHeight || image.full_height
                 }
             });
         }
         if (inlineVideo) {
             const video = typeof inlineVideo === 'string' ? { url: inlineVideo } : inlineVideo;
-            submessages.push({ messageType: RichSubMessageType.TEXT, messageText: '[ CANNOT_LOAD_VIDEO - NIXEL ]' });
             extraSections.push({
                 view_model: {
                     primitive: buildImaginePrimitive({
                         mediaType: 'video',
-                        url: video?.url || video?.videoUrl || '',
-                        mimeType: video?.mimeType || video?.mime_type || 'video/mp4',
-                        fileLength: video?.fileLength || video?.file_length || 0,
-                        duration: video?.duration || 0,
-                        thumbnail: video?.thumbnail,
+                        url: video?.url || video?.videoUrl || video?.video_url || '',
+                        mimeType: video?.mimeType || video?.mime_type || video?.mimetype || 'video/mp4',
+                        fileLength: video?.fileLength ?? video?.file_length ?? video?.filesize ?? 0,
+                        duration: video?.duration ?? 0,
+                        thumbnail: video?.thumbnail || video?.thumbnailUrl || video?.thumbnail_url,
                         status: video?.status || 'READY'
                     }),
                     __typename: 'GenAISingleLayoutViewModel'
@@ -1565,10 +1700,6 @@ export const prepareRichResponseMessage = (content) => {
             });
         }
         if (posts) {
-            submessages.push({
-                messageType: RichSubMessageType.TEXT,
-                messageText: '[ CANNOT_LOAD_POST - NIXEL ]'
-            });
             const postItems = (Array.isArray(posts) ? posts : [posts]).map((post) => ({
                 title: post?.title || '',
                 subtitle: post?.subtitle || '',
@@ -1593,10 +1724,6 @@ export const prepareRichResponseMessage = (content) => {
             if (postItems.length) extraSections.push({ view_model: { primitives: postItems, __typename: 'GenAIHScrollLayoutViewModel' } });
         }
         if (products) {
-            submessages.push({
-                messageType: RichSubMessageType.TEXT,
-                messageText: '[ CANNOT_LOAD_PRODUCT - NIXEL ]'
-            });
             const productItems = (Array.isArray(products) ? products : [products]).map((product) => ({
                 title: product?.title || '',
                 brand: product?.brand || '',
@@ -1621,14 +1748,14 @@ export const prepareRichResponseMessage = (content) => {
                 messageText: 'SUGGESTED_PROMPT'
             });
         }
-        if (table) {
+        if (Array.isArray(table)) {
             submessages.push({
                 messageType: RichSubMessageType.TABLE,
                 tableMetadata: {
                     title,
                     rows: table.map((items, index) => ({
                         isHeading: !noHeading && index == 0,
-                        items
+                        items: Array.isArray(items) ? items.map(String) : [String(items)]
                     }))
                 }
             });
@@ -1640,11 +1767,82 @@ export const prepareRichResponseMessage = (content) => {
             });
         }
     }
+    const htmlIsTabbedConfig = html && typeof html === 'object' && Array.isArray(html.tabs);
+    const simpleHtmlPayload = htmlIsTabbedConfig ? '' : (typeof html === 'string' ? html : (html?.html ?? html?.payload ?? ''));
+    const htmlPayload = simpleHtmlPayload;
+    const htmlTrustedSources = Array.isArray(html?.trustedSources) ? html.trustedSources : trustedSources;
+    if (String(htmlPayload).trim()) {
+        extraSections.push(buildFoaHtmlSection(htmlPayload, htmlTrustedSources));
+    }
+    const richHtmlOptions = richHtml ?? (htmlIsTabbedConfig ? html : null);
+    const richHtmlConfig = typeof richHtmlOptions === 'string'
+        ? { html: richHtmlOptions, trustedSources }
+        : (richHtmlOptions && typeof richHtmlOptions === 'object'
+            ? { ...richHtmlOptions, trustedSources: richHtmlOptions.trustedSources ?? trustedSources }
+            : null);
+    const hasRichHtmlContent = !!(richHtmlConfig && (
+        String(richHtmlConfig.html || '').trim() ||
+        (Array.isArray(richHtmlConfig.tabs) && richHtmlConfig.tabs.some(tab => String(tab?.html ?? tab?.payload ?? '').trim()))
+    ));
+    let richHtmlScreen;
+    if (hasRichHtmlContent) {
+        richHtmlScreen = buildRichHtmlScreen(richHtmlConfig);
+        submessages.unshift({
+            messageType: RichSubMessageType.TEXT,
+            messageText: `> ${richHtmlScreen.title}`
+        });
+    }
     const uuid = randomUUID();
     const unified = toUnified(submessages, uuid);
     unified.sections = [...unified.sections.filter(Boolean), ...extraSections];
+    if (compatibility === 'new-rich-media' || compatibility === 'both') {
+        const compatible = prepareNewRichMediaCompatibility({ reels, images: images || (inlineImage ? [inlineImage] : image ? [image] : []), posts });
+        unified.sections.push(...compatible.sections);
+        unified.new_rich_media = {
+            compatibility: compatible.compatibility,
+            reels: compatible.reels,
+            images: compatible.images,
+            posts: compatible.posts
+        };
+    }
+    if (richHtmlScreen) unified.embedded_screens = [richHtmlScreen.embeddedScreen];
+
+    // Compose the remaining AIRich convenience formats as sections. These
+    // aliases intentionally mirror the standalone send* helpers, allowing a
+    // caller to mix them with text, HTML, tables, media, and citations in one
+    // PLOGME message. Raw sections remain available as the forward-compatible
+    // escape hatch for new WhatsApp primitives.
+    const composed = { sections: unified.sections, embedded_screens: unified.embedded_screens, submessages, botMetadata: {} };
+    const append = (prepared) => appendPreparedRichContent(composed, prepared);
+    if (copyButton || copyToClipboard || copyText) append(prepareCopyToClipboardMessage(copyButton || copyToClipboard || { text: copyText, label: copyLabel }));
+    if (richText) append(prepareRichTextMessage(typeof richText === 'string' ? { text: richText } : richText));
+    if (quote) append(prepareRichQuoteMessage(typeof quote === 'string' ? { text: quote } : quote));
+    if (richImage) append(prepareRichImageMessage(typeof richImage === 'string' ? { url: richImage } : richImage));
+    if (richLinks) append(prepareRichLinkMessage(Array.isArray(richLinks) ? { links: richLinks } : richLinks));
+    if (richMap || map) append(prepareRichMapMessage(richMap || map));
+    if (dynamicMedia || richDynamicMedia) append(prepareRichDynamicMediaMessage(dynamicMedia || richDynamicMedia));
+    if (socialEntity) append(prepareSocialEntityMessage(socialEntity));
+    if (socialProfile) append(prepareSocialProfileMessage(socialProfile));
+    if (richMenu) append(prepareRichMenuMessage(richMenu));
+    if (airichCommandMenu) append(prepareAIRichCommandMenu(airichCommandMenu));
+    if (gridImages) append(prepareGridImageMessage({ imageUrls: gridImages, verificationMetadata }));
+    if (verticalAlbum) append(prepareVerticalAlbumMessage({ items: verticalAlbum, verificationMetadata }));
+    if (videoGrid) append(prepareVideoGridMessage({ videos: videoGrid, verificationMetadata }));
+    if (richGeneration) append(prepareRichGenerationMessage({ ...richGeneration, verificationMetadata }));
+    if (richLabel) append(buildRichLabelMessage(richLabel));
+    if (suggestedPrompt) append(prepareBotPromptSuggestionsMessage({ ...suggestedPrompt, verificationMetadata }));
+    if (botSources) append(prepareBotSourcesMessage({ ...botSources, verificationMetadata }));
+    if (botPttTranscript) append(prepareBotPttTranscriptMessage({ ...botPttTranscript, verificationMetadata }));
+    if (unifiedResponse?.sections) {
+        unified.sections.push(...unifiedResponse.sections);
+        if (Array.isArray(unifiedResponse.embedded_screens)) unified.embedded_screens = [...(unified.embedded_screens || []), ...unifiedResponse.embedded_screens];
+    }
+    for (const section of [...(Array.isArray(rawSections) ? rawSections : []), ...(Array.isArray(richSections) ? richSections : [])]) {
+        if (section && typeof section === 'object') unified.sections.push(section);
+    }
+    if (composed.embedded_screens?.length) unified.embedded_screens = composed.embedded_screens;
     const richResponseMessage = proto.AIRichResponseMessage.create({
-        submessages,
+        submessages: composed.submessages,
         messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
         unifiedResponse: {
             data: Buffer.from(JSON.stringify(unified)) // Lia@Note 25-04-26 --- Expects "ArrayBufferLike"
@@ -1658,6 +1856,7 @@ export const prepareRichResponseMessage = (content) => {
     });
     const message = wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
     const botMetadata = message.messageContextInfo.botMetadata;
+    Object.assign(botMetadata, composed.botMetadata);
     // Lia@Note 13-05-26 --- Add disclaimer text on richResponseMessage
     if (disclaimerText) {
         botMetadata.messageDisclaimerText = disclaimerText;
@@ -1706,19 +1905,7 @@ export const botMetadataCertificate = (length = 685) => {
  */
 export const prepareHtmlMessage = (options = {}) => {
     const { html = '', trustedSources = [], verificationMetadata } = options;
-    const sections = [
-        {
-            __typename: 'GenAIUnifiedResponseSection',
-            view_model: {
-                __typename: 'GenAISingleLayoutViewModel',
-                primitive: {
-                    __typename: 'FOAHtmlPrimitiveDemoDONOTUSE',
-                    trusted_sources: trustedSources,
-                    payload: String(html).trim()
-                }
-            }
-        }
-    ];
+    const sections = [buildFoaHtmlSection(html, trustedSources)];
     const unified = { response_id: randomUUID(), sections };
     const richResponseMessage = proto.AIRichResponseMessage.create({
         submessages: [],
@@ -1735,35 +1922,8 @@ export const prepareHtmlMessage = (options = {}) => {
  * aeacdsnw HTML primitive used by the attached game message.
  */
 export const prepareRichHtmlMessage = (options = {}) => {
-    const {
-        html = '',
-        trustedSources = [],
-        url = '',
-        title = 'Preview',
-        tabHeader = 'HTML',
-        tabs,
-        verificationMetadata
-    } = options;
-    const tabItems = Array.isArray(tabs) && tabs.length
-        ? tabs
-        : [{ id: 'tab_0', tab_header: tabHeader, html }];
-    const embeddedTabs = tabItems.map((tab, index) => ({
-        id: tab.id || `tab_${index}`,
-        tab_header: tab.tab_header || tab.title || `HTML ${index + 1}`,
-        sections: [{
-            __typename: 'GenAIUnifiedResponseSection',
-            view_model: {
-                __typename: 'GenAISingleLayoutViewModel',
-                primitive: {
-                    __typename: 'GenAIaeacdsnwHtmlPrimitive',
-                    payload: String(tab.html ?? tab.payload ?? html).trim(),
-                    url: tab.url || url,
-                    trusted_sources: tab.trustedSources || trustedSources
-                }
-            }
-        }],
-        step_entries: []
-    }));
+    const { verificationMetadata } = options;
+    const { title, embeddedScreen } = buildRichHtmlScreen(options);
     const unified = {
         response_id: randomUUID(),
         sections: [{
@@ -1772,13 +1932,7 @@ export const prepareRichHtmlMessage = (options = {}) => {
                 __typename: 'GenAISingleLayoutViewModel'
             }
         }],
-        embedded_screens: [{
-            title,
-            content: [{
-                __typename: 'FOAIDNixelButtonSheets',
-                tabs: embeddedTabs
-            }]
-        }]
+        embedded_screens: [embeddedScreen]
     };
     const richResponseMessage = proto.AIRichResponseMessage.create({
         messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
@@ -1789,6 +1943,245 @@ export const prepareRichHtmlMessage = (options = {}) => {
     return wrapToBotForwardedMessage(richResponseMessage, verificationMetadata);
 };
 
+const decodePreparedUnified = (prepared) => {
+    const richResponse = prepared?.botForwardedMessage?.message?.richResponseMessage;
+    const rawData = richResponse?.unifiedResponse?.data;
+    if (!rawData) return null;
+    try {
+        const text = Buffer.isBuffer(rawData)
+            ? rawData.toString()
+            : (rawData instanceof Uint8Array ? Buffer.from(rawData).toString() : String(rawData));
+        const decoded = Buffer.from(text, /^[A-Za-z0-9+/]+=*$/.test(text) ? 'base64' : 'utf8').toString();
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+};
+
+/**
+ * Compose each rich fragment in the order its key appears in the caller's
+ * object. The fixed-order renderer remains the single source of wire formats;
+ * this wrapper only orders independently rendered sections before combining
+ * them into one AIRich response.
+ */
+export const prepareRichResponseMessage = (content = {}) => {
+    if (!content || typeof content !== 'object' || Array.isArray(content)) {
+        throw new Boom('rich response content must be an object', { statusCode: 400 });
+    }
+    const submessages = [];
+    const sections = [];
+    const embeddedScreens = [];
+    const mergedBotMetadata = {};
+    const compatibility = content.compatibility === 'new-rich-media' || content.compatibility === 'both';
+    let compatibilityAdded = false;
+    let newRichMedia;
+
+    const appendPrepared = (prepared) => {
+        const unified = decodePreparedUnified(prepared);
+        if (Array.isArray(unified?.sections)) sections.push(...unified.sections.filter(Boolean));
+        if (Array.isArray(unified?.embedded_screens)) embeddedScreens.push(...unified.embedded_screens);
+        const richResponse = prepared?.botForwardedMessage?.message?.richResponseMessage;
+        if (Array.isArray(richResponse?.submessages)) submessages.push(...richResponse.submessages);
+        const botMetadata = prepared?.messageContextInfo?.botMetadata;
+        if (botMetadata) Object.assign(mergedBotMetadata, botMetadata);
+    };
+
+    const appendField = (key, value) => {
+        const fragment = { noDonation: true, verificationMetadata: content.verificationMetadata };
+        switch (key) {
+            case 'text':
+                fragment.contentText = value;
+                break;
+            case 'table':
+                appendTableValue(value);
+                return;
+            case 'code':
+                fragment.code = value;
+                fragment.language = content.language;
+                break;
+            case 'inlineImage':
+                fragment.inlineImage = value;
+                fragment.imageText = content.imageText;
+                fragment.alignment = content.alignment;
+                fragment.tapLinkUrl = content.tapLinkUrl;
+                break;
+            case 'html':
+                fragment.html = value;
+                fragment.trustedSources = content.trustedSources;
+                break;
+            case 'richHtml':
+                fragment.richHtml = value;
+                fragment.trustedSources = content.trustedSources;
+                break;
+            case 'richTable':
+                appendTableValue(value);
+                return;
+            case 'tables':
+                if (Array.isArray(value)) value.forEach(appendTableValue);
+                return;
+            case 'richResponse': {
+                if (!Array.isArray(value)) break;
+                for (const item of value) {
+                    if (item?.inlineVideo) appendField('inlineVideo', item.inlineVideo);
+                    else if (Object.hasOwn(item || {}, 'table')) appendField('table', item.table);
+                    else if (item?.posts) appendField('posts', item.posts);
+                    else if (item?.products) appendField('products', item.products);
+                    else if (item?.suggested) appendField('suggested', item.suggested);
+                    else appendPrepared(prepareRichResponseMessageFixedOrder({
+                        richResponse: [item],
+                        noDonation: true,
+                        verificationMetadata: content.verificationMetadata
+                    }));
+                }
+                return;
+            }
+            case 'contentItemsGroup':
+                Object.assign(fragment, value);
+                break;
+            default:
+                fragment[key] = value;
+        }
+        appendPrepared(prepareRichResponseMessageFixedOrder(fragment));
+    };
+
+    const appendSimpleTable = (tableRows) => {
+        const normalizedRows = tableRows.map(row => Array.isArray(row) ? row : [row]);
+        appendPrepared(prepareRichResponseMessageFixedOrder({
+            table: normalizedRows,
+            title: content.title,
+            noHeading: content.noHeading,
+            noDonation: true,
+            verificationMetadata: content.verificationMetadata
+        }));
+    };
+
+    const appendRichTable = (table) => {
+        if (!table || typeof table !== 'object' || Array.isArray(table)) return;
+        const richTable = generateTableContent(
+            String(table.title ?? ''),
+            Array.isArray(table.headers) ? table.headers : [],
+            Array.isArray(table.rows) ? table.rows : [],
+            undefined,
+            { headerText: table.headerText, footer: table.footer }
+        );
+        const richResponse = richTable?.message?.botForwardedMessage?.message?.richResponseMessage;
+        if (Array.isArray(richResponse?.submessages)) submessages.push(...richResponse.submessages);
+    };
+
+    const appendTableValue = (table) => {
+        if (Array.isArray(table)) {
+            appendSimpleTable(table);
+            return;
+        }
+        if (!table || typeof table !== 'object') return;
+        if (Array.isArray(table.headers) && Array.isArray(table.rows)) {
+            appendRichTable(table);
+        }
+        else if (Array.isArray(table.rows)) {
+            appendSimpleTable([...(Array.isArray(table.headers) ? [table.headers] : []), ...table.rows]);
+        }
+    };
+
+    const appendCompatibility = () => {
+        if (compatibilityAdded || !compatibility) return;
+        compatibilityAdded = true;
+        const compatible = prepareNewRichMediaCompatibility({
+            reels: content.reels,
+            images: content.images || (content.image ? [content.image] : []),
+            posts: content.posts
+        });
+        if (!compatible.sections.length) return;
+        sections.push(...compatible.sections);
+        newRichMedia = {
+            compatibility: compatible.compatibility,
+            reels: compatible.reels,
+            images: compatible.images,
+            posts: compatible.posts
+        };
+    };
+
+    const nonRenderableKeys = new Set([
+        'alignment', 'compatibility', 'copyLabel', 'disclaimerText',
+        'image', 'images', 'language', 'noDonation', 'noHeading', 'title',
+        'tapLinkUrl', 'trustedSources', 'verificationMetadata'
+    ]);
+    const renderableKeys = new Set([
+        'headerText', 'contentText', 'text', 'footerText', 'code', 'table', 'richTable', 'tables', 'items', 'reels',
+        'inlineImage', 'inlineVideo', 'latex', 'links', 'sources', 'posts', 'products', 'suggested',
+        'html', 'richHtml', 'richResponse', 'copyButton', 'copyToClipboard', 'copyText',
+        'richText', 'quote', 'richImage', 'richLinks', 'richMap', 'map', 'dynamicMedia',
+        'richDynamicMedia', 'socialEntity', 'socialProfile', 'richMenu', 'airichCommandMenu',
+        'unifiedResponse', 'gridImages', 'verticalAlbum', 'videoGrid', 'richGeneration',
+        'richLabel', 'suggestedPrompt', 'botSources', 'botPttTranscript', 'sections', 'richSections'
+    ]);
+    const inputEntries = Object.entries(content);
+    const entries = [
+        ...inputEntries.filter(([key]) => key === 'headerText'),
+        ...inputEntries.filter(([key]) => key !== 'headerText' && key !== 'footerText'),
+        ...inputEntries.filter(([key]) => key === 'footerText')
+    ];
+    for (let index = 0; index < entries.length; index++) {
+        const [key, value] = entries[index];
+        if (['reels', 'images', 'image', 'posts'].includes(key)) appendCompatibility();
+        if (key === 'items' || key === 'reels') {
+            const grouped = {};
+            let nextIndex = index;
+            while (nextIndex < entries.length && ['items', 'reels'].includes(entries[nextIndex][0])) {
+                const [groupKey, groupValue] = entries[nextIndex];
+                grouped[groupKey] = groupValue;
+                nextIndex++;
+            }
+            if (Object.hasOwn(grouped, 'reels')) appendCompatibility();
+            appendField('contentItemsGroup', grouped);
+            index = nextIndex - 1;
+            continue;
+        }
+        if (!renderableKeys.has(key) || nonRenderableKeys.has(key)) continue;
+        appendField(key, value);
+    }
+
+    if (content.noDonation !== true) {
+        appendPrepared(prepareRichResponseMessageFixedOrder({ links: [], noDonation: false }));
+    }
+
+    const responseId = randomUUID();
+    const unified = {
+        response_id: responseId,
+        sections,
+        ...(embeddedScreens.length ? { embedded_screens: embeddedScreens } : {}),
+        ...(newRichMedia ? { new_rich_media: newRichMedia } : {})
+    };
+    const richResponseMessage = proto.AIRichResponseMessage.create({
+        submessages,
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: { data: Buffer.from(JSON.stringify(unified)) },
+        contextInfo: { isForwarded: true, forwardingScore: 1, forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' }, forwardOrigin: 4 }
+    });
+    const message = wrapToBotForwardedMessage(richResponseMessage, content.verificationMetadata);
+    const botMetadata = message.messageContextInfo.botMetadata;
+    Object.assign(botMetadata, mergedBotMetadata);
+    if (content.disclaimerText) botMetadata.messageDisclaimerText = content.disclaimerText;
+    botMetadata.botResponseId = responseId;
+    const { sources, mediaDetailsMetadataList } = buildAdditionalBotMetadataContext(submessages);
+    if (sources.length > 0) botMetadata.richResponseSourcesMetadata = { sources };
+    if (mediaDetailsMetadataList.length > 0) botMetadata.unifiedResponseMutation = { mediaDetailsMetadataList };
+    return message;
+};
+
+/** Merge any prepared AIRich helper into a single PLOGME response. */
+const appendPreparedRichContent = (target, prepared) => {
+    const unified = decodePreparedUnified(prepared);
+    if (unified?.sections?.length) target.sections.push(...unified.sections);
+    if (Array.isArray(unified?.embedded_screens)) {
+        target.embedded_screens = [...(target.embedded_screens || []), ...unified.embedded_screens];
+    }
+    const richResponse = prepared?.botForwardedMessage?.message?.richResponseMessage;
+    if (Array.isArray(richResponse?.submessages)) target.submessages.push(...richResponse.submessages);
+    const botMetadata = prepared?.messageContextInfo?.botMetadata;
+    if (botMetadata) Object.assign(target.botMetadata, botMetadata);
+};
+
 /**
  * Proofs are forwarded only when the caller supplies real, verifiable proofs.
  * The library never fabricates a certificate chain or signature: an unverifiable