@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/dist/unstable/useComposerInputHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComposerInputHistory.js","names":[],"sources":["../../src/unstable/useComposerInputHistory.ts"],"sourcesContent":["\"use client\";\n\nimport { nextTick } from \"vue\";\nimport { useIsomorphicLayoutEffect } from \"@ulearning/ai-store/internal\";\nimport { useAui } from \"@ulearning/ai-store\";\nimport { flushTapSync } from \"@ulearning/ai-tap\";\nimport type { ThreadMessage } from \"@ulearning/ai-core\";\nimport { getThreadMessageText } from \"@ulearning/ai-core/internal\";\nimport { useTriggerPopoverRootContextOptional } from \"../primitives/composer/trigger/TriggerPopoverRootContext\";\n\n/** @deprecated Experimental since 2026-06-11. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_ComposerInputHistory = {\n  /** Keydown handler to spread onto `ComposerPrimitive.Input`. */\n  onKeyDown: (event: KeyboardEvent) => void;\n};\n\ntype BrowseState = {\n  cursor: number;\n  draftSnapshot: string;\n  lastRecalledText: string;\n};\n\nconst deriveHistory = (messages: readonly ThreadMessage[]): string[] => {\n  const entries: string[] = [];\n  for (let i = messages.length - 1; i >= 0; i--) {\n    const message = messages[i]!;\n    if (message.role !== \"user\") continue;\n    const text = getThreadMessageText(message).trim();\n    if (!text) continue;\n    if (entries[entries.length - 1] === text) continue;\n    entries.push(text);\n  }\n  return entries;\n};\n\nconst isOnFirstLine = (value: string, caret: number): boolean =>\n  !value.slice(0, caret).includes(\"\\n\");\n\nconst isOnLastLine = (value: string, caret: number): boolean =>\n  !value.slice(caret).includes(\"\\n\");\n\n/**\n * Terminal-style input history for the thread composer: ArrowUp on an\n * empty draft recalls previously sent user messages (newest first),\n * ArrowDown steps back toward the newest and finally restores the draft\n * that was being typed when browsing started.\n *\n * Recall only triggers when the caret is on the first/last line with no\n * selection, so multi-line editing keeps native arrow behavior. The\n * handler yields to an open mention/slash popover, to IME composition,\n * to modifier keys, and to consumer handlers that already called\n * `preventDefault`. It is inert on edit composers.\n *\n * @deprecated Experimental since 2026-06-11. Not scheduled for removal; the API may change in any release.\n *\n * @example\n * ```tsx\n * const history = unstable_useComposerInputHistory();\n * <ComposerPrimitive.Input {...history} />\n * ```\n */\nexport function unstable_useComposerInputHistory(): Unstable_ComposerInputHistory {\n  const aui = useAui();\n  const popoverCtx = useTriggerPopoverRootContextOptional();\n  const browseRef: { current: BrowseState | null } = { current: null };\n  let generation = 0;\n\n  useIsomorphicLayoutEffect(() => {\n    if (aui.composer.getState().type !== \"thread\" || !aui.optional.threads)\n      return undefined;\n\n    return aui.on(\"threads.selectionChanged\", () => {\n      generation++;\n      browseRef.current = null;\n    });\n  }, []);\n  useIsomorphicLayoutEffect(\n    () => () => {\n      generation++;\n      browseRef.current = null;\n    },\n    [],\n  );\n\n  const onKeyDown = (e: KeyboardEvent) => {\n    if (e.defaultPrevented) return;\n    if (e.key !== \"ArrowUp\" && e.key !== \"ArrowDown\") return;\n    if (e.isComposing || e.keyCode === 229) return;\n    if (e.shiftKey || e.ctrlKey || e.metaKey || e.altKey) return;\n    if (popoverCtx && popoverCtx.getActiveAria() !== null) return;\n    if (aui.composer.getState().type !== \"thread\") return;\n\n    const textarea = e.currentTarget;\n    if (!(textarea instanceof HTMLTextAreaElement)) return;\n    const { selectionStart, selectionEnd, value } = textarea;\n    if (selectionStart !== selectionEnd) return;\n\n    if (browseRef.current && value !== browseRef.current.lastRecalledText) {\n      browseRef.current = null;\n    }\n    const browse = browseRef.current;\n\n    const commitText = (text: string): void => {\n      flushTapSync(() => aui.composer.setText(text, { origin: \"recall\" }));\n      const owner = generation;\n      void nextTick(() => {\n        if (owner === generation && textarea.isConnected)\n          textarea.setSelectionRange(text.length, text.length);\n      });\n      e.preventDefault();\n    };\n\n    const recall = (\n      history: readonly string[],\n      cursor: number,\n      draftSnapshot: string,\n    ): void => {\n      const entry = history[cursor];\n      if (entry === undefined) {\n        e.preventDefault();\n        return;\n      }\n      browseRef.current = { cursor, draftSnapshot, lastRecalledText: entry };\n      commitText(entry);\n    };\n\n    if (e.key === \"ArrowUp\") {\n      if (!isOnFirstLine(value, selectionStart)) return;\n\n      if (!browse) {\n        if (value.trim() !== \"\") return;\n        const history = deriveHistory(aui.thread.getState().messages);\n        if (history.length === 0) return;\n        recall(history, 0, value);\n        return;\n      }\n\n      const history = deriveHistory(aui.thread.getState().messages);\n      const next = browse.cursor + 1;\n      if (next >= history.length) {\n        e.preventDefault();\n        return;\n      }\n      recall(history, next, browse.draftSnapshot);\n      return;\n    }\n\n    if (!browse) return;\n    if (!isOnLastLine(value, selectionEnd)) return;\n\n    const next = browse.cursor - 1;\n    if (next < 0) {\n      browseRef.current = null;\n      commitText(browse.draftSnapshot);\n      return;\n    }\n\n    const history = deriveHistory(aui.thread.getState().messages);\n    recall(history, next, browse.draftSnapshot);\n  };\n\n  return { onKeyDown };\n}\n"],"mappings":";;;;;;;;AAsBA,MAAM,iBAAiB,aAAiD;CACtE,MAAM,UAAoB,CAAC;CAC3B,KAAK,IAAI,IAAI,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK;EAC7C,MAAM,UAAU,SAAS;EACzB,IAAI,QAAQ,SAAS,QAAQ;EAC7B,MAAM,OAAO,qBAAqB,OAAO,CAAC,CAAC,KAAK;EAChD,IAAI,CAAC,MAAM;EACX,IAAI,QAAQ,QAAQ,SAAS,OAAO,MAAM;EAC1C,QAAQ,KAAK,IAAI;CACnB;CACA,OAAO;AACT;AAEA,MAAM,iBAAiB,OAAe,UACpC,CAAC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,SAAS,IAAI;AAEtC,MAAM,gBAAgB,OAAe,UACnC,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,IAAI;;;;;;;;;;;;;;;;;;;;;AAsBnC,SAAgB,mCAAkE;CAChF,MAAM,MAAM,OAAO;CACnB,MAAM,aAAa,qCAAqC;CACxD,MAAM,YAA6C,EAAE,SAAS,KAAK;CACnE,IAAI,aAAa;CAEjB,gCAAgC;EAC9B,IAAI,IAAI,SAAS,SAAS,CAAC,CAAC,SAAS,YAAY,CAAC,IAAI,SAAS,SAC7D,OAAO,KAAA;EAET,OAAO,IAAI,GAAG,kCAAkC;GAC9C;GACA,UAAU,UAAU;EACtB,CAAC;CACH,GAAG,CAAC,CAAC;CACL,sCACc;EACV;EACA,UAAU,UAAU;CACtB,GACA,CAAC,CACH;CAEA,MAAM,aAAa,MAAqB;EACtC,IAAI,EAAE,kBAAkB;EACxB,IAAI,EAAE,QAAQ,aAAa,EAAE,QAAQ,aAAa;EAClD,IAAI,EAAE,eAAe,EAAE,YAAY,KAAK;EACxC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ;EACtD,IAAI,cAAc,WAAW,cAAc,MAAM,MAAM;EACvD,IAAI,IAAI,SAAS,SAAS,CAAC,CAAC,SAAS,UAAU;EAE/C,MAAM,WAAW,EAAE;EACnB,IAAI,EAAE,oBAAoB,sBAAsB;EAChD,MAAM,EAAE,gBAAgB,cAAc,UAAU;EAChD,IAAI,mBAAmB,cAAc;EAErC,IAAI,UAAU,WAAW,UAAU,UAAU,QAAQ,kBACnD,UAAU,UAAU;EAEtB,MAAM,SAAS,UAAU;EAEzB,MAAM,cAAc,SAAuB;GACzC,mBAAmB,IAAI,SAAS,QAAQ,MAAM,EAAE,QAAQ,SAAS,CAAC,CAAC;GACnE,MAAM,QAAQ;GACd,eAAoB;IAClB,IAAI,UAAU,cAAc,SAAS,aACnC,SAAS,kBAAkB,KAAK,QAAQ,KAAK,MAAM;GACvD,CAAC;GACD,EAAE,eAAe;EACnB;EAEA,MAAM,UACJ,SACA,QACA,kBACS;GACT,MAAM,QAAQ,QAAQ;GACtB,IAAI,UAAU,KAAA,GAAW;IACvB,EAAE,eAAe;IACjB;GACF;GACA,UAAU,UAAU;IAAE;IAAQ;IAAe,kBAAkB;GAAM;GACrE,WAAW,KAAK;EAClB;EAEA,IAAI,EAAE,QAAQ,WAAW;GACvB,IAAI,CAAC,cAAc,OAAO,cAAc,GAAG;GAE3C,IAAI,CAAC,QAAQ;IACX,IAAI,MAAM,KAAK,MAAM,IAAI;IACzB,MAAM,UAAU,cAAc,IAAI,OAAO,SAAS,CAAC,CAAC,QAAQ;IAC5D,IAAI,QAAQ,WAAW,GAAG;IAC1B,OAAO,SAAS,GAAG,KAAK;IACxB;GACF;GAEA,MAAM,UAAU,cAAc,IAAI,OAAO,SAAS,CAAC,CAAC,QAAQ;GAC5D,MAAM,OAAO,OAAO,SAAS;GAC7B,IAAI,QAAQ,QAAQ,QAAQ;IAC1B,EAAE,eAAe;IACjB;GACF;GACA,OAAO,SAAS,MAAM,OAAO,aAAa;GAC1C;EACF;EAEA,IAAI,CAAC,QAAQ;EACb,IAAI,CAAC,aAAa,OAAO,YAAY,GAAG;EAExC,MAAM,OAAO,OAAO,SAAS;EAC7B,IAAI,OAAO,GAAG;GACZ,UAAU,UAAU;GACpB,WAAW,OAAO,aAAa;GAC/B;EACF;EAGA,OADgB,cAAc,IAAI,OAAO,SAAS,CAAC,CAAC,QACvC,GAAG,MAAM,OAAO,aAAa;CAC5C;CAEA,OAAO,EAAE,UAAU;AACrB"}

