@btst/stack 2.2.0 → 2.4.0

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">

package/src/plugins/ai-chat/client/context/page-ai-context.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useId,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+
+/**
+ * A client-side tool handler — receives the AI's tool call args and returns a result.
+ * The result is sent back to the model so it can continue the conversation.
+ */
+export type PageAIClientTool = (
+	args: any,
+) => Promise<{ success: boolean; message?: string }>;
+
+/**
+ * Configuration registered by a page to provide AI context and capabilities.
+ * Any component in the tree can call useRegisterPageAIContext with this config.
+ */
+export interface PageAIContextConfig {
+	/**
+	 * Identifier for the current route/page (e.g. "blog-post", "ui-builder-edit-page").
+	 * Shown as a badge in the chat header.
+	 */
+	routeName: string;
+
+	/**
+	 * Human-readable description of the current page and its content.
+	 * Injected into the AI system prompt so it understands what the user is looking at.
+	 * Capped at 8,000 characters server-side.
+	 */
+	pageDescription: string;
+
+	/**
+	 * Optional suggested prompts shown as quick-action chips in the chat empty state.
+	 * These augment (not replace) any static suggestions configured in plugin overrides.
+	 */
+	suggestions?: string[];
+
+	/**
+	 * Client-side tool handlers keyed by tool name.
+	 * When the AI calls a tool by this name, the handler is invoked with the tool args.
+	 * The result is sent back to the model via addToolResult.
+	 *
+	 * Tool schemas must be registered server-side via enablePageTools + clientToolSchemas
+	 * in aiChatBackendPlugin (built-in tools like fillBlogForm are pre-registered).
+	 */
+	clientTools?: Record<string, PageAIClientTool>;
+}
+
+interface PageAIAPIContextValue {
+	register: (id: string, config: PageAIContextConfig) => void;
+	unregister: (id: string) => void;
+	getActive: () => PageAIContextConfig | null;
+}
+
+/**
+ * Stable API context — holds register/unregister/getActive.
+ * Never changes reference, so useRegisterPageAIContext effects don't re-run
+ * simply because the provider re-rendered after a bumpVersion call.
+ */
+const PageAIAPIContext = createContext<PageAIAPIContextValue | null>(null);
+
+/**
+ * Reactive version context — incremented on every register/unregister.
+ * Consumers of usePageAIContext subscribe here so they re-render when
+ * registrations change and re-call getActive() to pick up the latest config.
+ */
+const PageAIVersionContext = createContext<number>(0);
+
+/**
+ * Provider that enables route-aware AI context across the app.
+ *
+ * Place this at the root layout — above all StackProviders — so it spans
+ * both your main app tree and any chat modals rendered as parallel/intercept routes.
+ *
+ * @example
+ * // app/layout.tsx
+ * import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
+ *
+ * export default function RootLayout({ children }) {
+ *   return <PageAIContextProvider>{children}</PageAIContextProvider>
+ * }
+ */
+export function PageAIContextProvider({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	// Map from stable registration id → config
+	// Using useRef so mutations don't trigger re-renders of the provider itself
+	const registrationsRef = useRef<Map<string, PageAIContextConfig>>(new Map());
+	// Track insertion order so the last-registered (most specific) wins
+	const insertionOrderRef = useRef<string[]>([]);
+
+	// Version counter — bumped on every register/unregister so consumers re-read
+	const [version, setVersion] = useState(0);
+	const bumpVersion = useCallback(() => setVersion((v) => v + 1), []);
+
+	const register = useCallback(
+		(id: string, config: PageAIContextConfig) => {
+			registrationsRef.current.set(id, config);
+			// Move to end to mark as most recent
+			insertionOrderRef.current = insertionOrderRef.current.filter(
+				(k) => k !== id,
+			);
+			insertionOrderRef.current.push(id);
+			bumpVersion();
+		},
+		[bumpVersion],
+	);
+
+	const unregister = useCallback(
+		(id: string) => {
+			registrationsRef.current.delete(id);
+			insertionOrderRef.current = insertionOrderRef.current.filter(
+				(k) => k !== id,
+			);
+			bumpVersion();
+		},
+		[bumpVersion],
+	);
+
+	const getActive = useCallback((): PageAIContextConfig | null => {
+		const order = insertionOrderRef.current;
+		if (order.length === 0) return null;
+		// Last registered wins (most deeply nested / most recently mounted)
+		const lastId = order[order.length - 1];
+		if (!lastId) return null;
+		return registrationsRef.current.get(lastId) ?? null;
+	}, []);
+
+	// Memoize the API object so its reference never changes — this is what
+	// breaks the infinite loop: useRegisterPageAIContext has `ctx` (the API)
+	// in its effect deps, and a stable reference means the effect won't re-run
+	// just because the provider re-rendered after bumpVersion().
+	const api = useMemo(
+		() => ({ register, unregister, getActive }),
+		[register, unregister, getActive],
+	);
+
+	return (
+		<PageAIAPIContext.Provider value={api}>
+			<PageAIVersionContext.Provider value={version}>
+				{children}
+			</PageAIVersionContext.Provider>
+		</PageAIAPIContext.Provider>
+	);
+}
+
+/**
+ * Register page AI context from any component.
+ * The registration is cleaned up automatically when the component unmounts.
+ *
+ * Pass `null` to conditionally disable context (e.g. while data is loading).
+ *
+ * @example
+ * // Blog post page
+ * useRegisterPageAIContext(post ? {
+ *   routeName: "blog-post",
+ *   pageDescription: `Blog post: "${post.title}"\n\n${post.content?.slice(0, 16000)}`,
+ *   suggestions: ["Summarize this post", "What are the key takeaways?"],
+ * } : null)
+ */
+export function useRegisterPageAIContext(
+	config: PageAIContextConfig | null,
+): void {
+	// Use the stable API context — its reference never changes, so adding it
+	// to the dependency array below does NOT cause the effect to re-run after
+	// bumpVersion() fires. This breaks the register → bumpVersion → re-render
+	// → effect re-run → register loop that caused "Maximum update depth exceeded".
+	const ctx = useContext(PageAIAPIContext);
+	const id = useId();
+
+	// Always keep the ref current so clientTools handlers are never stale.
+	// Updating a ref during render is safe — the value is visible to any effect
+	// that runs in the same commit.
+	const configRef = useRef<PageAIContextConfig | null>(config);
+	configRef.current = config;
+
+	useEffect(() => {
+		if (!ctx || !configRef.current) return;
+		// Register a live proxy that always reads from configRef. This ensures
+		// clientTools handlers are fresh even when the effect doesn't re-run —
+		// for example when a handler's closure captures new state but the
+		// serializable fields (routeName, pageDescription, suggestions) are unchanged.
+		// JSON.stringify silently strips function values, so clientTools would be
+		// invisible to a plain JSON.stringify(config) dependency check.
+		ctx.register(id, {
+			get routeName() {
+				return configRef.current?.routeName ?? "";
+			},
+			get pageDescription() {
+				return configRef.current?.pageDescription ?? "";
+			},
+			get suggestions() {
+				return configRef.current?.suggestions;
+			},
+			get clientTools() {
+				return configRef.current?.clientTools;
+			},
+		});
+		return () => {
+			ctx.unregister(id);
+		};
+		// Track serializable fields individually. JSON.stringify on the whole config
+		// would silently strip clientTools (functions), making handler changes invisible.
+		// Handler freshness is provided by the ref-proxy above instead.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [
+		ctx,
+		id,
+		config === null,
+		config?.routeName,
+		config?.pageDescription,
+		JSON.stringify(config?.suggestions),
+	]);
+}
+
+/**
+ * Read the currently active page AI context.
+ * Returns null when no page has registered context, or when PageAIContextProvider
+ * is not in the tree.
+ *
+ * Used internally by ChatInterface to inject context into requests.
+ */
+export function usePageAIContext(): PageAIContextConfig | null {
+	// Subscribe to the version counter so this hook re-runs whenever a page
+	// registers or unregisters context, then read the latest active config.
+	useContext(PageAIVersionContext);
+	const ctx = useContext(PageAIAPIContext);
+	if (!ctx) return null;
+	return ctx.getActive();
+}

package/src/plugins/ai-chat/schemas.ts

@@ -37,4 +37,20 @@ export const chatRequestSchema = z.object({
 	),
 	conversationId: z.string().optional(),
 	model: z.string().optional(),
+	/**
+	 * Description of the current page context, injected into the AI system prompt.
+	 * Sent by ChatInterface when a page has registered context via useRegisterPageAIContext.
+	 */
+	pageContext: z.string().max(16000).optional(),
+	/**
+	 * Names of client-side tools currently available on the page.
+	 * The server includes matching tool schemas in the streamText call.
+	 */
+	availableTools: z.array(z.string()).optional(),
+	/**
+	 * The routeName registered by the page via useRegisterPageAIContext.
+	 * Cross-validated server-side against each built-in tool's route allowlist
+	 * to prevent a page from claiming tools intended for a different route.
+	 */
+	routeName: z.string().optional(),
 });

