@btst/stack 2.3.0 → 2.5.0

package/dist/shared/{stack.rTy7-wQU.d.mts → stack.n1_i1p2B.d.cts}

@@ -1,18 +1,18 @@
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
 import * as better_call from 'better-call';
 import { Adapter } from '@btst/db';
-import { B as BoardWithColumns, d as Board, e as Column, T as Task, C as ColumnWithTasks } from './stack.DJaKVY7v.mjs';
+import { B as BoardWithColumns, P as Priority, T as Task, d as Board, e as Column, C as ColumnWithTasks } from './stack.DJaKVY7v.cjs';
 import { z } from 'zod';
 import { QueryClient } from '@tanstack/react-query';
 
 declare const createBoardSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
-    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     slug: z.ZodOptional<z.ZodString>;
     ownerId: z.ZodOptional<z.ZodString>;
     organizationId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
 }, z.core.$strip>;
 declare const updateBoardSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
@@ -28,8 +28,8 @@ declare const createColumnSchema: z.ZodObject<{
     title: z.ZodString;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    boardId: z.ZodString;
     order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    boardId: z.ZodString;
 }, z.core.$strip>;
 declare const updateColumnSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
@@ -109,6 +109,58 @@ declare function getAllBoards(adapter: Adapter, params?: z.infer<typeof BoardLis
  */
 declare function getBoardById(adapter: Adapter, id: string): Promise<BoardWithColumns | null>;
 
+/**
+ * Input for creating a new Kanban task.
+ */
+interface CreateKanbanTaskInput {
+    title: string;
+    columnId: string;
+    description?: string;
+    priority?: Priority;
+    assigneeId?: string;
+}
+/**
+ * Create a new task in a Kanban column.
+ * Computes the next order value from existing tasks in the column.
+ *
+ * @remarks **Security:** No authorization hooks (onBeforeCreateTask) are called.
+ * The caller is responsible for any access-control checks before invoking this
+ * function.
+ *
+ * @param adapter - The database adapter
+ * @param input - Task creation input
+ */
+declare function createKanbanTask(adapter: Adapter, input: CreateKanbanTaskInput): Promise<Task>;
+/**
+ * Find a board by slug, or create it with the given name and custom column titles.
+ *
+ * Concurrency-safe at two levels:
+ * - **Same process**: concurrent calls with the same slug share a single in-flight
+ *   Promise (via `_pendingBoardCreations`), so only one DB write is attempted.
+ * - **Cross-instance**: the DB `unique` constraint on `slug` causes the losing
+ *   write to throw; the catch block re-fetches and returns the winner's board.
+ *
+ * @remarks **Security:** No authorization hooks are called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - Unique URL-safe slug for the board
+ * @param name - Display name for the board (used only on creation)
+ * @param columnTitles - Ordered list of column names to create (used only on creation)
+ */
+declare function findOrCreateKanbanBoard(adapter: Adapter, slug: string, name: string, columnTitles: string[]): Promise<Board>;
+/**
+ * Retrieve all columns for a given board, sorted by order.
+ * Co-located with mutations because it is primarily used alongside
+ * {@link createKanbanTask} to resolve column IDs before task creation.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ *
+ * @param adapter - The database adapter
+ * @param boardId - The board ID
+ */
+declare function getKanbanColumnsByBoardId(adapter: Adapter, boardId: string): Promise<Column[]>;
+
 /**
  * Route keys for the Kanban plugin — matches the keys returned by
  * `stackClient.router.getRoute(path).routeKey`.
@@ -137,25 +189,25 @@ interface KanbanApiContext<TBody = unknown, TParams = unknown, TQuery = unknown>
  */
 interface KanbanBackendHooks {
     /**
-     * Called before listing boards. Return false to deny access.
+     * Called before listing boards. Throw an error to deny access.
      */
-    onBeforeListBoards?: (filter: z.infer<typeof BoardListQuerySchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeListBoards?: (filter: z.infer<typeof BoardListQuerySchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before creating a board. Return false to deny access.
+     * Called before creating a board. Throw an error to deny access.
      */
-    onBeforeCreateBoard?: (data: z.infer<typeof createBoardSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeCreateBoard?: (data: z.infer<typeof createBoardSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before reading a single board. Return false to deny access.
+     * Called before reading a single board. Throw an error to deny access.
      */
-    onBeforeReadBoard?: (boardId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeReadBoard?: (boardId: string, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before updating a board. Return false to deny access.
+     * Called before updating a board. Throw an error to deny access.
      */
-    onBeforeUpdateBoard?: (boardId: string, data: z.infer<typeof updateBoardSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeUpdateBoard?: (boardId: string, data: z.infer<typeof updateBoardSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before deleting a board. Return false to deny access.
+     * Called before deleting a board. Throw an error to deny access.
      */
-    onBeforeDeleteBoard?: (boardId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeDeleteBoard?: (boardId: string, context: KanbanApiContext) => Promise<void> | void;
     /**
      * Called after boards are listed successfully.
      * Receives the items array (same shape as `board[]`) for consistency
@@ -199,17 +251,17 @@ interface KanbanBackendHooks {
      */
     onDeleteBoardError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before creating a column. Return false to deny access.
+     * Called before creating a column. Throw an error to deny access.
      */
-    onBeforeCreateColumn?: (data: z.infer<typeof createColumnSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeCreateColumn?: (data: z.infer<typeof createColumnSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before updating a column. Return false to deny access.
+     * Called before updating a column. Throw an error to deny access.
      */
-    onBeforeUpdateColumn?: (columnId: string, data: z.infer<typeof updateColumnSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeUpdateColumn?: (columnId: string, data: z.infer<typeof updateColumnSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before deleting a column. Return false to deny access.
+     * Called before deleting a column. Throw an error to deny access.
      */
-    onBeforeDeleteColumn?: (columnId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeDeleteColumn?: (columnId: string, context: KanbanApiContext) => Promise<void> | void;
     /**
      * Called after a column is created successfully
      */
@@ -223,17 +275,17 @@ interface KanbanBackendHooks {
      */
     onColumnDeleted?: (columnId: string, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before creating a task. Return false to deny access.
+     * Called before creating a task. Throw an error to deny access.
      */
-    onBeforeCreateTask?: (data: z.infer<typeof createTaskSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeCreateTask?: (data: z.infer<typeof createTaskSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before updating a task. Return false to deny access.
+     * Called before updating a task. Throw an error to deny access.
      */
-    onBeforeUpdateTask?: (taskId: string, data: z.infer<typeof updateTaskSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeUpdateTask?: (taskId: string, data: z.infer<typeof updateTaskSchema>, context: KanbanApiContext) => Promise<void> | void;
     /**
-     * Called before deleting a task. Return false to deny access.
+     * Called before deleting a task. Throw an error to deny access.
      */
-    onBeforeDeleteTask?: (taskId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    onBeforeDeleteTask?: (taskId: string, context: KanbanApiContext) => Promise<void> | void;
     /**
      * Called after a task is created successfully
      */
@@ -272,11 +324,11 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
         body: z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
             name: z.ZodString;
-            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
             slug: z.ZodOptional<z.ZodString>;
             ownerId: z.ZodOptional<z.ZodString>;
             organizationId: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
         }, z.core.$strip>;
     }, {
         columns: ColumnWithTasks[];
@@ -294,11 +346,11 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
         body: z.ZodObject<{
             description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
             name: z.ZodOptional<z.ZodString>;
-            createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
-            updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
             slug: z.ZodOptional<z.ZodString>;
             ownerId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
             organizationId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
         }, z.core.$strip>;
     }, Board>;
     readonly deleteBoard: better_call.StrictEndpoint<"/boards/:id", {
@@ -312,8 +364,8 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
             title: z.ZodString;
             createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
             updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-            boardId: z.ZodString;
             order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            boardId: z.ZodString;
         }, z.core.$strip>;
     }, Column>;
     readonly updateColumn: better_call.StrictEndpoint<"/columns/:id", {
@@ -322,8 +374,8 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
             title: z.ZodOptional<z.ZodString>;
             createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
             updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
-            boardId: z.ZodOptional<z.ZodString>;
             order: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodNumber>>>;
+            boardId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, Column>;
     readonly deleteColumn: better_call.StrictEndpoint<"/columns/:id", {
@@ -406,6 +458,9 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
     getAllBoards: (params?: Parameters<typeof getAllBoards>[1]) => Promise<BoardListResult>;
     getBoardById: (id: string) => Promise<BoardWithColumns | null>;
     prefetchForRoute: KanbanPrefetchForRoute;
+    createTask: (input: Parameters<typeof createKanbanTask>[1]) => Promise<Task>;
+    findOrCreateBoard: (slug: string, name: string, columnTitles: string[]) => Promise<Board>;
+    getColumnsByBoardId: (boardId: string) => Promise<Column[]>;
 }>;
 type KanbanApiRouter = ReturnType<ReturnType<typeof kanbanBackendPlugin>["routes"]>;
 
@@ -441,5 +496,5 @@ declare const KANBAN_QUERY_KEYS: {
     boardDetail: (boardId: string) => readonly ["boards", "detail", string];
 };
 
-export { getBoardById as d, KANBAN_QUERY_KEYS as e, getAllBoards as g, kanbanBackendPlugin as k };
-export type { BoardListResult as B, KanbanApiRouter as K, KanbanRouteKey as a, KanbanApiContext as b, KanbanBackendHooks as c, BoardsListDiscriminator as f };
+export { getBoardById as d, createKanbanTask as e, findOrCreateKanbanBoard as f, getAllBoards as g, getKanbanColumnsByBoardId as h, KANBAN_QUERY_KEYS as i, kanbanBackendPlugin as k };
+export type { BoardListResult as B, CreateKanbanTaskInput as C, KanbanApiRouter as K, KanbanRouteKey as a, KanbanApiContext as b, KanbanBackendHooks as c, BoardsListDiscriminator as j };

package/dist/shared/{stack.IdtKDRka.d.cts → stack.sO33ZDhK.d.ts}

@@ -1,5 +1,5 @@
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
-import { a as SerializedContentItemWithType, S as SerializedContentType, b as ContentType, c as ContentItem, d as SerializedContentItem, e as ContentItemWithType, f as CMSBackendConfig, I as InverseRelation } from './stack.CVDTkMoO.cjs';
+import { a as SerializedContentItemWithType, S as SerializedContentType, b as ContentType, c as ContentItem, d as SerializedContentItem, e as ContentItemWithType, f as CMSBackendConfig, I as InverseRelation } from './stack.B8QD11QU.js';
 import * as better_call from 'better-call';
 import { z } from 'zod';
 import { Adapter } from '@btst/db';
@@ -78,6 +78,35 @@ declare function getContentItemById(adapter: Adapter, id: string): Promise<Seria
  */
 declare function getContentItemBySlug(adapter: Adapter, contentTypeSlug: string, slug: string): Promise<SerializedContentItemWithType | null>;
 
+/**
+ * Input for creating a new CMS content item.
+ */
+interface CreateCMSContentItemInput {
+    /** URL-safe slug for the item */
+    slug: string;
+    /** Arbitrary data payload — should match the content type schema */
+    data: Record<string, unknown>;
+}
+/**
+ * Create a new content item for a content type (looked up by slug).
+ *
+ * Bypasses Zod schema validation and relation processing — the caller is
+ * responsible for providing valid, relation-free data. For relation fields or
+ * schema validation, use the HTTP endpoint instead.
+ *
+ * Throws if the content type is not found or the slug is already taken within
+ * that content type.
+ *
+ * @remarks **Security:** No authorization hooks (`onBeforeCreate`, `onAfterCreate`)
+ * are called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param contentTypeSlug - Slug of the target content type
+ * @param input - Item slug and data payload
+ */
+declare function createCMSContentItem(adapter: Adapter, contentTypeSlug: string, input: CreateCMSContentItemInput): Promise<SerializedContentItem>;
+
 /**
  * Route keys for the CMS plugin — matches the keys returned by
  * `stackClient.router.getRoute(path).routeKey`.
@@ -257,6 +286,7 @@ declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugin
     getContentItemBySlug: (contentTypeSlug: string, slug: string) => Promise<SerializedContentItemWithType<Record<string, unknown>> | null>;
     getContentItemById: (id: string) => Promise<SerializedContentItemWithType<Record<string, unknown>> | null>;
     prefetchForRoute: CMSPrefetchForRoute;
+    createContentItem: (typeSlug: string, input: Parameters<typeof createCMSContentItem>[2]) => Promise<SerializedContentItem>;
 }>;
 type CMSApiRouter = ReturnType<ReturnType<typeof cmsBackendPlugin>["routes"]>;
 
@@ -293,5 +323,5 @@ declare const CMS_QUERY_KEYS: {
     contentDetail: (typeSlug: string, id: string) => readonly ["cmsContent", "detail", string, string];
 };
 
-export { cmsBackendPlugin as c, getAllContentItems as d, getContentItemBySlug as e, getContentItemById as f, getAllContentTypes as g, serializeContentItem as h, serializeContentItemWithType as i, CMS_QUERY_KEYS as j, serializeContentType as s };
-export type { CMSApiRouter as C, ContentListDiscriminator as a, CMSRouteKey as b };
+export { cmsBackendPlugin as c, getAllContentItems as d, getContentItemBySlug as e, getContentItemById as f, getAllContentTypes as g, serializeContentItem as h, serializeContentItemWithType as i, createCMSContentItem as j, CMS_QUERY_KEYS as l, serializeContentType as s };
+export type { CMSApiRouter as C, ContentListDiscriminator as a, CMSRouteKey as b, CreateCMSContentItemInput as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.3.0",
+  "version": "2.5.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"
       ],

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.",
+				),
+		}),
+	}),
+};