@puckeditor/cli 0.24.0-canary.c16ace08 → 0.24.0-canary.c9aa1fa8

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.
Files changed (187) hide show
  1. package/dist/bin.mjs +61 -5
  2. package/dist/docs/cloud/ai/assembly-mode.md +271 -0
  3. package/dist/docs/cloud/ai/business-context.md +69 -0
  4. package/dist/docs/cloud/ai/custom-agents.md +133 -0
  5. package/dist/docs/cloud/ai/design-mode.md +235 -0
  6. package/dist/docs/cloud/ai/headless-generation.md +122 -0
  7. package/dist/docs/cloud/ai/localization.md +43 -0
  8. package/dist/docs/cloud/ai/model-configuration.md +113 -0
  9. package/dist/docs/cloud/ai/overview.md +35 -0
  10. package/dist/docs/cloud/ai/setup.md +65 -0
  11. package/dist/docs/cloud/ai/tools.md +99 -0
  12. package/dist/docs/cloud/api-reference/cloud-client/helpers/chat.md +515 -0
  13. package/dist/docs/cloud/api-reference/cloud-client/helpers/login-url.md +21 -0
  14. package/dist/docs/cloud/api-reference/cloud-client/helpers/tool.md +128 -0
  15. package/dist/docs/cloud/api-reference/cloud-client/puck-cloud.md +73 -0
  16. package/dist/docs/cloud/api-reference/cloud-client/puck-handler.md +434 -0
  17. package/dist/docs/cloud/api-reference/cloud-client/server-apis/ai-generate.md +523 -0
  18. package/dist/docs/cloud/api-reference/cloud-client/server-apis/auth-get-session.md +41 -0
  19. package/dist/docs/cloud/api-reference/cloud-client/server-apis/auth-sign-out.md +24 -0
  20. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-create-version.md +50 -0
  21. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-create.md +45 -0
  22. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-delete.md +42 -0
  23. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get-by-path.md +34 -0
  24. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get-published.md +25 -0
  25. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get.md +34 -0
  26. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-list-versions.md +49 -0
  27. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-list.md +46 -0
  28. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-publish.md +30 -0
  29. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-unpublish.md +25 -0
  30. package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-update.md +38 -0
  31. package/dist/docs/cloud/api-reference/cloud-client/types/ai-generate-field-type.md +33 -0
  32. package/dist/docs/cloud/api-reference/cloud-client/types/page-list.md +41 -0
  33. package/dist/docs/cloud/api-reference/cloud-client/types/page.md +61 -0
  34. package/dist/docs/cloud/api-reference/cloud-client/types/puck-cloud-error.md +34 -0
  35. package/dist/docs/cloud/api-reference/cloud-client/types/puck-session.md +53 -0
  36. package/dist/docs/cloud/api-reference/plugin-ai/ai-configuration/components.md +72 -0
  37. package/dist/docs/cloud/api-reference/plugin-ai/ai-configuration/fields.md +231 -0
  38. package/dist/docs/cloud/api-reference/plugin-ai/ai-field-type.md +41 -0
  39. package/dist/docs/cloud/api-reference/plugin-ai/ai-part.md +90 -0
  40. package/dist/docs/cloud/api-reference/plugin-ai/create-ai-plugin.md +311 -0
  41. package/dist/docs/cloud/api-reference/plugin-ai/dictionary.md +77 -0
  42. package/dist/docs/cloud/api-reference/plugin-ai/use-puck-ai.md +175 -0
  43. package/dist/docs/cloud/api-reference/plugin-ai/with-dynamic-config.md +35 -0
  44. package/dist/docs/cloud/api-reference/plugin-auth/create-auth-plugin.md +43 -0
  45. package/dist/docs/cloud/api-reference/plugin-pages/create-pages-plugin.md +65 -0
  46. package/dist/docs/cloud/auth/overview.md +24 -0
  47. package/dist/docs/cloud/auth/setup.md +169 -0
  48. package/dist/docs/cloud/auth-and-identity.md +70 -0
  49. package/dist/docs/cloud/getting-started.md +47 -0
  50. package/dist/docs/cloud/overview.md +23 -0
  51. package/dist/docs/cloud/pages/overview.md +38 -0
  52. package/dist/docs/cloud/pages/setup.md +80 -0
  53. package/dist/docs/cloud/server-apis.md +58 -0
  54. package/dist/docs/cloud/setup-cloud-plugins.md +202 -0
  55. package/dist/docs/editor/api-reference/actions.md +63 -0
  56. package/dist/docs/editor/api-reference/components/action-bar-action.md +35 -0
  57. package/dist/docs/editor/api-reference/components/action-bar-drag-handle.md +33 -0
  58. package/dist/docs/editor/api-reference/components/action-bar-group.md +24 -0
  59. package/dist/docs/editor/api-reference/components/action-bar-label.md +25 -0
  60. package/dist/docs/editor/api-reference/components/action-bar-separator.md +16 -0
  61. package/dist/docs/editor/api-reference/components/action-bar.md +32 -0
  62. package/dist/docs/editor/api-reference/components/auto-field.md +62 -0
  63. package/dist/docs/editor/api-reference/components/drawer-item.md +73 -0
  64. package/dist/docs/editor/api-reference/components/drawer.md +28 -0
  65. package/dist/docs/editor/api-reference/components/drop-zone.md +231 -0
  66. package/dist/docs/editor/api-reference/components/field-group-item.md +39 -0
  67. package/dist/docs/editor/api-reference/components/field-group.md +86 -0
  68. package/dist/docs/editor/api-reference/components/field-label.md +135 -0
  69. package/dist/docs/editor/api-reference/components/field-tab.md +55 -0
  70. package/dist/docs/editor/api-reference/components/inline-text-field.md +76 -0
  71. package/dist/docs/editor/api-reference/components/puck-components.md +18 -0
  72. package/dist/docs/editor/api-reference/components/puck-fields.md +37 -0
  73. package/dist/docs/editor/api-reference/components/puck-layout.md +26 -0
  74. package/dist/docs/editor/api-reference/components/puck-outline.md +18 -0
  75. package/dist/docs/editor/api-reference/components/puck-preview.md +37 -0
  76. package/dist/docs/editor/api-reference/components/puck.md +564 -0
  77. package/dist/docs/editor/api-reference/components/render.md +113 -0
  78. package/dist/docs/editor/api-reference/components/rich-text-menu-control.md +87 -0
  79. package/dist/docs/editor/api-reference/components/rich-text-menu-group.md +27 -0
  80. package/dist/docs/editor/api-reference/components/rich-text-menu.md +99 -0
  81. package/dist/docs/editor/api-reference/components.md +36 -0
  82. package/dist/docs/editor/api-reference/configuration/component-config.md +611 -0
  83. package/dist/docs/editor/api-reference/configuration/config.md +108 -0
  84. package/dist/docs/editor/api-reference/configuration.md +4 -0
  85. package/dist/docs/editor/api-reference/data-model/app-state.md +182 -0
  86. package/dist/docs/editor/api-reference/data-model/component-data.md +62 -0
  87. package/dist/docs/editor/api-reference/data-model/data.md +95 -0
  88. package/dist/docs/editor/api-reference/data-model/item-selector.md +34 -0
  89. package/dist/docs/editor/api-reference/data-model/root-data.md +59 -0
  90. package/dist/docs/editor/api-reference/data-model.md +8 -0
  91. package/dist/docs/editor/api-reference/dictionary.md +173 -0
  92. package/dist/docs/editor/api-reference/field-transforms.md +51 -0
  93. package/dist/docs/editor/api-reference/fields/array.md +211 -0
  94. package/dist/docs/editor/api-reference/fields/base.md +96 -0
  95. package/dist/docs/editor/api-reference/fields/checkbox.md +87 -0
  96. package/dist/docs/editor/api-reference/fields/custom.md +191 -0
  97. package/dist/docs/editor/api-reference/fields/external.md +413 -0
  98. package/dist/docs/editor/api-reference/fields/number.md +132 -0
  99. package/dist/docs/editor/api-reference/fields/object.md +100 -0
  100. package/dist/docs/editor/api-reference/fields/radio.md +82 -0
  101. package/dist/docs/editor/api-reference/fields/richtext.md +415 -0
  102. package/dist/docs/editor/api-reference/fields/select.md +79 -0
  103. package/dist/docs/editor/api-reference/fields/slot.md +306 -0
  104. package/dist/docs/editor/api-reference/fields/text.md +93 -0
  105. package/dist/docs/editor/api-reference/fields/textarea.md +93 -0
  106. package/dist/docs/editor/api-reference/fields.md +17 -0
  107. package/dist/docs/editor/api-reference/functions/migrate.md +203 -0
  108. package/dist/docs/editor/api-reference/functions/register-overlay-portal.md +44 -0
  109. package/dist/docs/editor/api-reference/functions/resolve-all-data.md +26 -0
  110. package/dist/docs/editor/api-reference/functions/set-deep.md +54 -0
  111. package/dist/docs/editor/api-reference/functions/transform-props.md +50 -0
  112. package/dist/docs/editor/api-reference/functions/use-get-puck.md +23 -0
  113. package/dist/docs/editor/api-reference/functions/use-puck.md +42 -0
  114. package/dist/docs/editor/api-reference/functions/walk-tree.md +87 -0
  115. package/dist/docs/editor/api-reference/functions.md +8 -0
  116. package/dist/docs/editor/api-reference/overrides/action-bar.md +50 -0
  117. package/dist/docs/editor/api-reference/overrides/component-overlay.md +41 -0
  118. package/dist/docs/editor/api-reference/overrides/drawer-item.md +24 -0
  119. package/dist/docs/editor/api-reference/overrides/drawer.md +19 -0
  120. package/dist/docs/editor/api-reference/overrides/field-label.md +18 -0
  121. package/dist/docs/editor/api-reference/overrides/field-types.md +51 -0
  122. package/dist/docs/editor/api-reference/overrides/fields.md +45 -0
  123. package/dist/docs/editor/api-reference/overrides/header-actions.md +24 -0
  124. package/dist/docs/editor/api-reference/overrides/header.md +29 -0
  125. package/dist/docs/editor/api-reference/overrides/iframe.md +32 -0
  126. package/dist/docs/editor/api-reference/overrides/outline.md +19 -0
  127. package/dist/docs/editor/api-reference/overrides/preview.md +19 -0
  128. package/dist/docs/editor/api-reference/overrides/puck.md +19 -0
  129. package/dist/docs/editor/api-reference/overrides.md +28 -0
  130. package/dist/docs/editor/api-reference/permissions.md +55 -0
  131. package/dist/docs/editor/api-reference/plugin.md +111 -0
  132. package/dist/docs/editor/api-reference/plugins/blocks-plugin.md +53 -0
  133. package/dist/docs/editor/api-reference/plugins/fields-plugin.md +64 -0
  134. package/dist/docs/editor/api-reference/plugins/legacy-side-bar-plugin.md +51 -0
  135. package/dist/docs/editor/api-reference/plugins/outline-plugin.md +53 -0
  136. package/dist/docs/editor/api-reference/puck-api.md +279 -0
  137. package/dist/docs/editor/api-reference/theming/action-bar.md +32 -0
  138. package/dist/docs/editor/api-reference/theming/button.md +65 -0
  139. package/dist/docs/editor/api-reference/theming/canvas.md +20 -0
  140. package/dist/docs/editor/api-reference/theming/computed-values.md +209 -0
  141. package/dist/docs/editor/api-reference/theming/drawer.md +34 -0
  142. package/dist/docs/editor/api-reference/theming/field-tabs.md +28 -0
  143. package/dist/docs/editor/api-reference/theming/fields.md +77 -0
  144. package/dist/docs/editor/api-reference/theming/global.md +127 -0
  145. package/dist/docs/editor/api-reference/theming/header.md +19 -0
  146. package/dist/docs/editor/api-reference/theming/icon-button.md +28 -0
  147. package/dist/docs/editor/api-reference/theming/outline.md +35 -0
  148. package/dist/docs/editor/api-reference/theming/plugin-bar.md +24 -0
  149. package/dist/docs/editor/api-reference/theming/sidebar.md +19 -0
  150. package/dist/docs/editor/api-reference/theming/slot.md +27 -0
  151. package/dist/docs/editor/components-and-fields/component-configuration.md +157 -0
  152. package/dist/docs/editor/components-and-fields/custom-fields.md +131 -0
  153. package/dist/docs/editor/components-and-fields/dynamic-fields.md +86 -0
  154. package/dist/docs/editor/components-and-fields/field-grouping.md +149 -0
  155. package/dist/docs/editor/components-and-fields/field-transforms.md +102 -0
  156. package/dist/docs/editor/components-and-fields/multi-column-layouts.md +226 -0
  157. package/dist/docs/editor/components-and-fields/overlay-portals.md +29 -0
  158. package/dist/docs/editor/components-and-fields/rich-text-editing.md +224 -0
  159. package/dist/docs/editor/components-and-fields/root-configuration.md +170 -0
  160. package/dist/docs/editor/customize/categories.md +91 -0
  161. package/dist/docs/editor/customize/composition.md +53 -0
  162. package/dist/docs/editor/customize/feature-toggling.md +121 -0
  163. package/dist/docs/editor/customize/internal-puck-api.md +94 -0
  164. package/dist/docs/editor/customize/localization.md +216 -0
  165. package/dist/docs/editor/customize/plugins.md +154 -0
  166. package/dist/docs/editor/customize/styling.md +117 -0
  167. package/dist/docs/editor/customize/theming.md +89 -0
  168. package/dist/docs/editor/customize/ui-overrides.md +130 -0
  169. package/dist/docs/editor/customize/viewports.md +74 -0
  170. package/dist/docs/editor/data-and-rendering/dynamic-props.md +136 -0
  171. package/dist/docs/editor/data-and-rendering/external-data-sources.md +149 -0
  172. package/dist/docs/editor/data-and-rendering/save-and-render-pages.md +78 -0
  173. package/dist/docs/editor/data-and-rendering/server-components.md +186 -0
  174. package/dist/docs/editor/getting-started.md +60 -0
  175. package/dist/docs/editor/migrations/data-migration.md +83 -0
  176. package/dist/docs/editor/migrations/dropzones-to-slots.md +136 -0
  177. package/dist/docs/editor/overview.md +27 -0
  178. package/dist/docs/index.json +704 -0
  179. package/dist/templates/next/app/puck/[...puckPath]/page.tsx +3 -2
  180. package/dist/templates/next/app/puck/page.tsx +0 -2
  181. package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +3 -2
  182. package/dist/templates/next-ai/app/puck/page.tsx +0 -2
  183. package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +3 -2
  184. package/dist/templates/vinext/app/puck/page.tsx +0 -2
  185. package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +3 -2
  186. package/dist/templates/vinext-ai/app/puck/page.tsx +0 -2
  187. package/package.json +1 -1
