@copilotkit/core 2.0.0-rc.4 → 2.0.0-rc.41

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 (47) hide show
  1. package/dist/a2ui-markdown-BxZr1mEU.mjs +1360 -0
  2. package/dist/a2ui-markdown-BxZr1mEU.mjs.map +1 -0
  3. package/dist/a2ui-markdown-DkMXFQih.cjs +1419 -0
  4. package/dist/a2ui-markdown-DkMXFQih.cjs.map +1 -0
  5. package/dist/chat-configuration.cjs +269 -0
  6. package/dist/chat-configuration.cjs.map +1 -0
  7. package/dist/chat-configuration.d.cts +123 -0
  8. package/dist/chat-configuration.d.cts.map +1 -0
  9. package/dist/chat-configuration.d.mts +123 -0
  10. package/dist/chat-configuration.d.mts.map +1 -0
  11. package/dist/chat-configuration.mjs +268 -0
  12. package/dist/chat-configuration.mjs.map +1 -0
  13. package/dist/generative-ui/index.cjs +3474 -0
  14. package/dist/generative-ui/index.cjs.map +1 -0
  15. package/dist/generative-ui/index.d.cts +1041 -0
  16. package/dist/generative-ui/index.d.cts.map +1 -0
  17. package/dist/generative-ui/index.d.mts +1041 -0
  18. package/dist/generative-ui/index.d.mts.map +1 -0
  19. package/dist/generative-ui/index.mjs +3425 -0
  20. package/dist/generative-ui/index.mjs.map +1 -0
  21. package/dist/index.cjs +10892 -2231
  22. package/dist/index.cjs.map +1 -1
  23. package/dist/index.d.cts +3 -3908
  24. package/dist/index.d.mts +3 -3908
  25. package/dist/index.mjs +10613 -2222
  26. package/dist/index.mjs.map +1 -1
  27. package/dist/index.umd.js +14459 -2201
  28. package/dist/index.umd.js.map +1 -1
  29. package/dist/learning-bridge-Cqc7VJuV.d.cts +10919 -0
  30. package/dist/learning-bridge-Cqc7VJuV.d.cts.map +1 -0
  31. package/dist/learning-bridge-y2bnVsjp.d.mts +10919 -0
  32. package/dist/learning-bridge-y2bnVsjp.d.mts.map +1 -0
  33. package/dist/styles.cjs +1 -1
  34. package/dist/styles.cjs.map +1 -1
  35. package/dist/styles.css +1 -1
  36. package/dist/styles.mjs +1 -1
  37. package/dist/styles.mjs.map +1 -1
  38. package/dist/viewport-CksL5y8p.mjs +954 -0
  39. package/dist/viewport-CksL5y8p.mjs.map +1 -0
  40. package/dist/viewport-D-tuKCeb.cjs +1182 -0
  41. package/dist/viewport-D-tuKCeb.cjs.map +1 -0
  42. package/package.json +36 -8
  43. package/stryker.config.mjs +6 -0
  44. package/tsdown.config.ts +16 -2
  45. package/vitest.mutation.config.mjs +6 -0
  46. package/dist/index.d.cts.map +0 -1
  47. package/dist/index.d.mts.map +0 -1
