@vanzxy/baileys 2.0.1 → 2.0.3

package/lib/Builders/AIRich.js

@@ -1,8 +1,11 @@
-import { BaseBuilder, Toolkit, extractIE, waitAllPromises, getSharp, getFfmpeg, botMetadataSignature, botMetadataCertificate, crypto, generateWAMessageFromContent, prepareWAMessageMedia, generateMessageIDV2 } from './shared.js';
+import { BaseBuilder, Toolkit, extractIE, waitAllPromises, crypto, generateWAMessageFromContent, generateMessageIDV2 } from './shared.js';
+
+const VERSION = '5.0';
+
 class AIRich extends BaseBuilder {
 	#client;
 
-	constructor(client) {
+	constructor(client, { dynamic = true, unsupportedTypeAlert = true } = {}) {
 		if (!client) {
 			throw new Error('Socket is required');
 		}
@@ -10,204 +13,125 @@ class AIRich extends BaseBuilder {
 		super();
 		this.#client = client;
 		this._contextInfo = {};
-		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._nodes = [];
+		this._idIndex = new Map();
+		this._unsupportedTypeAlert = !!unsupportedTypeAlert;
+		this._dynamic = !!dynamic;
+		this._responseId = crypto.randomUUID();
+		this._botResponseId = crypto.randomUUID();
 		this._lastMessageKey = null;
+	}
 
-		// 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).
-		//
-		// Vanz@Note (bug 71, behavior — not fixed, documented) --- insertAt always inserts right after
-		// the ANCHOR's block, not after "whatever was most recently inserted there". Chaining (each new
-		// item gets its own id, and the next call's insertAt points at THAT id — exactly what the
-		// addText/addSuggest streaming-reveal example does) produces the expected order. But calling
-		// insertAt at the SAME static anchor id repeatedly, without giving each new item its own id to
-		// chain onto, inserts every one of them right after the original anchor — so the order comes out
-		// reversed relative to call order (confirmed by test: id:'x' then 3x insertAt:'x' with no id of
-		// their own on the new items produces [x, third, second, first], not [x, first, second, third]).
-		// Left as-is rather than "fixed": making insertAt self-advance (re-pointing the anchor's block at
-		// whatever was just inserted) would silently change what an id resolves to for any OTHER caller
-		// still holding that id for a later replace()/delete()/insertAt() — a subtler, harder-to-diagnose
-		// bug than the surprising-but-deterministic order this produces. Chain with fresh ids instead.
-		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;
-					};
+	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);
 				}
+			} catch {}
+		}
 
-				return (...args) => {
-					const opts = args.find((a) => a && typeof a === 'object' && !Array.isArray(a) && !Buffer.isBuffer(a) && ('id' in a || 'insertAt' in a || 'replace' in a));
-					const id = opts?.id;
-					const insertAt = opts?.insertAt;
-					const replace = opts?.replace;
-
-					// Vanz@Fix (bug 70) --- `id` reuse across two different add*/set* calls was silently
-					// accepted: target._blocks.set(id, ...) below just clobbers the previous registration,
-					// so the FIRST block with that id becomes an untracked ghost — still in _sections/
-					// _submessages (still renders), but no longer reachable via hasId/peek/delete/replace/
-					// insertAt (the id now only resolves to the second block). Confirmed by direct test:
-					// addText('first',{id:'dup'}); addText('second',{id:'dup'}) left both in the message
-					// but getIds() only ever had one 'dup', pointing at 'second'. Fail fast instead — same
-					// as re-registering the same id you're actively `replace`-ing (that's a legitimate
-					// "update this block, keep its id" call, not a collision).
-					if (id && target._blocks.has(id) && replace !== id) {
-						throw new Error(`add*/set*: id "${id}" is already registered — each id must be unique (pass { replace: "${id}" } to update that block instead, or use a different id)`);
-					}
+		this._nodes = [];
+		this._idIndex = new Map();
 
-					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 if (replace) {
-						// replace: delete the old block's items at their current positions,
-						// then insert new items at the same positions
-						const old = target._blocks.get(replace);
-						if (!old) throw new Error(`replace: no block registered with id "${replace}" (register it first with { id: "${replace}" })`);
-
-						let subIdx = old.subItems.length > 0 ? target._submessages.indexOf(old.subItems[0]) : target._submessages.length;
-						if (subIdx === -1) subIdx = target._submessages.length;
-						for (const item of old.subItems) {
-							const i = target._submessages.indexOf(item);
-							if (i !== -1) target._submessages.splice(i, 1);
-						}
-						target._submessages.splice(subIdx, 0, ...subItems);
-
-						let secIdx = old.secItems.length > 0 ? target._sections.indexOf(old.secItems[0]) : target._sections.length;
-						if (secIdx === -1) secIdx = target._sections.length;
-						for (const item of old.secItems) {
-							const i = target._sections.indexOf(item);
-							if (i !== -1) target._sections.splice(i, 1);
-						}
-						target._sections.splice(secIdx, 0, ...secItems);
-
-						target._blocks.delete(replace);
-						if (id) target._blocks.set(id, { subItems, secItems });
-						else target._blocks.set(replace, { subItems, secItems });
-					} else {
-						target._submessages.push(...subItems);
-						target._sections.push(...secItems);
-					}
+		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,
+			});
+		}
 
-					if (id) target._blocks.set(id, { subItems, secItems });
+		this._extraPayload = {};
 
-					return result === target ? receiver : result;
-				};
-			},
-		});
+		for (const [key, value] of Object.entries(message)) {
+			if (key !== 'messageContextInfo' && key !== 'botForwardedMessage' && key !== 'richResponseMessage') {
+				this._extraPayload[key] = structuredClone(value);
+			}
+		}
+
+		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] : []);
-		});
+	setResponseId(id) {
+		if (typeof id !== 'string') {
+			throw new TypeError('ID must be a string');
+		}
+		this._responseId = id;
+
+		return this;
 	}
 
-	/** 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];
+	refreshResponseId() {
+		this._responseId = crypto.randomUUID();
 
-		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');
-			}
+		return this;
+	}
 
-			this._submessages.push(item);
+	setBotResponseId(id) {
+		if (typeof id !== 'string') {
+			throw new TypeError('ID must be a string');
 		}
+		this._botResponseId = id;
 
 		return this;
 	}
 
-	/** Push a raw pre-built section wrapper around one or more submessages. */
-	addSection(section) {
-		const items = Array.isArray(section) ? section : [section];
+	refreshBotResponseId() {
+		this._botResponseId = crypto.randomUUID();
 
-		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');
-			}
+		return this;
+	}
 
