@delmaredigital/payload-puck 0.6.13 → 0.6.15

package/README.md

@@ -2,9 +2,21 @@
 
 A PayloadCMS plugin for integrating [Puck](https://puckeditor.com) visual page builder. Build pages visually with drag-and-drop components while leveraging Payload's content management capabilities.
 
-[![Demo](https://img.shields.io/badge/Demo-Live-blue)](https://demo.delmaredigital.com)
-[![Starter Template](https://img.shields.io/badge/Starter-Template-green)](https://github.com/delmaredigital/dd-starter)
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D)
+<p align="center">
+  <a href="https://demo.delmaredigital.com"><img src="https://img.shields.io/badge/Live_Demo-Try_It_Now-2ea44f?style=for-the-badge&logo=vercel&logoColor=white" alt="Live Demo - Try It Now"></a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/delmaredigital/dd-starter"><img src="https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white" alt="Starter Template - Use This"></a>
+</p>
+
+<p align="center">
+  <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32"></a>
+</p>
+
+---
+
+## Documentation
+
+For additional documentation, visit: [https://deepwiki.com/delmaredigital/payload-puck](https://deepwiki.com/delmaredigital/payload-puck)
 
 ---
 

package/dist/admin/EditWithPuckButton.d.ts

@@ -71,4 +71,3 @@ export declare function EditWithPuckLink({ id, collectionSlug, editorPathPattern
     adminRoute?: string;
 }): import("react").JSX.Element;
 export default EditWithPuckButton;
-//# sourceMappingURL=EditWithPuckButton.d.ts.map

package/dist/admin/EditWithPuckButton.js

@@ -150,5 +150,3 @@ import { useDocumentInfo, useConfig } from '@payloadcms/ui';
     });
 }
 export default EditWithPuckButton;
-
-//# sourceMappingURL=EditWithPuckButton.js.map

package/dist/admin/EditWithPuckCell.d.ts

@@ -40,4 +40,3 @@ export interface EditWithPuckCellConfig {
  */
 export declare const EditWithPuckCell: React.FC<DefaultCellComponentProps>;
 export default EditWithPuckCell;
-//# sourceMappingURL=EditWithPuckCell.d.ts.map

package/dist/admin/EditWithPuckCell.js

@@ -92,5 +92,3 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
     });
 };
 export default EditWithPuckCell;
-
-//# sourceMappingURL=EditWithPuckCell.js.map

package/dist/admin/PuckEditorView.d.ts

@@ -82,4 +82,3 @@ export interface PuckEditorViewProps {
  */
 export declare function PuckEditorView({ config, collectionSlug, apiBasePath, backUrl, previewUrl, layoutStyles, layoutKey, plugins, onSaveSuccess, onSaveError, }: PuckEditorViewProps): import("react").JSX.Element;
 export default PuckEditorView;
-//# sourceMappingURL=PuckEditorView.d.ts.map

package/dist/admin/PuckEditorView.js

@@ -217,5 +217,3 @@ import { useParams, useSearchParams } from 'next/navigation';
     });
 }
 export default PuckEditorView;
-
-//# sourceMappingURL=PuckEditorView.js.map

package/dist/admin/client.d.ts

@@ -9,4 +9,3 @@
  */
 export { EditWithPuckButton, EditWithPuckLink, type EditWithPuckButtonProps, } from './EditWithPuckButton.js';
 export { EditWithPuckCell, type EditWithPuckCellConfig } from './EditWithPuckCell.js';
-//# sourceMappingURL=client.d.ts.map

package/dist/admin/client.js

@@ -11,5 +11,3 @@
 export { EditWithPuckButton, EditWithPuckLink } from './EditWithPuckButton.js';
 // Cell component for list view
 export { EditWithPuckCell } from './EditWithPuckCell.js';
-
-//# sourceMappingURL=client.js.map

package/dist/admin/generateAdminComponents.d.ts