package/dist/unstable/useLiveCompletionAdapter.d.ts

@@ -0,0 +1,52 @@
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+import type { Unstable_TriggerAdapter, Unstable_TriggerItem } from "@ulearning/ai-core";
+/** @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_UseLiveCompletionAdapterOptions = {
+    /**
+     * Fetches the items for a query from an async source. Called debounced; the
+     * resolved items are cached and returned synchronously to the popover on the
+     * next render.
+     */
+    readonly fetcher: (query: string) => Promise<readonly Unstable_TriggerItem[]>;
+    /**
+     * Identifies the fetcher's data source. Change this when switching accounts,
+     * workspaces, or another boundary that should invalidate cached results.
+     */
+    readonly cacheKey?: string | number | undefined;
+    /** Debounce applied before a fetch fires, in milliseconds. @default 60 */
+    readonly debounceMs?: number | undefined;
+    /** When `false`, no fetch is scheduled and the adapter stays empty. @default true */
+    readonly enabled?: boolean | undefined;
+};
+/**
+ * Bridges an async completion source (a server search, a gateway RPC) into the
+ * synchronous `Unstable_TriggerAdapter` that `ComposerTriggerPopover` consumes.
+ * `search(query)` returns the last fetched items synchronously and schedules a
+ * debounced fetch when the query changes; when results arrive the returned
+ * `adapter` identity changes, which re-runs the popover's lookup so the fresh
+ * items render. This is a search-only adapter (`categories` are empty).
+ *
+ * `isLoading` is `true` while a fetch is in flight. Pass it to the popover's
+ * `isLoading` prop to render a loading state.
+ *
+ * @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const mentions = unstable_useLiveCompletionAdapter({
+ *   fetcher: (query) => searchUsers(query),
+ * });
+ *
+ * <ComposerTriggerPopover
+ *   char="@"
+ *   adapter={mentions.adapter}
+ *   isLoading={mentions.isLoading}
+ *   directive={{ onInserted }}
+ * />
+ * ```
+ */
+export declare function unstable_useLiveCompletionAdapter(options: MaybeRefOrGetter<Unstable_UseLiveCompletionAdapterOptions>): ComputedRef<{
+    adapter: Unstable_TriggerAdapter;
+    isLoading: boolean;
+}>;
+//# sourceMappingURL=useLiveCompletionAdapter.d.ts.map

