@ai-matrx/messaging 0.1.3 → 0.3.0

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { ReactNode, SVGProps } from 'react';
+import { ReactNode, ComponentType, SVGProps } from 'react';
 import { MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
@@ -781,12 +781,85 @@ declare function messagingClientId(): string;
  * resubscribe loop that looks exactly like "realtime is broken".
  */
 
+/**
+ * What the host needs to decide whether to interrupt someone, and what to say.
+ */
+interface IncomingMessageContext {
+    /** The message landed in the conversation currently on screen. */
+    readonly isActiveConversation: boolean;
+    /** The conversation it landed in, when the inbox already holds it. */
+    readonly conversation: ConversationSummary | null;
+}
+/**
+ * A host-supplied surface for ONE action kind.
+ *
+ * Chips answer a QUESTION ("Approve" / "Decline"); some actions are not
+ * questions. A shared-resource card, a link out to a report, a reminder with an
+ * app icon — those are app-shaped surfaces that only the host can draw, and a
+ * host that cannot draw them in the bubble ends up keeping its own message
+ * renderer beside this package's, which is the failure this package exists to
+ * prevent.
+ *
+ * The forward-compatibility rule is unchanged and enforced here, not by the
+ * host: a kind at a version this build does not list renders NOTHING.
+ */
+interface MessageActionRenderProps<TPayload = unknown> {
+    readonly message: Message;
+    readonly payload: TPayload;
+    /** The signed-in user wrote this message — bubble-side styling depends on it. */
+    readonly isOwn: boolean;
+}
+interface MessageActionRenderer<TPayload = unknown> {
+    readonly kind: string;
+    /** Versions this build understands. An unlisted version renders nothing. */
+    readonly versions: readonly number[];
+    readonly render: ComponentType<MessageActionRenderProps<TPayload>>;
+}
+/**
+ * A host's own renderer for a Matrx reference.
+ *
+ * References are the ONE piece of a bubble an app is likely to already render
+ * everywhere else — this platform resolves a ```matrx fence through a kind
+ * registry and draws a live, openable chip. Two different treatments of the
+ * same fence in one app is the second-renderer defect, so a host may hand us
+ * theirs. Omit it and the package's own card is used, which is what a
+ * greenfield consumer wants.
+ */
+type ReferenceRenderer = ComponentType<{
+    reference: MatrxReference;
+}>;
+/**
+ * App chrome wrapped around ONE message bubble or ONE conversation row.
+ *
+ * The reason this exists is the right-click menu. A platform whose every
+ * surface answers a right-click with copy / export / attach / hand-to-an-agent
+ * cannot have messaging be the one surface that does not — and a menu is
+ * per-row app chrome that no package can own (it needs the app's surface name,
+ * its entity tokens, its clipboard primitive). Without the seam a host keeps
+ * its own message list beside this one, which is the whole failure mode.
+ *
+ * It wraps; it does not replace. The bubble it receives is the package's.
+ */
+interface MessageWrapperProps {
+    readonly message: Message;
+    readonly isMine: boolean;
+    readonly children: ReactNode;
+}
+interface ConversationRowWrapperProps {
+    readonly conversation: ConversationSummary;
+    readonly children: ReactNode;
+}
 interface MessagingHost {
     readonly engine: MessagingEngine;
     readonly actions: ActionRegistry;
     readonly ai: MessagingAi | null;
     readonly identity: MessagingIdentity;
     readonly openReference: ((reference: MatrxReference) => void) | null;
+    /** Host surfaces for action kinds whose answer is a card, not a chip. */
+    readonly actionRenderers: ReadonlyMap<string, MessageActionRenderer>;
+    readonly renderReference: ReferenceRenderer | null;
+    readonly wrapMessage: ComponentType<MessageWrapperProps> | null;
+    readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
 interface MessagingProviderProps {
     /** Any Supabase client. `null` while the host is still resolving one. */
@@ -804,10 +877,31 @@ interface MessagingProviderProps {
     agents?: MessagingAgents | undefined;
     /** Handlers for actionable messages. Registered once per handler identity. */
     actions?: readonly ActionHandler<never>[] | undefined;
+    /**
+     * Host surfaces for action kinds whose answer is a CARD, not a chip — a
+     * shared-resource card, a link out, an app-shaped reminder. A kind with a
+     * renderer draws that instead of chips; every other rule is unchanged,
+     * including the one that matters: an unknown kind, or a known kind at an
+     * unlisted version, renders NOTHING.
+     */
+    actionRenderers?: readonly MessageActionRenderer<never>[] | undefined;
     /** Called when a reference card is clicked. Omit and cards render inert-but-labeled. */
     onOpenReference?: ((reference: MatrxReference) => void) | undefined;
-    /** A message arrived from someone else — for a toast, sound, or badge. */
-    onIncomingMessage?: ((message: Message) => void) | undefined;
+    /** Draw references with the app's own renderer instead of the package card. */
+    renderReference?: ReferenceRenderer | undefined;
+    /** App chrome (a right-click menu, a drop target) around each message bubble. */
+    wrapMessage?: ComponentType<MessageWrapperProps> | undefined;
+    /** App chrome around each conversation row. */
+    wrapConversationRow?: ComponentType<ConversationRowWrapperProps> | undefined;
+    /**
+     * A message arrived from someone else — for a toast, sound, or badge.
+     *
+     * The CONTEXT is not a courtesy. "Do not interrupt someone for the
+     * conversation they are looking at" is the rule every chat app needs and only
+     * this package can answer, and a notification names the SENDER, whose display
+     * name lives on the conversation the host cannot see from above the provider.
+     */
+    onIncomingMessage?: ((message: Message, context: IncomingMessageContext) => void) | undefined;
     /** Background failures, with a remedy. Defaults to a console sink. */
     onDiagnostic?: ((event: EngineDiagnostic) => void) | undefined;
     /** Re-resolve a session after one goes missing. Enables the single retry. */
@@ -1286,4 +1380,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, avatarPaletteIndex, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, getInitials, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, avatarPaletteIndex, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, getInitials, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, SVGProps } from 'react';
+import { ReactNode, ComponentType, SVGProps } from 'react';
 import { MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
@@ -781,12 +781,85 @@ declare function messagingClientId(): string;
  * resubscribe loop that looks exactly like "realtime is broken".
  */
 
+/**
+ * What the host needs to decide whether to interrupt someone, and what to say.
+ */
+interface IncomingMessageContext {
+    /** The message landed in the conversation currently on screen. */
+    readonly isActiveConversation: boolean;
+    /** The conversation it landed in, when the inbox already holds it. */
+    readonly conversation: ConversationSummary | null;
+}
+/**
+ * A host-supplied surface for ONE action kind.
+ *
+ * Chips answer a QUESTION ("Approve" / "Decline"); some actions are not
+ * questions. A shared-resource card, a link out to a report, a reminder with an
+ * app icon — those are app-shaped surfaces that only the host can draw, and a
+ * host that cannot draw them in the bubble ends up keeping its own message
+ * renderer beside this package's, which is the failure this package exists to
+ * prevent.
+ *
+ * The forward-compatibility rule is unchanged and enforced here, not by the
+ * host: a kind at a version this build does not list renders NOTHING.
+ */
+interface MessageActionRenderProps<TPayload = unknown> {
+    readonly message: Message;
+    readonly payload: TPayload;
+    /** The signed-in user wrote this message — bubble-side styling depends on it. */
+    readonly isOwn: boolean;
+}
+interface MessageActionRenderer<TPayload = unknown> {
+    readonly kind: string;
+    /** Versions this build understands. An unlisted version renders nothing. */
+    readonly versions: readonly number[];
+    readonly render: ComponentType<MessageActionRenderProps<TPayload>>;
+}
+/**
+ * A host's own renderer for a Matrx reference.
+ *
+ * References are the ONE piece of a bubble an app is likely to already render
+ * everywhere else — this platform resolves a ```matrx fence through a kind
+ * registry and draws a live, openable chip. Two different treatments of the
+ * same fence in one app is the second-renderer defect, so a host may hand us
+ * theirs. Omit it and the package's own card is used, which is what a
+ * greenfield consumer wants.
+ */
+type ReferenceRenderer = ComponentType<{
+    reference: MatrxReference;
+}>;
+/**
+ * App chrome wrapped around ONE message bubble or ONE conversation row.
+ *
+ * The reason this exists is the right-click menu. A platform whose every
+ * surface answers a right-click with copy / export / attach / hand-to-an-agent
+ * cannot have messaging be the one surface that does not — and a menu is
+ * per-row app chrome that no package can own (it needs the app's surface name,
+ * its entity tokens, its clipboard primitive). Without the seam a host keeps
+ * its own message list beside this one, which is the whole failure mode.
+ *
+ * It wraps; it does not replace. The bubble it receives is the package's.
+ */
+interface MessageWrapperProps {
+    readonly message: Message;
+    readonly isMine: boolean;
+    readonly children: ReactNode;
+}
+interface ConversationRowWrapperProps {
+    readonly conversation: ConversationSummary;
+    readonly children: ReactNode;
+}
 interface MessagingHost {
     readonly engine: MessagingEngine;
     readonly actions: ActionRegistry;
     readonly ai: MessagingAi | null;
     readonly identity: MessagingIdentity;
     readonly openReference: ((reference: MatrxReference) => void) | null;
+    /** Host surfaces for action kinds whose answer is a card, not a chip. */
+    readonly actionRenderers: ReadonlyMap<string, MessageActionRenderer>;
+    readonly renderReference: ReferenceRenderer | null;
+    readonly wrapMessage: ComponentType<MessageWrapperProps> | null;
+    readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
 interface MessagingProviderProps {
     /** Any Supabase client. `null` while the host is still resolving one. */
@@ -804,10 +877,31 @@ interface MessagingProviderProps {
     agents?: MessagingAgents | undefined;
     /** Handlers for actionable messages. Registered once per handler identity. */
     actions?: readonly ActionHandler<never>[] | undefined;
+    /**
+     * Host surfaces for action kinds whose answer is a CARD, not a chip — a
+     * shared-resource card, a link out, an app-shaped reminder. A kind with a
+     * renderer draws that instead of chips; every other rule is unchanged,
+     * including the one that matters: an unknown kind, or a known kind at an
+     * unlisted version, renders NOTHING.
+     */
+    actionRenderers?: readonly MessageActionRenderer<never>[] | undefined;
     /** Called when a reference card is clicked. Omit and cards render inert-but-labeled. */
     onOpenReference?: ((reference: MatrxReference) => void) | undefined;
-    /** A message arrived from someone else — for a toast, sound, or badge. */
-    onIncomingMessage?: ((message: Message) => void) | undefined;
+    /** Draw references with the app's own renderer instead of the package card. */
+    renderReference?: ReferenceRenderer | undefined;
+    /** App chrome (a right-click menu, a drop target) around each message bubble. */
+    wrapMessage?: ComponentType<MessageWrapperProps> | undefined;
+    /** App chrome around each conversation row. */
+    wrapConversationRow?: ComponentType<ConversationRowWrapperProps> | undefined;
+    /**
+     * A message arrived from someone else — for a toast, sound, or badge.
+     *
+     * The CONTEXT is not a courtesy. "Do not interrupt someone for the
+     * conversation they are looking at" is the rule every chat app needs and only
+     * this package can answer, and a notification names the SENDER, whose display
+     * name lives on the conversation the host cannot see from above the provider.
+     */
+    onIncomingMessage?: ((message: Message, context: IncomingMessageContext) => void) | undefined;
     /** Background failures, with a remedy. Defaults to a console sink. */
     onDiagnostic?: ((event: EngineDiagnostic) => void) | undefined;
     /** Re-resolve a session after one goes missing. Enables the single retry. */
@@ -1286,4 +1380,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, avatarPaletteIndex, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, getInitials, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, avatarPaletteIndex, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, getInitials, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.js

@@ -10,7 +10,11 @@ import {
   useRef,
   useSyncExternalStore
 } from "react";
-import { RealtimeProvider, useRealtimeManager } from "@ai-matrx/realtime/react";
+import {
+  RealtimeProvider,
+  useIsRealtimeProviderMounted,
+  useRealtimeManager
+} from "@ai-matrx/realtime/react";
 
 // src/core/actions.ts
 function receiptKey(kind, messageId, actorId) {
@@ -1684,7 +1688,12 @@ function createMessagingRepository(options) {
 
 // src/react/provider.tsx
 import { jsx } from "react/jsx-runtime";
-var MessagingContext = createContext(null);
+function messagingContext() {
+  return globalSlot(
+    "react-context",
+    () => createContext(null)
+  );
+}
 function defaultDiagnostics(event) {
   const line = `[@ai-matrx/messaging] ${event.message}${event.remedy !== void 0 ? `
   \u2192 ${event.remedy}` : ""}`;
@@ -1695,6 +1704,8 @@ function defaultDiagnostics(event) {
 function MessagingProvider(props) {
   const { client, userId, organizationId } = props;
   const ready = client != null && typeof userId === "string" && userId.length > 0 && typeof organizationId === "string" && organizationId.length > 0;
+  const hostProvidesRealtime = useIsRealtimeProviderMounted();
+  if (hostProvidesRealtime) return /* @__PURE__ */ jsx(MessagingRuntime, { ...props });
   return /* @__PURE__ */ jsx(RealtimeProvider, { client: ready ? client : null, actorId: userId ?? void 0, children: /* @__PURE__ */ jsx(MessagingRuntime, { ...props }) });
 }
 function MessagingRuntime(props) {
@@ -1728,7 +1739,8 @@ function MessagingRuntime(props) {
       identity,
       ...props.resolveSession !== void 0 ? { resolveSession: props.resolveSession } : {}
     });
-    return createMessagingEngine({
+    let built = null;
+    built = createMessagingEngine({
       repository,
       manager,
       identity,
@@ -1737,8 +1749,18 @@ function MessagingRuntime(props) {
         onFallback: (message) => report({ level: "warn", message })
       }),
       onDiagnostic: report,
-      onIncoming: (message) => incomingRef.current?.(message)
+      onIncoming: (message) => {
+        const snapshot = built?.store.snapshot();
+        if (snapshot === void 0) return;
+        incomingRef.current?.(message, {
+          isActiveConversation: snapshot.activeConversationId === message.conversationId,
+          conversation: snapshot.conversations.find(
+            (item) => item.conversation.id === message.conversationId
+          ) ?? null
+        });
+      }
     });
+    return built;
   }, [ready, manager, userId, organizationId]);
   useEffect(() => {
     if (engine === null) return void 0;
@@ -1763,6 +1785,17 @@ function MessagingRuntime(props) {
       agents
     });
   }, [transport, agents, ready, organizationId]);
+  const renderers = props.actionRenderers;
+  const rendererMap = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    (renderers ?? []).forEach((renderer) => {
+      map.set(renderer.kind, renderer);
+    });
+    return map;
+  }, [renderers]);
+  const renderReference = props.renderReference ?? null;
+  const wrapMessage = props.wrapMessage ?? null;
+  const wrapConversationRow = props.wrapConversationRow ?? null;
   const host = useMemo(() => {
     if (engine === null) return null;
     return {
@@ -1770,13 +1803,18 @@ function MessagingRuntime(props) {
       actions: actionRegistry,
       ai,
       identity: engine.identity,
-      openReference: referenceRef.current ?? null
+      openReference: referenceRef.current ?? null,
+      actionRenderers: rendererMap,
+      renderReference,
+      wrapMessage,
+      wrapConversationRow
     };
-  }, [engine, actionRegistry, ai]);
+  }, [engine, actionRegistry, ai, rendererMap, renderReference, wrapMessage, wrapConversationRow]);
+  const MessagingContext = messagingContext();
   return /* @__PURE__ */ jsx(MessagingContext.Provider, { value: host, children });
 }
 function useMessagingHost() {
-  return useContext(MessagingContext);
+  return useContext(messagingContext());
 }
 function useRequiredMessagingHost() {
   const host = useMessagingHost();
@@ -2442,6 +2480,7 @@ var AI_LABELS = {
 };
 function ConversationList(props) {
   const { conversations, hasMore, isInitialLoading, loadMore, select, activeConversationId } = useConversations();
+  const RowChrome = useMessagingHost()?.wrapConversationRow ?? null;
   const [query, setQuery] = useState2("");
   const visible = useMemo3(() => {
     const needle = query.trim().toLowerCase();
@@ -2482,17 +2521,20 @@ function ConversationList(props) {
           title: query.length > 0 ? "No matches" : "No conversations yet",
           body: query.length > 0 ? "Try a different name or word." : "Start one and it will appear here."
         }
-      ) : /* @__PURE__ */ jsx4("ul", { className: "mx-msg__rows", children: visible.map((item) => /* @__PURE__ */ jsx4("li", { children: /* @__PURE__ */ jsx4(
-        ConversationRow,
-        {
-          summary: item,
-          isActive: item.conversation.id === activeConversationId,
-          onSelect: () => {
-            select(item.conversation.id);
-            props.onSelect?.(item.conversation.id);
+      ) : /* @__PURE__ */ jsx4("ul", { className: "mx-msg__rows", children: visible.map((item) => {
+        const row = /* @__PURE__ */ jsx4(
+          ConversationRow,
+          {
+            summary: item,
+            isActive: item.conversation.id === activeConversationId,
+            onSelect: () => {
+              select(item.conversation.id);
+              props.onSelect?.(item.conversation.id);
+            }
           }
-        }
-      ) }, item.conversation.id)) }),
+        );
+        return /* @__PURE__ */ jsx4("li", { children: RowChrome !== null ? /* @__PURE__ */ jsx4(RowChrome, { conversation: item, children: row }) : row }, item.conversation.id);
+      }) }),
       hasMore && !isInitialLoading ? /* @__PURE__ */ jsx4(
         "button",
         {
@@ -2721,6 +2763,8 @@ function MessageGroupView(props) {
 function MessageBubble(props) {
   const { message, isMine } = props;
   const host = useMessagingHost();
+  const HostReference = host?.renderReference ?? null;
+  const MessageChrome = host?.wrapMessage ?? null;
   if (message.deletedAt !== null) {
     return /* @__PURE__ */ jsx4("div", { className: "mx-msg__bubble mx-msg__bubble--deleted", children: "Message deleted" });
   }
@@ -2731,10 +2775,16 @@ function MessageBubble(props) {
     message.deliveryState === "sending" ? "mx-msg__bubble--pending" : "",
     message.deliveryState === "failed" ? "mx-msg__bubble--failed" : ""
   ].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsxs2(Fragment, { children: [
+  const bubble = /* @__PURE__ */ jsxs2(Fragment, { children: [
     /* @__PURE__ */ jsxs2("div", { className: classes, children: [
       splitText(message.content).map(
-        (segment, index) => segment.type === "text" ? /* @__PURE__ */ jsx4("span", { children: segment.value }, index) : /* @__PURE__ */ jsx4(
+        (segment, index) => segment.type === "text" ? /* @__PURE__ */ jsx4("span", { children: segment.value }, index) : HostReference !== null ? /* @__PURE__ */ jsx4(
+          HostReference,
+          {
+            reference: segment.reference
+          },
+          `${segment.reference.entityType}:${segment.reference.entityId}`
+        ) : /* @__PURE__ */ jsx4(
           ReferenceCard,
           {
             reference: segment.reference,
@@ -2743,14 +2793,22 @@ function MessageBubble(props) {
           `${segment.reference.entityType}:${segment.reference.entityId}`
         )
       ),
-      message.references.map((reference) => /* @__PURE__ */ jsx4(
-        ReferenceCard,
-        {
-          reference,
-          onOpen: host?.openReference ?? null
-        },
-        `structured:${reference.entityType}:${reference.entityId}`
-      )),
+      message.references.map(
+        (reference) => HostReference !== null ? /* @__PURE__ */ jsx4(
+          HostReference,
+          {
+            reference
+          },
+          `structured:${reference.entityType}:${reference.entityId}`
+        ) : /* @__PURE__ */ jsx4(
+          ReferenceCard,
+          {
+            reference,
+            onOpen: host?.openReference ?? null
+          },
+          `structured:${reference.entityType}:${reference.entityId}`
+        )
+      ),
       message.action !== null ? /* @__PURE__ */ jsx4(MessageActionChips, { message }) : null
     ] }),
     /* @__PURE__ */ jsxs2(
@@ -2786,9 +2844,25 @@ function MessageBubble(props) {
       }
     )
   ] });
+  return MessageChrome !== null ? /* @__PURE__ */ jsx4(MessageChrome, { message, isMine, children: bubble }) : bubble;
 }
 function MessageActionChips(props) {
+  const host = useRequiredMessagingHost();
   const action = useMessageAction(props.message);
+  const declared = props.message.action;
+  const renderer = declared === null ? void 0 : host.actionRenderers.get(declared.kind);
+  if (declared !== null && renderer !== void 0) {
+    if (!renderer.versions.includes(declared.version)) return null;
+    const Render = renderer.render;
+    return /* @__PURE__ */ jsx4(
+      Render,
+      {
+        message: props.message,
+        payload: declared.payload,
+        isOwn: props.message.senderId === host.identity.userId
+      }
+    );
+  }
   if (action.receipt !== null) {
     return /* @__PURE__ */ jsxs2("span", { className: "mx-msg__receipt", children: [
       action.receipt.label,