@puckeditor/cli 0.24.0-canary.90a7801f → 0.24.0-canary.b20be8d3

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 (43) hide show
  1. package/dist/bin.mjs +148 -7
  2. package/dist/docs/ai/ai-configuration.md +246 -0
  3. package/dist/docs/ai/business-context.md +69 -0
  4. package/dist/docs/ai/custom-agents.md +133 -0
  5. package/dist/docs/ai/design-mode.md +177 -0
  6. package/dist/docs/ai/getting-started.md +185 -0
  7. package/dist/docs/ai/headless-generation.md +155 -0
  8. package/dist/docs/ai/localization.md +43 -0
  9. package/dist/docs/ai/model-configuration.md +113 -0
  10. package/dist/docs/ai/overview.md +21 -0
  11. package/dist/docs/ai/tools.md +99 -0
  12. package/dist/docs/api-reference/ai/ai-plugin/create-ai-plugin.md +307 -0
  13. package/dist/docs/api-reference/ai/ai-plugin/dictionary.md +77 -0
  14. package/dist/docs/api-reference/ai/ai-plugin/installation.md +14 -0
  15. package/dist/docs/api-reference/ai/ai-plugin/use-puck-ai.md +175 -0
  16. package/dist/docs/api-reference/ai/ai-plugin/with-dynamic-config.md +35 -0
  17. package/dist/docs/api-reference/ai/cloud-client/chat.md +496 -0
  18. package/dist/docs/api-reference/ai/cloud-client/generate.md +546 -0
  19. package/dist/docs/api-reference/ai/cloud-client/installation.md +16 -0
  20. package/dist/docs/api-reference/ai/cloud-client/puck-handler.md +423 -0
  21. package/dist/docs/api-reference/ai/cloud-client/tool.md +128 -0
  22. package/dist/docs/api-reference/ai/configuration/components.md +72 -0
  23. package/dist/docs/api-reference/ai/configuration/fields.md +231 -0
  24. package/dist/docs/api-reference/components/action-bar-drag-handle.md +33 -0
  25. package/dist/docs/api-reference/components/field-group-item.md +39 -0
  26. package/dist/docs/api-reference/components/field-group.md +86 -0
  27. package/dist/docs/api-reference/components/field-tab.md +55 -0
  28. package/dist/docs/api-reference/data-model/ai-field-type.md +31 -0
  29. package/dist/docs/api-reference/data-model/ai-part.md +90 -0
  30. package/dist/docs/api-reference/fields/checkbox.md +87 -0
  31. package/dist/docs/api-reference/theming/field-tabs.md +28 -0
  32. package/dist/docs/cli.md +28 -3
  33. package/dist/docs/index.json +124 -0
  34. package/dist/docs/integrating-puck/field-grouping.md +149 -0
  35. package/dist/templates/next/app/puck/[...puckPath]/page.tsx +3 -2
  36. package/dist/templates/next/app/puck/page.tsx +0 -2
  37. package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +3 -2
  38. package/dist/templates/next-ai/app/puck/page.tsx +0 -2
  39. package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +3 -2
  40. package/dist/templates/vinext/app/puck/page.tsx +0 -2
  41. package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +3 -2
  42. package/dist/templates/vinext-ai/app/puck/page.tsx +0 -2
  43. 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
  };