package/dist/unstable/useLiveCompletionAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveCompletionAdapter.d.ts","mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,KAAK;AAEZ,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,oBAAoB;AAE3B;AACA,MAAM,MAAM,wCAAwC,GAAG;IACrD;;;;;IAKA,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC;IAC7E;;;;IAIA,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAC/C;IACA,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS;IACxC;IACA,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS;CACvC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,gBAAgB,CAAC,wCAAwC,CAAC,GAClE,WAAW,CAAC;IAAE,OAAO,EAAE,uBAAuB;IAAE,SAAS,EAAE,OAAO;CAAE,CAAC","names":[],"ignoreList":[],"sources":["../../src/unstable/useLiveCompletionAdapter.ts"],"sourcesContent":[null]}

package/dist/unstable/useLiveCompletionAdapter.js

@@ -0,0 +1,184 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect.js";
+import { computed, shallowRef, toValue } from "vue";
+// src/unstable/useLiveCompletionAdapter.ts
+/** Sentinel that no real query (including the empty string) equals, so the first query always fetches. */
+const NO_QUERY = "\0";
+/**
+* Bridges an async completion source (a server search, a gateway RPC) into the
+* synchronous `Unstable_TriggerAdapter` that `ComposerTriggerPopover` consumes.
+* `search(query)` returns the last fetched items synchronously and schedules a
+* debounced fetch when the query changes; when results arrive the returned
+* `adapter` identity changes, which re-runs the popover's lookup so the fresh
+* items render. This is a search-only adapter (`categories` are empty).
+*
+* `isLoading` is `true` while a fetch is in flight. Pass it to the popover's
+* `isLoading` prop to render a loading state.
+*
+* @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release.
+*
+* @example
+* ```tsx
+* const mentions = unstable_useLiveCompletionAdapter({
+*   fetcher: (query) => searchUsers(query),
+* });
+*
+* <ComposerTriggerPopover
+*   char="@"
+*   adapter={mentions.adapter}
+*   isLoading={mentions.isLoading}
+*   directive={{ onInserted }}
+* />
+* ```
+*/
+function unstable_useLiveCompletionAdapter(options) {
+	const initial = toValue(options);
+	const state = shallowRef({
+		query: NO_QUERY,
+		items: [],
+		failed: false
+	});
+	const isLoading = shallowRef(false);
+	const enabled = computed(() => toValue(options).enabled ?? true);
+	let fetcher = initial.fetcher;
+	let committedEnabled = initial.enabled ?? true;
+	let debounceMs = initial.debounceMs ?? 60;
+	let cacheKey = initial.cacheKey;
+	let timer = null;
+	let token = 0;
+	let pendingQuery = null;
+	let retryableQuery = null;
+	let pendingRetryQuery = null;
+	let inactive = true;
+	let deferredQuery = null;
+	const cancelTimer = () => {
+		if (timer !== null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+	const rearmPendingRetry = () => {
+		if (pendingRetryQuery === null) return;
+		retryableQuery = pendingRetryQuery;
+		pendingRetryQuery = null;
+	};
+	const invalidatePending = () => {
+		rearmPendingRetry();
+		cancelTimer();
+		pendingQuery = null;
+		token++;
+		isLoading.value = false;
+	};
+	const scheduleFetch = (query) => {
+		if (!committedEnabled) return;
+		if (inactive) {
+			deferredQuery = query;
+			return;
+		}
+		if (pendingQuery === query) return;
+		rearmPendingRetry();
+		if (retryableQuery === query) {
+			retryableQuery = null;
+			pendingRetryQuery = query;
+		}
+		pendingQuery = query;
+		cancelTimer();
+		const requestToken = ++token;
+		isLoading.value = true;
+		timer = setTimeout(() => {
+			timer = null;
+			Promise.resolve().then(() => fetcher(query)).then((items) => {
+				if (requestToken !== token) return;
+				pendingRetryQuery = null;
+				state.value = {
+					query,
+					items,
+					failed: false
+				};
+				isLoading.value = false;
+			}, () => {
+				if (requestToken !== token) return;
+				pendingQuery = null;
+				pendingRetryQuery = null;
+				state.value = {
+					query,
+					items: [],
+					failed: true
+				};
+				isLoading.value = false;
+			});
+		}, debounceMs);
+	};
+	const commitConfiguration = () => {
+		const current = toValue(options);
+		fetcher = current.fetcher;
+		committedEnabled = current.enabled ?? true;
+		debounceMs = current.debounceMs ?? 60;
+		if (cacheKey !== current.cacheKey) {
+			cacheKey = current.cacheKey;
+			invalidatePending();
+			retryableQuery = null;
+			pendingRetryQuery = null;
+			state.value = {
+				query: NO_QUERY,
+				items: [],
+				failed: false
+			};
+		}
+		if (!committedEnabled) {
+			invalidatePending();
+			if (state.value.query !== NO_QUERY) state.value = {
+				query: NO_QUERY,
+				items: [],
+				failed: false
+			};
+		}
+	};
+	useIsomorphicLayoutEffect(commitConfiguration, () => {
+		const current = toValue(options);
+		return [
+			current.fetcher,
+			current.cacheKey,
+			current.enabled,
+			current.debounceMs
+		];
+	});
+	useIsomorphicLayoutEffect(() => {
+		commitConfiguration();
+		inactive = false;
+		const query = deferredQuery;
+		deferredQuery = null;
+		if (query !== null) scheduleFetch(query);
+		return () => {
+			inactive = true;
+			invalidatePending();
+		};
+	}, []);
+	useIsomorphicLayoutEffect(() => {
+		retryableQuery = state.value.failed ? state.value.query : null;
+	}, () => [state.value]);
+	const adapter = computed(() => {
+		const active = enabled.value;
+		const snapshot = state.value;
+		return {
+			categories: () => [],
+			categoryItems: () => [],
+			search: (query) => {
+				if (!active) return [];
+				if (query !== snapshot.query || retryableQuery === query) queueMicrotask(() => scheduleFetch(query));
+				else queueMicrotask(() => {
+					if (deferredQuery !== null && deferredQuery !== query) deferredQuery = null;
+					if (pendingQuery !== null && pendingQuery !== query) invalidatePending();
+				});
+				return snapshot.items;
+			}
+		};
+	});
+	return computed(() => ({
+		adapter: adapter.value,
+		isLoading: isLoading.value
+	}));
+}
+export { unstable_useLiveCompletionAdapter };
+
+//# sourceMappingURL=useLiveCompletionAdapter.js.map

package/dist/unstable/useLiveCompletionAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveCompletionAdapter.js","names":[],"sources":["../../src/unstable/useLiveCompletionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  computed,\n  shallowRef,\n  toValue,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n} from \"vue\";\nimport { useIsomorphicLayoutEffect } from \"../utils/useIsomorphicLayoutEffect\";\nimport type {\n  Unstable_TriggerAdapter,\n  Unstable_TriggerItem,\n} from \"@ulearning/ai-core\";\n\n/** @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_UseLiveCompletionAdapterOptions = {\n  /**\n   * Fetches the items for a query from an async source. Called debounced; the\n   * resolved items are cached and returned synchronously to the popover on the\n   * next render.\n   */\n  readonly fetcher: (query: string) => Promise<readonly Unstable_TriggerItem[]>;\n  /**\n   * Identifies the fetcher's data source. Change this when switching accounts,\n   * workspaces, or another boundary that should invalidate cached results.\n   */\n  readonly cacheKey?: string | number | undefined;\n  /** Debounce applied before a fetch fires, in milliseconds. @default 60 */\n  readonly debounceMs?: number | undefined;\n  /** When `false`, no fetch is scheduled and the adapter stays empty. @default true */\n  readonly enabled?: boolean | undefined;\n};\n\n/** Sentinel that no real query (including the empty string) equals, so the first query always fetches. */\nconst NO_QUERY = \"\\u0000\";\n\n/**\n * Bridges an async completion source (a server search, a gateway RPC) into the\n * synchronous `Unstable_TriggerAdapter` that `ComposerTriggerPopover` consumes.\n * `search(query)` returns the last fetched items synchronously and schedules a\n * debounced fetch when the query changes; when results arrive the returned\n * `adapter` identity changes, which re-runs the popover's lookup so the fresh\n * items render. This is a search-only adapter (`categories` are empty).\n *\n * `isLoading` is `true` while a fetch is in flight. Pass it to the popover's\n * `isLoading` prop to render a loading state.\n *\n * @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release.\n *\n * @example\n * ```tsx\n * const mentions = unstable_useLiveCompletionAdapter({\n *   fetcher: (query) => searchUsers(query),\n * });\n *\n * <ComposerTriggerPopover\n *   char=\"@\"\n *   adapter={mentions.adapter}\n *   isLoading={mentions.isLoading}\n *   directive={{ onInserted }}\n * />\n * ```\n */\nexport function unstable_useLiveCompletionAdapter(\n  options: MaybeRefOrGetter<Unstable_UseLiveCompletionAdapterOptions>,\n): ComputedRef<{ adapter: Unstable_TriggerAdapter; isLoading: boolean }> {\n  const initial = toValue(options);\n  const state = shallowRef<{\n    query: string;\n    items: readonly Unstable_TriggerItem[];\n    failed: boolean;\n  }>({ query: NO_QUERY, items: [], failed: false });\n  const isLoading = shallowRef(false);\n  const enabled = computed(() => toValue(options).enabled ?? true);\n  let fetcher = initial.fetcher;\n  let committedEnabled = initial.enabled ?? true;\n  let debounceMs = initial.debounceMs ?? 60;\n  let cacheKey = initial.cacheKey;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let token = 0;\n  let pendingQuery: string | null = null;\n  let retryableQuery: string | null = null;\n  let pendingRetryQuery: string | null = null;\n  let inactive = true;\n  let deferredQuery: string | null = null;\n\n  const cancelTimer = () => {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  };\n  const rearmPendingRetry = () => {\n    if (pendingRetryQuery === null) return;\n    retryableQuery = pendingRetryQuery;\n    pendingRetryQuery = null;\n  };\n  const invalidatePending = () => {\n    rearmPendingRetry();\n    cancelTimer();\n    pendingQuery = null;\n    token++;\n    isLoading.value = false;\n  };\n  const scheduleFetch = (query: string) => {\n    if (!committedEnabled) return;\n    if (inactive) {\n      deferredQuery = query;\n      return;\n    }\n    if (pendingQuery === query) return;\n    rearmPendingRetry();\n    if (retryableQuery === query) {\n      retryableQuery = null;\n      pendingRetryQuery = query;\n    }\n    pendingQuery = query;\n    cancelTimer();\n    const requestToken = ++token;\n    isLoading.value = true;\n    timer = setTimeout(() => {\n      timer = null;\n      Promise.resolve()\n        .then(() => fetcher(query))\n        .then(\n          (items) => {\n            if (requestToken !== token) return;\n            pendingRetryQuery = null;\n            state.value = { query, items, failed: false };\n            isLoading.value = false;\n          },\n          () => {\n            if (requestToken !== token) return;\n            pendingQuery = null;\n            pendingRetryQuery = null;\n            state.value = { query, items: [], failed: true };\n            isLoading.value = false;\n          },\n        );\n    }, debounceMs);\n  };\n  const commitConfiguration = () => {\n    const current = toValue(options);\n    fetcher = current.fetcher;\n    committedEnabled = current.enabled ?? true;\n    debounceMs = current.debounceMs ?? 60;\n    if (cacheKey !== current.cacheKey) {\n      cacheKey = current.cacheKey;\n      invalidatePending();\n      retryableQuery = null;\n      pendingRetryQuery = null;\n      state.value = { query: NO_QUERY, items: [], failed: false };\n    }\n    if (!committedEnabled) {\n      invalidatePending();\n      if (state.value.query !== NO_QUERY)\n        state.value = { query: NO_QUERY, items: [], failed: false };\n    }\n  };\n  useIsomorphicLayoutEffect(commitConfiguration, () => {\n    const current = toValue(options);\n    return [\n      current.fetcher,\n      current.cacheKey,\n      current.enabled,\n      current.debounceMs,\n    ];\n  });\n  useIsomorphicLayoutEffect(() => {\n    // Reconnection order can differ for descendant KeepAlive hooks. Commit\n    // this owner's configuration before replaying work retained while hidden.\n    commitConfiguration();\n    inactive = false;\n    const query = deferredQuery;\n    deferredQuery = null;\n    if (query !== null) scheduleFetch(query);\n    return () => {\n      inactive = true;\n      invalidatePending();\n    };\n  }, []);\n  // Arm retries only after the failure render commits, preventing render-time\n  // search from creating an automatic retry loop.\n  useIsomorphicLayoutEffect(\n    () => {\n      retryableQuery = state.value.failed ? state.value.query : null;\n    },\n    () => [state.value],\n  );\n  const adapter = computed<Unstable_TriggerAdapter>(() => {\n    const active = enabled.value;\n    const snapshot = state.value;\n    return {\n      categories: () => [],\n      categoryItems: () => [],\n      search: (query: string) => {\n        if (!active) return [];\n        if (query !== snapshot.query || retryableQuery === query) {\n          queueMicrotask(() => scheduleFetch(query));\n        } else {\n          queueMicrotask(() => {\n            if (deferredQuery !== null && deferredQuery !== query)\n              deferredQuery = null;\n            if (pendingQuery !== null && pendingQuery !== query)\n              invalidatePending();\n          });\n        }\n        return snapshot.items;\n      },\n    };\n  });\n  return computed(() => ({\n    adapter: adapter.value,\n    isLoading: isLoading.value,\n  }));\n}\n"],"mappings":"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"}

