@btst/stack 2.2.0 → 2.4.0

package/dist/shared/stack.kcdnD4gA.d.cts

@@ -0,0 +1,293 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as better_call from 'better-call';
+import { S as SerializedForm, b as SerializedFormSubmissionWithData, F as Form, d as FormSubmission, a as SerializedFormSubmission, e as FormSubmissionWithForm, f as FormBuilderBackendConfig } from './stack.DdI5W6MB.cjs';
+import { z } from 'zod';
+import { Adapter } from '@btst/db';
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Serialize a Form for SSR/SSG use (convert dates to strings).
+ */
+declare function serializeForm(form: Form): SerializedForm;
+/**
+ * Serialize a FormSubmission for SSR/SSG use (convert dates to strings).
+ */
+declare function serializeFormSubmission(submission: FormSubmission): SerializedFormSubmission;
+/**
+ * Serialize a FormSubmission with parsed data and joined Form.
+ * If `submission.data` is corrupted JSON, `parsedData` is set to `null` rather
+ * than throwing, so one bad row cannot crash the entire list or SSG build.
+ */
+declare function serializeFormSubmissionWithData(submission: FormSubmissionWithForm): SerializedFormSubmissionWithData;
+/**
+ * Retrieve all forms with optional status filter and pagination.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListForms`) are NOT
+ * called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters
+ */
+declare function getAllForms(adapter: Adapter, params?: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    items: SerializedForm[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}>;
+/**
+ * Retrieve a single form by its ID (UUID).
+ * Returns null if the form is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param id - The form UUID
+ */
+declare function getFormById(adapter: Adapter, id: string): Promise<SerializedForm | null>;
+/**
+ * Retrieve a single form by its slug.
+ * Returns null if the form is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - The form slug
+ */
+declare function getFormBySlug(adapter: Adapter, slug: string): Promise<SerializedForm | null>;
+/**
+ * Retrieve submissions for a form by form ID, with optional pagination.
+ * Returns an empty result if the form does not exist.
+ * Pure DB function — no hooks, no HTTP context. Safe for server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param formId - The form ID
+ * @param params - Optional pagination parameters
+ */
+declare function getFormSubmissions(adapter: Adapter, formId: string, params?: {
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    items: SerializedFormSubmissionWithData[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}>;
+
+/**
+ * Route keys for the Form Builder plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+type FormBuilderRouteKey = "formList" | "newForm" | "editForm" | "submissions";
+interface FormBuilderPrefetchForRoute {
+    (key: "formList" | "newForm", qc: QueryClient): Promise<void>;
+    (key: "editForm" | "submissions", qc: QueryClient, params: {
+        id: string;
+    }): Promise<void>;
+}
+/**
+ * Form Builder backend plugin
+ * Provides API endpoints for managing forms and form submissions
+ *
+ * @param config - Configuration with optional hooks
+ */
+declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    listForms: better_call.StrictEndpoint<"/forms", {
+        method: "GET";
+        query: z.ZodObject<{
+            status: z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>;
+            limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+            offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+        }, z.core.$strip>;
+    }, {
+        items: SerializedForm[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getFormBySlug: better_call.StrictEndpoint<"/forms/:slug", {
+        method: "GET";
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    getFormById: better_call.StrictEndpoint<"/forms/id/:id", {
+        method: "GET";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    createForm: better_call.StrictEndpoint<"/forms", {
+        method: "POST";
+        body: z.ZodObject<{
+            name: z.ZodString;
+            slug: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            schema: z.ZodString;
+            successMessage: z.ZodOptional<z.ZodString>;
+            redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+            status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>>;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    updateForm: better_call.StrictEndpoint<"/forms/:id", {
+        method: "PUT";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+        body: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            schema: z.ZodOptional<z.ZodString>;
+            successMessage: z.ZodOptional<z.ZodString>;
+            redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+            status: z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    deleteForm: better_call.StrictEndpoint<"/forms/:id", {
+        method: "DELETE";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+    submitForm: better_call.StrictEndpoint<"/forms/:slug/submit", {
+        method: "POST";
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+        body: z.ZodObject<{
+            data: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>;
+    }, {
+        form: {
+            successMessage: string | undefined;
+            redirectUrl: string | undefined;
+        };
+        submittedAt: string;
+        id: string;
+        data: string;
+        formId: string;
+        submittedBy?: string | undefined;
+        ipAddress?: string | undefined;
+        userAgent?: string | undefined;
+    }>;
+    listSubmissions: better_call.StrictEndpoint<"/forms/:formId/submissions", {
+        method: "GET";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+        }, z.core.$strip>;
+        query: z.ZodObject<{
+            limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+            offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+        }, z.core.$strip>;
+    }, {
+        items: SerializedFormSubmissionWithData[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getSubmission: better_call.StrictEndpoint<"/forms/:formId/submissions/:subId", {
+        method: "GET";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+            subId: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedFormSubmissionWithData<Record<string, unknown>>>;
+    deleteSubmission: better_call.StrictEndpoint<"/forms/:formId/submissions/:subId", {
+        method: "DELETE";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+            subId: z.ZodString;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+}, {
+    getAllForms: (params?: Parameters<typeof getAllForms>[1]) => Promise<{
+        items: SerializedForm[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getFormById: (id: string) => Promise<SerializedForm | null>;
+    getFormBySlug: (slug: string) => Promise<SerializedForm | null>;
+    getFormSubmissions: (formId: string, params?: Parameters<typeof getFormSubmissions>[2]) => Promise<{
+        items: SerializedFormSubmissionWithData[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    prefetchForRoute: FormBuilderPrefetchForRoute;
+}>;
+type FormBuilderApiRouter = ReturnType<ReturnType<typeof formBuilderBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the Form Builder plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+interface FormsListDiscriminator {
+    status?: "active" | "inactive" | "archived";
+    limit: number;
+    offset: number;
+}
+interface SubmissionsListDiscriminator {
+    formId: string;
+    limit: number;
+    offset: number;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare const FORM_QUERY_KEYS: {
+    /**
+     * Key for forms.list(params) query.
+     * Full key: ["forms", "list", "list", { status, limit, offset }]
+     */
+    formsList: (params?: {
+        status?: "active" | "inactive" | "archived";
+        limit?: number;
+        offset?: number;
+    }) => readonly ["forms", "list", "list", FormsListDiscriminator];
+    /**
+     * Key for forms.byId(id) query.
+     * Full key: ["forms", "byId", "byId", id]
+     */
+    formById: (id: string) => readonly ["forms", "byId", "byId", string];
+    /**
+     * Key for formSubmissions.list(params) query.
+     * Full key: ["formSubmissions", "list", { formId, limit, offset }]
+     */
+    submissionsList: (params: {
+        formId: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["formSubmissions", "list", SubmissionsListDiscriminator];
+};
+
+export { getFormById as c, getFormBySlug as d, getFormSubmissions as e, formBuilderBackendPlugin as f, getAllForms as g, serializeFormSubmission as h, serializeFormSubmissionWithData as i, FORM_QUERY_KEYS as j, serializeForm as s };
+export type { FormBuilderApiRouter as F, SubmissionsListDiscriminator as S, FormsListDiscriminator as a, FormBuilderRouteKey as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -163,6 +163,16 @@
         "default": "./dist/plugins/ai-chat/client/hooks/index.cjs"
       }
     },
+    "./plugins/ai-chat/client/context": {
+      "import": {
+        "types": "./dist/plugins/ai-chat/client/context/page-ai-context.d.ts",
+        "default": "./dist/plugins/ai-chat/client/context/page-ai-context.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/ai-chat/client/context/page-ai-context.d.cts",
+        "default": "./dist/plugins/ai-chat/client/context/page-ai-context.cjs"
+      }
+    },
     "./plugins/ai-chat/css": "./dist/plugins/ai-chat/style.css",
     "./plugins/blog/css": "./dist/plugins/blog/style.css",
     "./plugins/cms/api": {
@@ -392,6 +402,9 @@
       "plugins/ai-chat/client/hooks": [
         "./dist/plugins/ai-chat/client/hooks/index.d.ts"
       ],
+      "plugins/ai-chat/client/context": [
+        "./dist/plugins/ai-chat/client/context/page-ai-context.d.ts"
+      ],
       "plugins/cms/api": [
         "./dist/plugins/cms/api/index.d.ts"
       ],
@@ -458,7 +471,7 @@
   },
   "peerDependencies": {
     "@ai-sdk/react": ">=2.0.0",
-    "@btst/yar": ">=1.1.0",
+    "@btst/yar": ">=1.2.0",
     "@hookform/resolvers": ">=5.0.0",
     "@radix-ui/react-dialog": ">=1.1.0",
     "@radix-ui/react-label": ">=2.1.0",
@@ -494,7 +507,7 @@
   "devDependencies": {
     "@ai-sdk/react": "^2.0.94",
     "@btst/adapter-memory": "2.0.3",
-    "@btst/yar": "1.1.1",
+    "@btst/yar": "1.2.0",
     "@types/react": "^19.0.0",
     "@types/slug": "^5.0.9",
     "@workspace/ui": "workspace:*",

package/src/client/components/compose.tsx

@@ -89,10 +89,13 @@ export function ComposedRoute({
 }) {
 	if (PageComponent) {
 		const content = <PageComponent {...props} />;
-		// Avoid server-side skeletons: only show loading fallback in the browser
-		const isBrowser = typeof window !== "undefined";
-		const suspenseFallback =
-			isBrowser && LoadingComponent ? <LoadingComponent /> : null;
+		// Always provide the same fallback on server and client — using
+		// `typeof window !== "undefined"` here would produce a different JSX tree
+		// on each side, shifting React's useId() counter and causing hydration
+		// mismatches in any descendant that uses Radix (Select, Dialog, etc.).
+		// If the Suspense boundary never actually suspends during SSR (data is
+		// prefetched), React won't emit the fallback into the HTML anyway.
+		const suspenseFallback = LoadingComponent ? <LoadingComponent /> : null;
 
 		// If an ErrorComponent is provided (which itself may be lazy), ensure we have
 		// a Suspense boundary that can handle both the page content and the lazy error UI

package/src/plugins/ai-chat/api/page-tools.ts

@@ -0,0 +1,111 @@
+import { tool } from "ai";
+import type { Tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Maps each built-in page tool to the route names that are permitted to request it.
+ *
+ * The server cross-checks the `routeName` field sent with every chat request
+ * against this allowlist before including a built-in tool in the streamText call.
+ * A tool is only activated when both conditions are true:
+ *   1. The tool name appears in the request's `availableTools` list, AND
+ *   2. The request's `routeName` is in this tool's allowlist.
+ *
+ * Consumer-defined tools (via `clientToolSchemas`) are not validated here —
+ * the consumer is responsible for their own access control.
+ */
+export const BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST: Record<string, string[]> = {
+	/** Blog new-post and edit-post pages */
+	fillBlogForm: ["blog-new-post", "blog-edit-post", "newPost", "editPost"],
+	/** UI builder edit page */
+	updatePageLayers: ["ui-builder-edit-page"],
+};
+
+/**
+ * Built-in client-side-only tool schemas for route-aware AI context.
+ *
+ * These tools have no `execute` function — they are handled on the client side
+ * via the onToolCall handler in ChatInterface, which dispatches to handlers
+ * registered by pages via useRegisterPageAIContext.
+ *
+ * Consumers can add their own tool schemas via `clientToolSchemas` in AiChatBackendConfig.
+ */
+export const BUILT_IN_PAGE_TOOL_SCHEMAS: Record<string, Tool> = {
+	/**
+	 * Fill in the blog post editor form fields.
+	 * Registered by blog new/edit page via useRegisterPageAIContext.
+	 */
+	fillBlogForm: tool({
+		description:
+			"Fill in the blog post editor form fields. Call this when the user asks to write, draft, or populate a blog post. You can fill any combination of title, content, excerpt, and tags.",
+		inputSchema: z.object({
+			title: z.string().optional().describe("The post title"),
+			content: z
+				.string()
+				.optional()
+				.describe(
+					"Full markdown content for the post body. Use proper markdown formatting with headings, lists, etc.",
+				),
+			excerpt: z
+				.string()
+				.optional()
+				.describe("A short summary/excerpt of the post (1-2 sentences)"),
+			tags: z
+				.array(z.string())
+				.optional()
+				.describe("Array of tag names to apply to the post"),
+		}),
+	}),
+
+	/**
+	 * Replace the UI builder page layers with new ones.
+	 * Registered by the UI builder edit page via useRegisterPageAIContext.
+	 */
+	updatePageLayers: tool({
+		description: `Replace the UI builder page component layers. Call this when the user asks to change, add, redesign, or update the page layout and components.
+
+Rules:
+- Provide the COMPLETE layer tree, not a partial diff. The entire tree will replace the current layers.
+- Only use component types that appear in the "Available Component Types" list in the page context.
+- Every layer must have a unique \`id\` string (e.g. "hero-section", "card-title-1").
+- The \`type\` field must exactly match a name from the component registry (e.g. "div", "Button", "Card", "Flexbox").
+- The \`name\` field is the human-readable label shown in the layers panel.
+- \`props\` contains component-specific props (className uses Tailwind classes).
+- \`children\` is either an array of child ComponentLayer objects, or a plain string for text content.
+- Use \`Flexbox\` or \`Grid\` for layout instead of raw div flex/grid when possible.
+- Preserve any layers the user has not asked to change — read the current layers from the page context first.
+- ALWAYS use shadcn/ui semantic color tokens in className (e.g. bg-background, bg-card, bg-primary, text-foreground, text-muted-foreground, text-primary-foreground, border-border) instead of hardcoded Tailwind colors like bg-white, bg-gray-*, text-black, etc. This ensures the UI automatically adapts to light and dark themes.`,
+		inputSchema: z.object({
+			layers: z
+				.array(
+					z.object({
+						id: z.string().describe("Unique identifier for this layer"),
+						type: z
+							.string()
+							.describe(
+								"Component type — must match a key in the component registry (e.g. 'div', 'Button', 'Card', 'Flexbox')",
+							),
+						name: z
+							.string()
+							.describe(
+								"Human-readable display name shown in the layers panel",
+							),
+						props: z
+							.record(z.string(), z.any())
+							.describe(
+								"Component props object. Use Tailwind classes for className. See the component registry for valid props per type.",
+							),
+						children: z
+							.any()
+							.optional()
+							.describe(
+								"Child layers (array of ComponentLayer) or plain text string",
+							),
+					}),
+				)
+				.describe(
+					"Complete replacement layer tree. Must include ALL layers for the page, not just changed ones.",
+				),
+		}),
+	}),
+};