@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/src/mcp/message-buffer.js

@@ -1,8 +1,20 @@
 /**
  * Ring buffer storing messages per thread with cursor-based incremental reads.
  * Shared by both stdio and HTTP MCP transports.
+ *
+ * Several bots can share one listener, so "read" is per consumer: each named
+ * consumer has its own read cursor, and marking messages read moves only that
+ * cursor. It used to delete the messages, so one bot's zalo_mark_read emptied
+ * every other bot's inbox (triage M7). Messages now leave only by eviction
+ * (maxSize per thread, maxAge), which bounds memory as before.
  */
 
+/** The consumer a caller that names none reads as. */
+export const DEFAULT_CONSUMER = "default";
+
+/** Consumers remembered at most; the least recently active is forgotten first. */
+const MAX_CONSUMERS = 256;
+
 export class MessageBuffer {
     /**
      * @param {number} maxSize - Max messages per thread before eviction
@@ -14,6 +26,17 @@ export class MessageBuffer {
         this._maxSize = maxSize;
         this._maxAge = maxAge;
         this._globalCursor = 0;
+        /** @type {Map<string, { cursor: number, at: number }>} */
+        this._readCursors = new Map();
+    }
+
+    /**
+     * The read cursor of one consumer: messages after it are unread for them.
+     * @param {string} [consumer="default"]
+     * @returns {number}
+     */
+    readCursor(consumer = DEFAULT_CONSUMER) {
+        return this._readCursors.get(consumer)?.cursor ?? 0;
     }
 
     /**
@@ -60,18 +83,25 @@ export class MessageBuffer {
     }
 
     /**
-     * Advance read cursor — discard messages at or before given cursor.
+     * Advance one consumer's read cursor to `cursor`. Nothing is deleted, and no
+     * other consumer's cursor moves; a cursor never moves backwards.
      * @param {number} cursor
-     * @returns {number} Count of discarded messages
+     * @param {string} [consumer="default"]
+     * @returns {number} how many buffered messages this newly marked read for that consumer
      */
