@assistant-ui/react 0.14.26 → 0.14.28

package/src/primitives/messagePart/useMessagePartFile.ts

@@ -1,12 +1,26 @@
 "use client";
 
-import type { FileMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  FileMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_FILE_PART: MessagePartState & FileMessagePart = Object.freeze({
+  type: "file",
+  data: "",
+  mimeType: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
- * Return `null` for optional rendering, or throw inside the selector to
- * preserve the old hook's strict behavior.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +33,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartFile = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const file = useAuiState((s) => {
-    if (s.part.type !== "file")
-      throw new Error(
-        "MessagePartFile can only be used inside file message parts.",
-      );
+    if (s.part.type !== "file") return EMPTY_FILE_PART;
 
     return s.part as MessagePartState & FileMessagePart;
   });

package/src/primitives/messagePart/useMessagePartImage.ts

@@ -1,12 +1,25 @@
 "use client";
 
-import type { ImageMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  ImageMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_IMAGE_PART: MessagePartState & ImageMessagePart = Object.freeze({
+  type: "image",
+  image: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
- * Return `null` for optional rendering, or throw inside the selector to
- * preserve the old hook's strict behavior.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +32,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartImage = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const image = useAuiState((s) => {
-    if (s.part.type !== "image")
-      throw new Error(
-        "MessagePartImage can only be used inside image message parts.",
-      );
+    if (s.part.type !== "image") return EMPTY_IMAGE_PART;
 
     return s.part as MessagePartState & ImageMessagePart;
   });

package/src/primitives/messagePart/useMessagePartReasoning.ts

@@ -3,13 +3,24 @@
 import type {
   ReasoningMessagePart,
   MessagePartState,
+  MessagePartStatus,
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_REASONING_PART: MessagePartState & ReasoningMessagePart =
+  Object.freeze({
+    type: "reasoning",
+    text: "",
+    status: COMPLETE_STATUS,
+  });
+
 /**
  * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
- * Return `null` for optional rendering, or throw inside the selector to
- * preserve the old hook's strict behavior.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -22,11 +33,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartReasoning = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const text = useAuiState((s) => {
-    if (s.part.type !== "reasoning")
-      throw new Error(
-        "MessagePartReasoning can only be used inside reasoning message parts.",
-      );
+    if (s.part.type !== "reasoning") return EMPTY_REASONING_PART;
 
     return s.part as MessagePartState & ReasoningMessagePart;
   });

package/src/primitives/messagePart/useMessagePartSource.ts

@@ -1,12 +1,27 @@
 "use client";
 
-import type { SourceMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  SourceMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_SOURCE_PART: MessagePartState & SourceMessagePart = Object.freeze({
+  type: "source",
+  sourceType: "url",
+  id: "",
+  url: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
- * Return `null` for optional rendering, or throw inside the selector to
- * preserve the old hook's strict behavior.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +34,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartSource = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const source = useAuiState((s) => {
-    if (s.part.type !== "source")
-      throw new Error(
-        "MessagePartSource can only be used inside source message parts.",
-      );
+    if (s.part.type !== "source") return EMPTY_SOURCE_PART;
 
     return s.part as MessagePartState & SourceMessagePart;
   });

package/src/primitives/messagePart/useMessagePartText.ts

@@ -4,13 +4,23 @@ import type {
   TextMessagePart,
   ReasoningMessagePart,
   MessagePartState,
+  MessagePartStatus,
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_TEXT_PART: MessagePartState & TextMessagePart = Object.freeze({
+  type: "text",
+  text: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
- * Return `null` for optional rendering, or throw inside the selector to
- * preserve the old hook's strict behavior.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -23,11 +33,11 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartText = () => {
+  // Runs inside useSyncExternalStore's getSnapshot, where a throw tears down
+  // the React root; the module-level frozen sentinel keeps snapshots stable.
   const text = useAuiState((s) => {
     if (s.part.type !== "text" && s.part.type !== "reasoning")
-      throw new Error(
-        "MessagePartText can only be used inside text or reasoning message parts.",
-      );
+      return EMPTY_TEXT_PART;
 
     return s.part as MessagePartState &
       (TextMessagePart | ReasoningMessagePart);

package/src/primitives/thread/ThreadViewport.tsx

@@ -23,6 +23,7 @@ import { useTopAnchorReserve } from "./topAnchor/useTopAnchorReserve";
 import {
   getActiveTopAnchorAnchorId,
   getActiveTopAnchorTargetId,
+  isTopAnchorTurnValid,
 } from "./topAnchor/topAnchorTurn";
 
 export namespace ThreadPrimitiveViewport {
@@ -110,11 +111,25 @@ const useTopAnchorTurn = (enabled: boolean) => {
     if (!enabled) return undefined;
     return getActiveTopAnchorTargetId(s.thread);
   });
+  const topAnchorTurn = useThreadViewport((s) => s.topAnchorTurn);
   const activeTurn = useMemo(() => {
     if (!activeAnchorId || !activeTargetId) return null;
     return { anchorId: activeAnchorId, targetId: activeTargetId };
   }, [activeAnchorId, activeTargetId]);
 
+  const topAnchorTurnIsValid = useAuiState(
+    (s) =>
+      enabled &&
+      !!topAnchorTurn &&
+      isTopAnchorTurnValid(topAnchorTurn, s.thread.messages),
+  );
+
+  useLayoutEffect(() => {
+    if (!topAnchorTurn || topAnchorTurnIsValid) return;
+
+    threadViewportStore.getState().setTopAnchorTurn(null);
+  }, [threadViewportStore, topAnchorTurn, topAnchorTurnIsValid]);
+
   useLayoutEffect(() => {
     if (!activeTurn) return;
 

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.test.ts

@@ -43,6 +43,7 @@ const makeStore = (state: ReturnType<TopAnchorStore["getState"]>) => {
 };
 
 const numericClamp = { tallerThan: 160, visibleHeight: 96 };
+const activeTopAnchorTurn = { anchorId: "user-1", targetId: "assistant-1" };
 
 describe("mountTopAnchorReserve", () => {
   beforeEach(() => {
@@ -76,6 +77,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
 
     mountTopAnchorReserve(store);
@@ -90,6 +92,245 @@ describe("mountTopAnchorReserve", () => {
     expect(reserve.style.height).toBe("60px");
   });
 
+  it("preserves the reserve across a transient between-turns anchor gap", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    const unmount = mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+    const optimisticUserMessage = document.createElement("div");
+    reserveHost.append(optimisticUserMessage);
+    const appendSpy = vi.spyOn(reserveHost, "append");
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(true);
+    expect(reserve.style.height).toBe("60px");
+    expect(reserve.previousElementSibling).toBe(optimisticUserMessage);
+    expect(appendSpy).toHaveBeenCalledTimes(1);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(appendSpy).toHaveBeenCalledTimes(1);
+
+    const nextAnchor = document.createElement("div");
+    const nextTarget = document.createElement("div");
+    reserveHost.append(nextTarget);
+    defineReadonlyNumber(nextAnchor, "offsetTop", 236);
+    defineReadonlyNumber(nextAnchor, "offsetHeight", 64);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: nextAnchor, target: nextTarget },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.previousElementSibling).toBe(nextTarget);
+
+    unmount();
+    expect(reserve.isConnected).toBe(false);
+  });
+
+  it("removes the reserve when the active turn is no longer valid", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when only the registered anchor unmounts", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when the viewport is unavailable", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport: null, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when top anchoring is disabled", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "bottom",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
   it("does not repeat the smooth top-anchor scroll for the same message", () => {
     const viewport = document.createElement("div");
     const anchor = document.createElement("div");
@@ -108,6 +349,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
 
     mountTopAnchorReserve(store);
@@ -123,6 +365,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
     vi.runOnlyPendingTimers();
 

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.ts

@@ -29,6 +29,10 @@ export type TopAnchorStore = {
       tallerThan: number;
       visibleHeight: number;
     } | null;
+    topAnchorTurn: {
+      readonly anchorId: string;
+      readonly targetId: string;
+    } | null;
   };
   subscribe(fn: () => void): () => void;
 };
@@ -62,13 +66,30 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     const { viewport, anchor, target } = state.element;
     const clamp = state.targetConfig;
 
-    if (
-      state.turnAnchor !== "top" ||
-      !viewport ||
-      !anchor ||
-      !target ||
-      !clamp
-    ) {
+    if (state.turnAnchor !== "top" || !viewport) {
+      observers.disconnect();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    if (!anchor && !target && !clamp && state.topAnchorTurn) {
+      // ThreadViewport clears this state once the stored pair stops being the
+      // trailing turn (followed at most by pending user messages), so reaching
+      // here means the anchor gap is transient and the next run is imminent.
+      observers.disconnect();
+      if (
+        reserve?.parentElement &&
+        reserve.parentElement.lastElementChild !== reserve
+      ) {
+        reserve.parentElement.append(reserve);
+      }
+      return;
+    }
+
+    if (!anchor || !target || !clamp) {
       observers.disconnect();
       if (reserve) {
         setReserveHeight(reserve, 0);

package/src/primitives/thread/topAnchor/topAnchorTurn.test.ts

@@ -3,6 +3,7 @@ import {
   getActiveTopAnchorAnchorId,
   getActiveTopAnchorTargetId,
   getActiveTopAnchorTurn,
+  isTopAnchorTurnValid,
 } from "./topAnchorTurn";
 
 describe("topAnchorTurn", () => {
@@ -43,4 +44,72 @@ describe("topAnchorTurn", () => {
 
     expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toBe(null);
   });
+
+  it("keeps a completed turn valid while it remains the trailing turn", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "assistant-1", role: "assistant" },
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("keeps a turn valid across the between-turns gap with pending user messages", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "user-4", role: "user" },
+      ]),
+    ).toBe(true);
+  });
+
+  it.each([
+    [
+      "thread switch",
+      [
+        { id: "other-user", role: "user" },
+        { id: "other-assistant", role: "assistant" },
+      ],
+    ],
+    ["new chat", []],
+    ["last-turn deletion", [{ id: "older-assistant", role: "assistant" }]],
+    [
+      "branch swap",
+      [
+        { id: "branch-user", role: "user" },
+        { id: "branch-assistant", role: "assistant" },
+      ],
+    ],
+    [
+      "an externally synced completed turn",
+      [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "assistant-3", role: "assistant" },
+      ],
+    ],
+    [
+      "a resync separating the pair",
+      [
+        { id: "user-2", role: "user" },
+        { id: "inserted-assistant", role: "assistant" },
+        { id: "assistant-2", role: "assistant" },
+      ],
+    ],
+  ])("invalidates a stored turn after %s", (_transition, messages) => {
+    expect(
+      isTopAnchorTurnValid(
+        { anchorId: "user-2", targetId: "assistant-2" },
+        messages,
+      ),
+    ).toBe(false);
+  });
 });

package/src/primitives/thread/topAnchor/topAnchorTurn.ts

@@ -5,6 +5,35 @@ type TopAnchorTurnMessage = {
   readonly role: string;
 };
 
+export type TopAnchorTurn = {
+  readonly anchorId: string;
+  readonly targetId: string;
+};
+
+/**
+ * A stored turn stays valid only while it is still the trailing turn: the
+ * anchor immediately precedes the target, and anything after the target is a
+ * pending user message awaiting the next run. An assistant message after the
+ * target means the turn was superseded (e.g. an external store synced in a
+ * turn completed elsewhere), so the reserve must be torn down, not preserved.
+ */
+export const isTopAnchorTurnValid = (
+  turn: TopAnchorTurn | null,
+  messages: readonly TopAnchorTurnMessage[],
+) => {
+  if (!turn) return false;
+
+  const targetIndex = messages.findIndex(
+    (message) => message.id === turn.targetId,
+  );
+  if (targetIndex < 1) return false;
+
+  return (
+    messages[targetIndex - 1]?.id === turn.anchorId &&
+    messages.slice(targetIndex + 1).every((message) => message.role === "user")
+  );
+};
+
 export const getActiveTopAnchorTurn = ({
   isRunning,
   messages,