@zeyos/zx 5.6.0 → 5.7.1

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 (227) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +41 -7
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
@@ -0,0 +1,260 @@
1
+ /** The version a `begin` operation and a document carry. */
2
+ export declare const SURFACE_VERSION = "surface/1";
3
+ /** The version every reply carries. */
4
+ export declare const REPLY_VERSION = "reply/1";
5
+ /** The limits of one surface. Anything over a limit is dropped and reported. */
6
+ export declare const LIMITS: Readonly<{
7
+ /** Nodes per surface. */
8
+ nodes: 400;
9
+ /** Depth of the node tree, counting the root's children as 1. */
10
+ depth: 12;
11
+ /** Characters per string. */
12
+ string: 20000;
13
+ /** Rows per table or diff, and entries per list or other array. */
14
+ rows: 1000;
15
+ /** Input schema properties per surface. */
16
+ fields: 50;
17
+ /** Choices per choice node or schema property. */
18
+ choices: 64;
19
+ /** Actions per surface. */
20
+ actions: 8;
21
+ /** Characters of the surface's data, written as JSON. */
22
+ data: 1000000;
23
+ /** Nesting of a `visible`, `when` or `if` condition. */
24
+ condition: 4;
25
+ /** Nesting of any JSON value inside one operation, counting the operation as 1. */
26
+ value: 32;
27
+ /** Columns per table. */
28
+ columns: 50;
29
+ /** Table cells across all tables of a surface; a `$data` binding counts each time it is used. */
30
+ cells: 100000;
31
+ /** Datasets per chart. */
32
+ datasets: 12;
33
+ /** Steps per questionnaire. */
34
+ steps: 50;
35
+ /** Sources per surface. */
36
+ sources: 50;
37
+ /** Characters of a title, label or other short text. */
38
+ label: 200;
39
+ /** Characters of a description. */
40
+ description: 2000;
41
+ /** Characters of an id, a name, an author or a tool. */
42
+ name: 64;
43
+ /** Characters of a link address. */
44
+ href: 2000;
45
+ }>;
46
+ /** The six intents, in the order the guide presents them. */
47
+ export declare const INTENTS: readonly SurfaceIntent[];
48
+ /** Where a surface asks to be placed. */
49
+ export declare const PLACEMENTS: readonly SurfacePlacement[];
50
+ /** Action ids kept for closing a surface. An action of the surface's own cannot use them. */
51
+ export declare const RESERVED_ACTIONS: readonly string[];
52
+ /** What an id looks like: a node, an action, a row or a surface. Never `constructor` or `prototype`. */
53
+ export declare const ID_PATTERN = "^(?!(?:constructor|prototype)$)[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$";
54
+ /**
55
+ * What an input name, a column id, a row key or a step name looks like: it becomes a key of the
56
+ * reply's `values` or of a row, so `__proto__`, `constructor` and `prototype` are excluded.
57
+ */
58
+ export declare const NAME_PATTERN = "^(?!(?:__proto__|constructor|prototype)$)[A-Za-z_][A-Za-z0-9_.-]{0,63}$";
59
+ /**
60
+ * What a link address looks like: `https://` in lower case, a host without credentials, and no
61
+ * whitespace, control, backslash or invisible format characters anywhere. The validator applies
62
+ * the same pattern, then parses the address.
63
+ */
64
+ export declare const HREF_PATTERN: string;
65
+ /** What an icon name looks like. */
66
+ export declare const ICON_PATTERN = "^[a-z0-9][a-z0-9-]{0,39}$";
67
+ /** Keys refused anywhere, at any depth. */
68
+ export declare const FORBIDDEN_KEYS: readonly string[];
69
+ export type SurfaceIntent = 'show' | 'ask' | 'choose' | 'confirm' | 'review' | 'questionnaire';
70
+ export type SurfacePlacement = 'inline' | 'sheet' | 'dialog';
71
+ export type CatalogType = 'string' | 'integer' | 'number' | 'boolean' | 'number|string' | 'string[]' | 'Href' | 'Ref' | 'Column[]' | 'Row[]' | 'Figure[]' | 'ChartData' | 'Choice[]' | 'DiffRow[]' | 'Schema' | 'Step[]';
72
+ export type CatalogProp = {
73
+ /**
74
+ * What the value is.
75
+ */
76
+ type: CatalogType;
77
+ /**
78
+ * The values allowed.
79
+ */
80
+ enum?: ReadonlyArray<string | number>;
81
+ /**
82
+ * Most characters of a string, or entries of a list.
83
+ */
84
+ max?: number;
85
+ /**
86
+ * Whether the node needs it to render.
87
+ */
88
+ required?: boolean;
89
+ /**
90
+ * The component option the property maps to: an option name, or
91
+ * `<option>[].<member>` for a member of a list option's entries. `null` when the surface itself
92
+ * consumes it (an input's `name`, a link's text and address).
93
+ */
94
+ option: string | null;
95
+ };
96
+ export type CatalogNode = {
97
+ /**
98
+ * The node type.
99
+ */
100
+ type: string;
101
+ /**
102
+ * The component that draws it, as `docs/api.json` names it;
103
+ * `null` for a node the surface draws itself.
104
+ */
105
+ component: string | null;
106
+ /**
107
+ * The one intent the node may appear in.
108
+ */
109
+ intentOnly?: SurfaceIntent;
110
+ /**
111
+ * Whether it lays out `children`.
112
+ */
113
+ children: boolean;
114
+ /**
115
+ * Whether its value lands in the reply's `values`.
116
+ */
117
+ input: boolean;
118
+ /**
119
+ * Its properties.
120
+ */
121
+ props: Readonly<Record<string, CatalogProp>>;
122
+ };
123
+ export type CatalogIntent = {
124
+ /**
125
+ * The intent.
126
+ */
127
+ intent: SurfaceIntent;
128
+ /**
129
+ * Node types of which the surface needs at least one;
130
+ * empty when it needs none.
131
+ */
132
+ requires: ReadonlyArray<string>;
133
+ /**
134
+ * The default actions, by label.
135
+ */
136
+ actions: ReadonlyArray<string>;
137
+ /**
138
+ * What the reply's `values` hold.
139
+ */
140
+ reply: string;
141
+ };
142
+ export type SurfaceCatalog = {
143
+ /**
144
+ * The format version, `surface/1`.
145
+ */
146
+ version: string;
147
+ /**
148
+ * The intents.
149
+ */
150
+ intents: Readonly<Partial<Record<SurfaceIntent, CatalogIntent>>>;
151
+ /**
152
+ * The node types.
153
+ */
154
+ nodes: Readonly<Record<string, CatalogNode>>;
155
+ };
156
+ /**
157
+ * The full catalog. Frozen; narrow it with `narrowCatalog()`.
158
+ * @type {SurfaceCatalog}
159
+ */
160
+ export declare const CATALOG: SurfaceCatalog;
161
+ /**
162
+ * Returns a catalog limited to some intents and node types. It can only narrow: a name the
163
+ * catalog does not have is refused, and so is an intent whose required node would be removed
164
+ * (`ask` without `fields`, `choose` without `choice`, `review` without `diff` or `table`,
165
+ * `questionnaire` without `questionnaire`). A node that belongs to one intent leaves with it.
166
+ * @param {SurfaceCatalog} catalog The catalog to narrow: `CATALOG` or an already narrowed one.
167
+ * @param {{intents?: SurfaceIntent[], nodes?: string[]}} [options] What to keep; all when left out.
168
+ * @returns {SurfaceCatalog} A new frozen catalog.
169
+ * @throws {TypeError} For an unknown name, an intent left without its required node, or a
170
+ * catalog that is not the library's.
171
+ */
172
+ export declare function narrowCatalog(catalog: SurfaceCatalog, options?: {
173
+ intents?: SurfaceIntent[];
174
+ nodes?: string[];
175
+ }): SurfaceCatalog;
176
+ /**
177
+ * Throws unless the catalog is the library's, or narrowed from it: every intent and node entry
178
+ * must be the library's own frozen entry, so a catalog cannot be widened by building one by hand.
179
+ * @param {unknown} catalog
180
+ * @returns {asserts catalog is SurfaceCatalog}
181
+ * @throws {TypeError} When the catalog is not the library's.
182
+ */
183
+ export declare function assertCatalog(catalog: unknown): asserts catalog is SurfaceCatalog;
184
+ export type Profile = 'full' | 'strict';
185
+ export type JsonSchema = Record<string, any>;
186
+ /**
187
+ * The JSON Schema (2020-12) of the format for a catalog: one operation line, and a whole document.
188
+ * Validation, not the schema, is what decides: the schema cannot see duplicate ids, the order of
189
+ * inputs a condition may name, or the application's entities, and it leaves out the repairs the
190
+ * validator makes.
191
+ * @param {SurfaceCatalog} [catalog=CATALOG]
192
+ * @returns {{line: JsonSchema, document: JsonSchema}}
193
+ */
194
+ export declare function surfaceSchema(catalog?: SurfaceCatalog): {
195
+ line: JsonSchema;
196
+ document: JsonSchema;
197
+ };
198
+ export type SurfaceTool = {
199
+ /**
200
+ * The tool's name.
201
+ */
202
+ name: string;
203
+ /**
204
+ * What it does, for the model.
205
+ */
206
+ description: string;
207
+ /**
208
+ * The arguments' JSON Schema, usable with strict structured
209
+ * output.
210
+ */
211
+ parameters: JsonSchema;
212
+ };
213
+ /**
214
+ * A function-calling tool definition in the neutral shape providers adapt.
215
+ * @typedef {Object} SurfaceTool
216
+ * @property {string} name The tool's name.
217
+ * @property {string} description What it does, for the model.
218
+ * @property {JsonSchema} parameters The arguments' JSON Schema, usable with strict structured
219
+ * output.
220
+ */
221
+ /**
222
+ * The tool definitions a model calls to put a surface in front of the person: `show_surface`
223
+ * (any intent, a whole document) and `ask_user` (an `ask` surface; left out when the catalog has
224
+ * no `ask`). The person's reply is each call's result. Arguments follow the strict profile: every
225
+ * key present, `null` for one that does not apply, schema properties and table rows as lists.
226
+ * @param {SurfaceCatalog} [catalog=CATALOG]
227
+ * @returns {SurfaceTool[]}
228
+ */
229
+ export declare function surfaceTools(catalog?: SurfaceCatalog): SurfaceTool[];
230
+ export type WorkedExample = {
231
+ title: string;
232
+ intro: string;
233
+ intent: SurfaceIntent;
234
+ nodes: string[];
235
+ document: Record<string, any>;
236
+ lines: Record<string, any>[];
237
+ before: string;
238
+ after: string;
239
+ };
240
+ /**
241
+ * The worked examples that fit a catalog: at most `count`, in order of preference.
242
+ * @param {SurfaceCatalog} catalog @param {number} [count=2]
243
+ * @returns {WorkedExample[]}
244
+ */
245
+ export declare function workedExamples(catalog?: SurfaceCatalog, count?: number): WorkedExample[];
246
+ /**
247
+ * The model-facing guide to composing surfaces for a catalog, as one Markdown string: the
248
+ * delivery, the intents, a node reference generated from the catalog, the rules, and two worked
249
+ * examples written for the delivery `mode` picks. `rules` are the application's own lines,
250
+ * appended after the library's. The guide only informs; validation and the application's policy
251
+ * enforce.
252
+ * @param {SurfaceCatalog} [catalog=CATALOG]
253
+ * @param {{mode?: 'tool'|'inline', rules?: string[]}} [options]
254
+ * @returns {string}
255
+ * @throws {TypeError} For an unknown mode or a catalog that is not the library's.
256
+ */
257
+ export declare function surfacePrompt(catalog?: SurfaceCatalog, options?: {
258
+ mode?: 'tool' | 'inline';
259
+ rules?: string[];
260
+ }): string;
@@ -0,0 +1,81 @@
1
+ export type InputSchema = import('./schema.js').InputSchema;
2
+ export type OpenSurfaceOptions = import('./surface.js').OpenSurfaceOptions;
3
+ export type ElicitRequest = {
4
+ /**
5
+ * What is asked, and why.
6
+ */
7
+ message: string;
8
+ /**
9
+ * One flat object of `string`, `number`, `integer`,
10
+ * `boolean` and multiple-choice properties.
11
+ */
12
+ requestedSchema: InputSchema;
13
+ };
14
+ export type ElicitResult = {
15
+ /**
16
+ * `accept` with the content, `decline` when the
17
+ * person refused, `cancel` when they closed the form.
18
+ */
19
+ action: 'accept' | 'decline' | 'cancel';
20
+ /**
21
+ * The submitted values,
22
+ * checked against the schema; only with `accept`.
23
+ */
24
+ content?: Record<string, string | number | boolean | string[]>;
25
+ };
26
+ export type ElicitOptions = Omit<OpenSurfaceOptions, 'document'> & {
27
+ title?: string;
28
+ author?: string;
29
+ lang?: string;
30
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
31
+ };
32
+ /** @typedef {import('./schema.js').InputSchema} InputSchema */
33
+ /** @typedef {import('./surface.js').OpenSurfaceOptions} OpenSurfaceOptions */
34
+ /**
35
+ * A form-mode elicitation request.
36
+ * @typedef {Object} ElicitRequest
37
+ * @property {string} message What is asked, and why.
38
+ * @property {InputSchema} requestedSchema One flat object of `string`, `number`, `integer`,
39
+ * `boolean` and multiple-choice properties.
40
+ */
41
+ /**
42
+ * The person's answer.
43
+ * @typedef {Object} ElicitResult
44
+ * @property {'accept'|'decline'|'cancel'} action `accept` with the content, `decline` when the
45
+ * person refused, `cancel` when they closed the form.
46
+ * @property {Record<string, string|number|boolean|string[]>} [content] The submitted values,
47
+ * checked against the schema; only with `accept`.
48
+ */
49
+ /**
50
+ * Options of `elicit()`: where the form goes, who asks, and the Surface's own options.
51
+ * @typedef {Omit<OpenSurfaceOptions, 'document'> & {
52
+ * title?: string,
53
+ * author?: string,
54
+ * lang?: string,
55
+ * msg?: Record<string, string>|Record<string, Record<string, string>>
56
+ * }} ElicitOptions
57
+ */
58
+ /**
59
+ * The `ask` surface `elicit()` draws for a request: the server's message as plain text — its
60
+ * characters drawn as given, never read as markup — and the form, with Submit and Decline. Labels
61
+ * resolve as a Surface's own do: `options.msg` for the active language, then its flat entries, the
62
+ * host translator, and English. Pure: it draws nothing.
63
+ * @param {ElicitRequest} request
64
+ * @param {ElicitOptions} [options] `title`, `author`, `msg` and `lang` are read.
65
+ * @returns {import('./validate.js').SurfaceDocument}
66
+ * @throws {TypeError} When the schema lies outside the subset, naming what is unsupported.
67
+ */
68
+ export declare function elicitDocument(request: ElicitRequest, options?: ElicitOptions): import('./validate.js').SurfaceDocument;
69
+ /**
70
+ * Asks the person for the values a request names, in a Dialog — or inline in `options.target` —
71
+ * and resolves with their answer: Submit resolves `accept` with the values checked against the
72
+ * schema, Decline resolves `decline`, and Escape or closing resolves `cancel`. The surface is
73
+ * `elicitDocument()`'s. `options.signal` withdraws the request: when it aborts — or if it already
74
+ * has — the form is cancelled (a dialog closes, an inline form stays as its receipt) and the
75
+ * promise resolves `cancel`.
76
+ * @param {ElicitRequest} request
77
+ * @param {ElicitOptions} [options]
78
+ * @returns {Promise<ElicitResult>}
79
+ * @throws {TypeError} Rejects when the schema lies outside the subset, naming what is unsupported.
80
+ */
81
+ export declare function elicit(request: ElicitRequest, options?: ElicitOptions): Promise<ElicitResult>;
@@ -0,0 +1,165 @@
1
+ export type ElicitResult = import('./elicit.js').ElicitResult;
2
+ export type InputSchema = import('./schema.js').InputSchema;
3
+ export type SurfaceReply = import('./surface.js').SurfaceReply;
4
+ /** @typedef {import('./elicit.js').ElicitResult} ElicitResult */
5
+ /** @typedef {import('./schema.js').InputSchema} InputSchema */
6
+ /** @typedef {import('./surface.js').SurfaceReply} SurfaceReply */
7
+ /** The MCP revision whose elicitation the handler implements. */
8
+ export declare const MCP_ELICITATION_VERSION = "2026-07-28";
9
+ export type ElicitationParams = {
10
+ /**
11
+ * How the server asks.
12
+ */
13
+ mode?: 'form' | 'url';
14
+ /**
15
+ * What is asked, and why.
16
+ */
17
+ message: string;
18
+ /**
19
+ * Form mode: one flat object of primitive and
20
+ * multiple-choice properties.
21
+ */
22
+ requestedSchema?: InputSchema;
23
+ /**
24
+ * URL mode: the page the person is sent to, `https:` only.
25
+ */
26
+ url?: string;
27
+ /**
28
+ * Sent by servers of the 2025-11-25 revision; ignored.
29
+ */
30
+ elicitationId?: string;
31
+ };
32
+ export type ElicitationHandlerOptions = {
33
+ /**
34
+ * The name of the server that asks, as the client knows it; shown as
35
+ * "Asked by <server>". Required: the person must always see who asks.
36
+ */
37
+ serverName: string;
38
+ /**
39
+ * Display names by key; when it lists
40
+ * `serverName`, that entry's name is shown instead.
41
+ */
42
+ authors?: Record<string, {
43
+ name: string;
44
+ }>;
45
+ /**
46
+ * Where the surface goes inline; a Dialog without one.
47
+ */
48
+ target?: Element | string | null;
49
+ /**
50
+ * Opens the page in URL mode, after the person
51
+ * agreed. It receives the normalised address and must open it in a new browsing context that
52
+ * cannot reach the application; returning `false` or throwing means it was not opened, and the
53
+ * request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
54
+ */
55
+ open?: (url: string) => boolean | void;
56
+ /**
57
+ * Localized
58
+ * messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
59
+ */
60
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
61
+ };
62
+ export type ElicitationContext = {
63
+ /**
64
+ * Withdraws the request — the server cancelled it, the call
65
+ * timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
66
+ * closes, an inline surface stays as its receipt), nothing opens, and the request resolves
67
+ * `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
68
+ * when the application removes an inline `target`, or the request stays pending.
69
+ */
70
+ signal?: AbortSignal | null;
71
+ };
72
+ export type ElicitationUrl = {
73
+ /**
74
+ * The normalised address: what is shown in full and what is opened.
75
+ */
76
+ href: string;
77
+ /**
78
+ * The host, with its port when it has one, as the browser will reach it.
79
+ */
80
+ host: string;
81
+ /**
82
+ * Whether the host holds an internationalised (Punycode) label,
83
+ * which can imitate another name.
84
+ */
85
+ international: boolean;
86
+ };
87
+ /**
88
+ * An elicitation request's `params`. Form mode is the default when `mode` is absent; fields a mode
89
+ * does not use, such as the `elicitationId` of earlier revisions, are ignored.
90
+ * @typedef {Object} ElicitationParams
91
+ * @property {'form'|'url'} [mode] How the server asks.
92
+ * @property {string} message What is asked, and why.
93
+ * @property {InputSchema} [requestedSchema] Form mode: one flat object of primitive and
94
+ * multiple-choice properties.
95
+ * @property {string} [url] URL mode: the page the person is sent to, `https:` only.
96
+ * @property {string} [elicitationId] Sent by servers of the 2025-11-25 revision; ignored.
97
+ */
98
+ /**
99
+ * Options of `elicitationHandler()`.
100
+ * @typedef {Object} ElicitationHandlerOptions
101
+ * @property {string} serverName The name of the server that asks, as the client knows it; shown as
102
+ * "Asked by <server>". Required: the person must always see who asks.
103
+ * @property {Record<string, {name: string}>} [authors={}] Display names by key; when it lists
104
+ * `serverName`, that entry's name is shown instead.
105
+ * @property {Element|string|null} [target=null] Where the surface goes inline; a Dialog without one.
106
+ * @property {(url: string) => boolean|void} [open] Opens the page in URL mode, after the person
107
+ * agreed. It receives the normalised address and must open it in a new browsing context that
108
+ * cannot reach the application; returning `false` or throwing means it was not opened, and the
109
+ * request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
110
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
111
+ * messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
112
+ */
113
+ /**
114
+ * What the client knows about one request beyond its `params`.
115
+ * @typedef {Object} ElicitationContext
116
+ * @property {AbortSignal|null} [signal] Withdraws the request — the server cancelled it, the call
117
+ * timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
118
+ * closes, an inline surface stays as its receipt), nothing opens, and the request resolves
119
+ * `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
120
+ * when the application removes an inline `target`, or the request stays pending.
121
+ */
122
+ /**
123
+ * A URL-mode address, checked and normalised.
124
+ * @typedef {Object} ElicitationUrl
125
+ * @property {string} href The normalised address: what is shown in full and what is opened.
126
+ * @property {string} host The host, with its port when it has one, as the browser will reach it.
127
+ * @property {boolean} international Whether the host holds an internationalised (Punycode) label,
128
+ * which can imitate another name.
129
+ */
130
+ /**
131
+ * Creates the function an MCP client installs to answer elicitation requests. Form mode draws an
132
+ * `ask` surface through `elicit()`. URL mode draws a `confirm` surface naming the page's host,
133
+ * emphasised, and its full address; nothing is loaded and nothing opens until the person agrees.
134
+ * Open the page opens it in a new browsing context, without opener or referrer, and answers
135
+ * `accept`; Decline answers `decline`; Cancel, Escape or closing the dialog answers `cancel`.
136
+ * @param {ElicitationHandlerOptions} options
137
+ * @returns {(params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>}
138
+ * Resolves the result to send back;
139
+ * rejects with a `TypeError` — so the client can answer the server with an error — for a request
140
+ * that is not an object, an unknown `mode`, a `message` that is not text, a schema outside the
141
+ * supported subset, or an address that is not a valid `https:` URL.
142
+ * @throws {TypeError} When `serverName` is missing.
143
+ */
144
+ export declare function elicitationHandler(options: ElicitationHandlerOptions): (params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>;
145
+ /**
146
+ * Checks a URL-mode address the way surface links are checked, and normalises it: an absolute
147
+ * `https://` address in lower case, without credentials, spaces, backslashes, control or invisible
148
+ * formatting characters, at most 2000 characters. The address returned is the parsed one, so the
149
+ * host shown and the page opened come from the same string.
150
+ * @param {unknown} value The request's `url`.
151
+ * @returns {ElicitationUrl}
152
+ * @throws {TypeError} When the address is missing or refused.
153
+ */
154
+ export declare function elicitationUrl(value: unknown): ElicitationUrl;
155
+ /**
156
+ * The `confirm` surface that asks before a URL-mode page opens: the server's message as plain
157
+ * text, the host emphasised, the full address, a warning for an internationalised host, and what
158
+ * opening does. No part of it is a link.
159
+ * @param {string} message The server's message.
160
+ * @param {ElicitationUrl} url From `elicitationUrl()`.
161
+ * @param {(key: string, ...args: unknown[]) => string} [text] Resolves the `mcp.*` messages;
162
+ * English by default.
163
+ * @returns {import('./validate.js').SurfaceDocument}
164
+ */
165
+ export declare function urlConsentDocument(message: string, url: ElicitationUrl, text?: (key: string, ...args: unknown[]) => string): import('./validate.js').SurfaceDocument;