@ai-matrx/messaging 0.3.0 → 0.6.0

package/dist/react.d.cts

@@ -17,10 +17,22 @@ import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
  * is the JSON boundary — `metadata` and `action_data` are host/DB-generated
  * shapes this package does not own (the data 0.2.1 `Json = unknown` lesson).
  */
-/** Nominal id types. A conversation id can never be passed where a user id goes. */
-declare const brand: unique symbol;
+/**
+ * Nominal id types. A conversation id can never be passed where a user id goes.
+ *
+ * 🚨 THE MARKER IS A NAMED PROPERTY, NOT A `unique symbol`. This package ships
+ * two entries built as two separate bundles, so a `declare const brand: unique
+ * symbol` is DECLARED TWICE — and two unique symbols are two different types.
+ * `ConversationId` from `@ai-matrx/messaging` then does not match
+ * `ConversationId` from `@ai-matrx/messaging/react`, which makes the two
+ * entries unusable together: the first consumer hit exactly that, calling
+ * `asConversationId` from the core and passing it to a hook. A structural
+ * marker is identical in both declarations, so the brands unify — and it still
+ * cannot be produced by accident, which is all nominal typing needs to do.
+ * (The marker is types-only; nothing writes it at runtime.)
+ */
 type Brand<T, B extends string> = T & {
-    readonly [brand]: B;
+    readonly __mxBrand: B;
 };
 type ConversationId = Brand<string, "ConversationId">;
 type MessageId = Brand<string, "MessageId">;
