@btst/stack 4.1.1 → 4.2.0

package/dist/plugins/form-builder/client/hooks/index.d.ts

@@ -8,7 +8,7 @@ import '@btst/stack/context';
 import '../../permissions.js';
 import 'zod';
 import '@btst/stack/plugins/client';
-import '../../../../shared/stack.BuxUQqL8.js';
+import '../../../../shared/stack.CGmh-Lpe.js';
 import '@btst/db';
 import 'zod/v4/core';
 import 'better-call';

package/dist/plugins/form-builder/query-keys.d.cts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.CX83YNuS.cjs';
+import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.zch70Loj.cjs';
 import { P as PaginatedForms, S as SerializedForm, a as SerializedFormSubmission, e as PaginatedFormSubmissions, d as SerializedFormSubmissionWithData } from '../../shared/stack.v2O65JqF.cjs';
 import { StackIdentity } from '@btst/stack/context';
 import '@btst/stack/plugins/api';

package/dist/plugins/form-builder/query-keys.d.mts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.Egr3RWhA.mjs';
+import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.Doy2_wgl.mjs';
 import { P as PaginatedForms, S as SerializedForm, a as SerializedFormSubmission, e as PaginatedFormSubmissions, d as SerializedFormSubmissionWithData } from '../../shared/stack.OYT8WU4n.mjs';
 import { StackIdentity } from '@btst/stack/context';
 import '@btst/stack/plugins/api';

package/dist/plugins/form-builder/query-keys.d.ts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.BuxUQqL8.js';
+import { F as FormsListDiscriminator, S as SubmissionsListDiscriminator, a as FormBuilderApiRouter } from '../../shared/stack.CGmh-Lpe.js';
 import { P as PaginatedForms, S as SerializedForm, a as SerializedFormSubmission, e as PaginatedFormSubmissions, d as SerializedFormSubmissionWithData } from '../../shared/stack.C3bU9w6L.js';
 import { StackIdentity } from '@btst/stack/context';
 import '@btst/stack/plugins/api';

package/dist/plugins/ui-builder/client/hooks/index.d.cts

@@ -9,7 +9,7 @@ import '../../../../shared/stack.fdi94T4S.cjs';
 import 'react-hook-form';
 import 'react/jsx-runtime';
 import '@btst/stack/plugins/client';
-import '../../../../shared/stack.BV0uNV4f.cjs';
+import '../../../../shared/stack.D6Pg-ufX.cjs';
 import '@btst/stack/plugins/api';
 import '../../../../authorization/index.cjs';
 import 'better-call';

package/dist/plugins/ui-builder/client/hooks/index.d.mts

@@ -9,7 +9,7 @@ import '../../../../shared/stack.fdi94T4S.mjs';
 import 'react-hook-form';
 import 'react/jsx-runtime';
 import '@btst/stack/plugins/client';
-import '../../../../shared/stack.lsbdKRj7.mjs';
+import '../../../../shared/stack.B8PG21zX.mjs';
 import '@btst/stack/plugins/api';
 import '../../../../authorization/index.mjs';
 import 'better-call';

package/dist/plugins/ui-builder/client/hooks/index.d.ts

@@ -9,7 +9,7 @@ import '../../../../shared/stack.fdi94T4S.js';
 import 'react-hook-form';
 import 'react/jsx-runtime';
 import '@btst/stack/plugins/client';
-import '../../../../shared/stack.BMlTZnZp.js';
+import '../../../../shared/stack.CyalJ0j6.js';
 import '@btst/stack/plugins/api';
 import '../../../../authorization/index.js';
 import 'better-call';

package/dist/plugins/ui-builder/client/index.d.cts

@@ -15,7 +15,7 @@ import '../../../shared/stack.B3_aDcYL.cjs';
 import 'react-hook-form';
 import '@tanstack/react-query';
 import '@btst/stack/plugins/client/hooks';
-import '../../../shared/stack.BV0uNV4f.cjs';
+import '../../../shared/stack.D6Pg-ufX.cjs';
 import '@btst/stack/plugins/api';
 import '../../../authorization/index.cjs';
 import 'better-call';

package/dist/plugins/ui-builder/client/index.d.mts

@@ -15,7 +15,7 @@ import '../../../shared/stack.B3_aDcYL.mjs';
 import 'react-hook-form';
 import '@tanstack/react-query';
 import '@btst/stack/plugins/client/hooks';