@@ -783,6 +810,7 @@ var OPTIONS = {
783
810
  config: { type: "string" },
784
811
  "package-manager": { type: "string" },
785
812
  wait: { type: "boolean" },
813
+ login: { type: "boolean" },
786
814
  framework: { type: "string" },
787
815
  name: { type: "string" },
788
816
  offline: { type: "boolean" },
@@ -816,6 +844,7 @@ var MUTATING = [
816
844
  "config",
817
845
  "package-manager",
818
846
  "wait",
847
+ "login",
819
848
  "backend",
820
849
  "backend-url"
821
850
  ];
@@ -965,6 +994,7 @@ var parseCliArgs = (argv) => {
965
994
  config: values.config,
966
995
  packageManager: pm,
967
996
  wait: Boolean(values.wait),
997
+ login: Boolean(values.login),
968
998
  framework,
969
999
  name: values.name,
970
1000
  offline: Boolean(values.offline),
@@ -1161,6 +1191,22 @@ var createCloudApi = (baseUrl, fetchImpl) => {
1161
1191
  }
1162
1192
  return body;
1163
1193
  },
1194
+ async createClaimableProject(client) {
1195
+ const res = await request("api/claimable-projects", {
1196
+ method: "POST",
1197
+ headers: { "content-type": "application/json" },
1198
+ body: JSON.stringify(client)
1199
+ });
1200
+ if (res.status === 404 || res.status === 429) return null;
1201
+ const body = await json(res);
1202
+ if (!res.ok || typeof body.apiKey !== "string" || typeof body.claimUrl !== "string") {
1203
+ throw new CloudRequestError(
1204
+ `Puck Cloud returned an unexpected response (${res.status})`,
1205
+ "bad_response"
1206
+ );
1207
+ }
1208
+ return body;
1209
+ },
1164
1210
  async pollConnect(deviceCode) {
1165
1211
  const res = await request("api/cli/connect/token", {
1166
1212
  method: "POST",
@@ -1406,6 +1452,8 @@ Flags:
1406
1452
  add one, use one elsewhere, or none (editor only)
1407
1453
  --backend-url <url> The server for --backend external, e.g. http://localhost:3000
1408
1454
  --wait Wait for Puck Cloud login approval instead of returning
1455
+ --login Log in to Puck Cloud instead of starting on a project
1456
+ without an account (init, add)
1409
1457
  --framework <name> Framework for new apps (init), one of:
1410
1458
  ${FRAMEWORK_IDS.join(", ")}
1411
1459
  --name <name> Directory name for new apps (init)
@@ -1417,7 +1465,8 @@ Flags:
1417
1465
  For agents:
1418
1466
  Every command prints exactly one JSON document with --json. When "status" is
1419
1467
  "action_required", surface each entry in "actions" to the developer (e.g. a
1420
- browser_login URL and code), then run its "rerun" command. Exit codes:
1468
+ browser_login URL and code), then run its "rerun" command. Show a
1469
+ claim_project link to the developer even when "status" is "success". Exit codes:
1421
1470
  0 success, 2 usage, 3 unsupported project, 4 file conflict, 5 package manager,
1422
1471
  6 doctor found problems, 7 Puck Cloud unreachable, 10 action required, 11 partial.
1423
1472
 
@@ -1896,6 +1945,27 @@ var configImportClause = (shape, local) => {
1896
1945
  if (shape.named.length === 1) return `{ ${shape.named[0]} as ${local} }`;
1897
1946
  return null;
1898
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
+ };
1899
1969
  var TYPE_FALLBACKS = {
1900
1970
  UserData: 'import("@puckeditor/core").Data'
1901
1971
  };
@@ -1988,6 +2058,9 @@ var relocateModule = (code, opts) => {
1988
2058
  });
1989
2059
  }
1990
2060
  }
2061
+ if (opts.cacheComponents && /(^|\/)page\.[jt]sx?$/.test(opts.to)) {
2062
+ edits.push(...cacheComponentsEdits(ast, code));
2063
+ }
1991
2064
  return { ok: true, code: applyEdits(code, edits) };
1992
2065
  };
1993
2066
 
@@ -2574,6 +2647,7 @@ import "@puckeditor/core/puck.css";
2574
2647
  ${ai ? `import "@puckeditor/plugin-ai/styles.css";
2575
2648
  ` : ""}import "@puckeditor/plugin-pages/styles.css";
2576
2649
  import { Metadata } from "next";
2650
+ import { connection } from "next/server";
2577
2651
  import { Client } from "./client";${auth ? `
2578
2652
  import { requirePuckSession } from "../../../lib/puck-auth";` : ""}
