@ai-matrx/chat 0.7.26 → 0.7.27

package/dist/messenger/MessengerRail.js

@@ -0,0 +1,184 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useState, useSyncExternalStore } from "react";
+import { ChevronDown, ChevronRight, PanelLeftClose, PanelLeftOpen } from "lucide-react";
+import { cn } from "@ai-matrx/design-system/cn";
+import {
+  isSpaceGroup
+} from "./contract.js";
+import { MessengerAvatar } from "./MessengerAvatar.js";
+import { MessengerContextMenu } from "./MessengerMenu.js";
+const RAIL_COLLAPSED_KEY = "ai-matrx.messenger.rail-collapsed";
+const listeners = /* @__PURE__ */ new Set();
+function readCollapsed() {
+  try {
+    return globalThis.localStorage?.getItem(RAIL_COLLAPSED_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+function subscribe(listener) {
+  listeners.add(listener);
+  const onStorage = (event) => {
+    if (event.key === RAIL_COLLAPSED_KEY) listener();
+  };
+  globalThis.addEventListener?.("storage", onStorage);
+  return () => {
+    listeners.delete(listener);
+    globalThis.removeEventListener?.("storage", onStorage);
+  };
+}
+function useRailCollapsed() {
+  const collapsed = useSyncExternalStore(subscribe, readCollapsed, () => false);
+  const set = (next) => {
+    try {
+      globalThis.localStorage?.setItem(RAIL_COLLAPSED_KEY, next ? "1" : "0");
+    } catch {
+    }
+    for (const listener of listeners) listener();
+  };
+  return [collapsed, set];
+}
+function formatCount(count) {
+  return count > 999 ? "999+" : String(count);
+}
+function SpaceItem({
+  space,
+  active,
+  collapsed,
+  source
+}) {
+  const Icon = space.icon;
+  const count = space.count ?? 0;
+  const menu = source.spaceMenu;
+  return /* @__PURE__ */ jsx(MessengerContextMenu, { entries: menu ? () => menu(space) : void 0, children: /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: "button",
+      onClick: () => source.onSelectSpace(space.id),
+      "aria-current": active ? "page" : void 0,
+      "aria-label": collapsed ? space.label : void 0,
+      title: collapsed ? space.label : void 0,
+      "data-space-id": space.id,
+      className: cn(
+        "relative flex w-full min-w-0 items-center rounded-lg text-[14px] text-foreground transition-colors",
+        collapsed ? "h-10 justify-center" : "h-8 gap-2.5 px-2",
+        active ? "bg-accent font-medium" : "hover:bg-accent/60"
+      ),
+      children: [
+        /* @__PURE__ */ jsx(Icon, { className: "h-5 w-5 shrink-0", strokeWidth: 1.75 }),
+        collapsed ? count > 0 ? /* @__PURE__ */ jsx("span", { className: "absolute right-0.5 top-0.5 min-w-4 rounded-full bg-primary px-1 text-center text-[10px] font-semibold leading-4 text-primary-foreground", children: formatCount(count) }) : null : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: space.label }),
+          count > 0 ? /* @__PURE__ */ jsx("span", { className: "shrink-0 text-[13px] tabular-nums text-muted-foreground", children: formatCount(count) }) : null
+        ] })
+      ]
+    }
+  ) });
+}
+function Group({
+  entry,
+  collapsed,
+  source
+}) {
+  const [open, setOpen] = useState(entry.defaultOpen ?? true);
+  if (collapsed) {
+    return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-0.5", "data-space-group": entry.id, children: [
+      /* @__PURE__ */ jsx("div", { className: "mx-auto my-1.5 h-px w-6 bg-border" }),
+      entry.spaces.map((space) => /* @__PURE__ */ jsx(SpaceItem, { space, active: source.activeSpaceId === space.id, collapsed: true, source }, space.id))
+    ] });
+  }
+  const Chevron = open ? ChevronDown : ChevronRight;
+  return /* @__PURE__ */ jsxs("div", { className: "mt-3 flex flex-col gap-0.5", "data-space-group": entry.id, children: [
+    /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        onClick: () => setOpen(!open),
+        "aria-expanded": open,
+        className: "flex h-7 w-full items-center justify-between rounded-md px-2 text-[12px] font-medium text-muted-foreground hover:text-foreground",
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate", children: entry.label }),
+          /* @__PURE__ */ jsx(Chevron, { className: "h-3.5 w-3.5 shrink-0" })
+        ]
+      }
+    ),
+    open ? entry.spaces.map((space) => /* @__PURE__ */ jsx(SpaceItem, { space, active: source.activeSpaceId === space.id, collapsed: false, source }, space.id)) : null
+  ] });
+}
+function Profile({ profile, collapsed }) {
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: "button",
+      onClick: profile.onSelect,
+      disabled: profile.onSelect === void 0,
+      title: collapsed ? profile.name : void 0,
+      className: cn(
+        "flex min-w-0 items-center rounded-lg text-[14px] font-medium text-foreground enabled:hover:bg-accent/60",
+        collapsed ? "h-10 w-full justify-center" : "h-10 w-full gap-2.5 px-1.5"
+      ),
+      children: [
+        /* @__PURE__ */ jsx(MessengerAvatar, { name: profile.name, avatar: profile.avatar, size: "rail" }),
+        collapsed ? null : /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: profile.name })
+      ]
+    }
+  );
+}
+function MessengerRail({
+  source,
+  className,
+  forceCollapsed = false
+}) {
+  const [remembered, setCollapsed] = useRailCollapsed();
+  const collapsed = forceCollapsed || remembered;
+  const Toggle = collapsed ? PanelLeftOpen : PanelLeftClose;
+  return /* @__PURE__ */ jsxs(
+    "nav",
+    {
+      "aria-label": "Spaces",
+      "data-collapsed": collapsed ? "true" : "false",
+      className: cn(
+        "flex h-full shrink-0 flex-col border-r border-border bg-muted/40 py-2 transition-[width] duration-150",
+        collapsed ? "w-16 px-2" : "w-36 px-2",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto overflow-x-hidden", children: source.rail.map(
+          (entry) => isSpaceGroup(entry) ? /* @__PURE__ */ jsx(Group, { entry, collapsed, source }, entry.id) : /* @__PURE__ */ jsx(
+            SpaceItem,
+            {
+              space: entry,
+              active: source.activeSpaceId === entry.id,
+              collapsed,
+              source
+            },
+            entry.id
+          )
+        ) }),
+        /* @__PURE__ */ jsxs("div", { className: "mt-2 flex shrink-0 flex-col gap-1", children: [
+          source.profile ? /* @__PURE__ */ jsx(Profile, { profile: source.profile, collapsed }) : null,
+          forceCollapsed ? null : /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              onClick: () => setCollapsed(!collapsed),
+              "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar",
+              title: collapsed ? "Expand" : "Collapse",
+              "aria-pressed": collapsed,
+              className: cn(
+                "flex h-8 items-center rounded-lg text-muted-foreground hover:bg-accent/60 hover:text-foreground",
+                collapsed ? "w-full justify-center" : "w-8 justify-center"
+              ),
+              children: /* @__PURE__ */ jsx(Toggle, { className: "h-4 w-4", strokeWidth: 1.75 })
+            }
+          )
+        ] })
+      ]
+    }
+  );
+}
+export {
+  MessengerRail,
+  RAIL_COLLAPSED_KEY,
+  useRailCollapsed
+};