package/dist/unstable/useMentionAdapter.d.ts

@@ -0,0 +1,95 @@
+import { type Component, type ComputedRef, type MaybeRefOrGetter } from "vue";
+import type { Unstable_DirectiveFormatter, Unstable_TriggerAdapter, Unstable_TriggerItem } from "@ulearning/ai-core";
+import type { ReadonlyJSONObject } from "@ulearning/ai-stream/utils";
+/**
+ * Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`.
+ *
+ * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.
+ */
+export type Unstable_IconComponent = Component<{
+    className?: string;
+}>;
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_Mention = {
+    readonly id: string;
+    readonly type: string;
+    readonly label: string;
+    readonly description?: string | undefined;
+    /** Shortcut for `metadata.icon`; merged with `metadata` if both are given. */
+    readonly icon?: string | undefined;
+    readonly metadata?: ReadonlyJSONObject | undefined;
+};
+/** @deprecated Experimental since 2026-03-16. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MentionCategory = {
+    readonly id: string;
+    readonly label: string;
+    readonly items: readonly Unstable_Mention[];
+};
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_ModelContextToolsOptions = {
+    /**
+     * Wrap tools in a dedicated category. Selects drill-down mode on its own
+     * when `categories` is unset and `items` is omitted.
+     */
+    readonly category?: {
+        readonly id: string;
+        readonly label: string;
+    };
+    /** Format tool name for display. */
+    readonly formatLabel?: (toolName: string) => string;
+    /** Default icon key for each tool. */
+    readonly icon?: string;
+};
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_UseMentionAdapterOptions = {
+    /**
+     * Flat mention list. Ignored when `categories` is set, and keeps the
+     * adapter flat when a tool `category` is configured.
+     */
+    readonly items?: readonly Unstable_Mention[];
+    /** Categorized mentions for drill-down navigation. */
+    readonly categories?: readonly Unstable_MentionCategory[];
+    /**
+     * How tools registered in model context integrate.
+     * - `false`: exclude.
+     * - `true`: include (default when no `items`/`categories`; as a category
+     *   if `categories` is set, flat otherwise).
+     * - object: explicit config; `category` also selects drill-down mode.
+     *
+     * Omitted → defaults to `true` iff neither `items` nor `categories`.
+     */
+    readonly includeModelContextTools?: boolean | Unstable_ModelContextToolsOptions;
+    /** Directive formatter. @default unstable_defaultDirectiveFormatter */
+    readonly formatter?: Unstable_DirectiveFormatter;
+    /** Fires after an item is inserted into the composer. */
+    readonly onInserted?: (item: Unstable_TriggerItem) => void;
+    /** Maps `metadata.icon` / `category.id` string keys to Vue components. */
+    readonly iconMap?: Record<string, Unstable_IconComponent>;
+    /** Fallback icon when no entry in `iconMap` matches. */
+    readonly fallbackIcon?: Unstable_IconComponent;
+};
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MentionDirective = {
+    readonly formatter: Unstable_DirectiveFormatter;
+    readonly onInserted?: ((item: Unstable_TriggerItem) => void) | undefined;
+};
+/**
+ * Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
+ * Supports tools registered in model context, explicit items, or both —
+ * flat or categorized.
+ *
+ * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const mention = unstable_useMentionAdapter();
+ * <ComposerTriggerPopover char="@" {...mention} />
+ * ```
+ */
+export declare function unstable_useMentionAdapter(options?: MaybeRefOrGetter<Unstable_UseMentionAdapterOptions | undefined>): ComputedRef<{
+    adapter: Unstable_TriggerAdapter;
+    directive: Unstable_MentionDirective;
+    iconMap?: Record<string, Unstable_IconComponent>;
+    fallbackIcon?: Unstable_IconComponent;
+}>;
+//# sourceMappingURL=useMentionAdapter.d.ts.map

