@btst/stack 2.3.0 → 2.4.0

package/dist/shared/{stack.BIXEI6v_.d.mts → stack.heOA9gzA.d.cts}

@@ -1,7 +1,7 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { QueryClient } from '@tanstack/react-query';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { P as Post, T as Tag, c as createPostSchema, u as updatePostSchema, S as SerializedPost, a as SerializedTag } from './stack.CBON0dWL.mjs';
+import { P as Post, T as Tag, c as createPostSchema, u as updatePostSchema, S as SerializedPost, a as SerializedTag } from './stack.BQmuNl5p.cjs';
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
 import * as better_call from 'better-call';
 import { Adapter } from '@btst/db';
@@ -218,11 +218,11 @@ declare const blogBackendPlugin: (hooks?: BlogBackendHooks) => _btst_stack_plugi
                 name: z.ZodString;
                 slug: z.ZodString;
             }, z.core.$strip>]>>>>;
+            title: z.ZodString;
             slug: z.ZodOptional<z.ZodString>;
-            publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
             createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
             updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-            title: z.ZodString;
+            publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
             content: z.ZodString;
             excerpt: z.ZodString;
             image: z.ZodOptional<z.ZodString>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -163,6 +163,16 @@
         "default": "./dist/plugins/ai-chat/client/hooks/index.cjs"
       }
     },
