@assistant-ui/react 0.15.24 → 0.15.26

package/dist/unstable/useLiveCompletionAdapter.js

@@ -1,11 +1,10 @@
 "use client";
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "@assistant-ui/tap/react-shim";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "@assistant-ui/tap/react-shim";
 //#region src/unstable/useLiveCompletionAdapter.ts
 /** Sentinel that no real query (including the empty string) equals, so the first query always fetches. */
 const NO_QUERY = "\0";
 /**
-* @deprecated Under active development and may change without notice.
-*
 * 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
@@ -16,6 +15,8 @@ const NO_QUERY = "\0";
 * `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({
@@ -39,7 +40,7 @@ function unstable_useLiveCompletionAdapter(options) {
 	});
 	const [isLoading, setIsLoading] = useState(false);
 	const fetcherRef = useRef(fetcher);
-	useLayoutEffect(() => {
+	useIsomorphicLayoutEffect(() => {
 		fetcherRef.current = fetcher;
 	}, [fetcher]);
 	const timerRef = useRef(null);
@@ -107,7 +108,7 @@ function unstable_useLiveCompletionAdapter(options) {
 		rearmPendingRetry
 	]);
 	const scheduleFetchRef = useRef(scheduleFetch);
-	useLayoutEffect(() => {
+	useIsomorphicLayoutEffect(() => {
 		scheduleFetchRef.current = scheduleFetch;
 	}, [scheduleFetch]);
 	const invalidatePending = useCallback(() => {
@@ -118,7 +119,7 @@ function unstable_useLiveCompletionAdapter(options) {
 		setIsLoading(false);
 	}, [cancelTimer, rearmPendingRetry]);
 	const cacheKeyRef = useRef(cacheKey);
-	useLayoutEffect(() => {
+	useIsomorphicLayoutEffect(() => {
 		if (cacheKeyRef.current === cacheKey) return;
 		cacheKeyRef.current = cacheKey;
 		invalidatePending();
@@ -139,7 +140,7 @@ function unstable_useLiveCompletionAdapter(options) {
 			failed: false
 		});
 	}, [enabled, invalidatePending]);
-	useLayoutEffect(() => {
+	useIsomorphicLayoutEffect(() => {
 		inactiveRef.current = false;
 		const deferredQuery = deferredQueryRef.current;
 		deferredQueryRef.current = null;

package/dist/unstable/useLiveCompletionAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveCompletionAdapter.js","names":["useCallback","useEffect","useLayoutEffect","useMemo","useRef","useState","Unstable_TriggerAdapter","Unstable_TriggerItem","Unstable_UseLiveCompletionAdapterOptions","fetcher","query","Promise","cacheKey","debounceMs","enabled","NO_QUERY","unstable_useLiveCompletionAdapter","options","adapter","isLoading","state","setState","items","failed","setIsLoading","fetcherRef","current","timerRef","ReturnType","setTimeout","tokenRef","pendingQueryRef","retryableQueryRef","pendingRetryQueryRef","inactiveRef","deferredQueryRef","cancelTimer","clearTimeout","rearmPendingRetry","scheduleFetch","token","resolve","then","scheduleFetchRef","invalidatePending","cacheKeyRef","s","deferredQuery","categories","categoryItems","search","queueMicrotask"],"sources":["../../src/unstable/useLiveCompletionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\nimport type {\n  Unstable_TriggerAdapter,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/core\";\n\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 * @deprecated Under active development and may change without notice.\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 * @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: Unstable_UseLiveCompletionAdapterOptions,\n): { adapter: Unstable_TriggerAdapter; isLoading: boolean } {\n  const { fetcher, cacheKey, debounceMs = 60, enabled = true } = options;\n\n  const [state, setState] = useState<{\n    query: string;\n    items: readonly Unstable_TriggerItem[];\n    failed: boolean;\n  }>({ query: NO_QUERY, items: [], failed: false });\n  const [isLoading, setIsLoading] = useState(false);\n\n  const fetcherRef = useRef(fetcher);\n  // The debounce timer must only observe fetchers from committed renders.\n  useLayoutEffect(() => {\n    fetcherRef.current = fetcher;\n  }, [fetcher]);\n\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const tokenRef = useRef(0);\n  const pendingQueryRef = useRef<string | null>(null);\n  const retryableQueryRef = useRef<string | null>(null);\n  const pendingRetryQueryRef = useRef<string | null>(null);\n  const inactiveRef = useRef(true);\n  const deferredQueryRef = useRef<string | null>(null);\n\n  const cancelTimer = useCallback(() => {\n    if (timerRef.current !== null) {\n      clearTimeout(timerRef.current);\n      timerRef.current = null;\n    }\n  }, []);\n\n  const rearmPendingRetry = useCallback(() => {\n    const query = pendingRetryQueryRef.current;\n    if (query === null) return;\n    retryableQueryRef.current = query;\n    pendingRetryQueryRef.current = null;\n  }, []);\n\n  const scheduleFetch = useCallback(\n    (query: string) => {\n      if (!enabled) return;\n      if (inactiveRef.current) {\n        deferredQueryRef.current = query;\n        return;\n      }\n      if (pendingQueryRef.current === query) return;\n      rearmPendingRetry();\n      if (retryableQueryRef.current === query) {\n        retryableQueryRef.current = null;\n        pendingRetryQueryRef.current = query;\n      }\n      pendingQueryRef.current = query;\n      cancelTimer();\n      const token = ++tokenRef.current;\n      setIsLoading(true);\n      timerRef.current = setTimeout(() => {\n        timerRef.current = null;\n        Promise.resolve()\n          .then(() => fetcherRef.current(query))\n          .then(\n            (items) => {\n              if (token !== tokenRef.current) return;\n              pendingRetryQueryRef.current = null;\n              setState({ query, items, failed: false });\n              setIsLoading(false);\n            },\n            () => {\n              if (token !== tokenRef.current) return;\n              pendingQueryRef.current = null;\n              pendingRetryQueryRef.current = null;\n              setState({ query, items: [], failed: true });\n              setIsLoading(false);\n            },\n          );\n      }, debounceMs);\n    },\n    [enabled, debounceMs, cancelTimer, rearmPendingRetry],\n  );\n\n  const scheduleFetchRef = useRef(scheduleFetch);\n  useLayoutEffect(() => {\n    scheduleFetchRef.current = scheduleFetch;\n  }, [scheduleFetch]);\n\n  const invalidatePending = useCallback(() => {\n    rearmPendingRetry();\n    cancelTimer();\n    pendingQueryRef.current = null;\n    tokenRef.current += 1;\n    setIsLoading(false);\n  }, [cancelTimer, rearmPendingRetry]);\n\n  const cacheKeyRef = useRef(cacheKey);\n  useLayoutEffect(() => {\n    if (cacheKeyRef.current === cacheKey) return;\n    cacheKeyRef.current = cacheKey;\n    invalidatePending();\n    retryableQueryRef.current = null;\n    pendingRetryQueryRef.current = null;\n    setState({ query: NO_QUERY, items: [], failed: false });\n  }, [cacheKey, invalidatePending]);\n\n  useEffect(() => {\n    if (enabled) return;\n    invalidatePending();\n    setState((s) =>\n      s.query === NO_QUERY ? s : { query: NO_QUERY, items: [], failed: false },\n    );\n  }, [enabled, invalidatePending]);\n\n  // Render-time searches can outlive an abandoned render, so they only arm\n  // request work after this hook commits.\n  useLayoutEffect(() => {\n    inactiveRef.current = false;\n    const deferredQuery = deferredQueryRef.current;\n    deferredQueryRef.current = null;\n    if (deferredQuery !== null) scheduleFetchRef.current(deferredQuery);\n    return () => {\n      inactiveRef.current = true;\n      invalidatePending();\n    };\n  }, [invalidatePending]);\n\n  // Arm retries only after the failed state commits. Arming during rejection\n  // would let the failure render immediately schedule another request.\n  useEffect(() => {\n    retryableQueryRef.current = state.failed ? state.query : null;\n  }, [state]);\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(\n    () => ({\n      categories: () => [],\n      categoryItems: () => [],\n      search: (query: string) => {\n        // search() runs inside the popover's render; defer state updates with\n        // queueMicrotask so they are not dispatched while another component renders.\n        if (query !== state.query || retryableQueryRef.current === query) {\n          queueMicrotask(() => scheduleFetch(query));\n        } else {\n          queueMicrotask(() => {\n            if (\n              deferredQueryRef.current !== null &&\n              deferredQueryRef.current !== query\n            ) {\n              deferredQueryRef.current = null;\n            }\n            if (\n              pendingQueryRef.current !== null &&\n              pendingQueryRef.current !== query\n            ) {\n              invalidatePending();\n            }\n          });\n        }\n        return state.items;\n      },\n    }),\n    [state, scheduleFetch, invalidatePending],\n  );\n\n  return { adapter, isLoading };\n}\n"],"mappings":"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"}
+{"version":3,"file":"useLiveCompletionAdapter.js","names":["useCallback","useEffect","useMemo","useRef","useState","useIsomorphicLayoutEffect","Unstable_TriggerAdapter","Unstable_TriggerItem","Unstable_UseLiveCompletionAdapterOptions","fetcher","query","Promise","cacheKey","debounceMs","enabled","NO_QUERY","unstable_useLiveCompletionAdapter","options","adapter","isLoading","state","setState","items","failed","setIsLoading","fetcherRef","current","timerRef","ReturnType","setTimeout","tokenRef","pendingQueryRef","retryableQueryRef","pendingRetryQueryRef","inactiveRef","deferredQueryRef","cancelTimer","clearTimeout","rearmPendingRetry","scheduleFetch","token","resolve","then","scheduleFetchRef","invalidatePending","cacheKeyRef","s","deferredQuery","categories","categoryItems","search","queueMicrotask"],"sources":["../../src/unstable/useLiveCompletionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { useIsomorphicLayoutEffect } from \"../utils/useIsomorphicLayoutEffect\";\nimport type {\n  Unstable_TriggerAdapter,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/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: Unstable_UseLiveCompletionAdapterOptions,\n): { adapter: Unstable_TriggerAdapter; isLoading: boolean } {\n  const { fetcher, cacheKey, debounceMs = 60, enabled = true } = options;\n\n  const [state, setState] = useState<{\n    query: string;\n    items: readonly Unstable_TriggerItem[];\n    failed: boolean;\n  }>({ query: NO_QUERY, items: [], failed: false });\n  const [isLoading, setIsLoading] = useState(false);\n\n  const fetcherRef = useRef(fetcher);\n  // The debounce timer must only observe fetchers from committed renders.\n  useIsomorphicLayoutEffect(() => {\n    fetcherRef.current = fetcher;\n  }, [fetcher]);\n\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const tokenRef = useRef(0);\n  const pendingQueryRef = useRef<string | null>(null);\n  const retryableQueryRef = useRef<string | null>(null);\n  const pendingRetryQueryRef = useRef<string | null>(null);\n  const inactiveRef = useRef(true);\n  const deferredQueryRef = useRef<string | null>(null);\n\n  const cancelTimer = useCallback(() => {\n    if (timerRef.current !== null) {\n      clearTimeout(timerRef.current);\n      timerRef.current = null;\n    }\n  }, []);\n\n  const rearmPendingRetry = useCallback(() => {\n    const query = pendingRetryQueryRef.current;\n    if (query === null) return;\n    retryableQueryRef.current = query;\n    pendingRetryQueryRef.current = null;\n  }, []);\n\n  const scheduleFetch = useCallback(\n    (query: string) => {\n      if (!enabled) return;\n      if (inactiveRef.current) {\n        deferredQueryRef.current = query;\n        return;\n      }\n      if (pendingQueryRef.current === query) return;\n      rearmPendingRetry();\n      if (retryableQueryRef.current === query) {\n        retryableQueryRef.current = null;\n        pendingRetryQueryRef.current = query;\n      }\n      pendingQueryRef.current = query;\n      cancelTimer();\n      const token = ++tokenRef.current;\n      setIsLoading(true);\n      timerRef.current = setTimeout(() => {\n        timerRef.current = null;\n        Promise.resolve()\n          .then(() => fetcherRef.current(query))\n          .then(\n            (items) => {\n              if (token !== tokenRef.current) return;\n              pendingRetryQueryRef.current = null;\n              setState({ query, items, failed: false });\n              setIsLoading(false);\n            },\n            () => {\n              if (token !== tokenRef.current) return;\n              pendingQueryRef.current = null;\n              pendingRetryQueryRef.current = null;\n              setState({ query, items: [], failed: true });\n              setIsLoading(false);\n            },\n          );\n      }, debounceMs);\n    },\n    [enabled, debounceMs, cancelTimer, rearmPendingRetry],\n  );\n\n  const scheduleFetchRef = useRef(scheduleFetch);\n  useIsomorphicLayoutEffect(() => {\n    scheduleFetchRef.current = scheduleFetch;\n  }, [scheduleFetch]);\n\n  const invalidatePending = useCallback(() => {\n    rearmPendingRetry();\n    cancelTimer();\n    pendingQueryRef.current = null;\n    tokenRef.current += 1;\n    setIsLoading(false);\n  }, [cancelTimer, rearmPendingRetry]);\n\n  const cacheKeyRef = useRef(cacheKey);\n  useIsomorphicLayoutEffect(() => {\n    if (cacheKeyRef.current === cacheKey) return;\n    cacheKeyRef.current = cacheKey;\n    invalidatePending();\n    retryableQueryRef.current = null;\n    pendingRetryQueryRef.current = null;\n    setState({ query: NO_QUERY, items: [], failed: false });\n  }, [cacheKey, invalidatePending]);\n\n  useEffect(() => {\n    if (enabled) return;\n    invalidatePending();\n    setState((s) =>\n      s.query === NO_QUERY ? s : { query: NO_QUERY, items: [], failed: false },\n    );\n  }, [enabled, invalidatePending]);\n\n  // Render-time searches can outlive an abandoned render, so they only arm\n  // request work after this hook commits.\n  useIsomorphicLayoutEffect(() => {\n    inactiveRef.current = false;\n    const deferredQuery = deferredQueryRef.current;\n    deferredQueryRef.current = null;\n    if (deferredQuery !== null) scheduleFetchRef.current(deferredQuery);\n    return () => {\n      inactiveRef.current = true;\n      invalidatePending();\n    };\n  }, [invalidatePending]);\n\n  // Arm retries only after the failed state commits. Arming during rejection\n  // would let the failure render immediately schedule another request.\n  useEffect(() => {\n    retryableQueryRef.current = state.failed ? state.query : null;\n  }, [state]);\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(\n    () => ({\n      categories: () => [],\n      categoryItems: () => [],\n      search: (query: string) => {\n        // search() runs inside the popover's render; defer state updates with\n        // queueMicrotask so they are not dispatched while another component renders.\n        if (query !== state.query || retryableQueryRef.current === query) {\n          queueMicrotask(() => scheduleFetch(query));\n        } else {\n          queueMicrotask(() => {\n            if (\n              deferredQueryRef.current !== null &&\n              deferredQueryRef.current !== query\n            ) {\n              deferredQueryRef.current = null;\n            }\n            if (\n              pendingQueryRef.current !== null &&\n              pendingQueryRef.current !== query\n            ) {\n              invalidatePending();\n            }\n          });\n        }\n        return state.items;\n      },\n    }),\n    [state, scheduleFetch, invalidatePending],\n  );\n\n  return { adapter, isLoading };\n}\n"],"mappings":"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"}

package/dist/unstable/useMentionAdapter.d.ts

@@ -1,10 +1,15 @@
 import { type FC } from "react";
 import type { Unstable_DirectiveFormatter, Unstable_TriggerAdapter, Unstable_TriggerItem } from "@assistant-ui/core";
 import type { ReadonlyJSONObject } from "assistant-stream/utils";
-/** Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`. */
+/**
+ * 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 = FC<{
     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;
@@ -14,11 +19,13 @@ export type Unstable_Mention = {
     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
@@ -33,6 +40,7 @@ export type Unstable_ModelContextToolsOptions = {
     /** 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
@@ -60,17 +68,18 @@ export type Unstable_UseMentionAdapterOptions = {
     /** 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;
 };
 /**
- * @deprecated Under active development and might change without notice.
- *
  * 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();

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

@@ -1 +1 @@
-{"version":3,"file":"useMentionAdapter.d.ts","sourceRoot":"","sources":["../../src/unstable/useMentionAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAEzC,OAAO,KAAK,EACV,2BAA2B,EAC3B,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAQjE,6EAA6E;AAC7E,MAAM,MAAM,sBAAsB,GAAG,EAAE,CAAC;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,oCAAoC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC1D;;;;;;;;OAQG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAC9B,OAAO,GACP,iCAAiC,CAAC;IACtC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACjD,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC3D,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC1D,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1E,CAAC;AAsCF;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,CAAC,EAAE,iCAAiC,GAC1C;IACD,OAAO,EAAE,uBAAuB,CAAC;IACjC,SAAS,EAAE,yBAAyB,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACjD,YAAY,CAAC,EAAE,sBAAsB,CAAC;CACvC,CAoGA"}
+{"version":3,"file":"useMentionAdapter.d.ts","sourceRoot":"","sources":["../../src/unstable/useMentionAdapter.ts"],"names":[],"mappings":"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"}

package/dist/unstable/useMentionAdapter.js

@@ -29,12 +29,12 @@ const toolMentionSource = {
 	isEqual: shallowEqualRecords
 };
 /**
-* @deprecated Under active development and might change without notice.
-*
 * 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();

package/dist/unstable/useMentionAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMentionAdapter.js","names":["useMemo","FC","useAui","Unstable_DirectiveFormatter","Unstable_TriggerAdapter","Unstable_TriggerCategory","Unstable_TriggerItem","unstable_defaultDirectiveFormatter","ReadonlyJSONObject","matchesTriggerItemQuery","shallowEqualRecords","useModelContextSnapshot","ModelContextSnapshotSource","Unstable_IconComponent","className","Unstable_Mention","id","type","label","description","icon","metadata","Unstable_MentionCategory","items","Unstable_ModelContextToolsOptions","category","formatLabel","toolName","Unstable_UseMentionAdapterOptions","categories","includeModelContextTools","formatter","onInserted","item","iconMap","Record","fallbackIcon","Unstable_MentionDirective","EMPTY_TOOL_MENTIONS","Readonly","Object","freeze","toolMentionSource","empty","read","aui","tools","thread","getModelContext","mentions","create","name","tool","entries","subscribe","onChange","unsubscribeContext","on","unsubscribeSelection","scope","event","isEqual","unstable_useMentionAdapter","options","adapter","directive","includeTools","toolsConfig","undefined","wantsTools","isCategorized","toolMentions","defaultIcon","toolItems","map","toTriggerItem","groups","cat","allGroups","length","categoryItems","find","g","search","query","lower","toLowerCase","flatMap","filter","flatItems","seen","Set","i","flatPool","t","has","m"],"sources":["../../src/unstable/useMentionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport { useMemo, type FC } from \"react\";\nimport { useAui } from \"@assistant-ui/store\";\nimport type {\n  Unstable_DirectiveFormatter,\n  Unstable_TriggerAdapter,\n  Unstable_TriggerCategory,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/core\";\nimport { unstable_defaultDirectiveFormatter } from \"@assistant-ui/core\";\nimport type { ReadonlyJSONObject } from \"assistant-stream/utils\";\nimport { matchesTriggerItemQuery } from \"../primitives/composer/trigger/matchesTriggerItemQuery\";\nimport {\n  shallowEqualRecords,\n  useModelContextSnapshot,\n  type ModelContextSnapshotSource,\n} from \"./useModelContextSnapshot\";\n\n/** Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`. */\nexport type Unstable_IconComponent = FC<{ className?: string }>;\n\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\nexport type Unstable_MentionCategory = {\n  readonly id: string;\n  readonly label: string;\n  readonly items: readonly Unstable_Mention[];\n};\n\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\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 React components. */\n  readonly iconMap?: Record<string, Unstable_IconComponent>;\n  /** Fallback icon when no entry in `iconMap` matches. */\n  readonly fallbackIcon?: Unstable_IconComponent;\n};\n\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 * @deprecated Under active development and might change without notice.\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 * @example\n * ```tsx\n * const mention = unstable_useMentionAdapter();\n * <ComposerTriggerPopover char=\"@\" {...mention} />\n * ```\n */\nexport function unstable_useMentionAdapter(\n  options?: Unstable_UseMentionAdapterOptions,\n): {\n  adapter: Unstable_TriggerAdapter;\n  directive: Unstable_MentionDirective;\n  iconMap?: Record<string, Unstable_IconComponent>;\n  fallbackIcon?: Unstable_IconComponent;\n} {\n  const aui = useAui();\n\n  const items = options?.items;\n  const categories = options?.categories;\n  const includeTools =\n    options?.includeModelContextTools ?? (!items && !categories);\n  const toolsConfig =\n    typeof includeTools === \"object\" ? includeTools : undefined;\n  const wantsTools = includeTools !== false;\n  const formatter = options?.formatter;\n  const onInserted = options?.onInserted;\n  const isCategorized =\n    categories !== undefined ||\n    (toolsConfig?.category !== undefined && items === undefined);\n  const toolMentions = useModelContextSnapshot(\n    aui,\n    wantsTools,\n    toolMentionSource,\n  );\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(() => {\n    const formatLabel = toolsConfig?.formatLabel;\n    const defaultIcon = toolsConfig?.icon;\n    const toolItems = wantsTools\n      ? Object.entries(toolMentions).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) {\n      const groups = (categories ?? []).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?.category?.id ?? \"tools\",\n                label: toolsConfig?.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 ?? []).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  }, [items, categories, wantsTools, toolsConfig, isCategorized, toolMentions]);\n\n  const directive = useMemo<Unstable_MentionDirective>(\n    () => ({\n      formatter: formatter ?? unstable_defaultDirectiveFormatter,\n      ...(onInserted ? { onInserted } : {}),\n    }),\n    [formatter, onInserted],\n  );\n\n  return {\n    adapter,\n    directive,\n    ...(options?.iconMap ? { iconMap: options.iconMap } : {}),\n    ...(options?.fallbackIcon ? { fallbackIcon: options.fallbackIcon } : {}),\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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"}
+{"version":3,"file":"useMentionAdapter.js","names":["useMemo","FC","useAui","Unstable_DirectiveFormatter","Unstable_TriggerAdapter","Unstable_TriggerCategory","Unstable_TriggerItem","unstable_defaultDirectiveFormatter","ReadonlyJSONObject","matchesTriggerItemQuery","shallowEqualRecords","useModelContextSnapshot","ModelContextSnapshotSource","Unstable_IconComponent","className","Unstable_Mention","id","type","label","description","icon","metadata","Unstable_MentionCategory","items","Unstable_ModelContextToolsOptions","category","formatLabel","toolName","Unstable_UseMentionAdapterOptions","categories","includeModelContextTools","formatter","onInserted","item","iconMap","Record","fallbackIcon","Unstable_MentionDirective","EMPTY_TOOL_MENTIONS","Readonly","Object","freeze","toolMentionSource","empty","read","aui","tools","thread","getModelContext","mentions","create","name","tool","entries","subscribe","onChange","unsubscribeContext","on","unsubscribeSelection","scope","event","isEqual","unstable_useMentionAdapter","options","adapter","directive","includeTools","toolsConfig","undefined","wantsTools","isCategorized","toolMentions","defaultIcon","toolItems","map","toTriggerItem","groups","cat","allGroups","length","categoryItems","find","g","search","query","lower","toLowerCase","flatMap","filter","flatItems","seen","Set","i","flatPool","t","has","m"],"sources":["../../src/unstable/useMentionAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport { useMemo, type FC } from \"react\";\nimport { useAui } from \"@assistant-ui/store\";\nimport type {\n  Unstable_DirectiveFormatter,\n  Unstable_TriggerAdapter,\n  Unstable_TriggerCategory,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/core\";\nimport { unstable_defaultDirectiveFormatter } from \"@assistant-ui/core\";\nimport type { ReadonlyJSONObject } from \"assistant-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 = FC<{ 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 React 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?: Unstable_UseMentionAdapterOptions,\n): {\n  adapter: Unstable_TriggerAdapter;\n  directive: Unstable_MentionDirective;\n  iconMap?: Record<string, Unstable_IconComponent>;\n  fallbackIcon?: Unstable_IconComponent;\n} {\n  const aui = useAui();\n\n  const items = options?.items;\n  const categories = options?.categories;\n  const includeTools =\n    options?.includeModelContextTools ?? (!items && !categories);\n  const toolsConfig =\n    typeof includeTools === \"object\" ? includeTools : undefined;\n  const wantsTools = includeTools !== false;\n  const formatter = options?.formatter;\n  const onInserted = options?.onInserted;\n  const isCategorized =\n    categories !== undefined ||\n    (toolsConfig?.category !== undefined && items === undefined);\n  const toolMentions = useModelContextSnapshot(\n    aui,\n    wantsTools,\n    toolMentionSource,\n  );\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(() => {\n    const formatLabel = toolsConfig?.formatLabel;\n    const defaultIcon = toolsConfig?.icon;\n    const toolItems = wantsTools\n      ? Object.entries(toolMentions).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) {\n      const groups = (categories ?? []).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?.category?.id ?? \"tools\",\n                label: toolsConfig?.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 ?? []).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  }, [items, categories, wantsTools, toolsConfig, isCategorized, toolMentions]);\n\n  const directive = useMemo<Unstable_MentionDirective>(\n    () => ({\n      formatter: formatter ?? unstable_defaultDirectiveFormatter,\n      ...(onInserted ? { onInserted } : {}),\n    }),\n    [formatter, onInserted],\n  );\n\n  return {\n    adapter,\n    directive,\n    ...(options?.iconMap ? { iconMap: options.iconMap } : {}),\n    ...(options?.fallbackIcon ? { fallbackIcon: options.fallbackIcon } : {}),\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

@@ -1,3 +1,4 @@
+/** @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
@@ -6,6 +7,7 @@ export type Unstable_MessageStallDetectionOptions = {
      */
     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;
@@ -13,8 +15,6 @@ export type Unstable_MessageStallDetection = {
     stalledForMs: number;
 };
 /**
- * @deprecated Under active development and might change without notice.
- *
  * 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`.
@@ -22,6 +22,8 @@ export type Unstable_MessageStallDetection = {
  * 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?: Unstable_MessageStallDetectionOptions): Unstable_MessageStallDetection;
 //# sourceMappingURL=useMessageStallDetection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useMessageStallDetection.d.ts","sourceRoot":"","sources":["../../src/unstable/useMessageStallDetection.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,qCAAqC,GAAG;IAClD;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,CAAC,EAAE,qCAAqC,GAC9C,8BAA8B,CA8DhC"}
+{"version":3,"file":"useMessageStallDetection.d.ts","sourceRoot":"","sources":["../../src/unstable/useMessageStallDetection.ts"],"names":[],"mappings":"AAMA,+GAA+G;AAC/G,MAAM,MAAM,qCAAqC,GAAG;IAClD;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,+GAA+G;AAC/G,MAAM,MAAM,8BAA8B,GAAG;IAC3C,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,CAAC,EAAE,qCAAqC,GAC9C,8BAA8B,CAkEhC"}

package/dist/unstable/useMessageStallDetection.js

@@ -4,8 +4,6 @@ import { useAuiState } from "@assistant-ui/store";
 import { useShallowSelector } from "@assistant-ui/store/internal";
 //#region src/unstable/useMessageStallDetection.ts
 /**
-* @deprecated Under active development and might change without notice.
-*
 * 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`.
@@ -13,6 +11,8 @@ import { useShallowSelector } from "@assistant-ui/store/internal";
 * 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.
 */
 function unstable_useMessageStallDetection(options) {
 	const thresholdMs = options?.thresholdMs ?? 2e3;
@@ -25,9 +25,9 @@ function unstable_useMessageStallDetection(options) {
 		return values;
 	}));
 	const running = activity[0] === true;
-	const lastActivityRef = useRef(Date.now());
+	const lastActivityRef = useRef(0);
 	const [stalled, setStalled] = useState(false);
-	const [, setTick] = useState(0);
+	const [now, setNow] = useState(0);
 	useEffect(() => {
 		if (!running) return void 0;
 		lastActivityRef.current = Date.now();
@@ -37,13 +37,17 @@ function unstable_useMessageStallDetection(options) {
 			setStalled(false);
 			return;
 		}
+		const stall = () => {
+			setNow(Date.now());
+			setStalled(true);
+		};
 		const sinceActivity = Date.now() - lastActivityRef.current;
 		if (sinceActivity >= thresholdMs) {
-			setStalled(true);
+			stall();
 			return;
 		}
 		setStalled(false);
-		const id = setTimeout(() => setStalled(true), thresholdMs - sinceActivity);
+		const id = setTimeout(stall, thresholdMs - sinceActivity);
 		return () => clearTimeout(id);
 	}, [
 		running,
@@ -52,7 +56,7 @@ function unstable_useMessageStallDetection(options) {
 	]);
 	useEffect(() => {
 		if (!stalled) return void 0;
-		const id = setInterval(() => setTick((t) => t + 1), 1e3);
+		const id = setInterval(() => setNow(Date.now()), 1e3);
 		return () => clearInterval(id);
 	}, [stalled]);
 	if (!stalled) return {
@@ -61,7 +65,7 @@ function unstable_useMessageStallDetection(options) {
 	};
 	return {
 		stalled: true,
-		stalledForMs: Math.max(0, Date.now() - lastActivityRef.current)
+		stalledForMs: Math.max(0, now - lastActivityRef.current)
 	};
 }
 //#endregion

package/dist/unstable/useMessageStallDetection.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMessageStallDetection.js","names":["useEffect","useRef","useState","useAuiState","useShallowSelector","Unstable_MessageStallDetectionOptions","thresholdMs","Unstable_MessageStallDetection","stalled","stalledForMs","unstable_useMessageStallDetection","options","activity","s","running","message","status","type","values","content","length","part","push","text","argsText","result","undefined","lastActivityRef","Date","now","setStalled","setTick","current","sinceActivity","id","setTimeout","clearTimeout","setInterval","t","clearInterval","Math","max"],"sources":["../../src/unstable/useMessageStallDetection.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { useAuiState } from \"@assistant-ui/store\";\nimport { useShallowSelector } from \"@assistant-ui/store/internal\";\n\nexport type Unstable_MessageStallDetectionOptions = {\n  /**\n   * Milliseconds of unchanged message content before the message counts as\n   * stalled.\n   * @default 2000\n   */\n  thresholdMs?: number | undefined;\n};\n\nexport type Unstable_MessageStallDetection = {\n  /** True while the message is running and its content has not changed for at least `thresholdMs`. */\n  stalled: boolean;\n  /** Milliseconds since the last observed content change. `0` while not stalled. */\n  stalledForMs: number;\n};\n\n/**\n * @deprecated Under active development and might change without notice.\n *\n * Detects mid-run output stalls on the current message: while the message is\n * running, watches its text, reasoning, and tool-argument values plus tool-result\n * availability and reports a stall once they stop changing for `thresholdMs`.\n * Useful for re-surfacing a \"still working\" indicator during tool think-time or\n * provider stalls, after the first tokens have already streamed.\n *\n * Must be used inside a message scope.\n */\nexport function unstable_useMessageStallDetection(\n  options?: Unstable_MessageStallDetectionOptions,\n): Unstable_MessageStallDetection {\n  const thresholdMs = options?.thresholdMs ?? 2000;\n\n  const activity = useAuiState(\n    useShallowSelector((s) => {\n      const running = s.message.status?.type === \"running\";\n      if (!running) return [false];\n\n      const values: unknown[] = [true, s.message.content.length];\n\n      for (const part of s.message.content) {\n        if (part.type === \"text\" || part.type === \"reasoning\") {\n          values.push(part.type, part.text);\n        } else if (part.type === \"tool-call\") {\n          values.push(part.type, part.argsText, part.result !== undefined);\n        } else {\n          values.push(part.type);\n        }\n      }\n      return values;\n    }),\n  );\n\n  const running = activity[0] === true;\n  const lastActivityRef = useRef(Date.now());\n  const [stalled, setStalled] = useState(false);\n  const [, setTick] = useState(0);\n\n  useEffect(() => {\n    if (!running) return undefined;\n    lastActivityRef.current = Date.now();\n    return undefined;\n  }, [running, activity]);\n\n  useEffect(() => {\n    if (!running) {\n      setStalled(false);\n      return undefined;\n    }\n\n    const sinceActivity = Date.now() - lastActivityRef.current;\n    if (sinceActivity >= thresholdMs) {\n      setStalled(true);\n      return undefined;\n    }\n\n    setStalled(false);\n    const id = setTimeout(() => setStalled(true), thresholdMs - sinceActivity);\n    return () => clearTimeout(id);\n  }, [running, activity, thresholdMs]);\n\n  useEffect(() => {\n    if (!stalled) return undefined;\n    const id = setInterval(() => setTick((t) => t + 1), 1000);\n    return () => clearInterval(id);\n  }, [stalled]);\n\n  if (!stalled) return { stalled: false, stalledForMs: 0 };\n  return {\n    stalled: true,\n    stalledForMs: Math.max(0, Date.now() - lastActivityRef.current),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiCA,SAAgBU,kCACdC,SACgC;CAChC,MAAML,cAAcK,SAASL,eAAe;CAE5C,MAAMM,WAAWT,YACfC,oBAAoBS,MAAM;EAExB,IAAI,EADYA,EAAEE,QAAQC,QAAQC,SAAS,YAC7B,OAAO,CAAC,KAAK;EAE3B,MAAMC,SAAoB,CAAC,MAAML,EAAEE,QAAQI,QAAQC,MAAM;EAEzD,KAAK,MAAMC,QAAQR,EAAEE,QAAQI,SAC3B,IAAIE,KAAKJ,SAAS,UAAUI,KAAKJ,SAAS,aACxCC,OAAOI,KAAKD,KAAKJ,MAAMI,KAAKE,IAAI;OAC3B,IAAIF,KAAKJ,SAAS,aACvBC,OAAOI,KAAKD,KAAKJ,MAAMI,KAAKG,UAAUH,KAAKI,WAAWC,KAAAA,CAAS;OAE/DR,OAAOI,KAAKD,KAAKJ,IAAI;EAGzB,OAAOC;CACT,CAAC,CACH;CAEA,MAAMJ,UAAUF,SAAS,OAAO;CAChC,MAAMe,kBAAkB1B,OAAO2B,KAAKC,IAAI,CAAC;CACzC,MAAM,CAACrB,SAASsB,cAAc5B,SAAS,KAAK;CAC5C,MAAM,GAAG6B,WAAW7B,SAAS,CAAC;CAE9BF,gBAAgB;EACd,IAAI,CAACc,SAAS,OAAOY,KAAAA;EACrBC,gBAAgBK,UAAUJ,KAAKC,IAAI;CAErC,GAAG,CAACf,SAASF,QAAQ,CAAC;CAEtBZ,gBAAgB;EACd,IAAI,CAACc,SAAS;GACZgB,WAAW,KAAK;GAChB;EACF;EAEA,MAAMG,gBAAgBL,KAAKC,IAAI,IAAIF,gBAAgBK;EACnD,IAAIC,iBAAiB3B,aAAa;GAChCwB,WAAW,IAAI;GACf;EACF;EAEAA,WAAW,KAAK;EAChB,MAAMI,KAAKC,iBAAiBL,WAAW,IAAI,GAAGxB,cAAc2B,aAAa;EACzE,aAAaG,aAAaF,EAAE;CAC9B,GAAG;EAACpB;EAASF;EAAUN;CAAW,CAAC;CAEnCN,gBAAgB;EACd,IAAI,CAACQ,SAAS,OAAOkB,KAAAA;EACrB,MAAMQ,KAAKG,kBAAkBN,SAASO,MAAMA,IAAI,CAAC,GAAG,GAAI;EACxD,aAAaC,cAAcL,EAAE;CAC/B,GAAG,CAAC1B,OAAO,CAAC;CAEZ,IAAI,CAACA,SAAS,OAAO;EAAEA,SAAS;EAAOC,cAAc;CAAE;CACvD,OAAO;EACLD,SAAS;EACTC,cAAc+B,KAAKC,IAAI,GAAGb,KAAKC,IAAI,IAAIF,gBAAgBK,OAAO;CAChE;AACF"}
+{"version":3,"file":"useMessageStallDetection.js","names":["useEffect","useRef","useState","useAuiState","useShallowSelector","Unstable_MessageStallDetectionOptions","thresholdMs","Unstable_MessageStallDetection","stalled","stalledForMs","unstable_useMessageStallDetection","options","activity","s","running","message","status","type","values","content","length","part","push","text","argsText","result","undefined","lastActivityRef","setStalled","now","setNow","current","Date","stall","sinceActivity","id","setTimeout","clearTimeout","setInterval","clearInterval","Math","max"],"sources":["../../src/unstable/useMessageStallDetection.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { useAuiState } from \"@assistant-ui/store\";\nimport { useShallowSelector } from \"@assistant-ui/store/internal\";\n\n/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_MessageStallDetectionOptions = {\n  /**\n   * Milliseconds of unchanged message content before the message counts as\n   * stalled.\n   * @default 2000\n   */\n  thresholdMs?: number | undefined;\n};\n\n/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_MessageStallDetection = {\n  /** True while the message is running and its content has not changed for at least `thresholdMs`. */\n  stalled: boolean;\n  /** Milliseconds since the last observed content change. `0` while not stalled. */\n  stalledForMs: number;\n};\n\n/**\n * Detects mid-run output stalls on the current message: while the message is\n * running, watches its text, reasoning, and tool-argument values plus tool-result\n * availability and reports a stall once they stop changing for `thresholdMs`.\n * Useful for re-surfacing a \"still working\" indicator during tool think-time or\n * provider stalls, after the first tokens have already streamed.\n *\n * Must be used inside a message scope.\n *\n * @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release.\n */\nexport function unstable_useMessageStallDetection(\n  options?: Unstable_MessageStallDetectionOptions,\n): Unstable_MessageStallDetection {\n  const thresholdMs = options?.thresholdMs ?? 2000;\n\n  const activity = useAuiState(\n    useShallowSelector((s) => {\n      const running = s.message.status?.type === \"running\";\n      if (!running) return [false];\n\n      const values: unknown[] = [true, s.message.content.length];\n\n      for (const part of s.message.content) {\n        if (part.type === \"text\" || part.type === \"reasoning\") {\n          values.push(part.type, part.text);\n        } else if (part.type === \"tool-call\") {\n          values.push(part.type, part.argsText, part.result !== undefined);\n        } else {\n          values.push(part.type);\n        }\n      }\n      return values;\n    }),\n  );\n\n  const running = activity[0] === true;\n  const lastActivityRef = useRef(0);\n  const [stalled, setStalled] = useState(false);\n  const [now, setNow] = useState(0);\n\n  useEffect(() => {\n    if (!running) return undefined;\n    lastActivityRef.current = Date.now();\n    return undefined;\n  }, [running, activity]);\n\n  useEffect(() => {\n    if (!running) {\n      setStalled(false);\n      return undefined;\n    }\n\n    const stall = () => {\n      setNow(Date.now());\n      setStalled(true);\n    };\n    const sinceActivity = Date.now() - lastActivityRef.current;\n    if (sinceActivity >= thresholdMs) {\n      stall();\n      return undefined;\n    }\n\n    setStalled(false);\n    const id = setTimeout(stall, thresholdMs - sinceActivity);\n    return () => clearTimeout(id);\n  }, [running, activity, thresholdMs]);\n\n  useEffect(() => {\n    if (!stalled) return undefined;\n    const id = setInterval(() => setNow(Date.now()), 1000);\n    return () => clearInterval(id);\n  }, [stalled]);\n\n  if (!stalled) return { stalled: false, stalledForMs: 0 };\n  return {\n    stalled: true,\n    stalledForMs: Math.max(0, now - lastActivityRef.current),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAmCA,SAAgBU,kCACdC,SACgC;CAChC,MAAML,cAAcK,SAASL,eAAe;CAE5C,MAAMM,WAAWT,YACfC,oBAAoBS,MAAM;EAExB,IAAI,EADYA,EAAEE,QAAQC,QAAQC,SAAS,YAC7B,OAAO,CAAC,KAAK;EAE3B,MAAMC,SAAoB,CAAC,MAAML,EAAEE,QAAQI,QAAQC,MAAM;EAEzD,KAAK,MAAMC,QAAQR,EAAEE,QAAQI,SAC3B,IAAIE,KAAKJ,SAAS,UAAUI,KAAKJ,SAAS,aACxCC,OAAOI,KAAKD,KAAKJ,MAAMI,KAAKE,IAAI;OAC3B,IAAIF,KAAKJ,SAAS,aACvBC,OAAOI,KAAKD,KAAKJ,MAAMI,KAAKG,UAAUH,KAAKI,WAAWC,KAAAA,CAAS;OAE/DR,OAAOI,KAAKD,KAAKJ,IAAI;EAGzB,OAAOC;CACT,CAAC,CACH;CAEA,MAAMJ,UAAUF,SAAS,OAAO;CAChC,MAAMe,kBAAkB1B,OAAO,CAAC;CAChC,MAAM,CAACO,SAASoB,cAAc1B,SAAS,KAAK;CAC5C,MAAM,CAAC2B,KAAKC,UAAU5B,SAAS,CAAC;CAEhCF,gBAAgB;EACd,IAAI,CAACc,SAAS,OAAOY,KAAAA;EACrBC,gBAAgBI,UAAUC,KAAKH,IAAI;CAErC,GAAG,CAACf,SAASF,QAAQ,CAAC;CAEtBZ,gBAAgB;EACd,IAAI,CAACc,SAAS;GACZc,WAAW,KAAK;GAChB;EACF;EAEA,MAAMK,cAAc;GAClBH,OAAOE,KAAKH,IAAI,CAAC;GACjBD,WAAW,IAAI;EACjB;EACA,MAAMM,gBAAgBF,KAAKH,IAAI,IAAIF,gBAAgBI;EACnD,IAAIG,iBAAiB5B,aAAa;GAChC2B,MAAM;GACN;EACF;EAEAL,WAAW,KAAK;EAChB,MAAMO,KAAKC,WAAWH,OAAO3B,cAAc4B,aAAa;EACxD,aAAaG,aAAaF,EAAE;CAC9B,GAAG;EAACrB;EAASF;EAAUN;CAAW,CAAC;CAEnCN,gBAAgB;EACd,IAAI,CAACQ,SAAS,OAAOkB,KAAAA;EACrB,MAAMS,KAAKG,kBAAkBR,OAAOE,KAAKH,IAAI,CAAC,GAAG,GAAI;EACrD,aAAaU,cAAcJ,EAAE;CAC/B,GAAG,CAAC3B,OAAO,CAAC;CAEZ,IAAI,CAACA,SAAS,OAAO;EAAEA,SAAS;EAAOC,cAAc;CAAE;CACvD,OAAO;EACLD,SAAS;EACTC,cAAc+B,KAAKC,IAAI,GAAGZ,MAAMF,gBAAgBI,OAAO;CACzD;AACF"}

package/dist/unstable/useSlashCommandAdapter.d.ts

@@ -1,5 +1,6 @@
 import type { Unstable_TriggerAdapter, Unstable_TriggerItem } from "@assistant-ui/core";
 import type { Unstable_IconComponent } from "./useMentionAdapter.js";
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
 export type Unstable_SlashCommand = {
     readonly id: string;
     readonly label?: string | undefined;
@@ -7,6 +8,7 @@ export type Unstable_SlashCommand = {
     readonly icon?: string | undefined;
     readonly execute: () => void;
 };
+/** @deprecated Experimental since 2026-04-06. Not scheduled for removal; the API may change in any release. */
 export type Unstable_UseSlashCommandAdapterOptions = {
     readonly commands: readonly Unstable_SlashCommand[];
     /** Strip the trigger text from the composer after executing. @default false */
@@ -16,18 +18,19 @@ export type Unstable_UseSlashCommandAdapterOptions = {
     /** 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_SlashCommandAction = {
     readonly onExecute: (item: Unstable_TriggerItem) => void;
     readonly removeOnExecute?: boolean | undefined;
 };
 /**
- * @deprecated Under active development and may change without notice.
- *
  * Bundles slash command definitions (with inline `execute` callbacks) into
  * `{adapter, action}` that plug directly into `ComposerTriggerPopover`.
  * `execute` stays in the hook closure and is never attached to the returned
  * `TriggerItem`, keeping items serializable.
  *
+ * @deprecated Experimental since 2026-04-06. Not scheduled for removal; the API may change in any release.
+ *
  * @example
  * ```tsx
  * const slash = unstable_useSlashCommandAdapter({

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

@@ -1 +1 @@
-{"version":3,"file":"useSlashCommandAdapter.d.ts","sourceRoot":"","sources":["../../src/unstable/useSlashCommandAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,+BAA4B;AAGlE,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,sCAAsC,GAAG;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC1D,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C;IACD,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACjD,YAAY,CAAC,EAAE,sBAAsB,CAAC;CACvC,CAiDA"}
+{"version":3,"file":"useSlashCommandAdapter.d.ts","sourceRoot":"","sources":["../../src/unstable/useSlashCommandAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,+BAA4B;AAGlE,+GAA+G;AAC/G,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,+GAA+G;AAC/G,MAAM,MAAM,sCAAsC,GAAG;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC1D,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;CAChD,CAAC;AAEF,+GAA+G;AAC/G,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C;IACD,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACjD,YAAY,CAAC,EAAE,sBAAsB,CAAC;CACvC,CAiDA"}

package/dist/unstable/useSlashCommandAdapter.js

@@ -1,15 +1,16 @@
 "use client";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect.js";
 import { matchesTriggerItemQuery } from "../primitives/composer/trigger/matchesTriggerItemQuery.js";
-import { useLayoutEffect, useMemo, useRef } from "@assistant-ui/tap/react-shim";
+import { useMemo, useRef } from "@assistant-ui/tap/react-shim";
 //#region src/unstable/useSlashCommandAdapter.ts
 /**
-* @deprecated Under active development and may change without notice.
-*
 * Bundles slash command definitions (with inline `execute` callbacks) into
 * `{adapter, action}` that plug directly into `ComposerTriggerPopover`.
 * `execute` stays in the hook closure and is never attached to the returned
 * `TriggerItem`, keeping items serializable.
 *
+* @deprecated Experimental since 2026-04-06. Not scheduled for removal; the API may change in any release.
+*
 * @example
 * ```tsx
 * const slash = unstable_useSlashCommandAdapter({
@@ -28,7 +29,7 @@ function unstable_useSlashCommandAdapter(options) {
 	const committedItemsRef = useRef(void 0);
 	const nextItems = commands.map(toItem);
 	const items = areTriggerItemsEqual(committedItemsRef.current, nextItems) ? committedItemsRef.current : nextItems;
-	useLayoutEffect(() => {
+	useIsomorphicLayoutEffect(() => {
 		commandsRef.current = commands;
 		committedItemsRef.current = items;
 	}, [commands, items]);

package/dist/unstable/useSlashCommandAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSlashCommandAdapter.js","names":["useLayoutEffect","useMemo","useRef","Unstable_TriggerAdapter","Unstable_TriggerItem","Unstable_IconComponent","matchesTriggerItemQuery","Unstable_SlashCommand","id","label","description","icon","execute","Unstable_UseSlashCommandAdapterOptions","commands","removeOnExecute","iconMap","Record","fallbackIcon","Unstable_SlashCommandAction","onExecute","item","unstable_useSlashCommandAdapter","options","adapter","action","commandsRef","committedItemsRef","undefined","nextItems","map","toItem","items","areTriggerItemsEqual","current","categories","categoryItems","search","query","lower","toLowerCase","filter","find","c","cmd","type","metadata","previous","next","length","every","index","nextItem"],"sources":["../../src/unstable/useSlashCommandAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport { useLayoutEffect, useMemo, useRef } from \"react\";\nimport type {\n  Unstable_TriggerAdapter,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/core\";\nimport type { Unstable_IconComponent } from \"./useMentionAdapter\";\nimport { matchesTriggerItemQuery } from \"../primitives/composer/trigger/matchesTriggerItemQuery\";\n\nexport type Unstable_SlashCommand = {\n  readonly id: string;\n  readonly label?: string | undefined;\n  readonly description?: string | undefined;\n  readonly icon?: string | undefined;\n  readonly execute: () => void;\n};\n\nexport type Unstable_UseSlashCommandAdapterOptions = {\n  readonly commands: readonly Unstable_SlashCommand[];\n  /** Strip the trigger text from the composer after executing. @default false */\n  readonly removeOnExecute?: boolean | undefined;\n  /** Maps `metadata.icon` / `category.id` string keys to React components. */\n  readonly iconMap?: Record<string, Unstable_IconComponent>;\n  /** Fallback icon when no entry in `iconMap` matches. */\n  readonly fallbackIcon?: Unstable_IconComponent;\n};\n\nexport type Unstable_SlashCommandAction = {\n  readonly onExecute: (item: Unstable_TriggerItem) => void;\n  readonly removeOnExecute?: boolean | undefined;\n};\n\n/**\n * @deprecated Under active development and may change without notice.\n *\n * Bundles slash command definitions (with inline `execute` callbacks) into\n * `{adapter, action}` that plug directly into `ComposerTriggerPopover`.\n * `execute` stays in the hook closure and is never attached to the returned\n * `TriggerItem`, keeping items serializable.\n *\n * @example\n * ```tsx\n * const slash = unstable_useSlashCommandAdapter({\n *   commands: [\n *     { id: \"summarize\", execute: () => runSummarize(), icon: \"FileText\" },\n *     { id: \"translate\", execute: () => runTranslate(), icon: \"Languages\" },\n *   ],\n * });\n *\n * <ComposerTriggerPopover char=\"/\" {...slash} />\n * ```\n */\nexport function unstable_useSlashCommandAdapter(\n  options: Unstable_UseSlashCommandAdapterOptions,\n): {\n  adapter: Unstable_TriggerAdapter;\n  action: Unstable_SlashCommandAction;\n  iconMap?: Record<string, Unstable_IconComponent>;\n  fallbackIcon?: Unstable_IconComponent;\n} {\n  const { commands, removeOnExecute } = options;\n\n  const commandsRef = useRef(commands);\n  const committedItemsRef = useRef<readonly Unstable_TriggerItem[]>(undefined);\n  const nextItems = commands.map(toItem);\n  // A referential cache, never state: `items` is always structurally equal to\n  // `nextItems`, so the render-time read cannot change what the adapter shows.\n  const items = areTriggerItemsEqual(committedItemsRef.current, nextItems)\n    ? committedItemsRef.current\n    : nextItems;\n\n  // The adapter's callbacks must only observe commands from committed renders.\n  useLayoutEffect(() => {\n    commandsRef.current = commands;\n    committedItemsRef.current = items;\n  }, [commands, items]);\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(\n    () => ({\n      categories: () => [],\n      categoryItems: () => [],\n      search: (query: string) => {\n        const lower = query.toLowerCase();\n        return items.filter((item) => matchesTriggerItemQuery(item, lower));\n      },\n    }),\n    [items],\n  );\n\n  const action = useMemo<Unstable_SlashCommandAction>(\n    () => ({\n      onExecute: (item) => {\n        commandsRef.current.find((c) => c.id === item.id)?.execute();\n      },\n      ...(removeOnExecute !== undefined ? { removeOnExecute } : {}),\n    }),\n    [removeOnExecute],\n  );\n\n  return useMemo(\n    () => ({\n      adapter,\n      action,\n      ...(options.iconMap ? { iconMap: options.iconMap } : {}),\n      ...(options.fallbackIcon ? { fallbackIcon: options.fallbackIcon } : {}),\n    }),\n    [adapter, action, options.iconMap, options.fallbackIcon],\n  );\n}\n\nfunction toItem(cmd: Unstable_SlashCommand): Unstable_TriggerItem {\n  return {\n    id: cmd.id,\n    type: \"command\",\n    label: cmd.label ?? `/${cmd.id}`,\n    ...(cmd.description !== undefined ? { description: cmd.description } : {}),\n    ...(cmd.icon !== undefined ? { metadata: { icon: cmd.icon } } : {}),\n  };\n}\n\nfunction areTriggerItemsEqual(\n  previous: readonly Unstable_TriggerItem[] | undefined,\n  next: readonly Unstable_TriggerItem[],\n): previous is readonly Unstable_TriggerItem[] {\n  if (!previous || previous.length !== next.length) return false;\n\n  return previous.every((item, index) => {\n    const nextItem = next[index];\n    return (\n      nextItem !== undefined &&\n      item.id === nextItem.id &&\n      item.label === nextItem.label &&\n      item.description === nextItem.description &&\n      item.metadata?.icon === nextItem.metadata?.icon\n    );\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgBsB,gCACdC,SAMA;CACA,MAAM,EAAET,UAAUC,oBAAoBQ;CAEtC,MAAMG,cAAcxB,OAAOY,QAAQ;CACnC,MAAMa,oBAAoBzB,OAAwC0B,KAAAA,CAAS;CAC3E,MAAMC,YAAYf,SAASgB,IAAIC,MAAM;CAGrC,MAAMC,QAAQC,qBAAqBN,kBAAkBO,SAASL,SAAS,IACnEF,kBAAkBO,UAClBL;CAGJ7B,sBAAsB;EACpB0B,YAAYQ,UAAUpB;EACtBa,kBAAkBO,UAAUF;CAC9B,GAAG,CAAClB,UAAUkB,KAAK,CAAC;CAEpB,MAAMR,UAAUvB,eACP;EACLkC,kBAAkB,CAAA;EAClBC,qBAAqB,CAAA;EACrBC,SAASC,UAAkB;GACzB,MAAMC,QAAQD,MAAME,YAAY;GAChC,OAAOR,MAAMS,QAAQpB,SAASf,wBAAwBe,MAAMkB,KAAK,CAAC;EACpE;CACF,IACA,CAACP,KAAK,CACR;CAEA,MAAMP,SAASxB,eACN;EACLmB,YAAYC,SAAS;GACnBK,YAAYQ,QAAQQ,MAAMC,MAAMA,EAAEnC,OAAOa,KAAKb,EAAE,CAAC,EAAEI,QAAQ;EAC7D;EACA,GAAIG,oBAAoBa,KAAAA,IAAY,EAAEb,gBAAgB,IAAI,CAAC;CAC7D,IACA,CAACA,eAAe,CAClB;CAEA,OAAOd,eACE;EACLuB;EACAC;EACA,GAAIF,QAAQP,UAAU,EAAEA,SAASO,QAAQP,QAAQ,IAAI,CAAC;EACtD,GAAIO,QAAQL,eAAe,EAAEA,cAAcK,QAAQL,aAAa,IAAI,CAAC;CACvE,IACA;EAACM;EAASC;EAAQF,QAAQP;EAASO,QAAQL;CAAY,CACzD;AACF;AAEA,SAASa,OAAOa,KAAkD;CAChE,OAAO;EACLpC,IAAIoC,IAAIpC;EACRqC,MAAM;EACNpC,OAAOmC,IAAInC,SAAS,IAAImC,IAAIpC;EAC5B,GAAIoC,IAAIlC,gBAAgBkB,KAAAA,IAAY,EAAElB,aAAakC,IAAIlC,YAAY,IAAI,CAAC;EACxE,GAAIkC,IAAIjC,SAASiB,KAAAA,IAAY,EAAEkB,UAAU,EAAEnC,MAAMiC,IAAIjC,KAAK,EAAE,IAAI,CAAC;CACnE;AACF;AAEA,SAASsB,qBACPc,UACAC,MAC6C;CAC7C,IAAI,CAACD,YAAYA,SAASE,WAAWD,KAAKC,QAAQ,OAAO;CAEzD,OAAOF,SAASG,OAAO7B,MAAM8B,UAAU;EACrC,MAAMC,WAAWJ,KAAKG;EACtB,OACEC,aAAaxB,KAAAA,KACbP,KAAKb,OAAO4C,SAAS5C,MACrBa,KAAKZ,UAAU2C,SAAS3C,SACxBY,KAAKX,gBAAgB0C,SAAS1C,eAC9BW,KAAKyB,UAAUnC,SAASyC,SAASN,UAAUnC;CAE/C,CAAC;AACH"}
+{"version":3,"file":"useSlashCommandAdapter.js","names":["useMemo","useRef","useIsomorphicLayoutEffect","Unstable_TriggerAdapter","Unstable_TriggerItem","Unstable_IconComponent","matchesTriggerItemQuery","Unstable_SlashCommand","id","label","description","icon","execute","Unstable_UseSlashCommandAdapterOptions","commands","removeOnExecute","iconMap","Record","fallbackIcon","Unstable_SlashCommandAction","onExecute","item","unstable_useSlashCommandAdapter","options","adapter","action","commandsRef","committedItemsRef","undefined","nextItems","map","toItem","items","areTriggerItemsEqual","current","categories","categoryItems","search","query","lower","toLowerCase","filter","find","c","cmd","type","metadata","previous","next","length","every","index","nextItem"],"sources":["../../src/unstable/useSlashCommandAdapter.ts"],"sourcesContent":["\"use client\";\n\nimport { useMemo, useRef } from \"react\";\nimport { useIsomorphicLayoutEffect } from \"../utils/useIsomorphicLayoutEffect\";\nimport type {\n  Unstable_TriggerAdapter,\n  Unstable_TriggerItem,\n} from \"@assistant-ui/core\";\nimport type { Unstable_IconComponent } from \"./useMentionAdapter\";\nimport { matchesTriggerItemQuery } from \"../primitives/composer/trigger/matchesTriggerItemQuery\";\n\n/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_SlashCommand = {\n  readonly id: string;\n  readonly label?: string | undefined;\n  readonly description?: string | undefined;\n  readonly icon?: string | undefined;\n  readonly execute: () => void;\n};\n\n/** @deprecated Experimental since 2026-04-06. Not scheduled for removal; the API may change in any release. */\nexport type Unstable_UseSlashCommandAdapterOptions = {\n  readonly commands: readonly Unstable_SlashCommand[];\n  /** Strip the trigger text from the composer after executing. @default false */\n  readonly removeOnExecute?: boolean | undefined;\n  /** Maps `metadata.icon` / `category.id` string keys to React 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_SlashCommandAction = {\n  readonly onExecute: (item: Unstable_TriggerItem) => void;\n  readonly removeOnExecute?: boolean | undefined;\n};\n\n/**\n * Bundles slash command definitions (with inline `execute` callbacks) into\n * `{adapter, action}` that plug directly into `ComposerTriggerPopover`.\n * `execute` stays in the hook closure and is never attached to the returned\n * `TriggerItem`, keeping items serializable.\n *\n * @deprecated Experimental since 2026-04-06. Not scheduled for removal; the API may change in any release.\n *\n * @example\n * ```tsx\n * const slash = unstable_useSlashCommandAdapter({\n *   commands: [\n *     { id: \"summarize\", execute: () => runSummarize(), icon: \"FileText\" },\n *     { id: \"translate\", execute: () => runTranslate(), icon: \"Languages\" },\n *   ],\n * });\n *\n * <ComposerTriggerPopover char=\"/\" {...slash} />\n * ```\n */\nexport function unstable_useSlashCommandAdapter(\n  options: Unstable_UseSlashCommandAdapterOptions,\n): {\n  adapter: Unstable_TriggerAdapter;\n  action: Unstable_SlashCommandAction;\n  iconMap?: Record<string, Unstable_IconComponent>;\n  fallbackIcon?: Unstable_IconComponent;\n} {\n  const { commands, removeOnExecute } = options;\n\n  const commandsRef = useRef(commands);\n  const committedItemsRef = useRef<readonly Unstable_TriggerItem[]>(undefined);\n  const nextItems = commands.map(toItem);\n  // A referential cache, never state: `items` is always structurally equal to\n  // `nextItems`, so the render-time read cannot change what the adapter shows.\n  const items = areTriggerItemsEqual(committedItemsRef.current, nextItems)\n    ? committedItemsRef.current\n    : nextItems;\n\n  // The adapter's callbacks must only observe commands from committed renders.\n  useIsomorphicLayoutEffect(() => {\n    commandsRef.current = commands;\n    committedItemsRef.current = items;\n  }, [commands, items]);\n\n  const adapter = useMemo<Unstable_TriggerAdapter>(\n    () => ({\n      categories: () => [],\n      categoryItems: () => [],\n      search: (query: string) => {\n        const lower = query.toLowerCase();\n        return items.filter((item) => matchesTriggerItemQuery(item, lower));\n      },\n    }),\n    [items],\n  );\n\n  const action = useMemo<Unstable_SlashCommandAction>(\n    () => ({\n      onExecute: (item) => {\n        commandsRef.current.find((c) => c.id === item.id)?.execute();\n      },\n      ...(removeOnExecute !== undefined ? { removeOnExecute } : {}),\n    }),\n    [removeOnExecute],\n  );\n\n  return useMemo(\n    () => ({\n      adapter,\n      action,\n      ...(options.iconMap ? { iconMap: options.iconMap } : {}),\n      ...(options.fallbackIcon ? { fallbackIcon: options.fallbackIcon } : {}),\n    }),\n    [adapter, action, options.iconMap, options.fallbackIcon],\n  );\n}\n\nfunction toItem(cmd: Unstable_SlashCommand): Unstable_TriggerItem {\n  return {\n    id: cmd.id,\n    type: \"command\",\n    label: cmd.label ?? `/${cmd.id}`,\n    ...(cmd.description !== undefined ? { description: cmd.description } : {}),\n    ...(cmd.icon !== undefined ? { metadata: { icon: cmd.icon } } : {}),\n  };\n}\n\nfunction areTriggerItemsEqual(\n  previous: readonly Unstable_TriggerItem[] | undefined,\n  next: readonly Unstable_TriggerItem[],\n): previous is readonly Unstable_TriggerItem[] {\n  if (!previous || previous.length !== next.length) return false;\n\n  return previous.every((item, index) => {\n    const nextItem = next[index];\n    return (\n      nextItem !== undefined &&\n      item.id === nextItem.id &&\n      item.label === nextItem.label &&\n      item.description === nextItem.description &&\n      item.metadata?.icon === nextItem.metadata?.icon\n    );\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgBsB,gCACdC,SAMA;CACA,MAAM,EAAET,UAAUC,oBAAoBQ;CAEtC,MAAMG,cAAczB,OAAOa,QAAQ;CACnC,MAAMa,oBAAoB1B,OAAwC2B,KAAAA,CAAS;CAC3E,MAAMC,YAAYf,SAASgB,IAAIC,MAAM;CAGrC,MAAMC,QAAQC,qBAAqBN,kBAAkBO,SAASL,SAAS,IACnEF,kBAAkBO,UAClBL;CAGJ3B,gCAAgC;EAC9BwB,YAAYQ,UAAUpB;EACtBa,kBAAkBO,UAAUF;CAC9B,GAAG,CAAClB,UAAUkB,KAAK,CAAC;CAEpB,MAAMR,UAAUxB,eACP;EACLmC,kBAAkB,CAAA;EAClBC,qBAAqB,CAAA;EACrBC,SAASC,UAAkB;GACzB,MAAMC,QAAQD,MAAME,YAAY;GAChC,OAAOR,MAAMS,QAAQpB,SAASf,wBAAwBe,MAAMkB,KAAK,CAAC;EACpE;CACF,IACA,CAACP,KAAK,CACR;CAEA,MAAMP,SAASzB,eACN;EACLoB,YAAYC,SAAS;GACnBK,YAAYQ,QAAQQ,MAAMC,MAAMA,EAAEnC,OAAOa,KAAKb,EAAE,CAAC,EAAEI,QAAQ;EAC7D;EACA,GAAIG,oBAAoBa,KAAAA,IAAY,EAAEb,gBAAgB,IAAI,CAAC;CAC7D,IACA,CAACA,eAAe,CAClB;CAEA,OAAOf,eACE;EACLwB;EACAC;EACA,GAAIF,QAAQP,UAAU,EAAEA,SAASO,QAAQP,QAAQ,IAAI,CAAC;EACtD,GAAIO,QAAQL,eAAe,EAAEA,cAAcK,QAAQL,aAAa,IAAI,CAAC;CACvE,IACA;EAACM;EAASC;EAAQF,QAAQP;EAASO,QAAQL;CAAY,CACzD;AACF;AAEA,SAASa,OAAOa,KAAkD;CAChE,OAAO;EACLpC,IAAIoC,IAAIpC;EACRqC,MAAM;EACNpC,OAAOmC,IAAInC,SAAS,IAAImC,IAAIpC;EAC5B,GAAIoC,IAAIlC,gBAAgBkB,KAAAA,IAAY,EAAElB,aAAakC,IAAIlC,YAAY,IAAI,CAAC;EACxE,GAAIkC,IAAIjC,SAASiB,KAAAA,IAAY,EAAEkB,UAAU,EAAEnC,MAAMiC,IAAIjC,KAAK,EAAE,IAAI,CAAC;CACnE;AACF;AAEA,SAASsB,qBACPc,UACAC,MAC6C;CAC7C,IAAI,CAACD,YAAYA,SAASE,WAAWD,KAAKC,QAAQ,OAAO;CAEzD,OAAOF,SAASG,OAAO7B,MAAM8B,UAAU;EACrC,MAAMC,WAAWJ,KAAKG;EACtB,OACEC,aAAaxB,KAAAA,KACbP,KAAKb,OAAO4C,SAAS5C,MACrBa,KAAKZ,UAAU2C,SAAS3C,SACxBY,KAAKX,gBAAgB0C,SAAS1C,eAC9BW,KAAKyB,UAAUnC,SAASyC,SAASN,UAAUnC;CAE/C,CAAC;AACH"}

package/dist/unstable/webmcp/useWebMcpProvider.d.ts

@@ -1,7 +1,9 @@
 import type { Tool } from "assistant-stream";
+/** @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release. */
 export type Unstable_WebMcpProviderOptions = {
     filter?: (name: string, tool: Tool<any, any>) => boolean;
 };
+/** @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release. */
 export type Unstable_WebMcpProviderResult = {
     status: "unsupported" | "active";
     registeredToolNames: readonly string[];
@@ -13,6 +15,8 @@ export type Unstable_WebMcpProviderResult = {
  * Returns `status: "unsupported"` when the page exposes no
  * `document.modelContext` (or `navigator.modelContext`), and the sorted names
  * of the tools currently registered with the host.
+ *
+ * @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release.
  */
 export declare const unstable_useWebMcpProvider: (options?: Unstable_WebMcpProviderOptions) => Unstable_WebMcpProviderResult;
 //# sourceMappingURL=useWebMcpProvider.d.ts.map

package/dist/unstable/webmcp/useWebMcpProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useWebMcpProvider.d.ts","sourceRoot":"","sources":["../../../src/unstable/webmcp/useWebMcpProvider.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAU7C,MAAM,MAAM,8BAA8B,GAAG;IAC3C,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;IACjC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CAAC;AA8FF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAS,8BAAmC,KAC3C,6BAyCF,CAAC"}
+{"version":3,"file":"useWebMcpProvider.d.ts","sourceRoot":"","sources":["../../../src/unstable/webmcp/useWebMcpProvider.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAU7C,+GAA+G;AAC/G,MAAM,MAAM,8BAA8B,GAAG;IAC3C,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC;CAC1D,CAAC;AAEF,+GAA+G;AAC/G,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;IACjC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CAAC;AA8FF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAS,8BAAmC,KAC3C,6BAyCF,CAAC"}

package/dist/unstable/webmcp/useWebMcpProvider.js

@@ -80,6 +80,8 @@ const useWebMcpRegistry = (t0) => {
 * Returns `status: "unsupported"` when the page exposes no
 * `document.modelContext` (or `navigator.modelContext`), and the sorted names
 * of the tools currently registered with the host.
+*
+* @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release.
 */
 const unstable_useWebMcpProvider = (options = {}) => {
 	const aui = useAui();