@pmate/chat-sdk 0.12.0-next.7 → 0.12.0-next.71

package/lib/commands.d.ts

@@ -0,0 +1,20 @@
+/** Host-owned command catalog. Selecting a suggestion edits the draft only. */
+export type ChatCommand = {
+    name: string;
+    description: string;
+    usage?: string;
+};
+export type ChatCommandConfig = {
+    commands: ChatCommand[];
+    label?: string;
+    emptyText?: string;
+};
+export declare function commandQuery(value: string, caret: number): {
+    query: string;
+    end: number;
+} | null;
+export declare function filterCommands(commands: ChatCommand[], query: string): ChatCommand[];
+export declare function completeCommand(value: string, end: number, command: ChatCommand): {
+    text: string;
+    caret: number;
+};

package/lib/commands.js

@@ -0,0 +1,12 @@
+export function commandQuery(value, caret) {
+    const match = /^\/([^\s/]*)(?=\s|$)/.exec(value);
+    return match && caret >= 1 && caret <= match[0].length ? { query: value.slice(1, caret).toLowerCase(), end: match[0].length } : null;
+}
+export function filterCommands(commands, query) {
+    return commands.filter(c => /^[a-z][a-z0-9-]*$/.test(c.name) && c.name.toLowerCase().startsWith(query));
+}
+export function completeCommand(value, end, command) {
+    const prefix = `/${command.name}`, suffix = value.slice(end);
+    const text = prefix + (suffix || " ");
+    return { text, caret: prefix.length + 1 };
+}

package/lib/components/ChatInputDesktop.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { handleImagePaste } from "../ux/imagePaste";
-import { useMentions } from "../hooks/useMentions";
+import { useComposerSuggestions } from "../hooks/useComposerSuggestions";
+import { CommandMenu } from "./CommandMenu";
 import { MentionMenu } from "./MentionMenu";
 import React from "react";
 import { Provider, createStore } from "jotai";
