@ai-matrx/messaging 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 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
+`git diff npm/messaging/v0.1.2..npm/messaging/v0.1.3 -- apps/shared/messaging`).
+No source changes intended and no consumer action required.
+
 ## 0.1.2 — 2026-08-31
 
 **Typing, presence and message broadcast work.** The root defect was in `@ai-matrx/realtime`

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,25 @@ 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.
+
 ### 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) {
@@ -1859,6 +1866,14 @@ 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 host = (0, import_react.useMemo)(() => {
     if (engine === null) return null;
     return {
@@ -1866,13 +1881,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__ */ (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();
@@ -2884,7 +2901,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__ */ (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,