jamdesk 1.1.126 → 1.1.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.126",
+  "version": "1.1.127",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/app/api/og/route.tsx

@@ -1,5 +1,6 @@
 import { ImageResponse } from '@vercel/og';
 import { NextRequest } from 'next/server';
+import { sanitizeLogoUrl } from '@/lib/sanitize-url';
 
 export const runtime = 'edge';
 
@@ -20,6 +21,27 @@ function truncateText(text: string, maxLength: number): string {
   return text.substring(0, maxLength) + '...';
 }
 
+/**
+ * Fetch an image and convert it to a base64 data URI for Satori compatibility
+ * (Satori doesn't support webp and can fail on remote URLs). 3s timeout; '' on failure.
+ */
+async function fetchDataUri(url: string): Promise<string> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    // redirect: 'manual' so a sanitized public host can't 302 to an internal one (SSRF).
+    const res = await fetch(url, { signal: controller.signal, redirect: 'manual' });
+    if (!res.ok) return '';
+    const contentType = res.headers.get('content-type') || 'image/png';
+    const buf = await res.arrayBuffer();
+    return `data:${contentType};base64,${Buffer.from(buf).toString('base64')}`;
+  } catch {
+    return ''; // Skip image on fetch failure
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 /**
  * OG Image Generator
  *
@@ -31,6 +53,7 @@ function truncateText(text: string, maxLength: number): string {
  * - section: Section/group name (optional, e.g., "Get Started")
  * - siteName: Site name (optional, defaults to "Documentation")
  * - logo: URL to the project's logo (optional)
+ * - bg: URL to a custom background image rendered behind the text (optional)
  * - theme: accepted but ignored (always uses cream/warm style)
  *
  * Example:
@@ -43,27 +66,14 @@ export async function GET(request: NextRequest) {
   const description = searchParams.get('description') || '';
   const section = searchParams.get('section') || '';
   const siteName = searchParams.get('siteName') || 'Documentation';
-  const logoUrl = searchParams.get('logo') || '';
+  // SSRF guard: HTTPS-only, blocks private/loopback/metadata IPs (incl. encoded forms).
+  const logoUrl = sanitizeLogoUrl(searchParams.get('logo') || '');
+  const bgUrl = sanitizeLogoUrl(searchParams.get('bg') || '');
 
-  // Fetch logo and convert to base64 data URI for Satori compatibility
-  // (Satori doesn't support webp and can fail on remote URLs)
-  let logo = '';
-  if (logoUrl) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 3000);
-    try {
-      const res = await fetch(logoUrl, { signal: controller.signal });
-      if (res.ok) {
-        const contentType = res.headers.get('content-type') || 'image/png';
-        const buf = await res.arrayBuffer();
-        logo = `data:${contentType};base64,${Buffer.from(buf).toString('base64')}`;
-      }
-    } catch {
-      // Skip logo on fetch failure
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
+  const [logo, bg] = await Promise.all([
+    logoUrl ? fetchDataUri(logoUrl) : Promise.resolve(''),
+    bgUrl ? fetchDataUri(bgUrl) : Promise.resolve(''),
+  ]);
 
   const titleFontSize = title.length > LONG_TITLE_THRESHOLD ? '52px' : '64px';
 
@@ -71,119 +81,148 @@ export async function GET(request: NextRequest) {
     (
       <div
         style={{
+          position: 'relative',
           height: '100%',
           width: '100%',
           display: 'flex',
-          flexDirection: 'column',
-          padding: '60px',
           background: BG_GRADIENT,
           fontFamily: FONT_STACK,
         }}
       >
-        {/* Logo and site name */}
+        {/* Custom background image, full-bleed behind the text */}
+        {bg && (
+          <img
+            src={bg}
+            alt=""
+            width={1200}
+            height={630}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '1200px',
+              height: '630px',
+              objectFit: 'cover',
+            }}
+          />
+        )}
+        {/* Content (painted on top of the background) */}
         <div
           style={{
             display: 'flex',
             flexDirection: 'column',
-            alignItems: 'flex-start',
-            marginBottom: '40px',
+            width: '100%',
+            height: '100%',
+            padding: '60px',
           }}
         >