package/dist/messenger/MessengerShell.d.ts

@@ -0,0 +1,6 @@
+import { type MessengerSource } from "./contract.js";
+export interface MessengerShellProps {
+    readonly source: MessengerSource;
+    readonly className?: string;
+}
+export declare function MessengerShell({ source, className }: MessengerShellProps): import("react").JSX.Element;

package/dist/messenger/MessengerShell.js

@@ -0,0 +1,115 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useState, useSyncExternalStore } from "react";
+import { MessageCircle, X } from "lucide-react";
+import { cn } from "@ai-matrx/design-system/cn";
+import { visibleContacts } from "./contract.js";
+import { MessengerContactList } from "./MessengerContactList.js";
+import { MessengerRail } from "./MessengerRail.js";
+import { MessengerThreadHeader } from "./MessengerThreadHeader.js";
+const NARROW = "(max-width: 767px)";
+function useNarrow() {
+  return useSyncExternalStore(
+    (listener) => {
+      const query = globalThis.matchMedia?.(NARROW);
+      query?.addEventListener?.("change", listener);
+      return () => query?.removeEventListener?.("change", listener);
+    },
+    () => globalThis.matchMedia?.(NARROW)?.matches ?? false,
+    () => false
+  );
+}
+function MessengerShell({ source, className }) {
+  const [query, setQuery] = useState("");
+  const [filterId, setFilterId] = useState(null);
+  const [detailsOpen, setDetailsOpen] = useState(false);
+  const [pane, setPane] = useState(source.activeContactId !== null ? "thread" : "list");
+  const narrow = useNarrow();
+  const filter = source.filters?.find((f) => f.id === filterId) ?? null;
+  const contacts = useMemo(() => visibleContacts(source.contacts, query, filter), [source.contacts, query, filter]);
+  const active = source.contacts.find((c) => c.id === source.activeContactId) ?? null;
+  const showThread = pane === "thread" && active !== null;
+  const shellSource = useMemo(
+    () => ({
+      ...source,
+      onSelectContact: (id) => {
+        source.onSelectContact(id);
+        setPane("thread");
+      }
+    }),
+    [source]
+  );
+  const renderDetails = source.renderDetails;
+  const toggleDetails = renderDetails ? () => setDetailsOpen((open) => !open) : null;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn("relative flex h-full min-h-0 w-full min-w-0 overflow-hidden bg-background text-foreground", className),
+      "data-messenger-shell": true,
+      "data-pane": showThread ? "thread" : "list",
+      children: [
+        /* @__PURE__ */ jsx(MessengerRail, { source: shellSource, forceCollapsed: narrow, className: cn(showThread && "max-md:hidden") }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              "flex min-h-0 w-[320px] min-w-0 shrink-0 border-r border-border max-md:w-auto max-md:flex-1",
+              showThread && "max-md:hidden"
+            ),
+            children: /* @__PURE__ */ jsx(
+              MessengerContactList,
+              {
+                source: shellSource,
+                contacts,
+                query,
+                onQueryChange: setQuery,
+                activeFilter: filter,
+                onFilterChange: setFilterId
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx("main", { className: cn("flex min-h-0 min-w-0 flex-1 flex-col", !showThread && "max-md:hidden"), "aria-label": "Conversation", children: active ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(
+            MessengerThreadHeader,
+            {
+              source,
+              contact: active,
+              detailsOpen,
+              onToggleDetails: toggleDetails,
+              onBack: () => setPane("list")
+            }
+          ),
+          /* @__PURE__ */ jsx("div", { className: "flex min-h-0 min-w-0 flex-1 flex-col", "data-messenger-thread": true, children: source.renderThread(active) }, active.id)
+        ] }) : source.renderEmpty?.() ?? /* @__PURE__ */ jsxs("div", { className: "flex flex-1 flex-col items-center justify-center gap-3 bg-muted/30 text-muted-foreground", children: [
+          /* @__PURE__ */ jsx(MessageCircle, { className: "h-10 w-10", strokeWidth: 1.25 }),
+          /* @__PURE__ */ jsx("span", { className: "text-[14px]", children: "Pick a conversation" })
+        ] }) }),
+        active && renderDetails && detailsOpen ? /* @__PURE__ */ jsxs(
+          "aside",
+          {
+            "aria-label": "Details",
+            className: "relative flex min-h-0 w-80 shrink-0 flex-col border-l border-border bg-card max-lg:absolute max-lg:inset-y-0 max-lg:right-0 max-lg:z-20 max-lg:shadow-xl max-md:w-full",
+            "data-messenger-details": true,
+            children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  onClick: () => setDetailsOpen(false),
+                  "aria-label": "Close details",
+                  className: "absolute right-3 top-3 z-10 flex h-8 w-8 items-center justify-center rounded-full border border-border bg-card text-muted-foreground hover:text-foreground",
+                  children: /* @__PURE__ */ jsx(X, { className: "h-4 w-4" })
+                }
+              ),
+              renderDetails(active)
+            ]
+          }
+        ) : null
+      ]
+    }
+  );
+}
+export {
+  MessengerShell
+};

