@btst/stack 4.1.0 → 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.Csi-4Mgz.d.cts → stack.CKc_Bais.d.cts}

@@ -1,13 +1,6 @@
 import { z } from 'zod';
 
 declare const createPostSchema: z.ZodObject<{
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -17,6 +10,13 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.Csi-4Mgz.d.mts → stack.CKc_Bais.d.mts}

@@ -1,13 +1,6 @@
 import { z } from 'zod';
 
 declare const createPostSchema: z.ZodObject<{
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -17,6 +10,13 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.Csi-4Mgz.d.ts → stack.CKc_Bais.d.ts}

@@ -1,13 +1,6 @@
 import { z } from 'zod';
 
 declare const createPostSchema: z.ZodObject<{
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -17,6 +10,13 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;