-          {logo && (
-            <img
-              src={logo}
-              alt=""
-              width={48}
-              height={48}
-              style={{
-                marginBottom: '16px',
-                borderRadius: '8px',
-              }}
-            />
-          )}
-          <span
-            style={{
-              fontSize: '24px',
-              fontWeight: 600,
-              color: MUTED_COLOR,
-              textTransform: 'uppercase',
-              letterSpacing: '0.05em',
-            }}
-          >
-            {siteName}
-          </span>
-        </div>
-
-        {/* Section badge */}
-        {section && (
+          {/* Logo and site name */}
           <div
             style={{
               display: 'flex',
-              marginBottom: '20px',
+              flexDirection: 'column',
+              alignItems: 'flex-start',
+              marginBottom: '40px',
             }}
           >
+            {logo && (
+              <img
+                src={logo}
+                alt=""
+                height={48}
+                style={{
+                  height: '48px',
+                  maxWidth: '360px',
+                  objectFit: 'contain',
+                  marginBottom: '16px',
+                  borderRadius: '8px',
+                }}
+              />
+            )}
             <span
               style={{
-                fontSize: '18px',
-                fontWeight: 500,
-                color: ACCENT_COLOR,
-                padding: '8px 16px',
-                background: BADGE_BG,
-                borderRadius: '20px',
+                fontSize: '24px',
+                fontWeight: 600,
+                color: MUTED_COLOR,
+                textTransform: 'uppercase',
+                letterSpacing: '0.05em',
               }}
             >
-              {section}
+              {siteName}
             </span>
           </div>
-        )}
 
-        {/* Title and description */}
-        <div
-          style={{
-            display: 'flex',
-            flex: 1,
-            flexDirection: 'column',
-            justifyContent: 'center',
-          }}
-        >
-          <h1
+          {/* Section badge */}
+          {section && (
+            <div
+              style={{
+                display: 'flex',
+                marginBottom: '20px',
+              }}
+            >
+              <span
+                style={{
+                  fontSize: '18px',
+                  fontWeight: 500,
+                  color: ACCENT_COLOR,
+                  padding: '8px 16px',
+                  background: BADGE_BG,
+                  borderRadius: '20px',
+                }}
+              >
+                {section}
+              </span>
+            </div>
+          )}
+
+          {/* Title and description */}
+          <div
             style={{
-              fontSize: titleFontSize,
-              fontWeight: 700,
-              color: TEXT_COLOR,
-              lineHeight: 1.2,
-              margin: 0,
-              maxWidth: '900px',
+              display: 'flex',
+              flex: 1,
+              flexDirection: 'column',
+              justifyContent: 'center',
             }}
           >
-            {title}
-          </h1>
-
-          {description && (
-            <p
+            <h1
               style={{
-                fontSize: '28px',
-                color: MUTED_COLOR,
-                marginTop: '24px',
-                lineHeight: 1.4,
-                maxWidth: '800px',
+                fontSize: titleFontSize,
+                fontWeight: 700,
+                color: TEXT_COLOR,
+                lineHeight: 1.2,
+                margin: 0,
+                maxWidth: '900px',
               }}
             >
-              {truncateText(description, MAX_DESCRIPTION_LENGTH)}
-            </p>
-          )}
-        </div>
+              {title}
+            </h1>
 
