@athenaintel/react 0.13.0 → 0.14.0

package/dist/chat-ui/auth/sign-in-card.d.ts

@@ -0,0 +1,57 @@
+import type { FC, ReactNode } from "react";
+export declare const SignInCard: FC<{
+    /** e.g. "Local build abcd1234" — shown under the heading when set. */
+    buildLabel?: string | null;
+    subtitle?: ReactNode;
+    /** Environment pickers, consent checkboxes, and other host controls. */
+    children?: ReactNode;
+    error?: string | null;
+    /** Hint shown above the button (e.g. host cannot open a dialog). */
+    notice?: ReactNode;
+    primaryLabel: string;
+    primaryPendingLabel: string;
+    isPending: boolean;
+    disabled?: boolean;
+    onPrimary: () => void;
+    /** Developer fallbacks and other secondary affordances. */
+    footer?: ReactNode;
+}>;
+export declare const SignInSelect: FC<{
+    id: string;
+    label: string;
+    value: string;
+    options: ReadonlyArray<{
+        label: string;
+        value: string;
+    }>;
+    onChange: (value: string) => void;
+    /** Resolved endpoint shown under the select. */
+    hint?: string | null;
+}>;
+export declare const SignInTextField: FC<{
+    label: string;
+    placeholder?: string;
+    value: string;
+    onChange: (value: string) => void;
+    type?: "url" | "password" | "text";
+    className?: string;
+}>;
+/** Collapsible section under the primary button, for developer-only logins. */
+export declare const SignInFallbackSection: FC<{
+    isOpen: boolean;
+    onToggle: () => void;
+    label: string;
+    children: ReactNode;
+}>;
+/** Secondary button matching the fallback section's weight. */
+export declare const SignInSecondaryButton: FC<{
+    onClick: () => void;
+    disabled?: boolean;
+    children: ReactNode;
+}>;
+/** Checkbox + explanatory copy, used for host data-use disclosures. */
+export declare const SignInConsent: FC<{
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    children: ReactNode;
+}>;

package/dist/chat-ui/composer/composer-action.d.ts

@@ -0,0 +1,5 @@
+export type ComposerAction = "send" | "queue" | "stop";
+export declare function resolveComposerAction({ hasDraft, isRunning, }: {
+    hasDraft: boolean;
+    isRunning: boolean;
+}): ComposerAction;

package/dist/chat-ui/composer/pending-attachment-uploads.d.ts

@@ -0,0 +1,5 @@
+export declare class PendingAttachmentUploads {
+    private readonly pending;
+    track(upload: Promise<void>): Promise<void>;
+    waitForIdle(): Promise<void>;
+}

package/dist/chat-ui/composer/tiptap-composer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tiptap Composer — Full Olympus mention system integration
+ *
+ * Uses the ported Olympus infrastructure:
+ * - MentionSuggestionList (with scope navigation, breadcrumbs, keyboard nav)
+ * - MentionSuggestionPopup (Floating UI positioning)
+ * - MentionSuggestionsExtension (Tiptap @ trigger)
+ * - MentionExtension (inline mention chips)
+ * - useMentionSuggestions (full Olympus categories + async data)
+ *
+ * Auth credentials for GraphQL are provided via MentionAuthCtx, and the host
+ * app (Chrome side panel, Office task pane) supplies any host-only mention
+ * items — browser tabs, for instance — through `webpages`.
+ */
+import { type JSONContent } from "@tiptap/core";
+import { type MentionRootCategory } from "../mentions/suggestions/data/use-mention-suggestions";
+import type { WebpageMention } from "../mentions/suggestions/data/types";
+import { type UploadedChatAsset } from "@athenaintel/agent-runtime";
+/** Convert recovered runtime text without letting Tiptap parse it as HTML. */
+export declare function plainTextToTiptapContent(text: string): JSONContent;
+export interface TiptapComposerHandle {
+    submit: () => Promise<void>;
+    addAttachment: (file: File) => Promise<void>;
+    insertAssetMention: (asset: UploadedChatAsset) => void;
+}
+export interface TiptapComposerProps {
+    placeholder?: string;
+    threadId: string;
+    disabled?: boolean;
+    /** Host-provided browser-tab mentions; empty in hosts without tab access. */
+    webpages?: readonly WebpageMention[];
+    rootCategories?: readonly MentionRootCategory[];
+    onDraftStateChange?: (hasDraft: boolean) => void;
+}
+export declare const TiptapComposer: import("react").ForwardRefExoticComponent<TiptapComposerProps & import("react").RefAttributes<TiptapComposerHandle>>;

