@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/ai-chat/client/localization/index.ts

@@ -1,3 +1,8 @@
+"use client";
+
+import { useCallback } from "react";
+import { useTranslate, type TranslateFn } from "@btst/stack/context";
+
 /**
  * AI Chat plugin localization strings
  */
@@ -25,6 +30,7 @@ export interface AiChatLocalization {
 	// Conversation actions
 	CONVERSATION_RENAME: string;
 	CONVERSATION_RENAME_PLACEHOLDER: string;
+	CONVERSATION_RENAME_DESCRIPTION: string;
 	CONVERSATION_RENAME_SAVE: string;
 	CONVERSATION_RENAME_CANCEL: string;
 	CONVERSATION_DELETE: string;
@@ -32,6 +38,11 @@ export interface AiChatLocalization {
 	CONVERSATION_DELETE_CONFIRM_DESCRIPTION: string;
 	CONVERSATION_DELETE_CONFIRM_BUTTON: string;
 	CONVERSATION_DELETE_CANCEL: string;
+	CONVERSATION_RENAME_SUCCESS: string;
+	CONVERSATION_RENAME_FAILURE: string;
+	CONVERSATION_DELETE_SUCCESS: string;
+	CONVERSATION_DELETE_FAILURE: string;
+	CONVERSATION_TITLE_REQUIRED: string;
 
 	// Image upload (legacy)
 	IMAGE_UPLOAD_BUTTON: string;
@@ -46,6 +57,10 @@ export interface AiChatLocalization {
 	FILE_UPLOAD_ERROR_TOO_LARGE: string;
 	FILE_UPLOAD_SUCCESS: string;
 	FILE_UPLOAD_FAILURE: string;
+	FILE_REMOVE: string;
+	FILE_FALLBACK_NAME: string;
+	IMAGE_ATTACHED_ALT: string;
+	IMAGE_GENERATED_ALT: string;
 
 	// Timestamps
 	TIME_JUST_NOW: string;
@@ -67,6 +82,26 @@ export interface AiChatLocalization {
 	A11Y_ASSISTANT_MESSAGE: string;
 	A11Y_COPY_CODE: string;
 	A11Y_CODE_COPIED: string;
+	A11Y_CONVERSATION_ACTIONS: string;
+	A11Y_CHAT_TITLE: string;
+	A11Y_CLEAR_CHAT: string;
+	A11Y_CLOSE_CHAT: string;
+	A11Y_OPEN_CHAT: string;
+	A11Y_OPEN_MENU: string;
+	A11Y_CLOSE_SIDEBAR: string;
+	A11Y_OPEN_SIDEBAR: string;
+
+	// Tool calls
+	TOOL_STATUS_RUNNING: string;
+	TOOL_STATUS_EXECUTING: string;
+	TOOL_STATUS_ERROR: string;
+	TOOL_STATUS_COMPLETE: string;
+	TOOL_STATUS_PENDING: string;
+	TOOL_INPUT: string;
+	TOOL_OUTPUT: string;
+	TOOL_ID: string;
+	TOOL_EXECUTION_FAILED: string;
+	TOOL_HANDLER_MISSING: string;
 }
 
 /**
@@ -98,6 +133,7 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 	// Conversation actions
 	CONVERSATION_RENAME: "Rename",
 	CONVERSATION_RENAME_PLACEHOLDER: "Enter conversation name",
+	CONVERSATION_RENAME_DESCRIPTION: "Enter a new title for this conversation.",
 	CONVERSATION_RENAME_SAVE: "Save",
 	CONVERSATION_RENAME_CANCEL: "Cancel",
 	CONVERSATION_DELETE: "Delete",
@@ -106,6 +142,11 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 		"Are you sure you want to delete this conversation? This action cannot be undone.",
 	CONVERSATION_DELETE_CONFIRM_BUTTON: "Delete",
 	CONVERSATION_DELETE_CANCEL: "Cancel",
+	CONVERSATION_RENAME_SUCCESS: "Conversation renamed",
+	CONVERSATION_RENAME_FAILURE: "Failed to rename conversation",
+	CONVERSATION_DELETE_SUCCESS: "Conversation deleted",
+	CONVERSATION_DELETE_FAILURE: "Failed to delete conversation",
+	CONVERSATION_TITLE_REQUIRED: "Title is required",
 
 	// Image upload (legacy)
 	IMAGE_UPLOAD_BUTTON: "Attach image",
@@ -120,6 +161,10 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 	FILE_UPLOAD_ERROR_TOO_LARGE: "File must be less than 10MB",
 	FILE_UPLOAD_SUCCESS: "File attached",
 	FILE_UPLOAD_FAILURE: "Failed to attach file",
+	FILE_REMOVE: "Remove file",
+	FILE_FALLBACK_NAME: "File",
+	IMAGE_ATTACHED_ALT: "Attached image {count}",
+	IMAGE_GENERATED_ALT: "Image {count}",
 
 	// Timestamps
 	TIME_JUST_NOW: "Just now",
@@ -141,6 +186,27 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 	A11Y_ASSISTANT_MESSAGE: "AI response",
 	A11Y_COPY_CODE: "Copy code",
 	A11Y_CODE_COPIED: "Code copied",
+	A11Y_CONVERSATION_ACTIONS: "Conversation actions",
+	A11Y_CHAT_TITLE: "AI Chat",
+	A11Y_CLEAR_CHAT: "Clear chat",
+	A11Y_CLOSE_CHAT: "Close chat",
+	A11Y_OPEN_CHAT: "Open chat",
+	A11Y_OPEN_MENU: "Open menu",
+	A11Y_CLOSE_SIDEBAR: "Close sidebar",
+	A11Y_OPEN_SIDEBAR: "Open sidebar",
+
+	// Tool calls
+	TOOL_STATUS_RUNNING: "Running...",
+	TOOL_STATUS_EXECUTING: "Executing...",
+	TOOL_STATUS_ERROR: "Error",
+	TOOL_STATUS_COMPLETE: "Complete",
+	TOOL_STATUS_PENDING: "Pending",
+	TOOL_INPUT: "Input",
+	TOOL_OUTPUT: "Output",
+	TOOL_ID: "ID: {id}",
+	TOOL_EXECUTION_FAILED: "Tool execution failed",
+	TOOL_HANDLER_MISSING:
+		'No client-side handler registered for tool "{toolName}". The page context may have changed while the response was streaming.',
 };
 
 /**
@@ -154,3 +220,47 @@ export function formatLocalized(
 		return values[key]?.toString() ?? match;
 	});
 }
+
+/**
+ * Resolves AI Chat strings with the legacy override taking precedence over
+ * the StackProvider i18n catalog. Legacy `{name}` placeholders remain
+ * supported while catalog defaults use `{{name}}` interpolation.
+ */
+export function resolveAiChatString(
+	t: TranslateFn,
+	localization: Partial<AiChatLocalization> | undefined,
+	legacyKey: keyof AiChatLocalization,
+	key: string,
+	defaultValue: string,
+	params?: Record<string, string | number>,
+): string {
+	const legacyValue = localization?.[legacyKey];
+	if (legacyValue !== undefined) {
+		return params ? formatLocalized(legacyValue, params) : legacyValue;
+	}
+	return t(key, defaultValue, params);
+}
+
+/** Client hook for resolving AI Chat catalog strings. */
+export function useAiChatTranslation(
+	localization?: Partial<AiChatLocalization>,
+) {
+	const t = useTranslate();
+	return useCallback(
+		(
+			legacyKey: keyof AiChatLocalization,
+			key: string,
+			defaultValue: string,
+			params?: Record<string, string | number>,
+		) =>
+			resolveAiChatString(
+				t,
+				localization,
+				legacyKey,
+				key,
+				defaultValue,
+				params,
+			),
+		[t, localization],
+	);
+}

package/src/plugins/ai-chat/client/overrides.ts

@@ -92,8 +92,8 @@ export interface RouteContext {
 /**
  * Overridable components and functions for the AI Chat plugin
  *
- * External consumers can provide their own implementations of these
- * to customize the behavior for their framework (Next.js, React Router, etc.)
+ * External consumers can provide their own implementations to customize
+ * plugin-specific components and behavior.
  */
 export interface AiChatPluginOverrides {
 	/**
@@ -102,38 +102,6 @@ export interface AiChatPluginOverrides {
 	 */
 	mode?: AiChatMode;
 
-	/**
-	 * API base URL
-	 */
-	apiBaseURL: string;
-
-	/**
-	 * API base path
-	 */
-	apiBasePath: string;
-
-	/**
-	 * Navigation function for programmatic navigation
-	 */
-	navigate: (path: string) => void | Promise<void>;
-
-	/**
-	 * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
-	 */
-	refresh?: () => void | Promise<void>;
-
-	/**
-	 * Link component for navigation
-	 */
-	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
-
-	/**
-	 * Image component for displaying images
-	 */
-	Image?: ComponentType<
-		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
-	>;
-
 	/**
 	 * Function used to upload a file and return its URL.
 	 * Called for images, PDFs, text files, and other supported file types.
@@ -220,22 +188,4 @@ export interface AiChatPluginOverrides {
 		error: Error,
 		context: RouteContext,
 	) => void | Promise<void>;
-
-	/**
-	 * Called before the chat page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforeChatPageRendered?: (context: RouteContext) => boolean;
-
-	/**
-	 * Called before a conversation page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param id - The conversation ID
-	 * @param context - Route context
-	 */
-	onBeforeConversationPageRendered?: (
-		id: string,
-		context: RouteContext,
-	) => boolean;
 }

package/src/plugins/ai-chat/client/plugin.tsx

@@ -1,15 +1,16 @@
 import {
 	defineClientPlugin,
 	createApiClient,
-	runClientHookWithShim,
+	createSanitizedSSRLoaderError,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { AiChatApiRouter } from "../api";
 import { createAiChatQueryKeys } from "../query-keys";
 import type { SerializedConversation, SerializedMessage } from "../types";
-import { ChatLayout } from "./components/chat-layout";
+import { ChatPageComponent } from "./components/pages/chat-page";
 import type { AiChatMode } from "./overrides";
 
 /**
@@ -96,7 +97,7 @@ export interface AiChatClientConfig {
 		/** Replaces the chat home page */
 		chat?: ComponentType;
 		/** Replaces the conversation page (authenticated mode only) */
-		chatConversation?: ComponentType<{ conversationId: string }>;
+		chatConversation?: ComponentType<{ params: { id: string } }>;
 	};
 }
 
@@ -171,24 +172,19 @@ function createConversationsLoader(config: AiChatClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<AiChatApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createAiChatQueryKeys(client, headers);
+			const listQuery = queries.conversations.list();
 
 			try {
 				// Before hook
 				if (hooks?.beforeLoadConversations) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadConversations!(context),
-						"Load prevented by beforeLoadConversations hook",
-					);
+					await hooks.beforeLoadConversations(context);
 				}
 
-				const client = createApiClient<AiChatApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-
-				const queries = createAiChatQueryKeys(client, headers);
-				const listQuery = queries.conversations.list();
-
 				await queryClient.prefetchQuery(listQuery);
 
 				// After hook
@@ -197,10 +193,7 @@ function createConversationsLoader(config: AiChatClientConfig) {
 						queryClient.getQueryData<SerializedConversation[]>(
 							listQuery.queryKey,
 						) || null;
-					await runClientHookWithShim(
-						() => hooks.afterLoadConversations!(conversations, context),
-						"Load prevented by afterLoadConversations hook",
-					);
+					await hooks.afterLoadConversations(conversations, context);
 				}
 
 				// Check for errors
@@ -213,6 +206,21 @@ function createConversationsLoader(config: AiChatClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/ai-chat] route.loader() failed — no server running at build time. " +
+							"AI Chat conversation history does not support SSG.",
+					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: listQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -235,27 +243,21 @@ function createConversationLoader(id: string, config: AiChatClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<AiChatApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createAiChatQueryKeys(client, headers);
+			const conversationQuery = queries.conversations.detail(id);
+			const listQuery = queries.conversations.list();
 
 			try {
 				// Before hook
 				if (hooks?.beforeLoadConversation) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadConversation!(id, context),
-						"Load prevented by beforeLoadConversation hook",
-					);
+					await hooks.beforeLoadConversation(id, context);
 				}
 
-				const client = createApiClient<AiChatApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-
-				const queries = createAiChatQueryKeys(client, headers);
-
 				// Prefetch both the conversation and the conversations list
-				const conversationQuery = queries.conversations.detail(id);
-				const listQuery = queries.conversations.list();
-
 				await Promise.all([
 					queryClient.prefetchQuery(conversationQuery),
 					queryClient.prefetchQuery(listQuery),
@@ -267,10 +269,7 @@ function createConversationLoader(id: string, config: AiChatClientConfig) {
 						queryClient.getQueryData<
 							SerializedConversation & { messages: SerializedMessage[] }
 						>(conversationQuery.queryKey) || null;
-					await runClientHookWithShim(
-						() => hooks.afterLoadConversation!(conversation, id, context),
-						"Load prevented by afterLoadConversation hook",
-					);
+					await hooks.afterLoadConversation(conversation, id, context);
 				}
 
 				// Check for errors
@@ -285,6 +284,30 @@ function createConversationLoader(id: string, config: AiChatClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/ai-chat] route.loader() failed — no server running at build time. " +
+							"AI Chat conversations do not support SSG.",
+					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await Promise.all([
+						queryClient.prefetchQuery({
+							queryKey: conversationQuery.queryKey,
+							queryFn: () => {
+								throw errToStore;
+							},
+							retry: false,
+						}),
+						queryClient.prefetchQuery({
+							queryKey: listQuery.queryKey,
+							queryFn: () => {
+								throw errToStore;
+							},
+							retry: false,
+						}),
+					]);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -392,25 +415,18 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 		return defineClientPlugin({
 			name: "ai-chat",
 
-			routes: () => ({
-				// Chat home - simple chat interface without history
-				chat: createRoute("/chat", () => {
-					const CustomChat = config.pageComponents?.chat;
-					return {
-						PageComponent:
-							CustomChat ??
-							(() => (
-								<ChatLayout
-									apiBaseURL={config.apiBaseURL}
-									apiBasePath={config.apiBasePath}
-									showSidebar={false}
-								/>
-							)),
-						loader: createConversationsLoader(config),
-						meta: createChatHomeMeta(config),
-					};
-				}),
-			}),
+			routes: () =>
+				defineRoutes(
+					{
+						// Chat home - simple chat interface without history
+						chat: defineRoute("/chat", {
+							page: () => <ChatPageComponent />,
+							loader: createConversationsLoader(config),
+							meta: createChatHomeMeta(config),
+						}),
+					},
+					{ pages: config.pageComponents },
+				),
 
 			sitemap: async () => [],
 		});
@@ -420,42 +436,28 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 	return defineClientPlugin({
 		name: "ai-chat",
 
-		routes: () => ({
-			// Chat home - new conversation or list
-			chat: createRoute("/chat", () => {
-				const CustomChat = config.pageComponents?.chat;
-				return {
-					PageComponent:
-						CustomChat ??
-						(() => (
-							<ChatLayout
-								apiBaseURL={config.apiBaseURL}
-								apiBasePath={config.apiBasePath}
-							/>
-						)),
-					loader: createConversationsLoader(config),
-					meta: createChatHomeMeta(config),
-				};
-			}),
-
-			// Existing conversation
-			chatConversation: createRoute("/chat/:id", ({ params }) => {
-				const CustomConversation = config.pageComponents?.chatConversation;
-				return {
-					PageComponent: CustomConversation
-						? () => <CustomConversation conversationId={params.id} />
-						: () => (
-								<ChatLayout
-									apiBaseURL={config.apiBaseURL}
-									apiBasePath={config.apiBasePath}
-									conversationId={params.id}
-								/>
-							),
-					loader: createConversationLoader(params.id, config),
-					meta: createConversationMeta(params.id, config),
-				};
-			}),
-		}),
+		routes: () =>
+			defineRoutes(
+				{
+					// Chat home - new conversation or list
+					chat: defineRoute("/chat", {
+						page: () => <ChatPageComponent />,
+						loader: createConversationsLoader(config),
+						meta: createChatHomeMeta(config),
+					}),
+
+					// Existing conversation
+					chatConversation: defineRoute("/chat/:id", {
+						page: ({ params }) => (
+							<ChatPageComponent conversationId={params.id} />
+						),
+						loader: ({ params }) =>
+							createConversationLoader(params.id, config)(),
+						meta: ({ params }) => createConversationMeta(params.id, config)(),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 
 		// Chat pages typically shouldn't be in sitemap, but we provide the option
 		sitemap: async () => {

package/src/plugins/ai-chat/query-keys.ts

@@ -1,87 +1,92 @@
 import {
-	mergeQueryKeys,
-	createQueryKeys,
-} from "@lukemorales/query-key-factory";
-import type { AiChatApiRouter } from "./api";
-import { createApiClient } from "@btst/stack/plugins/client";
+	createApiClient,
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type { AiChatApiRouter } from "./api/plugin";
 import type { SerializedConversation, SerializedMessage } from "./types";
 
-// Helper to check and handle error responses
-function handleResponse<T>(response: unknown): T {
-	if (
-		typeof response === "object" &&
-		response !== null &&
-		"error" in response
-	) {
-		const errorResponse = response as { error?: unknown };
-		if (errorResponse.error !== null && errorResponse.error !== undefined) {
-			const error = errorResponse.error;
-			if (error instanceof Error) {
-				throw error;
-			}
-			if (typeof error === "object" && error !== null) {
-				const errorObj = error as Record<string, unknown>;
-				const message =
-					(typeof errorObj.message === "string" ? errorObj.message : null) ||
-					(typeof errorObj.error === "string" ? errorObj.error : null) ||
-					JSON.stringify(error);
-				throw new Error(message);
-			}
-			throw new Error(String(error));
-		}
-	}
-	return (response as { data?: T }).data as T;
-}
-
 export type ConversationWithMessages = SerializedConversation & {
 	messages: SerializedMessage[];
 };
 
-export function createAiChatQueryKeys(
-	client: ReturnType<typeof createApiClient<AiChatApiRouter>>,
-	headers?: HeadersInit,
-) {
-	const conversations = createConversationsQueries(client, headers);
+export interface CreateConversationInput {
+	id?: string;
+	title?: string;
+}
 
-	return mergeQueryKeys(conversations);
+export interface RenameConversationInput {
+	id: string;
+	title: string;
 }
 
-function createConversationsQueries(
+/** Single source of truth for conversation HTTP mappings and cache behavior. */
+export const aiChatResources = {
+	conversations: {
+		queries: {
+			list: {
+				path: "/chat/conversations",
+				key: () => ["all"],
+				select: (data: any): SerializedConversation[] => data ?? [],
+			},
+			detail: {
+				path: "/chat/conversations/:id",
+				params: (id: string) => ({ id }),
+				key: (id: string) => [id],
+				select: (data: any): ConversationWithMessages | null => data,
+				skip: (id: string) => !id,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/chat/conversations",
+				method: "POST" as const,
+				input: (input: CreateConversationInput) => ({ body: input }),
+				select: (data: any): SerializedConversation | null => data,
+				invalidates: ["conversations.list"],
+			},
+			rename: {
+				path: "@put/chat/conversations/:id",
+				method: "PUT" as const,
+				input: (input: RenameConversationInput) => ({
+					params: { id: input.id },
+					body: { title: input.title },
+				}),
+				select: (data: any): SerializedConversation | null => data,
+				invalidates: ["conversations.list"],
+				setData: {
+					args: (result: SerializedConversation | null) =>
+						result?.id ? [result.id] : null,
+					updater: (
+						previous: unknown,
+						result: SerializedConversation | null,
+					) =>
+						previous && result
+							? { ...(previous as ConversationWithMessages), ...result }
+							: previous,
+				},
+			},
+			delete: {
+				path: "@delete/chat/conversations/:id",
+				method: "DELETE" as const,
+				input: (input: { id: string }) => ({ params: { id: input.id } }),
+				select: (data: any): { success: boolean } => data,
+				invalidates: ["conversations.list"],
+				removeData: {
+					args: (_result: { success: boolean }, input: { id: string }) => [
+						input.id,
+					],
+				},
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+export function createAiChatQueryKeys(
 	client: ReturnType<typeof createApiClient<AiChatApiRouter>>,
 	headers?: HeadersInit,
 ) {
-	return createQueryKeys("conversations", {
-		// List all conversations
-		list: () => ({
-			// NOTE: query-key-factory already namespaces as:
-			// ["conversations", "list", ...queryKey]
-			// so we use a stable marker (not "list") to avoid ["...","list","list"].
-			queryKey: ["all"],
-			queryFn: async () => {
-				const response = await client("/chat/conversations", {
-					method: "GET",
-					headers,
-				});
-
-				const data = handleResponse<SerializedConversation[] | null>(response);
-				return data ?? [];
-			},
-		}),
-
-		// Get single conversation with messages
-		detail: (id: string) => ({
-			queryKey: [id],
-			queryFn: async () => {
-				if (!id) return null;
-
-				const response = await client("/chat/conversations/:id", {
-					method: "GET",
-					params: { id },
-					headers,
-				});
-
-				return handleResponse<ConversationWithMessages | null>(response);
-			},
-		}),
-	});
+	return createResourceQueryKeys(client, aiChatResources, headers);
 }
+
+export type AiChatQueryKeys = ReturnType<typeof createAiChatQueryKeys>;

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

@@ -6,7 +6,7 @@ export const createConversationSchema = z.object({
 });
 
 export const updateConversationSchema = z.object({
-	title: z.string().optional(),
+	title: z.string().trim().min(1, "Title is required"),
 });
 
 export const chatRequestSchema = z.object({