@spectrum-ts/imessage 5.0.0

package/dist/index.js

@@ -0,0 +1,2153 @@
+import { MessageEffect, NotFoundError, ValidationError, createClient } from "@photon-ai/advanced-imessage";
+import { IMessageSDK } from "@photon-ai/imessage-kit";
+import { sanitizePhone, withSpan } from "@photon-ai/otel";
+import { UnsupportedError, appLayoutSchema, cloud, definePlatform, fromVCard, mergeStreams, read, stream, text, toVCard } from "@spectrum-ts/core";
+import { asAttachment, asContact, asCustom, asGroup, asPoll, asPollOption, asRichlink, asText, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, messageEffectSchema, photoActionSchema, reactionSchema, resumableOrderedStream, sanitizeErrorMessage } from "@spectrum-ts/core/authoring";
+import z from "zod";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { createReadStream } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { Marked } from "marked";
+import { LRUCache } from "lru-cache";
+//#region src/content/background.ts
+/**
+* iMessage-only chat background content. Lives entirely under the iMessage
+* provider — never enters the universal `Content` discriminated union. The
+* framework recognizes it via two generic content-level contracts:
+*
+* 1. `__platform: "iMessage"` — `findUnsupportedPlatformContent` in
+*    `platform/build.ts` reads this tag and warns-and-skips when a different
+*    platform receives it.
+* 2. `__fireAndForget: true` — `dispatchSend`'s fire-and-forget check
+*    treats this as a side-effecting send that returns no message id, the
+*    same way it treats `reaction` / `typing` / `edit`.
+*
+* iMessage's `send` handler narrows back to `Background` via the `isBackground`
+* type guard before dispatching to `chats.setBackground` / `removeBackground`.
+*/
+const backgroundSchema = z.object({
+	type: z.literal("background"),
+	__platform: z.literal("iMessage"),
+	__fireAndForget: z.literal(true),
+	action: photoActionSchema
+});
+const isBackground = (v) => backgroundSchema.safeParse(v).success;
+function background(input, options) {
+	const action = buildPhotoAction(input, options, "background");
+	return { build: async () => backgroundSchema.parse({
+		type: "background",
+		__platform: "iMessage",
+		__fireAndForget: true,
+		action
+	}) };
+}
+//#endregion
+//#region src/content/contact-card.ts
+/**
+* iMessage-only "share contact card" control signal. Pushes the *local
+* account's native contact card* (the name + photo a recipient sees in their
+* Messages app) to a chat via the SDK's `chats.shareContactInfo`.
+*
+* This is Apple's "Share Name and Photo" mechanism — distinct from the
+* universal `contact(...)` content, which uploads an arbitrary person's vCard
+* as a *file* attachment. There is no payload: the card shared is always the
+* bot account's own.
+*
+* Like `background`, it lives entirely under the iMessage provider and never
+* enters the universal `Content` discriminated union. The framework recognizes
+* it via two generic content-level contracts:
+*
+* 1. `__platform: "iMessage"` — `findUnsupportedPlatformContent` in
+*    `platform/build.ts` reads this tag and warns-and-skips when a different
+*    platform receives it.
+* 2. `__fireAndForget: true` — `dispatchSend`'s fire-and-forget check treats
+*    this as a side-effecting send that returns no message id, the same way it
+*    treats `read` / `typing`.
+*
+* iMessage's `send` handler narrows back via the `isContactCard` type guard
+* before dispatching to `chats.shareContactInfo`.
+*/
+const contactCardSchema = z.object({
+	type: z.literal("contactCard"),
+	__platform: z.literal("iMessage"),
+	__fireAndForget: z.literal(true)
+});
+const isContactCard = (v) => contactCardSchema.safeParse(v).success;
+/**
+* Share the bot account's native iMessage contact card (name + photo) with the
+* chat. iMessage-only, remote-only.
+*
+* `space.send(nativeContactCard())` is the canonical form; `space.shareContactCard()`
+* is sugar attached via `PlatformDef.space.actions` (only typed on
+* `PlatformSpace<IMessageDef>`).
+*
+* This is an explicit, on-demand share and always fires — unlike the automatic
+* best-effort share gated behind the `imessageSynced` project profile, which
+* dedupes to once per chat per 24h (see `remote/contact-share.ts`). Works in
+* both DMs and group chats; the recipient chooses whether to accept the card.
+*
+* `ContactCard` is intentionally not a member of the universal `Content`
+* union — the `as unknown as Content` cast keeps the builder shape compatible
+* with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+* The framework treats it as a fire-and-forget control signal at runtime.
+*/
+function nativeContactCard() {
+	return { build: async () => contactCardSchema.parse({
+		type: "contactCard",
+		__platform: "iMessage",
+		__fireAndForget: true
+	}) };
+}
+//#endregion
+//#region src/content/customized-mini-app.ts
+const layoutSchema = appLayoutSchema;
+/**
+* iMessage-only mini-app card content. Lives entirely under the iMessage
+* provider — never enters the universal `Content` discriminated union. The
+* framework recognizes it via the generic content-level platform contract:
+*
+* - `__platform: "iMessage"` — `findUnsupportedPlatformContent` reads this tag
+*   and warns-and-skips when a different platform receives it.
+*
+* Unlike `background` / `read`, this content is **not** `__fireAndForget`: it
+* produces a real outbound message, so the iMessage `send` handler narrows
+* back to `CustomizedMiniApp` via the `isCustomizedMiniApp` guard and returns
+* the resulting `ProviderMessageRecord` (rather than `void`).
+*/
+const customizedMiniAppSchema = z.object({
+	type: z.literal("customized-mini-app"),
+	__platform: z.literal("iMessage"),
+	appName: z.string().nonempty(),
+	appStoreId: z.number().int().positive().optional(),
+	extensionBundleId: z.string().nonempty(),
+	layout: layoutSchema,
+	teamId: z.string(),
+	url: z.url()
+});
+const isCustomizedMiniApp = (v) => customizedMiniAppSchema.safeParse(v).success;
+const asCustomizedMiniApp = (input) => customizedMiniAppSchema.parse({
+	type: "customized-mini-app",
+	__platform: "iMessage",
+	...input
+});
+/**
+* Construct a `customized-mini-app` content value. iMessage-only, remote-only.
+*
+* The layout is what recipients see in the bubble. `teamId` and
+* `extensionBundleId` identify the iMessage extension that receives `url` when
+* the recipient taps the card; the server constructs the matching
+* `MSMessageExtensionBalloonPlugin` plugin id from these values. `appStoreId`
+* is optional and only points recipients without the extension at its App
+* Store entry.
+*
+* `space.send(customizedMiniApp(...))` is the canonical form.
+*
+* `CustomizedMiniApp` is intentionally not a member of the universal `Content`
+* union — the `as unknown as Content` cast keeps the builder shape compatible
+* with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+*/
+function customizedMiniApp(input) {
+	return { build: async () => asCustomizedMiniApp(input) };
+}
+//#endregion
+//#region src/content/effect.ts
+const SUPPORTED_EFFECTS = new Set(Object.values(MessageEffect));
+const resolveContent = (input) => typeof input === "string" ? text(input).build() : input.build();
+function effect(input, messageEffect) {
+	return { build: async () => {
+		if (!SUPPORTED_EFFECTS.has(messageEffect)) throw new Error(`Unsupported iMessage message effect "${messageEffect}"`);
+		const inner = await resolveContent(input);
+		if (inner.type !== "text" && inner.type !== "markdown" && inner.type !== "attachment") throw new Error(`imessage effect() only supports text, markdown, and attachment content, got "${inner.type}"`);
+		return messageEffectSchema.parse({
+			type: "effect",
+			content: inner,
+			effect: messageEffect
+		});
+	} };
+}
+//#endregion
+//#region src/types.ts
+/**
+* Sentinel phone for shared-token mode. The single shared client serves an
+* unknown set of numbers (the SDK exposes no recipient field on inbound and
+* no `from` parameter on send), so all routing through it tags this sentinel.
+*/
+const SHARED_PHONE = "shared";
+const isLocal = (client) => client instanceof IMessageSDK;
+const clientEntry = z.object({
+	address: z.string(),
+	token: z.string(),
+	phone: z.string()
+});
+const configSchema = z.union([z.object({ local: z.literal(true) }), z.object({
+	local: z.literal(false).optional().default(false),
+	clients: clientEntry.or(z.array(clientEntry)).optional()
+})]);
+z.object({});
+const spaceSchema = z.object({
+	id: z.string(),
+	type: z.enum(["dm", "group"]),
+	phone: z.string()
+});
+const spaceParamsSchema = z.object({ phone: z.string().optional() });
+/**
+* iMessage-specific per-message metadata surfaced on `IMessageMessage`.
+* - `partIndex`: attachment index within a multi-part message (0 for bare
+*   or single-attachment messages; 0..N-1 for a group's sub-items).
+* - `parentId`: guid of the parent message for a group sub-item. Undefined
+*   when the message itself is the parent.
+*/
+const messageSchema = z.object({
+	partIndex: z.number().int().nonnegative().optional(),
+	parentId: z.string().optional()
+});
+//#endregion
+//#region src/auth.ts
+const log$3 = createLogger("spectrum.imessage.auth");
+const RENEWAL_RATIO = .8;
+const EXPIRY_BUFFER_MS = 3e4;
+const RETRY_DELAY_MS = 3e4;
+const cloudAuthState = /* @__PURE__ */ new WeakMap();
+const requirePhone = (data, instanceId) => {
+	const phone = data.numbers?.[instanceId];
+	if (!phone) throw new Error(`iMessage instance ${instanceId} has no phone assigned`);
+	return phone;
+};
+async function createCloudClients(projectId, projectSecret) {
+	let tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
+	let tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+	let disposed = false;
+	let renewalTimer;
+	let refreshFailures = 0;
+	const records = [];
+	const syncPhones = (data) => {
+		for (const { entry, instanceId } of records) entry.phone = requirePhone(data, instanceId);
+	};
+	const onRefreshSuccess = () => {
+		if (refreshFailures > 0) {
+			log$3.info("imessage token refresh recovered", { "spectrum.imessage.auth.attempt": refreshFailures });
+			refreshFailures = 0;
+		}
+	};
+	const onRefreshFailure = (error) => {
+		refreshFailures += 1;
+		log$3.warn("imessage token refresh failed; retrying", {
+			"spectrum.imessage.auth.attempt": refreshFailures,
+			"spectrum.imessage.auth.retry_in_ms": RETRY_DELAY_MS,
+			...errorAttrs(error)
+		}, error);
+	};
+	const scheduleRenewal = () => {
+		if (disposed) return;
+		const ttlMs = tokenData.expiresIn * 1e3;
+		const renewInMs = Math.max(ttlMs * RENEWAL_RATIO, 5e3);
+		renewalTimer = setTimeout(async () => {
+			try {
+				tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
+				tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+				if (tokenData.type === "dedicated") syncPhones(tokenData);
+				onRefreshSuccess();
+				scheduleRenewal();
+			} catch (error) {
+				onRefreshFailure(error);
+				renewalTimer = setTimeout(() => scheduleRenewal(), RETRY_DELAY_MS);
+				renewalTimer?.unref?.();
+			}
+		}, renewInMs);
+		renewalTimer?.unref?.();
+	};
+	scheduleRenewal();
+	const refreshIfNeeded = async () => {
+		if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) return;
+		tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
+		tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+		if (tokenData.type === "dedicated") syncPhones(tokenData);
+		onRefreshSuccess();
+		scheduleRenewal();
+	};
+	if (tokenData.type === "shared") {
+		const entries = [{
+			phone: SHARED_PHONE,
+			client: createClient({
+				address: process.env.SPECTRUM_IMESSAGE_ADDRESS ?? "imessage.spectrum.photon.codes:443",
+				tls: true,
+				token: async () => {
+					await refreshIfNeeded();
+					return tokenData.token;
+				}
+			})
+		}];
+		cloudAuthState.set(entries, { dispose: () => {
+			disposed = true;
+			if (renewalTimer !== void 0) {
+				clearTimeout(renewalTimer);
+				renewalTimer = void 0;
+			}
+		} });
+		return entries;
+	}
+	const dedicated = tokenData;
+	for (const [instanceId, token] of Object.entries(dedicated.auth)) {
+		const entry = {
+			phone: requirePhone(dedicated, instanceId),
+			client: createClient({
+				address: `${instanceId}.imsg.photon.codes:443`,
+				tls: true,
+				token: async () => {
+					await refreshIfNeeded();
+					return tokenData.auth[instanceId] ?? token;
+				}
+			})
+		};
+		records.push({
+			entry,
+			instanceId
+		});
+	}
+	const entries = records.map((r) => r.entry);
+	cloudAuthState.set(entries, { dispose: () => {
+		disposed = true;
+		if (renewalTimer !== void 0) {
+			clearTimeout(renewalTimer);
+			renewalTimer = void 0;
+		}
+	} });
+	return entries;
+}
+async function disposeCloudAuth(clients) {
+	const auth = cloudAuthState.get(clients);
+	if (auth) {
+		auth.dispose();
+		cloudAuthState.delete(clients);
+	}
+}
+//#endregion
+//#region src/cache.ts
+const DEFAULT_MAX = 1e3;
+/**
+* Bounded insertion-order cache of recently-seen iMessage messages, keyed by
+* guid. Provides O(1) lookup for reaction target resolution. When capacity is
+* exceeded, the oldest entry is evicted. Access does not promote recency —
+* this is a bounded FIFO, not an LRU. The workload (reactions arriving shortly
+* after the message they target) doesn't benefit from LRU semantics, and FIFO
+* avoids a dependency.
+*/
+var MessageCache = class {
+	map = /* @__PURE__ */ new Map();
+	max;
+	constructor(max = DEFAULT_MAX) {
+		this.max = max;
+	}
+	get(id) {
+		return this.map.get(id);
+	}
+	set(id, message) {
+		if (this.map.has(id)) this.map.delete(id);
+		this.map.set(id, message);
+		if (this.map.size > this.max) {
+			const first = this.map.keys().next().value;
+			if (first !== void 0) this.map.delete(first);
+		}
+	}
+	clear() {
+		this.map.clear();
+	}
+};
+/**
+* Bounded insertion-order cache of recently-seen iMessage polls, keyed by
+* poll message guid. The public poll shape deliberately hides provider ids;
+* `optionsByIdentifier` keeps the private lookup table needed to correlate
+* vote events back to public `PollChoice` objects.
+*/
+var PollCache = class {
+	map = /* @__PURE__ */ new Map();
+	max;
+	constructor(max = DEFAULT_MAX) {
+		this.max = max;
+	}
+	get(id) {
+		return this.map.get(id);
+	}
+	set(id, poll) {
+		if (this.map.has(id)) this.map.delete(id);
+		this.map.set(id, poll);
+		if (this.map.size > this.max) {
+			const first = this.map.keys().next().value;
+			if (first !== void 0) this.map.delete(first);
+		}
+	}
+	clear() {
+		this.map.clear();
+	}
+};
+const messageCaches = /* @__PURE__ */ new WeakMap();
+const pollCaches = /* @__PURE__ */ new WeakMap();
+/**
+* Returns a per-client message cache. Keyed by an object (the client array
+* for remote, or the IMessageSDK instance for local), so each iMessage
+* provider instance has its own cache and multiple providers don't share
+* state accidentally.
+*/
+const getMessageCache = (owner) => {
+	let cache = messageCaches.get(owner);
+	if (!cache) {
+		cache = new MessageCache();
+		messageCaches.set(owner, cache);
+	}
+	return cache;
+};
+const getPollCache = (owner) => {
+	let cache = pollCaches.get(owner);
+	if (!cache) {
+		cache = new PollCache();
+		pollCaches.set(owner, cache);
+	}
+	return cache;
+};
+//#endregion
+//#region src/shared/vcard.ts
+const VCARD_MIME_TYPES = new Set([
+	"text/vcard",
+	"text/x-vcard",
+	"text/directory",
+	"application/vcard",
+	"application/x-vcard"
+]);
+const normalizeMimeType = (mimeType) => (mimeType.split(";")[0] ?? "").trim().toLowerCase();
+const isVCardAttachment = (mimeType, fileName) => {
+	if (mimeType && VCARD_MIME_TYPES.has(normalizeMimeType(mimeType))) return true;
+	return Boolean(fileName?.toLowerCase().endsWith(".vcf"));
+};
+const vcardFileName = (contact) => {
+	return `${(contact.name?.formatted ?? contact.user?.id ?? "contact").replace(/[^a-zA-Z0-9_\-.]/g, "_")}.vcf`;
+};
+const readLocalAttachment = async (att) => {
+	if (!att.localPath) throw new Error(`iMessage attachment ${att.id} has no local file available on disk`);
+	return readFile(att.localPath);
+};
+const toAttachmentContent$1 = (att) => {
+	const { localPath } = att;
+	return asAttachment({
+		id: att.id,
+		name: att.fileName ?? "attachment",
+		mimeType: att.mimeType,
+		size: att.sizeBytes,
+		read: () => readLocalAttachment(att),
+		stream: localPath ? async () => Readable.toWeb(createReadStream(localPath)) : void 0
+	});
+};
+const toVCardContent$1 = async (att) => {
+	try {
+		return asContact(fromVCard((await readLocalAttachment(att)).toString("utf8")));
+	} catch {
+		return toAttachmentContent$1(att);
+	}
+};
+const localAttachmentContent = async (att) => isVCardAttachment(att.mimeType, att.fileName) ? await toVCardContent$1(att) : toAttachmentContent$1(att);
+//#endregion
+//#region src/local/inbound.ts
+const ATTACHMENT_PLACEHOLDER = "";
+const ATTACHMENT_JOIN_RETRY_DELAY_MS = 250;
+const ATTACHMENT_JOIN_RETRY_LIMIT = 8;
+const ATTACHMENT_JOIN_FETCH_LIMIT = 10;
+const hasAttachmentPlaceholder = (message) => message.text?.includes(ATTACHMENT_PLACEHOLDER) ?? false;
+const isPendingAttachmentJoin = (message) => message.attachments.length === 0 && (message.hasAttachments || hasAttachmentPlaceholder(message));
+const refetchUntilAttachmentsSettle = async (client, message) => {
+	if (!message.chatId) return message;
+	for (let attempt = 0; attempt < ATTACHMENT_JOIN_RETRY_LIMIT; attempt += 1) {
+		await setTimeout$1(ATTACHMENT_JOIN_RETRY_DELAY_MS);
+		let rows;
+		try {
+			rows = await client.getMessages({
+				chatId: message.chatId,
+				limit: ATTACHMENT_JOIN_FETCH_LIMIT,
+				since: message.createdAt
+			});
+		} catch {
+			continue;
+		}
+		const refreshed = rows.find((row) => row.id === message.id);
+		if (refreshed && !isPendingAttachmentJoin(refreshed)) return refreshed;
+	}
+	return message;
+};
+const toMessages = async (message) => {
+	const { chatId, chatKind } = message;
+	if (!chatId || chatKind === "unknown") return [];
+	if (message.reaction !== null || message.kind !== "text" || message.retractedAt !== null) return [];
+	if (isPendingAttachmentJoin(message)) return [];
+	const base = {
+		sender: { id: message.participant ?? "" },
+		space: {
+			id: chatId,
+			type: chatKind === "group" ? "group" : "dm",
+			phone: ""
+		},
+		timestamp: message.createdAt
+	};
+	if (message.attachments.length > 0) return Promise.all(message.attachments.map(async (att) => ({
+		...base,
+		id: `${message.id}:${att.id}`,
+		content: await localAttachmentContent(att)
+	})));
+	return [{
+		...base,
+		id: message.id,
+		content: {
+			type: "text",
+			text: message.text ?? ""
+		}
+	}];
+};
+const messages$3 = (client) => stream((emit, end) => {
+	let lastPromise = Promise.resolve();
+	const handleIncoming = async (message) => {
+		const ms = await toMessages(isPendingAttachmentJoin(message) ? await refetchUntilAttachmentsSettle(client, message) : message);
+		for (const m of ms) await emit(m);
+	};
+	const startPromise = client.startWatching({
+		onIncomingMessage: (message) => {
+			lastPromise = lastPromise.then(() => handleIncoming(message)).catch(end);
+		},
+		onError: end
+	}).catch(end);
+	return async () => {
+		await startPromise.catch(() => {});
+		await client.stopWatching();
+		await lastPromise.catch(() => {});
+	};
+});
+//#endregion
+//#region src/shared/errors.ts
+const IMESSAGE_PLATFORM = "iMessage";
+const LOCAL_IMESSAGE_PLATFORM = "iMessage (local mode)";
+const unsupportedRemoteContent = (type, detail) => UnsupportedError.content(type, IMESSAGE_PLATFORM, detail);
+const unsupportedLocalContent = (type, detail) => UnsupportedError.content(type, LOCAL_IMESSAGE_PLATFORM, detail);
+//#endregion
+//#region src/local/send.ts
+const synthRecord = (spaceId, content) => ({
+	id: crypto.randomUUID(),
+	content,
+	space: { id: spaceId },
+	timestamp: /* @__PURE__ */ new Date()
+});
+const sendTempFile = async (client, spaceId, name, data) => {
+	const safeName = basename(name) || "attachment";
+	const dir = await mkdtemp(join(tmpdir(), "spectrum-"));
+	const tmp = join(dir, safeName);
+	await writeFile(tmp, data);
+	try {
+		await client.send({
+			to: spaceId,
+			attachments: [tmp]
+		});
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+};
+const send$3 = async (client, spaceId, content) => {
+	switch (content.type) {
+		case "text":
+			await client.send({
+				to: spaceId,
+				text: content.text
+			});
+			return synthRecord(spaceId, content);
+		case "attachment":
+			await sendTempFile(client, spaceId, content.name, await content.read());
+			return synthRecord(spaceId, content);
+		case "contact": {
+			const vcf = await toVCard(content);
+			await sendTempFile(client, spaceId, vcardFileName(content), Buffer.from(vcf, "utf8"));
+			return synthRecord(spaceId, content);
+		}
+		case "effect": throw unsupportedLocalContent("effect", "message effects require remote iMessage");
+		case "poll": throw unsupportedLocalContent("poll");
+		default: throw unsupportedLocalContent(content.type);
+	}
+};
+const getMessage$3 = async (_client, _id) => void 0;
+//#endregion
+//#region src/local/api.ts
+const messages$2 = (client) => messages$3(client);
+const send$2 = async (client, spaceId, content) => send$3(client, spaceId, content);
+const getMessage$2 = async (client, id) => getMessage$3(client, id);
+//#endregion
+//#region src/remote/ids.ts
+const PART_PREFIX = /^p:(\d+)\//;
+const dmChatGuid = (address) => `any;-;${address}`;
+const chatTypeFromGuid = (guid) => guid.includes(";+;") ? "group" : "dm";
+const toChatGuid = (value) => value;
+const toMessageGuid = (value) => value;
+const formatChildId = (partIndex, parentGuid) => `p:${partIndex}/${parentGuid}`;
+const parseChildId = (id) => {
+	const match = id.match(PART_PREFIX);
+	if (!match) return null;
+	return {
+		parentGuid: id.replace(PART_PREFIX, ""),
+		partIndex: Number(match[1])
+	};
+};
+//#endregion
+//#region src/remote/avatar.ts
+/**
+* Apply an `Avatar` content value to a remote iMessage group chat.
+*
+* `set` uploads the icon bytes via `groups.setIcon`; `clear` removes the
+* current icon via `groups.removeIcon`. Both surfaces are fire-and-forget —
+* no message id is produced. The caller (`handleAvatar` in the iMessage
+* provider) is responsible for the group-only / remote-only guards.
+*/
+const setIcon$1 = async (remote, spaceId, content) => {
+	const chat = toChatGuid(spaceId);
+	if (content.action.kind === "clear") {
+		await remote.groups.removeIcon(chat);
+		return;
+	}
+	const buffer = await content.action.read();
+	await remote.groups.setIcon(chat, new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
+};
+//#endregion
+//#region src/remote/background.ts
+/**
+* Apply a `Background` content value to a remote iMessage chat.
+*
+* `set` uploads the photo bytes via `chats.setBackground`; `clear` removes
+* any current background via `chats.removeBackground`. Both surfaces are
+* fire-and-forget — no message id is produced.
+*/
+const setBackground$1 = async (remote, spaceId, content) => {
+	const chat = toChatGuid(spaceId);
+	if (content.action.kind === "clear") {
+		await remote.chats.removeBackground(chat);
+		return;
+	}
+	const buffer = await content.action.read();
+	await remote.chats.setBackground(chat, new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
+};
+//#endregion
+//#region src/remote/contact-card.ts
+/**
+* Share the local account's native contact card (name + photo) with the chat.
+*
+* The SDK exposes a single chat-level `chats.shareContactInfo(chatGuid)` — the
+* card shared is always the bot account's own, so there is no payload beyond
+* the chat. `send` has already resolved the space into `spaceId` by the time
+* the dispatcher reaches here.
+*
+* On-demand and unconditional: unlike the proactive `ContactShareTracker` in
+* `contact-share.ts` (24h dedupe, gated behind the `imessageSynced` profile),
+* this fires every time the caller asks.
+*/
+const shareContactCard$1 = async (remote, spaceId) => {
+	await remote.chats.shareContactInfo(toChatGuid(spaceId));
+};
+//#endregion
+//#region src/remote/customized-mini-app.ts
+/**
+* Send a `CustomizedMiniApp` card to a remote iMessage chat.
+*
+* Unlike `setBackground`, this produces a real outbound message, so it returns
+* a `ProviderMessageRecord`. The `content` carries extra `type` / `__platform`
+* tags the SDK ignores; it is passed as a variable (not an object literal) so
+* no excess-property check applies, and the wire serializer reads only the
+* fields it knows.
+*/
+const sendCustomizedMiniApp$1 = async (remote, spaceId, content) => {
+	const chat = toChatGuid(spaceId);
+	const message = await remote.messages.sendCustomizedMiniApp(chat, content);
+	return {
+		id: message.guid,
+		content,
+		direction: "outbound",
+		space: { id: spaceId },
+		timestamp: message.dateCreated
+	};
+};
+//#endregion
+//#region src/remote/attachments.ts
+/**
+* Stream the primary file bytes of an attachment as a `ReadableStream`.
+* Skips header and Live Photo companion frames; emits only `primaryChunk`
+* payloads. Cleans up the underlying gRPC iterator on cancel and on error.
+*/
+const downloadPrimaryAttachmentStream = (client, attachmentGuid) => {
+	const frames = client.attachments.downloadStream(attachmentGuid);
+	const iterator = frames[Symbol.asyncIterator]();
+	let closed = false;
+	const closeFrames = async () => {
+		if (closed) return;
+		closed = true;
+		try {
+			await iterator.return?.();
+		} finally {
+			await frames.close();
+		}
+	};
+	return new ReadableStream({
+		async cancel() {
+			await closeFrames();
+		},
+		async pull(controller) {
+			try {
+				while (true) {
+					const result = await iterator.next();
+					if (result.done) {
+						controller.close();
+						await closeFrames();
+						return;
+					}
+					if (result.value.type === "primaryChunk") {
+						controller.enqueue(result.value.data);
+						return;
+					}
+				}
+			} catch (error) {
+				await closeFrames();
+				throw error;
+			}
+		}
+	});
+};
+/**
+* Collect the primary file bytes of an attachment into a single `Buffer`.
+* Skips header and Live Photo companion frames.
+*/
+const downloadPrimaryAttachment = async (client, attachmentGuid) => {
+	const chunks = [];
+	const frames = client.attachments.downloadStream(attachmentGuid);
+	try {
+		for await (const frame of frames) if (frame.type === "primaryChunk") chunks.push(Buffer.from(frame.data));
+	} finally {
+		await frames.close();
+	}
+	return Buffer.concat(chunks);
+};
+/**
+* Fetch an attachment by GUID and wrap it as a spectrum `Attachment`. The
+* returned object is lazy: `.read()` triggers a Buffer download, `.stream()`
+* opens a fresh byte stream. Calling both issues two independent gRPC
+* downloads — cache `.read()` if you need the bytes more than once.
+*
+* Returns `undefined` when the GUID is unknown to the server.
+*/
+const getRemoteAttachment = async (client, guid) => {
+	let info;
+	try {
+		info = await client.attachments.get(guid);
+	} catch (err) {
+		if (err instanceof NotFoundError) return;
+		throw err;
+	}
+	return asAttachment({
+		id: info.guid,
+		name: info.fileName,
+		mimeType: info.mimeType,
+		size: info.totalBytes,
+		read: () => downloadPrimaryAttachment(client, info.guid),
+		stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+	});
+};
+//#endregion
+//#region src/remote/inbound.ts
+const log$2 = createLogger("spectrum.imessage.inbound");
+const URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
+const getBalloonBundleId = (message) => message.content.balloonBundleId;
+const messageAttachments = (message) => message.content.attachments;
+const resolveChatGuid = (message, hint) => {
+	if (hint) return hint;
+	return message.chatGuids?.[0] ?? "";
+};
+const resolveSenderId = (message) => message.sender?.address ?? "";
+const isIMessageMessage = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return typeof record.id === "string" && record.id.length > 0 && typeof record.content === "object" && record.content !== null && typeof record.space === "object" && record.space !== null;
+};
+const asProviderGroup = (items) => groupSchema.parse({
+	type: "group",
+	items
+});
+const buildMessageBase = (message, chatGuidHint, timestamp, phone) => {
+	const chat = resolveChatGuid(message, chatGuidHint);
+	return {
+		direction: message.isFromMe ? "outbound" : "inbound",
+		sender: { id: resolveSenderId(message) },
+		space: {
+			id: chat,
+			type: chatTypeFromGuid(chat),
+			phone
+		},
+		timestamp
+	};
+};
+const toAttachmentContent = (client, info) => asAttachment({
+	id: info.guid,
+	name: info.fileName,
+	mimeType: info.mimeType,
+	size: info.totalBytes,
+	read: async () => await downloadPrimaryAttachment(client, info.guid),
+	stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+});
+const toVCardContent = async (client, info) => {
+	try {
+		return asContact(fromVCard((await downloadPrimaryAttachment(client, info.guid)).toString("utf8")));
+	} catch (err) {
+		log$2.warn("failed to parse vCard attachment; falling back to attachment content", {
+			"spectrum.imessage.attachment.guid": info.guid,
+			...errorAttrs(err)
+		}, err);
+		return toAttachmentContent(client, info);
+	}
+};
+const attachmentContent = async (client, info) => isVCardAttachment(info.mimeType, info.fileName) ? await toVCardContent(client, info) : toAttachmentContent(client, info);
+const buildAttachmentMessage = async (client, base, info, id, partIndex, parentId) => {
+	const content = await attachmentContent(client, info);
+	const msg = {
+		...base,
+		id,
+		content,
+		partIndex
+	};
+	if (parentId !== void 0) msg.parentId = parentId;
+	return msg;
+};
+const toRichlinkMessage = (message, base, id) => {
+	const url = message.content.text ?? "";
+	try {
+		return {
+			...base,
+			id,
+			content: asRichlink({ url })
+		};
+	} catch (err) {
+		log$2.warn("failed to convert message to rich link; falling back to text/custom content", {
+			"spectrum.imessage.message.id": id,
+			...errorAttrs(err)
+		}, err);
+		return {
+			...base,
+			id,
+			content: url ? asText(url) : asCustom(message)
+		};
+	}
+};
+const rebuildFromAppleMessage = async (client, message, phone, chatGuidHint) => {
+	const messageGuidStr = message.guid;
+	const base = buildMessageBase(message, chatGuidHint, message.dateCreated ?? /* @__PURE__ */ new Date(), phone);
+	const attachments = messageAttachments(message);
+	if (attachments.length === 1) {
+		const info = attachments[0];
+		if (!info) throw new Error("Unreachable: attachments.length === 1 but no element");
+		return buildAttachmentMessage(client, base, info, messageGuidStr, 0);
+	}
+	if (attachments.length > 1) {
+		const items = [];
+		for (let i = 0; i < attachments.length; i++) {
+			const info = attachments[i];
+			if (!info) continue;
+			items.push(await buildAttachmentMessage(client, base, info, formatChildId(i, messageGuidStr), i, messageGuidStr));
+		}
+		return {
+			...base,
+			id: messageGuidStr,
+			content: asProviderGroup(items)
+		};
+	}
+	if (getBalloonBundleId(message) === URL_BALLOON_BUNDLE_ID) return toRichlinkMessage(message, base, messageGuidStr);
+	const text = message.content.text;
+	return {
+		...base,
+		id: messageGuidStr,
+		content: text ? asText(text) : asCustom(message)
+	};
+};
+const cacheMessage = (cache, message) => {
+	cache.set(message.id, message);
+	if (message.content.type === "group") {
+		for (const item of message.content.items) if (isIMessageMessage(item)) cache.set(item.id, item);
+	}
+};
+const toInboundMessages = async (client, cache, event, phone) => {
+	const base = buildMessageBase(event.message, event.chatGuid, event.occurredAt, phone);
+	const messageGuidStr = event.message.guid;
+	if (getBalloonBundleId(event.message) === URL_BALLOON_BUNDLE_ID) {
+		const msg = toRichlinkMessage(event.message, base, messageGuidStr);
+		cacheMessage(cache, msg);
+		return [msg];
+	}
+	const attachments = messageAttachments(event.message);
+	if (attachments.length === 1) {
+		const info = attachments[0];
+		if (!info) throw new Error("Unreachable: attachments.length === 1 but no element");
+		const msg = await buildAttachmentMessage(client, base, info, messageGuidStr, 0);
+		cacheMessage(cache, msg);
+		return [msg];
+	}
+	if (attachments.length > 1) {
+		const items = [];
+		for (let i = 0; i < attachments.length; i++) {
+			const info = attachments[i];
+			if (!info) continue;
+			items.push(await buildAttachmentMessage(client, base, info, formatChildId(i, messageGuidStr), i, messageGuidStr));
+		}
+		const parent = {
+			...base,
+			id: messageGuidStr,
+			content: asProviderGroup(items)
+		};
+		cacheMessage(cache, parent);
+		return [parent];
+	}
+	const text = event.message.content.text;
+	const msg = {
+		...base,
+		id: messageGuidStr,
+		content: text ? asText(text) : asCustom(event.message)
+	};
+	cacheMessage(cache, msg);
+	return [msg];
+};
+const getMessage$1 = async (remote, spaceId, msgId, phone) => {
+	const cache = getMessageCache(remote);
+	const cached = cache.get(msgId);
+	if (cached) return cached;
+	const childRef = parseChildId(msgId);
+	if (childRef) try {
+		const parent = await rebuildFromAppleMessage(remote, await remote.messages.get(toMessageGuid(childRef.parentGuid)), phone, spaceId);
+		cacheMessage(cache, parent);
+		if (parent.content.type !== "group") return;
+		const item = parent.content.items[childRef.partIndex];
+		return isIMessageMessage(item) ? item : void 0;
+	} catch (err) {
+		if (err instanceof NotFoundError) return;
+		throw err;
+	}
+	try {
+		const rebuilt = await rebuildFromAppleMessage(remote, await remote.messages.get(toMessageGuid(msgId)), phone, spaceId);
+		cacheMessage(cache, rebuilt);
+		return rebuilt;
+	} catch (err) {
+		if (err instanceof NotFoundError) return;
+		throw err;
+	}
+};
+//#endregion
+//#region src/remote/reactions.ts
+const EMOJI_TO_TAPBACK = {
+	"❤️": "love",
+	"👍": "like",
+	"👎": "dislike",
+	"😂": "laugh",
+	"‼️": "emphasize",
+	"❓": "question"
+};
+const TAPBACK_TO_EMOJI = Object.fromEntries(Object.entries(EMOJI_TO_TAPBACK).map(([emoji, kind]) => [kind, emoji]));
+const reactionEmoji = (reaction) => reaction.kind === "emoji" ? reaction.emoji : TAPBACK_TO_EMOJI[reaction.kind];
+const asProviderReaction = (emoji, target) => reactionSchema.parse({
+	emoji,
+	target,
+	type: "reaction"
+});
+const resolveReactionTarget = async (client, cache, chat, targetGuid, partIndex, phone) => {
+	let candidate = cache.get(targetGuid);
+	if (!candidate) try {
+		candidate = await rebuildFromAppleMessage(client, await client.messages.get(toMessageGuid(targetGuid)), phone, chat);
+		cacheMessage(cache, candidate);
+	} catch {
+		return;
+	}
+	if (candidate.content.type === "group") {
+		const items = candidate.content.items;
+		if (!Array.isArray(items)) return candidate;
+		const item = items[partIndex ?? 0];
+		return isIMessageMessage(item) ? item : candidate;
+	}
+	return candidate;
+};
+const toReactionMessages = async (client, cache, event, phone) => {
+	const emoji = reactionEmoji(event.reaction);
+	if (!emoji) return [];
+	const senderAddress = event.actor?.address;
+	if (!senderAddress) return [];
+	const resolved = await resolveReactionTarget(client, cache, event.chatGuid, event.messageGuid, event.targetPartIndex, phone);
+	if (!resolved) return [];
+	const partSuffix = typeof event.targetPartIndex === "number" ? `:${event.targetPartIndex}` : "";
+	return [{
+		sender: { id: senderAddress },
+		space: {
+			id: event.chatGuid,
+			type: chatTypeFromGuid(event.chatGuid),
+			phone
+		},
+		timestamp: event.occurredAt,
+		id: `${event.messageGuid}:reaction:${event.sequence}${partSuffix}`,
+		content: asProviderReaction(emoji, resolved)
+	}];
+};
+const toSettableReaction = (emoji) => {
+	const native = EMOJI_TO_TAPBACK[emoji];
+	return native ? { kind: native } : {
+		kind: "emoji",
+		emoji
+	};
+};
+const tapbackTarget = (target) => ({
+	guid: toMessageGuid(target.parentId ?? target.id),
+	opts: typeof target.partIndex === "number" ? { partIndex: target.partIndex } : void 0
+});
+const reactToMessage$1 = async (remote, spaceId, target, reaction) => {
+	const { guid, opts } = tapbackTarget(target);
+	const sent = await remote.messages.setReaction(toChatGuid(spaceId), guid, toSettableReaction(reaction), true, opts);
+	return {
+		id: sent.guid,
+		content: asProviderReaction(reaction, target),
+		direction: "outbound",
+		space: { id: spaceId },
+		timestamp: sent.dateCreated
+	};
+};
+const unsendReaction$1 = async (remote, spaceId, target, reaction) => {
+	const { guid, opts } = tapbackTarget(target);
+	await remote.messages.setReaction(toChatGuid(spaceId), guid, toSettableReaction(reaction), false, opts);
+};
+//#endregion
+//#region src/remote/read.ts
+/**
+* Mark every unread message in the chat as read.
+*
+* The SDK exposes only a chat-level `chats.markRead(chatGuid)` — there is no
+* per-message API. The `Read` content's `target` is used by the caller to
+* derive the chat, which `send` has already resolved into `spaceId` by the
+* time the dispatcher reaches here.
+*/
+const markRead$1 = async (remote, spaceId) => {
+	await remote.chats.markRead(toChatGuid(spaceId));
+};
+//#endregion
+//#region src/remote/rename.ts
+/**
+* Apply a `Rename` content value to a remote iMessage group chat.
+* Fire-and-forget — the `Chat` returned by `setDisplayName` is discarded.
+*/
+const setDisplayName$1 = async (remote, spaceId, content) => {
+	await remote.groups.setDisplayName(toChatGuid(spaceId), content.displayName);
+};
+//#endregion
+//#region src/remote/markdown.ts
+const markdownLexer = new Marked();
+const BULLET = "• ";
+const HR_LINE = "———";
+const NESTED_LIST_INDENT = "  ";
+const BLOCK_SEPARATOR = "\n\n";
+const TABLE_CELL_SEPARATOR = " | ";
+const DEFAULT_LIST_START = 1;
+const LEADING_WHITESPACE = /^\s+/;
+const TRAILING_WHITESPACE = /\s+$/;
+const MONOSPACE_UPPER_A = 120432;
+const MONOSPACE_LOWER_A = 120458;
+const MONOSPACE_DIGIT_ZERO = 120822;
+const UPPER_A = 65;
+const UPPER_Z = 90;
+const LOWER_A = 97;
+const LOWER_Z = 122;
+const DIGIT_ZERO = 48;
+const DIGIT_NINE = 57;
+const monospaceCodePoint = (codePoint) => {
+	if (codePoint >= UPPER_A && codePoint <= UPPER_Z) return MONOSPACE_UPPER_A + (codePoint - UPPER_A);
+	if (codePoint >= LOWER_A && codePoint <= LOWER_Z) return MONOSPACE_LOWER_A + (codePoint - LOWER_A);
+	if (codePoint >= DIGIT_ZERO && codePoint <= DIGIT_NINE) return MONOSPACE_DIGIT_ZERO + (codePoint - DIGIT_ZERO);
+	return codePoint;
+};
+const toMonospace = (text) => {
+	let out = "";
+	for (const char of text) {
+		const codePoint = char.codePointAt(0);
+		out += codePoint === void 0 ? char : String.fromCodePoint(monospaceCodePoint(codePoint));
+	}
+	return out;
+};
+const STYLE_ORDER = [
+	"bold",
+	"italic",
+	"strikethrough"
+];
+const plain = (text) => ({
+	text,
+	styles: []
+});
+const withStyle = (spans, style) => spans.map((span) => span.styles.includes(style) ? span : {
+	...span,
+	styles: [...span.styles, style]
+});
+const asLink = (spans) => spans.map((span) => ({
+	...span,
+	link: true
+}));
+const spanText = (spans) => {
+	let out = "";
+	for (const span of spans) out += span.text;
+	return out;
+};
+const joinSpans = (blocks, separator) => {
+	const out = [];
+	for (const [index, block] of blocks.entries()) {
+		if (index > 0) out.push(plain(separator));
+		out.push(...block);
+	}
+	return out;
+};
+const splitSpanLines = (spans) => {
+	let current = [];
+	const lines = [current];
+	for (const span of spans) {
+		const parts = span.text.split("\n");
+		for (const [index, part] of parts.entries()) {
+			if (index > 0) {
+				current = [];
+				lines.push(current);
+			}
+			if (part) current.push({
+				...span,
+				text: part
+			});
+		}
+	}
+	return lines;
+};
+const asMarkedToken = (token) => token;
+const checkboxPrefix = (item) => {
+	if (!item.task) return "";
+	return item.checked ? "[x] " : "[ ] ";
+};
+const listMarker = (list, index) => {
+	if (!list.ordered) return BULLET;
+	return `${(list.start === "" ? DEFAULT_LIST_START : list.start) + index}. `;
+};
+const renderLink = (token) => {
+	if (token.text === token.href) return [{
+		text: token.href,
+		styles: [],
+		link: true
+	}];
+	return [...asLink(renderInlineTokens(token.tokens)), {
+		text: ` (${token.href})`,
+		styles: [],
+		link: true
+	}];
+};
+const renderImage = (token) => [{
+	text: token.text ? `${token.text} (${token.href})` : token.href,
+	styles: [],
+	link: true
+}];
+const renderInlineToken = (token) => {
+	switch (token.type) {
+		case "strong": return withStyle(renderInlineTokens(token.tokens), "bold");
+		case "em": return withStyle(renderInlineTokens(token.tokens), "italic");
+		case "del": return withStyle(renderInlineTokens(token.tokens), "strikethrough");
+		case "codespan": return [plain(toMonospace(token.text))];
+		case "br": return [plain("\n")];
+		case "link": return renderLink(token);
+		case "image": return renderImage(token);
+		case "escape": return [plain(token.text)];
+		case "text": return token.tokens ? renderInlineTokens(token.tokens) : [plain(token.text)];
+		case "html": return [plain(token.text)];
+		case "checkbox": return [];
+		default: return "raw" in token ? [plain(String(token.raw))] : [];
+	}
+};
+const renderInlineTokens = (tokens) => {
+	const out = [];
+	for (const token of tokens) out.push(...renderInlineToken(asMarkedToken(token)));
+	return out;
+};
+const renderBlockquote = (quote) => {
+	const lines = splitSpanLines(renderBlockTokens(quote.tokens));
+	const out = [];
+	for (const [index, line] of lines.entries()) {
+		if (index > 0) out.push(plain("\n"));
+		out.push(plain(line.length > 0 ? "> " : ">"), ...line);
+	}
+	return out;
+};
+const renderList = (list) => {
+	const out = [];
+	for (const [index, item] of list.items.entries()) {
+		const prefix = `${listMarker(list, index)}${checkboxPrefix(item)}`;
+		const blocks = [];
+		for (const token of item.tokens) {
+			const rendered = renderBlockToken(asMarkedToken(token));
+			if (spanText(rendered)) blocks.push(rendered);
+		}
+		const [first = [], ...rest] = splitSpanLines(joinSpans(blocks, "\n"));
+		if (out.length > 0) out.push(plain("\n"));
+		out.push(plain(prefix), ...first);
+		for (const line of rest) out.push(plain(`\n${NESTED_LIST_INDENT}`), ...line);
+	}
+	return out;
+};
+const renderTable = (table) => {
+	const out = [];
+	const pushRow = (cells, rowIndex) => {
+		if (rowIndex > 0) out.push(plain("\n"));
+		for (const [cellIndex, cell] of cells.entries()) {
+			if (cellIndex > 0) out.push(plain(TABLE_CELL_SEPARATOR));
+			out.push(...renderInlineTokens(cell.tokens));
+		}
+	};
+	pushRow(table.header, 0);
+	for (const [index, row] of table.rows.entries()) pushRow(row, index + 1);
+	return out;
+};
+const renderBlockToken = (token) => {
+	switch (token.type) {
+		case "heading": return withStyle(renderInlineTokens(token.tokens), "bold");
+		case "paragraph": return renderInlineTokens(token.tokens);
+		case "code": return [plain(toMonospace(token.text))];
+		case "blockquote": return renderBlockquote(token);
+		case "list": return renderList(token);
+		case "table": return renderTable(token);
+		case "hr": return [plain(HR_LINE)];
+		case "space":
+		case "def": return [];
+		default: return renderInlineToken(token);
+	}
+};
+const renderBlockTokens = (tokens) => {
+	const blocks = [];
+	for (const token of tokens) {
+		const rendered = renderBlockToken(asMarkedToken(token));
+		if (spanText(rendered)) blocks.push(rendered);
+	}
+	return joinSpans(blocks, BLOCK_SEPARATOR);
+};
+const trimSpans = (spans) => {
+	const trimmed = [...spans];
+	while (trimmed.length > 0) {
+		const first = trimmed.at(0);
+		const text = first?.text.replace(LEADING_WHITESPACE, "");
+		if (first && text) {
+			trimmed[0] = {
+				...first,
+				text
+			};
+			break;
+		}
+		trimmed.shift();
+	}
+	while (trimmed.length > 0) {
+		const last = trimmed.at(-1);
+		const text = last?.text.replace(TRAILING_WHITESPACE, "");
+		if (last && text) {
+			trimmed[trimmed.length - 1] = {
+				...last,
+				text
+			};
+			break;
+		}
+		trimmed.pop();
+	}
+	return trimmed;
+};
+const finalize = (spans) => {
+	let text = "";
+	let hasLinks = false;
+	const open = /* @__PURE__ */ new Map();
+	const ranges = [];
+	const close = (style, end) => {
+		const start = open.get(style);
+		open.delete(style);
+		if (start !== void 0 && end > start) ranges.push({
+			type: style,
+			start,
+			length: end - start
+		});
+	};
+	for (const span of spans) {
+		if (!span.text) continue;
+		hasLinks ||= span.link === true;
+		const offset = text.length;
+		for (const style of STYLE_ORDER) if (span.styles.includes(style)) {
+			if (!open.has(style)) open.set(style, offset);
+		} else close(style, offset);
+		text += span.text;
+	}
+	for (const style of STYLE_ORDER) close(style, text.length);
+	ranges.sort((a, b) => a.start - b.start || STYLE_ORDER.indexOf(a.type) - STYLE_ORDER.indexOf(b.type));
+	return {
+		text,
+		formatting: ranges,
+		hasLinks
+	};
+};
+/**
+* Render standard markdown (CommonMark + GFM) to iMessage styled text: a
+* plain string plus UTF-16 formatting ranges for `messages.sendText`'s
+* `formatting` option. Block layout matches the plain-text renderer (list
+* bullets, `label (url)` links); inline emphasis becomes native
+* bold/italic/strikethrough ranges instead of being stripped, headings
+* render as bold, and code maps to Unicode mathematical monospace
+* characters. `hasLinks` reports whether any link or image put a URL into
+* the text, so the sender can enable Apple's data-detector pass.
+*/
+const markdownToIMessageText = (markdown) => finalize(trimSpans(renderBlockTokens(markdownLexer.lexer(markdown))));
+//#endregion
+//#region src/remote/send.ts
+const GROUP_ITEM_ALLOWED = new Set([
+	"text",
+	"markdown",
+	"attachment",
+	"contact",
+	"voice"
+]);
+const GROUP_TEXT_TYPES = new Set(["text", "markdown"]);
+const MAX_GROUP_TEXT_ITEMS = 1;
+const outboundRecord = (spaceId, id, content, timestamp, extras) => ({
+	id,
+	content,
+	direction: "outbound",
+	space: { id: spaceId },
+	timestamp,
+	...extras
+});
+const outboundGroupItem = (spaceId, id, content, timestamp, partIndex, parentId) => outboundRecord(spaceId, id, content, timestamp, {
+	partIndex,
+	parentId
+});
+const providerGroup = (items) => asGroup({ items });
+const withReply = (options, replyTo) => replyTo ? {
+	...options,
+	replyTo
+} : options;
+const replyOptions = (replyTo) => replyTo ? { replyTo } : void 0;
+const effectOption = (effect) => effect ? { effect } : {};
+const formattingOption = (formatting) => formatting.length > 0 ? { formatting } : {};
+const dataDetectionOption = (hasLinks) => hasLinks ? { enableDataDetection: true } : {};
+const renderMarkdown = (markdown) => {
+	const rendered = markdownToIMessageText(markdown);
+	if (!rendered.text) throw unsupportedRemoteContent("markdown", "renders to empty text — nothing to send");
+	return rendered;
+};
+const replyTargetFromId = (messageId) => {
+	const childRef = parseChildId(messageId);
+	if (childRef) return {
+		guid: toMessageGuid(childRef.parentGuid),
+		partIndex: childRef.partIndex
+	};
+	return toMessageGuid(messageId);
+};
+const outboundMessage = (spaceId, message, content) => outboundRecord(spaceId, message.guid, content, message.dateCreated);
+const outboundPoll = (spaceId, poll, content) => outboundRecord(spaceId, poll.pollMessageGuid, content, /* @__PURE__ */ new Date());
+const sendVCardAttachment = (remote, name, vcf) => remote.attachments.upload({
+	data: Buffer.from(vcf, "utf8"),
+	fileName: name
+});
+const sendContactAttachment = async (remote, content) => {
+	const vcf = await toVCard(content);
+	const name = vcardFileName(content);
+	return {
+		guid: (await sendVCardAttachment(remote, name, vcf)).attachment.guid,
+		name
+	};
+};
+const uploadAttachment = async (remote, content) => {
+	return {
+		guid: (await remote.attachments.upload({
+			data: await content.read(),
+			fileName: content.name
+		})).attachment.guid,
+		name: content.name
+	};
+};
+const uploadVoice = async (remote, content) => {
+	const { buffer } = await ensureM4a(await content.read(), content.mimeType);
+	const name = content.name ?? "voice.m4a";
+	return {
+		guid: (await remote.attachments.upload({
+			data: buffer,
+			fileName: name
+		})).attachment.guid,
+		name
+	};
+};
+const sendContent = async (remote, spaceId, chat, content, replyTo, effect) => {
+	switch (content.type) {
+		case "effect": return sendContent(remote, spaceId, chat, content.content, replyTo, content.effect);
+		case "text": return outboundMessage(spaceId, await remote.messages.sendText(chat, content.text, withReply(effectOption(effect), replyTo)), content);
+		case "markdown": {
+			const rendered = renderMarkdown(content.markdown);
+			return outboundMessage(spaceId, await remote.messages.sendText(chat, rendered.text, withReply({
+				...effectOption(effect),
+				...formattingOption(rendered.formatting),
+				...dataDetectionOption(rendered.hasLinks)
+			}, replyTo)), content);
+		}
+		case "richlink": return outboundMessage(spaceId, await remote.messages.sendText(chat, content.url, withReply({ enableLinkPreview: true }, replyTo)), content);
+		case "attachment": {
+			const { guid } = await uploadAttachment(remote, content);
+			return outboundMessage(spaceId, await remote.messages.sendAttachment(chat, guid, withReply(effectOption(effect), replyTo)), content);
+		}
+		case "contact": {
+			const { guid } = await sendContactAttachment(remote, content);
+			return outboundMessage(spaceId, await remote.messages.sendAttachment(chat, guid, replyOptions(replyTo)), content);
+		}
+		case "voice": {
+			const { guid } = await uploadVoice(remote, content);
+			return outboundMessage(spaceId, await remote.messages.sendAttachment(chat, guid, {
+				isAudioMessage: true,
+				...replyOptions(replyTo)
+			}), content);
+		}
+		case "poll":
+			if (replyTo) throw unsupportedRemoteContent("poll", "polls cannot be sent as replies");
+			return outboundPoll(spaceId, await remote.polls.create(chat, content.title, content.options.map((option) => option.title)), content);
+		default: throw unsupportedRemoteContent(content.type);
+	}
+};
+const validateGroupContent = (content) => {
+	let textCount = 0;
+	for (const sub of content.items) {
+		const itemType = sub.content.type;
+		if (!GROUP_ITEM_ALLOWED.has(itemType)) throw unsupportedRemoteContent("group", `"${itemType}" items are not supported inside a group`);
+		if (GROUP_TEXT_TYPES.has(itemType) && ++textCount > MAX_GROUP_TEXT_ITEMS) throw unsupportedRemoteContent("group", `groups can contain at most ${MAX_GROUP_TEXT_ITEMS} text item`);
+	}
+};
+const resolvePart = async (remote, content) => {
+	switch (content.type) {
+		case "text": return { text: content.text };
+		case "markdown": {
+			const rendered = renderMarkdown(content.markdown);
+			return {
+				text: rendered.text,
+				...formattingOption(rendered.formatting)
+			};
+		}
+		case "attachment": {
+			const { guid, name } = await uploadAttachment(remote, content);
+			return {
+				attachmentGuid: guid,
+				attachmentName: name
+			};
+		}
+		case "contact": {
+			const { guid, name } = await sendContactAttachment(remote, content);
+			return {
+				attachmentGuid: guid,
+				attachmentName: name
+			};
+		}
+		case "voice": {
+			const { guid, name } = await uploadVoice(remote, content);
+			return {
+				attachmentGuid: guid,
+				attachmentName: name
+			};
+		}
+		default: throw unsupportedRemoteContent(content.type);
+	}
+};
+const send$1 = async (remote, spaceId, content) => {
+	const chat = toChatGuid(spaceId);
+	if (content.type === "group") {
+		validateGroupContent(content);
+		const resolved = await Promise.all(content.items.map((sub) => resolvePart(remote, sub.content)));
+		const message = await remote.messages.sendMultipart(chat, resolved.map((part, idx) => ({
+			...part,
+			bubbleIndex: idx
+		})));
+		const parentGuid = message.guid;
+		const timestamp = message.dateCreated;
+		return outboundRecord(spaceId, parentGuid, providerGroup(content.items.map((sub, idx) => outboundGroupItem(spaceId, formatChildId(idx, parentGuid), sub.content, timestamp, idx, parentGuid))), timestamp);
+	}
+	return sendContent(remote, spaceId, chat, content);
+};
+const replyToMessage$1 = async (remote, spaceId, msgId, content) => {
+	return sendContent(remote, spaceId, toChatGuid(spaceId), content, replyTargetFromId(msgId));
+};
+const editMessage$1 = async (remote, spaceId, msgId, content) => {
+	if (content.type !== "text") throw unsupportedRemoteContent(content.type, "only text content can be edited");
+	const childRef = parseChildId(msgId);
+	await remote.messages.edit(toChatGuid(spaceId), toMessageGuid(childRef?.parentGuid ?? msgId), content.text, childRef ? { partIndex: childRef.partIndex } : void 0);
+};
+const unsendMessage$1 = async (remote, spaceId, msgId) => {
+	const childRef = parseChildId(msgId);
+	await remote.messages.unsend(toChatGuid(spaceId), toMessageGuid(childRef?.parentGuid ?? msgId), childRef ? { partIndex: childRef.partIndex } : void 0);
+};
+//#endregion
+//#region src/remote/contact-share.ts
+const log$1 = createLogger("spectrum.imessage.contact");
+const SHARE_TTL_MS = 1440 * 60 * 1e3;
+const MAX_TRACKED_CHATS = 1e4;
+/**
+* Tracks which chats this bot has already proactively pushed its contact card
+* to, so `im.chats.shareContactInfo` is fired at most once per chat per 24h
+* per iMessage provider instance.
+*
+* Backed by `lru-cache` for TTL + bounded memory. `ttlAutopurge: false`
+* keeps eviction lazy (on access) — there is no background timer to leak
+* across Spectrum lifecycles.
+*/
+var ContactShareTracker = class {
+	cache = new LRUCache({
+		max: MAX_TRACKED_CHATS,
+		ttl: SHARE_TTL_MS,
+		ttlAutopurge: false
+	});
+	/**
+	* Best-effort share. The cache is set eagerly so that a burst of inbound
+	* messages for the same chat coalesces to a single API call. On failure the
+	* entry is evicted so the next inbound retries — transient errors don't
+	* permanently mute the feature for a chat. Never awaits and never throws:
+	* the receive stream must not crash on share failures.
+	*/
+	maybeShare(client, chatGuid) {
+		if (this.cache.has(chatGuid)) return;
+		this.cache.set(chatGuid, true);
+		const safeChatGuid = sanitizeErrorMessage(chatGuid);
+		client.chats.shareContactInfo(chatGuid).then(() => {
+			log$1.info("shared contact card", { "spectrum.imessage.contact.chat": safeChatGuid });
+		}).catch((error) => {
+			this.cache.delete(chatGuid);
+			log$1.warn("failed to share contact card", {
+				"spectrum.imessage.contact.chat": safeChatGuid,
+				...errorAttrs(error)
+			}, error);
+		});
+	}
+};
+const trackers = /* @__PURE__ */ new WeakMap();
+/**
+* Returns a per-owner tracker. Mirrors `getMessageCache`/`getPollCache` in
+* ../cache.ts — keyed by an object (the `RemoteClient[]` array for remote
+* mode), so each iMessage provider instance has its own tracker and multiple
+* providers don't share state accidentally.
+*/
+const getContactShareTracker = (owner) => {
+	let tracker = trackers.get(owner);
+	if (!tracker) {
+		tracker = new ContactShareTracker();
+		trackers.set(owner, tracker);
+	}
+	return tracker;
+};
+//#endregion
+//#region src/remote/polls.ts
+const log = createLogger("spectrum.imessage.poll");
+const isVotedPollEvent = (event) => event.delta.type === "voted";
+const isUnvotedPollEvent = (event) => event.delta.type === "unvoted";
+const toCachedPoll = (input) => {
+	const poll = asPoll({
+		title: input.title,
+		options: input.options.map((optionInfo) => ({ title: optionInfo.text }))
+	});
+	const optionsByIdentifier = /* @__PURE__ */ new Map();
+	for (const [index, optionInfo] of input.options.entries()) {
+		const option = poll.options[index];
+		if (option && optionInfo.optionIdentifier) optionsByIdentifier.set(optionInfo.optionIdentifier, option);
+	}
+	return {
+		poll,
+		optionsByIdentifier
+	};
+};
+const cachePollInfo = (cache, info) => {
+	const cached = toCachedPoll(info);
+	cache.set(info.pollMessageGuid, cached);
+	return cached;
+};
+const cachePollEvent = (cache, event) => {
+	if (event.delta.type === "created" || event.delta.type === "optionAdded") try {
+		const cached = toCachedPoll({
+			title: event.delta.title,
+			options: event.delta.options
+		});
+		cache.set(event.pollMessageGuid, cached);
+		return cached;
+	} catch (e) {
+		log.error("failed to cache poll", {
+			"spectrum.imessage.poll.guid": event.pollMessageGuid,
+			...errorAttrs(e)
+		}, e);
+	}
+};
+const fetchPollInfo = async (client, cache, event) => {
+	try {
+		const info = await client.polls.get(event.pollMessageGuid);
+		cachePollInfo(cache, info);
+		return info;
+	} catch (e) {
+		log.error("failed to fetch poll", {
+			"spectrum.imessage.poll.guid": event.pollMessageGuid,
+			...errorAttrs(e)
+		}, e);
+		return;
+	}
+};
+const resolvePoll = async (client, cache, event) => {
+	const cached = cache.get(event.pollMessageGuid);
+	if (cached) return cached;
+	try {
+		return cachePollInfo(cache, await client.polls.get(event.pollMessageGuid));
+	} catch (e) {
+		log.error("failed to resolve poll", {
+			"spectrum.imessage.poll.guid": event.pollMessageGuid,
+			...errorAttrs(e)
+		}, e);
+		return;
+	}
+};
+const buildPollOptionMessage = (input) => {
+	const option = input.cached.optionsByIdentifier.get(input.optionId);
+	if (!option) return;
+	const action = input.selected ? "selected" : "deselected";
+	const eventTime = input.event.occurredAt.getTime();
+	return {
+		id: `${input.event.pollMessageGuid}:${input.senderAddress}:${input.optionId}:${action}:${eventTime}`,
+		sender: { id: input.senderAddress },
+		space: {
+			id: input.chatGuid,
+			type: chatTypeFromGuid(input.chatGuid),
+			phone: input.phone
+		},
+		timestamp: input.event.occurredAt,
+		content: asPollOption({
+			option,
+			poll: input.cached.poll,
+			selected: input.selected
+		})
+	};
+};
+const refreshPollMetadata = async (client, pollCache, event) => {
+	const info = await fetchPollInfo(client, pollCache, event);
+	if (!info) return;
+	return pollCache.get(info.pollMessageGuid);
+};
+const toPollOptionMessage = async (client, pollCache, event, phone) => {
+	const senderAddress = event.actor?.address;
+	const optionId = event.delta.optionIdentifier;
+	if (!(senderAddress && optionId)) return [];
+	let cached = await resolvePoll(client, pollCache, event);
+	if (!cached) return [];
+	if (!cached.optionsByIdentifier.has(optionId)) {
+		const refreshed = await refreshPollMetadata(client, pollCache, event);
+		if (refreshed) cached = refreshed;
+	}
+	const message = buildPollOptionMessage({
+		cached,
+		chatGuid: event.chatGuid,
+		event,
+		optionId,
+		phone,
+		selected: event.delta.type === "voted",
+		senderAddress
+	});
+	return message ? [message] : [];
+};
+const toPollDeltaMessages = async (client, pollCache, event, phone) => {
+	if (isVotedPollEvent(event)) return toPollOptionMessage(client, pollCache, event, phone);
+	if (isUnvotedPollEvent(event)) return toPollOptionMessage(client, pollCache, event, phone);
+	return [];
+};
+//#endregion
+//#region src/remote/stream.ts
+const isCursorRejectedIMessageError = (error) => error instanceof ValidationError;
+const streamLabel = (kind, phone) => `imessage.${kind}:${phone === "shared" ? phone : sanitizePhone(phone)}`;
+const isEventFromCurrentAccount = (event, phone) => event.isFromMe || phone !== "shared" && event.actor?.address !== void 0 && event.actor.address === phone;
+const toMessageItem = async (client, event, phone, cursor, onInbound) => {
+	if (event.type === "message.received") {
+		if (event.message.isFromMe) return {
+			cursor,
+			id: event.message.guid,
+			values: []
+		};
+		const inboundChatGuid = event.message.chatGuids?.[0];
+		if (inboundChatGuid) onInbound?.(inboundChatGuid);
+		const cache = getMessageCache(client);
+		return {
+			cursor,
+			id: event.message.guid,
+			values: await toInboundMessages(client, cache, event, phone)
+		};
+	}
+	if (event.type === "message.reactionAdded") {
+		if (isEventFromCurrentAccount(event, phone)) return {
+			cursor,
+			id: `${event.messageGuid}:reaction:${event.sequence}`,
+			values: []
+		};
+		const cache = getMessageCache(client);
+		return {
+			cursor,
+			id: `${event.messageGuid}:reaction:${event.sequence}`,
+			values: await toReactionMessages(client, cache, event, phone)
+		};
+	}
+	return {
+		cursor,
+		id: `${event.type}:${"messageGuid" in event ? event.messageGuid : "unknown"}:${event.sequence}`,
+		values: []
+	};
+};
+const toPollItem = async (client, pollCache, event, phone, cursor) => {
+	cachePollEvent(pollCache, event);
+	if (isEventFromCurrentAccount(event, phone)) return {
+		cursor,
+		id: `${event.pollMessageGuid}:poll:${event.sequence}`,
+		values: []
+	};
+	return {
+		cursor,
+		id: `${event.pollMessageGuid}:poll:${event.sequence}`,
+		values: await toPollDeltaMessages(client, pollCache, event, phone)
+	};
+};
+const toCatchUpCompleteItem = (event) => ({
+	cursor: String(event.headSequence),
+	id: `${event.type}:${event.headSequence}`,
+	values: []
+});
+const isMessageEvent = (event) => event.type.startsWith("message.");
+const isPollEvent = (event) => event.type === "poll.changed";
+async function* catchUpEvents(client, cursor, isWanted) {
+	const since = toResumeAfter(cursor);
+	if (since === void 0) return;
+	for await (const event of client.events.catchUp(since)) {
+		if (event.type === "catchup.complete") {
+			yield event;
+			return;
+		}
+		if (isWanted(event)) yield event;
+	}
+}
+const toResumeAfter = (cursor) => {
+	if (!cursor) return;
+	const sequence = Number(cursor);
+	return Number.isSafeInteger(sequence) && sequence >= 0 ? sequence : void 0;
+};
+async function* afterCursor(stream, cursor) {
+	const resumeAfter = toResumeAfter(cursor);
+	try {
+		for await (const event of stream) {
+			if (resumeAfter !== void 0 && event.sequence <= resumeAfter) continue;
+			yield event;
+		}
+	} finally {
+		await stream.close?.();
+	}
+}
+const withClose = (source, cursor) => Object.assign(afterCursor(source, cursor), { close: async () => {
+	await source.close?.();
+} });
+const messageStream = (client, phone, onInbound) => resumableOrderedStream({
+	fetchMissed: (cursor) => catchUpEvents(client, cursor, isMessageEvent),
+	isCursorRejectedError: isCursorRejectedIMessageError,
+	label: streamLabel("messages", phone),
+	processLive: (event) => toMessageItem(client, event, phone, String(event.sequence), onInbound),
+	processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toMessageItem(client, event, phone, String(event.sequence), onInbound),
+	subscribeLive: (cursor) => withClose(client.messages.subscribeEvents(), cursor)
+});
+const pollStream = (client, pollCache, phone) => resumableOrderedStream({
+	fetchMissed: (cursor) => catchUpEvents(client, cursor, isPollEvent),
+	isCursorRejectedError: isCursorRejectedIMessageError,
+	label: streamLabel("polls", phone),
+	processLive: (event) => toPollItem(client, pollCache, event, phone, String(event.sequence)),
+	processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toPollItem(client, pollCache, event, phone, String(event.sequence)),
+	subscribeLive: (cursor) => withClose(client.polls.subscribeEvents(), cursor)
+});
+const clientStream = (client, pollCache, phone, onInbound) => mergeStreams([messageStream(client, phone, onInbound), pollStream(client, pollCache, phone)]);
+const messages$1 = (clients, projectConfig) => {
+	const pollCache = getPollCache(clients);
+	const tracker = projectConfig?.profile?.imessageSynced === true ? getContactShareTracker(clients) : void 0;
+	return mergeStreams(clients.map((entry) => clientStream(entry.client, pollCache, entry.phone, tracker ? (chatGuid) => tracker.maybeShare(entry.client, chatGuid) : void 0)));
+};
+//#endregion
+//#region src/remote/stream-text.ts
+const INITIAL_THROTTLE_MS = 1e3;
+const BACKOFF_FACTOR = 2;
+const MAX_EDITS = 5;
+/**
+* Deliver a `streamText` content by sending the first chunk as a real message
+* and editing it in place as more text arrives. The stream materializes into a
+* normal text message: the returned record carries `asText(fullText)` with the
+* first send's id and timestamp.
+*/
+const sendStreamText$1 = async (remote, spaceId, content) => {
+	if (content.format === "markdown") throw unsupportedRemoteContent("streamText", "markdown-formatted streams have no native iMessage delivery");
+	const chat = toChatGuid(spaceId);
+	let sent;
+	let full = "";
+	let lastSentText = "";
+	let lastEditAt = 0;
+	let editCount = 0;
+	const flushEdit = async (text) => {
+		if (!sent || text === lastSentText) return;
+		await remote.messages.edit(chat, toMessageGuid(sent.guid), text);
+		lastSentText = text;
+		lastEditAt = Date.now();
+		editCount += 1;
+	};
+	for await (const delta of content.stream()) {
+		full += delta;
+		if (!sent) {
+			sent = await remote.messages.sendText(chat, full);
+			lastSentText = full;
+			lastEditAt = Date.now();
+			continue;
+		}
+		const hasBudgetForInterimEdit = editCount < MAX_EDITS - 1;
+		const requiredGap = INITIAL_THROTTLE_MS * BACKOFF_FACTOR ** editCount;
+		if (hasBudgetForInterimEdit && Date.now() - lastEditAt >= requiredGap) await flushEdit(full);
+	}
+	if (!sent) throw unsupportedRemoteContent("streamText", "stream produced no text — nothing to send");
+	await flushEdit(full);
+	return {
+		id: sent.guid,
+		content: asText(full),
+		direction: "outbound",
+		space: { id: spaceId },
+		timestamp: sent.dateCreated
+	};
+};
+//#endregion
+//#region src/remote/typing.ts
+const startTyping$1 = async (remote, spaceId) => {
+	await remote.chats.setTyping(toChatGuid(spaceId), true);
+};
+const stopTyping$1 = async (remote, spaceId) => {
+	await remote.chats.setTyping(toChatGuid(spaceId), false);
+};
+//#endregion
+//#region src/remote/api.ts
+const messages = (clients, projectConfig) => messages$1(clients, projectConfig);
+const setBackground = async (remote, spaceId, content) => setBackground$1(remote, spaceId, content);
+const sendCustomizedMiniApp = async (remote, spaceId, content) => sendCustomizedMiniApp$1(remote, spaceId, content);
+const setDisplayName = async (remote, spaceId, content) => setDisplayName$1(remote, spaceId, content);
+const setIcon = async (remote, spaceId, content) => setIcon$1(remote, spaceId, content);
+const markRead = async (remote, spaceId) => {
+	await markRead$1(remote, spaceId);
+};
+const shareContactCard = async (remote, spaceId) => {
+	await shareContactCard$1(remote, spaceId);
+};
+const startTyping = async (remote, spaceId) => {
+	await startTyping$1(remote, spaceId);
+};
+const stopTyping = async (remote, spaceId) => {
+	await stopTyping$1(remote, spaceId);
+};
+const send = async (remote, spaceId, content) => send$1(remote, spaceId, content);
+const sendStreamText = async (remote, spaceId, content) => sendStreamText$1(remote, spaceId, content);
+const replyToMessage = async (remote, spaceId, msgId, content) => replyToMessage$1(remote, spaceId, msgId, content);
+const editMessage = async (remote, spaceId, msgId, content) => editMessage$1(remote, spaceId, msgId, content);
+const reactToMessage = async (remote, spaceId, target, reaction) => reactToMessage$1(remote, spaceId, target, reaction);
+const unsendMessage = async (remote, spaceId, msgId) => unsendMessage$1(remote, spaceId, msgId);
+const unsendReaction = async (remote, spaceId, target, reaction) => unsendReaction$1(remote, spaceId, target, reaction);
+const getMessage = async (remote, spaceId, msgId, phone) => getMessage$1(remote, spaceId, msgId, phone);
+//#endregion
+//#region src/remote/app.ts
+/**
+* Fixed identity of Spectrum's own iMessage extension. The universal `app`
+* content renders through this extension, so callers never supply (or even see)
+* these constants — they pass only a URL and the card opens it inside the
+* Spectrum mini app on tap. Callers shipping their *own* extension use the
+* low-level `customizedMiniApp()` instead.
+*/
+const SPECTRUM_MINI_APP = {
+	appName: "Spectrum",
+	extensionBundleId: "codes.photon.Spectrum.MessagesExtension",
+	teamId: "P8XT6232SL",
+	appStoreId: 6777616651
+};
+/**
+* Build the iMessage mini-app card for an `app` content: Spectrum's fixed
+* identity plus the per-message `url` and the `layout` already derived from the
+* URL's link metadata.
+*/
+const toSpectrumMiniApp = (url, layout) => asCustomizedMiniApp({
+	...SPECTRUM_MINI_APP,
+	url,
+	layout
+});
+//#endregion
+//#region src/remote/client.ts
+const isSharedMode = (clients) => clients.length === 1 && clients[0]?.phone === "shared";
+const availablePhones = (clients) => clients.map((c) => c.phone);
+const clientForPhone = (clients, phone) => {
+	if (isSharedMode(clients)) {
+		const entry = clients[0];
+		if (!entry) throw new Error("No iMessage clients configured");
+		return entry.client;
+	}
+	const entry = clients.find((c) => c.phone === phone);
+	if (!entry) {
+		const list = availablePhones(clients).join(", ") || "<none>";
+		throw new Error(`No iMessage client serves phone ${phone}. Available: ${list}`);
+	}
+	return entry.client;
+};
+const randomPhone = (clients) => {
+	if (clients.length === 0) throw new Error("No iMessage phones configured for this account");
+	if (isSharedMode(clients)) return SHARED_PHONE;
+	const entry = clients[Math.floor(Math.random() * clients.length)];
+	if (!entry) throw new Error("No iMessage phones configured for this account");
+	return entry.phone;
+};
+//#endregion
+//#region src/index.ts
+const isPollContent = (content) => content.type === "poll" || content.type === "poll_option";
+const cacheRemoteOutbound = (remote, space, record) => {
+	if (!record) return record;
+	cacheMessage(getMessageCache(remote), {
+		...record,
+		direction: record.direction ?? "outbound",
+		space: {
+			...record.space,
+			id: record.space.id,
+			phone: space.phone,
+			type: space.type
+		}
+	});
+	return record;
+};
+const handleEdit = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("edit", "iMessage (local mode)");
+	if (content.content.type !== "text") throw UnsupportedError.content("edit", "iMessage", `only text content can be edited (got "${content.content.type}")`);
+	await editMessage(clientForPhone(client, space.phone), space.id, content.target.id, content.content);
+};
+const handleUnsend = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("unsend", "iMessage (local mode)");
+	if (isPollContent(content.target.content)) throw UnsupportedError.action("unsend", "iMessage", "iMessage polls cannot be unsent");
+	const remote = clientForPhone(client, space.phone);
+	const targetContent = content.target.content;
+	if (targetContent.type === "reaction") {
+		await unsendReaction(remote, space.id, targetContent.target, targetContent.emoji);
+		return;
+	}
+	await unsendMessage(remote, space.id, content.target.id);
+};
+const handleStreamText = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("streamText", "iMessage (local mode)", "streaming text responses require remote iMessage");
+	const remote = clientForPhone(client, space.phone);
+	return cacheRemoteOutbound(remote, space, await sendStreamText(remote, space.id, content));
+};
+const handleBackground = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("background", "iMessage (local mode)", "chat backgrounds require remote iMessage");
+	await setBackground(clientForPhone(client, space.phone), space.id, content);
+};
+const handleCustomizedMiniApp = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("customized-mini-app", "iMessage (local mode)", "mini app cards require remote iMessage");
+	const remote = clientForPhone(client, space.phone);
+	return cacheRemoteOutbound(remote, space, await sendCustomizedMiniApp(remote, space.id, content));
+};
+/**
+* Render the universal `app` content. On remote it becomes a native Spectrum
+* mini-app card (fixed `SPECTRUM_MINI_APP` identity + the URL + the layout
+* already parsed from the URL's link metadata). Local mode cannot send cards,
+* so it degrades to the bare URL as a text message.
+*/
+const handleApp = async (client, space, content) => {
+	const url = await content.url();
+	if (isLocal(client)) return await send$2(client, space.id, await text(url).build());
+	const layout = await content.layout();
+	const remote = clientForPhone(client, space.phone);
+	return cacheRemoteOutbound(remote, space, await sendCustomizedMiniApp(remote, space.id, toSpectrumMiniApp(url, layout)));
+};
+const handleRead = async (client, space) => {
+	if (isLocal(client)) throw UnsupportedError.action("read", "iMessage (local mode)", "marking chats as read requires remote iMessage");
+	await markRead(clientForPhone(client, space.phone), space.id);
+};
+const handleShareContactCard = async (client, space) => {
+	if (isLocal(client)) throw UnsupportedError.action("shareContactCard", "iMessage (local mode)", "sharing the contact card requires remote iMessage");
+	await shareContactCard(clientForPhone(client, space.phone), space.id);
+};
+const handleTyping = async (client, space, state) => {
+	if (isLocal(client)) return;
+	const remote = clientForPhone(client, space.phone);
+	if (state === "start") await startTyping(remote, space.id);
+	else await stopTyping(remote, space.id);
+};
+const handleRename = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("rename", "iMessage (local mode)", "renaming chats requires remote iMessage");
+	if (space.type !== "group") throw UnsupportedError.action("rename", "iMessage", "only group chats can be renamed (this space is a DM)");
+	await setDisplayName(clientForPhone(client, space.phone), space.id, content);
+};
+const handleAvatar = async (client, space, content) => {
+	if (isLocal(client)) throw UnsupportedError.action("avatar", "iMessage (local mode)", "setting group avatars requires remote iMessage");
+	if (space.type !== "group") throw UnsupportedError.action("avatar", "iMessage", "only group chats have avatars (this space is a DM)");
+	await setIcon(clientForPhone(client, space.phone), space.id, content);
+};
+/**
+* Dispatch the iMessage-only fire-and-forget control signals that live outside
+* the universal `Content` union (`background`, `contactCard`). Each is narrowed
+* via a runtime guard rather than a `content.type ===` check — the literals
+* aren't members of `Content["type"]`. Returns `true` when it consumed the
+* content so `send` can return early, keeping its dispatch chain flat.
+*/
+const handleProviderControlSignal = async (client, space, content) => {
+	if (isBackground(content)) {
+		await handleBackground(client, space, content);
+		return true;
+	}
+	if (isContactCard(content)) {
+		await handleShareContactCard(client, space);
+		return true;
+	}
+	return false;
+};
+/**
+* Resolve the remote client for a `reply` / `reaction` whose target is another
+* message. Both reject local mode and poll targets identically, so the guard
+* lives here to keep the `send` dispatch flat. `action` labels the error and
+* `pollNoun` is the plural used in the poll-unsupported message.
+*/
+const remoteForMessageTarget = (client, space, target, action, pollNoun) => {
+	if (isLocal(client)) throw UnsupportedError.action(action, "iMessage (local mode)");
+	if (isPollContent(target.content)) throw UnsupportedError.action(action, "iMessage", `iMessage polls do not support ${pollNoun}`);
+	return clientForPhone(client, space.phone);
+};
+const imessage = definePlatform("iMessage", {
+	config: configSchema,
+	static: { effect: { message: MessageEffect } },
+	lifecycle: {
+		createClient: async ({ config, projectId, projectSecret }) => {
+			if (config.local) return new IMessageSDK();
+			if (config.clients) return (Array.isArray(config.clients) ? config.clients : [config.clients]).map((e) => ({
+				phone: e.phone,
+				client: createClient({
+					address: e.address,
+					tls: true,
+					token: e.token
+				})
+			}));
+			if (!(projectId && projectSecret)) throw new Error("iMessage requires projectId and projectSecret. Either pass credentials to Spectrum(), use local mode: imessage.config({ local: true }), or provide explicit client config: imessage.config({ clients: [...] })");
+			return await createCloudClients(projectId, projectSecret);
+		},
+		destroyClient: async ({ client }) => {
+			if (isLocal(client)) {
+				await client.close();
+				return;
+			}
+			await disposeCloudAuth(client);
+			await Promise.all(client.map((entry) => entry.client.close()));
+		}
+	},
+	user: { resolve: async ({ input }) => ({ id: input.userID }) },
+	space: {
+		schema: spaceSchema,
+		params: spaceParamsSchema,
+		create: async ({ input, client }) => {
+			if (isLocal(client)) throw UnsupportedError.action("space.create", "iMessage (local mode)", "local mode only supports replying to existing messages");
+			if (input.users.length === 0) throw new Error("iMessage space creation requires at least one user");
+			if (client.length === 0) throw new Error("No iMessage clients configured");
+			const addresses = input.users.map((u) => u.id);
+			if (isSharedMode(client)) {
+				if (addresses.length > 1) throw UnsupportedError.action("space.create", "iMessage (shared mode)", "shared mode cannot create group chats — use a dedicated number, or space.get(chatGuid) for an existing group");
+				return {
+					id: dmChatGuid(addresses[0] ?? ""),
+					type: "dm",
+					phone: SHARED_PHONE
+				};
+			}
+			const phone = input.params?.phone ?? randomPhone(client);
+			const { chat } = await clientForPhone(client, phone).chats.create(addresses);
+			return {
+				id: chat.guid,
+				type: chat.isGroup ? "group" : "dm",
+				phone
+			};
+		},
+		get: async ({ input, client }) => {
+			if (isLocal(client)) throw UnsupportedError.action("space.get", "iMessage (local mode)", "local mode only supports replying to existing messages");
+			if (client.length === 0) throw new Error("No iMessage clients configured");
+			const phone = isSharedMode(client) ? SHARED_PHONE : input.params?.phone ?? (client.length === 1 ? client[0]?.phone : void 0);
+			if (!phone) throw new Error(`iMessage space.get requires params.phone when multiple clients are configured. Available: ${availablePhones(client).join(", ")}`);
+			return {
+				id: input.id,
+				type: chatTypeFromGuid(input.id),
+				phone
+			};
+		},
+		actions: {
+			background: async (space, input, opts) => {
+				await space.send(background(input, opts));
+			},
+			shareContactCard: async (space) => {
+				await space.send(nativeContactCard());
+			}
+		}
+	},
+	message: { schema: messageSchema },
+	messages: ({ client, projectConfig }) => isLocal(client) ? messages$2(client) : messages(client, projectConfig),
+	send: async ({ space, content, client }) => {
+		if (content.type === "reply") {
+			const remote = remoteForMessageTarget(client, space, content.target, "reply", "replies");
+			return cacheRemoteOutbound(remote, space, await replyToMessage(remote, space.id, content.target.id, content.content));
+		}
+		if (content.type === "reaction") {
+			const remote = remoteForMessageTarget(client, space, content.target, "react", "reactions");
+			return cacheRemoteOutbound(remote, space, await reactToMessage(remote, space.id, content.target, content.emoji));
+		}
+		if (content.type === "typing") {
+			await handleTyping(client, space, content.state);
+			return;
+		}
+		if (content.type === "edit") {
+			await handleEdit(client, space, content);
+			return;
+		}
+		if (content.type === "unsend") {
+			await handleUnsend(client, space, content);
+			return;
+		}
+		if (content.type === "streamText") return await handleStreamText(client, space, content);
+		if (content.type === "rename") {
+			await handleRename(client, space, content);
+			return;
+		}
+		if (content.type === "avatar") {
+			await handleAvatar(client, space, content);
+			return;
+		}
+		if (content.type === "read") {
+			await handleRead(client, space);
+			return;
+		}
+		if (content.type === "app") return await handleApp(client, space, content);
+		if (await handleProviderControlSignal(client, space, content)) return;
+		if (isCustomizedMiniApp(content)) return await handleCustomizedMiniApp(client, space, content);
+		if (isLocal(client)) return await send$2(client, space.id, content);
+		const remote = clientForPhone(client, space.phone);
+		return cacheRemoteOutbound(remote, space, await send(remote, space.id, content));
+	},
+	actions: {
+		getMessage: async ({ client }, space, messageId) => {
+			if (isLocal(client)) return getMessage$2(client, messageId);
+			return getMessage(clientForPhone(client, space.phone), space.id, messageId, space.phone);
+		},
+		getAttachment: async ({ client }, guid, phone) => {
+			if (isLocal(client)) throw UnsupportedError.action("getAttachment", "iMessage (local mode)", "fetching attachments by GUID requires remote iMessage");
+			if (client.length === 0) throw new Error("No iMessage clients configured");
+			const routedPhone = (() => {
+				if (isSharedMode(client)) return SHARED_PHONE;
+				if (phone) return phone;
+				if (client.length === 1) return client[0].phone;
+				throw new Error(`imessage.getAttachment requires a phone in multi-phone mode. Available: ${availablePhones(client).join(", ")}`);
+			})();
+			const remote = clientForPhone(client, routedPhone);
+			return withSpan("spectrum.imessage.getAttachment", {
+				"spectrum.provider": "iMessage",
+				"spectrum.imessage.attachment.guid": guid,
+				"spectrum.imessage.phone": routedPhone
+			}, () => getRemoteAttachment(remote, guid));
+		}
+	}
+});
+//#endregion
+export { background, customizedMiniApp, effect, imessage, nativeContactCard, read };