diff --git a/examples/next/app/blogs/[blog]/page.val.ts b/examples/next/app/blogs/[blog]/page.val.ts
index f9544a619..69cd041b1 100644
--- a/examples/next/app/blogs/[blog]/page.val.ts
+++ b/examples/next/app/blogs/[blog]/page.val.ts
@@ -3,8 +3,11 @@ import authorsVal from "../../../content/authors.val";
 import { linkSchema } from "../../../components/link.val";
 
 const blogSchema = s.object({
-  title: s.string().maxLength(3),
+  title: s.string(),
   content: s.richtext({
+    style: {
+      bold: true,
+    },
     inline: {
       a: s.route(),
     },
diff --git a/examples/next/val.config.ts b/examples/next/val.config.ts
index cfde56f86..068807b4a 100644
--- a/examples/next/val.config.ts
+++ b/examples/next/val.config.ts
@@ -7,7 +7,7 @@ const { s, c, val, config, nextAppRouter, externalPageRouter } = initVal({
   ai: {
     chat: {
       experimental: {
-        enable: false,
+        enable: true,
       },
       suggestions: [
         "Summarize",
diff --git a/packages/shared/src/internal/sessionStorage.ts b/packages/shared/src/internal/sessionStorage.ts
index f7aa2f798..7861f9d79 100644
--- a/packages/shared/src/internal/sessionStorage.ts
+++ b/packages/shared/src/internal/sessionStorage.ts
@@ -1,2 +1,3 @@
 export const VAL_CONFIG_SESSION_STORAGE_KEY = "val-config";
 export const VAL_THEME_SESSION_STORAGE_KEY = "val-theme";
+export const VAL_AI_SESSION_STORAGE_KEY = "val-ai-session";
diff --git a/packages/ui/spa/components/AIChat.stories.tsx b/packages/ui/spa/components/AIChat.stories.tsx
index b12c2be7a..bd92c8d5f 100644
--- a/packages/ui/spa/components/AIChat.stories.tsx
+++ b/packages/ui/spa/components/AIChat.stories.tsx
@@ -27,8 +27,8 @@ type Story = StoryObj<typeof AIChat>;
 
 export const Empty: Story = {
   args: {
-    onSendMessage: (text: string) => {
-      console.log("Send:", text);
+    onSendMessage: (content) => {
+      console.log("Send:", content);
       return true;
     },
   },
@@ -42,8 +42,8 @@ export const CustomSuggestions: Story = {
       "Fix validation errors",
       "Generate a summary",
     ],
-    onSendMessage: (text: string) => {
-      console.log("Send:", text);
+    onSendMessage: (content) => {
+      console.log("Send:", content);
       return true;
     },
   },
@@ -92,8 +92,8 @@ const conversationMessages: ChatMessage[] = [
 export const WithConversation: Story = {
   args: {
     initialMessages: conversationMessages,
-    onSendMessage: (text: string) => {
-      console.log("Send:", text);
+    onSendMessage: (content) => {
+      console.log("Send:", content);
       return true;
     },
   },
@@ -191,8 +191,8 @@ export const Error: Story = {
         error: "Connection lost — the server closed the WebSocket unexpectedly",
       },
     ],
-    onSendMessage: (text: string) => {
-      console.log("Retry send:", text);
+    onSendMessage: (content) => {
+      console.log("Retry send:", content);
       return true;
     },
   },
@@ -216,8 +216,8 @@ export const ErrorAfterPartialResponse: Story = {
         error: "Stream interrupted — request timed out after 30s",
       },
     ],
-    onSendMessage: (text: string) => {
-      console.log("Retry send:", text);
+    onSendMessage: (content) => {
+      console.log("Retry send:", content);
       return true;
     },
   },
@@ -287,8 +287,8 @@ export const LongMarkdown: Story = {
         status: "complete",
       },
     ],
-    onSendMessage: (text: string) => {
-      console.log("Send:", text);
+    onSendMessage: (content) => {
+      console.log("Send:", content);
       return true;
     },
   },
diff --git a/packages/ui/spa/components/AIChat.tsx b/packages/ui/spa/components/AIChat.tsx
index b5d302c2c..3549e0941 100644
--- a/packages/ui/spa/components/AIChat.tsx
+++ b/packages/ui/spa/components/AIChat.tsx
@@ -5,6 +5,7 @@ import React, {
   useCallback,
   useImperativeHandle,
   forwardRef,
+  type RefObject,
 } from "react";
 import ReactMarkdown from "react-markdown";
 import { ScrollArea } from "./designSystem/scroll-area";
@@ -14,7 +15,6 @@ import {
   Send,
   RotateCcw,
   Sparkles,
-  Check,
   Loader2,
   LogIn,
   Search,
@@ -38,9 +38,21 @@ import type { AISession } from "../hooks/useAIWebSocket";
 import type { AIContentBlock, AIMessageContent } from "./ValProvider";
 import { ToolName } from "../utils/toolNames";
 import { useValConfig } from "./ValFieldProvider";
+import { useValPortal } from "./ValPortalProvider";
 import { DEFAULT_APP_HOST } from "@valbuild/core";
 import { urlOf } from "@valbuild/shared/internal";
 import { CopyableCodeBlock } from "./designSystem/CopyableCodeBlock";
+import { AIChatEditor } from "./AIChatEditor";
+import type {
+  ChatBlockNode,
+  ChatDocument,
+  ChatEditorRef,
+  ChatInlineNode,
+} from "./AIChatEditor";
+import {
+  chatDocumentToPlainText,
+  collectImageKeysFromDoc,
+} from "./AIChatEditor";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -72,6 +84,12 @@ export type ChatMessage = {
   errorCode?: string;
   toolActivities?: ToolActivity[];
   attachments?: ChatMessageAttachment[];
+  /**
+   * For user messages composed in the rich editor, the original document so
+   * the bubble can render inline images / field refs without re-parsing HTML
+   * (which would lose `previewUrl`s for image nodes).
+   */
+  userDoc?: ChatDocument;
 };
 
 type AttachedFile = {
@@ -115,11 +133,13 @@ export type AIChatHandle = {
 export type AIChatProps = {
   /** Called when the user submits a message (via input or suggestion chip). Returns true if sent successfully. */
   onSendMessage?: (
-    text: string,
+    content: string | ChatDocument,
     attachments?: ChatMessageAttachment[],
   ) => boolean;
   /** Called to upload a file to the current AI session. Returns the server key. */
   onUploadFile?: (file: File) => Promise<{ key: string }>;
+  /** Shared ref to the inner rich text editor (used by Field.tsx to insert field references). */
+  chatEditorRef?: RefObject<ChatEditorRef | null>;
   /** Called when the user clicks "New Chat" to start a fresh session */
   onNewSession?: () => void;
   /** Prompt suggestion chips shown on the empty state */
@@ -134,14 +154,16 @@ export type AIChatProps = {
   mode: "http" | "fs" | "unknown";
   /** List of past sessions (fetched on demand) */
   sessions?: AISession[];
-  /** The currently active session ID */
-  currentSessionId?: string;
+  /** The currently active session ID; null when the session is unborn (no message sent yet). */
+  currentSessionId?: string | null;
   /** Called to load a previous session */
   onLoadSession?: (sessionId: string) => void;
   /** Called to trigger a sessions fetch */
   onFetchSessions?: () => void;
   /** Called to rename a session */
   onSetSessionName?: (sessionId: string, name: string) => void;
+  /** True while a previous session's messages are being fetched from the server. */
+  isLoadingSession?: boolean;
   /**
    * @internal – seed messages for Storybook / testing only.
    * Not part of the public API.
@@ -181,6 +203,244 @@ function getTextContent(content: AIMessageContent): string {
     .join("\n\n");
 }
 
+// HTML-esque tag set that the rich chat editor produces (see
+// chatDocumentToHtmlText). Restored sessions arrive as strings containing
+// these tags, so we re-render them as formatted React instead of literal text.
+const USER_HTML_TAG_RE =
+  /<\/?(?:p|h[1-3]|blockquote|ul|ol|li|strong|em|del|code|br|img|field)\b/i;
+
+function renderHtmlChildren(nodes: ArrayLike<ChildNode>): React.ReactNode[] {
+  return Array.from(nodes).map((n, i) => renderHtmlNode(n, i));
+}
+
+function renderHtmlNode(node: ChildNode, key: number): React.ReactNode {
+  if (node.nodeType === 3 /* TEXT_NODE */) return node.nodeValue ?? "";
+  if (node.nodeType !== 1 /* ELEMENT_NODE */) return null;
+  const el = node as Element;
+  const children = renderHtmlChildren(el.childNodes);
+  switch (el.tagName.toLowerCase()) {
+    case "p":
+      return (
+        <p key={key} className="whitespace-pre-wrap">
+          {children}
+        </p>
+      );
+    case "h1":
+      return (
+        <h1 key={key} className="text-base font-semibold">
+          {children}
+        </h1>
+      );
+    case "h2":
+      return (
+        <h2 key={key} className="text-base font-semibold">
+          {children}
+        </h2>
+      );
+    case "h3":
+      return (
+        <h3 key={key} className="text-sm font-semibold">
+          {children}
+        </h3>
+      );
+    case "blockquote":
+      return (
+        <blockquote
+          key={key}
+          className="border-l-2 border-border-primary pl-2 italic"
+        >
+          {children}
+        </blockquote>
+      );
+    case "ul":
+      return (
+        <ul key={key} className="list-disc pl-5">
+          {children}
+        </ul>
+      );
+    case "ol":
+      return (
+        <ol key={key} className="list-decimal pl-5">
+          {children}
+        </ol>
+      );
+    case "li":
+      return <li key={key}>{children}</li>;
+    case "strong":
+    case "b":
+      return <strong key={key}>{children}</strong>;
+    case "em":
+    case "i":
+      return <em key={key}>{children}</em>;
+    case "del":
+    case "s":
+      return <del key={key}>{children}</del>;
+    case "code":
+      return (
+        <code
+          key={key}
+          className="rounded bg-bg-tertiary px-1 py-0.5 font-mono text-[0.85em]"
+        >
+          {children}
+        </code>
+      );
+    case "br":
+      return <br key={key} />;
+    case "img": {
+      const alt = el.getAttribute("alt");
+      return (
+        <span key={key} className="italic text-fg-secondary">
+          [{alt ? `image: ${alt}` : "image"}]
+        </span>
+      );
+    }
+    case "field": {
+      const path = el.getAttribute("path") ?? "";
+      return (
+        <span
+          key={key}
+          className="rounded bg-bg-tertiary px-1 py-0.5 text-fg-brand-primary"
+        >
+          @{path}
+        </span>
+      );
+    }
+    default:
+      return <>{children}</>;
+  }
+}
+
+function renderUserMessageText(text: string): React.ReactNode {
+  if (!USER_HTML_TAG_RE.test(text)) {
+    return <p className="whitespace-pre-wrap">{text}</p>;
+  }
+  const doc = new DOMParser().parseFromString(
+    `<body>${text}</body>`,
+    "text/html",
+  );
+  return <>{renderHtmlChildren(doc.body.childNodes)}</>;
+}
+
+// Render a ChatDocument from the rich editor directly to React. Used for
+// freshly-sent user messages so inline images keep their preview blob URLs
+// (re-parsing HTML would strip the previewUrl off image nodes).
+function ChatDocumentRenderer({
+  doc,
+}: {
+  doc: ChatDocument;
+}): React.ReactElement {
+  return <>{doc.map((block, i) => renderChatBlock(block, i))}</>;
+}
+
+function renderChatBlock(block: ChatBlockNode, key: number): React.ReactNode {
+  switch (block.tag) {
+    case "p":
+      return (
+        <p key={key} className="whitespace-pre-wrap">
+          {block.children.map((c, i) => renderChatInline(c, i))}
+        </p>
+      );
+    case "h1":
+      return (
+        <h1 key={key} className="text-base font-semibold">
+          {block.children.map((c, i) => renderChatInline(c, i))}
+        </h1>
+      );
+    case "h2":
+      return (
+        <h2 key={key} className="text-base font-semibold">
+          {block.children.map((c, i) => renderChatInline(c, i))}
+        </h2>
+      );
+    case "h3":
+      return (
+        <h3 key={key} className="text-sm font-semibold">
+          {block.children.map((c, i) => renderChatInline(c, i))}
+        </h3>
+      );
+    case "blockquote":
+      return (
+        <blockquote
+          key={key}
+          className="border-l-2 border-border-primary pl-2 italic"
+        >
+          {block.children.map((c, i) => renderChatBlock(c, i))}
+        </blockquote>
+      );
+    case "ul":
+      return (
+        <ul key={key} className="list-disc pl-5">
+          {block.children.map((item, i) => (
+            <li key={i}>
+              {item.children.map((c, j) => renderChatBlock(c, j))}
+            </li>
+          ))}
+        </ul>
+      );
+    case "ol":
+      return (
+        <ol key={key} className="list-decimal pl-5">
+          {block.children.map((item, i) => (
+            <li key={i}>
+              {item.children.map((c, j) => renderChatBlock(c, j))}
+            </li>
+          ))}
+        </ol>
+      );
+  }
+}
+
+function renderChatInline(node: ChatInlineNode, key: number): React.ReactNode {
+  if (typeof node === "string") return node;
+  if (node.tag === "br") return <br key={key} />;
+  if (node.tag === "span") {
+    let el: React.ReactNode = node.children[0];
+    for (const style of node.styles) {
+      if (style === "bold") el = <strong key={key}>{el}</strong>;
+      else if (style === "italic") el = <em key={key}>{el}</em>;
+      else if (style === "line-through") el = <del key={key}>{el}</del>;
+      else if (style === "code")
+        el = (
+          <code
+            key={key}
+            className="rounded bg-bg-tertiary px-1 py-0.5 font-mono text-[0.85em]"
+          >
+            {el}
+          </code>
+        );
+    }
+    return <React.Fragment key={key}>{el}</React.Fragment>;
+  }
+  if (node.tag === "img") {
+    if (node.previewUrl) {
+      return (
+        <img
+          key={key}
+          src={node.previewUrl}
+          alt={node.alt ?? ""}
+          className="inline-block max-h-16 rounded border border-border-primary align-baseline mx-0.5"
+        />
+      );
+    }
+    return (
+      <span key={key} className="italic text-fg-secondary">
+        [{node.alt ? `image: ${node.alt}` : "image"}]
+      </span>
+    );
+  }
+  if (node.tag === "field_ref") {
+    return (
+      <span
+        key={key}
+        className="rounded bg-bg-tertiary px-1 py-0.5 text-fg-brand-primary"
+      >
+        @{node.path}
+      </span>
+    );
+  }
+  return null;
+}
+
 function getImageUrls(content: AIMessageContent): string[] {
   if (typeof content === "string") {
     return [];
@@ -212,7 +472,9 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
     onLoadSession,
     onFetchSessions,
     onSetSessionName,
+    isLoadingSession,
     initialMessages,
+    chatEditorRef: chatEditorRefProp,
   },
   ref,
 ) {
@@ -222,10 +484,13 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
   const [currentMessage, setCurrentMessage] = useState<CurrentMessage | null>(
     null,
   );
-  const [inputValue, setInputValue] = useState("");
+  const [isEditorEmpty, setIsEditorEmpty] = useState(true);
+  const [hasPendingInlineImage, setHasPendingInlineImage] = useState(false);
+  const [isAwaitingAssistant, setIsAwaitingAssistant] = useState(false);
   const [attachedFiles, setAttachedFiles] = useState<AttachedFile[]>([]);
   const fileInputRef = useRef<HTMLInputElement>(null);
-  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const internalEditorRef = useRef<ChatEditorRef | null>(null);
+  const editorRef = chatEditorRefProp ?? internalEditorRef;
   const bottomRef = useRef<HTMLDivElement>(null);
   const [showSessions, setShowSessions] = useState(false);
   const [renamingSessionId, setRenamingSessionId] = useState<string | null>(
@@ -233,6 +498,7 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
   );
   const [renameValue, setRenameValue] = useState("");
   const config = useValConfig();
+  const portalContainer = useValPortal();
   const effectiveSuggestions = config?.ai?.chat?.suggestions ?? suggestions;
   const emptyTitle = config?.ai?.chat?.title;
   const emptyDescription = config?.ai?.chat?.description;
@@ -249,6 +515,12 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
     });
   }, [messages]);
 
+  // Once the assistant message actually starts streaming, drop the
+  // "thinking" placeholder so the StreamingCursor takes over.
+  useEffect(() => {
+    if (currentMessage) setIsAwaitingAssistant(false);
+  }, [currentMessage]);
+
   // 2-minute timeout for in-progress assistant messages
   useEffect(() => {
     if (!currentMessage) return;
@@ -446,9 +718,33 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
   }, []);
 
   const handleSend = useCallback(
-    (text?: string) => {
-      const content = (text ?? inputValue).trim();
-      if (!content || isStreaming) return;
+    (suggestion?: string) => {
+      if (isStreaming) return;
+
+      let outgoing: string | ChatDocument;
+      let displayText: string;
+      let outgoingDoc: ChatDocument | undefined;
+      if (suggestion !== undefined) {
+        const trimmed = suggestion.trim();
+        if (!trimmed) return;
+        outgoing = trimmed;
+        displayText = trimmed;
+      } else {
+        const editor = editorRef.current;
+        if (!editor || editor.isEmpty()) return;
+        const doc = editor.getDocument();
+        if (
+          collectImageKeysFromDoc(doc).some((k) => k.startsWith("pending:"))
+        ) {
+          // Image still uploading — Send button should already be disabled,
+          // but bail out defensively so a stale pending key never reaches the
+          // server (it would 404 when the AI tries to use it).
+          return;
+        }
+        outgoing = doc;
+        outgoingDoc = doc;
+        displayText = chatDocumentToPlainText(doc);
+      }
 
       const doneAttachments: ChatMessageAttachment[] = attachedFiles
         .filter(
@@ -462,7 +758,6 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
           previewUrl: f.previewUrl,
         }));
 
-      // Revoke object URLs for files we're sending (they'll be in the message)
       attachedFiles.forEach((f) => {
         if (f.previewUrl && f.status !== "done")
           URL.revokeObjectURL(f.previewUrl);
@@ -473,16 +768,21 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
       const userMsg: ChatMessage = {
         id: msgId,
         role: "user",
-        content,
+        content: displayText,
         status: "complete",
         attachments: doneAttachments.length > 0 ? doneAttachments : undefined,
+        userDoc: outgoingDoc,
       };
       setCompletedMessages((prev) => [...prev, userMsg]);
-      setInputValue("");
+
+      if (suggestion === undefined) {
+        editorRef.current?.clear();
+        setIsEditorEmpty(true);
+      }
 
       const sent = onSendMessage
         ? onSendMessage(
-            content,
+            outgoing,
             doneAttachments.length > 0 ? doneAttachments : undefined,
           )
         : true;
@@ -494,12 +794,13 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
               : m,
           ),
         );
+      } else {
+        setIsAwaitingAssistant(true);
       }
 
-      // Refocus textarea after send
-      requestAnimationFrame(() => textareaRef.current?.focus());
+      requestAnimationFrame(() => editorRef.current?.focus());
     },
-    [inputValue, isStreaming, attachedFiles, onSendMessage],
+    [isStreaming, attachedFiles, onSendMessage, editorRef],
   );
 
   const handleRetry = useCallback(
@@ -515,9 +816,10 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
               : m,
           ),
         );
-        const retryText = getTextContent(errorMsg.content);
+        const retryPayload: string | ChatDocument =
+          errorMsg.userDoc ?? getTextContent(errorMsg.content);
         const sent = onSendMessage
-          ? onSendMessage(retryText, errorMsg.attachments)
+          ? onSendMessage(retryPayload, errorMsg.attachments)
           : true;
         if (!sent) {
           setCompletedMessages((prev) =>
@@ -527,6 +829,8 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
                 : m,
             ),
           );
+        } else {
+          setIsAwaitingAssistant(true);
         }
         return;
       }
@@ -543,24 +847,15 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
 
       // Remove the errored assistant message
       setCompletedMessages((prev) => prev.filter((m) => m.id !== errorMsgId));
-      onSendMessage?.(
-        getTextContent(prevUserMsg.content),
-        prevUserMsg.attachments,
-      );
+      const retryPayload: string | ChatDocument =
+        prevUserMsg.userDoc ?? getTextContent(prevUserMsg.content);
+      const sent =
+        onSendMessage?.(retryPayload, prevUserMsg.attachments) ?? true;
+      if (sent) setIsAwaitingAssistant(true);
     },
     [messages, onSendMessage],
   );
 
-  const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-      if (e.key === "Enter" && !e.shiftKey) {
-        e.preventDefault();
-        handleSend();
-      }
-    },
-    [handleSend],
-  );
-
   // ---- Render ----
 
   return (
@@ -720,9 +1015,14 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
 
       {/* Message list */}
       <ScrollArea className="flex-1 min-h-0">
-        <div className="flex flex-col gap-4 p-4">
+        <div className="flex flex-col gap-4 p-4 min-w-0 max-w-full">
           {authError ? (
             <AuthPrompt mode={mode} />
+          ) : isLoadingSession && isEmpty ? (
+            <div className="flex flex-col items-center justify-center gap-2 py-12 text-fg-secondary">
+              <Loader2 className="h-5 w-5 animate-spin" />
+              <span className="text-sm">Loading conversation…</span>
+            </div>
           ) : isEmpty ? (
             <EmptyState
               suggestions={effectiveSuggestions}
@@ -735,6 +1035,7 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
               <MessageBubble key={msg.id} message={msg} onRetry={handleRetry} />
             ))
           )}
+          {isAwaitingAssistant && !currentMessage && <ThinkingIndicator />}
           <div ref={bottomRef} />
         </div>
       </ScrollArea>
@@ -793,65 +1094,66 @@ export const AIChat = forwardRef<AIChatHandle, AIChatProps>(function AIChat(
             accept="image/*"
           />
         )}
-        <div className="flex items-end gap-2">
-          {onUploadFile && (
+        <div
+          className={cn(
+            "flex flex-col rounded-md border border-border-primary bg-bg-primary",
+            "focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2",
+          )}
+        >
+          <AIChatEditor
+            ref={editorRef}
+            disabled={authError || !isConnected || isStreaming}
+            placeholder={isConnected && !authError ? "Ask something…" : ""}
+            onSubmit={() => handleSend()}
+            onUploadAiImage={onUploadFile}
+            getPortalContainer={() => portalContainer}
+            onChange={(doc) => {
+              const empty =
+                doc.length === 0 ||
+                (doc.length === 1 &&
+                  doc[0].tag === "p" &&
+                  doc[0].children.length === 0);
+              setIsEditorEmpty(empty);
+              const keys = collectImageKeysFromDoc(doc);
+              setHasPendingInlineImage(
+                keys.some((k) => k.startsWith("pending:")),
+              );
+            }}
+            className={cn(
+              "max-h-[18rem] overflow-y-auto px-3 pt-3 pb-1",
+              "text-fg-primary text-base",
+            )}
+          />
+          <div className="flex items-center border-t border-border-primary px-2 py-1.5">
+            {onUploadFile && (
+              <Button
+                variant="ghost"
+                size="icon-sm"
+                disabled={!isConnected || isStreaming || authError}
+                onClick={() => fileInputRef.current?.click()}
+                aria-label="Attach files"
+              >
+                <Paperclip className="h-4 w-4" />
+              </Button>
+            )}
             <Button
               variant="ghost"
               size="icon-sm"
-              disabled={!isConnected || isStreaming || authError}
-              onClick={() => fileInputRef.current?.click()}
-              aria-label="Attach files"
-              className="mb-1"
+              disabled={
+                !isConnected ||
+                isStreaming ||
+                isUploading ||
+                hasPendingInlineImage ||
+                authError ||
+                isEditorEmpty
+              }
+              onClick={() => handleSend()}
+              aria-label="Send message"
+              className="ml-auto"
             >
-              <Paperclip className="h-4 w-4" />
+              <Send className="h-4 w-4" />
             </Button>
-          )}
-          <div className="flex-1 grid">
-            <textarea
-              ref={textareaRef}
-              value={inputValue}
-              onChange={(e) => setInputValue(e.target.value)}
-              onKeyDown={handleKeyDown}
-              disabled={authError}
-              placeholder={isConnected && !authError ? "Ask something…" : ""}
-              rows={1}
-              className={cn(
-                "resize-none overflow-hidden",
-                "flex rounded-md border border-border-primary bg-bg-primary px-3 py-2",
-                "text-fg-primary",
-                "ring-offset-background placeholder:text-muted-foreground",
-                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
-              )}
-              style={{ gridArea: "1 / 1 / 2 / 2" }}
-            />
-            {/* Hidden mirror for auto-grow */}
-            <div
-              className={cn(
-                "whitespace-pre-wrap invisible",
-                "flex rounded-md border border-border-primary bg-bg-primary px-3 py-2",
-                "text-sm",
-              )}
-              style={{ gridArea: "1 / 1 / 2 / 2" }}
-            >
-              {inputValue + " "}
-            </div>
           </div>
-          <Button
-            variant="ghost"
-            size="icon-sm"
-            disabled={
-              !isConnected ||
-              isStreaming ||
-              isUploading ||
-              authError ||
-              !inputValue.trim()
-            }
-            onClick={() => handleSend()}
-            aria-label="Send message"
-            className="mb-1"
-          >
-            <Send className="h-4 w-4" />
-          </Button>
         </div>
       </div>
     </div>
@@ -961,10 +1263,13 @@ function MessageBubble({
   const fileUrls = getImageUrls(message.content);
 
   return (
-    <div className={cn("flex", isUser ? "justify-end" : "justify-start")}>
+    <div
+      className={cn("flex min-w-0", isUser ? "justify-end" : "justify-start")}
+    >
       <div
         className={cn(
-          "rounded-lg px-4 py-2.5 text-sm leading-relaxed",
+          "min-w-0 overflow-hidden rounded-lg px-4 py-2.5 text-sm leading-relaxed",
+          "[overflow-wrap:anywhere]",
           isUser
             ? "bg-bg-secondary text-fg-primary max-w-[80%]"
             : "bg-bg-tertiary text-fg-primary w-full max-w-full",
@@ -1007,20 +1312,22 @@ function MessageBubble({
                 ))}
               </div>
             )}
-            {textContent && (
-              <p className="whitespace-pre-wrap">{textContent}</p>
-            )}
-            {message.status === "complete" && (
-              <div className="mt-1 flex justify-end">
-                <span className="flex items-center gap-0.5 text-[10px] text-fg-secondary">
-                  <Check className="h-2.5 w-2.5" />
-                  Sent
-                </span>
-              </div>
+            {message.userDoc ? (
+              <ChatDocumentRenderer doc={message.userDoc} />
+            ) : (
+              textContent && renderUserMessageText(textContent)
             )}
           </>
         ) : (
-          <div className="prose prose-sm dark:prose-invert max-w-none">
+          <div
+            className={cn(
+              "prose prose-sm dark:prose-invert max-w-none",
+              "[&_pre]:overflow-x-auto [&_pre]:max-w-full",
+              "[&_code]:break-words",
+              "[&_table]:block [&_table]:overflow-x-auto [&_table]:max-w-full",
+              "[&_a]:break-all",
+            )}
+          >
             {message.toolActivities && message.toolActivities.length > 0 && (
               <ToolActivitiesIndicator activities={message.toolActivities} />
             )}
@@ -1098,6 +1405,24 @@ function StreamingCursor() {
   );
 }
 
+function ThinkingIndicator() {
+  return (
+    <div className="flex justify-start">
+      <div className="flex items-center gap-1 rounded-lg bg-bg-tertiary px-4 py-3">
+        <span className="h-1.5 w-1.5 rounded-full bg-fg-secondary animate-pulse" />
+        <span
+          className="h-1.5 w-1.5 rounded-full bg-fg-secondary animate-pulse"
+          style={{ animationDelay: "150ms" }}
+        />
+        <span
+          className="h-1.5 w-1.5 rounded-full bg-fg-secondary animate-pulse"
+          style={{ animationDelay: "300ms" }}
+        />
+      </div>
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Tool activity display
 // ---------------------------------------------------------------------------
diff --git a/packages/ui/spa/components/AIChatActionsContext.tsx b/packages/ui/spa/components/AIChatActionsContext.tsx
new file mode 100644
index 000000000..c8c977184
--- /dev/null
+++ b/packages/ui/spa/components/AIChatActionsContext.tsx
@@ -0,0 +1,75 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import type { SourcePath } from "@valbuild/core";
+import type { ChatEditorRef } from "./AIChatEditor";
+
+export interface AIChatActions {
+  isAIChatEnabled: boolean;
+  openAIChat(): void;
+  setOpenAIChatImpl(fn: (() => void) | null): void;
+  chatEditorRef: RefObject<ChatEditorRef | null>;
+}
+
+const AIChatActionsContext = createContext<AIChatActions>({
+  isAIChatEnabled: false,
+  openAIChat: () => {},
+  setOpenAIChatImpl: () => {},
+  chatEditorRef: { current: null },
+});
+
+export function AIChatActionsProvider({
+  isAIChatEnabled,
+  children,
+}: {
+  isAIChatEnabled: boolean;
+  children: ReactNode;
+}) {
+  const openImplRef = useRef<(() => void) | null>(null);
+  const chatEditorRef = useRef<ChatEditorRef | null>(null);
+
+  const openAIChat = useCallback(() => {
+    openImplRef.current?.();
+  }, []);
+
+  const setOpenAIChatImpl = useCallback((fn: (() => void) | null) => {
+    openImplRef.current = fn;
+  }, []);
+
+  const value = useMemo<AIChatActions>(
+    () => ({
+      isAIChatEnabled,
+      openAIChat,
+      setOpenAIChatImpl,
+      chatEditorRef,
+    }),
+    [isAIChatEnabled, openAIChat, setOpenAIChatImpl],
+  );
+
+  return (
+    <AIChatActionsContext.Provider value={value}>
+      {children}
+    </AIChatActionsContext.Provider>
+  );
+}
+
+export function useAIChatActions(): AIChatActions {
+  return useContext(AIChatActionsContext);
+}
+
+export function useInsertFieldRef() {
+  const { chatEditorRef, openAIChat } = useAIChatActions();
+  return useCallback(
+    (path: SourcePath) => {
+      openAIChat();
+      chatEditorRef.current?.insertFieldRef(path);
+    },
+    [chatEditorRef, openAIChat],
+  );
+}
diff --git a/packages/ui/spa/components/AIChatEditor/AIChatEditor.tsx b/packages/ui/spa/components/AIChatEditor/AIChatEditor.tsx
new file mode 100644
index 000000000..3b92117a5
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/AIChatEditor.tsx
@@ -0,0 +1,318 @@
+import {
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useMemo,
+  useEffect,
+} from "react";
+import { EditorState, Selection } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { history } from "prosemirror-history";
+import { dropCursor } from "prosemirror-dropcursor";
+import { gapCursor } from "prosemirror-gapcursor";
+import type { Schema } from "prosemirror-model";
+import classNames from "classnames";
+import type { SourcePath } from "@valbuild/core";
+import { buildChatSchema } from "./schema/buildChatSchema";
+import { buildChatKeymap } from "./plugins/keymap";
+import { buildChatInputRules } from "./plugins/inputRules";
+import { createSubmitOnEnterPlugin } from "./plugins/submitOnEnterPlugin";
+import { createChatFloatingToolbarPlugin } from "./plugins/floatingToolbar";
+import {
+  createChatImageNodeView,
+  fetchUrlAsFile,
+  insertImageWithUpload,
+} from "./plugins/imageNodeView";
+import { createFieldRefNodeView } from "./plugins/fieldRefNodeView";
+import { serializeChatDocument } from "./serialize/serializeChatDocument";
+import { parseChatDocument } from "./serialize/parseChatDocument";
+import type { ChatDocument, ChatEditorRef } from "./types";
+
+export interface AIChatEditorProps {
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  onSubmit?: () => void;
+  onChange?: (doc: ChatDocument) => void;
+  onUploadAiImage?: (file: File) => Promise<{ key: string }>;
+  getPortalContainer?: () => HTMLElement | null;
+}
+
+function transformPastedHtml(html: string): string {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<meta[^>]*>/gi, "")
+    .replace(/<o:p\b[^>]*>[\s\S]*?<\/o:p>/gi, "");
+}
+
+// Pull every <img src="..."> URL out of an HTML fragment, skipping any image
+// that already carries our `data-val-ai-key` attribute (those are round-trips
+// from our own editor and have a valid key already).
+function extractImageSrcsFromHtml(html: string | undefined | null): string[] {
+  if (!html) return [];
+  const doc = new DOMParser().parseFromString(
+    `<body>${html}</body>`,
+    "text/html",
+  );
+  const out: string[] = [];
+  doc.body.querySelectorAll("img").forEach((img) => {
+    if (img.hasAttribute("data-val-ai-key")) return;
+    const src = img.getAttribute("src");
+    if (src) out.push(src);
+  });
+  return out;
+}
+
+async function uploadHtmlImageSrcs(
+  view: EditorView,
+  srcs: string[],
+  upload: (file: File) => Promise<{ key: string }>,
+): Promise<void> {
+  for (const src of srcs) {
+    const file = await fetchUrlAsFile(src);
+    if (!file) {
+      console.warn("AI chat: skipped pasted image (fetch failed)", src);
+      continue;
+    }
+    insertImageWithUpload(view, file, upload);
+  }
+}
+
+export const AIChatEditor = forwardRef<ChatEditorRef | null, AIChatEditorProps>(
+  function AIChatEditor(
+    {
+      placeholder,
+      disabled,
+      className,
+      onSubmit,
+      onChange,
+      onUploadAiImage,
+      getPortalContainer,
+    },
+    ref,
+  ) {
+    const containerRef = useRef<HTMLDivElement | null>(null);
+    const viewRef = useRef<EditorView | null>(null);
+    const schema = useMemo<Schema>(() => buildChatSchema(), []);
+
+    const onSubmitRef = useRef(onSubmit);
+    onSubmitRef.current = onSubmit;
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const onUploadAiImageRef = useRef(onUploadAiImage);
+    onUploadAiImageRef.current = onUploadAiImage;
+    const disabledRef = useRef<boolean | undefined>(disabled);
+    disabledRef.current = disabled;
+
+    useLayoutEffect(() => {
+      const container = containerRef.current;
+      if (!container) return;
+
+      const doc = schema.node("doc", null, [schema.node("paragraph")]);
+
+      const plugins = [
+        createSubmitOnEnterPlugin(schema, () => onSubmitRef.current?.()),
+        ...buildChatKeymap(schema),
+        buildChatInputRules(schema),
+        history(),
+        dropCursor(),
+        gapCursor(),
+        createChatFloatingToolbarPlugin(schema, {
+          getPortalContainer,
+          getUploadAiImage: () => onUploadAiImageRef.current,
+        }),
+      ];
+
+      const view = new EditorView(container, {
+        state: EditorState.create({ doc, schema, plugins }),
+        nodeViews: {
+          field_ref: createFieldRefNodeView(),
+          image: createChatImageNodeView(),
+        },
+        transformPastedHTML: transformPastedHtml,
+        handlePaste(view, event) {
+          const upload = onUploadAiImageRef.current;
+          if (!upload) return false;
+          const items = event.clipboardData?.items;
+          if (items) {
+            for (let i = 0; i < items.length; i++) {
+              const item = items[i];
+              if (item.kind === "file" && item.type.startsWith("image/")) {
+                const file = item.getAsFile();
+                if (file) {
+                  insertImageWithUpload(view, file, upload);
+                  return true;
+                }
+              }
+            }
+          }
+          // No binary image in the clipboard. If the HTML payload contains an
+          // <img src=...> from a web page, fetch + upload it through the same
+          // pipeline so we never leave a stale pending: key in the doc.
+          const html = event.clipboardData?.getData("text/html");
+          const srcs = extractImageSrcsFromHtml(html);
+          if (srcs.length > 0) {
+            uploadHtmlImageSrcs(view, srcs, upload);
+            return true;
+          }
+          return false;
+        },
+        handleDrop(view, event) {
+          const upload = onUploadAiImageRef.current;
+          if (!upload) return false;
+          const dt = (event as DragEvent).dataTransfer;
+          const files = dt?.files;
+          if (files && files.length > 0) {
+            const file = Array.from(files).find((f) =>
+              f.type.startsWith("image/"),
+            );
+            if (file) {
+              event.preventDefault();
+              insertImageWithUpload(view, file, upload);
+              return true;
+            }
+          }
+          const html = dt?.getData("text/html");
+          const srcs = extractImageSrcsFromHtml(html);
+          if (srcs.length > 0) {
+            event.preventDefault();
+            uploadHtmlImageSrcs(view, srcs, upload);
+            return true;
+          }
+          return false;
+        },
+        dispatchTransaction(tr) {
+          const next = view.state.apply(tr);
+          view.updateState(next);
+          if (tr.docChanged) {
+            onChangeRef.current?.(serializeChatDocument(next.doc));
+          }
+        },
+        editable: () => !disabledRef.current,
+      });
+
+      viewRef.current = view;
+
+      return () => {
+        view.destroy();
+        viewRef.current = null;
+      };
+    }, [schema]);
+
+    useEffect(() => {
+      const view = viewRef.current;
+      if (!view) return;
+      view.setProps({ editable: () => !disabledRef.current });
+    }, [disabled]);
+
+    useImperativeHandle(
+      ref,
+      (): ChatEditorRef => ({
+        getDocument: () => {
+          const view = viewRef.current;
+          if (!view) return [];
+          return serializeChatDocument(view.state.doc);
+        },
+        setDocument: (newDoc) => {
+          const view = viewRef.current;
+          if (!view) return;
+          const next = parseChatDocument(newDoc, schema);
+          const state = EditorState.create({
+            doc: next,
+            schema,
+            plugins: view.state.plugins,
+          });
+          view.updateState(state);
+        },
+        clear: () => {
+          const view = viewRef.current;
+          if (!view) return;
+          const next = schema.node("doc", null, [schema.node("paragraph")]);
+          const state = EditorState.create({
+            doc: next,
+            schema,
+            plugins: view.state.plugins,
+          });
+          view.updateState(state);
+        },
+        focus: () => {
+          viewRef.current?.focus();
+        },
+        isEmpty: () => {
+          const view = viewRef.current;
+          if (!view) return true;
+          const doc = view.state.doc;
+          if (doc.childCount === 0) return true;
+          if (doc.childCount > 1) return false;
+          const only = doc.firstChild;
+          if (!only) return true;
+          if (only.type.name !== "paragraph") return false;
+          return only.content.size === 0;
+        },
+        insertFieldRef: (path: SourcePath) => {
+          const view = viewRef.current;
+          if (!view) return;
+          const fieldType = schema.nodes.field_ref;
+          const node = fieldType.create({ path });
+          const docSize = view.state.doc.content.size;
+          const last = view.state.doc.lastChild;
+          const tr = view.state.tr;
+          if (last && last.type.name === "paragraph") {
+            const insertPos = docSize - 1;
+            tr.insert(insertPos, node);
+            tr.insertText(" ", insertPos + node.nodeSize);
+          } else {
+            const para = schema.node("paragraph", null, [node]);
+            tr.insert(docSize, para);
+          }
+          view.dispatch(tr.scrollIntoView());
+          view.focus();
+        },
+      }),
+      [schema],
+    );
+
+    return (
+      <div
+        className={classNames(
+          "val-chat-editor relative flex flex-col cursor-text",
+          className,
+          {
+            "opacity-60 cursor-not-allowed": disabled,
+          },
+        )}
+        onMouseDown={(e) => {
+          // If the user clicks the wrapper (padding/empty area) — not inside
+          // the editor DOM itself — focus the editor at the end so the click
+          // doesn't feel "dead".
+          if (disabled) return;
+          const view = viewRef.current;
+          if (!view) return;
+          if (
+            e.target === e.currentTarget ||
+            e.target === containerRef.current
+          ) {
+            e.preventDefault();
+            view.focus();
+            const end = view.state.doc.content.size;
+            view.dispatch(
+              view.state.tr.setSelection(
+                Selection.near(view.state.doc.resolve(end)),
+              ),
+            );
+          }
+        }}
+      >
+        <div
+          ref={containerRef}
+          className={classNames(
+            "val-chat-editor-content flex-1 min-h-[2.25rem] outline-none",
+            "[&_.ProseMirror]:min-h-full [&_.ProseMirror]:outline-none",
+          )}
+          data-placeholder={placeholder || ""}
+        />
+      </div>
+    );
+  },
+);
diff --git a/packages/ui/spa/components/AIChatEditor/__tests__/serializeChat.test.ts b/packages/ui/spa/components/AIChatEditor/__tests__/serializeChat.test.ts
new file mode 100644
index 000000000..eb5d9a673
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/__tests__/serializeChat.test.ts
@@ -0,0 +1,312 @@
+import type { SourcePath } from "@valbuild/core";
+import { buildChatSchema } from "../schema/buildChatSchema";
+import { parseChatDocument } from "../serialize/parseChatDocument";
+import { serializeChatDocument } from "../serialize/serializeChatDocument";
+import { chatDocumentToHtmlText } from "../serialize/chatDocumentToHtmlText";
+import {
+  collectImageKeysFromDoc,
+  collectImageNodesFromDoc,
+} from "../serialize/collectImageKeysFromDoc";
+import type { ChatDocument } from "../types";
+
+const schema = buildChatSchema();
+
+function roundTrip(doc: ChatDocument): ChatDocument {
+  const pm = parseChatDocument(doc, schema);
+  return serializeChatDocument(pm);
+}
+
+describe("serializeChatDocument / parseChatDocument round-trip", () => {
+  it("empty document materializes a single empty paragraph", () => {
+    const out = roundTrip([]);
+    expect(out).toEqual([{ tag: "p", children: [] }]);
+  });
+
+  it("preserves a plain paragraph", () => {
+    const doc: ChatDocument = [{ tag: "p", children: ["hello world"] }];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves headings h1/h2/h3", () => {
+    const doc: ChatDocument = [
+      { tag: "h1", children: ["title"] },
+      { tag: "h2", children: ["subtitle"] },
+      { tag: "h3", children: ["section"] },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves marks (bold, italic, line-through, code)", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: [
+          "plain ",
+          { tag: "span", styles: ["bold"], children: ["bold"] },
+          " ",
+          { tag: "span", styles: ["italic"], children: ["italic"] },
+          " ",
+          { tag: "span", styles: ["line-through"], children: ["strike"] },
+          " ",
+          { tag: "span", styles: ["code"], children: ["code"] },
+        ],
+      },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves hard breaks", () => {
+    const doc: ChatDocument = [
+      { tag: "p", children: ["line 1", { tag: "br" }, "line 2"] },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves bullet and ordered lists", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "ul",
+        children: [
+          { tag: "li", children: [{ tag: "p", children: ["alpha"] }] },
+          { tag: "li", children: [{ tag: "p", children: ["beta"] }] },
+        ],
+      },
+      {
+        tag: "ol",
+        children: [
+          { tag: "li", children: [{ tag: "p", children: ["one"] }] },
+          { tag: "li", children: [{ tag: "p", children: ["two"] }] },
+        ],
+      },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves blockquote", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "blockquote",
+        children: [{ tag: "p", children: ["quoted text"] }],
+      },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves image nodes with key + metadata", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: [
+          "look: ",
+          {
+            tag: "img",
+            key: "abc123",
+            alt: "a cat",
+            previewUrl: "blob:xyz",
+            width: 320,
+            height: 240,
+            mimeType: "image/png",
+          },
+        ],
+      },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+
+  it("preserves field_ref nodes", () => {
+    const path = "/content/blogs.val.ts?p=0.title" as SourcePath;
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: ["change ", { tag: "field_ref", path }],
+      },
+    ];
+    expect(roundTrip(doc)).toEqual(doc);
+  });
+});
+
+describe("chatDocumentToHtmlText", () => {
+  it("renders a simple paragraph", () => {
+    expect(chatDocumentToHtmlText([{ tag: "p", children: ["hello"] }])).toBe(
+      "<p>hello</p>",
+    );
+  });
+
+  it("escapes <, > and & in text", () => {
+    expect(
+      chatDocumentToHtmlText([
+        { tag: "p", children: ['<script>alert("x") & co</script>'] },
+      ]),
+    ).toBe('<p>&lt;script&gt;alert("x") &amp; co&lt;/script&gt;</p>');
+  });
+
+  it("emits inline marks as HTML tags", () => {
+    expect(
+      chatDocumentToHtmlText([
+        {
+          tag: "p",
+          children: [
+            { tag: "span", styles: ["bold"], children: ["b"] },
+            { tag: "span", styles: ["italic"], children: ["i"] },
+            { tag: "span", styles: ["line-through"], children: ["s"] },
+            { tag: "span", styles: ["code"], children: ["c"] },
+          ],
+        },
+      ]),
+    ).toBe("<p><strong>b</strong><em>i</em><del>s</del><code>c</code></p>");
+  });
+
+  it("renders headings, blockquote, lists and br", () => {
+    const doc: ChatDocument = [
+      { tag: "h1", children: ["Title"] },
+      { tag: "blockquote", children: [{ tag: "p", children: ["q"] }] },
+      {
+        tag: "ul",
+        children: [
+          {
+            tag: "li",
+            children: [{ tag: "p", children: ["x", { tag: "br" }, "y"] }],
+          },
+        ],
+      },
+      {
+        tag: "ol",
+        children: [{ tag: "li", children: [{ tag: "p", children: ["one"] }] }],
+      },
+    ];
+    expect(chatDocumentToHtmlText(doc)).toBe(
+      "<h1>Title</h1>\n<blockquote><p>q</p></blockquote>\n<ul><li><p>x<br/>y</p></li></ul>\n<ol><li><p>one</p></li></ol>",
+    );
+  });
+
+  it("renders image with key (escaping attr) and optional alt", () => {
+    expect(
+      chatDocumentToHtmlText([
+        {
+          tag: "p",
+          children: [
+            { tag: "img", key: 'k"&<>', alt: 'a "cat"' },
+            { tag: "img", key: "plain" },
+          ],
+        },
+      ]),
+    ).toBe(
+      '<p><img key="k&quot;&amp;&lt;&gt;" alt="a &quot;cat&quot;"/><img key="plain"/></p>',
+    );
+  });
+
+  it("renders field_ref as a self-closing tag with attr escaping", () => {
+    const path = '/content/foo.val.ts?p="bar"' as SourcePath;
+    expect(
+      chatDocumentToHtmlText([
+        { tag: "p", children: [{ tag: "field_ref", path }] },
+      ]),
+    ).toBe('<p><field path="/content/foo.val.ts?p=&quot;bar&quot;"/></p>');
+  });
+});
+
+describe("collectImageKeysFromDoc", () => {
+  it("returns no keys for a doc without images", () => {
+    const doc: ChatDocument = [{ tag: "p", children: ["just text"] }];
+    expect(collectImageKeysFromDoc(doc)).toEqual([]);
+  });
+
+  it("collects keys from a flat paragraph in document order", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: [
+          "see ",
+          { tag: "img", key: "a", previewUrl: "blob:1" },
+          " and ",
+          { tag: "img", key: "b", previewUrl: "blob:2" },
+        ],
+      },
+    ];
+    expect(collectImageKeysFromDoc(doc)).toEqual(["a", "b"]);
+  });
+
+  it("walks into blockquote, ul and ol", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "blockquote",
+        children: [{ tag: "p", children: [{ tag: "img", key: "in-bq" }] }],
+      },
+      {
+        tag: "ul",
+        children: [
+          {
+            tag: "li",
+            children: [{ tag: "p", children: [{ tag: "img", key: "in-ul" }] }],
+          },
+        ],
+      },
+      {
+        tag: "ol",
+        children: [
+          {
+            tag: "li",
+            children: [{ tag: "p", children: [{ tag: "img", key: "in-ol" }] }],
+          },
+        ],
+      },
+    ];
+    expect(collectImageKeysFromDoc(doc)).toEqual(["in-bq", "in-ul", "in-ol"]);
+  });
+
+  it("returns full image nodes via collectImageNodesFromDoc", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: [
+          {
+            tag: "img",
+            key: "k1",
+            alt: "cat",
+            previewUrl: "blob:cat",
+            width: 100,
+            height: 50,
+            mimeType: "image/png",
+          },
+        ],
+      },
+    ];
+    expect(collectImageNodesFromDoc(doc)).toEqual([
+      {
+        tag: "img",
+        key: "k1",
+        alt: "cat",
+        previewUrl: "blob:cat",
+        width: 100,
+        height: 50,
+        mimeType: "image/png",
+      },
+    ]);
+  });
+
+  it("preserves both pending: and real keys (filtering is caller's job)", () => {
+    const doc: ChatDocument = [
+      {
+        tag: "p",
+        children: [
+          { tag: "img", key: "pending:abc" },
+          { tag: "img", key: "real-key" },
+        ],
+      },
+    ];
+    expect(collectImageKeysFromDoc(doc)).toEqual(["pending:abc", "real-key"]);
+  });
+});
+
+describe("buildChatSchema image node spec", () => {
+  it("has exactly one parseDOM rule (the data-val-ai-key one)", () => {
+    // Sanity: the old `img[src]` fallback minted stale pending: keys via
+    // Math.random() and was the source of the 404 "Session file(s) not found"
+    // bug. It has been removed. Paste/drop handlers fetch HTML <img src> and
+    // run them through insertImageWithUpload so a real key is always assigned.
+    const imageSpec = schema.nodes.image.spec;
+    const rules = imageSpec.parseDOM ?? [];
+    expect(rules).toHaveLength(1);
+    expect(rules[0].tag).toBe("img[data-val-ai-key]");
+  });
+});
diff --git a/packages/ui/spa/components/AIChatEditor/index.ts b/packages/ui/spa/components/AIChatEditor/index.ts
new file mode 100644
index 000000000..d4bada206
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/index.ts
@@ -0,0 +1,20 @@
+export { AIChatEditor } from "./AIChatEditor";
+export type { AIChatEditorProps } from "./AIChatEditor";
+export type {
+  ChatDocument,
+  ChatBlockNode,
+  ChatInlineNode,
+  ChatImageNode,
+  ChatFieldRefNode,
+  ChatEditorRef,
+} from "./types";
+export { EMPTY_CHAT_DOCUMENT } from "./types";
+export { chatDocumentToHtmlText } from "./serialize/chatDocumentToHtmlText";
+export { chatDocumentToPlainText } from "./serialize/chatDocumentToPlainText";
+export { parseChatDocument } from "./serialize/parseChatDocument";
+export { serializeChatDocument } from "./serialize/serializeChatDocument";
+export {
+  collectImageKeysFromDoc,
+  collectImageNodesFromDoc,
+} from "./serialize/collectImageKeysFromDoc";
+export { buildChatSchema } from "./schema/buildChatSchema";
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/ChatToolbarButtons.tsx b/packages/ui/spa/components/AIChatEditor/plugins/ChatToolbarButtons.tsx
new file mode 100644
index 000000000..eb73defc8
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/ChatToolbarButtons.tsx
@@ -0,0 +1,251 @@
+import { useState } from "react";
+import type { EditorView } from "prosemirror-view";
+import type { MarkType, NodeType, Schema } from "prosemirror-model";
+import type { EditorState } from "prosemirror-state";
+import { toggleMark, setBlockType, wrapIn } from "prosemirror-commands";
+import { wrapInList, liftListItem } from "prosemirror-schema-list";
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  Code as CodeIcon,
+  List,
+  ListOrdered,
+  Quote,
+  Image as ImageIcon,
+  ChevronDown,
+} from "lucide-react";
+import classNames from "classnames";
+import { insertImageWithUpload } from "./imageNodeView";
+
+function isMarkActive(state: EditorState, type: MarkType): boolean {
+  const { from, $from, to, empty } = state.selection;
+  if (empty) return !!type.isInSet(state.storedMarks || $from.marks());
+  return state.doc.rangeHasMark(from, to, type);
+}
+
+function isListActive(state: EditorState, listType: NodeType): boolean {
+  const { $from } = state.selection;
+  for (let d = $from.depth; d > 0; d--) {
+    if ($from.node(d).type === listType) return true;
+  }
+  return false;
+}
+
+function toggleList(view: EditorView, listType: NodeType, schema: Schema) {
+  const { state, dispatch } = view;
+  if (isListActive(state, listType)) {
+    return liftListItem(schema.nodes.list_item)(state, dispatch);
+  }
+  return wrapInList(listType)(state, dispatch);
+}
+
+function currentHeadingLevel(state: EditorState): 1 | 2 | 3 | null {
+  const { $from } = state.selection;
+  if ($from.parent.type.name === "heading") {
+    const level = $from.parent.attrs.level as number;
+    if (level === 1 || level === 2 || level === 3) return level;
+  }
+  return null;
+}
+
+function ToolbarIconButton({
+  active,
+  onMouseDown,
+  title,
+  children,
+  disabled,
+}: {
+  active?: boolean;
+  onMouseDown: (e: React.MouseEvent) => void;
+  title: string;
+  children: React.ReactNode;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      title={title}
+      aria-pressed={active}
+      disabled={disabled}
+      onMouseDown={onMouseDown}
+      className={classNames(
+        "flex h-7 w-7 items-center justify-center rounded text-fg-primary",
+        "hover:bg-bg-secondary disabled:opacity-50",
+        { "bg-bg-secondary": active },
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function ChatToolbarButtons({
+  view,
+  schema,
+  onUploadAiImage,
+}: {
+  view: EditorView;
+  schema: Schema;
+  onUploadAiImage?: (file: File) => Promise<{ key: string }>;
+}) {
+  const [headingOpen, setHeadingOpen] = useState(false);
+  const { state } = view;
+  const currentLevel = currentHeadingLevel(state);
+  const headingLabel = currentLevel ? `H${currentLevel}` : "P";
+
+  const apply = (cmd: (s: EditorState) => boolean) => (e: React.MouseEvent) => {
+    e.preventDefault();
+    cmd(view.state);
+    view.focus();
+  };
+
+  return (
+    <>
+      <div className="relative">
+        <button
+          type="button"
+          title="Block type"
+          onMouseDown={(e) => {
+            e.preventDefault();
+            setHeadingOpen((v) => !v);
+          }}
+          className="flex h-7 items-center justify-center gap-1 rounded px-2 text-xs font-medium text-fg-primary hover:bg-bg-secondary"
+        >
+          {headingLabel}
+          <ChevronDown size={12} />
+        </button>
+        {headingOpen && (
+          <div className="absolute left-0 top-8 z-10 min-w-[8em] rounded-md border border-border-primary bg-bg-primary shadow-md py-1">
+            {(["P", "H1", "H2", "H3"] as const).map((label) => (
+              <button
+                key={label}
+                type="button"
+                onMouseDown={(e) => {
+                  e.preventDefault();
+                  if (label === "P") {
+                    setBlockType(schema.nodes.paragraph)(
+                      view.state,
+                      view.dispatch,
+                      view,
+                    );
+                  } else {
+                    const level = parseInt(label[1], 10);
+                    setBlockType(schema.nodes.heading, { level })(
+                      view.state,
+                      view.dispatch,
+                      view,
+                    );
+                  }
+                  setHeadingOpen(false);
+                  view.focus();
+                }}
+                className="block w-full px-3 py-1 text-left text-xs hover:bg-bg-secondary"
+              >
+                {label === "P" ? "Paragraph" : `Heading ${label[1]}`}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className="mx-1 h-5 w-px bg-border-primary" />
+
+      <ToolbarIconButton
+        title="Bold (Ctrl+B)"
+        active={isMarkActive(state, schema.marks.bold)}
+        onMouseDown={apply((s) =>
+          toggleMark(schema.marks.bold)(s, view.dispatch),
+        )}
+      >
+        <Bold size={14} />
+      </ToolbarIconButton>
+      <ToolbarIconButton
+        title="Italic (Ctrl+I)"
+        active={isMarkActive(state, schema.marks.italic)}
+        onMouseDown={apply((s) =>
+          toggleMark(schema.marks.italic)(s, view.dispatch),
+        )}
+      >
+        <Italic size={14} />
+      </ToolbarIconButton>
+      <ToolbarIconButton
+        title="Strikethrough (Ctrl+Shift+X)"
+        active={isMarkActive(state, schema.marks.strikethrough)}
+        onMouseDown={apply((s) =>
+          toggleMark(schema.marks.strikethrough)(s, view.dispatch),
+        )}
+      >
+        <Strikethrough size={14} />
+      </ToolbarIconButton>
+      <ToolbarIconButton
+        title="Inline code (Ctrl+E)"
+        active={isMarkActive(state, schema.marks.code)}
+        onMouseDown={apply((s) =>
+          toggleMark(schema.marks.code)(s, view.dispatch),
+        )}
+      >
+        <CodeIcon size={14} />
+      </ToolbarIconButton>
+
+      <div className="mx-1 h-5 w-px bg-border-primary" />
+
+      <ToolbarIconButton
+        title="Bullet list (Ctrl+Shift+8)"
+        active={isListActive(state, schema.nodes.bullet_list)}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          toggleList(view, schema.nodes.bullet_list, schema);
+          view.focus();
+        }}
+      >
+        <List size={14} />
+      </ToolbarIconButton>
+      <ToolbarIconButton
+        title="Numbered list (Ctrl+Shift+9)"
+        active={isListActive(state, schema.nodes.ordered_list)}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          toggleList(view, schema.nodes.ordered_list, schema);
+          view.focus();
+        }}
+      >
+        <ListOrdered size={14} />
+      </ToolbarIconButton>
+      <ToolbarIconButton
+        title="Blockquote (Ctrl+Shift+B)"
+        onMouseDown={(e) => {
+          e.preventDefault();
+          wrapIn(schema.nodes.blockquote)(view.state, view.dispatch);
+          view.focus();
+        }}
+      >
+        <Quote size={14} />
+      </ToolbarIconButton>
+
+      {onUploadAiImage && (
+        <>
+          <div className="mx-1 h-5 w-px bg-border-primary" />
+          <ToolbarIconButton
+            title="Insert image"
+            onMouseDown={(e) => {
+              e.preventDefault();
+              const input = document.createElement("input");
+              input.type = "file";
+              input.accept = "image/*";
+              input.onchange = () => {
+                const file = input.files?.[0];
+                if (file) {
+                  insertImageWithUpload(view, file, onUploadAiImage);
+                }
+              };
+              input.click();
+            }}
+          >
+            <ImageIcon size={14} />
+          </ToolbarIconButton>
+        </>
+      )}
+    </>
+  );
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/fieldRefNodeView.tsx b/packages/ui/spa/components/AIChatEditor/plugins/fieldRefNodeView.tsx
new file mode 100644
index 000000000..cd6b1a85c
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/fieldRefNodeView.tsx
@@ -0,0 +1,110 @@
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { EditorView, NodeView } from "prosemirror-view";
+import type { Node as PMNode } from "prosemirror-model";
+import { Internal, type SourcePath } from "@valbuild/core";
+import { prettifyFilename } from "../../../utils/prettifyFilename";
+
+function FieldRefChip({
+  path,
+  onRemove,
+}: {
+  path: SourcePath;
+  onRemove: () => void;
+}) {
+  let label = path;
+  try {
+    const [moduleFilePath, modulePath] =
+      Internal.splitModuleFilePathAndModulePath(path);
+    const moduleParts = Internal.splitModuleFilePath(moduleFilePath);
+    const modulePathParts = Internal.splitModulePath(modulePath);
+    const moduleSuffix =
+      moduleParts.length > 0
+        ? prettifyFilename(moduleParts[moduleParts.length - 1])
+        : moduleFilePath;
+    const allParts = [moduleSuffix, ...modulePathParts.map(prettifyFilename)];
+    label = allParts.join(" / ") as SourcePath;
+  } catch {
+    // fall through to raw path
+  }
+  return createElement(
+    "span",
+    {
+      className:
+        "inline-flex items-center gap-1 align-baseline rounded bg-bg-secondary text-fg-primary px-1.5 py-0.5 text-xs font-mono mx-0.5",
+      title: path,
+      contentEditable: false,
+    },
+    createElement("span", { className: "truncate max-w-[16em]" }, label),
+    createElement(
+      "button",
+      {
+        type: "button",
+        onMouseDown: (e: MouseEvent) => {
+          e.preventDefault();
+          e.stopPropagation();
+          onRemove();
+        },
+        className: "text-fg-secondary hover:text-fg-primary leading-none",
+        "aria-label": "Remove field reference",
+      },
+      "×",
+    ),
+  );
+}
+
+export function createFieldRefNodeView() {
+  return function fieldRefNodeView(
+    node: PMNode,
+    view: EditorView,
+    getPos: () => number | undefined,
+  ): NodeView {
+    const dom = document.createElement("span");
+    dom.setAttribute("data-val-field-ref", node.attrs.path as string);
+    dom.style.display = "inline-block";
+    dom.style.verticalAlign = "baseline";
+    dom.contentEditable = "false";
+
+    const root: Root = createRoot(dom);
+
+    const removeSelf = () => {
+      const pos = getPos();
+      if (pos === undefined) return;
+      const tr = view.state.tr.delete(pos, pos + node.nodeSize);
+      view.dispatch(tr);
+      view.focus();
+    };
+
+    root.render(
+      createElement(FieldRefChip, {
+        path: node.attrs.path as SourcePath,
+        onRemove: removeSelf,
+      }),
+    );
+
+    return {
+      dom,
+      update(updated) {
+        if (updated.type !== node.type) return false;
+        if (updated.attrs.path === node.attrs.path) return true;
+        root.render(
+          createElement(FieldRefChip, {
+            path: updated.attrs.path as SourcePath,
+            onRemove: removeSelf,
+          }),
+        );
+        return true;
+      },
+      stopEvent(e) {
+        // Allow clicks on our × button without ProseMirror swallowing them.
+        return (e as Event).type === "mousedown";
+      },
+      ignoreMutation() {
+        return true;
+      },
+      destroy() {
+        queueMicrotask(() => root.unmount());
+      },
+    };
+  };
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/floatingToolbar.ts b/packages/ui/spa/components/AIChatEditor/plugins/floatingToolbar.ts
new file mode 100644
index 000000000..6f22f635c
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/floatingToolbar.ts
@@ -0,0 +1,118 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+import type { Schema } from "prosemirror-model";
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { ChatToolbarButtons } from "./ChatToolbarButtons";
+
+export const chatFloatingToolbarKey = new PluginKey("chatFloatingToolbar");
+
+export interface ChatFloatingToolbarOptions {
+  getPortalContainer?: () => HTMLElement | null;
+  getUploadAiImage?: () =>
+    | ((file: File) => Promise<{ key: string }>)
+    | undefined;
+}
+
+export function createChatFloatingToolbarPlugin(
+  schema: Schema,
+  options?: ChatFloatingToolbarOptions,
+): Plugin {
+  let toolbarEl: HTMLElement | null = null;
+  let reactRoot: Root | null = null;
+
+  function updateToolbar(view: EditorView) {
+    if (!toolbarEl || !reactRoot) return;
+    const { selection } = view.state;
+    const { empty, from, to } = selection;
+    if (empty || !view.hasFocus()) {
+      toolbarEl.style.display = "none";
+      return;
+    }
+
+    reactRoot.render(
+      createElement(ChatToolbarButtons, {
+        view,
+        schema,
+        onUploadAiImage: options?.getUploadAiImage?.(),
+      }),
+    );
+
+    const portal = options?.getPortalContainer?.();
+    toolbarEl.style.display = "flex";
+
+    const positionToolbar = () => {
+      if (!toolbarEl) return;
+      const start = view.coordsAtPos(from);
+      const end = view.coordsAtPos(to);
+      const selectionCenterX = (start.left + end.left) / 2;
+      const selectionTop = Math.min(start.top, end.top);
+      const selectionBottom = Math.max(start.bottom, end.bottom);
+
+      // Fallbacks cover the very first render before React has flushed
+      // the buttons (offsetWidth/Height would be 0 then).
+      const toolbarWidth = toolbarEl.offsetWidth || 220;
+      const toolbarHeight = toolbarEl.offsetHeight || 36;
+
+      const margin = 8;
+      const gap = 8;
+
+      let leftViewport = selectionCenterX - toolbarWidth / 2;
+      let topViewport = selectionTop - toolbarHeight - gap;
+
+      // Flip below the selection if there's no room above.
+      if (topViewport < margin) {
+        topViewport = selectionBottom + gap;
+      }
+
+      // Clamp horizontally so the toolbar stays inside the viewport.
+      const maxLeft = window.innerWidth - toolbarWidth - margin;
+      leftViewport = Math.max(margin, Math.min(leftViewport, maxLeft));
+
+      if (portal) {
+        toolbarEl.style.left = `${leftViewport}px`;
+        toolbarEl.style.top = `${topViewport}px`;
+      } else {
+        const parentRect = view.dom.parentElement?.getBoundingClientRect();
+        if (!parentRect) return;
+        toolbarEl.style.left = `${leftViewport - parentRect.left}px`;
+        toolbarEl.style.top = `${topViewport - parentRect.top}px`;
+      }
+    };
+
+    positionToolbar();
+    // Re-position after React commits, so the very first show uses real
+    // toolbar dimensions instead of the fallback estimate.
+    requestAnimationFrame(positionToolbar);
+  }
+
+  return new Plugin({
+    key: chatFloatingToolbarKey,
+    view(editorView) {
+      toolbarEl = document.createElement("div");
+      const portal = options?.getPortalContainer?.();
+      toolbarEl.className = [
+        `${portal ? "fixed" : "absolute"} z-50 flex items-center gap-x-0.5 rounded-md border border-border-primary`,
+        "bg-bg-primary px-1 py-1 shadow-lg",
+      ].join(" ");
+      toolbarEl.style.display = "none";
+      toolbarEl.setAttribute("role", "toolbar");
+      toolbarEl.setAttribute("aria-label", "Chat formatting (selection)");
+      toolbarEl.addEventListener("mousedown", (e) => e.preventDefault(), true);
+      (portal ?? editorView.dom.parentElement)?.appendChild(toolbarEl);
+      reactRoot = createRoot(toolbarEl);
+      return {
+        update: updateToolbar,
+        destroy() {
+          const root = reactRoot;
+          reactRoot = null;
+          toolbarEl?.remove();
+          toolbarEl = null;
+          if (root) {
+            queueMicrotask(() => root.unmount());
+          }
+        },
+      };
+    },
+  });
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/imageNodeView.ts b/packages/ui/spa/components/AIChatEditor/plugins/imageNodeView.ts
new file mode 100644
index 000000000..9ea9e6aed
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/imageNodeView.ts
@@ -0,0 +1,144 @@
+import type { EditorView, NodeView } from "prosemirror-view";
+import type { Node as PMNode } from "prosemirror-model";
+
+export function createChatImageNodeView() {
+  return function imageNodeView(
+    node: PMNode,
+    view: EditorView,
+    getPos: () => number | undefined,
+  ): NodeView {
+    const wrapper = document.createElement("span");
+    wrapper.className = "relative inline-block align-baseline mx-0.5";
+    wrapper.style.lineHeight = "0";
+    wrapper.contentEditable = "false";
+
+    const img = document.createElement("img");
+    img.style.maxHeight = "64px";
+    img.style.borderRadius = "4px";
+    img.style.border = "1px solid var(--border-primary, #ddd)";
+    img.style.display = "inline-block";
+    img.style.verticalAlign = "baseline";
+
+    const setImgAttrs = (n: PMNode) => {
+      img.src = (n.attrs.previewUrl as string | null) ?? "";
+      img.alt = (n.attrs.alt as string | null) ?? "";
+      img.setAttribute("data-val-ai-key", (n.attrs.key as string) ?? "");
+      const isPending = (n.attrs.key as string)?.startsWith("pending:");
+      wrapper.style.opacity = isPending ? "0.6" : "1";
+    };
+    setImgAttrs(node);
+
+    const removeBtn = document.createElement("button");
+    removeBtn.type = "button";
+    removeBtn.textContent = "×";
+    removeBtn.setAttribute("aria-label", "Remove image");
+    removeBtn.className =
+      "absolute -top-1 -right-1 rounded-full bg-bg-primary border border-border-primary text-fg-secondary hover:text-fg-primary w-4 h-4 leading-none text-xs flex items-center justify-center";
+    removeBtn.addEventListener("mousedown", (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const pos = getPos();
+      if (pos === undefined) return;
+      view.dispatch(view.state.tr.delete(pos, pos + node.nodeSize));
+      view.focus();
+    });
+
+    wrapper.appendChild(img);
+    wrapper.appendChild(removeBtn);
+
+    return {
+      dom: wrapper,
+      update(updated) {
+        if (updated.type !== node.type) return false;
+        setImgAttrs(updated);
+        return true;
+      },
+      stopEvent(e) {
+        return (e as Event).type === "mousedown";
+      },
+      ignoreMutation() {
+        return true;
+      },
+      // Note: we intentionally do NOT revoke the blob URL on destroy. Once the
+      // user sends the message, the URL is "transferred" to the user bubble in
+      // AIChat — clearing the editor must not invalidate it. Blob URLs are
+      // released when the page is reloaded.
+    };
+  };
+}
+
+/**
+ * Fetch a URL and wrap the response as a File so it can be uploaded via
+ * `insertImageWithUpload`. Used by the editor's paste/drop handlers when the
+ * payload is HTML containing an `<img src>` instead of a binary file.
+ * Returns null on CORS failures, non-2xx responses, or non-image content.
+ */
+export async function fetchUrlAsFile(
+  url: string,
+  fallbackName = "pasted-image",
+): Promise<File | null> {
+  try {
+    const res = await fetch(url, { credentials: "omit", mode: "cors" });
+    if (!res.ok) return null;
+    const blob = await res.blob();
+    if (!blob.type.startsWith("image/")) return null;
+    const ext = blob.type.split("/")[1] || "png";
+    return new File([blob], `${fallbackName}.${ext}`, { type: blob.type });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Insert an image node with a `pending:` key and trigger an upload. After the
+ * upload resolves, update the node attrs in place to carry the real key.
+ */
+export function insertImageWithUpload(
+  view: EditorView,
+  file: File,
+  uploadAiImage: (file: File) => Promise<{ key: string }>,
+): boolean {
+  const imageType = view.state.schema.nodes.image;
+  if (!imageType) return false;
+
+  const pendingKey = `pending:${crypto.randomUUID()}`;
+  const previewUrl = URL.createObjectURL(file);
+  const mimeType = file.type || "image/*";
+
+  const node = imageType.create({
+    key: pendingKey,
+    alt: "",
+    previewUrl,
+    mimeType,
+  });
+
+  const { from } = view.state.selection;
+  view.dispatch(view.state.tr.insert(from, node));
+
+  uploadAiImage(file)
+    .then(({ key }) => {
+      view.state.doc.descendants((n, pos) => {
+        if (n.type === imageType && n.attrs.key === pendingKey) {
+          const tr = view.state.tr.setNodeMarkup(pos, undefined, {
+            ...n.attrs,
+            key,
+          });
+          view.dispatch(tr);
+          return false;
+        }
+        return true;
+      });
+    })
+    .catch((err) => {
+      console.error("AI chat image upload failed", err);
+      view.state.doc.descendants((n, pos) => {
+        if (n.type === imageType && n.attrs.key === pendingKey) {
+          view.dispatch(view.state.tr.delete(pos, pos + n.nodeSize));
+          return false;
+        }
+        return true;
+      });
+    });
+
+  return true;
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/inputRules.ts b/packages/ui/spa/components/AIChatEditor/plugins/inputRules.ts
new file mode 100644
index 000000000..3f993b839
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/inputRules.ts
@@ -0,0 +1,53 @@
+import {
+  inputRules,
+  wrappingInputRule,
+  textblockTypeInputRule,
+  InputRule,
+} from "prosemirror-inputrules";
+import type { MarkType, Schema } from "prosemirror-model";
+import type { Plugin } from "prosemirror-state";
+
+function markingInputRule(regex: RegExp, markType: MarkType): InputRule {
+  return new InputRule(regex, (state, match, start, end) => {
+    const captured = match[1];
+    if (!captured) return null;
+    const tr = state.tr;
+    const startReplace = start;
+    const endReplace = end;
+    tr.replaceWith(
+      startReplace,
+      endReplace,
+      state.schema.text(captured, [markType.create()]),
+    );
+    tr.removeStoredMark(markType);
+    return tr;
+  });
+}
+
+export function buildChatInputRules(schema: Schema): Plugin {
+  const rules: InputRule[] = [];
+
+  rules.push(
+    textblockTypeInputRule(/^(#{1,3})\s$/, schema.nodes.heading, (match) => ({
+      level: match[1].length,
+    })),
+  );
+
+  rules.push(wrappingInputRule(/^\s*>\s$/, schema.nodes.blockquote));
+  rules.push(wrappingInputRule(/^\s*([-+*])\s$/, schema.nodes.bullet_list));
+  rules.push(
+    wrappingInputRule(
+      /^(\d+)\.\s$/,
+      schema.nodes.ordered_list,
+      (match) => ({ order: +match[1] }),
+      (match, node) => node.childCount + node.attrs.order === +match[1],
+    ),
+  );
+
+  rules.push(markingInputRule(/\*\*([^*]+)\*\*$/, schema.marks.bold));
+  rules.push(markingInputRule(/(?:^|[^*])\*([^*]+)\*$/, schema.marks.italic));
+  rules.push(markingInputRule(/~~([^~]+)~~$/, schema.marks.strikethrough));
+  rules.push(markingInputRule(/`([^`]+)`$/, schema.marks.code));
+
+  return inputRules({ rules });
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/keymap.ts b/packages/ui/spa/components/AIChatEditor/plugins/keymap.ts
new file mode 100644
index 000000000..393f37ed5
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/keymap.ts
@@ -0,0 +1,60 @@
+import { keymap } from "prosemirror-keymap";
+import {
+  baseKeymap,
+  toggleMark,
+  setBlockType,
+  wrapIn,
+} from "prosemirror-commands";
+import { undo, redo } from "prosemirror-history";
+import {
+  wrapInList,
+  splitListItem,
+  liftListItem,
+  sinkListItem,
+} from "prosemirror-schema-list";
+import type { Schema } from "prosemirror-model";
+import type {
+  Command,
+  Plugin,
+  EditorState,
+  Transaction,
+} from "prosemirror-state";
+
+export function buildChatKeymap(schema: Schema): Plugin[] {
+  const keys: Record<string, Command> = {};
+
+  keys["Mod-z"] = undo;
+  keys["Mod-y"] = redo;
+  keys["Mod-Shift-z"] = redo;
+
+  keys["Mod-b"] = toggleMark(schema.marks.bold);
+  keys["Mod-i"] = toggleMark(schema.marks.italic);
+  keys["Mod-Shift-x"] = toggleMark(schema.marks.strikethrough);
+  keys["Mod-e"] = toggleMark(schema.marks.code);
+
+  const br = schema.nodes.hard_break;
+  keys["Shift-Enter"] = (
+    state: EditorState,
+    dispatch?: (tr: Transaction) => void,
+  ) => {
+    if (dispatch) {
+      dispatch(state.tr.replaceSelectionWith(br.create()).scrollIntoView());
+    }
+    return true;
+  };
+
+  for (let i = 1; i <= 3; i++) {
+    keys[`Mod-Alt-${i}`] = setBlockType(schema.nodes.heading, { level: i });
+  }
+  keys["Mod-Alt-0"] = setBlockType(schema.nodes.paragraph);
+
+  keys["Mod-Shift-b"] = wrapIn(schema.nodes.blockquote);
+  keys["Mod-Shift-8"] = wrapInList(schema.nodes.bullet_list);
+  keys["Mod-Shift-9"] = wrapInList(schema.nodes.ordered_list);
+
+  keys["Enter"] = splitListItem(schema.nodes.list_item);
+  keys["Mod-["] = liftListItem(schema.nodes.list_item);
+  keys["Mod-]"] = sinkListItem(schema.nodes.list_item);
+
+  return [keymap(keys), keymap(baseKeymap)];
+}
diff --git a/packages/ui/spa/components/AIChatEditor/plugins/submitOnEnterPlugin.ts b/packages/ui/spa/components/AIChatEditor/plugins/submitOnEnterPlugin.ts
new file mode 100644
index 000000000..8e889e021
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/plugins/submitOnEnterPlugin.ts
@@ -0,0 +1,41 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import type { Schema } from "prosemirror-model";
+
+export const submitOnEnterKey = new PluginKey("submitOnEnter");
+
+export function createSubmitOnEnterPlugin(
+  schema: Schema,
+  onSubmit: () => void,
+): Plugin {
+  return new Plugin({
+    key: submitOnEnterKey,
+    props: {
+      handleKeyDown(view, event) {
+        if (event.key !== "Enter") return false;
+
+        // Cmd/Ctrl-Enter always submits.
+        if (event.metaKey || event.ctrlKey) {
+          event.preventDefault();
+          onSubmit();
+          return true;
+        }
+
+        // Shift-Enter → hard_break (handled by the keymap).
+        if (event.shiftKey) return false;
+
+        // Inside a list item, let splitListItem handle Enter.
+        const { $from } = view.state.selection;
+        for (let d = $from.depth; d > 0; d--) {
+          const nodeType = $from.node(d).type;
+          if (nodeType === schema.nodes.list_item) {
+            return false;
+          }
+        }
+
+        event.preventDefault();
+        onSubmit();
+        return true;
+      },
+    },
+  });
+}
diff --git a/packages/ui/spa/components/AIChatEditor/schema/buildChatSchema.ts b/packages/ui/spa/components/AIChatEditor/schema/buildChatSchema.ts
new file mode 100644
index 000000000..078e9f177
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/schema/buildChatSchema.ts
@@ -0,0 +1,215 @@
+import { Schema, type NodeSpec, type MarkSpec } from "prosemirror-model";
+
+function buildNodes(): Record<string, NodeSpec> {
+  const nodes: Record<string, NodeSpec> = {
+    doc: { content: "block+" },
+    paragraph: {
+      content: "inline*",
+      group: "block",
+      parseDOM: [
+        { tag: "p" },
+        // h4-h6 are unsupported in chat; downgrade to paragraph on paste.
+        { tag: "h4" },
+        { tag: "h5" },
+        { tag: "h6" },
+      ],
+      toDOM() {
+        return ["p", 0];
+      },
+    },
+    text: { group: "inline" },
+    hard_break: {
+      inline: true,
+      group: "inline",
+      selectable: false,
+      parseDOM: [{ tag: "br" }],
+      toDOM() {
+        return ["br"];
+      },
+    },
+    heading: {
+      attrs: { level: { default: 1 } },
+      content: "inline*",
+      group: "block",
+      defining: true,
+      parseDOM: [
+        { tag: "h1", attrs: { level: 1 } },
+        { tag: "h2", attrs: { level: 2 } },
+        { tag: "h3", attrs: { level: 3 } },
+      ],
+      toDOM(node) {
+        return [`h${node.attrs.level}`, 0];
+      },
+    },
+    blockquote: {
+      content: "block+",
+      group: "block",
+      defining: true,
+      parseDOM: [{ tag: "blockquote" }],
+      toDOM() {
+        return ["blockquote", 0];
+      },
+    },
+    list_item: {
+      content: "paragraph block*",
+      parseDOM: [{ tag: "li" }],
+      toDOM() {
+        return ["li", 0];
+      },
+      defining: true,
+    },
+    bullet_list: {
+      content: "list_item+",
+      group: "block",
+      parseDOM: [{ tag: "ul" }],
+      toDOM() {
+        return ["ul", 0];
+      },
+    },
+    ordered_list: {
+      attrs: { order: { default: 1 } },
+      content: "list_item+",
+      group: "block",
+      parseDOM: [
+        {
+          tag: "ol",
+          getAttrs(dom) {
+            const el = dom as HTMLElement;
+            return {
+              order: el.hasAttribute("start")
+                ? +(el.getAttribute("start") || 1)
+                : 1,
+            };
+          },
+        },
+      ],
+      toDOM(node) {
+        return node.attrs.order === 1
+          ? ["ol", 0]
+          : ["ol", { start: node.attrs.order }, 0];
+      },
+    },
+    image: {
+      inline: true,
+      atom: true,
+      attrs: {
+        key: { default: "" },
+        alt: { default: null },
+        previewUrl: { default: null },
+        width: { default: null },
+        height: { default: null },
+        mimeType: { default: null },
+      },
+      group: "inline",
+      draggable: true,
+      parseDOM: [
+        {
+          tag: "img[data-val-ai-key]",
+          getAttrs(dom) {
+            const el = dom as HTMLElement;
+            return {
+              key: el.getAttribute("data-val-ai-key") || "",
+              alt: el.getAttribute("alt"),
+              previewUrl: el.getAttribute("src"),
+            };
+          },
+        },
+      ],
+      toDOM(node) {
+        return [
+          "img",
+          {
+            src: node.attrs.previewUrl ?? "",
+            alt: node.attrs.alt ?? "",
+            "data-val-ai-key": node.attrs.key,
+          },
+        ];
+      },
+    },
+    field_ref: {
+      inline: true,
+      atom: true,
+      selectable: true,
+      draggable: false,
+      attrs: { path: { default: "" } },
+      group: "inline",
+      parseDOM: [
+        {
+          tag: "span[data-val-field-ref]",
+          getAttrs(dom) {
+            const el = dom as HTMLElement;
+            return { path: el.getAttribute("data-val-field-ref") || "" };
+          },
+        },
+      ],
+      toDOM(node) {
+        return [
+          "span",
+          {
+            "data-val-field-ref": node.attrs.path,
+            contenteditable: "false",
+            class:
+              "inline-flex items-center align-baseline rounded bg-bg-secondary text-fg-primary px-1.5 py-0.5 text-xs font-mono mx-0.5",
+          },
+          node.attrs.path,
+        ];
+      },
+    },
+  };
+  return nodes;
+}
+
+function buildMarks(): Record<string, MarkSpec> {
+  const marks: Record<string, MarkSpec> = {};
+
+  marks.bold = {
+    parseDOM: [
+      { tag: "strong" },
+      {
+        tag: "b",
+        getAttrs: (node) =>
+          (node as HTMLElement).style.fontWeight !== "normal" && null,
+      },
+      { style: "font-weight=bold" },
+      {
+        style: "font-weight",
+        getAttrs: (value) =>
+          /^(bold(er)?|[5-9]\d{2,})$/.test(value as string) && null,
+      },
+    ],
+    toDOM() {
+      return ["strong", 0];
+    },
+  };
+
+  marks.italic = {
+    parseDOM: [{ tag: "i" }, { tag: "em" }, { style: "font-style=italic" }],
+    toDOM() {
+      return ["em", 0];
+    },
+  };
+
+  marks.strikethrough = {
+    parseDOM: [
+      { tag: "s" },
+      { tag: "del" },
+      { style: "text-decoration=line-through" },
+    ],
+    toDOM() {
+      return ["del", 0];
+    },
+  };
+
+  marks.code = {
+    parseDOM: [{ tag: "code" }],
+    toDOM() {
+      return ["code", 0];
+    },
+  };
+
+  return marks;
+}
+
+export function buildChatSchema(): Schema {
+  return new Schema({ nodes: buildNodes(), marks: buildMarks() });
+}
diff --git a/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToHtmlText.ts b/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToHtmlText.ts
new file mode 100644
index 000000000..528b7a6a1
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToHtmlText.ts
@@ -0,0 +1,89 @@
+import type {
+  ChatDocument,
+  ChatBlockNode,
+  ChatInlineNode,
+  ChatListItemNode,
+  ChatNodeStyle,
+} from "../types";
+
+const STYLE_TAGS: Record<ChatNodeStyle, string> = {
+  bold: "strong",
+  italic: "em",
+  "line-through": "del",
+  code: "code",
+};
+
+function escapeText(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function writeInline(node: ChatInlineNode): string {
+  if (typeof node === "string") {
+    return escapeText(node);
+  }
+  if (node.tag === "br") {
+    return "<br/>";
+  }
+  if (node.tag === "span") {
+    const text = escapeText(node.children[0]);
+    const tags = node.styles
+      .map((s) => STYLE_TAGS[s])
+      .filter((t): t is string => !!t);
+    const open = tags.map((t) => `<${t}>`).join("");
+    const close = tags
+      .slice()
+      .reverse()
+      .map((t) => `</${t}>`)
+      .join("");
+    return `${open}${text}${close}`;
+  }
+  if (node.tag === "img") {
+    const altPart =
+      node.alt !== undefined ? ` alt="${escapeAttr(node.alt)}"` : "";
+    return `<img key="${escapeAttr(node.key)}"${altPart}/>`;
+  }
+  if (node.tag === "field_ref") {
+    return `<field path="${escapeAttr(node.path)}"/>`;
+  }
+  return "";
+}
+
+function writeInlineContent(children: ChatInlineNode[]): string {
+  return children.map(writeInline).join("");
+}
+
+function writeListItem(item: ChatListItemNode): string {
+  return `<li>${item.children.map(writeBlock).join("")}</li>`;
+}
+
+function writeBlock(node: ChatBlockNode): string {
+  switch (node.tag) {
+    case "p":
+      return `<p>${writeInlineContent(node.children)}</p>`;
+    case "h1":
+    case "h2":
+    case "h3":
+      return `<${node.tag}>${writeInlineContent(node.children)}</${node.tag}>`;
+    case "ul":
+      return `<ul>${node.children.map(writeListItem).join("")}</ul>`;
+    case "ol":
+      return `<ol>${node.children.map(writeListItem).join("")}</ol>`;
+    case "blockquote":
+      return `<blockquote>${node.children.map(writeBlock).join("")}</blockquote>`;
+  }
+}
+
+export function chatDocumentToHtmlText(doc: ChatDocument): string {
+  return doc.map(writeBlock).join("\n");
+}
diff --git a/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToPlainText.ts b/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToPlainText.ts
new file mode 100644
index 000000000..7bd0c0a3f
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/serialize/chatDocumentToPlainText.ts
@@ -0,0 +1,84 @@
+import { Internal, type SourcePath } from "@valbuild/core";
+import type {
+  ChatDocument,
+  ChatBlockNode,
+  ChatInlineNode,
+  ChatListItemNode,
+} from "../types";
+
+function prettifyPath(path: SourcePath): string {
+  try {
+    const [moduleFilePath, modulePath] =
+      Internal.splitModuleFilePathAndModulePath(path);
+    const modulePathParts = Internal.splitModulePath(modulePath);
+    if (modulePathParts.length === 0) return moduleFilePath;
+    return `${moduleFilePath}#${modulePathParts.join("/")}`;
+  } catch {
+    return path;
+  }
+}
+
+function inlineToText(node: ChatInlineNode): string {
+  if (typeof node === "string") return node;
+  if (node.tag === "br") return "\n";
+  if (node.tag === "span") return node.children[0];
+  if (node.tag === "img") return node.alt ? `[image: ${node.alt}]` : "[image]";
+  if (node.tag === "field_ref") return `@${prettifyPath(node.path)}`;
+  return "";
+}
+
+function inlineContentToText(children: ChatInlineNode[]): string {
+  return children.map(inlineToText).join("");
+}
+
+function listItemToText(
+  item: ChatListItemNode,
+  marker: string,
+  indent: string,
+): string {
+  const lines: string[] = [];
+  let isFirstParagraph = true;
+  for (const child of item.children) {
+    if (child.tag === "p") {
+      const prefix = isFirstParagraph ? `${indent}${marker} ` : `${indent}  `;
+      lines.push(`${prefix}${inlineContentToText(child.children)}`);
+      isFirstParagraph = false;
+    } else if (child.tag === "ul") {
+      for (const nested of child.children) {
+        lines.push(listItemToText(nested, "-", `${indent}  `));
+      }
+    } else if (child.tag === "ol") {
+      let i = 0;
+      for (const nested of child.children) {
+        lines.push(listItemToText(nested, `${i + 1}.`, `${indent}  `));
+        i += 1;
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+function blockToText(block: ChatBlockNode): string {
+  switch (block.tag) {
+    case "p":
+      return inlineContentToText(block.children);
+    case "h1":
+    case "h2":
+    case "h3":
+      return inlineContentToText(block.children);
+    case "blockquote":
+      return block.children.map(blockToText).join("\n");
+    case "ul":
+      return block.children
+        .map((item) => listItemToText(item, "-", ""))
+        .join("\n");
+    case "ol":
+      return block.children
+        .map((item, i) => listItemToText(item, `${i + 1}.`, ""))
+        .join("\n");
+  }
+}
+
+export function chatDocumentToPlainText(doc: ChatDocument): string {
+  return doc.map(blockToText).join("\n\n");
+}
diff --git a/packages/ui/spa/components/AIChatEditor/serialize/collectImageKeysFromDoc.ts b/packages/ui/spa/components/AIChatEditor/serialize/collectImageKeysFromDoc.ts
new file mode 100644
index 000000000..25a906b1a
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/serialize/collectImageKeysFromDoc.ts
@@ -0,0 +1,46 @@
+import type {
+  ChatBlockNode,
+  ChatDocument,
+  ChatImageNode,
+  ChatInlineNode,
+  ChatListItemNode,
+} from "../types";
+
+function visitInline(node: ChatInlineNode, out: ChatImageNode[]): void {
+  if (typeof node === "string") return;
+  if (node.tag === "img") {
+    out.push(node);
+  }
+}
+
+function visitListItem(item: ChatListItemNode, out: ChatImageNode[]): void {
+  for (const child of item.children) visitBlock(child, out);
+}
+
+function visitBlock(block: ChatBlockNode, out: ChatImageNode[]): void {
+  switch (block.tag) {
+    case "p":
+    case "h1":
+    case "h2":
+    case "h3":
+      for (const child of block.children) visitInline(child, out);
+      return;
+    case "ul":
+    case "ol":
+      for (const item of block.children) visitListItem(item, out);
+      return;
+    case "blockquote":
+      for (const child of block.children) visitBlock(child, out);
+      return;
+  }
+}
+
+export function collectImageNodesFromDoc(doc: ChatDocument): ChatImageNode[] {
+  const out: ChatImageNode[] = [];
+  for (const block of doc) visitBlock(block, out);
+  return out;
+}
+
+export function collectImageKeysFromDoc(doc: ChatDocument): string[] {
+  return collectImageNodesFromDoc(doc).map((n) => n.key);
+}
diff --git a/packages/ui/spa/components/AIChatEditor/serialize/parseChatDocument.ts b/packages/ui/spa/components/AIChatEditor/serialize/parseChatDocument.ts
new file mode 100644
index 000000000..cc5a6e8a6
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/serialize/parseChatDocument.ts
@@ -0,0 +1,116 @@
+import type { Node as PMNode, Mark, Schema } from "prosemirror-model";
+import type {
+  ChatDocument,
+  ChatBlockNode,
+  ChatInlineNode,
+  ChatListItemNode,
+  ChatNodeStyle,
+} from "../types";
+
+const STYLE_TO_MARK: Record<ChatNodeStyle, string> = {
+  bold: "bold",
+  italic: "italic",
+  "line-through": "strikethrough",
+  code: "code",
+};
+
+function styleToMark(style: ChatNodeStyle, schema: Schema): Mark | null {
+  const name = STYLE_TO_MARK[style];
+  const markType = name ? schema.marks[name] : undefined;
+  return markType ? markType.create() : null;
+}
+
+export function parseChatDocument(doc: ChatDocument, schema: Schema): PMNode {
+  const blocks = doc.map((block) => parseBlockNode(block, schema));
+  if (blocks.length === 0) {
+    blocks.push(schema.node("paragraph"));
+  }
+  return schema.node("doc", null, blocks);
+}
+
+function parseBlockNode(node: ChatBlockNode, schema: Schema): PMNode {
+  switch (node.tag) {
+    case "p":
+      return schema.node(
+        "paragraph",
+        null,
+        parseInlineNodes(node.children, schema),
+      );
+    case "h1":
+    case "h2":
+    case "h3": {
+      const level = parseInt(node.tag[1], 10);
+      return schema.node(
+        "heading",
+        { level },
+        parseInlineNodes(node.children, schema),
+      );
+    }
+    case "ul":
+      return schema.node(
+        "bullet_list",
+        null,
+        node.children.map((li) => parseListItem(li, schema)),
+      );
+    case "ol":
+      return schema.node(
+        "ordered_list",
+        null,
+        node.children.map((li) => parseListItem(li, schema)),
+      );
+    case "blockquote":
+      return schema.node(
+        "blockquote",
+        null,
+        node.children.map((child) => parseBlockNode(child, schema)),
+      );
+  }
+}
+
+function parseListItem(item: ChatListItemNode, schema: Schema): PMNode {
+  const children = item.children.map((child) => parseBlockNode(child, schema));
+  return schema.node("list_item", null, children);
+}
+
+function parseInlineNodes(
+  children: ChatInlineNode[],
+  schema: Schema,
+): PMNode[] {
+  const result: PMNode[] = [];
+  for (const child of children) {
+    if (typeof child === "string") {
+      if (child.length > 0) {
+        result.push(schema.text(child));
+      }
+    } else if (child.tag === "br") {
+      if (schema.nodes.hard_break) {
+        result.push(schema.node("hard_break"));
+      }
+    } else if (child.tag === "span") {
+      const marks = child.styles
+        .map((style) => styleToMark(style, schema))
+        .filter((m): m is NonNullable<typeof m> => m !== null);
+      if (child.children[0].length > 0) {
+        result.push(schema.text(child.children[0], marks));
+      }
+    } else if (child.tag === "img") {
+      if (schema.nodes.image) {
+        result.push(
+          schema.node("image", {
+            key: child.key,
+            alt: child.alt ?? null,
+            previewUrl: child.previewUrl ?? null,
+            width: child.width ?? null,
+            height: child.height ?? null,
+            mimeType: child.mimeType ?? null,
+          }),
+        );
+      }
+    } else if (child.tag === "field_ref") {
+      if (schema.nodes.field_ref) {
+        result.push(schema.node("field_ref", { path: child.path }));
+      }
+    }
+  }
+  return result;
+}
diff --git a/packages/ui/spa/components/AIChatEditor/serialize/serializeChatDocument.ts b/packages/ui/spa/components/AIChatEditor/serialize/serializeChatDocument.ts
new file mode 100644
index 000000000..786fb5b8c
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/serialize/serializeChatDocument.ts
@@ -0,0 +1,123 @@
+import type { Node as PMNode, Mark } from "prosemirror-model";
+import type { SourcePath } from "@valbuild/core";
+import type {
+  ChatDocument,
+  ChatBlockNode,
+  ChatInlineNode,
+  ChatListItemNode,
+  ChatNodeStyle,
+  ChatImageNode,
+} from "../types";
+
+export function serializeChatDocument(doc: PMNode): ChatDocument {
+  const blocks: ChatBlockNode[] = [];
+  doc.forEach((child) => {
+    const block = serializeBlockNode(child);
+    if (block) blocks.push(block);
+  });
+  return blocks;
+}
+
+function serializeBlockNode(node: PMNode): ChatBlockNode | null {
+  switch (node.type.name) {
+    case "paragraph":
+      return { tag: "p", children: serializeInlineContent(node) };
+    case "heading": {
+      const level = Math.min(3, Math.max(1, node.attrs.level as number));
+      return {
+        tag: `h${level}` as "h1" | "h2" | "h3",
+        children: serializeInlineContent(node),
+      };
+    }
+    case "bullet_list":
+      return { tag: "ul", children: serializeListItems(node) };
+    case "ordered_list":
+      return { tag: "ol", children: serializeListItems(node) };
+    case "blockquote": {
+      const children: ChatBlockNode[] = [];
+      node.forEach((child) => {
+        const block = serializeBlockNode(child);
+        if (block) children.push(block);
+      });
+      return { tag: "blockquote", children };
+    }
+    default:
+      return null;
+  }
+}
+
+function serializeListItems(node: PMNode): ChatListItemNode[] {
+  const items: ChatListItemNode[] = [];
+  node.forEach((child) => {
+    if (child.type.name === "list_item") {
+      const children: ChatBlockNode[] = [];
+      child.forEach((liChild) => {
+        const block = serializeBlockNode(liChild);
+        if (block) children.push(block);
+      });
+      items.push({
+        tag: "li",
+        children: children as ChatListItemNode["children"],
+      });
+    }
+  });
+  return items;
+}
+
+function serializeInlineContent(node: PMNode): ChatInlineNode[] {
+  const result: ChatInlineNode[] = [];
+  node.forEach((child) => {
+    if (child.isText) {
+      const text = child.text || "";
+      const styles = marksToStyles(child.marks);
+      if (styles.length === 0) {
+        result.push(text);
+      } else {
+        result.push({ tag: "span", styles, children: [text] });
+      }
+    } else if (child.type.name === "hard_break") {
+      result.push({ tag: "br" });
+    } else if (child.type.name === "image") {
+      const key = child.attrs.key as string;
+      const width = child.attrs.width as number | null;
+      const height = child.attrs.height as number | null;
+      const mimeType = child.attrs.mimeType as string | null;
+      const previewUrl = child.attrs.previewUrl as string | null;
+      const alt = child.attrs.alt as string | null;
+      const img: ChatImageNode = { tag: "img", key };
+      if (alt) img.alt = alt;
+      if (previewUrl) img.previewUrl = previewUrl;
+      if (width !== null) img.width = width;
+      if (height !== null) img.height = height;
+      if (mimeType !== null) img.mimeType = mimeType;
+      result.push(img);
+    } else if (child.type.name === "field_ref") {
+      result.push({
+        tag: "field_ref",
+        path: child.attrs.path as SourcePath,
+      });
+    }
+  });
+  return result;
+}
+
+function marksToStyles(marks: readonly Mark[]): ChatNodeStyle[] {
+  const styles: ChatNodeStyle[] = [];
+  for (const mark of marks) {
+    switch (mark.type.name) {
+      case "bold":
+        styles.push("bold");
+        break;
+      case "italic":
+        styles.push("italic");
+        break;
+      case "strikethrough":
+        styles.push("line-through");
+        break;
+      case "code":
+        styles.push("code");
+        break;
+    }
+  }
+  return styles;
+}
diff --git a/packages/ui/spa/components/AIChatEditor/types.ts b/packages/ui/spa/components/AIChatEditor/types.ts
new file mode 100644
index 000000000..1b56fe3fc
--- /dev/null
+++ b/packages/ui/spa/components/AIChatEditor/types.ts
@@ -0,0 +1,85 @@
+import type { SourcePath } from "@valbuild/core";
+
+export type ChatNodeStyle = "bold" | "italic" | "line-through" | "code";
+
+export interface ChatSpanNode {
+  tag: "span";
+  styles: ChatNodeStyle[];
+  children: [string];
+}
+
+export interface ChatBrNode {
+  tag: "br";
+}
+
+export interface ChatImageNode {
+  tag: "img";
+  key: string;
+  alt?: string;
+  previewUrl?: string;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+}
+
+export interface ChatFieldRefNode {
+  tag: "field_ref";
+  path: SourcePath;
+}
+
+export type ChatInlineNode =
+  | string
+  | ChatSpanNode
+  | ChatBrNode
+  | ChatImageNode
+  | ChatFieldRefNode;
+
+export interface ChatParagraphNode {
+  tag: "p";
+  children: ChatInlineNode[];
+}
+
+export interface ChatHeadingNode {
+  tag: "h1" | "h2" | "h3";
+  children: ChatInlineNode[];
+}
+
+export interface ChatListItemNode {
+  tag: "li";
+  children: (ChatParagraphNode | ChatBulletListNode | ChatOrderedListNode)[];
+}
+
+export interface ChatBulletListNode {
+  tag: "ul";
+  children: ChatListItemNode[];
+}
+
+export interface ChatOrderedListNode {
+  tag: "ol";
+  children: ChatListItemNode[];
+}
+
+export interface ChatBlockquoteNode {
+  tag: "blockquote";
+  children: ChatBlockNode[];
+}
+
+export type ChatBlockNode =
+  | ChatParagraphNode
+  | ChatHeadingNode
+  | ChatBulletListNode
+  | ChatOrderedListNode
+  | ChatBlockquoteNode;
+
+export type ChatDocument = ChatBlockNode[];
+
+export const EMPTY_CHAT_DOCUMENT: ChatDocument = [];
+
+export interface ChatEditorRef {
+  getDocument(): ChatDocument;
+  setDocument(doc: ChatDocument): void;
+  clear(): void;
+  focus(): void;
+  isEmpty(): boolean;
+  insertFieldRef(path: SourcePath): void;
+}
diff --git a/packages/ui/spa/components/Field.tsx b/packages/ui/spa/components/Field.tsx
index 1a26e34f3..6cfa9ec00 100644
--- a/packages/ui/spa/components/Field.tsx
+++ b/packages/ui/spa/components/Field.tsx
@@ -2,7 +2,7 @@ import { Json, SerializedSchema, SourcePath } from "@valbuild/core";
 import { Label } from "./Label";
 import { fromCamelToTitleCase } from "../utils/prettifyText";
 import classNames from "classnames";
-import { ChevronDown, ChevronsDown } from "lucide-react";
+import { ChevronDown, ChevronsDown, Plus, Sparkles } from "lucide-react";
 import { Checkbox } from "./designSystem/checkbox";
 import { JSONValue } from "@valbuild/core/patch";
 import { ArrayAndRecordTools } from "./ArrayAndRecordTools";
@@ -16,6 +16,7 @@ import {
 import { FieldValidationError } from "./FieldValidationError";
 import { FieldPatchAuthorsSection } from "./FieldPatchAuthorsSection";
 import { ShallowSource, useAllSources, useSchemas } from "./ValFieldProvider";
+import { useAIChatActions, useInsertFieldRef } from "./AIChatActionsContext";
 import { useFieldState } from "./useFieldState";
 import { useNavigation } from "./ValRouter";
 import { getNavPathFromAll } from "./getNavPath";
@@ -77,6 +78,8 @@ export function Field({
   const { navigate } = useNavigation();
   const schemas = useSchemas();
   const allSources = useAllSources();
+  const { isAIChatEnabled } = useAIChatActions();
+  const insertFieldRef = useInsertFieldRef();
   const handleLabelNavigate = () => {
     const schemasData = schemas.status === "success" ? schemas.data : undefined;
     const navPath = getNavPathFromAll(path, allSources, schemasData);
@@ -194,6 +197,25 @@ export function Field({
           {!hasOverrides && !compact && (
             <FieldPatchAuthorsSection path={path} />
           )}
+          {!hasOverrides && isAIChatEnabled && (
+            <button
+              type="button"
+              onClick={() => insertFieldRef(path)}
+              title="Mention this field in AI chat"
+              aria-label="Mention this field in AI chat"
+              className={classNames(
+                "flex items-center justify-center rounded text-fg-secondary hover:text-fg-primary hover:bg-bg-secondary",
+                {
+                  "size-6": !compact,
+                  "size-5": compact,
+                  invisible: effectiveReadonly,
+                },
+              )}
+            >
+              <Sparkles size={compact ? 9 : 10} />
+              <Plus size={compact ? 7 : 8} className="-ml-0.5" />
+            </button>
+          )}
           {!hasOverrides && source !== null && (
             <div className={classNames({ invisible: effectiveReadonly })}>
               <ArrayAndRecordTools path={path} variant={"field"} />
diff --git a/packages/ui/spa/components/ToolsMenu.tsx b/packages/ui/spa/components/ToolsMenu.tsx
index 009e9d93e..20b9c3f70 100644
--- a/packages/ui/spa/components/ToolsMenu.tsx
+++ b/packages/ui/spa/components/ToolsMenu.tsx
@@ -24,15 +24,16 @@ import {
   PanelsTopLeft,
 } from "lucide-react";
 import { Button } from "./designSystem/button";
-import { urlOf } from "@valbuild/shared/internal";
-import { Fragment, useMemo, useRef, useState } from "react";
+import { urlOf, VAL_AI_SESSION_STORAGE_KEY } from "@valbuild/shared/internal";
+import { Fragment, useEffect, useMemo, useRef, useState } from "react";
 import { cn } from "./designSystem/cn";
 import { AIChat } from "./AIChat";
 import type { AIChatHandle } from "./AIChat";
 import { useAI } from "../hooks/useAI";
+import { useAIChatActions } from "./AIChatActionsContext";
 import { Internal, ModuleFilePath, SourcePath } from "@valbuild/core";
 import { prettifyFilename } from "../utils/prettifyFilename";
-import { useNavigation, VAL_ERRORS_ROUTE } from "./ValRouter";
+import { useNavigation, useSessionParam, VAL_ERRORS_ROUTE } from "./ValRouter";
 import { PublishButton } from "./PublishButton";
 import { Checkbox } from "./designSystem/checkbox";
 import {
@@ -49,6 +50,19 @@ export function ToolsMenu() {
   const mode = useValMode();
   const config = useValConfig();
   const isChatEnabled = config?.ai?.chat?.experimental?.enable === true;
+  const { chatEditorRef, setOpenAIChatImpl } = useAIChatActions();
+  const chatPanelRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!isChatEnabled) return;
+    const open = () => {
+      chatPanelRef.current?.scrollIntoView({
+        behavior: "smooth",
+        block: "end",
+      });
+    };
+    setOpenAIChatImpl(open);
+    return () => setOpenAIChatImpl(null);
+  }, [isChatEnabled, setOpenAIChatImpl]);
   const [errorModules, fieldsWithErrors, errorPaths] = useMemo(() => {
     const modulesWithErrors = new Set<ModuleFilePath>();
     const errorPaths: SourcePath[] = [];
@@ -67,6 +81,10 @@ export function ToolsMenu() {
   const committedPatchIds = useCommittedPatches();
   const pendingChanges = currentPatchIds.length - committedPatchIds.size;
   const chatRef = useRef<AIChatHandle | null>(null);
+  const { sessionParam, setSessionParam } = useSessionParam();
+  // Capture the URL session id once on first render — later URL changes (e.g.
+  // navigations that re-write the URL) must not retrigger session loading.
+  const initialSessionIdRef = useRef(sessionParam);
   const {
     sendMessage,
     uploadAiImage,
@@ -78,7 +96,26 @@ export function ToolsMenu() {
     getSessions,
     setSessionName,
     loadSession,
-  } = useAI(chatRef);
+    isLoadingSession,
+  } = useAI(chatRef, {
+    initialSessionId: initialSessionIdRef.current,
+    onSessionBorn: (id) => {
+      setSessionParam(id, { replace: true });
+      try {
+        sessionStorage.setItem(VAL_AI_SESSION_STORAGE_KEY, id);
+      } catch {
+        // sessionStorage may be disabled — URL remains the source of truth.
+      }
+    },
+    onSessionCleared: () => {
+      setSessionParam(null, { replace: true });
+      try {
+        sessionStorage.removeItem(VAL_AI_SESSION_STORAGE_KEY);
+      } catch {
+        // see above
+      }
+    },
+  });
   return (
     <div
       className="flex flex-col h-[100svh] bg-bg-primary"
@@ -146,9 +183,13 @@ export function ToolsMenu() {
         </div>
       </div>
       {(mode === "http" || mode === "fs") && isChatEnabled && (
-        <div className="flex-1 min-h-0 border-t border-border-primary">
+        <div
+          ref={chatPanelRef}
+          className="flex-1 min-h-0 border-t border-border-primary"
+        >
           <AIChat
             ref={chatRef}
+            chatEditorRef={chatEditorRef}
             onSendMessage={sendMessage}
             onUploadFile={uploadAiImage}
             onNewSession={newSession}
@@ -160,6 +201,7 @@ export function ToolsMenu() {
             onLoadSession={loadSession}
             onFetchSessions={getSessions}
             onSetSessionName={setSessionName}
+            isLoadingSession={isLoadingSession}
           />
         </div>
       )}
diff --git a/packages/ui/spa/components/ValOverlay.tsx b/packages/ui/spa/components/ValOverlay.tsx
index 1bdfd56d5..6e1b809f3 100644
--- a/packages/ui/spa/components/ValOverlay.tsx
+++ b/packages/ui/spa/components/ValOverlay.tsx
@@ -20,6 +20,9 @@ import {
 import React, {
   Dispatch,
   SetStateAction,
+  createContext,
+  useCallback,
+  useContext,
   useEffect,
   useMemo,
   useRef,
@@ -45,7 +48,7 @@ import { useSchemaAtPath, useValConfig, useSchemas } from "./ValFieldProvider";
 import { useTheme } from "./ValThemeProvider";
 import { useValPortal } from "./ValPortalProvider";
 import { FieldLoading } from "./FieldLoading";
-import { urlOf } from "@valbuild/shared/internal";
+import { urlOf, VAL_AI_SESSION_STORAGE_KEY } from "@valbuild/shared/internal";
 import { Popover, PopoverContent } from "./designSystem/popover";
 import { PopoverTrigger } from "@radix-ui/react-popover";
 import { Switch } from "./designSystem/switch";
@@ -68,6 +71,7 @@ import { HoverCardArrow } from "@radix-ui/react-hover-card";
 import { AIChat } from "./AIChat";
 import type { AIChatHandle } from "./AIChat";
 import { useAI } from "../hooks/useAI";
+import { useAIChatActions } from "./AIChatActionsContext";
 
 export type ValOverlayProps = {
   draftMode: boolean;
@@ -76,6 +80,23 @@ export type ValOverlayProps = {
   disableOverlay: () => void;
 };
 
+/**
+ * Holds the overlay's "born" AI chat session id so that the studio-link
+ * sites (top menu, WindowField) can append `?session=` to their hrefs.
+ * Null until the user has actually used the chat (sent a message or
+ * uploaded an attachment) — matches the unborn/born model in useAI.
+ */
+const OverlaySessionContext = createContext<{
+  bornSessionId: string | null;
+  setBornSessionId: (id: string | null) => void;
+}>({ bornSessionId: null, setBornSessionId: () => {} });
+
+function appendSessionParam(base: string, sid: string | null): string {
+  if (!sid) return base;
+  const sep = base.includes("?") ? "&" : "?";
+  return `${base}${sep}session=${encodeURIComponent(sid)}`;
+}
+
 type ValMenuProps = ValOverlayProps & {
   setMode: Dispatch<SetStateAction<OverlayModes>>;
   mode: OverlayModes;
@@ -151,6 +172,26 @@ export function ValOverlay(props: ValOverlayProps) {
     }>
   >([]);
   const [isChatOpen, setIsChatOpen] = useState(false);
+  // The overlay's "born" chat session id is mirrored to sessionStorage so it
+  // survives a host page reload and so other consumers (e.g. studio links
+  // generated from inside the overlay) keep working after reload.
+  const [bornSessionId, setBornSessionIdState] = useState<string | null>(() => {
+    try {
+      return sessionStorage.getItem(VAL_AI_SESSION_STORAGE_KEY);
+    } catch {
+      return null;
+    }
+  });
+  const setBornSessionId = useCallback((id: string | null) => {
+    setBornSessionIdState(id);
+    try {
+      if (id == null) sessionStorage.removeItem(VAL_AI_SESSION_STORAGE_KEY);
+      else sessionStorage.setItem(VAL_AI_SESSION_STORAGE_KEY, id);
+    } catch {
+      // sessionStorage may be disabled (private mode, quota) — fall back to
+      // React-state-only behavior.
+    }
+  }, []);
   useEffect(() => {
     if (!props.draftMode) {
       setMode(null);
@@ -341,67 +382,31 @@ export function ValOverlay(props: ValOverlayProps) {
   };
 
   return (
-    <div {...(theme ? { "data-mode": theme } : {})} id="val-overlay-container">
-      <Window editMode={editMode} setMode={setMode} setEditMode={setEditMode} />
-      {boundingBox && (
-        <div
-          className={cn(
-            "absolute z-[8998]",
-            "cursor-pointer",
-            "rounded-sm",
-            "transition-all duration-150 ease-in-out",
-            "border-2 border-bg-brand-primary hover:border-bg-brand-primary-hover",
-          )}
-          style={maxRect(
-            {
-              top: boundingBox.top,
-              left: boundingBox.left,
-              width: boundingBox.width,
-              height: boundingBox.height,
-            },
-            {
-              top: window.scrollY,
-              left: window.scrollX,
-              width: window.innerWidth,
-              height: window.innerHeight,
-            },
-            2,
-          )}
-          onClick={(ev) => {
-            ev.preventDefault();
-            ev.stopPropagation();
-            setBoundingBox(null);
-            setEditMode({
-              joinedPaths: boundingBox.joinedPaths,
-              clientX: boundingBox.left,
-              clientY: boundingBox.top,
-              boundingBox: {
-                top: boundingBox.top,
-                left: boundingBox.left,
-                width: boundingBox.width,
-                height: boundingBox.height,
-              },
-            });
-          }}
-        ></div>
-      )}
-      {showAllBoundingBoxes &&
-        allBoundingBoxes.map((box, index) => (
+    <OverlaySessionContext.Provider value={{ bornSessionId, setBornSessionId }}>
+      <div
+        {...(theme ? { "data-mode": theme } : {})}
+        id="val-overlay-container"
+      >
+        <Window
+          editMode={editMode}
+          setMode={setMode}
+          setEditMode={setEditMode}
+        />
+        {boundingBox && (
           <div
-            key={`${box.joinedPaths}-${index}`}
             className={cn(
-              "absolute z-[8997] pointer-events-none",
+              "absolute z-[8998]",
+              "cursor-pointer",
               "rounded-sm",
-              "border-2 border-bg-brand-primary",
-              "transition-opacity duration-200 ease-out",
-              allBoundingBoxesVisible ? "opacity-50" : "opacity-0",
+              "transition-all duration-150 ease-in-out",
+              "border-2 border-bg-brand-primary hover:border-bg-brand-primary-hover",
             )}
             style={maxRect(
               {
-                top: box.top,
-                left: box.left,
-                width: box.width,
-                height: box.height,
+                top: boundingBox.top,
+                left: boundingBox.left,
+                width: boundingBox.width,
+                height: boundingBox.height,
               },
               {
                 top: window.scrollY,
@@ -411,29 +416,75 @@ export function ValOverlay(props: ValOverlayProps) {
               },
               2,
             )}
-          />
-        ))}
-      <ChatWindow
-        isOpen={isChatOpen && props.draftMode}
-        onClose={() => setIsChatOpen(false)}
-      />
-      {editMode === null && (
-        <DraggableValMenu
-          {...props}
-          mode={mode}
-          setMode={setMode}
-          loading={theme === null}
-          dropZone={dropZone}
-          setDropZone={setDropZone}
-          findAllValPathElements={findAllValPathElements}
-          setAllBoundingBoxes={setAllBoundingBoxes}
-          setShowAllBoundingBoxes={setShowAllBoundingBoxes}
-          setAllBoundingBoxesVisible={setAllBoundingBoxesVisible}
-          isChatOpen={isChatOpen}
-          setIsChatOpen={setIsChatOpen}
+            onClick={(ev) => {
+              ev.preventDefault();
+              ev.stopPropagation();
+              setBoundingBox(null);
+              setEditMode({
+                joinedPaths: boundingBox.joinedPaths,
+                clientX: boundingBox.left,
+                clientY: boundingBox.top,
+                boundingBox: {
+                  top: boundingBox.top,
+                  left: boundingBox.left,
+                  width: boundingBox.width,
+                  height: boundingBox.height,
+                },
+              });
+            }}
+          ></div>
+        )}
+        {showAllBoundingBoxes &&
+          allBoundingBoxes.map((box, index) => (
+            <div
+              key={`${box.joinedPaths}-${index}`}
+              className={cn(
+                "absolute z-[8997] pointer-events-none",
+                "rounded-sm",
+                "border-2 border-bg-brand-primary",
+                "transition-opacity duration-200 ease-out",
+                allBoundingBoxesVisible ? "opacity-50" : "opacity-0",
+              )}
+              style={maxRect(
+                {
+                  top: box.top,
+                  left: box.left,
+                  width: box.width,
+                  height: box.height,
+                },
+                {
+                  top: window.scrollY,
+                  left: window.scrollX,
+                  width: window.innerWidth,
+                  height: window.innerHeight,
+                },
+                2,
+              )}
+            />
+          ))}
+        <ChatWindow
+          isOpen={isChatOpen && props.draftMode}
+          onClose={() => setIsChatOpen(false)}
+          onOpen={() => setIsChatOpen(true)}
         />
-      )}
-    </div>
+        {editMode === null && (
+          <DraggableValMenu
+            {...props}
+            mode={mode}
+            setMode={setMode}
+            loading={theme === null}
+            dropZone={dropZone}
+            setDropZone={setDropZone}
+            findAllValPathElements={findAllValPathElements}
+            setAllBoundingBoxes={setAllBoundingBoxes}
+            setShowAllBoundingBoxes={setShowAllBoundingBoxes}
+            setAllBoundingBoxesVisible={setAllBoundingBoxesVisible}
+            isChatOpen={isChatOpen}
+            setIsChatOpen={setIsChatOpen}
+          />
+        )}
+      </div>
+    </OverlaySessionContext.Provider>
   );
 }
 
@@ -446,6 +497,7 @@ function Window({
   setMode: Dispatch<SetStateAction<OverlayModes>>;
   setEditMode: Dispatch<SetStateAction<EditMode | null>>;
 }) {
+  const { bornSessionId } = useContext(OverlaySessionContext);
   // place outside viewport initially
   const [windowPos, setWindowPos] = useState({
     x: window.innerWidth,
@@ -757,11 +809,14 @@ function Window({
                 Internal.splitJoinedSourcePaths(editMode.joinedPaths).length ===
                   1 && (
                   <a
-                    href={
+                    href={appendSessionParam(
                       window.origin +
-                      "/val/~" +
-                      Internal.splitJoinedSourcePaths(editMode.joinedPaths)[0]
-                    }
+                        "/val/~" +
+                        Internal.splitJoinedSourcePaths(
+                          editMode.joinedPaths,
+                        )[0],
+                      bornSessionId,
+                    )}
                     className="inline-flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-md border border-border-primary bg-bg-secondary hover:bg-bg-secondary-hover text-fg-primary transition-colors"
                   >
                     <ExternalLink size={16} />
@@ -827,11 +882,24 @@ function Window({
 function ChatWindow({
   isOpen,
   onClose,
+  onOpen,
 }: {
   isOpen: boolean;
   onClose: () => void;
+  onOpen: () => void;
 }) {
   const chatRef = useRef<AIChatHandle | null>(null);
+  const { chatEditorRef, setOpenAIChatImpl } = useAIChatActions();
+  useEffect(() => {
+    setOpenAIChatImpl(onOpen);
+    return () => setOpenAIChatImpl(null);
+  }, [onOpen, setOpenAIChatImpl]);
+  const { bornSessionId, setBornSessionId } = useContext(OverlaySessionContext);
+  // Capture the seeded-from-sessionStorage value once so later state changes
+  // don't re-trigger useAI's mount-load effect. This is how a user coming
+  // back from the studio (with an active session) sees the chat rehydrate
+  // in the overlay.
+  const initialBornSessionIdRef = useRef(bornSessionId);
   const {
     sendMessage,
     uploadAiImage,
@@ -843,7 +911,12 @@ function ChatWindow({
     getSessions,
     setSessionName,
     loadSession,
-  } = useAI(chatRef);
+    isLoadingSession,
+  } = useAI(chatRef, {
+    initialSessionId: initialBornSessionIdRef.current,
+    onSessionBorn: setBornSessionId,
+    onSessionCleared: () => setBornSessionId(null),
+  });
   const mode = useValMode();
   const [windowPos, setWindowPos] = useState({
     x: Math.max(20, window.innerWidth - 570),
@@ -1002,6 +1075,7 @@ function ChatWindow({
         <div className="flex-1 overflow-hidden">
           <AIChat
             ref={chatRef}
+            chatEditorRef={chatEditorRef}
             onSendMessage={sendMessage}
             onUploadFile={uploadAiImage}
             onNewSession={newSession}
@@ -1013,6 +1087,7 @@ function ChatWindow({
             onLoadSession={loadSession}
             onFetchSessions={getSessions}
             onSetSessionName={setSessionName}
+            isLoadingSession={isLoadingSession}
           />
         </div>
         {!isMobile && (
@@ -1073,7 +1148,11 @@ function WindowField({
   showInlineStudioLink: boolean;
 }) {
   const schemaAtPath = useSchemaAtPath(path);
-  const studioUrl = window.origin + "/val/~" + path;
+  const { bornSessionId } = useContext(OverlaySessionContext);
+  const studioUrl = appendSessionParam(
+    window.origin + "/val/~" + path,
+    bornSessionId,
+  );
 
   if (schemaAtPath.status === "error") {
     return (
@@ -1211,6 +1290,7 @@ function ValMenu({
   dropZone: DropZones;
   ghost?: boolean;
 } & ValMenuProps) {
+  const { bornSessionId } = useContext(OverlaySessionContext);
   const dir =
     dropZone === "val-menu-right-center" || dropZone === "val-menu-left-center"
       ? "vertical"
@@ -1381,7 +1461,10 @@ function ValMenu({
           <HoverCard>
             <HoverCardTrigger className="inline-flex" asChild>
               <MenuButton
-                href={window.origin + "/val/compare"}
+                href={appendSessionParam(
+                  window.origin + "/val/compare",
+                  bornSessionId,
+                )}
                 icon={
                   <div className="relative">
                     {patchIds.length > 0 && (
@@ -1455,14 +1538,15 @@ function ValMenu({
                     <PanelsTopLeft size={16} />
                   )
                 }
-                href={
+                href={appendSessionParam(
                   window.origin +
-                  "/val/~" +
-                  (sourcePathResult.status === "success" &&
-                  sourcePathResult.data
-                    ? sourcePathResult.data
-                    : "")
-                }
+                    "/val/~" +
+                    (sourcePathResult.status === "success" &&
+                    sourcePathResult.data
+                      ? sourcePathResult.data
+                      : ""),
+                  bornSessionId,
+                )}
               />
             </HoverCardTrigger>
             <HoverCardContent
@@ -1576,13 +1660,14 @@ function ValMenu({
                 <PanelsTopLeft size={16} />
               )
             }
-            href={
+            href={appendSessionParam(
               window.origin +
-              "/val/~" +
-              (sourcePathResult.status === "success" && sourcePathResult.data
-                ? sourcePathResult.data
-                : "")
-            }
+                "/val/~" +
+                (sourcePathResult.status === "success" && sourcePathResult.data
+                  ? sourcePathResult.data
+                  : ""),
+              bornSessionId,
+            )}
           />
           <MenuButton
             label="Disable Val"
diff --git a/packages/ui/spa/components/ValProvider.tsx b/packages/ui/spa/components/ValProvider.tsx
index 17c900e2e..3359661af 100644
--- a/packages/ui/spa/components/ValProvider.tsx
+++ b/packages/ui/spa/components/ValProvider.tsx
@@ -47,6 +47,7 @@ import { ValErrorProvider } from "./ValErrorProvider";
 import { ValPortalProvider } from "./ValPortalProvider";
 import { ValFieldProvider } from "./ValFieldProvider";
 import { ValRemoteProvider } from "./ValRemoteProvider";
+import { AIChatActionsProvider } from "./AIChatActionsContext";
 import {
   useAIWebSocket,
   type AIMessageHandler,
@@ -661,29 +662,31 @@ export function ValProvider({
       }}
     >
       <TooltipProvider>
-        {theme !== undefined && setTheme ? (
-          <ValThemeProvider
-            theme={theme}
-            setTheme={setTheme}
-            config={runtimeConfig}
-          >
-            <ValErrorProvider syncEngine={syncEngine}>
-              <ValPortalProvider>
-                <ValRemoteProvider remoteFiles={remoteFiles}>
-                  <ValFieldProvider
-                    syncEngine={syncEngine}
-                    getDirectFileUploadSettings={getDirectFileUploadSettings}
-                    config={runtimeConfig}
-                  >
-                    {children}
-                  </ValFieldProvider>
-                </ValRemoteProvider>
-              </ValPortalProvider>
-            </ValErrorProvider>
-          </ValThemeProvider>
-        ) : (
-          children
-        )}
+        <AIChatActionsProvider isAIChatEnabled={wsEnabled}>
+          {theme !== undefined && setTheme ? (
+            <ValThemeProvider
+              theme={theme}
+              setTheme={setTheme}
+              config={runtimeConfig}
+            >
+              <ValErrorProvider syncEngine={syncEngine}>
+                <ValPortalProvider>
+                  <ValRemoteProvider remoteFiles={remoteFiles}>
+                    <ValFieldProvider
+                      syncEngine={syncEngine}
+                      getDirectFileUploadSettings={getDirectFileUploadSettings}
+                      config={runtimeConfig}
+                    >
+                      {children}
+                    </ValFieldProvider>
+                  </ValRemoteProvider>
+                </ValPortalProvider>
+              </ValErrorProvider>
+            </ValThemeProvider>
+          ) : (
+            children
+          )}
+        </AIChatActionsProvider>
       </TooltipProvider>
     </ValContext.Provider>
   );
diff --git a/packages/ui/spa/components/ValRouter.tsx b/packages/ui/spa/components/ValRouter.tsx
index a459dead9..7a2baafd9 100644
--- a/packages/ui/spa/components/ValRouter.tsx
+++ b/packages/ui/spa/components/ValRouter.tsx
@@ -6,6 +6,7 @@ import React, {
   useRef,
   useState,
 } from "react";
+import { VAL_AI_SESSION_STORAGE_KEY } from "@valbuild/shared/internal";
 
 const VAL_COMPARE_ROUTE = "/val/compare";
 export const VAL_ERRORS_ROUTE = "/val/errors";
@@ -29,6 +30,10 @@ type ValRouterContextValue = {
   isCompareView: boolean;
   isErrorsView: boolean;
   errorFields: SourcePath[];
+  /** Current value of the `?session=` query param, or null if absent. */
+  sessionParam: string | null;
+  /** Update the `?session=` query param. No-op when running in overlay mode. */
+  setSessionParam: (id: string | null, opts?: { replace?: boolean }) => void;
 };
 const ValRouterContext = React.createContext<ValRouterContextValue>(
   new Proxy(
@@ -88,9 +93,11 @@ export function ValRouter({
   const [isCompareView, setIsCompareView] = useState(false);
   const [isErrorsView, setIsErrorsView] = useState(false);
   const [errorFields, setErrorFields] = useState<SourcePath[]>([]);
+  const [sessionParam, setSessionParamState] = useState<string | null>(null);
   const historyState = useRef<number[]>([]);
   useEffect(() => {
     const listener = () => {
+      setSessionParamState(new URLSearchParams(location.search).get("session"));
       if (
         location.pathname === VAL_COMPARE_ROUTE ||
         location.pathname === VAL_COMPARE_ROUTE + "/"
@@ -208,6 +215,25 @@ export function ValRouter({
         : isErrors
           ? VAL_ERRORS_ROUTE + errorFieldsQuery
           : `${VAL_CONTENT_VIEW_ROUTE}${path}`;
+      // Preserve `?session=` across in-studio navigations. Without this every
+      // sidebar/compare/errors click would strip the AI chat session id from
+      // the URL. URL only — useAI does not re-read this after mount, so chat
+      // state is intentionally not affected by navigations.
+      //
+      // In overlay mode the host page URL has no `?session=`, so fall back to
+      // sessionStorage so AI navigate_to (and overlay→studio nav generally)
+      // brings the active chat along to the studio.
+      let sid: string | null = sessionParam;
+      if (overlay && sid == null) {
+        try {
+          sid = sessionStorage.getItem(VAL_AI_SESSION_STORAGE_KEY);
+        } catch {
+          sid = null;
+        }
+      }
+      const finalTo = sid
+        ? `${navigateTo}${navigateTo.includes("?") ? "&" : "?"}session=${encodeURIComponent(sid)}`
+        : navigateTo;
       setIsCompareView(isCompare);
       setIsErrorsView(isErrors);
       setErrorFields(isErrors ? (params?.errorFields ?? []) : []);
@@ -240,18 +266,35 @@ export function ValRouter({
           historyState.current.push(prevScrollPos);
         }
         if (params?.replace) {
-          window.history.replaceState(null, "", navigateTo);
+          window.history.replaceState(null, "", finalTo);
         } else {
-          window.history.pushState(null, "", navigateTo);
+          window.history.pushState(null, "", finalTo);
         }
       } else {
         window.location.href =
-          navigateTo +
+          finalTo +
           (params?.scrollToPath
             ? `#${encodeURIComponent(params.scrollToPath)}`
             : "");
       }
     },
+    [overlay, sessionParam],
+  );
+  const setSessionParam = useCallback(
+    (id: string | null, opts?: { replace?: boolean }) => {
+      // Overlay runs on the host page — never mutate that URL.
+      if (overlay) return;
+      const url = new URL(window.location.href);
+      if (id == null) url.searchParams.delete("session");
+      else url.searchParams.set("session", id);
+      const target = url.pathname + url.search + url.hash;
+      if (opts?.replace) {
+        window.history.replaceState(null, "", target);
+      } else {
+        window.history.pushState(null, "", target);
+      }
+      setSessionParamState(id);
+    },
     [overlay],
   );
   return (
@@ -264,6 +307,8 @@ export function ValRouter({
         isCompareView,
         isErrorsView,
         errorFields,
+        sessionParam,
+        setSessionParam,
       }}
     >
       {children}
@@ -298,3 +343,8 @@ export function useParams(): {
     sourcePath: ctx.currentSourcePath,
   };
 }
+
+export function useSessionParam() {
+  const { sessionParam, setSessionParam } = useContext(ValRouterContext);
+  return { sessionParam, setSessionParam };
+}
diff --git a/packages/ui/spa/hooks/useAI.ts b/packages/ui/spa/hooks/useAI.ts
index 072825844..55032f765 100644
--- a/packages/ui/spa/hooks/useAI.ts
+++ b/packages/ui/spa/hooks/useAI.ts
@@ -1,5 +1,10 @@
 import React, { useCallback, useEffect, useRef, useState } from "react";
 import type { AIChatHandle, ChatMessageAttachment } from "../components/AIChat";
+import type { ChatDocument } from "../components/AIChatEditor";
+import {
+  chatDocumentToHtmlText,
+  collectImageNodesFromDoc,
+} from "../components/AIChatEditor";
 import {
   type AITool,
   SessionImageToPatchError,
@@ -18,7 +23,6 @@ import type {
   AIMessageContentBlock,
   AIPromptMessage,
 } from "./useAIWebSocket";
-import { getRecentSession } from "./useAIWebSocket";
 import { useAISearch } from "./useAISearch";
 import { useAIValidation } from "./useAIValidation";
 import type {
@@ -338,7 +342,19 @@ const ALL_TOOLS: AITool[] = [
   SHOW_COMPARE_VIEW_TOOL,
 ];
 
-export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
+export type UseAIOptions = {
+  /** Initial session id to load on mount (e.g. read from URL). When null, the chat starts in an unborn state. */
+  initialSessionId?: string | null;
+  /** Called when the session transitions from unborn → born (first send) or when an existing session is loaded. */
+  onSessionBorn?: (id: string) => void;
+  /** Called when the session returns to the unborn state (newSession, or loadSession failure). */
+  onSessionCleared?: () => void;
+};
+
+export function useAI(
+  chatRef: React.RefObject<AIChatHandle | null>,
+  opts?: UseAIOptions,
+) {
   const {
     subscribeToWsMessages,
     sendWsMessage,
@@ -359,11 +375,17 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
   const config = useValConfig();
   const isChatEnabled = config?.ai?.chat?.experimental?.enable === true;
   const [isStreaming, setIsStreaming] = useState(false);
+  const [isLoadingSession, setIsLoadingSession] = useState(false);
   const [sessions, setSessions] = useState<AISession[]>([]);
-  const [currentSessionId, setCurrentSessionId] = useState<string>(() =>
-    crypto.randomUUID(),
-  );
-  const sessionIdRef = useRef<string>(currentSessionId);
+  const [currentSessionId, setCurrentSessionId] = useState<string | null>(null);
+  const sessionIdRef = useRef<string | null>(null);
+  // Keep callbacks in a ref so we don't have to thread them through every useCallback dep array.
+  const onSessionBornRef = useRef(opts?.onSessionBorn);
+  const onSessionClearedRef = useRef(opts?.onSessionCleared);
+  useEffect(() => {
+    onSessionBornRef.current = opts?.onSessionBorn;
+    onSessionClearedRef.current = opts?.onSessionCleared;
+  });
   // Track active streaming ID — startAssistantMessage always appends a new
   // message (NOT idempotent), so we must only call it once per message ID.
   const activeIdRef = useRef<string | null>(null);
@@ -1154,12 +1176,22 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
         } else if (message.name === "set_session_name") {
           const args = message.arguments as { name: string };
           const name = String(args.name ?? "").slice(0, 60);
-          aiSetSessionName(sessionIdRef.current, name)
+          const sid = sessionIdRef.current;
+          if (sid == null) {
+            // Defensive: tool calls only run for an active session.
+            sendWsMessage({
+              type: "ai_tool_result",
+              toolCallId: message.toolCallId,
+              result: { success: false, error: "No active session." },
+              isError: true,
+            });
+            chatRef.current?.errorToolCall(message.id, message.toolCallId);
+            return;
+          }
+          aiSetSessionName(sid, name)
             .then(() => {
               setSessions((prev) =>
-                prev.map((s) =>
-                  s.id === sessionIdRef.current ? { ...s, name } : s,
-                ),
+                prev.map((s) => (s.id === sid ? { ...s, name } : s)),
               );
               sendWsMessage({
                 type: "ai_tool_result",
@@ -1249,6 +1281,15 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
           "Cannot upload AI image: content host is not configured. Set the `project` option in val.config (or VAL_PROJECT) and ensure a personal access token is available.",
         );
       }
+      // Uploading an image attaches binary data to the session on the server,
+      // so it counts as "using" the session — mint the id now if still unborn.
+      let sid = sessionIdRef.current;
+      const wasUnborn = sid == null;
+      if (sid == null) {
+        sid = crypto.randomUUID();
+        sessionIdRef.current = sid;
+        setCurrentSessionId(sid);
+      }
       const headers: Record<string, string> = {
         "Content-Type": file.type || "application/octet-stream",
         "Content-Length": String(file.size),
@@ -1257,7 +1298,7 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
         headers["x-val-auth-nonce"] = contentAuthNonce;
       }
       const queryParams = new URLSearchParams();
-      queryParams.set("sessionid", encodeURIComponent(sessionIdRef.current));
+      queryParams.set("sessionid", encodeURIComponent(sid));
       queryParams.set("width", encodeURIComponent(readRes.width || 0));
       queryParams.set("height", encodeURIComponent(readRes.height || 0));
       queryParams.set(
@@ -1278,20 +1319,59 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
         throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
       }
       const body = (await res.json()) as { key: string };
+      if (wasUnborn) {
+        onSessionBornRef.current?.(sid);
+      }
       return body;
     },
     [getDirectFileUploadSettings],
   );
 
   const sendMessage = useCallback(
-    (text: string, attachments?: ChatMessageAttachment[]): boolean => {
-      let augmentedText = text;
-      if (attachments && attachments.length > 0) {
-        const lines = attachments.map(
+    (
+      content: string | ChatDocument,
+      attachments?: ChatMessageAttachment[],
+    ): boolean => {
+      // Lazily mint the session id on the first send so unborn sessions don't
+      // appear in the URL or on the server until the user actually says something.
+      let sid = sessionIdRef.current;
+      const wasUnborn = sid == null;
+      if (sid == null) {
+        sid = crypto.randomUUID();
+        sessionIdRef.current = sid;
+        setCurrentSessionId(sid);
+      }
+      const baseText =
+        typeof content === "string" ? content : chatDocumentToHtmlText(content);
+      // Pull inline image nodes out of the rich document so their keys are
+      // registered as `image_key` content blocks (the protocol the server
+      // expects), not buried in the HTML text. Drop any still-pending keys —
+      // the editor should already block Send while uploads are in flight, but
+      // this is a defence-in-depth check.
+      const inlineImages =
+        typeof content === "string" ? [] : collectImageNodesFromDoc(content);
+      const inlineImageAttachments: ChatMessageAttachment[] = inlineImages
+        .filter((n) => n.key && !n.key.startsWith("pending:"))
+        .map((n) => ({
+          key: n.key,
+          name: n.alt || "inline image",
+          mimeType: n.mimeType,
+          previewUrl: n.previewUrl,
+        }));
+      const mergedAttachments: ChatMessageAttachment[] = [];
+      const seenKeys = new Set<string>();
+      for (const a of [...(attachments ?? []), ...inlineImageAttachments]) {
+        if (seenKeys.has(a.key)) continue;
+        seenKeys.add(a.key);
+        mergedAttachments.push(a);
+      }
+      let augmentedText = baseText;
+      if (mergedAttachments.length > 0) {
+        const lines = mergedAttachments.map(
           (a) => `- ${a.name}: image_key="${a.key}"`,
         );
         augmentedText =
-          text +
+          baseText +
           "\n\n[Attached images — when calling convert_session_image_to_patch, " +
           "use the exact image_key string from this list (NOT any vision-system file id):\n" +
           lines.join("\n") +
@@ -1299,15 +1379,15 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
       }
       const contentBlocks: AIMessageContentBlock[] = [
         { type: "text", text: augmentedText },
-        ...(attachments?.map((attachment) => ({
+        ...mergedAttachments.map((attachment) => ({
           type: "image_key" as const,
           key: attachment.key,
-        })) ?? []),
+        })),
       ];
       const message: AIPromptMessage = {
         type: "ai_prompt",
         message: contentBlocks,
-        sessionId: sessionIdRef.current,
+        sessionId: sid,
         id: crypto.randomUUID(),
         agents: [
           {
@@ -1318,6 +1398,16 @@ export function useAI(chatRef: React.RefObject<AIChatHandle | null>) {
 ## Who you are talking to
 Users are content editors — they are NOT developers. Never use technical terms like "patch", "JSON", "schema", "module", or "RFC 6902". Explain everything in plain language. Refer to content files by their friendly name or path (e.g. "Blog Posts").
 
+## User message format (HTML-esque rich text)
+The user's message text in the \`text\` content block may include rich formatting written as an HTML-esque string. Treat the formatting as the user's intent, but do NOT echo or quote the tags back at them.
+- Block tags: <p>, <h1>, <h2>, <h3>, <blockquote>, <ul>, <ol>, <li>.
+- Inline marks: <strong>, <em>, <del>, <code>.
+- Line break: <br/>.
+- Non-standard self-closing tags:
+  - <field path="..."/>: the user explicitly pointed at this Val source path. Treat it as if they typed and named that path; when relevant, call get_source on the corresponding module to read the current value and reference the field by its friendly name in your reply.
+  - <img key="..."/>: an inline image attached by the user. The key is the same as an image_key content block — use it with convert_session_image_to_patch / add_session_image_to_gallery as you would any other session image. Do not try to fetch the URL of an inline image.
+Plain user messages without tags should be treated as plain text.
+
 ## Understanding where user is
 If the get_current_context pathname starts with /val, the user is in the Val Studio. 
 
@@ -1389,16 +1479,22 @@ Do not describe what you will do unless you do it for clarification — just do
           },
         ],
       };
-      return sendWsMessage(message);
+      const sent = sendWsMessage(message);
+      // Notify the session was "born" only after a successful send so a failed
+      // first send doesn't leak an empty session id into the URL.
+      if (sent && wasUnborn) {
+        onSessionBornRef.current?.(sid);
+      }
+      return sent;
     },
     [sendWsMessage],
   );
 
   const newSession = useCallback(() => {
-    const id = crypto.randomUUID();
-    sessionIdRef.current = id;
-    setCurrentSessionId(id);
+    sessionIdRef.current = null;
+    setCurrentSessionId(null);
     chatRef.current?.clearMessages();
+    onSessionClearedRef.current?.();
   }, [chatRef]);
 
   const getSessions = useCallback(
@@ -1428,6 +1524,7 @@ Do not describe what you will do unless you do it for clarification — just do
       sessionIdRef.current = sessionId;
       setCurrentSessionId(sessionId);
       chatRef.current?.clearMessages();
+      setIsLoadingSession(true);
       try {
         const res = await aiGetSessionMessages(sessionId);
         const messages = res.messages
@@ -1439,35 +1536,38 @@ Do not describe what you will do unless you do it for clarification — just do
             status: "complete" as const,
           }));
         chatRef.current?.loadMessages(messages);
+        onSessionBornRef.current?.(sessionId);
       } catch (err) {
-        console.error("Failed to load session messages:", err);
+        console.warn("Failed to load session messages, clearing:", err);
+        sessionIdRef.current = null;
+        setCurrentSessionId(null);
+        chatRef.current?.clearMessages();
+        onSessionClearedRef.current?.();
+      } finally {
+        setIsLoadingSession(false);
       }
     },
     [chatRef, aiGetSessionMessages],
   );
 
-  // On mount, restore the most recent session if it was used within the last 24 hours
+  // On mount, populate the sessions dropdown and (if an initial session id was
+  // passed in, e.g. from ?session= in the URL) load it. Intentional: this runs
+  // only once — popstate / URL changes after mount must NOT hijack the user's
+  // open chat, so we capture initialSessionId via opts only on the first render.
+  const initialSessionIdRef = useRef(opts?.initialSessionId ?? null);
   useEffect(() => {
     if (!isChatEnabled) return;
-    let cancelled = false;
-    getSessions({ limit: 1 })
-      .then((fetchedSessions) => {
-        if (cancelled) return;
-        const session = getRecentSession(fetchedSessions);
-        if (session) return loadSession(session.id);
-      })
-      .catch((err) => {
-        console.error("Failed to restore last session:", err);
-      });
-    return () => {
-      cancelled = true;
-    };
+    getSessions({ limit: 1 }).catch(() => {});
+    if (initialSessionIdRef.current != null) {
+      loadSession(initialSessionIdRef.current);
+    }
   }, [isChatEnabled]);
 
   return {
     sendMessage,
     uploadAiImage,
     isStreaming,
+    isLoadingSession,
     isConnected: isWsConnected,
     authError: aiAuthError,
     newSession,