+    "./plugins/ai-chat/client/context": {
+      "import": {
+        "types": "./dist/plugins/ai-chat/client/context/page-ai-context.d.ts",
+        "default": "./dist/plugins/ai-chat/client/context/page-ai-context.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/ai-chat/client/context/page-ai-context.d.cts",
+        "default": "./dist/plugins/ai-chat/client/context/page-ai-context.cjs"
+      }
+    },
     "./plugins/ai-chat/css": "./dist/plugins/ai-chat/style.css",
     "./plugins/blog/css": "./dist/plugins/blog/style.css",
     "./plugins/cms/api": {
@@ -392,6 +402,9 @@
       "plugins/ai-chat/client/hooks": [
         "./dist/plugins/ai-chat/client/hooks/index.d.ts"
       ],
+      "plugins/ai-chat/client/context": [
+        "./dist/plugins/ai-chat/client/context/page-ai-context.d.ts"
+      ],
       "plugins/cms/api": [
         "./dist/plugins/cms/api/index.d.ts"
       ],

package/src/client/components/compose.tsx

@@ -89,10 +89,13 @@ export function ComposedRoute({
 }) {
 	if (PageComponent) {
 		const content = <PageComponent {...props} />;
-		// Avoid server-side skeletons: only show loading fallback in the browser
-		const isBrowser = typeof window !== "undefined";
-		const suspenseFallback =
-			isBrowser && LoadingComponent ? <LoadingComponent /> : null;
+		// Always provide the same fallback on server and client — using
+		// `typeof window !== "undefined"` here would produce a different JSX tree
+		// on each side, shifting React's useId() counter and causing hydration
+		// mismatches in any descendant that uses Radix (Select, Dialog, etc.).
+		// If the Suspense boundary never actually suspends during SSR (data is
+		// prefetched), React won't emit the fallback into the HTML anyway.
+		const suspenseFallback = LoadingComponent ? <LoadingComponent /> : null;
 
 		// If an ErrorComponent is provided (which itself may be lazy), ensure we have
 		// a Suspense boundary that can handle both the page content and the lazy error UI

package/src/plugins/ai-chat/api/page-tools.ts

@@ -0,0 +1,111 @@
+import { tool } from "ai";
+import type { Tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Maps each built-in page tool to the route names that are permitted to request it.
+ *
+ * The server cross-checks the `routeName` field sent with every chat request
+ * against this allowlist before including a built-in tool in the streamText call.
+ * A tool is only activated when both conditions are true:
+ *   1. The tool name appears in the request's `availableTools` list, AND
+ *   2. The request's `routeName` is in this tool's allowlist.
+ *
+ * Consumer-defined tools (via `clientToolSchemas`) are not validated here —
+ * the consumer is responsible for their own access control.
+ */
+export const BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST: Record<string, string[]> = {
+	/** Blog new-post and edit-post pages */
+	fillBlogForm: ["blog-new-post", "blog-edit-post", "newPost", "editPost"],
+	/** UI builder edit page */
+	updatePageLayers: ["ui-builder-edit-page"],
+};
+
+/**
+ * Built-in client-side-only tool schemas for route-aware AI context.
+ *
+ * These tools have no `execute` function — they are handled on the client side
+ * via the onToolCall handler in ChatInterface, which dispatches to handlers
+ * registered by pages via useRegisterPageAIContext.
+ *
+ * Consumers can add their own tool schemas via `clientToolSchemas` in AiChatBackendConfig.
+ */
+export const BUILT_IN_PAGE_TOOL_SCHEMAS: Record<string, Tool> = {
+	/**
+	 * Fill in the blog post editor form fields.
+	 * Registered by blog new/edit page via useRegisterPageAIContext.
+	 */
+	fillBlogForm: tool({
+		description:
+			"Fill in the blog post editor form fields. Call this when the user asks to write, draft, or populate a blog post. You can fill any combination of title, content, excerpt, and tags.",
+		inputSchema: z.object({
+			title: z.string().optional().describe("The post title"),
+			content: z
+				.string()
+				.optional()
+				.describe(
+					"Full markdown content for the post body. Use proper markdown formatting with headings, lists, etc.",
+				),
+			excerpt: z
+				.string()
+				.optional()
+				.describe("A short summary/excerpt of the post (1-2 sentences)"),
+			tags: z
+				.array(z.string())
+				.optional()
+				.describe("Array of tag names to apply to the post"),
+		}),
+	}),
+
+	/**
+	 * Replace the UI builder page layers with new ones.
+	 * Registered by the UI builder edit page via useRegisterPageAIContext.
+	 */
+	updatePageLayers: tool({
+		description: `Replace the UI builder page component layers. Call this when the user asks to change, add, redesign, or update the page layout and components.
+
+Rules:
+- Provide the COMPLETE layer tree, not a partial diff. The entire tree will replace the current layers.
+- Only use component types that appear in the "Available Component Types" list in the page context.
+- Every layer must have a unique \`id\` string (e.g. "hero-section", "card-title-1").
+- The \`type\` field must exactly match a name from the component registry (e.g. "div", "Button", "Card", "Flexbox").
+- The \`name\` field is the human-readable label shown in the layers panel.
+- \`props\` contains component-specific props (className uses Tailwind classes).
+- \`children\` is either an array of child ComponentLayer objects, or a plain string for text content.
+- Use \`Flexbox\` or \`Grid\` for layout instead of raw div flex/grid when possible.
+- Preserve any layers the user has not asked to change — read the current layers from the page context first.
+- ALWAYS use shadcn/ui semantic color tokens in className (e.g. bg-background, bg-card, bg-primary, text-foreground, text-muted-foreground, text-primary-foreground, border-border) instead of hardcoded Tailwind colors like bg-white, bg-gray-*, text-black, etc. This ensures the UI automatically adapts to light and dark themes.`,
+		inputSchema: z.object({
+			layers: z
+				.array(
+					z.object({
+						id: z.string().describe("Unique identifier for this layer"),
+						type: z
+							.string()
+							.describe(
+								"Component type — must match a key in the component registry (e.g. 'div', 'Button', 'Card', 'Flexbox')",
+							),
+						name: z
+							.string()
+							.describe(
+								"Human-readable display name shown in the layers panel",
+							),
+						props: z
+							.record(z.string(), z.any())
+							.describe(
+								"Component props object. Use Tailwind classes for className. See the component registry for valid props per type.",
+							),
+						children: z
+							.any()
+							.optional()
+							.describe(
+								"Child layers (array of ComponentLayer) or plain text string",
+							),
+					}),
+				)
+				.describe(
+					"Complete replacement layer tree. Must include ALL layers for the page, not just changed ones.",
+				),
+		}),
+	}),
+};

package/src/plugins/ai-chat/api/plugin.ts

@@ -17,6 +17,10 @@ import {
 } from "../schemas";
 import type { Conversation, ConversationWithMessages, Message } from "../types";
 import { getAllConversations, getConversationById } from "./getters";
+import {
+	BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST,
+	BUILT_IN_PAGE_TOOL_SCHEMAS,
+} from "./page-tools";
 
 /**
  * Context passed to AI Chat API hooks
@@ -98,6 +102,23 @@ export interface AiChatBackendHooks {
 		context: ChatApiContext,
 	) => Promise<boolean> | boolean;
 
+	/**
+	 * Called after the structural routeName/allowlist validation, with the list
+	 * of tool names that passed. Return a filtered subset to further restrict
+	 * which tools the LLM sees, or return [] to suppress all page tools.
+	 * Throw an Error to abort the entire chat request with a 403 response.
+	 * Not called when no tools passed the structural validation step.
+	 *
+	 * @param toolNames - Names that passed the routeName allowlist check
+	 * @param routeName - routeName claimed by the request (may be undefined)
+	 * @param context   - Full request context (headers, body, etc.)
+	 */
+	onBeforeToolsActivated?: (
+		toolNames: string[],
+		routeName: string | undefined,
+		context: ChatApiContext,
+	) => Promise<string[]> | string[];
+
 	// ============== Lifecycle Hooks ==============
 
 	/**
@@ -232,6 +253,32 @@ export type AiChatMode = "authenticated" | "public";
 /**
  * Configuration for AI Chat backend plugin
  */
+/**
+ * Extracts only the literal (non-index-signature) keys from a type.
+ * For `Record<string, T>` this resolves to `never`, so collision checks are
+ * skipped when the tools map is typed with a broad string index.
+ */
+type KnownKeys<T> = {
+	[K in keyof T]: string extends K ? never : K;
+}[keyof T];
+
+/**
+ * Ensures `TClientTools` has no keys that are also literal keys in `TTools`.
+ * Colliding keys are mapped to `never`, which produces a compile-time error
+ * at the point of the duplicate key. When `TTools` uses a string index
+ * signature the check is skipped to avoid false positives.
+ */
+type NoKeyCollision<
+	TTools,
+	TClientTools extends Record<string, Tool>,
+> = KnownKeys<TTools> & keyof TClientTools extends never
+	? TClientTools
+	: {
+			[K in keyof TClientTools]: K extends KnownKeys<TTools>
+				? never // duplicate of a server-side tool — remove from clientToolSchemas
+				: TClientTools[K];
+		};
+
 export interface AiChatBackendConfig {
 	/**
 	 * The language model to use for chat completions.
@@ -269,6 +316,31 @@ export interface AiChatBackendConfig {
 	 */
 	tools?: Record<string, Tool>;
 
+	/**
+	 * Enable route-aware page tools.
+	 * When true, the server will include tool schemas for client-side page tools
+	 * (e.g. fillBlogForm, updatePageLayers) based on the availableTools list
+	 * sent with each request.
+	 * @default false
+	 */
+	enablePageTools?: boolean;
+
+	/**
+	 * Custom client-side tool schemas for non-BTST pages.
+	 * Merged with built-in page tool schemas (fillBlogForm, updatePageLayers).
+	 * Only included when enablePageTools is true and the tool name appears in
+	 * the availableTools list sent with the request.
+	 *
+	 * @example
+	 * clientToolSchemas: {
+	 *   addToCart: tool({
+	 *     description: "Add current product to cart",
+	 *     parameters: z.object({ quantity: z.number().int().min(1) }),
+	 *   }),
+	 * }
+	 */
+	clientToolSchemas?: Record<string, Tool>;
+
 	/**
 	 * Optional hooks for customizing plugin behavior
 	 */
@@ -282,7 +354,15 @@ export interface AiChatBackendConfig {
  *
  * @param config - Configuration including model, tools, and optional hooks
  */
-export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
+export const aiChatBackendPlugin = <
+	TTools extends Record<string, Tool> = Record<never, Tool>,
+	TClientTools extends Record<string, Tool> = Record<never, Tool>,
+>(
+	config: Omit<AiChatBackendConfig, "tools" | "clientToolSchemas"> & {
+		tools?: TTools;
+		clientToolSchemas?: NoKeyCollision<TTools, TClientTools>;
+	},
+) =>
 	defineBackendPlugin({
 		name: "ai-chat",
 		// Always include db schema - in public mode we just don't use it
@@ -350,7 +430,13 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 					body: chatRequestSchema,
 				},
 				async (ctx) => {
-					const { messages: rawMessages, conversationId } = ctx.body;
+					const {
+						messages: rawMessages,
+						conversationId,
+						pageContext,
+						availableTools,
+						routeName,
+					} = ctx.body;
 					const uiMessages = rawMessages as UIMessage[];
 
 					const context: ChatApiContext = {
@@ -388,22 +474,107 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 						// Convert UIMessages to CoreMessages for streamText
 						const modelMessages = convertToModelMessages(uiMessages);
 
-						// Add system prompt if configured
-						const messagesWithSystem = config.systemPrompt
+						// Build system prompt: base config + optional page context
+						const pageContextContent =
+							pageContext && pageContext.trim()
+								? `\n\nCurrent page context:\n${pageContext}`
+								: "";
+						const systemContent = config.systemPrompt
+							? `${config.systemPrompt}${pageContextContent}`
+							: pageContextContent || undefined;
+
+						const messagesWithSystem = systemContent
 							? [
-									{ role: "system" as const, content: config.systemPrompt },
+									{ role: "system" as const, content: systemContent },
 									...modelMessages,
 								]
 							: modelMessages;
 
+						// Merge page tool schemas when enablePageTools is on.
+						// Built-in schemas are only included when the request's routeName is in
+						// the tool's allowlist — this prevents a page from claiming tools that
+						// are intended for a different route (e.g. requesting updatePageLayers
+						// from a blog page). Consumer clientToolSchemas are trusted as-is.
+						const activePageTools: Record<string, Tool> =
+							config.enablePageTools &&
+							availableTools &&
+							availableTools.length > 0
+								? (() => {
+										const consumerSchemas: Record<string, Tool> =
+											(config.clientToolSchemas as Record<string, Tool>) ?? {};
+										return Object.fromEntries(
+											availableTools
+												.filter((name) => {
+													// Built-in tool: require routeName to be in its allowlist
+													if (name in BUILT_IN_PAGE_TOOL_SCHEMAS) {
+														const allowed =
+															BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST[name];
+														return (
+															allowed &&
+															routeName &&
+															allowed.includes(routeName)
+														);
+													}
+													// Consumer-defined tool: allow if schema is registered
+													return name in consumerSchemas;
+												})
+												.map((name) => {
+													const schema =
+														BUILT_IN_PAGE_TOOL_SCHEMAS[name] ??
+														consumerSchemas[name]!;
+													return [name, schema];
+												}),
+										);
+									})()
+								: {};
+
+						// Consumer hook: user-level tool authorization.
+						// Runs after the structural routeName allowlist check.
+						// A thrown Error is caught and returned as a 403 response,
+						// consistent with how onBeforeChat handles return false → 403.
+						if (
+							config.hooks?.onBeforeToolsActivated &&
+							Object.keys(activePageTools).length > 0
+						) {
+							try {
+								const allowed = await config.hooks.onBeforeToolsActivated(
+									Object.keys(activePageTools),
+									routeName,
+									context,
+								);
+								const allowedSet = new Set(allowed);
+								for (const key of Object.keys(activePageTools)) {
+									if (!allowedSet.has(key)) {
+										delete activePageTools[key];
+									}
+								}
+							} catch (hookError) {
+								throw ctx.error(403, {
+									message:
+										hookError instanceof Error
+											? hookError.message
+											: "Unauthorized: Tool activation denied",
+								});
+							}
+						}
+
+						// Page tools are layered under server-side tools so that a
+						// clientToolSchemas entry with the same name as a tool in
+						// config.tools never silently drops its `execute` function.
+						// Server-side tools always win on collision.
+						const mergedTools =
+							Object.keys(activePageTools).length > 0
+								? { ...activePageTools, ...config.tools }
+								: config.tools;
+
 						// PUBLIC MODE: Stream without persistence
 						if (isPublicMode) {
 							const result = streamText({
 								model: config.model,
 								messages: messagesWithSystem,
-								tools: config.tools,
+								tools: mergedTools,
 								// Enable multi-step tool calls if tools are configured
-								...(config.tools ? { stopWhen: stepCountIs(5) } : {}),
+								...(mergedTools ? { stopWhen: stepCountIs(5) } : {}),
 							});
 
 							return result.toUIMessageStreamResponse({
@@ -557,9 +728,9 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 						const result = streamText({
 							model: config.model,
 							messages: messagesWithSystem,
-							tools: config.tools,
+							tools: mergedTools,
 							// Enable multi-step tool calls if tools are configured
-							...(config.tools ? { stopWhen: stepCountIs(5) } : {}),
+							...(mergedTools ? { stopWhen: stepCountIs(5) } : {}),
 							onFinish: async (completion: { text: string }) => {
 								// Wrap in try-catch since this runs after the response is sent
 								// and errors would otherwise become unhandled promise rejections

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

@@ -260,14 +260,14 @@ export function ChatInput({
 				)}
 
 				{/* Text Input */}
-				<div className="relative flex-1">
+				<div className="relative flex-1 min-w-0">
 					<Textarea
 						value={input}
 						onChange={handleInputChange}
 						onKeyDown={handleKeyDown}
 						placeholder={placeholder || localization.CHAT_PLACEHOLDER}
 						className={cn(
-							"resize-none pr-12",
+							"resize-none pr-12 max-w-full",
 							isCompact
 								? "min-h-[40px] max-h-[120px] py-2"
 								: "min-h-[50px] max-h-[200px] py-3",