@btst/stack 4.1.1 → 4.3.0

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

@@ -1,6 +1,19 @@
 "use client";
 
-import { useState, useCallback } from "react";
+import {
+	useState,
+	useCallback,
+	useEffect,
+	useRef,
+	type CSSProperties,
+	type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+	Dialog,
+	DialogContent,
+	DialogTitle,
+} from "@workspace/ui/components/dialog";
 import { Button } from "@workspace/ui/components/button";
 import { Badge } from "@workspace/ui/components/badge";
 import {
@@ -13,6 +26,8 @@ import {
 	PanelLeftClose,
 	PanelLeft,
 	Sparkles,
+	Maximize2,
+	Minimize2,
 	Trash2,
 	X,
 } from "lucide-react";
@@ -20,10 +35,18 @@ import { cn } from "@workspace/ui/lib/utils";
 import { ChatSidebar } from "./chat-sidebar";
 import { ChatInterface } from "./chat-interface";
 import type { UIMessage } from "ai";
-import { usePageAIContext } from "../context/page-ai-context";
+import {
+	usePageAIContext,
+	PageAIContextScope,
+	type PageAIContextConfig,
+} from "../context/page-ai-context";
 import { usePluginOverrides, useStack } from "@btst/stack/context";
 import type { AiChatPluginOverrides } from "../overrides";
 import { resolveAiChatMode } from "../overrides";
+import {
+	ChatAnalyticsPageKey,
+	useChatAnalytics,
+} from "../context/chat-analytics";
 import { useAiChatTranslation } from "../localization";
 
 interface ChatLayoutBaseProps {
@@ -31,6 +54,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) */
@@ -44,10 +76,18 @@ 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(640px, calc(100dvh - 112px))"` */
 	widgetHeight?: string | number;
-	/** Width of the widget panel. Default: `"380px"` */
+	/** Width of the widget panel. Default: `"min(440px, calc(100vw - 32px))"` */
 	widgetWidth?: string | number;
+	/** Show a button to expand the widget to the viewport. Default: false. Escape restores the compact size. */
+	expandable?: boolean;
+	/** 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
@@ -62,6 +102,8 @@ interface ChatLayoutWidgetProps extends ChatLayoutBaseProps {
 	 * so that the built-in button does not appear alongside your own UI.
 	 */
 	showTrigger?: boolean;
+	/** Icon shown in the closed widget's trigger button. Defaults to Sparkles. */
+	triggerIcon?: ReactNode;
 }
 
 interface ChatLayoutFullProps extends ChatLayoutBaseProps {
@@ -77,10 +119,22 @@ export type ChatLayoutProps = ChatLayoutWidgetProps | ChatLayoutFullProps;
  * or a compact widget mode for embedding.
  */
 export function ChatLayout(props: ChatLayoutProps) {
+	return (
+		<PageAIContextScope.Provider value={props.pageContext}>
+			<ChatAnalyticsPageKey.Provider value={props.pageKey}>
+				<ChatLayoutContent key={props.pageKey} {...props} />
+			</ChatAnalyticsPageKey.Provider>
+		</PageAIContextScope.Provider>
+	);
+}
+
+function ChatLayoutContent(props: ChatLayoutProps) {
+	const track = useChatAnalytics();
 	const {
 		conversationId,
 		layout = "full",
 		className,
+		style,
 		showSidebar: requestedShowSidebar = true,
 		initialMessages,
 		onMessagesChange,
@@ -97,13 +151,18 @@ export function ChatLayout(props: ChatLayoutProps) {
 
 	// Widget-specific props — TypeScript narrows props to ChatLayoutWidgetProps here
 	const widgetHeight =
-		props.layout === "widget" ? (props.widgetHeight ?? "600px") : "600px";
+		props.layout === "widget"
+			? (props.widgetHeight ?? "min(640px, calc(100dvh - 112px))")
+			: undefined;
 	const widgetWidth =
-		props.layout === "widget" ? (props.widgetWidth ?? "380px") : "380px";
+		props.layout === "widget"
+			? (props.widgetWidth ?? "min(440px, calc(100vw - 32px))")
+			: undefined;
 	const defaultOpen =
 		props.layout === "widget" ? (props.defaultOpen ?? false) : false;
 	const showTrigger =
 		props.layout === "widget" ? (props.showTrigger ?? true) : true;
+	const triggerIcon = props.layout === "widget" ? props.triggerIcon : undefined;
 
 	const [sidebarOpen, setSidebarOpen] = useState(true);
 	const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
@@ -111,6 +170,40 @@ export function ChatLayout(props: ChatLayoutProps) {
 	const [chatResetKey, setChatResetKey] = useState(0);
 	// Widget open/closed state — starts with defaultOpen value
 	const [widgetOpen, setWidgetOpen] = useState(defaultOpen);
+	const [expanded, setExpanded] = useState(false);
+	const expandable = props.layout === "widget" && props.expandable === true;
+	const widgetExpanded = expandable && expanded && widgetOpen;
+	useEffect(() => {
+		if (!expandable) setExpanded(false);
+	}, [expandable]);
+	const compactPanelRef = useRef<HTMLDivElement>(null);
+	const triggerRef = useRef<HTMLButtonElement>(null);
+	const expandRef = useRef<HTMLButtonElement>(null);
+	const [panelContainer, setPanelContainer] = useState<HTMLDivElement | null>(
+		null,
+	);
+	const expandLabel = widgetExpanded
+		? tr("A11Y_COLLAPSE_CHAT", "aiChat.a11y.collapseChat", "Collapse chat")
+		: tr("A11Y_EXPAND_CHAT", "aiChat.a11y.expandChat", "Expand chat");
+
+	useEffect(() => {
+		if (layout !== "widget") return;
+		const container = document.createElement("div");
+		container.className = "flex h-full min-h-0 flex-col";
+		compactPanelRef.current?.appendChild(container);
+		setPanelContainer(container);
+		return () => container.remove();
+	}, [layout]);
+	// The portal target stays the same; only its DOM parent changes. This keeps
+	// the draft, attachments and active stream mounted while Dialog owns modality.
+	const mountExpandedPanel = useCallback(
+		(node: HTMLDivElement | null) => {
+			if (panelContainer) {
+				(node ?? compactPanelRef.current)?.appendChild(panelContainer);
+			}
+		},
+		[panelContainer],
+	);
 	// Key to force widget ChatInterface remount on clear
 	const [widgetResetKey, setWidgetResetKey] = useState(0);
 	// Only mount the widget ChatInterface after the widget has been opened at least once.
@@ -118,6 +211,38 @@ export function ChatLayout(props: ChatLayoutProps) {
 	// so suggestion chips and tool hints appear immediately on first open.
 	// When defaultOpen is true the widget is pre-opened, so we mark it as ever-opened immediately.
 	const [widgetEverOpened, setWidgetEverOpened] = useState(defaultOpen);
+	const [tipDismissed, setTipDismissed] = useState(defaultOpen);
+	const introTip = props.layout === "widget" ? props.introTip : undefined;
+	const introTipDuration =
+		props.layout === "widget" ? (props.introTipDuration ?? 6000) : 6000;
+	const tipShown = useRef(false);
+	const tipDismissedRef = useRef(defaultOpen);
+	const dismissTip = useCallback(
+		(reason: "timeout" | "manual" | "open") => {
+			if (tipShown.current && !tipDismissedRef.current) {
+				tipDismissedRef.current = true;
+				track({ type: "intro_tip_dismissed", reason });
+			}
+			setTipDismissed(true);
+		},
+		[track],
+	);
+	useEffect(() => {
+		if (!introTip || !showTrigger || tipDismissed) return;
+		if (!tipShown.current) {
+			tipShown.current = true;
+			track({ type: "intro_tip_shown" });
+		}
+		const timeout = setTimeout(() => dismissTip("timeout"), introTipDuration);
+		return () => clearTimeout(timeout);
+	}, [
+		introTip,
+		introTipDuration,
+		showTrigger,
+		tipDismissed,
+		dismissTip,
+		track,
+	]);
 
 	// Read page AI context to show badge in header
 	const pageAIContext = usePageAIContext();
@@ -136,88 +261,197 @@ export function ChatLayout(props: ChatLayoutProps) {
 			<div
 				className={cn(
 					"flex flex-col items-end gap-3",
+					props.layout === "widget" &&
+						props.floating &&
+						"fixed right-4 bottom-[max(1rem,env(safe-area-inset-bottom))] z-50",
 					className,
 					classNames?.container,
 				)}
+				style={style}
 			>
-				{/* Chat panel — always mounted to preserve conversation state, hidden when closed */}
-				<div
-					className={cn(
-						"flex flex-col border rounded-xl overflow-hidden bg-background shadow-xl",
-						widgetOpen ? "flex" : "hidden",
-					)}
-					style={{ height: widgetHeight, width: widgetWidth }}
-				>
-					{/* Widget header with page context badge and action buttons */}
-					<div className="flex items-center gap-1.5 px-3 py-1.5 border-b bg-muted/40">
-						<Sparkles className="h-3 w-3 text-muted-foreground" />
-						{pageAIContext ? (
-							<Badge
-								variant="secondary"
-								className="text-xs"
-								data-testid="page-context-badge"
-							>
-								{pageAIContext.routeName}
-							</Badge>
-						) : (
-							<span className="text-xs text-muted-foreground font-medium">
-								{tr("A11Y_CHAT_TITLE", "aiChat.a11y.title", "AI Chat")}
-							</span>
-						)}
-						<div className="flex-1" />
-						<Button
-							variant="ghost"
-							size="icon"
-							className="h-5 w-5"
-							onClick={() => {
-								onClear?.();
-								setWidgetResetKey((prev) => prev + 1);
-							}}
-							aria-label={tr(
-								"A11Y_CLEAR_CHAT",
-								"aiChat.a11y.clearChat",
-								"Clear chat",
-							)}
-							title={tr(
-								"A11Y_CLEAR_CHAT",
-								"aiChat.a11y.clearChat",
-								"Clear chat",
-							)}
-						>
-							<Trash2 className="h-3.5 w-3.5" />
-						</Button>
+				{introTip && showTrigger && !tipDismissed && !widgetOpen && (
+					<div
+						role="status"
+						className="flex max-w-[min(280px,calc(100vw-32px))] items-center gap-2 rounded-lg border bg-background p-3 text-sm text-foreground shadow-lg"
+					>
+						<span>{introTip}</span>
 						<Button
+							type="button"
 							variant="ghost"
 							size="icon"
-							className="h-5 w-5"
-							onClick={() => setWidgetOpen(false)}
+							className="h-7 w-7 shrink-0"
+							onClick={() => dismissTip("manual")}
 							aria-label={tr(
-								"A11Y_CLOSE_CHAT",
-								"aiChat.a11y.closeChat",
-								"Close chat",
+								"A11Y_DISMISS_CHAT_TIP",
+								"aiChat.a11y.dismissChatTip",
+								"Dismiss chat tip",
 							)}
 						>
-							<X className="h-3.5 w-3.5" />
+							<X className="h-4 w-4" aria-hidden="true" />
 						</Button>
 					</div>
-					{widgetEverOpened && (
-						<ChatInterface
-							key={`widget-${conversationId ?? "new"}-${widgetResetKey}`}
-							id={conversationId}
-							variant="widget"
-							initialMessages={initialMessages}
-							onMessagesChange={onMessagesChange}
-						/>
+				)}
+				{/* Compact panel remains available when the fullscreen dialog closes. */}
+				<div
+					ref={compactPanelRef}
+					role="dialog"
+					tabIndex={-1}
+					aria-label={tr("A11Y_CHAT_TITLE", "aiChat.a11y.title", "AI Chat")}
+					className={cn(
+						"overflow-hidden rounded-xl border bg-background shadow-xl",
+						(!widgetOpen || widgetExpanded) && "hidden",
+					)}
+					style={{ height: widgetHeight, width: widgetWidth }}
+				/>
+				<Dialog open={widgetExpanded} onOpenChange={setExpanded}>
+					<DialogContent
+						showCloseButton={false}
+						style={{
+							...style,
+							position: "fixed",
+							inset: 0,
+							top: 0,
+							right: 0,
+							bottom: 0,
+							left: 0,
+							width: "100vw",
+							height: "100dvh",
+							minWidth: 0,
+							minHeight: 0,
+							maxWidth: "none",
+							maxHeight: "none",
+							margin: 0,
+							transform: "none",
+							translate: "none",
+							zIndex: 50,
+							animation: "none",
+						}}
+						aria-describedby={undefined}
+						className={cn(
+							className,
+							classNames?.container,
+							"fixed inset-0 z-50 flex h-dvh w-screen max-w-none translate-x-0 translate-y-0 flex-col gap-0 rounded-none border-0 p-0 sm:max-w-none pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)] pl-[env(safe-area-inset-left)] pr-[env(safe-area-inset-right)]",
+						)}
+						onCloseAutoFocus={(event) => {
+							const target = widgetOpen
+								? (expandRef.current ?? compactPanelRef.current)
+								: triggerRef.current;
+							if (target) {
+								event.preventDefault();
+								target.focus();
+							}
+						}}
+					>
+						<DialogTitle className="sr-only">
+							{tr("A11Y_CHAT_TITLE", "aiChat.a11y.title", "AI Chat")}
+						</DialogTitle>
+						<div ref={mountExpandedPanel} className="min-h-0 flex-1" />
+					</DialogContent>
+				</Dialog>
+				{panelContainer &&
+					createPortal(
+						<>
+							{/* Widget header with page context badge and action buttons */}
+							<div className="flex shrink-0 items-center gap-1.5 px-3 py-1.5 border-b bg-muted/40">
+								<Sparkles className="h-3 w-3 text-muted-foreground" />
+								{pageAIContext ? (
+									<Badge
+										variant="secondary"
+										className="text-xs"
+										data-testid="page-context-badge"
+									>
+										{pageAIContext.routeName}
+									</Badge>
+								) : (
+									<span className="text-xs text-muted-foreground font-medium">
+										{tr("A11Y_CHAT_TITLE", "aiChat.a11y.title", "AI Chat")}
+									</span>
+								)}
+								<div className="flex-1" />
+								{expandable && (
+									<Button
+										type="button"
+										variant="ghost"
+										size="icon"
+										className="h-7 w-7"
+										ref={expandRef}
+										onClick={() => setExpanded((prev) => !prev)}
+										aria-label={expandLabel}
+										title={expandLabel}
+										aria-expanded={widgetExpanded}
+									>
+										{widgetExpanded ? (
+											<Minimize2 className="h-3.5 w-3.5" aria-hidden="true" />
+										) : (
+											<Maximize2 className="h-3.5 w-3.5" aria-hidden="true" />
+										)}
+									</Button>
+								)}
+								<Button
+									variant="ghost"
+									size="icon"
+									className="h-5 w-5"
+									onClick={() => {
+										track({ type: "conversation_cleared" });
+										onClear?.();
+										setWidgetResetKey((prev) => prev + 1);
+									}}
+									aria-label={tr(
+										"A11Y_CLEAR_CHAT",
+										"aiChat.a11y.clearChat",
+										"Clear chat",
+									)}
+									title={tr(
+										"A11Y_CLEAR_CHAT",
+										"aiChat.a11y.clearChat",
+										"Clear chat",
+									)}
+								>
+									<Trash2 className="h-3.5 w-3.5" />
+								</Button>
+								<Button
+									variant="ghost"
+									size="icon"
+									className="h-5 w-5"
+									onClick={() => {
+										setWidgetOpen(false);
+										setExpanded(false);
+										triggerRef.current?.focus();
+										track({ type: "widget_closed" });
+									}}
+									aria-label={tr(
+										"A11Y_CLOSE_CHAT",
+										"aiChat.a11y.closeChat",
+										"Close chat",
+									)}
+								>
+									<X className="h-3.5 w-3.5" />
+								</Button>
+							</div>
+							{widgetEverOpened && (
+								<ChatInterface
+									key={`widget-${conversationId ?? "new"}-${widgetResetKey}`}
+									id={conversationId}
+									variant="widget"
+									initialMessages={initialMessages}
+									onMessagesChange={onMessagesChange}
+								/>
+							)}
+						</>,
+						panelContainer,
 					)}
-				</div>
 
 				{/* Trigger button — rendered only when showTrigger is true */}
 				{showTrigger && (
 					<Button
+						ref={triggerRef}
 						size="icon"
 						className="h-12 w-12 rounded-full shadow-lg"
 						onClick={() => {
+							dismissTip("open");
+							track({ type: widgetOpen ? "widget_closed" : "widget_opened" });
 							setWidgetOpen((prev) => !prev);
+							setExpanded(false);
 							setWidgetEverOpened(true);
 						}}
 						aria-label={
@@ -230,7 +464,7 @@ export function ChatLayout(props: ChatLayoutProps) {
 						{widgetOpen ? (
 							<X className="h-5 w-5" />
 						) : (
-							<Sparkles className="h-5 w-5" />
+							(triggerIcon ?? <Sparkles className="h-5 w-5" />)
 						)}
 					</Button>
 				)}
@@ -247,6 +481,7 @@ export function ChatLayout(props: ChatLayoutProps) {
 				classNames?.container,
 			)}
 			data-testid="chat-layout"
+			style={style}
 		>
 			{/* Desktop Sidebar */}
 			{showSidebar && (
@@ -347,6 +582,7 @@ export function ChatLayout(props: ChatLayoutProps) {
 							variant="ghost"
 							size="icon"
 							onClick={() => {
+								track({ type: "conversation_cleared" });
 								onClear();
 								setChatResetKey((prev) => prev + 1);
 							}}

package/src/plugins/ai-chat/client/components/tool-call-display.tsx

@@ -10,7 +10,7 @@ import { MarkdownContent } from "@workspace/ui/components/markdown-content";
 import { Skeleton } from "@workspace/ui/components/skeleton";
 import { cn } from "@workspace/ui/lib/utils";
 import { Wrench, Check, AlertCircle, Loader2 } from "lucide-react";
-import { usePluginOverrides } from "@btst/stack/context";
+import { usePluginOverrides, useStack } from "@btst/stack/context";
 import type {
 	AiChatPluginOverrides,
 	ToolCallProps,
@@ -106,6 +106,34 @@ export function ToolCallDisplay({
 		Partial<AiChatPluginOverrides>
 	>("aiChat", {});
 	const tr = useAiChatTranslation(localization);
+	const { plugins } = useStack();
+	if (
+		toolName === "readPage" &&
+		plugins?.aiChat?.config?.pageContent === true
+	) {
+		const failed = state === "output-error";
+		return (
+			<p className="text-xs text-muted-foreground" role="status">
+				{failed
+					? tr(
+							"PAGE_CONTENT_ERROR",
+							"aiChat.pageContent.error",
+							"Unable to read this page.",
+						)
+					: state === "output-available"
+						? tr(
+								"PAGE_CONTENT_READ",
+								"aiChat.pageContent.read",
+								"Read page content",
+							)
+						: tr(
+								"PAGE_CONTENT_READING",
+								"aiChat.pageContent.reading",
+								"Reading page content…",
+							)}
+			</p>
+		);
+	}
 	const displayName = formatToolName(toolName);
 	const statusLabel =
 		isLoading || state === "input-streaming"

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

@@ -86,7 +86,13 @@ export interface AiChatLocalization {
 	A11Y_CHAT_TITLE: string;
 	A11Y_CLEAR_CHAT: string;
 	A11Y_CLOSE_CHAT: string;
+	A11Y_EXPAND_CHAT: string;
+	A11Y_COLLAPSE_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;
@@ -190,7 +196,13 @@ export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
 	A11Y_CHAT_TITLE: "AI Chat",
 	A11Y_CLEAR_CHAT: "Clear chat",
 	A11Y_CLOSE_CHAT: "Close chat",
+	A11Y_EXPAND_CHAT: "Expand chat",
+	A11Y_COLLAPSE_CHAT: "Collapse 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.