@@ -48,4 +48,3 @@ export interface AdminComponentsConfig {
  * ```
  */
 export declare function generatePuckEditField(config?: AdminComponentsConfig): Field;
-//# sourceMappingURL=generateAdminComponents.d.ts.map

package/dist/admin/generateAdminComponents.js

@@ -38,5 +38,3 @@
         }
     };
 }
-
-//# sourceMappingURL=generateAdminComponents.js.map

package/dist/admin/index.d.ts

@@ -18,4 +18,3 @@ export type { EditWithPuckButtonProps } from './EditWithPuckButton.js';
 export type { EditWithPuckCellConfig } from './EditWithPuckCell.js';
 export type { AdminComponentsConfig } from './generateAdminComponents.js';
 export { generatePuckEditField } from './generateAdminComponents.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/admin/index.js

@@ -15,5 +15,3 @@
  */ // Re-export types only (safe for RSC)
 // Helper for generating edit button field (safe for RSC)
 export { generatePuckEditField } from './generateAdminComponents.js';
-
-//# sourceMappingURL=index.js.map

package/dist/ai/collections/AiContext.d.ts

@@ -13,4 +13,3 @@ import type { CollectionConfig } from 'payload';
  * - "Industry Context" - Your market and audience
  */
 export declare const AiContextCollection: CollectionConfig;
-//# sourceMappingURL=AiContext.d.ts.map

package/dist/ai/collections/AiContext.js

@@ -110,5 +110,3 @@
     ],
     timestamps: true
 };
-
-//# sourceMappingURL=AiContext.js.map

package/dist/ai/collections/AiPrompts.d.ts

@@ -7,4 +7,3 @@ import type { CollectionConfig } from 'payload';
  * start common AI generation tasks.
  */
 export declare const AiPromptsCollection: CollectionConfig;
-//# sourceMappingURL=AiPrompts.d.ts.map

package/dist/ai/collections/AiPrompts.js

@@ -64,5 +64,3 @@
     ],
     timestamps: true
 };
-
-//# sourceMappingURL=AiPrompts.js.map

package/dist/ai/createAiApiRoutes.d.ts

@@ -37,4 +37,3 @@ import type { PuckAiRoutesConfig, PuckAiRouteHandlers } from './types.js';
  * ```
  */
 export declare function createPuckAiApiRoutes(config: PuckAiRoutesConfig): PuckAiRouteHandlers;
-//# sourceMappingURL=createAiApiRoutes.d.ts.map

package/dist/ai/createAiApiRoutes.js

@@ -75,8 +75,10 @@
                         puckTools[name] = tool({
                             description: toolDef.description,
                             inputSchema: toolDef.inputSchema,
+                            outputSchema: toolDef.outputSchema,
                             execute: toolDef.execute,
-                            name: toolDef.name
+                            name: toolDef.name,
+                            mode: toolDef.mode
                         });
                     }
                 }
@@ -86,7 +88,8 @@
                     host: ai?.host,
                     ai: {
                         context: ai?.context,
-                        tools: Object.keys(puckTools).length > 0 ? puckTools : undefined
+                        tools: Object.keys(puckTools).length > 0 ? puckTools : undefined,
+                        onFinish: ai?.onFinish
                     }
                 });
             } catch (error) {
@@ -111,5 +114,3 @@
         }
     };
 }
-
-//# sourceMappingURL=createAiApiRoutes.js.map

package/dist/ai/createAiGenerate.d.ts

