@ttt-productions/chat-core 0.4.22 → 0.5.1

package/dist/constants.d.ts

@@ -1,4 +1,7 @@
-export { MAX_CHAT_MESSAGE_LENGTH } from '@ttt-productions/ttt-core';
-/** Age threshold after which a stale chat-attachment row becomes eligible for cleanup (1 hour). */
-export declare const CHAT_ATTACHMENT_STALE_AGE_MS: number;
+/**
+ * Maximum chat message text length (characters). Consumer apps may override
+ * by passing a custom value through `ChatCoreConfig`; this constant is the
+ * package default and is also what chat-core's own internal schemas use.
+ */
+export declare const MAX_CHAT_MESSAGE_LENGTH = 4000;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,mGAAmG;AACnG,eAAO,MAAM,4BAA4B,QAAiB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC"}

package/dist/constants.js

@@ -1,7 +1,8 @@
 // Chat-domain limits and operational constants.
-// Re-exported from ttt-core. Source of truth lives there so ttt-core's
-// schemas can reference it without creating a circular package dependency.
-export { MAX_CHAT_MESSAGE_LENGTH } from '@ttt-productions/ttt-core';
-/** Age threshold after which a stale chat-attachment row becomes eligible for cleanup (1 hour). */
-export const CHAT_ATTACHMENT_STALE_AGE_MS = 60 * 60 * 1000;
+/**
+ * Maximum chat message text length (characters). Consumer apps may override
+ * by passing a custom value through `ChatCoreConfig`; this constant is the
+ * package default and is also what chat-core's own internal schemas use.
+ */
+export const MAX_CHAT_MESSAGE_LENGTH = 4000;
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAEhD,uEAAuE;AACvE,2EAA2E;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,mGAAmG;AACnG,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { MAX_CHAT_MESSAGE_LENGTH, CHAT_ATTACHMENT_STALE_AGE_MS } from "./constants.js";
+export { MAX_CHAT_MESSAGE_LENGTH } from "./constants.js";
 export { GROUP_GAP_SEC } from "./types.js";
 export { isContinuation } from "./grouping.js";
-export type { ChatAttachment, ChatId, ChatThreadV1, ChatMessageV1, ChatAccessMode, ChatCoreConfig, ChatAttachmentConfig, SendAttachmentInput, SendAttachmentFn, ModerationHandlers, MessageRenderer, MessageRendererRegistry, ChatNameResolver, ChatPrewarmSenders, } from "./types.js";
+export type { ChatAttachment, ChatId, ChatThreadV1, ChatMessageV1, ChatAccessMode, ChatCoreConfig, ChatAttachmentConfig, SendAttachmentInput, SendAttachmentFn, ModerationHandlers, MessageRenderer, MessageRendererRegistry, ChatNameResolver, ChatPrewarmSenders, ChatMentionConfig, } from "./types.js";
+export type { MentionRef, ParsedSegment, MentionProvider, RecentMentionsAdapter, MentionAnchor, } from "./mentions/types.js";
+export { parseMentionTokens, formatMentionToken } from "./mentions/parser.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,MAAM,EACN,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,MAAM,EACN,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,aAAa,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 // Server-safe barrel. React UI, hooks, and the ChatNameResolver context
 // live on the "/react" subpath. Cloud Functions and other server code
 // import from this barrel only.
-export { MAX_CHAT_MESSAGE_LENGTH, CHAT_ATTACHMENT_STALE_AGE_MS } from "./constants.js";
+export { MAX_CHAT_MESSAGE_LENGTH } from "./constants.js";
 export { GROUP_GAP_SEC } from "./types.js";
 export { isContinuation } from "./grouping.js";
+export { parseMentionTokens, formatMentionToken } from "./mentions/parser.js";
 // CSS: import "@ttt-productions/chat-core/styles" in your app layout.
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,sEAAsE;AACtE,gCAAgC;AAEhC,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAkB/C,sEAAsE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,sEAAsE;AACtE,gCAAgC;AAEhC,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA0B/C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,sEAAsE"}