package/dist/bin.mjs CHANGED
@@ -159,6 +159,19 @@ var findStringProperty = (code, filename, key) => {
159
159
  });
160
160
  return result;
161
161
  };
162
+ var hasTrueProperty = (code, filename, key) => {
163
+ const ast = tryParseModule(code, filename);
164
+ let found = false;
165
+ if (ast) {
166
+ walk(ast.program, (node) => {
167
+ if (node.type !== "ObjectProperty" || node.computed) return;
168
+ const name = node.key.type === "Identifier" ? node.key.name : node.key.type === "StringLiteral" ? node.key.value : null;
169
+ if (name === key && node.value.type === "BooleanLiteral")
170
+ found ||= node.value.value;
171
+ });
172
+ }
173
+ return found;
174
+ };
162
175
 
163
176
  // src/detect/package-json.ts
164
177
  import path from "path";
@@ -340,6 +353,18 @@ var findViteConfig = (vfs, root) => firstExisting(
340
353
  root,
341
354
  CONFIG_EXTENSIONS.map((ext) => `vite.config.${ext}`)
342
355
  );
356
+ var detectCacheComponents = (vfs, root) => {
357
+ const config = firstExisting(
358
+ vfs,
359
+ root,
360
+ CONFIG_EXTENSIONS.map((ext) => `next.config.${ext}`)
361
+ );
362
+ return config ? hasTrueProperty(
363
+ vfs.readText(path3.join(root, config)) ?? "",
364
+ config,
365
+ "cacheComponents"
366
+ ) : false;
367
+ };
343
368
  var normalizeDir = (dir) => path3.posix.normalize(dir).replace(/^\.\/?$/, "").replace(/\/+$/, "");
