@mapier/imsg-sdk 0.2.3 → 0.3.1

package/docs/gateway-contract.md

@@ -57,6 +57,10 @@ interface Gateway {
     groupPhoto: boolean;
     groupParticipants: boolean;
     namePhotoSharing: boolean;
+    chatBackgroundSet: boolean;
+    chatBackgroundRemove: boolean;
+    editMessage: boolean;
+    mentionFormatting: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -91,7 +95,11 @@ interface Gateway {
   ): Promise<SendResult>;
   sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
   sendRichLink(chatId: number, url: string): Promise<SendResult>;
-  editMessage(chatId: number, targetGuid: string, text: string): Promise<{ ok: boolean }>;
+  editMessage(chatId: number, targetGuid: string, text: string): Promise<{
+    ok: boolean;
+    skipped?: 'unchanged';
+    effectStarted?: boolean;
+  }>;
   unsendMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
   deleteMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
   setTyping(chatId: number, on: boolean): Promise<{ ok: boolean }>;
@@ -106,6 +114,21 @@ interface Gateway {
     skipped?: 'not-offered';
     effectStarted?: boolean;
   }>;
+  chatBackgroundStatus(chatId: number): Promise<{
+    chatId: number;
+    backgroundSet: boolean;
+    backgroundGuid: string | null;
+  } | null>;
+  setChatBackground(chatId: number, preset?: 'gradient'): Promise<{
+    ok: boolean;
+    backgroundGuid?: string;
+    effectStarted?: boolean;
+  }>;
+  removeChatBackground(chatId: number, expectedGuid?: string): Promise<{
+    ok: boolean;
+    skipped?: 'no-background';
+    effectStarted?: boolean;
+  }>;
 }
 
 interface ReactionNote {
@@ -160,7 +183,16 @@ both the long-lived RPC process and its one-time `status --json` probe.
 Patched verbs require the injected bridge's explicit selector markers
 `emojiTapbackSend`, `stickerSend`, `groupPhotoUpdate`, `groupAddParticipant`, and
 `groupRemoveParticipant`; Name & Photo requires both `namePhotoShouldOffer`
-and `namePhotoShare`; emoji additionally requires the selected RPC binary
+and `namePhotoShare`; chat backgrounds are gated per verb on
+`chatBackgroundSetGradient` (setter + PosterBoard/ChatKit runtime) and
+`chatBackgroundRemove` (setter + live-GUID getter), which the injected helper
+already composes; edit message requires any one of `editMessageItemTranslation`
+(macOS 27's five-argument `-[IMChat editMessageItem:…newPartTranslation:…]`,
+imsg#3), `editMessageItem` (macOS 26) or `editMessage` (macOS 13) — the helper
+uses the first present one; confirmed @mentions on `sendRich` require
+`mentionFormatting`, which the helper advertises only when IMSharedUtilities'
+confirmed-mention attribute key resolves at runtime (imsg#13); emoji
+additionally requires the selected RPC binary
 to report `rpc_features:["tapback.emoji"]`. That second half prevents a
 patched dylib behind a stock CLI from false-advertising custom emoji support.
 Missing status, malformed JSON, or absent markers fail closed.
@@ -175,10 +207,11 @@ guid by scanning `history(chatId, 30)` — the same 30-message ceiling
 `recentReactions` already documents above — so a guid older than that is as
 invisible to these methods as it is to `recentReactions`. `tapback` and
 `deleteMessage` pre-check against that scan before firing, so they return
-`{ ok: false }` without touching anything; `editMessage`/`unsendMessage` fire
-the RPC first and only find the ceiling on the VERIFY pass, so a guid outside
-the window still reports `{ ok: false }` but may have mutated the real row on
-the way there — "no confirmable effect," not a guaranteed no-op. FakeGateway
+`{ ok: false }` without touching anything, and so does `editMessage` (it also
+refuses a message that is not `is_from_me`); `unsendMessage` fires the RPC
+first and only finds the ceiling on the VERIFY pass, so a guid outside the
+window still reports `{ ok: false }` but may have mutated the real row on the
+way there — "no confirmable effect," not a guaranteed no-op. FakeGateway
 must enforce the identical window regardless: finding the target guid by
 scanning ALL of `this.messages` unconditionally would let the fake succeed
 at targeting a message the real path can't reach (parity rule 2) — a
@@ -219,6 +252,46 @@ prevent.
   this Gateway because `ImsgMessage` has no subject field. The `url` submode is
   exposed separately as `sendRichLink` because openclaw treats URL and
   text/subject/effect/reply as mutually exclusive modes.
+  `opts.textFormatting` is a list of ranges over the text in **UTF-16 code
+  units** (a JS string index; an emoji is two units): `styles`
+  (bold/italic/underline/strikethrough, macOS 15+, silently dropped on older
+  hosts), `effect` (a named macOS 27 text effect, resolved to Apple's id in
+  `resolveTextFormatting`), and `mention` — a **confirmed @mention**
+  (imsg#13, merged into `mapier/deploy` as `7c31772` — the pinned submodule
+  — `docs/send.md` "Text formatting and mentions"; the rules below mirror
+  `IMsgMentionFormatting.m` at that revision). `mention` is the EXACT `IMHandle.ID` of a participant of the
+  target chat as IMCore reports it (E.164 phone or the email), matched
+  byte-for-byte by the helper against the live participant list; the visible
+  text in the range must be the person's display name, never the handle (a
+  handle as visible text renders as a phone link with no highlight and no
+  notification, verified 2026-09-03 on an iPhone). Do not prefix the name
+  with "@": Messages' composer swallows the typed "@" and a genuine mention
+  row carries only the highlighted name (an "@" in the range simply renders
+  as text, as the 2026-09-03 SDK run showed). Formatting is **never
+  degraded**: the shared preflight `sendRichPreflight` /
+  `textFormattingRefusal` runs before the bridge is touched and refuses, with
+  a typed `SendResult.refused`, a mention range on a bridge without the
+  `mentionFormatting` marker (`mention-capability`), bad offsets on ANY range
+  — non-integer, zero length, outside the text, or splitting a surrogate pair
+  (`text-formatting-range`; the helper would otherwise silently drop a style
+  range and send plain text, which a caller cannot detect since formatting
+  is write-only), and a mention identifier that is not a bounded id or whose
+  visible text is the handle itself (`mention-identifier`). The helper
+  refuses a non-participant handle (`-32603` "Mention identifier is not a
+  participant handle of this chat", no row written), which `ImsgGateway`
+  classifies as `mention-not-participant`; a chat whose live participant
+  list is unreadable refuses every mention the same way. FakeGateway applies
+  the same preflight, checks membership against its chat record, and refuses
+  all mentions on an unreported-directory group. **A bare `ok:false` without
+  `refused` is NOT a no-send guarantee** (bridge timeout, transport loss);
+  only a `refused` result proves nothing was sent. Formatting and mentions
+  are write-only through this Gateway: `ImsgMessage` exposes neither, so the
+  smoke reads the confirmed-mention attribute (`__kIMMentionConfirmedMention`
+  followed by the handle) from `chat.db message.attributedBody` directly. The
+  `--only-mention` leg is opt-in via `--mention-handle` even in the full
+  Tier-2 run, because a confirmed mention notifies a real person.
+  **Host-verified 2026-09-03** through `ImsgGateway` on the shared Mac,
+  including the recipient-side highlight on an iPhone (see the ledger).
 - **`sendAttachment(chatId, filePath, opts?)`** — `send.attachment`
   (`handleSendAttachment`). Targets an **existing** chat only. `opts.audio:true`
   sends the file as a native voice-note bubble; `opts.replyToGuid` sets an
@@ -265,8 +338,44 @@ prevent.
   balloon lands as its own row later. `SendResult.guid` is therefore always
   undefined here; FakeGateway must not return one either.
 - **`editMessage(chatId, targetGuid, text)`** — `message.edit`
-  (`handleMessageEdit`). **Edits mutate the existing row's text IN PLACE: no
-  new row, no `subscribe()` event.** `MessageWatcher`'s cursor is a ROWID
+  (`handleMessageEdit`; imsg `docs/edit.md`). Capability-gated on the
+  `editMessage` marker (see above): on macOS 27 the helper calls the
+  five-argument `editMessageItem:atPartIndex:withNewPartText:newPartTranslation:backwardCompatabilityText:`
+  with part index 0 and the new text as backwards-compatibility text, and the
+  RPC answers `{ok:true}` on invocation only. **Preflight before firing**, same
+  discipline as `tapback`/`deleteMessage`: the guid must be inside the scan
+  window — located by a short poll (3 × 1 s, sleeping only between reads),
+  because a just-sent guid can lag history by a beat and a one-shot read
+  would fail closed on a message about to appear —
+  and the message must be an **editable own plain-text message**
+  (`isEditableOwnTextMessage` in `gateway/types.ts`, shared by both
+  implementations): `is_from_me` (Apple only permits editing your own
+  messages and the helper does not check), non-empty `text`, and no
+  attachments/poll — the RPC always edits part 0, which on those rows is not
+  the text, and a retracted row has nothing left to edit. Anything else is
+  refused as `ok:false, effectStarted:false` without touching the bridge, as
+  is empty or whitespace-only text. Text identical to the current row is the
+  idempotent `skipped:'unchanged'` (`ok:true`, nothing fired). The whole
+  decision is one shared function (`decideEditMessagePreflight`) so the two
+  implementations cannot drift. Known gap: a rich-link balloon carries its
+  URL as `text` and nothing on `ImsgMessage` marks it, so the real path
+  fires on it and the read-back decides; FakeGateway's rich-link row has no
+  text and is refused. After the RPC fires, a structured `-32603` whose
+  `data` is one of the helper's pre-invoke refusals (chat/message not found,
+  no selector, bad signature) is `effectStarted:false`; a bridge timeout or
+  any other `-32603` (an exception after IMChat was invoked) and an
+  unconfirmed read-back are `ok:false, effectStarted:true` — a consumer
+  reconciles those rather than treating them as a no-op. **Host-verified
+  2026-09-03** through `ImsgGateway` on the shared Mac (see the ledger
+  below); recipient-side rendering remains unobserved. `unsendMessage`
+  deliberately keeps its fire-first shape: retracting a just-sent row is a
+  legitimate use and its verify pass is the existing contract; a matching
+  preflight is a follow-up, not part of this change. Native CLI/RPC E2E on macOS 27 `26A5421a` (imsg#11, chat 8): both
+  paths edited a fresh own message and read the new text back on the same
+  guid/ROWID, with `message.date_edited` stamped — that column is not exposed
+  through `messages.history`, so the SDK smoke reads it from chat.db directly
+  while the gateway verifies by text read-back. **Edits mutate the existing
+  row's text IN PLACE: no new row, no `subscribe()` event.** `MessageWatcher`'s cursor is a ROWID
   high-water mark (`WHERE ROWID > cursor`), so an UPDATE to an existing row is
   structurally invisible to the watch stream — the only way to observe an
   edit is re-reading `history()` and comparing text for a guid you already
@@ -340,6 +449,84 @@ both implementations — none of Apple's group primitives apply to a 1:1 chat.
   and the receiving iPhone displayed Mapi's new contact info, closing the
   receiver-side verification gap.
 
+- **Chat backgrounds** — `chatBackgroundStatus` / `setChatBackground` /
+  `removeChatBackground` (Mapier-Labs/imsg#12, `chat.background.status|set|remove`).
+  A background is chat-scoped state recorded in chat.db's background tables,
+  not a message row: there is no `subscribe()` event and no history row on
+  either implementation. DM and group chats both accept all three verbs.
+  `chatBackgroundStatus` is a plain chat.db read (no selector marker, but it
+  needs the imsg#12 binary: an older build answers `-32601` and the call
+  throws). `null` means the chat does not exist (`-32602`); any other failure
+  is thrown, so a transient rpc/bridge fault can never masquerade as "no such
+  chat". It returns the persisted background channel GUID, which **lags
+  imagent** — a durable snapshot, never the live IMChat state.
+  `setChatBackground` supports the single runtime-verified `gradient` preset.
+  On the native side the RPC returns on helper acceptance — its response
+  embeds the pre-mutation chat.db snapshot, so no separate preflight read —
+  and the pipeline (PosterBoard builder → hidden `OverFullScreen` editor →
+  ChatKit poster/watch payloads → `setTranscriptBackgroundAndSendToChat:transferID:`)
+  runs asynchronously, bounded by per-stage watchdogs and a 90 s overall cap.
+  `ImsgGateway` therefore polls `chat.background.status` under a 90 s
+  deadline on a **monotonic** clock (`performance.now()`; a wall-clock
+  rollback cannot stretch the wait — the native CLI's own window; read first,
+  sleep 1 s between), in the pure loop `src/gateway/chat-background.ts`. Each poll is a
+  local chat.db read. The helper's operation record is a bridge round-trip on
+  Messages' main thread — it competes with the pipeline itself and, because
+  the native JSON-RPC loop is strictly serial, holds every other gateway verb
+  for up to 10 s on a stall — so it is read only (a) once, pulled forward,
+  when a NEW candidate appears (a background GUID different from the
+  pre-mutation snapshot) and (b) on a 15 s cadence for early failure
+  detection; a helper read that times out doubles that gap, up to 60 s, and
+  chat.db polling carries on meanwhile. **Success requires operation
+  correlation**: a candidate is accepted only when it equals the record's
+  `transfer_id` (the identifier IMChat persists as the background GUID, imsg
+  `docs/chat-background.md`). A changed guid, a newer `set` event, or both
+  are NOT evidence — a delayed write from an earlier operation satisfies them
+  — and a helper that no longer tracks the operation (bounded record table,
+  Messages relaunch) leaves nothing to correlate with, so that case ends the
+  wait as ambiguous rather than guessing. A bridge-timeout on a verification
+  read keeps polling; any other read failure (dead rpc child, transport loss)
+  ends the wait as ambiguous. `ok:true` carries the persisted GUID; a re-set
+  replaces the background and the GUID changes. FakeGateway mints a fresh GUID
+  per set from a sequence it persists in its snapshot. Result semantics
+  follow `shareNamePhoto`: `effectStarted:false` is a proven preflight
+  rejection — capability absent, `-32602` (unknown chat, bad preset), or a
+  helper refusal the SDK recognises in the JSON-RPC `error.data` (busy with
+  another background operation — the helper holds one in-process lock —,
+  guard mismatch, missing selector/runtime, "did not queue"); `ok:false,
+  effectStarted:true` means the effect may have started and persistence was
+  not proven — helper record `failed`, the deadline passed, an
+  rpc-child/transport failure, a bridge timeout, or any other `-32603` such as
+  an exception raised after IMChat was invoked (the native server reports all
+  of these under one code with the reason only in `data`) — and must be
+  reconciled, never reported as a proven no-op.
+  `removeChatBackground` is driven by the helper's **live** IMChat GUID, never
+  the caller's chat.db snapshot. The optional `expectedGuid` is a
+  compare-and-clear guard evaluated against that live GUID **first**, before
+  the no-background check: a mismatch — including a guard on a chat with no
+  live background — is `ok:false, effectStarted:false` and leaves the
+  background in place. An empty string is no guard (`normalizeChatBackgroundGuard`
+  in `gateway/types.ts`, shared by both implementations; the wire only
+  carries a non-empty one). Only then is a chat with no live background the
+  explicit `skipped:'no-background'` no-op (`ok:true`, IMChat never invoked).
+  The gateway reads chat.db before firing (the remove response's own snapshot
+  is post-invoke) and after a real clear checks that response, then polls
+  under a 30 s deadline for a `clear` event newer than the baseline; an unchanged empty
+  snapshot counts only when the pre-mutation read recorded the background
+  that is now gone, because an already-lagging empty snapshot proves nothing.
+  Native Set/Remove semantics were smoke-verified on macOS 27 `26A5421a`
+  (matching live GUID, chat.db event, cache, watch cache, upload metadata),
+  and the production CLI/RPC path went through its matched-build E2E before
+  imsg#12 merged. The SDK verbs were **host-verified 2026-09-03** through
+  `ImsgGateway` on the shared Mac (`--only-chat-background` leg of
+  `scripts/tier2-smoke.ts`; see the ledger below); recipient-side rendering,
+  group chats and the replace path were **eyeballed 2026-09-04** (ledger
+  entry below), with one receiver-side condition: a brand-new thread from a
+  sender the iPhone has never seen may render no background until the
+  thread is "known" (see the entry). The leg
+  (`scripts/tier2-chat-background-leg.ts`) stops at the first failed check
+  and never clears a background whose guid it did not read back.
+
 **Host-verification ledger.** Exercised through `ImsgGateway` on the host Mac
 2026-07-14 (`scripts/tier2-smoke.ts`, chat 3996):
 
@@ -361,6 +548,118 @@ Each leg prints an EYEBALL step because a local write is not proof of
 receiver-visible delivery (the group-photo lesson). The `sendRich`
 text/effect/reply path was already live-verified.
 
+Exercised 2026-09-03 on the shared Mac (macOS 27 `26A5421a`, user
+`mapidev`, disposable DM chat 8, SDK `bf92147` against the deployed imsg#12
+CLI/helper: `bridge_version 2`, `v2_ready true`, `chatBackgroundSetGradient
+true`, `chatBackgroundRemove true`; `scripts/tier2-smoke.ts 8
+--only-chat-background`, run dir `map175-sdk-bg-e2e.PCVLad`):
+
+- **`setChatBackground` / `removeChatBackground` / `chatBackgroundStatus`**
+  — live-verified: both capability rows; baseline `backgroundSet:false`;
+  Set Gradient persisted a NEW background guid in ~7 s and a separate status
+  read returned the same guid; Remove with `NOT-THE-LIVE-GUID` →
+  `ok:false, effectStarted:false` with the background unchanged (the logged
+  `ImsgRpcError` is the deliberate mismatch); guarded Remove cleared it,
+  status read `backgroundSet:false`, and an unguarded Remove on the bare
+  chat → `skipped:'no-background'`. `ALL PASS`, exit 0; the audit recorded
+  two events, both in chat 8; native status identical before and after and
+  the fixture back at its no-background baseline. The `live-smoke.ts 8
+  --read-only` gate passed first. Not observed: the receiving device
+  rendering the Gradient; not covered: group chats, the replace (re-set)
+  path, relay/public-API integration.
+
+Exercised 2026-09-03 on the same host (SDK `6cf6ac5` against the same
+deployed helper: `editMessageItemTranslation true`, the two four-argument
+markers false; `scripts/tier2-smoke.ts 8 --only-edit-message`, run dir
+`map175-sdk-edit-e2e.fgUq4t`):
+
+Exercised 2026-09-03 on the same host (SDK `6e28c82` against the deployed
+imsg#13 helper, `mentionFormatting true`; disposable group chat 12 with
+three phone-handle participants; `scripts/tier2-smoke.ts 12 --only-mention
+--mention-handle <participant IMHandle.ID> --mention-name <display name>`, run dir
+`map175-sdk-mention-e2e.PuauKG`):
+
+- **`sendRich` confirmed @mention** — live-verified: capability row;
+  `@Neo tier2-smoke 21:13:08 mention` sent
+  (`86246294-B16D-4E5C-9E15-D5E80C90CB14`, row 3143) and read back on the
+  same guid; `chat.db attributedBody` carries `__kIMMentionConfirmedMention`
+  at byte 266 followed by the handle at byte 300; a non-participant handle
+  refused by the helper (`-32603` "Mention identifier is not a participant
+  handle of this chat") → `refused:'mention-not-participant'`, a range
+  outside the text → `'text-formatting-range'`, and the handle as visible
+  text → `'mention-identifier'`, none of the three texts in history
+  afterwards. 9/9 PASS, `ALL PASS`, exit 0; the audit recorded exactly one
+  event, in chat 12; native status identical before and after. The
+  `live-smoke.ts 12 --read-only` gate passed first (6/6). **Recipient-side
+  observed** this time: on the mentioned participant's iPhone the message
+  rendered with "@Neo" highlighted in the same style as a native mention.
+  Not covered: email-handle mentions (not covered natively either), the
+  `send-attachment` / multipart mention legs (no SDK surface).
+
+- **`editMessage`** — live-verified: capability row from the three-marker
+  fold; marker message sent (`73263626-5A07-4B3C-8244-D3133B8A8EA6`), edited,
+  new text read back on the SAME guid, `chat.db message.date_edited`
+  stamped (`810141791007747072`); unchanged text → `skipped:'unchanged'`;
+  whitespace text → `ok:false, effectStarted:false` with the edited text
+  still in place; the chat's newest inbound row (the DM partner's echo of
+  the marker) → `ok:false, effectStarted:false` and untouched. 10/10 PASS,
+  `ALL PASS`, exit 0; native status identical before and after. The
+  `live-smoke.ts 8 --read-only` gate passed first (6/6). Not observed: the
+  receiving device rendering "Edited" (the inbound echo carried the original
+  text, which is the partner's copy, not evidence either way).
+
+Eyeballed 2026-09-04 on the same host (SDK `5826316` = v0.3.0, deployed
+`imsg` 0.13.0 helper, all four 0.3.0 capability flags true) with a human
+watching the receiving iPhone (iOS 26.6.1) between steps, one gateway call
+per invocation (`scripts/eyeball.ts`, checked into no branch — it is an
+observation aid, not a check). Fixtures: DM chat 13 (the host's account →
+the phone, created that day) and group chat 12 (three phone handles):
+
+- **`setChatBackground` → receiver** — observed on the phone in the DM and
+  in the group: the conversation switched to the Gradient background and
+  Messages posted "<sender> changed the background." The phone's own
+  `imagent` log (Console.app, device streaming) showed the full inbound
+  path each time: `Received incoming transcript background` → asset fetch
+  → `Successfully blastdoor'd data` → `Writing poster` → `Update type:
+  setNewBackground`, ~6 s after the call. **Receiver-side condition (sticky,
+  trigger not isolated):** the first four Sets into the brand-new DM were
+  processed by the phone's `imagent` exactly the same way but Messages
+  rendered nothing and offered no Backgrounds entry in that DM; the host's
+  account was an email the phone had never seen. Right after that account
+  was saved as a contact the next Set rendered — and every later Set kept
+  rendering after the contact was deleted again, in the DM and in the
+  group, so whatever flips the thread from "does not render" to "renders"
+  stays flipped. Saving the contact is the time-correlated candidate, and
+  the phone's own background action in the group (before the group's first
+  successful Set) the other; separating them needs a fresh DM to a fresh
+  number. The Mac side gives no hint of any of this: chat.db, the upload
+  and the IDS send
+  (command 138, sealed for every endpoint of the number that advertises
+  `supports-transcript-backgrounds`) all succeed either way, so a
+  `setChatBackground` `ok:true` is proof the Mac set it, not that the
+  recipient can see it.
+- **`removeChatBackground` → receiver** — observed in the DM and the group:
+  the background returned to default on the phone. The compare-and-clear
+  guard was exercised for real along the way: the phone had cleared and the
+  host re-set the background between two steps, so a Remove carrying the
+  earlier guid answered `ok:false, effectStarted:false` (the helper's
+  "does not match expected GUID" refusal) and left the live background in
+  place; the Remove with the live guid cleared it.
+- **Reverse direction** — a background set and a background cleared from
+  the phone both arrived in the host's chat.db (`item_type 3`,
+  `group_action_type 4` / `6`, `handle_id` = the phone) and
+  `chatBackgroundStatus` tracked them. Host-initiated actions land as
+  `is_from_me 0, handle_id 0` rows; the status read keys off the chat's
+  live background guid, not that column.
+- **`editMessage` → receiver** — observed in the DM: the phone showed the
+  SAME bubble with the new text and the "Edited" label, no new bubble
+  (marker `6026CE4C-1CF1-4B97-8C90-925834F59272`).
+- Three IDS endpoints are registered for the receiving number; one of them
+  (a macOS 15 Mac, which has no transcript backgrounds) is dropped by the
+  sender's capability policy on every Set (`IF lacks(supports-transcript-
+  backgrounds) THEN failure`). That is per-endpoint pruning, not a failure
+  of the send, and the phone's endpoints are unaffected.
+
 - **subscribe(sinceId?)** — long-lived event stream of new messages/reactions across all
   chats the host Mac's Messages account can see. `sinceId` is an **exclusive** cursor: only
   events with `id > sinceId` are delivered (catch-up semantics, not "starting at"). Today
@@ -783,8 +1082,16 @@ harness (`tsx --test`, see `package.json`). Required cases:
   returns `ok:false` for fewer than two options or an unknown chat
 - `sendRichLink` echoes an outbound row and returns `ok:false` for an unknown chat; preview
   metadata is not queryable through `ImsgMessage`
+- `sendRich` with a confirmed mention of a participant sends once (DM and group, alongside
+  styles); a non-participant handle, a wrongly formatted participant, a range outside the
+  text (mention OR style), an empty or padded handle, the handle as visible text, an
+  unreported group directory, and a missing `mentionFormatting` marker each return
+  `ok:false` with the matching typed `refused` reason and nothing sent
 - `editMessage` changes the target row's text in place — same row count before/after, no
-  new row
+  new row; refuses an inbound (not `is_from_me`) message, empty/whitespace text, and our own
+  message outside the scan window without mutation;
+  unchanged text is the idempotent `skipped:'unchanged'`; returns `ok:false` without
+  mutation when the `editMessage` capability marker is absent
 - `unsendMessage` retracts the target row (text clears, row persists);
   `deleteMessage` is dispatch-only with no stable history postcondition (the
   fake conservatively preserves the row); both return `ok: false` for an
@@ -794,13 +1101,19 @@ harness (`tsx --test`, see `package.json`). Required cases:
 - `renameGroup`/`addParticipant`/`removeParticipant` are reflected in a message sent
   afterward (`chat_name`/`participants`) and return `ok: false` against a DM
 - `setGroupPhoto`/`leaveGroup` return `ok: true` against a group and `ok: false` against a DM
-- patched sticker, group-photo, and participant verbs return `ok:false` without mutation
-  when their `imsg status` capability markers are absent
+- patched sticker, group-photo, participant, and chat-background verbs return `ok:false`
+  without mutation when their `imsg status` capability markers are absent
+- chat background: `setChatBackground` persists a NEW guid on a DM and a group (a re-set
+  changes the guid), `chatBackgroundStatus` reflects it, `removeChatBackground` clears it;
+  remove on a bare chat is the explicit `no-background` skip (also with an empty guard), a
+  mismatched `expectedGuid` is a preflight rejection that leaves the background (and is
+  checked before the no-background branch, so a stale guard on a bare chat rejects), and an
+  unknown chat never starts an effect
 - `recentReactions` surfaces an inbound custom-emoji reaction (`reaction: 'custom'`) with the
   real `emoji` intact
 - Fake-only restart coverage snapshots and restores a world, then proves
-  `sendStatus`, `checkHandle`, Name & Photo idempotency, current group metadata,
-  fixture state, and monotonic IDs survive exactly
+  `sendStatus`, `checkHandle`, Name & Photo idempotency, chat backgrounds (and their
+  guid sequence), current group metadata, fixture state, and monotonic IDs survive exactly
 
 FakeGateway runs this suite in CI on every PR. ImsgGateway runs it as a manual runbook step on
 the host Mac (see `docs/host-mac-control.md`) until a host-Mac CI runner exists — at that point

package/docs/imcore_selectors.md

@@ -66,8 +66,9 @@ for per-host fragility, and it's the reason for nearly every defensive choice in
    version, and why "wired ≠ host-verified."
 
 **The upside:** runtime resolution also buys adaptivity. One dylib can carry fallbacks
-and pick per host — which is exactly why `handleEditMessage` tries `editMessageItem:…`
-then falls back to `editMessage:…`, and why a fixed `leaveChat` would probe candidates
+and pick per host — which is exactly why `handleEditMessage` tries the macOS 27
+five-argument `editMessageItem:…newPartTranslation:…` first, then `editMessageItem:…`,
+then `editMessage:…`, and why a fixed `leaveChat` would probe candidates
 and choose whichever the host has. A statically-linked binary couldn't branch like that;
 a runtime-resolved one straddles multiple macOS versions from a single build.
 
@@ -97,7 +98,7 @@ Ex.
 ### Mutate a message
 | Verb | Handler | Call | Host |
 |---|---|---|---|
-| `edit-message` | `handleEditMessage` | **IMChat** `editMessageItem:atPartIndex:withNewPartText:backwardCompatabilityText:` (fallback `editMessage:atPartIndex:…`) | **⚠ old selectors false; replacement identified, not wired/smoked — see MAP-175 findings** |
+| `edit-message` | `handleEditMessage` | **IMChat** `editMessageItem:atPartIndex:withNewPartText:newPartTranslation:backwardCompatabilityText:` (macOS 27; fallbacks `editMessageItem:…` / `editMessage:…`) | ✓ wired on macOS 27 (imsg#3), native CLI/RPC E2E'd (imsg#11); SDK verb capability-gated + preflighted, host `tier2-smoke --only-edit-message` pending |
 | `unsend-message` | `handleUnsendMessage` | **IMChat** `retractMessagePart:` | ✓ |
 | `delete-message` | `handleDeleteMessage` | **IMChat** `deleteChatItems:` (device-local only) | ✓ |
 
@@ -109,7 +110,7 @@ Ex.
 | `set-display-name` | `handleSetDisplayName` | **IMChat** `_setDisplayName:` (+ `sendGroupPhotoUpdate:`) | ✓ |
 | `update-group-photo` | `handleUpdateGroupPhoto` | **IMChat** `sendGroupPhotoUpdate:` + **IMFileTransferCenter** `createNewOutgoingGroupPhotoTransferWithLocalFileURL:` | ✓ |
 | `create-chat` | `handleCreateChat` | **IMChatRegistry** `chatForIMHandle:` / `chatForIMHandles:` (+ `_setDisplayName:`) | ✓ |
-| **`leave-chat`** | `handleLeaveChat` | **IMChat** `leaveChat` | **✗ selector gone ([#5]); replacement identified, not wired/smoked — see MAP-175 findings** |
+| **`leave-chat`** | `handleLeaveChat` | **IMChat** `leave` (macOS 27; `leaveChat` fallback for older hosts) | **⚠ call site updated to `leave`; not yet tested on relay e2e** |
 | `delete-chat` | `handleDeleteChat` | **IMChatRegistry** `sharedInstance` (delete path selector-gated) | ✗ not wired above |
 
 ### Read / presence
@@ -129,8 +130,10 @@ Ex.
 
 The selector **markers** reported by `imsg status --json` are probed in
 `IMsgInjected.m` near the top of the file: it checks `IMChat` for
+`editMessageItem:…newPartTranslation:…` (marker `editMessageItemTranslation`),
 `editMessageItem:…`, `editMessage:…`, `retractMessagePart:`, `sendMessage:reason:`.
-Add a probe there when adding a verb so the SDK can capability-gate it.
+Add a probe there when adding a verb so the SDK can capability-gate it; the SDK's
+`editMessage` capability is any one of the three edit markers.
 
 ## macOS 27 operation callsites — MAP-175
 
@@ -139,12 +142,12 @@ operation callsites were found and verified by **Neo Shangguan** for MAP-175.
 
 | Operation | Current bridge selector | macOS 27 entrypoint found | Downstream operation dispatch | Integration status | Found by |
 |---|---|---|---|---|---|
-| `leave-chat` | `-[IMChat leaveChat]` — absent | `-[IMChat leave]` | `[provider _chat_leave:chat]` | Found; not wired/live-smoked | **Neo Shangguan** |
-| `edit-message` | Four-argument `-[IMChat editMessageItem:…]` / `-[IMChat editMessage:…]` — absent | Five-argument `-[IMChat editMessageItem:…newPartTranslation:…]` | `[provider _chat:chat sendEditedMessageItem:editedItem previousMessageItem:originalItem partIndex:index editType:1 backwardCompatabilityText:text]` | Found; not wired/live-smoked | **Neo Shangguan** |
-| `mentions` | No bridge operation | Confirmed-mention `NSAttributedString` attributes; no dedicated send selector | Existing `IMMessage` construction → `IMChat` send path | Payload construction found; not wired/live-smoked | **Neo Shangguan** |
-| `text-styling` / `text-effects` | No bridge operation | IM text-style/effect attributes on `NSAttributedString`; no dedicated send selector | Existing `IMMessage` construction → `IMChat` send path | Payload construction found; not wired/live-smoked | **Neo Shangguan** |
+| `leave-chat` | `-[IMChat leaveChat]` — absent | `-[IMChat leave]` | `[provider _chat_leave:chat]` | Call site updated to `leave`; not yet tested on relay e2e | **Neo Shangguan** |
+| `edit-message` | Four-argument `-[IMChat editMessageItem:…]` / `-[IMChat editMessage:…]` — absent | Five-argument `-[IMChat editMessageItem:…newPartTranslation:…]` | `[provider _chat:chat sendEditedMessageItem:editedItem previousMessageItem:originalItem partIndex:index editType:1 backwardCompatabilityText:text]` | Wired (imsg#3), native CLI/RPC E2E'd (imsg#11) and SDK verb host-verified 2026-09-03 on macOS 27 | **Neo Shangguan** |
+| `mentions` | `send-rich` / `send.rich` `text_formatting[].mention` (imsg#13) | Confirmed-mention `NSAttributedString` attribute (`__kIMMentionConfirmedMention`) resolved at runtime; no dedicated send selector | Existing `IMMessage` construction → `IMChat` send path | Wired + native E2E'd 2026-09-03 (attribute keys match a genuine iPhone mention row; highlight + notification on the recipient); SDK verb host-verified 2026-09-03 incl. recipient highlight | **Neo Shangguan** |
+| `text-styling` / `text-effects` | No bridge operation | IM text-style/effect attributes on `NSAttributedString`; no dedicated send selector | Existing `IMMessage` construction → `IMChat` send path | Wired + tested e2e relayside | **Neo Shangguan** |
 | `contact-card` | No contact-card-specific bridge operation | `.vcf` attachment identified by `kUTTypeVCard` / `public.vcard` | Existing `IMFileTransfer` attachment send path | Attachment representation found; not live-smoked | **Neo Shangguan** |
-| `chat-background` | No bridge operation | `-[IMChat setTranscriptBackgroundAndSendToChat:transferID:]` | `[provider _chat:chat setTranscriptBackgroundAndSendToChat:background transferID:transferID]` | Set/remove control flow found; asset/transfer contract not wired/live-smoked | **Neo Shangguan** |
+| `chat-background` | `chat.background.set` / `chat.background.remove` / `chat.background.status` (Mapier-Labs/imsg#12, merged) | `-[IMChat setTranscriptBackgroundAndSendToChat:transferID:]` | `[provider _chat:chat setTranscriptBackgroundAndSendToChat:background transferID:transferID]` | Native bridge merged after matched-build CLI/RPC E2E; SDK verbs `setChatBackground` / `removeChatBackground` / `chatBackgroundStatus` in this repo; relay command + recipient-side validation pending | **Neo Shangguan** |
 | `location-request` | No bridge operation | `+[MSMessage findMyLocationRequestMessage]` | `+[CKComposition compositionWithMSMessage:appExtensionIdentifier:]` using `IMBalloonBundleIdentifierWaldo` → `-[CKChatController setComposition:]` | Factory/staging callsites found; payload/bridge route pending; not wired/live-smoked | **Neo Shangguan** |
 
 The summary records stable selector names for implementation. Numeric callsite
@@ -191,9 +194,9 @@ replacement entrypoint; bridge code should call it rather than reaching into
 group-leave operation, so it is not a `leaveChat` replacement.
 
 The existing `leaveChat` selector can remain as the older-system path, with
-`leave` as a runtime-gated fallback. This is a research result, not a release
-claim: the native fork has not been rebuilt/injected with the fallback and no
-live group-leave smoke has been performed.
+`leave` as a runtime-gated fallback. **Update:** the bridge call site has since
+been updated to probe `leave`; it has not yet been tested end-to-end through
+relay (no relay e2e group-leave smoke performed).
 
 ### `edit-message` — found by Neo Shangguan
 
@@ -383,9 +386,11 @@ As with mentions, these mutation helpers live in the `/System/iOSSupport`
 ChatKit image and are evidence for payload shape rather than bridge call
 targets. A bridge implementation should resolve the native
 `IMSharedUtilities` symbols by name, construct the attributed payload itself,
-and reuse the existing `IMMessage`/`IMChat` send path. The marker values,
-serialization behavior, recipient rendering, and range handling still require
-a development-profile live send smoke.
+and reuse the existing `IMMessage`/`IMChat` send path. **Update:** this is now
+wired and tested end-to-end through relay — the attributed payload is
+constructed over the requested ranges and sent via the existing path, with
+effects animating on device on the `mapidev` development profile. Inbound
+styled-text parsing remains open if that direction is needed.
 
 ### `contact-card` — found by Neo Shangguan
 
@@ -494,21 +499,49 @@ else:
 ```
 
 `-[CKCoreChatController updateTranscriptBackground:transferID:]` begins at
-`0x1dbc7c538`. Its non-null asynchronous completion and null removal branch
-converge on the same `IMChat` selector:
+`0x1dbc7c538`. Its non-null branch stages the prepared poster and watch payloads
+on disk, obtains the poster URL's `absoluteString`, and then converges with the
+null removal branch on the same `IMChat` selector:
 
 ```text
-set:     [chat setTranscriptBackgroundAndSendToChat:preparedBackground
+set:     [chat setTranscriptBackgroundAndSendToChat:posterURL.absoluteString
                                         transferID:transferID]  callsite 0x1dbc7cc38
 remove:  [chat setTranscriptBackgroundAndSendToChat:nil
                                         transferID:transferID]  callsite 0x1dbc7c710
 ```
 
+The `absoluteString` selector stub immediately before the non-null callsite is
+at `0x1e0016430` and resolves to selector address `0x1f5907443`. A live smoke
+that passed the `CKTranscriptBackground` object itself produced
+`-[ChatKit.CKTranscriptBackground length]: unrecognized selector`, further
+confirming that the daemon-facing first argument is the staged URL string, not
+the ChatKit wrapper object.
+
 This establishes that removal is represented by a null background sent through
-the same operation, not by a separate remove selector. A complete bridge recipe
-still needs the concrete background object/archive construction and channel
-transfer contract. Those details, recipient behavior, and both set/remove
-operations require a development-profile live smoke before release claims.
+the same operation, not by a separate remove selector. The complete native
+recipe archives the poster configuration, prepares its watch snapshot, stages
+the resulting `posterData` and `watchData` at the poster URL and its
+`im_associatedWatchBackgroundURL`, and passes the poster URL string to IMChat.
+Recipient behavior outside the development profile still requires validation.
+
+A read-only runtime probe on the macOS 27 development host (build `26A5421a`)
+confirmed that `IMChat` responds to
+`setTranscriptBackgroundAndSendToChat:transferID:`. Its live Objective-C method
+signature returns `void`, has four total arguments (`self`, `_cmd`, and two
+object arguments), and `+[NSString stringGUID]` is available for generating the
+transfer identifier. A development-profile semantic smoke then generated and
+staged a Gradient background, invoked IMChat, and matched the live background
+GUID to the persisted `set` event and cache assets. Passing a null first
+argument with a fresh transfer identifier subsequently cleared the same live
+GUID and persisted a matching `clear` event. This verified the direct native
+set/remove operations. The production bridge (Gradient builder, null-background
+removal handler, capability probes, standalone smoke scripts, and
+persistence-confirming CLI/RPC surfaces) then passed its matched CLI/dylib
+E2E on the development profile and merged as Mapier-Labs/imsg#12 into
+`mapier/deploy`. This repo's `ImsgGateway` exposes it as `setChatBackground`,
+`removeChatBackground`, and `chatBackgroundStatus` (see
+`docs/gateway-contract.md` §2 "Chat backgrounds"). Relay command wiring and
+recipient-side end-to-end coverage remain pending.
 
 ### `location-request` — found by Neo Shangguan
 
@@ -558,13 +591,13 @@ for the MAP-175 findings above:
 
 | Operation | Readiness | What is resolved | Remaining implementation work |
 |---|---|---|---|
-| `leave-chat` | **Ready to wire** | macOS 27 `-[IMChat leave]` entrypoint and `_chat_leave:` dispatch | Add the runtime-gated `leave` fallback while retaining the older `leaveChat` path; rebuild/inject and live-smoke on `mapidev` |
-| `edit-message` | **Ready to wire** | Five-argument selector, argument order, edited-item builder, and daemon dispatch | Add an accurately cast `objc_msgSend`, runtime probe/fallbacks, and ordinary-edit `nil` translation handling; rebuild/inject and live-smoke |
-| `mentions` | **Partially blocked** | Native mention attribute symbols and confirmed-mention mutation path | Confirm the target identity/handle attribute value, serialization, and range behavior with a development-profile send/receive smoke |
-| `text-styling` / `text-effects` | **Prototype-ready** | Transport attributes, style bit mapping, effect type/name mapping, and existing send boundary | Resolve symbols dynamically, construct/serialize the attributed payload, validate mixed/attachment ranges and recipient rendering, then live-smoke |
+| `leave-chat` | **Call site updated** | macOS 27 `-[IMChat leave]` entrypoint and `_chat_leave:` dispatch; call site re-pointed to `leave` with the `leaveChat` fallback retained | Test end-to-end through relay on `mapidev` (bridge call site updated, relay e2e not yet run) |
+| `edit-message` | **Native merged (imsg#3/#11); SDK verb host-verified 2026-09-03** | Five-argument selector, argument order, edited-item builder, daemon dispatch, runtime probe/fallbacks, native CLI/RPC E2E | Relay `message.moderate edit` mapping of `effectStarted`; recipient-side rendering check |
+| `mentions` | **Native merged (imsg#13, `7c31772`); SDK verb host-verified 2026-09-03** | Attribute key + handle value confirmed against a genuine row, recipient highlight + notification, membership fail-closed | Relay `message.send` payload for mention ranges |
+| `text-styling` / `text-effects` | **Done — tested e2e relayside** | Transport attributes, style bit mapping, effect type/name mapping, existing send boundary; attributed payload constructed and sent through the relay path, animating on device | — (inbound styled-text parsing still open if needed) |
 | `contact-card` | **Prototype-ready** | vCard UTI/content representation and reuse of the existing attachment-transfer path | Choose/validate MIME and transfer metadata, accept or serialize `.vcf` input, verify recipient rendering and inbound parsing |
-| `chat-background` remove | **Ready to prototype** | Null-background remove semantics, transfer-ID generation, `IMChat` entrypoint, and daemon dispatch | Wire the operation and validate removal plus recipient state on the development profile |
-| `chat-background` set | **Partially blocked** | Set control flow, Watch-data preparation selector, `IMChat` entrypoint, and daemon dispatch | Recover/reproduce the concrete background archive and channel-transfer contract; then validate upload, recipient rendering, and retry behavior |
+| `chat-background` remove | **Native merged (imsg#12); SDK verb in this repo** | Null-background semantics, transfer-ID generation, selector ABI, live clear, persisted clear event, race-guard contract, matched-build CLI/RPC E2E | Host-Mac `tier2-smoke.ts --chat-background`; relay `chat.background.remove` command; validate recipient state |
+| `chat-background` set | **Native merged (imsg#12); SDK verb in this repo** | Gradient configuration build, archive, poster/watch snapshot, staging contract, URL-string IMChat argument, live set, persisted event, cache/upload metadata, matched-build CLI/RPC E2E | Host-Mac `tier2-smoke.ts --chat-background`; relay `chat.background.set` command; validate recipient rendering and retry behavior |
 | `location-request` | **Callsite-only** | Waldo feature gate, `MSMessage` factory selector, `CKComposition` wrapper, and app-extension identifier | Recover the factory's serialized Waldo payload and a safe bridge route into the existing send path without depending on a `CKChatController` UI instance |
 
 Every new or replaced bridge path still needs defensive runtime capability
@@ -592,9 +625,10 @@ macOS version:
    the matched CLI+dylib, inject (SIP off), and smoke.
 
 For `leave-chat`: `handleLeaveChat` and everything above it (relay → RPC → file
-IPC → dispatch) is intact. The only dead link is `-[IMChat leaveChat]`. MAP-175
-identified `-[IMChat leave]` as its macOS 27 replacement; the remaining work is
-to re-point that call, add a status marker, rebuild/inject the matched native
-fork, and live-smoke it on the development profile.
+IPC → dispatch) is intact. The only dead link was `-[IMChat leaveChat]`;
+`-[IMChat leave]` is its macOS 27 replacement and the call site has since been
+re-pointed to it (with `leaveChat` retained as the older-host path). The
+remaining work is to test it end-to-end through relay on the development
+profile.
 
 [#5]: https://github.com/Mapier-Labs/imsg-sdk/issues/5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapier/imsg-sdk",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "TypeScript SDK for iMessage automation on macOS: the Gateway contract, ImsgGateway (real), and a device-free FakeGateway.",
   "license": "MIT",
   "repository": {