package/dist/mentions/MentionAutocomplete.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Visual autocomplete dropdown for the mention system.
+ *
+ * Pure presentation — driven entirely by `state` from `useMentionAutocomplete`.
+ * The consumer is expected to absolutely-position this near the textarea (or
+ * use its caret position via a wrapping container). chat-core does not
+ * compute textarea-caret coordinates; that's the consumer's job.
+ *
+ * Selecting a result fires `onSelect(ref)`. Hovering / arrow-keying updates
+ * the highlight via `onHighlight(index)`.
+ */
+import type { AutocompleteState } from './use-mention-autocomplete.js';
+import type { MentionRef } from './types.js';
+export interface MentionAutocompleteProps<TKind extends string = string> {
+    state: AutocompleteState<TKind>;
+    onSelect: (ref: MentionRef<TKind>) => void;
+    onHighlight?: (flatIndex: number) => void;
+    /** Class name applied to the outer container. */
+    className?: string;
+}
+export declare function MentionAutocomplete<TKind extends string = string>(props: MentionAutocompleteProps<TKind>): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=MentionAutocomplete.d.ts.map

package/dist/mentions/MentionAutocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MentionAutocomplete.d.ts","sourceRoot":"","sources":["../../src/mentions/MentionAutocomplete.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,wBAAwB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACrE,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAChC,QAAQ,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC/D,KAAK,EAAE,wBAAwB,CAAC,KAAK,CAAC,kDAoEvC"}

package/dist/mentions/MentionAutocomplete.js

@@ -0,0 +1,21 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '@ttt-productions/ui-core';
+export function MentionAutocomplete(props) {
+    const { state, onSelect, onHighlight, className } = props;
+    if (!state.open)
+        return null;
+    const anyResults = state.flatResults.length > 0;
+    const anyLoading = state.groups.some((g) => g.loading);
+    let flatIndex = 0;
+    return (_jsxs("div", { role: "listbox", "aria-label": "Mentions", className: cn('chat-mention-autocomplete', 'rounded-md border bg-popover text-popover-foreground shadow-md', 'max-h-72 overflow-y-auto min-w-[16rem]', className), children: [!anyResults && anyLoading && (_jsx("div", { className: "px-3 py-2 text-xs text-muted-foreground", children: "Searching\u2026" })), !anyResults && !anyLoading && (_jsx("div", { className: "px-3 py-2 text-xs text-muted-foreground", children: state.showingRecent ? 'No recent mentions' : 'No matches' })), state.groups.map((group) => (_jsxs("div", { className: "chat-mention-group", children: [_jsx("div", { className: "px-3 pt-2 pb-1 text-xs font-semibold text-muted-foreground", children: state.showingRecent ? `Recent ${group.label}` : group.label }), group.loading && group.results.length === 0 && (_jsx("div", { className: "px-3 pb-2 text-xs text-muted-foreground", children: "Loading\u2026" })), _jsx("ul", { children: group.results.map((ref) => {
+                            const myIndex = flatIndex;
+                            flatIndex += 1;
+                            const highlighted = myIndex === state.highlightedIndex;
+                            return (_jsx("li", { children: _jsx("button", { type: "button", role: "option", "aria-selected": highlighted, className: cn('w-full text-left px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground', highlighted && 'bg-accent text-accent-foreground'), onMouseEnter: () => onHighlight?.(myIndex), onClick: (e) => {
+                                        e.preventDefault();
+                                        onSelect(ref);
+                                    }, children: group.renderResult ? group.renderResult(ref) : _jsxs("span", { children: ["@", ref.displayText] }) }) }, `${ref.kind}:${ref.id}`));
+                        }) })] }, group.kind)))] }));
+}
+//# sourceMappingURL=MentionAutocomplete.js.map

