radiant-docs 0.1.41 → 0.1.42

package/template/src/components/chat/AssistantEmbedPanel.tsx

@@ -28,8 +28,10 @@ import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
 import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
+import { getDocsBasePath, withBasePath } from "../../lib/base-path";
 
 type AssistantLinkTarget = "current" | "blank";
+export type AssistantPanelSize = "default" | "expanded";
 
 type HastNode = {
   type?: string;
@@ -56,7 +58,11 @@ type AssistantEmbedPanelProps = {
   linkTarget?: AssistantLinkTarget;
   allowApiPathQueryOverride?: boolean;
   openSignal?: number;
+  panelSize?: AssistantPanelSize;
+  onRequestOpen?: () => void;
   onRequestClose?: () => void;
+  onRequestPanelSizeToggle?: (size: AssistantPanelSize) => void;
+  onCurrentLinkNavigate?: (href: string, sourceElement?: Element) => void;
 };
 
 type AssistantColorByMode = {
@@ -77,8 +83,42 @@ type AssistantStreamEvent = {
 
 type ChatInputKeyEvent = JSX.TargetedKeyboardEvent<HTMLTextAreaElement>;
 type ChatViewportWheelEvent = JSX.TargetedWheelEvent<HTMLDivElement>;
+type ChatViewportScrollEvent = JSX.TargetedEvent<HTMLDivElement, Event>;
+
+type PersistedPanelState = {
+  messages: ChatMessage[];
+  scrollTop: number;
+  inFlight: boolean;
+  isAwaitingFirstToken: boolean;
+  inFlightUpdatedAt: number;
+  panelSize: AssistantPanelSize;
+};
+
+type PersistPanelStateOptions = {
+  allowBusyListenerWrite?: boolean;
+  refreshInFlightTimestamp?: boolean;
+};
+
+type CurrentLinkNavigationRequest = {
+  href: string;
+  sourceElement: HTMLAnchorElement;
+};
+
+type PendingAssistantHandoff = {
+  state: PersistedPanelState;
+  targetWindow: Window;
+  timeoutId: number;
+};
 
-const STORAGE_KEY = "docs:assistant-embed-panel:v1";
+export const ASSISTANT_PANEL_STORAGE_KEY = "docs:assistant-embed-panel:v1";
+const HANDOFF_QUERY_PARAM = "assistantHandoff";
+const OPEN_QUERY_PARAM = "assistant";
+const OPEN_QUERY_VALUE = "open";
+const HANDOFF_READY_TYPE = "assistant-handoff:ready";
+const HANDOFF_STATE_TYPE = "assistant-handoff:state";
+const HANDOFF_ACK_TYPE = "assistant-handoff:ack";
+const IN_FLIGHT_STALE_MS = 10000;
+const IN_FLIGHT_HEARTBEAT_MS = 3000;
 const MARKDOWN_HTML_CACHE_LIMIT = 300;
 const markdownHtmlCache = new Map<string, string>();
 const PRISM_LANGUAGE_ALIAS: Record<string, string> = {
@@ -113,6 +153,8 @@ const PRISM_LANGUAGE_LABEL: Record<string, string> = {
   mdx: "MDX",
 };
 
+const EXTERNAL_PROTOCOL_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+
 function normalizeRelTokens(value: unknown): string[] {
   if (Array.isArray(value)) {
     return value
@@ -138,6 +180,154 @@ function visitHastNodes(
   }
 }
 
+function isDocumentLocalHref(href: string): boolean {
+  return (
+    href.startsWith("#") ||
+    href.startsWith("?") ||
+    href.startsWith("//") ||
+    href.startsWith("./") ||
+    href.startsWith("../")
+  );
+}
+
+function rebaseAssistantLinkHref(href: string): string {
+  const value = href.trim();
+  if (!value || isDocumentLocalHref(value)) {
+    return href;
+  }
+
+  if (!EXTERNAL_PROTOCOL_REGEX.test(value)) {
+    return withBasePath(value);
+  }
+
+  if (
+    typeof window === "undefined" ||
+    !/^https?:/i.test(value) ||
+    !getDocsBasePath()
+  ) {
+    return href;
+  }
+
+  try {
+    const parsed = new URL(value);
+    if (parsed.origin !== window.location.origin) {
+      return href;
+    }
+
+    const rebasedHref = withBasePath(
+      `${parsed.pathname}${parsed.search}${parsed.hash}`,
+    );
+    return new URL(rebasedHref, parsed.origin).toString();
+  } catch {
+    return href;
+  }
+}
+
+function getSameOriginNavigationRequest(
+  event: JSX.TargetedMouseEvent<HTMLDivElement>,
+): CurrentLinkNavigationRequest | null {
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  ) {
+    return null;
+  }
+
+  const targetElement = event.target instanceof Element ? event.target : null;
+  const anchor = targetElement?.closest("a[href]") as HTMLAnchorElement | null;
+  if (!anchor || !event.currentTarget.contains(anchor)) {
+    return null;
+  }
+
+  const target = anchor.getAttribute("target")?.trim().toLowerCase();
+  if ((target && target !== "_self") || anchor.hasAttribute("download")) {
+    return null;
+  }
+
+  const rawHref = anchor.getAttribute("href")?.trim();
+  if (!rawHref || rawHref.startsWith("#") || rawHref.startsWith("?")) {
+    return null;
+  }
+
+  try {
+    const url = new URL(anchor.href, window.location.href);
+    if (url.origin !== window.location.origin) {
+      return null;
+    }
+
+    if (
+      url.pathname === window.location.pathname &&
+      url.search === window.location.search &&
+      url.hash
+    ) {
+      return null;
+    }
+
+    return { href: url.href, sourceElement: anchor };
+  } catch {
+    return null;
+  }
+}
+
+function getSameOriginBlankNavigationRequest(
+  event: JSX.TargetedMouseEvent<HTMLDivElement>,
+): CurrentLinkNavigationRequest | null {
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  ) {
+    return null;
+  }
+
+  const targetElement = event.target instanceof Element ? event.target : null;
+  const anchor = targetElement?.closest("a[href]") as HTMLAnchorElement | null;
+  if (!anchor || !event.currentTarget.contains(anchor)) {
+    return null;
+  }
+
+  const target = anchor.getAttribute("target")?.trim().toLowerCase();
+  if ((target && target !== "_blank") || anchor.hasAttribute("download")) {
+    return null;
+  }
+
+  const rawHref = anchor.getAttribute("href")?.trim();
+  if (!rawHref || rawHref.startsWith("#") || rawHref.startsWith("?")) {
+    return null;
+  }
+
+  try {
+    const url = new URL(anchor.href, window.location.href);
+    if (url.origin !== window.location.origin) {
+      return null;
+    }
+
+    return { href: url.href, sourceElement: anchor };
+  } catch {
+    return null;
+  }
+}
+
+const rehypeRebaseInternalLinks: Plugin<[], HastNode> = () => {
+  return (tree) => {
+    visitHastNodes(tree, (node) => {
+      if (node.type !== "element" || node.tagName !== "a") return;
+
+      const props = node.properties;
+      if (!props || typeof props.href !== "string") return;
+
+      props.href = rebaseAssistantLinkHref(props.href);
+    });
+  };
+};
+
 const rehypeOpenLinksInNewTab: Plugin<[], HastNode> = () => {
   return (tree) => {
     visitHastNodes(tree, (node) => {
@@ -166,41 +356,212 @@ function createMessageId(): string {
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 
-function readPersistedMessages(): ChatMessage[] {
-  if (typeof window === "undefined") {
+function normalizePersistedMessages(rawMessages: unknown): ChatMessage[] {
+  if (!Array.isArray(rawMessages)) {
     return [];
   }
 
+  return rawMessages
+    .filter((message): message is ChatMessage => {
+      if (!message || typeof message !== "object") {
+        return false;
+      }
+      const candidate = message as Partial<ChatMessage>;
+      return (
+        (candidate.role === "user" || candidate.role === "assistant") &&
+        typeof candidate.id === "string" &&
+        typeof candidate.content === "string"
+      );
+    })
+    .map((message) => ({
+      id: message.id,
+      role: message.role,
+      content: message.content,
+    }));
+}
+
+function createEmptyPersistedPanelState(): PersistedPanelState {
+  return {
+    messages: [],
+    scrollTop: 0,
+    inFlight: false,
+    isAwaitingFirstToken: false,
+    inFlightUpdatedAt: 0,
+    panelSize: "default",
+  };
+}
+
+function normalizePanelSize(value: unknown): AssistantPanelSize {
+  return value === "expanded" ? "expanded" : "default";
+}
+
+function normalizePersistedPanelState(rawState: unknown): PersistedPanelState {
+  if (!rawState || typeof rawState !== "object") {
+    return createEmptyPersistedPanelState();
+  }
+
+  const state = rawState as {
+    messages?: unknown;
+    scrollTop?: unknown;
+    inFlight?: unknown;
+    isAwaitingFirstToken?: unknown;
+    inFlightUpdatedAt?: unknown;
+    panelSize?: unknown;
+  };
+  const inFlightUpdatedAt =
+    typeof state.inFlightUpdatedAt === "number" &&
+    Number.isFinite(state.inFlightUpdatedAt)
+      ? Math.max(0, state.inFlightUpdatedAt)
+      : 0;
+  const isInFlightFresh =
+    state.inFlight === true &&
+    inFlightUpdatedAt > 0 &&
+    Date.now() - inFlightUpdatedAt <= IN_FLIGHT_STALE_MS;
+  const scrollTop =
+    typeof state.scrollTop === "number" && Number.isFinite(state.scrollTop)
+      ? Math.max(0, state.scrollTop)
+      : 0;
+
+  return {
+    messages: normalizePersistedMessages(state.messages),
+    scrollTop,
+    inFlight: isInFlightFresh,
+    isAwaitingFirstToken:
+      isInFlightFresh && state.isAwaitingFirstToken === true,
+    inFlightUpdatedAt: isInFlightFresh ? inFlightUpdatedAt : 0,
+    panelSize: normalizePanelSize(state.panelSize),
+  };
+}
+
+function parsePersistedPanelState(raw: string | null): PersistedPanelState {
+  if (!raw) {
+    return createEmptyPersistedPanelState();
+  }
+
   try {
-    const raw = window.localStorage.getItem(STORAGE_KEY);
-    if (!raw) {
-      return [];
+    const parsed = JSON.parse(raw) as unknown;
+    if (Array.isArray(parsed)) {
+      return {
+        ...createEmptyPersistedPanelState(),
+        messages: normalizePersistedMessages(parsed),
+      };
     }
 
-    const parsed = JSON.parse(raw) as { messages?: unknown };
-    if (!Array.isArray(parsed.messages)) {
-      return [];
+    return normalizePersistedPanelState(parsed);
+  } catch {
+    return createEmptyPersistedPanelState();
+  }
+}
+
+function readPersistedPanelState(): PersistedPanelState {
+  if (typeof window === "undefined") {
+    return createEmptyPersistedPanelState();
+  }
+
+  try {
+    return parsePersistedPanelState(
+      window.localStorage.getItem(ASSISTANT_PANEL_STORAGE_KEY),
+    );
+  } catch {
+    return createEmptyPersistedPanelState();
+  }
+}
+
+function writePersistedPanelState(state: PersistedPanelState) {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    window.localStorage.setItem(
+      ASSISTANT_PANEL_STORAGE_KEY,
+      JSON.stringify({
+        messages: state.messages,
+        scrollTop:
+          Number.isFinite(state.scrollTop) && state.scrollTop > 0
+            ? state.scrollTop
+            : 0,
+        inFlight: state.inFlight,
+        isAwaitingFirstToken: state.inFlight && state.isAwaitingFirstToken,
+        inFlightUpdatedAt: state.inFlight ? state.inFlightUpdatedAt : 0,
+        panelSize: normalizePanelSize(state.panelSize),
+      }),
+    );
+  } catch {
+    // Ignore storage failures in private mode or constrained embeds.
+  }
+}
+
+function buildHandoffUrl(href: string, handoffId: string): string {
+  const url = new URL(href, window.location.href);
+  url.searchParams.set(HANDOFF_QUERY_PARAM, handoffId);
+  url.searchParams.set(OPEN_QUERY_PARAM, OPEN_QUERY_VALUE);
+  return url.toString();
+}
+
+function readAssistantUrlSignal(): {
+  handoffId: string;
+  shouldOpen: boolean;
+} {
+  if (typeof window === "undefined") {
+    return { handoffId: "", shouldOpen: false };
+  }
+
+  try {
+    const url = new URL(window.location.href);
+    const searchHandoffId = url.searchParams.get(HANDOFF_QUERY_PARAM) ?? "";
+    const searchShouldOpen =
+      url.searchParams.get(OPEN_QUERY_PARAM) === OPEN_QUERY_VALUE;
+    const hashParams = new URLSearchParams(
+      url.hash.startsWith("#") ? url.hash.slice(1) : url.hash,
+    );
+    const hashHandoffId = hashParams.get(HANDOFF_QUERY_PARAM) ?? "";
+    const hashShouldOpen =
+      hashParams.get(OPEN_QUERY_PARAM) === OPEN_QUERY_VALUE;
+
+    return {
+      handoffId: searchHandoffId || hashHandoffId,
+      shouldOpen:
+        Boolean(searchHandoffId || hashHandoffId) ||
+        searchShouldOpen ||
+        hashShouldOpen,
+    };
+  } catch {
+    return { handoffId: "", shouldOpen: false };
+  }
+}
+
+function clearAssistantUrlSignal() {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    const url = new URL(window.location.href);
+    url.searchParams.delete(HANDOFF_QUERY_PARAM);
+    url.searchParams.delete(OPEN_QUERY_PARAM);
+
+    const hashValue = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+    if (hashValue) {
+      const hashParams = new URLSearchParams(hashValue);
+      if (
+        hashParams.has(HANDOFF_QUERY_PARAM) ||
+        hashParams.has(OPEN_QUERY_PARAM)
+      ) {
+        hashParams.delete(HANDOFF_QUERY_PARAM);
+        hashParams.delete(OPEN_QUERY_PARAM);
+        const nextHash = hashParams.toString();
+        url.hash = nextHash ? `#${nextHash}` : "";
+      }
     }
 
-    return parsed.messages
-      .filter((message): message is ChatMessage => {
-        if (!message || typeof message !== "object") {
-          return false;
-        }
-        const candidate = message as Partial<ChatMessage>;
-        return (
-          (candidate.role === "user" || candidate.role === "assistant") &&
-          typeof candidate.id === "string" &&
-          typeof candidate.content === "string"
-        );
-      })
-      .map((message) => ({
-        id: message.id,
-        role: message.role,
-        content: message.content,
-      }));
+    window.history.replaceState(
+      window.history.state,
+      "",
+      `${url.pathname}${url.search}${url.hash}`,
+    );
   } catch {
-    return [];
+    // Leave the URL alone if parsing fails.
   }
 }
 
@@ -458,7 +819,8 @@ function renderMarkdownToHtml(
     const processor = unified()
       .use(remarkParse)
       .use(remarkGfm)
-      .use(remarkRehype, { allowDangerousHtml: false });
+      .use(remarkRehype, { allowDangerousHtml: false })
+      .use(rehypeRebaseInternalLinks);
 
     if (linkTarget === "blank") {
       processor.use(rehypeOpenLinksInNewTab);
@@ -504,12 +866,15 @@ function extractErrorMessage(rawBody: string): string {
   return rawBody.trim();
 }
 
-function postParentMessage(type: string) {
+function postParentMessage(
+  type: string,
+  payload: Record<string, unknown> = {},
+) {
   if (typeof window === "undefined") {
     return;
   }
 
-  window.parent.postMessage({ type }, "*");
+  window.parent.postMessage({ type, ...payload }, "*");
 }
 
 function getApiPath(
@@ -578,20 +943,50 @@ export default function AssistantEmbedPanel({
   linkTarget = "current",
   allowApiPathQueryOverride = true,
   openSignal = 0,
+  panelSize,
+  onRequestOpen,
   onRequestClose,
+  onRequestPanelSizeToggle,
+  onCurrentLinkNavigate,
 }: AssistantEmbedPanelProps) {
+  const [initialPanelState] = useState<PersistedPanelState>(() =>
+    canSendChatRequest
+      ? readPersistedPanelState()
+      : createEmptyPersistedPanelState(),
+  );
   const [messages, setMessages] = useState<ChatMessage[]>(
-    canSendChatRequest ? readPersistedMessages : [],
+    initialPanelState.messages,
   );
   const [input, setInput] = useState("");
-  const [isBusy, setIsBusy] = useState(false);
-  const [isAwaitingFirstToken, setIsAwaitingFirstToken] = useState(false);
+  const [isBusy, setIsBusy] = useState(initialPanelState.inFlight);
+  const [isAwaitingFirstToken, setIsAwaitingFirstToken] = useState(
+    initialPanelState.isAwaitingFirstToken,
+  );
   const [errorMessage, setErrorMessage] = useState("");
   const [showUnavailableState, setShowUnavailableState] =
     useState(!isChatAvailable);
   const [emptyStateAnimationKey, setEmptyStateAnimationKey] = useState(0);
+  const [localPanelSize, setLocalPanelSize] = useState<AssistantPanelSize>(
+    panelSize ?? initialPanelState.panelSize,
+  );
+  const [isShellFullscreen, setIsShellFullscreen] = useState(false);
   const activeRequestAbortRef = useRef<AbortController | null>(null);
   const scrollViewportRef = useRef<HTMLDivElement | null>(null);
+  const savedScrollTopRef = useRef(initialPanelState.scrollTop);
+  const scrollPersistenceFrameRef = useRef<number | null>(null);
+  const scrollPersistenceUnlockTimeoutRef = useRef<number | null>(null);
+  const isScrollPersistenceLockedRef = useRef(false);
+  const pendingHandoffsRef = useRef(new Map<string, PendingAssistantHandoff>());
+  const messagesRef = useRef(initialPanelState.messages);
+  const isBusyRef = useRef(initialPanelState.inFlight);
+  const isAwaitingFirstTokenRef = useRef(
+    initialPanelState.isAwaitingFirstToken,
+  );
+  const inFlightUpdatedAtRef = useRef(initialPanelState.inFlightUpdatedAt);
+  const panelSizeRef = useRef<AssistantPanelSize>(
+    panelSize ?? initialPanelState.panelSize,
+  );
+  const skipNextMessagesPersistRef = useRef(false);
   const inputRef = useRef<HTMLTextAreaElement | null>(null);
   const resolvedApiPathRef = useRef(
     getApiPath(apiPath, allowApiPathQueryOverride),
@@ -608,33 +1003,500 @@ export default function AssistantEmbedPanel({
     launcherIconColors?.light ?? launcherIconColor ?? "#ffffff";
   const launcherIconColorDark =
     launcherIconColors?.dark ?? launcherIconColor ?? "#ffffff";
+  const resolvedPanelSize = panelSize ?? localPanelSize;
+
+  const persistPanelState = (
+    nextMessages = messagesRef.current,
+    scrollTop = savedScrollTopRef.current,
+    options: PersistPanelStateOptions = {},
+  ) => {
+    const ownsActiveRequest = Boolean(activeRequestAbortRef.current);
+    if (
+      isBusyRef.current &&
+      !ownsActiveRequest &&
+      !options.allowBusyListenerWrite
+    ) {
+      return;
+    }
+
+    if (!isBusyRef.current) {
+      inFlightUpdatedAtRef.current = 0;
+    } else if (
+      ownsActiveRequest &&
+      options.refreshInFlightTimestamp !== false
+    ) {
+      inFlightUpdatedAtRef.current = Date.now();
+    }
+
+    writePersistedPanelState({
+      messages: nextMessages,
+      scrollTop,
+      inFlight: isBusyRef.current,
+      isAwaitingFirstToken:
+        isBusyRef.current && isAwaitingFirstTokenRef.current,
+      inFlightUpdatedAt: inFlightUpdatedAtRef.current,
+      panelSize: panelSizeRef.current,
+    });
+  };
+
+  const cancelQueuedScrollPersistence = () => {
+    if (
+      typeof window !== "undefined" &&
+      scrollPersistenceFrameRef.current !== null
+    ) {
+      window.cancelAnimationFrame(scrollPersistenceFrameRef.current);
+      scrollPersistenceFrameRef.current = null;
+    }
+  };
+
+  const clearScrollPersistenceUnlockTimeout = () => {
+    if (
+      typeof window !== "undefined" &&
+      scrollPersistenceUnlockTimeoutRef.current !== null
+    ) {
+      window.clearTimeout(scrollPersistenceUnlockTimeoutRef.current);
+      scrollPersistenceUnlockTimeoutRef.current = null;
+    }
+  };
+
+  const unlockScrollPersistence = () => {
+    clearScrollPersistenceUnlockTimeout();
+    isScrollPersistenceLockedRef.current = false;
+  };
+
+  const lockScrollPersistence = () => {
+    if (typeof window === "undefined") {
+      isScrollPersistenceLockedRef.current = true;
+      return;
+    }
+
+    clearScrollPersistenceUnlockTimeout();
+    isScrollPersistenceLockedRef.current = true;
+    scrollPersistenceUnlockTimeoutRef.current = window.setTimeout(() => {
+      scrollPersistenceUnlockTimeoutRef.current = null;
+      isScrollPersistenceLockedRef.current = false;
+    }, 1200);
+  };
+
+  const snapshotThreadScrollPosition = () => {
+    const viewport = scrollViewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    savedScrollTopRef.current = viewport.scrollTop;
+    cancelQueuedScrollPersistence();
+    persistPanelState();
+  };
+
+  const restoreSavedScrollPosition = (unlockAfterRestore = false) => {
+    const viewport = scrollViewportRef.current;
+    if (!viewport) {
+      if (unlockAfterRestore) {
+        unlockScrollPersistence();
+      }
+      return;
+    }
+
+    const maxScrollTop = Math.max(
+      0,
+      viewport.scrollHeight - viewport.clientHeight,
+    );
+    viewport.scrollTop = clamp(savedScrollTopRef.current, 0, maxScrollTop);
+
+    if (unlockAfterRestore && typeof window !== "undefined") {
+      window.requestAnimationFrame(() => {
+        unlockScrollPersistence();
+      });
+    } else if (unlockAfterRestore) {
+      unlockScrollPersistence();
+    }
+  };
+
+  const queueSavedScrollRestore = (unlockAfterRestore = false) => {
+    if (typeof window === "undefined") {
+      restoreSavedScrollPosition(unlockAfterRestore);
+      return;
+    }
+
+    window.requestAnimationFrame(() => {
+      window.requestAnimationFrame(() => {
+        restoreSavedScrollPosition(unlockAfterRestore);
+      });
+    });
+  };
+
+  const queueThreadScrollToBottom = (nextMessages: ChatMessage[]) => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    window.requestAnimationFrame(() => {
+      const viewport = scrollViewportRef.current;
+      if (!viewport) {
+        return;
+      }
+
+      viewport.scrollTop = viewport.scrollHeight;
+      savedScrollTopRef.current = viewport.scrollTop;
+      persistPanelState(nextMessages, savedScrollTopRef.current);
+    });
+  };
+
+  const resetThreadScrollPosition = (nextMessages: ChatMessage[]) => {
+    savedScrollTopRef.current = 0;
+    if (scrollViewportRef.current) {
+      scrollViewportRef.current.scrollTop = 0;
+    }
+    persistPanelState(nextMessages, 0);
+  };
+
+  const setSharedBusy = (nextIsBusy: boolean) => {
+    isBusyRef.current = nextIsBusy;
+    inFlightUpdatedAtRef.current = nextIsBusy ? Date.now() : 0;
+    setIsBusy(nextIsBusy);
+  };
+
+  const setSharedAwaitingFirstToken = (nextIsAwaiting: boolean) => {
+    isAwaitingFirstTokenRef.current = nextIsAwaiting;
+    setIsAwaitingFirstToken(nextIsAwaiting);
+  };
+
+  const notifyPanelSizeChange = (nextPanelSize: AssistantPanelSize) => {
+    if (onRequestPanelSizeToggle) {
+      onRequestPanelSizeToggle(nextPanelSize);
+      return;
+    }
+
+    postParentMessage("assistant-embed:set-panel-size", {
+      size: nextPanelSize,
+    });
+  };
+
+  const setSharedPanelSize = (
+    nextPanelSize: AssistantPanelSize,
+    shouldNotifyShell = true,
+  ) => {
+    panelSizeRef.current = nextPanelSize;
+    setLocalPanelSize(nextPanelSize);
+    persistPanelState(messagesRef.current, savedScrollTopRef.current, {
+      allowBusyListenerWrite: true,
+      refreshInFlightTimestamp: false,
+    });
+
+    if (shouldNotifyShell) {
+      notifyPanelSizeChange(nextPanelSize);
+    }
+  };
+
+  const applyPersistedPanelState = (nextState: PersistedPanelState) => {
+    messagesRef.current = nextState.messages;
+    savedScrollTopRef.current = nextState.scrollTop;
+    isBusyRef.current = nextState.inFlight;
+    isAwaitingFirstTokenRef.current = nextState.isAwaitingFirstToken;
+    inFlightUpdatedAtRef.current = nextState.inFlightUpdatedAt;
+    panelSizeRef.current = nextState.panelSize;
+    skipNextMessagesPersistRef.current = true;
+    setMessages(nextState.messages);
+    setIsBusy(nextState.inFlight);
+    setIsAwaitingFirstToken(nextState.isAwaitingFirstToken);
+    setLocalPanelSize(nextState.panelSize);
+    queueSavedScrollRestore();
+  };
+
+  const requestPanelOpen = () => {
+    if (onRequestOpen) {
+      onRequestOpen();
+      return;
+    }
+
+    postParentMessage("assistant-embed:open");
+  };
+
+  const clearPendingHandoff = (handoffId: string) => {
+    const pending = pendingHandoffsRef.current.get(handoffId);
+    if (!pending) {
+      return;
+    }
+
+    window.clearTimeout(pending.timeoutId);
+    pendingHandoffsRef.current.delete(handoffId);
+  };
+
+  const openBlankLinkWithHandoff = (
+    navigationRequest: CurrentLinkNavigationRequest,
+  ) => {
+    if (typeof window === "undefined") {
+      return false;
+    }
+
+    snapshotThreadScrollPosition();
+
+    const handoffId = createMessageId();
+    const targetWindow = window.open(
+      buildHandoffUrl(navigationRequest.href, handoffId),
+      "_blank",
+    );
+    if (!targetWindow) {
+      return false;
+    }
+
+    const timeoutId = window.setTimeout(() => {
+      pendingHandoffsRef.current.delete(handoffId);
+    }, 30000);
+
+    pendingHandoffsRef.current.set(handoffId, {
+      state: {
+        messages: messagesRef.current,
+        scrollTop: savedScrollTopRef.current,
+        inFlight: isBusyRef.current,
+        isAwaitingFirstToken:
+          isBusyRef.current && isAwaitingFirstTokenRef.current,
+        inFlightUpdatedAt:
+          isBusyRef.current && activeRequestAbortRef.current
+            ? Date.now()
+            : inFlightUpdatedAtRef.current,
+        panelSize: panelSizeRef.current,
+      },
+      targetWindow,
+      timeoutId,
+    });
+
+    return true;
+  };
 
   useEffect(() => {
     return () => {
       activeRequestAbortRef.current?.abort();
       activeRequestAbortRef.current = null;
+      if (
+        typeof window !== "undefined" &&
+        scrollPersistenceFrameRef.current !== null
+      ) {
+        window.cancelAnimationFrame(scrollPersistenceFrameRef.current);
+      }
+      clearScrollPersistenceUnlockTimeout();
+      for (const handoffId of pendingHandoffsRef.current.keys()) {
+        clearPendingHandoff(handoffId);
+      }
     };
   }, []);
 
+  useEffect(() => {
+    messagesRef.current = messages;
+    if (skipNextMessagesPersistRef.current) {
+      skipNextMessagesPersistRef.current = false;
+      return;
+    }
+    persistPanelState(messages);
+  }, [messages]);
+
   useEffect(() => {
     if (typeof window === "undefined") {
       return;
     }
 
-    try {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify({ messages }));
-    } catch {
-      // Ignore storage failures in private mode or constrained embeds.
+    if (!isBusy || !activeRequestAbortRef.current) {
+      return;
     }
-  }, [messages]);
+
+    const inFlightHeartbeat = window.setInterval(() => {
+      if (!activeRequestAbortRef.current) {
+        return;
+      }
+
+      persistPanelState();
+    }, IN_FLIGHT_HEARTBEAT_MS);
+
+    return () => {
+      window.clearInterval(inFlightHeartbeat);
+    };
+  }, [isBusy]);
 
   useEffect(() => {
-    const viewport = scrollViewportRef.current;
-    if (!viewport) {
+    if (typeof window === "undefined") {
       return;
     }
-    viewport.scrollTop = viewport.scrollHeight;
-  }, [messages, isAwaitingFirstToken]);
+
+    const handleStorage = (event: StorageEvent) => {
+      if (
+        event.key !== ASSISTANT_PANEL_STORAGE_KEY ||
+        event.newValue === null
+      ) {
+        return;
+      }
+
+      if (activeRequestAbortRef.current) {
+        return;
+      }
+
+      applyPersistedPanelState(parsePersistedPanelState(event.newValue));
+    };
+
+    window.addEventListener("storage", handleStorage);
+    return () => {
+      window.removeEventListener("storage", handleStorage);
+    };
+  }, []);
+
+  useEffect(() => {
+    queueSavedScrollRestore();
+
+    if (typeof document === "undefined") {
+      return;
+    }
+
+    const persistCurrentScrollPosition = () => {
+      if (isScrollPersistenceLockedRef.current) {
+        return;
+      }
+
+      const viewport = scrollViewportRef.current;
+      if (!viewport) {
+        return;
+      }
+
+      savedScrollTopRef.current = viewport.scrollTop;
+      persistPanelState();
+    };
+
+    const handleAfterSwap = () => {
+      queueSavedScrollRestore(isScrollPersistenceLockedRef.current);
+    };
+
+    document.addEventListener(
+      "astro:before-preparation",
+      persistCurrentScrollPosition,
+    );
+    document.addEventListener("astro:after-swap", handleAfterSwap);
+    return () => {
+      document.removeEventListener(
+        "astro:before-preparation",
+        persistCurrentScrollPosition,
+      );
+      document.removeEventListener("astro:after-swap", handleAfterSwap);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const handleHandoffMessage = (event: MessageEvent) => {
+      if (
+        event.origin !== window.location.origin ||
+        !event.data ||
+        typeof event.data !== "object"
+      ) {
+        return;
+      }
+
+      const data = event.data as {
+        type?: unknown;
+        handoffId?: unknown;
+      };
+      if (typeof data.handoffId !== "string") {
+        return;
+      }
+
+      const pending = pendingHandoffsRef.current.get(data.handoffId);
+      if (!pending || event.source !== pending.targetWindow) {
+        return;
+      }
+
+      if (data.type === HANDOFF_READY_TYPE) {
+        pending.targetWindow.postMessage(
+          {
+            type: HANDOFF_STATE_TYPE,
+            handoffId: data.handoffId,
+            state: pending.state,
+          },
+          window.location.origin,
+        );
+        return;
+      }
+
+      if (data.type === HANDOFF_ACK_TYPE) {
+        clearPendingHandoff(data.handoffId);
+      }
+    };
+
+    window.addEventListener("message", handleHandoffMessage);
+    return () => {
+      window.removeEventListener("message", handleHandoffMessage);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const { handoffId, shouldOpen } = readAssistantUrlSignal();
+    if (!handoffId && !shouldOpen) {
+      return;
+    }
+
+    requestPanelOpen();
+    clearAssistantUrlSignal();
+
+    if (!handoffId || !window.opener) {
+      return;
+    }
+
+    const handleIncomingHandoff = (event: MessageEvent) => {
+      if (
+        event.origin !== window.location.origin ||
+        event.source !== window.opener ||
+        !event.data ||
+        typeof event.data !== "object"
+      ) {
+        return;
+      }
+
+      const data = event.data as {
+        type?: unknown;
+        handoffId?: unknown;
+        state?: unknown;
+      };
+      if (data.type !== HANDOFF_STATE_TYPE || data.handoffId !== handoffId) {
+        return;
+      }
+
+      const handoffState = normalizePersistedPanelState(data.state);
+      const nextState = {
+        ...handoffState,
+        inFlight: isBusyRef.current,
+        isAwaitingFirstToken:
+          isBusyRef.current && isAwaitingFirstTokenRef.current,
+        inFlightUpdatedAt: isBusyRef.current ? inFlightUpdatedAtRef.current : 0,
+      };
+      applyPersistedPanelState(nextState);
+      writePersistedPanelState(nextState);
+
+      window.opener?.postMessage(
+        { type: HANDOFF_ACK_TYPE, handoffId },
+        window.location.origin,
+      );
+      window.removeEventListener("message", handleIncomingHandoff);
+    };
+
+    window.addEventListener("message", handleIncomingHandoff);
+    window.opener.postMessage(
+      { type: HANDOFF_READY_TYPE, handoffId },
+      window.location.origin,
+    );
+
+    const handoffTimeout = window.setTimeout(() => {
+      window.removeEventListener("message", handleIncomingHandoff);
+    }, 5000);
+
+    return () => {
+      window.clearTimeout(handoffTimeout);
+      window.removeEventListener("message", handleIncomingHandoff);
+    };
+  }, []);
 
   const resizeChatInputTextarea = () => {
     const textarea = inputRef.current;
@@ -669,21 +1531,50 @@ export default function AssistantEmbedPanel({
     resizeChatInputTextarea();
   }, [input]);
 
+  useEffect(() => {
+    if (panelSize) {
+      setSharedPanelSize(panelSize, false);
+    }
+  }, [panelSize]);
+
+  useEffect(() => {
+    notifyPanelSizeChange(resolvedPanelSize);
+  }, [resolvedPanelSize]);
+
   useEffect(() => {
     if (typeof window === "undefined") {
       return;
     }
 
     const handlePanelMessage = (event: MessageEvent) => {
-      if (
-        !event.data ||
-        typeof event.data !== "object" ||
-        event.data.type !== "assistant-embed:panel-opened"
-      ) {
+      if (!event.data || typeof event.data !== "object") {
         return;
       }
 
-      setEmptyStateAnimationKey((previous) => previous + 1);
+      const data = event.data as {
+        type?: unknown;
+        size?: unknown;
+        isFullscreen?: unknown;
+      };
+
+      if (data.type === "assistant-embed:panel-opened") {
+        setEmptyStateAnimationKey((previous) => previous + 1);
+        queueSavedScrollRestore();
+        postParentMessage("assistant-embed:get-panel-layout");
+        return;
+      }
+
+      if (data.type === "assistant-embed:set-panel-layout") {
+        setIsShellFullscreen(data.isFullscreen === true);
+        return;
+      }
+
+      if (
+        data.type === "assistant-embed:set-panel-size" &&
+        (data.size === "default" || data.size === "expanded")
+      ) {
+        setSharedPanelSize(data.size, true);
+      }
     };
 
     window.addEventListener("message", handlePanelMessage);
@@ -694,15 +1585,17 @@ export default function AssistantEmbedPanel({
 
   useEffect(() => {
     setEmptyStateAnimationKey((previous) => previous + 1);
+    queueSavedScrollRestore();
   }, [openSignal]);
 
   const handleStartNewChat = () => {
     activeRequestAbortRef.current?.abort();
     activeRequestAbortRef.current = null;
+    setSharedBusy(false);
+    setSharedAwaitingFirstToken(false);
+    resetThreadScrollPosition([]);
     setMessages([]);
     setInput("");
-    setIsBusy(false);
-    setIsAwaitingFirstToken(false);
     setErrorMessage("");
     setShowUnavailableState(false);
   };
@@ -716,13 +1609,20 @@ export default function AssistantEmbedPanel({
     postParentMessage("assistant-embed:close");
   };
 
+  const handlePanelSizeToggle = () => {
+    const nextPanelSize =
+      resolvedPanelSize === "expanded" ? "default" : "expanded";
+    setSharedPanelSize(nextPanelSize);
+  };
+
   const handleUnavailableBack = () => {
     activeRequestAbortRef.current?.abort();
     activeRequestAbortRef.current = null;
+    setSharedBusy(false);
+    setSharedAwaitingFirstToken(false);
+    resetThreadScrollPosition([]);
     setMessages([]);
     setInput("");
-    setIsBusy(false);
-    setIsAwaitingFirstToken(false);
     setErrorMessage("");
     setShowUnavailableState(false);
   };
@@ -739,8 +1639,8 @@ export default function AssistantEmbedPanel({
     }
 
     setErrorMessage("");
-    setIsBusy(true);
-    setIsAwaitingFirstToken(true);
+    setSharedBusy(true);
+    setSharedAwaitingFirstToken(true);
 
     const userMessage: ChatMessage = {
       id: createMessageId(),
@@ -752,6 +1652,7 @@ export default function AssistantEmbedPanel({
 
     setInput("");
     setMessages(nextConversation);
+    queueThreadScrollToBottom(nextConversation);
 
     activeRequestAbortRef.current?.abort();
     const abortController = new AbortController();
@@ -842,7 +1743,7 @@ export default function AssistantEmbedPanel({
           ) {
             if (!hasReceivedFirstTextDelta) {
               hasReceivedFirstTextDelta = true;
-              setIsAwaitingFirstToken(false);
+              setSharedAwaitingFirstToken(false);
             }
 
             setMessages((previous) => {
@@ -885,8 +1786,9 @@ export default function AssistantEmbedPanel({
       if (activeRequestAbortRef.current === abortController) {
         activeRequestAbortRef.current = null;
       }
-      setIsBusy(false);
-      setIsAwaitingFirstToken(false);
+      setSharedBusy(false);
+      setSharedAwaitingFirstToken(false);
+      persistPanelState();
     }
   };
 
@@ -915,39 +1817,73 @@ export default function AssistantEmbedPanel({
       ".ask-ai-copy-code-button",
     ) as HTMLButtonElement | null;
 
-    if (!copyButton) {
-      return;
-    }
+    if (copyButton) {
+      event.preventDefault();
+      event.stopPropagation();
 
-    event.preventDefault();
-    event.stopPropagation();
+      if (copyButton.dataset.copying === "true") {
+        return;
+      }
+
+      const preElement = copyButton.closest("pre");
+      const codeElement = preElement?.querySelector("code");
+      if (!codeElement) {
+        return;
+      }
 
-    if (copyButton.dataset.copying === "true") {
+      const codeText = codeElement.textContent ?? "";
+      copyButton.dataset.copying = "true";
+
+      void (async () => {
+        const didCopy = await copyToClipboard(codeText);
+        if (didCopy) {
+          copyButton.dataset.copied = "true";
+        } else {
+          delete copyButton.dataset.copied;
+        }
+
+        window.setTimeout(() => {
+          delete copyButton.dataset.copied;
+          delete copyButton.dataset.copying;
+        }, 1200);
+      })();
       return;
     }
 
-    const preElement = copyButton.closest("pre");
-    const codeElement = preElement?.querySelector("code");
-    if (!codeElement) {
+    const blankNavigationRequest =
+      linkTarget === "blank"
+        ? getSameOriginBlankNavigationRequest(event)
+        : null;
+    if (blankNavigationRequest) {
+      event.preventDefault();
+      event.stopPropagation();
+      const didOpen = openBlankLinkWithHandoff(blankNavigationRequest);
+      if (!didOpen && typeof window !== "undefined") {
+        window.open(
+          blankNavigationRequest.href,
+          "_blank",
+          "noopener,noreferrer",
+        );
+      }
       return;
     }
 
-    const codeText = codeElement.textContent ?? "";
-    copyButton.dataset.copying = "true";
-
-    void (async () => {
-      const didCopy = await copyToClipboard(codeText);
-      if (didCopy) {
-        copyButton.dataset.copied = "true";
-      } else {
-        delete copyButton.dataset.copied;
-      }
+    const navigationRequest =
+      linkTarget === "current" && onCurrentLinkNavigate
+        ? getSameOriginNavigationRequest(event)
+        : null;
+    if (!navigationRequest) {
+      return;
+    }
 
-      window.setTimeout(() => {
-        delete copyButton.dataset.copied;
-        delete copyButton.dataset.copying;
-      }, 1200);
-    })();
+    event.preventDefault();
+    event.stopPropagation();
+    snapshotThreadScrollPosition();
+    lockScrollPersistence();
+    onCurrentLinkNavigate(
+      navigationRequest.href,
+      navigationRequest.sourceElement,
+    );
   };
 
   const handleThreadViewportWheel = (event: ChatViewportWheelEvent) => {
@@ -993,6 +1929,26 @@ export default function AssistantEmbedPanel({
     }
   };
 
+  const handleThreadViewportScroll = (event: ChatViewportScrollEvent) => {
+    if (isScrollPersistenceLockedRef.current) {
+      return;
+    }
+
+    savedScrollTopRef.current = event.currentTarget.scrollTop;
+
+    if (
+      typeof window === "undefined" ||
+      scrollPersistenceFrameRef.current !== null
+    ) {
+      return;
+    }
+
+    scrollPersistenceFrameRef.current = window.requestAnimationFrame(() => {
+      scrollPersistenceFrameRef.current = null;
+      persistPanelState();
+    });
+  };
+
   const panelClassName = [
     "relative flex min-h-0 flex-col overflow-hidden text-neutral-900 shadow-2xl dark:text-neutral-50",
     panelSurface === "inline"
@@ -1002,8 +1958,8 @@ export default function AssistantEmbedPanel({
 
   return (
     <div className={panelClassName}>
-      <header className="flex items-center justify-between gap-3 px-2 pt-2 pb-1">
-        <div className="flex min-w-0 items-center gap-2 ">
+      <header className="flex items-center justify-between gap-2 px-2 pt-2 pb-1">
+        <div className="flex min-w-0 flex-1 items-center gap-2">
           <AssistantPanelIcon
             color={launcherIconColor}
             imageSrc={launcherIconImageSrc}
@@ -1017,32 +1973,61 @@ export default function AssistantEmbedPanel({
               Assistant
             </p>
           </div>
+          {messages.length > 0 ? (
+            <button
+              type="button"
+              className="shrink-0 inline-flex items-center gap-1.5 rounded-md border border-neutral-900/8 px-2 py-1 ml-1.5 text-[12px] text-neutral-500 transition hover:bg-neutral-900/4 disabled:cursor-not-allowed disabled:opacity-50 dark:border-white/10 dark:bg-white/5 dark:text-neutral-300 dark:hover:bg-white/10 cursor-pointer"
+              onClick={handleStartNewChat}
+              aria-label="Clear chat"
+              title="Clear chat"
+            >
+              <Icon
+                icon="lucide:trash-2"
+                className="size-3.5 -ml-px"
+                aria-hidden="true"
+              />
+              Clear
+            </button>
+          ) : null}
         </div>
-        {messages.length > 0 ? (
+        <div className="flex shrink-0 items-center">
+          {!isShellFullscreen ? (
+            <button
+              type="button"
+              className="inline-flex items-center justify-center rounded-md size-9 rotate-90 text-[13px] text-neutral-500 hover:bg-neutral-900/5 dark:text-neutral-300 dark:hover:bg-white/10 transition cursor-pointer"
+              onClick={handlePanelSizeToggle}
+              aria-label={
+                resolvedPanelSize === "expanded"
+                  ? "Use default panel size"
+                  : "Expand panel"
+              }
+              title={
+                resolvedPanelSize === "expanded"
+                  ? "Default size"
+                  : "Expand panel"
+              }
+            >
+              <Icon
+                icon={
+                  resolvedPanelSize === "expanded"
+                    ? "lucide:minimize-2"
+                    : "lucide:maximize-2"
+                }
+                className="size-4"
+                aria-hidden="true"
+              />
+            </button>
+          ) : null}
           <button
             type="button"
-            className="ml-auto inline-flex items-center gap-1.5 rounded-md border border-neutral-900/8 px-2 py-1 text-[12px] text-neutral-500 transition hover:bg-neutral-900/4 disabled:cursor-not-allowed disabled:opacity-50 dark:border-white/10 dark:bg-white/5 dark:text-neutral-300 dark:hover:bg-white/10 cursor-pointer"
-            onClick={handleStartNewChat}
-            aria-label="Clear chat"
-            title="Clear chat"
+            className="inline-flex items-center justify-center rounded-md size-9 text-[13px] text-neutral-500 hover:bg-neutral-900/5 dark:text-neutral-300 dark:hover:bg-white/10 transition cursor-pointer"
+            onClick={handleRequestClose}
+            aria-label="Close chat"
+            title="Close"
           >
-            <Icon
-              icon="lucide:trash-2"
-              className="size-3.5 -ml-px"
-              aria-hidden="true"
-            />
-            Clear
+            <Icon icon="lucide:x" className="size-5" aria-hidden="true" />
           </button>
-        ) : null}
-        <button
-          type="button"
-          className="inline-flex items-center justify-center gap-1 rounded-md size-9 text-[13px] text-neutral-500 hover:bg-neutral-900/5 dark:text-neutral-300 dark:hover:bg-white/10 transition cursor-pointer"
-          onClick={handleRequestClose}
-          aria-label="Close chat"
-          title="Close"
-        >
-          <Icon icon="lucide:x" className="size-5" aria-hidden="true" />
-        </button>
+        </div>
       </header>
 
       {!showUnavailableState ? (
@@ -1050,6 +2035,7 @@ export default function AssistantEmbedPanel({
           <div
             ref={scrollViewportRef}
             className={`mask-t-from-[calc(100%-1rem)] flex-1 overflow-y-auto overscroll-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden px-4 py-4 ${messages.length > 0 ? "pb-60" : ""} mb-10 space-y-6`}
+            onScroll={handleThreadViewportScroll}
             onWheel={handleThreadViewportWheel}
           >
             {messages.length === 0 ? (