@mapier/imsg-sdk 0.5.0 → 0.6.0

package/dist/gateway/extension-card.d.ts

@@ -0,0 +1,34 @@
+import type { ExtensionCard, ExtensionCardHandle, ExtensionCardResult, GatewayCapabilities } from './types.js';
+export declare const EXTENSION_CARD_MAX_FIELD_LENGTH = 4096;
+export declare const EXTENSION_CARD_PROVEN_REJECTIONS: readonly string[];
+export declare function classifyExtensionCardFireFailure(err: unknown): ExtensionCardResult;
+export interface ExtensionCardWireParams {
+    chat_id: number;
+    team_id: string;
+    extension_bundle_id: string;
+    app_name: string;
+    caption: string;
+    url: string;
+    live_layout: boolean;
+    subcaption?: string;
+    summary_text?: string;
+    app_store_id?: number;
+    session_id?: string;
+    updates_message_guid?: string;
+}
+export interface ExtensionCardSendResponse {
+    ok: boolean;
+    guid?: string;
+    message_id?: string;
+    session_id?: string;
+    balloon_bundle_id?: string;
+    live_layout?: boolean;
+    updated_message_guid?: string;
+}
+export declare function extensionCardRefusalReason(card: ExtensionCard, update?: ExtensionCardHandle): string | null;
+export declare function extensionCardPreflight(capabilities: Pick<GatewayCapabilities, 'extensionCardSend' | 'extensionCardUpdate'>, card: ExtensionCard, update?: ExtensionCardHandle): {
+    result: ExtensionCardResult;
+    reason: string;
+} | null;
+export declare function extensionCardWireParams(chatId: number, card: ExtensionCard, update?: ExtensionCardHandle): ExtensionCardWireParams;
+export declare function extensionCardResultFromResponse(response: ExtensionCardSendResponse, card: ExtensionCard, update?: ExtensionCardHandle): ExtensionCardResult;

package/dist/gateway/extension-card.js