package/dist/mentions/MentionAutocomplete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MentionAutocomplete.js","sourceRoot":"","sources":["../../src/mentions/MentionAutocomplete.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAgBb,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAU9C,MAAM,UAAU,mBAAmB,CACjC,KAAsC;IAEtC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC1D,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAE7B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAEvD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,OAAO,CACL,eACE,IAAI,EAAC,SAAS,gBACH,UAAU,EACrB,SAAS,EAAE,EAAE,CACX,2BAA2B,EAC3B,gEAAgE,EAChE,wCAAwC,EACxC,SAAS,CACV,aAEA,CAAC,UAAU,IAAI,UAAU,IAAI,CAC5B,cAAK,SAAS,EAAC,yCAAyC,gCAAiB,CAC1E,EACA,CAAC,UAAU,IAAI,CAAC,UAAU,IAAI,CAC7B,cAAK,SAAS,EAAC,yCAAyC,YACrD,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY,GACtD,CACP,EACA,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAC3B,eAAsB,SAAS,EAAC,oBAAoB,aAClD,cAAK,SAAS,EAAC,4DAA4D,YACxE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GACxD,EACL,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAC9C,cAAK,SAAS,EAAC,yCAAyC,8BAAe,CACxE,EACD,uBACG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;4BACzB,MAAM,OAAO,GAAG,SAAS,CAAC;4BAC1B,SAAS,IAAI,CAAC,CAAC;4BACf,MAAM,WAAW,GAAG,OAAO,KAAK,KAAK,CAAC,gBAAgB,CAAC;4BACvD,OAAO,CACL,uBACE,iBACE,IAAI,EAAC,QAAQ,EACb,IAAI,EAAC,QAAQ,mBACE,WAAW,EAC1B,SAAS,EAAE,EAAE,CACX,iFAAiF,EACjF,WAAW,IAAI,kCAAkC,CAClD,EACD,YAAY,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,EAC1C,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;wCACb,CAAC,CAAC,cAAc,EAAE,CAAC;wCACnB,QAAQ,CAAC,GAAG,CAAC,CAAC;oCAChB,CAAC,YAEA,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gCAAQ,GAAG,CAAC,WAAW,IAAQ,GACxE,IAhBF,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAiB3B,CACN,CAAC;wBACJ,CAAC,CAAC,GACC,KAjCG,KAAK,CAAC,IAAI,CAkCd,CACP,CAAC,IACE,CACP,CAAC;AACJ,CAAC"}