@@ -62,4 +62,3 @@ import type { AiGenerateConfig, AiGenerateFunction } from './types.js';
  * ```
  */
 export declare function createAiGenerate(config: AiGenerateConfig): AiGenerateFunction;
-//# sourceMappingURL=createAiGenerate.d.ts.map

package/dist/ai/createAiGenerate.js

@@ -80,8 +80,10 @@
                 puckTools[name] = tool({
                     description: toolDef.description,
                     inputSchema: toolDef.inputSchema,
+                    outputSchema: toolDef.outputSchema,
                     execute: toolDef.execute,
-                    name: toolDef.name
+                    name: toolDef.name,
+                    mode: toolDef.mode
                 });
             }
         }
@@ -93,7 +95,8 @@
             apiKey: ai?.apiKey,
             host: ai?.host,
             pageData,
-            tools: Object.keys(puckTools).length > 0 ? puckTools : undefined
+            tools: Object.keys(puckTools).length > 0 ? puckTools : undefined,
+            onFinish: ai?.onFinish
         });
         if (!result) {
             throw new Error('AI generation failed: no result returned');
@@ -101,5 +104,3 @@
         return result;
     };
 }
-
-//# sourceMappingURL=createAiGenerate.js.map

package/dist/ai/createAiPlugin.d.ts

@@ -36,4 +36,3 @@ import type { AiPluginOptions } from './types.js';
  * ```
  */
 export declare function createAiPlugin(options?: AiPluginOptions): PuckPlugin;
-//# sourceMappingURL=createAiPlugin.d.ts.map

package/dist/ai/createAiPlugin.js

@@ -34,7 +34,7 @@
  * <PuckEditor plugins={[aiPlugin]} />
  * ```
  */ export function createAiPlugin(options = {}) {
-    const { host = '/api/puck', examplePrompts, onSubmit } = options;
+    const { host = '/api/puck', examplePrompts, onSubmit, prepareRequest, scrollTracking } = options;
     // Dynamic import to avoid build errors if plugin-ai not installed
     // Also allows for tree-shaking when AI is not used
     try {
@@ -45,7 +45,9 @@
             chat: {
                 examplePrompts,
                 onSubmit
-            }
+            },
+            prepareRequest,
+            scrollTracking
         });
     } catch (e) {
         // Return a placeholder plugin if @puckeditor/plugin-ai is not installed
@@ -55,5 +57,3 @@
         };
     }
 }
-
-//# sourceMappingURL=createAiPlugin.js.map

package/dist/ai/hooks/useAiContext.d.ts

@@ -60,4 +60,3 @@ export interface UseAiContextReturn {
  * ```
  */
 export declare function useAiContext(options?: UseAiContextOptions): UseAiContextReturn;
-//# sourceMappingURL=useAiContext.d.ts.map

package/dist/ai/hooks/useAiContext.js

@@ -153,5 +153,3 @@ import { useState, useEffect, useCallback } from 'react';
         remove
     };
 }
-
-//# sourceMappingURL=useAiContext.js.map

package/dist/ai/hooks/useAiPrompts.d.ts

@@ -22,4 +22,3 @@ export declare function useAiPrompts(apiEndpoint?: string, enabled?: boolean): {
     error: string | null;
     refetch: () => Promise<void>;
 };
-//# sourceMappingURL=useAiPrompts.d.ts.map

package/dist/ai/hooks/useAiPrompts.js

@@ -78,5 +78,3 @@ import { useState, useEffect, useCallback } from 'react';
         refetch: fetchPrompts
     };
 }
-
-//# sourceMappingURL=useAiPrompts.js.map

package/dist/ai/index.d.ts

@@ -48,4 +48,3 @@ export { injectAiConfig, hasAiConfig } from './utils/injectAiConfig.js';
 export { defaultComponentAiConfig, minimalComponentAiConfig, } from './presets/componentAiDefaults.js';
 export { comprehensiveComponentAiConfig, pagePatternSystemContext, pagePatternContext, componentFieldReference, allComponents, componentNames, typographyInstructions, layoutInstructions, interactiveInstructions, mediaInstructions, } from './presets/index.js';
 export type { AiTool, AiToolContext, AiOptions, AiFieldConfig, AiComponentConfig, PuckAiRoutesConfig, PuckAiRouteHandlers, AiGenerateConfig, AiGenerateOptions, AiGenerateFunction, AiPluginOptions, AiExamplePrompt, PromptEditorPluginOptions, ComponentAiOverrides, AiPrompt, AiContext, ContextEditorPluginOptions, PuckPluginAiConfig, } from './types.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.js