package/dist/messenger/MessengerThreadHeader.d.ts

@@ -0,0 +1,8 @@
+import type { MessengerContact, MessengerSource } from "./contract.js";
+export declare function MessengerThreadHeader({ source, contact, detailsOpen, onToggleDetails, onBack, }: {
+    source: MessengerSource;
+    contact: MessengerContact;
+    detailsOpen: boolean;
+    onToggleDetails: (() => void) | null;
+    onBack: () => void;
+}): import("react").JSX.Element;

package/dist/messenger/MessengerThreadHeader.js

@@ -0,0 +1,62 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ChevronDown, ChevronLeft, MoreVertical, PanelRight } from "lucide-react";
+import { cn } from "@ai-matrx/design-system/cn";
+import { MessengerAvatar } from "./MessengerAvatar.js";
+import { MessengerContextMenu, MessengerDropdownMenu } from "./MessengerMenu.js";
+const ICON_BUTTON = "flex h-9 w-9 shrink-0 items-center justify-center rounded-full text-muted-foreground hover:bg-accent hover:text-foreground";
+function MessengerThreadHeader({
+  source,
+  contact,
+  detailsOpen,
+  onToggleDetails,
+  onBack
+}) {
+  const info = source.header(contact);
+  const headerMenu = source.headerMenu;
+  const titleMenu = source.titleMenu;
+  const titleBlock = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 items-center gap-1", children: [
+      /* @__PURE__ */ jsx("span", { className: "truncate text-[15px] font-semibold text-foreground", "data-header-title": true, children: info.title }),
+      titleMenu ? /* @__PURE__ */ jsx(ChevronDown, { className: "h-4 w-4 shrink-0 text-muted-foreground" }) : null
+    ] }),
+    info.subtitle ? /* @__PURE__ */ jsx("span", { className: "truncate text-[13px] text-muted-foreground", children: info.subtitle }) : null
+  ] });
+  const titleClass = "flex min-w-0 flex-col items-start justify-center rounded-md px-1 py-0.5 text-left leading-tight hover:bg-accent/60";
+  return /* @__PURE__ */ jsx(MessengerContextMenu, { entries: headerMenu ? () => headerMenu(contact) : void 0, children: /* @__PURE__ */ jsxs("header", { className: "flex h-14 w-full min-w-0 shrink-0 items-center gap-2 border-b border-border bg-card px-3", children: [
+    /* @__PURE__ */ jsx("button", { type: "button", onClick: onBack, "aria-label": "Back", className: cn(ICON_BUTTON, "-ml-1 md:hidden"), children: /* @__PURE__ */ jsx(ChevronLeft, { className: "h-5 w-5" }) }),
+    /* @__PURE__ */ jsx(MessengerAvatar, { name: info.title, avatar: info.avatar ?? contact.avatar, size: "header" }),
+    /* @__PURE__ */ jsx("div", { className: "flex min-w-0 flex-1 items-center", children: titleMenu ? /* @__PURE__ */ jsx(
+      MessengerDropdownMenu,
+      {
+        align: "start",
+        entries: () => titleMenu(contact),
+        trigger: /* @__PURE__ */ jsx("button", { type: "button", className: titleClass, "aria-label": `${info.title}, switch`, children: titleBlock })
+      }
+    ) : onToggleDetails ? /* @__PURE__ */ jsx("button", { type: "button", className: titleClass, onClick: onToggleDetails, children: titleBlock }) : /* @__PURE__ */ jsx("div", { className: "flex min-w-0 flex-col justify-center px-1 leading-tight", children: titleBlock }) }),
+    /* @__PURE__ */ jsxs("div", { className: "flex shrink-0 items-center gap-0.5", children: [
+      source.headerActions?.(contact),
+      onToggleDetails ? /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          onClick: onToggleDetails,
+          "aria-label": detailsOpen ? "Hide details" : "Show details",
+          "aria-pressed": detailsOpen,
+          className: cn(ICON_BUTTON, detailsOpen && "bg-accent text-foreground"),
+          children: /* @__PURE__ */ jsx(PanelRight, { className: "h-[18px] w-[18px]", strokeWidth: 1.75 })
+        }
+      ) : null,
+      headerMenu ? /* @__PURE__ */ jsx(
+        MessengerDropdownMenu,
+        {
+          entries: () => headerMenu(contact),
+          trigger: /* @__PURE__ */ jsx("button", { type: "button", "aria-label": "Conversation menu", className: ICON_BUTTON, children: /* @__PURE__ */ jsx(MoreVertical, { className: "h-[18px] w-[18px]" }) })
+        }
+      ) : null
+    ] })
+  ] }) });
+}
+export {
+  MessengerThreadHeader
+};