package/dist/mentions/MessageText.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Renders message text with inline mention chips.
+ *
+ * Walks the parser output and renders each segment: text segments as
+ * `<span>`, mention segments via the consumer-supplied `renderMention`
+ * callback (or a default chip when omitted).
+ *
+ * Pure, no context. Safe to use inside MessageItem renderers, ReplyQuote
+ * previews, or any other text surface that should honor mention tokens.
+ */
+import type { ReactNode } from 'react';
+import type { MentionRef } from './types.js';
+export interface MessageTextProps<TKind extends string = string> {
+    /** Raw message text containing optional `@[kind:id|displayText]` tokens. */
+    text: string;
+    /**
+     * Custom mention renderer. When omitted, mentions render as a
+     * `<span class="chat-mention-chip">@{displayText}</span>` chip — consumers
+     * style via CSS. To make mentions clickable / linked / role-aware, supply
+     * a renderMention.
+     */
+    renderMention?: (ref: MentionRef<TKind>) => ReactNode;
+    /** Optional className applied to the wrapping `<span>`. */
+    className?: string;
+}
+export declare function MessageText<TKind extends string = string>(props: MessageTextProps<TKind>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=MessageText.d.ts.map

package/dist/mentions/MessageText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageText.d.ts","sourceRoot":"","sources":["../../src/mentions/MessageText.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,gBAAgB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC7D,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;IACtD,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,2CAiBxF"}

package/dist/mentions/MessageText.js

@@ -0,0 +1,20 @@
+'use client';
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { parseMentionTokens } from './parser.js';
+function DefaultMentionChip({ ref }) {
+    return (_jsxs("span", { className: "chat-mention-chip", "data-mention-kind": ref.kind, "data-mention-id": ref.id, children: ["@", ref.displayText] }));
+}
+export function MessageText(props) {
+    const { text, renderMention, className } = props;
+    const segments = parseMentionTokens(text);
+    return (_jsx("span", { className: className, children: segments.map((seg, i) => {
+            if (seg.type === 'text') {
+                return _jsx("span", { children: seg.text }, i);
+            }
+            if (renderMention) {
+                return _jsx("span", { children: renderMention(seg.ref) }, i);
+            }
+            return _jsx(DefaultMentionChip, { ref: seg.ref }, i);
+        }) }));
+}
+//# sourceMappingURL=MessageText.js.map

package/dist/mentions/MessageText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageText.js","sourceRoot":"","sources":["../../src/mentions/MessageText.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAeb,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAgBjD,SAAS,kBAAkB,CAAuB,EAAE,GAAG,EAA8B;IACnF,OAAO,CACL,gBAAM,SAAS,EAAC,mBAAmB,uBAAoB,GAAG,CAAC,IAAI,qBAAmB,GAAG,CAAC,EAAE,kBACpF,GAAG,CAAC,WAAW,IACZ,CACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAgC,KAA8B;IACvF,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACjD,MAAM,QAAQ,GAAG,kBAAkB,CAAQ,IAAI,CAAC,CAAC;IAEjD,OAAO,CACL,eAAM,SAAS,EAAE,SAAS,YACvB,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACvB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACxB,OAAO,yBAAe,GAAG,CAAC,IAAI,IAAZ,CAAC,CAAmB,CAAC;YACzC,CAAC;YACD,IAAI,aAAa,EAAE,CAAC;gBAClB,OAAO,yBAAe,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAA1B,CAAC,CAAiC,CAAC;YACvD,CAAC;YACD,OAAO,KAAC,kBAAkB,IAAS,GAAG,EAAE,GAAG,CAAC,GAAG,IAAf,CAAC,CAAkB,CAAC;QACtD,CAAC,CAAC,GACG,CACR,CAAC;AACJ,CAAC"}

package/dist/mentions/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mention token parser.
+ *
+ * Token grammar:
+ *   @[kind:id]                — minimal form; displayText defaults to id
+ *   @[kind:id|displayText]    — full form
+ *
+ *   kind         : [A-Za-z0-9-]+
+ *   id           : [^\]|]+
+ *   displayText  : [^\]]*     (may be empty; defaults to id when omitted)
+ *
+ * Anything not matching the grammar is preserved verbatim as text segments.
+ * Malformed tokens (unterminated, illegal characters) are NOT parsed — they
+ * pass through as plain text so the user always sees what they typed.
+ */
+import type { MentionRef, ParsedSegment } from './types.js';
+/**
+ * Parse a string of message text into an ordered array of text and mention
+ * segments. Always returns at least one segment for non-empty input. For an
+ * empty string, returns an empty array.
+ *
+ * The parser is intentionally permissive in `TKind` — it returns mentions
+ * with `kind` typed as `TKind`, but does NOT validate that the parsed kind
+ * is a member of the consumer's union. Validation, if needed, is the
+ * consumer's job; the wire token is the source of truth.
+ */
+export declare function parseMentionTokens<TKind extends string = string>(text: string): Array<ParsedSegment<TKind>>;
+/**
+ * Build a wire token from a MentionRef. Inverse of the parser's per-token
+ * branch — same grammar.
+ */
+export declare function formatMentionToken<TKind extends string>(ref: MentionRef<TKind>): string;
+//# sourceMappingURL=parser.d.ts.map

package/dist/mentions/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/mentions/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI5D;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC9D,IAAI,EAAE,MAAM,GACX,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAgC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAEvF"}

package/dist/mentions/parser.js

