@btst/stack 4.1.1 → 4.2.0

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

@@ -0,0 +1,46 @@
+"use client";
+
+import { createContext, useCallback, useContext, useRef } from "react";
+import { usePluginOverrides, useStack } from "@btst/stack/context";
+import { usePageAIContext } from "./page-ai-context";
+import { resolveAiChatMode, type AiChatPluginOverrides } from "../overrides";
+import type { AiChatAnalyticsEvent } from "../analytics";
+
+export const ChatAnalyticsPageKey = createContext<string | undefined>(
+	undefined,
+);
+type EventDetails<T> = T extends unknown
+	? Omit<T, "pageKey" | "routeName" | "mode">
+	: never;
+
+export function useChatAnalytics() {
+	const { onAnalyticsEvent } = usePluginOverrides<
+		AiChatPluginOverrides,
+		Partial<AiChatPluginOverrides>
+	>("aiChat", {});
+	const { plugins } = useStack();
+	const pageKey = useContext(ChatAnalyticsPageKey);
+	const routeName = usePageAIContext()?.routeName;
+	const latest = useRef({
+		onAnalyticsEvent,
+		pageKey,
+		routeName,
+		mode: resolveAiChatMode(plugins?.aiChat?.config),
+	});
+	latest.current = {
+		onAnalyticsEvent,
+		pageKey,
+		routeName,
+		mode: resolveAiChatMode(plugins?.aiChat?.config),
+	};
+	return useCallback((event: EventDetails<AiChatAnalyticsEvent>) => {
+		const { onAnalyticsEvent: callback, ...context } = latest.current;
+		try {
+			void Promise.resolve(callback?.({ ...context, ...event })).catch(
+				() => {},
+			);
+		} catch {
+			// Optional instrumentation must never interrupt chat interactions.
+		}
+	}, []);
+}

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

@@ -33,7 +33,8 @@ export interface PageAIContextConfig {
 	/**
 	 * 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.
+	 * Limited to 16,000 characters server-side. For longer content, pass a page
+	 * path and configure the backend pageContent resolver.
 	 */
 	pageDescription: string;
 
@@ -74,6 +75,11 @@ const PageAIAPIContext = createContext<PageAIAPIContextValue | null>(null);
  */
 const PageAIVersionContext = createContext<number>(0);
 
+/** Instance-local context used by ChatLayout; undefined inherits page registrations. */
+export const PageAIContextScope = createContext<
+	PageAIContextConfig | null | undefined
+>(undefined);
+
 /**
  * Provider that enables route-aware AI context across the app.
  *
@@ -235,6 +241,8 @@ export function usePageAIContext(): PageAIContextConfig | null {
 	// registers or unregisters context, then read the latest active config.
 	useContext(PageAIVersionContext);
 	const ctx = useContext(PageAIAPIContext);
+	const scoped = useContext(PageAIContextScope);
+	if (scoped !== undefined) return scoped;
 	if (!ctx) return null;
 	return ctx.getActive();
 }

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

@@ -24,3 +24,5 @@ export { ToolCallDisplay } from "./components/tool-call-display";
 
 // Re-export UIMessage type from AI SDK for consumer convenience
 export type { UIMessage } from "ai";
+
+export type { AiChatAnalyticsEvent } from "./analytics";

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

@@ -87,6 +87,10 @@ export interface AiChatLocalization {
 	A11Y_CLEAR_CHAT: string;
 	A11Y_CLOSE_CHAT: string;
 	A11Y_OPEN_CHAT: string;
+	A11Y_DISMISS_CHAT_TIP: string;
+	PAGE_CONTENT_READING: string;
+	PAGE_CONTENT_READ: string;
+	PAGE_CONTENT_ERROR: string;
 	A11Y_OPEN_MENU: string;
 	A11Y_CLOSE_SIDEBAR: string;
 	A11Y_OPEN_SIDEBAR: string;
@@ -191,6 +195,10 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 	A11Y_CLEAR_CHAT: "Clear chat",
 	A11Y_CLOSE_CHAT: "Close chat",
 	A11Y_OPEN_CHAT: "Open chat",
+	A11Y_DISMISS_CHAT_TIP: "Dismiss chat tip",
+	PAGE_CONTENT_READING: "Reading page content…",
+	PAGE_CONTENT_READ: "Read page content",
+	PAGE_CONTENT_ERROR: "Unable to read this page.",
 	A11Y_OPEN_MENU: "Open menu",
 	A11Y_CLOSE_SIDEBAR: "Close sidebar",
 	A11Y_OPEN_SIDEBAR: "Open sidebar",

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

@@ -1,3 +1,4 @@
+import type { AiChatAnalyticsEvent } from "./analytics";
 import type { ComponentType } from "react";
 import { normalizePath } from "@btst/stack/client";
 import type { AiChatLocalization } from "./localization";
@@ -13,6 +14,8 @@ export type AiChatMode = "authenticated" | "public";
 export interface AiChatProviderConfig {
 	/** Conversation behavior selected by `aiChatClientPlugin()`. */
 	readonly mode: AiChatMode;
+	/** Whether built-in page reader permission checks and status UI are enabled. */
+	readonly pageContent?: boolean;
 }
 
 /** Resolve the registered AI Chat client factory mode. */
