@ai-matrx/messaging 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 0.4.0 — 2026-09-07
+
+**A ```matrx fence written in the PLATFORM's dialect was being deleted on render.** Found the
+moment the first consumer's real messages went through this package's bubble. Third and last
+release of the adoption session.
+
+### Fixed
+
+- **A fence this package cannot parse is never dropped.** `splitText` advanced past an
+  unrecognized fence and emitted nothing for it, so a message that named a note or a task lost
+  that paragraph between the sender and the reader — silently, with the surrounding prose intact
+  so nothing looked wrong. This package understands exactly one fence dialect (its own array of
+  `{entityType, entityId}`); Matrx's real fences are two-key `__kind` directive shells whose
+  items are typed per noun and resolvable only by the app's kind registry, i.e. every real
+  reference on the platform hit this path.
+- **The regression test that should have caught it was hollow** — it asserted
+  `segments.every(s => s.type === "text")` on what was, after the drop, an EMPTY array. Replaced
+  with one that asserts the fence survives, and one for the platform's own dialect.
+- **An unreadable fence collapses to the label `Reference` in previews and notifications**, never
+  to nothing. Collapsing to nothing is how a reference-only message becomes an inbox row reading
+  "No messages yet".
+
+### Added
+
+- **`renderFence`** — the host draws ```matrx fences with its own renderer, every fence, parsed
+  or not. A platform's fence dialect is the platform's business.
+- `TextSegment` gains `{ type: "fence", body }`. With no host renderer the bubble draws an inert
+  card labeled "Reference" whose title says what is missing and how to wire it — drawn, never
+  deleted, never a code block of JSON.
+
+### Consumer action (C28)
+
+- **A host on the Matrx reference-fence protocol MUST pass `renderFence`** or its references
+  render as the generic inert card. matrx-frontend passes `MatrxEnvelopeBlock`.
+- Code that switches on `TextSegment.type` gains a third case. TypeScript will point at it.
+
+## 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,32 @@ 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.
+
+**If your platform has its own ```matrx fence dialect, pass `renderFence` too.** This package
+parses one shape (an array of `{entityType, entityId}`); anything else reaches your renderer
+verbatim as the fence body. Without it those fences draw an honest inert "Reference" card — they
+are never deleted, and never shown to a reader as JSON.
+
 ### Theming
 
 Structural CSS ships in the package; the token **contract** is enforced; token **values** are

package/dist/index.cjs

@@ -319,21 +319,32 @@ function splitText(content) {
     if (start > cursor) {
       segments.push({ type: "text", value: content.slice(cursor, start) });
     }
-    parseFenceBody(match[1] ?? "").forEach((reference) => {
-      segments.push({ type: "reference", reference });
-    });
+    const body = match[1] ?? "";
+    const references = parseFenceBody(body);
+    if (references.length === 0) {
+      segments.push({ type: "fence", body });
+    } else {
+      references.forEach((reference) => {
+        segments.push({ type: "reference", reference });
+      });
+    }
     cursor = start + match[0].length;
   }
   if (cursor < content.length) {
     segments.push({ type: "text", value: content.slice(cursor) });
   }
   return segments.filter(
-    (segment) => segment.type === "reference" || segment.value.trim().length > 0
+    (segment) => segment.type !== "text" || segment.value.trim().length > 0
   );
 }
 function summarizeText(content, maxLength = 140) {
   const parts = splitText(content).map(
-    (segment) => segment.type === "text" ? segment.value : segment.reference.label
+    (segment) => segment.type === "text" ? segment.value : segment.type === "reference" ? segment.reference.label : (
+      // A fence we cannot read still SAYS something. Collapsing it to
+      // nothing is how a reference-only message becomes an inbox row that
+      // reads "No messages yet" — a screen telling a lie.
+      "Reference"
+    )
   );
   const flattened = parts.join(" ").replace(/\s+/g, " ").trim();
   if (flattened.length <= maxLength) return flattened;