@@ -64,5 +64,3 @@ export { defaultComponentAiConfig, minimalComponentAiConfig } from './presets/co
 // New comprehensive AI config exports
 export { comprehensiveComponentAiConfig, pagePatternSystemContext, pagePatternContext, componentFieldReference, allComponents, componentNames, // Individual instruction modules for advanced usage
 typographyInstructions, layoutInstructions, interactiveInstructions, mediaInstructions } from './presets/index.js';
-
-//# sourceMappingURL=index.js.map

package/dist/ai/plugins/ContextEditorPanel.d.ts

@@ -6,4 +6,3 @@ interface ContextEditorPanelProps extends ContextEditorPluginOptions {
  */
 export declare function ContextEditorPanel({ apiEndpoint, canEdit, canCreate, canDelete, }: ContextEditorPanelProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=ContextEditorPanel.d.ts.map

package/dist/ai/plugins/ContextEditorPanel.js

@@ -687,5 +687,3 @@ const CATEGORY_OPTIONS = [
         ]
     });
 }
-
-//# sourceMappingURL=ContextEditorPanel.js.map

package/dist/ai/plugins/PromptEditorPanel.d.ts

@@ -6,4 +6,3 @@ interface PromptEditorPanelProps extends PromptEditorPluginOptions {
  */
 export declare function PromptEditorPanel({ apiEndpoint, canEdit, canCreate, canDelete, }: PromptEditorPanelProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=PromptEditorPanel.d.ts.map

package/dist/ai/plugins/PromptEditorPanel.js

@@ -452,5 +452,3 @@ import { dispatchPromptsUpdated } from '../hooks/useAiPrompts.js';
         ]
     });
 }
-
-//# sourceMappingURL=PromptEditorPanel.js.map

package/dist/ai/plugins/contextEditorPlugin.d.ts

@@ -27,4 +27,3 @@ import type { ContextEditorPluginOptions } from '../types.js';
  * ```
  */
 export declare function createContextEditorPlugin(options?: ContextEditorPluginOptions): PuckPlugin;
-//# sourceMappingURL=contextEditorPlugin.d.ts.map

package/dist/ai/plugins/contextEditorPlugin.js

@@ -43,5 +43,3 @@ import { ContextEditorPanel } from './ContextEditorPanel.js';
             })
     };
 }
-
-//# sourceMappingURL=contextEditorPlugin.js.map

package/dist/ai/plugins/promptApiRoutes.d.ts

@@ -65,4 +65,3 @@ export declare function createPromptApiRoutesWithId(config: PromptApiRoutesConfi
     PATCH: RouteHandlerWithId;
     DELETE: RouteHandlerWithId;
 };
-//# sourceMappingURL=promptApiRoutes.d.ts.map

package/dist/ai/plugins/promptApiRoutes.js

@@ -246,5 +246,3 @@ import { getPayload } from 'payload';
         }
     };
 }
-
-//# sourceMappingURL=promptApiRoutes.js.map

package/dist/ai/plugins/promptEditorPlugin.d.ts

@@ -26,4 +26,3 @@ import type { PromptEditorPluginOptions } from '../types.js';
  * ```
  */
 export declare function createPromptEditorPlugin(options?: PromptEditorPluginOptions): PuckPlugin;
-//# sourceMappingURL=promptEditorPlugin.d.ts.map

package/dist/ai/plugins/promptEditorPlugin.js

@@ -42,5 +42,3 @@ import { PromptEditorPanel } from './PromptEditorPanel.js';
             })
     };
 }
-
-//# sourceMappingURL=promptEditorPlugin.js.map

package/dist/ai/presets/componentAiDefaults.d.ts