@@ -0,0 +1,182 @@
+import { bridgeEffectStarted } from './chat-background.js';
+import { extensionCardFailure } from './types.js';
+// Counted in UTF-16 code units, which is what a JS string's `.length` counts
+// and what `[NSString length]` counts on the helper's side of the bridge —
+// the same field cap ExtensionCardRequest.swift enforces.
+export const EXTENSION_CARD_MAX_FIELD_LENGTH = 4096;
+// handleSendExtensionCard's returns BEFORE `dispatchIMMessageInChat` /
+// `[chat sendMessage:]` (IMsgInjected.m), plus the builder's own refusals
+// (IMsgExtensionCard.m), matched against `error.data` exactly as the group
+// verbs match theirs. Deliberately absent: `send-extension-card failed:` —
+// that wraps an NSException caught around the whole build-and-send block, so
+// the text cannot prove which side of the send it was raised on and the result
+// stays ambiguous.
+export const EXTENSION_CARD_PROVEN_REJECTIONS = [
+    'Missing chatGuid',
+    'Extension balloon IMMessage initializer unavailable on this macOS',
+    'Associated-message IMMessage initializer unavailable on this macOS',
+    "teamId must be 10 characters of A-Z0-9 and bundleId reverse-DNS without ':'",
+    // Formatted with the guid appended, so the match has to be a prefix.
+    'Chat not found',
+    'Extension card spec is missing',
+    'Extension card url is required',
+    'Extension card appName is required',
+    'Extension card caption is required',
+    'Could not build extension card',
+    'Could not construct extension card IMMessage',
+];
+// The card call itself threw. `refused` only when the error proves the helper
+// stopped before IMChat was invoked; everything else — a bridge timeout, an
+// exception raised after the send, a dead rpc child — may already have put a
+// card in the thread.
+export function classifyExtensionCardFireFailure(err) {
+    return extensionCardFailure(bridgeEffectStarted(err, EXTENSION_CARD_PROVEN_REJECTIONS) ? 'fire-failed' : 'refused');
+}
+const TEAM_ID = /^[A-Z0-9]{10}$/;
+// Reverse-DNS: the helper's own charset (letters, digits, '.', '-') plus at
+// least one dot. A ':' would forge the `plugin:team:extension` structure of
+// the balloon identifier and is excluded by the charset.
+const EXTENSION_BUNDLE_ID = /^[A-Za-z0-9.-]+$/;
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function requiredText(value, field) {
+    if (typeof value !== 'string' || !value)
+        return `${field} is required`;
+    return overlongText(value, field);
+}
+function overlongText(value, field) {
+    if (typeof value !== 'string')
+        return `${field} must be a string`;
+    // `.length` is UTF-16 code units, the unit the helper caps on.
+    if (value.length > EXTENSION_CARD_MAX_FIELD_LENGTH) {
+        return `${field} must be at most ${EXTENSION_CARD_MAX_FIELD_LENGTH} UTF-16 units`;
+    }
+    return null;
+}
+// Every field the native side would reject, checked here so a bad card is a
+// proven no-op instead of a round trip. The one deliberate divergence is `url`:
+// the helper accepts anything `URL(string:)` parses, which includes a
+// scheme-relative string, while this requires an absolute URL. A card's URL is
+// the extension's own state (a `data:` or `https:` URL in practice), never a
+// relative path, so the stricter rule costs nothing real and keeps a caller
+// from shipping a card whose URL the app cannot resolve.
+export function extensionCardRefusalReason(card, update) {
+    if (card === null || typeof card !== 'object')
+        return 'card must be an object';
+    const teamIdProblem = requiredText(card.teamId, 'teamId');
+    if (teamIdProblem)
+        return teamIdProblem;
+    if (!TEAM_ID.test(card.teamId))
+        return 'teamId must be exactly 10 characters of A-Z and 0-9';
+    const bundleProblem = requiredText(card.extensionBundleId, 'extensionBundleId');
+    if (bundleProblem)
+        return bundleProblem;
+    if (!EXTENSION_BUNDLE_ID.test(card.extensionBundleId) || !card.extensionBundleId.includes('.')) {
+        return "extensionBundleId must be reverse-DNS (letters, digits, '-', at least one '.') and must not contain ':'";
+    }
+    for (const field of ['appName', 'caption', 'url']) {
+        const problem = requiredText(card[field], field);
+        if (problem)
+            return problem;
+    }
+    if (!URL.canParse(card.url))
+        return 'url must be an absolute URL';
+    for (const field of ['subcaption', 'summaryText']) {
+        const value = card[field];
+        if (value === undefined)
+            continue;
+        const problem = overlongText(value, field);
+        if (problem)
+            return problem;
+    }
+    if (card.appStoreId !== undefined && (!Number.isSafeInteger(card.appStoreId) || card.appStoreId <= 0)) {
+        return 'appStoreId must be a positive integer';
+    }
+    // Strict, like the native handler: a live_layout that cannot be read must
+    // not quietly become the default, because the two values render differently
+    // on the recipient's phone.
+    if (card.liveLayout !== undefined && typeof card.liveLayout !== 'boolean') {
+        return 'liveLayout must be a boolean';
+    }
+    if (update === undefined)
+        return null;
+    if (update === null || typeof update !== 'object')
+        return 'update must be an ExtensionCardHandle';
+    // Both halves or neither: the session id alone starts a second card in the
+    // same session rather than replacing anything, and a guid alone is refused
+    // by the helper.
+    if (typeof update.sessionId !== 'string' || !UUID.test(update.sessionId)) {
+        return 'update.sessionId must be the UUID a previous send returned';
+    }
+    if (typeof update.firstCardMessageGuid !== 'string' || !UUID.test(update.firstCardMessageGuid)) {
+        return "update.firstCardMessageGuid must be the FIRST card's message guid, as a UUID";
+    }
+    return null;
+}
+// The whole sendExtensionCard preflight, shared by both gateways so parity is
+// structural: the capability gates, then the field rules. Returns the result
+// to answer with plus a line to log, or null to fire. Nothing has been sent at
+// any exit here, so every one of them is `effectStarted:false`.
+export function extensionCardPreflight(capabilities, card, update) {
+    if (!capabilities.extensionCardSend) {
+        return {
+            result: extensionCardFailure('unsupported'),
+            reason: 'bridge does not advertise extensionCardSend',
+        };
+    }
+    // An update is a send plus the associated-message initializer, so it needs
+    // both markers; a host can advertise the first without the second.
+    if (update !== undefined && !capabilities.extensionCardUpdate) {
+        return {
+            result: extensionCardFailure('unsupported'),
+            reason: 'bridge does not advertise extensionCardUpdate',
+        };
+    }
+    const refusal = extensionCardRefusalReason(card, update);
+    return refusal ? { result: extensionCardFailure('refused'), reason: refusal } : null;
+}
+export function extensionCardWireParams(chatId, card, update) {
+    return {
+        chat_id: chatId,
+        team_id: card.teamId,
+        extension_bundle_id: card.extensionBundleId,
+        app_name: card.appName,
+        caption: card.caption,
+        url: card.url,
+        // Sent explicitly rather than left to the native default, so the value
+        // that shaped the send is the value that comes back in the result.
+        live_layout: card.liveLayout ?? true,
+        ...(card.subcaption !== undefined ? { subcaption: card.subcaption } : {}),
+        ...(card.summaryText !== undefined ? { summary_text: card.summaryText } : {}),
+        ...(card.appStoreId !== undefined ? { app_store_id: card.appStoreId } : {}),
+        ...(update ? { session_id: update.sessionId, updates_message_guid: update.firstCardMessageGuid } : {}),
+    };
+}
+// Build the caller's result out of the host's response. Shared by both
+// gateways, which is what keeps the first-card rule from drifting: on an
+// update `result.handle` is the one that was passed IN, never one built from
+// this row's guid, so `handle = result.handle` after every update still points
+// at the session's first card.
+export function extensionCardResultFromResponse(response, card, update) {
+    // The native handler answers `ok:true` on every path that reaches a result
+    // and raises a JSON-RPC error otherwise, so a falsy `ok` is a host the SDK
+    // cannot read. It was invoked, so it is ambiguous, not a refusal.
+    if (!response.ok)
+        return extensionCardFailure('fire-failed');
+    const messageGuid = response.guid || response.message_id || undefined;
+    const sessionId = response.session_id || update?.sessionId || undefined;
+    // An update re-uses the handle it was given. A first send can only mint one
+    // when Messages actually exposed the new row's guid; `updatable:false` says
+    // that card is unreachable forever rather than handing back a guid we do not
+    // have.
+    const handle = update ?? (sessionId && messageGuid ? { sessionId, firstCardMessageGuid: messageGuid } : undefined);
+    return {
+        ok: true,
+        ...(sessionId ? { sessionId } : {}),
+        ...(messageGuid ? { messageGuid } : {}),
+        ...(handle ? { handle } : {}),
+        updatable: handle !== undefined,
+        ...(response.balloon_bundle_id ? { balloonBundleId: response.balloon_bundle_id } : {}),
+        liveLayout: response.live_layout ?? card.liveLayout ?? true,
+    };
+}
+//# sourceMappingURL=extension-card.js.map

