@mapier/imsg-sdk 0.2.2 → 0.3.0

package/docs/imcore_selectors.md

@@ -0,0 +1,634 @@
+# IMCore Selectors
+
+Every bridge handler in `Sources/IMsgHelper/IMsgInjected.m` ultimately calls one
+or more **private Apple selectors**. This maps each verb → handler → the selector
+it fires → the class and framework that selector lives in on the Mac. Use it when
+a macOS release breaks a verb (a selector renamed/removed, like `leaveChat` in
+[#5]) and you need to find what to re-point to.
+
+## Where the selectors live
+
+| Framework | Classes used here | Path (pre-26) |
+|---|---|---|
+| **IMCore** | `IMChat`, `IMMessage`, `IMMessageItem`, `IMMessagePartChatItem`, `IMChatRegistry`, `IMHandle`, `IMHandleRegistrar`, `IMAccount`, `IMAccountController`, `IMChatHistoryController`, `IMNicknameController`, `IMFileTransfer`, `IMFileTransferCenter`, `IMDaemonController`, `IMEmojiTapback`, `IMTapbackSender`, `IMMutableChatContext` | `/System/Library/PrivateFrameworks/IMCore.framework` |
+| **IDS** (Apple Identity Services) | `IDSIDQueryController` | `/System/Library/PrivateFrameworks/IDS.framework` |
+| **IMDPersistence / daemon** | `IMDPersistentAttachmentController` | daemon-side (IMSharedUtilities/IMDPersistence) |
+
+On **macOS 26** the framework binaries moved, and that changes how you inspect them:
+
+- **The binary moved off disk.** Pre-26, a framework's code was a real file inside its
+  bundle (`IMCore.framework/Versions/A/IMCore`) that you could open, link, or dump. On
+  macOS 26 that file is gone — the code exists **only inside the dyld shared cache**, one
+  giant pre-linked blob that's mapped into every running process. The `.framework` folder
+  may still be there, but it's an empty shell (Info.plist, no executable).
+- **`class-dump` must target the cache, not a raw binary.** `class-dump` lists a binary's
+  Objective-C classes and selectors — this is how you'd find what `leaveChat` became. Since
+  there's no on-disk `IMCore` binary to point it at, use a cache-aware tool
+  (`ipsw class-dump`, `dsdump`) or first extract the image out with `ipsw dyld extract`.
+- **Some C functions must be found at runtime (`dlsym`), not linked at build time.** To call
+  a function the computer needs its memory address. Normally the *linker* fills that in when
+  you build — but it needs an IMCore file/stub at build time, and there isn't one, so the
+  build would fail ("undefined symbol"). Instead the dylib looks the address up **while
+  running** and populates the map from function to address dynamically with function `dlsym` — the code is already in memory (via the shared cache),
+  so `dlsym("IMCreate…")` hands back a pointer to call through. 
+
+## Consequences of linking at runtime instead of compile-time
+
+Because there are no framework files to link against, the dylib resolves every
+private class, selector, and C symbol **by name at runtime** (`NSClassFromString`
++ `performSelector:` + `dlsym`). That trades the compiler's build-time guarantees
+for per-host fragility, and it's the reason for nearly every defensive choice in
+`IMsgInjected.m`:
+
+1. **No compiler safety net — this *is* why a selector like `leaveChat` fails the
+   way it does.** A renamed/removed name still **compiles fine**; it only fails when
+   it runs on a host that lacks it. So `#5` is a runtime `respondsToSelector: NO`,
+   not a build error. The whole "a selector died on the new OS" bug class exists
+   *because* resolution is deferred to runtime.
+2. **Fragile to OS version upgrades.** The same shipped dylib
+   can work on one macOS and silently no-op on another. That's why the SDK model is
+   **capability-based, not version-based**: `imsg status --json` probes each selector
+   live (`respondsToSelector:` / `dlsym != NULL`) and reports what actually resolved.
+3. **Everything is hand-declared, and nothing checks you.** No headers to `#import`,
+   so the dylib forward-declares the private classes/selectors itself and writes
+   function-pointer typedefs for C funcs. If Apple changes a method's *signature*
+   (arg types, not just its name), the declaration is now wrong with **no compiler to
+   flag it** — you get corruption or a crash at runtime. Correctness is on you + tests.
+   * Particularly dangerous for long arg calls. `performSelector:` only handles
+   simple signatures (object args, ≤2). For the 4-arg `editMessageItem:…` or the 13-arg `initWithSender:…` drop to `objc_msgSend` cast to a hand-written function-pointer type, and a wrong function declaration can cause memory corruption (usually compiler is there to guard).
+4. **Every call is defensive by necessity.** `respondsToSelector:` guard →
+   `performSelector:` → `@try/@catch`, degrading to `{ok:false}` rather than crashing
+   Messages.app. Compiler would have caught this at compile-time.
+5. **Two runtime gates stack.** The dylib both injects (`DYLD_INSERT_LIBRARIES`, SIP off) and resolves privately at runtime. macOS 26 library-validation/entitlement limits can block the injection entirely; even injected, the names must still resolve against the mapped shared cache. Neither is knowable at build time.
+6. **Testing is the only verification.** Since neither compiler nor linker validates any
+   of this, the only way to know a build works is to run it on a specific macOS and smoke
+   it — which is why the release record pins `imsg status --json` + `live-smoke` per OS
+   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 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.
+
+## The map
+
+Target class in **bold**; `sel` is the selector the handler invokes on it.
+
+**Note: In Objective C, the arguments are part of the function name itself, and are separated by colons. Square brackets denote a function call.**
+
+Ex. 
+```
+[chat sendMessage:aMessage reason:aReason];   // call
+        selector: sendMessage:reason:
+```
+
+### Send
+| Verb | Handler | Call | Host |
+|---|---|---|---|
+| `send-message` / `send-rich-link` | `handleSendMessage` | **IMChat** `sendMessage:reason:` (msg built on **IMMessage**, threaded via `setThreadOriginator:` / `setThreadIdentifier:`) | ✓ |
+| `send-poll` | `handleSendPoll` | **IMMessage** `initWithSender:time:text:…associatedMessageType:…` + `setBalloonBundleID:` + `setPayloadData:` → **IMChat** send | ✓ |
+| `send-poll-vote` / `-unvote` | `handleSendPollVoteMutation` | **IMChat** `sendMessage:` (summary-info mutation) | ✓ selector live, not wired above |
+| `send-multipart` / `send-attachment` | `handleSendMultipart` | **IMFileTransferCenter** `guidForNewOutgoingTransferWithLocalURL:` · `transferForGUID:` · `registerTransferWithDaemon:` · **IMDPersistentAttachmentController** `_persistentPathForTransfer:filename:highQuality:chatGUID:storeAtExternalPath:` · **IMFileTransfer** `setLocalURL:`/`setMimeType:`/`setTransferredFilename:` | ✓ |
+| `send-sticker` | `handleSendSticker` | **IMChat** `sendMessage:` targeting **IMMessagePartChatItem** (`guid`/`index`/`messagePartRange`) | ✓ |
+| `send-reaction` | `handleSendReaction` | **IMTapbackSender** `initWithTapback:chat:messagePartChatItem:` / `initWithTapback:chat:messageGUID:messagePartRange:messageSummaryInfo:threadIdentifier:` + `send`; emoji via **IMEmojiTapback** `initWithEmoji:isRemoved:`; legacy fallback **IMChat** `sendMessage:` | ✓ |
+| `notify-anyways` | `handleNotifyAnyways` | **IMChat** `markChatItemAsNotifyRecipient:` | ✗ not wired above |
+
+### Mutate a message
+| Verb | Handler | Call | Host |
+|---|---|---|---|
+| `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) | ✓ |
+
+### Group / chat management
+| Verb | Handler | Call | Host |
+|---|---|---|---|
+| `add-participant` | `handleAddParticipant` | **IMChat** `inviteParticipants:reason:` / `inviteParticipantsToiMessageChat:reason:` | ✓ |
+| `remove-participant` | `handleRemoveParticipant` | **IMChat** `removeParticipants:reason:` / `removeParticipantsFromiMessageChat:reason:` | ✓ |
+| `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** `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
+| Verb | Handler | Call | Host |
+|---|---|---|---|
+| `mark-chat-read` | `handleMarkChatRead` | **IMChat** `markAllMessagesAsRead` | ✓ internal only |
+| `mark-chat-unread` | `handleMarkChatUnread` | **IMChat** `markLastMessageAsUnread` | ✗ not wired above |
+| `start-/stop-/check-typing` | `handleStartTyping` … | **IMChat** `isCurrentlyTyping` (+ typing setter) | ✓ internal only |
+
+### Identity / introspection
+| Verb | Handler | Call | Host |
+|---|---|---|---|
+| `check-imessage-availability` | `handleCheckIMessageAvailability` | **IDSIDQueryController** `_currentIDStatusForDestination:service:listenerID:` / `currentIDStatusForDestination:service:` | ✓ selector live, not wired above |
+| `get-account-info` | `handleGetAccountInfo` | **IMAccountController** `sharedInstance`/`activeIMessageAccount` → **IMAccount** `vettedAliases`/`loginIMHandle` | ✓ |
+| `get-nickname-info` / `share-nickname` / `should-offer-nickname-sharing` | `handleGetNicknameInfo` … | **IMNicknameController** `nicknameForHandle:` · `personalNickname` · `shouldOfferNicknameSharingForChat:` | ✓ (Name & Photo) |
+| `download-purged-attachment` | `handleDownloadPurgedAttachment` | **IMFileTransferCenter** `acceptTransfer:` · **IMDaemonController** `connectToDaemon` | ✓ |
+
+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; the SDK's
+`editMessage` capability is any one of the three edit markers.
+
+## macOS 27 operation callsites — MAP-175
+
+**Research attribution:** These replacement entrypoints and downstream
+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]` | 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` | `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
+addresses remain in the detailed evidence below because they are specific to a
+single macOS build and must not become bridge constants.
+
+The research ran against the development `mapidev` Messages profile, not the
+production profile, on macOS 27.0 build `26A5421a` (`arm64e`) with IMCore
+`1491.100.1.1.9`. `ipsw 3.1.712` read the native IMCore image directly from the
+dyld shared cache. Runtime availability was checked by loading IMCore in an
+independent process and querying the Objective-C method table; the probe did
+not attach to or mutate Messages.
+
+All addresses below are unslid and specific to this OS build. They are audit
+evidence only and must never be hard-coded by the bridge; selectors still need
+to be resolved by name at runtime.
+
+### `leave-chat` — found by Neo Shangguan
+
+Runtime availability:
+
+```text
+-[IMChat leaveChat]          false
+-[IMChat leave]              true
+-[IMChat leaveConversation]  true
+```
+
+`-[IMChat leave]` begins at `0x1bf212c88`. Its operation path is:
+
+```text
+-[IMChat leave]
+  [self daemonServiceProvider]   callsite 0x1bf212da4
+  [provider _chat_leave:self]    callsite 0x1bf212db4
+```
+
+The selector stubs resolve to `daemonServiceProvider` and `_chat_leave:`. At
+the downstream callsite, the provider is the receiver and the current `IMChat`
+is the operation argument. This establishes `-[IMChat leave]` as the high-level
+replacement entrypoint; bridge code should call it rather than reaching into
+`_chat_leave:` directly.
+
+`-[IMChat leaveConversation]` was also disassembled and resolves to
+`[self _closeSession:NO]`. It closes the session rather than dispatching the
+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. **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
+
+Runtime availability:
+
+```text
+editMessageItem:atPartIndex:withNewPartText:
+  backwardCompatabilityText:                                      false
+editMessage:atPartIndex:withNewPartText:
+  backwardCompatabilityText:                                      false
+editMessageItem:atPartIndex:withNewPartText:
+  newPartTranslation:backwardCompatabilityText:                    true
+```
+
+The new method inserts a `newPartTranslation:` argument. It begins at
+`0x1bf209994`, with the arm64 business arguments laid out as:
+
+```text
+x2 = original message item
+x3 = part index
+x4 = new part text
+x5 = new part translation
+x6 = backward-compatibility text
+```
+
+The ordinary-message operation path is:
+
+```text
+-[IMChat editMessageItem:...newPartTranslation:...]
+  [factory editedMessageItemWithOriginalMessageItem:
+    editedPartIndex:newPartText:newPartTranslation:]       callsite 0x1bf209b18
+  [self daemonServiceProvider]                             callsite 0x1bf209b28
+  [provider _chat:self
+    sendEditedMessageItem:editedItem
+    previousMessageItem:originalItem
+    partIndex:index
+    editType:1
+    backwardCompatabilityText:backwardText]                callsite 0x1bf209b4c
+```
+
+The final selector is
+`_chat:sendEditedMessageItem:previousMessageItem:partIndex:editType:backwardCompatabilityText:`.
+The method constructs the new edited item, resolves the daemon service
+provider, and dispatches the edit with constant `editType` value `1`. The
+alternate branch calls
+`editScheduledMessageItem:atPartIndex:withNewPartText:newPartTranslation:` and
+is for scheduled messages, not the ordinary edit path.
+
+`newPartTranslation` is retained and forwarded without a non-null branch, which
+is consistent with passing `nil` for an ordinary untranslated edit. A live
+smoke must verify that assumption. The high-level five-argument `IMChat` method
+is the replacement target; it requires an accurately cast `objc_msgSend` call
+rather than `performSelector:` and should be runtime-gated alongside the older
+selectors.
+
+### `mentions` — found by Neo Shangguan
+
+Mentions do not introduce a separate daemon operation selector. `IMMessage`
+continues to carry an `NSAttributedString`, and the existing `IMChat` send path
+dispatches the message. The missing bridge work is therefore attributed-text
+payload construction rather than discovery of another `IMChat` send method.
+
+The native macOS 27 `IMSharedUtilities` image exports the transport constants
+needed to construct and inspect that payload:
+
+```text
+IMMentionAttributeName                  "__kIMMentionAttributeName"
+IMMentionAttributeNameNeedsAnimation    "__kIMMentionAttributeNameNeedsAnimation"
+IMMentionConfirmedMention               "__kIMMentionConfirmedMention"
+IMMentionAutomaticConfirmedMention      "__kIMMentionAutomaticConfirmedMention"
+IMMentionUnconfirmedDirectMention       "__kIMMentionUnconfirmedDirectMention"
+```
+
+They were resolved from
+`/System/Library/PrivateFrameworks/IMSharedUtilities.framework` in an
+independent runtime probe. Bridge code should likewise resolve symbols by name
+and must not embed their build-specific addresses or private string values.
+
+The construction pattern is visible in the iOSSupport ChatKit image at
+`+[CKMentionsUtilities configureAttributedString:inTextView:
+forConfirmedMentionInRange:needingAnimation:]`, beginning at `0x1dbecbe38`:
+
+```text
+add IMMentionAttributeName to the confirmed mention range     0x1dbecbea0
+remove IMMentionUnconfirmedDirectMention from that range      0x1dbecbebc
+remove IMMentionAutomaticConfirmedMention from that range     0x1dbecbed8
+conditionally add IMMentionAttributeNameNeedsAnimation        0x1dbecbf54
+```
+
+The mutation callsites resolve to
+`-[NSMutableAttributedString addAttribute:value:range:]` and
+`-[NSMutableAttributedString removeAttribute:range:]`. The related
+`configureAttributedString:automaticMentionAttributeWithOriginalText:
+entityNode:nodeId:forRange:` method builds composer/autocomplete metadata and
+stores it under `IMMentionAutomaticConfirmedMention`; the confirmed path
+removes that temporary marker before sending.
+
+ChatKit is present in this cache under `/System/iOSSupport` rather than as the
+native transport framework, so its helper itself is evidence for the payload
+shape, not a selector the bridge should invoke. The native
+`IMSharedUtilities` constants plus the existing attributed `IMMessage` send
+path are the candidate integration boundary. Exact attribute values and range
+handling still require a development-profile live send smoke before the
+feature can be declared available.
+
+### `text-styling` and `text-effects` — found by Neo Shangguan
+
+Inline bold, italic, underline, strikethrough, and animated text effects also
+reuse the attributed `IMMessage` and existing `IMChat` send operation. There is
+no additional daemon send selector. The missing bridge work is to construct
+the transport attributes over the requested text ranges.
+
+The native macOS 27 `IMSharedUtilities` image exports the relevant integration
+symbols:
+
+```text
+IMTextBoldAttributeName
+IMTextItalicAttributeName
+IMTextUnderlineAttributeName
+IMTextStrikethroughAttributeName
+IMTextEffectAttributeName
+IMTextStyleAll
+IMTextEffectNameFromType
+IMTextEffectTypeFromName
+IMTextEffectOrderedSupportedNames
+IMTextEffectNameBig / Bloom / Bounce / Explode / Jitter / Nod /
+  ScaleRipple / Shake / Small / Somersault / Squish / Stretch
+IMServiceCapabilityTextEffects
+```
+
+The iOSSupport ChatKit construction reference maps the inline-style bit values
+to transport and local display attributes as follows:
+
+| Style value | IM transport marker | Local display attribute |
+|---|---|---|
+| `1` | `IMTextBoldAttributeName` | `NSFontAttributeName` with the bold trait |
+| `2` | `IMTextItalicAttributeName` | `NSFontAttributeName` with the italic trait |
+| `4` | `IMTextUnderlineAttributeName` | `NSUnderlineStyleAttributeName` |
+| `8` | `IMTextStrikethroughAttributeName` | `NSStrikethroughStyleAttributeName` |
+
+`-[NSMutableAttributedString(TextEffects)
+ck_applyTextStyle:options:range:]` begins at `0x1dbcc19fc`. It asks
+`ck_actionForIMTextStyle:range:` whether the requested style should be added,
+removed, or left unchanged, then tail-dispatches to
+`ck_addTextStyle:options:range:` at `0x1dbcc1a74` or
+`ck_removeTextStyle:options:range:` at `0x1dbcc1aac`. The add implementation
+begins at `0x1dbcc1ac4`.
+
+Within `ck_addTextStyle:options:range:`, option bit zero controls the private IM
+transport marker and option bit one controls the corresponding local display
+attribute. The callsites that add the four IM markers are:
+
+```text
+IMTextBoldAttributeName             0x1dbcc1d04
+IMTextItalicAttributeName           0x1dbcc1c2c
+IMTextUnderlineAttributeName        0x1dbcc1ccc
+IMTextStrikethroughAttributeName    0x1dbcc1da8
+```
+
+Each transport marker receives a constant `NSNumber` value. ChatKit separately
+updates font traits or the standard underline/strikethrough attributes for
+local display. Those visual attributes must not be confused with the private
+IM markers that describe the wire payload.
+
+Animated effects are constructed by
+`-[NSMutableAttributedString(TextEffects)
+ck_applyTextEffectType:range:]`, beginning at `0x1dbcc1340`. Its primary path
+is:
+
+```text
+remove IMTextEffectAttributeName and NSTextAnimationAttributeName
+remove IMTextStyleAll with both transport and display options
+effectName = IMTextEffectNameFromType(effectType)             0x1dbcc14e4
+animation = [UITextAnimation animationWithName:effectName]    0x1dbcc1670
+wireValue = [NSNumber numberWithInteger:effectType]           0x1dbcc16a0
+add NSTextAnimationAttributeName = animation                  0x1dbcc1694
+add IMTextEffectAttributeName = wireValue                     0x1dbcc16c0
+```
+
+The method also checks confirmed-mention and attachment ranges before applying
+an effect, and may repeat the two add operations over adjusted subranges. The
+`NSTextAnimationAttributeName`/`UITextAnimation` pair is the local preview;
+the `IMTextEffectAttributeName`/numeric effect type pair is the transport
+representation.
+
+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. **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
+
+A real contact card is a specialized vCard attachment, not a distinct IMCore
+send operation. The recipient-side ChatKit type is `CKContactMediaObject`,
+which inherits through `CKCardMediaObject` from the generic `CKMediaObject`
+attachment model:
+
+```text
+CKContactMediaObject : CKCardMediaObject : CKMediaObject
+```
+
+`CKMediaObject` directly stores a `CKFileTransfer`, file URL, transfer GUID,
+data, filename, MIME type, and UTI. `CKContactMediaObject` adds vCard parsing,
+summary, image, preview, and contact-balloon behavior; its methods include
+`contactCardPayloadFileURL:`, `vCardSummary`, and `vCardImageOfSize:`.
+
+`+[CKContactMediaObject UTITypes]` begins at `0x1dbcf40b4`. It loads
+`kUTTypeVCard` and returns it in a one-element array via
+`+[NSArray arrayWithObjects:count:]` at `0x1dbcf40f4`:
+
+```text
++[CKContactMediaObject UTITypes] → @[ kUTTypeVCard ]
+```
+
+The shared-cache wire identifiers corroborate the representation:
+
+```text
+public.vcard    native IMSharedUtilities
+text/vcard      IMDaemonCore
+text/x-vcard    IMDaemonCore and IMFoundation (legacy-compatible MIME)
+.vcf            Contacts filename generation
+```
+
+The outbound integration path is therefore:
+
+```text
+CNContact or caller-supplied vCard data
+  → serialize/write a .vcf file
+  → filename + vCard MIME/UTI metadata
+  → existing IMFileTransfer attachment send
+  → recipient CKContactMediaObject
+  → CKContactBalloonView
+```
+
+The existing bridge attachment handler already stages a local file through
+`IMFileTransferCenter`, sets the transfer filename and MIME type, registers the
+transfer with the daemon, and reuses the ordinary message send operation. A
+contact-card integration should build on that path rather than call ChatKit.
+It may either accept a valid `.vcf` or serialize a contact using the Contacts
+framework; the exact accepted MIME choice, transfer metadata, recipient
+rendering, and inbound parsing still require a development-profile live smoke.
+
+One apparent UI lead was explicitly ruled out. Despite its name,
+`-[CKChatController(Contacts) contactPicker:didSelectContact:]` at
+`0x1dc070830` eventually dispatches
+`updateContact:withNicknameUpdate:updateType:addHandleToContact:presentationMode:`
+at `0x1dc070a00` / `0x1dc070a40`. It updates the local address book after a
+contact/nickname prompt; it is not a contact-card send callsite.
+
+### `chat-background` — found by Neo Shangguan
+
+The macOS 27 `IMChat` entrypoint is:
+
+```objc
+-[IMChat setTranscriptBackgroundAndSendToChat:transferID:]
+```
+
+It begins at `0x1bf20b080`. The arm64 argument flow shows the first business
+argument retained as the pending background object and the second retained as
+the transfer identifier. The operation path is:
+
+```text
+-[IMChat setTranscriptBackgroundAndSendToChat:background transferID:transferID]
+  [self daemonServiceProvider]                                      callsite 0x1bf20b0b8
+  [provider _chat:self
+    setTranscriptBackgroundAndSendToChat:background
+    transferID:transferID]                                          callsite 0x1bf20b0d0
+```
+
+The final selector stub resolves to
+`_chat:setTranscriptBackgroundAndSendToChat:transferID:`. ChatKit also exposes
+`setPendingTranscriptBackground:transferID:`, corroborating that the outbound
+UI flow stages a background and its associated transfer before invoking the
+`IMChat` entrypoint.
+
+The ChatKit set/remove control flow was also recovered. The UI entrypoint
+`-[CKCoreChatController setNewTranscriptBackground:]` begins at
+`0x1dbc7d1b8` and generates the transfer identifier with
+`+[NSString stringGUID]`. It stores the pending state on the conversation and
+then branches on the background argument:
+
+```text
+transferID = [NSString stringGUID]
+[self.conversation setPendingTranscriptBackground:background
+                                           transferID:transferID]
+
+if background != nil:
+  [background createBackgroundWithWatchDataWithCompletion:^(preparedBackground) {
+    [self updateTranscriptBackground:preparedBackground
+                           transferID:transferID]
+  }]
+else:
+  [self updateTranscriptBackground:nil
+                         transferID:transferID]
+```
+
+`-[CKCoreChatController updateTranscriptBackground:transferID:]` begins at
+`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: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. 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
+
+Location Request is a Find My Messages-app payload, not an
+`IMFMFSession` tracking operation. The ChatKit entrypoint
+`-[CKChatController _stageFindMyLocationRequest]` begins at `0x1dbc13240`.
+Its relevant operation path is:
+
+```text
+[IMFeatureFlags sharedFeatureFlags]
+  -isWaldoEnabled
+
+soft-link the MSMessage class
+  +respondsToSelector:@selector(findMyLocationRequestMessage)
+  +findMyLocationRequestMessage
+
+[CKComposition compositionWithMSMessage:requestMessage
+                  appExtensionIdentifier:IMBalloonBundleIdentifierWaldo]
+  → [CKChatController setComposition:composition]
+```
+
+The feature-gate selectors resolve to `sharedFeatureFlags` and
+`isWaldoEnabled`. ChatKit soft-links the `MSMessage` class, verifies the class
+factory at runtime, and then invokes `+[MSMessage findMyLocationRequestMessage]`.
+It wraps the returned request in a `CKComposition` using the private
+`IMBalloonBundleIdentifierWaldo` constant before staging the composition.
+`Waldo` is the Find My Messages-balloon/app identity used for this request.
+
+This rules out two misleading IMCore paths. `-[IMFMFSession
+startTrackingLocationForChat:]` refreshes an already-shared location, while
+`-[IMFMFSession startSharingWithChat:withDuration:]` starts sharing the local
+user's location. Neither is the operation that constructs a request asking the
+other participant to share.
+
+The callable factory and staging callsites are now known, but a bridge recipe
+is still incomplete. The implementation of
+`+[MSMessage findMyLocationRequestMessage]`, the serialized payload it returns,
+and the safest route from that payload into the bridge's existing `IMMessage`
+send path remain to be recovered. Calling a `CKChatController` UI instance is
+not assumed to be an appropriate relay integration path.
+
+### Implementation readiness and remaining work
+
+Finding a callsite removes the selector-discovery blocker; it does not by
+itself make the operation available. This table is the implementation handoff
+for the MAP-175 findings above:
+
+| Operation | Readiness | What is resolved | Remaining implementation work |
+|---|---|---|---|
+| `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 | **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
+probing, native wiring, a matched CLI/dylib rebuild, injection under the
+development `mapidev` profile, and operation-specific live smoke evidence.
+Build-specific addresses above remain audit evidence and must never become
+runtime constants.
+
+These findings do not include an upstream Messages UI-controller trace. MAP-175
+does not require that trace once the callable entrypoint and downstream
+operation dispatch have been established.
+
+## Finding a replacement selector (the archaeology)
+
+When a selector goes dead (host `✗`, `respondsToSelector:` NO), on a host of that
+macOS version:
+
+1. **Dump the class.** `class-dump` (or Hopper/IDA) the dyld shared cache and read
+   the target class — e.g. all `IMChat` methods — to spot the renamed/new one.
+2. **Trace the UI.** Attach `lldb` / `frida-trace` to Messages.app, do the action
+   by hand, and watch which IMCore selectors fire (`objc` method trace on `IMChat`).
+3. **Cross-check open source.** BlueBubbles and Barcelona (open-imcore) implement
+   leave / edit / etc.; their newer-macOS handling names candidate selectors.
+4. Swap the `@selector(...)` in the handler, add its status-probe marker, rebuild
+   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 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.2",
+  "version": "0.3.0",
   "description": "TypeScript SDK for iMessage automation on macOS: the Gateway contract, ImsgGateway (real), and a device-free FakeGateway.",
   "license": "MIT",
   "repository": {