-        {/* Bottom accent bar */}
-        <div
-          style={{
-            display: 'flex',
-            height: '6px',
-            background: ACCENT_GRADIENT,
-            borderRadius: '3px',
-            marginTop: '40px',
-          }}
-        />
+            {description && (
+              <p
+                style={{
+                  fontSize: '28px',
+                  color: MUTED_COLOR,
+                  marginTop: '24px',
+                  lineHeight: 1.4,
+                  maxWidth: '800px',
+                }}
+              >
+                {truncateText(description, MAX_DESCRIPTION_LENGTH)}
+              </p>
+            )}
+          </div>
+
+          {/* Bottom accent bar */}
+          <div
+            style={{
+              display: 'flex',
+              height: '6px',
+              background: ACCENT_GRADIENT,
+              borderRadius: '3px',
+              marginTop: '40px',
+            }}
+          />
+        </div>
       </div>
     ),
     {

package/vendored/components/chat/ChatMessage.tsx

@@ -4,6 +4,7 @@ import { memo } from 'react';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { ChatCodeBlock } from './ChatCodeBlock';
+import { CopyButton } from './CopyButton';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import type { ChatMessage as ChatMessageType } from '@/hooks/useChat';
 
@@ -126,6 +127,13 @@ export const ChatMessage = memo(function ChatMessage({ message, onSelectOption }
             )}
           </div>
 
+          {/* Copy answer — only on a finalized, non-empty assistant message */}
+          {!message.isStreaming && message.content && (
+            <div className="mt-1 -ml-2">
+              <CopyButton getText={() => message.content} ariaLabel="Copy answer" />
+            </div>
+          )}
+
           {/* Clarification options — tappable buttons for disambiguation */}
           {hasClarificationOptions && (
             <div className="mt-3">

package/vendored/components/chat/ChatPanel.tsx

@@ -3,9 +3,13 @@
 import { useRef, useEffect, useLayoutEffect, useCallback, useState } from 'react';
 import { useChat } from '@/hooks/useChat';
 import { useBodyScrollLock } from '@/hooks/useBodyScrollLock';
+import { useChatPanelOptional } from '@/hooks/useChatPanel';
 import { ChatMessage } from './ChatMessage';
 import { ChatInput } from './ChatInput';
 import { ChatEmptyState } from './ChatEmptyState';
+import { CopyButton } from './CopyButton';
+import { formatTranscript } from '@/lib/chat-transcript';
+import { isNearBottom } from '@/lib/chat-scroll';
 import { crispAvailable, hideCrispLauncher, openCrispChat, showCrispLauncher } from '../../lib/crisp-bridge';
 
 const SOMETHING_ELSE_PATTERNS = ['something else', 'none of the above', 'none of these'];
@@ -43,6 +47,33 @@ interface ChatPanelProps {
 export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mode = 'overlay' }: ChatPanelProps) {
   const { messages, sendMessage, isLoading, abort, retry, clearChat, error, markClarificationSelected } = useChat(chatEndpoint);
 
+  // Search (and any external trigger) hands a question to chat via the
+  // ChatPanelContext. We append it as the next message — no clearChat — so an
+  // in-progress conversation is preserved. useChatPanelOptional (not the
+  // throwing useChatPanel) keeps ChatPanel renderable in unit tests / outside
+  // a provider.
+  const chatPanel = useChatPanelOptional();
+  const pendingQuestion = chatPanel?.pendingQuestion ?? null;
+  const consumePendingQuestion = chatPanel?.consumePendingQuestion;
+  const consumingRef = useRef(false);
+
+  useEffect(() => {
+    if (!pendingQuestion) {
+      consumingRef.current = false;
+      return;
+    }
+    // R1: sendMessage() is a no-op while a stream is in flight (useChat guards
+    // on isLoadingRef). Do NOT consume the question then — it would vanish.
+    // Hold it; isLoading is a dependency, so when the stream finishes the
+    // effect re-runs and delivers. consumingRef prevents an effect double-fire
+    // from sending twice within one delivery; it resets when pendingQuestion
+    // clears.
+    if (isLoading || consumingRef.current) return;
+    consumingRef.current = true;
+    sendMessage(pendingQuestion);
+    consumePendingQuestion?.();
+  }, [pendingQuestion, isLoading, sendMessage, consumePendingQuestion]);
+
   const [hasCrisp, setHasCrisp] = useState(false);
   useEffect(() => { setHasCrisp(crispAvailable()); }, []);
 
@@ -51,6 +82,15 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
     openCrispChat();
   }, [onClose]);
 
+  // "New chat" must also drop any not-yet-delivered handoff question. Otherwise
+  // a question queued mid-stream (held by the consume effect while isLoading)
+  // would fire into the freshly cleared conversation once clearChat()'s abort()
+  // flips isLoading false and the effect re-runs.
+  const handleNewChat = useCallback(() => {
+    clearChat();
+    consumePendingQuestion?.();
+  }, [clearChat, consumePendingQuestion]);
+
   const messagesContainerRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLDivElement>(null);
   const overlayPanelRef = useRef<HTMLDivElement>(null);
@@ -109,14 +149,29 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
     };
   }, [isOpen, isInline]);
 
