@btst/stack 2.2.0 → 2.4.0

package/dist/packages/stack/src/plugins/kanban/client/hooks/kanban-hooks.mjs

@@ -33,7 +33,8 @@ function useBoards(params) {
   const queries = createKanbanQueryKeys(client, headers);
   return useQuery({
     ...queries.boards.list(params),
-    staleTime: 3e4
+    staleTime: 3e4,
+    refetchOnWindowFocus: true
   });
 }
 function useSuspenseBoards(params) {
@@ -41,7 +42,8 @@ function useSuspenseBoards(params) {
   const queries = createKanbanQueryKeys(client, headers);
   const result = useSuspenseQuery({
     ...queries.boards.list(params),
-    staleTime: 3e4
+    staleTime: 3e4,
+    refetchOnWindowFocus: true
   });
   if (result.error && !result.isFetching) {
     throw result.error;
@@ -54,6 +56,7 @@ function useBoard(boardId) {
   return useQuery({
     ...queries.boards.detail(boardId),
     staleTime: 3e4,
+    refetchOnWindowFocus: true,
     enabled: !!boardId
   });
 }
@@ -62,7 +65,8 @@ function useSuspenseBoard(boardId) {
   const queries = createKanbanQueryKeys(client, headers);
   const result = useSuspenseQuery({
     ...queries.boards.detail(boardId),
-    staleTime: 3e4
+    staleTime: 3e4,
+    refetchOnWindowFocus: true
   });
   if (result.error && !result.isFetching) {
     throw result.error;

package/dist/packages/stack/src/plugins/kanban/client/plugin.cjs

@@ -51,6 +51,11 @@ function createBoardsLoader(config) {
           await hooks.onLoadError(error, context);
         }
       } catch (error) {
+        if (client.isConnectionError(error)) {
+          console.warn(
+            "[btst/kanban] route.loader() failed \u2014 no server running at build time. Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching."
+          );
+        }
         if (hooks?.onLoadError) {
           await hooks.onLoadError(error, context);
         }
@@ -103,6 +108,11 @@ function createBoardLoader(boardId, config) {
           await hooks.onLoadError(error, context);
         }
       } catch (error) {
+        if (client.isConnectionError(error)) {
+          console.warn(
+            "[btst/kanban] route.loader() failed \u2014 no server running at build time. Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching."
+          );
+        }
         if (hooks?.onLoadError) {
           await hooks.onLoadError(error, context);
         }

package/dist/packages/stack/src/plugins/kanban/client/plugin.mjs

@@ -1,5 +1,5 @@
 import { jsx } from 'react/jsx-runtime';
-import { defineClientPlugin, createApiClient } from '@btst/stack/plugins/client';
+import { defineClientPlugin, createApiClient, isConnectionError } from '@btst/stack/plugins/client';
 import { createRoute } from '@btst/yar';
 import { createKanbanQueryKeys } from '../../../../../../plugins/kanban/query-keys.mjs';
 import { BoardsListPageComponent } from './components/pages/boards-list-page.mjs';
@@ -49,6 +49,11 @@ function createBoardsLoader(config) {
           await hooks.onLoadError(error, context);
         }
       } catch (error) {
+        if (isConnectionError(error)) {
+          console.warn(
+            "[btst/kanban] route.loader() failed \u2014 no server running at build time. Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching."
+          );
+        }
         if (hooks?.onLoadError) {
           await hooks.onLoadError(error, context);
         }
@@ -101,6 +106,11 @@ function createBoardLoader(boardId, config) {
           await hooks.onLoadError(error, context);
         }
       } catch (error) {
+        if (isConnectionError(error)) {
+          console.warn(
+            "[btst/kanban] route.loader() failed \u2014 no server running at build time. Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching."
+          );
+        }
         if (hooks?.onLoadError) {
           await hooks.onLoadError(error, context);
         }

package/dist/packages/stack/src/plugins/ui-builder/client/components/pages/page-builder-page.internal.cjs

@@ -12,10 +12,73 @@ const label = require('../../../../../../../ui/src/components/label.cjs');
 const LucideIcons = require('lucide-react');
 const sonner = require('sonner');
 const index$1 = require('../../../../../../../ui/src/components/ui-builder/index.cjs');
+const layerStore = require('../../../../../../../ui/src/lib/ui-builder/store/layer-store.cjs');
+const context$1 = require('@btst/stack/plugins/ai-chat/client/context');
 const uiBuilderHooks = require('../../hooks/ui-builder-hooks.cjs');
 const index = require('../../localization/index.cjs');
 const registry = require('../../registry.cjs');
 
+function buildRegistryDescription(registry) {
+  const lines = [];
+  for (const [name, entry] of Object.entries(registry)) {
+    let propsLine = "";
+    try {
+      const shape = entry.schema?.shape;
+      if (shape) {
+        const fields = Object.keys(shape).join(", ");
+        propsLine = ` \u2014 props: ${fields}`;
+      }
+    } catch {
+    }
+    lines.push(`- ${name}${propsLine}`);
+  }
+  return lines.join("\n");
+}
+function buildPageDescription(id, slug, layers, registry) {
+  const header = id ? `UI Builder \u2014 editing page (slug: "${slug}")` : "UI Builder \u2014 creating new page";
+  const layersJson = JSON.stringify(layers, null, 2);
+  const registryDesc = buildRegistryDescription(registry);
+  const layerFormat = `Each layer: { id: string, type: string, name: string, props: Record<string,any>, children?: ComponentLayer[] | string }`;
+  const full = [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    layersJson,
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n");
+  if (full.length <= 16e3) return full;
+  const overhead = [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    "",
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n").length + 30;
+  const budget = Math.max(0, 16e3 - overhead);
+  const truncatedLayers = layersJson.length > budget ? layersJson.slice(0, budget) + "\n...(truncated)" : layersJson;
+  return [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    truncatedLayers,
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n");
+}
 function slugify(str) {
   return str.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -72,6 +135,32 @@ function PageBuilderPageContent({
   const [layers, setLayers] = React.useState(existingLayers);
   const [variables, setVariables] = React.useState(existingVariables);
   const [autoSlug, setAutoSlug] = React.useState(!id);
+  context$1.useRegisterPageAIContext({
+    routeName: id ? "ui-builder-edit-page" : "ui-builder-new-page",
+    pageDescription: buildPageDescription(id, slug, layers, componentRegistry),
+    suggestions: [
+      "Add a hero section",
+      "Add a 3-column feature grid",
+      "Make the layout full-width",
+      "Add a card with a title, description, and button",
+      "Replace the layout with a centered single-column design"
+    ],
+    clientTools: {
+      updatePageLayers: async ({ layers: newLayers }) => {
+        const store = layerStore.useLayerStore.getState();
+        store.initialize(
+          newLayers,
+          store.selectedPageId || newLayers[0]?.id,
+          void 0,
+          store.variables
+        );
+        return {
+          success: true,
+          message: `Applied ${newLayers.length} layer(s) to the page`
+        };
+      }
+    }
+  });
   const handleLayersChange = React.useCallback(
     (newLayers) => {
       setLayers(newLayers);

package/dist/packages/stack/src/plugins/ui-builder/client/components/pages/page-builder-page.internal.mjs

@@ -10,10 +10,73 @@ import { Label } from '../../../../../../../ui/src/components/label.mjs';
 import { ArrowLeft, Settings2, Save } from 'lucide-react';
 import { toast } from 'sonner';
 import UIBuilder from '../../../../../../../ui/src/components/ui-builder/index.mjs';
+import { useLayerStore } from '../../../../../../../ui/src/lib/ui-builder/store/layer-store.mjs';
+import { useRegisterPageAIContext } from '@btst/stack/plugins/ai-chat/client/context';
 import { useSuspenseUIBuilderPage, useCreateUIBuilderPage, useUpdateUIBuilderPage } from '../../hooks/ui-builder-hooks.mjs';
 import { uiBuilderLocalization } from '../../localization/index.mjs';
 import { defaultComponentRegistry } from '../../registry.mjs';
 
+function buildRegistryDescription(registry) {
+  const lines = [];
+  for (const [name, entry] of Object.entries(registry)) {
+    let propsLine = "";
+    try {
+      const shape = entry.schema?.shape;
+      if (shape) {
+        const fields = Object.keys(shape).join(", ");
+        propsLine = ` \u2014 props: ${fields}`;
+      }
+    } catch {
+    }
+    lines.push(`- ${name}${propsLine}`);
+  }
+  return lines.join("\n");
+}
+function buildPageDescription(id, slug, layers, registry) {
+  const header = id ? `UI Builder \u2014 editing page (slug: "${slug}")` : "UI Builder \u2014 creating new page";
+  const layersJson = JSON.stringify(layers, null, 2);
+  const registryDesc = buildRegistryDescription(registry);
+  const layerFormat = `Each layer: { id: string, type: string, name: string, props: Record<string,any>, children?: ComponentLayer[] | string }`;
+  const full = [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    layersJson,
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n");
+  if (full.length <= 16e3) return full;
+  const overhead = [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    "",
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n").length + 30;
+  const budget = Math.max(0, 16e3 - overhead);
+  const truncatedLayers = layersJson.length > budget ? layersJson.slice(0, budget) + "\n...(truncated)" : layersJson;
+  return [
+    header,
+    "",
+    `## Current Layers (${layers.length})`,
+    truncatedLayers,
+    "",
+    `## Available Component Types`,
+    registryDesc,
+    "",
+    `## ComponentLayer format`,
+    layerFormat
+  ].join("\n");
+}
 function slugify(str) {
   return str.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -70,6 +133,32 @@ function PageBuilderPageContent({
   const [layers, setLayers] = useState(existingLayers);
   const [variables, setVariables] = useState(existingVariables);
   const [autoSlug, setAutoSlug] = useState(!id);
+  useRegisterPageAIContext({
+    routeName: id ? "ui-builder-edit-page" : "ui-builder-new-page",
+    pageDescription: buildPageDescription(id, slug, layers, componentRegistry),
+    suggestions: [
+      "Add a hero section",
+      "Add a 3-column feature grid",
+      "Make the layout full-width",
+      "Add a card with a title, description, and button",
+      "Replace the layout with a centered single-column design"
+    ],
+    clientTools: {
+      updatePageLayers: async ({ layers: newLayers }) => {
+        const store = useLayerStore.getState();
+        store.initialize(
+          newLayers,
+          store.selectedPageId || newLayers[0]?.id,
+          void 0,
+          store.variables
+        );
+        return {
+          success: true,
+          message: `Applied ${newLayers.length} layer(s) to the page`
+        };
+      }
+    }
+  });
   const handleLayersChange = useCallback(
     (newLayers) => {
       setLayers(newLayers);

package/dist/packages/stack/src/plugins/utils.cjs

@@ -2,6 +2,11 @@
 
 const client = require('better-call/client');
 
+function isConnectionError(err) {
+  if (!(err instanceof Error)) return false;
+  const code = err.cause?.code ?? err.code;
+  return err.message.includes("ECONNREFUSED") || err.message.includes("fetch failed") || err.message.includes("ERR_CONNECTION_REFUSED") || code === "ECONNREFUSED" || code === "ERR_CONNECTION_REFUSED";
+}
 function createApiClient(options) {
   const { baseURL = "", basePath = "/" } = options ?? {};
   const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
@@ -14,3 +19,4 @@ function createApiClient(options) {
 }
 
 exports.createApiClient = createApiClient;
+exports.isConnectionError = isConnectionError;

package/dist/packages/stack/src/plugins/utils.mjs

@@ -1,5 +1,10 @@
 import { createClient } from 'better-call/client';
 
+function isConnectionError(err) {
+  if (!(err instanceof Error)) return false;
+  const code = err.cause?.code ?? err.code;
+  return err.message.includes("ECONNREFUSED") || err.message.includes("fetch failed") || err.message.includes("ERR_CONNECTION_REFUSED") || code === "ECONNREFUSED" || code === "ERR_CONNECTION_REFUSED";
+}
 function createApiClient(options) {
   const { baseURL = "", basePath = "/" } = options ?? {};
   const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
@@ -11,4 +16,4 @@ function createApiClient(options) {
   });
 }
 
-export { createApiClient };
+export { createApiClient, isConnectionError };

package/dist/plugins/ai-chat/api/index.d.cts

@@ -1,4 +1,4 @@
-export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.CMh_EdxW.cjs';
+export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.DWoCZff7.cjs';
 import { Adapter } from '@btst/db';
 import { C as Conversation, M as Message } from '../../../shared/stack.Be1QIHEn.cjs';
 import '@tanstack/react-query';

package/dist/plugins/ai-chat/api/index.d.mts

@@ -1,4 +1,4 @@
-export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.Dg09R0oB.mjs';
+export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.DTDxgFj8.mjs';
 import { Adapter } from '@btst/db';
 import { C as Conversation, M as Message } from '../../../shared/stack.Be1QIHEn.mjs';
 import '@tanstack/react-query';

package/dist/plugins/ai-chat/api/index.d.ts

@@ -1,4 +1,4 @@
-export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.BeSm90va.js';
+export { e as AiChatApiRouter, b as AiChatBackendConfig, A as AiChatBackendHooks, a as AiChatMode, C as ChatApiContext, d as aiChatBackendPlugin, c as createAiChatQueryKeys } from '../../../shared/stack.BEn34wW6.js';
 import { Adapter } from '@btst/db';
 import { C as Conversation, M as Message } from '../../../shared/stack.Be1QIHEn.js';
 import '@tanstack/react-query';

package/dist/plugins/ai-chat/client/components/index.d.cts

@@ -1,4 +1,4 @@
-export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.DaOcgmrM.cjs';
+export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.BV9hnvu4.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { FallbackProps } from 'react-error-boundary';
 import 'ai';

package/dist/plugins/ai-chat/client/components/index.d.mts

@@ -1,4 +1,4 @@
-export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.DaOcgmrM.mjs';
+export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.BV9hnvu4.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { FallbackProps } from 'react-error-boundary';
 import 'ai';

package/dist/plugins/ai-chat/client/components/index.d.ts

@@ -1,4 +1,4 @@
-export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.DaOcgmrM.js';
+export { i as ChatInput, C as ChatInterface, e as ChatLayout, f as ChatLayoutProps, h as ChatMessage, g as ChatSidebar, j as ToolCallDisplay } from '../../../../shared/stack.BV9hnvu4.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { FallbackProps } from 'react-error-boundary';
 import 'ai';

package/dist/plugins/ai-chat/client/context/page-ai-context.cjs

@@ -0,0 +1,92 @@
+"use client";
+'use strict';
+
+const jsxRuntime = require('react/jsx-runtime');
+const React = require('react');
+
+const PageAIAPIContext = React.createContext(null);
+const PageAIVersionContext = React.createContext(0);
+function PageAIContextProvider({
+  children
+}) {
+  const registrationsRef = React.useRef(/* @__PURE__ */ new Map());
+  const insertionOrderRef = React.useRef([]);
+  const [version, setVersion] = React.useState(0);
+  const bumpVersion = React.useCallback(() => setVersion((v) => v + 1), []);
+  const register = React.useCallback(
+    (id, config) => {
+      registrationsRef.current.set(id, config);
+      insertionOrderRef.current = insertionOrderRef.current.filter(
+        (k) => k !== id
+      );
+      insertionOrderRef.current.push(id);
+      bumpVersion();
+    },
+    [bumpVersion]
+  );
+  const unregister = React.useCallback(
+    (id) => {
+      registrationsRef.current.delete(id);
+      insertionOrderRef.current = insertionOrderRef.current.filter(
+        (k) => k !== id
+      );
+      bumpVersion();
+    },
+    [bumpVersion]
+  );
+  const getActive = React.useCallback(() => {
+    const order = insertionOrderRef.current;
+    if (order.length === 0) return null;
+    const lastId = order[order.length - 1];
+    if (!lastId) return null;
+    return registrationsRef.current.get(lastId) ?? null;
+  }, []);
+  const api = React.useMemo(
+    () => ({ register, unregister, getActive }),
+    [register, unregister, getActive]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(PageAIAPIContext.Provider, { value: api, children: /* @__PURE__ */ jsxRuntime.jsx(PageAIVersionContext.Provider, { value: version, children }) });
+}
+function useRegisterPageAIContext(config) {
+  const ctx = React.useContext(PageAIAPIContext);
+  const id = React.useId();
+  const configRef = React.useRef(config);
+  configRef.current = config;
+  React.useEffect(() => {
+    if (!ctx || !configRef.current) return;
+    ctx.register(id, {
+      get routeName() {
+        return configRef.current?.routeName ?? "";
+      },
+      get pageDescription() {
+        return configRef.current?.pageDescription ?? "";
+      },
+      get suggestions() {
+        return configRef.current?.suggestions;
+      },
+      get clientTools() {
+        return configRef.current?.clientTools;
+      }
+    });
+    return () => {
+      ctx.unregister(id);
+    };
+  }, [
+    ctx,
+    id,
+    config === null,
+    config?.routeName,
+    config?.pageDescription,
+    JSON.stringify(config?.suggestions)
+  ]);
+}
+function usePageAIContext() {
+  React.useContext(PageAIVersionContext);
+  const ctx = React.useContext(PageAIAPIContext);
+  if (!ctx) return null;
+  return ctx.getActive();
+}
+
+exports.PageAIContextProvider = PageAIContextProvider;
+exports.usePageAIContext = usePageAIContext;
+exports.useRegisterPageAIContext = useRegisterPageAIContext;

package/dist/plugins/ai-chat/client/context/page-ai-context.d.cts

@@ -0,0 +1,84 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * A client-side tool handler — receives the AI's tool call args and returns a result.
+ * The result is sent back to the model so it can continue the conversation.
+ */
+type PageAIClientTool = (args: any) => Promise<{
+    success: boolean;
+    message?: string;
+}>;
+/**
+ * Configuration registered by a page to provide AI context and capabilities.
+ * Any component in the tree can call useRegisterPageAIContext with this config.
+ */
+interface PageAIContextConfig {
+    /**
+     * Identifier for the current route/page (e.g. "blog-post", "ui-builder-edit-page").
+     * Shown as a badge in the chat header.
+     */
+    routeName: string;
+    /**
+     * 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.
+     */
+    pageDescription: string;
+    /**
+     * Optional suggested prompts shown as quick-action chips in the chat empty state.
+     * These augment (not replace) any static suggestions configured in plugin overrides.
+     */
+    suggestions?: string[];
+    /**
+     * Client-side tool handlers keyed by tool name.
+     * When the AI calls a tool by this name, the handler is invoked with the tool args.
+     * The result is sent back to the model via addToolResult.
+     *
+     * Tool schemas must be registered server-side via enablePageTools + clientToolSchemas
+     * in aiChatBackendPlugin (built-in tools like fillBlogForm are pre-registered).
+     */
+    clientTools?: Record<string, PageAIClientTool>;
+}
+/**
+ * Provider that enables route-aware AI context across the app.
+ *
+ * Place this at the root layout — above all StackProviders — so it spans
+ * both your main app tree and any chat modals rendered as parallel/intercept routes.
+ *
+ * @example
+ * // app/layout.tsx
+ * import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
+ *
+ * export default function RootLayout({ children }) {
+ *   return <PageAIContextProvider>{children}</PageAIContextProvider>
+ * }
+ */
+declare function PageAIContextProvider({ children, }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Register page AI context from any component.
+ * The registration is cleaned up automatically when the component unmounts.
+ *
+ * Pass `null` to conditionally disable context (e.g. while data is loading).
+ *
+ * @example
+ * // Blog post page
+ * useRegisterPageAIContext(post ? {
+ *   routeName: "blog-post",
+ *   pageDescription: `Blog post: "${post.title}"\n\n${post.content?.slice(0, 16000)}`,
+ *   suggestions: ["Summarize this post", "What are the key takeaways?"],
+ * } : null)
+ */
+declare function useRegisterPageAIContext(config: PageAIContextConfig | null): void;
+/**
+ * Read the currently active page AI context.
+ * Returns null when no page has registered context, or when PageAIContextProvider
+ * is not in the tree.
+ *
+ * Used internally by ChatInterface to inject context into requests.
+ */
+declare function usePageAIContext(): PageAIContextConfig | null;
+
+export { PageAIContextProvider, usePageAIContext, useRegisterPageAIContext };
+export type { PageAIClientTool, PageAIContextConfig };

package/dist/plugins/ai-chat/client/context/page-ai-context.d.mts

@@ -0,0 +1,84 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * A client-side tool handler — receives the AI's tool call args and returns a result.
+ * The result is sent back to the model so it can continue the conversation.
+ */
+type PageAIClientTool = (args: any) => Promise<{
+    success: boolean;
+    message?: string;
+}>;
+/**
+ * Configuration registered by a page to provide AI context and capabilities.
+ * Any component in the tree can call useRegisterPageAIContext with this config.
+ */
+interface PageAIContextConfig {
+    /**
+     * Identifier for the current route/page (e.g. "blog-post", "ui-builder-edit-page").
+     * Shown as a badge in the chat header.
+     */
+    routeName: string;
+    /**
+     * 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.
+     */
+    pageDescription: string;
+    /**
+     * Optional suggested prompts shown as quick-action chips in the chat empty state.
+     * These augment (not replace) any static suggestions configured in plugin overrides.
+     */
+    suggestions?: string[];
+    /**
+     * Client-side tool handlers keyed by tool name.
+     * When the AI calls a tool by this name, the handler is invoked with the tool args.
+     * The result is sent back to the model via addToolResult.
+     *
+     * Tool schemas must be registered server-side via enablePageTools + clientToolSchemas
+     * in aiChatBackendPlugin (built-in tools like fillBlogForm are pre-registered).
+     */
+    clientTools?: Record<string, PageAIClientTool>;
+}
+/**
+ * Provider that enables route-aware AI context across the app.
+ *
+ * Place this at the root layout — above all StackProviders — so it spans
+ * both your main app tree and any chat modals rendered as parallel/intercept routes.
+ *
+ * @example
+ * // app/layout.tsx
+ * import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
+ *
+ * export default function RootLayout({ children }) {
+ *   return <PageAIContextProvider>{children}</PageAIContextProvider>
+ * }
+ */
+declare function PageAIContextProvider({ children, }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Register page AI context from any component.
+ * The registration is cleaned up automatically when the component unmounts.
+ *
+ * Pass `null` to conditionally disable context (e.g. while data is loading).
+ *
+ * @example
+ * // Blog post page
+ * useRegisterPageAIContext(post ? {
+ *   routeName: "blog-post",
+ *   pageDescription: `Blog post: "${post.title}"\n\n${post.content?.slice(0, 16000)}`,
+ *   suggestions: ["Summarize this post", "What are the key takeaways?"],
+ * } : null)
+ */
+declare function useRegisterPageAIContext(config: PageAIContextConfig | null): void;
+/**
+ * Read the currently active page AI context.
+ * Returns null when no page has registered context, or when PageAIContextProvider
+ * is not in the tree.
+ *
+ * Used internally by ChatInterface to inject context into requests.
+ */
+declare function usePageAIContext(): PageAIContextConfig | null;
+
+export { PageAIContextProvider, usePageAIContext, useRegisterPageAIContext };
+export type { PageAIClientTool, PageAIContextConfig };