@@ -143,6 +146,8 @@ export interface RouteContext {
  * plugin-specific components and behavior.
  */
 export interface AiChatPluginOverrides {
+	/** Optional content-free usage telemetry. Exceptions and rejections are isolated from chat. */
+	onAnalyticsEvent?: (event: AiChatAnalyticsEvent) => void | Promise<void>;
 	/**
 	 * Function used to upload a file and return its URL.
 	 * Called for images, PDFs, text files, and other supported file types.

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

@@ -67,6 +67,8 @@ export interface AiChatClientConfig {
 	 * @default 'authenticated'
 	 */
 	mode?: AiChatMode;
+	/** Enable built-in readPage permission checks and compact status alongside backend pageContent. */
+	pageContent?: boolean;
 
 	/** Optional SEO configuration for meta tags */
 	seo?: {
@@ -560,6 +562,7 @@ export const aiChatClientPlugin = (config: AiChatClientConfig = {}) =>
 		id: "aiChat",
 		providerConfig: {
 			mode: config.mode ?? "authenticated",
+			...(config.pageContent ? { pageContent: true } : {}),
 		} satisfies AiChatProviderConfig,
 		resolve: (runtime) => resolveAiChatClientPlugin({ ...config, runtime }),
 	});

package/dist/shared/{stack.lsbdKRj7.d.mts → stack.B8PG21zX.d.mts}

@@ -95,8 +95,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
     }>;
