@zeyos/zx 5.6.0 → 5.7.0

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 (215) hide show
  1. package/CHANGELOG.md +154 -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/code-editor/code-editor.d.ts +7 -2
  15. package/dist/types/components/composer/composer.d.ts +206 -4
  16. package/dist/types/components/composer/queue.d.ts +76 -0
  17. package/dist/types/components/copy/copy-button.d.ts +6 -4
  18. package/dist/types/components/copy/copy-input.d.ts +10 -6
  19. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  20. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  21. package/dist/types/components/dock/dock.d.ts +12 -3
  22. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  23. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  24. package/dist/types/components/file-item/file-item.d.ts +3 -2
  25. package/dist/types/components/file-list/file-list.d.ts +14 -8
  26. package/dist/types/components/filter/filter-model.d.ts +31 -1
  27. package/dist/types/components/filter/filter.d.ts +20 -2
  28. package/dist/types/components/finder/finder.d.ts +14 -6
  29. package/dist/types/components/flag/flag.d.ts +99 -0
  30. package/dist/types/components/grid/grid.d.ts +1 -1
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  32. package/dist/types/components/launcher/launcher.d.ts +2 -0
  33. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  34. package/dist/types/components/number-field/number-field.d.ts +17 -6
  35. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  36. package/dist/types/components/prose/prose.d.ts +9 -6
  37. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  38. package/dist/types/components/questionnaire/items.d.ts +52 -30
  39. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  40. package/dist/types/components/rating/rating.d.ts +5 -3
  41. package/dist/types/components/select/country.d.ts +106 -0
  42. package/dist/types/components/select/field-adapter.d.ts +2 -1
  43. package/dist/types/components/select/locale.d.ts +102 -0
  44. package/dist/types/components/select/select.d.ts +41 -2
  45. package/dist/types/components/slider/slider.d.ts +1 -0
  46. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  47. package/dist/types/components/source-list/source-list.d.ts +7 -5
  48. package/dist/types/components/split-view/split-view.d.ts +5 -3
  49. package/dist/types/components/surface/catalog.d.ts +260 -0
  50. package/dist/types/components/surface/elicit.d.ts +81 -0
  51. package/dist/types/components/surface/mcp.d.ts +165 -0
  52. package/dist/types/components/surface/schema.d.ts +314 -0
  53. package/dist/types/components/surface/stream.d.ts +118 -0
  54. package/dist/types/components/surface/surface.d.ts +718 -0
  55. package/dist/types/components/surface/text.d.ts +277 -0
  56. package/dist/types/components/surface/validate.d.ts +339 -0
  57. package/dist/types/components/table/table.d.ts +55 -3
  58. package/dist/types/components/table/window.d.ts +203 -0
  59. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  60. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  61. package/dist/types/components/tree/tree.d.ts +20 -13
  62. package/dist/types/core/component.d.ts +10 -0
  63. package/dist/types/core/date.d.ts +8 -1
  64. package/dist/types/core/dom.d.ts +1 -0
  65. package/dist/types/core/http.d.ts +10 -0
  66. package/dist/types/core/i18n.d.ts +38 -0
  67. package/dist/types/core/messages.d.ts +344 -1
  68. package/dist/types/core/storage.d.ts +7 -2
  69. package/dist/types/elements/define.d.ts +21 -46
  70. package/dist/types/elements/definitions.d.ts +147 -0
  71. package/dist/types/elements/kit.d.ts +7 -0
  72. package/dist/types/elements/reflect.d.ts +6 -3
  73. package/dist/types/index.d.ts +10 -1
  74. package/dist/types/internal/date-locale.d.ts +7 -0
  75. package/dist/types/internal/json-patch.d.ts +146 -0
  76. package/dist/types/locales/de.d.ts +13 -0
  77. package/dist/types/locales/en.d.ts +2 -0
  78. package/dist/types/locales/index.d.ts +823 -0
  79. package/dist/types/zeyos/view.d.ts +8 -1
  80. package/dist/zx-zeyos.esm.js +16802 -15180
  81. package/dist/zx-zeyos.esm.min.js +5 -5
  82. package/dist/zx.core.css +1276 -0
  83. package/dist/zx.core.min.css +1 -0
  84. package/dist/zx.css +498 -134
  85. package/dist/zx.esm.js +40778 -29654
  86. package/dist/zx.esm.min.js +36 -23
  87. package/dist/zx.global.js +40778 -29654
  88. package/dist/zx.global.min.js +36 -23
  89. package/dist/zx.layered.css +17302 -0
  90. package/dist/zx.layered.min.css +1 -0
  91. package/dist/zx.min.css +1 -1
  92. package/docs/agent-catalog.json +12501 -0
  93. package/docs/agent-surfaces.md +340 -0
  94. package/docs/api.json +851 -121
  95. package/docs/llms.md +1018 -71
  96. package/docs/llms.txt +30 -9
  97. package/package.json +29 -6
  98. package/src/components/account-menu/account-menu.js +6 -3
  99. package/src/components/activity-item/activity-item.js +2 -1
  100. package/src/components/activity-list/activity-list.js +16 -10
  101. package/src/components/agent-thread/ag-ui.js +1439 -0
  102. package/src/components/agent-thread/agent-thread.js +359 -54
  103. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  104. package/src/components/app-sidebar/app-sidebar.js +18 -8
  105. package/src/components/approval-card/approval-card.js +3 -2
  106. package/src/components/block-view/block-view.js +7 -6
  107. package/src/components/breadcrumb/breadcrumb.js +8 -5
  108. package/src/components/calendar/calendar-model.js +8 -2
  109. package/src/components/calendar/calendar.js +53 -18
  110. package/src/components/chart/chart.js +54 -23
  111. package/src/components/code-editor/code-editor.js +45 -8
  112. package/src/components/code-editor/field-adapter.js +1 -1
  113. package/src/components/composer/composer.css +80 -1
  114. package/src/components/composer/composer.js +390 -16
  115. package/src/components/composer/queue.js +78 -0
  116. package/src/components/context-menu/context-menu.js +12 -1
  117. package/src/components/copy/copy-button.js +9 -7
  118. package/src/components/copy/copy-input.js +10 -6
  119. package/src/components/date-picker/date-picker.js +2 -1
  120. package/src/components/date-picker/date-range-picker.js +8 -7
  121. package/src/components/datebox/date-range-box.js +3 -9
  122. package/src/components/datebox/datebox.js +18 -21
  123. package/src/components/datebox/placeholder.js +18 -0
  124. package/src/components/dialog/dialog.js +1 -1
  125. package/src/components/dock/dock.js +34 -13
  126. package/src/components/entity-ref/entity-ref.js +16 -5
  127. package/src/components/field-upload/field-upload.js +81 -38
  128. package/src/components/file-item/file-item.js +70 -40
  129. package/src/components/file-list/file-list.js +15 -9
  130. package/src/components/filter/filter-model.js +46 -8
  131. package/src/components/filter/filter.css +3 -3
  132. package/src/components/filter/filter.js +29 -10
  133. package/src/components/filter-panel/filter-panel.js +13 -5
  134. package/src/components/finder/finder.js +50 -26
  135. package/src/components/flag/flag.css +40 -0
  136. package/src/components/flag/flag.js +177 -0
  137. package/src/components/form/form.js +1 -1
  138. package/src/components/grid/grid.js +22 -8
  139. package/src/components/kanban-view/kanban-view.js +51 -81
  140. package/src/components/launcher/launcher.js +17 -2
  141. package/src/components/list-toolbar/list-toolbar.js +2 -1
  142. package/src/components/master-panel/master-panel.js +1 -1
  143. package/src/components/menu-button/menu-button.js +4 -0
  144. package/src/components/message/message.js +3 -0
  145. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  146. package/src/components/navigation-bar/navigation-bar.js +3 -3
  147. package/src/components/number-field/number-field.js +29 -13
  148. package/src/components/prompt-starters/prompt-starters.css +91 -0
  149. package/src/components/prompt-starters/prompt-starters.js +206 -0
  150. package/src/components/prose/prose.js +14 -10
  151. package/src/components/questionnaire/conditions.js +666 -0
  152. package/src/components/questionnaire/items.js +150 -41
  153. package/src/components/questionnaire/questionnaire.js +126 -32
  154. package/src/components/rating/rating.js +5 -4
  155. package/src/components/run-status/run-status.js +2 -2
  156. package/src/components/select/country.js +136 -0
  157. package/src/components/select/field-adapter.js +7 -2
  158. package/src/components/select/locale.js +219 -0
  159. package/src/components/select/select.css +20 -22
  160. package/src/components/select/select.js +94 -12
  161. package/src/components/sheet/sheet-stack.js +10 -1
  162. package/src/components/slider/slider.js +7 -2
  163. package/src/components/sort-control/sort-control.js +15 -5
  164. package/src/components/source-list/source-list.js +7 -4
  165. package/src/components/split-view/split-view.js +5 -3
  166. package/src/components/surface/catalog.js +1334 -0
  167. package/src/components/surface/elicit.js +107 -0
  168. package/src/components/surface/mcp.js +243 -0
  169. package/src/components/surface/schema.js +644 -0
  170. package/src/components/surface/stream.js +245 -0
  171. package/src/components/surface/surface.css +308 -0
  172. package/src/components/surface/surface.js +2291 -0
  173. package/src/components/surface/text.js +513 -0
  174. package/src/components/surface/validate.js +2218 -0
  175. package/src/components/tabbox/tabbox.js +9 -0
  176. package/src/components/table/table.css +63 -3
  177. package/src/components/table/table.js +167 -28
  178. package/src/components/table/window.js +317 -0
  179. package/src/components/toolbar/toolbar.js +12 -7
  180. package/src/components/tooltip/tooltip.css +2 -3
  181. package/src/components/tooltip/tooltip.js +32 -5
  182. package/src/components/tree/tree.js +53 -23
  183. package/src/core/component.js +25 -1
  184. package/src/core/date.js +62 -16
  185. package/src/core/dom.js +22 -2
  186. package/src/core/format.js +15 -13
  187. package/src/core/http.js +29 -20
  188. package/src/core/i18n.js +83 -10
  189. package/src/core/keyboard.js +79 -8
  190. package/src/core/messages.js +376 -2
  191. package/src/core/overlay-host.js +1 -0
  192. package/src/core/storage.js +59 -6
  193. package/src/elements/define.js +178 -130
  194. package/src/elements/definitions.js +229 -0
  195. package/src/elements/kit.js +444 -0
  196. package/src/elements/reflect.js +8 -3
  197. package/src/index.js +10 -1
  198. package/src/internal/date-locale.js +11 -0
  199. package/src/internal/json-patch.js +405 -0
  200. package/src/locales/de.js +911 -0
  201. package/src/locales/en.js +2 -0
  202. package/src/locales/index.js +7 -0
  203. package/src/zeyos/calendar.js +2 -1
  204. package/src/zeyos/form.js +2 -1
  205. package/src/zeyos/launcher.js +7 -6
  206. package/src/zeyos/module-bar.js +2 -1
  207. package/src/zeyos/schema.js +37 -23
  208. package/src/zeyos/select.js +4 -3
  209. package/src/zeyos/table.js +2 -13
  210. package/src/zeyos/view.js +57 -17
  211. package/styles/core.css +11 -0
  212. package/styles/tokens/semantic.css +1 -0
  213. package/styles/zeyos.css +2 -0
  214. package/styles/zx.css +4 -8
  215. package/styles/zx.layered.css +1 -0