package/dist/unstable/useMentionAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMentionAdapter.d.ts","mappings":"AAEA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,KAAK;AAEZ,OAAO,KAAK,EACV,2BAA2B,EAC3B,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,oBAAoB;AAE3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B;AAQpE;;;;;AAKA,MAAM,MAAM,sBAAsB,GAAG,SAAS,CAAC;IAAE,SAAS,CAAC,EAAE,MAAM;CAAE,CAAC;AAEtE;AACA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS;IACzC;IACA,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS;CACnD;AAED;AACA,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE;CAC5C;AAED;AACA,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;;IAIA,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM;KAAE;IACnE;IACA,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM;IACnD;IACA,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;CACvB;AAED;AACA,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;;IAIA,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE;IAC5C;IACA,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,wBAAwB,EAAE;IACzD;;;;;;;;;IASA,QAAQ,CAAC,wBAAwB,CAAC,EAC9B,OAAO,GACP,iCAAiC;IACrC;IACA,QAAQ,CAAC,SAAS,CAAC,EAAE,2BAA2B;IAChD;IACA,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI;IAC1D;IACA,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACzD;IACA,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB;CAC/C;AAED;AACA,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,SAAS,EAAE,2BAA2B;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC,GAAG,SAAS;CACzE;AAsCD;;;;;;;;;;;;;AAaA,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,gBAAgB,CACvB,iCAAiC,GAAG,SAAS,CAClC,GACZ,WAAW,CAAC;IACb,OAAO,EAAE,uBAAuB;IAChC,SAAS,EAAE,yBAAyB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAChD,YAAY,CAAC,EAAE,sBAAsB;CACtC,CAAC","names":[],"ignoreList":[],"sources":["../../src/unstable/useMentionAdapter.ts"],"sourcesContent":[null]}