344
369
  var dynamicConfig = (file, what) => ({
345
370
  status: "unsupported",
@@ -396,7 +421,8 @@ var detectNext = (vfs, root, range) => {
396
421
  version,
397
422
  major: major2,
398
423
  ...layout,
399
- proxyKind: major2 >= 16 ? "proxy" : "middleware"
424
+ proxyKind: major2 >= 16 ? "proxy" : "middleware",
425
+ cacheComponents: detectCacheComponents(vfs, root)
400
426
  }
401
427
  };
402
428
  };
@@ -418,6 +444,7 @@ var detectVinext = (vfs, root, range) => {
418
444
  major: majorOf(version) ?? majorOf(range),
419
445
  ...layout,
420
446
  proxyKind: hasMiddleware ? "middleware" : "proxy",
447
+ cacheComponents: false,
421
448
  viteConfig: findViteConfig(vfs, root)
422
449
  }
423
450
  };
@@ -1918,6 +1945,27 @@ var configImportClause = (shape, local) => {
1918
1945
  if (shape.named.length === 1) return `{ ${shape.named[0]} as ${local} }`;
1919
1946
  return null;
1920
1947
  };
1948
+ var INSTANT = `// Cache Components: allow rendering on request, outside <Suspense>
1949
+ export const instant = false;`;
1950
+ var cacheComponentsEdits = (ast, code) => {
1951
+ const dynamic = ast.program.body.find(
1952
+ (s) => s.type === "ExportNamedDeclaration" && s.declaration?.type === "VariableDeclaration" && s.declaration.declarations.some(
1953
+ (d) => d.id.type === "Identifier" && d.id.name === "dynamic"
1954
+ )
1955
+ );
1956
+ if (!dynamic) {
1957
+ return [{ start: code.length, end: code.length, text: `
1958
+ ${INSTANT}
1959
+ ` }];
1960
+ }
1961
+ return [
1962
+ {
1963
+ start: dynamic.leadingComments?.[0]?.start ?? dynamic.start,
1964
+ end: dynamic.end,
1965
+ text: INSTANT
1966
+ }
1967
+ ];
1968
+ };
1921
1969
  var TYPE_FALLBACKS = {
1922
1970
  UserData: 'import("@puckeditor/core").Data'
1923
1971
  };