package/dist/gateway/extension-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-card.js","sourceRoot":"","sources":["../../src/gateway/extension-card.ts"],"names":[],"mappings":"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"}

package/dist/gateway/fake.d.ts

@@ -1,5 +1,5 @@
 import type { MessageAttachment } from '../types.js';
-import type { ChatBackgroundPreset, ChatBackgroundRemoveResult, ChatBackgroundSetResult, ChatBackgroundStatus, EditMessageResult, Gateway, GatewayCapabilities, GatewayEvent, GatewayChat, GatewayHistoryRange, GroupChatResolution, GroupChatResolutionRequest, GroupMutationResult, HandleCheck, ImsgMessage, LocationUpdate, MessageService, NamePhotoShareResult, Reaction, ReactionNote, ReactResult, SendResult, SendStatus, SendTarget, SharedLocation, TextFormatRange } from './types.js';
+import type { ChatBackgroundPreset, ChatBackgroundRemoveResult, ChatBackgroundSetResult, ChatBackgroundStatus, EditMessageResult, ExtensionCard, ExtensionCardHandle, ExtensionCardResult, Gateway, GatewayCapabilities, GatewayEvent, GatewayChat, GatewayHistoryRange, GroupChatResolution, GroupChatResolutionRequest, GroupMutationResult, HandleCheck, ImsgMessage, LocationUpdate, MessageRemovalResult, MessageService, NamePhotoShareResult, Reaction, ReactionNote, ReactResult, SendResult, SendStatus, SendTarget, SharedLocation, TextFormatRange } from './types.js';
 export interface FakeGatewayOptions {
     latencyMs?: number;
     capabilities?: Partial<GatewayCapabilities>;
@@ -76,8 +76,9 @@ export declare class FakeGateway implements Gateway {
         aliasType?: 'phone' | 'email';
     }): Promise<HandleCheck>;
     private findInScanWindow;