package/dist/messenger/contract.d.ts

@@ -0,0 +1,149 @@
+/**
+ * THE MESSENGER SOURCE CONTRACT — what a data source hands `<MessengerShell>`.
+ *
+ * The shell is chrome only: a rail of spaces, a contact list, a thread header,
+ * an optional details panel and the right-click menus. It never renders a
+ * message, a bubble or a composer. Everything a person reads or writes comes
+ * from the SOURCE (`renderThread`), so the people source mounts
+ * `@ai-matrx/messaging`'s `ConversationView` and the agents source mounts this
+ * package's own chat room — one renderer each, never a third.
+ *
+ * Search and filter chips are applied by the shell over `contacts`
+ * (`matchesQuery` / `MessengerFilter.test`), so a source only lists its rows.
+ * Every menu is the source's: each use case supplies options about the item
+ * that was clicked, and the shell renders them with the design system's
+ * context-menu and dropdown-menu primitives.
+ */
+import type { ComponentType, ReactNode } from "react";
+/** Any icon component (lucide-react and @ai-matrx/icons both fit). */
+export type MessengerIcon = ComponentType<{
+    className?: string;
+    strokeWidth?: number;
+}>;
+/** What a round avatar shows. A monogram with no `text` uses the name's initials. */
+export type MessengerAvatar = {
+    readonly kind: "image";
+    readonly src: string;
+} | {
+    readonly kind: "emoji";
+    readonly emoji: string;
+} | {
+    readonly kind: "icon";
+    readonly icon: MessengerIcon;
+} | {
+    readonly kind: "monogram";
+    readonly text?: string;
+};
+export interface MessengerMenuAction {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: MessengerIcon;
+    readonly onSelect: () => void;
+    readonly destructive?: boolean;
+    readonly disabled?: boolean;
+}
+export interface MessengerMenuSeparator {
+    readonly id: string;
+    readonly separator: true;
+}
+export type MessengerMenuEntry = MessengerMenuAction | MessengerMenuSeparator;
+export declare function isMenuSeparator(entry: MessengerMenuEntry): entry is MessengerMenuSeparator;
+/** One top-level rail item (WhatsApp's Chats, Calls, Starred…). */
+export interface MessengerSpace {
+    readonly id: string;
+    readonly label: string;
+    readonly icon: MessengerIcon;
+    /** Shown beside the label (or as a badge when collapsed). 0 and undefined draw nothing. */
+    readonly count?: number;
+}
+/** A collapsible group of spaces (WhatsApp's "More" and "Communities"). */
+export interface MessengerSpaceGroup {
+    readonly id: string;
+    readonly label: string;
+    readonly spaces: readonly MessengerSpace[];
+    readonly defaultOpen?: boolean;
+}
+export type MessengerRailEntry = MessengerSpace | MessengerSpaceGroup;
+export declare function isSpaceGroup(entry: MessengerRailEntry): entry is MessengerSpaceGroup;
+/** One row in the contact list. Every field but `id` and `name` is optional chrome. */
+export interface MessengerContact {
+    readonly id: string;
+    readonly name: string;
+    readonly avatar?: MessengerAvatar;
+    /** Already formatted for the row ("11:24 AM", "Yesterday"). */
+    readonly time?: string;
+    readonly preview?: string;
+    readonly unread?: number;
+    readonly pinned?: boolean;
+    readonly muted?: boolean;
+    /** An unsent draft; the row shows "Draft:" and this text instead of the preview. */
+    readonly draft?: string;
+    /** Extra text the search matches (an email, a handle). Never drawn. */
+    readonly searchText?: string;
+}
+/** A filter chip under the search ("All", "Unread", "Groups"). */
+export interface MessengerFilter {
+    readonly id: string;
+    readonly label: string;
+    readonly test: (contact: MessengerContact) => boolean;
+}
+export interface MessengerHeaderInfo {
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly avatar?: MessengerAvatar;
+}
+export interface MessengerProfile {
+    readonly name: string;
+    readonly avatar?: MessengerAvatar;
+    readonly onSelect?: () => void;
+}
+export interface MessengerListState {
+    readonly loading?: boolean;
+    readonly error?: string | null;
+    readonly retry?: () => void;
+    readonly hasMore?: boolean;
+    readonly loadMore?: () => void;
+    /** Words for an empty list ("No chats yet"). */
+    readonly emptyLabel?: string;
+}
+export interface MessengerSource {
+    /** The list title ("Chats"). */
+    readonly title: string;
+    readonly rail: readonly MessengerRailEntry[];
+    readonly activeSpaceId: string | null;
+    readonly onSelectSpace: (spaceId: string) => void;
+    readonly spaceMenu?: (space: MessengerSpace) => readonly MessengerMenuEntry[];
+    readonly profile?: MessengerProfile;
+    readonly contacts: readonly MessengerContact[];
+    readonly listState?: MessengerListState;
+    readonly filters?: readonly MessengerFilter[];
+    readonly activeContactId: string | null;
+    readonly onSelectContact: (contactId: string) => void;
+    readonly contactMenu?: (contact: MessengerContact) => readonly MessengerMenuEntry[];
+    /** The title row's "⋯" menu. */
+    readonly listMenu?: () => readonly MessengerMenuEntry[];
+    /** The title row's "+" button. Absent: no button. */
+    readonly onNew?: () => void;
+    readonly newLabel?: string;
+    readonly header: (contact: MessengerContact) => MessengerHeaderInfo;
+    /** Right-click and "⋯" on the thread header. */
+    readonly headerMenu?: (contact: MessengerContact) => readonly MessengerMenuEntry[];
+    /**
+     * A dropdown under the header title (past threads + "New chat" for an agent).
+     * Present: the title opens it. Absent: the title opens the details panel.
+     */
+    readonly titleMenu?: (contact: MessengerContact) => readonly MessengerMenuEntry[];
+    readonly headerActions?: (contact: MessengerContact) => ReactNode;
+    /** The thread body. The source's own renderer; the shell draws nothing inside it. */
+    readonly renderThread: (contact: MessengerContact) => ReactNode;
+    /** The right-hand details panel. Absent: no panel and no toggle. */
+    readonly renderDetails?: (contact: MessengerContact) => ReactNode;
+    /** What the thread area shows with no contact selected. */
+    readonly renderEmpty?: () => ReactNode;
+}
+/** The shell's search: case-insensitive over name, preview and `searchText`. */
+export declare function matchesQuery(contact: MessengerContact, query: string): boolean;
+/** The rows the list draws: the active filter chip, then the search. */
+export declare function visibleContacts(contacts: readonly MessengerContact[], query: string, filter: MessengerFilter | null): readonly MessengerContact[];
+/** Two-letter initials for a monogram avatar. */
+export declare function initialsOf(name: string): string;

