@puckeditor/plugin-ai 0.8.2 → 0.9.0-canary.50fad349

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as ai from 'ai';
+import { LanguageModelUsage, UIMessage, ChatOnFinishCallback, DataUIPart, CreateUIMessage, ChatStatus } from 'ai';
 import { PuckAction, Data, Config } from '@puckeditor/core';
-import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
 
 type _JSONSchema = boolean | JSONSchema;
 type JSONSchema = {
@@ -247,6 +248,32 @@ type PuckProviderMetadata = {
 
 type PuckMessage = UIMessage<PuckProviderMetadata, PuckDataParts>;
 
+type SubagentChildPart = {
+    kind: "text";
+    blockId: string;
+    text: string;
+} | {
+    kind: "reasoning";
+    blockId: string;
+    text: string;
+    state: "streaming" | "done";
+} | {
+    kind: "tool";
+    childToolCallId: string;
+    toolName: string;
+    input?: unknown;
+    output?: unknown;
+};
+type SubagentState = {
+    toolCallId: string;
+    parentToolCallId?: string;
+    agentType: string;
+    depth: number;
+    label: string;
+    state: "running" | "done";
+    parts: SubagentChildPart[];
+};
+
 type Mode = "assembly" | "design";
 type RequestOptions = {
     body?: {
@@ -261,6 +288,84 @@ type RequestOptions = {
     headers?: HeadersInit;
     credentials?: RequestCredentials;
 };
+type UsePuckAiOptions = {
+    /** Endpoint serving the chat stream. Defaults to `/api/puck/chat`. */
+    host?: string;
+    /**
+     * Endpoint serving one-shot generations for `stream()`. Defaults to
+     * `/api/puck/stream`.
+     */
+    streamHost?: string;
+    /**
+     * Whether the agent assembles your components or designs new ones. Read at
+     * request time, so a plugin can flip it between calls.
+     */
+    mode?: Mode;
+    apiVersion?: string;
+    /** Adjust the outgoing request — add auth headers, extra body fields. */
+    prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
+    onFinish?: ChatOnFinishCallback<PuckMessage>;
+    onError?: (error: Error) => void;
+};
+type SendMessageOptions = {
+    /** Override the hook's mode for this call. */
+    mode?: Mode;
+    /** Attachments to send alongside the prompt. */
+    files?: Extract<PuckMessage["parts"][number], {
+        type: "file";
+    }>[];
+};
+type StreamOptions = {
+    /** Override the hook's mode for this call. */
+    mode?: Mode;
+    /** Extra context for this generation. */
+    context?: string;
+};
+/**
+ * Puck AI, wired into the editor you're already inside.
+ *
+ * Call it from any plugin render or override — it reads the editor through
+ * `useGetPuck`, so there's no provider to add. `stream()` sends a prompt and
+ * applies everything that comes back to the live canvas: component writes,
+ * design-mode definitions, and the screenshot/page-data round trips the agent
+ * uses to see what it built.
+ *
+ * The UI is yours. This owns the transport and the editor mutations only.
+ */
+declare function usePuckAi({ host, streamHost, mode, apiVersion, prepareRequest, onFinish, onError, }?: UsePuckAiOptions): {
+    /**
+     * Send a prompt as the next turn of a conversation. The agent sees the
+     * history, and can write, check its work and correct itself.
+     */
+    sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
+    /**
+     * Run a one-shot generation from a prompt, with no conversation. Cheaper
+     * and more predictable than `sendMessage`, but it stops after its first
+     * write rather than reviewing the result.
+     */
+    stream: (prompt: string, opts?: StreamOptions) => Promise<void>;
+    /** Abort whichever request is in flight */
+    stop: () => void;
+    status: ai.ChatStatus;
+    /** The conversation so far, for building a transcript */
+    messages: PuckMessage[];
+    setMessages: (messages: PuckMessage[] | ((messages: PuckMessage[]) => PuckMessage[])) => void;
+    regenerate: ({ messageId, ...options }?: {
+        messageId?: string;
+    } & ai.ChatRequestOptions) => Promise<void>;
+    error: string | undefined;
+    /** Live per-tool progress, keyed by tool call id */
+    toolStatus: Record<string, ToolStatus>;
+    /** Live subagent progress, keyed by tool call id */
+    subagentState: Record<string, SubagentState>;
+    /**
+     * @internal Apply a single stream part to the editor. Exposed for
+     * replaying a recorded stream (the marketing demo) — a real agent should
+     * go through `stream`.
+     */
+    processData: (dataPart: DataUIPart<PuckDataParts>) => void;
+};
+
 type AiPluginProps = {
     host?: string;
     chat?: {
@@ -306,6 +411,7 @@ declare global {
 }
 
 declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
+
 declare function createAiPlugin(opts?: AiPluginProps): {
     label: string;
     name: string;
@@ -322,4 +428,4 @@ declare function createAiPlugin(opts?: AiPluginProps): {
     };
 };
 
-export { type ComponentAiParams, type FieldAiParams, createAiPlugin, withDynamicConfig };
+export { type ComponentAiParams, type FieldAiParams, type StreamOptions, type UsePuckAiOptions, createAiPlugin, usePuckAi, withDynamicConfig };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as ai from 'ai';
+import { LanguageModelUsage, UIMessage, ChatOnFinishCallback, DataUIPart, CreateUIMessage, ChatStatus } from 'ai';
 import { PuckAction, Data, Config } from '@puckeditor/core';
-import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
 
 type _JSONSchema = boolean | JSONSchema;
 type JSONSchema = {
@@ -247,6 +248,32 @@ type PuckProviderMetadata = {
 
 type PuckMessage = UIMessage<PuckProviderMetadata, PuckDataParts>;
 
+type SubagentChildPart = {
+    kind: "text";
+    blockId: string;
+    text: string;
+} | {
+    kind: "reasoning";
+    blockId: string;
+    text: string;
+    state: "streaming" | "done";
+} | {
+    kind: "tool";
+    childToolCallId: string;
+    toolName: string;
+    input?: unknown;
+    output?: unknown;
+};
+type SubagentState = {
+    toolCallId: string;
+    parentToolCallId?: string;
+    agentType: string;
+    depth: number;
+    label: string;
+    state: "running" | "done";
+    parts: SubagentChildPart[];
+};
+
 type Mode = "assembly" | "design";
 type RequestOptions = {
     body?: {
@@ -261,6 +288,84 @@ type RequestOptions = {
     headers?: HeadersInit;
     credentials?: RequestCredentials;
 };
+type UsePuckAiOptions = {
+    /** Endpoint serving the chat stream. Defaults to `/api/puck/chat`. */
+    host?: string;
+    /**
+     * Endpoint serving one-shot generations for `stream()`. Defaults to
+     * `/api/puck/stream`.
+     */
+    streamHost?: string;
+    /**
+     * Whether the agent assembles your components or designs new ones. Read at
+     * request time, so a plugin can flip it between calls.
+     */
+    mode?: Mode;
+    apiVersion?: string;
+    /** Adjust the outgoing request — add auth headers, extra body fields. */
+    prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
+    onFinish?: ChatOnFinishCallback<PuckMessage>;
+    onError?: (error: Error) => void;
+};
+type SendMessageOptions = {
+    /** Override the hook's mode for this call. */
+    mode?: Mode;
+    /** Attachments to send alongside the prompt. */
+    files?: Extract<PuckMessage["parts"][number], {
+        type: "file";
+    }>[];
+};
+type StreamOptions = {
+    /** Override the hook's mode for this call. */
+    mode?: Mode;
+    /** Extra context for this generation. */
+    context?: string;
+};
+/**
+ * Puck AI, wired into the editor you're already inside.
+ *
+ * Call it from any plugin render or override — it reads the editor through
+ * `useGetPuck`, so there's no provider to add. `stream()` sends a prompt and
+ * applies everything that comes back to the live canvas: component writes,
+ * design-mode definitions, and the screenshot/page-data round trips the agent
+ * uses to see what it built.
+ *
+ * The UI is yours. This owns the transport and the editor mutations only.
+ */
+declare function usePuckAi({ host, streamHost, mode, apiVersion, prepareRequest, onFinish, onError, }?: UsePuckAiOptions): {
+    /**
+     * Send a prompt as the next turn of a conversation. The agent sees the
+     * history, and can write, check its work and correct itself.
+     */
+    sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
+    /**
+     * Run a one-shot generation from a prompt, with no conversation. Cheaper
+     * and more predictable than `sendMessage`, but it stops after its first
+     * write rather than reviewing the result.
+     */
+    stream: (prompt: string, opts?: StreamOptions) => Promise<void>;
+    /** Abort whichever request is in flight */
+    stop: () => void;
+    status: ai.ChatStatus;
+    /** The conversation so far, for building a transcript */
+    messages: PuckMessage[];
+    setMessages: (messages: PuckMessage[] | ((messages: PuckMessage[]) => PuckMessage[])) => void;
+    regenerate: ({ messageId, ...options }?: {
+        messageId?: string;
+    } & ai.ChatRequestOptions) => Promise<void>;
+    error: string | undefined;
+    /** Live per-tool progress, keyed by tool call id */
+    toolStatus: Record<string, ToolStatus>;
+    /** Live subagent progress, keyed by tool call id */
+    subagentState: Record<string, SubagentState>;
+    /**
+     * @internal Apply a single stream part to the editor. Exposed for
+     * replaying a recorded stream (the marketing demo) — a real agent should
+     * go through `stream`.
+     */
+    processData: (dataPart: DataUIPart<PuckDataParts>) => void;
+};
+
 type AiPluginProps = {
     host?: string;
     chat?: {
@@ -306,6 +411,7 @@ declare global {
 }
 
 declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
+
 declare function createAiPlugin(opts?: AiPluginProps): {
     label: string;
     name: string;
@@ -322,4 +428,4 @@ declare function createAiPlugin(opts?: AiPluginProps): {
     };
 };
 
-export { type ComponentAiParams, type FieldAiParams, createAiPlugin, withDynamicConfig };
+export { type ComponentAiParams, type FieldAiParams, type StreamOptions, type UsePuckAiOptions, createAiPlugin, usePuckAi, withDynamicConfig };