2579
2653
 
@@ -2588,15 +2662,18 @@ ${auth ? `export default async function Page({
2588
2662
  }: {
2589
2663
  searchParams: Promise<Record<string, string>>;
2590
2664
  }) {
2665
+ // Puck renders in the browser, so the editor is rendered on every request
2666
+ await connection();
2591
2667
  const query = new URLSearchParams(await searchParams).toString();
2592
2668
  await requirePuckSession(\`/puck\${query ? \`?\${query}\` : ""}\`);
2593
2669
 
2594
2670
  return <Client />;
2595
2671
  }` : `export default async function Page() {
2672
+ // Puck renders in the browser, so the editor is rendered on every request
2673
+ await connection();
2674
+
2596
2675
  return <Client />;
2597
2676
  }`}
2598
-
2599
- export const dynamic = "force-dynamic";
2600
2677
  `;
2601
2678
  var nextPagesRenderPage = (host) => `/**
2602
2679
  * This file implements a catch-all route that renders the pages published in
@@ -3312,7 +3389,8 @@ var nextRelocation = (p, info) => {
3312
3389
  "lib/puck-auth": `${lib}/puck-auth`,
3313
3390
  "puck.config": configModuleTarget(p)
3314
3391
  },
3315
- config: configRelocation(p)
3392
+ config: configRelocation(p),
3393
+ cacheComponents: info.cacheComponents
3316
3394
  };
3317
3395
  };
3318
3396
  var conflictingSegments = (p, appDir) => {
@@ -6790,6 +6868,12 @@ var actionLines = (action) => {
6790
6868
  ` and confirm the code ${pc.bold(action.userCode)}`
6791
6869
  );
6792
6870
  break;
6871
+ case "claim_project":
6872
+ lines.push(
6873
+ ` Open ${pc.cyan(action.url)}`,
6874
+ ` before ${new Date(action.expiresAt).toLocaleString()}`
6875
+ );
6876
+ break;
6793
6877
  case "provide_api_key":
6794
6878
  lines.push(` ${action.instructions}`);
6795
6879
  break;
@@ -8194,6 +8278,28 @@ var connectFallback = (rc, err) => {
8194
8278
  warnings: []
8195
8279
  };
8196
8280
  };
8281
+ var startUnclaimed = async (rc, info) => {
8282
+ let created;
8283
+ try {
8284
+ created = await rc.cloud.createClaimableProject(clientPayload(rc, info));
8285
+ } catch (err) {
8286
+ return connectFallback(rc, err);
8287
+ }
8288
+ if (!created) return null;
8289
+ const secret = secretFrom(rc, created.apiKey, "Puck Cloud");
8290
+ rc.log(
8291
+ `\u2713 Created the Puck Cloud project "${created.project.name}" without an account (key "${created.keyName}")`
8292
+ );
8293
+ return {
8294
+ kind: "resolved",
8295
+ secret,
8296
+ source: "connect",
8297
+ needsWrite: true,
8298
+ verified: "valid",
8299
+ warnings: [],
8300
+ claim: { url: created.claimUrl, expiresAt: created.expiresAt }
8301
+ };
8302
+ };
8197
8303
  var connectNonInteractive = async (rc, info, attempt = 0) => {
8198
8304
  const store = new SessionStore(
8199
8305
  cacheDirFor(rc.deps.env, rc.deps.homedir),
@@ -8412,10 +8518,22 @@ var resolveCredential = async (rc, state, info, { fresh = false } = {}) => {
8412
8518
  "How do you want to connect to Puck Cloud?",
8413
8519
  [
8414
8520
  { value: "login", name: "Log in with the browser (recommended)" },
8521
+ // `connect` replaces the key, often for a branch, so it always logs in
8522
+ ...fresh ? [] : [
8523
+ {
8524
+ value: "unclaimed",
8525
+ name: "Start without an account (claim it within 72 hours)"
8526
+ }
8527
+ ],
8415
8528
  { value: "paste", name: "Paste an existing API key" }
8416
8529
  ]
8417
8530
  );
8418
- if (method === "login") {
8531
+ if (method === "unclaimed") {
8532
+ const started = await startUnclaimed(rc, info);
8533
+ if (started?.kind === "resolved") return { ...started, warnings };
8534
+ rc.log("Couldn't start without an account. Log in instead.");
8535
+ }
8536
+ if (method === "login" || method === "unclaimed") {
8419
8537
  const connected = await connectInteractive(rc, info);
8420
8538
  if (connected) return { ...connected, warnings };
8421
8539
  rc.log("Falling back to pasting an API key.");
@@ -8437,6 +8555,11 @@ var resolveCredential = async (rc, state, info, { fresh = false } = {}) => {
8437
8555
  }
8438
8556
  };
8439
8557
  }
8558
+ if (!fresh && !rc.flags.login) {
8559
+ const started = await startUnclaimed(rc, info);
8560
+ if (started)
8561
+ return { ...started, warnings: [...warnings, ...started.warnings] };
8562
+ }
8440
8563
  const resolution = await connectNonInteractive(rc, info);
8441
8564
  return { ...resolution, warnings: [...warnings, ...resolution.warnings] };
8442
8565
  };
@@ -8908,6 +9031,24 @@ var runMutation = async (rc, input) => {
8908
9031
  [credential.action]
8909
9032
  );
8910
9033
  }
9034
+ if (credential.kind === "resolved" && credential.claim) {
9035
+ const { url, expiresAt } = credential.claim;
9036
+ planner.manual({
9037
+ id: "cloud:claim",
9038
+ type: "claim_project",
9039
+ required: false,
9040
+ message: "Ask the developer to claim this Puck Cloud project before it expires, or it's deleted with its pages.",
9041
+ url,
9042
+ expiresAt,
9043
+ instructions: `Open ${url} and sign up or log in before ${expiresAt}. ${ENV_KEY} keeps working once it's claimed.`
9044
+ });
9045
+ if (capabilities.includes("ai") || state.ai.installed) {
9046
+ planner.warn(
9047
+ "PUCK-CLI-W-AI-UNCLAIMED",
9048
+ `Puck AI works once the project is claimed. Open ${url} to claim it.`
9049
+ );
9050
+ }
9051
+ }
8911
9052
  if (credential.kind === "resolved" && credential.needsWrite) {
8912
9053
  planEnvWrite(planner, credential.secret);
8913
9054
  } else if (credential.kind === "resolved" && state.cloud.apiKey.file) {
@@ -11573,7 +11714,7 @@ runCli(process.argv.slice(2), {
11573
11714
  stdout: process.stdout,
11574
11715
  stderr: process.stderr,
11575
11716
  stdinIsTTY: Boolean(process.stdin.isTTY),
11576
- cliVersion: "0.24.0-canary.90a7801f",
11717
+ cliVersion: "0.24.0-canary.b20be8d3",
11577
11718
  invocation: localInvocation(
11578
11719
  fs8.realpathSync(fileURLToPath(import.meta.url)),
11579
11720
  fs8.realpathSync(process.cwd()),
@@ -0,0 +1,246 @@
1
+ # AI Configuration
2
+
3
+ AI configuration allows further control of agent behavior via the `ai` parameter on both [component](/docs/api-reference/ai/configuration/components) and [field](/docs/api-reference/ai/configuration/fields) configs.
4
+
5
+ ## Providing instructions
6
+
7
+ The `instructions` parameter provides the agent with natural-language guidance on how to use a component or field.
8
+
9
+ Here's an example using [`instructions` on components](/docs/api-reference/ai/configuration/components#instructions):
10
+
11
+ ```ts
12
+ const config = {
13
+ components: {
14
+ HeadingBlock: {
15
+ ai: {
16
+ instructions: "Always place this first",
17
+ },
18
+ fields: {
19
+ title: {
20
+ type: "text",
21
+ },
22
+ },
23
+ render: ({ title }) => <h1>{title}</h1>,
24
+ },
25
+ },
26
+ };
27
+ ```
28
+
29
+ And using [`instructions` on fields](/docs/api-reference/ai/configuration/fields#instructions):
30
+
31
+ ```ts
32
+ const config = {
33
+ components: {
34
+ HeadingBlock: {
35
+ fields: {
36
+ title: {
37
+ type: "text",
38
+ ai: {
39
+ instructions: "Always use caps",
40
+ },
41
+ },
42
+ },
43
+ render: ({ title }) => <h1>{title}</h1>,
44
+ },
45
+ },
46
+ };
47
+ ```
48
+
49
+ ## Setting a schema
50
+
51
+ Some field types like [`custom`](/docs/api-reference/fields/custom), [`external`](/docs/api-reference/fields/external), or [user fields](/docs/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.
52
+
53
+ To address this, provide a [`schema`](/docs/api-reference/ai/configuration/fields#schema) using JSON Schema:
54
+
55
+ ```tsx
56
+ const config = {
57
+ components: {
58
+ HeadingBlock: {
59
+ fields: {
60
+ title: {
61
+ type: "custom",
62
+ ai: {
63
+ schema: { type: "text" },
64
+ },
65
+ render: () => <input />,
66
+ },
67
+ },
68
+ render: ({ title }) => <h1>{title}</h1>,
69
+ },
70
+ },
71
+ };
72
+ ```
73
+
74
+ We recommend using [Zod](https://zod.dev/json-schema) to help with producing JSON Schema for complex shapes:
75
+
76
+ ```tsx
77
+
78
+ const config = {
79
+ components: {
80
+ HeadingBlock: {
81
+ fields: {
82
+ object: {
83
+ type: "custom",
84
+ ai: {
85
+ schema: z.toJSONSchema(
86
+ z.object({
87
+ title: z.string(),
88
+ })
89
+ ),
90
+ },
91
+ render: () => <input />,
92
+ },
93
+ },
94
+ render: ({ object }) => <h1>{object.title}</h1>,
95
+ },
96
+ },
97
+ };
98
+ ```
99
+
100
+ ## Excluding components
101
+
102
+ To completely ignore a component when generating a page, use the [`exclude` API](/docs/api-reference/ai/configuration/components#exclude):
103
+
104
+ ```tsx
105
+ const config = {
106
+ components: {
107
+ HeadingBlock: {
108
+ fields: {
109
+ title: { type: "text" },
110
+ },
111
+ ai: {
112
+ exclude: true,
113
+ },
114
+ render: ({ title }) => <h1>{title}</h1>,
115
+ },
116
+ },
117
+ };
118
+ ```
119
+
120
+ ## Disabling streaming
121
+
122
+ When using the [AI plugin](/docs/api-reference/ai/ai-plugin/installation), Puck AI will stream field values wherever possible. This can sometimes result in unexpected behavior when rendering the preview, such as broken image URLs.
123
+
124
+ You can set the [`stream` parameter](/docs/api-reference/ai/configuration/fields#stream) to `false` to disable streaming of a field:
125
+
126
+ ```tsx
127
+ const config = {
128
+ components: {
129
+ HeadingBlock: {
130
+ fields: {
131
+ src: {
132
+ type: "text",
133
+ ai: {
134
+ stream: false,
135
+ },
136
+ },
137
+ },
138
+ render: ({ src }) => <img src={src} />,
139
+ },
140
+ },
141
+ };
142
+ ```
143
+
144
+ ## Setting required fields
145
+
146
+ By default, all fields provided in [`defaultProps`](/docs/api-reference/configuration/component-config#defaultprops) are considered required by the agent.
147
+
148
+ You can explicitly mark a field as required or optional by using the [`required` parameter](/docs/api-reference/ai/configuration/fields#required).
149
+
150
+ ```tsx
151
+ const config = {
152
+ components: {
153
+ HeadingBlock: {
154
+ fields: {
155
+ src: {
156
+ type: "text",
157
+ ai: {
158
+ required: true, // Mark this as required, even though it doesn't exist in defaultProps
159
+ },
160
+ },
161
+ },
162
+ render: ({ src }) => <img src={src} />,
163
+ defaultProps: {},
164
+ },
165
+ },
166
+ };
167
+ ```
168
+
169
+ ## Excluding fields
170
+
171
+ To completely ignore a field when generating a page, use the [`exclude` API](/docs/api-reference/ai/configuration/fields#exclude):
172
+
173
+ ```tsx
174
+ const config = {
175
+ components: {
176
+ HeadingBlock: {
177
+ fields: {
178
+ src: {
179
+ type: "text",
180
+ ai: {
181
+ exclude: true,
182
+ },
183
+ },
184
+ },
185
+ render: ({ src }) => <img src={src} />,
186
+ },
187
+ },
188
+ };
189
+ ```
190
+
191
+ ## Registering reusable field types
192
+
193
+ A [user field type](/docs/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` on the [AI plugin](/docs/api-reference/ai/ai-plugin/create-ai-plugin#fieldtypes):
194
+
195
+ ```tsx
196
+ const aiPlugin = createAiPlugin({
197
+ fieldTypes: {
198
+ cta: {
199
+ // Included in the prompt, so describe any rules for using the field
200
+ description: "Renders a call-to-action button",
201
+ schema: {
202
+ type: "object",
203
+ properties: {
204
+ label: { type: "string" },
205
+ },
206
+ },
207
+ },
208
+ },
209
+ });
210
+ ```
211
+
212
+ When using this field, Puck AI will generate against the `schema`.
213
+
214
+ Omit `schema` and provide a `defaultValue` to have Puck AI add a field without generating the value.
215
+
216
+ ```tsx
217
+ const aiPlugin = createAiPlugin({
218
+ fieldTypes: {
219
+ timer: {
220
+ defaultValue: { label: "Countdown" },
221
+ description: "Renders a countdown",
222
+ },
223
+ },
224
+ });
225
+ ```
226
+
227
+ ## Rendering components as fields
228
+
229
+ By combining `fieldTypes` with [field transforms](/docs/extending-puck/field-transforms), Puck AI can render your components using fields. This works with [design mode](/docs/ai/design-mode).
230
+
231
+ ```tsx
232
+ const fieldTransforms = {
233
+ cta: ({ value }) => <button>{value.label}</button>,
234
+ };
235
+
236
+ const Example = () => <Puck fieldTransforms={fieldTransforms} />;
237
+ ```
238
+
239
+ ## Further reading
240
+
241
+ - [Field AI Config API reference](/docs/api-reference/ai/configuration/fields)
242
+ - [Component AI Config API reference](/docs/api-reference/ai/configuration/components)
243
+ - [`AiFieldType` API reference](/docs/api-reference/data-model/ai-field-type)
244
+ - [`createAiPlugin()` API reference](/docs/api-reference/ai/ai-plugin/create-ai-plugin)
245
+ - [Field transforms](/docs/extending-puck/field-transforms)
246
+ - [Design mode](/docs/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/api-reference/ai/ai-plugin/installation), you can provide context to all interactions by using the [`ai.context`](/docs/api-reference/ai/cloud-client/puck-handler#aicontext) parameter in the [`puckHandler()`](/docs/api-reference/ai/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 one-off pages
52
+
53
+ The `context` parameter on [`ai.generate()`](/docs/api-reference/ai/cloud-client/generate#context) allows you to provide additional business information when generating one-off pages:
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/api-reference/ai/cloud-client/generate)
69
+ - [`puckHandler()` API reference](/docs/api-reference/ai/cloud-client/puck-handler)