package/dist/messenger/contract.js

@@ -0,0 +1,28 @@
+function isMenuSeparator(entry) {
+  return "separator" in entry && entry.separator === true;
+}
+function isSpaceGroup(entry) {
+  return "spaces" in entry;
+}
+function matchesQuery(contact, query) {
+  const q = query.trim().toLowerCase();
+  if (q === "") return true;
+  return [contact.name, contact.preview, contact.searchText].some((text) => text !== void 0 && text.toLowerCase().includes(q));
+}
+function visibleContacts(contacts, query, filter) {
+  return contacts.filter((c) => (filter === null || filter.test(c)) && matchesQuery(c, query));
+}
+function initialsOf(name) {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return "?";
+  const first = words[0].charAt(0);
+  const last = words.length > 1 ? words[words.length - 1].charAt(0) : "";
+  return `${first}${last}`.toUpperCase();
+}
+export {
+  initialsOf,
+  isMenuSeparator,
+  isSpaceGroup,
+  matchesQuery,
+  visibleContacts
+};

package/dist/messenger/people/format-time.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A row's time, the desktop-messenger way: today → "11:24 AM", yesterday →
+ * "Yesterday", this week → the weekday, older → the short date. Pure; `now`
+ * is injectable for tests.
+ */
+export declare function formatMessengerTime(iso: string | null, now?: Date): string | undefined;