package/src/plugins/blog/api/index.ts

@@ -6,4 +6,6 @@ export {
 	type PostListParams,
 	type PostListResult,
 } from "./getters";
+export { serializePost, serializeTag } from "./serializers";
+export { BLOG_QUERY_KEYS } from "./query-key-defs";
 export { createBlogQueryKeys } from "../query-keys";

package/src/plugins/blog/api/plugin.ts

@@ -7,6 +7,90 @@ import type { Post, PostWithPostTag, Tag } from "../types";
 import { slugify } from "../utils";
 import { createPostSchema, updatePostSchema } from "../schemas";
 import { getAllPosts, getPostBySlug, getAllTags } from "./getters";
+import { BLOG_QUERY_KEYS } from "./query-key-defs";
+import { serializePost, serializeTag } from "./serializers";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the blog plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type BlogRouteKey =
+	| "posts"
+	| "drafts"
+	| "post"
+	| "tag"
+	| "newPost"
+	| "editPost";
+
+/**
+ * Overloaded signature for `prefetchForRoute`.
+ * TypeScript enforces the correct params for each routeKey at call sites.
+ */
+interface BlogPrefetchForRoute {
+	(key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
+	(
+		key: "post" | "editPost",
+		qc: QueryClient,
+		params: { slug: string },
+	): Promise<void>;
+	(key: "tag", qc: QueryClient, params: { tagSlug: string }): Promise<void>;
+}
+
+function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: BlogRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "posts":
+			case "drafts": {
+				const published = key === "posts";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published, limit: 10 }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(BLOG_QUERY_KEYS.postsList({ published, limit: 10 }), {
+					pages: [result.items.map(serializePost)],
+					pageParams: [0],
+				});
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			case "post":
+			case "editPost": {
+				const slug = params?.slug ?? "";
+				if (slug) {
+					const post = await getPostBySlug(adapter, slug);
+					qc.setQueryData(
+						BLOG_QUERY_KEYS.postDetail(slug),
+						post ? serializePost(post) : null,
+					);
+				}
+				break;
+			}
+			case "tag": {
+				const tagSlug = params?.tagSlug ?? "";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published: true, limit: 10, tagSlug }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(
+					BLOG_QUERY_KEYS.postsList({ published: true, limit: 10, tagSlug }),
+					{
+						pages: [result.items.map(serializePost)],
+						pageParams: [0],
+					},
+				);
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			default:
+				break;
+		}
+	} as BlogPrefetchForRoute;
+}
 
 export const PostListQuerySchema = z.object({
 	slug: z.string().optional(),
@@ -174,6 +258,7 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 				getAllPosts(adapter, params),
 			getPostBySlug: (slug: string) => getPostBySlug(adapter, slug),
 			getAllTags: () => getAllTags(adapter),
+			prefetchForRoute: createBlogPrefetchForRoute(adapter),
 		}),
 
 		routes: (adapter: Adapter) => {

package/src/plugins/blog/api/query-key-defs.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal query key constants for the blog plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface PostsListDiscriminator {
+	query: string | undefined;
+	limit: number;
+	published: boolean;
+	tagSlug: string | undefined;
+}
+
+/**
+ * Builds the discriminator object used as the cache key for the posts list.
+ * Mirrors the inline object in createPostsQueries so both paths stay in sync.
+ */
+export function postsListDiscriminator(params: {
+	published: boolean;
+	limit?: number;
+	tagSlug?: string;
+	query?: string;
+}): PostsListDiscriminator {
+	return {
+		query:
+			params.query !== undefined && params.query.trim() === ""
+				? undefined
+				: params.query,
+		limit: params.limit ?? 10,
+		published: params.published,
+		tagSlug: params.tagSlug,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const BLOG_QUERY_KEYS = {
+	postsList: (params: {
+		published: boolean;
+		limit?: number;
+		tagSlug?: string;
+	}) => ["posts", "list", postsListDiscriminator(params)] as const,
+
+	postDetail: (slug: string) => ["posts", "detail", slug] as const,
+
+	tagsList: () => ["tags", "list", "tags"] as const,
+};