@@ -0,0 +1,61 @@
+/**
+ * Mention token parser.
+ *
+ * Token grammar:
+ *   @[kind:id]                — minimal form; displayText defaults to id
+ *   @[kind:id|displayText]    — full form
+ *
+ *   kind         : [A-Za-z0-9-]+
+ *   id           : [^\]|]+
+ *   displayText  : [^\]]*     (may be empty; defaults to id when omitted)
+ *
+ * Anything not matching the grammar is preserved verbatim as text segments.
+ * Malformed tokens (unterminated, illegal characters) are NOT parsed — they
+ * pass through as plain text so the user always sees what they typed.
+ */
+const TOKEN_RE = /@\[([A-Za-z0-9-]+):([^\]|]+)(?:\|([^\]]*))?\]/g;
+/**
+ * Parse a string of message text into an ordered array of text and mention
+ * segments. Always returns at least one segment for non-empty input. For an
+ * empty string, returns an empty array.
+ *
+ * The parser is intentionally permissive in `TKind` — it returns mentions
+ * with `kind` typed as `TKind`, but does NOT validate that the parsed kind
+ * is a member of the consumer's union. Validation, if needed, is the
+ * consumer's job; the wire token is the source of truth.
+ */
+export function parseMentionTokens(text) {
+    if (text.length === 0)
+        return [];
+    const segments = [];
+    let lastIndex = 0;
+    TOKEN_RE.lastIndex = 0;
+    let match;
+    while ((match = TOKEN_RE.exec(text)) !== null) {
+        const [whole, kindRaw, idRaw, displayRaw] = match;
+        const start = match.index;
+        const end = start + whole.length;
+        if (start > lastIndex) {
+            segments.push({ type: 'text', text: text.slice(lastIndex, start) });
+        }
+        const ref = {
+            kind: kindRaw,
+            id: idRaw,
+            displayText: displayRaw && displayRaw.length > 0 ? displayRaw : idRaw,
+        };
+        segments.push({ type: 'mention', ref });
+        lastIndex = end;
+    }
+    if (lastIndex < text.length) {
+        segments.push({ type: 'text', text: text.slice(lastIndex) });
+    }
+    return segments;
+}
+/**
+ * Build a wire token from a MentionRef. Inverse of the parser's per-token
+ * branch — same grammar.
+ */
+export function formatMentionToken(ref) {
+    return `@[${ref.kind}:${ref.id}|${ref.displayText}]`;
+}
+//# sourceMappingURL=parser.js.map

package/dist/mentions/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/mentions/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,QAAQ,GAAG,gDAAgD,CAAC;AAElE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY;IAEZ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAgC,EAAE,CAAC;IACjD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC;IACvB,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;QAEjC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,GAAG,GAAsB;YAC7B,IAAI,EAAE,OAAgB;YACtB,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK;SACtE,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAExC,SAAS,GAAG,GAAG,CAAC;IAClB,CAAC;IAED,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAuB,GAAsB;IAC7E,OAAO,KAAK,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,WAAW,GAAG,CAAC;AACvD,CAAC"}