-    markRead(cursor) {
-        let discarded = 0;
+    markRead(cursor, consumer = DEFAULT_CONSUMER) {
+        const from = this.readCursor(consumer);
+        const to = Math.max(from, Number(cursor) || 0);
+        let marked = 0;
         for (const [, thread] of this._threads) {
-            const before = thread.messages.length;
-            thread.messages = thread.messages.filter((m) => m._cursor > cursor);
-            discarded += before - thread.messages.length;
+            for (const m of thread.messages) if (m._cursor > from && m._cursor <= to) marked++;
+        }
+        this._readCursors.delete(consumer); // re-insert: Map order is recency
+        this._readCursors.set(consumer, { cursor: to, at: Date.now() });
+        while (this._readCursors.size > MAX_CONSUMERS) {
+            this._readCursors.delete(this._readCursors.keys().next().value);
         }
-        return discarded;
+        return marked;
     }
 
     /**

package/src/mcp/message-buffer.test.js

@@ -108,23 +108,22 @@ describe("MessageBuffer cursor-based incremental reads", () => {
 });
 
 describe("MessageBuffer markRead", () => {
-    it("discards messages at or before cursor and returns count", () => {
+    it("marks messages at or before cursor read and returns how many", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         buf.push("t1", msg("b"));
         const { cursor } = buf.read("t1");
-        const discarded = buf.markRead(cursor);
-        assert.equal(discarded, 2);
+        assert.equal(buf.markRead(cursor), 2);
     });
 
-    it("messages after cursor are kept", () => {
+    it("messages after the cursor stay unread for that consumer", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         const { cursor: c1 } = buf.read("t1");
         buf.push("t1", msg("b"));
 
         buf.markRead(c1);
-        const { messages } = buf.read("t1");
+        const { messages } = buf.read("t1", buf.readCursor());
         assert.equal(messages.length, 1);
         assert.equal(messages[0].text, "b");
     });
@@ -138,13 +137,56 @@ describe("MessageBuffer markRead", () => {
         assert.equal(second, 0);
     });
 
-    it("markRead across multiple threads discards from all", () => {
+    it("markRead covers every thread", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("a"));
         buf.push("t2", msg("b"));
         const { cursor } = buf.read(); // reads all
-        const discarded = buf.markRead(cursor);
-        assert.equal(discarded, 2);
+        assert.equal(buf.markRead(cursor), 2);
+    });
+});
+
+// Triage M7: several bots share one listener. markRead used to delete, so one
+// bot marking read emptied every other bot's inbox.
+describe("MessageBuffer read cursors, per consumer", () => {
+    it("markRead deletes nothing: another consumer still sees every message", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor, "bot-1");
+
+        assert.equal(buf.read("t1", buf.readCursor("bot-1")).messages.length, 0);
+        // Red if markRead goes back to deleting for everyone.
+        assert.equal(buf.read("t1", buf.readCursor("bot-2")).messages.length, 2);
+    });
+
+    it("each consumer's cursor is its own, and never moves backwards", () => {
+        const buf = new MessageBuffer();
+        for (const t of ["a", "b", "c"]) buf.push("t1", msg(t));
+        buf.markRead(2, "bot-1");
+        buf.markRead(1, "bot-1");
+        assert.equal(buf.readCursor("bot-1"), 2);
+        assert.equal(buf.readCursor("bot-2"), 0);
+        assert.equal(buf.readCursor(), 0, "the default consumer is untouched");
+    });
+
+    it("unread counts follow the consumer's cursor", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.markRead(1, "bot-1");
+        assert.equal(buf.getStats(buf.readCursor("bot-1"))[0].unread, 1);
+        assert.equal(buf.getStats(buf.readCursor("bot-2"))[0].unread, 2);
+    });
+
+    it("remembers a bounded number of consumers, forgetting the least recent", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        for (let i = 0; i < 300; i++) buf.markRead(1, `bot-${i}`);
+        assert.ok(buf._readCursors.size <= 256);
+        assert.equal(buf.readCursor("bot-299"), 1, "the most recent is kept");
+        assert.equal(buf.readCursor("bot-0"), 0, "the oldest is forgotten");
     });
 });
 
@@ -210,7 +252,7 @@ describe("MessageBuffer multi-thread isolation", () => {
         assert.equal(r2.messages[0].text, "from-t2");
     });
 
-    it("markRead on shared cursor only keeps messages after it in each thread", () => {
+    it("markRead on the global cursor leaves unread only what came after it, in each thread", () => {
         const buf = new MessageBuffer();
         buf.push("t1", msg("t1-a"));
         const { cursor: midCursor } = buf.read();
@@ -218,8 +260,8 @@ describe("MessageBuffer multi-thread isolation", () => {
 
         buf.markRead(midCursor);
 
-        const r1 = buf.read("t1");
-        const r2 = buf.read("t2");
+        const r1 = buf.read("t1", buf.readCursor());
+        const r2 = buf.read("t2", buf.readCursor());
         assert.equal(r1.messages.length, 0);
         assert.equal(r2.messages.length, 1);
     });
@@ -255,14 +297,24 @@ describe("MessageBuffer getStats", () => {
     });
 
     it("excludes threads with no messages", () => {
-        const buf = new MessageBuffer(500, 999999);
-        buf.push("t1", msg("a"));
-        const { cursor } = buf.read("t1");
-        buf.markRead(cursor); // discards all messages
+        // markRead no longer empties a thread (it moves a consumer's cursor);
+        // eviction is what leaves one with no messages.
+        const buf = new MessageBuffer(500, 1000);
+        buf.push("t1", msg("a", Date.now() - 5000)); // already past maxAge
 
         const stats = buf.getStats(0);
         assert.equal(stats.length, 0);
     });
+
+    it("keeps listing a thread whose messages were all marked read, with 0 unread", () => {
+        const buf = new MessageBuffer(500, 999999);
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor);
+        const [t1] = buf.getStats(buf.readCursor());
+        assert.equal(t1.unread, 0);
+        assert.equal(t1.total, 1);
+    });
 });
 
 describe("MessageBuffer getThreadType", () => {

package/src/mcp/notifier.js

@@ -5,10 +5,21 @@
 
 import { parseDuration } from "./mcp-config.js";
 
-/** Emoji prefix per message type for notification previews */
+/**
+ * Emoji prefix per message type for notification previews.
+ *
+ * Keyed on the shared type vocabulary (`photo`, not `image`) that
+ * `classifyLiveMessage` produces for every capture path; `image` stays as an
+ * alias so a message buffered by an older build still renders.
+ */
 const TYPE_EMOJI = {
     text: "💬",
+    photo: "📷",
     image: "📷",
+    sticker: "😀",
+    card: "🪪",
+    location: "📍",
+    doodle: "🖌️",
     file: "📎",
     link: "🔗",
     video: "🎬",
@@ -20,7 +31,12 @@ const TYPE_EMOJI = {
 /** Vietnamese label per message type for notification breakdown */
 const TYPE_LABEL = {
     text: "text",
+    photo: "ảnh",
     image: "ảnh",
+    sticker: "sticker",
+    card: "thẻ",
+    location: "vị trí",
+    doodle: "hình vẽ",
     file: "file",
     link: "link",
     video: "video",

package/src/mcp/notifier.test.js

@@ -1,3 +1,9 @@
+// sandbox.js FIRST: it redirects HOME/USERPROFILE before
+// credentials.js freezes CONFIG_DIR at module-eval time. This file
+// reaches that module transitively, so without the redirect it binds
+// to the real ~/.zalo-agent-cli/. Enforced by
+// tests/cli/sandbox-discipline.test.js.
+import "../../tests/helpers/sandbox.js";
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { ZaloNotifier } from "./notifier.js";

package/src/mcp/sync-jobs.js

@@ -0,0 +1,82 @@
+/**
+ * Process-local tracking for explicitly requested MCP sync stages. The daemon
+ * owns this object, not an HTTP request's short-lived McpServer. The runners
+ * own all sync work; this module only tracks bounded progress and the result.
+ */
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+
+/**
+ * Create a bounded, account-local job tracker using the daemon's stage lock.
+ * Completed jobs are retained until displaced by ten newer jobs or restart.
+ * A requestId retry returns the same job while retained, without another tap.
+ * @param {{runners: object, lock: object}} deps - daemon runners and shared stage lock
+ * @returns {{start: Function, status: Function}}
+ */
+export function createSyncJobs({ runners, lock }) {
+    const jobs = new Map();
+    const snapshot = (job) => (job ? structuredClone(job) : null);
+
+    return {
+        start({ requestId, stage, ...params }) {
+            const existing = [...jobs.values()].find((job) => job.requestId === requestId);
+            if (existing) {
+                if (existing.stage !== stage || !isDeepStrictEqual(existing.params, params)) {
+                    throw new Error("requestId already names a different sync request; use a new requestId.");
+                }
+                return snapshot(existing);
+            }
+            if (!["messages", "reactions"].includes(stage) || typeof runners[stage] !== "function") {
+                throw new Error("Unsupported sync stage.");
+            }
+            const release = lock.tryAcquire(`mcp-sync:${stage}`);
+            if (!release)
+                throw new Error(`Sync/history is busy (${lock.current()?.stage}); check status and retry later.`);
+
+            const job = {
+                jobId: randomUUID(),
+                requestId,
+                stage,
+                params,
+                state: "running",
+                startedAt: Date.now(),
+                finishedAt: null,
+                phoneConfirmationRequired: stage === "messages",
+                events: [],
+            };
+            // The lock guarantees no other running job is evicted here.
+            while (jobs.size >= 10) jobs.delete(jobs.keys().next().value);
+            jobs.set(job.jobId, job);
+            const initial = snapshot(job);
+            Promise.resolve().then(async () => {
+                try {
+                    job.result = await runners[stage](params, (event) => {
+                        // Retain recent progress, never an unbounded event stream.
+                        job.events.push({
+                            at: Date.now(),
+                            phase: String(event.phase || "progress").slice(0, 80),
+                            detail: String(event.detail || "").slice(0, 1000),
+                        });
+                        if (job.events.length > 20) job.events.shift();
+                    });
+                    job.state = "completed";
+                } catch (error) {
+                    job.state = "failed";
+                    job.error = error?.message || String(error);
+                } finally {
+                    job.finishedAt = Date.now();
+                    release();
+                }
+            });
+            return initial;
+        },
+        status(jobId) {
+            if (jobId) {
+                const job = jobs.get(jobId);
+                if (!job) throw new Error("Unknown or expired sync job; jobs are lost when the daemon restarts.");
+                return snapshot(job);
+            }
+            return snapshot([...jobs.values()].at(-1)) || { state: "idle" };
+        },
+    };
+}

package/src/mcp/thread-name-cache.js

@@ -1,3 +1,5 @@
+import { readUserAliases, resolveCurrentUserNames } from "../core/current-user-names.js";
+
 /**
  * In-memory cache mapping threadId → {name, type, memberCount}.
  * Built on startup by fetching all groups + friends from Zalo API.
@@ -35,6 +37,7 @@ export class ThreadNameCache {
         const start = Date.now();
         let groupCount = 0;
         let friendCount = 0;
+        const friendProfiles = new Map();
 
         // Load groups: getAllGroups() → IDs → batched getGroupInfo()
         try {
@@ -63,12 +66,13 @@ export class ThreadNameCache {
             console.error("[thread-name-cache] getAllGroups failed:", e.message);
         }
 
-        // Load friends (DM threads)
+        // Load friends (DM threads), honoring the owner's aliases explicitly.
         try {
             const friends = await api.getAllFriends();
             const list = Array.isArray(friends) ? friends : [];
             for (const f of list) {
                 if (f.userId) {
+                    friendProfiles.set(String(f.userId), f);
                     this._cache.set(f.userId, {
                         name: f.displayName || f.zaloName || "?",
                         type: "dm",
@@ -80,6 +84,7 @@ export class ThreadNameCache {
             console.error("[thread-name-cache] getAllFriends failed:", e.message);
         }
 
+        await this.refreshUsers(api, friendProfiles);
         this._ready = true;
         const elapsed = Date.now() - start;
         console.error(`[thread-name-cache] Ready: ${groupCount} groups, ${friendCount} friends (${elapsed}ms)`);
@@ -94,6 +99,14 @@ export class ThreadNameCache {
         return this._cache.get(threadId) || null;
     }
 
+    /** Refresh current DM labels without modifying per-message names or group titles. */
+    async refreshUsers(api, profiles = new Map()) {
+        const ids = [...this._cache].filter(([, v]) => v.type === "dm").map(([id]) => id);
+        const aliases = await readUserAliases(api);
+        const names = await resolveCurrentUserNames(api, ids, { aliases, profiles });
+        for (const [id, current] of names) this.set(id, { name: current.name, type: "dm" });
+    }
+
     /**
      * Get thread name by ID. Returns null if not cached.
      * @param {string} threadId

package/src/mcp/thread-name-cache.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { ThreadNameCache } from "./thread-name-cache.js";
 
 /** Create a mock API that returns predictable group/friend data */
-function createMockApi(groups = {}, friends = []) {
+function createMockApi(groups = {}, friends = [], aliases = []) {
     return {
         getAllGroups: async () => ({
             gridVerMap: Object.fromEntries(Object.keys(groups).map((id) => [id, 1])),
@@ -12,6 +12,7 @@ function createMockApi(groups = {}, friends = []) {
             gridInfoMap: Object.fromEntries(ids.filter((id) => groups[id]).map((id) => [id, groups[id]])),
         }),
         getAllFriends: async () => friends,
+        getAliasList: async () => ({ items: aliases }),
     };
 }
 
@@ -39,6 +40,7 @@ describe("ThreadNameCache", () => {
                 { userId: "u1", displayName: "Viet Anh", zaloName: "VA" },
                 { userId: "u2", zaloName: "Bob" },
             ],
+            [{ userId: "u1", alias: "Viet Anh" }],
         );
 
         await cache.init(api);
@@ -77,6 +79,7 @@ describe("ThreadNameCache", () => {
                     g4: { name: "Admin Team", totalMember: 5 },
                 },
                 [{ userId: "u1", displayName: "Soạn Văn", zaloName: "SV" }],
+                [{ userId: "u1", alias: "Soạn Văn" }],
             );
             await cache.init(api);
         });

package/src/utils/bank-helpers.js

@@ -5,7 +5,9 @@
 import { mkdtempSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import nodefetch from "node-fetch";
+// Node >=22 (see engines in package.json) has a native, global `fetch` —
+// no need for the `node-fetch` package, which drags in a deprecated
+// node-domexception polyfill via formdata-polyfill/fetch-blob.
 
 /** Bank name aliases (lowercase, no spaces) → BIN codes. */
 export const BANK_NAME_TO_BIN = {
@@ -219,9 +221,12 @@ export async function generateQrTransferImage(bin, accountNumber, amount = null,
     const outPath = join(tmpDir, "qr.png");
 
     try {
-        const resp = await nodefetch(url, {
+        // node-fetch's `timeout` option isn't a thing on native fetch —
+        // use AbortSignal.timeout() instead (same pattern already used for
+        // the webhook POST in commands/listen.js).
+        const resp = await fetch(url, {
             headers: { "User-Agent": "Mozilla/5.0" },
-            timeout: 15000,
+            signal: AbortSignal.timeout(15000),
         });
         if (!resp.ok) return null;
         const buffer = Buffer.from(await resp.arrayBuffer());

package/src/utils/device-fingerprint.js

@@ -0,0 +1,72 @@
+/**
+ * Generates a randomized-but-internally-consistent browser fingerprint
+ * (User-Agent + matching Client Hints) for the one-time QR login handshake.
+ *
+ * Why this exists: zca-js's default QR-login fingerprint is broken and
+ * identical across every install on earth — it sends a literal
+ * "...Firefox/133.0" User-Agent header while our zca-js patch's
+ * secChUaHeaders() fallback (and, before this patch, every hardcoded call
+ * site in loginQR.js) separately claims Chromium/Chrome v130 Client Hints
+ * on every QR-flow request to id.zalo.me. Real browsers never produce that
+ * combination — Firefox doesn't send sec-ch-ua headers at all — and Zalo's
+ * server appears to read the Client Hints for the "Thiết bị" device label
+ * shown on the phone's QR-confirm screen, which is why every zca-js login
+ * shows "Chrome - Windows 10" regardless of what's actually running the
+ * CLI. Beyond being cosmetically wrong, a fingerprint that's byte-identical
+ * across every zca-js user is itself a correlatable signal.
+ *
+ * Scope: this only matters for the INITIAL QR-login handshake. Once logged
+ * in, the chosen userAgent is persisted in that account's credentials file
+ * (see extractCredentials()/loginWithCredentials() in zalo-client.js) and
+ * reused consistently for every subsequent API call — so a fresh, plausible,
+ * internally-consistent choice made once here, at first login, is enough;
+ * it doesn't need to be regenerated per-command. Re-scanning to log into the
+ * same account again later (after a full logout, not just a session resume)
+ * gets a freshly randomized fingerprint, same as a real user occasionally
+ * updating their browser — that's expected, not a bug.
+ */
+
+const CHROME_VERSIONS = ["131.0.0.0", "130.0.0.0", "129.0.0.0", "128.0.0.0"];
+
+/**
+ * Windows-first, Chrome-only presets. Deliberately not branching into
+ * Firefox/Safari: those browsers don't send sec-ch-ua headers at all, and
+ * Zalo's own device-label rendering already appears tuned for Chrome/Chromium
+ * (see the hardcoded literals this patch replaces) — straying from Chrome
+ * would trade one kind of oddity for another. Varying version + OS build is
+ * enough to avoid every install presenting an identical fingerprint.
+ */
+const PRESETS = [
+    ...CHROME_VERSIONS.map((v) => ({
+        userAgent: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v} Safari/537.36`,
+        secChUaPlatform: '"Windows"',
+    })),
+    ...CHROME_VERSIONS.map((v) => ({
+        userAgent: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v} Safari/537.36`,
+        secChUaPlatform: '"macOS"',
+    })),
+];
+
+function buildSecChUa(chromeVersion) {
+    const major = chromeVersion.split(".")[0];
+    // Matches the brand-list shape real Chrome sends (order, quoting, the
+    // "Not?A_Brand" filler entry — all part of Chrome's actual GREASE
+    // pattern for this header, not something we're inventing).
+    return `"Chromium";v="${major}", "Google Chrome";v="${major}", "Not?A_Brand";v="99"`;
+}
+
+/**
+ * Pick a random, internally-consistent fingerprint for a fresh QR login.
+ * @returns {{userAgent: string, secChUa: string, secChUaPlatform: string, secChUaMobile: string}}
+ */
+export function generateDeviceFingerprint() {
+    const preset = PRESETS[Math.floor(Math.random() * PRESETS.length)];
+    const versionMatch = preset.userAgent.match(/Chrome\/([\d.]+)/);
+    const chromeVersion = versionMatch ? versionMatch[1] : CHROME_VERSIONS[0];
+    return {
+        userAgent: preset.userAgent,
+        secChUa: buildSecChUa(chromeVersion),
+        secChUaPlatform: preset.secChUaPlatform,
+        secChUaMobile: "?0",
+    };
+}

package/src/utils/mentions.js

@@ -0,0 +1,140 @@
+/**
+ * Zalo @-mention offsets.
+ *
+ * A mention is `{ pos, uid, len }`, where `pos` and `len` are **UTF-16
+ * code-unit offsets into the message string** — not byte offsets, and not
+ * grapheme counts. Zalo renders the tag over exactly `text.slice(pos, pos +
+ * len)`, so an offset that is off by one paints the highlight over the wrong
+ * span and the tagged person may not be notified at all.
+ *
+ * Measured against real mentions in a local cache (name changed):
+ *
+ *     text  "Em ko biết mở ch ạ @Trần Bích Ngọc"   { pos: 19, len: 15 }
+ *     text.slice(19, 34)              === "@Trần Bích Ngọc"       correct
+ *     Buffer.from(text).slice(19, 34) -> "h ạ @Trần Bí…"          wrong
+ *
+ * Accented Vietnamese is exactly where hand-counted offsets break, and it is
+ * most of what this CLI sends. So `--mention <pos:uid:len>` stays for
+ * back-compat, but the `@[uid]` token form below computes the offsets from
+ * the string it just built and is the one to reach for.
+ */
+
+/** The uid Zalo reserves for @All. zca-js turns it into `type: 1`. */
+export const ALL_MENTION_UID = "-1";
+
+/**
+ * Label used for `@[-1]` when no name is supplied.
+ *
+ * Zalo's own clients write the literal "@All" (confirmed on real @All rows
+ * in the cache: `{ uid: "-1", pos: 0, len: 4, type: 1 }`), including in
+ * Vietnamese groups. Do not localize this.
+ */
+export const ALL_MENTION_LABEL = "All";
+
+/**
+ * `@[uid]` — the token expanded by {@link expandMentions}.
+ *
+ * Deliberately restricted to decimal ids (plus `-1` for @All), which is every
+ * uid Zalo accepts in a mention. Anything else in brackets — `@[see below]`,
+ * `@[TODO]` — is left in the text verbatim rather than turned into a mention
+ * of a uid that does not exist.
+ */
+const MENTION_TOKEN = /@\[(-?\d+)\]/g;
+
+/**
+ * Parse the legacy `--mention pos:uid:len` specs.
+ *
+ * Kept because scripts pass it; `@[uid]` tokens are the safe way in. Specs
+ * that are not three colon-separated parts, or whose pos/len are not numbers,
+ * are dropped rather than sent as NaN — zca-js's own filter would discard
+ * them anyway, silently and later.
+ *
+ * @param {string[]} [specs] - raw `pos:uid:len` strings
+ * @returns {{pos: number, uid: string, len: number}[]}
+ */
+export function parseMentionSpecs(specs) {
+    return (specs || [])
+        .map((spec) => {
+            const [pos, uid, len] = String(spec).split(":");
+            if (!uid) return null;
+            const parsed = { pos: Number(pos), uid, len: Number(len) };
+            if (!Number.isFinite(parsed.pos) || !Number.isFinite(parsed.len)) return null;
+            return parsed;
+        })
+        .filter(Boolean);
+}
+
+/**
+ * Expand `@[uid]` tokens into `@Display Name`, recording each mention's
+ * offsets in the string that comes out.
+ *
+ * Because the offsets are measured on the built string rather than counted by
+ * hand, they are correct whatever the surrounding text contains — accents,
+ * emoji, earlier mentions of different lengths.
+ *
+ * `edits` reports each substitution in *input* coordinates so that text
+ * styles counted against the pre-expansion message can be moved with
+ * {@link shiftStyles}.
+ *
+ * @param {string} text - message body, possibly containing `@[uid]` tokens
+ * @param {(uid: string) => (string|null|undefined)} [resolveName] - uid → display
+ *   name; anything falsy falls back to "All" for `@[-1]` and to the uid itself
+ *   otherwise, so an unknown user still gets a syntactically valid mention
+ * @returns {{text: string, mentions: {pos: number, uid: string, len: number}[],
+ *            edits: {start: number, oldLen: number, newLen: number}[]}}
+ */
+export function expandMentions(text, resolveName) {
+    const src = String(text ?? "");
+    const mentions = [];
+    const edits = [];
+    let out = "";
+    let cursor = 0;
+
+    // lastIndex is shared state on a module-level regex, so iterate a fresh copy.
+    const token = new RegExp(MENTION_TOKEN.source, "g");
+    let match;
+    while ((match = token.exec(src)) !== null) {
+        const uid = match[1];
+        const resolved = typeof resolveName === "function" ? resolveName(uid) : null;
+        const name = resolved || (uid === ALL_MENTION_UID ? ALL_MENTION_LABEL : uid);
+        const label = `@${name}`;
+
+        out += src.slice(cursor, match.index);
+        mentions.push({ pos: out.length, uid, len: label.length });
+        edits.push({ start: match.index, oldLen: match[0].length, newLen: label.length });
+        out += label;
+        cursor = match.index + match[0].length;
+    }
+    out += src.slice(cursor);
+
+    return { text: out, mentions, edits };
+}
+
+/**
+ * Move text styles across the edits {@link expandMentions} made.
+ *
+ * `--style start:len:style` and `--md` both produce offsets against the
+ * message *before* mentions expand, and a `@[uid]` token is almost always
+ * shorter than the name it becomes. Without this, `--md` plus a mention
+ * silently paints bold over the wrong words.
+ *
+ * A style that starts after an edit moves by the edit's delta; a style that
+ * spans one grows by it (`**hi @[123]**` keeps the whole run bold).
+ *
+ * @param {{start: number, len: number, st: string}[]} styles
+ * @param {{start: number, oldLen: number, newLen: number}[]} edits
+ * @returns {{start: number, len: number, st: string}[]}
+ */
+export function shiftStyles(styles, edits) {
+    if (!edits || edits.length === 0) return styles;
+    return styles.map((style) => {
+        let start = style.start;
+        let len = style.len;
+        for (const edit of edits) {
+            const delta = edit.newLen - edit.oldLen;
+            if (edit.start < style.start) start += delta;
+            else if (edit.start < style.start + style.len) len += delta;
+        }
+        return { ...style, start, len };
+    });
+}