@vanzxy/baileys 1.5.5 → 1.5.6

package/lib/Utils/MessageBuilder.js

@@ -44,7 +44,10 @@
 
 'use strict';
 
-const MESSAGE_BUILDER_VERSION = '4.9';
+const MESSAGE_BUILDER_VERSION = '4.9.1';
+// Vanz@Fix 24-08-26: use the exported builder version everywhere; the old
+// verification helper referenced an undeclared `VERSION`, making every AIRich.build() fail.
+
 
 import { generateWAMessageFromContent, prepareWAMessageMedia } from './messages.js';
 import { generateMessageIDV2 } from './generics.js';
@@ -532,10 +535,6 @@ class Toolkit {
 			}
 		});
 	}
-
-	static stringifyEscaped(obj) {
-		return JSON.stringify(obj).replace(/[\u007f-\uffff]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
-	}
 }
 
 /**
@@ -1013,6 +1012,106 @@ class Button extends BaseBuilder {
 		return this;
 	}
 
+
+	/** Native-flow `card_message` shortcut, matching this fork's prepareNativeFlowButtons(). */
+	addCardMessage(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) throw new TypeError('addCardMessage(payload) requires a plain object');
+		this._buttons.push({ name: 'card_message', buttonParamsJson: JSON.stringify(payload) });
+		return this;
+	}
+
+	/** Native-flow `order_details` shortcut. */
+	addOrderDetails(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) throw new TypeError('addOrderDetails(payload) requires a plain object');
+		this._buttons.push({ name: 'order_details', buttonParamsJson: JSON.stringify(payload) });
+		return this;
+	}
+
+	/** Native-flow `order_status` shortcut. */
+	addOrderStatus(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) throw new TypeError('addOrderStatus(payload) requires a plain object');
+		this._buttons.push({ name: 'order_status', buttonParamsJson: JSON.stringify(payload) });
+		return this;
+	}
+
+	/** Native-flow `payment_status` shortcut. */
+	addPaymentStatus(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) throw new TypeError('addPaymentStatus(payload) requires a plain object');
+		this._buttons.push({ name: 'payment_status', buttonParamsJson: JSON.stringify(payload) });
+		return this;
+	}
+
+	/** Native-flow `payment_method` shortcut. */
+	addPaymentMethod(payload = {}) {
+		if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) throw new TypeError('addPaymentMethod(payload) requires a plain object');
+		this._buttons.push({ name: 'payment_method', buttonParamsJson: JSON.stringify(payload) });
+		return this;
+	}
+
+	/** Native-flow `track_order` shortcut. */
+	addTrackOrder(id, display_text = '🚚 Track order') {
+		if (!id) throw new TypeError('addTrackOrder(id) requires a non-empty id');
+		this._buttons.push({ name: 'track_order', buttonParamsJson: JSON.stringify({ id, display_text }) });
+		return this;
+	}
+
+	/** Native-flow `reorder` shortcut. */
+	addReorder(id, display_text = '🔁 Reorder') {
+		if (!id) throw new TypeError('addReorder(id) requires a non-empty id');
+		this._buttons.push({ name: 'reorder', buttonParamsJson: JSON.stringify({ id, display_text }) });
+		return this;
+	}
+
+	/** Native-flow `cancel_order` shortcut. */
+	addCancelOrder(id, display_text = '❌ Cancel order') {
+		if (!id) throw new TypeError('addCancelOrder(id) requires a non-empty id');
+		this._buttons.push({ name: 'cancel_order', buttonParamsJson: JSON.stringify({ id, display_text }) });
+		return this;
+	}
+
+	/** Native-flow `clear_chat` shortcut. */
+	addClearChat() {
+		this._buttons.push({ name: 'clear_chat', buttonParamsJson: '{}' });
+		return this;
+	}
+
+	/** Native-flow `navigateToScreen` shortcut. */
+	addNavigateToScreen(screen, data = {}) {
+		if (!screen) throw new TypeError('addNavigateToScreen(screen) requires a non-empty screen');
+		this._buttons.push({ name: 'navigateToScreen', buttonParamsJson: JSON.stringify({ screen_name: screen, data }) });
+		return this;
+	}
+
+	/** WhatsApp Flows `flow_action` shortcut. Requires a real registered Flow. */
+	addFlow(flow = {}, display_text = '') {
+		if (typeof flow !== 'object' || flow === null || Array.isArray(flow) || !flow.id) throw new TypeError('addFlow(flow) requires a plain object with flow.id');
+		this._buttons.push({
+			name: 'flow_action',
+			buttonParamsJson: JSON.stringify({
+				flow_message_version: flow.version || '3',
+				flow_id: flow.id,
+				flow_cta: display_text || flow.cta || 'Continue',
+				flow_action: flow.action || 'navigate',
+				flow_action_payload: flow.actionPayload || { screen: flow.screen || 'WELCOME', data: flow.data || {} },
+			}),
+		});
+		return this;
+	}
+
+	/** Native-flow `voice_call` shortcut. */
+	addVoiceCall(id, display_text = '📞 Voice call') {
+		if (!id) throw new TypeError('addVoiceCall(id) requires a non-empty id');
+		this._buttons.push({ name: 'voice_call', buttonParamsJson: JSON.stringify({ display_text, id }) });
+		return this;
+	}
+
+	/** Native-flow `video_call_button` shortcut. */
+	addVideoCall(id, display_text = '🎥 Video call') {
+		if (!id) throw new TypeError('addVideoCall(id) requires a non-empty id');
+		this._buttons.push({ name: 'video_call_button', buttonParamsJson: JSON.stringify({ display_text, id }) });
+		return this;
+	}
+
 	// Vanz@Fix (bug 43) --- paramsList documented the schema for these 3 message-level native flow
 	// params (limited_time_offer / bottom_sheet / tap_target_configuration) but no helper ever wrote
 	// them into this._params — only manual setParams() could, with zero validation against the