@@ -128,8 +128,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly createContentItem: better_call.StrictEndpoint<"/content/:typeSlug", {
         params: z.ZodObject<{
@@ -165,8 +165,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly updateContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
         params: z.ZodObject<{
@@ -203,8 +203,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly deleteContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
         params: z.ZodObject<{
@@ -248,8 +248,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
                 readonly id: string;
                 readonly slug: string;
                 readonly contentTypeId: string;
-                readonly data: string;
                 readonly authorId?: string | undefined;
+                readonly data: string;
             }[];
         };
         readonly contentType?: {
@@ -271,8 +271,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly listContentByRelation: better_call.StrictEndpoint<"/content/:typeSlug/by-relation", {
         params: z.ZodObject<{
@@ -314,8 +314,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
         readonly limit: number;
@@ -383,8 +383,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
         readonly limit: number;
@@ -459,8 +459,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
     }, false>;
@@ -493,8 +493,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly createContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -522,8 +522,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly updateContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -554,8 +554,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly deleteContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -598,8 +598,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
                 id: string;
                 slug: string;
                 contentTypeId: string;
-                data: string;
                 authorId?: string | undefined;
+                data: string;
             }[];
         };
         contentType?: {
@@ -619,8 +619,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly listContentByRelation: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -657,8 +657,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
         limit: number;
@@ -715,8 +715,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
         limit: number;

package/dist/shared/{stack.BuxUQqL8.d.ts → stack.CGmh-Lpe.d.ts}

@@ -127,11 +127,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
             readonly status: Form["status"];
             readonly createdAt: string;
             readonly updatedAt: string;
-            readonly schema: string;
             readonly id: string;
+            readonly name: string;
+            readonly schema: string;
             readonly description?: string | undefined;
             readonly slug: string;
-            readonly name: string;
             readonly successMessage?: string | undefined;
             readonly redirectUrl?: string | undefined;
             readonly createdBy?: string | undefined;
@@ -151,11 +151,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
         readonly status: Form["status"];
         readonly createdAt: string;
         readonly updatedAt: string;
-        readonly schema: string;
         readonly id: string;
+        readonly name: string;
+        readonly schema: string;
         readonly description?: string | undefined;
         readonly slug: string;
-        readonly name: string;
         readonly successMessage?: string | undefined;
         readonly redirectUrl?: string | undefined;
         readonly createdBy?: string | undefined;
@@ -171,11 +171,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
         readonly status: Form["status"];
         readonly createdAt: string;
         readonly updatedAt: string;
-        readonly schema: string;
         readonly id: string;
+        readonly name: string;
+        readonly schema: string;
         readonly description?: string | undefined;
         readonly slug: string;
-        readonly name: string;
         readonly successMessage?: string | undefined;
         readonly redirectUrl?: string | undefined;
         readonly createdBy?: string | undefined;
@@ -191,11 +191,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
         readonly status: Form["status"];
         readonly createdAt: string;
         readonly updatedAt: string;
-        readonly schema: string;
         readonly id: string;
+        readonly name: string;
+        readonly schema: string;
         readonly description?: string | undefined;
         readonly slug: string;
-        readonly name: string;
         readonly successMessage?: string | undefined;
         readonly redirectUrl?: string | undefined;
         readonly createdBy?: string | undefined;
@@ -225,11 +225,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
         readonly status: Form["status"];
         readonly createdAt: string;
         readonly updatedAt: string;
-        readonly schema: string;
         readonly id: string;
+        readonly name: string;
+        readonly schema: string;
         readonly description?: string | undefined;
         readonly slug: string;
-        readonly name: string;
         readonly successMessage?: string | undefined;
         readonly redirectUrl?: string | undefined;
         readonly createdBy?: string | undefined;
@@ -259,11 +259,11 @@ declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _
         readonly status: Form["status"];
         readonly createdAt: string;
         readonly updatedAt: string;
-        readonly schema: string;
         readonly id: string;
+        readonly name: string;
+        readonly schema: string;
         readonly description?: string | undefined;
         readonly slug: string;
-        readonly name: string;
         readonly successMessage?: string | undefined;
         readonly redirectUrl?: string | undefined;
         readonly createdBy?: string | undefined;

package/dist/shared/{stack.BggTHKlo.d.mts → stack.CTneIW0u.d.mts}

@@ -900,8 +900,8 @@ declare const blogResources: {
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({
@@ -1072,8 +1072,8 @@ declare function createBlogQueryKeys(client: ReturnType<typeof createApiClient<B
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({

package/dist/shared/{stack.CtrnoQgH.d.cts → stack.Ce6V7eDj.d.cts}

@@ -900,8 +900,8 @@ declare const blogResources: {
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({
@@ -1072,8 +1072,8 @@ declare function createBlogQueryKeys(client: ReturnType<typeof createApiClient<B
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({

package/dist/shared/{stack.BMlTZnZp.d.ts → stack.CyalJ0j6.d.ts}

@@ -95,8 +95,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
     }>;
@@ -128,8 +128,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly createContentItem: better_call.StrictEndpoint<"/content/:typeSlug", {
         params: z.ZodObject<{
@@ -165,8 +165,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly updateContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
         params: z.ZodObject<{
@@ -203,8 +203,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly deleteContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
         params: z.ZodObject<{
@@ -248,8 +248,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
                 readonly id: string;
                 readonly slug: string;
                 readonly contentTypeId: string;
-                readonly data: string;
                 readonly authorId?: string | undefined;
+                readonly data: string;
             }[];
         };
         readonly contentType?: {
@@ -271,8 +271,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         readonly id: string;
         readonly slug: string;
         readonly contentTypeId: string;
-        readonly data: string;
         readonly authorId?: string | undefined;
+        readonly data: string;
     }>;
     readonly listContentByRelation: better_call.StrictEndpoint<"/content/:typeSlug/by-relation", {
         params: z.ZodObject<{
@@ -314,8 +314,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
         readonly limit: number;
@@ -383,8 +383,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             readonly id: string;
             readonly slug: string;
             readonly contentTypeId: string;
-            readonly data: string;
             readonly authorId?: string | undefined;
+            readonly data: string;
         }[];
         readonly total: number;
         readonly limit: number;
@@ -459,8 +459,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
     }, false>;
@@ -493,8 +493,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly createContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -522,8 +522,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly updateContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -554,8 +554,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly deleteContentItem: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -598,8 +598,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
                 id: string;
                 slug: string;
                 contentTypeId: string;
-                data: string;
                 authorId?: string | undefined;
+                data: string;
             }[];
         };
         contentType?: {
@@ -619,8 +619,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
         id: string;
         slug: string;
         contentTypeId: string;
-        data: string;
         authorId?: string | undefined;
+        data: string;
     }, false>;
     readonly listContentByRelation: _btst_stack_plugins_api.Operation<z.ZodObject<{
         typeSlug: z.ZodString;
@@ -657,8 +657,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
         limit: number;
@@ -715,8 +715,8 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
             id: string;
             slug: string;
             contentTypeId: string;
-            data: string;
             authorId?: string | undefined;
+            data: string;
         }[];
         total: number;
         limit: number;

package/dist/shared/{stack.lPKwd_v0.d.ts → stack.D5b9l24t.d.ts}

@@ -900,8 +900,8 @@ declare const blogResources: {
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({
@@ -1072,8 +1072,8 @@ declare function createBlogQueryKeys(client: ReturnType<typeof createApiClient<B
                 method: "POST";
                 input: (vars: PostCreateInput) => {
                     body: {
-                        published: boolean;
                         title: string;
+                        published: boolean;
                         content: string;
                         excerpt: string;
                         tags: ({