-import '../../../shared/stack.lsbdKRj7.mjs';
+import '../../../shared/stack.B8PG21zX.mjs';
 import '@btst/stack/plugins/api';
 import '../../../authorization/index.mjs';
 import 'better-call';

package/dist/plugins/ui-builder/client/index.d.ts

@@ -15,7 +15,7 @@ import '../../../shared/stack.B3_aDcYL.js';
 import 'react-hook-form';
 import '@tanstack/react-query';
 import '@btst/stack/plugins/client/hooks';
-import '../../../shared/stack.BMlTZnZp.js';
+import '../../../shared/stack.CyalJ0j6.js';
 import '@btst/stack/plugins/api';
 import '../../../authorization/index.js';
 import 'better-call';

package/dist/plugins/ui-builder/query-keys.d.cts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.BV0uNV4f.cjs';
+import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.D6Pg-ufX.cjs';
 import { C as ComponentLayer, V as Variable } from '../../shared/stack.DmpPDPxA.cjs';
 import { P as PaginatedContentItems, a as SerializedContentItemWithType } from '../../shared/stack.B3_aDcYL.cjs';
 import { UIBuilderPageSchemaType, PaginatedUIBuilderPages, SerializedUIBuilderPage } from './index.cjs';

package/dist/plugins/ui-builder/query-keys.d.mts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.lsbdKRj7.mjs';
+import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.B8PG21zX.mjs';
 import { C as ComponentLayer, V as Variable } from '../../shared/stack.B1srlBud.mjs';
 import { P as PaginatedContentItems, a as SerializedContentItemWithType } from '../../shared/stack.B3_aDcYL.mjs';
 import { UIBuilderPageSchemaType, PaginatedUIBuilderPages, SerializedUIBuilderPage } from './index.mjs';

package/dist/plugins/ui-builder/query-keys.d.ts

@@ -1,6 +1,6 @@
 import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.BMlTZnZp.js';
+import { a as ContentListDiscriminator, C as CMSApiRouter } from '../../shared/stack.CyalJ0j6.js';
 import { C as ComponentLayer, V as Variable } from '../../shared/stack.BK9Z2dcL.js';
 import { P as PaginatedContentItems, a as SerializedContentItemWithType } from '../../shared/stack.B3_aDcYL.js';
 import { UIBuilderPageSchemaType, PaginatedUIBuilderPages, SerializedUIBuilderPage } from './index.js';

package/dist/shared/{stack.B5yPgHsp.d.mts → stack.B7Mj74BQ.d.mts}

@@ -41,6 +41,20 @@ type SerializedMessage = Omit<Message, "createdAt"> & {
     createdAt: string;
 };
 
+/** Server-owned content loader for the standard readPage tool. */
+interface AiChatPageContentConfig {
+    /** Allowed page paths. Validated before resolve; paths are also limited to 16,000 characters. */
+    pathSchema: z.ZodType<string, string>;
+    /**
+     * Load the complete page as JSON-serializable reference material. Enforce
+     * publication and access rules here using the request context. Return null
+     * when unavailable. BTST never fetches URLs or truncates the returned content.
+     */
+    resolve: (path: string, context: ChatApiContext<ChatOperationInput>) => unknown | Promise<unknown>;
+    /** Optional model-facing description of the supported page types. */
+    description?: string;
+}
+
 type AiChatAccess = "authorized" | "public";
 /** Runtime input for one conversation operation. */
 declare const ConversationOperationInputSchema: z.ZodObject<{
@@ -208,6 +222,8 @@ interface AiChatBackendConfig {
     access?: AiChatAccess;
     systemPrompt?: string;
     tools?: Record<string, Tool>;
+    /** Enable the standard readPage server tool for full page content. Reserves the readPage tool name. */
+    pageContent?: AiChatPageContentConfig;
     enablePageTools?: boolean;
     clientToolSchemas?: Record<string, Tool>;
     hooks?: AiChatBackendHooks;
@@ -503,5 +519,5 @@ declare function createAiChatQueryKeys(client: ReturnType<typeof createApiClient
 }>;
 type AiChatQueryKeys = ReturnType<typeof createAiChatQueryKeys>;
 
-export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as n, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as o, AiChatOperationError as p, ChatOperationInputSchema as q, ConversationOperationInputSchema as r };
-export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatAccess as k, AiChatBackendHooks as l, ChatApiContext as m };
+export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as o, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as p, AiChatOperationError as q, ChatOperationInputSchema as r, ConversationOperationInputSchema as s };
+export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatPageContentConfig as k, AiChatAccess as l, AiChatBackendHooks as m, ChatApiContext as n };