package/dist/messenger/people/format-time.js

@@ -0,0 +1,14 @@
+function formatMessengerTime(iso, now = /* @__PURE__ */ new Date()) {
+  if (iso === null) return void 0;
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return void 0;
+  const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+  const days = Math.round((startOfDay(now) - startOfDay(at)) / 864e5);
+  if (days <= 0) return at.toLocaleTimeString(void 0, { hour: "numeric", minute: "2-digit" });
+  if (days === 1) return "Yesterday";
+  if (days < 7) return at.toLocaleDateString(void 0, { weekday: "long" });
+  return at.toLocaleDateString(void 0, { month: "numeric", day: "numeric", year: "2-digit" });
+}
+export {
+  formatMessengerTime
+};

package/dist/messenger/people/usePeopleMessengerSource.d.ts

@@ -0,0 +1,35 @@
+/**
+ * THE PEOPLE SOURCE — `@ai-matrx/messaging` conversations as a MessengerSource.
+ *
+ * Everything real is messaging's: the inbox (useConversations), the People /
+ * Agents and archive axes (server requests, never client sieves), presence,
+ * mark-read, and the thread body, which is messaging's own `ConversationView`
+ * (`showHeader={false}`, `appearance="messenger"`) — rich content, references,
+ * actions, typing and the composer are never re-implemented here.
+ *
+ * Needs a `<MessagingProvider>` above it (a host mounts one app-wide).
+ * Only this subpath imports `@ai-matrx/messaging`; the build is per-file, so a
+ * chat host that never mounts the messenger loads none of it.
+ */
+import { type ReactNode } from "react";
+import { type ConversationId, type ConversationSummary } from "@ai-matrx/messaging/react";
+import type { MessengerMenuEntry, MessengerProfile, MessengerSource } from "../contract.js";
+export interface PeopleMessengerOptions {
+    /** The list title. Default "Chats". */
+    readonly title?: string;
+    readonly profile?: MessengerProfile;
+    /** The "+" button (the host's new-conversation dialog). */
+    readonly onNewConversation?: () => void;
+    /** Conversation ids the host keeps pinned, in order. With `onTogglePin`, rows get Pin/Unpin. */
+    readonly pinnedConversationIds?: readonly string[];
+    readonly onTogglePin?: (conversationId: string) => void;
+    /**
+     * The thread body. Default: messaging's `ConversationView` with the messenger
+     * appearance. A host that wraps that SAME view in its own chrome (its
+     * right-click menu, its composer field) passes it here — never a second renderer.
+     */
+    readonly renderConversation?: (conversationId: ConversationId) => ReactNode;
+    /** Host-specific options appended to every conversation menu. */
+    readonly conversationMenuExtras?: (summary: ConversationSummary) => readonly MessengerMenuEntry[];
+}
+export declare function usePeopleMessengerSource(options?: PeopleMessengerOptions): MessengerSource;