@puckeditor/plugin-ai 0.9.0-canary.5c55a953 → 0.9.0-canary.d4a0bc62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,9 +1,8 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode } from 'react';
3
3
  import * as react_jsx_runtime from 'react/jsx-runtime';
4
- import * as ai from 'ai';
5
- import { LanguageModelUsage, UIMessage, ChatOnFinishCallback, DataUIPart, CreateUIMessage, ChatStatus } from 'ai';
6
4
  import { PuckAction, Data, Config } from '@puckeditor/core';
5
+ import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
7
6
 
8
7
  type _JSONSchema = boolean | JSONSchema;
9
8
  type JSONSchema = {
@@ -116,6 +115,37 @@ type DataToolStatus = {
116
115
  status: ToolStatus;
117
116
  toolCallId: string;
118
117
  };
118
+ type AiFieldTypeShape<Value> = {
119
+ /** What the field represents, and any rules for using it */
120
+ description?: string;
121
+ /**
122
+ * JSON Schema for the field's value — the shape the model may write, at
123
+ * creation and in later edits. Without one the model never writes the
124
+ * field, like `ai.exclude`.
125
+ */
126
+ schema?: Record<string, any>;
127
+ /**
128
+ * What a field the model designs starts as. When set, the model places the
129
+ * field and this value fills it; the model authors a value against `schema`
130
+ * only when this is absent.
131
+ */
132
+ defaultValue?: Value;
133
+ };
134
+ /**
135
+ * A user field type registered by the developer's config. Puck can't infer a
136
+ * value shape for one, so a type carries `schema`, `defaultValue`, or both.
137
+ */
138
+ type AiFieldType$1<Value = AiFieldTypeValue> = AiFieldTypeShape<Value> & ({
139
+ schema: Record<string, any>;
140
+ } | {
141
+ defaultValue: Value;
142
+ });
143
+ /**
144
+ * Any JSON-ish value. Spelled out rather than `unknown` so a union with a
145
+ * function form doesn't collapse, which would drop the callback's parameter
146
+ * types at the call site.
147
+ */
148
+ type AiFieldTypeValue = string | number | boolean | null | readonly unknown[] | Record<string, unknown>;
119
149
  type AddOperation = {
120
150
  op: "add";
121
151
  id: string;
@@ -248,31 +278,20 @@ type PuckProviderMetadata = {
248
278
 
249
279
  type PuckMessage = UIMessage<PuckProviderMetadata, PuckDataParts>;
250
280
 
251
- type SubagentChildPart = {
252
- kind: "text";
253
- blockId: string;
254
- text: string;
255
- } | {
256
- kind: "reasoning";
257
- blockId: string;
258
- text: string;
259
- state: "streaming" | "done";
260
- } | {
261
- kind: "tool";
262
- childToolCallId: string;
263
- toolName: string;
264
- input?: unknown;
265
- output?: unknown;
266
- };
267
- type SubagentState = {
268
- toolCallId: string;
269
- parentToolCallId?: string;
270
- agentType: string;
271
- depth: number;
272
- label: string;
273
- state: "running" | "done";
274
- parts: SubagentChildPart[];
281
+ type AiFieldTypeContext = {
282
+ /** The designed component the field belongs to */
283
+ componentName: string;
284
+ /** The field's name within that component */
285
+ fieldName: string;
275
286
  };
287
+ /**
288
+ * A field type the developer's config registers: `schema` is what the model
289
+ * may write, `defaultValue` is what a designed field starts as — one or both.
290
+ * In the editor the default may be a function of the component and field
291
+ * being created.
292
+ */
293
+ type AiFieldType = AiFieldType$1<AiFieldTypeValue | ((ctx: AiFieldTypeContext) => AiFieldTypeValue)>;
294
+ type AiFieldTypeRegistry = Record<string, AiFieldType>;
276
295
 
277
296
  type Mode = "assembly" | "design";
278
297
  type RequestOptions = {
@@ -288,86 +307,15 @@ type RequestOptions = {
288
307
  headers?: HeadersInit;
289
308
  credentials?: RequestCredentials;
290
309
  };
291
- type UsePuckAiOptions = {
292
- /** Endpoint serving the chat stream. Defaults to `/api/puck/chat`. */
310
+ type AiPluginProps = {
293
311
  host?: string;
294
312
  /**
295
- * Endpoint serving one-shot generations for `stream()`. Defaults to
296
- * `/api/puck/stream`.
297
- */
298
- streamHost?: string;
299
- /**
300
- * Whether the agent assembles your components or designs new ones. Read at
301
- * request time, so a plugin can flip it between calls.
313
+ * Field types this config registers, keyed by field type. Each gives either
314
+ * a `schema` the AI writes the value against, or a `defaultValue` every
315
+ * field of the type starts with. Sent to the server as JSON, so a function
316
+ * `defaultValue` only resolves in the editor.
302
317
  */
303
- mode?: Mode;
304
- apiVersion?: string;
305
- /** Adjust the outgoing request — add auth headers, extra body fields. */
306
- prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
307
- onFinish?: ChatOnFinishCallback<PuckMessage>;
308
- onError?: (error: Error) => void;
309
- };
310
- type SendMessageOptions = {
311
- /** Override the hook's mode for this call. */
312
- mode?: Mode;
313
- /** Attachments to send alongside the prompt. */
314
- files?: Extract<PuckMessage["parts"][number], {
315
- type: "file";
316
- }>[];
317
- };
318
- type StreamOptions = {
319
- /** Override the hook's mode for this call. */
320
- mode?: Mode;
321
- /** Extra context for this generation. */
322
- context?: string;
323
- };
324
- /**
325
- * Puck AI, wired into the editor you're already inside.
326
- *
327
- * Call it from any plugin render or override — it reads the editor through
328
- * `useGetPuck`, so there's no provider to add. `stream()` sends a prompt and
329
- * applies everything that comes back to the live canvas: component writes,
330
- * design-mode definitions, and the screenshot/page-data round trips the agent
331
- * uses to see what it built.
332
- *
333
- * The UI is yours. This owns the transport and the editor mutations only.
334
- */
335
- declare function usePuckAi({ host, streamHost, mode, apiVersion, prepareRequest, onFinish, onError, }?: UsePuckAiOptions): {
336
- /**
337
- * Send a prompt as the next turn of a conversation. The agent sees the
338
- * history, and can write, check its work and correct itself.
339
- */
340
- sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
341
- /**
342
- * Run a one-shot generation from a prompt, with no conversation. Cheaper
343
- * and more predictable than `sendMessage`, but it stops after its first
344
- * write rather than reviewing the result.
345
- */
346
- stream: (prompt: string, opts?: StreamOptions) => Promise<void>;
347
- /** Abort whichever request is in flight */
348
- stop: () => void;
349
- status: ai.ChatStatus;
350
- /** The conversation so far, for building a transcript */
351
- messages: PuckMessage[];
352
- setMessages: (messages: PuckMessage[] | ((messages: PuckMessage[]) => PuckMessage[])) => void;
353
- regenerate: ({ messageId, ...options }?: {
354
- messageId?: string;
355
- } & ai.ChatRequestOptions) => Promise<void>;
356
- error: string | undefined;
357
- /** Live per-tool progress, keyed by tool call id */
358
- toolStatus: Record<string, ToolStatus>;
359
- /** Live subagent progress, keyed by tool call id */
360
- subagentState: Record<string, SubagentState>;
361
- /**
362
- * @internal Apply a single stream part to the editor. Exposed for
363
- * replaying a recorded stream (the marketing demo) — a real agent should
364
- * go through `stream`.
365
- */
366
- processData: (dataPart: DataUIPart<PuckDataParts>) => void;
367
- };
368
-
369
- type AiPluginProps = {
370
- host?: string;
318
+ fieldTypes?: AiFieldTypeRegistry;
371
319
  chat?: {
372
320
  attachments?: {
373
321
  enabled?: boolean;
@@ -411,7 +359,6 @@ declare global {
411
359
  }
412
360
 
413
361
  declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
414
-
415
362
  declare function createAiPlugin(opts?: AiPluginProps): {
416
363
  label: string;
417
364
  name: string;
@@ -428,4 +375,4 @@ declare function createAiPlugin(opts?: AiPluginProps): {
428
375
  };
429
376
  };
430
377
 
431
- export { type ComponentAiParams, type FieldAiParams, type StreamOptions, type UsePuckAiOptions, createAiPlugin, usePuckAi, withDynamicConfig };
378
+ export { type ComponentAiParams, type FieldAiParams, createAiPlugin, withDynamicConfig };
package/dist/index.d.ts CHANGED
@@ -1,9 +1,8 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode } from 'react';
3
3
  import * as react_jsx_runtime from 'react/jsx-runtime';
4
- import * as ai from 'ai';
5
- import { LanguageModelUsage, UIMessage, ChatOnFinishCallback, DataUIPart, CreateUIMessage, ChatStatus } from 'ai';
6
4
  import { PuckAction, Data, Config } from '@puckeditor/core';
5
+ import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
7
6
 
8
7
  type _JSONSchema = boolean | JSONSchema;
9
8
  type JSONSchema = {
@@ -116,6 +115,37 @@ type DataToolStatus = {
116
115
  status: ToolStatus;
117
116
  toolCallId: string;
118
117
  };
118
+ type AiFieldTypeShape<Value> = {
119
+ /** What the field represents, and any rules for using it */
120
+ description?: string;
121
+ /**
122
+ * JSON Schema for the field's value — the shape the model may write, at
123
+ * creation and in later edits. Without one the model never writes the
124
+ * field, like `ai.exclude`.
125
+ */
126
+ schema?: Record<string, any>;
127
+ /**
128
+ * What a field the model designs starts as. When set, the model places the
129
+ * field and this value fills it; the model authors a value against `schema`
130
+ * only when this is absent.
131
+ */
132
+ defaultValue?: Value;
133
+ };
134
+ /**
135
+ * A user field type registered by the developer's config. Puck can't infer a
136
+ * value shape for one, so a type carries `schema`, `defaultValue`, or both.
137
+ */
138
+ type AiFieldType$1<Value = AiFieldTypeValue> = AiFieldTypeShape<Value> & ({
139
+ schema: Record<string, any>;
140
+ } | {
141
+ defaultValue: Value;
142
+ });
143
+ /**
144
+ * Any JSON-ish value. Spelled out rather than `unknown` so a union with a
145
+ * function form doesn't collapse, which would drop the callback's parameter
146
+ * types at the call site.
147
+ */
148
+ type AiFieldTypeValue = string | number | boolean | null | readonly unknown[] | Record<string, unknown>;
119
149
  type AddOperation = {
120
150
  op: "add";
121
151
  id: string;
@@ -248,31 +278,20 @@ type PuckProviderMetadata = {
248
278
 
249
279
  type PuckMessage = UIMessage<PuckProviderMetadata, PuckDataParts>;
250
280
 
251
- type SubagentChildPart = {
252
- kind: "text";
253
- blockId: string;
254
- text: string;
255
- } | {
256
- kind: "reasoning";
257
- blockId: string;
258
- text: string;
259
- state: "streaming" | "done";
260
- } | {
261
- kind: "tool";
262
- childToolCallId: string;
263
- toolName: string;
264
- input?: unknown;
265
- output?: unknown;
266
- };
267
- type SubagentState = {
268
- toolCallId: string;
269
- parentToolCallId?: string;
270
- agentType: string;
271
- depth: number;
272
- label: string;
273
- state: "running" | "done";
274
- parts: SubagentChildPart[];
281
+ type AiFieldTypeContext = {
282
+ /** The designed component the field belongs to */
283
+ componentName: string;
284
+ /** The field's name within that component */
285
+ fieldName: string;
275
286
  };
287
+ /**
288
+ * A field type the developer's config registers: `schema` is what the model
289
+ * may write, `defaultValue` is what a designed field starts as — one or both.
290
+ * In the editor the default may be a function of the component and field
291
+ * being created.
292
+ */
293
+ type AiFieldType = AiFieldType$1<AiFieldTypeValue | ((ctx: AiFieldTypeContext) => AiFieldTypeValue)>;
294
+ type AiFieldTypeRegistry = Record<string, AiFieldType>;
276
295
 
277
296
  type Mode = "assembly" | "design";
278
297
  type RequestOptions = {
@@ -288,86 +307,15 @@ type RequestOptions = {
288
307
  headers?: HeadersInit;
289
308
  credentials?: RequestCredentials;
290
309
  };
291
- type UsePuckAiOptions = {
292
- /** Endpoint serving the chat stream. Defaults to `/api/puck/chat`. */
310
+ type AiPluginProps = {
293
311
  host?: string;
294
312
  /**
295
- * Endpoint serving one-shot generations for `stream()`. Defaults to
296
- * `/api/puck/stream`.
297
- */
298
- streamHost?: string;
299
- /**
300
- * Whether the agent assembles your components or designs new ones. Read at
301
- * request time, so a plugin can flip it between calls.
313
+ * Field types this config registers, keyed by field type. Each gives either
314
+ * a `schema` the AI writes the value against, or a `defaultValue` every
315
+ * field of the type starts with. Sent to the server as JSON, so a function
316
+ * `defaultValue` only resolves in the editor.
302
317
  */
303
- mode?: Mode;
304
- apiVersion?: string;
305
- /** Adjust the outgoing request — add auth headers, extra body fields. */
306
- prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
307
- onFinish?: ChatOnFinishCallback<PuckMessage>;
308
- onError?: (error: Error) => void;
309
- };
310
- type SendMessageOptions = {
311
- /** Override the hook's mode for this call. */
312
- mode?: Mode;
313
- /** Attachments to send alongside the prompt. */
314
- files?: Extract<PuckMessage["parts"][number], {
315
- type: "file";
316
- }>[];
317
- };
318
- type StreamOptions = {
319
- /** Override the hook's mode for this call. */
320
- mode?: Mode;
321
- /** Extra context for this generation. */
322
- context?: string;
323
- };
324
- /**
325
- * Puck AI, wired into the editor you're already inside.
326
- *
327
- * Call it from any plugin render or override — it reads the editor through
328
- * `useGetPuck`, so there's no provider to add. `stream()` sends a prompt and
329
- * applies everything that comes back to the live canvas: component writes,
330
- * design-mode definitions, and the screenshot/page-data round trips the agent
331
- * uses to see what it built.
332
- *
333
- * The UI is yours. This owns the transport and the editor mutations only.
334
- */
335
- declare function usePuckAi({ host, streamHost, mode, apiVersion, prepareRequest, onFinish, onError, }?: UsePuckAiOptions): {
336
- /**
337
- * Send a prompt as the next turn of a conversation. The agent sees the
338
- * history, and can write, check its work and correct itself.
339
- */
340
- sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
341
- /**
342
- * Run a one-shot generation from a prompt, with no conversation. Cheaper
343
- * and more predictable than `sendMessage`, but it stops after its first
344
- * write rather than reviewing the result.
345
- */
346
- stream: (prompt: string, opts?: StreamOptions) => Promise<void>;
347
- /** Abort whichever request is in flight */
348
- stop: () => void;
349
- status: ai.ChatStatus;
350
- /** The conversation so far, for building a transcript */
351
- messages: PuckMessage[];
352
- setMessages: (messages: PuckMessage[] | ((messages: PuckMessage[]) => PuckMessage[])) => void;
353
- regenerate: ({ messageId, ...options }?: {
354
- messageId?: string;
355
- } & ai.ChatRequestOptions) => Promise<void>;
356
- error: string | undefined;
357
- /** Live per-tool progress, keyed by tool call id */
358
- toolStatus: Record<string, ToolStatus>;
359
- /** Live subagent progress, keyed by tool call id */
360
- subagentState: Record<string, SubagentState>;
361
- /**
362
- * @internal Apply a single stream part to the editor. Exposed for
363
- * replaying a recorded stream (the marketing demo) — a real agent should
364
- * go through `stream`.
365
- */
366
- processData: (dataPart: DataUIPart<PuckDataParts>) => void;
367
- };
368
-
369
- type AiPluginProps = {
370
- host?: string;
318
+ fieldTypes?: AiFieldTypeRegistry;
371
319
  chat?: {
372
320
  attachments?: {
373
321
  enabled?: boolean;
@@ -411,7 +359,6 @@ declare global {
411
359
  }
412
360
 
413
361
  declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
414
-
415
362
  declare function createAiPlugin(opts?: AiPluginProps): {
416
363
  label: string;
417
364
  name: string;
@@ -428,4 +375,4 @@ declare function createAiPlugin(opts?: AiPluginProps): {
428
375
  };
429
376
  };
430
377
 
431
- export { type ComponentAiParams, type FieldAiParams, type StreamOptions, type UsePuckAiOptions, createAiPlugin, usePuckAi, withDynamicConfig };
378
+ export { type ComponentAiParams, type FieldAiParams, createAiPlugin, withDynamicConfig };