package/dist/unstable/useMentionAdapter.js

@@ -0,0 +1,129 @@
+"use client";
+import { matchesTriggerItemQuery } from "../primitives/composer/trigger/matchesTriggerItemQuery.js";
+import { shallowEqualRecords, useModelContextSnapshot } from "./useModelContextSnapshot.js";
+import { unstable_defaultDirectiveFormatter } from "@ulearning/ai-core";
+import { computed, toValue } from "vue";
+import { useAui } from "@ulearning/ai-store";
+// src/unstable/useMentionAdapter.ts
+const EMPTY_TOOL_MENTIONS = Object.freeze({});
+const toolMentionSource = {
+	empty: EMPTY_TOOL_MENTIONS,
+	read: (aui) => {
+		const tools = aui.thread.getModelContext().tools;
+		if (!tools) return EMPTY_TOOL_MENTIONS;
+		const mentions = Object.create(null);
+		for (const [name, tool] of Object.entries(tools)) mentions[name] = tool.description;
+		return mentions;
+	},
+	subscribe: (aui, onChange) => {
+		const unsubscribeContext = aui.on("thread.modelContextUpdate", onChange);
+		const unsubscribeSelection = aui.on({
+			scope: "*",
+			event: "threads.selectionChanged"
+		}, onChange);
+		return () => {
+			unsubscribeContext();
+			unsubscribeSelection();
+		};
+	},
+	isEqual: shallowEqualRecords
+};
+/**
+* Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
+* Supports tools registered in model context, explicit items, or both —
+* flat or categorized.
+*
+* @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.
+*
+* @example
+* ```tsx
+* const mention = unstable_useMentionAdapter();
+* <ComposerTriggerPopover char="@" {...mention} />
+* ```
+*/
+function unstable_useMentionAdapter(options = void 0) {
+	const aui = useAui();
+	const items = computed(() => toValue(options)?.items);
+	const categories = computed(() => toValue(options)?.categories);
+	const includeTools = computed(() => toValue(options)?.includeModelContextTools ?? (!items.value && !categories.value));
+	const toolsConfig = computed(() => typeof includeTools.value === "object" ? includeTools.value : void 0);
+	const wantsTools = computed(() => includeTools.value !== false);
+	const formatter = computed(() => toValue(options)?.formatter);
+	const onInserted = computed(() => toValue(options)?.onInserted);
+	const isCategorized = computed(() => categories.value !== void 0 || toolsConfig.value?.category !== void 0 && items.value === void 0);
+	const toolMentions = useModelContextSnapshot(aui, wantsTools, toolMentionSource);
+	const adapter = computed(() => {
+		const formatLabel = toolsConfig.value?.formatLabel;
+		const defaultIcon = toolsConfig.value?.icon;
+		const toolItems = wantsTools.value ? Object.entries(toolMentions.value).map(([name, description]) => toTriggerItem({
+			id: name,
+			type: "tool",
+			label: formatLabel ? formatLabel(name) : name,
+			description,
+			icon: defaultIcon
+		})) : [];
+		if (isCategorized.value) {
+			const groups = (categories.value ?? []).map((cat) => ({
+				id: cat.id,
+				label: cat.label,
+				items: cat.items.map(toTriggerItem)
+			}));
+			const allGroups = toolItems.length > 0 ? [...groups, {
+				id: toolsConfig.value?.category?.id ?? "tools",
+				label: toolsConfig.value?.category?.label ?? "Tools",
+				items: toolItems
+			}] : groups;
+			return {
+				categories: () => allGroups.map(({ id, label }) => ({
+					id,
+					label
+				})),
+				categoryItems: (id) => allGroups.find((g) => g.id === id)?.items ?? [],
+				search: (query) => {
+					const lower = query.toLowerCase();
+					return allGroups.flatMap((g) => g.items).filter((item) => matchesTriggerItemQuery(item, lower));
+				}
+			};
+		}
+		const flatItems = (items.value ?? []).map(toTriggerItem);
+		const seen = new Set(flatItems.map((i) => i.id));
+		const flatPool = [...flatItems, ...toolItems.filter((t) => !seen.has(t.id))];
+		return {
+			categories: () => [],
+			categoryItems: () => [],
+			search: (query) => {
+				const lower = query.toLowerCase();
+				return flatPool.filter((item) => matchesTriggerItemQuery(item, lower));
+			}
+		};
+	});
+	const directive = computed(() => ({
+		formatter: formatter.value ?? unstable_defaultDirectiveFormatter,
+		...onInserted.value ? { onInserted: onInserted.value } : {}
+	}));
+	return computed(() => {
+		const current = toValue(options);
+		return {
+			adapter: adapter.value,
+			directive: directive.value,
+			...current?.iconMap ? { iconMap: current.iconMap } : {},
+			...current?.fallbackIcon ? { fallbackIcon: current.fallbackIcon } : {}
+		};
+	});
+}
+function toTriggerItem(m) {
+	const metadata = m.icon !== void 0 ? {
+		...m.metadata ?? {},
+		icon: m.icon
+	} : m.metadata;
+	return {
+		id: m.id,
+		type: m.type,
+		label: m.label,
+		...m.description !== void 0 ? { description: m.description } : {},
+		...metadata !== void 0 ? { metadata } : {}
+	};
+}
+export { unstable_useMentionAdapter };
+
+//# sourceMappingURL=useMentionAdapter.js.map