package/dist/shared/{stack.rVF0f509.d.mts → stack.C-eQN_Jt.d.ts}

@@ -1,6 +1,39 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { UIMessage } from 'ai';
-import { ComponentType, FormEvent } from 'react';
+import { ComponentType, CSSProperties, FormEvent } from 'react';
+import { PageAIContextConfig } from '../plugins/ai-chat/client/context/page-ai-context.js';
+
+/** Content-free usage events. No prompts, answers, page descriptions, or tool outputs. */
+type AiChatAnalyticsEvent = {
+    /** Caller-supplied page identity; omit sensitive values. */
+    pageKey?: string;
+    /** Page label, without its description or document content. */
+    routeName?: string;
+    /** Registered client mode, not an assertion about the viewer's identity. */
+    mode: AiChatMode;
+} & ({
+    type: "widget_opened" | "widget_closed" | "intro_tip_shown" | "conversation_cleared";
+} | {
+    type: "intro_tip_dismissed";
+    reason: "timeout" | "manual" | "open";
+} | {
+    type: "suggestion_selected";
+    index: number;
+} | {
+    type: "message_submitted";
+    inputKind: "typed" | "suggestion" | "edit" | "retry";
+    inputLength: number;
+    messageCount: number;
+    attachmentCount: number;
+} | {
+    type: "response_completed";
+    durationMs: number;
+    outputLength: number;
+    toolCallCount: number;
+} | {
+    type: "response_failed";
+    durationMs: number;
+});
 
 /**
  * AI Chat plugin localization strings
@@ -69,6 +102,10 @@ 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;
@@ -94,6 +131,8 @@ type AiChatMode = "authenticated" | "public";
 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;
 }
 /**
  * State of a tool call execution
@@ -152,6 +191,8 @@ interface RouteContext {
  * plugin-specific components and behavior.
  */
 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.