-    tapback(chatId: number, targetGuid: string, reaction: Reaction, remove?: boolean): Promise<ReactResult>;
-    emojiTapback(chatId: number, targetGuid: string, emoji: string, remove?: boolean): Promise<ReactResult>;
+    private partCount;
+    tapback(chatId: number, targetGuid: string, reaction: Reaction, remove?: boolean, partIndex?: number): Promise<ReactResult>;
+    emojiTapback(chatId: number, targetGuid: string, emoji: string, remove?: boolean, partIndex?: number): Promise<ReactResult>;
     sendRich(chatId: number, text: string, opts?: {
         effect?: string;
         replyToGuid?: string;
@@ -95,13 +96,12 @@ export declare class FakeGateway implements Gateway {
     sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
     votePoll(chatId: number, pollGuid: string, optionId: string): Promise<ReactResult>;
     sendRichLink(chatId: number, _url: string): Promise<SendResult>;
+    sendExtensionCard(chatId: number, card: ExtensionCard, opts?: {
+        update?: ExtensionCardHandle;
+    }): Promise<ExtensionCardResult>;
     editMessage(chatId: number, targetGuid: string, text: string): Promise<EditMessageResult>;
-    unsendMessage(chatId: number, targetGuid: string): Promise<{
-        ok: boolean;
-    }>;
-    deleteMessage(chatId: number, targetGuid: string): Promise<{
-        ok: boolean;
-    }>;
+    unsendMessage(chatId: number, targetGuid: string): Promise<MessageRemovalResult>;
+    deleteMessage(chatId: number, targetGuid: string): Promise<MessageRemovalResult>;
     setTyping(chatId: number, _on: boolean): Promise<{
         ok: boolean;
     }>;
@@ -141,6 +141,7 @@ export declare class FakeGateway implements Gateway {
         reaction?: Reaction;
         emoji?: string;
         targetGuid?: string;
+        partIndex?: number;
     }): ImsgMessage;
     injectPollCreate(params: {
         chatId?: number;

package/dist/gateway/fake.js

@@ -1,5 +1,8 @@
+import { randomUUID } from 'node:crypto';
 import { aggregatePolls } from '../polls.js';
-import { CHAT_BACKGROUND_PRESETS, decideEditMessagePreflight, groupMutationFailure, normalizeChatBackgroundGuard, PATCHED_GATEWAY_CAPABILITIES, removalWouldBreakGroupMinimum, sendRichPreflight, TIER2_HISTORY_SCAN_WINDOW, toReactionNoteType, } from './types.js';
+import { extensionCardPreflight, extensionCardResultFromResponse } from './extension-card.js';
+import { CHAT_BACKGROUND_PRESETS, decideEditMessagePreflight, extensionCardFailure, groupMutationFailure, messageRemovalFailure, normalizeChatBackgroundGuard, PATCHED_GATEWAY_CAPABILITIES, removalWouldBreakGroupMinimum, sendRichPreflight, tapbackFailure, TIER2_HISTORY_SCAN_WINDOW, } from './types.js';
+import { reactionOnPart, tapbackPartRefusal, toReactionNote } from './tapback.js';
 import { locationUpdateFromWire, sharedLocationToWire } from './locations.js';
 import { classifyGroupChatResolution } from './portable-chat.js';
 // How far back recentReactions() scans, mirroring ImsgGateway's
@@ -145,12 +148,20 @@ export class FakeGateway {
     // Maintains the target message's reactions[] aggregate (the state the real
     // gateway reads from history) and emits the reaction event (the row the
     // real gateway sees on the watch stream).
-    toggleReaction(chatId, targetGuid, isFromMe, senderHandle, senderName, type, emoji) {
+    //
+    // `partIndex` (M2B-45) is part of a reaction's IDENTITY, not a detail on it:
+    // the same type on part 0 and part 1 is two separate reactions on the host,
+    // so the match below compares the part and the entry records it.
+    toggleReaction(chatId, targetGuid, isFromMe, senderHandle, senderName, type, emoji, partIndex = 0) {
         const target = this.messages.find((m) => m.guid === targetGuid);
         if (!target)
             throw new Error(`toggleReaction: no message with guid ${targetGuid}`);
         target.reactions ??= [];
-        const existingIdx = target.reactions.findIndex((r) => r.type === type && r.emoji === emoji && r.is_from_me === isFromMe && (isFromMe || r.sender === senderHandle));
+        const existingIdx = target.reactions.findIndex((r) => r.type === type &&
+            r.emoji === emoji &&
+            r.is_from_me === isFromMe &&
+            reactionOnPart(r, partIndex) &&
+            (isFromMe || r.sender === senderHandle));
         const nowActive = existingIdx === -1;
         const id = this.allocId();
         const createdAt = new Date().toISOString();
@@ -162,6 +173,9 @@ export class FakeGateway {
                 is_from_me: isFromMe,
                 sender: senderHandle,
                 created_at: createdAt,
+                // Absent for part 0, exactly as the native emits it — a whole-message
+                // reaction carries no `target_part` and must not grow one here.
+                ...(partIndex ? { target_part: partIndex } : {}),
             };
             target.reactions.push(entry);
         }
@@ -183,6 +197,9 @@ export class FakeGateway {
             reaction_type: type,
             reaction_emoji: emoji,
             is_reaction_add: nowActive,
+            // The event row carries the part under its own name, and
+            // `reacted_to_guid` stays the bare message guid (contract §2).
+            ...(partIndex ? { reaction_target_part: partIndex } : {}),
             reacted_to_guid: targetGuid,
             created_at: createdAt,
         };
@@ -336,7 +353,7 @@ export class FakeGateway {
                 continue;
             for (const r of m.reactions) {
                 if (!r.is_from_me)
-                    notes.push({ id: r.id, reaction: toReactionNoteType(r.type), emoji: r.emoji });
+                    notes.push(toReactionNote(r));
             }
         }
         return notes.sort((a, b) => b.id - a.id).slice(0, limit);
@@ -444,33 +461,59 @@ export class FakeGateway {
             .slice(-HISTORY_SCAN_WINDOW)
             .find((m) => m.guid === targetGuid);
     }
+    // How many parts a fake message has (M2B-45). The host counts the message's
+    // real chat items; the fake counts its attachments, so a two-photo message
+    // has parts 0 and 1 and anything else has the single part 0. That is
+    // deliberately CONSERVATIVE: a mixed text+photos message really has more
+    // parts than this says, so the fake refuses some parts the host would
+    // accept, and never the other way round (parity rule 2 — the fake must not
+    // succeed at something the real path refuses).
+    partCount(target) {
+        return Math.max(1, target.attachments?.length ?? 0);
+    }
     // Targeted tapback: any message guid (within the scan window above),
     // explicit add/remove, works in groups. Same closed Reaction set as
     // react(); the patched custom-emoji path is modeled separately below.
-    async tapback(chatId, targetGuid, reaction, remove = false) {
+    async tapback(chatId, targetGuid, reaction, remove = false, partIndex) {
         await this.delay();
+        const partRefusal = tapbackPartRefusal(partIndex, this.capabilities);
+        if (partRefusal)
+            return partRefusal;
+        // Every failure the fake can reach is a proven no-op (same rule as the
+        // group verbs below): nothing fired, so it says so.
         const target = this.findInScanWindow(chatId, targetGuid);
         if (!target)
-            return { ok: false };
-        const active = Boolean(target.reactions?.some((r) => r.is_from_me && r.type === reaction));
+            return tapbackFailure('refused');
+        // The bridge refuses a part the message does not have before sending
+        // anything (`Message <guid> has no part <n>`), so the fake must too.
+        if (partIndex !== undefined && partIndex >= this.partCount(target))
+            return tapbackFailure('refused');
+        const active = Boolean(target.reactions?.some((r) => r.is_from_me && r.type === reaction && reactionOnPart(r, partIndex)));
         if (remove ? !active : active) {
             return { ok: true, skipped: remove ? 'not-reacted' : 'already-reacted' };
         }
-        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, reaction, REACTION_EMOJI_BY_TYPE[reaction]);
+        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, reaction, REACTION_EMOJI_BY_TYPE[reaction], partIndex);
         return { ok: true };
     }
-    async emojiTapback(chatId, targetGuid, emoji, remove = false) {
+    async emojiTapback(chatId, targetGuid, emoji, remove = false, partIndex) {
         await this.delay();
-        if (!this.capabilities.emojiTapback || !emoji)
-            return { ok: false };
+        if (!this.capabilities.emojiTapback)
+            return tapbackFailure('unsupported');
+        if (!emoji)
+            return tapbackFailure('refused');
+        const partRefusal = tapbackPartRefusal(partIndex, this.capabilities);
+        if (partRefusal)
+            return partRefusal;
         const target = this.findInScanWindow(chatId, targetGuid);
         if (!target)
-            return { ok: false };
-        const active = target.reactions?.some((r) => r.is_from_me && r.type === 'custom' && r.emoji === emoji) ?? false;
+            return tapbackFailure('refused');
+        if (partIndex !== undefined && partIndex >= this.partCount(target))
+            return tapbackFailure('refused');
+        const active = target.reactions?.some((r) => r.is_from_me && r.type === 'custom' && r.emoji === emoji && reactionOnPart(r, partIndex)) ?? false;
         if (remove ? !active : active) {
             return { ok: true, skipped: remove ? 'not-reacted' : 'already-reacted' };
         }
-        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, 'custom', emoji);
+        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, 'custom', emoji, partIndex);
         return { ok: true };
     }
     // Targets an EXISTING chat only — no find-or-create `to:` form (contract §2).
@@ -585,6 +628,44 @@ export class FakeGateway {
         this.emit(this.buildMessage(chat, { is_from_me: true }));
         return { ok: true };
     }
+    async sendExtensionCard(chatId, card, opts = {}) {
+        await this.delay();
+        // The same shared preflight ImsgGateway runs, so the capability gates and
+        // every field rule answer identically on both implementations.
+        const refusal = extensionCardPreflight(this.capabilities, card, opts.update);
+        if (refusal)
+            return refusal.result;
+        const chat = this.chats.get(chatId);
+        // No find-or-create, like every other tier-2 send. On the host this is the
+        // helper's "Chat not found", a proven pre-invoke rejection.
+        if (!chat)
+            return extensionCardFailure('refused');
+        // NOT a UUID by the fake's usual `fake-msg-<id>` convention: a real card's
+        // guid is a Messages UUID and the update path validates it as one, so a
+        // fake guid would make the update leg unreachable here while it works on a
+        // host. The fake must be neither easier nor harder than the Mac.
+        const guid = randomUUID().toUpperCase();
+        // The card lands as its own balloon row; ImsgMessage models nothing of the
+        // payload, so the fake emits the bare outbound row like sendLocationRequest
+        // and lets the shared result builder do the rest. An update emits a row
+        // too — on a host it is a real associated-message row, and the card it
+        // replaces is restamped rather than removed.
+        this.emit(this.buildMessage(chat, { is_from_me: true, guid }));
+        // Deliberately NOT checked: that `update` names a card this gateway sent,
+        // that it is the FIRST card of its session, or that the session exists.
+        // The Mac cannot check any of it — an update aimed at a previous update's
+        // guid arrives as a separate card with `ok:true` and a real guid — and a
+        // fake that caught it would hide the one mistake this verb is shaped
+        // around (see ExtensionCardHandle).
+        return extensionCardResultFromResponse({
+            ok: true,
+            guid,
+            session_id: opts.update?.sessionId ?? randomUUID(),
+            balloon_bundle_id: `com.apple.messages.MSMessageExtensionBalloonPlugin:${card.teamId}:${card.extensionBundleId}`,
+            live_layout: card.liveLayout ?? true,
+            ...(opts.update ? { updated_message_guid: opts.update.firstCardMessageGuid } : {}),
+        }, card, opts.update);
+    }
     // Edits mutate the target row's text IN PLACE — no new row, no subscribe()
     // event (contract §2: this is what breaks the "same guid = immutable
     // content" assumption elsewhere in the codebase).
@@ -603,11 +684,18 @@ export class FakeGateway {
         return { ok: true };
     }
     // Live parity: unsend leaves a tombstone row whose text is cleared.
+    //
+    // The fake has no bridge to time out on, so it can only ever reach the
+    // proven half of the vocabulary. A guid outside the scan window is the one
+    // failure it can model — and it is `refused` here, not the `unverified` the
+    // real path reports for the same input: the real verb fires before it
+    // discovers the ceiling, the fake never fires at all. That is the fake
+    // staying INSIDE the real gateway's certainty, not exceeding it.
     async unsendMessage(chatId, targetGuid) {
         await this.delay();
         const target = this.findInScanWindow(chatId, targetGuid);
         if (!target)
-            return { ok: false };
+            return messageRemovalFailure('refused');
         target.text = undefined;
         return { ok: true };
     }
@@ -618,7 +706,7 @@ export class FakeGateway {
         await this.delay();
         const target = this.findInScanWindow(chatId, targetGuid);
         if (!target)
-            return { ok: false };
+            return messageRemovalFailure('refused');
         return { ok: true };
     }
     // Fire-and-forget: no observable effect through history() or this
@@ -855,6 +943,11 @@ export class FakeGateway {
     // Simulate another participant tapback-reacting (their side can target any
     // message, same as real Messages.app — only OUR react() is most-recent-
     // incoming-only).
+    // `partIndex` reacts to one part of the target (M2B-45), the way a phone
+    // reacts to the second photo of two. Unlike our own tapback() this is a
+    // fixture, not a verb: it models what the other side's device did, so it is
+    // not capability-gated — the reaction exists in the thread whatever THIS
+    // host can send.
     injectReaction(params) {
         if ((params.reaction === undefined) === (params.emoji === undefined)) {
             throw new Error('injectReaction: provide exactly one of reaction or emoji');
@@ -864,7 +957,7 @@ export class FakeGateway {
             throw new Error('injectReaction: chat has no message to react to');
         const type = params.reaction ?? 'custom';
         const emoji = params.emoji ?? REACTION_EMOJI_BY_TYPE[params.reaction];
-        return this.toggleReaction(params.chatId, target, false, params.sender, params.senderName, type, emoji);
+        return this.toggleReaction(params.chatId, target, false, params.sender, params.senderName, type, emoji, params.partIndex);
     }
     // ---- native poll fixtures (contract §2 "Native poll readback") ----
     // Polls are created through sendPoll(), a manual host-Mac `imsg poll send`