@@ -2010,6 +2058,9 @@ var relocateModule = (code, opts) => {
2010
2058
  });
2011
2059
  }
2012
2060
  }
2061
+ if (opts.cacheComponents && /(^|\/)page\.[jt]sx?$/.test(opts.to)) {
2062
+ edits.push(...cacheComponentsEdits(ast, code));
2063
+ }
2013
2064
  return { ok: true, code: applyEdits(code, edits) };
2014
2065
  };
2015
2066
 
@@ -2596,6 +2647,7 @@ import "@puckeditor/core/puck.css";
2596
2647
  ${ai ? `import "@puckeditor/plugin-ai/styles.css";
2597
2648
  ` : ""}import "@puckeditor/plugin-pages/styles.css";
2598
2649
  import { Metadata } from "next";
2650
+ import { connection } from "next/server";
2599
2651
  import { Client } from "./client";${auth ? `
2600
2652
  import { requirePuckSession } from "../../../lib/puck-auth";` : ""}
2601
2653
 
@@ -2610,15 +2662,18 @@ ${auth ? `export default async function Page({
2610
2662
  }: {
2611
2663
  searchParams: Promise<Record<string, string>>;
2612
2664
  }) {
2665
+ // Puck renders in the browser, so the editor is rendered on every request
2666
+ await connection();
2613
2667
  const query = new URLSearchParams(await searchParams).toString();
2614
2668
  await requirePuckSession(\`/puck\${query ? \`?\${query}\` : ""}\`);
2615
2669
 
2616
2670
  return <Client />;
2617
2671
  }` : `export default async function Page() {
2672
+ // Puck renders in the browser, so the editor is rendered on every request
2673
+ await connection();
2674
+
2618
2675
  return <Client />;
2619
2676
  }`}