@@ -0,0 +1,107 @@
1
+ // @ts-check
2
+ /**
3
+ * `elicit()`: a form-mode elicitation request — a message and a restricted JSON Schema — drawn as
4
+ * an `ask` surface, answered as `accept`, `decline` or `cancel`. It is the renderer a client of the
5
+ * MCP protocol's form-mode elicitation needs; transport stays with the application.
6
+ */
7
+ import { uid } from '../../core/util.js';
8
+ import { LIMITS } from './catalog.js';
9
+ import { unsupported } from './schema.js';
10
+ import { openSurface } from './surface.js';
11
+ import { messageResolver, plainInline } from './text.js';
12
+
13
+ /** @typedef {import('./schema.js').InputSchema} InputSchema */
14
+ /** @typedef {import('./surface.js').OpenSurfaceOptions} OpenSurfaceOptions */
15
+
16
+ /**
17
+ * A form-mode elicitation request.
18
+ * @typedef {Object} ElicitRequest
19
+ * @property {string} message What is asked, and why.
20
+ * @property {InputSchema} requestedSchema One flat object of `string`, `number`, `integer`,
21
+ * `boolean` and multiple-choice properties.
22
+ */
23
+
24
+ /**
25
+ * The person's answer.
26
+ * @typedef {Object} ElicitResult
27
+ * @property {'accept'|'decline'|'cancel'} action `accept` with the content, `decline` when the
28
+ * person refused, `cancel` when they closed the form.
29
+ * @property {Record<string, string|number|boolean|string[]>} [content] The submitted values,
30
+ * checked against the schema; only with `accept`.
31
+ */
32
+
33
+ /**
34
+ * Options of `elicit()`: where the form goes, who asks, and the Surface's own options.
35
+ * @typedef {Omit<OpenSurfaceOptions, 'document'> & {
36
+ * title?: string,
37
+ * author?: string,
38
+ * lang?: string,
39
+ * msg?: Record<string, string>|Record<string, Record<string, string>>
40
+ * }} ElicitOptions
41
+ */
42
+
43
+ /**
44
+ * The `ask` surface `elicit()` draws for a request: the server's message as plain text — its
45
+ * characters drawn as given, never read as markup — and the form, with Submit and Decline. Labels
46
+ * resolve as a Surface's own do: `options.msg` for the active language, then its flat entries, the
47
+ * host translator, and English. Pure: it draws nothing.
48
+ * @param {ElicitRequest} request
49
+ * @param {ElicitOptions} [options] `title`, `author`, `msg` and `lang` are read.
50
+ * @returns {import('./validate.js').SurfaceDocument}
51
+ * @throws {TypeError} When the schema lies outside the subset, naming what is unsupported.
52
+ */
53
+ export function elicitDocument(request, options = {}) {
54
+ const message = typeof request?.message === 'string' ? request.message : '';
55
+ const schema = request?.requestedSchema;
56
+ const problems = unsupported(schema);
57
+ if (problems.length) {
58
+ throw new TypeError(`The requested schema is not supported: ${problems.map((problem) => (problem.path ? `${problem.path}: ${problem.message}` : problem.message)).join('; ')}`);
59
+ }
60
+ const { title, author = 'server' } = options;
61
+ const lang = /** @type {any} */ (options).lang ?? /** @type {any} */ (options).language;
62
+ const text = messageResolver(/** @type {Record<string, any>|undefined} */ (options.msg), typeof lang === 'string' ? lang : undefined);
63
+ const short = message.trim() && message.length <= LIMITS.label;
64
+ /** @type {Array<Record<string, unknown>>} */
65
+ const nodes = [];
66
+ if (message.trim() && (title || !short)) nodes.push({ id: 'message', type: 'text', text: plainInline(message, LIMITS.string) });
67
+ nodes.push({ id: 'form', type: 'fields', schema: structuredClone(schema) });
68
+ return /** @type {any} */ ({
69
+ zx: 'surface/1',
70
+ surface: uid('elicit'),
71
+ intent: 'ask',
72
+ // A title is drawn as text, never as markup.
73
+ title: (title ?? (short ? message : text('surface.requested'))).slice(0, LIMITS.label),
74
+ author,
75
+ root: nodes.map((node) => node.id),
76
+ nodes,
77
+ actions: [
78
+ { id: 'submit', label: text('surface.submit'), kind: 'primary' },
79
+ { id: 'reject', label: text('surface.decline') }
80
+ ]
81
+ });
82
+ }
83
+
84
+ /**
85
+ * Asks the person for the values a request names, in a Dialog — or inline in `options.target` —
86
+ * and resolves with their answer: Submit resolves `accept` with the values checked against the
87
+ * schema, Decline resolves `decline`, and Escape or closing resolves `cancel`. The surface is
88
+ * `elicitDocument()`'s. `options.signal` withdraws the request: when it aborts — or if it already
89
+ * has — the form is cancelled (a dialog closes, an inline form stays as its receipt) and the
90
+ * promise resolves `cancel`.
91
+ * @param {ElicitRequest} request
92
+ * @param {ElicitOptions} [options]
93
+ * @returns {Promise<ElicitResult>}
94
+ * @throws {TypeError} Rejects when the schema lies outside the subset, naming what is unsupported.
95
+ */
96
+ export async function elicit(request, options = {}) {
97
+ const document = elicitDocument(request, options);
98
+ const { title, author, target = null, placement, ...rest } = options;
99
+ const reply = await openSurface(document, {
100
+ ...rest,
101
+ target,
102
+ placement: placement ?? (target ? 'inline' : 'dialog')
103
+ });
104
+ if (reply.action === 'submit') return { action: 'accept', content: /** @type {any} */ (reply.values) };
105
+ if (reply.action === 'reject') return { action: 'decline' };
106
+ return { action: 'cancel' };
107
+ }
@@ -0,0 +1,243 @@
1
+ // @ts-check
2
+ /**
3
+ * `elicitationHandler()`: answers MCP elicitation requests with surfaces.
4
+ *
5
+ * In MCP, a server asks the client for input in one of two modes. In form mode it sends a message
6
+ * and a restricted JSON Schema, and the person fills a form. In URL mode it sends a message and an
7
+ * address, and the person is sent to that page. The handler takes the request's `params` already
8
+ * parsed, whether they came as an `elicitation/create` request or as an `inputRequests` entry of
9
+ * an `input_required` result, and resolves the result the client sends back. The application owns
10
+ * the MCP client: transport, sessions and authentication stay with it.
11
+ */
12
+ import { uid } from '../../core/util.js';
13
+ import { LIMITS } from './catalog.js';
14
+ import { elicit } from './elicit.js';
15
+ import { openSurface } from './surface.js';
16
+ import { messageResolver, plainInline } from './text.js';
17
+ import { normaliseLink } from './validate.js';
18
+
19
+ /** @typedef {import('./elicit.js').ElicitResult} ElicitResult */
20
+ /** @typedef {import('./schema.js').InputSchema} InputSchema */
21
+ /** @typedef {import('./surface.js').SurfaceReply} SurfaceReply */
22
+
23
+ /** The MCP revision whose elicitation the handler implements. */
24
+ export const MCP_ELICITATION_VERSION = '2026-07-28';
25
+
26
+ /** The author key every elicitation surface is drawn under; its name is the server's. */
27
+ const AUTHOR = 'mcp-server';
28
+
29
+ /**
30
+ * An elicitation request's `params`. Form mode is the default when `mode` is absent; fields a mode
31
+ * does not use, such as the `elicitationId` of earlier revisions, are ignored.
32
+ * @typedef {Object} ElicitationParams
33
+ * @property {'form'|'url'} [mode] How the server asks.
34
+ * @property {string} message What is asked, and why.
35
+ * @property {InputSchema} [requestedSchema] Form mode: one flat object of primitive and
36
+ * multiple-choice properties.
37
+ * @property {string} [url] URL mode: the page the person is sent to, `https:` only.
38
+ * @property {string} [elicitationId] Sent by servers of the 2025-11-25 revision; ignored.
39
+ */
40
+
41
+ /**
42
+ * Options of `elicitationHandler()`.
43
+ * @typedef {Object} ElicitationHandlerOptions
44
+ * @property {string} serverName The name of the server that asks, as the client knows it; shown as
45
+ * "Asked by <server>". Required: the person must always see who asks.
46
+ * @property {Record<string, {name: string}>} [authors={}] Display names by key; when it lists
47
+ * `serverName`, that entry's name is shown instead.
48
+ * @property {Element|string|null} [target=null] Where the surface goes inline; a Dialog without one.
49
+ * @property {(url: string) => boolean|void} [open] Opens the page in URL mode, after the person
50
+ * agreed. It receives the normalised address and must open it in a new browsing context that
51
+ * cannot reach the application; returning `false` or throwing means it was not opened, and the
52
+ * request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
53
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
54
+ * messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
55
+ */
56
+
57
+ /**
58
+ * What the client knows about one request beyond its `params`.
59
+ * @typedef {Object} ElicitationContext
60
+ * @property {AbortSignal|null} [signal] Withdraws the request — the server cancelled it, the call
61
+ * timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
62
+ * closes, an inline surface stays as its receipt), nothing opens, and the request resolves
63
+ * `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
64
+ * when the application removes an inline `target`, or the request stays pending.
65
+ */
66
+
67
+ /**
68
+ * A URL-mode address, checked and normalised.
69
+ * @typedef {Object} ElicitationUrl
70
+ * @property {string} href The normalised address: what is shown in full and what is opened.
71
+ * @property {string} host The host, with its port when it has one, as the browser will reach it.
72
+ * @property {boolean} international Whether the host holds an internationalised (Punycode) label,
73
+ * which can imitate another name.
74
+ */
75
+
76
+ /**
77
+ * Creates the function an MCP client installs to answer elicitation requests. Form mode draws an
78
+ * `ask` surface through `elicit()`. URL mode draws a `confirm` surface naming the page's host,
79
+ * emphasised, and its full address; nothing is loaded and nothing opens until the person agrees.
80
+ * Open the page opens it in a new browsing context, without opener or referrer, and answers
81
+ * `accept`; Decline answers `decline`; Cancel, Escape or closing the dialog answers `cancel`.
82
+ * @param {ElicitationHandlerOptions} options
83
+ * @returns {(params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>}
84
+ * Resolves the result to send back;
85
+ * rejects with a `TypeError` — so the client can answer the server with an error — for a request
86
+ * that is not an object, an unknown `mode`, a `message` that is not text, a schema outside the
87
+ * supported subset, or an address that is not a valid `https:` URL.
88
+ * @throws {TypeError} When `serverName` is missing.
89
+ */
90
+ export function elicitationHandler(options) {
91
+ const serverName = typeof options?.serverName === 'string' ? options.serverName.trim() : '';
92
+ if (!serverName) throw new TypeError('elicitationHandler() needs the "serverName" of the server that asks');
93
+ const authors = options.authors && typeof options.authors === 'object' ? options.authors : {};
94
+ const listed = Object.hasOwn(authors, serverName) ? authors[serverName]?.name : undefined;
95
+ const shown = (typeof listed === 'string' && listed.trim() ? listed : serverName).slice(0, LIMITS.label);
96
+ const target = options.target ?? null;
97
+ const open = typeof options.open === 'function' ? options.open : openPage;
98
+ const own = options.msg && typeof options.msg === 'object' ? options.msg : null;
99
+ const text = messageResolver(own);
100
+
101
+ return async (params, context = {}) => {
102
+ if (!params || typeof params !== 'object' || Array.isArray(params)) {
103
+ throw new TypeError('An elicitation request is an object');
104
+ }
105
+ const mode = params.mode;
106
+ if (mode !== undefined && mode !== 'form' && mode !== 'url') {
107
+ throw new TypeError(`The elicitation mode ${JSON.stringify(mode)} is not supported; use "form" or "url"`);
108
+ }
109
+ if (typeof params.message !== 'string') throw new TypeError('An elicitation request needs a "message"');
110
+ // Read on every request, so a language switched in between is honoured.
111
+ const msg = withByline(own, text('mcp.askedBy'));
112
+ const signal = context?.signal ?? null;
113
+ const surface = { target, authors: { [AUTHOR]: { name: shown } }, msg, signal };
114
+ if (mode === 'url') return askToOpen(params.message, elicitationUrl(params.url), surface, open, text);
115
+ return elicit({ message: params.message, requestedSchema: /** @type {InputSchema} */ (params.requestedSchema) },
116
+ { ...surface, author: AUTHOR });
117
+ };
118
+ }
119
+
120
+ /**
121
+ * Checks a URL-mode address the way surface links are checked, and normalises it: an absolute
122
+ * `https://` address in lower case, without credentials, spaces, backslashes, control or invisible
123
+ * formatting characters, at most 2000 characters. The address returned is the parsed one, so the
124
+ * host shown and the page opened come from the same string.
125
+ * @param {unknown} value The request's `url`.
126
+ * @returns {ElicitationUrl}
127
+ * @throws {TypeError} When the address is missing or refused.
128
+ */
129
+ export function elicitationUrl(value) {
130
+ if (value === undefined) throw new TypeError('The elicitation URL is refused: a URL-mode request needs a "url"');
131
+ const link = normaliseLink(value);
132
+ if (link.href === null) throw new TypeError(`The elicitation URL is refused: ${link.problem}`);
133
+ const url = new URL(link.href);
134
+ return { href: link.href, host: url.host, international: url.hostname.split('.').some((label) => label.startsWith('xn--')) };
135
+ }
136
+
137
+ /**
138
+ * The `confirm` surface that asks before a URL-mode page opens: the server's message as plain
139
+ * text, the host emphasised, the full address, a warning for an internationalised host, and what
140
+ * opening does. No part of it is a link.
141
+ * @param {string} message The server's message.
142
+ * @param {ElicitationUrl} url From `elicitationUrl()`.
143
+ * @param {(key: string, ...args: unknown[]) => string} [text] Resolves the `mcp.*` messages;
144
+ * English by default.
145
+ * @returns {import('./validate.js').SurfaceDocument}
146
+ */
147
+ export function urlConsentDocument(message, url, text = messageResolver(null)) {
148
+ /** @type {Array<Record<string, unknown>>} */
149
+ const nodes = [];
150
+ if (message.trim()) nodes.push({ id: 'message', type: 'text', text: plainInline(message, LIMITS.string) });
151
+ nodes.push({ id: 'host', type: 'text', text: around(text, 'mcp.urlHost', `**${plainInline(url.host)}**`) });
152
+ nodes.push({ id: 'address', type: 'text', text: around(text, 'mcp.urlAddress', plainInline(url.href)) });
153
+ if (url.international) nodes.push({ id: 'international', type: 'callout', tone: 'warning', text: text('mcp.urlInternational') });
154
+ nodes.push({ id: 'note', type: 'text', text: text('mcp.urlNote') });
155
+ return /** @type {any} */ ({
156
+ zx: 'surface/1',
157
+ surface: uid('elicit-url'),
158
+ intent: 'confirm',
159
+ title: text('mcp.urlTitle').slice(0, LIMITS.label),
160
+ author: AUTHOR,
161
+ root: nodes.map((node) => node.id),
162
+ nodes,
163
+ actions: [
164
+ { id: 'confirm', label: text('mcp.urlOpen').slice(0, LIMITS.label), kind: 'primary' },
165
+ { id: 'reject', label: text('mcp.decline').slice(0, LIMITS.label) }
166
+ ]
167
+ });
168
+ }
169
+
170
+ /* ------------------------------------------------------------------ module helpers -- */
171
+
172
+ /** Stands in for a server's value while a message is resolved. */
173
+ const PLACEHOLDER = '\u0000';
174
+
175
+ /**
176
+ * A message around a value of the server's, which is put in afterwards: a message's placeholders
177
+ * are read in what it is given too, and an address may hold what looks like one (`/%a%/`).
178
+ * @param {(key: string, ...args: unknown[]) => string} text @param {string} key @param {string} value
179
+ * @returns {string}
180
+ */
181
+ function around(text, key, value) {
182
+ const message = text(key, PLACEHOLDER);
183
+ return message.includes(PLACEHOLDER) ? message.replace(PLACEHOLDER, () => value) : `${message} ${value}`;
184
+ }
185
+
186
+ /**
187
+ * Asks before opening a URL-mode page, and opens it in the click that agreed.
188
+ * @param {string} message @param {ElicitationUrl} url
189
+ * @param {{target: Element|string|null, authors: Record<string, {name: string}>, msg: Record<string, any>, signal: AbortSignal|null}} surface
190
+ * @param {(url: string) => boolean|void} open
191
+ * @param {(key: string, ...args: unknown[]) => string} text
192
+ * @returns {Promise<ElicitResult>}
193
+ */
194
+ async function askToOpen(message, url, surface, open, text) {
195
+ let opened = false;
196
+ const reply = await openSurface(urlConsentDocument(message, url, text), {
197
+ ...surface,
198
+ placement: surface.target ? 'inline' : 'dialog',
199
+ // The page opens inside the person's click, before the dialog closes, so a browser that
200
+ // blocks pages opened without a gesture lets it through.
201
+ onopen: (drawn) => drawn.on('reply', (event) => {
202
+ if (/** @type {CustomEvent<{reply: SurfaceReply}>} */ (event).detail.reply.action !== 'confirm') return;
203
+ try {
204
+ opened = open(url.href) !== false;
205
+ } catch {
206
+ opened = false;
207
+ }
208
+ })
209
+ });
210
+ if (reply.action === 'confirm') return { action: opened ? 'accept' : 'cancel' };
211
+ if (reply.action === 'reject') return { action: 'decline' };
212
+ return { action: 'cancel' };
213
+ }
214
+
215
+ /**
216
+ * The default opener: a new top-level browsing context that gets neither a handle on this page
217
+ * nor its address.
218
+ * @param {string} href
219
+ * @returns {boolean}
220
+ */
221
+ function openPage(href) {
222
+ const view = globalThis.window;
223
+ if (typeof view?.open !== 'function') return false;
224
+ // With "noopener" the browser returns no handle, so a blocked window cannot be told apart.
225
+ view.open(href, '_blank', 'noopener,noreferrer');
226
+ return true;
227
+ }
228
+
229
+ /**
230
+ * The `msg` a surface gets: the application's, with the byline saying who asks — in every
231
+ * language table it holds, so none of them says "Composed by".
232
+ * @param {Record<string, any>|null} own @param {string} byline
233
+ * @returns {Record<string, any>}
234
+ */
235
+ function withByline(own, byline) {
236
+ /** @type {Record<string, any>} */
237
+ const msg = {};
238
+ for (const [key, value] of Object.entries(own ?? {})) {
239
+ msg[key] = value && typeof value === 'object' ? { ...value, 'surface.byline': byline } : value;
240
+ }
241
+ msg['surface.byline'] = byline;
242
+ return msg;
243
+ }