-  // Auto-scroll to bottom when new messages arrive. Uses useLayoutEffect so
-  // scrollHeight is accurate (DOM is updated) and there's no visible 1-frame lag.
-  // Scrolls the container directly instead of scrollIntoView to avoid scrolling
-  // ancestor elements (which pushes the panel off-screen on mobile).
+  // Auto-scroll only when the user is already at the bottom. If they've
+  // scrolled up to re-read mid-stream, leave their position alone. We track
+  // "pinned" in a ref (not state) so updating it on every scroll event doesn't
+  // re-render. Direct container scroll (no scrollIntoView — that scrolls every
+  // ancestor; documented anti-pattern in CLAUDE.md).
+  const isPinnedToBottomRef = useRef(true);
+
+  const handleMessagesScroll = useCallback(() => {
+    const container = messagesContainerRef.current;
+    if (!container) return;
+    isPinnedToBottomRef.current = isNearBottom(
+      container.scrollTop,
+      container.scrollHeight,
+      container.clientHeight,
+    );
+  }, []);
+
   useLayoutEffect(() => {
     const container = messagesContainerRef.current;
     if (!container) return;
-    container.scrollTop = container.scrollHeight;
+    if (isPinnedToBottomRef.current) {
+      container.scrollTop = container.scrollHeight;
+    }
   }, [messages]);
 
   // Escape key handling is in useChatPanel (capture phase, with search-modal awareness)
@@ -152,9 +207,17 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
           </span>
         </div>
         <div className="flex items-center gap-1">
+          {/* R8: only when no message is mid-stream, so the transcript captures
+              the post-rewrite (absolute-URL) link form, not slug placeholders. */}
+          {hasMessages && !messages.some((m) => m.isStreaming) && (
+            <CopyButton
+              getText={() => formatTranscript(messages)}
+              ariaLabel="Copy transcript"
+            />
+          )}
           {hasMessages && (
             <button
-              onClick={clearChat}
+              onClick={handleNewChat}
               className="px-2 py-1 text-xs text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] transition-colors rounded-md hover:bg-[var(--color-bg-secondary)] cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"
             >
               New chat
@@ -175,6 +238,7 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
         ref={messagesContainerRef}
         className="flex-1 overflow-y-auto min-h-0"
         style={{ overscrollBehavior: 'contain' }}
+        onScroll={handleMessagesScroll}
         aria-live="polite"
         aria-label="Chat messages"
       >

package/vendored/components/chat/CopyButton.tsx

@@ -0,0 +1,57 @@
+// builder/build-service/components/chat/CopyButton.tsx
+'use client';
+
+import { memo, useCallback, useEffect, useRef, useState } from 'react';
+
+interface CopyButtonProps {
+  /** Lazily produce the text to copy (so we don't recompute on every render). */
+  getText: () => string;
+  /** Accessible name + tooltip (e.g. "Copy answer", "Copy transcript"). */
+  ariaLabel: string;
+  /** Optional visible label rendered next to the icon (used by the transcript button). */
+  idleLabel?: string;
+  className?: string;
+}
+
+/**
+ * Clipboard button with a transient "copied" checkmark. Mirrors the copy
+ * pattern in ChatCodeBlock.tsx but reusable: powers both the per-answer copy
+ * and the "Copy transcript" header action. Fails silently when the Clipboard
+ * API is unavailable (non-HTTPS) or rejects (permission denied).
+ */
+export const CopyButton = memo(function CopyButton({ getText, ariaLabel, idleLabel, className }: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  const handleCopy = useCallback(() => {
+    const text = getText();
+    if (!text || !navigator.clipboard?.writeText) return;
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(true);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), 2000);
+    }).catch(() => {
+      // Clipboard write rejected (permissions) — leave UI unchanged.
+    });
+  }, [getText]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      aria-label={ariaLabel}
+      title={copied ? 'Copied!' : ariaLabel}
+      className={
+        className ??
+        'inline-flex items-center gap-1.5 px-2 py-1 text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors rounded-md hover:bg-[var(--color-bg-secondary)] cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]'
+      }
+    >
+      <i className={`fa-solid ${copied ? 'fa-check text-green-500' : 'fa-copy'}`} aria-hidden="true" />
+      {idleLabel && <span>{copied ? 'Copied' : idleLabel}</span>}
+    </button>
+  );
+});

