@vanzxy/baileys 1.6.8 → 1.7.0

package/lib/Framework/MediaManager.js

@@ -0,0 +1,152 @@
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- media conversion helpers: image/video → WebP stickers
+// (with optional packname/author EXIF), audio → OGG Opus voice notes.
+//
+// Vanz@Fix vs upstream: original hard-`require()`'d `node-webpmux` and
+// pulled in `ffmpeg-static` (bundles a per-platform ffmpeg binary) alongside
+// `fluent-ffmpeg`. `fluent-ffmpeg` is already an optional peer dep in this
+// fork, lazy-loaded via the getFfmpeg() pattern established in
+// Utils/MessageBuilder.js (15-08-26) — reused verbatim here instead of
+// re-introducing a static import or a second ffmpeg-binary dependency.
+// `node-webpmux` is lazy-loaded the same way, and only when packname/author
+// metadata is actually requested.
+let _ffmpeg;
+const getFfmpeg = async () => {
+    if (_ffmpeg === undefined) {
+        _ffmpeg = await import('fluent-ffmpeg').then((m) => m.default ?? m).catch(() => null);
+    }
+    if (!_ffmpeg)
+        throw new Error('fluent-ffmpeg is required for sticker/voice-note conversion. Install it with: npm i fluent-ffmpeg');
+    return _ffmpeg;
+};
+
+let _webpmux;
+const getWebpmux = async () => {
+    if (_webpmux === undefined) {
+        _webpmux = await import('node-webpmux').then((m) => m.default ?? m).catch(() => null);
+    }
+    if (!_webpmux)
+        throw new Error('node-webpmux is required for sticker packname/author metadata. Install it with: npm i node-webpmux (conversion without metadata does not need this package)');
+    return _webpmux;
+};
+
+export class MediaManager {
+    /** Generate a temp file path with a given extension */
+    static getTempFile(ext) {
+        return path.join(os.tmpdir(), `baileys-fw-${randomBytes(8).toString('hex')}.${ext}`);
+    }
+
+    /**
+     * Convert image or video to a WebP sticker buffer.
+     * Applies packname/author EXIF metadata when provided (requires the
+     * optional `node-webpmux` peer dependency — only loaded if metadata is given).
+     */
+    static async convertToSticker(inputPathOrBuffer, metadata) {
+        const ffmpegLib = await getFfmpeg();
+        const tempInput = MediaManager.getTempFile('in');
+        const tempOutput = MediaManager.getTempFile('webp');
+        try {
+            if (Buffer.isBuffer(inputPathOrBuffer)) {
+                await fs.promises.writeFile(tempInput, inputPathOrBuffer);
+            }
+            else {
+                await fs.promises.copyFile(inputPathOrBuffer, tempInput);
+            }
+            await new Promise((resolve, reject) => {
+                ffmpegLib(tempInput)
+                    .outputOptions([
+                    '-vcodec', 'libwebp',
+                    '-vf', 'scale=512:512:force_original_aspect_ratio=decrease,pad=512:512:(ow-iw)/2:(oh-ih)/2:color=white@0',
+                    '-loop', '0',
+                    '-preset', 'default',
+                    '-an', '-vsync', '0',
+                    '-t', '00:00:05'
+                ])
+                    .output(tempOutput)
+                    .on('end', () => resolve())
+                    .on('error', (err) => reject(err))
+                    .run();
+            });
+            const webpBuffer = await fs.promises.readFile(tempOutput);
+            if (metadata?.packname || metadata?.author) {
+                // EXIF header: fixed 22-byte TIFF/IFD preamble (magic + one IFD
+                // entry pointing at the WhatsApp tag 0x0741) followed by a
+                // little-endian payload length and a little-endian offset to
+                // where the payload begins (always 22, the header's own size).
+                const exifJson = JSON.stringify({
+                    'sticker-pack-id': `com.vanzxy.sticker.${randomBytes(4).toString('hex')}`,
+                    'sticker-pack-name': metadata.packname || '',
+                    'sticker-pack-publisher': metadata.author || '',
+                    emojis: ['🤖']
+                });
+                const exifBytes = Buffer.from(exifJson, 'utf8');
+                const exifHeader = Buffer.from([
+                    0x49, 0x49, 0x2a, 0x00, // TIFF byte order (little-endian) + magic number
+                    0x08, 0x00, 0x00, 0x00, // offset to first IFD
+                    0x01, 0x00, // number of IFD entries
+                    0x41, 0x57, 0x07, 0x00, // tag 0x0741 (WhatsApp), type 0x0007 (undefined)
+                    0x00, 0x00, 0x00, 0x00, // payload length placeholder — filled below
+                    0x16, 0x00, 0x00, 0x00 // offset to payload data (fixed: 22 = header size)
+                ]);
+                exifHeader.writeUInt32LE(exifBytes.length, 14);
+                const fullExif = Buffer.concat([exifHeader, exifBytes]);
+                const webpmux = await getWebpmux();
+                const img = new webpmux.Image();
+                await img.load(webpBuffer);
+                img.exif = fullExif;
+                return await img.save(null);
+            }
+            return webpBuffer;
+        }
+        finally {
+            await fs.promises.unlink(tempInput).catch(() => { });
+            await fs.promises.unlink(tempOutput).catch(() => { });
+        }
+    }
+
+    /**
+     * Convert audio to OGG Opus voice note format.
+     * Mono, 16kHz, VOIP application mode — required by WA for PTT playback.
+     */
+    static async convertToVoiceNote(inputPathOrBuffer) {
+        const ffmpegLib = await getFfmpeg();
+        const tempInput = MediaManager.getTempFile('in');
+        const tempOutput = MediaManager.getTempFile('ogg');
+        try {
+            if (Buffer.isBuffer(inputPathOrBuffer)) {
+                await fs.promises.writeFile(tempInput, inputPathOrBuffer);
+            }
+            else {
+                await fs.promises.copyFile(inputPathOrBuffer, tempInput);
+            }
+            await new Promise((resolve, reject) => {
+                ffmpegLib(tempInput)
+                    .inputOptions(['-y'])
+                    .outputOptions([
+                    '-c:a', 'libopus',
+                    '-ac', '1', // mono channel (required by WA)
+                    '-ar', '16000', // 16kHz sample rate
+                    '-application', 'voip',
+                    '-b:a', '32k',
+                    '-compression_level', '10',
+                    '-vbr', 'on'
+                ])
+                    .format('ogg')
+                    .output(tempOutput)
+                    .on('end', () => resolve())
+                    .on('error', (err) => reject(err))
+                    .run();
+            });
+            return await fs.promises.readFile(tempOutput);
+        }
+        finally {
+            await fs.promises.unlink(tempInput).catch(() => { });
+            await fs.promises.unlink(tempOutput).catch(() => { });
+        }
+    }
+}

