@ai-matrx/messaging 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 0.3.0 — 2026-09-07
+
+**Three more seams the first adoption needed** — each one a case where the host
+would otherwise have kept a piece of its own messaging UI beside this package's,
+which is the failure this package exists to prevent. Same session as 0.2.0.
+
+### Added
+
+- **`wrapMessage` / `wrapConversationRow` — app chrome around a bubble and a row.**
+  The reason 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 that menu needs the app's surface name, entity tokens and clipboard primitive — none
+  of which a package can own. The wrapper WRAPS the package's bubble; it cannot replace it.
+- **`renderReference` — the host's own reference renderer.** References are the one part of a
+  bubble an app is most likely to already render everywhere else (this platform resolves a
+  ```matrx fence through a kind registry into a live chip). Two treatments of one fence in one
+  app is the second-renderer defect. Omit it and the package's card is used, unchanged.
+- **`onIncomingMessage` now receives an `IncomingMessageContext`** —
+  `{ isActiveConversation, conversation }`. "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
+  desktop notification names the SENDER, whose display name lives on a conversation the host
+  cannot see from above the provider. (The origin surface had `sender_id.substring(0, 8)` and a
+  `// Placeholder` comment where the name belonged.)
+
+### Consumer action (C28)
+
+- `onIncomingMessage` gains a SECOND argument. Existing one-argument callbacks keep compiling and
+  keep working — but if you were suppressing notifications for the open conversation by reading
+  your own state, delete that and read `context.isActiveConversation`.
+- Hosts with their own reference chips or per-row context menus: pass `renderReference` /
+  `wrapMessage` / `wrapConversationRow` and DELETE the host-side message list.
+
+## 0.2.0 — 2026-09-07
+
+**Both fixes came from the first real adoption** (matrx-frontend, the C9 full-elimination swap).
+Each is a case of the package forcing the host to keep something it should not have had to keep.
+
+### Fixed
+
+- **The provider no longer builds a SECOND realtime manager under a host that already has one.**
+  `<MessagingProvider>` mounted `<RealtimeProvider>` unconditionally. An app that wires
+  `@ai-matrx/realtime` has exactly ONE provider on purpose — the manager owns the write ledger
+  that makes an optimistic write's own echo recognizable — so a second manager beneath it gave
+  this package its own ledger and its own channels: our sends looked remote to the host's
+  realtime consumers, and both sides subscribed to the same rooms twice. The provider now asks
+  `useIsRealtimeProviderMounted()` (`@ai-matrx/realtime` 0.3.0) and rides the host's manager when
+  there is one; an app that wires none still gets a provider for free, so R7 is unchanged.
+  Probing `useRealtimeManager() !== null` would NOT have worked — it is also null while a mounted
+  host provider waits for its Supabase client.
+- **The React context moved into the `globalSlot`.** Module-scope `createContext` splits in two
+  under dual ESM/CJS evaluation, exactly like every other piece of module-level state this
+  package already slots.
+
+### Added
+
+- **`actionRenderers` — a host surface for an action kind whose answer is a CARD, not a chip.**
+  Chips answer a question ("Approve" / "Decline"); a shared-resource card, a link out to a
+  report, an app-icon reminder are app-shaped surfaces only the host can draw. Without this seam
+  the first consumer had to keep its own message renderer beside this package's — a package plus
+  a surviving custom copy, which is the failure this package exists to prevent. The
+  forward-compatibility rule stays the PACKAGE's: an unknown kind, or a known kind at a version
+  the renderer does not list, renders nothing.
+  Types: `MessageActionRenderer`, `MessageActionRenderProps` from `@ai-matrx/messaging/react`.
+- `src/react/host-integration.test.tsx` — four tests: the host's manager is the one messaging
+  uses (fails against 0.1.3), a provider-less app still gets one, a host renderer draws inside
+  the bubble, and an unlisted version renders nothing.
+
+### Consumer action (C28)
+
+- **Requires `@ai-matrx/realtime` >= 0.3.0**, picked up automatically by the `"latest"` spec.
+- Nothing to change in existing wiring. If your app mounts its own `<RealtimeProvider>`, messaging
+  now rides it — that is the fix, and it is what you wanted.
+- Hosts with action kinds that render a card rather than a decision: pass them as
+  `actionRenderers={[{ kind, versions, render }]}` and DELETE the host-side bubble renderer.
+
 ## 0.1.3
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -184,6 +184,19 @@ that fails when pressed.
 Omit it and reference cards render as labeled, non-interactive cards with a title explaining why —
 honest, never a button that does nothing.
 
+### Mounting it in an app that already wires realtime
+
+Nothing to do. `<MessagingProvider>` rides the host's `<RealtimeProvider>` when one is mounted
+above it, and mounts its own only when there is none. That is not a convenience — an app has ONE
+realtime manager on purpose (it owns the write ledger that makes an optimistic write's own echo
+recognizable), and a second one under it makes each manager's writes look remote to the other.
+
+```tsx
+<RealtimeProvider client={supabase} actorId={user.id}>   {/* the app's ONE mount */}
+  <MessagingProvider client={supabase} userId={user.id} organizationId={org.id}>
+    …
+```
+
 ### Registering an actionable message kind
 
 ```tsx
@@ -209,6 +222,46 @@ honest, never a button that does nothing.
 This is the seam `@ai-matrx/meet` uses: a call invitation is just a message with a structured
 payload.
 
+### An action kind whose answer is a card, not a chip
+
+Chips answer a question. A shared-resource card, a link out to a report, a reminder with an app
+icon are app-shaped surfaces only the host can draw — so the host supplies the surface and the
+package still owns the gate:
+
+```tsx
+<MessagingProvider … actionRenderers={[{
+  kind: "resource_shared",
+  versions: [1],
+  render: ({ payload, isOwn }) => <ResourceSharedCard payload={payload} isOwn={isOwn} />,
+}]}>
+```
+
+A kind with a renderer draws it instead of chips. Everything else is unchanged, including the
+rule that matters: an unknown kind — or a known kind at a version this build does not list —
+renders NOTHING. Use `actions` for decisions, `actionRenderers` for surfaces; a kind may have
+both a handler (for `summarize`, used by previews) and a renderer.
+
+### Your app's chrome around our bubbles
+
+A platform whose surfaces all answer a right-click, or that already renders references through
+its own registry, hands those in rather than rebuilding the thread:
+
+```tsx
+<MessagingProvider …
+  wrapMessage={({ message, children }) => (
+    <MessageContextMenu message={message}>{children}</MessageContextMenu>
+  )}
+  wrapConversationRow={({ conversation, children }) => (
+    <ConversationContextMenu conversation={conversation}>{children}</ConversationContextMenu>
+  )}
+  renderReference={({ reference }) => <AppReferenceChip reference={reference} />}
+/>
+```
+
+`wrapMessage` and `wrapConversationRow` WRAP; they never replace. `renderReference` replaces the
+package's card — deliberately, because an app that draws references everywhere else must not
+draw them two ways.
+
 ### Theming
 
 Structural CSS ships in the package; the token **contract** is enforced; token **values** are

package/dist/react.cjs

@@ -1780,7 +1780,12 @@ function createMessagingRepository(options) {
 
 // src/react/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-var MessagingContext = (0, import_react.createContext)(null);
+function messagingContext() {
+  return globalSlot(
+    "react-context",
+    () => (0, import_react.createContext)(null)
+  );
+}
 function defaultDiagnostics(event) {
   const line = `[@ai-matrx/messaging] ${event.message}${event.remedy !== void 0 ? `
   \u2192 ${event.remedy}` : ""}`;
@@ -1791,6 +1796,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 = (0, import_react2.useIsRealtimeProviderMounted)();
+  if (hostProvidesRealtime) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MessagingRuntime, { ...props });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.RealtimeProvider, { client: ready ? client : null, actorId: userId ?? void 0, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MessagingRuntime, { ...props }) });
 }
 function MessagingRuntime(props) {
@@ -1824,7 +1831,8 @@ function MessagingRuntime(props) {
       identity,
       ...props.resolveSession !== void 0 ? { resolveSession: props.resolveSession } : {}
     });
-    return createMessagingEngine({
+    let built = null;
+    built = createMessagingEngine({
       repository,
       manager,
       identity,
@@ -1833,8 +1841,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]);
   (0, import_react.useEffect)(() => {
     if (engine === null) return void 0;
@@ -1859,6 +1877,17 @@ function MessagingRuntime(props) {
       agents
     });
   }, [transport, agents, ready, organizationId]);
+  const renderers = props.actionRenderers;
+  const rendererMap = (0, import_react.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 = (0, import_react.useMemo)(() => {
     if (engine === null) return null;
     return {
@@ -1866,13 +1895,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__ */ (0, import_jsx_runtime.jsx)(MessagingContext.Provider, { value: host, children });
 }
 function useMessagingHost() {
-  return (0, import_react.useContext)(MessagingContext);
+  return (0, import_react.useContext)(messagingContext());
 }
 function useRequiredMessagingHost() {
   const host = useMessagingHost();
@@ -2538,6 +2572,7 @@ var AI_LABELS = {
 };
 function ConversationList(props) {
   const { conversations, hasMore, isInitialLoading, loadMore, select, activeConversationId } = useConversations();
+  const RowChrome = useMessagingHost()?.wrapConversationRow ?? null;
   const [query, setQuery] = (0, import_react5.useState)("");
   const visible = (0, import_react5.useMemo)(() => {
     const needle = query.trim().toLowerCase();
@@ -2578,17 +2613,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__ */ (0, import_jsx_runtime4.jsx)("ul", { className: "mx-msg__rows", children: visible.map((item) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("li", { children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
-        ConversationRow,
-        {
-          summary: item,
-          isActive: item.conversation.id === activeConversationId,
-          onSelect: () => {
-            select(item.conversation.id);
-            props.onSelect?.(item.conversation.id);
+      ) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("ul", { className: "mx-msg__rows", children: visible.map((item) => {
+        const row = /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          ConversationRow,
+          {
+            summary: item,
+            isActive: item.conversation.id === activeConversationId,
+            onSelect: () => {
+              select(item.conversation.id);
+              props.onSelect?.(item.conversation.id);
+            }
           }
-        }
-      ) }, item.conversation.id)) }),
+        );
+        return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("li", { children: RowChrome !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(RowChrome, { conversation: item, children: row }) : row }, item.conversation.id);
+      }) }),
       hasMore && !isInitialLoading ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
         "button",
         {
@@ -2817,6 +2855,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__ */ (0, import_jsx_runtime4.jsx)("div", { className: "mx-msg__bubble mx-msg__bubble--deleted", children: "Message deleted" });
   }
@@ -2827,10 +2867,16 @@ function MessageBubble(props) {
     message.deliveryState === "sending" ? "mx-msg__bubble--pending" : "",
     message.deliveryState === "failed" ? "mx-msg__bubble--failed" : ""
   ].filter(Boolean).join(" ");
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
+  const bubble = /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: classes, children: [
       splitText(message.content).map(
-        (segment, index) => segment.type === "text" ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { children: segment.value }, index) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+        (segment, index) => segment.type === "text" ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { children: segment.value }, index) : HostReference !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          HostReference,
+          {
+            reference: segment.reference
+          },
+          `${segment.reference.entityType}:${segment.reference.entityId}`
+        ) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
           ReferenceCard,
           {
             reference: segment.reference,
@@ -2839,14 +2885,22 @@ function MessageBubble(props) {
           `${segment.reference.entityType}:${segment.reference.entityId}`
         )
       ),
-      message.references.map((reference) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
-        ReferenceCard,
-        {
-          reference,
-          onOpen: host?.openReference ?? null
-        },
-        `structured:${reference.entityType}:${reference.entityId}`
-      )),
+      message.references.map(
+        (reference) => HostReference !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          HostReference,
+          {
+            reference
+          },
+          `structured:${reference.entityType}:${reference.entityId}`
+        ) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          ReferenceCard,
+          {
+            reference,
+            onOpen: host?.openReference ?? null
+          },
+          `structured:${reference.entityType}:${reference.entityId}`
+        )
+      ),
       message.action !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(MessageActionChips, { message }) : null
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
@@ -2882,9 +2936,25 @@ function MessageBubble(props) {
       }
     )
   ] });
+  return MessageChrome !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(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__ */ (0, import_jsx_runtime4.jsx)(
+      Render,
+      {
+        message: props.message,
+        payload: declared.payload,
+        isOwn: props.message.senderId === host.identity.userId
+      }
+    );
+  }
   if (action.receipt !== null) {
     return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("span", { className: "mx-msg__receipt", children: [
       action.receipt.label,