package/dist/unstable/useMentionAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMentionAdapter.js","names":[],"sources":["../../src/unstable/useMentionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  computed,\n  toValue,\n  type Component,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n} from \"vue\";\nimport { useAui } from \"@ulearning/ai-store\";\nimport type {\n  Unstable_DirectiveFormatter,\n  Unstable_TriggerAdapter,\n  Unstable_TriggerCategory,\n  Unstable_TriggerItem,\n} from \"@ulearning/ai-core\";\nimport { unstable_defaultDirectiveFormatter } from \"@ulearning/ai-core\";\nimport type { ReadonlyJSONObject } from \"@ulearning/ai-stream/utils\";\nimport { matchesTriggerItemQuery } from \"../primitives/composer/trigger/matchesTriggerItemQuery\";\nimport {\n  shallowEqualRecords,\n  useModelContextSnapshot,\n  type ModelContextSnapshotSource,\n} from \"./useModelContextSnapshot\";\n\n/**\n * Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`.\n *\n * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.\n */\nexport type Unstable_IconComponent = Component<{ className?: string }>;\n\n/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_Mention = {\n  readonly id: string;\n  readonly type: string;\n  readonly label: string;\n  readonly description?: string | undefined;\n  /** Shortcut for `metadata.icon`; merged with `metadata` if both are given. */\n  readonly icon?: string | undefined;\n  readonly metadata?: ReadonlyJSONObject | undefined;\n};\n\n/** @deprecated Experimental since 2026-03-16. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_MentionCategory = {\n  readonly id: string;\n  readonly label: string;\n  readonly items: readonly Unstable_Mention[];\n};\n\n/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_ModelContextToolsOptions = {\n  /**\n   * Wrap tools in a dedicated category. Selects drill-down mode on its own\n   * when `categories` is unset and `items` is omitted.\n   */\n  readonly category?: { readonly id: string; readonly label: string };\n  /** Format tool name for display. */\n  readonly formatLabel?: (toolName: string) => string;\n  /** Default icon key for each tool. */\n  readonly icon?: string;\n};\n\n/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_UseMentionAdapterOptions = {\n  /**\n   * Flat mention list. Ignored when `categories` is set, and keeps the\n   * adapter flat when a tool `category` is configured.\n   */\n  readonly items?: readonly Unstable_Mention[];\n  /** Categorized mentions for drill-down navigation. */\n  readonly categories?: readonly Unstable_MentionCategory[];\n  /**\n   * How tools registered in model context integrate.\n   * - `false`: exclude.\n   * - `true`: include (default when no `items`/`categories`; as a category\n   *   if `categories` is set, flat otherwise).\n   * - object: explicit config; `category` also selects drill-down mode.\n   *\n   * Omitted → defaults to `true` iff neither `items` nor `categories`.\n   */\n  readonly includeModelContextTools?:\n    | boolean\n    | Unstable_ModelContextToolsOptions;\n  /** Directive formatter. @default unstable_defaultDirectiveFormatter */\n  readonly formatter?: Unstable_DirectiveFormatter;\n  /** Fires after an item is inserted into the composer. */\n  readonly onInserted?: (item: Unstable_TriggerItem) => void;\n  /** Maps `metadata.icon` / `category.id` string keys to Vue components. */\n  readonly iconMap?: Record<string, Unstable_IconComponent>;\n  /** Fallback icon when no entry in `iconMap` matches. */\n  readonly fallbackIcon?: Unstable_IconComponent;\n};\n\n/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_MentionDirective = {\n  readonly formatter: Unstable_DirectiveFormatter;\n  readonly onInserted?: ((item: Unstable_TriggerItem) => void) | undefined;\n};\n\nconst EMPTY_TOOL_MENTIONS: Readonly<Record<string, string | undefined>> =\n  Object.freeze({});\n\n// The description is copied out rather than reached through the tool, so a\n// provider that returns a stable tool object and edits it in place is observed.\nconst toolMentionSource: ModelContextSnapshotSource<\n  Readonly<Record<string, string | undefined>>\n> = {\n  empty: EMPTY_TOOL_MENTIONS,\n  read: (aui) => {\n    const tools = aui.thread.getModelContext().tools;\n    if (!tools) return EMPTY_TOOL_MENTIONS;\n    const mentions = Object.create(null) as Record<string, string | undefined>;\n    for (const [name, tool] of Object.entries(tools)) {\n      mentions[name] = tool.description;\n    }\n    return mentions;\n  },\n  subscribe: (aui, onChange) => {\n    const unsubscribeContext = aui.on(\"thread.modelContextUpdate\", onChange);\n    // Rebinding the thread event subject to a new thread does not replay it,\n    // so a switch between threads carrying different providers is its own\n    // refresh trigger. Subscribed globally because a composer can render\n    // without a thread list scope.\n    const unsubscribeSelection = aui.on(\n      { scope: \"*\", event: \"threads.selectionChanged\" },\n      onChange,\n    );\n    return () => {\n      unsubscribeContext();\n      unsubscribeSelection();\n    };\n  },\n  isEqual: shallowEqualRecords,\n};\n\n/**\n * Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.\n * Supports tools registered in model context, explicit items, or both —\n * flat or categorized.\n *\n * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.\n *\n * @example\n * ```tsx\n * const mention = unstable_useMentionAdapter();\n * <ComposerTriggerPopover char=\"@\" {...mention} />\n * ```\n */\nexport function unstable_useMentionAdapter(\n  options: MaybeRefOrGetter<\n    Unstable_UseMentionAdapterOptions | undefined\n  > = undefined,\n): ComputedRef<{\n  adapter: Unstable_TriggerAdapter;\n  directive: Unstable_MentionDirective;\n  iconMap?: Record<string, Unstable_IconComponent>;\n  fallbackIcon?: Unstable_IconComponent;\n}> {\n  const aui = useAui();\n  const items = computed(() => toValue(options)?.items);\n  const categories = computed(() => toValue(options)?.categories);\n  const includeTools = computed(\n    () =>\n      toValue(options)?.includeModelContextTools ??\n      (!items.value && !categories.value),\n  );\n  const toolsConfig = computed(() =>\n    typeof includeTools.value === \"object\" ? includeTools.value : undefined,\n  );\n  const wantsTools = computed(() => includeTools.value !== false);\n  const formatter = computed(() => toValue(options)?.formatter);\n  const onInserted = computed(() => toValue(options)?.onInserted);\n  const isCategorized = computed(\n    () =>\n      categories.value !== undefined ||\n      (toolsConfig.value?.category !== undefined && items.value === undefined),\n  );\n  const toolMentions = useModelContextSnapshot(\n    aui,\n    wantsTools,\n    toolMentionSource,\n  );\n\n  const adapter = computed<Unstable_TriggerAdapter>(() => {\n    const formatLabel = toolsConfig.value?.formatLabel;\n    const defaultIcon = toolsConfig.value?.icon;\n    const toolItems = wantsTools.value\n      ? Object.entries(toolMentions.value).map(([name, description]) =>\n          toTriggerItem({\n            id: name,\n            type: \"tool\",\n            label: formatLabel ? formatLabel(name) : name,\n            description,\n            icon: defaultIcon,\n          }),\n        )\n      : [];\n\n    // Categorized: drill-down mode\n    if (isCategorized.value) {\n      const groups = (categories.value ?? []).map((cat) => ({\n        id: cat.id,\n        label: cat.label,\n        items: cat.items.map(toTriggerItem),\n      }));\n      const allGroups =\n        toolItems.length > 0\n          ? [\n              ...groups,\n              {\n                id: toolsConfig.value?.category?.id ?? \"tools\",\n                label: toolsConfig.value?.category?.label ?? \"Tools\",\n                items: toolItems,\n              },\n            ]\n          : groups;\n\n      return {\n        categories: () => allGroups.map(({ id, label }) => ({ id, label })),\n        categoryItems: (id) => allGroups.find((g) => g.id === id)?.items ?? [],\n        search: (query) => {\n          const lower = query.toLowerCase();\n          return allGroups\n            .flatMap((g) => g.items)\n            .filter((item) => matchesTriggerItemQuery(item, lower));\n        },\n      };\n    }\n\n    // Flat: items + (optionally) tools, all in one search pool\n    const flatItems = (items.value ?? []).map(toTriggerItem);\n    // Dedupe by id — explicit items win.\n    const seen = new Set(flatItems.map((i) => i.id));\n    const flatPool = [\n      ...flatItems,\n      ...toolItems.filter((t) => !seen.has(t.id)),\n    ];\n\n    return {\n      categories: (): readonly Unstable_TriggerCategory[] => [],\n      categoryItems: () => [],\n      search: (query) => {\n        const lower = query.toLowerCase();\n        return flatPool.filter((item) => matchesTriggerItemQuery(item, lower));\n      },\n    };\n  });\n\n  const directive = computed<Unstable_MentionDirective>(() => ({\n    formatter: formatter.value ?? unstable_defaultDirectiveFormatter,\n    ...(onInserted.value ? { onInserted: onInserted.value } : {}),\n  }));\n\n  return computed(() => {\n    const current = toValue(options);\n    return {\n      adapter: adapter.value,\n      directive: directive.value,\n      ...(current?.iconMap ? { iconMap: current.iconMap } : {}),\n      ...(current?.fallbackIcon ? { fallbackIcon: current.fallbackIcon } : {}),\n    };\n  });\n}\n\nfunction toTriggerItem(m: Unstable_Mention): Unstable_TriggerItem {\n  const metadata =\n    m.icon !== undefined ? { ...(m.metadata ?? {}), icon: m.icon } : m.metadata;\n  return {\n    id: m.id,\n    type: m.type,\n    label: m.label,\n    ...(m.description !== undefined ? { description: m.description } : {}),\n    ...(metadata !== undefined ? { metadata } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/unstable/useMessageStallDetection.d.ts