-			this._sections.push(item);
+	createAlert(type) {
+		if (this._unsupportedTypeAlert) {
+			return {
+				messageType: 2,
+				messageText: `[ UNSUPPORTED_TYPE - ${type}]`,
+			};
 		}
 
-		return this;
+		return undefined;
 	}
 
-	/** 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') {
+	addText(text, { hyperlink = true, citation = true, latex = true, id, replace, insertAt } = {}) {
+		if (typeof text !== 'string') {
 			throw new TypeError('Text must be a string');
 		}
 
@@ -217,195 +141,185 @@ class AIRich extends BaseBuilder {
 			latex,
 		});
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: extractedText,
+		const section = AIRich.newLayout('Single', {
+			text: extractedText,
+			...(inline_entities.length && { inline_entities }),
+			__typename: 'GenAIMarkdownTextUXPrimitive',
 		});
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				text: extractedText,
-				...(inline_entities.length && {
-					inline_entities,
-				}),
-				__typename: 'GenAIMarkdownTextUXPrimitive',
-			})
-		);
+		const submessages = [
+			{
+				messageType: 2,
+				messageText: text,
+			},
+		].filter(Boolean);
 
-		return this;
+		return this._addContent(section, submessages, {
+			id,
+			replace,
+			insertAt,
+		});
+	}
+
+	/** Alias — .d.ts documents this as "addHeading" (FOATextPrimitive), source only ever exposed addFOAText(). */
+	addHeading(text, options = {}) {
+		return this.addFOAText(text, options);
+	}
+
+	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',
+		});
+
+		const submessages = [
+			{
+				messageType: 2,
+				messageText: text,
+			},
+		];
+
+		return this._addContent(section, submessages, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Add a syntax-highlighted code block. @param {string} language e.g. 'javascript', 'python'. */
-	addCode(language, code) {
+	addCode(language, code, { id, replace, insertAt } = {}) {
 		if (typeof language !== 'string' || typeof code !== 'string') {
 			throw new TypeError('Language and code must be a string');
 		}
 
 		const meta = AIRich.tokenizer(code, language);
 
-		this._submessages.push({
-			messageType: 5,
-			codeMetadata: {
-				codeLanguage: language,
-				codeBlocks: meta.codeBlock,
-			},
+		const section = AIRich.newLayout('Single', {
+			language,
+			code_blocks: meta.unified_codeBlock,
+			__typename: 'GenAICodeUXPrimitive',
 		});
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				language,
-				code_blocks: meta.unified_codeBlock,
-				__typename: 'GenAICodeUXPrimitive',
-			})
-		);
+		const submessages = [
+			{
+				messageType: 5,
+				codeMetadata: {
+					codeLanguage: language,
+					codeBlocks: meta.codeBlock,
+				},
+			},
+		];
 
-		return this;
+		return this._addContent(section, submessages, {
+			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 } = {}) {
+	addTable(table, { hyperlink = true, citation = true, latex = true, id, replace, insertAt } = {}) {
 		if (!Array.isArray(table)) {
 			throw new TypeError('Table must be an array');
 		}
 
-		const meta = AIRich.toTableMetadata(table, { hyperlink, citation, latex });
-
-		this._submessages.push({
-			messageType: 4,
-			tableMetadata: {
-				title: meta.title,
-				rows: meta.rows,
-			},
+		const meta = AIRich.toTableMetadata(table, {
+			hyperlink,
+			citation,
+			latex,
 		});
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				rows: meta.unified_rows,
-				__typename: 'GenATableUXPrimitive',
-			})
-		);
-
-		return this;
-	}
+		const section = AIRich.newLayout('Single', {
+			rows: meta.unified_rows,
+			__typename: 'GenATableUXPrimitive',
+		});
 
-	/** 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 submessages = [
+			{
+				messageType: 4,
+				tableMetadata: {
+					title: meta.title,
+					rows: meta.rows,
 				},
-			};
-			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;
-	}
+			},
+		];
 
-	/** 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 },
+		return this._addContent(section, submessages, {
+			id,
+			replace,
+			insertAt,
 		});
-		this._sections.push(AIRich.newLayout('Single', {
-			items,
-			content_type: 1,
-			__typename: 'GenAIContentItemsUXPrimitive',
-		}));
-		return this;
 	}
 
-	/** 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;
-	}
+	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');
+
+		const isArrayFormat = sources.every((item) => Array.isArray(item) && item.every((value) => typeof value === 'string'));
+
+		const isObjectFormat = sources.every((item) => item && typeof item === 'object' && !Array.isArray(item));
+
+		if (!isStringArray && !isArrayFormat && !isObjectFormat) {
+			throw new TypeError('Sources must be a string array, array of string arrays, or array of objects');
+		}
+
+		if (isStringArray) {
+			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 ?? '',
+			};
+		});
 
-	addSource(sources = [], { resolveUrl = false } = {}) {
-		// Accept 3 formats:
-		// 1. Array of objects: [{ icon, url, title, subtitle }] — from v4.7 example
-		// 2. Array of string arrays: [['iconUrl', 'url', 'text']]
-		// 3. Single string array (shorthand for format 2): ['iconUrl', 'url', 'text']
-		const isObjArray = Array.isArray(sources) && sources.every((item) => item && typeof item === 'object' && !Array.isArray(item));
-		const isStrArrayArray = Array.isArray(sources) && sources.every((item) => Array.isArray(item) && item.every((v) => typeof v === 'string'));
-		const isFlatStrArray = Array.isArray(sources) && sources.every((item) => typeof item === 'string');
-
-		if (!isObjArray && !isStrArrayArray && !isFlatStrArray) {
-			throw new TypeError('addSource(): pass an array of objects { icon, url, title, subtitle } or string arrays [iconUrl, url, text]');
-		}
-
-		let normalized;
-		if (isObjArray) {
-			normalized = sources.map((item) => ({
-				icon: item.icon ?? item.iconUrl ?? item.favicon ?? '',
-				url: item.url ?? '',
-				text: item.title ?? item.displayName ?? item.text ?? '',
-				subtitle: item.subtitle ?? 'AI',
-			}));
-		} else {
-			const arr = isFlatStrArray ? [sources] : sources;
-			normalized = arr.map(([icon = '', url = '', text = '']) => ({ icon, url, text, subtitle: 'AI' }));
-		}
-
-		const source = normalized.map(({ icon, url, text, subtitle }) => ({
+		const source = normalizedSources.map(({ icon, url, title, subtitle }) => ({
 			source_type: 'THIRD_PARTY',
-			source_display_name: text,
+			source_display_name: title,
 			source_subtitle: subtitle,
 			source_url: url,
 			favicon: {
-				url: Toolkit.resolveMedia(this.#client, icon, 'image', { resolveUrl }),
+				url: Toolkit.resolveMedia(this.#client, icon, 'image'),
 				mime_type: 'image/jpeg',
 				width: 16,
 				height: 16,
 			},
 		}));
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				sources: source,
-				__typename: 'GenAISearchResultPrimitive',
-			})
-		);
+		const submessage = this.createAlert('GenAISearchResultPrimitive');
 
-		return this;
+		const section = AIRich.newLayout('Single', {
+			sources: source,
+			__typename: 'GenAISearchResultPrimitive',
+		});
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Add a horizontally-scrollable reel of image/video items. */
-	addReels(reelsItems = [], { resolveUrl = false } = {}) {
+	addReels(reelsItems = [], { id, replace, insertAt } = {}) {
 		if (
 			!(
 				(reelsItems && typeof reelsItems === 'object' && !Array.isArray(reelsItems)) ||
@@ -415,88 +329,64 @@ class AIRich extends BaseBuilder {
 			throw new TypeError('Reels items must be an object or an array of objects');
 		}
 
-		if (!Array.isArray(reelsItems)) {
-			reelsItems = [reelsItems];
-		}
+		const items = Array.isArray(reelsItems) ? reelsItems : [reelsItems];
 
-		const reels = reelsItems.map((item) => ({
+		const reels = items.map((item) => ({
 			...item,
-			_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 }),
+			_avatar: Toolkit.resolveMedia(this.#client, item.profileIconUrl ?? item.profile_url ?? item.profile ?? '', 'image'),
+			_thumbnail: Toolkit.resolveMedia(this.#client, item.thumbnailUrl ?? item.thumbnail ?? '', 'image'),
 		}));
 
-		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 ?? '',
-					},
-				})),
+		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 ?? '',
+						},
+					})),
+				},
 			},