@@ -1577,48 +1676,10 @@ class Poll extends BaseBuilder {
  * everything ChatGPT/Gemini-in-WhatsApp-style bots typically render.
  * Also exported as `AIVanzxy` / `LeafRich` / `VanzxyAI` / `VanzxyRich` (identical class, alternate names).
  */
-
-class AIRichError extends Error {
-	constructor(message, code, meta = {}) {
-		super(message);
-		this.name = 'AIRichError';
-		this.code = code;
-		Object.assign(this, meta);
-	}
-}
-
-class ItemNotFoundError extends AIRichError {
-	constructor(id, knownIds = []) {
-		super(`Item with id "${id}" not found`, 'ITEM_NOT_FOUND', { id, knownIds });
-		this.name = 'ItemNotFoundError';
-	}
-}
-
-class DuplicateIdError extends AIRichError {
-	constructor(id) {
-		super(`Id "${id}" is already in use`, 'DUPLICATE_ID', { id });
-		this.name = 'DuplicateIdError';
-	}
-}
-
-class InvalidTargetError extends AIRichError {
-	constructor(message, meta = {}) {
-		super(message, 'INVALID_TARGET', meta);
-		this.name = 'InvalidTargetError';
-	}
-}
-
-class ContentValidationError extends AIRichError {
-	constructor(message, meta = {}) {
-		super(message, 'CONTENT_VALIDATION', meta);
-		this.name = 'ContentValidationError';
-	}
-}
-
 class AIRich extends BaseBuilder {
 	#client;
 
-	constructor(client, { dynamic = true, unsupportedTypeAlert = true } = {}) {
+	constructor(client) {
 		if (!client) {
 			throw new Error('Socket is required');
 		}
@@ -1626,125 +1687,152 @@ class AIRich extends BaseBuilder {
 		super();
 		this.#client = client;
 		this._contextInfo = {};
-		this._nodes = [];
-		this._idIndex = new Map();
-		this._unsupportedTypeAlert = !!unsupportedTypeAlert;
-		this._dynamic = !!dynamic;
-		this._responseId = crypto.randomUUID();
-		this._botResponseId = crypto.randomUUID();
+		this._submessages = [];
+		this._sections = [];
+		this._richResponseSources = [];
+		// Vanz@Fix (bug 42 / inline image fallback): WA rejects rendering AIRichResponseInlineImageMetadata
+		// for third-party bots regardless of URL (confirmed empirically — Meta/WA CDN url with valid
+		// mediaKey still doesn't render, so it's a trust-chain gate, not a domain/encoding issue).
+		// Track every addInlineImage() call here so send() can fall back to a normal imageMessage.
+		this._inlineImages = [];
+
+		// Vanz@Add 24-08-26 --- ported from temen's MessageBuilderV4.7 (setResponseId/setBotResponseId
+		// below), rewritten to fit this fork's conventions. build() used to always mint a fresh
+		// crypto.randomUUID() for both unifiedResponse.response_id and botMetadata.botResponseId on
+		// every call, with no way to reuse one — so a `sendEdit()`-style flow (rebuild the same
+		// message with updated content, same response_id, so WA patches it in place instead of
+		// showing a new message) was never actually possible despite being in the gist example.
+		// null here means "not pinned yet" — build() falls back to a fresh randomUUID() same as before
+		// when neither setResponseId() nor setBotResponseId() has been called.
+		this._responseId = null;
+		this._botResponseId = null;
+
+		// Vanz@Add --- set by send()/sendEdit() after every relay so a follow-up sendEdit(), called
+		// with no args, knows which jid/message id to patch in place (matches temen's v4.7 API).
 		this._lastMessageKey = null;
-	}
-
-	loadFrom(msg) {
-		if (!msg) throw new Error('AI Rich message needed');
-
-		const message = msg.message ?? msg;
-
-		let richResponseMessage = message?.botForwardedMessage?.message?.richResponseMessage;
-
-		if (!richResponseMessage) {
-			richResponseMessage = message?.botForwardedMessage?.richResponseMessage;
-		}
-
-		if (!richResponseMessage) {
-			richResponseMessage = message?.richResponseMessage;
-		}
-
-		if (!richResponseMessage) {
-			throw new Error('richResponseMessage not found');
-		}
-
-		const messageContextInfo = message?.messageContextInfo ?? {};
-		const botMetadata = messageContextInfo?.botMetadata ?? {};
-
-		this._title = botMetadata?.messageDisclaimerText ?? '';
-
-		this._contextInfo = structuredClone(richResponseMessage?.contextInfo ?? {});
-
-		const loadedSubmessages = Array.isArray(richResponseMessage?.submessages) ? structuredClone(richResponseMessage.submessages) : [];
 
-		let loadedSections = [];
-
-		const unifiedData = richResponseMessage?.unifiedResponse?.data;
-
-		if (unifiedData) {
-			try {
-				const decoded = Buffer.from(unifiedData, 'base64').toString('utf8');
-				const unifiedResponse = JSON.parse(decoded);
-
-				if (Array.isArray(unifiedResponse?.sections)) {
-					loadedSections = structuredClone(unifiedResponse.sections);
+		// Vanz@Add (v4.9.1) --- { id, insertAt } support for every add*()/set*() call, without
+		// touching each method's own body/signature. Every add*() call ends up pushing 0-N items
+		// onto _submessages and 0-N onto _sections (some push to both, some to just one — e.g.
+		// addSuggest only touches _submessages, addSection only touches _sections). A Proxy wraps
+		// every add*/set* call: it snapshots array lengths before calling the real method, lets the
+		// method push onto the tail as it always has, then — if the caller passed { insertAt } —
+		// peels those freshly-pushed items back off the tail and re-splices them right after the
+		// last item that belongs to the block named by insertAt. Blocks are tracked by *object
+		// reference*, not saved numeric index, so earlier insertions shifting the array around never
+		// invalidates a later insertAt lookup (indexOf on the reference always finds the live position).
+		this._blocks = new Map(); // id -> { subItems: object[], secItems: object[] }
+		return new Proxy(this, {
+			get(target, prop, receiver) {
+				const orig = Reflect.get(target, prop, receiver);
+				if (typeof orig !== 'function') return orig;
+
+				// Vanz@Fix 23-08-26 (part 2) --- the add*/set* filter below only wrapped methods whose
+				// name starts with "add"/"set". Everything else (send(), build(), ...) fell through to
+				// `return orig` unwrapped, so calling e.g. `richInstance.send(...)` still invoked the
+				// real method with `this` = the Proxy (`receiver`), hitting the exact same
+				// "Cannot read private member #client..." brand-check error the add*/set* fix was for —
+				// just one level up, in send()/build() themselves. Every function property now gets
+				// bound to `target` (the real instance) at minimum; add*/set* additionally get the
+				// insertAt/id bookkeeping below.
+				if (!/^(add|set)/.test(String(prop))) {
+					return (...args) => {
+						const result = orig.apply(target, args);
+						return result === target ? receiver : result;
+					};
 				}
-			} catch {}
-		}
-
-		this._nodes = [];
-		this._idIndex = new Map();
-
-		const maxLength = Math.max(loadedSections.length, loadedSubmessages.length);
 
-		for (let i = 0; i < maxLength; i++) {
-			this._nodes.push({
-				id: null,
-				section: loadedSections[i] ?? null,
-				submessage: loadedSubmessages[i] ?? null,
-			});
-		}
-
-		this._extraPayload = {};
+				return (...args) => {
+					const opts = args.find((a) => a && typeof a === 'object' && !Array.isArray(a) && !Buffer.isBuffer(a) && ('id' in a || 'insertAt' in a));
+					const id = opts?.id;
+					const insertAt = opts?.insertAt;
+
+					const subBefore = target._submessages.length;
+					const secBefore = target._sections.length;
+
+					// Vanz@Fix 23-08-26 --- was orig.apply(receiver, args): calling the real method bound to
+					// the Proxy itself (`receiver`) makes any `this.#client` access inside throw
+					// "Cannot read private member #client from an object whose class did not declare it",
+					// because a Proxy is never the branded instance a private field was declared on —
+					// this hit every add*() that touches #client via Toolkit.resolveMedia(this.#client, ...)
+					// (addProduct/addPost/addReels/addSource, and would eventually hit addImage/addVideo
+					// too once JIT/engine specifics changed). Binding to `target` (the real instance) instead
+					// fixes it for good; `target._submessages`/`target._sections` below are unaffected since
+					// they're plain properties, and `result === target ? receiver : result` still converts a
+					// `this`-return back to the Proxy so chaining (`.addX().addY()`) keeps working.
+					const result = orig.apply(target, args);
+
+
+					const subItems = target._submessages.splice(subBefore);
+					const secItems = target._sections.splice(secBefore);
+
+					if (insertAt) {
+						const anchor = target._blocks.get(insertAt);
+						if (!anchor) throw new Error(`insertAt: no block registered with id "${insertAt}" (register it by passing { id: "${insertAt}" } on an earlier add*() call)`);
+
+						const lastSub = anchor.subItems[anchor.subItems.length - 1];
+						const subIdx = lastSub ? target._submessages.indexOf(lastSub) + 1 : target._submessages.length;
+						target._submessages.splice(subIdx, 0, ...subItems);
+
+						const lastSec = anchor.secItems[anchor.secItems.length - 1];
+						const secIdx = lastSec ? target._sections.indexOf(lastSec) + 1 : target._sections.length;
+						target._sections.splice(secIdx, 0, ...secItems);
+					} else {
+						target._submessages.push(...subItems);
+						target._sections.push(...secItems);
+					}
 
-		for (const [key, value] of Object.entries(message)) {
-			if (key !== 'messageContextInfo' && key !== 'botForwardedMessage' && key !== 'richResponseMessage') {
-				this._extraPayload[key] = structuredClone(value);
-			}
-		}
+					if (id) target._blocks.set(id, { subItems, secItems });
 
-		return this;
+					return result === target ? receiver : result;
+				};
+			},
+		});
 	}
 
-	setResponseId(id) {
-		if (typeof id !== 'string') {
-			throw new TypeError('ID must be a string');
-		}
-		this._responseId = id;
-
-		return this;
+	/** Flatten every primitive pushed into `_sections` so far into one array — lets you build a
+	 * card set in one AIRich instance and re-embed it into another via addSection(AIRich.newLayout(...)). */
+	get items() {
+		return this._sections.flatMap((s) => {
+			const vm = s?.view_model;
+			if (!vm) return [];
+			return vm.primitives ?? (vm.primitive !== undefined ? [vm.primitive] : []);
+		});
 	}
 
-	refreshResponseId() {
-		this._responseId = crypto.randomUUID();
+	/** Push a raw pre-built submessage block (escape hatch for shapes not covered by the add*() helpers). */
+	addSubmessage(submessage) {
+		const items = Array.isArray(submessage) ? submessage : [submessage];
 
-		return this;
-	}
+		for (const item of items) {
+			if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+				throw new TypeError('Submessage must be a plain object or array of plain objects');
+			}
 
-	setBotResponseId(id) {
-		if (typeof id !== 'string') {
-			throw new TypeError('ID must be a string');
+			this._submessages.push(item);
 		}
-		this._botResponseId = id;
 
 		return this;
 	}
 
-	refreshBotResponseId() {
-		this._botResponseId = crypto.randomUUID();
+	/** Push a raw pre-built section wrapper around one or more submessages. */
+	addSection(section) {
+		const items = Array.isArray(section) ? section : [section];
 
-		return this;
-	}
+		for (const item of items) {
+			if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+				throw new TypeError('Section must be a plain object or array of plain objects');
+			}
 
-	createAlert(type) {
-		if (this._unsupportedTypeAlert) {
-			return {
-				messageType: 2,
-				messageText: `[ UNSUPPORTED_TYPE - ${type}]`,
-			};
+			this._sections.push(item);
 		}
 
-		return undefined;
+		return this;
 	}
 
-	addText(text, { hyperlink = true, citation = true, latex = true, id, replace, insertAt } = {}) {
-		if (typeof text !== 'string') {
+	/** Add a text block. `[label](url)` becomes a hyperlink, `[](url)` a numbered citation, `[expr]<img-url>` a rendered latex expression — toggle each via the options. */
+	addText(text, { hyperlink = true, citation = true, latex = true } = {}) {
+		if (typeof text != 'string') {
 			throw new TypeError('Text must be a string');
 		}
 
@@ -1754,180 +1842,178 @@ class AIRich extends BaseBuilder {
 			latex,
 		});
 
-		const section = AIRich.newLayout('Single', {
-			text: extractedText,
-			...(inline_entities.length && { inline_entities }),
-			__typename: 'GenAIMarkdownTextUXPrimitive',
-		});
-
-		const submessages = [
-			{
-				messageType: 2,
-				messageText: text,
-			},
-		].filter(Boolean);
-
-		return this._addContent(section, submessages, {
-			id,
-			replace,
-			insertAt,
-		});
-	}
-
-	addFOAText(text, { id, replace, insertAt } = {}) {
-		if (typeof text !== 'string') {
-			throw new TypeError('Text must be a string');
-		}
-
-		const section = AIRich.newLayout('Single', {
-			text,
-			__typename: 'FOATextPrimitive',
+		this._submessages.push({
+			messageType: 2,
+			messageText: extractedText,
 		});
 
-		const submessages = [
-			{
-				messageType: 2,
-				messageText: text,
-			},
-		];
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				text: extractedText,
+				...(inline_entities.length && {
+					inline_entities,
+				}),
+				__typename: 'GenAIMarkdownTextUXPrimitive',
+			})
+		);
 
-		return this._addContent(section, submessages, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	addCode(language, code, { id, replace, insertAt } = {}) {
+	/** Add a syntax-highlighted code block. @param {string} language e.g. 'javascript', 'python'. */
+	addCode(language, code) {
 		if (typeof language !== 'string' || typeof code !== 'string') {
 			throw new TypeError('Language and code must be a string');
 		}
 
 		const meta = AIRich.tokenizer(code, language);
 
-		const section = AIRich.newLayout('Single', {
-			language,
-			code_blocks: meta.unified_codeBlock,
-			__typename: 'GenAICodeUXPrimitive',
+		this._submessages.push({
+			messageType: 5,
+			codeMetadata: {
+				codeLanguage: language,
+				codeBlocks: meta.codeBlock,
+			},
 		});
 
-		const submessages = [
-			{
-				messageType: 5,
-				codeMetadata: {
-					codeLanguage: language,
-					codeBlocks: meta.codeBlock,
-				},
-			},
-		];
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				language,
+				code_blocks: meta.unified_codeBlock,
+				__typename: 'GenAICodeUXPrimitive',
+			})
+		);
 
-		return this._addContent(section, submessages, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	addTable(table, { hyperlink = true, citation = true, latex = true, id, replace, insertAt } = {}) {
+	/** Add a table. @param {string[][]} table Row-major grid, first row treated as the header. */
+	addTable(table, { hyperlink = true, citation = true, latex = true } = {}) {
 		if (!Array.isArray(table)) {
 			throw new TypeError('Table must be an array');
 		}
 
-		const meta = AIRich.toTableMetadata(table, {
-			hyperlink,
-			citation,
-			latex,
-		});
+		const meta = AIRich.toTableMetadata(table, { hyperlink, citation, latex });
 
-		const section = AIRich.newLayout('Single', {
-			rows: meta.unified_rows,
-			__typename: 'GenATableUXPrimitive',
+		this._submessages.push({
+			messageType: 4,
+			tableMetadata: {
+				title: meta.title,
+				rows: meta.rows,
+			},
 		});
 
-		const submessages = [
-			{
-				messageType: 4,
-				tableMetadata: {
-					title: meta.title,
-					rows: meta.rows,
-				},
-			},
-		];
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				rows: meta.unified_rows,
+				__typename: 'GenATableUXPrimitive',
+			})
+		);
 
-		return this._addContent(section, submessages, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	addSource(sources = [], { id, replace, insertAt } = {}) {
-		if (!Array.isArray(sources)) {
-			throw new TypeError('Sources must be an array of strings, arrays, or objects');
-		}
-
-		const isStringArray = sources.every((item) => typeof item === 'string');
+	/** Add a "Sources" strip. @param {string[]|string[][]} sources Flat list of urls, or `[title, url]` pairs. */
+
+	/** Build rich-response citation/link submessages using the same shape as Baileys' `links` content shortcut. */
+	addLinks(links = []) {
+		if (!Array.isArray(links)) throw new TypeError('links must be an array');
+		links.forEach((linkField, index) => {
+			if (!linkField || typeof linkField !== 'object') throw new TypeError('Each link must be an object');
+			const prefix = 'SS_' + index;
+			const url = linkField.url || '';
+			const text = String(linkField.text ?? '');
+			const sources = Array.isArray(linkField.sources) ? linkField.sources.map((sourceField) => ({
+				source_type: 'THIRD_PARTY',
+				source_display_name: sourceField?.displayName || sourceField?.title || 'Source',
+				source_subtitle: sourceField?.subtitle || '',
+				source_url: sourceField?.url || url,
+			})) : [];
+			const entity = {
+				key: prefix,
+				metadata: {
+					reference_id: index + 1,
+					reference_url: url,
+					reference_title: linkField.title || 'Source',
+					reference_display_name: linkField.displayName || linkField.title || 'Source',
+					sources,
+					__typename: 'GenAISearchCitationItem',
+				},
+			};
+			const section = AIRich.newLayout('Single', {
+				text: `${text} {{${prefix}}}${url}{{/${prefix}}}`,
+				inline_entities: [entity],
+				__typename: 'GenAIMarkdownTextUXPrimitive',
+			});
+			this._sections.push(section);
+			this._submessages.push({
+				messageType: 2,
+				messageText: `${text} {{${prefix}}}¹{{/${prefix}}} `,
+				inlineEntities: [entity],
+			});
+		});
+		return this;
+	}
 
-		const isArrayFormat = sources.every((item) => Array.isArray(item) && item.every((value) => typeof value === 'string'));
+	/** Add a raw rich-response content-items carousel, matching Baileys' `items` field. */
+	addContentItems(items = []) {
+		if (!Array.isArray(items)) throw new TypeError('items must be an array');
+		this._submessages.push({
+			messageType: 9,
+			contentItemsMetadata: { itemsMetadata: items, contentType: 1 },
+		});
+		this._sections.push(AIRich.newLayout('Single', {
+			items,
+			content_type: 1,
+			__typename: 'GenAIContentItemsUXPrimitive',
+		}));
+		return this;
+	}
 
-		const isObjectFormat = sources.every((item) => item && typeof item === 'object' && !Array.isArray(item));
+	/** Add Baileys-compatible inline-video marker. WhatsApp's current rich-response helper carries this as a text marker. */
+	addInlineVideo() {
+		this._submessages.push({ messageType: 2, messageText: 'INLINE_VIDEO' });
+		this._sections.push(AIRich.newLayout('Single', {
+			text: 'INLINE_VIDEO',
+			__typename: 'GenAIMarkdownTextUXPrimitive',
+		}));
+		return this;
+	}
 
-		if (!isStringArray && !isArrayFormat && !isObjectFormat) {
-			throw new TypeError('Sources must be a string array, array of string arrays, or array of objects');
+	addSource(sources = [], { resolveUrl = false } = {}) {
+		if (!(Array.isArray(sources) && (sources.every((item) => typeof item === 'string') || sources.every((item) => Array.isArray(item) && item.every((v) => typeof v === 'string'))))) {
+			throw new TypeError('Sources must be a string array or an array of string arrays');
 		}
 
-		if (isStringArray) {
+		if (sources.every((item) => typeof item === 'string')) {
 			sources = [sources];
 		}
 
-		const normalizedSources = sources.map((source) => {
-			if (Array.isArray(source)) {
-				const [icon, url, title, subtitle] = source;
-
-				return {
-					icon,
-					url,
-					title,
-					subtitle,
-				};
-			}
-
-			return {
-				icon: source.favicon ?? source.icon ?? '',
-				url: source.url ?? '',
-				title: source.title ?? '',
-				subtitle: source.subtitle ?? '',
-			};
-		});
-
-		const source = normalizedSources.map(({ icon, url, title, subtitle }) => ({
+		const source = sources.map(([icon, url, text]) => ({
 			source_type: 'THIRD_PARTY',
-			source_display_name: title,
-			source_subtitle: subtitle,
-			source_url: url,
+			source_display_name: text ?? '',
+			source_subtitle: 'AI',
+			source_url: url ?? '',
 			favicon: {
-				url: Toolkit.resolveMedia(this.#client, icon, 'image'),
+				url: Toolkit.resolveMedia(this.#client, icon ?? '', 'image', { resolveUrl }),
 				mime_type: 'image/jpeg',
 				width: 16,
 				height: 16,
 			},
 		}));
 
-		const submessage = this.createAlert('GenAISearchResultPrimitive');
-
-		const section = AIRich.newLayout('Single', {
-			sources: source,
-			__typename: 'GenAISearchResultPrimitive',
-		});
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				sources: source,
+				__typename: 'GenAISearchResultPrimitive',
+			})
+		);
 
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	addReels(reelsItems = [], { id, replace, insertAt } = {}) {
+	/** Add a horizontally-scrollable reel of image/video items. */
+	addReels(reelsItems = [], { resolveUrl = false } = {}) {
 		if (
 			!(
 				(reelsItems && typeof reelsItems === 'object' && !Array.isArray(reelsItems)) ||
@@ -1937,64 +2023,88 @@ class AIRich extends BaseBuilder {
 			throw new TypeError('Reels items must be an object or an array of objects');
 		}
 
-		const items = Array.isArray(reelsItems) ? reelsItems : [reelsItems];
+		if (!Array.isArray(reelsItems)) {
+			reelsItems = [reelsItems];
+		}
 
-		const reels = items.map((item) => ({
+		const reels = reelsItems.map((item) => ({
 			...item,
-			_avatar: Toolkit.resolveMedia(this.#client, item.profileIconUrl ?? item.profile_url ?? item.profile ?? '', 'image'),
-			_thumbnail: Toolkit.resolveMedia(this.#client, item.thumbnailUrl ?? item.thumbnail ?? '', 'image'),
+			_avatar: Toolkit.resolveMedia(this.#client, item.profileIconUrl ?? item.profile_url ?? item.profile ?? '', 'image', { resolveUrl }),
+			_thumbnail: Toolkit.resolveMedia(this.#client, item.thumbnailUrl ?? item.thumbnail ?? '', 'image', { resolveUrl }),
 		}));
 
-		const section = AIRich.newLayout(
-			'HScroll',
-			reels.map((item) => ({
-				reels_url: item.videoUrl ?? item.url ?? '',
-				thumbnail_url: item._thumbnail,
-				creator: item.username ?? item.title ?? '',
-				avatar_url: item._avatar,
-				reels_title: item.reels_title ?? item.title ?? '',
-				likes_count: item.likes_count ?? item.like ?? 0,
-				shares_count: item.shares_count ?? item.share ?? 0,
-				view_count: item.view_count ?? item.view ?? 0,
-				reel_source: item.reel_source ?? item.source ?? 'IG',
-				is_verified: !!(item.is_verified || item.verified),
-				__typename: 'GenAIReelPrimitive',
-			}))
-		);
-
-		const submessages = [
-			{
-				messageType: 9,
-				contentItemsMetadata: {
-					contentType: 1,
-					itemsMetadata: reels.map((item) => ({
-						reelItem: {
-							title: item.username ?? '',
-							profileIconUrl: item._avatar,
-							thumbnailUrl: item._thumbnail,
-							videoUrl: item.videoUrl ?? item.url ?? '',
-						},
-					})),
-				},
+		this._submessages.push({
+			messageType: 9,
+			contentItemsMetadata: {
+				contentType: 1,
+				itemsMetadata: reels.map((item) => ({
+					reelItem: {
+						title: item.username ?? '',
+						profileIconUrl: item._avatar,
+						thumbnailUrl: item._thumbnail,
+						videoUrl: item.videoUrl ?? item.url ?? '',
+					},
+				})),
 			},
-		];
+		});
 
-		return this._addContent(section, submessages, {
-			id,
-			replace,
-			insertAt,
+		reels.forEach((item, idx) => {
+			this._richResponseSources.push({
+				provider: 'Evernight AI',
+				thumbnailCDNURL: item._thumbnail,
+				sourceProviderURL: item.videoUrl ?? item.url ?? '',
+				sourceQuery: '',
+				faviconCDNURL: item._avatar,
+				citationNumber: idx + 1,
+				sourceTitle: item.username ?? '',
+			});
 		});
+
+		this._sections.push(
+			AIRich.newLayout(
+				'HScroll',
+				reels.map((item) => ({
+					reels_url: item.videoUrl ?? item.url ?? '',
+					thumbnail_url: item._thumbnail,
+					creator: item.username ?? item.title ?? '',
+					avatar_url: item._avatar,
+					reels_title: item.reels_title ?? item.title ?? '',
+					likes_count: item.likes_count ?? item.like ?? 0,
+					shares_count: item.shares_count ?? item.share ?? 0,
+					view_count: item.view_count ?? item.view ?? 0,
+					reel_source: item.reel_source ?? item.source ?? 'IG',
+					is_verified: !!(item.is_verified || item.verified),
+					__typename: 'GenAIReelPrimitive',
+				}))
+			)
+		);
+
+		return this;
 	}
 
-	addImage(imageUrl, { width, height, status = 'READY', update_text, resolveUrl = false, id, replace, insertAt } = {}) {
+	/** Add a full-width image (or grid of images if `imageUrl` is an array). */
+	/**
+	 * @param {{ resolveUrl?: boolean, instant?: boolean|'only' }} [options]
+	 * `instant: true` — sends BOTH: the GRID_IMAGE card (still shows WA's "can't verify"
+	 *   forwarded-download prompt, unavoidable per-design of botForwardedMessage) AND a plain
+	 *   (non-forwarded) imageMessage via send()'s inline-image fallback queue (`_inlineImages`,
+	 *   shared with addInlineImage()) that renders instantly with no prompt. Two images, by design.
+	 * `instant: 'only'` — Vanz@Add (v4.9.2): skips building the GRID_IMAGE card entirely (no
+	 *   submessage, no GenAIImaginePrimitive section) and queues ONLY the plain imageMessage.
+	 *   One image, no prompt, nothing to download — use this when you don't need the rich card,
+	 *   just the picture to show up immediately.
+	 */
+	addImage(imageUrl, { resolveUrl = false, instant = false } = {}) {
 		if (!(typeof imageUrl === 'string' || Buffer.isBuffer(imageUrl) || (Array.isArray(imageUrl) && imageUrl.every((v) => typeof v === 'string' || Buffer.isBuffer(v))))) {
 			throw new TypeError('imageUrl must be string | buffer | array of string/buffer');
 		}
+		if (instant !== false && instant !== true && instant !== 'only') {
+			throw new TypeError(`instant must be false, true, or 'only' — got ${JSON.stringify(instant)}`);
+		}
 
 		const list = Array.isArray(imageUrl)
 			? imageUrl.map((v) => {
 					const url = Toolkit.resolveMedia(this.#client, v, 'image', { resolveUrl });
-
 					return {
 						imagePreviewUrl: url,
 						imageHighResUrl: url,
@@ -2003,7 +2113,6 @@ class AIRich extends BaseBuilder {
 				})
 			: (() => {
 					const url = Toolkit.resolveMedia(this.#client, imageUrl, 'image', { resolveUrl });
-
 					return [
 						{
 							imagePreviewUrl: url,
@@ -2013,48 +2122,117 @@ class AIRich extends BaseBuilder {
 					];
 				})();
 
-		const sections = list.map(({ imagePreviewUrl }) =>
-			AIRich.newLayout('Single', {
-				media: {
-					url: imagePreviewUrl,
-					mime_type: 'image/png',
-					width,
-					height,
-				},
-				imagine_type: 'IMAGE',
-				status: {
-					status,
-					update_text,
-				},
-				__typename: 'GenAIImaginePrimitive',
-			})
-		);
+		const buildCard = instant !== 'only';
 
-		const submessage = {
-			messageType: 1,
-			gridImageMetadata: {
-				gridImageUrl: {
-					imagePreviewUrl: list[0]?.imagePreviewUrl,
+		if (buildCard) {
+			this._submessages.push({
+				messageType: 1,
+				gridImageMetadata: {
+					gridImageUrl: {
+						imagePreviewUrl: list[0]?.imagePreviewUrl,
+					},
+					imageUrls: list,
 				},
-				imageUrls: list,
-			},
-		};
-
-		if (id && sections.length !== 1) {
-			throw new Error('Cannot assign one id to multiple image sections');
+			});
 		}
 
-		return this._addContent(sections, submessage, {
-			id,
-			replace,
-			insertAt,
+		list.forEach(({ imagePreviewUrl }) => {
+			if (buildCard) {
+				this._sections.push(
+					AIRich.newLayout('Single', {
+						media: {
+							url: imagePreviewUrl,
+							mime_type: 'image/png',
+						},
+						imagine_type: 'IMAGE',
+						status: { status: 'READY' },
+						__typename: 'GenAIImaginePrimitive',
+					})
+				);
+			}
+
+			if (instant) {
+				this._inlineImages.push({ url: imagePreviewUrl, caption: undefined });
+			}
 		});
+
+		return this;
 	}
 
-	addVideo(videoUrl, { autoFill = true, status = 'READY', estimatedTime, id, replace, insertAt } = {}) {
-		const isObjectVideo = (v) => v && typeof v === 'object' && !Array.isArray(v) && v.url;
+	// Vanz@Fix 15-08-26 (bug 41) --- addImage() only builds GRID_IMAGE (messageType 1).
+	// There was no helper for standalone INLINE_IMAGE (messageType 3): callers were manually
+	// pushing addSubmessage() (correct proto shape) + addSection() (WRONG shape — reused the
+	// GRID_IMAGE/GenAIImaginePrimitive section schema instead of GenAIInlineImageUXPrimitive),
+	// which broke client-side unifiedResponse rendering even though the submessage itself was fine.
+	// Mirrors RichSubMessageType.INLINE_IMAGE handling in rich-message-utils.js's toUnified().
+	/** Add an image inline with the surrounding text flow (falls back to a plain imageMessage on send() if the client can't render inline images — see skipImageFallback). */
+	addInlineImage(imageUrl, { text = '', alignment = 'center', tapLinkUrl = '', resolveUrl = false } = {}) {
+		if (!(typeof imageUrl === 'string' || Buffer.isBuffer(imageUrl) || (imageUrl && typeof imageUrl === 'object'))) {
+			throw new TypeError('imageUrl must be string | buffer | { imagePreviewUrl, imageHighResUrl, sourceUrl }');
+		}
+
+		const ALIGNMENT_ENUM = { leading: 0, trailing: 1, center: 2 };
+		const ALIGNMENT_NAME = ['AI_RICH_RESPONSE_IMAGE_LAYOUT_LEADING_ALIGNED', 'AI_RICH_RESPONSE_IMAGE_LAYOUT_TRAILING_ALIGNED', 'AI_RICH_RESPONSE_IMAGE_LAYOUT_CENTER_ALIGNED'];
+		const alignmentNum = typeof alignment === 'number' ? alignment : (ALIGNMENT_ENUM[String(alignment).toLowerCase()] ?? ALIGNMENT_ENUM.center);
+
+		const url =
+			imageUrl && typeof imageUrl === 'object'
+				? {
+						imagePreviewUrl: imageUrl.imagePreviewUrl || imageUrl.url,
+						imageHighResUrl: imageUrl.imageHighResUrl || imageUrl.url,
+						sourceUrl: imageUrl.sourceUrl || imageUrl.url,
+					}
+				: (() => {
+						const resolved = Toolkit.resolveMedia(this.#client, imageUrl, 'image', { resolveUrl });
+						return { imagePreviewUrl: resolved, imageHighResUrl: resolved, sourceUrl: resolved };
+					})();
+
+		this._submessages.push({
+			messageType: 3,
+			imageMetadata: {
+				imageUrl: url,
+				imageText: text,
+				alignment: alignmentNum,
+				tapLinkUrl,
+			},
+		});
 
-		const isValidPrimitive =
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				image_url: {
+					image_preview_url: url.imagePreviewUrl || '',
+					image_high_res_url: url.imageHighResUrl || '',
+					source_url: url.sourceUrl || '',
+				},
+				image_text: text,
+				alignment: ALIGNMENT_NAME[alignmentNum],
+				tap_link_url: tapLinkUrl,
+				__typename: 'GenAIInlineImageUXPrimitive',
+			})
+		);
+
+		// Vanz@Fix (bug 42): stash for the imageMessage fallback in send()
+		this._inlineImages.push({
+			url: url.sourceUrl || url.imageHighResUrl || url.imagePreviewUrl,
+			caption: text || undefined,
+		});
+
+		return this;
+	}
+
+	// Vanz@Perf 15-08-26 --- autoFill defaults to false (arslan-baileys behavior): skips the
+	// fetch-full-video + ffmpeg-frame-extraction + duration-parse round trip per video, which
+	// was the main source of blurose's slower response time. Pass { autoFill: true } to opt
+	// back into the complete/slow path (real thumbnail + duration + file_length).
+	// Vanz@Fix 23-08-26 --- addVideo() had no resolveUrl option at all (unlike addImage()), so the
+	// video url always stayed a raw external link, which stock WA clients show a "download" state
+	// for before rendering. Mirrors addImage()'s { resolveUrl } — when true, the url is uploaded to
+	// WA's own media server first via Toolkit.toUrl() so it renders instantly like WA-native media.
+	/** Add a video block. */
+	addVideo(videoUrl, { autoFill = false, resolveUrl = false } = {}) {
+		const isObjectVideo = (v) => v && typeof v === 'object' && v.url;
+
+		const isValidPrimitive =
 			typeof videoUrl === 'string' ||
 			Buffer.isBuffer(videoUrl) ||
 			isObjectVideo(videoUrl) ||
@@ -2066,15 +2244,17 @@ class AIRich extends BaseBuilder {
 
 		const items = Array.isArray(videoUrl) ? videoUrl : [videoUrl];
 
-		const alert = this.createAlert('GenAIImaginePrimitive (ANIMATE)');
-
-		const sections = [];
-		const submessages = [];
+		this._submessages.push({
+			messageType: 2,
+			messageText: '[ Video tidak dapat dimuat ]',
+		});
 
-		for (const item of items) {
+		items.forEach((item) => {
 			const isObject = isObjectVideo(item);
 
-			const url = isObject ? Toolkit.resolveMedia(this.#client, item.url ?? '', 'video') : Toolkit.resolveMedia(this.#client, item, 'video');
+			const url = isObject
+				? Toolkit.resolveMedia(this.#client, item.url ?? '', 'video', { resolveUrl })
+				: Toolkit.resolveMedia(this.#client, item, 'video', { resolveUrl });
 
 			const bufferPromise = autoFill ? Promise.resolve(url).then((u) => Toolkit.fetchBuffer(u)) : null;
 
@@ -2100,15 +2280,17 @@ class AIRich extends BaseBuilder {
 							height: 300,
 						})
 					: autoFill
-						? bufferPromise?.then((b) =>
-								Toolkit.getMp4Preview(b, {
-									time: 0,
-									result: 'base64',
-								})
-							)
+						? bufferPromise
+							? bufferPromise.then((b) =>
+									Toolkit.getMp4Preview(b, {
+										time: 0,
+										result: 'base64',
+									})
+								)
+							: null
 						: null;
 
-			sections.push(
+			this._sections.push(
 				AIRich.newLayout('Single', {
 					media: {
 						url,
@@ -2117,38 +2299,35 @@ class AIRich extends BaseBuilder {
 						duration,
 					},
 					imagine_type: 'ANIMATE',
-					status: {
-						status,
-						estimated_completion_time: estimatedTime != null ? Math.floor((Date.now() + estimatedTime) / 1000) : undefined,
-					},
+					status: { status: 'READY' },
 					thumbnail: {
 						raw_media: thumbnail,
 					},
 					__typename: 'GenAIImaginePrimitive',
 				})
 			);
-		}
-
-		if (alert !== undefined) {
-			submessages.push(alert);
-		}
-
-		if (submessages.length > 1) {
-			throw new Error('Video content can only have one submessage');
-		}
-
-		return this._addContent(sections, submessages[0], {
-			id,
-			replace,
-			insertAt,
 		});
+
+		return this;
 	}
 
-	addProduct(data = {}, { id, replace, insertAt } = {}) {
+	/** Add an inline product card (or array of cards). Each item needs at least a `title`. */
+	addProduct(data = {}, { resolveUrl = false } = {}) {
 		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
 			throw new TypeError('Product items must be an object or an array of objects');
 		}
 
+		const itemsToCheck = Array.isArray(data) ? data : [data];
+		const missingTitleAt = itemsToCheck.findIndex((item) => !item.title);
+		if (missingTitleAt !== -1) {
+			throw new TypeError(`addProduct() item[${missingTitleAt}] is missing a required "title"`);
+		}
+
+		this._submessages.push({
+			messageType: 2,
+			messageText: '[ Produk tidak dapat dimuat ]',
+		});
+
 		const items = Array.isArray(data) ? data : [data];
 
 		const product = items.map((item) => ({
@@ -2158,41 +2337,41 @@ class AIRich extends BaseBuilder {
 			sale_price: item.sale_price,
 			product_url: item.product_url ?? item.url,
 			image: {
-				url: Toolkit.resolveMedia(this.#client, item.image_url ?? item.image, 'image'),
+				url: Toolkit.resolveMedia(this.#client, item.image_url ?? item.image, 'image', { resolveUrl }),
 			},
 			additional_images: [
 				{
-					url: Toolkit.resolveMedia(this.#client, item.icon_url ?? item.icon, 'image'),
+					url: Toolkit.resolveMedia(this.#client, item.icon_url ?? item.icon, 'image', { resolveUrl }),
 				},
 			],
 			__typename: 'GenAIProductItemCardPrimitive',
 		}));
 
-		const section = AIRich.newLayout(Array.isArray(data) ? 'HScroll' : 'Single', Array.isArray(data) ? product : product[0]);
+		this._sections.push(AIRich.newLayout(Array.isArray(data) ? 'HScroll' : 'Single', Array.isArray(data) ? product : product[0]));
 
-		const submessage = this.createAlert('GenAIProductItemCardPrimitive');
-
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	addPost(data = {}, { id, replace, insertAt } = {}) {
+	/** Add an inline social-post style card (or array of cards). */
+	addPost(data = {}, { resolveUrl = false } = {}) {
 		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
 			throw new TypeError('Post items must be an object or an array of objects');
 		}
 
 		const posts = Array.isArray(data) ? data : [data];
 
+		this._submessages.push({
+			messageType: 2,
+			messageText: '[ Postingan tidak dapat dimuat ]',
+		});
+
 		const primitives = posts.map((p) => ({
 			title: p.title ?? '',
 			subtitle: p.subtitle ?? '',
 			username: p.username ?? '',
-			profile_picture_url: Toolkit.resolveMedia(this.#client, p.profile_picture_url ?? p.profile_url ?? p.profile ?? '', 'image'),
+			profile_picture_url: Toolkit.resolveMedia(this.#client, p.profile_picture_url ?? p.profile_url ?? p.profile ?? '', 'image', { resolveUrl }),
 			is_verified: !!(p.is_verified || p.verified),
-			thumbnail_url: Toolkit.resolveMedia(this.#client, p.thumbnail_url ?? p.thumbnail ?? '', 'image'),
+			thumbnail_url: Toolkit.resolveMedia(this.#client, p.thumbnail_url ?? p.thumbnail ?? '', 'image', { resolveUrl }),
 			post_caption: p.post_caption ?? p.caption ?? '',
 			likes_count: p.likes_count ?? p.like ?? 0,
 			comments_count: p.comments_count ?? p.comment ?? 0,
@@ -2201,151 +2380,419 @@ class AIRich extends BaseBuilder {
 			post_deeplink: p.post_deeplink ?? p.deeplink ?? '',
 			source_app: p.source_app || p.source || 'INSTAGRAM',
 			footer_label: p.footer_label ?? p.footer ?? '',
-			footer_icon: Toolkit.resolveMedia(this.#client, p.footer_icon ?? p.icon ?? '', 'image'),
+			footer_icon: Toolkit.resolveMedia(this.#client, p.footer_icon ?? p.icon ?? '', 'image', { resolveUrl }),
 			is_carousel: posts.length > 1,
 			orientation: p.orientation ?? 'LANDSCAPE',
 			post_type: p.post_type ?? 'VIDEO',
 			__typename: 'GenAIPostPrimitive',
 		}));
 
-		const section = AIRich.newLayout('HScroll', primitives);
+		this._sections.push(AIRich.newLayout('HScroll', primitives));
 
-		const submessage = this.createAlert('GenAIPostPrimitive');
+		return this;
+	}
 
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
-		});
+	// Vanz@Add 24-08-26 --- ported from temen's MessageBuilderV4.7 (setResponseId/setBotResponseId/
+	// refreshResponseId/refreshBotResponseId), rewritten for this fork. Pins the two ids build()
+	// generates (see constructor comment) so a rebuilt message can reuse the same response_id/
+	// botResponseId — needed for editing an already-sent AIRich message in place.
+
+	/** Pin `unifiedResponse.response_id` to a specific value instead of a fresh random one each build() — needed to re-send an edited version of an already-sent message in place. */
+	setResponseId(id) {
+		if (typeof id !== 'string' || !id) throw new TypeError('setResponseId(id) requires a non-empty string');
+		this._responseId = id;
+		return this;
 	}
 
-	addMetadata(text, { id, replace, insertAt } = {}) {
-		if (typeof text !== 'string') {
-			throw new TypeError('Text must be a string');
-		}
+	/** Un-pin `unifiedResponse.response_id`, generating a fresh crypto.randomUUID() immediately (not deferred to the next build()). */
+	refreshResponseId() {
+		this._responseId = crypto.randomUUID();
+		return this;
+	}
 
-		const section = AIRich.newLayout('Single', {
-			text,
-			__typename: 'GenAIMetadataTextPrimitive',
-		});
+	/** Pin `botMetadata.botResponseId` to a specific value instead of a fresh random one each build(). */
+	setBotResponseId(id) {
+		if (typeof id !== 'string' || !id) throw new TypeError('setBotResponseId(id) requires a non-empty string');
+		this._botResponseId = id;
+		return this;
+	}
+
+	/** Un-pin `botMetadata.botResponseId`, generating a fresh crypto.randomUUID() immediately. */
+	refreshBotResponseId() {
+		this._botResponseId = crypto.randomUUID();
+		return this;
+	}
+
+	/** Add a small metadata-style text line (`GenAIMetadataTextPrimitive`) — same visual style as the auto-appended footer/`addTip()`'s callout, but insertable anywhere and without `addTip()`'s icon prefix. */
+	addMetadata(text) {
+		if (typeof text !== 'string' || !text) throw new TypeError('addMetadata(text) requires a non-empty string');
 
-		const submessage = {
+		this._submessages.push({
 			messageType: 2,
 			messageText: text,
-		};
-
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
 		});
+
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				text,
+				__typename: 'GenAIMetadataTextPrimitive',
+			})
+		);
+
+		return this;
 	}
 
-	addTip(text, { id, replace, insertAt } = {}) {
-		if (typeof text !== 'string') {
-			throw new TypeError('Text must be a string');
+	/** Add a small "tip" callout banner. @param {string} text */
+	addTip(text) {
+		if (typeof text !== 'string' || !text) {
+			throw new TypeError('addTip(text) requires a non-empty string');
 		}
 
-		const section = AIRich.newLayout('Single', {
-			text: 'ⓘ ' + text,
-			__typename: 'GenAIMetadataTextPrimitive',
-		});
-
-		const submessage = {
+		this._submessages.push({
 			messageType: 2,
 			messageText: text,
-		};
-
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
 		});
+
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				text,
+				__typename: 'GenAIMetadataTextPrimitive',
+			})
+		);
+
+		return this;
 	}
 
-	addWidget(data, { layout, id, replace, insertAt, ...options } = {}) {
-		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
-			throw new TypeError('Widget must be an object or an array of objects');
+	// Vanz@Add 22-08-26 (v4.7) --- addHeading/addImageCard/addWidget/addFooterAction: 4 primitives
+	// reverse-engineered from captured Meta-AI-in-WhatsApp traffic that this project's own crm/snip
+	// tooling (see rich-message-utils.js) dumps for study. Not in any public Baileys schema, so
+	// unknown enum values (kind/state on addWidget's ctas) are passed through as observed rather
+	// than guessed at, and documented as experimental below.
+
+	/** Add a large heading-style text block (`FOATextPrimitive`) — visually distinct from `addText()`'s regular paragraph text. */
+	addHeading(text) {
+		if (typeof text !== 'string' || !text) {
+			throw new TypeError('addHeading(text) requires a non-empty string');
 		}
 
-		const isArray = Array.isArray(data);
+		this._submessages.push({
+			messageType: 2,
+			messageText: text,
+		});
 
-		const items = isArray ? data : [data];
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				text,
+				__typename: 'FOATextPrimitive',
+			})
+		);
 
-		const widgets = items.map((item) => ({
-			__typename: 'GenAI3PExtWidgetPrimitive',
+		return this;
+	}
 
-			header: {
-				__typename: 'GenAI3PExtWidgetStandardHeader',
-				title: item.title ?? '',
-				...(item.header ?? {}),
-			},
+	/**
+	 * Add a "ready" static image card (`GenAIImagePrimitive`: preview + full-res, no generating/status
+	 * state) — distinct from `addImage()`'s AI-generation-style `GenAIImaginePrimitive`.
+	 * @param {string|Buffer} previewUrl Preview/thumbnail image.
+	 * @param {string|Buffer} [fullUrl] Full-resolution image; defaults to `previewUrl`.
+	 */
+	addImageCard(previewUrl, fullUrl = previewUrl, { resolveUrl = false } = {}) {
+		if (!(typeof previewUrl === 'string' || Buffer.isBuffer(previewUrl))) {
+			throw new TypeError('addImageCard(previewUrl) requires a string url or buffer');
+		}
 
-			body: {
-				__typename: 'GenAI3PExtCalendarEventList',
-				sections: item.sections ?? [],
-
-				ctas: (item.actions ?? []).map((action) => ({
-					__typename: 'GenAI3PExtWidgetCTA',
-					label: action.label ?? '',
-					state: action.state ?? 'PENDING',
-					kind: action.kind ?? 'OTHER',
-					tool_call_id: action.tool_call_id ?? action.id ?? '',
-
-					...(action.toast && {
-						toast: {
-							__typename: 'GenAI3PExtWidgetToast',
-							label: action.toast.label ?? action.label ?? '',
-						},
-					}),
-				})),
+		const preview = Toolkit.resolveMedia(this.#client, previewUrl, 'image', { resolveUrl });
+		const full = fullUrl === previewUrl ? preview : Toolkit.resolveMedia(this.#client, fullUrl, 'image', { resolveUrl });
 
-				...(item.body ?? {}),
+		this._submessages.push({
+			messageType: 1,
+			gridImageMetadata: {
+				gridImageUrl: { imagePreviewUrl: preview },
+				imageUrls: [{ imagePreviewUrl: preview, imageHighResUrl: full, sourceUrl: full }],
 			},
-		}));
+		});
 
-		const section = AIRich.newLayout(layout ?? (isArray ? 'HScroll' : 'Single'), isArray ? widgets : widgets[0], options);
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				preview_image: { url: preview, mime_type: 'image/jpeg', __typename: 'GenAIMediaItem' },
+				full_image: { url: full, mime_type: 'image/jpeg', __typename: 'GenAIMediaItem' },
+				__typename: 'GenAIImagePrimitive',
+			})
+		);
 
-		const submessage = this.createAlert('GenAI3PExtWidgetStandardHeader');
+		return this;
+	}
 
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
+	/**
+	 * Add a "3P extension" widget card (`GenAI3PExtWidgetPrimitive`) — a small panel with a title and
+	 * a row of tappable CTA chips. Per captured traffic these CTAs call back into a tool (`tool_call_id`)
+	 * rather than opening a url; `kind`/`state` semantics beyond the observed `'OTHER'`/`'PENDING'`
+	 * defaults aren't publicly documented, so treat this as experimental.
+	 *
+	 * Vanz@Add (v4.8) --- accepts an `{ layout }` override so consecutive `addWidget()` calls can
+	 * pick different renderings (e.g. one `HScroll` row, one `ActionRow` stack) instead of always
+	 * inferring HScroll-for-array/Single-for-object from the shape of `data`. Also accepts either
+	 * `ctas` (original key, matches the wire field) or `actions` (alias) on each item — whichever
+	 * is present is used; `ctas` wins if both are somehow given.
+	 * @param {Record<string, any>|Record<string, any>[]} data `{ title, ctas|actions: [{ label, tool_call_id?, kind?, state?, toast? }] }` (single or array).
+	 * @param {{layout?: 'Single'|'HScroll'|'ActionRow'|string}} [options] `layout` overrides the default single/array inference.
+	 */
+	addWidget(data = {}, { layout } = {}) {
+		const items = Array.isArray(data) ? data : [data];
+
+		items.forEach((item, i) => {
+			if (!item?.title) {
+				throw new TypeError(`addWidget() item[${i}] is missing a required "title"`);
+			}
+			const ctas = item.ctas ?? item.actions;
+			if (!Array.isArray(ctas) || !ctas.length) {
+				throw new TypeError(`addWidget() item[${i}] requires a non-empty "ctas" (or "actions") array`);
+			}
 		});
-	}
 
-	addFooterAction(data, { layout, id, replace, insertAt, ...options } = {}) {
-		if (!((data && typeof data === 'object' && !Array.isArray(data)) || (Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item))))) {
-			throw new TypeError('Footer action must be an object or an array of objects');
-		}
+		this._submessages.push({
+			messageType: 2,
+			messageText: items.map((item) => item.title).join(', '),
+		});
+
+		const widgets = items.map((item) => {
+			const ctas = item.ctas ?? item.actions;
+			return {
+				header: { title: item.title, __typename: 'GenAI3PExtWidgetStandardHeader' },
+				body: {
+					sections: item.sections ?? [],
+					ctas: ctas.map((cta, idx) => ({
+						label: cta.label ?? '',
+						state: cta.state ?? 'PENDING',
+						kind: cta.kind ?? 'OTHER',
+						tool_call_id: cta.tool_call_id ?? String(idx).padStart(2, '0'),
+						...(cta.toast !== false && {
+							toast: { label: typeof cta.toast === 'string' ? cta.toast : item.title, __typename: 'GenAI3PExtWidgetToast' },
+						}),
+						__typename: 'GenAI3PExtWidgetCTA',
+					})),
+					__typename: item.body_typename ?? 'GenAI3PExtCalendarEventList',
+				},
+				__typename: 'GenAI3PExtWidgetPrimitive',
+			};
+		});
 
-		const isArray = Array.isArray(data);
+		const resolvedLayout = layout ?? (Array.isArray(data) ? 'HScroll' : 'Single');
+		const asArray = resolvedLayout !== 'Single';
 
-		const items = isArray ? data : [data];
+		this._sections.push(AIRich.newLayout(resolvedLayout, asArray ? widgets : widgets[0]));
 
-		const actions = items.map((item) => ({
-			__typename: 'GenAIFooterActionPrimitive',
+		return this;
+	}
 
-			cta_text: item.text ?? item.cta_text ?? '',
+	/**
+	 * Add footer action link(s) (`GenAIFooterActionPrimitive`) — e.g. "Join our WhatsApp Group/Channel"
+	 * chips shown below the response, separate from `setFooter()`'s plain text footer.
+	 * @param {{text: string, url: string, type?: string}|{text: string, url: string, type?: string}[]} actions
+	 */
+	addFooterAction(actions) {
+		const items = Array.isArray(actions) ? actions : [actions];
 
-			cta_type: item.type ?? item.cta_type ?? 'OPEN_URL',
+		items.forEach((item, i) => {
+			if (!item?.text || !item?.url) {
+				throw new TypeError(`addFooterAction() item[${i}] requires both "text" and "url"`);
+			}
+		});
 
-			cta_url: item.url ?? item.cta_url ?? '',
+		const primitives = items.map((item) => ({
+			cta_text: item.text,
+			cta_type: item.type ?? 'OPEN_URL',
+			cta_url: item.url,
+			__typename: 'GenAIFooterActionPrimitive',
 		}));
 
-		const section = AIRich.newLayout(layout ?? (isArray ? 'HScroll' : 'Single'), isArray ? actions : actions[0], options);
+		this._sections.push(AIRich.newLayout('HScroll', primitives));
 
-		const submessage = this.createAlert('GenAIFooterActionPrimitive');
+		return this;
+	}
+
+	// Vanz@Add (v4.8) --- 8 primitives from the 20-item reference test script that had no
+	// add*() helper yet (Divider/Spacer/Task/ProgressStatus/ThinkingStatus/QuotaUpsell/FOABloks
+	// have no dedicated AIRichResponseSubMessageType — WA carries them purely in the
+	// unifiedResponse view-model JSON, so their submessage falls back to plain AI_RICH_RESPONSE_TEXT
+	// like addTip/addHeading already do. Latex is the one exception: it has a real proto type
+	// (AI_RICH_RESPONSE_LATEX = 8, confirmed in WAProto) with its own latexMetadata, so that one
+	// gets a proper submessage instead of the text fallback.
 
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
+	/** Add a plain horizontal divider line (`GenAIDividerPrimitive`, no content). */
+	addDivider() {
+		this._submessages.push({ messageType: 2, messageText: '---' });
+		this._sections.push(AIRich.newLayout('Single', { __typename: 'GenAIDividerPrimitive' }));
+		return this;
+	}
+
+	/** Add blank vertical spacing (`GenAISpacerPrimitive`). @param {number} [spacing=1] Spacing unit, per observed traffic. */
+	addSpacer(spacing = 1) {
+		if (typeof spacing !== 'number' || spacing < 0) {
+			throw new TypeError('addSpacer(spacing) requires a non-negative number');
+		}
+		this._submessages.push({ messageType: 2, messageText: `spasi ${spacing}` });
+		this._sections.push(AIRich.newLayout('Single', { spacing, __typename: 'GenAISpacerPrimitive' }));
+		return this;
+	}
+
+	/**
+	 * Add a rendered LaTeX expression (`GenAILatexUXPrimitive`), with a real `AI_RICH_RESPONSE_LATEX`
+	 * submessage (unlike most primitives in this block, this one has a proper proto type).
+	 * @param {string} expression LaTeX source, e.g. `'$$E = mc^2$$'`.
+	 */
+	addLatex(expression) {
+		if (typeof expression !== 'string' || !expression) {
+			throw new TypeError('addLatex(expression) requires a non-empty string');
+		}
+		this._submessages.push({
+			messageType: 8,
+			latexMetadata: { text: expression, expressions: [{ latexExpression: expression }] },
 		});
+		this._sections.push(AIRich.newLayout('Single', { latex_expression: expression, __typename: 'GenAILatexUXPrimitive' }));
+		return this;
+	}
+
+	/**
+	 * Add a task/checklist card (`GenAITaskPrimitive`).
+	 * @param {{task_id?: string, title: string, subtitle?: string, status?: string}} data
+	 */
+	addTask(data = {}) {
+		if (!data?.title) {
+			throw new TypeError('addTask() requires a "title"');
+		}
+		this._submessages.push({ messageType: 2, messageText: `Tugas: ${data.title}` });
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				task_id: data.task_id ?? '',
+				title: data.title,
+				subtitle: data.subtitle ?? '',
+				status: data.status ?? 'IN_PROGRESS',
+				__typename: 'GenAITaskPrimitive',
+			})
+		);
+		// Safety net: GenAITaskPrimitive is a custom AI-only component the stock WA client
+		// doesn't render visibly. Append a plain text section so the task is still visible.
+		// Set data.textFallback = false to skip.
+		if (data.textFallback !== false) {
+			const fallbackText = data.subtitle ? `${data.title} — ${data.subtitle}` : data.title;
+			this._sections.push(AIRich.newLayout('Single', { text: `Tugas: ${fallbackText}`, __typename: 'FOATextPrimitive' }));
+		}
+		return this;
+	}
+
+	/**
+	 * Add a "searching/working" progress banner (`GenAIBotProgressStatusPrimitive`) — a one-shot
+	 * status chip (unlike `addSuggest`, this isn't tappable). Distinct from `addThinkingStatus()`'s
+	 * icon/typename.
+	 * @param {string} title
+	 * @param {{icon?: string, is_in_progress?: boolean}} [options]
+	 */
+	addProgressStatus(title, { icon = 'SEARCH', is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id } = {}) {
+		if (typeof title !== 'string' || !title) {
+			throw new TypeError('addProgressStatus(title) requires a non-empty string');
+		}
+		this._submessages.push({ messageType: 2, messageText: title });
+		const primitive = {
+			title,
+			icon,
+			is_in_progress,
+			meta_search_apps: [],
+			__typename: 'GenAIBotProgressStatusPrimitive',
+		};
+		// NOTE: these two fields must be OMITTED when unset, not sent as `null` —
+		// an explicit null here was reproducibly crashing the WA client renderer
+		// on group-open/media-download. Only include when the caller actually passes one.
+		if (target_secondary_screen_id != null) primitive.target_secondary_screen_id = target_secondary_screen_id;
+		if (target_secondary_screen_tab_id != null) primitive.target_secondary_screen_tab_id = target_secondary_screen_tab_id;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		return this;
+	}
+
+	/** Add a "thinking" status banner (`GenAIBotThinkingStatusPrimitive`). See `addProgressStatus()`. */
+	addThinkingStatus(title, { icon = 'THINKING', is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id, textFallback = true } = {}) {
+		if (typeof title !== 'string' || !title) {
+			throw new TypeError('addThinkingStatus(title) requires a non-empty string');
+		}
+		this._submessages.push({ messageType: 2, messageText: title });
+		const primitive = {
+			title,
+			icon,
+			is_in_progress,
+			meta_search_apps: [],
+			__typename: 'GenAIBotThinkingStatusPrimitive',
+		};
+		// Same crash-avoidance rule as addProgressStatus(): omit, never null.
+		if (target_secondary_screen_id != null) primitive.target_secondary_screen_id = target_secondary_screen_id;
+		if (target_secondary_screen_tab_id != null) primitive.target_secondary_screen_tab_id = target_secondary_screen_tab_id;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		// Safety net: stock WA client doesn't render this primitive's own view (it's meant
+		// as a transient spinner in the official app), so the card shows blank when forwarded.
+		// Append a plain text section so the title is still visible. Set { textFallback: false } to skip.
+		if (textFallback) {
+			this._sections.push(AIRich.newLayout('Single', { text: title, __typename: 'FOATextPrimitive' }));
+		}
+		return this;
+	}
+
+	/**
+	 * Add a subscription-quota-limit upsell card (`GenAIMetaSubsQuotaUpsellPrimitive`).
+	 * @param {{title: string, body?: string, body_line1?: string, body_line2?: string, buttons?: {label: string, action?: string, deeplink?: string}[]}} data
+	 */
+	addQuotaUpsell(data = {}) {
+		if (!data?.title) {
+			throw new TypeError('addQuotaUpsell() requires a "title"');
+		}
+		this._submessages.push({ messageType: 2, messageText: data.title });
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				title: data.title,
+				body: data.body ?? '',
+				body_line1: data.body_line1 ?? '',
+				body_line2: data.body_line2 ?? '',
+				buttons: (data.buttons ?? []).map((b) => ({
+					label: b.label ?? '',
+					action: b.action ?? 'OPEN_DEEPLINK',
+					deeplink: b.deeplink ?? '',
+				})),
+				__typename: 'GenAIMetaSubsQuotaUpsellPrimitive',
+			})
+		);
+		return this;
+	}
+
+	/**
+	 * Add a raw Bloks payload (`FOABloksPrimitive`) — Meta's internal UI-description format.
+	 * Escape hatch: field meaning beyond what's passed through is undocumented, so this is the
+	 * most experimental primitive in this block; pass whatever your captured traffic shows.
+	 * @param {{type: string, data: string, uuid?: string, initial_response?: any, versioning_id?: string}} data
+	 */
+	addBloks(data = {}) {
+		if (!data?.type) {
+			throw new TypeError('addBloks() requires a "type"');
+		}
+		this._submessages.push({ messageType: 2, messageText: 'Bloks' });
+		const primitive = {
+			type: data.type,
+			data: data.data ?? '{}',
+			uuid: data.uuid ?? '',
+			versioning_id: data.versioning_id ?? '',
+			__typename: 'FOABloksPrimitive',
+		};
+		// Omit initial_response entirely when unset — same null-field crash as addProgressStatus/addThinkingStatus.
+		if (data.initial_response != null) primitive.initial_response = data.initial_response;
+		this._sections.push(AIRich.newLayout('Single', primitive));
+		// Safety net: FOABloksPrimitive needs a real, client-registered Bloks screen to render
+		// anything — arbitrary/placeholder payloads show up blank. Append a plain text section
+		// so the card isn't empty. Set data.textFallback = false to skip.
+		if (data.textFallback !== false) {
+			this._sections.push(AIRich.newLayout('Single', { text: `Bloks: ${data.type}`, __typename: 'FOATextPrimitive' }));
+		}
+		return this;
 	}
 
-	addSuggest(suggestion, { scroll = true, layout, id, replace, insertAt } = {}) {
+	/** Add tappable follow-up suggestion chips below the message. @param {string|string[]} suggestion */
+	addSuggest(suggestion, { scroll = true, layout } = {}) {
 		if (!(typeof suggestion === 'string' || (Array.isArray(suggestion) && suggestion.every((v) => typeof v === 'string')))) {
 			throw new TypeError('Suggestion must be a string or array of strings');
 		}
@@ -2366,28 +2813,18 @@ class AIRich extends BaseBuilder {
 
 		const type = layout ?? (suggest.length === 1 ? 'Single' : scroll ? 'HScroll' : 'ActionRow');
 
-		const section = AIRich.newLayout(type, type === 'Single' ? suggest[0] : suggest, {
-			__typename: 'GenAIUnifiedResponseSection',
-		});
-
-		const submessage = this.createAlert('GenAIFollowUpSuggestionPillPrimitive');
+		this._sections.push(AIRich.newLayout(type, type === 'Single' ? suggest[0] : suggest, { __typename: 'GenAIUnifiedResponseSection' }));
 
-		return this._addContent(section, submessage, {
-			id,
-			replace,
-			insertAt,
-		});
+		return this;
 	}
 
-	async build(
-		jid,
-		{ bypassDownload = true, forwarded = true, notification = false, includesUnifiedResponse = true, includesSubmessages = true, quoted, quotedParticipant, messageId, ...options } = {}
-	) {
+	/** @returns {Promise<Record<string, any>>} The generated AI-rich message content (without wrapping/sending it). */
+	async build({ forwarded = true, notification = false, includesUnifiedResponse = true, includesSubmessages = true, quoted, quotedParticipant, ...options } = {}) {
 		const forward = forwarded
 			? {
 					forwardingScore: 1,
 					isForwarded: true,
-					forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' },
+					forwardedAiBotMessageInfo: { botJid: '0@bot' },
 					forwardOrigin: 4,
 				}
 			: {};
@@ -2405,7 +2842,7 @@ class AIRich extends BaseBuilder {
 		const qObj = quoted
 			? {
 					stanzaId: quoted?.key?.id || quoted?.id,
-					participant: quotedParticipant || quoted?.key?.participant || quoted?.participant || quoted?.key?.remoteJid,
+					participant: quotedParticipant || quoted?.key?.participant || quoted?.key?.remoteJid,
 					quotedType: 0,
 					quotedMessage: typeof quoted === 'object' && quoted !== null ? (quoted.message ?? quoted) : undefined,
 				}
@@ -2421,88 +2858,140 @@ class AIRich extends BaseBuilder {
 				]
 			: [...(await waitAllPromises(this._sections))];
 
-		if (this._dynamic) {
-			this.refreshResponseId();
-			this.refreshBotResponseId();
-		}
+		// Vanz@Merge 15-08-26 --- Neither blurose nor arslan sign the bot metadata with
+		// verificationMetadata (proofs/certificateChain). Backported from this project's own
+		// rich-message-utils.js botMetadataSignature/botMetadataCertificate helpers, plus a
+		// botResponseId tying the signed metadata to unifiedResponse.response_id.
+		// Vanz@Fix 24-08-26 --- was `const responseId = crypto.randomUUID()` shared for BOTH
+		// unifiedResponse.response_id and botMetadata.botResponseId, generated fresh every build()
+		// with no override. Now each has its own id, pinned via setResponseId()/setBotResponseId()
+		// if the caller set one (for sendEdit()-style in-place message updates), otherwise still
+		// defaults to a fresh randomUUID() per build() exactly like before.
+		const responseId = this._responseId ?? crypto.randomUUID();
+		const botResponseId = this._botResponseId ?? crypto.randomUUID();
 
-		return generateWAMessageFromContent(
-			jid,
-			{
-				messageContextInfo: {
-					deviceListMetadata: {},
-					deviceListMetadataVersion: 2,
-					botMetadata: {
-						messageDisclaimerText: this._title,
-						...notif,
-						verificationMetadata: AIRich.generateVerificationMetadata(),
-						botResponseId: this._botResponseId,
+		return {
+			messageContextInfo: {
+				deviceListMetadata: {},
+				deviceListMetadataVersion: 2,
+				botMetadata: {
+					messageDisclaimerText: this._title,
+					richResponseSourcesMetadata: { sources: this._richResponseSources },
+					botResponseId: botResponseId,
+					verificationMetadata: {
+						proofs: [
+							{
+								certificateChain: [botMetadataCertificate(), botMetadataCertificate(892)],
+								version: 1,
+								useCase: 1,
+								signature: botMetadataSignature(),
+							},
+						],
 					},
+					...notif,
 				},
-				...this._extraPayload,
-				botForwardedMessage: {
-					message: {
-						richResponseMessage: {
-							messageType: 1,
-							submessages: includesSubmessages ? await waitAllPromises(this._submessages) : [],
-							unifiedResponse: {
-								data: includesUnifiedResponse ? Buffer.from(Toolkit.stringifyEscaped({ response_id: this._responseId, sections })).toString('base64') : '',
-							},
-							contextInfo: {
-								...forward,
-								...qObj,
-								...this._contextInfo,
-							},
+			},
+			...this._extraPayload,
+			botForwardedMessage: {
+				message: {
+					richResponseMessage: {
+						messageType: 1,
+						submessages: includesSubmessages ? await waitAllPromises(this._submessages) : [],
+						unifiedResponse: {
+							data: includesUnifiedResponse ? Buffer.from(JSON.stringify({ response_id: responseId, sections })).toString('base64') : '',
+						},
+						contextInfo: {
+							...forward,
+							...qObj,
+							...this._contextInfo,
 						},
 					},
 				},
 			},
-			{ messageId: messageId || generateMessageIDV2(), ...options }
-		);
+		};
 	}
 
-	async buildEdit(targetJid, targetId, { msg, messageId, ...options } = {}) {
-		if (!msg) {
-			msg = (await this.build(targetJid, options)).message;
+	// Vanz@Fix (bug 42 / inline image fallback) --- WA won't render AIRichResponseInlineImageMetadata
+	// for bot-sent messages (confirmed: even a valid WA-CDN url with mediaKey stays blank), so any
+	// image added via addInlineImage() is sent here as a normal imageMessage instead. Pass
+	// { skipImageFallback: true } to opt out and send only the (image-less-looking) rich card.
+	// Vanz@Fix: don't spread relayMessage-shaped `options` into sendMessage()'s options param —
+	// the two calls expect different option shapes, so the fallback now only forwards `quoted`
+	// (the one option that clearly applies to both) instead of blindly spreading everything.
+	/** Build and send this AI-rich message. @param {string} jid Destination chat/group jid. @param {boolean} [skipImageFallback] Skip auto-resending inline images as a plain imageMessage. */
+	async send(jid, { forwarded, notification, includesUnifiedResponse, includesSubmessages, skipImageFallback = false, quoted, messageId, ...options } = {}) {
+		const msg = await this.build({ forwarded, notification, includesUnifiedResponse, includesSubmessages, quoted, ...options });
+
+		if (!skipImageFallback && this._inlineImages.length) {
+			for (const { url, caption } of this._inlineImages) {
+				try {
+					await this.#client.sendMessage(jid, { image: { url }, caption }, quoted ? { quoted } : {});
+				} catch (err) {
+					// Vanz@Fix: don't let a fallback image failure block the actual rich card from sending
+					this.#client.logger?.warn?.({ err, url }, 'inline image fallback failed, continuing with rich card');
+				}
+			}
 		}
 
-		const editedMessage = msg;
+		// Vanz@Add --- pin our own messageId (instead of letting relayMessage mint one internally)
+		// so we know exactly which id was sent, and stash it as _lastMessageKey. That's what lets
+		// sendEdit() be called with no args afterwards and still know which message to patch.
+		messageId = messageId || generateMessageIDV2();
+
+		await this.#client.relayMessage(jid, msg, { messageId, ...options });
+
+		this._lastMessageKey = { remoteJid: jid, fromMe: true, id: messageId };
+
+		return { key: this._lastMessageKey, message: msg };
+	}
+
+	/**
+	 * Build a `protocolMessage` (type EDIT) that patches an already-sent AIRich message in place.
+	 * @param {string} targetJid Chat the original message lives in.
+	 * @param {string} targetId `key.id` of the original message (the id `send()`/`sendEdit()` returned).
+	 * @param {object} [opts] Pass `{ msg }` to reuse an already-built content object instead of rebuilding via build().
+	 */
+	async buildEdit(targetJid, targetId, { msg, messageId, ...options } = {}) {
+		const editedMessage = msg || (await this.build({ ...options }));
 
 		if (!editedMessage) {
-			throw new Error('buildEdit: msg does not contain botForwardedMessage');
+			throw new Error('buildEdit: no message content to edit (build() returned nothing)');
 		}
 
 		return generateWAMessageFromContent(
 			targetJid,
 			{
-				botForwardedMessage: {
-					message: {
-						protocolMessage: {
-							key: {
-								remoteJid: targetJid,
-								fromMe: true,
-								id: targetId,
-							},
-							type: 14,
-							editedMessage,
-						},
+				protocolMessage: {
+					key: {
+						remoteJid: targetJid,
+						fromMe: true,
+						id: targetId,
 					},
+					type: 14, // MESSAGE_EDIT
+					editedMessage,
 				},
 			},
 			{ messageId: messageId || generateMessageIDV2(), ...options }
 		);
 	}
 
+	/**
+	 * Rebuild this AIRich message's current content and patch it into an already-sent message in place
+	 * (WA edits the bubble instead of showing a new one). With no args, edits the message from the last
+	 * send()/sendEdit() call — that's the flow `.addX(...); await rich.sendEdit();` relies on.
+	 * @param {string} [jid] Defaults to the jid from the last send()/sendEdit().
+	 * @param {string} [id] Defaults to the message id from the last send()/sendEdit().
+	 */
 	async sendEdit(jid, id, { msg, messageId, additionalNodes = [], ...options } = {}) {
 		jid = jid ?? this._lastMessageKey?.remoteJid;
 		id = id ?? this._lastMessageKey?.id;
 
 		if (!jid) {
-			throw new Error('JID is required');
+			throw new Error('sendEdit: no jid — pass one explicitly, or call send() first');
 		}
 
 		if (!id) {
-			throw new Error('Message id is required');
+			throw new Error('sendEdit: no message id — pass one explicitly, or call send() first');
 		}
 
 		const msgEdit = await this.buildEdit(jid, id, {
@@ -2516,36 +3005,13 @@ class AIRich extends BaseBuilder {
 			additionalNodes,
 		});
 
+		// Vanz@Note --- deliberately NOT overwriting _lastMessageKey with msgEdit.key here: the
+		// protocolMessage envelope has its own id, but the message the user actually sees (and the
+		// one future sendEdit() calls need to keep patching) is still `id`/`jid` above.
 		return msgEdit;
 	}
 
-	async send(jid, { bypassDownload = true, forwarded = true, notification = false, includesUnifiedResponse = true, includesSubmessages = true, messageId, additionalNodes = [], ...options } = {}) {
-		const msg = await this.build(jid, {
-			forwarded,
-			notification,
-			includesUnifiedResponse,
-			includesSubmessages,
-			messageId,
-			...options,
-		});
-
-		await this.#client.relayMessage(msg.key.remoteJid, msg.message, {
-			messageId: msg.key.id,
-			additionalNodes,
-			...options,
-		});
-
-		if (includesUnifiedResponse && bypassDownload) {
-			await this.sendEdit(jid, msg.key.id, {
-				msg: msg.message,
-			});
-		}
-
-		this._lastMessageKey = msg.key;
-
-		return msg;
-	}
-
+	/** Tokenize `code` into `{ type, value }` spans for syntax highlighting. Covers JS/TS/Python/Java and more; unsupported languages fall back to a single plain-text token. */
 	static tokenizer(code, lang = 'javascript') {
 		const keywordsMap = {
 			javascript: new Set([
@@ -3211,6 +3677,7 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
+	/** Convert a raw `string[][]` grid into the table metadata shape addTable()/addText() produce internally. */
 	static toTableMetadata(arr, { hyperlink = true, citation = true, latex = true } = {}) {
 		if (!Array.isArray(arr) || !arr.every((row) => Array.isArray(row) && row.every((cell) => typeof cell === 'string'))) {
 			throw new TypeError('Table must be a nested array of strings');
@@ -3259,358 +3726,129 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
-	static generateVerificationMetadata() {
-		const signatureMaterial = Buffer.from(
-			`\u004E\u0049\u0058\u0045\u004C\u002E\u004D\u0065\u0073\u0073\u0061\u0067\u0065\u0042\u0075\u0069\u006C\u0064\u0065\u0072\u0056${VERSION}\u002D\u0056\u0065\u0072\u0069\u0066\u0069\u0063\u0061\u0074\u0069\u006F\u006E\u0053\u0069\u0067\u006E\u0061\u0074\u0075\u0072\u0065\u002E\u004D\u0065\u0074\u0061\u0064\u0061\u0074\u0061`
-		);
-
-		const certificateMaterial = Buffer.from(
-			`\u004E\u0049\u0058\u0045\u004C\u002E\u004D\u0065\u0073\u0073\u0061\u0067\u0065\u0042\u0075\u0069\u006C\u0064\u0065\u0072\u0056${VERSION}\u002D\u0043\u0065\u0072\u0074\u0069\u0066\u0069\u0063\u0061\u0074\u0065\u0043\u0068\u0061\u0069\u006E\u002E\u004D\u0065\u0074\u0061\u0064\u0061\u0074\u0061`
-		);
-
-		const signature = Buffer.concat([signatureMaterial, crypto.randomBytes(64 - signatureMaterial.length)]).toString('base64');
-
-		const certificateChain = [
-			Buffer.concat([certificateMaterial, crypto.randomBytes(684 - certificateMaterial.length)]).toString('base64'),
-
-			Buffer.concat([certificateMaterial, crypto.randomBytes(892 - certificateMaterial.length)]).toString('base64'),
-		];
-
-		return {
-			proofs: [
-				{
-					version: 1,
-					useCase: 1,
-					signature,
-					certificateChain,
+	/**
+	 * Add an "AI is generating..." placeholder card (`GenAIImaginePrimitive` with status
+	 * GENERATING) — distinct from addImage()/addVideo() which always send status READY.
+	 * Use this to show a pending-generation state before the real media is ready.
+	 * @param {{ imagine_type?: 'IMAGE'|'ANIMATE', estimated_completion_time?: number }} [options]
+	 */
+	addGenerating({ imagine_type = 'IMAGE', estimated_completion_time, textFallback = true } = {}) {
+		this._submessages.push({ messageType: 2, messageText: '[ Sedang diproses... ]' });
+		this._sections.push(
+			AIRich.newLayout('Single', {
+				media: { url: '', mime_type: imagine_type === 'ANIMATE' ? 'video/mp4' : 'image/png' },
+				imagine_type,
+				status: {
+					status: 'GENERATING',
+					estimated_completion_time: estimated_completion_time ?? Math.floor(Date.now() / 1000) + 30,
 				},
-			],
-		};
+				__typename: 'GenAIImaginePrimitive',
+			})
+		);
+		// Vanz@Fix 23-08-26 (v4.8) --- media.url kosong + status GENERATING gak punya renderer
+		// visual instan di stock WA client; sebelumnya cuma diem sampe WA nge-timeout sendiri
+		// dan nampilin fallback bawaannya ("Saat ini, saya tidak bisa membuat gambar itu...").
+		// Same fix class kayak addTask/addBloks: append FOATextPrimitive biar ada fallback
+		// instan, gak perlu nunggu timeout WA. Set { textFallback: false } buat skip.
+		if (textFallback) {
+			this._sections.push(AIRich.newLayout('Single', { text: '[ Sedang diproses... ]', __typename: 'FOATextPrimitive' }));
+		}
+		return this;
 	}
 
-	static newLayout(name, data, extra = {}) {
-		return {
-			...extra,
-			view_model: {
-				[Array.isArray(data) ? 'primitives' : 'primitive']: data,
-				__typename: `GenAI${name}LayoutViewModel`,
+	/**
+	 * Send a support-ticket marker message (`messageContextInfo.supportPayload`) — a plain
+	 * conversation message tagged as an AI/support-bot ticket, distinct from richResponseMessage.
+	 * @param {import('../../WAProto/index.js').WASocket} client
+	 * @param {string} jid
+	 * @param {string} text
+	 * @param {{ ticketId?: string, isAiMessage?: boolean, shouldShowSystemMessage?: boolean, version?: number }} [options]
+	 */
+	static async sendSupportPayload(client, jid, text, { ticketId = crypto.randomUUID(), isAiMessage = true, shouldShowSystemMessage = true, version = 1 } = {}) {
+		if (!client) throw new Error('Socket is required');
+		if (typeof text !== 'string' || !text) throw new TypeError('sendSupportPayload(client, jid, text) requires a non-empty string text');
+
+		const msg = {
+			conversation: text,
+			messageContextInfo: {
+				messageSecret: crypto.randomBytes(32),
+				supportPayload: JSON.stringify({
+					version,
+					is_ai_message: isAiMessage,
+					should_show_system_message: shouldShowSystemMessage,
+					ticket_id: ticketId,
+				}),
 			},
 		};
-	}
 
-	_makeNode(id, section, submessage) {
-		return { id: id ?? null, section: section ?? null, submessage: submessage ?? null };
+		return client.relayMessage(jid, msg, {
+			additionalNodes: [
+				{ tag: 'bot', attrs: { biz_bot: '1' } },
+				{ tag: 'biz', attrs: {} },
+			],
+		});
 	}
 
-	_registerId(node, id) {
-		if (id === undefined || id === null || id === '') return;
-
-		if (typeof id !== 'string') {
-			throw new ContentValidationError('Item id must be a string', { id });
-		}
+	/**
+	 * Send an image and video as one paired-media unit (image sent first, video linked to it via
+	 * `messageAssociation`). Distinct from a plain album — the client treats them as a single group.
+	 * @param {import('../../WAProto/index.js').WASocket} client
+	 * @param {string} jid
+	 * @param {{ image: string|Buffer, video: string|Buffer }} media
+	 */
+	static async sendPairedMedia(client, jid, { image, video } = {}) {
+		if (!client) throw new Error('Socket is required');
+		if (!image || !video) throw new TypeError('sendPairedMedia() requires both "image" and "video"');
 
-		if (this._idIndex.has(id)) {
-			throw new DuplicateIdError(id);
-		}
+		const imagePrepared = await prepareWAMessageMedia(
+			{ image: typeof image === 'string' ? { url: image } : image },
+			{ upload: client.waUploadToServer }
+		);
+		const videoPrepared = await prepareWAMessageMedia(
+			{ video: typeof video === 'string' ? { url: video } : video },
+			{ upload: client.waUploadToServer }
+		);
 
-		node.id = id;
-		this._idIndex.set(id, node);
-	}
+		const imageMsg = generateWAMessageFromContent(
+			jid,
+			{
+				imageMessage: {
+					...imagePrepared.imageMessage,
+					contextInfo: { pairedMediaType: 5, statusSourceType: 0 },
+				},
+			},
+			{}
+		);
 
-	_unregisterId(node) {
-		if (node.id && this._idIndex.get(node.id) === node) {
-			this._idIndex.delete(node.id);
-		}
-	}
+		await client.relayMessage(jid, imageMsg.message, { messageId: imageMsg.key.id });
 
-	hasId(id) {
-		return typeof id === 'string' && this._idIndex.has(id);
-	}
+		await client.relayMessage(
+			jid,
+			{
+				videoMessage: {
+					...videoPrepared.videoMessage,
+					contextInfo: { pairedMediaType: 6, statusSourceType: 0 },
+				},
+				messageContextInfo: {
+					messageAssociation: { associationType: 12, parentMessageKey: imageMsg.key },
+				},
+			},
+			{}
+		);
 
-	getIds() {
-		return [...this._idIndex.keys()];
+		return imageMsg.key;
 	}
 
-	peek(id) {
-		const node = this._idIndex.get(id);
-
-		if (!node) return null;
-
+	/** Build a raw submessage layout block by name — escape hatch for layouts not covered by the add*() helpers. */
+	static newLayout(name, data, extra = {}) {
 		return {
-			id: node.id,
-			section: node.section,
-			submessage: node.submessage,
+			...extra,
+			view_model: {
+				[Array.isArray(data) ? 'primitives' : 'primitive']: data,
+				__typename: `GenAI${name}LayoutViewModel`,
+			},
 		};
 	}
-
-	assignId(index, id) {
-		if (!Number.isInteger(index) || index < 0 || index >= this._nodes.length) {
-			throw new InvalidTargetError(`Node index ${index} is out of range (0-${this._nodes.length - 1})`, { index });
-		}
-
-		const node = this._nodes[index];
-
-		if (node.id) {
-			throw new AIRichError(`Node at index ${index} already has id "${node.id}"`, 'ALREADY_HAS_ID', { index, id: node.id });
-		}
-
-		this._registerId(node, id);
-
-		return this;
-	}
-
-	_getNode(id) {
-		if (typeof id !== 'string' || !id) {
-			throw new ContentValidationError('Item id must be a non-empty string', { id });
-		}
-
-		const node = this._idIndex.get(id);
-
-		if (!node) {
-			throw new ItemNotFoundError(id, this.getIds());
-		}
-
-		return node;
-	}
-
-	_resolveTarget(target) {
-		if (Array.isArray(target)) {
-			if (target.length < 1 || target.length > 2) {
-				throw new ContentValidationError('Target must be id or [id, offset]', { target });
-			}
-
-			const [id, offset = 0] = target;
-
-			if (typeof id !== 'string' || !id) {
-				throw new ContentValidationError('Target id must be a non-empty string', { target });
-			}
-
-			if (!Number.isInteger(offset)) {
-				throw new ContentValidationError('Offset must be an integer', { target });
-			}
-
-			return { id, offset };
-		}
-
-		if (typeof target !== 'string' || !target) {
-			throw new ContentValidationError('Target must be a non-empty id or [id, offset]', { target });
-		}
-
-		return { id: target, offset: 0 };
-	}
-
-	_resolveNodeIndex(target) {
-		const { id, offset } = this._resolveTarget(target);
-		const node = this._getNode(id);
-		const baseIndex = this._nodes.indexOf(node);
-
-		if (baseIndex === -1) {
-			throw new InvalidTargetError(`Item id "${id}" is registered but not present in the node list (internal desync)`, { id });
-		}
-
-		const index = baseIndex + offset;
-
-		if (index < 0 || index >= this._nodes.length) {
-			throw new InvalidTargetError(`Target "${id}" with offset ${offset} resolves to index ${index}, which is out of range (0-${this._nodes.length - 1})`, { id, offset, index });
-		}
-
-		return { id, offset, baseIndex, index };
-	}
-
-	_validateSections(section) {
-		const items = Array.isArray(section) ? section : [section];
-
-		if (!items.length) {
-			throw new ContentValidationError('At least one section is required');
-		}
-
-		for (const item of items) {
-			if (!item || typeof item !== 'object' || Array.isArray(item)) {
-				throw new ContentValidationError('Sections must be plain objects');
-			}
-		}
-
-		return items;
-	}
-
-	_validateSubmessages(submessage) {
-		if (submessage === undefined || submessage === null) {
-			return [];
-		}
-
-		const items = Array.isArray(submessage) ? submessage : [submessage];
-
-		for (const item of items) {
-			if (!item || typeof item !== 'object' || Array.isArray(item)) {
-				throw new ContentValidationError('Submessages must be plain objects');
-			}
-		}
-
-		return items;
-	}
-
-	_pairSubmessages(sections, submessages) {
-		const n = sections.length;
-		const m = submessages.length;
-
-		if (m === 0) return sections.map(() => null);
-		if (m === 1) return sections.map((_, i) => (i === 0 ? submessages[0] : null));
-		if (m === n) return submessages;
-
-		throw new ContentValidationError(`Cannot pair ${m} submessage(s) with ${n} section(s): expected 0, 1, or ${n}`, { sectionCount: n, submessageCount: m });
-	}
-
-	_addContent(section, submessage, { id, replace, insertAt } = {}) {
-		const hasReplace = replace !== undefined && replace !== null && replace !== '';
-
-		const hasInsertAt = insertAt !== undefined && insertAt !== null && insertAt !== '';
-
-		if (hasReplace && hasInsertAt) {
-			throw new ContentValidationError('replace and insertAt cannot be used together');
-		}
-
-		const sections = this._validateSections(section);
-		const submessages = this._validateSubmessages(submessage);
-
-		if (!sections.length) {
-			throw new ContentValidationError('At least one section is required');
-		}
-
-		if (id !== undefined && id !== null && id !== '' && sections.length !== 1) {
-			throw new ContentValidationError('One id can only be assigned to one node', {
-				id,
-				sectionCount: sections.length,
-			});
-		}
-
-		if (submessages.length && submessages.length !== sections.length && submessages.length !== 1) {
-			throw new ContentValidationError('Section and submessage count must match');
-		}
-
-		const pairedSubmessages = sections.map((_, index) => {
-			if (!submessages.length) return undefined;
-
-			return submessages.length === 1 ? submessages[0] : submessages[index];
-		});
-
-		if (id && this._idIndex.has(id) && !(hasReplace && this._resolveTarget(replace)?.id === id)) {
-			throw new DuplicateIdError(id);
-		}
-
-		const newNodes = sections.map((currentSection, index) => {
-			return this._makeNode(index === 0 ? id : null, currentSection, pairedSubmessages[index]);
-		});
-
-		if (hasReplace) {
-			if (newNodes.length !== 1) {
-				throw new ContentValidationError('replace only supports adding exactly one node');
-			}
-
-			const target = this._resolveNodeIndex(replace);
-
-			if (!target) {
-				throw new ContentValidationError('Target node could not be resolved');
-			}
-
-			const oldNode = this._nodes[target.index];
-			const newNode = newNodes[0];
-
-			if (!newNode.id && oldNode?.id) {
-				newNode.id = oldNode.id;
-			}
-
-			this._unregisterId(oldNode);
-
-			this._nodes.splice(target.index, 1, newNode);
-
-			if (newNode.id) {
-				this._idIndex.set(newNode.id, newNode);
-			}
-
-			return this;
-		}
-
-		if (hasInsertAt) {
-			const target = this._resolveNodeIndex(insertAt);
-
-			if (!target) {
-				throw new ContentValidationError('Target node could not be resolved');
-			}
-
-			const insertIndex = target.offset < 0 ? target.index : target.index + 1;
-
-			this._nodes.splice(insertIndex, 0, ...newNodes);
-
-			for (const node of newNodes) {
-				if (node.id) {
-					this._idIndex.set(node.id, node);
-				}
-			}
-
-			return this;
-		}
-
-		this._nodes.push(...newNodes);
-
-		for (const node of newNodes) {
-			if (node.id) {
-				this._idIndex.set(node.id, node);
-			}
-		}
-
-		return this;
-	}
-
-	addSection(section, options = {}) {
-		return this._addContent(section, undefined, options);
-	}
-
-	addSubmessage(submessage, options = {}) {
-		const items = this._validateSubmessages(submessage);
-
-		if (!items.length) {
-			throw new ContentValidationError('At least one submessage is required');
-		}
-
-		return this._addContent(undefined, items, options);
-	}
-
-	delete(target) {
-		const { index } = this._resolveNodeIndex(target);
-		const [oldNode] = this._nodes.splice(index, 1);
-
-		this._unregisterId(oldNode);
-
-		return this;
-	}
-
-	get _sections() {
-		return this._nodes.filter((n) => n.section !== null).map((n) => n.section);
-	}
-
-	get _submessages() {
-		return this._nodes.filter((n) => n.submessage !== null).map((n) => n.submessage);
-	}
-
-	get sections() {
-		return this._sections;
-	}
-
-	get items() {
-		return this._sections.flatMap((section) => {
-			const vm = section?.view_model;
-
-			if (Array.isArray(vm?.primitives)) {
-				return vm.primitives;
-			}
-
-			if (vm?.primitive) {
-				return [vm.primitive];
-			}
-
-			return [];
-		});
-	}
 }
 
 // Vanz@Alias --- AIRich diekspos ulang pake nama sendiri. Implementasi & referensi