@@ -37,4 +37,3 @@ export declare const defaultComponentAiConfig: ComponentAiOverrides;
  * required fields. Custom fields are still auto-excluded by injectAiConfig.
  */
 export declare const minimalComponentAiConfig: ComponentAiOverrides;
-//# sourceMappingURL=componentAiDefaults.d.ts.map

package/dist/ai/presets/componentAiDefaults.js

@@ -260,5 +260,3 @@
         }
     }
 };
-
-//# sourceMappingURL=componentAiDefaults.js.map

package/dist/ai/presets/index.d.ts

@@ -91,4 +91,3 @@ export { typographyInstructions } from './instructions/typography.js';
 export { layoutInstructions } from './instructions/layout.js';
 export { interactiveInstructions } from './instructions/interactive.js';
 export { mediaInstructions } from './instructions/media.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/ai/presets/index.js

@@ -100,5 +100,3 @@ export { typographyInstructions } from './instructions/typography.js';
 export { layoutInstructions } from './instructions/layout.js';
 export { interactiveInstructions } from './instructions/interactive.js';
 export { mediaInstructions } from './instructions/media.js';
-
-//# sourceMappingURL=index.js.map

package/dist/ai/presets/instructions/interactive.d.ts

@@ -12,4 +12,3 @@ export declare const interactiveInstructions: ComponentAiOverrides;
  * Interactive component names for reference
  */
 export declare const interactiveComponents: readonly ["Button", "Card", "Accordion", "Divider"];
-//# sourceMappingURL=interactive.d.ts.map

package/dist/ai/presets/instructions/interactive.js

@@ -340,5 +340,3 @@ Example: { hex: '#e5e7eb', opacity: 100 }`,
     'Accordion',
     'Divider'
 ];
-
-//# sourceMappingURL=interactive.js.map

package/dist/ai/presets/instructions/layout.d.ts

@@ -13,4 +13,3 @@ export declare const layoutInstructions: ComponentAiOverrides;
  * Layout component names for reference
  */
 export declare const layoutComponents: readonly ["Section", "Container", "Flex", "Grid", "Spacer"];
-//# sourceMappingURL=layout.d.ts.map

package/dist/ai/presets/instructions/layout.js

@@ -487,5 +487,3 @@ WHEN NOT TO USE:
     'Grid',
     'Spacer'
 ];
-
-//# sourceMappingURL=layout.js.map

package/dist/ai/presets/instructions/media.d.ts

@@ -12,4 +12,3 @@ export declare const mediaInstructions: ComponentAiOverrides;
  * Media component names for reference
  */
 export declare const mediaComponents: readonly ["Image", "Template"];
-//# sourceMappingURL=media.d.ts.map

package/dist/ai/presets/instructions/media.js

@@ -134,5 +134,3 @@ rather than relying on Template placeholders that users must configure later.`
     'Image',
     'Template'
 ];
-
-//# sourceMappingURL=media.js.map

package/dist/ai/presets/instructions/pagePatterns.d.ts

@@ -17,4 +17,3 @@ export declare const pagePatternContext = "\n## Page Composition Guidelines\n\nW
  * Useful as a quick reference in AI context
  */
 export declare const componentFieldReference = "\n## Quick Field Reference\n\nBUTTON: text (required), link (required), variant (default/secondary/outline), size (sm/default/lg), openInNewTab (yes/no)\n\nCARD: heading (required), text, image (user selects), link, shadow (none/sm/md/lg/xl)\n\nHEADING: text (required), level (h1-h6), alignment (left/center/right)\n\nTEXT: content (required), size (xs/sm/base/lg/xl), alignment (left/center/right)\n\nRICHTEXT: content (required, HTML string)\n\nACCORDION: items (array of {title, content, defaultOpen}), allowMultiple (yes/no)\n\nSECTION: content (slot), semanticElement, id, sectionBackground, sectionPadding\n  - sectionBackground: { type: 'solid', solid: { hex, opacity? } } or { type: 'gradient', gradient: { type, angle, stops } }\n  - sectionPadding: { xs: { top, right, bottom, left, unit: 'px', linked: boolean } }\n\nFLEX: content (slot), direction (row/column), justifyContent, alignItems, gap (number), wrap (wrap/nowrap)\n  - justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between'\n  - alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'\n\nGRID: content (slot), numColumns (1-12), gap (number)\n\nSPACER: size (8/16/24/32/48/64/80/96/128), direction (vertical/horizontal/both)\n\nDIVIDER: style (solid/dashed/dotted)\n\nIMAGE: image (user selects), alt, aspectRatio (auto/1:1/16:9/4:3/3:2), link\n";