-		});
+		];
 
-		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 ?? '',
-			});
+		return this._addContent(section, submessages, {
+			id,
+			replace,
+			insertAt,
 		});
-
-		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;
 	}
 
-	/** 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 } = {}) {
+	addImage(imageUrl, { width, height, status = 'READY', update_text, resolveUrl = false, id, replace, insertAt } = {}) {
 		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,
@@ -505,6 +395,7 @@ class AIRich extends BaseBuilder {
 				})
 			: (() => {
 					const url = Toolkit.resolveMedia(this.#client, imageUrl, 'image', { resolveUrl });
+
 					return [
 						{
 							imagePreviewUrl: url,
@@ -514,115 +405,46 @@ class AIRich extends BaseBuilder {
 					];
 				})();
 
-		const buildCard = instant !== 'only';
-
-		if (buildCard) {
-			this._submessages.push({
-				messageType: 1,
-				gridImageMetadata: {
-					gridImageUrl: {
-						imagePreviewUrl: list[0]?.imagePreviewUrl,
-					},
-					imageUrls: list,
-				},
-			});
-		}
-
-		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;
-	}
-
-	// 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,
-			},
-		});
-
-		this._sections.push(
+		const sections = list.map(({ imagePreviewUrl }) =>
 			AIRich.newLayout('Single', {
-				image_url: {
-					image_preview_url: url.imagePreviewUrl || '',
-					image_high_res_url: url.imageHighResUrl || '',
-					source_url: url.sourceUrl || '',
+				media: {
+					url: imagePreviewUrl,
+					mime_type: 'image/png',
+					width,
+					height,
+				},
+				imagine_type: 'IMAGE',
+				status: {
+					status,
+					update_text,
 				},
-				image_text: text,
-				alignment: ALIGNMENT_NAME[alignmentNum],
-				tap_link_url: tapLinkUrl,
-				__typename: 'GenAIInlineImageUXPrimitive',
+				__typename: 'GenAIImaginePrimitive',
 			})
 		);
 
-		// Vanz@Fix (bug 42): stash for the imageMessage fallback in send()
-		this._inlineImages.push({
-			url: url.sourceUrl || url.imageHighResUrl || url.imagePreviewUrl,
-			caption: text || undefined,
-		});
+		const submessage = {
+			messageType: 1,
+			gridImageMetadata: {
+				gridImageUrl: {
+					imagePreviewUrl: list[0]?.imagePreviewUrl,
+				},
+				imageUrls: list,
+			},
+		};
 
-		return this;
+		if (id && sections.length !== 1) {
+			throw new Error('Cannot assign one id to multiple image sections');
+		}
+
+		return this._addContent(sections, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	// 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;
+	addVideo(videoUrl, { autoFill = true, status = 'READY', estimatedTime, id, replace, insertAt } = {}) {
+		const isObjectVideo = (v) => v && typeof v === 'object' && !Array.isArray(v) && v.url;
 
 		const isValidPrimitive =
 			typeof videoUrl === 'string' ||
@@ -636,17 +458,15 @@ class AIRich extends BaseBuilder {
 
 		const items = Array.isArray(videoUrl) ? videoUrl : [videoUrl];
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: '[ Video tidak dapat dimuat ]',
-		});
+		const alert = this.createAlert('GenAIImaginePrimitive (ANIMATE)');
+
+		const sections = [];
+		const submessages = [];
 
-		items.forEach((item) => {
+		for (const item of items) {
 			const isObject = isObjectVideo(item);
 
-			const url = isObject
-				? Toolkit.resolveMedia(this.#client, item.url ?? '', 'video', { resolveUrl })
-				: Toolkit.resolveMedia(this.#client, item, 'video', { resolveUrl });
+			const url = isObject ? Toolkit.resolveMedia(this.#client, item.url ?? '', 'video') : Toolkit.resolveMedia(this.#client, item, 'video');
 
 			const bufferPromise = autoFill ? Promise.resolve(url).then((u) => Toolkit.fetchBuffer(u)) : null;
 
@@ -672,17 +492,15 @@ class AIRich extends BaseBuilder {
 							height: 300,
 						})
 					: autoFill
-						? bufferPromise
-							? bufferPromise.then((b) =>
-									Toolkit.getMp4Preview(b, {
-										time: 0,
-										result: 'base64',
-									})
-								)
-							: null
+						? bufferPromise?.then((b) =>
+								Toolkit.getMp4Preview(b, {
+									time: 0,
+									result: 'base64',
+								})
+							)
 						: null;
 
-			this._sections.push(
+			sections.push(
 				AIRich.newLayout('Single', {
 					media: {
 						url,
@@ -691,34 +509,37 @@ class AIRich extends BaseBuilder {
 						duration,
 					},
 					imagine_type: 'ANIMATE',
-					status: { status: 'READY' },
+					status: {
+						status,
+						estimated_completion_time: estimatedTime != null ? Math.floor((Date.now() + estimatedTime) / 1000) : undefined,
+					},
 					thumbnail: {
 						raw_media: thumbnail,
 					},
 					__typename: 'GenAIImaginePrimitive',
 				})
 			);
-		});
-
-		return this;
-	}
+		}
 
-	/** 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');
+		if (alert !== undefined) {
+			submessages.push(alert);
 		}
 
-		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"`);
+		if (submessages.length > 1) {
+			throw new Error('Video content can only have one submessage');
 		}
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: '[ Produk tidak dapat dimuat ]',
+		return this._addContent(sections, submessages[0], {
+			id,
+			replace,
+			insertAt,
 		});
+	}
+
+	addProduct(data = {}, { id, replace, insertAt } = {}) {
+		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 items = Array.isArray(data) ? data : [data];
 
@@ -729,41 +550,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', { resolveUrl }),
+				url: Toolkit.resolveMedia(this.#client, item.image_url ?? item.image, 'image'),
 			},
 			additional_images: [
 				{
-					url: Toolkit.resolveMedia(this.#client, item.icon_url ?? item.icon, 'image', { resolveUrl }),
+					url: Toolkit.resolveMedia(this.#client, item.icon_url ?? item.icon, 'image'),
 				},
 			],
 			__typename: 'GenAIProductItemCardPrimitive',
 		}));
 
-		this._sections.push(AIRich.newLayout(Array.isArray(data) ? 'HScroll' : 'Single', Array.isArray(data) ? product : product[0]));
+		const section = AIRich.newLayout(Array.isArray(data) ? 'HScroll' : 'Single', Array.isArray(data) ? product : product[0]);
 
-		return this;
+		const submessage = this.createAlert('GenAIProductItemCardPrimitive');
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Add an inline social-post style card (or array of cards). */
-	addPost(data = {}, { resolveUrl = false } = {}) {
+	addPost(data = {}, { id, replace, insertAt } = {}) {
 		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', { resolveUrl }),
+			profile_picture_url: Toolkit.resolveMedia(this.#client, p.profile_picture_url ?? p.profile_url ?? p.profile ?? '', 'image'),
 			is_verified: !!(p.is_verified || p.verified),
-			thumbnail_url: Toolkit.resolveMedia(this.#client, p.thumbnail_url ?? p.thumbnail ?? '', 'image', { resolveUrl }),
+			thumbnail_url: Toolkit.resolveMedia(this.#client, p.thumbnail_url ?? p.thumbnail ?? '', 'image'),
 			post_caption: p.post_caption ?? p.caption ?? '',
 			likes_count: p.likes_count ?? p.like ?? 0,
 			comments_count: p.comments_count ?? p.comment ?? 0,
@@ -772,456 +593,462 @@ 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', { resolveUrl }),
+			footer_icon: Toolkit.resolveMedia(this.#client, p.footer_icon ?? p.icon ?? '', 'image'),
 			is_carousel: posts.length > 1,
 			orientation: p.orientation ?? 'LANDSCAPE',
 			post_type: p.post_type ?? 'VIDEO',
 			__typename: 'GenAIPostPrimitive',
 		}));
 
-		this._sections.push(AIRich.newLayout('HScroll', primitives));
+		const section = AIRich.newLayout('HScroll', primitives);
 
-		return this;
+		const submessage = this.createAlert('GenAIPostPrimitive');
+
+		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.
+	addMetadata(text, { id, replace, insertAt } = {}) {
+		if (typeof text !== 'string') {
+			throw new TypeError('Text must be a string');
+		}
 
-	/** 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;
-	}
+		const section = AIRich.newLayout('Single', {
+			text,
+			__typename: 'GenAIMetadataTextPrimitive',
+		});
 
-	/** 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 submessage = {
+			messageType: 2,
+			messageText: text,
+		};
 
-	/** 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;
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Un-pin `botMetadata.botResponseId`, generating a fresh crypto.randomUUID() immediately. */
-	refreshBotResponseId() {
-		this._botResponseId = crypto.randomUUID();
-		return this;
-	}
+	addTip(text, { id, replace, insertAt } = {}) {
+		if (typeof text !== 'string') {
+			throw new TypeError('Text must be a string');
+		}
 
-	// Vanz@Add 25-08-26 --- ported from temen's MessageBuilderV4.7 (hasId/getIds/peek/delete).
-	// That fork tracked every block in a unified `_nodes` array so query/delete-by-id was free;
-	// this fork instead tracks blocks in the `_blocks` Map (id -> {subItems, secItems}, populated
-	// by the constructor's Proxy on every add*/set* call that passes {id}) but never exposed a way
-	// to query or undo one after the fact — you could insertAt an id but never inspect, check, or
-	// remove it. These 4 read/delete that same Map, so no changes to the Proxy itself were needed.
+		const section = AIRich.newLayout('Single', {
+			text: 'ⓘ ' + text,
+			__typename: 'GenAIMetadataTextPrimitive',
+		});
 
-	/** Check whether a block id was registered by an earlier `add*()`/`set*()` call passing `{id}`. */
-	hasId(id) {
-		return typeof id === 'string' && this._blocks.has(id);
-	}
+		const submessage = {
+			messageType: 2,
+			messageText: text,
+		};
 
-	/** List every block id registered so far, in no particular order. */
-	getIds() {
-		return [...this._blocks.keys()];
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Inspect a registered block without modifying it. Returns `null` if `id` isn't registered. */
-	peek(id) {
-		const block = this._blocks.get(id);
-		if (!block) return null;
+	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');
+		}
 
-		return { id, sections: [...block.secItems], submessages: [...block.subItems] };
-	}
+		const isArray = Array.isArray(data);
 
-	/** Remove a previously-added block (by the `id` passed to its `add*()`/`set*()` call) from the message. Throws if `id` isn't registered. */
-	delete(id) {
-		const block = this._blocks.get(id);
-		if (!block) throw new Error(`delete(id): no block registered with id "${id}"`);
+		const items = isArray ? data : [data];
 
-		for (const item of block.subItems) {
-			const idx = this._submessages.indexOf(item);
-			if (idx !== -1) this._submessages.splice(idx, 1);
-		}
-		for (const item of block.secItems) {
-			const idx = this._sections.indexOf(item);
-			if (idx !== -1) this._sections.splice(idx, 1);
-		}
+		const widgets = items.map((item) => ({
+			__typename: 'GenAI3PExtWidgetPrimitive',
 
-		this._blocks.delete(id);
-		return this;
-	}
+			header: {
+				__typename: 'GenAI3PExtWidgetStandardHeader',
+				title: item.title ?? '',
+				...(item.header ?? {}),
+			},
 
-	/** 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');
+			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 ?? '',
+						},
+					}),
+				})),
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: text,
-		});
+				...(item.body ?? {}),
+			},
+		}));
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				text,
-				__typename: 'GenAIMetadataTextPrimitive',
-			})
-		);
+		const section = AIRich.newLayout(layout ?? (isArray ? 'HScroll' : 'Single'), isArray ? widgets : widgets[0], options);
 
-		return this;
+		const submessage = this.createAlert('GenAI3PExtWidgetStandardHeader');
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** 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');
+	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: text,
-		});
+		const isArray = Array.isArray(data);
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				text,
-				__typename: 'GenAIMetadataTextPrimitive',
-			})
-		);
+		const items = isArray ? data : [data];
 
-		return this;
-	}
+		const actions = items.map((item) => ({
+			__typename: 'GenAIFooterActionPrimitive',
 
-	// Vanz@Add 22-08-26 (v4.7) --- addHeading/addWidget/addFooterAction: 3 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.
-	// Vanz@Fix 25-08-26 --- removed addImageCard(): its GenAIImagePrimitive/preview_image+full_image
-	// shape was mis-reverse-engineered (not a real WA schema) and crashed the client renderer on
-	// arrival. addImage() already covers static image cards correctly — use that instead.
+			cta_text: item.text ?? item.cta_text ?? '',
 
-	/** 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');
-		}
+			cta_type: item.type ?? item.cta_type ?? 'OPEN_URL',
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: text,
-		});
+			cta_url: item.url ?? item.cta_url ?? '',
+		}));
 
-		this._sections.push(
-			AIRich.newLayout('Single', {
-				text,
-				__typename: 'FOATextPrimitive',
-			})
-		);
+		const section = AIRich.newLayout(layout ?? (isArray ? 'HScroll' : 'Single'), isArray ? actions : actions[0], options);
 
-		return this;
+		const submessage = this.createAlert('GenAIFooterActionPrimitive');
+
+		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];
+	addTask(data, { id, replace, insertAt } = {}) {
+		if (Array.isArray(data) && data.length === 0) {
+			throw new TypeError('Task array must not be empty');
+		}
+
+		const isValidSingle = data && typeof data === 'object' && !Array.isArray(data);
+		const isValidArray = Array.isArray(data) && data.every((item) => item && typeof item === 'object' && !Array.isArray(item));
 
-		// Vanz@Fix (bug 44) --- layout: 'Single' forces `widgets[0]` below (a "Single" layout's
-		// view_model can only ever hold one `primitive`, never a `primitives` array — see
-		// newLayout()). Previously an explicit { layout: 'Single' } combined with a multi-item
-		// array silently dropped every item past the first with no error. Fail loud instead.
-		if (layout === 'Single' && items.length > 1) {
-			throw new TypeError(`addWidget(): layout "Single" can only hold one widget (got ${items.length}) — use "HScroll"/"ActionRow" (or omit layout) for multiple`);
+		if (!isValidSingle && !isValidArray) {
+			throw new TypeError('Task must be an object or a non-empty array of objects');
 		}
 
-		items.forEach((item, i) => {
-			// header.title or top-level title required
-			const hasTitle = item?.title || item?.header?.title;
-			if (!hasTitle) {
-				throw new TypeError(`addWidget() item[${i}] is missing a required "title" (or "header.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`);
-			}
-		});
+		const isArray = Array.isArray(data);
+		const items = isArray ? data : [data];
 
-		this._submessages.push({
-			messageType: 2,
-			messageText: items.map((item) => item.header?.title ?? item.title).join(', '),
-		});
+		const tasks = items.map((item) => {
+			if (typeof item.title !== 'string' || !item.title) {
+				throw new TypeError('addTask() requires a "title"');
+			}
 
-		// Vanz@Fix (bug 45) --- auto tool_call_id used to be `idx` scoped per-item (ctas.map's own
-		// index), resetting to 0 for every widget item. Two items (or two separate addWidget()
-		// calls) that both omit tool_call_id/id ended up minting the identical auto id ("00"),
-		// so a CTA tap could route to the wrong widget's tool call. Track the counter on the
-		// instance instead so every auto-generated id is unique for this AIRich's lifetime.
-		this._widgetCtaCounter ??= 0;
-
-		const widgets = items.map((item) => {
-			const ctas = item.ctas ?? item.actions;
-			// header accepts either a string title (legacy) or an object { title, subtitle }
-			const headerTitle = item.header?.title ?? item.title;
-			const headerSubtitle = item.header?.subtitle ?? item.subtitle ?? undefined;
 			return {
-				header: {
-					title: headerTitle,
-					...(headerSubtitle !== undefined && { subtitle: headerSubtitle }),
-					__typename: 'GenAI3PExtWidgetStandardHeader',
-				},
-				body: {
-					sections: item.sections ?? [],
-					ctas: ctas.map((cta) => ({
-						label: cta.label ?? '',
-						state: cta.state ?? 'PENDING',
-						kind: cta.kind ?? 'OTHER',
-						tool_call_id: cta.tool_call_id ?? cta.id ?? String(this._widgetCtaCounter++).padStart(2, '0'),
-						...(cta.toast !== false && {
-							toast: { label: typeof cta.toast === 'string' ? cta.toast : headerTitle, __typename: 'GenAI3PExtWidgetToast' },
-						}),
-						__typename: 'GenAI3PExtWidgetCTA',
-					})),
-					__typename: item.body_typename ?? 'GenAI3PExtCalendarEventList',
-				},
-				__typename: 'GenAI3PExtWidgetPrimitive',
+				task_id: item.task_id ?? '',
+				title: item.title,
+				subtitle: item.subtitle ?? '',
+				status: item.status ?? 'PENDING',
+				__typename: 'GenAITaskPrimitive',
 			};
 		});
 
-		const resolvedLayout = layout ?? (Array.isArray(data) ? 'HScroll' : 'Single');
-		const asArray = resolvedLayout !== 'Single';
+		const section = AIRich.newLayout(isArray ? 'HScroll' : 'Single', isArray ? tasks : tasks[0]);
 
-		this._sections.push(AIRich.newLayout(resolvedLayout, asArray ? widgets : widgets[0]));
+		const submessage = this.createAlert('GenAITaskPrimitive');
 
-		return this;
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/**
-	 * 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];
+	addQuotaUpsell(data, { id, replace, insertAt } = {}) {
+		if (!data || typeof data !== 'object' || Array.isArray(data)) {
+			throw new TypeError('Quota upsell must be an object');
+		}
 
-		items.forEach((item, i) => {
-			if (!item?.text || !item?.url) {
-				throw new TypeError(`addFooterAction() item[${i}] requires both "text" and "url"`);
-			}
-		});
+		if (typeof data.title !== 'string' || !data.title) {
+			throw new TypeError('addQuotaUpsell() requires a "title"');
+		}
 
-		const primitives = items.map((item) => ({
-			cta_text: item.text,
-			cta_type: item.type ?? 'OPEN_URL',
-			cta_url: item.url,
-			__typename: 'GenAIFooterActionPrimitive',
-		}));
+		const buttons = Array.isArray(data.buttons) ? data.buttons : [];
 
-		this._sections.push(AIRich.newLayout('HScroll', primitives));
+		const primitive = {
+			__typename: 'GenAIMetaSubsQuotaUpsellPrimitive',
+			title: data.title,
+			body_line1: data.body_line1 ?? data.body ?? '',
+			body_line2: data.body_line2 ?? '',
+
+			buttons: buttons.map((btn) => ({
+				__typename: 'GenAIMetaSubsQuotaUpsellButton',
+				label: btn.label ?? '',
+				action: btn.action ?? 'OPEN_DEEPLINK',
+				deeplink: btn.deeplink ?? '',
+			})),
+		};
 
-		return this;
+		const section = AIRich.newLayout('Single', primitive);
+
+		const submessage = this.createAlert('GenAIMetaSubsQuotaUpsellPrimitive');
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	// 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.
-
-	/** 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;
+	/** GenAIDividerPrimitive — plain horizontal line, no content. */
+	addDivider({ id, replace, insertAt } = {}) {
+		const section = AIRich.newLayout('Single', {
+			__typename: 'GenAIDividerPrimitive',
+		});
+
+		return this._addContent(section, undefined, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** 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;
+	/** GenAISpacerPrimitive — blank vertical spacing. */
+	addSpacer(spacing, { id, replace, insertAt } = {}) {
+		const section = AIRich.newLayout('Single', {
+			spacing,
+			__typename: 'GenAISpacerPrimitive',
+		});
+
+		return this._addContent(section, undefined, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
 	/**
-	 * 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$$'`.
+	 * GenAILatexItem — corrected after cross-checking an older, actually-shipped build
+	 * (MessageBuilder v4.7, pre-dates this primitive-card guess). LaTeX in this ecosystem
+	 * is NOT a standalone card — the real, working mechanism is an inline entity inside
+	 * addText()'s own extractIE() parser (`[expr|width|height|font_height|padding]<imageUrl>`
+	 * syntax), and it requires a PRE-RENDERED image of the equation — WhatsApp does not
+	 * render raw LaTeX text client-side. The previous addLatex() (standalone
+	 * GenAILatexUXPrimitive card, text-only) was confirmed via eval to render blank because
+	 * that primitive/approach never existed in the first place. This version is a thin
+	 * wrapper around the real, already-working addText() inline syntax.
 	 */
-	addLatex(expression) {
+	addLatex(expression, { url, width, height, font_height, padding, id, replace, insertAt } = {}) {
 		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 }] },
+
+		if (!url) {
+			throw new TypeError('addLatex() requires a pre-rendered equation image "url" — WhatsApp renders LaTeX as an inline image, not raw text');
+		}
+
+		const extras = [width, height, font_height, padding];
+
+		while (extras.length && extras[extras.length - 1] == null) {
+			extras.pop();
+		}
+
+		const raw = [expression, ...extras].join('|');
+
+		return this.addText(`[${raw}]<${url}>`, {
+			id,
+			replace,
+			insertAt,
 		});
-		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
+	 * GenAIInlineImageUXPrimitive — messageType 3 (INLINE_IMAGE) submessage, field layout
+	 * ported from rich-message-utils.js toUnified() INLINE_IMAGE case (same image-url-object
+	 * fix as addImage()/bug 40 round 2), not guessed from the .d.ts alone.
 	 */
-	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' }));
+	addInlineImage(imageUrl, { text = '', alignment = 'center', tapLinkUrl = '', resolveUrl = false, id, replace, insertAt } = {}) {
+		if (!(typeof imageUrl === 'string' || Buffer.isBuffer(imageUrl))) {
+			throw new TypeError('imageUrl must be string | buffer');
 		}
-		return this;
+
+		const url = Toolkit.resolveMedia(this.#client, imageUrl, 'image', { resolveUrl });
+
+		const ALIGNMENT_INDEX = { 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 alignmentIndex = ALIGNMENT_INDEX[String(alignment).toLowerCase()] ?? ALIGNMENT_INDEX.center;
+
+		const section = AIRich.newLayout('Single', {
+			image_url: {
+				image_preview_url: url,
+				image_high_res_url: url,
+				source_url: url,
+			},
+			image_text: text,
+			alignment: ALIGNMENT_NAME[alignmentIndex],
+			tap_link_url: tapLinkUrl,
+			__typename: 'GenAIInlineImageUXPrimitive',
+		});
+
+		const submessage = {
+			messageType: 3,
+			imageMetadata: {
+				imageUrl: { imagePreviewUrl: url, imageHighResUrl: url, sourceUrl: url },
+				imageText: text,
+				alignment: alignmentIndex,
+				tapLinkUrl,
+			},
+		};
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
 	/**
-	 * 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]
+	 * GenAIContentItemsUXPrimitive — messageType 9 (CONTENT_ITEMS) submessage, ported from
+	 * rich-message-utils.js toUnified() CONTENT_ITEMS case (bug 40: was returning {}).
 	 */
-	addProgressStatus(title, { icon = 'SEARCH', is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id } = {}) {
+	addContentItems(items = [], { content_type = 1, id, replace, insertAt } = {}) {
+		if (!Array.isArray(items)) {
+			throw new TypeError('addContentItems() requires an array of items');
+		}
+
+		const section = AIRich.newLayout('Single', {
+			items,
+			content_type,
+			__typename: 'GenAIContentItemsUXPrimitive',
+		});
+
+		const submessage = {
+			messageType: 9,
+			contentItemsMetadata: {
+				itemsMetadata: items,
+				contentType: content_type,
+			},
+		};
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
+	}
+
+	/** GenAIBotProgressStatusPrimitive — one-shot "searching/working" status chip. */
+	addProgressStatus(title, { icon, is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id, id, replace, insertAt } = {}) {
 		if (typeof title !== 'string' || !title) {
-			throw new TypeError('addProgressStatus(title) requires a non-empty string');
+			throw new TypeError('addProgressStatus() requires a "title"');
 		}
-		this._submessages.push({ messageType: 2, messageText: title });
-		const primitive = {
+
+		const section = AIRich.newLayout('Single', {
 			title,
 			icon,
 			is_in_progress,
-			meta_search_apps: [],
+			target_secondary_screen_id,
+			target_secondary_screen_tab_id,
 			__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;
+		});
+
+		const submessage = this.createAlert('GenAIBotProgressStatusPrimitive');
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** 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 } = {}) {
+	/** GenAIBotThinkingStatusPrimitive — one-shot "thinking" status chip. */
+	addThinkingStatus(title, { icon, is_in_progress = true, target_secondary_screen_id, target_secondary_screen_tab_id, textFallback = true, id, replace, insertAt } = {}) {
 		if (typeof title !== 'string' || !title) {
-			throw new TypeError('addThinkingStatus(title) requires a non-empty string');
+			throw new TypeError('addThinkingStatus() requires a "title"');
 		}
-		this._submessages.push({ messageType: 2, messageText: title });
-		const primitive = {
+
+		const section = AIRich.newLayout('Single', {
 			title,
 			icon,
 			is_in_progress,
-			meta_search_apps: [],
+			target_secondary_screen_id,
+			target_secondary_screen_tab_id,
 			__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;
+		});
+
+		const submessage = textFallback ? this.createAlert('GenAIBotThinkingStatusPrimitive') : undefined;
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/**
-	 * 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"');
+	/** FOABloksPrimitive — raw Bloks payload; most experimental primitive, fields passed through as-is. */
+	addBloks(data, { id, replace, insertAt } = {}) {
+		if (!data || typeof data !== 'object' || Array.isArray(data)) {
+			throw new TypeError('Bloks payload must be an object');
 		}
-		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) {
+		if (typeof data.type !== 'string' || !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 ?? '',
+
+		const { textFallback = true, ...rest } = data;
+
+		const section = AIRich.newLayout('Single', {
+			...rest,
 			__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;
+		});
+
+		const submessage = textFallback ? this.createAlert('FOABloksPrimitive') : undefined;
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
+	}
+
+	/**
+	 * GenAIImaginePrimitive with status GENERATING — pending-generation placeholder.
+	 * Mirrors addVideo()'s ANIMATE/GENERATING branch but with no media yet.
+	 */
+	addGenerating({ imagine_type = 'IMAGE', estimated_completion_time, textFallback = true, id, replace, insertAt } = {}) {
+		const section = AIRich.newLayout('Single', {
+			imagine_type,
+			status: {
+				status: 'GENERATING',
+				// Matches addVideo()'s convention: input is a ms-from-now duration, stored as a unix-seconds timestamp.
+				estimated_completion_time: estimated_completion_time != null ? Math.floor((Date.now() + estimated_completion_time) / 1000) : undefined,
+			},
+			__typename: 'GenAIImaginePrimitive',
+		});
+
+		const submessage = textFallback ? this.createAlert(`GenAIImaginePrimitive (${imagine_type === 'ANIMATE' ? 'ANIMATE' : 'IMAGE'} GENERATING)`) : undefined;
+
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** Add tappable follow-up suggestion chips below the message. @param {string|string[]} suggestion */
-	addSuggest(suggestion, { scroll = true, layout } = {}) {
+	addSuggest(suggestion, { scroll = true, layout, id, replace, insertAt } = {}) {
 		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');
 		}
@@ -1242,18 +1069,28 @@ class AIRich extends BaseBuilder {
 
 		const type = layout ?? (suggest.length === 1 ? 'Single' : scroll ? 'HScroll' : 'ActionRow');
 
-		this._sections.push(AIRich.newLayout(type, type === 'Single' ? suggest[0] : suggest, { __typename: 'GenAIUnifiedResponseSection' }));
+		const section = AIRich.newLayout(type, type === 'Single' ? suggest[0] : suggest, {
+			__typename: 'GenAIUnifiedResponseSection',
+		});
+
+		const submessage = this.createAlert('GenAIFollowUpSuggestionPillPrimitive');
 
-		return this;
+		return this._addContent(section, submessage, {
+			id,
+			replace,
+			insertAt,
+		});
 	}
 
-	/** @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 } = {}) {
+	async build(
+		jid,
+		{ bypassDownload = true, forwarded = true, notification = false, includesUnifiedResponse = true, includesSubmessages = true, quoted, quotedParticipant, messageId, ...options } = {}
+	) {
 		const forward = forwarded
 			? {
 					forwardingScore: 1,
 					isForwarded: true,
-					forwardedAiBotMessageInfo: { botJid: '0@bot' },
+					forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' },
 					forwardOrigin: 4,
 				}
 			: {};
@@ -1271,7 +1108,7 @@ class AIRich extends BaseBuilder {
 		const qObj = quoted
 			? {
 					stanzaId: quoted?.key?.id || quoted?.id,
-					participant: quotedParticipant || quoted?.key?.participant || quoted?.key?.remoteJid,
+					participant: quotedParticipant || quoted?.key?.participant || quoted?.participant || quoted?.key?.remoteJid,
 					quotedType: 0,
 					quotedMessage: typeof quoted === 'object' && quoted !== null ? (quoted.message ?? quoted) : undefined,
 				}
@@ -1287,140 +1124,91 @@ class AIRich extends BaseBuilder {
 				]
 			: [...(await waitAllPromises(this._sections))];
 
-		// 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();
+		if (this._dynamic) {
+			this.refreshResponseId();
+			this.refreshBotResponseId();
+		}
 
-		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(),
-							},
-						],
+		return generateWAMessageFromContent(
+			jid,
+			{
+				messageContextInfo: {
+					deviceListMetadata: {},
+					deviceListMetadataVersion: 2,
+					botMetadata: {
+						messageDisclaimerText: this._title,
+						...notif,
+						verificationMetadata: AIRich.generateVerificationMetadata(),
+						botResponseId: this._botResponseId,
 					},
-					...notif,
 				},
-			},
-			...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,
+				...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') : '',
+							},
+							originalRecipientMetadata: {
+								data: includesUnifiedResponse ? Buffer.from(Toolkit.stringifyEscaped({ response_id: this._responseId, sections })).toString('base64') : '',
+							},
+							contextInfo: {
+								...forward,
+								...qObj,
+								...this._contextInfo,
+							},
 						},
 					},
 				},
 			},
-		};
+			{ messageId: messageId || generateMessageIDV2(), ...options }
+		);
 	}
 
-	// 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');
-				}
-			}
+	async buildEdit(targetJid, targetId, { msg, messageId, ...options } = {}) {
+		if (!msg) {
+			msg = (await this.build(targetJid, options)).message;
 		}
 
-		// 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 }));
+		const editedMessage = msg;
 
 		if (!editedMessage) {
-			throw new Error('buildEdit: no message content to edit (build() returned nothing)');
+			throw new Error('buildEdit: msg does not contain botForwardedMessage');
 		}
 
 		return generateWAMessageFromContent(
 			targetJid,
 			{
-				protocolMessage: {
-					key: {
-						remoteJid: targetJid,
-						fromMe: true,
-						id: targetId,
+				botForwardedMessage: {
+					message: {
+						protocolMessage: {
+							key: {
+								remoteJid: targetJid,
+								fromMe: true,
+								id: targetId,
+							},
+							type: 14,
+							editedMessage,
+						},
 					},
-					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('sendEdit: no jid — pass one explicitly, or call send() first');
+			throw new Error('JID is required');
 		}
 
 		if (!id) {
-			throw new Error('sendEdit: no message id — pass one explicitly, or call send() first');
+			throw new Error('Message id is required');
 		}
 
 		const msgEdit = await this.buildEdit(jid, id, {
@@ -1434,13 +1222,36 @@ 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;
 	}
 
-	/** 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. */
+	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;
+	}
+
 	static tokenizer(code, lang = 'javascript') {
 		const keywordsMap = {
 			javascript: new Set([
@@ -2106,7 +1917,6 @@ 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');
@@ -2155,120 +1965,35 @@ class AIRich extends BaseBuilder {
 		};
 	}
 
-	/**
-	 * 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',
-			})
+	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`
 		);
-		// 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;
-	}
-
-	/**
-	 * 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,
-				}),
-			},
-		};
-
-		return client.relayMessage(jid, msg, {
-			additionalNodes: [
-				{ tag: 'bot', attrs: { biz_bot: '1' } },
-				{ tag: 'biz', attrs: {} },
-			],
-		});
-	}
-
-	/**
-	 * 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"');
 
-		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 }
+		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 imageMsg = generateWAMessageFromContent(
-			jid,
-			{
-				imageMessage: {
-					...imagePrepared.imageMessage,
-					contextInfo: { pairedMediaType: 5, statusSourceType: 0 },
-				},
-			},
-			{}
-		);
+		const signature = Buffer.concat([signatureMaterial, crypto.randomBytes(64 - signatureMaterial.length)]).toString('base64');
 
-		await client.relayMessage(jid, imageMsg.message, { messageId: imageMsg.key.id });
+		const certificateChain = [
+			Buffer.concat([certificateMaterial, crypto.randomBytes(684 - certificateMaterial.length)]).toString('base64'),
 
-		await client.relayMessage(
-			jid,
-			{
-				videoMessage: {
-					...videoPrepared.videoMessage,
-					contextInfo: { pairedMediaType: 6, statusSourceType: 0 },
-				},
-				messageContextInfo: {
-					messageAssociation: { associationType: 12, parentMessageKey: imageMsg.key },
-				},
-			},
-			{}
-		);
+			Buffer.concat([certificateMaterial, crypto.randomBytes(892 - certificateMaterial.length)]).toString('base64'),
+		];
 
-		return imageMsg.key;
+		return {
+			proofs: [
+				{
+					version: 1,
+					useCase: 1,
+					signature,
+					certificateChain,
+				},
+			],
+		};
 	}
 
-	/** Build a raw submessage layout block by name — escape hatch for layouts not covered by the add*() helpers. */
 	static newLayout(name, data, extra = {}) {
 		return {
 			...extra,
@@ -2278,9 +2003,324 @@ class AIRich extends BaseBuilder {
 			},
 		};
 	}
+
+	_makeNode(id, section, submessage) {
+		return { id: id ?? null, section: section ?? null, submessage: submessage ?? null };
+	}
+
+	_registerId(node, id) {
+		if (id === undefined || id === null || id === '') return;
+
+		if (typeof id !== 'string') {
+			throw new ContentValidationError('Item id must be a string', { id });
+		}
+
+		if (this._idIndex.has(id)) {
+			throw new DuplicateIdError(id);
+		}
+
+		node.id = id;
+		this._idIndex.set(id, node);
+	}
+
+	_unregisterId(node) {
+		if (node.id && this._idIndex.get(node.id) === node) {
+			this._idIndex.delete(node.id);
+		}
+	}
+
+	hasId(id) {
+		return typeof id === 'string' && this._idIndex.has(id);
+	}
+
+	getIds() {
+		return [...this._idIndex.keys()];
+	}
+
+	peek(id) {
+		const node = this._idIndex.get(id);
+
+		if (!node) return null;
+
+		return {
+			id: node.id,
+			section: node.section,
+			submessage: node.submessage,
+		};
+	}
+
+	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 [];
+		});
+	}
 }
 
-/** Thin no-op subclass of `AIRich` — kept for drop-in compatibility with code ported from ourin-baileys that references `ORich` by name. */
+
+/** Compatibility alias. */
 class ORich extends AIRich {}
 
 export { AIRich, ORich };