2620
-
2621
- export const dynamic = "force-dynamic";
2622
2677
  `;
2623
2678
  var nextPagesRenderPage = (host) => `/**
2624
2679
  * This file implements a catch-all route that renders the pages published in
@@ -3334,7 +3389,8 @@ var nextRelocation = (p, info) => {
3334
3389
  "lib/puck-auth": `${lib}/puck-auth`,
3335
3390
  "puck.config": configModuleTarget(p)
3336
3391
  },
3337
- config: configRelocation(p)
3392
+ config: configRelocation(p),
3393
+ cacheComponents: info.cacheComponents
3338
3394
  };
3339
3395
  };
3340
3396
  var conflictingSegments = (p, appDir) => {
@@ -11658,7 +11714,7 @@ runCli(process.argv.slice(2), {
11658
11714
  stdout: process.stdout,
11659
11715
  stderr: process.stderr,
11660
11716
  stdinIsTTY: Boolean(process.stdin.isTTY),
11661
- cliVersion: "0.24.0-canary.c16ace08",
11717
+ cliVersion: "0.24.0-canary.c9aa1fa8",
11662
11718
  invocation: localInvocation(
11663
11719
  fs8.realpathSync(fileURLToPath(import.meta.url)),
11664
11720
  fs8.realpathSync(process.cwd()),
@@ -0,0 +1,271 @@
1
+ # Assembly Mode
2
+
3
+ Assembly mode allows Puck AI to create pages from your existing components.
4
+
5
+ You can control agent behavior via the `ai` parameter on both [component](/docs/cloud/api-reference/plugin-ai/ai-configuration/components) and [field](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields) configs.
6
+
7
+ ## Providing instructions
8
+
9
+ The `instructions` parameter provides the agent with natural-language guidance on how to use a component or field.
10
+
11
+ Here's an example using [`instructions` on components](/docs/cloud/api-reference/plugin-ai/ai-configuration/components#instructions):
12
+
13
+ ```ts
14
+ const config = {
15
+ components: {
16
+ HeadingBlock: {
17
+ ai: {
18
+ instructions: "Always place this first",
19
+ },
20
+ fields: {
21
+ title: {
22
+ type: "text",
23
+ },
24
+ },
25
+ render: ({ title }) => <h1>{title}</h1>,
26
+ },
27
+ },
28
+ };
29
+ ```
30
+
31
+ And using [`instructions` on fields](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#instructions):
32
+
33
+ ```ts
34
+ const config = {
35
+ components: {
36
+ HeadingBlock: {
37
+ fields: {
38
+ title: {
39
+ type: "text",
40
+ ai: {
41
+ instructions: "Always use caps",
42
+ },
43
+ },
44
+ },
45
+ render: ({ title }) => <h1>{title}</h1>,
46
+ },
47
+ },
48
+ };
49
+ ```
50
+
51
+ ## Setting a schema
52
+
53
+ Some field types like [`custom`](/docs/editor/api-reference/fields/custom), [`external`](/docs/editor/api-reference/fields/external), or [user fields](/docs/editor/api-reference/overrides/field-types), are not supported without further configuration. This is because the shape of the data produced by those fields is unknown to the agent.
54
+
55
+ To address this, provide a [`schema`](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#schema) using JSON Schema:
56
+
57
+ ```tsx
58
+ const config = {
59
+ components: {
60
+ HeadingBlock: {
61
+ fields: {
62
+ title: {
63
+ type: "custom",
64
+ ai: {
65
+ schema: { type: "text" },
66
+ },
67
+ render: () => <input />,
68
+ },
69
+ },
70
+ render: ({ title }) => <h1>{title}</h1>,
71
+ },
72
+ },
73
+ };
74
+ ```
75
+
76
+ We recommend using [Zod](https://zod.dev/json-schema) to help with producing JSON Schema for complex shapes:
77
+
78
+ ```tsx
79
+
80
+ const config = {
81
+ components: {
82
+ HeadingBlock: {
83
+ fields: {
84
+ object: {
85
+ type: "custom",
86
+ ai: {
87
+ schema: z.toJSONSchema(
88
+ z.object({
89
+ title: z.string(),
90
+ })
91
+ ),
92
+ },
93
+ render: () => <input />,
94
+ },
95
+ },
96
+ render: ({ object }) => <h1>{object.title}</h1>,
97
+ },
98
+ },
99
+ };
100
+ ```
101
+
102
+ ## Excluding components
103
+
104
+ To completely ignore a component when generating a page, use the [`exclude` API](/docs/cloud/api-reference/plugin-ai/ai-configuration/components#exclude):
105
+
106
+ ```tsx
107
+ const config = {
108
+ components: {
109
+ HeadingBlock: {
110
+ fields: {
111
+ title: { type: "text" },
112
+ },
113
+ ai: {
114
+ exclude: true,
115
+ },
116
+ render: ({ title }) => <h1>{title}</h1>,
117
+ },
118
+ },
119
+ };
120
+ ```
121
+
122
+ ## Disabling streaming
123
+
124
+ When using the [AI plugin](/docs/cloud/api-reference/plugin-ai/create-ai-plugin), Puck AI will stream field values wherever possible. This can sometimes result in unexpected behavior when rendering the preview, such as broken image URLs.
125
+
126
+ You can set the [`stream` parameter](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#stream) to `false` to disable streaming of a field:
127
+
128
+ ```tsx
129
+ const config = {
130
+ components: {
131
+ HeadingBlock: {
132
+ fields: {
133
+ src: {
134
+ type: "text",
135
+ ai: {
136
+ stream: false,
137
+ },
138
+ },
139
+ },
140
+ render: ({ src }) => <img src={src} />,
141
+ },
142
+ },
143
+ };
144
+ ```
145
+
146
+ ## Setting required fields
147
+
148
+ By default, all fields provided in [`defaultProps`](/docs/editor/api-reference/configuration/component-config#defaultprops) are considered required by the agent.
149
+
150
+ You can explicitly mark a field as required or optional by using the [`required` parameter](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#required).
151
+
152
+ ```tsx
153
+ const config = {
154
+ components: {
155
+ HeadingBlock: {
156
+ fields: {
157
+ src: {
158
+ type: "text",
159
+ ai: {
160
+ required: true, // Mark this as required, even though it doesn't exist in defaultProps
161
+ },
162
+ },
163
+ },
164
+ render: ({ src }) => <img src={src} />,
165
+ defaultProps: {},
166
+ },
167
+ },
168
+ };
169
+ ```
170
+
171
+ ## Excluding fields
172
+
173
+ To completely ignore a field when generating a page, use the [`exclude` API](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#exclude):
174
+
175
+ ```tsx
176
+ const config = {
177
+ components: {
178
+ HeadingBlock: {
179
+ fields: {
180
+ src: {
181
+ type: "text",
182
+ ai: {
183
+ exclude: true,
184
+ },
185
+ },
186
+ },
187
+ render: ({ src }) => <img src={src} />,
188
+ },
189
+ },
190
+ };
191
+ ```
192
+
193
+ ## Registering reusable field types
194
+
195
+ A [user field type](/docs/editor/api-reference/overrides/field-types) can be shared by many fields. Rather than repeating `ai.schema` on each one, describe the type once via `fieldTypes`.
196
+
197
+ Field types can be provided to the AI plugin:
198
+
199
+ ```tsx
200
+ const aiPlugin = createAiPlugin({
201
+ fieldTypes: {
202
+ cta: {
203
+ // Included in the prompt, so describe any rules for using the field
204
+ description: "Renders a call-to-action button",
205
+ schema: {
206
+ type: "object",
207
+ properties: {
208
+ label: { type: "string" },
209
+ },
210
+ },
211
+ },
212
+ },
213
+ });
214
+ ```
215
+
216
+ or `ai.generate`:
217
+
218
+ ```tsx
219
+ const { data } = await puck.ai.generate({
220
+ prompt: "Create a page about our products",
221
+ config,
222
+ fieldTypes: {
223
+ cta: {
224
+ // Included in the prompt, so describe any rules for using the field
225
+ description: "Renders a call-to-action button",
226
+ schema: {
227
+ type: "object",
228
+ properties: {
229
+ label: { type: "string" },
230
+ },
231
+ },
232
+ },
233
+ },
234
+ });
235
+ ```
236
+
237
+ When using this field, Puck AI will generate against the `schema`.
238
+
239
+ Omit `schema` and provide a `defaultValue` to have Puck AI add a field without generating the value.
240
+
241
+ ```tsx
242
+ const aiPlugin = createAiPlugin({
243
+ fieldTypes: {
244
+ timer: {
245
+ defaultValue: { label: "Countdown" },
246
+ description: "Renders a countdown",
247
+ },
248
+ },
249
+ });
250
+ ```
251
+
252
+ ## Rendering components as fields
253
+
254
+ By combining `fieldTypes` with [field transforms](/docs/editor/components-and-fields/field-transforms), Puck AI can render your components using fields. This works with [design mode](/docs/cloud/ai/design-mode).
255
+
256
+ ```tsx
257
+ const fieldTransforms = {
258
+ cta: ({ value }) => <button>{value.label}</button>,
259
+ };
260
+
261
+ const Example = () => <Puck fieldTransforms={fieldTransforms} />;
262
+ ```
263
+
264
+ ## Further reading
265
+
266
+ - [Field AI Config API reference](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields)
267
+ - [Component AI Config API reference](/docs/cloud/api-reference/plugin-ai/ai-configuration/components)
268
+ - [`AiFieldType` API reference](/docs/cloud/api-reference/plugin-ai/ai-field-type)
269
+ - [`createAiPlugin()` API reference](/docs/cloud/api-reference/plugin-ai/create-ai-plugin)
270
+ - [Field transforms](/docs/editor/components-and-fields/field-transforms)
271
+ - [Design mode](/docs/cloud/ai/design-mode)
@@ -0,0 +1,69 @@
1
+ # Business Context
2
+
3
+ Providing business context enables Puck AI to understand your business and build relevant pages. It applies in both assembly and design modes.
4
+
5
+ ## Context for AI plugin
6
+
7
+ When using the [AI plugin](/docs/cloud/api-reference/plugin-ai/create-ai-plugin), you can provide context to all interactions by using the [`ai.context`](/docs/cloud/api-reference/cloud-client/puck-handler#aicontext) parameter in the [`puckHandler()`](/docs/cloud/api-reference/cloud-client/puck-handler).
8
+
9
+ ```tsx
10
+
11
+ export async function POST(request) {
12
+ return puckHandler(request, {
13
+ ai: {
14
+ context: "We are Google. You create Google landing pages.",
15
+ },
16
+ });
17
+ }
18
+ ```
19
+
20
+ You can use this parameter to provide extensive information for your use-case:
21
+
22
+ ```tsx
23
+
24
+ const context = `## Overview
25
+ We are Google. You help us build Google landing pages.
26
+
27
+ ## Brand guidelines
28
+
29
+ Our brand colors are:
30
+
31
+ - #4285F4 (primary)
32
+ - #DB4437
33
+ - #F4B400
34
+ - #0F9D58
35
+
36
+ ## Tone of voice
37
+
38
+ - American English
39
+ - ...
40
+ `;
41
+
42
+ export async function POST(request) {
43
+ return puckHandler(request, {
44
+ ai: {
45
+ context,
46
+ },
47
+ });
48
+ }
49
+ ```
50
+
51
+ ## Context for server APIs
52
+
53
+ The `context` parameter on [`ai.generate()`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate#context) allows you to provide additional business information when [generating pages headlessly](/docs/cloud/ai/headless-generation):
54
+
55
+ ```ts
56
+
57
+ const puck = puckCloud();
58
+
59
+ await puck.ai.generate({
60
+ config,
61
+ context: "We are Google. You help us build Google landing pages.",
62
+ prompt: "Create a page about our maps product",
63
+ });
64
+ ```
65
+
66
+ ## Further reading
67
+
68
+ - [`ai.generate()` API reference](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate)
69
+ - [`puckHandler()` API reference](/docs/cloud/api-reference/cloud-client/puck-handler)
@@ -0,0 +1,133 @@
1
+ # Custom Agents
2
+
3
+ Build custom chat and AI streaming interfaces using the [`usePuckAi()` API](/docs/cloud/api-reference/plugin-ai/use-puck-ai).
4
+
5
+ ## Build a chat interface
6
+
7
+ Use [`usePuckAi().chat`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#returns) to hold a conversation with the agent, sending and reading messages. Changes are automatically applied to the canvas.
8
+
9
+ ```tsx
10
+
11
+ function ChatPlugin() {
12
+ const { chat } = usePuckAi();
13
+ const [input, setInput] = useState("");
14
+
15
+ return (
16
+ <div>
17
+ {chat.messages.map((message) =>
18
+ message.parts.map((part, i) =>
19
+ part.type === "text" ? <p key={i}>{part.text}</p> : null
20
+ )
21
+ )}
22
+
23
+ <form
24
+ onSubmit={(e) => {
25
+ e.preventDefault();
26
+ chat.sendMessage(input);
27
+ setInput("");
28
+ }}
29
+ >
30
+ <input value={input} onChange={(e) => setInput(e.target.value)} />
31
+ <button>Send</button>
32
+ </form>
33
+ </div>
34
+ );
35
+ }
36
+
37
+ export function Editor() {
38
+ return (
39
+ <Puck
40
+ config={config}
41
+ data={data}
42
+ plugins={[{ name: "chat", label: "Chat", render: ChatPlugin }]}
43
+ />
44
+ );
45
+ }
46
+ ```
47
+
48
+ ### Show the agent's progress
49
+
50
+ Look up each tool part in [`chat.toolStatus`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#chattoolstatus) to show what the agent is doing.
51
+
52
+ ```tsx
53
+ message.parts.map((part, i) => {
54
+ if (part.type === "text") return <p key={i}>{part.text}</p>;
55
+
56
+ // For example, "Updating page"
57
+ if ("toolCallId" in part) {
58
+ return <p key={i}>{chat.toolStatus[part.toolCallId]?.label}</p>;
59
+ }
60
+
61
+ return null;
62
+ });
63
+ ```
64
+
65
+ ## Request a single change
66
+
67
+ Use [`usePuckAi().generate()`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#generateprompt-options) to request a change to the current page, outside of a conversation.
68
+
69
+ ```tsx
70
+
71
+ function TranslatePlugin({ language }) {
72
+ const { generate } = usePuckAi();
73
+
74
+ return (
75
+ <button onClick={() => generate(`Translate this page to ${language}`)}>
76
+ Translate
77
+ </button>
78
+ );
79
+ }
80
+ ```
81
+
82
+ ## Replaying generations
83
+
84
+ You can replay a generation created headlessly using the server [`ai.generate()`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate) API.
85
+
86
+ To record a generation, use [`onPart`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate#onpart) to store each [AI Part](/docs/cloud/api-reference/plugin-ai/ai-part):
87
+
88
+ File: `server.ts`
89
+
90
+ ```ts
91
+
92
+ const puck = puckCloud();
93
+
94
+ await puck.ai.generate({
95
+ prompt: "Add a pricing section",
96
+ config,
97
+ pageData,
98
+ onPart: (part) => {
99
+ // Store the part
100
+ },
101
+ });
102
+ ```
103
+
104
+ To replay the parts into the editor, provide the stored parts to [`usePuckAi().applyPart`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#applypartpart-options):
105
+
106
+ File: `ApplyPlugin.tsx`
107
+
108
+ ```tsx
109
+
110
+ function ApplyPlugin() {
111
+ const { applyPart } = usePuckAi();
112
+
113
+ const apply = async () => {
114
+ const parts = getMyParts(); // Get parts from wherever you stored them
115
+
116
+ for await (const part of parts) {
117
+ await applyPart(part); // Apply them
118
+ }
119
+ };
120
+
121
+ return <button onClick={apply}>Apply</button>;
122
+ }
123
+ ```
124
+
125
+ By default, the server's `ai.generate()` will run a single iteration. See [multi-step headless generation](/docs/cloud/ai/headless-generation#multi-step-headless-generation) to learn more.
126
+
127
+ ## Further reading
128
+
129
+ - [`usePuckAi()` API reference](/docs/cloud/api-reference/plugin-ai/use-puck-ai)
130
+ - [`ai.generate()` API reference](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate)
131
+ - [`AIPart` data model](/docs/cloud/api-reference/plugin-ai/ai-part)
132
+ - [`puckHandler()` API reference](/docs/cloud/api-reference/cloud-client/puck-handler)
133
+ - [Headless generation](/docs/cloud/ai/headless-generation)