-//# sourceMappingURL=pagePatterns.d.ts.map

package/dist/ai/presets/instructions/pagePatterns.js

@@ -284,5 +284,3 @@ DIVIDER: style (solid/dashed/dotted)
 
 IMAGE: image (user selects), alt, aspectRatio (auto/1:1/16:9/4:3/3:2), link
 `;
-
-//# sourceMappingURL=pagePatterns.js.map

package/dist/ai/presets/instructions/schemas.d.ts

@@ -1244,4 +1244,3 @@ export declare const transformSchema: {
         };
     };
 };
-//# sourceMappingURL=schemas.d.ts.map

package/dist/ai/presets/instructions/schemas.js

@@ -594,5 +594,3 @@
         }
     }
 };
-
-//# sourceMappingURL=schemas.js.map

package/dist/ai/presets/instructions/typography.d.ts

@@ -13,4 +13,3 @@ export declare const typographyInstructions: ComponentAiOverrides;
  * Typography component names for reference
  */
 export declare const typographyComponents: readonly ["Heading", "Text", "RichText"];
-//# sourceMappingURL=typography.d.ts.map

package/dist/ai/presets/instructions/typography.js

@@ -193,5 +193,3 @@ COMPOSITION:
     'Text',
     'RichText'
 ];
-
-//# sourceMappingURL=typography.js.map

package/dist/ai/tools/index.d.ts

@@ -113,4 +113,3 @@ export declare function createPayloadTools(config: PayloadToolsConfig): Record<s
  * ```
  */
 export declare function createTool<TInput, TOutput>(tool: AiTool<TInput, TOutput>): AiTool<TInput, TOutput>;
-//# sourceMappingURL=index.d.ts.map

package/dist/ai/tools/index.js

@@ -247,5 +247,3 @@
  */ export function createTool(tool) {
     return tool;
 }
-
-//# sourceMappingURL=index.js.map

package/dist/ai/types.d.ts

@@ -58,6 +58,18 @@ export interface AiTool<TInput = unknown, TOutput = unknown> {
      * Optional name for the tool
      */
     name?: string;
+    /**
+     * Controls how the tool interacts with the AI agent.
+     * - "auto": Agent decides when to use the tool (default)
+     * - "preload": Tool result is fetched before generation starts
+     * - "inline": Tool runs inline during generation
+     */
+    mode?: 'auto' | 'preload' | 'inline';
+    /**
+     * Optional output schema for the tool's return value.
+     * Must be a Zod schema.
+     */
+    outputSchema?: import('zod').ZodTypeAny;
 }
 /**
  * AI-specific configuration options for the server-side handler
@@ -97,6 +109,27 @@ export interface AiOptions {
      * Custom Puck Cloud host URL
      */
     host?: string;
