@btst/stack 2.3.0 → 2.5.0

package/src/plugins/ai-chat/client/components/chat-interface.tsx

@@ -7,7 +7,11 @@ import { ChatMessage } from "./chat-message";
 import { ChatInput, type AttachedFile } from "./chat-input";
 import { StackAttribution } from "@workspace/ui/components/stack-attribution";
 import { ScrollArea } from "@workspace/ui/components/scroll-area";
-import { DefaultChatTransport, type UIMessage } from "ai";
+import {
+	DefaultChatTransport,
+	lastAssistantMessageIsCompleteWithToolCalls,
+	type UIMessage,
+} from "ai";
 import { cn } from "@workspace/ui/lib/utils";
 import { usePluginOverrides, useBasePath } from "@btst/stack/context";
 import type { AiChatPluginOverrides } from "../overrides";
@@ -20,6 +24,7 @@ import {
 	useConversations,
 	type SerializedConversation,
 } from "../hooks/chat-hooks";
+import { usePageAIContext } from "../context/page-ai-context";
 
 interface ChatInterfaceProps {
 	apiPath?: string;
@@ -56,6 +61,9 @@ export function ChatInterface({
 	const basePath = useBasePath();
 	const isPublicMode = mode === "public";
 
+	// Read page AI context registered by the current page
+	const pageAIContext = usePageAIContext();
+
 	const localization = { ...AI_CHAT_LOCALIZATION, ...customLocalization };
 	const queryClient = useQueryClient();
 
@@ -126,6 +134,13 @@ export function ChatInterface({
 			!initialMessages || initialMessages.length === 0,
 	);
 
+	// Ref to always have the latest pageAIContext in the transport callback
+	// without recreating the transport on every context change
+	const pageAIContextRef = useRef(pageAIContext);
+	useEffect(() => {
+		pageAIContextRef.current = pageAIContext;
+	}, [pageAIContext]);
+
 	// Memoize the transport to prevent recreation on every render
 	const transport = useMemo(
 		() =>
@@ -135,8 +150,21 @@ export function ChatInterface({
 				body: isPublicMode
 					? undefined
 					: () => ({ conversationId: conversationIdRef.current }),
-				// Handle edit operations by using truncated messages from the ref
+				// Handle edit operations and inject page context
 				prepareSendMessagesRequest: ({ messages: hookMessages }) => {
+					const currentPageContext = pageAIContextRef.current;
+
+					// Build page context fields to include in every request
+					const pageContextBody = currentPageContext?.pageDescription
+						? {
+								pageContext: currentPageContext.pageDescription,
+								availableTools: Object.keys(
+									currentPageContext.clientTools ?? {},
+								),
+								routeName: currentPageContext.routeName,
+							}
+						: {};
+
 					// If we're in an edit operation, use the truncated messages + new user message
 					if (editMessagesRef.current !== null) {
 						const newUserMessage = hookMessages[hookMessages.length - 1];
@@ -150,6 +178,7 @@ export function ChatInterface({
 							body: {
 								messages: messagesToSend,
 								conversationId: conversationIdRef.current,
+								...pageContextBody,
 							},
 						};
 					}
@@ -158,6 +187,7 @@ export function ChatInterface({
 						body: {
 							messages: hookMessages,
 							conversationId: conversationIdRef.current,
+							...pageContextBody,
 						},
 					};
 				},
@@ -165,48 +195,99 @@ export function ChatInterface({
 		[apiPath, isPublicMode],
 	);
 
-	const { messages, sendMessage, status, error, setMessages, regenerate } =
-		useChat({
-			transport,
-			onError: (err) => {
-				console.error("useChat onError:", err);
-				// Reset first-message tracking if the send failed before a conversation was created.
-				// Without this, isFirstMessageSentRef stays true and the next successful send
-				// skips the "first message" navigation logic, corrupting the conversation flow.
-				if (!id && !hasNavigatedRef.current) {
-					isFirstMessageSentRef.current = false;
-				}
-			},
-			onFinish: async () => {
-				// In public mode, skip all persistence-related operations
-				if (isPublicMode) return;
+	// Use a ref so addToolOutput is always current inside the onToolCall closure
+	const addToolOutputRef = useRef<
+		ReturnType<typeof useChat>["addToolOutput"] | null
+	>(null);
 
-				// Invalidate conversation list to show new/updated conversations
-				await queryClient.invalidateQueries({
+	const {
+		messages,
+		sendMessage,
+		status,
+		error,
+		setMessages,
+		regenerate,
+		addToolOutput,
+	} = useChat({
+		transport,
+		// Automatically resubmit after all client-side tool results are provided
+		sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+		onToolCall: async ({ toolCall }) => {
+			// Dispatch client-side tool calls to the handler registered by the current page.
+			// In AI SDK v5, onToolCall returns void — addToolOutput must be called explicitly.
+			const toolName = toolCall.toolName;
+			const handler = pageAIContextRef.current?.clientTools?.[toolName];
+			if (handler) {
+				try {
+					const result = await handler(toolCall.input);
+					// No await — avoids potential deadlocks with sendAutomaticallyWhen
+					addToolOutputRef.current?.({
+						tool: toolName,
+						toolCallId: toolCall.toolCallId,
+						output: result,
+					});
+				} catch (err) {
+					addToolOutputRef.current?.({
+						tool: toolName,
+						toolCallId: toolCall.toolCallId,
+						state: "output-error",
+						errorText:
+							err instanceof Error ? err.message : "Tool execution failed",
+					});
+				}
+			} else {
+				// No handler found — this happens when the user navigates away while a
+				// tool-call response is streaming and the page context changes. Always
+				// call addToolOutput so sendAutomaticallyWhen can unblock; without this
+				// the conversation gets permanently stuck waiting for a missing output.
+				addToolOutputRef.current?.({
+					tool: toolName,
+					toolCallId: toolCall.toolCallId,
+					state: "output-error",
+					errorText: `No client-side handler registered for tool "${toolName}". The page context may have changed while the response was streaming.`,
+				});
+			}
+		},
+		onError: (err) => {
+			console.error("useChat onError:", err);
+			// Reset first-message tracking if the send failed before a conversation was created.
+			// Without this, isFirstMessageSentRef stays true and the next successful send
+			// skips the "first message" navigation logic, corrupting the conversation flow.
+			if (!id && !hasNavigatedRef.current) {
+				isFirstMessageSentRef.current = false;
+			}
+		},
+		onFinish: async () => {
+			// In public mode, skip all persistence-related operations
+			if (isPublicMode) return;
+
+			// Invalidate conversation list to show new/updated conversations
+			await queryClient.invalidateQueries({
+				queryKey: conversationsListQueryKey,
+			});
+
+			// If this was the first message on a new chat, update the URL without full navigation
+			// This avoids losing the in-memory messages during component remount
+			if (isFirstMessageSentRef.current && !id && !hasNavigatedRef.current) {
+				hasNavigatedRef.current = true;
+				// Wait for the invalidation to complete and refetch conversations
+				await queryClient.refetchQueries({
 					queryKey: conversationsListQueryKey,
 				});
-
-				// If this was the first message on a new chat, update the URL without full navigation
-				// This avoids losing the in-memory messages during component remount
-				if (isFirstMessageSentRef.current && !id && !hasNavigatedRef.current) {
-					hasNavigatedRef.current = true;
-					// Wait for the invalidation to complete and refetch conversations
-					await queryClient.refetchQueries({
-						queryKey: conversationsListQueryKey,
-					});
-					// Get the updated conversations from cache
-					const cachedConversations = queryClient.getQueryData<
-						SerializedConversation[]
-					>(conversationsListQueryKey);
-					if (cachedConversations && cachedConversations.length > 0) {
-						// The most recently updated conversation should be the one we just created
-						const newConversation = cachedConversations[0];
-						if (newConversation) {
-							// Update our local state
-							setCurrentConversationId(newConversation.id);
-							conversationIdRef.current = newConversation.id;
-							// Update URL without navigation to preserve in-memory messages
-							// Use replaceState to avoid adding to history stack
+				// Get the updated conversations from cache
+				const cachedConversations = queryClient.getQueryData<
+					SerializedConversation[]
+				>(conversationsListQueryKey);
+				if (cachedConversations && cachedConversations.length > 0) {
+					// The most recently updated conversation should be the one we just created
+					const newConversation = cachedConversations[0];
+					if (newConversation) {
+						// Update our local state
+						setCurrentConversationId(newConversation.id);
+						conversationIdRef.current = newConversation.id;
+						// Only update the URL in full-page mode; in widget mode the chat is
+						// embedded in another page and clobbering the URL is disruptive.
+						if (variant === "full") {
 							const newUrl = `${basePath}/chat/${newConversation.id}`;
 							if (typeof window !== "undefined") {
 								window.history.replaceState(
@@ -218,8 +299,14 @@ export function ChatInterface({
 						}
 					}
 				}
-			},
-		});
+			}
+		},
+	});
+
+	// Keep addToolOutputRef in sync so onToolCall always has the latest reference
+	useEffect(() => {
+		addToolOutputRef.current = addToolOutput;
+	}, [addToolOutput]);
 
 	// Load existing conversation messages when navigating to a conversation
 	useEffect(() => {
@@ -484,23 +571,32 @@ export function ChatInterface({
 						>
 							{messages.length === 0 ? (
 								<div className="flex flex-col h-full min-h-[300px]">
-									<div className="flex-1 flex items-center justify-center text-muted-foreground">
+									<div className="flex-1 flex items-center justify-center text-muted-foreground mb-4">
 										<p>{localization.CHAT_EMPTY_STATE}</p>
 									</div>
-									{chatSuggestions && chatSuggestions.length > 0 && (
-										<div className="flex flex-wrap justify-center gap-2 pb-4 max-w-md mx-auto">
-											{chatSuggestions.map((suggestion, index) => (
-												<button
-													key={index}
-													type="button"
-													onClick={() => setInput(suggestion)}
-													className="px-3 py-2 text-sm rounded-lg border border-border bg-background hover:bg-accent hover:text-accent-foreground transition-colors text-foreground"
-												>
-													{suggestion}
-												</button>
-											))}
-										</div>
-									)}
+									{(() => {
+										// Merge static suggestions from overrides with dynamic ones from page context.
+										// Page context suggestions appear first (most relevant to current page).
+										const pageSuggestions = pageAIContext?.suggestions ?? [];
+										const allSuggestions = [
+											...pageSuggestions,
+											...(chatSuggestions ?? []),
+										];
+										return allSuggestions.length > 0 ? (
+											<div className="flex flex-wrap justify-center gap-2 pb-4 max-w-md mx-auto">
+												{allSuggestions.map((suggestion, index) => (
+													<button
+														key={index}
+														type="button"
+														onClick={() => setInput(suggestion)}
+														className="px-3 py-2 text-sm rounded-lg border border-border bg-background hover:bg-accent hover:text-accent-foreground transition-colors text-foreground"
+													>
+														{suggestion}
+													</button>
+												))}
+											</div>
+										) : null;
+									})()}
 								</div>
 							) : (
 								messages.map((m, index) => (

package/src/plugins/ai-chat/client/components/chat-layout.tsx

@@ -2,57 +2,116 @@
 
 import { useState, useCallback } from "react";
 import { Button } from "@workspace/ui/components/button";
+import { Badge } from "@workspace/ui/components/badge";
 import {
 	Sheet,
 	SheetContent,
 	SheetTrigger,
 } from "@workspace/ui/components/sheet";
-import { Menu, PanelLeftClose, PanelLeft } from "lucide-react";
+import {
+	Menu,
+	PanelLeftClose,
+	PanelLeft,
+	Sparkles,
+	Trash2,
+	X,
+} from "lucide-react";
 import { cn } from "@workspace/ui/lib/utils";
 import { ChatSidebar } from "./chat-sidebar";
 import { ChatInterface } from "./chat-interface";
 import type { UIMessage } from "ai";
+import { usePageAIContext } from "../context/page-ai-context";
 
-export interface ChatLayoutProps {
+interface ChatLayoutBaseProps {
 	/** API base URL */
 	apiBaseURL: string;
 	/** API base path */
 	apiBasePath: string;
 	/** Current conversation ID (if viewing existing conversation) */
 	conversationId?: string;
-	/** Layout mode: 'full' for full page with sidebar, 'widget' for embeddable widget */
-	layout?: "full" | "widget";
 	/** Additional class name for the container */
 	className?: string;
-	/** Whether to show the sidebar (default: true for full layout) */
+	/** Whether to show the sidebar */
 	showSidebar?: boolean;
-	/** Height of the widget (only applies to widget layout) */
-	widgetHeight?: string | number;
 	/** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
 	initialMessages?: UIMessage[];
 	/** Called whenever messages change (for persistence). Only fires in public mode. */
 	onMessagesChange?: (messages: UIMessage[]) => void;
 }
 
+interface ChatLayoutWidgetProps extends ChatLayoutBaseProps {
+	/** Widget mode: compact embeddable panel with a floating trigger button */
+	layout: "widget";
+	/** Height of the widget panel. Default: `"600px"` */
+	widgetHeight?: string | number;
+	/** Width of the widget panel. Default: `"380px"` */
+	widgetWidth?: string | number;
+	/**
+	 * Whether the widget panel starts open. Default: `false`.
+	 * Set to `true` when embedding inside an already-open container such as a
+	 * Next.js intercepting-route modal — the panel will be immediately visible
+	 * without the user needing to click the trigger button.
+	 */
+	defaultOpen?: boolean;
+	/**
+	 * Whether to render the built-in floating trigger button. Default: `true`.
+	 * Set to `false` when you control open/close externally (e.g. a Next.js
+	 * parallel-route slot, a custom button, or a `router.back()` dismiss action)
+	 * so that the built-in button does not appear alongside your own UI.
+	 */
+	showTrigger?: boolean;
+}
+
+interface ChatLayoutFullProps extends ChatLayoutBaseProps {
+	/** Full-page mode with sidebar navigation (default) */
+	layout?: "full";
+}
+
+/** Props for the ChatLayout component */
+export type ChatLayoutProps = ChatLayoutWidgetProps | ChatLayoutFullProps;
+
 /**
  * ChatLayout component that provides a full-page chat experience with sidebar
  * or a compact widget mode for embedding.
  */
-export function ChatLayout({
-	apiBaseURL,
-	apiBasePath,
-	conversationId,
-	layout = "full",
-	className,
-	showSidebar = true,
-	widgetHeight = "600px",
-	initialMessages,
-	onMessagesChange,
-}: ChatLayoutProps) {
+export function ChatLayout(props: ChatLayoutProps) {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		conversationId,
+		layout = "full",
+		className,
+		showSidebar = true,
+		initialMessages,
+		onMessagesChange,
+	} = props;
+
+	// Widget-specific props — TypeScript narrows props to ChatLayoutWidgetProps here
+	const widgetHeight =
+		props.layout === "widget" ? (props.widgetHeight ?? "600px") : "600px";
+	const widgetWidth =
+		props.layout === "widget" ? (props.widgetWidth ?? "380px") : "380px";
+	const defaultOpen =
+		props.layout === "widget" ? (props.defaultOpen ?? false) : false;
+	const showTrigger =
+		props.layout === "widget" ? (props.showTrigger ?? true) : true;
+
 	const [sidebarOpen, setSidebarOpen] = useState(true);
 	const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
 	// Key to force ChatInterface remount when starting a new chat
 	const [chatResetKey, setChatResetKey] = useState(0);
+	// Widget open/closed state — starts with defaultOpen value
+	const [widgetOpen, setWidgetOpen] = useState(defaultOpen);
+	// Key to force widget ChatInterface remount on clear
+	const [widgetResetKey, setWidgetResetKey] = useState(0);
+	// Only mount the widget ChatInterface after the widget has been opened at least once.
+	// This ensures pageAIContext is already registered before ChatInterface first renders,
+	// so suggestion chips and tool hints appear immediately on first open.
+	// When defaultOpen is true the widget is pre-opened, so we mark it as ever-opened immediately.
+	const [widgetEverOpened, setWidgetEverOpened] = useState(defaultOpen);
+
+	// Read page AI context to show badge in header
+	const pageAIContext = usePageAIContext();
 
 	const apiPath = `${apiBaseURL}${apiBasePath}/chat`;
 
@@ -67,20 +126,83 @@ export function ChatLayout({
 
 	if (layout === "widget") {
 		return (
-			<div
-				className={cn(
-					"flex flex-col w-full border rounded-xl overflow-hidden bg-background shadow-sm",
-					className,
+			<div className={cn("flex flex-col items-end gap-3", className)}>
+				{/* Chat panel — always mounted to preserve conversation state, hidden when closed */}
+				<div
+					className={cn(
+						"flex flex-col border rounded-xl overflow-hidden bg-background shadow-xl",
+						widgetOpen ? "flex" : "hidden",
+					)}
+					style={{ height: widgetHeight, width: widgetWidth }}
+				>
+					{/* Widget header with page context badge and action buttons */}
+					<div className="flex items-center gap-1.5 px-3 py-1.5 border-b bg-muted/40">
+						<Sparkles className="h-3 w-3 text-muted-foreground" />
+						{pageAIContext ? (
+							<Badge
+								variant="secondary"
+								className="text-xs"
+								data-testid="page-context-badge"
+							>
+								{pageAIContext.routeName}
+							</Badge>
+						) : (
+							<span className="text-xs text-muted-foreground font-medium">
+								AI Chat
+							</span>
+						)}
+						<div className="flex-1" />
+						<Button
+							variant="ghost"
+							size="icon"
+							className="h-5 w-5"
+							onClick={() => setWidgetResetKey((prev) => prev + 1)}
+							aria-label="Clear chat"
+							title="Clear chat"
+						>
+							<Trash2 className="h-3.5 w-3.5" />
+						</Button>
+						<Button
+							variant="ghost"
+							size="icon"
+							className="h-5 w-5"
+							onClick={() => setWidgetOpen(false)}
+							aria-label="Close chat"
+						>
+							<X className="h-3.5 w-3.5" />
+						</Button>
+					</div>
+					{widgetEverOpened && (
+						<ChatInterface
+							key={`widget-${conversationId ?? "new"}-${widgetResetKey}`}
+							apiPath={apiPath}
+							id={conversationId}
+							variant="widget"
+							initialMessages={initialMessages}
+							onMessagesChange={onMessagesChange}
+						/>
+					)}
+				</div>
+
+				{/* Trigger button — rendered only when showTrigger is true */}
+				{showTrigger && (
+					<Button
+						size="icon"
+						className="h-12 w-12 rounded-full shadow-lg"
+						onClick={() => {
+							setWidgetOpen((prev) => !prev);
+							setWidgetEverOpened(true);
+						}}
+						aria-label={widgetOpen ? "Close chat" : "Open chat"}
+						data-testid="widget-trigger"
+					>
+						{widgetOpen ? (
+							<X className="h-5 w-5" />
+						) : (
+							<Sparkles className="h-5 w-5" />
+						)}
+					</Button>
 				)}
-				style={{ height: widgetHeight }}
-			>
-				<ChatInterface
-					apiPath={apiPath}
-					id={conversationId}
-					variant="widget"
-					initialMessages={initialMessages}
-					onMessagesChange={onMessagesChange}
-				/>
 			</div>
 		);
 	}
@@ -115,7 +237,7 @@ export function ChatLayout({
 			{/* Main Chat Area */}
 			<div className="flex-1 flex flex-col min-w-0">
 				{/* Header */}
-				<div className="flex items-center gap-2 p-2 border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+				<div className="flex items-center gap-2 p-2 border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
 					{/* Mobile menu button */}
 					{showSidebar && (
 						<Sheet open={mobileSidebarOpen} onOpenChange={setMobileSidebarOpen}>
@@ -159,6 +281,18 @@ export function ChatLayout({
 					)}
 
 					<div className="flex-1" />
+
+					{/* Page context badge — shown when a page has registered AI context */}
+					{pageAIContext && (
+						<Badge
+							variant="secondary"
+							className="text-xs gap-1 mr-2"
+							data-testid="page-context-badge"
+						>
+							<Sparkles className="h-3 w-3" />
+							{pageAIContext.routeName}
+						</Badge>
+					)}
 				</div>
 
 				<ChatInterface

package/src/plugins/ai-chat/client/components/chat-sidebar.tsx

@@ -163,7 +163,7 @@ export function ChatSidebar({
 			</div>
 
 			{/* Conversations List */}
-			<ScrollArea className="flex-1">
+			<ScrollArea className="flex-1 [&_[data-slot=scroll-area-viewport]>div]:!block">
 				<div className="p-2">
 					{isLoading ? (
 						<div className="p-4 text-center text-sm text-muted-foreground">