@@ -255,6 +296,15 @@ interface ChatLayoutBaseProps {
     conversationId?: string;
     /** Additional class name for the container */
     className?: string;
+    /** Additional container styles, including application-specific floating offsets. */
+    style?: CSSProperties;
+    /** Instance-local context. Omit to inherit page registrations; null disables them. */
+    pageContext?: PageAIContextConfig | null;
+    /**
+     * Page identity. Changing it resets the panel, tip, and conversation, stopping
+     * an active stream. Supply initialMessages/conversationId for this page only.
+     */
+    pageKey?: string;
     /** Whether to show the sidebar */
     showSidebar?: boolean;
     /** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
@@ -267,10 +317,16 @@ interface ChatLayoutBaseProps {
 interface ChatLayoutWidgetProps extends ChatLayoutBaseProps {
     /** Widget mode: compact embeddable panel with a floating trigger button */
     layout: "widget";
-    /** Height of the widget panel. Default: `"600px"` */
+    /** Height of the widget panel. Default: `"min(600px, calc(100dvh - 112px))"` */
     widgetHeight?: string | number;
-    /** Width of the widget panel. Default: `"380px"` */
+    /** Width of the widget panel. Default: `"min(380px, calc(100vw - 32px))"` */
     widgetWidth?: string | number;
+    /** Fix the widget to the bottom right. Default: false (embedded). Override offsets with className or style. */
+    floating?: boolean;
+    /** Optional dismissible introduction shown while the widget is closed. */
+    introTip?: string;
+    /** Milliseconds before hiding the introduction. Default: 6000. */
+    introTipDuration?: number;
     /**
      * Whether the widget panel starts open. Default: `false`.
      * Set to `true` when embedding inside an already-open container such as a
@@ -355,4 +411,4 @@ declare function ChatInput({ input, handleInputChange, handleSubmit, isLoading,
 declare function ToolCallDisplay({ toolCallId, toolName, state, input, output, errorText, isLoading, }: ToolCallProps): react_jsx_runtime.JSX.Element;
 
 export { ChatInterface as C, DEFAULT_ALLOWED_FILE_TYPES as D, ChatLayout as f, ChatSidebar as h, ChatMessage as i, ChatInput as j, ToolCallDisplay as k };
-export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g };
+export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g, AiChatAnalyticsEvent as l };

package/dist/shared/{stack.rVF0f509.d.ts → stack.C5FZr-jJ.d.mts}

@@ -1,6 +1,39 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { UIMessage } from 'ai';
-import { ComponentType, FormEvent } from 'react';
+import { ComponentType, CSSProperties, FormEvent } from 'react';
+import { PageAIContextConfig } from '../plugins/ai-chat/client/context/page-ai-context.mjs';
+
+/** Content-free usage events. No prompts, answers, page descriptions, or tool outputs. */
+type AiChatAnalyticsEvent = {
+    /** Caller-supplied page identity; omit sensitive values. */
+    pageKey?: string;
+    /** Page label, without its description or document content. */
+    routeName?: string;
+    /** Registered client mode, not an assertion about the viewer's identity. */
+    mode: AiChatMode;
+} & ({
+    type: "widget_opened" | "widget_closed" | "intro_tip_shown" | "conversation_cleared";
+} | {
+    type: "intro_tip_dismissed";
+    reason: "timeout" | "manual" | "open";
+} | {
+    type: "suggestion_selected";
+    index: number;
+} | {
+    type: "message_submitted";
+    inputKind: "typed" | "suggestion" | "edit" | "retry";
+    inputLength: number;
+    messageCount: number;
+    attachmentCount: number;
+} | {
+    type: "response_completed";
+    durationMs: number;
+    outputLength: number;
+    toolCallCount: number;
+} | {
+    type: "response_failed";
+    durationMs: number;
+});
 
 /**
  * AI Chat plugin localization strings
@@ -69,6 +102,10 @@ 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;
@@ -94,6 +131,8 @@ type AiChatMode = "authenticated" | "public";
 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;
 }
 /**
  * State of a tool call execution
@@ -152,6 +191,8 @@ interface RouteContext {
  * plugin-specific components and behavior.
  */
 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.
@@ -255,6 +296,15 @@ interface ChatLayoutBaseProps {
     conversationId?: string;
     /** Additional class name for the container */
     className?: string;
+    /** Additional container styles, including application-specific floating offsets. */
+    style?: CSSProperties;
+    /** Instance-local context. Omit to inherit page registrations; null disables them. */
+    pageContext?: PageAIContextConfig | null;
+    /**
+     * Page identity. Changing it resets the panel, tip, and conversation, stopping
+     * an active stream. Supply initialMessages/conversationId for this page only.
+     */
+    pageKey?: string;
     /** Whether to show the sidebar */
     showSidebar?: boolean;
     /** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
@@ -267,10 +317,16 @@ interface ChatLayoutBaseProps {
 interface ChatLayoutWidgetProps extends ChatLayoutBaseProps {
     /** Widget mode: compact embeddable panel with a floating trigger button */
     layout: "widget";
-    /** Height of the widget panel. Default: `"600px"` */
+    /** Height of the widget panel. Default: `"min(600px, calc(100dvh - 112px))"` */
     widgetHeight?: string | number;
-    /** Width of the widget panel. Default: `"380px"` */
+    /** Width of the widget panel. Default: `"min(380px, calc(100vw - 32px))"` */
     widgetWidth?: string | number;
+    /** Fix the widget to the bottom right. Default: false (embedded). Override offsets with className or style. */
+    floating?: boolean;
+    /** Optional dismissible introduction shown while the widget is closed. */
+    introTip?: string;
+    /** Milliseconds before hiding the introduction. Default: 6000. */
+    introTipDuration?: number;
     /**
      * Whether the widget panel starts open. Default: `false`.
      * Set to `true` when embedding inside an already-open container such as a
@@ -355,4 +411,4 @@ declare function ChatInput({ input, handleInputChange, handleSubmit, isLoading,
 declare function ToolCallDisplay({ toolCallId, toolName, state, input, output, errorText, isLoading, }: ToolCallProps): react_jsx_runtime.JSX.Element;
 
 export { ChatInterface as C, DEFAULT_ALLOWED_FILE_TYPES as D, ChatLayout as f, ChatSidebar as h, ChatMessage as i, ChatInput as j, ToolCallDisplay as k };
-export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g };
+export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g, AiChatAnalyticsEvent as l };

package/dist/shared/{stack.3Sr6qRtT.d.ts → stack.DBH1Bjko.d.ts}

@@ -41,6 +41,20 @@ type SerializedMessage = Omit<Message, "createdAt"> & {
     createdAt: string;
 };
 
+/** Server-owned content loader for the standard readPage tool. */
+interface AiChatPageContentConfig {
+    /** Allowed page paths. Validated before resolve; paths are also limited to 16,000 characters. */
+    pathSchema: z.ZodType<string, string>;
+    /**
+     * Load the complete page as JSON-serializable reference material. Enforce
+     * publication and access rules here using the request context. Return null
+     * when unavailable. BTST never fetches URLs or truncates the returned content.
+     */
+    resolve: (path: string, context: ChatApiContext<ChatOperationInput>) => unknown | Promise<unknown>;
+    /** Optional model-facing description of the supported page types. */
+    description?: string;
+}
+
 type AiChatAccess = "authorized" | "public";
 /** Runtime input for one conversation operation. */
 declare const ConversationOperationInputSchema: z.ZodObject<{
@@ -208,6 +222,8 @@ interface AiChatBackendConfig {
     access?: AiChatAccess;
     systemPrompt?: string;
     tools?: Record<string, Tool>;
+    /** Enable the standard readPage server tool for full page content. Reserves the readPage tool name. */
+    pageContent?: AiChatPageContentConfig;
     enablePageTools?: boolean;
     clientToolSchemas?: Record<string, Tool>;
     hooks?: AiChatBackendHooks;
@@ -503,5 +519,5 @@ declare function createAiChatQueryKeys(client: ReturnType<typeof createApiClient
 }>;
 type AiChatQueryKeys = ReturnType<typeof createAiChatQueryKeys>;
 
-export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as n, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as o, AiChatOperationError as p, ChatOperationInputSchema as q, ConversationOperationInputSchema as r };
-export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatAccess as k, AiChatBackendHooks as l, ChatApiContext as m };
+export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as o, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as p, AiChatOperationError as q, ChatOperationInputSchema as r, ConversationOperationInputSchema as s };
+export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatPageContentConfig as k, AiChatAccess as l, AiChatBackendHooks as m, ChatApiContext as n };

