@ai-matrx/messaging 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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).

package/README.md

@@ -241,6 +241,27 @@ rule that matters: an unknown kind — or a known kind at a version this build d
 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

@@ -1831,7 +1831,8 @@ function MessagingRuntime(props) {
       identity,
       ...props.resolveSession !== void 0 ? { resolveSession: props.resolveSession } : {}
     });
-    return createMessagingEngine({
+    let built = null;
+    built = createMessagingEngine({
       repository,
       manager,
       identity,
@@ -1840,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;
@@ -1874,6 +1885,9 @@ function MessagingRuntime(props) {
     });
     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 {
@@ -1882,9 +1896,12 @@ function MessagingRuntime(props) {
       ai,
       identity: engine.identity,
       openReference: referenceRef.current ?? null,
-      actionRenderers: rendererMap
+      actionRenderers: rendererMap,
+      renderReference,
+      wrapMessage,
+      wrapConversationRow
     };
-  }, [engine, actionRegistry, ai, rendererMap]);
+  }, [engine, actionRegistry, ai, rendererMap, renderReference, wrapMessage, wrapConversationRow]);
   const MessagingContext = messagingContext();
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MessagingContext.Provider, { value: host, children });
 }
@@ -2555,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();
@@ -2595,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",
         {
@@ -2834,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" });
   }
@@ -2844,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,
@@ -2856,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)(
@@ -2899,6 +2936,7 @@ function MessageBubble(props) {
       }
     )
   ] });
+  return MessageChrome !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(MessageChrome, { message, isMine, children: bubble }) : bubble;
 }
 function MessageActionChips(props) {
   const host = useRequiredMessagingHost();