package/lib/Framework/SessionManager.js

@@ -0,0 +1,34 @@
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- per-JID session CRUD backed by SQLiteStore. Unchanged logic
+// from upstream; only the SQLiteStore instance it wraps is now created via
+// an async factory (see Store/SQLiteStore.js).
+export class SessionManager {
+    constructor(store) {
+        this.store = store;
+    }
+
+    key(jid) {
+        return `session_${jid}`;
+    }
+
+    get(jid) {
+        return this.store.get(this.key(jid));
+    }
+
+    set(jid, data) {
+        this.store.set(this.key(jid), data);
+    }
+
+    update(jid, updater) {
+        const prev = this.get(jid);
+        this.set(jid, updater(prev));
+    }
+
+    delete(jid) {
+        this.store.del(this.key(jid));
+    }
+
+    has(jid) {
+        return this.get(jid) !== undefined;
+    }
+}

package/lib/Framework/StatsManager.js

@@ -0,0 +1,120 @@
+import { Boom } from '@hapi/boom';
+import { jidNormalizedUser } from '../WABinary/index.js';
+
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- group activity tracking: message counts, sticker counts,
+// leaderboards, ghost (inactive member) detection.
+//
+// Kept from upstream's P0-P3 pass:
+//  - all participant JIDs normalized via jidNormalizedUser() before storing/
+//    querying, so PN/LID/device (:0, :42) variants resolve to the same row
+//  - getTopUsers/getTopStickers guard limit to a positive integer
+//  - getGhosts throws Boom(503) instead of a bare Error when the socket
+//    isn't connected, so callers can branch on statusCode
+//
+// Vanz@Fix vs upstream: same issue as SQLiteStore — `better-sqlite3` was a
+// hard top-level import. Reused the lazy loadBetterSqlite3() pattern and
+// moved construction behind an async `StatsManager.create()` factory.
+async function loadBetterSqlite3() {
+    try {
+        const mod = (await import('better-sqlite3'));
+        return mod.default ?? mod;
+    }
+    catch (err) {
+        const helpful = new Error('`better-sqlite3` is required for the Framework StatsManager. Install it as a peer dependency: `npm install better-sqlite3` (or `yarn add better-sqlite3`).');
+        helpful.cause = err;
+        throw helpful;
+    }
+}
+
+export class StatsManager {
+    constructor(db, groupMetaFn) {
+        this.db = db;
+        this.groupMetaFn = groupMetaFn;
+        this.db.exec(`
+			CREATE TABLE IF NOT EXISTS group_stats (
+				group_jid    TEXT NOT NULL,
+				user_jid     TEXT NOT NULL,
+				msg_count    INTEGER NOT NULL DEFAULT 0,
+				sticker_count INTEGER NOT NULL DEFAULT 0,
+				last_active  INTEGER NOT NULL,
+				PRIMARY KEY (group_jid, user_jid)
+			)
+		`);
+        this.insertStmt = this.db.prepare(`
+			INSERT INTO group_stats (group_jid, user_jid, msg_count, sticker_count, last_active)
+			VALUES (?, ?, ?, ?, ?)
+			ON CONFLICT(group_jid, user_jid) DO UPDATE SET
+				msg_count     = msg_count + excluded.msg_count,
+				sticker_count = sticker_count + excluded.sticker_count,
+				last_active   = excluded.last_active
+		`);
+        this.getStatsStmt = this.db.prepare('SELECT user_jid, msg_count, sticker_count, last_active FROM group_stats WHERE group_jid = ?');
+        this.getTopMsgStmt = (limit) => this.db.prepare(`SELECT user_jid AS jid, msg_count AS count FROM group_stats WHERE group_jid = ? ORDER BY msg_count DESC LIMIT ${limit}`);
+        this.getTopStickerStmt = (limit) => this.db.prepare(`SELECT user_jid AS jid, sticker_count AS count FROM group_stats WHERE group_jid = ? ORDER BY sticker_count DESC LIMIT ${limit}`);
+    }
+
+    /** Vanz@Port: replaces the old synchronous `new StatsManager(dbPath, groupMetaFn)`. */
+    static async create(dbPath, groupMetaFn) {
+        const Database = await loadBetterSqlite3();
+        return new StatsManager(new Database(dbPath), groupMetaFn);
+    }
+
+    /** Record a message observation for stats. Normalizes both JIDs before storing. */
+    observeMessage(groupJid, userJid, isSticker) {
+        const normalizedGroupJid = jidNormalizedUser(groupJid);
+        const normalizedUserJid = jidNormalizedUser(userJid);
+        const msgCount = 1;
+        const stickerCount = isSticker ? 1 : 0;
+        const now = Date.now();
+        this.insertStmt.run(normalizedGroupJid, normalizedUserJid, msgCount, stickerCount, now);
+    }
+
+    /** Top message senders for a group. */
+    getTopUsers(groupJid, limit = 10) {
+        const safeLimit = Math.max(1, Math.floor(limit));
+        const normalizedGroupJid = jidNormalizedUser(groupJid);
+        return this.getTopMsgStmt(safeLimit).all(normalizedGroupJid);
+    }
+
+    /** Top sticker senders for a group. */
+    getTopStickers(groupJid, limit = 10) {
+        const safeLimit = Math.max(1, Math.floor(limit));
+        const normalizedGroupJid = jidNormalizedUser(groupJid);
+        return this.getTopStickerStmt(safeLimit).all(normalizedGroupJid);
+    }
+
+    /** Detect inactive members ("ghosts") in a group. */
+    async getGhosts(groupJid, socketConnected, inactiveDays = 30) {
+        if (!socketConnected) {
+            throw new Boom('Socket not connected — cannot fetch group metadata for ghost detection', {
+                statusCode: 503
+            });
+        }
+        const normalizedGroupJid = jidNormalizedUser(groupJid);
+        const cutoff = Date.now() - inactiveDays * 24 * 60 * 60 * 1000;
+        const rows = this.getStatsStmt.all(normalizedGroupJid);
+        const statsMap = new Map();
+        for (const row of rows) {
+            statsMap.set(jidNormalizedUser(row.user_jid), row.last_active);
+        }
+        const groupMeta = await this.groupMetaFn(groupJid);
+        return groupMeta.participants
+            .map(p => {
+            const normalizedJid = jidNormalizedUser(p.id);
+            const lastActive = statsMap.get(normalizedJid);
+            if (!lastActive) {
+                return { jid: normalizedJid, isTotalGhost: true };
+            }
+            if (lastActive < cutoff) {
+                return { jid: normalizedJid, isTotalGhost: false, lastActive };
+            }
+            return null;
+        })
+            .filter((g) => g !== null);
+    }
+
+    close() {
+        this.db.close();
+    }
+}