package/vendored/components/search/SearchModal.tsx

@@ -10,6 +10,8 @@ import { trackSearch } from '@/lib/analytics-client';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import { useProjectSlug } from '@/lib/project-slug-context';
 import type { SearchResult, SearchGroup } from '@/lib/search-client';
+import { useChatPanelOptional } from '@/hooks/useChatPanel';
+import { modifierKeyLabel } from '@/lib/platform-keys';
 
 interface PopularPage {
   title: string;
@@ -136,6 +138,11 @@ function countVisibleResults(rows: SearchRow[]): number {
 export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: SearchModalProps) {
   const linkPrefix = useLinkPrefix();
   const projectSlug = useProjectSlug();
+  const chatPanel = useChatPanelOptional();
+  // Ask AI is offered only when the docs chrome (ChatPanelProvider) is present
+  // AND chat is enabled. The 404 page renders SearchModal without the provider,
+  // so chatPanel is null there and the affordance is hidden.
+  const canAsk = !!chatPanel && chatPanel.chatEnabled;
   const pathname = usePathname() ?? '';
   const [query, setQuery] = useState('');
   const [groups, setGroups] = useState<SearchGroup[]>([]);
@@ -354,11 +361,38 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
     });
   }, []);
 
+  const handleAskAi = useCallback(() => {
+    // Cap at the chat endpoint's 2000-char limit (route.ts rejects longer with
+    // a 400) so a long paste degrades to a truncated question, not a dead end.
+    const trimmed = query.trim().slice(0, 2000);
+    if (!trimmed || !chatPanel) return;
+    addRecentSearch(projectSlug, trimmed);
+    onClose();
+    chatPanel.askChat(trimmed); // opens chat + queues the question (append)
+    // Clear the consumed query (mirrors handleResultClick). SearchModal renders
+    // null when closed but stays mounted, so query state would otherwise persist
+    // and the next search session concatenates onto the handed-off text.
+    setQuery('');
+    setGroups([]);
+  }, [query, chatPanel, projectSlug, onClose]);
+
   // Keyboard navigation
   useEffect(() => {
     if (!isOpen) return;
 
     const handleKeyDown = (e: KeyboardEvent) => {
+      // Cmd/Ctrl + Enter → hand the query to AI chat. Checked first and
+      // returned so it never falls through to the plain-Enter "open top
+      // result" path below.
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        if (canAsk && query.trim()) {
+          e.preventDefault();
+          e.stopPropagation();
+          handleAskAi();
+        }
+        return;
+      }
+
       // When we have search results, navigate through them
       if (rows.length > 0) {
         if (e.key === 'ArrowDown') {
@@ -419,7 +453,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, query, recentSearches, rows, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, projectSlug, handleResultClick, handleExpanderClick, isSearching, linkPrefix]);
+  }, [isOpen, query, recentSearches, rows, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, projectSlug, handleResultClick, handleExpanderClick, isSearching, linkPrefix, canAsk, handleAskAi]);
 
   const handleClearRecentSearches = () => {
     clearRecentSearches(projectSlug);
@@ -684,6 +718,21 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
                 <span className="ml-1">Close</span>
               </div>
             </div>
+            {canAsk && query.trim() && (
+              <button
+                type="button"
+                onClick={handleAskAi}
+                className="inline-flex items-center gap-1.5 px-2 py-1 rounded-md text-[11px] font-medium text-[var(--color-accent)] hover:bg-[var(--color-bg-tertiary)] transition-colors cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"
+                aria-label={`Ask AI about ${query.trim()}`}
+              >
+                <i className="fa-solid fa-sparkles text-[10px]" aria-hidden="true" />
+                <span>Ask AI</span>
+                {/* One keycap for the whole chord (⌘/Ctrl + ↵). Mouse-only:
+                    hidden on touch (coarse pointer), where there's no shortcut
+                    to press and the label tap suffices. */}
+                <kbd className="px-1 py-0.5 bg-[var(--color-bg-primary)] border border-[var(--color-border)] rounded text-[9px] font-medium pointer-coarse:hidden">{`${modifierKeyLabel()} ↵`}</kbd>
+              </button>
+            )}
           </div>
         </div>
       </div>

package/vendored/hooks/useChatPanel.tsx

@@ -16,6 +16,12 @@ interface ChatPanelContextValue {
   chatEnabled: boolean;
   chatEndpoint: string;
   starterQuestions?: string[];
+  /** Question queued by an external trigger (e.g. search "Ask AI"). Consumed once by ChatPanel. */
+  pendingQuestion: string | null;
+  /** Open the chat panel and queue `question` to be sent as the next message (append). */
+  askChat: (question: string) => void;
+  /** Clear the queued question after ChatPanel has sent it. */
+  consumePendingQuestion: () => void;
 }
 
 const ChatPanelContext = createContext<ChatPanelContextValue | null>(null);
@@ -34,6 +40,16 @@ function clampWidth(width: number): number {
 export function ChatPanelProvider({ children, chatEnabled, chatEndpoint, starterQuestions }: ChatPanelProviderProps) {
   const [isChatOpen, setIsChatOpen] = useState(false);
   const [chatWidth, setChatWidthRaw] = useState(DEFAULT_WIDTH);
+  const [pendingQuestion, setPendingQuestion] = useState<string | null>(null);
+
+  const askChat = useCallback((question: string) => {
+    setPendingQuestion(question);
+    setIsChatOpen(true);
+  }, []);
+
+  const consumePendingQuestion = useCallback(() => {
+    setPendingQuestion(null);
+  }, []);
 
   // Load persisted width from localStorage
   useEffect(() => {
@@ -86,7 +102,7 @@ export function ChatPanelProvider({ children, chatEnabled, chatEndpoint, starter
   }, [chatEnabled, isChatOpen, isDevMode]);
 
   return (
-    <ChatPanelContext.Provider value={{ isChatOpen, setIsChatOpen, chatWidth, setChatWidth, chatEnabled, chatEndpoint, starterQuestions }}>
+    <ChatPanelContext.Provider value={{ isChatOpen, setIsChatOpen, chatWidth, setChatWidth, chatEnabled, chatEndpoint, starterQuestions, pendingQuestion, askChat, consumePendingQuestion }}>
       {children}
     </ChatPanelContext.Provider>
   );
@@ -100,7 +116,17 @@ export function useChatPanel(): ChatPanelContextValue {
   return context;
 }
 
-export { MIN_WIDTH, MAX_WIDTH, DEFAULT_WIDTH };
+/**
+ * Non-throwing context accessor. Returns null when there is no
+ * ChatPanelProvider above (e.g. the 404 page renders SearchModal without
+ * the docs chrome). Callers that may render outside the provider MUST use
+ * this instead of useChatPanel().
+ */
+export function useChatPanelOptional(): ChatPanelContextValue | null {
+  return useContext(ChatPanelContext);
+}
+
+export { MIN_WIDTH, MAX_WIDTH, DEFAULT_WIDTH, ChatPanelContext };
 
 /**
  * Returns a chat-open handler that shows DevOnlyNotice in dev mode