@@ -25,8 +26,8 @@ function DesktopInner(props) {
     const tokens = mergeChatInputTokens(props.tokens);
     const state = useChatInputState();
     const attachments = useAttachmentState();
-    const mentions = useMentions({
-        value: state.text, config: props.mentions, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
+    const mentions = useComposerSuggestions({
+        value: state.text, mentions: props.mentions, commands: props.commands, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
         onChange(value) { state.setText(value); state.setStatus(value.trim() ? "typing" : "idle"); props.onChange?.(value); },
     });
     const [isEmojiOpen, setIsEmojiOpen] = useState(false);
@@ -186,7 +187,7 @@ function DesktopInner(props) {
         alignSelf: "center",
         transition: `color ${tokens.motion.stateTransition}, transform ${tokens.motion.pressFeedback}`,
     };
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsxs("div", { className: "grid gap-3", style: { position: "relative", width: "100%" }, children: [_jsx("input", { ref: imageInputRef, type: "file", accept: props.image?.accept ?? "image/*", style: { display: "none" }, onChange: (event) => {
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsx(CommandMenu, { ...mentions.commandMenuProps, tokens: tokens }), _jsxs("div", { className: "grid gap-3", style: { position: "relative", width: "100%" }, children: [_jsx("input", { ref: imageInputRef, type: "file", accept: props.image?.accept ?? "image/*", style: { display: "none" }, onChange: (event) => {
                             const file = event.target.files?.[0];
                             if (file) {
                                 void handleImageFile(file);

package/lib/components/ChatInputMobile.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { handleImagePaste } from "../ux/imagePaste";
-import { useMentions } from "../hooks/useMentions";
+import { useComposerSuggestions } from "../hooks/useComposerSuggestions";
+import { CommandMenu } from "./CommandMenu";
 import { MentionMenu } from "./MentionMenu";
 import React from "react";
 import { Provider, createStore } from "jotai";
@@ -26,8 +27,8 @@ function MobileInner(props) {
     const tokens = mergeChatInputTokens(props.tokens);
     const state = useChatInputState();
     const attachments = useAttachmentState();
-    const mentions = useMentions({
-        value: state.text, config: props.mentions, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
+    const mentions = useComposerSuggestions({
+        value: state.text, mentions: props.mentions, commands: props.commands, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
         onChange(value) { state.setText(value); state.setStatus(value.trim() ? "typing" : "idle"); props.onChange?.(value); },
     });
     const [recordingChoice, setRecordingChoice] = useState("send");
@@ -267,7 +268,7 @@ function MobileInner(props) {
             userSelect: "none",
             WebkitUserSelect: "none",
             WebkitTouchCallout: "none",
-        }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), isRecordingOverlayVisible ? (_jsxs("div", { style: {
+        }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsx(CommandMenu, { ...mentions.commandMenuProps, tokens: tokens }), isRecordingOverlayVisible ? (_jsxs("div", { style: {
                     position: "fixed",
                     left: "50%",
                     bottom: "calc(72px + env(safe-area-inset-bottom, 0px))",

package/lib/components/CommandMenu.d.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from "react";
+import type { ChatCommand } from "../commands";
+import type { ChatInputTokens, DeepPartial } from "../types/chatInput";
+export declare function CommandMenu({ id, open, candidates, activeIndex, onSelect, onActiveIndex, menuRef, label, emptyText, tokens: overrides }: {
+    id: string;
+    open: boolean;
+    candidates: ChatCommand[];
+    activeIndex: number;
+    onSelect: (c: ChatCommand) => void;
+    onActiveIndex: (i: number) => void;
+    menuRef: RefObject<HTMLDivElement | null>;
+    label: string;
+    emptyText: string;
+    tokens?: DeepPartial<ChatInputTokens>;
+}): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/CommandMenu.js

@@ -0,0 +1,10 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import React, { useEffect } from "react";
+import { mergeChatInputTokens } from "../tokens/defaultTokens";
+export function CommandMenu({ id, open, candidates, activeIndex, onSelect, onActiveIndex, menuRef, label, emptyText, tokens: overrides }) {
+    const tokens = mergeChatInputTokens(overrides);
+    useEffect(() => { menuRef.current?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: "nearest" }); }, [activeIndex, open]);
+    if (!open)
+        return null;
+    return _jsx("div", { id: id, ref: menuRef, role: "listbox", "aria-label": label, style: { position: "absolute", bottom: "calc(100% + 8px)", left: 0, width: "min(420px, 100%)", maxHeight: "min(320px, 40dvh)", overflowY: "auto", overscrollBehavior: "contain", zIndex: 20, boxSizing: "border-box", padding: 6, borderRadius: tokens.radius.inputSurface, border: `1px solid ${tokens.color.borderDefault}`, background: tokens.color.surfaceInputFocus, color: tokens.color.textPrimary, boxShadow: tokens.shadow.inputElevated, fontFamily: tokens.typography.familyBase }, children: candidates.length ? candidates.map((c, i) => _jsxs("button", { id: `${id}-${i}`, type: "button", role: "option", "aria-selected": i === activeIndex, tabIndex: -1, onMouseDown: e => e.preventDefault(), onMouseMove: () => onActiveIndex(i), onClick: () => onSelect(c), style: { display: "block", width: "100%", minHeight: 48, padding: "9px 12px", border: 0, borderRadius: 8, textAlign: "left", cursor: "pointer", color: "inherit", background: i === activeIndex ? `color-mix(in srgb, ${tokens.color.brandPrimary} 14%, ${tokens.color.surfaceInputFocus})` : "transparent" }, children: [_jsxs("span", { style: { display: "block", overflowWrap: "anywhere", fontSize: tokens.typography.inputText.size }, children: [_jsxs("strong", { style: { color: tokens.color.brandPrimary }, children: ["/", c.name] }), c.usage ? _jsx("span", { style: { marginLeft: 8, fontSize: 12, color: tokens.color.textSecondary }, children: c.usage }) : null] }), _jsx("small", { style: { display: "block", marginTop: 3, color: tokens.color.textSecondary }, children: c.description })] }, c.name)) : _jsx("div", { role: "status", style: { padding: 12, color: tokens.color.textSecondary }, children: emptyText }) });
+}

package/lib/credentials.d.ts

@@ -0,0 +1,26 @@
+export type TokenRequest = Readonly<{
+    forceRefresh: boolean;
+    signal: AbortSignal;
+}>;
+export type TokenProvider = (request: TokenRequest) => string | Promise<string>;
+/** Cancel the caller's wait, not the underlying shared operation. */
+export declare function waitForCaller<T>(task: Promise<T>, signal?: AbortSignal, onAbandonedValue?: (value: T) => void): Promise<T>;
+/** One scoped credential owner; stale 401s share one refresh rather than cascading. */
+export declare class ChatCredentials {
+    private provider;
+    private origin;
+    private transport;
+    private lifetime;
+    private flight?;
+    private refreshing?;
+    private latest?;
+    private recovery?;
+    private recoveredFrom;
+    private version;
+    constructor(provider: TokenProvider, origin: string, transport?: typeof fetch);
+    private acquire;
+    private recover;
+    getToken: () => Promise<string>;
+    fetch: typeof fetch;
+    close(): void;
+}

package/lib/credentials.js

@@ -0,0 +1,110 @@
+import { ChatError } from "./chatError.js";
+/** Cancel the caller's wait, not the underlying shared operation. */
+export function waitForCaller(task, signal, onAbandonedValue) {
+    if (!signal)
+        return task;
+    if (signal.aborted) {
+        void task.then(value => onAbandonedValue?.(value), () => { });
+        return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const abort = () => { if (settled)
+            return; settled = true; signal.removeEventListener("abort", abort); reject(signal.reason ?? new DOMException("Aborted", "AbortError")); };
+        signal.addEventListener("abort", abort, { once: true });
+        task.then(value => { signal.removeEventListener("abort", abort); if (settled) {
+            onAbandonedValue?.(value);
+            return;
+        } settled = true; resolve(value); }, error => { signal.removeEventListener("abort", abort); if (!settled) {
+            settled = true;
+            reject(error);
+        } });
+    });
+}
+/** One scoped credential owner; stale 401s share one refresh rather than cascading. */
+export class ChatCredentials {
+    provider;
+    origin;
+    transport;
+    lifetime = new AbortController();
+    flight;
+    refreshing;
+    latest;
+    recovery;
+    recoveredFrom = -1;
+    version = 0;
+    constructor(provider, origin, transport = fetch) {
+        this.provider = provider;
+        this.origin = origin;
+        this.transport = transport;
+    }
+    acquire(forceRefresh = false) {
+        if (this.lifetime.signal.aborted)
+            return Promise.reject(new ChatError("closed", "Chat credentials closed"));
+        if (this.refreshing)
+            return this.refreshing;
+        if (!forceRefresh && this.flight)
+            return this.flight;
+        const version = forceRefresh ? ++this.version : this.version;
+        const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(15000)]);
+        const task = waitForCaller(Promise.resolve().then(() => this.provider({ forceRefresh, signal })), signal).then(token => {
+            if (this.lifetime.signal.aborted)
+                throw new ChatError("closed", "Chat credentials closed");
+            if (typeof token !== "string" || !token.trim())
+                throw new ChatError("authentication-required", "A valid access token is required");
+            if (version < this.version && this.latest)
+                return this.latest;
+            const value = { token, version };
+            this.latest = value;
+            return value;
+        }).catch(error => {
+            if (error?.status === 401)
+                throw new ChatError("authentication-required", "Credentials require a fresh login", { cause: error, status: 401 });
+            if (error?.status === 403)
+                throw new ChatError("access-denied", "Credential access denied", { cause: error, status: 403 });
+            throw error;
+        }).finally(() => { if (this.flight === task)
+            this.flight = undefined; if (this.refreshing === task)
+            this.refreshing = undefined; });
+        if (forceRefresh)
+            this.refreshing = task;
+        else
+            this.flight = task;
+        return task;
+    }
+    recover(used) {
+        if (this.latest && this.latest.version > used.version)
+            return Promise.resolve(this.latest);
+        if (this.recovery && used.version <= this.recoveredFrom)
+            return this.recovery;
+        this.recoveredFrom = used.version;
+        this.recovery = this.acquire(true);
+        return this.recovery;
+    }
+    getToken = async () => { return (await this.acquire()).token; };
+    fetch = async (input, init) => {
+        const transport = this.transport;
+        const url = new URL(input instanceof Request ? input.url : String(input)), headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        // Never attach an app credential to uploads, other origins or unauthenticated requests.
+        if (url.origin !== this.origin || !headers.has("authorization"))
+            return transport(input, init);
+        const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        const signal = AbortSignal.any([this.lifetime.signal, ...(callerSignal ? [callerSignal] : [])]);
+        signal?.throwIfAborted();
+        const original = input instanceof Request ? input.clone() : input;
+        const send = async (token) => {
+            signal?.throwIfAborted();
+            headers.set("authorization", `Bearer ${token}`);
+            return transport(original instanceof Request ? original.clone() : original, { ...init, headers, signal });
+        };
+        const used = await waitForCaller(this.acquire(), signal ?? undefined);
+        const response = await send(used.token);
+        if (response.status !== 401)
+            return response;
+        // Denial (403) is terminal. Only an unauthenticated response gets one replay.
+        void response.body?.cancel().catch(() => { });
+        const next = await waitForCaller(this.recover(used), signal);
+        return send(next.token);
+    };
+    close() { this.lifetime.abort(new ChatError("closed", "Chat credentials closed")); }
+}

package/lib/fileMetadata.d.ts

@@ -0,0 +1,9 @@
+/** Durable file reference. Upload limits and download policy belong to the host. */
+export type ChatFile = Readonly<{
+    url: string;
+    name: string;
+    size: number;
+    mimeType?: string;
+    expiresAt?: number;
+}>;
+export declare function parseChatFile(value: unknown): ChatFile | undefined;

package/lib/fileMetadata.js

@@ -0,0 +1,18 @@
+export function parseChatFile(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const file = value;
+    if (typeof file.name !== "string" || !file.name.trim() || file.name.length > 255 || /[\u0000-\u001f\\/]/u.test(file.name) || typeof file.url !== "string" || file.url.length > 8192 || !Number.isSafeInteger(file.size) || Number(file.size) < 0)
+        return;
+    try {
+        const url = new URL(file.url);
+        if (url.protocol !== "https:" || url.username || url.password)
+            return;
+    }
+    catch {
+        return;
+    }
+    return { url: file.url, name: file.name, size: file.size,
+        ...(typeof file.mimeType === "string" && file.mimeType.length <= 255 && !/[\r\n]/.test(file.mimeType) ? { mimeType: file.mimeType } : {}),
+        ...(typeof file.expiresAt === "number" && Number.isSafeInteger(file.expiresAt) && file.expiresAt > 0 ? { expiresAt: file.expiresAt } : {}), };
+}

package/lib/framework.d.ts

@@ -0,0 +1,11 @@
+import type { Chat } from "./chatContract.js";
+import type { ChatSnapshot, ChatThreadSnapshot } from "./chatTypes.js";
+export interface ChatStore {
+    subscribeThread(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot)[]): () => void;
+    getSnapshot(): ChatSnapshot;
+    getSnapshot(threadId: string): ChatThreadSnapshot;
+    subscribeChanges(listener: () => void): () => void;
+    subscribeChanges(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot)[]): () => void;
+}
+/** Synchronous memory reads are for external-store integrations, not cache selection. */
+export declare function getChatStore(chat: Chat): ChatStore;

package/lib/framework.js

@@ -0,0 +1,12 @@
+import { chatEngine } from "./internal/chatRegistry.js";
+const stores = new WeakMap();
+/** Synchronous memory reads are for external-store integrations, not cache selection. */
+export function getChatStore(chat) {
+    let store = stores.get(chat);
+    if (!store) {
+        const engine = chatEngine(chat);
+        store = { subscribeThread: (id, listener, fields) => engine.subscribeThread(id, listener, { fields, emitCurrent: false }), getSnapshot: ((id) => id === undefined ? engine.getSnapshot() : engine.getSnapshot(id)), subscribeChanges: ((target, callback, fields) => typeof target === "function" ? engine.subscribe(target, { emitCurrent: false }) : engine.subscribe(target, callback, { fields, emitCurrent: false })) };
+        stores.set(chat, store);
+    }
+    return store;
+}

package/lib/history.d.ts

@@ -0,0 +1,4 @@
+import type { Chat } from "./chatContract.js";
+import type { ChatThreadSnapshot, ReadOptions } from "./chatTypes.js";
+/** Explicit complete-history operation for search/export; may scan many pages. */
+export declare function loadThreadHistory(chat: Chat, threadId: string, { signal }?: ReadOptions): Promise<ChatThreadSnapshot>;

package/lib/history.js

@@ -0,0 +1,8 @@
+import { chatEngine } from "./internal/chatRegistry.js";
+import { waitForCaller } from "./credentials.js";
+/** Explicit complete-history operation for search/export; may scan many pages. */
+export function loadThreadHistory(chat, threadId, { signal } = {}) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    return waitForCaller(chatEngine(chat).getMessages(threadId, { all: true }), signal);
+}

package/lib/hooks/useChatSnapshot.d.ts

@@ -0,0 +1,4 @@
+import type { Chat, ChatSnapshot, ChatThreadSnapshot } from "../chat.js";
+/** React consumes the same stable view as callback subscribers. No App-side cache. */
+export declare function useChatSnapshot(chat: Chat | undefined): ChatSnapshot;
+export declare function useChatSnapshot(chat: Chat | undefined, threadId: string): ChatThreadSnapshot;

package/lib/hooks/useChatSnapshot.js

@@ -0,0 +1,9 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { getChatStore } from "../framework.js";
+const emptySummary = Object.freeze({ threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" });
+const emptyThread = Object.freeze({ threadId: "", messages: [], status: "pending", ready: false, hasEarlier: false, unread: undefined, group: undefined, readCounts: undefined });
+export function useChatSnapshot(chat, threadId) {
+    const subscribe = useCallback((notify) => !chat ? () => { } : threadId === undefined ? getChatStore(chat).subscribeChanges(notify) : getChatStore(chat).subscribeThread(threadId, notify), [chat, threadId]);
+    const snapshot = useCallback(() => threadId === undefined ? (chat ? getChatStore(chat).getSnapshot() : undefined) ?? emptySummary : (chat ? getChatStore(chat).getSnapshot(threadId) : undefined) ?? emptyThread, [chat, threadId]);
+    return useSyncExternalStore(subscribe, snapshot, () => threadId === undefined ? emptySummary : emptyThread);
+}

package/lib/hooks/useComposerSuggestions.d.ts

@@ -0,0 +1,50 @@
+import type { ChangeEvent, KeyboardEvent, SyntheticEvent } from "react";
+import { type ChatCommand, type ChatCommandConfig } from "../commands";
+import type { MentionConfig } from "../mentions/model";
+/** One input contract for host-owned composers, SDK inputs, @ mentions and / commands. */
+export declare function useComposerSuggestions({ value, onChange, mentions: config, commands, disabled }: {
+    value: string;
+    onChange: (value: string) => void;
+    mentions?: MentionConfig;
+    commands?: ChatCommandConfig;
+    disabled?: boolean;
+}): {
+    getMentions: () => import("..").ChatMention[];
+    menuProps: {
+        open: boolean;
+        id: string;
+        candidates: import("..").MentionCandidate[];
+        activeIndex: number;
+        onSelect: (candidate: import("..").MentionCandidate) => void;
+        onActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+        menuRef: import("react").RefObject<HTMLDivElement | null>;
+        label: string;
+        emptyText: string;
+    };
+    commandMenuProps: {
+        id: string;
+        open: boolean;
+        candidates: ChatCommand[];
+        activeIndex: number;
+        onSelect: (command: ChatCommand) => void;
+        onActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+        menuRef: import("react").RefObject<HTMLDivElement | null>;
+        label: string;
+        emptyText: string;
+    };
+    inputProps: {
+        onChange(event: ChangeEvent<HTMLTextAreaElement>): void;
+        onSelect(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onFocus(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onBlur(event: React.FocusEvent<HTMLTextAreaElement>): void;
+        onCompositionStart(): void;
+        onCompositionEnd(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void;
+        role?: "combobox" | undefined;
+        "aria-autocomplete"?: "list" | undefined;
+        "aria-haspopup"?: "listbox" | undefined;
+        "aria-expanded"?: boolean | undefined;
+        "aria-controls"?: string | undefined;
+        "aria-activedescendant"?: string | undefined;
+    };
+};

package/lib/hooks/useComposerSuggestions.js

@@ -0,0 +1,70 @@
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { useMentions } from "./useMentions";
+import { commandQuery, completeCommand, filterCommands } from "../commands";
+/** One input contract for host-owned composers, SDK inputs, @ mentions and / commands. */
+export function useComposerSuggestions({ value, onChange, mentions: config, commands, disabled = false }) {
+    const mentions = useMentions({ value, onChange, config, disabled });
+    const id = useId(), inputRef = useRef(null), menuRef = useRef(null);
+    const pending = useRef(null);
+    const [caret, setCaret] = useState(0), [focused, setFocused] = useState(false), [composing, setComposing] = useState(false);
+    const [dismissed, setDismissed] = useState(false), [selected, setSelected] = useState(0), [collapsed, setCollapsed] = useState(true);
+    const query = commands?.commands.length && focused && collapsed && !composing && !disabled && !dismissed ? commandQuery(value, caret) : null;
+    const candidates = query ? filterCommands(commands.commands, query.query) : [];
+    const index = Math.min(selected, Math.max(0, candidates.length - 1));
+    useLayoutEffect(() => {
+        if (pending.current?.text !== value)
+            return;
+        const position = pending.current.caret;
+        pending.current = null;
+        inputRef.current?.focus({ preventScroll: true });
+        inputRef.current?.setSelectionRange(position, position);
+        setCaret(position);
+    }, [value]);
+    function observe(event) {
+        inputRef.current = event.currentTarget;
+        setCaret(event.currentTarget.selectionStart);
+        setCollapsed(event.currentTarget.selectionStart === event.currentTarget.selectionEnd);
+    }
+    function select(command) {
+        if (!query)
+            return;
+        const next = completeCommand(value, query.end, command);
+        pending.current = next;
+        setDismissed(true);
+        onChange(next.text);
+    }
+    return {
+        getMentions: mentions.getMentions,
+        menuProps: { ...mentions.menuProps, open: mentions.menuProps.open && !query },
+        commandMenuProps: { id, open: Boolean(query), candidates, activeIndex: index, onSelect: select, onActiveIndex: setSelected, menuRef, label: commands?.label ?? "选择命令", emptyText: commands?.emptyText ?? "没有匹配的命令" },
+        inputProps: {
+            ...mentions.inputProps,
+            ...(commands ? { role: "combobox", "aria-autocomplete": "list", "aria-haspopup": "listbox", "aria-expanded": Boolean(query || mentions.menuProps.open), "aria-controls": query ? id : mentions.inputProps["aria-controls"], "aria-activedescendant": query && candidates[index] ? `${id}-${index}` : mentions.inputProps["aria-activedescendant"] } : {}),
+            onChange(event) { observe(event); setDismissed(false); setSelected(0); mentions.inputProps.onChange(event); },
+            onSelect(event) { observe(event); mentions.inputProps.onSelect(event); },
+            onFocus(event) { observe(event); setFocused(true); mentions.inputProps.onFocus(event); },
+            onBlur(event) { if (!menuRef.current?.contains(event.relatedTarget))
+                setFocused(false); mentions.inputProps.onBlur(event); },
+            onCompositionStart() { setComposing(true); mentions.inputProps.onCompositionStart(); },
+            onCompositionEnd(event) { setComposing(false); setDismissed(false); observe(event); mentions.inputProps.onCompositionEnd(event); },
+            onKeyDown(event) {
+                if (query && !event.nativeEvent.isComposing && event.keyCode !== 229) {
+                    if (event.key === "Escape") {
+                        event.preventDefault();
+                        setDismissed(true);
+                    }
+                    else if (candidates.length && ["ArrowDown", "ArrowUp"].includes(event.key)) {
+                        event.preventDefault();
+                        setSelected((index + (event.key === "ArrowDown" ? 1 : candidates.length - 1)) % candidates.length);
+                    }
+                    else if (candidates[index] && ["Enter", "Tab"].includes(event.key) && !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
+                        event.preventDefault();
+                        select(candidates[index]);
+                    }
+                }
+                if (!event.defaultPrevented)
+                    mentions.inputProps.onKeyDown(event);
+            },
+        },
+    };
+}

package/lib/index.d.ts

@@ -41,3 +41,8 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, type Chat, ChatError, type ChatThreadSnapshot, type ChatMessage as MessageView, type ChatErrorCode, type ConversationTarget, type OutgoingContent, type CreateChatOptions, type ChatSnapshot, type SentMessage, type ReadOptions, type ReadersQuery, type GroupChanges } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
+export * from "./commands";
+export * from "./components/CommandMenu";
+export * from "./hooks/useComposerSuggestions";

package/lib/index.js

@@ -41,3 +41,8 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, ChatError } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
+export * from "./commands";
+export * from "./components/CommandMenu";
+export * from "./hooks/useComposerSuggestions";

package/lib/internal/chatEngine.d.ts

@@ -0,0 +1,131 @@
+export type { ChatMessage } from "../chatTypes.js";
+import { type CreateChatOptions } from "../runtime/createChat.js";
+import type { ChatSession } from "../runtime/chatSession.js";
+import type { CachedChatMessage } from "../runtime/cachedMessage.js";
+import type { ConversationTarget } from "../runtime/conversationDirectory.js";
+import type { OutgoingContent as RuntimeContent } from "../runtime/outgoingContent.js";
+export { ChatError } from "../chatError.js";
+export type { ChatErrorCode } from "../chatError.js";
+export type { CreateChatOptions, ConversationTarget };
+export type OutgoingContent = Exclude<RuntimeContent, {
+    groupCreate: unknown;
+} | {
+    groupUpdate: unknown;
+}>;
+import type { ChatThreadSnapshot, ChatSnapshot, ReadOptions } from "../chatTypes.js";
+export type { ChatGroup, ConversationInfo, ChatThreadSnapshot, ChatSnapshot, ReadOptions } from "../chatTypes.js";
+export type MessageQuery = {
+    earlier?: boolean;
+    all?: boolean;
+    refresh?: boolean;
+};
+export type ReadersQuery = {
+    afterProfileId?: string;
+    revision?: number;
+};
+export type GroupChanges = {
+    expectedRevision?: string;
+    addMembers?: readonly string[];
+    removeMembers?: readonly string[];
+    title?: string;
+    avatar?: string;
+};
+export type SendOptions = {
+    waitFor?: "accepted" | "delivered";
+};
+export type SentMessage = Readonly<{
+    id: string;
+    timestamp: number;
+}>;
+type SubscribeOptions<T> = {
+    fields?: readonly (keyof T)[];
+    emitCurrent?: boolean;
+};
+/** App-facing API. Cache coverage, raw protocol and synchronization stay in advanced. */
+export declare class ChatEngine {
+    readonly advanced: ChatSession<CachedChatMessage>;
+    private options;
+    private groups;
+    private group;
+    private present;
+    private redactedQuotes;
+    private messageLists;
+    private messages;
+    private views;
+    private summary?;
+    private targets;
+    private errors;
+    private listeners;
+    private closed;
+    constructor(advanced: ChatSession<CachedChatMessage>, options: CreateChatOptions);
+    private operation;
+    private deny;
+    private threadOperation;
+    start(): Promise<void>;
+    /** Resolve a scoped ID locally, registering its target when needed. No remote group is created. */
+    resolveThreadId(target: ConversationTarget): Promise<string>;
+    /** A trusted recent window. Source selection and synchronization belong to the SDK. */
+    getThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    loadEarlier(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    refreshThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    private readForCaller;
+    private threadSubscribers;
+    private openQueue;
+    private opening;
+    private drainOpens;
+    /** Listen first, then open the local window; concurrent consumers share the initial read. */
+    subscribeThread(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    /** @deprecated Use resolveThreadId. Retained only for the migration window. */
+    getConversation(target: ConversationTarget): Promise<string>;
+    getSnapshot(): ChatSnapshot;
+    getSnapshot(threadId: string): ChatThreadSnapshot;
+    getMessages(threadId: string, query?: MessageQuery): Promise<ChatThreadSnapshot>;
+    sendMessage(threadId: string, content: OutgoingContent, options?: SendOptions): Promise<SentMessage>;
+    retryMessage(messageId: string): Promise<SentMessage>;
+    subscribe(listener: (snapshot: ChatSnapshot) => void, options?: SubscribeOptions<ChatSnapshot>): () => void;
+    subscribe(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    private sessionFields;
+    private notify;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<void>;
+    markRead(threadId: string): Promise<void>;
+    getReaders(threadId: string, messageId: string, page?: ReadersQuery, signal?: AbortSignal): Promise<import("../runtime/messageReaders.js").MessageReadersPage>;
+    watchReaders(threadId: string | undefined, ids: string[], receiver?: string): Promise<void>;
+    handleReach(event: Parameters<ChatSession<CachedChatMessage>["handleReach"]>[0]): Promise<"handled" | undefined>;
+    getVoiceAttachment(threadId: string, messageId: string): Promise<import("../runtime/durableSender.js").VoiceAttachmentLease>;
+    getGroup(threadId: string, options?: {
+        refresh?: boolean;
+    }): Promise<Readonly<{
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>>;
+    createGroup(input: {
+        groupId?: string;
+        title: string;
+        members: readonly string[];
+    }): Promise<{
+        threadId: string;
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>;
+    updateGroup(threadId: string, changes: GroupChanges): Promise<Readonly<{
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>>;
+    revokeAccess(): Promise<void>;
+    close(): Promise<void>;
+}