@assistant-ui/react 0.15.25 → 0.15.27

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { useComposedRefs } from "radix-ui/internal";
-import { useCallback, useLayoutEffect, useRef, type RefCallback } from "react";
+import { useCallback, useRef, type RefCallback } from "react";
 import { useAui, useAuiEvent, useAuiState } from "@assistant-ui/store";
 import {
   isUserScrollUp,
@@ -13,12 +13,21 @@ import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useManagedRef } from "../../utils/hooks/useManagedRef";
 import { writableStore } from "../../context/ReadonlyStore";
 import { useThreadViewportStore } from "../../context/react/ThreadViewportContext";
-
-// Enter and Space activate a focused control, which is how a collapsible tool
-// call expands without a pointer event ever firing. No other key changes thread
-// content: the keys that scroll the viewport reach handleScroll, which already
-// clears the intent when the user scrolls up.
-const ACTIVATION_KEYS = new Set(["Enter", " "]);
+import { useIsomorphicLayoutEffect } from "../../utils/useIsomorphicLayoutEffect";
+
+const SCROLL_KEYS = new Set([
+  " ",
+  "ArrowUp",
+  "ArrowDown",
+  "PageUp",
+  "PageDown",
+  "Home",
+  "End",
+]);
+
+// Enter and Space activate focused controls, while navigation keys can
+// interrupt scrolling without producing a scroll event.
+const INTENT_CANCEL_KEYS = new Set(["Enter", ...SCROLL_KEYS]);
 
 // A control that consumes the activation key itself instead of acting on thread
 // content. `contenteditable="false"` marks a non-editable island inside an
@@ -35,6 +44,22 @@ const TEXT_ENTRY_SELECTOR = [
 
 const MESSAGE_SELECTOR = "[data-message-id]";
 
+const DISCLOSURE_SELECTOR = "[aria-expanded], summary";
+
+// A popup trigger (menu, dialog, listbox) also carries aria-expanded, but what
+// it opens is portaled away from the thread, so only disclosures count.
+const isOpeningDisclosure = (target: Element): boolean => {
+  const control = target.closest(DISCLOSURE_SELECTOR);
+  if (!control) return false;
+  if (control.tagName === "SUMMARY")
+    return control.parentElement?.hasAttribute("open") === false;
+  return (
+    control.getAttribute("aria-expanded") === "false" &&
+    (control.getAttribute("aria-haspopup") ?? "false") === "false" &&
+    control.getAttribute("role") !== "combobox"
+  );
+};
+
 type MessageOffset = { readonly id: string; readonly offset: number };
 
 const offsetInViewport = (element: Element, viewport: Element) =>
@@ -166,9 +191,15 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   // user actively scrolls up while content size is stable.
   const scrollingToBottomBehaviorRef = useRef<ScrollBehavior | null>(null);
   const followBottomRef = useRef(autoScroll);
+  // Set by expanding a disclosure; suspends follow without clearing its intent
+  // until a scroll gesture reaches an overflowing bottom (content that fits
+  // reads as at the bottom), a run starts, the thread changes, or the reader
+  // asks for the bottom again.
+  const followPausedRef = useRef(false);
+  const scrolledSincePauseRef = useRef(false);
   const previousAutoScrollRef = useRef(autoScroll);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const previousAutoScroll = previousAutoScrollRef.current;
     previousAutoScrollRef.current = autoScroll;
     if (previousAutoScroll || !autoScroll) return;
@@ -182,9 +213,12 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     if (!div) return;
 
     followBottomRef.current = true;
+    followPausedRef.current = false;
     scrollingToBottomBehaviorRef.current = behavior;
     prependAnchorRef.current = null;
     div.scrollTo({ top: div.scrollHeight, behavior });
+    lastScrollTop.current = div.scrollTop;
+    lastScrollHeight.current = div.scrollHeight;
   }, []);
 
   const cancelScheduledFrame = useCallback(() => {
@@ -205,7 +239,10 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     [cancelScheduledFrame, scrollToBottom],
   );
 
-  useLayoutEffect(() => () => cancelScheduledFrame(), [cancelScheduledFrame]);
+  useIsomorphicLayoutEffect(
+    () => () => cancelScheduledFrame(),
+    [cancelScheduledFrame],
+  );
 
   const hasActiveTopAnchor = useCallback(() => {
     const state = threadViewportStore.getState();
@@ -216,7 +253,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     );
   }, [threadViewportStore]);
 