+    /**
+     * Callback invoked when AI generation finishes.
+     * Provides usage metrics for cost tracking and analytics.
+     *
+     * @example
+     * ```typescript
+     * onFinish: ({ totalCost, tokenUsage }) => {
+     *   console.log(`Used ${tokenUsage.totalTokens} tokens, cost: ${totalCost}`)
+     * }
+     * ```
+     */
+    onFinish?: (result: {
+        totalCost: number;
+        tokenUsage: {
+            inputTokens: number | undefined;
+            outputTokens: number | undefined;
+            totalTokens: number | undefined;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+        };
+    }) => void;
 }
 /**
  * AI configuration for a Puck field
@@ -140,6 +173,25 @@ export interface AiFieldConfig {
         type: string;
         [key: string]: unknown;
     };
+    /**
+     * Bind this field to a named tool. The tool runs during generation
+     * and its result populates this field deterministically.
+     *
+     * @example
+     * ```typescript
+     * fields: {
+     *   src: {
+     *     type: 'text',
+     *     ai: { bind: 'getImageUrl' },
+     *   },
+     * }
+     * ```
+     */
+    bind?: string;
+    /**
+     * Whether this field's value should be streamed during AI generation.
+     */
+    stream?: boolean;
 }
 /**
  * AI configuration for a Puck component
@@ -161,8 +213,21 @@ export interface AiComponentConfig {
      */
     instructions?: string;
     /**
-     * Custom JSON schema for the entire component.
-     * For when Puck can't infer from fields.
+     * Exclude this component from AI generation.
+     * The component remains available for manual use in the editor.
+     */
+    exclude?: boolean;
+    /**
+     * Controls which components are allowed/disallowed in the default slot zone
+     * during AI generation.
+     */
+    defaultZone?: {
+        allow?: string[];
+        disallow?: string[];
+        disabled?: boolean;
+    };
+    /**
+     * @deprecated Removed in Puck AI 0.4. Use field-level `schema` on `AiFieldConfig` instead.
      */
     schema?: {
         type: 'object';
@@ -319,6 +384,34 @@ export interface AiPluginOptions {
      * Callback when user submits a prompt
      */
     onSubmit?: (prompt: string) => void;
+    /**
+     * Intercept and modify outgoing AI requests before they are sent.
+     * Use this to add custom headers, credentials, or body data.
+     *
+     * @example
+     * ```typescript
+     * prepareRequest: (opts) => ({
+     *   ...opts,
+     *   headers: { ...opts.headers, Authorization: 'Bearer token' },
+     *   credentials: 'include',
+     * })
+     * ```
+     */
+    prepareRequest?: (opts: {
+        body?: {
+            chatId?: string;
+            trigger?: string;
+            [key: string]: any;
+        };
+        headers?: HeadersInit;
+        credentials?: RequestCredentials;
+    }) => any | Promise<any>;
+    /**
+     * Enable automatic scroll tracking during AI generation.
+     * When true, the editor scrolls to follow new content as it streams in.
+     * @default true (in @puckeditor/plugin-ai 0.4+)
+     */
+    scrollTracking?: boolean;
 }
 /**
  * AI configuration overrides for components
@@ -503,5 +596,18 @@ export interface PuckPluginAiConfig {
      * ```
      */
     componentInstructions?: ComponentAiOverrides;
+    /**
+     * Callback invoked when AI generation finishes.
+     * Provides usage metrics for cost tracking and analytics.
+     */
+    onFinish?: (result: {
+        totalCost: number;
+        tokenUsage: {
+            inputTokens: number | undefined;
+            outputTokens: number | undefined;
+            totalTokens: number | undefined;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+        };
+    }) => void;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/ai/types.js

@@ -4,5 +4,3 @@
 /**
  * AI configuration for createPuckPlugin
  */ export { };
-
-//# sourceMappingURL=types.js.map

package/dist/ai/utils/injectAiConfig.d.ts

@@ -64,4 +64,3 @@ export declare function injectAiConfig(config: PuckConfig, overrides: ComponentA
  * @returns True if any component has AI configuration
  */
 export declare function hasAiConfig(config: PuckConfig): boolean;
-//# sourceMappingURL=injectAiConfig.d.ts.map

package/dist/ai/utils/injectAiConfig.js

@@ -205,5 +205,3 @@
     }
     return false;
 }
-
-//# sourceMappingURL=injectAiConfig.js.map