@ai-matrx/messaging 0.0.0 → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,1273 @@
+import { ReactNode, SVGProps } from 'react';
+import { MatrxTransport } from '@ai-matrx/agents/matrx';
+import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
+
+/**
+ * THE MESSAGING DOMAIN TYPES.
+ *
+ * Ported from `matrx-frontend/features/messaging/types.ts` with the coupling
+ * seams inverted: no imported host types, no app singletons. The DB-shaped
+ * types mirror `communication.dm_*` exactly (snake_case, nullable where the
+ * column is nullable) so a row read from PostgREST IS one of these without a
+ * mapping step that can silently drop a column.
+ *
+ * Strictness posture (C22): identity-bearing values are BRANDED, invalid states
+ * are unrepresentable (a `sending` message has a `clientMessageId`; a `failed`
+ * one carries a reason), and no surface here is `any`. The one honest `unknown`
+ * 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;
+type Brand<T, B extends string> = T & {
+    readonly [brand]: B;
+};
+type ConversationId = Brand<string, "ConversationId">;
+type MessageId = Brand<string, "MessageId">;
+type UserId = Brand<string, "UserId">;
+type OrganizationId = Brand<string, "OrganizationId">;
+/** The client-minted idempotency key that makes a send exactly-once end to end. */
+type ClientMessageId = Brand<string, "ClientMessageId">;
+declare const asConversationId: (value: string) => ConversationId;
+declare const asMessageId: (value: string) => MessageId;
+declare const asUserId: (value: string) => UserId;
+declare const asOrganizationId: (value: string) => OrganizationId;
+declare const asClientMessageId: (value: string) => ClientMessageId;
+type JsonValue = unknown;
+type JsonObject = Readonly<Record<string, JsonValue>>;
+type ConversationType = "direct" | "group" | "org";
+type ParticipantRole = "owner" | "admin" | "member";
+type MessageKind = "text" | "image" | "video" | "audio" | "file" | "system" | "action";
+/**
+ * The delivery ladder. `sending` and `failed` exist only client-side: they are
+ * the outbox's states, and the DB's `status` column never holds them.
+ */
+type DeliveryState = "sending" | "sent" | "delivered" | "read" | "failed";
+interface Conversation {
+    readonly id: ConversationId;
+    readonly type: ConversationType;
+    readonly groupName: string | null;
+    readonly groupImageUrl: string | null;
+    readonly createdBy: UserId | null;
+    readonly organizationId: OrganizationId;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly metadata: JsonObject;
+}
+interface Participant {
+    readonly conversationId: ConversationId;
+    readonly userId: UserId;
+    readonly role: ParticipantRole;
+    readonly joinedAt: string | null;
+    readonly lastReadAt: string | null;
+    readonly isMuted: boolean;
+    readonly isArchived: boolean;
+}
+interface UserSummary {
+    readonly userId: UserId;
+    readonly displayName: string;
+    readonly email: string | null;
+    readonly avatarUrl: string | null;
+    /** True when this participant is an AI agent rather than a person (R4). */
+    readonly isAgent: boolean;
+}
+/**
+ * A structured action carried by a message. THE SEAM other packages extend —
+ * `@ai-matrx/meet` puts a call invitation here rather than inventing a message
+ * type (D1).
+ *
+ * `version` is not decoration: a renderer that does not understand a version
+ * renders NOTHING rather than guessing, which is what lets a new sender ship
+ * before every reader has caught up.
+ */
+interface MessageAction<TKind extends string = string, TPayload = JsonObject> {
+    readonly kind: TKind;
+    readonly version: number;
+    readonly payload: TPayload;
+}
+/**
+ * A typed reference to a platform entity, rendered as a live openable card.
+ * NO DEAD ENDS: everything a message names must open, so a reference always
+ * carries enough to resolve — never a bare label.
+ */
+interface MatrxReference {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly label: string;
+    readonly href?: string | undefined;
+}
+interface Attachment {
+    /** A DURABLE file ref, never a signed URL. Signed URLs expire; identities do not. */
+    readonly fileId: string;
+    readonly fileName: string;
+    readonly mimeType: string | null;
+    readonly sizeBytes: number | null;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+interface Message {
+    readonly id: MessageId;
+    readonly conversationId: ConversationId;
+    readonly senderId: UserId;
+    readonly organizationId: OrganizationId;
+    readonly content: string;
+    readonly kind: MessageKind;
+    readonly deliveryState: DeliveryState;
+    readonly replyToId: MessageId | null;
+    readonly clientMessageId: ClientMessageId | null;
+    readonly createdAt: string;
+    readonly editedAt: string | null;
+    readonly deletedAt: string | null;
+    readonly deletedForEveryone: boolean;
+    readonly action: MessageAction | null;
+    readonly attachments: readonly Attachment[];
+    readonly references: readonly MatrxReference[];
+    readonly metadata: JsonObject;
+    /** Set only while this message is in the outbox and its last send failed. */
+    readonly failureReason?: string | undefined;
+}
+interface ConversationSummary {
+    readonly conversation: Conversation;
+    readonly participants: readonly UserSummary[];
+    readonly lastMessageContent: string | null;
+    readonly lastMessageSenderId: UserId | null;
+    readonly lastMessageAt: string | null;
+    readonly unreadCount: number;
+    readonly isMuted: boolean;
+    readonly isArchived: boolean;
+    /** Resolved for display: the group name, or the other participant's name. */
+    readonly displayName: string;
+    readonly displayImageUrl: string | null;
+    /** The keyset sort value. Pagination cursors are built from this + `id`. */
+    readonly sortAt: string;
+}
+/**
+ * THE PAGINATION CURSOR. Stable ordering is terminated by a UNIQUE column
+ * (R5 scale honesty): ordering by a timestamp alone silently duplicates or
+ * skips rows whenever two rows share a millisecond, which in a large org is
+ * every page.
+ */
+interface ConversationCursor {
+    readonly beforeSortAt: string;
+    readonly beforeConversationId: ConversationId;
+}
+interface MessageCursor {
+    readonly beforeCreatedAt: string;
+    readonly beforeMessageId: MessageId;
+}
+interface Page<TItem, TCursor> {
+    readonly items: readonly TItem[];
+    readonly nextCursor: TCursor | null;
+    readonly hasMore: boolean;
+}
+/** What the host injects. Identity ONLY — every hard part is in the package. */
+interface MessagingIdentity {
+    readonly userId: UserId;
+    readonly organizationId: OrganizationId;
+}
+interface DraftMessage {
+    readonly conversationId: ConversationId;
+    readonly content: string;
+    readonly kind?: MessageKind | undefined;
+    readonly replyToId?: MessageId | undefined;
+    readonly action?: MessageAction | undefined;
+    readonly attachments?: readonly Attachment[] | undefined;
+    readonly references?: readonly MatrxReference[] | undefined;
+    readonly metadata?: JsonObject | undefined;
+}
+
+/**
+ * ACTIONABLE MESSAGES — a message that carries something you can DO.
+ *
+ * A registry, never a `switch`. Two properties come from that choice, and both
+ * are load-bearing:
+ *
+ * - **Forward compatibility.** An unknown `kind` — or a known kind at a version
+ *   this build does not understand — renders NOTHING and executes nothing. A
+ *   `switch` with a `default: throw` means the day a new sender ships, every
+ *   older reader's thread breaks. Silently rendering an unknown payload with a
+ *   generic button is worse: it offers an action nobody can honor.
+ * - **Extensibility across packages.** `@ai-matrx/meet` registers its call
+ *   invitation here rather than this package learning about meetings (D1).
+ *
+ * 🚨 **IDEMPOTENCE IS ENFORCED HERE, NOT PROMISED BY HANDLERS.** Two tabs, a
+ * double-click, and a retried tap must apply an action ONCE. The registry
+ * de-duplicates by `(kind, messageId, actorId)`: a second execution while the
+ * first is in flight AWAITS it and returns the same receipt, and a settled
+ * action returns its stored receipt without touching the server.
+ *
+ * 🚨 **THE PAYLOAD IS NOT AUTHORIZATION.** A handler must re-resolve the
+ * durable, caller-authorized request row server-side before it writes. The
+ * message's `action_data` says what was ASKED, never what is ALLOWED — trusting
+ * it turns any message into a privilege grant. Handlers declare this by
+ * construction: they receive the payload and the actor, and must go to the
+ * database themselves.
+ */
+
+type ActionOutcome = "applied" | "already" | "declined" | "unavailable";
+interface ActionReceipt {
+    readonly kind: string;
+    readonly messageId: MessageId;
+    readonly actorId: UserId;
+    readonly outcome: ActionOutcome;
+    readonly label: string;
+    readonly settledAt: string;
+    readonly detail?: string | undefined;
+}
+interface ActionContext {
+    readonly messageId: MessageId;
+    readonly actorId: UserId;
+    readonly organizationId: string;
+    /** Which of the choices the user picked, e.g. `approve` / `decline`. */
+    readonly choice: string;
+}
+interface ActionChoice {
+    readonly id: string;
+    readonly label: string;
+    readonly tone: "primary" | "neutral" | "danger";
+}
+interface ActionHandler<TPayload = JsonObject> {
+    readonly kind: string;
+    /** Versions this build understands. An unlisted version renders nothing. */
+    readonly versions: readonly number[];
+    /** What the chips say. Return `[]` to render the action as read-only. */
+    choices: (payload: TPayload) => readonly ActionChoice[];
+    /** One-line summary for the inbox preview and notifications. */
+    summarize?: (payload: TPayload) => string;
+    /**
+     * Do the thing. MUST re-resolve the authorizing row server-side; the payload
+     * is the request, not the permission. Returning `already` is how a handler
+     * reports that the server had settled it — the registry treats it as success.
+     */
+    execute: (payload: TPayload, context: ActionContext) => Promise<ActionReceipt>;
+}
+interface ActionRegistry {
+    register<TPayload = JsonObject>(handler: ActionHandler<TPayload>): void;
+    /** The handler for an action, or null when this build cannot honor it. */
+    resolve(action: MessageAction): ActionHandler | null;
+    choicesFor(action: MessageAction): readonly ActionChoice[];
+    summarize(action: MessageAction): string | null;
+    /** Idempotent execution. Concurrent callers share one in-flight result. */
+    execute(action: MessageAction, context: ActionContext): Promise<ActionReceipt>;
+    /** The stored receipt for a settled action, if there is one. */
+    receiptFor(kind: string, messageId: MessageId, actorId: UserId): ActionReceipt | null;
+    /** Record a receipt observed from another client's broadcast. */
+    observeReceipt(receipt: ActionReceipt): void;
+    known(): readonly string[];
+}
+declare function createActionRegistry(): ActionRegistry;
+
+/**
+ * AI-NATIVE, OUT OF THE BOX (R4).
+ *
+ * Four conversation intelligences — catch me up, summarize, extract action
+ * items, draft a reply — plus agents as participants. All of it executes on the
+ * platform's agent system through `@ai-matrx/agents`; this package never talks
+ * to a model, never holds a prompt, and never carries an agent definition.
+ *
+ * 🚨 **THE USER-INPUT LAW.** `user_input` is what a HUMAN typed. Machine
+ * content — a transcript, a participant roster, a cutoff timestamp — travels as
+ * NAMED VARIABLES. This is not style: the server treats `user_input` as the
+ * turn's human utterance (it is stored as such, shown as such, and shapes the
+ * agent's framing), so smuggling a transcript through it silently corrupts
+ * every conversation it touches. Every call below sends `variables` and either
+ * a short human-shaped `user_input` or none.
+ *
+ * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes agent IDs as
+ * injected identity. When an id is not configured the capability reports
+ * `unavailable` WITH the remedy — it never silently no-ops, and the UI hides
+ * the action rather than offering a dead button (no dead ends).
+ */
+
+/**
+ * Which platform agent backs each capability. Every field is a DATABASE row id
+ * supplied by the host; an omitted one disables exactly that capability.
+ */
+interface MessagingAgents {
+    readonly catchUp?: string | undefined;
+    readonly summarize?: string | undefined;
+    readonly actionItems?: string | undefined;
+    readonly draftReply?: string | undefined;
+}
+interface MessagingAiOptions {
+    transport: MatrxTransport;
+    organizationId: string;
+    agents: MessagingAgents;
+    /** Stable source slugs so server-side analytics can see where a run came from. */
+    sourceApp?: string | undefined;
+    sourceFeature?: string | undefined;
+    /** Cap on how much transcript is sent. Default 200 messages. */
+    maxTranscriptMessages?: number | undefined;
+}
+type AiCapability = keyof MessagingAgents;
+interface AiResult {
+    readonly capability: AiCapability;
+    readonly text: string;
+    readonly conversationId: string | null;
+}
+interface MessagingAi {
+    /** Which capabilities this host actually configured. Drives what the UI offers. */
+    available(): readonly AiCapability[];
+    isAvailable(capability: AiCapability): boolean;
+    catchMeUp(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        since: string | null;
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    summarize(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    extractActionItems(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    draftReply(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        /** What the human asked for, if anything — this IS a human utterance. */
+        instruction?: string | undefined;
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+}
+declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
+
+/**
+ * THE OUTBOX — a message you typed is NEVER lost (R2, table-stakes law).
+ *
+ * This is the piece hosts always get wrong, so it is entirely in the package
+ * (C22). What "never lost" actually requires, and what each part defends:
+ *
+ * - **Durability across a reload.** The draft is persisted BEFORE the network
+ *   call, not after it succeeds. A tab closed mid-send comes back with the
+ *   message still queued. The storage port has a working default; a host that
+ *   injects nothing still gets in-memory queuing, and it SAYS so rather than
+ *   pretending to be durable.
+ * - **Exactly-once on retry.** Every entry carries a client-minted
+ *   `clientMessageId` that is generated ONCE and reused by every attempt. A
+ *   retry after a response that was actually delivered is deduped by the
+ *   database's idempotency key instead of posting the message twice.
+ * - **Order.** Entries for one conversation send strictly in order; message 2
+ *   never overtakes a retrying message 1.
+ * - **Bounded, honest failure.** Attempts back off; after `maxAttempts` the
+ *   entry stays in the queue marked `failed` WITH a reason and a retry door.
+ *   It is never silently dropped, and it never retries forever.
+ */
+
+interface OutboxEntry {
+    readonly id: string;
+    readonly clientMessageId: ClientMessageId;
+    readonly draft: DraftMessage;
+    readonly queuedAt: number;
+    readonly attempts: number;
+    readonly state: "queued" | "sending" | "failed";
+    readonly failureReason: string | null;
+}
+/**
+ * Persistence for pending sends. A default is always supplied — the package
+ * never leaves a port empty (THE ALL-INCLUSIVE LAW).
+ */
+interface OutboxStorage {
+    /** Human-readable, shown in diagnostics so "durable" is never assumed. */
+    readonly name: string;
+    readonly durable: boolean;
+    load(): readonly OutboxEntry[];
+    save(entries: readonly OutboxEntry[]): void;
+}
+declare function createMemoryOutboxStorage(): OutboxStorage;
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * The real default in a browser. Falls back to memory — announcing itself —
+ * when storage is unavailable (private mode, a disabled-cookies browser, SSR).
+ */
+declare function createWebOutboxStorage(args: {
+    key?: string;
+    storage?: WebStorageLike | null;
+    onFallback?: (reason: string) => void;
+}): OutboxStorage;
+interface OutboxOptions {
+    /** Actually send. Returns the persisted message. */
+    send: (draft: DraftMessage, clientMessageId: ClientMessageId) => Promise<Message>;
+    /** Called when an entry lands. The store collapses it with the optimistic row. */
+    onSent: (entry: OutboxEntry, message: Message) => void;
+    onChange: (entries: readonly OutboxEntry[]) => void;
+    onDiagnostic?: (message: string) => void;
+    storage?: OutboxStorage;
+    maxAttempts?: number;
+    /** Backoff schedule per attempt, ms. The last value repeats. */
+    backoffMs?: readonly number[];
+    timers?: {
+        setTimeout: (run: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+        now: () => number;
+    };
+}
+interface Outbox {
+    entries(): readonly OutboxEntry[];
+    /** Queue a draft. Returns the id the optimistic message must carry. */
+    enqueue(draft: DraftMessage): ClientMessageId;
+    /** Retry one failed entry, on the user's explicit ask. */
+    retry(entryId: string): void;
+    /** Drop one entry — the only sanctioned way a typed message leaves the queue. */
+    discard(entryId: string): void;
+    /** Network came back / tab woke: try everything that is waiting. */
+    flush(): void;
+    pendingFor(conversationId: ConversationId): readonly OutboxEntry[];
+    dispose(): void;
+}
+declare function createOutbox(options: OutboxOptions): Outbox;
+
+/**
+ * THE STRUCTURAL SUPABASE SHAPE.
+ *
+ * D2 says messaging is Supabase-locked — there is no provider abstraction and
+ * never will be. That is a statement about the CONTRACT, not about the import
+ * graph: this package still accepts the client STRUCTURALLY and never imports
+ * `@supabase/supabase-js` at runtime.
+ *
+ * Two reasons, both learned the hard way across the fleet:
+ *
+ * 1. A host that ships two copies of `@supabase/supabase-js` (the Next.js
+ *    server/browser split is the usual way) would get two different `Session`
+ *    identities and a package that refuses the host's own client.
+ * 2. `supabase-js` is a heavy dependency with its own release train; a package
+ *    that pins one is a version-drift generator (THE LATEST LAW's failure mode
+ *    in miniature).
+ *
+ * `supabase-shape.test.ts` proves at COMPILE TIME that a real `SupabaseClient`
+ * satisfies these interfaces. If that file stops compiling, the interface here
+ * is wrong — fix it here, never with a cast at the call site, and never by
+ * asking the consumer to adapt.
+ */
+
+/** What PostgREST hands back. `error` is opaque on purpose — we normalize it. */
+interface PostgrestLikeResponse<T> {
+    data: T | null;
+    error: {
+        message: string;
+        code?: string;
+        details?: string | null;
+    } | null;
+}
+interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TRow[]>> {
+    eq(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    neq(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    in(column: string, values: readonly unknown[]): PostgrestFilterLike<TRow>;
+    is(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    lt(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    gt(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    or(filters: string): PostgrestFilterLike<TRow>;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): PostgrestFilterLike<TRow>;
+    limit(count: number): PostgrestFilterLike<TRow>;
+    select(columns?: string): PostgrestFilterLike<TRow>;
+    single(): PromiseLike<PostgrestLikeResponse<TRow>>;
+    maybeSingle(): PromiseLike<PostgrestLikeResponse<TRow>>;
+}
+interface PostgrestTableLike<TRow> {
+    select(columns?: string): PostgrestFilterLike<TRow>;
+    insert(values: unknown): PostgrestFilterLike<TRow>;
+    update(values: unknown): PostgrestFilterLike<TRow>;
+    upsert(values: unknown, options?: {
+        onConflict?: string;
+    }): PostgrestFilterLike<TRow>;
+    delete(): PostgrestFilterLike<TRow>;
+}
+interface SchemaLike {
+    from<TRow = Record<string, unknown>>(table: string): PostgrestTableLike<TRow>;
+    rpc<TResult = unknown>(fn: string, args?: Record<string, unknown>): PromiseLike<PostgrestLikeResponse<TResult>>;
+}
+/**
+ * The subset of the Supabase client this package uses. `schema()` matters:
+ * every messaging table lives in the `communication` schema, never `public`
+ * (the platform's canonical DB conventions, R8).
+ */
+interface SupabaseLike extends SchemaLike {
+    schema(name: string): SchemaLike;
+}
+/**
+ * What `<MessagingProvider client={...}>` actually needs: the PostgREST surface
+ * above AND the realtime surface `@ai-matrx/realtime` accepts. A real
+ * `SupabaseClient` satisfies both, which is the point — the host passes the one
+ * client it already has, and the package never casts to make it fit.
+ */
+type MessagingSupabaseClient = SupabaseLike & RealtimeClientLike;
+
+/**
+ * THE DATA CONTRACT — the ONE place a messaging table or RPC name exists.
+ *
+ * Every name below was verified against Matrx Main (`https://db.matrxserver.com`)
+ * on 2026-08-31, not guessed from a client. `matrx-dm` grew a parallel schema in
+ * its own project (`public.conversations` / `messages` / `message_reactions`);
+ * per R8 exactly ONE canonical schema survives and it is this one — the
+ * platform-conventional `communication.dm_*` tables with explicit
+ * `organization_id`, `version`, and soft-delete columns, behind auth-checked
+ * SECURITY DEFINER RPCs.
+ *
+ * Four rules hold this file together:
+ *
+ * 1. **Org is explicit on every write (R5).** Not defaulted by a trigger we
+ *    hope fires, not inherited — passed, and refused in-package when absent.
+ * 2. **Authorization is the database's job.** There is no permission branch in
+ *    this file. An RPC that says no is a `forbidden` MessagingError, never a
+ *    client-side re-decision.
+ * 3. **Direct conversations are created ATOMICALLY, by RPC.** The banned
+ *    pattern — read `find_dm_direct_conversation`, then insert — races two
+ *    tabs into two conversations for the same pair. The RPC advisory-locks the
+ *    unordered pair. Nothing here may reintroduce the read-then-insert shape.
+ * 4. **Pagination is keyset and terminated by a unique column.** Ordering by a
+ *    timestamp alone duplicates or skips rows whenever two share a millisecond
+ *    — which in a large org is every page.
+ */
+
+/** The schema. Messaging is never in `public`. */
+declare const MESSAGING_SCHEMA = "communication";
+declare const TABLES: {
+    readonly conversations: "dm_conversations";
+    readonly participants: "dm_conversation_participants";
+    readonly messages: "dm_messages";
+};
+declare const RPCS: {
+    /** Atomic direct-conversation creation. Advisory-locks the unordered pair. */
+    readonly getOrCreateDirect: "dm_get_or_create_direct_conversation";
+    /** Conversation list + participants + last message + unread, keyset paged. */
+    readonly conversationsWithDetails: "get_dm_conversations_with_details";
+    readonly unreadCount: "get_dm_unread_count";
+    readonly userInfo: "get_dm_user_info";
+    readonly isParticipant: "is_dm_participant";
+};
+/**
+ * The host's session source. A messaging read that lands between sign-in and
+ * token arrival must not become a red error — it retries ONCE after the host
+ * resolves a session, then reports `session-unavailable`.
+ */
+type SessionResolver = () => Promise<unknown>;
+interface RepositoryOptions {
+    client: SupabaseLike;
+    identity: MessagingIdentity;
+    /** Called once before a retry when a read fails with a missing session. */
+    resolveSession?: SessionResolver | undefined;
+    /** Profile-lookup cache TTL. Default 5 minutes (the frontend's proven value). */
+    userTtlMs?: number | undefined;
+    now?: (() => number) | undefined;
+}
+interface MessagingRepository {
+    readonly identity: MessagingIdentity;
+    listConversations(args?: {
+        limit?: number;
+        cursor?: ConversationCursor | null;
+    }): Promise<Page<ConversationSummary, ConversationCursor>>;
+    getConversation(id: ConversationId): Promise<Conversation>;
+    listMessages(conversationId: ConversationId, args?: {
+        limit?: number;
+        cursor?: MessageCursor | null;
+    }): Promise<Page<Message, MessageCursor>>;
+    /** Messages created strictly after `since` — the reconnect backfill read. */
+    messagesSince(conversationId: ConversationId, since: string): Promise<readonly Message[]>;
+    getOrCreateDirectConversation(otherUserId: UserId): Promise<ConversationId>;
+    createGroupConversation(args: {
+        name: string;
+        memberIds: readonly UserId[];
+    }): Promise<ConversationId>;
+    insertMessage(draft: DraftMessage, clientMessageId: ClientMessageId): Promise<Message>;
+    editMessage(id: MessageId, content: string): Promise<Message>;
+    deleteMessage(id: MessageId, forEveryone: boolean): Promise<void>;
+    markRead(conversationId: ConversationId, at?: string): Promise<void>;
+    setConversationFlags(conversationId: ConversationId, flags: {
+        isMuted?: boolean;
+        isArchived?: boolean;
+    }): Promise<void>;
+    addMembers(conversationId: ConversationId, memberIds: readonly UserId[]): Promise<void>;
+    removeMember(conversationId: ConversationId, memberId: UserId): Promise<void>;
+    setMemberRole(conversationId: ConversationId, memberId: UserId, role: ParticipantRole): Promise<void>;
+    /** Cached + in-flight-deduped. N callers for one id make ONE request. */
+    getUser(userId: UserId): Promise<UserSummary | null>;
+    getUsers(userIds: readonly UserId[]): Promise<ReadonlyMap<UserId, UserSummary>>;
+    searchMessages(args: {
+        query: string;
+        conversationId?: ConversationId | null;
+        limit?: number;
+    }): Promise<readonly Message[]>;
+    invalidateUser(userId: UserId): void;
+}
+declare function createMessagingRepository(options: RepositoryOptions): MessagingRepository;
+
+/**
+ * THE MESSAGE STORE — where "the same message twice" is made impossible.
+ *
+ * A message can reach this store by FOUR different paths, often in any order:
+ * the optimistic bubble, the insert's own response, the broadcast, and the
+ * Postgres Changes row. Every duplicate bug in every chat product is one of
+ * those four arriving out of order. The rules here, each with a regression test:
+ *
+ * 1. **Identity is `id` OR `clientMessageId`.** The confirmed row and the
+ *    optimistic bubble are the SAME message; the client-minted key is what
+ *    proves it. Matching on `(sender, content)` — the tempting shortcut — merges
+ *    two genuinely different "ok" messages into one.
+ * 2. **Merge collapses; it never appends.** A confirmed row that finds an
+ *    optimistic twin REPLACES it in place, keeping the twin's position so the
+ *    bubble does not jump.
+ * 3. **Older never overwrites newer.** An out-of-order UPDATE carrying an older
+ *    `edited_at`/`created_at` than the held copy is DROPPED. Without this an
+ *    edit visibly reverts itself a second later.
+ * 4. **Order is `created_at` then `id`.** The unique tiebreaker is not
+ *    decoration: two messages in the same millisecond otherwise swap places on
+ *    every re-render.
+ * 5. **The active conversation's unread count is forced to zero.** A stale
+ *    server count must never re-badge a conversation the user is reading — a
+ *    safety net the origin needed in three separate places, so it lives in one
+ *    place here.
+ */
+
+interface ConversationThread {
+    readonly conversationId: ConversationId;
+    readonly messages: readonly Message[];
+    readonly hasMoreOlder: boolean;
+    /** The newest `created_at` held — the reconnect backfill's high-water mark. */
+    readonly latestAt: string | null;
+}
+interface MessagingSnapshot {
+    readonly conversations: readonly ConversationSummary[];
+    readonly hasMoreConversations: boolean;
+    /**
+     * True once the inbox has actually been READ at least once.
+     *
+     * An empty list means two completely different things — "you have no
+     * conversations" and "we have not looked yet" — and a UI that cannot tell
+     * them apart shows a confident "No conversations yet" to someone who has
+     * hundreds. That is a screen telling a lie, so the distinction is a fact the
+     * store carries rather than something each surface guesses from a timer.
+     */
+    readonly hasLoadedConversations: boolean;
+    readonly threads: ReadonlyMap<ConversationId, ConversationThread>;
+    readonly activeConversationId: ConversationId | null;
+    /** Conversations WITH unread, not total unread messages (the origin's semantics). */
+    readonly totalUnreadConversations: number;
+}
+interface MessagingStore {
+    snapshot(): MessagingSnapshot;
+    subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
+    setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    upsertConversation(item: ConversationSummary): void;
+    removeConversation(id: ConversationId): void;
+    setActiveConversation(id: ConversationId | null): void;
+    setThread(id: ConversationId, messages: readonly Message[], args?: {
+        hasMoreOlder?: boolean;
+    }): void;
+    prependOlder(id: ConversationId, messages: readonly Message[], hasMoreOlder: boolean): void;
+    /** The one door every incoming message uses. Returns what actually happened. */
+    ingest(message: Message): "added" | "merged" | "dropped-stale" | "dropped-duplicate";
+    ingestMany(messages: readonly Message[]): void;
+    removeMessage(conversationId: ConversationId, messageId: MessageId): void;
+    markConversationRead(id: ConversationId): void;
+    setUnreadCount(id: ConversationId, count: number): void;
+}
+declare function createMessagingStore(): MessagingStore;
+/**
+ * The optimistic row a composer shows the instant Enter is pressed. It carries
+ * the outbox's client key, which is the whole reason the confirmed row can find
+ * and replace it rather than appearing beside it.
+ */
+declare function optimisticMessage(args: {
+    conversationId: ConversationId;
+    senderId: UserId;
+    organizationId: Message["organizationId"];
+    content: string;
+    clientMessageId: ClientMessageId;
+    kind?: Message["kind"];
+    replyToId?: MessageId | null;
+    action?: Message["action"];
+    attachments?: readonly Message["attachments"][number][];
+    references?: readonly Message["references"][number][];
+    now?: () => number;
+}): Message;
+
+/**
+ * THE MESSAGING ENGINE — the object a host mounts once and never reasons about.
+ *
+ * It owns the wiring that every chat implementation gets wrong: which channel
+ * carries what, what happens on reconnect, which of four arrival paths wins,
+ * when a read receipt is written, and what a failed send does. All of it is
+ * here so a consumer's job is `engine.send(draft)` and rendering a snapshot.
+ *
+ * THE RECONNECT RULE, inherited from `@ai-matrx/realtime` and honored here:
+ * realtime has NO REPLAY. Every channel this engine opens declares an
+ * `onBackfill` door, and those doors re-read from the database. A reconnect
+ * without a re-read leaves a permanently wrong thread that looks perfectly
+ * healthy — the single most expensive bug class in messaging.
+ */
+
+interface EngineDiagnostic {
+    readonly level: "info" | "warn" | "error";
+    readonly message: string;
+    readonly remedy?: string | undefined;
+}
+interface MessagingEngineOptions {
+    repository: MessagingRepository;
+    manager: RealtimeManager;
+    identity: MessagingIdentity;
+    outboxStorage?: OutboxStorage | undefined;
+    onDiagnostic?: ((event: EngineDiagnostic) => void) | undefined;
+    /** Fired for a message from someone else, for notification sinks. */
+    onIncoming?: ((message: Message) => void) | undefined;
+    conversationPageSize?: number | undefined;
+    messagePageSize?: number | undefined;
+}
+interface MessagingEngine {
+    readonly store: MessagingStore;
+    readonly outbox: Outbox;
+    readonly identity: MessagingIdentity;
+    /** Load page one of the inbox and start the inbox channel. */
+    start(): Promise<void>;
+    loadMoreConversations(): Promise<void>;
+    /** Open a conversation: load its thread and subscribe to its channel. */
+    openConversation(id: ConversationId): Promise<void>;
+    closeConversation(id: ConversationId): void;
+    loadOlderMessages(id: ConversationId): Promise<void>;
+    /** Queue a message. Returns immediately with the optimistic row on screen. */
+    send(draft: DraftMessage): ClientMessageId;
+    retry(entryId: string): void;
+    discard(entryId: string): void;
+    editMessage(id: MessageId, conversationId: ConversationId, content: string): Promise<void>;
+    deleteMessage(id: MessageId, conversationId: ConversationId, forEveryone: boolean): Promise<void>;
+    markRead(id: ConversationId): Promise<void>;
+    startDirectConversation(otherUserId: UserId): Promise<ConversationId>;
+    dispose(): void;
+}
+declare function createMessagingEngine(options: MessagingEngineOptions): MessagingEngine;
+/** The realtime client session id, exposed for diagnostics surfaces. */
+declare function messagingClientId(): string;
+
+/**
+ * `<MessagingProvider>` — the one place an app wires messaging.
+ *
+ * THE ONE-HOUR INTEGRATION CONTRACT (R7) is this component's job: a host passes
+ * a Supabase client, who they are, and their org. Everything else — the
+ * repository, the realtime manager and its channels, the store, the outbox and
+ * its durable storage, the action registry, the AI surface — is constructed and
+ * owned here.
+ *
+ * What a host may inject is IDENTITY and app chrome: session source, agent ids,
+ * a navigator for reference cards, a notification sink, action handlers. What a
+ * host must NEVER have to inject is behavior — if you find yourself catching a
+ * package error, retrying a package call, or branching on a package quirk in
+ * host code, that logic belongs in here (C22).
+ *
+ * 🚨 THE PROVIDER'S LIFETIME IS `client` + `userId` + `organizationId`, AND
+ * NOTHING ELSE. Hosts pass fresh object literals for `agents`, `actions`, and
+ * `onDiagnostic` on every render; keying the engine on those identities would
+ * tear down and rebuild every channel on every parent re-render — a permanent
+ * resubscribe loop that looks exactly like "realtime is broken".
+ */
+
+interface MessagingHost {
+    readonly engine: MessagingEngine;
+    readonly actions: ActionRegistry;
+    readonly ai: MessagingAi | null;
+    readonly identity: MessagingIdentity;
+    readonly openReference: ((reference: MatrxReference) => void) | null;
+}
+interface MessagingProviderProps {
+    /** Any Supabase client. `null` while the host is still resolving one. */
+    client: MessagingSupabaseClient | null | undefined;
+    /** The signed-in user. `null` while auth is still resolving. */
+    userId: string | null | undefined;
+    /** The active organization. Every write carries it (R5). */
+    organizationId: string | null | undefined;
+    /**
+     * The Matrx API transport for AI features. Omit to run messaging without AI;
+     * the AI actions then do not render at all (never a dead button).
+     */
+    transport?: MatrxTransport | undefined;
+    /** Which database agent backs each AI capability. */
+    agents?: MessagingAgents | undefined;
+    /** Handlers for actionable messages. Registered once per handler identity. */
+    actions?: readonly ActionHandler<never>[] | undefined;
+    /** Called when a reference card is clicked. Omit and cards render inert-but-labeled. */
+    onOpenReference?: ((reference: MatrxReference) => void) | undefined;
+    /** A message arrived from someone else — for a toast, sound, or badge. */
+    onIncomingMessage?: ((message: Message) => void) | undefined;
+    /** Background failures, with a remedy. Defaults to a console sink. */
+    onDiagnostic?: ((event: EngineDiagnostic) => void) | undefined;
+    /** Re-resolve a session after one goes missing. Enables the single retry. */
+    resolveSession?: SessionResolver | undefined;
+    /** Override outbox persistence. Defaults to localStorage, then memory. */
+    outboxStorage?: OutboxStorage | undefined;
+    children: ReactNode;
+}
+declare function MessagingProvider(props: MessagingProviderProps): ReactNode;
+/** The host, or `null` while auth/org are still resolving. */
+declare function useMessagingHost(): MessagingHost | null;
+/**
+ * The host, or a thrown error naming the fix. Used by components that cannot
+ * render anything meaningful without it — they are inside `<MessagingInbox>`,
+ * which itself renders a loading state until the host exists.
+ */
+declare function useRequiredMessagingHost(): MessagingHost;
+/** The whole messaging snapshot, re-rendering only when it actually changes. */
+declare function useMessagingSnapshot(): MessagingSnapshot | null;
+
+interface UseConversationsResult {
+    conversations: readonly ConversationSummary[];
+    hasMore: boolean;
+    /** True only on the FIRST load; a refresh must not blank the list. */
+    isInitialLoading: boolean;
+    totalUnreadConversations: number;
+    loadMore: () => void;
+    select: (id: ConversationId) => void;
+    activeConversationId: ConversationId | null;
+    startDirect: (otherUserId: UserId) => Promise<ConversationId>;
+}
+declare function useConversations(): UseConversationsResult;
+interface UseConversationResult {
+    summary: ConversationSummary | null;
+    thread: ConversationThread | null;
+    messages: readonly Message[];
+    participants: readonly UserSummary[];
+    isLoading: boolean;
+    hasMoreOlder: boolean;
+    loadOlder: () => void;
+    pending: readonly OutboxEntry[];
+    retry: (entryId: string) => void;
+    discard: (entryId: string) => void;
+    edit: (messageId: Message["id"], content: string) => Promise<void>;
+    remove: (messageId: Message["id"], forEveryone: boolean) => Promise<void>;
+}
+declare function useConversation(id: ConversationId | null): UseConversationResult;
+interface UseComposerResult {
+    value: string;
+    setValue: (value: string) => void;
+    canSend: boolean;
+    send: () => void;
+    /** Call on EVERY keystroke; the typing lifecycle is entirely inside. */
+    onKeystroke: () => void;
+    replyTo: Message | null;
+    setReplyTo: (message: Message | null) => void;
+}
+/**
+ * The composer's state. `value` lives here so a draft SURVIVES a re-render and
+ * a conversation switch-and-back — losing a half-typed message on a re-render
+ * is the same defect as losing a sent one, one step earlier.
+ */
+declare function useComposer(conversationId: ConversationId | null): UseComposerResult;
+interface UseTypistsResult {
+    /** Ready-made label: "Ana is typing…". `null` when nobody is. */
+    label: string | null;
+    userIds: readonly UserId[];
+}
+declare function useTypists(conversationId: ConversationId | null, participants: readonly UserSummary[]): UseTypistsResult;
+declare function useOnlineUserIds(conversationId: ConversationId | null): ReadonlySet<string>;
+interface UseMessagingAiResult {
+    available: readonly AiCapability[];
+    isRunning: boolean;
+    result: AiResult | null;
+    error: string | null;
+    run: (capability: AiCapability, args?: {
+        instruction?: string;
+    }) => void;
+    clear: () => void;
+}
+declare function useMessagingAi(conversationId: ConversationId | null): UseMessagingAiResult;
+interface UseMessageActionResult {
+    choices: ReturnType<ActionRegistry["choicesFor"]>;
+    receipt: ActionReceipt | null;
+    isRunning: boolean;
+    execute: (choice: string) => void;
+}
+/**
+ * An actionable message's chips. The double-click guard is in the registry, not
+ * here — this hook only reflects it, which is why two components rendering the
+ * same action cannot double-apply it either.
+ */
+declare function useMessageAction(message: Message): UseMessageActionResult;
+
+/**
+ * THE DROP-IN SURFACES (R6/R7).
+ *
+ * `<MessagingInbox />` is the whole product in one element. The paired pieces
+ * are exported too, for a host that wants the list in a sidebar and the thread
+ * on a route — but composing pages is the host's job, and building a product
+ * is not.
+ *
+ * Every screen here obeys the same three rules: a control is absent or honest
+ * (never dead or disabled-looking with no reason); loading is a skeleton of the
+ * real thing, never the word "Loading…"; and a degraded connection SAYS so
+ * rather than quietly showing a stale thread.
+ */
+
+interface ConversationListProps {
+    onSelect?: (id: ConversationId) => void;
+    onNewConversation?: () => void;
+    className?: string;
+}
+declare function ConversationList(props: ConversationListProps): ReactNode;
+interface ConversationViewProps {
+    conversationId: ConversationId | null;
+    onBack?: () => void;
+    className?: string;
+}
+declare function ConversationView(props: ConversationViewProps): ReactNode;
+declare function MessageBubble(props: {
+    message: Message;
+    isMine: boolean;
+    isLast: boolean;
+    onRetry?: (entryId: string) => void;
+    onReply?: (message: Message) => void;
+    failedEntryId?: string | null;
+}): ReactNode;
+/**
+ * An actionable message's chips. An action this build cannot honor renders
+ * NOTHING — never a generic button that offers something nobody can deliver.
+ */
+declare function MessageActionChips(props: {
+    message: Message;
+}): ReactNode;
+declare function Composer(props: {
+    conversationId: ConversationId | null;
+}): ReactNode;
+interface MessagingInboxProps {
+    /** Start on a specific conversation (e.g. from a route param). */
+    conversationId?: ConversationId | null;
+    onConversationChange?: (id: ConversationId | null) => void;
+    onNewConversation?: () => void;
+    className?: string;
+}
+/**
+ * THE WHOLE PRODUCT IN ONE ELEMENT — step 2 of the one-hour contract (R7).
+ *
+ * On a phone the two panes become one pane that swaps, driven by `data-pane`;
+ * a 340px sidebar beside a thread on a 390px screen is the layout every chat
+ * app gets wrong exactly once.
+ */
+declare function MessagingInbox(props: MessagingInboxProps): ReactNode;
+
+declare function Avatar(props: {
+    name: string;
+    imageUrl?: string | null;
+    seed?: string;
+    small?: boolean;
+    online?: boolean;
+}): React.ReactElement;
+/**
+ * The delivery tick. Every state has a DISTINCT glyph and a distinct label —
+ * a spinner that means both "sending" and "failed" is the lie this prevents.
+ */
+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;
+}): React.ReactElement;
+declare function AgentTag(): React.ReactElement;
+declare function TypingDots(): React.ReactElement;
+/**
+ * Loading states are SKELETONS of the real thing, never the word "Loading…".
+ * The shape tells the user what is coming.
+ */
+declare function ConversationSkeleton(props: {
+    rows?: number;
+}): React.ReactElement;
+declare function EmptyState(props: {
+    title: string;
+    body?: string;
+    action?: React.ReactNode;
+}): React.ReactElement;
+
+/**
+ * INLINED SVGs. NO ICON LIBRARY, EVER (C19).
+ *
+ * A package that depends on an icon library forces its version on every
+ * consumer and ships a whole set to deliver a dozen glyphs. These are drawn in
+ * the Lucide idiom (24×24, 2px stroke, round caps) so they sit correctly beside
+ * a host's Lucide icons, and cost a fraction of a percent of the bundle.
+ *
+ * Every icon inherits `currentColor` and takes its size from `1em` — they are
+ * text, and they scale with the text they sit next to.
+ */
+
+type IconProps = Omit<SVGProps<SVGSVGElement>, "children">;
+declare const SendIcon: (props: IconProps) => React.ReactElement;
+declare const PaperclipIcon: (props: IconProps) => React.ReactElement;
+declare const SparklesIcon: (props: IconProps) => React.ReactElement;
+declare const CheckIcon: (props: IconProps) => React.ReactElement;
+declare const DoubleCheckIcon: (props: IconProps) => React.ReactElement;
+declare const ClockIcon: (props: IconProps) => React.ReactElement;
+declare const AlertIcon: (props: IconProps) => React.ReactElement;
+declare const SearchIcon: (props: IconProps) => React.ReactElement;
+declare const PlusIcon: (props: IconProps) => React.ReactElement;
+declare const CloseIcon: (props: IconProps) => React.ReactElement;
+declare const ChevronLeftIcon: (props: IconProps) => React.ReactElement;
+declare const ReplyIcon: (props: IconProps) => React.ReactElement;
+declare const LinkIcon: (props: IconProps) => React.ReactElement;
+declare const BotIcon: (props: IconProps) => React.ReactElement;
+declare const UsersIcon: (props: IconProps) => React.ReactElement;
+
+/**
+ * EFFECTIVE-ACTOR RESOLUTION — who a message is FROM, versus who wrote the row.
+ *
+ * `sender_id` is the AUDIT PRINCIPAL: the session the write happened under. It
+ * must never change, and it must never be what the UI renders when an agent
+ * acted through a human's session. Otherwise an automated message wears a
+ * colleague's face and name — the failure this module exists to prevent (R4
+ * puts agents in conversations, which makes it the normal case, not an edge).
+ *
+ * The effective actor is declared in the message's own metadata by whoever sent
+ * it. Nothing here infers an agent from heuristics on the content.
+ */
+
+interface ActorPresentation {
+    readonly displayName: string;
+    readonly avatarUrl: string | null;
+    /** True when the message was authored by an agent, not the human principal. */
+    readonly isAgent: boolean;
+    /** Set only for an agent: the human whose session it acted under. */
+    readonly onBehalfOfName: string | null;
+    /** The audit principal. Always the row's `sender_id`. Never rewritten. */
+    readonly principalUserId: Message["senderId"];
+}
+declare function resolveActor(message: Message, sender: UserSummary | null): ActorPresentation;
+
+/**
+ * IN-FLIGHT DEDUP + TTL CACHE — the cure for the request storm.
+ *
+ * The incident (matrx-frontend, 2026-08-21): every conversation row rendered
+ * called the profile lookup for its participants, every one of those calls hit
+ * the network independently, the transport wobbled, and the app captured
+ * **909 errors in 0.6 seconds**. The bug was never the transport — it was that
+ * N identical concurrent reads were N requests.
+ *
+ * Two guarantees, and both are load-bearing:
+ *
+ * 1. **Concurrent callers for the same key share ONE promise.** The second
+ *    caller does not start a second request; it awaits the first.
+ * 2. **A failure does not poison the cache.** The rejected promise is evicted
+ *    the moment it settles, so the next caller retries instead of inheriting a
+ *    permanent error. (The naive version caches the rejection and the surface
+ *    stays broken until reload — the reason this has a named test.)
+ *
+ * A resolved value is held for `ttlMs` and then re-read. This is a READ cache
+ * only: writes go straight through and invalidate.
+ */
+interface ReadCacheOptions {
+    /** How long a resolved value is served without a re-read. */
+    ttlMs: number;
+    /** Injected clock — the tests must not sleep. */
+    now?: () => number;
+    /** Bound on retained entries; the oldest is evicted first. */
+    maxEntries?: number;
+}
+interface ReadCache<T> {
+    /** Read through the cache. Identical concurrent keys share one call. */
+    read(key: string, load: () => Promise<T>): Promise<T>;
+    /** Drop one key (after a write that changes it). */
+    invalidate(key: string): void;
+    /** Drop everything (sign-out, org switch). */
+    clear(): void;
+    /** Diagnostics: how many resolved entries are held. */
+    size(): number;
+}
+declare function createReadCache<T>(options: ReadCacheOptions): ReadCache<T>;
+
+/**
+ * THE MESSAGING CHANNEL NAMESPACES.
+ *
+ * D5: zero hand-rolled `.channel(` in this package. Every topic is declared
+ * through `@ai-matrx/realtime`'s registry, which refuses a colliding
+ * re-declaration and hands every connection attempt a unique instance topic.
+ *
+ * TWO channels, deliberately — not four. The origin ran `messages:`, `typing:`,
+ * `presence:` and a global list channel as four independent subscriptions, and
+ * three of the four hardening items were about them fighting each other. Here:
+ *
+ * - `messaging-inbox` (per user): the conversation list's own feed.
+ * - `messaging-conversation` (per conversation): messages, presence, AND
+ *   typing on ONE channel, because they are one room. Sharing the channel is
+ *   what makes "the person typing is also present" true by construction
+ *   instead of by two subscriptions agreeing.
+ *
+ * `defineChannelNamespace` throws on a conflicting re-declaration, so these are
+ * created lazily through a `globalThis` slot: with dual ESM/CJS output the
+ * module can be evaluated twice in one process, and a second identical
+ * declaration must be a no-op rather than a crash.
+ */
+
+declare function inboxTopic(userId: UserId): string;
+declare function conversationTopic(conversationId: ConversationId): string;
+/** Broadcast event names. One place, so a sender and a receiver cannot drift. */
+declare const MESSAGING_EVENTS: {
+    /** A freshly sent message, broadcast beside the Postgres Changes row so a
+     *  receiver gets it on whichever path arrives first (both are deduped). */
+    readonly message: "mx.message";
+    /** A message edited or soft-deleted. */
+    readonly messageUpdated: "mx.message.updated";
+    /** An action receipt, so every viewer's chip settles at once. */
+    readonly actionSettled: "mx.action.settled";
+};
+
+/**
+ * ONE error classification for the whole package (C22).
+ *
+ * The banned alternative is the host catching a PostgREST error and deciding
+ * for itself whether it was an auth blip, a permission denial, or a real bug —
+ * which is how the same three-branch `if` ends up copy-pasted into every
+ * consumer and drifts. Everything this package throws is a `MessagingError`
+ * with a stable `code`, and the two that hosts genuinely treat differently
+ * (`session-unavailable`, `forbidden`) say so in the type.
+ *
+ * The incident behind `session-unavailable`: a DM reader mounted before the
+ * access token existed, every RPC came back `42501`, and the app captured 909
+ * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
+ * warns and retries; it is never a red error.
+ */
+type MessagingErrorCode = "session-unavailable" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
+declare class MessagingError extends Error {
+    readonly code: MessagingErrorCode;
+    /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
+    readonly remedy: string;
+    readonly cause?: unknown;
+    constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
+    /** True when retrying after the host re-establishes a session is the fix. */
+    get isRetryable(): boolean;
+}
+interface PostgrestErrorLike {
+    message: string;
+    code?: string | undefined;
+    details?: string | null | undefined;
+}
+/**
+ * THE ONE PLACE a raw PostgREST/transport error becomes a typed one. Called at
+ * every boundary in `repository.ts`; nothing else in the package inspects a raw
+ * error, and no consumer should ever have to.
+ */
+declare function normalizeMessagingError(error: PostgrestErrorLike | Error | unknown, operation: string): MessagingError;
+/** A response whose SHAPE is wrong — the ingress boundary, not the wire. */
+declare function invalidResponse(operation: string, detail: string): MessagingError;
+
+/**
+ * Display formatting. In the package because every consumer otherwise rebuilds
+ * it slightly differently and the inbox and the thread disagree about what
+ * "yesterday" means.
+ *
+ * Every function takes an explicit `now` so the tests do not depend on the
+ * clock, and none of them touches `Intl` with an implicit locale — a package
+ * that silently formats in the build machine's locale is a bug that only shows
+ * up for users in other timezones.
+ */
+
+declare function isSameDay(a: Date, b: Date): boolean;
+/** Compact stamp for a conversation row: `9:41 AM`, `Yesterday`, `Mar 4`. */
+declare function formatConversationTime(isoString: string | null, now?: number, locale?: string): string;
+/** The stamp under a bubble. */
+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.
+ */
+interface MessageGroup {
+    readonly senderId: UserId;
+    readonly messages: readonly Message[];
+    readonly dateSeparator: string | null;
+}
+declare function groupMessages(messages: readonly Message[], args?: {
+    now?: number;
+    windowMs?: number;
+    locale?: string;
+}): readonly MessageGroup[];
+/** "Ana is typing…" / "Ana and Bo are typing…" / "3 people are typing…" */
+declare function formatTypists(names: readonly string[]): string | null;
+declare function participantNames(participants: readonly UserSummary[], excluding: UserId): readonly string[];
+/** "Active now" / "Active 5m ago" — presence, said honestly. */
+declare function formatLastSeen(lastSeenMs: number | null, now?: number): string;
+
+/**
+ * THE INGRESS BOUNDARY — where a database row becomes a domain object.
+ *
+ * Everything crossing this line is validated, because the alternative is a
+ * screen that lies. A conversation row whose `participants` aggregate came back
+ * as a string instead of an array used to render an inbox entry named
+ * `undefined` with a working click target; refusing the row here turns a silent
+ * wrong screen into a loud, remediable error (nothing fails silently).
+ *
+ * The rules:
+ * - A missing REQUIRED field is a refusal, never a `?? ""` that renders blank.
+ * - A missing OPTIONAL field is a null, never an invented default.
+ * - `metadata` / `action_data` are host-and-DB-owned JSON: typed over `unknown`
+ *   and narrowed by shape, never cast (the data 0.2.1 `Json = unknown` lesson).
+ */
+
+declare function projectUserSummary(row: Record<string, unknown>): UserSummary;
+declare function projectMessageAction(value: unknown): MessageAction | null;
+declare function projectMessage(row: Record<string, unknown>, fallbackOrganizationId: OrganizationId): Message;
+declare function projectParticipantRole(value: unknown): ParticipantRole;
+declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, fallbackOrganizationId: OrganizationId): ConversationSummary;
+
+/**
+ * MATRX REFERENCES — a message can name a platform entity, and everything it
+ * names must OPEN. No dead ends.
+ *
+ * Two transports, both supported because both already exist in the wild:
+ *
+ * 1. **Structured**, in `metadata.references` — what this package writes.
+ * 2. **Fenced**, as a ```matrx block in the content — the platform's
+ *    reference-fence protocol, which arrives from senders outside messaging.
+ *
+ * Two failures this module exists to prevent:
+ *
+ * - **A raw fence rendered as a code block.** The reader sees JSON. `splitText`
+ *   is what lets the renderer draw a card instead.
+ * - **A fence leaking into a preview.** The inbox row and the desktop
+ *   notification are plain text; pasting the JSON there is the same defect one
+ *   layer down. `summarizeText` is the one collapse, used by both.
+ */
+
+type TextSegment = {
+    readonly type: "text";
+    readonly value: string;
+} | {
+    readonly type: "reference";
+    readonly reference: MatrxReference;
+};
+/** Every reference a message carries, from both transports, de-duplicated. */
+declare function extractReferences(content: string, structured?: readonly MatrxReference[]): readonly MatrxReference[];
+/**
+ * Split content into renderable segments. The renderer draws text for `text`
+ * and a live card for `reference`; a fence therefore CANNOT reach the screen as
+ * a code block.
+ */
+declare function splitText(content: string): readonly TextSegment[];
+/**
+ * ONE plain-text collapse, used by the inbox preview AND the notification body.
+ * A fence becomes its human label; it never reaches either as raw JSON.
+ */
+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, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, 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, 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 };