package/dist/shared/{stack.C4oVW2qK.d.cts → stack.Dgt3MCtW.d.cts}

@@ -41,6 +41,20 @@ type SerializedMessage = Omit<Message, "createdAt"> & {
     createdAt: string;
 };
 
+/** Server-owned content loader for the standard readPage tool. */
+interface AiChatPageContentConfig {
+    /** Allowed page paths. Validated before resolve; paths are also limited to 16,000 characters. */
+    pathSchema: z.ZodType<string, string>;
+    /**
+     * Load the complete page as JSON-serializable reference material. Enforce
+     * publication and access rules here using the request context. Return null
+     * when unavailable. BTST never fetches URLs or truncates the returned content.
+     */
+    resolve: (path: string, context: ChatApiContext<ChatOperationInput>) => unknown | Promise<unknown>;
+    /** Optional model-facing description of the supported page types. */
+    description?: string;
+}
+
 type AiChatAccess = "authorized" | "public";
 /** Runtime input for one conversation operation. */
 declare const ConversationOperationInputSchema: z.ZodObject<{
@@ -208,6 +222,8 @@ interface AiChatBackendConfig {
     access?: AiChatAccess;
     systemPrompt?: string;
     tools?: Record<string, Tool>;
+    /** Enable the standard readPage server tool for full page content. Reserves the readPage tool name. */
+    pageContent?: AiChatPageContentConfig;
     enablePageTools?: boolean;
     clientToolSchemas?: Record<string, Tool>;
     hooks?: AiChatBackendHooks;
@@ -503,5 +519,5 @@ declare function createAiChatQueryKeys(client: ReturnType<typeof createApiClient
 }>;
 type AiChatQueryKeys = ReturnType<typeof createAiChatQueryKeys>;
 
-export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as n, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as o, AiChatOperationError as p, ChatOperationInputSchema as q, ConversationOperationInputSchema as r };
-export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatAccess as k, AiChatBackendHooks as l, ChatApiContext as m };
+export { UpdateConversationOperationInputSchema as U, aiChatIdentityKey as d, aiChatResources as e, createAiChatQueryKeys as f, aiChatBackendPlugin as i, AI_CHAT_OPERATION_INVENTORY as o, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY as p, AiChatOperationError as q, ChatOperationInputSchema as r, ConversationOperationInputSchema as s };
+export type { AiChatIdentityPartition as A, ConversationWithMessages as C, Message as M, RenameConversationInput as R, SerializedConversation as S, SerializedMessage as a, CreateConversationInput as b, Conversation as c, AiChatQueryKeys as g, AiChatBackendConfig as h, AiChatApiRouter as j, AiChatPageContentConfig as k, AiChatAccess as l, AiChatBackendHooks as m, ChatApiContext as n };