package/dist/chat-ui/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared Athena chat UI — the thread shell, the Tiptap composer, the `@`
+ * mention system and the mention chips used by the Chrome extension side
+ * panel and the Microsoft 365 task pane. Host-specific behaviour (browser
+ * tabs, screenshots, auth transports) is injected by the host rather than
+ * living here.
+ *
+ * Published as the `@athenaintel/react/chat-ui` sub-path.
+ */
+export { ChatThreadShell } from "./thread/chat-thread-shell";
+export type { ChatThreadMessageComponents, ChatThreadShellProps, } from "./thread/chat-thread-shell";
+export { ChatComposerDock } from "./thread/chat-composer-dock";
+export type { ChatComposerDockProps } from "./thread/chat-composer-dock";
+export { ComposerSendOrStop } from "./thread/composer-send-or-stop";
+export type { ComposerSendOrStopProps, ComposerStopControls, } from "./thread/composer-send-or-stop";
+export { TiptapComposer, plainTextToTiptapContent, type TiptapComposerHandle, type TiptapComposerProps, } from "./composer/tiptap-composer";
+export { PendingAttachmentUploads } from "./composer/pending-attachment-uploads";
+export { resolveComposerAction, type ComposerAction, } from "./composer/composer-action";
+export { MentionExtension, makeMentionUrl, parseMentionAnchorAttributes, } from "./mentions/mention-extension";
+export { MentionChip, MentionLink, normalizeAthenaMentionHtml, parseMentionUrl, parseMentionsInText, } from "./mentions/mention-chip";
+export { MentionSuggestionsExtension } from "./mentions/suggestions/mention-suggestions.extension";
+export { MentionSuggestionList } from "./mentions/suggestions/components/mention-suggestion-list";
+export { MentionSuggestionPopup } from "./mentions/suggestions/components/mention-suggestion-popup";
+export { MentionIcon } from "./mentions/suggestions/components/mention-icon";
+export { MenuList } from "./mentions/suggestions/components/menu-list";
+export { MentionAuthCtx, fetchGraphQL, SIMPLE_SEARCH_QUERY, useMentionAuth, type MentionAuthContext, } from "./mentions/suggestions/data/api-client";
+export { ROOT_MENTION_CATEGORIES, useMentionSuggestions, webpageMentionFingerprint, type MentionRootCategory, type MentionSuggestionsStore, } from "./mentions/suggestions/data/use-mention-suggestions";
+export { buildRootMenuItems } from "./mentions/suggestions/data/sources";
+export { assetTypeToIcon, assetTypeToThumb, configureAssetIconBasePath, } from "./mentions/suggestions/data/sources/asset-type-icons";
+export { MentionMenuSection, type MenuItem, type MenuScope, type WebpageMention, type WebpageMentionScope, } from "./mentions/suggestions/data/types";
+export { createOlympusAssetUrl } from "./lib/asset-urls";
+export { COMPOSER_DOCK_CLASS, COMPOSER_EDITOR_ROW_CLASS, COMPOSER_SURFACE_CLASS, COMPOSER_TOOLBAR_CLASS, BranchPicker, ComposerSendButton, ComposerStopButton, IconButton, MarkdownText, SmallIconButton, THREAD_HEADER_ACTIONS_CLASS, THREAD_HEADER_CLASS, THREAD_HEADER_ICON_CLASS, THREAD_HEADER_PILL_CLASS, THREAD_PANEL_CLASS, THREAD_SCROLL_TO_BOTTOM_CLASS, UserMessage, createAssistantMessage, type CreateAssistantMessageOptions, } from "./messages/message-components";
+export { TextShimmerLoader, ThreadRunningIndicator, } from "./messages/running-indicator";
+export { SignInCard, SignInConsent, SignInFallbackSection, SignInSecondaryButton, SignInSelect, SignInTextField, } from "./auth/sign-in-card";

package/dist/chat-ui/lib/asset-urls.d.ts

@@ -0,0 +1,6 @@
+/** Deep link into Spaces for one or more assets referenced from chat. */
+export declare function createOlympusAssetUrl({ appUrl, backendUrl, assetIds, }: {
+    appUrl?: string | null;
+    backendUrl?: string | null;
+    assetIds: string | string[];
+}): string | null;