@@ -828,6 +840,17 @@ interface MessageActionRenderer<TPayload = unknown> {
 type ReferenceRenderer = ComponentType<{
     reference: MatrxReference;
 }>;
+/**
+ * A host's renderer for a raw ```matrx fence — the body between the backticks.
+ *
+ * This package understands one fence dialect: its own. A platform's fences are
+ * its platform's business (Matrx's are `__kind` directive shells resolved
+ * through a kind registry), and only the app can draw them. Give us this and
+ * EVERY fence in a message goes to you, parsed or not.
+ */
+type FenceRenderer = ComponentType<{
+    body: string;
+}>;
 /**
  * App chrome wrapped around ONE message bubble or ONE conversation row.
  *
@@ -858,6 +881,7 @@ interface MessagingHost {
     /** Host surfaces for action kinds whose answer is a card, not a chip. */
     readonly actionRenderers: ReadonlyMap<string, MessageActionRenderer>;
     readonly renderReference: ReferenceRenderer | null;
+    readonly renderFence: FenceRenderer | null;
     readonly wrapMessage: ComponentType<MessageWrapperProps> | null;
     readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
@@ -889,6 +913,8 @@ interface MessagingProviderProps {
     onOpenReference?: ((reference: MatrxReference) => void) | undefined;
     /** Draw references with the app's own renderer instead of the package card. */
     renderReference?: ReferenceRenderer | undefined;
+    /** Draw ```matrx fences with the app's own renderer — every fence, parsed or not. */
+    renderFence?: FenceRenderer | undefined;
     /** App chrome (a right-click menu, a drop target) around each message bubble. */
     wrapMessage?: ComponentType<MessageWrapperProps> | undefined;
     /** App chrome around each conversation row. */
@@ -1077,11 +1103,6 @@ declare function Avatar(props: {
 declare function DeliveryTick(props: {
     state: DeliveryState;
 }): React.ReactElement | null;
-/**
- * A reference card. NO DEAD ENDS: when the host wired `onOpenReference` it is a
- * button that opens; when it did not, it renders as a labeled, non-interactive
- * card with a title explaining why — never a button that does nothing.
- */
 declare function ReferenceCard(props: {
     reference: MatrxReference;
     onOpen?: ((reference: MatrxReference) => void) | null;
@@ -1289,13 +1310,6 @@ declare function formatConversationTime(isoString: string | null, now?: number,
 declare function formatMessageTime(isoString: string, locale?: string): string;
 /** The separator between day groups in a thread. */
 declare function formatDateSeparator(isoString: string, now?: number, locale?: string): string;
-declare function getInitials(name: string): string;
-/**
- * A stable palette index for an avatar with no image. Deterministic on the id,
- * so the same person is the same color on every device and every reload — a
- * random color per render is a surprisingly loud bug.
- */
-declare function avatarPaletteIndex(seed: string, buckets?: number): number;
 /**
  * Group consecutive messages by the same sender within a window, the way every
  * good chat UI does — one avatar and one name per burst.
@@ -1363,6 +1377,20 @@ type TextSegment = {
 } | {
     readonly type: "reference";
     readonly reference: MatrxReference;
+}
+/**
+ * A ```matrx fence this package could not resolve into references.
+ *
+ * It is NOT dropped. Platforms carry richer fence dialects than this
+ * package's own array shape — Matrx's is a `__kind` directive shell whose
+ * items are typed per noun, resolvable only by the app's kind registry — and
+ * a fence silently deleted on render is a message that lost a paragraph
+ * between the sender and the reader. The host draws it (`renderFence`), or
+ * the package draws an honest inert card. Never a code block of JSON.
+ */
+ | {
+    readonly type: "fence";
+    readonly body: string;
 };
 /** Every reference a message carries, from both transports, de-duplicated. */
 declare function extractReferences(content: string, structured?: readonly MatrxReference[]): readonly MatrxReference[];
@@ -1380,4 +1408,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, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, 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 MessageWrapperProps, 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, type ReferenceRenderer, 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, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, 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 MessageWrapperProps, 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, type ReferenceRenderer, 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, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, 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

@@ -17,10 +17,22 @@ import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
  * is the JSON boundary — `metadata` and `action_data` are host/DB-generated
  * shapes this package does not own (the data 0.2.1 `Json = unknown` lesson).
  */
-/** Nominal id types. A conversation id can never be passed where a user id goes. */
-declare const brand: unique symbol;
+/**
+ * Nominal id types. A conversation id can never be passed where a user id goes.
+ *
+ * 🚨 THE MARKER IS A NAMED PROPERTY, NOT A `unique symbol`. This package ships
+ * two entries built as two separate bundles, so a `declare const brand: unique
+ * symbol` is DECLARED TWICE — and two unique symbols are two different types.
+ * `ConversationId` from `@ai-matrx/messaging` then does not match
+ * `ConversationId` from `@ai-matrx/messaging/react`, which makes the two
+ * entries unusable together: the first consumer hit exactly that, calling
+ * `asConversationId` from the core and passing it to a hook. A structural
+ * marker is identical in both declarations, so the brands unify — and it still
+ * cannot be produced by accident, which is all nominal typing needs to do.
+ * (The marker is types-only; nothing writes it at runtime.)
+ */
 type Brand<T, B extends string> = T & {
-    readonly [brand]: B;
+    readonly __mxBrand: B;
 };
 type ConversationId = Brand<string, "ConversationId">;
 type MessageId = Brand<string, "MessageId">;
@@ -828,6 +840,17 @@ interface MessageActionRenderer<TPayload = unknown> {
 type ReferenceRenderer = ComponentType<{
     reference: MatrxReference;
 }>;
+/**
+ * A host's renderer for a raw ```matrx fence — the body between the backticks.
+ *
+ * This package understands one fence dialect: its own. A platform's fences are
+ * its platform's business (Matrx's are `__kind` directive shells resolved
+ * through a kind registry), and only the app can draw them. Give us this and
+ * EVERY fence in a message goes to you, parsed or not.
+ */
+type FenceRenderer = ComponentType<{
+    body: string;
+}>;
 /**
  * App chrome wrapped around ONE message bubble or ONE conversation row.
  *
@@ -858,6 +881,7 @@ interface MessagingHost {
     /** Host surfaces for action kinds whose answer is a card, not a chip. */
     readonly actionRenderers: ReadonlyMap<string, MessageActionRenderer>;
     readonly renderReference: ReferenceRenderer | null;
+    readonly renderFence: FenceRenderer | null;
     readonly wrapMessage: ComponentType<MessageWrapperProps> | null;
     readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
@@ -889,6 +913,8 @@ interface MessagingProviderProps {
     onOpenReference?: ((reference: MatrxReference) => void) | undefined;
     /** Draw references with the app's own renderer instead of the package card. */
     renderReference?: ReferenceRenderer | undefined;
+    /** Draw ```matrx fences with the app's own renderer — every fence, parsed or not. */
+    renderFence?: FenceRenderer | undefined;
     /** App chrome (a right-click menu, a drop target) around each message bubble. */
     wrapMessage?: ComponentType<MessageWrapperProps> | undefined;
     /** App chrome around each conversation row. */
@@ -1077,11 +1103,6 @@ declare function Avatar(props: {
 declare function DeliveryTick(props: {
     state: DeliveryState;
 }): React.ReactElement | null;
-/**
- * A reference card. NO DEAD ENDS: when the host wired `onOpenReference` it is a
- * button that opens; when it did not, it renders as a labeled, non-interactive
- * card with a title explaining why — never a button that does nothing.
- */
 declare function ReferenceCard(props: {
     reference: MatrxReference;
     onOpen?: ((reference: MatrxReference) => void) | null;
@@ -1289,13 +1310,6 @@ declare function formatConversationTime(isoString: string | null, now?: number,
 declare function formatMessageTime(isoString: string, locale?: string): string;
 /** The separator between day groups in a thread. */
 declare function formatDateSeparator(isoString: string, now?: number, locale?: string): string;
-declare function getInitials(name: string): string;
-/**
- * A stable palette index for an avatar with no image. Deterministic on the id,
- * so the same person is the same color on every device and every reload — a
- * random color per render is a surprisingly loud bug.
- */
-declare function avatarPaletteIndex(seed: string, buckets?: number): number;
 /**
  * Group consecutive messages by the same sender within a window, the way every
  * good chat UI does — one avatar and one name per burst.
@@ -1363,6 +1377,20 @@ type TextSegment = {
 } | {
     readonly type: "reference";
     readonly reference: MatrxReference;
+}
+/**
+ * A ```matrx fence this package could not resolve into references.
+ *
+ * It is NOT dropped. Platforms carry richer fence dialects than this
+ * package's own array shape — Matrx's is a `__kind` directive shell whose
+ * items are typed per noun, resolvable only by the app's kind registry — and
+ * a fence silently deleted on render is a message that lost a paragraph
+ * between the sender and the reader. The host draws it (`renderFence`), or
+ * the package draws an honest inert card. Never a code block of JSON.
+ */
+ | {
+    readonly type: "fence";
+    readonly body: string;
 };
 /** Every reference a message carries, from both transports, de-duplicated. */
 declare function extractReferences(content: string, structured?: readonly MatrxReference[]): readonly MatrxReference[];
@@ -1380,4 +1408,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, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, 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 MessageWrapperProps, 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, type ReferenceRenderer, 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, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, 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 MessageWrapperProps, 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, type ReferenceRenderer, 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, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, 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

@@ -222,21 +222,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;
@@ -1794,6 +1805,7 @@ function MessagingRuntime(props) {
     return map;
   }, [renderers]);
   const renderReference = props.renderReference ?? null;
+  const renderFence = props.renderFence ?? null;
   const wrapMessage = props.wrapMessage ?? null;
   const wrapConversationRow = props.wrapConversationRow ?? null;
   const host = useMemo(() => {
@@ -1806,10 +1818,20 @@ function MessagingRuntime(props) {
       openReference: referenceRef.current ?? null,
       actionRenderers: rendererMap,
       renderReference,
+      renderFence,
       wrapMessage,
       wrapConversationRow
     };
-  }, [engine, actionRegistry, ai, rendererMap, renderReference, wrapMessage, wrapConversationRow]);
+  }, [
+    engine,
+    actionRegistry,
+    ai,
+    rendererMap,
+    renderReference,
+    renderFence,
+    wrapMessage,
+    wrapConversationRow
+  ]);
   const MessagingContext = messagingContext();
   return /* @__PURE__ */ jsx(MessagingContext.Provider, { value: host, children });
 }
@@ -1885,20 +1907,6 @@ function formatDateSeparator(isoString, now = Date.now(), locale) {
     day: "numeric"
   });
 }
-function getInitials(name) {
-  const parts = name.trim().split(/\s+/).filter(Boolean);
-  if (parts.length === 0) return "?";
-  const first = parts[0]?.[0] ?? "";
-  const last = parts.length > 1 ? parts.at(-1)?.[0] ?? "" : "";
-  return `${first}${last}`.toUpperCase() || "?";
-}
-function avatarPaletteIndex(seed, buckets = 8) {
-  let hash = 0;
-  for (let index = 0; index < seed.length; index += 1) {
-    hash = hash * 31 + seed.charCodeAt(index) | 0;
-  }
-  return Math.abs(hash) % buckets;
-}
 function groupMessages(messages, args = {}) {
   const windowMs = args.windowMs ?? 5 * MINUTE;
   const now = args.now ?? Date.now();
@@ -2267,6 +2275,9 @@ function resolveActor(message, sender) {
   };
 }
 
+// src/react/parts.tsx
+import { avatarPaletteIndex, getInitials } from "@ai-matrx/kit/format";
+
 // src/react/icons.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
 function Icon(props) {
@@ -2400,6 +2411,20 @@ function DeliveryTick(props) {
       return null;
   }
 }
+function UnreadableReference() {
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      className: "mx-msg__reference mx-msg__reference--inert",
+      title: "This message names something in a reference format this app has not wired. Pass renderFence to <MessagingProvider> to render it.",
+      children: [
+        /* @__PURE__ */ jsx3(LinkIcon, {}),
+        /* @__PURE__ */ jsx3("span", { className: "mx-msg__reference-type", children: "reference" }),
+        "Reference"
+      ]
+    }
+  );
+}
 function ReferenceCard(props) {
   const { reference, onOpen } = props;
   const href = reference.href;
@@ -2764,6 +2789,7 @@ function MessageBubble(props) {
   const { message, isMine } = props;
   const host = useMessagingHost();
   const HostReference = host?.renderReference ?? null;
+  const HostFence = host?.renderFence ?? null;
   const MessageChrome = host?.wrapMessage ?? null;
   if (message.deletedAt !== null) {
     return /* @__PURE__ */ jsx4("div", { className: "mx-msg__bubble mx-msg__bubble--deleted", children: "Message deleted" });
@@ -2778,7 +2804,7 @@ function MessageBubble(props) {
   const bubble = /* @__PURE__ */ jsxs2(Fragment, { children: [
     /* @__PURE__ */ jsxs2("div", { className: classes, children: [
       splitText(message.content).map(
-        (segment, index) => segment.type === "text" ? /* @__PURE__ */ jsx4("span", { children: segment.value }, index) : HostReference !== null ? /* @__PURE__ */ jsx4(
+        (segment, index) => segment.type === "text" ? /* @__PURE__ */ jsx4("span", { children: segment.value }, index) : segment.type === "fence" ? HostFence !== null ? /* @__PURE__ */ jsx4(HostFence, { body: segment.body }, `fence:${index}`) : /* @__PURE__ */ jsx4(UnreadableReference, {}, `fence:${index}`) : HostReference !== null ? /* @__PURE__ */ jsx4(
           HostReference,
           {
             reference: segment.reference
@@ -3030,7 +3056,6 @@ export {
   asMessageId,
   asOrganizationId,
   asUserId,
-  avatarPaletteIndex,
   composeFence,
   conversationTopic,
   createActionRegistry,
@@ -3048,7 +3073,6 @@ export {
   formatLastSeen,
   formatMessageTime,
   formatTypists,
-  getInitials,
   groupMessages,
   inboxTopic,
   invalidResponse,