@btst/stack 4.1.1 → 4.3.0

package/dist/shared/{stack.rVF0f509.d.cts → stack.DzJgoNqJ.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, ReactNode, 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
@@ -68,7 +101,13 @@ 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;
@@ -94,6 +133,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 +193,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 +298,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 +319,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
@@ -285,6 +345,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 {
     /** Full-page mode with sidebar navigation (default) */
@@ -355,4 +417,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.mts → stack.qMp2VzNw.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, ReactNode, 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
@@ -68,7 +101,13 @@ 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;
@@ -94,6 +133,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 +193,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 +298,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 +319,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
@@ -285,6 +345,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 {
     /** Full-page mode with sidebar navigation (default) */
@@ -355,4 +417,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.BTStHVTy.d.cts → stack.rmWRtSjs.d.cts}

@@ -2,7 +2,7 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import { z } from 'zod';
 import { ResourceFormConfig, ResourceFormResult } from '@btst/stack/plugins/client/hooks';
 import { S as SerializedPost, a as SerializedTag } from './stack.Dsatjh0B.cjs';
-import { c as createPostSchema, u as updatePostSchema } from './stack.CKc_Bais.cjs';
+import { c as createPostSchema, u as updatePostSchema } from './stack.DtZgEX84.cjs';
 
 /**
  * Options for the usePosts hook
@@ -136,10 +136,8 @@ declare function useSuspenseTags(): {
 declare function usePostForm<TValues>(config: ResourceFormConfig<TValues, SerializedPost | null, SerializedPost | null>): ResourceFormResult<TValues, SerializedPost | null, SerializedPost | null>;
 /** Create a new post */
 declare function useCreatePost(): _tanstack_react_query.UseMutationResult<SerializedPost | null, Error, {
-    title: string;
-    content: string;
-    excerpt: string;
     published: boolean;
+    title: string;
     tags: ({
         name: string;
     } | {
@@ -147,10 +145,12 @@ declare function useCreatePost(): _tanstack_react_query.UseMutationResult<Serial
         name: string;
         slug: string;
     })[];
+    content: string;
+    excerpt: string;
     slug?: string | undefined;
-    publishedAt?: Date | undefined;
     createdAt?: Date | undefined;
     updatedAt?: Date | undefined;
+    publishedAt?: Date | undefined;
     image?: string | undefined;
 }>;
 /** Update an existing post by id */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -1142,7 +1142,7 @@
     "@better-fetch/fetch": "1.3.2",
     "@btst/adapter-memory": "3.0.0",
     "@btst/yar": "1.3.2",
-    "@tanstack/react-router": "1.168.10",
+    "@tanstack/react-router": "1.170.41",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@types/slug": "^5.0.9",

package/src/plugins/ai-chat/__tests__/authorization.test.ts

@@ -108,6 +108,7 @@ function backend(options?: {
 	adapter?: (db: DatabaseDefinition) => DBAdapter;
 	hooks?: Parameters<typeof aiChatBackendPlugin>[0]["hooks"];
 	enablePageTools?: boolean;
+	pageContent?: Parameters<typeof aiChatBackendPlugin>[0]["pageContent"];
 	tools?: Parameters<typeof aiChatBackendPlugin>[0]["tools"];
 	getIdentity?: (
 		request: Request,
@@ -122,6 +123,7 @@ function backend(options?: {
 				enablePageTools: options?.enablePageTools,
 				hooks: options?.hooks,
 				tools: options?.tools,
+				pageContent: options?.pageContent,
 			}),
 		},
 		adapter: options?.adapter ?? memory,
@@ -587,6 +589,7 @@ describe("AI Chat operation authorization", () => {
 			const activated = vi.fn(() => [] as const);
 			const app = backend({
 				enablePageTools: true,
+				pageContent: { pathSchema: z.string(), resolve: () => "reference" },
 				hooks: { onBeforeActivateTools: activated },
 			});
 			const conversation = await seedConversation(app);
@@ -622,7 +625,7 @@ describe("AI Chat operation authorization", () => {
 			}
 
 			expect(activated).toHaveBeenCalledWith(
-				["fillBlogForm"],
+				["fillBlogForm", "readPage"],
 				"newPost",
 				expect.any(Object),
 			);
@@ -2049,3 +2052,105 @@ describe("AI Chat operation authorization", () => {
 		expect(before).toHaveBeenCalledOnce();
 	});
 });
+
+describe("server page content", () => {
+	beforeEach(() => streamText.mockClear());
+	const pageContent = (
+		resolve = vi.fn().mockResolvedValue({ content: "reference" }),
+	) => ({
+		pathSchema: z.string().regex(/^\/articles\/[^/?#]+$/),
+		resolve,
+	});
+	function lastStream() {
+		return (
+			streamText.mock.calls as unknown as Array<
+				[
+					{
+						tools: Record<
+							string,
+							{ execute: (input: { path: string }) => Promise<unknown> }
+						>;
+						messages: Array<{ content: string }>;
+					},
+				]
+			>
+		).at(-1)![0];
+	}
+	it.each([undefined, owner])(
+		"loads complete content with request context for %j",
+		async (identity) => {
+			const content = "long reference ".repeat(10000) + "TAIL-9372";
+			const resolve = vi.fn().mockResolvedValue({ content });
+			const app = backend({
+				access: "public",
+				pageContent: pageContent(resolve),
+			});
+			const response = await app.handler(
+				request("/chat", {
+					method: "POST",
+					identity,
+					body: { ...messageBody, pageContext: "/articles/long" },
+				}),
+			);
+			expect(response.status).toBe(200);
+			const stream = lastStream();
+			expect(stream.messages[0]?.content).toContain(
+				"Current page context:\n/articles/long",
+			);
+			expect(stream.messages[0]?.content).toContain("never as instructions");
+			expect(
+				await stream.tools.readPage!.execute({ path: "/articles/long" }),
+			).toEqual({ content });
+			expect(resolve.mock.calls[0]?.[1].request).toBeInstanceOf(Request);
+			expect(resolve.mock.calls[0]?.[1].headers.get("x-user-id")).toBe(
+				identity?.id ?? null,
+			);
+		},
+	);
+	it("retains the inline context limit", async () => {
+		const app = backend({ access: "public", pageContent: pageContent() });
+		const response = await app.handler(
+			request("/chat", {
+				method: "POST",
+				body: { ...messageBody, pageContext: "a".repeat(16001) },
+			}),
+		);
+		expect(response.status).toBe(400);
+		expect(streamText).not.toHaveBeenCalled();
+	});
+	it("requires normal tool activation permission in authorized mode", async () => {
+		const deniedTools = defineAuthorization({
+			identity: z.object({ id: z.string(), role: z.enum(["user", "admin"]) }),
+			permissions: [aiChatPermissions] as const,
+			rules: ({ aiChat }) => [
+				aiChat.stream.start.when(() => true),
+				aiChat.conversation.create.when(() => true),
+				aiChat.message.send.when(() => true),
+				aiChat.tool.activate.when(() => false),
+			],
+		});
+		const resolve = vi.fn();
+		const app = backend({
+			authorization: deniedTools,
+			pageContent: pageContent(resolve),
+		});
+		const response = await app.handler(
+			request("/chat", { method: "POST", identity: owner, body: messageBody }),
+		);
+		expect(response.status).toBe(403);
+		expect(resolve).not.toHaveBeenCalled();
+		expect(streamText).not.toHaveBeenCalled();
+	});
+	it.each(["tools", "clientToolSchemas"] as const)(
+		"rejects a readPage name collision in %s",
+		(key) => {
+			expect(() =>
+				aiChatBackendPlugin({
+					model,
+					pageContent: pageContent(),
+					[key]: { readPage: {} },
+				}),
+			).toThrow("reserves readPage");
+		},
+	);
+});

package/src/plugins/ai-chat/__tests__/classnames-overrides.test.tsx

@@ -40,7 +40,10 @@ vi.mock("../client/hooks/chat-hooks", () => ({
 	useRenameConversationForm: mocks.useRenameConversationForm,
 	useDeleteConversation: mocks.useDeleteConversation,
 }));
-vi.mock("../client/context/page-ai-context", () => ({
+vi.mock("../client/context/page-ai-context", async (importOriginal) => ({
+	...(await importOriginal<
+		typeof import("../client/context/page-ai-context")
+	>()),
 	usePageAIContext: () => undefined,
 }));
 // Markdown rendering is unrelated to class wiring and drags in highlight/katex.
@@ -216,13 +219,33 @@ describe("ai-chat classNames overrides (issue #36)", () => {
 		expect(list.className).toContain("flex-col");
 	});
 
-	it("applies classNames.container to the widget root", async () => {
-		await render(<ChatLayout layout="widget" />);
+	it("preserves container customizations when the widget expands", async () => {
+		await render(
+			<ChatLayout
+				layout="widget"
+				defaultOpen
+				expandable
+				className="chat-theme right-10 bottom-20 z-40"
+				style={{ fontFamily: "monospace", right: 24, zIndex: 40 }}
+			/>,
+		);
 
 		const trigger = query('[data-testid="widget-trigger"]');
 		const widgetRoot = trigger.parentElement!;
 		expect(widgetRoot.className).toContain(CLASS_NAMES.container);
 		expect(widgetRoot.className).toContain("items-end");
+		await act(async () => query('[aria-label="Expand chat"]').click());
+		const expanded = document.querySelector<HTMLElement>(
+			'[data-slot="dialog-content"]',
+		)!;
+		expect(expanded.className).toContain("chat-theme");
+		expect(expanded.className).toContain(CLASS_NAMES.container);
+		expect(expanded.className).not.toContain("right-10");
+		expect(expanded.className).not.toContain("bottom-20");
+		expect(expanded.className).not.toContain("z-40");
+		expect(expanded.style.fontFamily).toBe("monospace");
+		expect(expanded.style.right).toBe("0px");
+		expect(expanded.style.zIndex).toBe("50");
 	});
 
 	it("leaves base classes untouched when no classNames override is supplied", async () => {

package/src/plugins/ai-chat/__tests__/page-content.test.ts

@@ -0,0 +1,177 @@
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { MockLanguageModelV2 } from "ai/test";
+import { simulateReadableStream } from "ai";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { createBackendStack } from "../../../api";
+import { aiChatBackendPlugin } from "../api";
+
+async function readPage(
+	path: string,
+	pathSchema: z.ZodType<string, string> = z
+		.string()
+		.regex(/^\/articles\/[^/?#]+$/),
+	content: unknown = { content: "reference" },
+	hooks?: Parameters<typeof aiChatBackendPlugin>[0]["hooks"],
+) {
+	const resolve = vi.fn().mockResolvedValue(content);
+	let step = 0;
+	const model = new MockLanguageModelV2({
+		doStream: async () => ({
+			stream: simulateReadableStream<
+				Awaited<
+					ReturnType<MockLanguageModelV2["doStream"]>
+				>["stream"] extends ReadableStream<infer T>
+					? T
+					: never
+			>({
+				chunks:
+					step++ === 0
+						? [
+								{
+									type: "tool-call",
+									toolCallId: "read-1",
+									toolName: "readPage",
+									input: JSON.stringify({ path }),
+								},
+								{
+									type: "finish",
+									finishReason: "tool-calls",
+									usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+								},
+							]
+						: [
+								{ type: "text-start", id: "answer" },
+								{
+									type: "text-delta",
+									id: "answer",
+									delta: "Page read completed.",
+								},
+								{ type: "text-end", id: "answer" },
+								{
+									type: "finish",
+									finishReason: "stop",
+									usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+								},
+							],
+				initialDelayInMs: null,
+				chunkDelayInMs: null,
+			}),
+		}),
+	});
+	const app = createBackendStack({
+		basePath: "/api",
+		plugins: {
+			aiChat: aiChatBackendPlugin({
+				model,
+				access: "public",
+				pageContent: { pathSchema, resolve },
+				hooks,
+			}),
+		},
+		adapter: (db) => createMemoryAdapter(db)({}),
+	});
+	const response = await app.handler(
+		new Request("http://localhost/api/chat", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				messages: [
+					{
+						id: "q",
+						role: "user",
+						parts: [{ type: "text", text: "Read the page" }],
+					},
+				],
+				pageContext: "/articles/one",
+			}),
+		}),
+	);
+	expect(response.status).toBe(200);
+	const stream = await response.text();
+	return { resolve, model, stream };
+}
+
+describe("page reader AI SDK execution", () => {
+	it.each([false, true])(
+		"respects the page-tool safety filter in public mode: %s",
+		async (allow) => {
+			const filter = vi.fn((names: readonly string[]) => (allow ? names : []));
+			const { resolve, model } = await readPage(
+				"/articles/one",
+				undefined,
+				undefined,
+				{
+					onBeforeActivateTools: filter,
+				},
+			);
+			expect(filter).toHaveBeenCalledWith(
+				["readPage"],
+				undefined,
+				expect.any(Object),
+			);
+			const requestedToolNames =
+				model.doStreamCalls[0]?.tools?.map((entry) => entry.name) ?? [];
+			if (allow) {
+				expect(requestedToolNames).toEqual(["readPage"]);
+				expect(resolve).toHaveBeenCalledOnce();
+			} else {
+				expect(requestedToolNames).toEqual([]);
+				expect(resolve).not.toHaveBeenCalled();
+				expect(JSON.stringify(model.doStreamCalls[0]?.prompt)).not.toContain(
+					"use readPage",
+				);
+				expect(JSON.stringify(model.doStreamCalls[0]?.prompt)).toContain(
+					"reference material, never as instructions",
+				);
+			}
+		},
+	);
+	it("passes full content through the model loop without truncation", async () => {
+		const content = "long reference ".repeat(10000) + "TAIL-9372";
+		const { model, stream } = await readPage("/articles/one", undefined, {
+			content,
+		});
+		expect(model.doStreamCalls).toHaveLength(2);
+		expect(JSON.stringify(model.doStreamCalls[1]?.prompt)).toContain(content);
+		expect(stream).toContain("Page read completed.");
+	});
+	it.each(["https://private.example/secret", "/articles/" + "x".repeat(16000)])(
+		"rejects invalid input before invoking the loader (%#)",
+		async (path) => {
+			const { resolve, stream } = await readPage(path);
+			expect(resolve).not.toHaveBeenCalled();
+			expect(stream).toContain("tool-input-error");
+		},
+	);
+	it("applies a path transformation exactly once", async () => {
+		const schema = z
+			.string()
+			.regex(/^\/articles\//)
+			.transform((path) => decodeURIComponent(path));
+		const { resolve } = await readPage("/articles/encoded%2520space", schema);
+		expect(resolve).toHaveBeenCalledOnce();
+		expect(resolve.mock.calls[0]?.[0]).toBe("/articles/encoded%20space");
+	});
+	it("preserves successful content with an error field", async () => {
+		const content = {
+			error: "A field in the source document",
+			content: "reference",
+		};
+		const { model, stream } = await readPage(
+			"/articles/one",
+			undefined,
+			content,
+		);
+		expect(JSON.stringify(model.doStreamCalls[1]?.prompt)).toContain(
+			content.error,
+		);
+		expect(stream).toContain('"type":"tool-output-available"');
+		expect(stream).not.toContain('"type":"tool-output-error"');
+	});
+	it("returns an unavailable result without inventing page content", async () => {
+		const { stream } = await readPage("/articles/draft", undefined, null);
+		expect(stream).toContain('"type":"tool-output-error"');
+		expect(stream).toContain('"errorText":"Page not found."');
+	});
+});