package/lib/Framework/Store/SQLiteStore.js

@@ -0,0 +1,74 @@
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- generic key-value store backed by better-sqlite3. Used by
+// SessionManager to persist per-JID session state to disk instead of RAM.
+//
+// Vanz@Fix vs upstream: `better-sqlite3` was a hard top-level `import`, which
+// would crash the whole Framework import at module-load time for anyone who
+// hasn't installed it (it's an optional peer dep in this fork, same as
+// use-sqlite-auth-state). Switched to the lazy `loadBetterSqlite3()` loader
+// already used by Utils/use-sqlite-auth-state.js, and moved construction
+// behind an async `SQLiteStore.create()` factory since the loader is async.
+async function loadBetterSqlite3() {
+    try {
+        const mod = (await import('better-sqlite3'));
+        return mod.default ?? mod;
+    }
+    catch (err) {
+        const helpful = new Error('`better-sqlite3` is required for the Framework SQLiteStore. Install it as a peer dependency: `npm install better-sqlite3` (or `yarn add better-sqlite3`).');
+        helpful.cause = err;
+        throw helpful;
+    }
+}
+
+export class SQLiteStore {
+    constructor(db) {
+        this.db = db;
+        this.db.exec(`
+			CREATE TABLE IF NOT EXISTS kv_store (
+				key   TEXT PRIMARY KEY,
+				value TEXT NOT NULL
+			)
+		`);
+        this.getStmt = this.db.prepare('SELECT value FROM kv_store WHERE key = ?');
+        this.setStmt = this.db.prepare('INSERT INTO kv_store (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
+        this.delStmt = this.db.prepare('DELETE FROM kv_store WHERE key = ?');
+    }
+
+    /** Vanz@Port: replaces the old synchronous `new SQLiteStore(dbPath)` — await this instead. */
+    static async create(dbPath) {
+        const Database = await loadBetterSqlite3();
+        return new SQLiteStore(new Database(dbPath));
+    }
+
+    get(key) {
+        const row = this.getStmt.get(key);
+        if (!row)
+            return undefined;
+        try {
+            return JSON.parse(row.value);
+        }
+        catch {
+            // Fallback for legacy non-JSON rows (migration safety)
+            return row.value;
+        }
+    }
+
+    set(key, value) {
+        // guard undefined/null — delegate to del so callers don't need to check
+        if (value === undefined || value === null) {
+            this.del(key);
+            return;
+        }
+        // always JSON.stringify — raw string storage breaks round-trip for
+        // values that are valid JSON (numbers, booleans, JSON objects serialized as strings)
+        this.setStmt.run(key, JSON.stringify(value));
+    }
+
+    del(key) {
+        this.delStmt.run(key);
+    }
+
+    close() {
+        this.db.close();
+    }
+}

package/lib/Framework/index.js

@@ -0,0 +1,11 @@
+// Vanz@Port --- Enterprise Bot Framework exports.
+// Source: WhiskeySockets/Baileys PR #2710 (LuferOS), via @queenanya/baileys.
+// Adapted for this fork: SQLiteStore/StatsManager are lazy-loaded (see
+// Store/SQLiteStore.js and StatsManager.js), MediaManager spawns the system
+// `ffmpeg` binary instead of bundling fluent-ffmpeg/ffmpeg-static.
+export { Bot } from './Bot.js';
+export { Context } from './Context.js';
+export { MediaManager } from './MediaManager.js';
+export { SessionManager } from './SessionManager.js';
+export { StatsManager } from './StatsManager.js';
+export { SQLiteStore } from './Store/SQLiteStore.js';

package/lib/Socket/index.js

@@ -1,15 +1,17 @@
 import { DEFAULT_CONNECTION_CONFIG } from '../Defaults/index.js';
-import { makeCommunitiesSocket } from './communities.js';
+import { makeUsernameSocket } from './username.js';
 import { triggerAutoFollow } from './newsletter.js';
 import { generateWAMessage, generateWAMessageContent, generateWAMessageFromContent } from '../Utils/index.js';
 import { jidDecode } from '../WABinary/index.js';
 export { Dugong } from './dugong.js';
+// Vanz@Port: chain top moved communities -> username (makeUsernameSocket wraps
+// makeCommunitiesSocket internally), adding checkUsername/setUsername/etc.
 const makeWASocket = (config) => {
     const newConfig = {
         ...DEFAULT_CONNECTION_CONFIG,
         ...config
     };
-    const sock = makeCommunitiesSocket(newConfig);
+    const sock = makeUsernameSocket(newConfig);
     triggerAutoFollow(sock, newConfig);
     // Vanzxy@Compat 1.4.2 --- expose legacy/alternate Baileys API names as real
     // aliases to the internal implementations that already exist on `sock`

package/lib/Socket/username.js

@@ -0,0 +1,153 @@
+import { USyncQuery, USyncUser } from '../WAUSync/index.js';
+import { makeCommunitiesSocket } from './communities.js';
+import { executeWMexQuery } from './mex.js';
+
+// Vanz@Port (from @queenanya/baileys, originally @innovatorssoft/baileys) ---
+// WhatsApp Username socket layer: check, set, pin, find, and recommend usernames.
+// Query IDs below are captured from live WA Web sessions and may rotate with
+// WA updates — re-capture via the proto-extract tool if a call starts failing
+// with an "unexpected response structure" Boom.
+export const USERNAME_QUERY_IDS = {
+    CHECK: '26124072630599520', // UsernameCheck
+    CHECK_MULTI: '27134626522840290', // UsernameCheckMulti
+    SET: '27108705368767936', // UsernameSet
+    GET: '32618050064506056', // UsernameGet
+    GET_RECOMMENDATIONS: '26077456248616956', // UsernameGetRecommendationsQuery
+    PIN_SET: '25529696019976770' // UsernamePinSet
+};
+
+export const USERNAME_CHECK_RESULT = {
+    SUCCESS: 'SUCCESS',
+    INVALID: 'INVALID'
+};
+
+export const USERNAME_SOURCE = {
+    FB: 'FB',
+    IG: 'IG',
+    USER_INPUT: 'USER_INPUT',
+    SUGGESTION: 'SUGGESTION'
+};
+
+export const makeUsernameSocket = (config) => {
+    const sock = makeCommunitiesSocket(config);
+    const { query, generateMessageTag, executeUSyncQuery } = sock;
+
+    /** Internal helper — wraps executeWMexQuery with this socket's query/tag */
+    const mexQuery = (variables, queryId, dataPath) => executeWMexQuery(variables, queryId, dataPath, query, generateMessageTag);
+
+    // 1. Check username availability
+    const checkUsername = async (username, includeSuggestions = true) => {
+        if (!USERNAME_QUERY_IDS.CHECK) {
+            throw new Error('Username CHECK query_id not configured — capture a live WA session to obtain it');
+        }
+        const data = await mexQuery({ username, include_suggestions: includeSuggestions }, USERNAME_QUERY_IDS.CHECK, 'xwa2_username_check');
+        if (data?.result === USERNAME_CHECK_RESULT.SUCCESS) {
+            return { available: true, username };
+        }
+        return {
+            available: false,
+            username,
+            suggestions: data?.suggestions ?? [],
+            rejectionReasons: data?.rejection_reasons ?? [],
+            suggestionsEligible: data?.suggestions_eligible ?? true
+        };
+    };
+
+    // 2. Check multiple usernames at once
+    const checkUsernameMulti = async (usernames) => {
+        if (!USERNAME_QUERY_IDS.CHECK_MULTI) {
+            throw new Error('Username CHECK_MULTI query_id not configured');
+        }
+        return mexQuery({ usernames }, USERNAME_QUERY_IDS.CHECK_MULTI, 'xwa2_username_check_multi');
+    };
+
+    // 3. Set username
+    const setUsername = async (username, options = {}) => {
+        if (!USERNAME_QUERY_IDS.SET) {
+            throw new Error('Username SET query_id not configured — capture a live WA session to obtain it');
+        }
+        const { source = USERNAME_SOURCE.USER_INPUT, sessionId, pin } = options;
+        const variables = {
+            username,
+            reserved: false,
+            source,
+            ...(sessionId ? { session_id: sessionId } : {}),
+            ...(pin ? { pin } : {})
+        };
+        return mexQuery(variables, USERNAME_QUERY_IDS.SET, 'xwa2_username_set');
+    };
+
+    // 4. Delete / unset username
+    const deleteUsername = async () => {
+        if (!USERNAME_QUERY_IDS.SET) {
+            throw new Error('Username SET query_id not configured — capture a live WA session to obtain it');
+        }
+        return mexQuery({ username: null }, USERNAME_QUERY_IDS.SET, 'xwa2_username_delete');
+    };
+
+    // 5. Get own username
+    const getMyUsername = async () => {
+        if (!USERNAME_QUERY_IDS.GET) {
+            throw new Error('Username GET query_id not configured — capture a live WA session to obtain it');
+        }
+        const data = await mexQuery({}, USERNAME_QUERY_IDS.GET, 'xwa2_username_get');
+        return data?.username ?? null;
+    };
+
+    // 6. Pin/unpin username (requires PIN)
+    const setUsernamePin = async (pin) => {
+        if (!USERNAME_QUERY_IDS.PIN_SET) {
+            throw new Error('Username PIN_SET query_id not configured — capture a live WA session to obtain it');
+        }
+        return mexQuery({ pin }, USERNAME_QUERY_IDS.PIN_SET, 'xwa2_username_pin_set');
+    };
+
+    // 7. Find user by username (USync)
+    const findUserByUsername = async (username, pin) => {
+        const usyncQuery = new USyncQuery().withContactProtocol();
+        const user = new USyncUser().withUsername(username);
+        if (pin) user.withUsernameKey(pin);
+        usyncQuery.withUser(user);
+        const result = await executeUSyncQuery(usyncQuery);
+        if (!result?.list?.length) return null;
+        const entry = result.list[0];
+        if (!entry) return null;
+        return {
+            jid: entry.id,
+            contact: Boolean(entry.contact)
+        };
+    };
+
+    // 8. Fetch usernames of known contacts (USync)
+    const fetchContactUsernames = async (...jids) => {
+        const usyncQuery = new USyncQuery().withUsernameProtocol();
+        for (const jid of jids) {
+            usyncQuery.withUser(new USyncUser().withId(jid));
+        }
+        const result = await executeUSyncQuery(usyncQuery);
+        return result?.list ?? [];
+    };
+
+    // 9. Get username recommendations
+    const getUsernameRecommendations = async (source = null) => {
+        const variables = {};
+        if (source) variables.source = source;
+        return mexQuery(variables, USERNAME_QUERY_IDS.GET_RECOMMENDATIONS, 'xwa2_username_get_recommendations');
+    };
+
+    return {
+        ...sock,
+        checkUsername,
+        checkUsernameMulti,
+        setUsername,
+        deleteUsername,
+        getMyUsername,
+        setUsernamePin,
+        findUserByUsername,
+        fetchContactUsernames,
+        getUsernameRecommendations,
+        USERNAME_QUERY_IDS,
+        USERNAME_CHECK_RESULT,
+        USERNAME_SOURCE
+    };
+};

package/lib/Utils/MessageBuilder.js

@@ -763,6 +763,46 @@ class Button extends BaseBuilder {
 	//   - a node can carry a builder-only `ref: 'name'` tag; another prop can then point back
 	//     at it with `{ $ref: 'name' }`, resolved to that node's real id after the whole tree
 	//     is walked (order-independent). `ref` itself is stripped and never reaches the wire.
+	//
+	// Vanz@Add 01-09-26 --- JSDoc typedefs for the "basic" A2UI catalog below (component set +
+	// props confirmed from captured traffic — see /areas/vanzxy-baileys.md). This is NOT the
+	// official A2UI spec (there isn't a public one we have access to), just what's been observed
+	// on the wire, so BloksNode ends with a permissive `AnyBloksNode` fallback: known components
+	// get full editor autocomplete + prop hints, anything else still type-checks and still works
+	// at runtime (setBloksWidget()'s own validation only ever requires a "component" string).
+	/**
+	 * @typedef {{ $ref: string }} BloksRef
+	 * Points back at a sibling node tagged `ref: 'name'` elsewhere in the same tree (currently
+	 * only needed for `Modal.trigger`/`Modal.content` — everything else nests directly).
+	 */
+	/**
+	 * @typedef {Object} BloksNodeBase
+	 * @property {string} [ref] Builder-only tag so another node can reference this one via `{ $ref: ref }`. Stripped before send.
+	 */
+	/**
+	 * @typedef {BloksNodeBase & { component: 'Column'|'Row', weight?: number, justify?: string, children?: BloksNode[] }} ColumnRowNode
+	 * @typedef {BloksNodeBase & { component: 'Text', text: string, variant?: string }} TextNode
+	 * @typedef {BloksNodeBase & { component: 'Icon', name: string }} IconNode
+	 * @typedef {BloksNodeBase & { component: 'Divider' }} DividerNode
+	 * @typedef {BloksNodeBase & { component: 'Image', url: string, variant?: string, fit?: string }} ImageNode
+	 * @typedef {BloksNodeBase & { component: 'Video', url: string }} VideoNode
+	 * @typedef {BloksNodeBase & { component: 'List', children?: BloksNode[] }} ListNode
+	 * @typedef {BloksNodeBase & { component: 'TextField', label?: string, value?: string, variant?: string }} TextFieldNode
+	 * @typedef {BloksNodeBase & { component: 'DateTimeInput', label?: string, value?: string, enableDate?: boolean, enableTime?: boolean }} DateTimeInputNode
+	 * @typedef {BloksNodeBase & { component: 'Slider', label?: string, min?: number, max?: number, value?: number }} SliderNode
+	 * @typedef {BloksNodeBase & { component: 'CheckBox', label?: string, value?: boolean }} CheckBoxNode
+	 * @typedef {BloksNodeBase & { component: 'ChoicePicker', label?: string, variant?: string, displayStyle?: string, options?: Array<{label: string, value: string}>, value?: string }} ChoicePickerNode
+	 * @typedef {BloksNodeBase & { component: 'Button', child?: BloksNode, variant?: string, action?: { call: string, args?: Record<string, any> } }} BloksButtonNode
+	 *   Note: unlike the CTA/native-flow `Button` class elsewhere in this file, an A2UI Button node
+	 *   has no `label`/`type`+`name` — its label comes from a nested `child` (usually a `Text` node),
+	 *   and tapping it fires `action.call` (with `action.args`), not a native-flow button name.
+	 * @typedef {BloksNodeBase & { component: 'Modal', trigger: string|BloksRef, content: BloksNode|string|BloksRef }} ModalNode
+	 * @typedef {BloksNodeBase & { component: 'Tabs', tabs: Array<{title: string, child: BloksNode}> }} TabsNode
+	 * @typedef {BloksNodeBase & { component: 'Card', child?: BloksNode }} CardNode
+	 * @typedef {BloksNodeBase & { component: 'AudioPlayer', url: string, description?: string }} AudioPlayerNode
+	 * @typedef {BloksNodeBase & { component: string, [key: string]: any }} AnyBloksNode Fallback for components not yet confirmed on the wire — still works, just no prop-level autocomplete.
+	 * @typedef {ColumnRowNode|TextNode|IconNode|DividerNode|ImageNode|VideoNode|ListNode|TextFieldNode|DateTimeInputNode|SliderNode|CheckBoxNode|ChoicePickerNode|BloksButtonNode|ModalNode|TabsNode|CardNode|AudioPlayerNode|AnyBloksNode} BloksNode
+	 */
 	#flattenBloks(tree, out, ctx = { n: 0, refs: new Map(), pending: [] }, id = 'root') {
 		if (!tree || typeof tree !== 'object') throw new TypeError('setBloksWidget: every node needs a "component" type');
 		const { component, children, child, ref, ...rest } = tree;
@@ -804,7 +844,7 @@ class Button extends BaseBuilder {
 	 * `Modal.trigger` — tag the source node with `ref: 'someName'` and point at it with
 	 * `{ $ref: 'someName' }`. Everything else (including `Modal.content`) can just be nested
 	 * directly, no special key needed.
-	 * @param {Record<string, any>} tree Root node, e.g. `{ component: 'Column', children: [...] }`.
+	 * @param {BloksNode} tree Root node, e.g. `{ component: 'Column', children: [...] }`.
 	 * @param {{uuid?: string, catalogId?: string, surfaceId?: string, version?: string}} [options]
 	 */
 	setBloksWidget(tree, { uuid = crypto.randomUUID(), catalogId = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json', surfaceId, version = 'v0.9' } = {}) {
@@ -2102,6 +2142,19 @@ class AIRich extends BaseBuilder {
 		// 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) {
@@ -2129,6 +2182,19 @@ class AIRich extends BaseBuilder {
 					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)`);
+					}
+
 					const subBefore = target._submessages.length;
 					const secBefore = target._sections.length;