@@ -0,0 +1,1041 @@
1
+ import { Gs as MarkdownSegment, Ms as A2UIMarkdownOperation, a as CopilotKitCore, dd as ɵGenerativeUIDebugRun, pd as ɵGenerativeUIDebugSource } from "../learning-bridge-Cqc7VJuV.cjs";
2
+ import "../index.cjs";
3
+ import { AbstractAgent, Message } from "@ag-ui/client";
4
+ import { A2UIActionMessage, A2UIFunctionPermissions, A2UIFunctionReturnType, A2UIOperation, CopilotKitUIEnvelope, GenerativeUIActionBinding, GenerativeUIFunctionManifest, GenerativeUIManifest, GenerativeUIRejectedOperation, GenerativeUISurfaceContent, GenerativeUISurfaceStatus, GenerativeUISurfaceSummary, GenerativeUITarget, GenerativeUIUserEvent, StandardSchemaV1, ValidateOperationOptions } from "@copilotkit/shared";
5
+ import { GenerativeUI, GenerativeUIError, GenerativeUIErrorInfo, GenerativeUIInvokeResult, GenerativeUISchema } from "@copilotkit/shared/generative-ui";
6
+ import { SurfaceModel } from "@a2ui/web_core/state";
7
+ import { z } from "zod";
8
+
9
+ //#region src/generative-ui/dispatcher.d.ts
10
+ /**
11
+ * A function that generated UI may call, as declared in
12
+ * `createGenerativeUI({ functions })`. Zod schemas fit `parameters`, because
13
+ * they implement Standard Schema.
14
+ */
15
+ interface GenerativeUIDeclaredFunction extends A2UIFunctionPermissions {
16
+ description?: string;
17
+ parameters: StandardSchemaV1;
18
+ returnType?: A2UIFunctionReturnType;
19
+ }
20
+ /**
21
+ * Holds the latest handler of one mounted `useGenerativeUIFunction`. The hook
22
+ * updates `current` on each render, so it registers only once per mount.
23
+ */
24
+ interface GenerativeUIHandlerRef {
25
+ current: (args: any) => unknown;
26
+ }
27
+ /** The component of a surface that called a function. */
28
+ interface GenerativeUIInvocationOrigin {
29
+ surfaceId: string;
30
+ componentId: string;
31
+ }
32
+ /**
33
+ * What called a function: a component of a surface, or the agent with a
34
+ * `callRendererFunction` operation.
35
+ */
36
+ type GenerativeUICallOrigin = GenerativeUIInvocationOrigin | {
37
+ functionCallId: string;
38
+ };
39
+ interface GenerativeUIDispatcher {
40
+ /**
41
+ * Call a declared function with arguments from generated UI or from the
42
+ * agent. Never throws: every failure becomes `{ ok: false, error }`.
43
+ */
44
+ invoke(name: string, args: unknown, origin: GenerativeUICallOrigin): Promise<GenerativeUIInvokeResult>;
45
+ /** The declared functions that have exactly one mounted handler, as JSON Schema. */
46
+ listExposed(): Record<string, GenerativeUIFunctionManifest>;
47
+ /**
48
+ * Mount a handler for a declared function. Returns the function that
49
+ * unmounts it. Calling the returned function more than once is safe.
50
+ */
51
+ register(name: string, ref: GenerativeUIHandlerRef): () => void;
52
+ /** How many handlers are mounted for `name`, for the inspector. */
53
+ handlerCount(name: string): number;
54
+ }
55
+ interface GenerativeUIDispatcherOptions {
56
+ /** The functions declared in `createGenerativeUI({ functions })`, read at call time. */
57
+ getDeclared: () => ReadonlyMap<string, GenerativeUIDeclaredFunction>;
58
+ /** Called for each failed `invoke`. A throw from it is ignored. */
59
+ onError?: (info: {
60
+ name: string;
61
+ origin: GenerativeUICallOrigin;
62
+ error: GenerativeUIError;
63
+ }) => void;
64
+ }
65
+ declare function createGenerativeUIDispatcher(options: GenerativeUIDispatcherOptions): GenerativeUIDispatcher;
66
+ //#endregion
67
+ //#region src/generative-ui/surface-manager.d.ts
68
+ declare function surfaceKey(threadId: string, surfaceId: string): string;
69
+ interface ManagedSurface {
70
+ readonly key: string;
71
+ readonly threadId: string;
72
+ readonly surfaceId: string;
73
+ readonly agentId: string | undefined;
74
+ /** Replaced by an empty model when the surface closes, to free its data. */
75
+ model: SurfaceModel<any>;
76
+ readonly createdAt: number;
77
+ target: string;
78
+ status: GenerativeUISurfaceStatus;
79
+ deleted: boolean;
80
+ /** Its first createSurface was rejected, so it never existed. */
81
+ failed: boolean;
82
+ /** Rejections reported by the runtime. */
83
+ serverRejected: GenerativeUIRejectedOperation[];
84
+ /** Rejections detected while applying operations in the browser. */
85
+ clientRejected: GenerativeUIRejectedOperation[];
86
+ /** The committed operations of the latest content, for the inspector. */
87
+ operations: readonly A2UIOperation[];
88
+ }
89
+ interface GenerativeUISurfaceManagerOptions {
90
+ onOperationRejected?: (info: {
91
+ surfaceId: string;
92
+ index: number;
93
+ reason: string;
94
+ }) => void;
95
+ }
96
+ /** What one mount of a target tells the model. */
97
+ interface GenerativeUITargetOptions {
98
+ /** Where the target is on the page and what to show in it. */
99
+ description?: string;
100
+ /**
101
+ * The only components that the surfaces of the target can use. Left out,
102
+ * every component of the UI is allowed.
103
+ */
104
+ components?: readonly string[];
105
+ }
106
+ /** A mounted target, as the manifest lists it. */
107
+ interface GenerativeUIMountedTarget {
108
+ id: string;
109
+ description?: string;
110
+ components?: string[];
111
+ }
112
+ /**
113
+ * Framework-agnostic store of generated surfaces. One web_core SurfaceModel per
114
+ * (threadId, surfaceId), shared by every mount. Applies only newly committed
115
+ * operations, validates each before applying it, and owns app state and the
116
+ * data model paths that the user wrote, so agent updates cannot overwrite
117
+ * them. App state never goes into a surface's data model. Selectors read it
118
+ * with `getState()`.
119
+ */
120
+ declare class GenerativeUISurfaceManager {
121
+ private readonly ui;
122
+ private readonly options;
123
+ private readonly surfaces;
124
+ private readonly bookkeeping;
125
+ private readonly listeners;
126
+ /** Mounts of each target id, in mount order. */
127
+ private readonly targets;
128
+ private state;
129
+ /**
130
+ * User-owned data model values, by surface key, then by path. Kept when a
131
+ * surface is rebuilt. Cleared when the surface is deleted.
132
+ */
133
+ private readonly owned;
134
+ /**
135
+ * Keys of the surfaces that a `deleteSurface` removed. A surface id is
136
+ * unique for the life of the page, so a key stays here when its surface is
137
+ * built again.
138
+ */
139
+ private readonly deletedKeys;
140
+ /**
141
+ * Surfaces that share their data model, by surface key: the parts of a
142
+ * chat surface that the prose lift split. A user write to one part goes
143
+ * to every part, so an input in one part drives a binding in another.
144
+ */
145
+ private readonly linked;
146
+ private readonly webCoreCatalog;
147
+ private activeThreadId;
148
+ private version;
149
+ constructor(ui: GenerativeUI, options?: GenerativeUISurfaceManagerOptions);
150
+ subscribe: (listener: () => void) => (() => void);
151
+ getVersion: () => number;
152
+ private notify;
153
+ setActiveThread(threadId: string | undefined): void;
154
+ getActiveThread(): string | undefined;
155
+ ingest(threadId: string, agentId: string | undefined, content: GenerativeUISurfaceContent): void;
156
+ /** The surface of a `key` (see `surfaceKey`), unless it is deleted. */
157
+ getSurfaceByKey(key: string): ManagedSurface | undefined;
158
+ getSurface(threadId: string, surfaceId: string): ManagedSurface | undefined;
159
+ getSurfaceForTarget(target: string, threadId?: string | undefined): ManagedSurface | undefined;
160
+ /**
161
+ * A surface whose first createSurface was rejected, so the chat can show
162
+ * the error where the surface would be. `undefined` for any other surface.
163
+ */
164
+ getFailedSurface(threadId: string, surfaceId: string): ManagedSurface | undefined;
165
+ /**
166
+ * The surfaces of a thread, for the model. A surface with user-owned
167
+ * values lists them in `dataModel`, so the model can read what the user
168
+ * entered. A surface with dropped operations lists them in `rejected`, so
169
+ * the model can fix them on the next run. A deleted surface, or one that
170
+ * was never created, has a `status`, so the model knows that the id is
171
+ * not a live surface.
172
+ */
173
+ describeSurfaces(threadId: string): Record<string, GenerativeUISurfaceSummary>;
174
+ /**
175
+ * Every surface that is not deleted, oldest first, for the inspector. The
176
+ * data model and the user values are copies, so the inspector cannot
177
+ * change the surface through them. The inspector asks for this on every
178
+ * change of the manager, so each copy is made only the first time it is
179
+ * read (then kept): a snapshot that nobody opens copies nothing. The user
180
+ * values are those of the call; the data model is the one of the first
181
+ * read, which the inspector does while it renders the snapshot.
182
+ */
183
+ debugSurfaces(): {
184
+ surfaceId: string;
185
+ threadId: string;
186
+ agentId: string | undefined;
187
+ target: string;
188
+ status: ManagedSurface["status"];
189
+ operations: ManagedSurface["operations"];
190
+ dataModel: unknown;
191
+ userValues: Record<string, unknown>;
192
+ rejected: Array<GenerativeUIRejectedOperation & {
193
+ source: "runtime" | "browser";
194
+ }>;
195
+ }[];
196
+ /**
197
+ * Marks a target as mounted. Returns the function that unmounts it. Calling
198
+ * that function more than once has no effect.
199
+ *
200
+ * @param id - The target id.
201
+ * @param options - The description and the allowed components of this mount.
202
+ */
203
+ registerTarget(id: string, options?: GenerativeUITargetOptions): () => void;
204
+ /**
205
+ * The mounted targets. Each has the description and the component list of
206
+ * its earliest mount that has one.
207
+ */
208
+ getMountedTargets(): GenerativeUIMountedTarget[];
209
+ /**
210
+ * The component list of the earliest mount of `id` that has one.
211
+ * `undefined` when no mount of `id` limits its components.
212
+ */
213
+ private targetComponents;
214
+ /** The components that `validateOperation` allows on a surface. */
215
+ private allowedComponentsFor;
216
+ /**
217
+ * The app state object. It is the same object until a key changes, so it
218
+ * can be a `useSyncExternalStore` snapshot.
219
+ */
220
+ getState: () => Readonly<Record<string, unknown>>;
221
+ /** Sets one state key. Notifies only when the value changed. */
222
+ setState(key: string, value: unknown): void;
223
+ /** Removes one state key. Notifies only when the key was set. */
224
+ removeState(key: string): void;
225
+ /**
226
+ * Makes the surfaces of `surfaceIds` share their data model: a user write
227
+ * to one of them goes to all of them (see `setOwnedValue`). The markdown
228
+ * transport links the parts of a chat surface that the prose lift split.
229
+ * A later call for one of the surfaces replaces its group.
230
+ *
231
+ * @param threadId - The thread of the surfaces.
232
+ * @param surfaceIds - The surface ids of the group. One id clears a link.
233
+ */
234
+ linkSurfaces(threadId: string, surfaceIds: readonly string[]): void;
235
+ /**
236
+ * Writes a user value into the data model of a surface, and marks `path`
237
+ * as user-owned. Then agent writes to that path, or below it, are ignored.
238
+ * An agent write above it keeps the user value. Ownership ends when the
239
+ * surface is deleted. Does nothing for an unknown or deleted surface with
240
+ * no live linked surface, and then does not check `value` either. The
241
+ * surfaces linked to it (see `linkSurfaces`) get the same write.
242
+ *
243
+ * @param key - The `key` of the surface.
244
+ * @param path - An absolute JSON pointer, for example "/form/email".
245
+ * @param value - The new value. It is copied with structuredClone
246
+ * semantics, so the data model never shares an object with it, and it
247
+ * keeps what structuredClone keeps: `NaN`, `Infinity`, `-0`, a `Date`,
248
+ * a `Map`, a `Set`; a class instance becomes a plain object. The agent
249
+ * reads it from the JSON request of the next run, so it is told what
250
+ * `JSON.stringify` makes of it (`NaN` becomes `null`, a valid `Date`
251
+ * its ISO string, an invalid one `null`, a `Map` `{}`). A value JSON refuses (a bigint, a cycle) is
252
+ * written, but left out of what the agent is told, with a
253
+ * `console.warn`. `null` or `undefined` removes the key, as an agent
254
+ * `null` does; the path stays user-owned, and the agent is told `null`
255
+ * for it, which the protocol reads as "removed".
256
+ * @throws An error named "DataCloneError" when structuredClone refuses
257
+ * `value`: a function, a symbol, a `WeakMap`, a `Promise`... It is
258
+ * checked before any surface is written, so nothing is written. The
259
+ * framework setters report it with `reportError`.
260
+ * @throws Error when a path segment is "__proto__", "constructor" or
261
+ * "prototype", or when the path does not fit the data (for example, a
262
+ * segment above it holds a string).
263
+ */
264
+ setOwnedValue(key: string, path: string, value: unknown): void;
265
+ /** Writes `owned`, which `setOwnedValue` made, as a user-owned value. */
266
+ private writeOwnedValue;
267
+ /**
268
+ * Writes the user-owned values into the new, empty data model of a rebuilt
269
+ * surface. The agent operations are applied after it.
270
+ */
271
+ private restoreOwnedValues;
272
+ /**
273
+ * The value that an agent write puts at `path`, with the user-owned values
274
+ * below `path` written back into it. `undefined` when `path` is user-owned
275
+ * or below a user-owned path, so the agent cannot write it. Throws when a
276
+ * user value does not fit the new value.
277
+ */
278
+ private mergeOwnedValues;
279
+ private extendsApplied;
280
+ private createSurface;
281
+ private disposeSurface;
282
+ /**
283
+ * Marks a surface deleted and frees its components and data. The record
284
+ * stays, so the model is still told about the id and the bookkeeping does
285
+ * not rebuild the surface for content that was already applied.
286
+ */
287
+ private closeSurface;
288
+ /** The surfaces of a thread that a part of `surfaceId` reads, for tests. */
289
+ getLinkedSurfaceIds(threadId: string, surfaceId: string): string[];
290
+ /**
291
+ * Drops the node keys that the app sets: bound props and matched events.
292
+ * The model does not see them, so a model value for one is ignored, not
293
+ * rejected. This runs before validation, because validation rejects keys
294
+ * that are not in the manifest. It never changes the given operation.
295
+ */
296
+ private dropAppSetKeys;
297
+ private dropAppSetNodeKeys;
298
+ /**
299
+ * The surfaces that `validateOperation` gets for one operation of the
300
+ * content of `surface`.
301
+ *
302
+ * - `knownSurfaces`: the surface, when it exists before the operation. It
303
+ * does not exist before its first createSurface, or after a delete.
304
+ * - `createdSurfaces`: the surface, when a createSurface at this position
305
+ * uses its id again. That is the case after the first operation, and for
306
+ * a surface that was deleted before, unless the content replays that
307
+ * delete.
308
+ */
309
+ private surfacesFor;
310
+ private applyOperation;
311
+ /** The first node with props of the wrong type, as a reason. */
312
+ private nodesProblem;
313
+ /**
314
+ * Writes an agent value at `path` and keeps the user-owned values. A write
315
+ * to a user-owned path is ignored, not rejected. Gives the reason when the
316
+ * value does not fit the data, else `undefined`.
317
+ */
318
+ private writeAgentData;
319
+ private checkNodeProps;
320
+ private upsertNode;
321
+ }
322
+ //#endregion
323
+ //#region src/generative-ui/runtime.d.ts
324
+ /**
325
+ * What the engine needs from the runtime of a framework: the surfaces, the
326
+ * function dispatcher, and how user events and errors leave the UI. A
327
+ * framework's runtime object satisfies it structurally and adds its own
328
+ * config and theme on top.
329
+ */
330
+ interface GenerativeUIEngine {
331
+ manager: GenerativeUISurfaceManager;
332
+ dispatcher: GenerativeUIDispatcher;
333
+ /** The generative UI given to the provider. */
334
+ ui: GenerativeUI;
335
+ forwardEvent: (event: GenerativeUIUserEvent, agentId: string | undefined) => Promise<GenerativeUIInvokeResult>;
336
+ reportError: (info: GenerativeUIErrorInfo) => void;
337
+ }
338
+ /**
339
+ * Reports an error without ever throwing: `reportError` reaches host code
340
+ * (`onError`), and a throwing host callback must not break rendering or an
341
+ * event handler.
342
+ */
343
+ declare function reportErrorSafely(engine: Pick<GenerativeUIEngine, "reportError">, info: GenerativeUIErrorInfo): void;
344
+ //#endregion
345
+ //#region src/generative-ui/functions.d.ts
346
+ /** Thrown for a bad call: an unknown function, bad args, or a bad value. */
347
+ declare class ExpressionError extends Error {
348
+ constructor(message: string);
349
+ }
350
+ /**
351
+ * Thrown when the platform lacks what a function needs: `window.open`, or
352
+ * an `Intl` constructor on a Hermes build. The call itself was fine, so it
353
+ * is not an ExpressionError: the dispatcher reports it as `handler_failed`,
354
+ * not `invalid_arguments`, and the model is not told to change its args.
355
+ */
356
+ declare class PlatformError extends Error {
357
+ constructor(message: string);
358
+ }
359
+ type BasicFunction = (args: Record<string, unknown>) => unknown;
360
+ /** The boolean of a DynamicBoolean: a ValidationResult counts as `valid`. */
361
+ declare function truthOf(value: unknown): boolean;
362
+ /**
363
+ * Opens an http(s) URL in a new tab. Any other scheme is refused.
364
+ *
365
+ * Without a `window` (server rendering) it does nothing. A platform that has
366
+ * a `window` but no `window.open` (React Native, where `window` is the global
367
+ * object) gets a PlatformError, not a misleading URL-parsing one. On a
368
+ * browser page WHATWG URL decides, as it always did. Without a real page
369
+ * origin (React Native, also with the location polyfill) only absolute
370
+ * URLs are taken: a relative one has nothing to resolve against. There the
371
+ * URL is checked by the stricter `parseUrl`, not by React Native's URL
372
+ * class, which accepts almost anything.
373
+ */
374
+ declare function openUrlSafely(url: unknown): void;
375
+ /**
376
+ * The basic functions, except `formatString`, `calc` and `series`:
377
+ * `resolve.ts` adds those three when it loads (`formatString` needs the
378
+ * resolver, and `calc.ts` uses this module). Import `resolve.ts` before
379
+ * looking a function up here.
380
+ */
381
+ declare const BASIC_FUNCTIONS: Record<string, BasicFunction>;
382
+ /** True when the basic function `name` must run from a user gesture. */
383
+ declare function requiresUserActivation(name: string): boolean;
384
+ /** True when a basic function gives a ValidationResult. */
385
+ declare function givesValidationResult(name: string): boolean;
386
+ //#endregion
387
+ //#region src/generative-ui/markdown-source.d.ts
388
+ /** What renders in place of one ```a2ui fence, in order. */
389
+ type MarkdownFenceBlock = {
390
+ kind: "markdown";
391
+ markdown: string;
392
+ } | {
393
+ kind: "surface";
394
+ surfaceId: string;
395
+ };
396
+ /** The part of a generative UI that the markdown source reads. */
397
+ type MarkdownSourceUI = Pick<GenerativeUI, "id" | "manifestComponents">;
398
+ interface BuildMarkdownSurfacesOptions {
399
+ ui: MarkdownSourceUI;
400
+ /** The declared functions. A `functionCall` must name one of them. */
401
+ functions: Record<string, GenerativeUIFunctionManifest>;
402
+ /**
403
+ * The last message can still grow. Then an open fence in it is still
404
+ * streaming: its last, unfinished operation is left out, and the surface
405
+ * it creates has the status "streaming". Else an open fence is final.
406
+ */
407
+ running: boolean;
408
+ /**
409
+ * The results of the earlier builds of the same thread. A build then
410
+ * parses only the fences that changed, and builds only the surfaces whose
411
+ * operations changed. Left out, everything is built again.
412
+ */
413
+ cache?: MarkdownBuildCache;
414
+ }
415
+ /**
416
+ * Values by key, from the latest build. A value that a build does not use
417
+ * is dropped at the end of that build, so the cache does not grow.
418
+ */
419
+ declare class BuildMemo<V> {
420
+ private previous;
421
+ private current;
422
+ /**
423
+ * The value of `key`. It is computed when no earlier value is there, or
424
+ * when `isFresh` says that the earlier value is out of date.
425
+ */
426
+ get(key: string, compute: () => V, isFresh?: (value: V) => boolean): V;
427
+ endBuild(): void;
428
+ }
429
+ /** The surfaces that one draft gives, and the operations it was built from. */
430
+ interface BuiltDraft {
431
+ operations: A2UIMarkdownOperation[];
432
+ target: string;
433
+ streaming: boolean;
434
+ parts: SurfacePart[];
435
+ contents: GenerativeUISurfaceContent[];
436
+ }
437
+ /** The results of the builds of one thread. See `BuildMarkdownSurfacesOptions.cache`. */
438
+ declare class MarkdownBuildCache {
439
+ readonly segments: BuildMemo<MarkdownSegment[]>;
440
+ readonly fences: BuildMemo<{
441
+ operations: A2UIMarkdownOperation[];
442
+ functionCalls: A2UIMarkdownOperation[];
443
+ }>;
444
+ readonly drafts: BuildMemo<BuiltDraft>;
445
+ /** The copies of an operation for other surface ids, by operation. */
446
+ readonly readdressed: WeakMap<object, Map<string, A2UIMarkdownOperation>>;
447
+ endBuild(): void;
448
+ }
449
+ /** The surface content, or one surface of it after the prose lift. */
450
+ type SurfacePart = {
451
+ kind: "markdown";
452
+ markdown: string;
453
+ } | {
454
+ kind: "surface";
455
+ surfaceId: string;
456
+ operations: A2UIMarkdownOperation[];
457
+ };
458
+ /** The key of one fence of one message. */
459
+ declare function fenceKey(messageId: string, fenceIndex: number): string;
460
+ /** One `callRendererFunction` line of a fence, in the order of the fences. */
461
+ interface MarkdownFunctionCall {
462
+ messageId: string;
463
+ fenceIndex: number;
464
+ /** The operation as the model wrote it. It is not validated yet. */
465
+ operation: A2UIMarkdownOperation;
466
+ }
467
+ /**
468
+ * Builds the surfaces of a thread from the ```a2ui fences of its assistant
469
+ * messages, in message order.
470
+ *
471
+ * - Operations are grouped by surfaceId across all messages. An operation
472
+ * with no surfaceId goes to the first surface of its fence, else to
473
+ * `<messageId>-<fenceIndex>`.
474
+ * - The fence that first writes a surface creates it. The `target=<id>` of
475
+ * that fence sets the target. With no target, the surface goes to the
476
+ * chat.
477
+ * - A later fence of the same reply for the same surfaceId updates it. A
478
+ * later reply that reuses the id of a chat surface gets a surface of its
479
+ * own, `<id>@<messageId>`. A page target is updated from any reply.
480
+ * - The status is "streaming" while the creating fence streams, else
481
+ * "ready".
482
+ * - Each operation is validated with `validateOperation`. Rejected ones are
483
+ * left out and listed in `rejected`.
484
+ * - Chat surfaces get the prose lift: informational cards lose their box,
485
+ * and prose becomes markdown that renders between sub-surfaces
486
+ * (`<surfaceId>#<n>`). An inline createSurface is split into its
487
+ * createSurface, updateDataModel and updateComponents first.
488
+ * - A `callRendererFunction` line is not part of a surface. It goes to
489
+ * `functionCalls`. A streaming line gives nothing, so a function never
490
+ * runs with a part of its args.
491
+ *
492
+ * The function is pure. Call it again on each stream update. The manager
493
+ * applies only the new operations, so unchanged surfaces do not render
494
+ * again.
495
+ *
496
+ * @param messages - The messages of one thread.
497
+ * @param options - The generative UI, its declared functions, and whether
498
+ * the last message can still grow.
499
+ * @returns `surfaces`, one content for each surface and sub-surface;
500
+ * `fences`, the blocks that each fence renders, by `fenceKey` (a fence
501
+ * that is not in `fences` renders nothing); `functionCalls`, the function
502
+ * calls of the fences in order; and `parts`, the surface ids of the parts
503
+ * of each surface, by surface id.
504
+ *
505
+ * @example
506
+ * ```ts
507
+ * const { surfaces } = buildMarkdownSurfaces(agent.messages, {
508
+ * ui,
509
+ * functions: {},
510
+ * running: agent.isRunning,
511
+ * });
512
+ * for (const content of surfaces) manager.ingest(threadId, agentId, content);
513
+ * ```
514
+ */
515
+ declare function buildMarkdownSurfaces(messages: readonly Message[], options: BuildMarkdownSurfacesOptions): {
516
+ surfaces: GenerativeUISurfaceContent[];
517
+ fences: Map<string, MarkdownFenceBlock[]>;
518
+ functionCalls: MarkdownFunctionCall[];
519
+ parts: Map<string, string[]>;
520
+ };
521
+ /**
522
+ * The markdown transport source of one surface manager. It turns the
523
+ * messages of a thread into surfaces in the manager, and keeps the blocks
524
+ * that each fence renders.
525
+ */
526
+ declare class MarkdownSurfaceSource {
527
+ private readonly manager;
528
+ private readonly ui;
529
+ private readonly functions;
530
+ /** By thread: the blocks of each fence, from the latest sync. */
531
+ private readonly fences;
532
+ /** By thread, then surface: the operations last ingested, as JSON. */
533
+ private readonly ingested;
534
+ /** By thread, then surface: the content last ingested. */
535
+ private readonly contents;
536
+ /** By thread: the results of the earlier builds. */
537
+ private readonly caches;
538
+ constructor(manager: GenerativeUISurfaceManager, ui: GenerativeUI);
539
+ /**
540
+ * Builds the surfaces of `threadId` from `messages` and gives them to the
541
+ * manager. A surface that an earlier sync of the thread made, and that the
542
+ * messages no longer write, is deleted. Other threads do not change.
543
+ *
544
+ * @param threadId - The thread of the messages.
545
+ * @param agentId - The agent that owns the thread.
546
+ * @param messages - All messages of the thread.
547
+ * @param options - `running`: the last message can still grow.
548
+ * @returns The function calls of the fences, in order. The source does
549
+ * not run them.
550
+ */
551
+ sync(threadId: string, agentId: string | undefined, messages: readonly Message[], options: {
552
+ running: boolean;
553
+ }): MarkdownFunctionCall[];
554
+ /**
555
+ * The blocks that a fence renders in the chat, from the latest sync of the
556
+ * thread. `undefined` when the fence renders nothing: it updates a surface
557
+ * of an earlier fence, its surface is for a named target, or it has no
558
+ * complete operation yet.
559
+ */
560
+ getFenceBlocks(threadId: string, messageId: string, fenceIndex: number): MarkdownFenceBlock[] | undefined;
561
+ }
562
+ /**
563
+ * The markdown source of a generative UI runtime. There is one source for
564
+ * each surface manager. The root syncs it, and the chat messages read the
565
+ * fence blocks from it.
566
+ */
567
+ declare function getMarkdownSurfaceSource(runtime: {
568
+ manager: GenerativeUISurfaceManager;
569
+ ui: GenerativeUI;
570
+ }): MarkdownSurfaceSource;
571
+ //#endregion
572
+ //#region src/generative-ui/function-calls.d.ts
573
+ type ReadonlyMessages = ReadonlyArray<Readonly<Message>>;
574
+ /** One agent-called function, as the model sent it. */
575
+ interface FunctionCallRequest {
576
+ functionCallId: string;
577
+ /** A `callRendererFunction` operation. It is not validated yet. */
578
+ operation: unknown;
579
+ }
580
+ /** The function calls of the tool transport: its function-call activities. */
581
+ declare function activityFunctionCalls(messages: ReadonlyMessages): FunctionCallRequest[];
582
+ /** The function calls of the markdown transport: its fence lines. */
583
+ declare function markdownFunctionCalls(calls: MarkdownFunctionCall[]): FunctionCallRequest[];
584
+ interface FunctionCallRunnerOptions {
585
+ /** Starts the follow-up runs. A framework's core subclass fits. */
586
+ core: Pick<CopilotKitCore, "runAgent">;
587
+ dispatcher: GenerativeUIDispatcher;
588
+ manifest: ValidateOperationOptions["manifest"];
589
+ /**
590
+ * Lets the app apply the state that the handlers set before the follow-up
591
+ * run reads it: React commits its pending updates, Angular runs a change
592
+ * detection tick.
593
+ */
594
+ settle: () => Promise<void>;
595
+ /** Gets a failed follow-up run. Development only. */
596
+ warn: (message: string, error: unknown) => void;
597
+ }
598
+ interface FunctionCallRunner {
599
+ /**
600
+ * Runs the calls of the thread of `agent` that did not run yet. When no
601
+ * run goes on, it also sends the pending answers.
602
+ *
603
+ * @param agent - The agent of the thread.
604
+ * @param requests - The function calls in the messages, in order.
605
+ * @param messages - All messages of the thread.
606
+ * @param running - A run goes on or starts now. The answers wait.
607
+ */
608
+ run(agent: AbstractAgent, requests: FunctionCallRequest[], messages: ReadonlyMessages, running: boolean): void;
609
+ }
610
+ /**
611
+ * Runs the functions that the agent calls with `callRendererFunction`, for
612
+ * both transports, and answers each call.
613
+ *
614
+ * - Each `functionCallId` runs once for each thread. A replay, a sync of
615
+ * the same messages again, or a call that already has an answer message
616
+ * does not run it again.
617
+ * - The answer is a hidden developer message with a `rendererFunctionResponse`.
618
+ * The answers go to the agent only when it is not running. Then one
619
+ * follow-up run starts for all of them.
620
+ * - A user turn has at most {@link MAX_FUNCTION_FOLLOW_UPS} follow-up runs.
621
+ * A call after that does not run. It gets a `follow_up_limit` error and
622
+ * starts no follow-up run.
623
+ */
624
+ declare function createFunctionCallRunner(options: FunctionCallRunnerOptions): FunctionCallRunner;
625
+ //#endregion
626
+ //#region src/generative-ui/calc.d.ts
627
+ /**
628
+ * The two CopilotKit value functions that A2UI 1.0 lacks: `calc`, an
629
+ * arithmetic expression over named args, and `series`, a computed list.
630
+ * Both are catalog functions in the sense of the spec: a catalog may
631
+ * declare functions beyond the basic ones, and the model learns them from
632
+ * the schema. The expression language is small and closed: numbers,
633
+ * strings, booleans, the args by name, `+ - * / %`, `^` (power),
634
+ * comparisons, `&& || !`, `cond ? a : b`, parentheses, min, max, round,
635
+ * floor, ceil, abs, pow, sqrt, exp, ln (also log), log10, and the
636
+ * constants pi and e. No property access, no assignment, no code.
637
+ */
638
+ type Value = number | string | boolean | null;
639
+ type CalcScope = Readonly<Record<string, unknown>>;
640
+ /**
641
+ * Evaluates `expression` with the names in `scope`. Gives a number, a
642
+ * string, a boolean or null. Throws an {@link ExpressionError} for a bad
643
+ * expression or a missing name.
644
+ */
645
+ declare function evaluateCalc(expression: unknown, scope: CalcScope): Value;
646
+ /** The `calc` function: the expression is `args.expression`, the rest is the scope. */
647
+ declare function calc(args: Record<string, unknown>): Value;
648
+ /**
649
+ * The `series` function: `count` copies of `item`, with the loop variable
650
+ * (`variable`, default "i") counting from `start` (default 1) and the other
651
+ * args in scope of the `${...}` expressions of the item.
652
+ */
653
+ declare function series(args: Record<string, unknown>): unknown[];
654
+ //#endregion
655
+ //#region src/generative-ui/resolve.d.ts
656
+ /**
657
+ * Resolves the dynamic values of A2UI 1.0 in a prop, an event context, or
658
+ * a function argument: `{"@path"}` bindings read the data model,
659
+ * `{"@call"}` values run a basic function, and `formatString` interpolates
660
+ * `${...}` expressions. Objects and arrays are walked, so a binding can sit
661
+ * at any depth. A value with nothing dynamic in it keeps its identity.
662
+ */
663
+ /** Reads the data model. The surface data model of web_core fits. */
664
+ interface DataReader {
665
+ get(path: string): unknown;
666
+ }
667
+ interface ResolveContext {
668
+ data: DataReader;
669
+ /**
670
+ * The data model path of the template item this value belongs to, or
671
+ * `undefined` outside of a template. Relative paths resolve against it.
672
+ */
673
+ basePath: string | undefined;
674
+ }
675
+ interface Resolved<T = unknown> {
676
+ value: T;
677
+ /** The absolute data model paths that the value read. */
678
+ paths: Set<string>;
679
+ }
680
+ /** Adds one segment to a JSON pointer: ("/items", "0") gives "/items/0". */
681
+ declare function joinPath(base: string, segment: string): string;
682
+ /**
683
+ * The absolute data model path of a binding. A path without a leading "/"
684
+ * is relative to the current template item, or to the root outside of one.
685
+ */
686
+ declare function resolvePath(path: string, basePath: string | undefined): string;
687
+ /**
688
+ * The index of the template item at `basePath`: its last segment.
689
+ * `undefined` outside of a template.
690
+ */
691
+ declare function templateIndex(basePath: string | undefined): number | undefined;
692
+ /**
693
+ * Resolves one dynamic value: the value with every binding and function
694
+ * call replaced, plus the data model paths it read. Throws an
695
+ * {@link ExpressionError} for a bad function call.
696
+ */
697
+ /** The options of a resolution. */
698
+ interface ResolveOptions {
699
+ /** Keep every validator result as an object. */
700
+ keepValidation?: boolean;
701
+ /**
702
+ * True when `value` is the `checks` prop of a component: the condition
703
+ * of each check then keeps its validator result as an object.
704
+ */
705
+ isChecks?: boolean;
706
+ }
707
+ declare function resolveDynamicValue<T = unknown>(value: unknown, context: ResolveContext, options?: ResolveOptions): Resolved<T>;
708
+ type ResolveAttempt<T = unknown> = ({
709
+ ok: true;
710
+ } & Resolved<T>) | {
711
+ ok: false;
712
+ error: Error; /** The paths read before the failure. A change there may fix it. */
713
+ paths: Set<string>;
714
+ };
715
+ /**
716
+ * Like {@link resolveDynamicValue}, but a failure comes back as a result
717
+ * with the paths read so far, so the caller can keep watching them: a
718
+ * function that fails on an empty field works once the user fills it.
719
+ */
720
+ declare function tryResolveDynamicValue<T = unknown>(value: unknown, context: ResolveContext, options?: ResolveOptions): ResolveAttempt<T>;
721
+ /** True when `value` holds a `{"@path"}` or `{"@call"}` at any depth. */
722
+ declare function containsDynamicValue(value: unknown): boolean;
723
+ //#endregion
724
+ //#region src/generative-ui/events.d.ts
725
+ /** One call of an event prop by a component. */
726
+ interface EventCall {
727
+ runtime: GenerativeUIEngine;
728
+ surface: ManagedSurface;
729
+ componentId: string;
730
+ /** The event prop name, for error messages. */
731
+ name: string;
732
+ /**
733
+ * The event `parameters`. When absent, the args go on unchecked. That is
734
+ * the case for a matched event without `parameters`: the function schema
735
+ * checks them.
736
+ */
737
+ parameters?: GenerativeUISchema;
738
+ args: unknown;
739
+ }
740
+ /**
741
+ * Runs one call of an event that the model bound: validates the component's
742
+ * args, merges them with the args from the binding (binding literals win),
743
+ * then calls a declared function or forwards an agent event. Never throws.
744
+ */
745
+ declare function invokeBoundEvent(params: EventCall & {
746
+ binding: GenerativeUIActionBinding; /** The template item path of the component, for relative paths. */
747
+ basePath: string | undefined;
748
+ }): Promise<GenerativeUIInvokeResult>;
749
+ /**
750
+ * Runs one call of an event that matches a declared function: validates the
751
+ * component's args with the event `parameters` (if any), then calls the
752
+ * function, which validates them with its own schema. Never throws.
753
+ */
754
+ declare function invokeMatchedEvent(params: EventCall & {
755
+ functionName: string;
756
+ }): Promise<GenerativeUIInvokeResult>;
757
+ //#endregion
758
+ //#region src/generative-ui/manifest.d.ts
759
+ /**
760
+ * The built-in functions (the A2UI basic catalog plus calc and series) as
761
+ * manifest entries. Their args are described by the short signature, not
762
+ * by a full JSON Schema: the renderer checks them when they run. An app
763
+ * function of the same name replaces the entry.
764
+ */
765
+ declare function builtInFunctionManifests(): Record<string, GenerativeUIFunctionManifest>;
766
+ /** What `buildCatalogManifest` adds to the catalog. */
767
+ interface CatalogManifestOptions {
768
+ /** The app functions with a mounted handler. A built-in of the same name is left out. */
769
+ functions?: Record<string, GenerativeUIFunctionManifest>;
770
+ /** The inline targets, after the chat target. */
771
+ targets?: GenerativeUITarget[];
772
+ /** The surfaces of the thread. */
773
+ surfaces?: Record<string, GenerativeUISurfaceSummary>;
774
+ }
775
+ /**
776
+ * The manifest of a catalog, with no React runtime: the components of `ui`,
777
+ * the built-in functions (minus the names the app declares) and
778
+ * `options.functions`, the chat target and `options.targets`, and
779
+ * `options.surfaces`. `buildGenerativeUIManifest` builds the per-run
780
+ * manifest with it; tools that run outside React use it directly.
781
+ *
782
+ * @example
783
+ * ```ts
784
+ * const manifest = buildCatalogManifest(standardUI);
785
+ * manifest.targets; // [{ id: "chat", kind: "chat" }]
786
+ * ```
787
+ */
788
+ declare function buildCatalogManifest(ui: Pick<GenerativeUI, "id" | "manifestComponents" | "functions">, options?: CatalogManifestOptions): GenerativeUIManifest;
789
+ /**
790
+ * Builds the per-run manifest. Never contains handlers or renderers.
791
+ *
792
+ * - `functions`: the built-in functions, then the declared functions with
793
+ * exactly one mounted handler.
794
+ * - `targets`: the chat first, then each mounted `<GenerativeUISurface>`,
795
+ * with its `description` and its `components` when it has them.
796
+ */
797
+ declare function buildGenerativeUIManifest(runtime: Pick<GenerativeUIEngine, "ui" | "manager" | "dispatcher">, threadId: string | undefined): GenerativeUIManifest;
798
+ /** How to build the envelope of one run. */
799
+ interface GenerativeUIEnvelopeOptions {
800
+ transport: CopilotKitUIEnvelope["metadata"]["extensions"]["copilotkit_transport"];
801
+ /**
802
+ * Send the component schemas. The tool transport always sends them,
803
+ * because the runtime validates operations with them.
804
+ */
805
+ includeCatalog: boolean;
806
+ /** True when the client also sends the guide as context entries. */
807
+ contextSent: boolean;
808
+ /**
809
+ * The markdown guideline. Left out, the markdown transport builds it from
810
+ * the manifest, with only the rule groups that the manifest uses. The
811
+ * tool transport sends none.
812
+ */
813
+ instructions?: string;
814
+ /** The user action that starts this run, when one does. */
815
+ action?: A2UIActionMessage;
816
+ }
817
+ /** The transport options of a framework's generative UI config. */
818
+ interface GenerativeUITransportConfig {
819
+ transport?: "tool" | "markdown";
820
+ /** Markdown only. Default `true`. */
821
+ sendContext?: boolean;
822
+ /** Markdown only. Default `true`. */
823
+ includeCatalog?: boolean;
824
+ }
825
+ /** What the envelope of a run says, from the provider config. */
826
+ declare function envelopeOptionsFor(config: GenerativeUITransportConfig): GenerativeUIEnvelopeOptions;
827
+ /**
828
+ * Builds the envelope that a run sends as `forwardedProps.copilotkit.ui`,
829
+ * from the per-run manifest. It has the A2UI v1.0 renderer capabilities
830
+ * shape: one inline catalog with the id of the UI, and the CopilotKit data
831
+ * in `metadata.extensions`.
832
+ *
833
+ * The inline catalog has no `components` only for the markdown transport
834
+ * with `includeCatalog: false`. It has `instructions` for the markdown
835
+ * transport, or when given.
836
+ *
837
+ * @param runtime - The generative UI runtime of the provider.
838
+ * @param threadId - The thread of the run. Its surfaces go in `copilotkit_surfaces`.
839
+ * @param options - The transport and what to send.
840
+ *
841
+ * @example
842
+ * ```ts
843
+ * const envelope = buildGenerativeUIEnvelope(runtime, agent.threadId, {
844
+ * transport: "tool",
845
+ * includeCatalog: true,
846
+ * contextSent: false,
847
+ * });
848
+ * envelope["1.0"].supportedCatalogIds; // [runtime.ui.id]
849
+ * ```
850
+ */
851
+ declare function buildGenerativeUIEnvelope(runtime: Pick<GenerativeUIEngine, "ui" | "manager" | "dispatcher">, threadId: string | undefined, options: GenerativeUIEnvelopeOptions): CopilotKitUIEnvelope;
852
+ //#endregion
853
+ //#region src/generative-ui/action-message.d.ts
854
+ /**
855
+ * Turns a user event that no function handles into the text of a visible
856
+ * user message.
857
+ *
858
+ * The first line is, in order: `userMessage`, `context.message`,
859
+ * `context.label`, the label of the source component (from `resolveLabel`),
860
+ * or the event name made readable (`choose_plan` becomes "Choose plan").
861
+ * Each other context field follows as one `key: value` line. Objects are
862
+ * written as JSON. `null` and `undefined` fields are skipped.
863
+ *
864
+ * @param event - The user event, as sent by a surface.
865
+ * @param resolveLabel - Finds the visible label of a component by id. Build
866
+ * one with {@link createComponentLabelResolver}.
867
+ *
868
+ * @example
869
+ * ```ts
870
+ * buildActionMessageText({
871
+ * name: "choose_plan",
872
+ * surfaceId: "plans",
873
+ * componentId: "team-button",
874
+ * userMessage: "I pick the Team plan",
875
+ * context: { seats: 12 },
876
+ * });
877
+ * // "I pick the Team plan\n\nseats: 12"
878
+ * ```
879
+ */
880
+ declare function buildActionMessageText(event: GenerativeUIUserEvent, resolveLabel?: (componentId: string) => string | undefined): string;
881
+ /**
882
+ * Builds a function that finds the visible label of a component on a surface.
883
+ *
884
+ * The label is the component's own string `label`, else its string `text`,
885
+ * else the first `child` or `children` component that has a string `label`
886
+ * or `text`. When a component id is defined more than once, the last
887
+ * definition wins, as in the renderer.
888
+ *
889
+ * @param operations - The committed operations of the surface.
890
+ *
891
+ * @example
892
+ * ```ts
893
+ * const resolveLabel = createComponentLabelResolver(surface.operations);
894
+ * buildActionMessageText(event, resolveLabel);
895
+ * ```
896
+ */
897
+ declare function createComponentLabelResolver(operations: readonly A2UIOperation[]): (componentId: string) => string | undefined;
898
+ /**
899
+ * The label resolver of a rendered surface: the components the surface has
900
+ * now, as one `updateComponents` operation, so that the label of the
901
+ * component that sent an event can be found.
902
+ */
903
+ declare function surfaceLabelResolver(surface: ManagedSurface): (componentId: string) => string | undefined;
904
+ //#endregion
905
+ //#region src/generative-ui/debug-source.d.ts
906
+ type RuntimeParts = Pick<GenerativeUIEngine, "ui" | "manager" | "dispatcher">;
907
+ /**
908
+ * What a run of `threadId` sends: its envelope, and the text that goes into
909
+ * the prompt of the model because of it.
910
+ *
911
+ * - Tool transport: the runtime adds the `render_ui` guide. It builds it
912
+ * from the envelope with `buildGenerativeUIPrompt`, as done here.
913
+ * - Markdown transport: the provider sends the guideline and the compact
914
+ * schema as context entries. With `sendContext: false`, the backend builds
915
+ * its own prompt, usually from the `instructions` of the envelope.
916
+ */
917
+ declare function describeGenerativeUIRun(runtime: RuntimeParts, threadId: string | undefined, options: GenerativeUIEnvelopeOptions): Pick<ɵGenerativeUIDebugRun, "envelope" | "prompt">;
918
+ /**
919
+ * The debug source that the provider gives core for the inspector. It builds
920
+ * a snapshot only when the inspector reads one.
921
+ *
922
+ * @param runtime - The generative UI parts of the provider.
923
+ * @param getOptions - The envelope options and agent ids of the current config.
924
+ * @returns The source, and `recordRun` for each run start.
925
+ */
926
+ declare function createGenerativeUIDebugSource(runtime: RuntimeParts, getOptions: () => {
927
+ options: GenerativeUIEnvelopeOptions;
928
+ agentIds: string[] | undefined;
929
+ }): {
930
+ source: ɵGenerativeUIDebugSource; /** Keeps what a run sent, so the inspector can show it. */
931
+ recordRun(run: ɵGenerativeUIDebugRun): void;
932
+ };
933
+ //#endregion
934
+ //#region src/generative-ui/accessibility.d.ts
935
+ /**
936
+ * The `accessibility` of the A2UI 1.0 component envelope, with its dynamic
937
+ * values resolved. Every component may carry it next to `id` and
938
+ * `component`; it is not a prop of the component.
939
+ */
940
+ interface GenerativeUIAccessibility {
941
+ /** A short name for assistive technologies, 1 to 3 words. */
942
+ label?: string;
943
+ /** Instructions, format requirements, or what an action does. */
944
+ description?: string;
945
+ /** How screen readers announce changes (WAI-ARIA `aria-live`). */
946
+ live?: "off" | "polite" | "assertive";
947
+ /** True hides the component and its children from assistive technologies. */
948
+ hidden?: boolean;
949
+ }
950
+ /** The ARIA attributes of a resolved `accessibility`, ready to spread. */
951
+ interface GenerativeUIAriaAttributes {
952
+ "aria-label"?: string;
953
+ "aria-description"?: string;
954
+ "aria-live"?: "off" | "polite" | "assertive";
955
+ "aria-hidden"?: true;
956
+ }
957
+ /**
958
+ * The accessibility of a component from its resolved `accessibility`
959
+ * value. Fields of the wrong type are left out: a label that is still a
960
+ * binding, or a list, names nothing.
961
+ */
962
+ declare function readAccessibility(value: unknown): GenerativeUIAccessibility | undefined;
963
+ /**
964
+ * The ARIA attributes for an `accessibility`. `live: "off"` is written out:
965
+ * a region inherits the live setting of its ancestors, and a `status` role
966
+ * is live on its own, so only the explicit value silences it.
967
+ *
968
+ * @example
969
+ * ```ts
970
+ * accessibilityAttributes({ label: "Totals", live: "polite" });
971
+ * // { "aria-label": "Totals", "aria-live": "polite" }
972
+ * ```
973
+ */
974
+ declare function accessibilityAttributes(accessibility: GenerativeUIAccessibility | undefined): GenerativeUIAriaAttributes;
975
+ /**
976
+ * The role of a container that the envelope names. A generic element
977
+ * cannot carry a name, so a label or a description makes it a `group`,
978
+ * unless the component has a role of its own.
979
+ */
980
+ declare function namedRole(aria: GenerativeUIAriaAttributes, explicit: string | undefined): string | undefined;
981
+ /**
982
+ * The part of the attributes for the focusable control of a labelled pair:
983
+ * its name and its description. ARIA names are not inherited, so the
984
+ * wrapper of a control cannot name it.
985
+ */
986
+ declare function controlAria(aria: GenerativeUIAriaAttributes): Pick<GenerativeUIAriaAttributes, "aria-label" | "aria-description">;
987
+ /**
988
+ * The part of the attributes for the wrapper around a control: hidden and
989
+ * live cover the label and the control together.
990
+ */
991
+ declare function wrapperAria(aria: GenerativeUIAriaAttributes): Pick<GenerativeUIAriaAttributes, "aria-hidden" | "aria-live">;
992
+ //#endregion
993
+ //#region src/generative-ui/targets.d.ts
994
+ /** Scrolls `element` into view, unless it is already fully on screen. */
995
+ declare function scrollToSurface(element: HTMLElement): void;
996
+ /**
997
+ * The names of `requested` that `ui` has, without repeats, at most the
998
+ * number that the envelope takes. `warning` tells what was dropped.
999
+ */
1000
+ declare function allowedComponents(requested: readonly string[], ui: GenerativeUI): {
1001
+ names: string[];
1002
+ warning: string;
1003
+ };
1004
+ //#endregion
1005
+ //#region src/generative-ui/activity-content.d.ts
1006
+ /**
1007
+ * The content of a generative UI surface activity message. A missing
1008
+ * `rejected` reads as []. Extra keys of the content are kept.
1009
+ */
1010
+ declare const GenerativeUISurfaceContentSchema: z.ZodObject<{
1011
+ surfaceId: z.ZodString;
1012
+ target: z.ZodString;
1013
+ catalogId: z.ZodString;
1014
+ operations: z.ZodArray<z.ZodAny>;
1015
+ status: z.ZodEnum<{
1016
+ error: "error";
1017
+ streaming: "streaming";
1018
+ ready: "ready";
1019
+ }>;
1020
+ rejected: z.ZodDefault<z.ZodArray<z.ZodObject<{
1021
+ index: z.ZodNumber;
1022
+ reason: z.ZodString;
1023
+ }, z.core.$strip>>>;
1024
+ }, z.core.$loose>;
1025
+ /** The content of a surface activity message, or the issues that make it malformed. */
1026
+ type ParsedGenerativeUISurfaceContent = {
1027
+ content: GenerativeUISurfaceContent;
1028
+ issues?: undefined;
1029
+ } | {
1030
+ content?: undefined;
1031
+ issues: string[];
1032
+ };
1033
+ /**
1034
+ * Reads the content of a surface activity message with
1035
+ * {@link GenerativeUISurfaceContentSchema}, or lists its issues (as
1036
+ * `path: message`) when it is malformed. Never throws.
1037
+ */
1038
+ declare function parseGenerativeUISurfaceContent(content: unknown): ParsedGenerativeUISurfaceContent;
1039
+ //#endregion
1040
+ export { BASIC_FUNCTIONS, BasicFunction, BuildMarkdownSurfacesOptions, CalcScope, CatalogManifestOptions, DataReader, ExpressionError, FunctionCallRequest, FunctionCallRunner, FunctionCallRunnerOptions, GenerativeUIAccessibility, GenerativeUIAriaAttributes, GenerativeUICallOrigin, GenerativeUIDeclaredFunction, GenerativeUIDispatcher, GenerativeUIDispatcherOptions, GenerativeUIEngine, GenerativeUIEnvelopeOptions, GenerativeUIHandlerRef, GenerativeUIInvocationOrigin, GenerativeUIMountedTarget, GenerativeUISurfaceContentSchema, GenerativeUISurfaceManager, GenerativeUISurfaceManagerOptions, GenerativeUITargetOptions, GenerativeUITransportConfig, ManagedSurface, MarkdownBuildCache, MarkdownFenceBlock, MarkdownFunctionCall, MarkdownSurfaceSource, ParsedGenerativeUISurfaceContent, PlatformError, ReadonlyMessages, ResolveAttempt, ResolveContext, ResolveOptions, Resolved, accessibilityAttributes, activityFunctionCalls, allowedComponents, buildActionMessageText, buildCatalogManifest, buildGenerativeUIEnvelope, buildGenerativeUIManifest, buildMarkdownSurfaces, builtInFunctionManifests, calc, containsDynamicValue, controlAria, createComponentLabelResolver, createFunctionCallRunner, createGenerativeUIDebugSource, createGenerativeUIDispatcher, describeGenerativeUIRun, envelopeOptionsFor, evaluateCalc, fenceKey, getMarkdownSurfaceSource, givesValidationResult, invokeBoundEvent, invokeMatchedEvent, joinPath, markdownFunctionCalls, namedRole, openUrlSafely, parseGenerativeUISurfaceContent, readAccessibility, reportErrorSafely, requiresUserActivation, resolveDynamicValue, resolvePath, scrollToSurface, series, surfaceKey, surfaceLabelResolver, templateIndex, truthOf, tryResolveDynamicValue, wrapperAria };
1041
+ //# sourceMappingURL=index.d.cts.map