package/dist/mentions/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Generic mention system types.
+ *
+ * chat-core owns the mention infrastructure (parsing, autocomplete UI, keyboard
+ * behavior, composer insertion, message text rendering) but knows nothing about
+ * what a "user" or "project" is. The consumer parameterizes `TKind` to its own
+ * union and supplies one `MentionProvider` per kind.
+ *
+ * Wire format — mentions are encoded inline in the message's `text` field as
+ * `@[kind:id|displayText]` tokens. The renderer parses them out at display
+ * time. No schema change to ChatMessage.
+ */
+import type { ReactNode } from 'react';
+/**
+ * Resolved mention — the value that ends up in the wire token after the user
+ * selects an autocomplete result.
+ *
+ * `kind` is the discriminator supplied by the consumer (e.g. `'member'`, `'tag'`); `id` is the
+ * consumer-chosen stable identifier; `displayText` is the user-facing label
+ * (typically a display name or title).
+ */
+export type MentionRef<TKind extends string = string> = {
+    kind: TKind;
+    id: string;
+    displayText: string;
+};
+/**
+ * Single segment in parsed message text. Either a literal text run or a
+ * resolved mention. The renderer walks an ordered array of these.
+ */
+export type ParsedSegment<TKind extends string = string> = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'mention';
+    ref: MentionRef<TKind>;
+};
+/**
+ * Provider supplying autocomplete results for one mention kind.
+ *
+ * - `kind` — the discriminator. Must match `MentionRef.kind` for results
+ *   returned by `search`.
+ * - `label` — human-readable label for the section / tab.
+ * - `search` — async query. Receives the current query string (after the
+ *   trigger character), the consumer-supplied `context`, and an optional
+ *   `signal` for cancellation. Returns up to whatever limit the provider
+ *   chooses; chat-core renders all returned results.
+ * - `renderResult` — optional custom row UI. When omitted, the autocomplete
+ *   renders the `displayText` plain.
+ *
+ * `TContext` is consumer-owned — pass anything you need inside `search`
+ * (Firestore db, current user id, surface-specific filters). chat-core never
+ * inspects it.
+ */
+export type MentionProvider<TKind extends string = string, TContext = unknown> = {
+    kind: TKind;
+    label: string;
+    search: (args: {
+        query: string;
+        context: TContext;
+        signal?: AbortSignal;
+    }) => Promise<MentionRef<TKind>[]>;
+    renderResult?: (ref: MentionRef<TKind>) => ReactNode;
+};
+/**
+ * Optional recent-mentions adapter. When provided, the autocomplete UI shows
+ * recent picks when the user opens the dropdown without typing a query
+ * (or after typing fewer than the configured minimum characters).
+ *
+ * `getRecent` MAY be async — the autocomplete renders a spinner while it
+ * resolves. `recordUse` is fired after a successful selection so consumers
+ * can persist usage.
+ */
+export type RecentMentionsAdapter<TKind extends string = string> = {
+    getRecent: () => MentionRef<TKind>[] | Promise<MentionRef<TKind>[]>;
+    recordUse?: (ref: MentionRef<TKind>) => void | Promise<void>;
+};
+/**
+ * Anchor describing the position of an inserted mention inside the composer's
+ * text buffer. Tracked in component state so positionally-collocated mentions
+ * with the same display string disambiguate on send.
+ *
+ * - `start` / `end` — character offsets into the current textarea value.
+ * - `ref` — the resolved MentionRef.
+ */
+export type MentionAnchor<TKind extends string = string> = {
+    start: number;
+    end: number;
+    ref: MentionRef<TKind>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/mentions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mentions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACtD,IAAI,EAAE,KAAK,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IACnD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;IAC/E,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,CAAC,IAAI,EAAE;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,QAAQ,CAAC;QAClB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,KAAK,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;CACtD,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACjE,SAAS,EAAE,MAAM,UAAU,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;CACxB,CAAC"}

package/dist/mentions/types.js

@@ -0,0 +1,14 @@
+/**
+ * Generic mention system types.
+ *
+ * chat-core owns the mention infrastructure (parsing, autocomplete UI, keyboard
+ * behavior, composer insertion, message text rendering) but knows nothing about
+ * what a "user" or "project" is. The consumer parameterizes `TKind` to its own
+ * union and supplies one `MentionProvider` per kind.
+ *
+ * Wire format — mentions are encoded inline in the message's `text` field as
+ * `@[kind:id|displayText]` tokens. The renderer parses them out at display
+ * time. No schema change to ChatMessage.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mentions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mentions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/mentions/use-mention-autocomplete.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Composer-side mention autocomplete state hook.
+ *
+ * Detects when the user types the trigger character (default `@`) inside the
+ * provided textarea, captures the live query (the text between the trigger
+ * and the cursor), debounces searches across all configured providers, and
+ * tracks the anchor positions of inserted mentions so the composer can
+ * convert display text back to wire tokens on send.
+ *
+ * Returns an `AutocompleteState` value tailored for the `<MentionAutocomplete>`
+ * UI component, plus an `insertMention` action and a `getValueWithTokens`
+ * accessor the composer calls on send.
+ *
+ * Generic over `TKind` and `TContext`; chat-core inspects neither.
+ */
+import { type RefObject } from 'react';
+import type { MentionAnchor, MentionProvider, MentionRef, RecentMentionsAdapter } from './types.js';
+export type AutocompleteResultGroup<TKind extends string = string> = {
+    kind: TKind;
+    label: string;
+    results: MentionRef<TKind>[];
+    /** True if `search` is in flight for this provider. */
+    loading: boolean;
+    /** Provider-supplied custom renderer for individual results, if any. */
+    renderResult?: (ref: MentionRef<TKind>) => import('react').ReactNode;
+};
+export type AutocompleteState<TKind extends string = string> = {
+    /** True iff the dropdown should be visible. */
+    open: boolean;
+    /** Current query text (everything after the trigger up to the cursor). */
+    query: string;
+    /** Results grouped by provider, in the order the consumer passed providers. */
+    groups: AutocompleteResultGroup<TKind>[];
+    /** When true, groups are recent picks (`getRecent`) rather than search results. */
+    showingRecent: boolean;
+    /** Index of the currently highlighted result, flattened across all groups. */
+    highlightedIndex: number;
+    /** Flat array of all results in display order. Used internally for keyboard nav. */
+    flatResults: MentionRef<TKind>[];
+};
+export interface UseMentionAutocompleteArgs<TKind extends string, TContext> {
+    textareaRef: RefObject<HTMLTextAreaElement>;
+    /** Current textarea value (controlled). */
+    value: string;
+    /** Setter for the textarea value. */
+    onChange: (next: string) => void;
+    /** Providers in display order. Empty list disables the system entirely. */
+    providers: MentionProvider<TKind, TContext>[];
+    /** Consumer-controlled context passed to each provider's `search`. */
+    context: TContext;
+    /** Optional recent-mentions adapter. */
+    recent?: RecentMentionsAdapter<TKind>;
+    /** Trigger character. Defaults to `'@'`. Must be exactly one character. */
+    trigger?: string;
+    /**
+     * Minimum query length to fire `search`. Below this, recent picks are shown
+     * (if `recent` is supplied) or the dropdown stays empty. Default: 0 (search
+     * fires immediately on trigger).
+     */
+    minQueryLength?: number;
+    /** Debounce window in ms for search calls. Default: 200. */
+    searchDebounceMs?: number;
+}
+export interface UseMentionAutocompleteResult<TKind extends string = string> {
+    state: AutocompleteState<TKind>;
+    /** Handle keydown from the textarea — returns true if the event was handled. */
+    handleKeyDown: (event: import('react').KeyboardEvent<HTMLTextAreaElement>) => boolean;
+    /** Programmatically insert a mention at the trigger position (called by the autocomplete UI). */
+    insertMention: (ref: MentionRef<TKind>) => void;
+    /**
+     * Returns the current textarea value with all tracked mention anchors
+     * substituted back to wire tokens. Call this from the composer's send path.
+     */
+    getValueWithTokens: () => string;
+    /** Anchor list — exposed for tests and consumers that need the raw positions. */
+    anchors: MentionAnchor<TKind>[];
+    /** Close the dropdown imperatively (e.g. on send). */
+    close: () => void;
+}
+export declare function useMentionAutocomplete<TKind extends string, TContext>(args: UseMentionAutocompleteArgs<TKind, TContext>): UseMentionAutocompleteResult<TKind>;
+//# sourceMappingURL=use-mention-autocomplete.d.ts.map

package/dist/mentions/use-mention-autocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mention-autocomplete.d.ts","sourceRoot":"","sources":["../../src/mentions/use-mention-autocomplete.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1F,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,UAAU,EACV,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,uBAAuB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACnE,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7B,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,OAAO,OAAO,EAAE,SAAS,CAAC;CACtE,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IAC7D,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAC;IACd,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,MAAM,EAAE,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;IACzC,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,WAAW,0BAA0B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ;IACxE,WAAW,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC5C,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,2EAA2E;IAC3E,SAAS,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;IAC9C,sEAAsE;IACtE,OAAO,EAAE,QAAQ,CAAC;IAClB,wCAAwC;IACxC,MAAM,CAAC,EAAE,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACtC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACzE,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAChC,gFAAgF;IAChF,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,KAAK,OAAO,CAAC;IACtF,iGAAiG;IACjG,aAAa,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,kBAAkB,EAAE,MAAM,MAAM,CAAC;IACjC,iFAAiF;IACjF,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAChC,sDAAsD;IACtD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAMD,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,EACnE,IAAI,EAAE,0BAA0B,CAAC,KAAK,EAAE,QAAQ,CAAC,GAChD,4BAA4B,CAAC,KAAK,CAAC,CAgVrC"}