package/dist/shared/{stack.rVF0f509.d.cts → stack.xAiy2VtO.d.cts}

@@ -1,6 +1,39 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { UIMessage } from 'ai';
-import { ComponentType, FormEvent } from 'react';
+import { ComponentType, CSSProperties, FormEvent } from 'react';
+import { PageAIContextConfig } from '../plugins/ai-chat/client/context/page-ai-context.cjs';
+
+/** Content-free usage events. No prompts, answers, page descriptions, or tool outputs. */
+type AiChatAnalyticsEvent = {
+    /** Caller-supplied page identity; omit sensitive values. */
+    pageKey?: string;
+    /** Page label, without its description or document content. */
+    routeName?: string;
+    /** Registered client mode, not an assertion about the viewer's identity. */
+    mode: AiChatMode;
+} & ({
+    type: "widget_opened" | "widget_closed" | "intro_tip_shown" | "conversation_cleared";
+} | {
+    type: "intro_tip_dismissed";
+    reason: "timeout" | "manual" | "open";
+} | {
+    type: "suggestion_selected";
+    index: number;
+} | {
+    type: "message_submitted";
+    inputKind: "typed" | "suggestion" | "edit" | "retry";
+    inputLength: number;
+    messageCount: number;
+    attachmentCount: number;
+} | {
+    type: "response_completed";
+    durationMs: number;
+    outputLength: number;
+    toolCallCount: number;
+} | {
+    type: "response_failed";
+    durationMs: number;
+});
 
 /**
  * AI Chat plugin localization strings
@@ -69,6 +102,10 @@ 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;
@@ -94,6 +131,8 @@ type AiChatMode = "authenticated" | "public";
 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;
 }
 /**
  * State of a tool call execution
@@ -152,6 +191,8 @@ interface RouteContext {
  * plugin-specific components and behavior.
  */
 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.
@@ -255,6 +296,15 @@ interface ChatLayoutBaseProps {
     conversationId?: string;
     /** Additional class name for the container */
     className?: string;
+    /** Additional container styles, including application-specific floating offsets. */
+    style?: CSSProperties;
+    /** Instance-local context. Omit to inherit page registrations; null disables them. */
+    pageContext?: PageAIContextConfig | null;
+    /**
+     * Page identity. Changing it resets the panel, tip, and conversation, stopping
+     * an active stream. Supply initialMessages/conversationId for this page only.
+     */
+    pageKey?: string;
     /** Whether to show the sidebar */
     showSidebar?: boolean;
     /** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
@@ -267,10 +317,16 @@ interface ChatLayoutBaseProps {
 interface ChatLayoutWidgetProps extends ChatLayoutBaseProps {
     /** Widget mode: compact embeddable panel with a floating trigger button */
     layout: "widget";
-    /** Height of the widget panel. Default: `"600px"` */
+    /** Height of the widget panel. Default: `"min(600px, calc(100dvh - 112px))"` */
     widgetHeight?: string | number;
-    /** Width of the widget panel. Default: `"380px"` */
+    /** Width of the widget panel. Default: `"min(380px, calc(100vw - 32px))"` */
     widgetWidth?: string | number;
+    /** Fix the widget to the bottom right. Default: false (embedded). Override offsets with className or style. */
+    floating?: boolean;
+    /** Optional dismissible introduction shown while the widget is closed. */
+    introTip?: string;
+    /** Milliseconds before hiding the introduction. Default: 6000. */
+    introTipDuration?: number;
     /**
      * Whether the widget panel starts open. Default: `false`.
      * Set to `true` when embedding inside an already-open container such as a
@@ -355,4 +411,4 @@ declare function ChatInput({ input, handleInputChange, handleSubmit, isLoading,
 declare function ToolCallDisplay({ toolCallId, toolName, state, input, output, errorText, isLoading, }: ToolCallProps): react_jsx_runtime.JSX.Element;
 
 export { ChatInterface as C, DEFAULT_ALLOWED_FILE_TYPES as D, ChatLayout as f, ChatSidebar as h, ChatMessage as i, ChatInput as j, ToolCallDisplay as k };
-export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g };
+export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AiChatProviderConfig as b, AllowedFileType as c, ToolCallState as d, ToolCallRenderer as e, ChatLayoutProps as g, AiChatAnalyticsEvent as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",