-  const handleScroll = () => {
+  const onScroll = () => {
     const div = divRef.current;
     if (!div) return;
 
@@ -231,7 +268,9 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     const newIsAtBottom = isViewportAtBottom(div);
 
     const isInFlightDownwardScroll =
-      !newIsAtBottom && lastScrollTop.current < div.scrollTop;
+      scrollingToBottomBehaviorRef.current !== null &&
+      !newIsAtBottom &&
+      lastScrollTop.current < div.scrollTop;
     if (isInFlightDownwardScroll) {
       // no-op: a smooth scroll-to-bottom fires many midpoint scroll events
       // before landing, don't flicker isAtBottom or clear intent mid-animation
@@ -249,6 +288,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
         // keep intent alive until content can actually scroll
         if (viewportOverflows(div)) {
           scrollingToBottomBehaviorRef.current = null;
+          if (scrolledSincePauseRef.current) followPausedRef.current = false;
         }
         if (autoScroll) followBottomRef.current = true;
       } else if (userScrolledUp) {
@@ -271,8 +311,13 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     lastScrollHeight.current = div.scrollHeight;
     firstMessageRef.current = measureFirstMessage(div);
   };
+  const onScrollRef = useRef(onScroll);
+  useIsomorphicLayoutEffect(() => {
+    onScrollRef.current = onScroll;
+  });
+  const handleScroll = useCallback(() => onScrollRef.current(), []);
 
-  const resizeRef = useOnResizeContent(() => {
+  const onResize = () => {
     const div = divRef.current;
     if (!div) return;
 
@@ -286,75 +331,156 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     lastObservedScrollHeight.current = scrollHeight;
     lastObservedClientHeight.current = clientHeight;
 
-    const scrollBehavior = scrollingToBottomBehaviorRef.current;
-    if (scrollBehavior && hasActiveTopAnchor()) {
-      // Let the top-anchor reserve own scrolling while a run starts to avoid a bottom-scroll race.
-      scrollingToBottomBehaviorRef.current = null;
-    } else if (scrollBehavior) {
-      scrollToBottom(scrollBehavior);
-    } else if (
-      autoScroll &&
-      !(isRunning && hasActiveTopAnchor()) &&
-      followBottomRef.current
-    ) {
-      scrollToBottom("instant");
-    } else if (
-      prependAnchorRef.current &&
-      !keepMessageAt(div, prependAnchorRef.current, heldScrollTopRef)
-    ) {
-      prependAnchorRef.current = null;
+    // A scheduled frame owns the pending behavior; resize callbacks must not apply it early.
+    if (scheduledFrameRef.current === null) {
+      const scrollBehavior = scrollingToBottomBehaviorRef.current;
+      if (scrollBehavior && hasActiveTopAnchor()) {
+        // Let the top-anchor reserve own scrolling while a run starts to avoid a bottom-scroll race.
+        scrollingToBottomBehaviorRef.current = null;
+      } else if (scrollBehavior) {
+        scrollToBottom(scrollBehavior);
+      } else if (
+        autoScroll &&
+        !(isRunning && hasActiveTopAnchor()) &&
+        followBottomRef.current &&
+        !followPausedRef.current
+      ) {
+        scrollToBottom("instant");
+      } else if (
+        prependAnchorRef.current &&
+        !keepMessageAt(div, prependAnchorRef.current, heldScrollTopRef)
+      ) {
+        prependAnchorRef.current = null;
+      }
     }
 
     handleScroll();
+  };
+  const onResizeRef = useRef(onResize);
+  useIsomorphicLayoutEffect(() => {
+    onResizeRef.current = onResize;
   });
-
-  const scrollRef = useManagedRef<HTMLElement>((el) => {
-    // A user gesture invalidates pending bottom-scroll intent; otherwise an
-    // intent kept alive by a non-overflowing thread (see handleScroll) hijacks
-    // the next content growth, e.g. expanding a collapsible tool call. Keyboard
-    // activation reaches that same content without ever emitting a pointer
-    // event, so it has to cancel the intent too.
-    const cancelPendingScrollToBottom = () => {
-      // A scheduled frame re-plants the intent when it runs, so clearing the
-      // ref alone leaves the gesture undone.
-      cancelScheduledFrame();
-      scrollingToBottomBehaviorRef.current = null;
-    };
-    // The composer renders inside the viewport, so its keystrokes bubble here;
-    // only an activation key aimed at something other than a text field is a
-    // gesture on thread content.
-    const cancelOnKeyDown = (event: KeyboardEvent) => {
-      if (!ACTIVATION_KEYS.has(event.key)) return;
-      const target = event.target as Element | null;
-      if (target?.closest?.(TEXT_ENTRY_SELECTOR)) return;
-      cancelPendingScrollToBottom();
-    };
-    const releasePrependAnchor = () => {
-      prependAnchorRef.current = null;
-    };
-    const gestures = ["pointerdown", "wheel", "touchstart", "keydown"] as const;
-    el.addEventListener("scroll", handleScroll);
-    el.addEventListener("pointerdown", cancelPendingScrollToBottom);
-    el.addEventListener("keydown", cancelOnKeyDown);
-    for (const gesture of gestures) {
-      el.addEventListener(gesture, releasePrependAnchor, { passive: true });
-    }
-    return () => {
-      el.removeEventListener("scroll", handleScroll);
-      el.removeEventListener("pointerdown", cancelPendingScrollToBottom);
-      el.removeEventListener("keydown", cancelOnKeyDown);
-      for (const gesture of gestures) {
-        el.removeEventListener(gesture, releasePrependAnchor);
-      }
-    };
-  });
+  const resizeRef = useOnResizeContent(() => onResizeRef.current());
+
+  const scrollRef = useManagedRef<HTMLElement>(
+    useCallback(
+      (el) => {
+        // A user gesture invalidates pending bottom-scroll intent; otherwise an
+        // intent kept alive by a non-overflowing thread (see handleScroll) hijacks
+        // the next content growth, e.g. expanding a collapsible tool call. Keyboard
+        // activation reaches that same content without ever emitting a pointer
+        // event, so it has to cancel the intent too.
+        const cancelPendingScrollToBottom = () => {
+          // With nothing pending, the last scroll event already published isAtBottom.
+          if (
+            scrollingToBottomBehaviorRef.current === null &&
+            scheduledFrameRef.current === null
+          )
+            return;
+          // A scheduled frame re-plants the intent when it runs, so clearing the
+          // ref alone leaves the gesture undone.
+          cancelScheduledFrame();
+          scrollingToBottomBehaviorRef.current = null;
+          handleScroll();
+        };
+        // The composer renders inside the viewport, so its keystrokes bubble here;
+        // cancellation keys only represent a gesture on thread content when they
+        // originate outside text entry.
+        const cancelOnKeyDown = (event: KeyboardEvent) => {
+          if (!INTENT_CANCEL_KEYS.has(event.key)) return;
+          const target = event.target as Element | null;
+          if (target?.closest?.(TEXT_ENTRY_SELECTOR)) return;
+          cancelPendingScrollToBottom();
+        };
+        // Expanding a disclosure inside a message, such as a reasoning block or a
+        // tool call card, means the reader is inspecting it, so bottom follow
+        // pauses until the reader scrolls or asks for the bottom again. Every
+        // other interaction, including copying or selecting text, keeps
+        // following. Activation is read from click, which keyboard activation also
+        // dispatches, in the capture phase so the state is read before any handler
+        // on the disclosure flips it or stops the event.
+        const pauseFollowOnExpand = (event: MouseEvent) => {
+          const target = event.target as Element | null;
+          if (
+            !target?.closest?.(MESSAGE_SELECTOR) ||
+            target.closest(TEXT_ENTRY_SELECTOR) ||
+            !isOpeningDisclosure(target)
+          )
+            return;
+          followPausedRef.current = true;
+          scrolledSincePauseRef.current = false;
+          cancelPendingScrollToBottom();
+        };
+        const noteScrollGesture = (event: Event) => {
+          if (event instanceof KeyboardEvent) {
+            if (!SCROLL_KEYS.has(event.key)) return;
+            if (
+              (event.target as Element | null)?.closest?.(TEXT_ENTRY_SELECTOR)
+            )
+              return;
+          } else if (event.type === "pointerdown" && event.target !== el) {
+            return;
+          }
+          scrolledSincePauseRef.current = true;
+        };
+        const releasePrependAnchor = () => {
+          prependAnchorRef.current = null;
+        };
+        const gestures = [
+          "pointerdown",
+          "wheel",
+          "touchstart",
+          "keydown",
+        ] as const;
+        const resumeGestures = [
+          "pointerdown",
+          "wheel",
+          "touchmove",
+          "keydown",
+        ] as const;
+        el.addEventListener("scroll", handleScroll);
+        el.addEventListener("pointerdown", cancelPendingScrollToBottom);
+        el.addEventListener("wheel", cancelPendingScrollToBottom, {
+          passive: true,
+        });
+        el.addEventListener("touchstart", cancelPendingScrollToBottom, {
+          passive: true,
+        });
+        el.addEventListener("keydown", cancelOnKeyDown);
+        el.addEventListener("click", pauseFollowOnExpand, { capture: true });
+        for (const gesture of resumeGestures) {
+          el.addEventListener(gesture, noteScrollGesture, { passive: true });
+        }
+        for (const gesture of gestures) {
+          el.addEventListener(gesture, releasePrependAnchor, { passive: true });
+        }
+        return () => {
+          el.removeEventListener("scroll", handleScroll);
+          el.removeEventListener("pointerdown", cancelPendingScrollToBottom);
+          el.removeEventListener("wheel", cancelPendingScrollToBottom);
+          el.removeEventListener("touchstart", cancelPendingScrollToBottom);
+          el.removeEventListener("keydown", cancelOnKeyDown);
+          el.removeEventListener("click", pauseFollowOnExpand, {
+            capture: true,
+          });
+          for (const gesture of resumeGestures) {
+            el.removeEventListener(gesture, noteScrollGesture);
+          }
+          for (const gesture of gestures) {
+            el.removeEventListener(gesture, releasePrependAnchor);
+          }
+        };
+      },
+      [cancelScheduledFrame, handleScroll],
+    ),
+  );
 
   // Earlier messages prepended above the reader put the old first message back
   // where the reader saw it, so growth below it in the same commit (a
   // streaming reply) is not mistaken for the page; where the browser already
   // anchored the scroll, this is a no-op.
   const previousRef = useRef({ threadId, firstMessageId });
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const previous = previousRef.current;
     previousRef.current = { threadId, firstMessageId };
     if (previous.threadId !== threadId) {
@@ -367,7 +493,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
       !div ||
       previousFirstMessageId === undefined ||
       previousFirstMessageId === firstMessageId ||
-      (autoScroll && followBottomRef.current) ||
+      (autoScroll && followBottomRef.current && !followPausedRef.current) ||
       scrollingToBottomBehaviorRef.current !== null
     )
       return;
@@ -397,7 +523,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     lastScrollHeight.current = div.scrollHeight;
   }, [aui, autoScroll, firstMessageId, threadId]);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!scrollToBottomOnInitialize) return;
     if (!hasMessages) {
       initializeScrollRequestedRef.current = false;
@@ -418,12 +544,14 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
 
   useAuiEvent("thread.runStart", () => {
     prependAnchorRef.current = null;
+    followPausedRef.current = false;
     if (!scrollToBottomOnRunStart) return;
     if (threadViewportStore.getState().turnAnchor === "top") return;
     scheduleScrollToBottom("auto");
   });
 
   useAuiEvent("threads.selectionChanged", () => {
+    followPausedRef.current = false;
     if (!scrollToBottomOnThreadSwitch) return;
     scheduleScrollToBottom("instant");
   });

package/src/sandbox-host/SandboxHost.tsx

@@ -1,12 +1,7 @@
 "use client";
 
-import {
-  type CSSProperties,
-  useEffect,
-  useLayoutEffect,
-  useRef,
-  useState,
-} from "react";
+import { type CSSProperties, useEffect, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect";
 import {
   isShimLoadError,
   type RenderedFrame,
@@ -95,7 +90,7 @@ export function SandboxHost({
     createBridge,
     onError,
   });
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     liveRef.current = { content, sandbox, createBridge, onError };
   }, [content, sandbox, createBridge, onError]);
 

package/src/unstable/useComposerInput.ts

@@ -12,6 +12,7 @@ import {
   useTriggerPopoverAriaProps,
 } from "../primitives/composer/useComposerInputState";
 
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
 export type Unstable_UseComposerInputOptions = {
   /**
    * Disables the input in addition to the composer's own disabled sources
@@ -21,6 +22,7 @@ export type Unstable_UseComposerInputOptions = {
   disabled?: boolean | undefined;
 };
 
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
 export type Unstable_ComposerInput = {
   /** Current composer text, or `""` when the composer is not editing. */
   value: string;
@@ -49,8 +51,6 @@ export type Unstable_ComposerInput = {
 };
 
 /**
- * @deprecated Under active development and might change without notice.
- *
  * Headless bridge to the composer's text value and send action, for building a
  * custom composer input without `ComposerPrimitive.Input`. It is a thin bridge,
  * not a second input: it does not own keyboard behavior, autosize, IME or
@@ -58,6 +58,8 @@ export type Unstable_ComposerInput = {
  * state. Spread `unstable_useTriggerPopoverAriaProps()` onto your element for
  * trigger-popover combobox semantics.
  *
+ * @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release.
+ *
  * @example
  * ```tsx
  * const { value, setText, send, isDisabled, canSend } = unstable_useComposerInput();
@@ -66,6 +68,8 @@ export type Unstable_ComposerInput = {
  *   disabled={isDisabled}
  *   onChange={(e) => setText(e.target.value)}
  *   onKeyDown={(e) => {
+ *     if (e.nativeEvent.isComposing || e.keyCode === 229) return;
+ *
  *     if (e.key === "Enter" && !e.shiftKey && canSend) {
  *       e.preventDefault();
  *       send();
@@ -104,17 +108,18 @@ export function unstable_useComposerInput(
   return { value, setText, send, isDisabled, canSend };
 }
 
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
 export type Unstable_TriggerPopoverAriaProps = TriggerPopoverAriaProps;
 
 /**
- * @deprecated Under active development and might change without notice.
- *
  * ARIA combobox attributes for the focused element (typically the composer
  * input) describing the open trigger popover, per the WAI-ARIA editable
  * combobox pattern. Returns an empty object outside a `TriggerPopoverRoot` or
  * when no popover is open. Spread these last so they take precedence over any
  * matching ARIA props you set yourself, mirroring `ComposerPrimitive.Input`.
  *
+ * @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release.
+ *
  * @example
  * ```tsx
  * const aria = unstable_useTriggerPopoverAriaProps();

package/src/unstable/useComposerInputHistory.ts

@@ -14,6 +14,7 @@ import type { ThreadMessage } from "@assistant-ui/core";
 import { getThreadMessageText } from "@assistant-ui/core/internal";
 import { useTriggerPopoverRootContextOptional } from "../primitives/composer/trigger/TriggerPopoverRootContext";
 
+/** @deprecated Experimental since 2026-06-11. Not scheduled for removal; the API may change in any release. */
 export type Unstable_ComposerInputHistory = {
   /** Keydown handler to spread onto `ComposerPrimitive.Input`. */
   onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>;
@@ -45,8 +46,6 @@ const isOnLastLine = (value: string, caret: number): boolean =>
   !value.slice(caret).includes("\n");
 
 /**
- * @deprecated Under active development and might change without notice.
- *
  * Terminal-style input history for the thread composer: ArrowUp on an
  * empty draft recalls previously sent user messages (newest first),
  * ArrowDown steps back toward the newest and finally restores the draft
@@ -58,6 +57,8 @@ const isOnLastLine = (value: string, caret: number): boolean =>
  * to modifier keys, and to consumer handlers that already called
  * `preventDefault`. It is inert on edit composers.
  *
+ * @deprecated Experimental since 2026-06-11. Not scheduled for removal; the API may change in any release.
+ *
  * @example
  * ```tsx
  * const history = unstable_useComposerInputHistory();

package/src/unstable/useLiveCompletionAdapter.ts

@@ -1,18 +1,13 @@
 "use client";
 
-import {
-  useCallback,
-  useEffect,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect";
 import type {
   Unstable_TriggerAdapter,
   Unstable_TriggerItem,
 } from "@assistant-ui/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
@@ -35,8 +30,6 @@ export type Unstable_UseLiveCompletionAdapterOptions = {
 const NO_QUERY = "\u0000";
 
 /**
- * @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
@@ -47,6 +40,8 @@ const NO_QUERY = "\u0000";
  * `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({
@@ -75,7 +70,7 @@ export function unstable_useLiveCompletionAdapter(
 
   const fetcherRef = useRef(fetcher);
   // The debounce timer must only observe fetchers from committed renders.
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     fetcherRef.current = fetcher;
   }, [fetcher]);
 
@@ -143,7 +138,7 @@ export function unstable_useLiveCompletionAdapter(
   );
 
   const scheduleFetchRef = useRef(scheduleFetch);
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     scheduleFetchRef.current = scheduleFetch;
   }, [scheduleFetch]);
 
@@ -156,7 +151,7 @@ export function unstable_useLiveCompletionAdapter(
   }, [cancelTimer, rearmPendingRetry]);
 
   const cacheKeyRef = useRef(cacheKey);
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (cacheKeyRef.current === cacheKey) return;
     cacheKeyRef.current = cacheKey;
     invalidatePending();
@@ -175,7 +170,7 @@ export function unstable_useLiveCompletionAdapter(
 
   // Render-time searches can outlive an abandoned render, so they only arm
   // request work after this hook commits.
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     inactiveRef.current = false;
     const deferredQuery = deferredQueryRef.current;
     deferredQueryRef.current = null;

package/src/unstable/useMentionAdapter.ts

@@ -17,9 +17,14 @@ import {
   type ModelContextSnapshotSource,
 } from "./useModelContextSnapshot";
 
-/** 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;
@@ -30,12 +35,14 @@ export type Unstable_Mention = {
   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
@@ -48,6 +55,7 @@ export type Unstable_ModelContextToolsOptions = {
   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
@@ -78,6 +86,7 @@ export type Unstable_UseMentionAdapterOptions = {
   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;
@@ -120,12 +129,12 @@ const toolMentionSource: ModelContextSnapshotSource<
 };
 
 /**
- * @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();