package/dist/chat-ui/mentions/mention-chip.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Mention chip rendering for message display.
+ *
+ * Parses [@name](mention://type?...) markdown links and renders them
+ * as styled inline chips matching the Olympus mention style.
+ * Used in both user messages (inline text) and assistant messages (markdown links).
+ */
+import { type FC, type ReactElement, type ReactNode } from "react";
+/**
+ * Custom <a> renderer for MarkdownTextPrimitive.
+ * Intercepts mention:// links and renders them as chips.
+ * Falls through to a normal link for non-mention URLs.
+ */
+export declare const MentionLink: FC<{
+    href?: string;
+    children?: ReactNode;
+}>;
+export declare const MentionChip: FC<{
+    name: string;
+    type?: string;
+    assetIds?: string[];
+    thumbnailUrl?: string;
+    sourceHref?: string;
+}>;
+export declare function parseMentionUrl(url: string): {
+    type: string;
+    name: string;
+    id: string;
+    assetIds?: string[];
+    thumbnailUrl?: string;
+};
+/** Turn complete model-emitted URL citation anchors into safe Markdown links. */
+export declare function normalizeAthenaMentionHtml(text: string): string;
+/**
+ * Parse text containing [@name](mention://...) patterns into
+ * an array of string segments and MentionChip elements.
+ */
+export declare function parseMentionsInText(text: string): (string | ReactElement)[];

package/dist/chat-ui/mentions/mention-extension.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tiptap Mention Node Extension
+ *
+ * Defines the mention node type used in the editor. When a mention is
+ * inserted, it creates a non-editable inline node with metadata.
+ *
+ * Renders as a chip with: [icon] Name
+ */
+import { Node } from "@tiptap/core";
+export declare function makeMentionUrl(attrs: {
+    id: string;
+    type: string;
+    name: string;
+    title?: string;
+    url?: string;
+    description?: string;
+    thumbnailUrl?: string;
+    assetType?: string;
+}): string;
+export interface MentionNodeAttrs {
+    type: string;
+    name: string;
+    id: string;
+    title?: string;
+    url?: string;
+    description?: string;
+    thumbnailUrl?: string;
+    fallbackIcon?: string;
+    assetType?: string;
+}
+export declare function parseMentionAnchorAttributes({ href, textContent, }: {
+    href: string;
+    textContent: string | null;
+}): MentionNodeAttrs;
+export declare const MentionExtension: Node<any, any>;

package/dist/chat-ui/mentions/suggestions/components/get-scope-name.d.ts

@@ -0,0 +1,15 @@
+import type { MenuScope } from '../data/types';
+import type { MentionSuggestionsStore } from '../data/use-mention-suggestions';
+/**
+ * getScopeName - Get friendly display name for a scope
+ *
+ * Strategy:
+ * 1. Check known category names (fast path)
+ * 2. Look up dynamic item in cache (folders, assets, etc.)
+ * 3. Fall back to scope ID itself
+ *
+ * @param scope - The scope ID to look up
+ * @param store - The mention suggestions store (to access cache)
+ * @returns Friendly display name
+ */
+export declare function getScopeName(scope: MenuScope, store: MentionSuggestionsStore): string;

package/dist/chat-ui/mentions/suggestions/components/mention-icon.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mention icon component.
+ * Maps string icon names to Lucide icon components.
+ */
+export declare function MentionIcon({ fallbackIcon, thumbnailUrl, alt, className, }: {
+    fallbackIcon?: string;
+    thumbnailUrl?: string;
+    alt?: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/chat-ui/mentions/suggestions/components/mention-suggestion-list.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MentionSuggestionList — Main mention menu component.
+ *
+ * Composed of:
+ * - Registry + cache backed data (async fetching)
+ * - useMenuNavigation for scope stack management
+ * - useKeyboardNavigation for keyboard handling
+ * - MenuList for item rendering with loading states
+ * - MenuSummary for breadcrumbs + back
+ */
+import type { Editor } from "@tiptap/core";
+import type { MenuItem } from "../data/types";
+import type { MentionSuggestionsStore } from "../data/use-mention-suggestions";
+import { type KeyboardNavigationHandle } from "./use-keyboard-navigation";
+export interface MentionSuggestionListProps {
+    store: MentionSuggestionsStore;
+    editor: Editor;
+    query: string;
+    command: (item: MenuItem) => void;
+    closeMenu: (dismissedByUser?: boolean) => void;
+}
+export declare const MentionSuggestionList: import("react").ForwardRefExoticComponent<MentionSuggestionListProps & import("react").RefAttributes<KeyboardNavigationHandle>>;

package/dist/chat-ui/mentions/suggestions/components/mention-suggestion-popup.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Floating popup wrapper for the mention suggestion menu.
+ * Uses Floating UI for positioning near the cursor.
+ */
+import { type FC, type ReactNode } from "react";
+export declare const MentionSuggestionPopup: FC<{
+    clientRect: (() => DOMRect | null) | null;
+    children: ReactNode;
+}>;

package/dist/chat-ui/mentions/suggestions/components/menu-breadcrumbs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Breadcrumb navigation for the mention menu.
+ */
+export declare function MenuBreadcrumbs({ scopePath, onNavigate, }: {
+    scopePath: {
+        id: string;
+        name: string;
+    }[];
+    onNavigate: (scopeId: string) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/chat-ui/mentions/suggestions/components/menu-item.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Individual menu item in the mention popup.
+ * Supports: tools (with description), users (with email), assets, categories.
+ */
+import type { MenuItem } from "../data/types";
+export declare function MenuItemRow({ item, isSelected, onMouseEnter, onClick, showArrow, }: {
+    item: MenuItem;
+    isSelected: boolean;
+    onMouseEnter: () => void;
+    onClick: () => void;
+    showArrow?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/chat-ui/mentions/suggestions/components/menu-list.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Scrollable list of menu items with loading and empty states.
+ */
+import { type MenuItem } from "../data/types";
+export declare function MenuList({ items, selectedIndex, isLoading, hasMore, onSelect, onMouseEnter, onLoadMore, }: {
+    items: MenuItem[];
+    selectedIndex: number;
+    isLoading?: boolean;
+    hasMore?: boolean;
+    onSelect: (item: MenuItem) => void;
+    onMouseEnter: (index: number) => void;
+    onLoadMore?: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/chat-ui/mentions/suggestions/components/menu-skeleton.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Loading skeleton for the mention menu.
+ */
+export declare function MenuSkeleton(): import("react/jsx-runtime").JSX.Element;

package/dist/chat-ui/mentions/suggestions/components/menu-summary.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Summary bar at the bottom of the mention menu.
+ * Shows breadcrumbs + back button + optional loading spinner.
+ */
+export declare function MenuSummary({ scopePath, onNavigate, onBackClick, isFetching, }: {
+    scopePath: {
+        id: string;
+        name: string;
+    }[];
+    onNavigate: (scopeId: string) => void;
+    onBackClick?: () => void;
+    isFetching?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/chat-ui/mentions/suggestions/components/use-keyboard-navigation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keyboard navigation for the mention menu.
+ *
+ * Exposes an imperative handle so MentionSuggestionList can forward keystrokes
+ * from the editor into the menu.
+ */
+import type { ForwardedRef } from "react";
+import type { MenuItem } from "../data/types";
+export interface KeyboardNavigationHandle {
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+export declare function useKeyboardNavigation(ref: ForwardedRef<KeyboardNavigationHandle>, opts: {
+    items: MenuItem[];
+    selectedIndex: number;
+    setSelectedIndex: (index: number) => void;
+    onSelect: (item: MenuItem) => void;
+    onBack?: () => void;
+    onClose: () => void;
+}): void;

package/dist/chat-ui/mentions/suggestions/components/use-menu-navigation.d.ts

@@ -0,0 +1,64 @@
+import { Store } from '@tanstack/store';
+import type { MenuScope } from '../data/types';
+/**
+ * Stack entry with scope and selected item position
+ *
+ * When navigating forward, we save the current selectedIndex so we can restore
+ * it when navigating back (like browser history).
+ */
+export interface ScopeStackEntry {
+    scope: MenuScope;
+    selectedIndex: number;
+    breadcrumbLabel?: string;
+    parentScope?: MenuScope;
+}
+/**
+ * Menu navigation state - tracks current navigation context
+ *
+ * This is the "current UI state" that changes as user navigates and types.
+ * Cleared when menu opens/closes.
+ *
+ * Uses a navigation stack for proper back button behavior:
+ * - Forward navigation: push to stack (with current selectedIndex)
+ * - Back navigation: pop from stack (restore selectedIndex)
+ * - Current scope: last item in stack
+ * - Parent scope: second-to-last item in stack
+ */
+export interface MenuNavigationState {
+    scopeStack: ScopeStackEntry[];
+    query: string;
+    isActive: boolean;
+}
+/**
+ * Menu navigation store with helper methods
+ */
+export interface MenuNavigationStore extends Store<MenuNavigationState> {
+    navigateTo: (scope: MenuScope, currentSelectedIndex: number, options?: {
+        breadcrumbLabel?: string;
+        parentScope?: MenuScope;
+    }) => void;
+    navigateBack: () => void;
+    setQuery: (query: string) => void;
+    open: () => void;
+    close: () => void;
+}
+/**
+ * Get current scope from state
+ */
+export declare function getCurrentScope(state: MenuNavigationState): MenuScope;
+/**
+ * Get parent scope from state (for source inheritance)
+ */
+export declare function getParentScope(state: MenuNavigationState): MenuScope | undefined;
+/**
+ * Get selected index from current scope stack entry
+ */
+export declare function getSelectedIndex(state: MenuNavigationState): number;
+/**
+ * useMenuNavigation - Creates per-editor navigation state
+ *
+ * This is a UI concern - each editor instance gets its own navigation state.
+ *
+ * Returns a TanStack Store with navigation helper methods.
+ */
+export declare function useMenuNavigation(): MenuNavigationStore;

package/dist/chat-ui/mentions/suggestions/components/utils.d.ts

@@ -0,0 +1,8 @@
+import type { Editor } from '@tiptap/core';
+/**
+ * Clear text after @ trigger
+ *
+ * When navigating in the menu, we want to clear the typed query
+ * but keep the @ trigger symbol.
+ */
+export declare function clearTextAfterTrigger(editor: Editor): void;

package/dist/chat-ui/mentions/suggestions/data/api-client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * API client for mention data fetching.
+ *
+ * Wraps raw fetch() with GraphQL support. Hosts authenticate with either a
+ * bearer token (Chrome extension) or a workspace API key (Microsoft 365
+ * add-in); agora's /graphql accepts both.
+ */
+export interface MentionAuthContext {
+    backendUrl: string;
+    appUrl?: string;
+    /** Bearer credential; hosts without one authenticate with `apiKey`. */
+    accessToken?: string;
+    apiKey?: string;
+    workspaceId?: string;
+    userId?: string;
+}
+export declare const MentionAuthCtx: import("react").Context<MentionAuthContext | null>;
+export declare function useMentionAuth(): MentionAuthContext;
+export declare function fetchGraphQL<T = any>(auth: MentionAuthContext, query: string, variables?: Record<string, any>): Promise<T>;
+export declare const SIMPLE_SEARCH_QUERY = "\n  query SimpleSearch($input: SimpleSearchRequestInput!) {\n    simpleSearch(input: $input) {\n      assets {\n        \n  id\n  title\n  athenaOriginalType\n  athenaConvertedType\n  parentFolderId\n  updatedAt\n  isFavorited\n  isArchived\n  isHidden\n\n      }\n      totalCount\n    }\n  }\n";
+export declare const PAGINATED_ASSETS_QUERY = "\n  query GetPaginatedAssetsForWorkspace(\n    $limit: Int!\n    $offset: Int!\n    $parentFolderId: String\n    $filterTypes: [String!]\n    $filterColumns: ColumnFilter\n  ) {\n    getPaginatedAssetsForWorkspace(\n      limit: $limit\n      offset: $offset\n      parentFolderId: $parentFolderId\n      filterTypes: $filterTypes\n      filterColumns: $filterColumns\n    ) {\n      \n  id\n  title\n  athenaOriginalType\n  athenaConvertedType\n  parentFolderId\n  updatedAt\n  isFavorited\n  isArchived\n  isHidden\n\n    }\n  }\n";
+export declare const WORKSPACE_MEMBERS_QUERY = "\n  query GetUsersInWorkspace($workspaceId: String!) {\n    getUsersInWorkspace(workspaceId: $workspaceId) {\n      id\n      email\n      firstName\n      lastName\n      isAdmin\n      avatarUrl\n    }\n  }\n";
+export interface AssetResult {
+    id: string;
+    title: string | null;
+    athenaOriginalType: string | null;
+    athenaConvertedType: string | null;
+    parentFolderId: string | null;
+    updatedAt: string | null;
+    isFavorited: boolean | null;
+    isArchived: boolean | null;
+    isHidden: boolean | null;
+}
+export interface WorkspaceMember {
+    id: string;
+    email: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    isAdmin: boolean;
+    avatarUrl: string | null;
+}

package/dist/chat-ui/mentions/suggestions/data/item-cache.d.ts

@@ -0,0 +1,76 @@
+import type { MenuItem, MenuScope } from './types';
+/**
+ * Item Cache
+ *
+ * Plain object + pure functions for caching menu items.
+ * Deduplicates by ID, handles renames/updates automatically.
+ */
+/**
+ * Item cache - plain object
+ * Stores all fetched items
+ */
+export interface ItemCache {
+    items: Record<string, MenuItem>;
+}
+/**
+ * Create empty cache
+ */
+export declare function createItemCache(): ItemCache;
+/**
+ * Add items to cache with scope tagging (mutates cache)
+ *
+ * Multi-scope system:
+ * - If item exists: ADD scope to existing scopes, update fields
+ * - If item new: Create with single scope
+ *
+ * Deduplication by ID:
+ * - ✅ Handles renames: Same ID, new name → updates name, adds scope
+ * - ✅ Handles multi-membership: Same ID → adds new scope without removing old ones
+ * - ✅ Handles updates: Same ID, new data → updates data, adds scope
+ * - ❌ Does NOT handle deletions: Use clearByScope() to remove stale data
+ *
+ * @param cache - Cache to mutate
+ * @param items - Items to add (without visibleInScopes set)
+ * @param scope - Scope to tag these items with
+ */
+export declare function addItems(cache: ItemCache, items: MenuItem[], scope: MenuScope): void;
+/**
+ * Get all items (read-only)
+ */
+export declare function getAllItems(cache: ItemCache): MenuItem[];
+/**
+ * Get filtered items by scope (read-only, no fetching)
+ *
+ * @param cache - Cache to read from
+ * @param scope - Current scope to filter by
+ * @param query - Search query
+ * @returns Filtered items from cache that belong to this scope
+ */
+export declare function getFilteredItems(cache: ItemCache, scope: MenuScope, query: string): MenuItem[];
+/**
+ * Clear all items
+ */
+export declare function clearCache(cache: ItemCache): void;
+/**
+ * Clear scope from all items (mutates cache)
+ * Used for invalidation when dynamic data changes
+ *
+ * Items lose the scope but stay in cache if they have other scopes.
+ * Only remove items completely if they have no scopes left.
+ *
+ * @param cache - Cache to mutate
+ * @param scope - Scope to remove from all items
+ */
+export declare function clearByScope(cache: ItemCache, scope: MenuScope): void;
+/**
+ * Remove specific item
+ */
+export declare function removeItem(cache: ItemCache, itemId: string): void;
+/**
+ * Get item by ID
+ */
+export declare function getItem(cache: ItemCache, itemId: string): MenuItem | undefined;
+/**
+ * Check if item belongs to a scope
+ */
+export declare function hasScope(item: MenuItem, scope: MenuScope): boolean;

package/dist/chat-ui/mentions/suggestions/data/orchestrator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Mention Orchestrator — Async data fetching with registry + cache.
+ *
+ * selectItems (pure read) + triggerFetchIfNeeded (async fetch).
+ */
+import type { MenuItem, MenuScope } from "./types";
+import type { MentionSuggestionsStore } from "./use-mention-suggestions";
+/**
+ * Select items for a given scope + query from the cache.
+ * Pure, synchronous read — no side effects.
+ */
+export declare function selectItems(store: MentionSuggestionsStore, scope: MenuScope | {
+    id: string;
+}, query: string, _targetCount?: number, parentScope?: MenuScope | {
+    id: string;
+}): {
+    items: MenuItem[];
+    isFetching: boolean;
+    hasMore: boolean;
+};
+/**
+ * Trigger an async fetch if needed.
+ * Called by useMenuItems when cache < target AND hasMore AND !fetching.
+ */
+export declare function triggerFetchIfNeeded(store: MentionSuggestionsStore, scope: MenuScope | {
+    id: string;
+}, query: string, _targetCount?: number, parentScope?: MenuScope | {
+    id: string;
+}): void;