npm - @jini-ai/ui - Versions diffs - 0.1.1 → 0.3.0 - Mend

@jini-ai/ui 0.1.1 → 0.3.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 (1417) hide show

package/dist/features/mcp-ui/surfaces/document.js ADDED Viewed

@@ -0,0 +1,327 @@
+/**
+ * @module features/mcp-ui/surfaces/document
+ *
+ * The document shell every generated surface is built from: doctype, head, the first `<style>` tag
+ * carrying the complete token block, the body wrapper, the protocol bridge, and the surface's own
+ * script — in that order, once, so no builder hand-rolls `<!doctype html>` boilerplate and no
+ * builder can accidentally ship a document whose tokens are half-declared.
+ *
+ * Also here: the small shared fragments (`header`, `detail list`, `status region`, `actions`) that
+ * every dialog-shaped surface needs. They live with the shell rather than in the individual
+ * builders because the CSS that styles them lives here — splitting the markup from the only
+ * stylesheet that can reach it is how a "generic" fragment quietly becomes unstyled in one caller.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE } from '@jini-ai/agentic';
+import { escapeHtml } from '../escape.js';
+import { SURFACE_BRIDGE_GLOBAL, renderBridgeScript } from './bridge.js';
+import { renderTokenBlock } from './tokens.js';
+/**
+ * The base stylesheet, applied after the token block.
+ *
+ * Every rule resolves through a token declared by {@link renderTokenBlock} — there is no external
+ * stylesheet to inherit from and no host cascade to fall back to, so a hardcoded color here would
+ * be a color no caller could reskin. `var(--x, fallback)` appears only where a value is genuinely
+ * optional.
+ */
+export const SURFACE_BASE_CSS = `*, *::before, *::after { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  /* Transparent, not var(--jini-mcpui-bg): this document has no page of its own to paint. It is an
+     allow-scripts-only sandboxed iframe embedded directly in a host's chat transcript, and html's
+     background is left at its (also transparent) initial value, so the host's own pane shows
+     straight through to .mcpui-surface below rather than through a second, unrelated rectangle of
+     fill color sitting between the two. --jini-mcpui-bg stays declared for a caller styling
+     something else via extraCss -- nothing in this stylesheet reads it anymore. */
+  background: transparent;
+  color: var(--jini-mcpui-text);
+  font-family: var(--jini-mcpui-font);
+  font-size: 14px;
+  line-height: 1.5;
+  padding: 16px;
+  -webkit-font-smoothing: antialiased;
+}
+.mcpui-surface {
+  background: linear-gradient(135deg,
+    color-mix(in srgb, var(--jini-mcpui-accent) 5%, var(--jini-mcpui-panel)) 0%,
+    var(--jini-mcpui-panel) 60%);
+  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 18%, var(--jini-mcpui-border));
+  border-radius: var(--jini-mcpui-radius-md);
+  box-shadow: var(--jini-mcpui-surface-shadow);
+  padding: 18px 20px 16px;
+  max-width: 640px;
+  margin: 0 auto;
+}
+.mcpui-title {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  color: var(--jini-mcpui-text-strong);
+}
+.mcpui-description { margin: 6px 0 0; color: var(--jini-mcpui-text-muted); }
+.mcpui-details {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: 4px 14px;
+  margin: 14px 0 0;
+}
+.mcpui-details dt { color: var(--jini-mcpui-text-soft); font-weight: 500; }
+.mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }
+.mcpui-warning {
+  margin: 14px 0 0;
+  padding: 9px 11px;
+  border-radius: var(--jini-mcpui-radius-md);
+  border: 1px solid var(--jini-mcpui-danger);
+  background: var(--jini-mcpui-danger-tint);
+  color: var(--jini-mcpui-text-strong);
+}
+.mcpui-fields { display: flex; flex-direction: column; gap: 12px; margin: 16px 0 0; border: 0; padding: 0; }
+.mcpui-field { display: flex; flex-direction: column; gap: 4px; }
+.mcpui-field-inline { flex-direction: row; align-items: flex-start; gap: 8px; }
+.mcpui-label { font-weight: 500; color: var(--jini-mcpui-text-strong); }
+.mcpui-required { color: var(--jini-mcpui-accent); margin-left: 2px; }
+.mcpui-hint { color: var(--jini-mcpui-text-soft); font-size: 13px; }
+.mcpui-input, .mcpui-select, .mcpui-textarea {
+  font: inherit;
+  color: var(--jini-mcpui-text);
+  background: var(--jini-mcpui-panel);
+  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));
+  border-radius: var(--jini-mcpui-radius-sm);
+  padding: 7px 9px;
+  width: 100%;
+  min-width: 0;
+}
+.mcpui-textarea { resize: vertical; min-height: 72px; font-family: var(--jini-mcpui-font); }
+.mcpui-checkbox { margin: 3px 0 0; accent-color: var(--jini-mcpui-accent); }
+.mcpui-choice-group { border: 0; padding: 0; margin: 0; min-width: 0; }
+.mcpui-choice { display: flex; flex-direction: row; align-items: flex-start; gap: 8px; margin: 6px 0 0; }
+.mcpui-choice-label { color: var(--jini-mcpui-text); font-weight: 400; }
+.mcpui-input:focus-visible, .mcpui-select:focus-visible, .mcpui-textarea:focus-visible,
+.mcpui-checkbox:focus-visible, .mcpui-button:focus-visible {
+  outline: 2px solid var(--jini-mcpui-accent-ring);
+  outline-offset: 1px;
+  border-color: var(--jini-mcpui-accent);
+}
+.mcpui-actions { display: flex; flex-wrap: wrap; gap: 8px; margin: 18px 0 0; }
+.mcpui-button {
+  font: inherit;
+  font-weight: 500;
+  padding: 7px 15px;
+  border-radius: var(--jini-mcpui-radius-pill);
+  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));
+  background: var(--jini-mcpui-panel);
+  color: var(--jini-mcpui-text);
+  cursor: pointer;
+}
+.mcpui-button:hover:not([disabled]) { background: var(--jini-mcpui-accent-tint); }
+.mcpui-button-primary {
+  background: var(--jini-mcpui-accent);
+  border-color: var(--jini-mcpui-accent);
+  color: var(--jini-mcpui-panel);
+}
+.mcpui-button-primary:hover:not([disabled]) { background: var(--jini-mcpui-accent-hover); border-color: var(--jini-mcpui-accent-hover); }
+.mcpui-button-danger {
+  background: var(--jini-mcpui-danger);
+  border-color: var(--jini-mcpui-danger);
+  color: var(--jini-mcpui-panel);
+}
+.mcpui-button-danger:hover:not([disabled]) { background: var(--jini-mcpui-danger-hover); border-color: var(--jini-mcpui-danger-hover); }
+.mcpui-button[disabled] { opacity: 0.55; cursor: default; }
+.mcpui-status { margin: 12px 0 0; min-height: 1.4em; color: var(--jini-mcpui-text-muted); }
+.mcpui-status[data-state="failed"], .mcpui-status[data-state="invalid"] { color: var(--jini-mcpui-danger); }
+.mcpui-status[data-state="done"] { color: var(--jini-mcpui-text-strong); }
+/* Neither a plain success nor a failure — e.g. an outcome surface reporting "uploaded, not yet
+   reachable" (outcome.ts's own state: partial). Distinct from both --jini-mcpui-danger (would
+   wrongly read as "this failed") and --jini-mcpui-text-strong (would wrongly read as "this is
+   fully done"); the accent token reads as "worth a second look" without asserting either. */
+.mcpui-status[data-state="partial"] { color: var(--jini-mcpui-accent); }
+.mcpui-code { font-family: var(--jini-mcpui-font-mono); font-size: 13px; color: var(--jini-mcpui-text-faint); }`;
+/**
+ * The Content-Security-Policy every generated surface declares in its own `<head>`.
+ *
+ * The sandbox attribute (`MCP_UI_VIEW_SANDBOX`) already denies the frame an origin, forms, popups,
+ * and top-level navigation. What it does not deny is *outbound network access*: a sandboxed frame
+ * can still `fetch()`, load an image, or open a WebSocket, which is a working exfiltration channel
+ * for whatever the surface was told — and a confirmation dialog is told, by design, a secret the
+ * model is not allowed to have. `default-src 'none'` closes it: no subresource of any kind, from
+ * any origin, including the frame's own.
+ *
+ * `'unsafe-inline'` for scripts and styles is not a weakening of that. Inline is the *only* way a
+ * `srcdoc` document can carry code or styling at all — there is no origin to serve a file from — so
+ * the alternative to allowing it is a document with neither. What matters is that the inline content
+ * is generated by this package from typed props, and that with `default-src 'none'` it has nowhere
+ * to send anything.
+ */
+export const SURFACE_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:; form-action 'none'; base-uri 'none'";
+/**
+ * Assembles a complete, self-contained surface document.
+ *
+ * @param spec - See {@link SurfaceDocumentSpec}.
+ * @returns The full HTML string, suitable for `createUIResource`'s `htmlString` and, on the host
+ * side, for an iframe's `srcdoc`.
+ * @complexity O(n) in the assembled length.
+ */
+export function renderSurfaceDocument(spec) {
+    const extraCss = spec.extraCss === undefined ? '' : `\n${spec.extraCss}`;
+    return `<!doctype html>
+<html lang="${escapeHtml(spec.lang ?? 'en')}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="${SURFACE_CSP}">
+<title>${escapeHtml(spec.title)}</title>
+<style>
+${renderTokenBlock(spec.tokens)}
+${SURFACE_BASE_CSS}${extraCss}
+</style>
+</head>
+<body>
+<main class="mcpui-surface">
+${spec.bodyHtml}
+</main>
+<script>
+${renderBridgeScript(spec.app)}
+</script>
+<script>
+${spec.script}
+</script>
+</body>
+</html>`;
+}
+/**
+ * Renders a surface's heading and optional description.
+ *
+ * @param spec.title - Shown as the `<h1>`. There is exactly one per surface — a frame this small
+ * has no room for a heading hierarchy, and a screen reader reaching a one-heading document announces
+ * it as the frame's purpose.
+ */
+export function renderSurfaceHeader(spec) {
+    const description = spec.description === undefined ? '' : `\n<p class="mcpui-description">${escapeHtml(spec.description)}</p>`;
+    return `<h1 class="mcpui-title">${escapeHtml(spec.title)}</h1>${description}`;
+}
+/**
+ * Renders a `label: value` description list.
+ *
+ * @returns The `<dl>`, or `''` for an empty list — an empty `<dl>` is announced by screen readers
+ * as a list with no items, which is worse than no list.
+ */
+export function renderDetailList(details) {
+    if (details.length === 0)
+        return '';
+    const rows = details
+        .map((detail) => `  <dt>${escapeHtml(detail.label)}</dt><dd>${escapeHtml(detail.value)}</dd>`)
+        .join('\n');
+    return `<dl class="mcpui-details">\n${rows}\n</dl>`;
+}
+/** Renders the polite live region every surface reports outcomes through. Its id is fixed so surface scripts can find it. */
+export function renderStatusRegion() {
+    return `<p class="mcpui-status" id="${SURFACE_STATUS_ELEMENT_ID}" role="status" aria-live="polite" data-state="idle"></p>`;
+}
+/** The id {@link renderStatusRegion} emits and {@link SURFACE_SCRIPT_PRELUDE} looks up. */
+export const SURFACE_STATUS_ELEMENT_ID = 'mcpui-status';
+export const DEFAULT_SURFACE_STATUS_TEXT = {
+    working: 'Working…',
+    done: 'Done.',
+    failedPrefix: 'Failed: ',
+    dismissed: 'Dismissed.',
+    missingPrefix: 'Please complete: ',
+};
+/**
+ * The JavaScript preamble every surface script opens with: the bridge handle, the status region,
+ * the action buttons, and the two helpers (`setStatus`, `setBusy`) that would otherwise be
+ * copy-pasted into each builder — and would then drift, so that one dialog disabled its buttons
+ * while another left them live for a second click on an in-flight destructive action.
+ *
+ * Declared with `var` and function declarations rather than `const`/arrow functions to match the
+ * rest of the emitted scripts: these run as classic scripts in whatever engine the host embeds, and
+ * the builders make no assumption about it beyond ES5.
+ */
+export const SURFACE_SCRIPT_PRELUDE = `var api = window.${SURFACE_BRIDGE_GLOBAL};
+var statusNode = document.getElementById(${JSON.stringify(SURFACE_STATUS_ELEMENT_ID)});
+var actionButtons = Array.prototype.slice.call(document.querySelectorAll("[data-mcpui-action]"));
+function setStatus(text, state) {
+  statusNode.textContent = text;
+  statusNode.setAttribute("data-state", state);
+}
+function setBusy(busy) {
+  for (var i = 0; i < actionButtons.length; i++) actionButtons[i].disabled = busy;
+}
+function describeError(error) {
+  return error && typeof error.message === "string" ? error.message : String(error);
+}`;
+/**
+ * A field name that is simultaneously an HTML `name`, part of a DOM `id`, and a key in the JSON
+ * params object the surface posts back. Anything outside this set breaks at least one of those
+ * three silently — a space in a `name` produces an `id` the `for` attribute cannot reference, so
+ * clicking the label stops focusing the control and nothing reports an error.
+ */
+const FIELD_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+/**
+ * Builds the DOM id for a field's control, validating the name on the way through.
+ *
+ * @throws If the name is not a valid field name. Thrown rather than sanitized, because silently
+ * rewriting a caller's field name would change the key of the params the tool receives.
+ */
+export function fieldElementId(name) {
+    if (!FIELD_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid MCP-UI field name ${JSON.stringify(name)}: expected /${FIELD_NAME_PATTERN.source}/.`);
+    }
+    return `mcpui-field-${name}`;
+}
+/**
+ * Renders a control's `<label>`, plus its optional hint.
+ *
+ * @param spec.inline - `true` for a checkbox, where the label follows the control rather than
+ * sitting above it, so the hint has to be wrapped instead of emitted as a sibling.
+ */
+export function renderFieldLabel(spec) {
+    const required = spec.required === true ? '<span class="mcpui-required" aria-hidden="true">*</span>' : '';
+    const hint = spec.hint === undefined
+        ? ''
+        : `\n<span class="mcpui-hint" id="${escapeHtml(fieldElementId(spec.name))}-hint">${escapeHtml(spec.hint)}</span>`;
+    return `<label class="mcpui-label" for="${escapeHtml(fieldElementId(spec.name))}">${escapeHtml(spec.label)}${required}</label>${hint}`;
+}
+/** The `aria-describedby` attribute pointing at a field's hint, or `''` when it has none. */
+export function fieldDescribedBy(spec) {
+    if (spec.hint === undefined)
+        return '';
+    return ` aria-describedby="${escapeHtml(fieldElementId(spec.name))}-hint"`;
+}
+/**
+ * Renders the action row.
+ *
+ * Buttons carry `data-mcpui-action`, never an `onclick` attribute: an inline handler would need a
+ * `script-src 'unsafe-inline'`-equivalent allowance for attributes specifically, and a host is free
+ * to apply a stricter CSP to the frame than this package can see.
+ *
+ * Each button also carries the `@jini-ai/agentic` `data-agent-*` markup convention
+ * ({@link AGENT_ELEMENT_ATTRIBUTE} et al.) — but this tagging is advisory, not the thing that makes
+ * a surface's actions reachable by `page.find_elements`/`page.click`. Those capabilities resolve a
+ * handle by scanning `document`/`contentDocument`, and this document renders inside a `srcdoc`
+ * iframe sandboxed to `allow-scripts` alone (`MCP_UI_VIEW_SANDBOX` — no `allow-same-origin`,
+ * deliberately), which gives it an opaque origin no ancestor document can read into. So this tagging
+ * is real for a driver that reaches INTO the frame directly — `frameLocator` in Playwright, proven
+ * end to end against exactly this markup — and inert for anything scanning the parent page. Making a
+ * surface's actions visible to `page.find_elements` needs a second, parent-DOM-side echo of this
+ * same action list; see `McpUiSurfaceCard` in `@jini-ai/chat` for that half.
+ */
+export function renderActions(actions) {
+    const buttons = actions
+        .map((action) => {
+        const variant = action.variant ?? 'neutral';
+        const variantClass = variant === 'neutral' ? '' : ` mcpui-button-${variant}`;
+        const label = escapeHtml(action.label);
+        // `mcpui-action-<id>` rather than the bare id: every id observed across this package's own
+        // builders ('confirm', 'cancel', 'submit') already satisfies the agentic package's stricter
+        // `[a-z0-9]+(-[a-z0-9]+)*` handle pattern, but `SurfaceAction.id` is typed as a plain `string`
+        // and nothing here enforces that — a future builder passing something else would still produce
+        // syntactically valid, HTML-escaped markup, just not necessarily a handle `resolveHandleSelector`
+        // would accept. That is unenforced on purpose (see the function doc above: `page.find_elements`
+        // can never reach this document to resolve it either way), so failing loudly here would refuse
+        // markup for a reason that can never matter to the one consumer that can actually query it.
+        return `  <button type="${action.type ?? 'button'}" class="mcpui-button${variantClass}" data-mcpui-action="${escapeHtml(action.id)}" ${AGENT_ELEMENT_ATTRIBUTE}="mcpui-action-${escapeHtml(action.id)}" ${AGENT_ROLE_ATTRIBUTE}="button" ${AGENT_LABEL_ATTRIBUTE}="${label}">${label}</button>`;
+    })
+        .join('\n');
+    return `<div class="mcpui-actions">\n${buttons}\n</div>`;
+}
+//# sourceMappingURL=document.js.map

package/dist/features/mcp-ui/surfaces/document.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"document.js","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/document.ts"],"names":[],"mappings":"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"}

package/dist/features/mcp-ui/surfaces/fields.d.ts ADDED Viewed

@@ -0,0 +1,77 @@
+import { type SelectOption } from './select.js';
+interface SurfaceFieldBase {
+    /** HTML `name`, DOM `id` suffix, and the params key the value is posted under. */
+    readonly name: string;
+    readonly label: string;
+    /** Help text, wired up with `aria-describedby`. */
+    readonly hint?: string;
+    readonly required?: boolean;
+    readonly disabled?: boolean;
+}
+export interface StringField extends SurfaceFieldBase {
+    readonly kind: 'string';
+    readonly value?: string;
+    readonly placeholder?: string;
+    readonly multiline?: boolean;
+    readonly rows?: number;
+    /** Renders as a masked `<input type="password">` — see {@link TextInputProps.secret}. */
+    readonly secret?: boolean;
+}
+export interface NumberField extends SurfaceFieldBase {
+    readonly kind: 'number';
+    readonly value?: number;
+    readonly placeholder?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+export interface BooleanField extends SurfaceFieldBase {
+    readonly kind: 'boolean';
+    readonly value?: boolean;
+}
+export interface EnumField extends SurfaceFieldBase {
+    readonly kind: 'enum';
+    readonly value?: string;
+    readonly options: readonly SelectOption[];
+    readonly placeholder?: string;
+    /**
+     * How the same one-of-N value is drawn. `select` (the default) hides the options until opened —
+     * right for a long list; `radio` shows them all at once — right for a short one the human is
+     * meant to compare before choosing. Presentation only: both post one string under `name`, and
+     * both read back through the same `control.value` path, so `kind` stays `'enum'` either way.
+     */
+    readonly presentation?: 'select' | 'radio';
+}
+/**
+ * A pick-any-number-of-N field.
+ *
+ * Its own kind rather than a flag on {@link EnumField}, because it is the only field whose value is
+ * an **array** — `form.ts`'s `readField` and `isBlank` both branch on that, and no `presentation`
+ * discriminator would have told them to.
+ */
+export interface MultiEnumField extends SurfaceFieldBase {
+    readonly kind: 'multi-enum';
+    /** Pre-checked values. Unknown entries check nothing rather than erroring. */
+    readonly value?: readonly string[];
+    readonly options: readonly SelectOption[];
+}
+export type SurfaceField = StringField | NumberField | BooleanField | EnumField | MultiEnumField;
+/**
+ * Renders the control fragment for one field, dispatching on its kind.
+ *
+ * @param field - See {@link SurfaceField}.
+ * @returns An HTML fragment.
+ * @complexity O(n) in the rendered length.
+ */
+export declare function renderFieldControl(field: SurfaceField): string;
+/** What the surface's inline script needs to read a field's value back and coerce it — the runtime half of {@link SurfaceField}, with the presentation stripped out. */
+export interface FieldReadSpec {
+    readonly name: string;
+    readonly label: string;
+    readonly kind: SurfaceField['kind'];
+    readonly required: boolean;
+}
+/** Projects fields down to what the inline script needs, so the generated JS carries no labels, hints, or option lists it will never read. */
+export declare function toFieldReadSpecs(fields: readonly SurfaceField[]): readonly FieldReadSpec[];
+export {};
+//# sourceMappingURL=fields.d.ts.map

package/dist/features/mcp-ui/surfaces/fields.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/fields.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAG9D,UAAU,gBAAgB;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,cAAc,CAAC;AAajG;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAiD9D;AAED,wKAAwK;AACxK,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,8IAA8I;AAC9I,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,aAAa,EAAE,CAO1F"}

package/dist/features/mcp-ui/surfaces/fields.js ADDED Viewed

@@ -0,0 +1,97 @@
+/**
+ * @module features/mcp-ui/surfaces/fields
+ *
+ * The field-kind union a form is described in, and the dispatch from a kind to its control builder.
+ *
+ * The four kinds are `string | number | boolean | enum` — the same set a JSON-Schema-shaped tool
+ * input reduces to once objects and arrays are excluded, which is deliberate: a surface built from
+ * a tool's own input schema should be describable without inventing a parallel type system. Nested
+ * objects and arrays are a documented gap rather than an oversight; a dialog that renders them well
+ * is a different, larger component than a confirmation box.
+ *
+ * {@link renderFieldControl}'s switch has no `default` branch on purpose. With every case returning
+ * and the union exhausted, adding a fifth kind makes this function stop satisfying its `: string`
+ * return type — a compile error at the switch itself. A `default` that threw would instead move
+ * that failure to runtime, and add a branch no test could reach.
+ */
+import { renderCheckbox } from './checkbox.js';
+import { renderChoiceGroup } from './choice-group.js';
+import { renderSelect } from './select.js';
+import { renderTextInput } from './text-input.js';
+/** Only the properties present on a given field are forwarded, because `exactOptionalPropertyTypes` makes `{ hint: undefined }` and `{}` different types. */
+function base(field) {
+    return {
+        name: field.name,
+        label: field.label,
+        ...(field.hint === undefined ? {} : { hint: field.hint }),
+        ...(field.required === undefined ? {} : { required: field.required }),
+        ...(field.disabled === undefined ? {} : { disabled: field.disabled }),
+    };
+}
+/**
+ * Renders the control fragment for one field, dispatching on its kind.
+ *
+ * @param field - See {@link SurfaceField}.
+ * @returns An HTML fragment.
+ * @complexity O(n) in the rendered length.
+ */
+export function renderFieldControl(field) {
+    switch (field.kind) {
+        case 'string':
+            return renderTextInput({
+                ...base(field),
+                ...(field.value === undefined ? {} : { value: field.value }),
+                ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
+                ...(field.multiline === undefined ? {} : { multiline: field.multiline }),
+                ...(field.rows === undefined ? {} : { rows: field.rows }),
+                ...(field.secret === undefined ? {} : { secret: field.secret }),
+            });
+        case 'number':
+            return renderTextInput({
+                ...base(field),
+                inputType: 'number',
+                ...(field.value === undefined ? {} : { value: field.value }),
+                ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
+                ...(field.min === undefined ? {} : { min: field.min }),
+                ...(field.max === undefined ? {} : { max: field.max }),
+                ...(field.step === undefined ? {} : { step: field.step }),
+            });
+        case 'boolean':
+            return renderCheckbox({
+                ...base(field),
+                ...(field.value === undefined ? {} : { value: field.value }),
+            });
+        case 'enum':
+            if (field.presentation === 'radio') {
+                return renderChoiceGroup({
+                    ...base(field),
+                    selection: 'single',
+                    options: field.options,
+                    ...(field.value === undefined ? {} : { value: [field.value] }),
+                });
+            }
+            return renderSelect({
+                ...base(field),
+                options: field.options,
+                ...(field.value === undefined ? {} : { value: field.value }),
+                ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
+            });
+        case 'multi-enum':
+            return renderChoiceGroup({
+                ...base(field),
+                selection: 'multiple',
+                options: field.options,
+                ...(field.value === undefined ? {} : { value: field.value }),
+            });
+    }
+}
+/** Projects fields down to what the inline script needs, so the generated JS carries no labels, hints, or option lists it will never read. */
+export function toFieldReadSpecs(fields) {
+    return fields.map((field) => ({
+        name: field.name,
+        label: field.label,
+        kind: field.kind,
+        required: field.required === true,
+    }));
+}
+//# sourceMappingURL=fields.js.map

package/dist/features/mcp-ui/surfaces/fields.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"fields.js","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/fields.ts"],"names":[],"mappings":"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"}

package/dist/features/mcp-ui/surfaces/form.d.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * @module features/mcp-ui/surfaces/form
+ *
+ * Composes a field list into one complete input dialog: the same shell, details, status region and
+ * action row `confirmation.ts` uses, wrapped in a real `<form>` whose submit collects, coerces, and
+ * validates the fields before calling a tool.
+ *
+ * A real `<form>` rather than a div with a click handler, for two behaviors that would otherwise
+ * need reimplementing: Enter in a text field submits it, and `form.elements` gives the script a
+ * name-keyed control lookup without a DOM query per field.
+ *
+ * It carries `novalidate`, so the required-field check below is the only one that runs. Controls
+ * still get their `required` attribute — that is what a screen reader announces — but the browser's
+ * own validation UI is suppressed on purpose: its bubble is positioned against the viewport and gets
+ * clipped by the frame's bounds in the small iframe a surface renders in, and the surface already
+ * owns a live region that announces the same information without being clipped.
+ *
+ * ## Coercion is here, not at the tool
+ *
+ * Every value the DOM hands back is a string — `"3"`, `""`, `"true"`. A tool declaring a numeric
+ * parameter would receive a string and either reject it or, worse, coerce it somewhere further
+ * downstream where the failure is harder to attribute. So each field's declared kind drives the
+ * conversion at the only point that knows it: `number` becomes a number or `null` when blank,
+ * `boolean` reads `checked`, and `string`/`enum` pass through.
+ */
+import { type UIResource, type UIResourceUri } from '../resource.js';
+import { type SurfaceDetail, type SurfaceStatusText } from './document.js';
+import { type SurfaceField } from './fields.js';
+import type { BridgeScriptSpec } from './bridge.js';
+import type { SurfaceTokenName } from './tokens.js';
+export interface FormSurfaceSpec {
+    readonly title: string;
+    readonly description?: string;
+    /** Read-only context shown above the fields — what the input is *about*. */
+    readonly details?: readonly SurfaceDetail[];
+    readonly fields: readonly SurfaceField[];
+    /** Callout above the buttons. */
+    readonly warning?: string;
+    /** Styles the submit button as destructive. */
+    readonly danger?: boolean;
+    readonly submitLabel: string;
+    /** The tool the collected values are sent to. */
+    readonly toolName: string;
+    /**
+     * Merged UNDER the collected field values, so a field can never be shadowed by a base param it
+     * shares a name with. Where a confirmation token belongs when the form is a confirmation.
+     */
+    readonly baseParams?: Readonly<Record<string, unknown>>;
+    /** Omit for a form with no cancel button. Give it a tool name to notify the server of the dismissal. */
+    readonly cancel?: {
+        readonly label: string;
+        readonly toolName?: string;
+        readonly params?: Readonly<Record<string, unknown>>;
+    };
+    readonly text?: Partial<SurfaceStatusText>;
+    readonly app?: BridgeScriptSpec;
+    readonly lang?: string;
+    readonly tokens?: Partial<Record<SurfaceTokenName, string>>;
+}
+/**
+ * Renders the form dialog as a complete, self-contained HTML document.
+ *
+ * @param spec - See {@link FormSurfaceSpec}.
+ * @returns The full HTML string.
+ * @complexity O(n) in the number of fields plus the rendered length.
+ */
+export declare function renderFormDocument(spec: FormSurfaceSpec): string;
+/**
+ * Renders the form dialog as an MCP-UI resource, ready for a tool result's `content` array.
+ *
+ * @param spec.uri - The `ui://` identifier. Never key it by a confirmation token.
+ * @complexity O(n) in the number of fields plus the rendered length.
+ */
+export declare function buildFormSurface(spec: FormSurfaceSpec & {
+    uri: UIResourceUri;
+    preferredFrameSize?: readonly [string, string];
+}): UIResource;
+//# sourceMappingURL=form.d.ts.map

package/dist/features/mcp-ui/surfaces/form.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAoB,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,wGAAwG;IACxG,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IAC9H,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7D;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CA0KhE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,eAAe,GAAG;IAAE,GAAG,EAAE,aAAa,CAAC;IAAC,kBAAkB,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7F,UAAU,CAMZ"}