@@ -0,0 +1,30 @@
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MessageStallDetectionOptions = {
+    /**
+     * Milliseconds of unchanged message content before the message counts as
+     * stalled.
+     * @default 2000
+     */
+    thresholdMs?: number | undefined;
+};
+/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MessageStallDetection = {
+    /** True while the message is running and its content has not changed for at least `thresholdMs`. */
+    stalled: boolean;
+    /** Milliseconds since the last observed content change. `0` while not stalled. */
+    stalledForMs: number;
+};
+/**
+ * Detects mid-run output stalls on the current message: while the message is
+ * running, watches its text, reasoning, and tool-argument values plus tool-result
+ * availability and reports a stall once they stop changing for `thresholdMs`.
+ * Useful for re-surfacing a "still working" indicator during tool think-time or
+ * provider stalls, after the first tokens have already streamed.
+ *
+ * Must be used inside a message scope.
+ *
+ * @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release.
+ */
+export declare function unstable_useMessageStallDetection(options?: MaybeRefOrGetter<Unstable_MessageStallDetectionOptions | undefined>): ComputedRef<Unstable_MessageStallDetection>;
+//# sourceMappingURL=useMessageStallDetection.d.ts.map

package/dist/unstable/useMessageStallDetection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMessageStallDetection.d.ts","mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,KAAK;AAOZ;AACA,MAAM,MAAM,qCAAqC,GAAG;IAClD;;;;;IAKA,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS;CACjC;AAED;AACA,MAAM,MAAM,8BAA8B,GAAG;IAC3C;IACA,OAAO,EAAE,OAAO;IAChB;IACA,YAAY,EAAE,MAAM;CACrB;AAED;;;;;;;;;;;AAWA,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE,gBAAgB,CACvB,qCAAqC,GAAG,SAAS,CACtC,GACZ,WAAW,CAAC,8BAA8B,CAAC","names":[],"ignoreList":[],"sources":["../../src/unstable/useMessageStallDetection.ts"],"sourcesContent":[null]}