@ai-matrx/messaging 0.1.3 → 0.2.0

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { ReactNode, SVGProps } from 'react';
+import { ComponentType, ReactNode, SVGProps } from 'react';
 import { MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
@@ -781,12 +781,39 @@ declare function messagingClientId(): string;
  * resubscribe loop that looks exactly like "realtime is broken".
  */
 
+/**
+ * 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>>;
+}
 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>;
 }
 interface MessagingProviderProps {
     /** Any Supabase client. `null` while the host is still resolving one. */
@@ -804,6 +831,14 @@ 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. */
@@ -1286,4 +1321,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, 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, type MessageActionRenderProps, type MessageActionRenderer, 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 };

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, SVGProps } from 'react';
+import { ComponentType, ReactNode, SVGProps } from 'react';
 import { MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
@@ -781,12 +781,39 @@ declare function messagingClientId(): string;
  * resubscribe loop that looks exactly like "realtime is broken".
  */
 
+/**
+ * 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>>;
+}
 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>;
 }
 interface MessagingProviderProps {
     /** Any Supabase client. `null` while the host is still resolving one. */
@@ -804,6 +831,14 @@ 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. */
@@ -1286,4 +1321,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, 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, type MessageActionRenderProps, type MessageActionRenderer, 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 };

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) {
@@ -1763,6 +1774,14 @@ 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 host = useMemo(() => {
     if (engine === null) return null;
     return {
@@ -1770,13 +1789,15 @@ function MessagingRuntime(props) {
       actions: actionRegistry,
       ai,
       identity: engine.identity,
-      openReference: referenceRef.current ?? null
+      openReference: referenceRef.current ?? null,
+      actionRenderers: rendererMap
     };
-  }, [engine, actionRegistry, ai]);
+  }, [engine, actionRegistry, ai, rendererMap]);
+  const MessagingContext = messagingContext();
   return /* @__PURE__ */ jsx(MessagingContext.Provider, { value: host, children });
 }
 function useMessagingHost() {
-  return useContext(MessagingContext);
+  return useContext(messagingContext());
 }
 function useRequiredMessagingHost() {
   const host = useMessagingHost();
@@ -2788,7 +2809,22 @@ function MessageBubble(props) {
   ] });
 }
 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,