@jini-ai/ui 0.3.10 → 0.3.12

package/dist/features/mcp-ui/surfaces/bridge.js

@@ -150,6 +150,7 @@ export function renderBridgeScript(spec) {
   function toError(error) {
     var failure = new Error(error && typeof error.message === "string" ? error.message : "Host returned an error");
     if (error && typeof error.code === "number") failure.code = error.code;
+    if (error && error.data !== undefined) failure.data = error.data;
     return failure;
   }
 

package/dist/features/mcp-ui/surfaces/checkbox.d.ts

@@ -13,6 +13,16 @@ export interface CheckboxProps {
      */
     readonly required?: boolean;
     readonly disabled?: boolean;
+    /**
+     * One extra `data-*` attribute on the `<input>`, escaped like every other value. For a caller
+     * that needs to look the box up by something other than its DOM `name` — e.g. the confirmation
+     * surface's per-choice ids, which are caller data and may contain characters `fieldElementId`'s
+     * `name` validation disallows.
+     */
+    readonly dataAttribute?: {
+        readonly name: string;
+        readonly value: string;
+    };
 }
 /**
  * Renders one boolean field.

package/dist/features/mcp-ui/surfaces/checkbox.js

@@ -16,10 +16,14 @@ import { fieldDescribedBy, fieldElementId, renderFieldLabel } from './document.j
  */
 export function renderCheckbox(props) {
     const id = fieldElementId(props.name);
+    const dataAttribute = props.dataAttribute === undefined
+        ? ''
+        : ` ${escapeHtml(props.dataAttribute.name)}="${escapeHtml(props.dataAttribute.value)}"`;
     const attributes = ` id="${escapeHtml(id)}" name="${escapeHtml(props.name)}"` +
         (props.value === true ? ' checked' : '') +
         (props.required === true ? ' required' : '') +
         (props.disabled === true ? ' disabled' : '') +
+        dataAttribute +
         fieldDescribedBy(props);
     return `<div class="mcpui-field mcpui-field-inline">\n<input class="mcpui-checkbox" type="checkbox"${attributes}>\n<span>${renderFieldLabel(props)}</span>\n</div>`;
 }

package/dist/features/mcp-ui/surfaces/confirmation.d.ts

@@ -38,11 +38,37 @@ export interface ConfirmationToolAction {
     /** Passed verbatim as the tool's `arguments`. The only safe home for a confirmation token. */
     readonly params: Readonly<Record<string, unknown>>;
 }
+/** One row of an optional per-item checkbox list — see {@link ConfirmationSurfaceSpec.choices}. */
+export interface ConfirmationChoice {
+    /**
+     * The value reported back when this box is ticked. Caller data, not a DOM name: it may contain
+     * any character, because it never becomes an HTML `name`/`id` (those are `choice-<index>` in the
+     * DOM; see `renderChoices`) — only a `data-mcpui-choice` attribute value, which any string escapes
+     * into safely.
+     */
+    readonly id: string;
+    readonly label: string;
+    readonly hint?: string;
+}
 export interface ConfirmationSurfaceSpec {
     readonly title: string;
     readonly description?: string;
     /** The facts being agreed about. A dialog that says "delete this?" without naming *this* is not consent. */
     readonly details?: readonly SurfaceDetail[];
+    /**
+     * Optional per-row checkboxes, rendered unchecked between the details and the warning. Ticking one
+     * never confirms anything by itself — the same property the module doc opens with, extended to a
+     * second input: a tick reaches a tool call ONLY by riding along on confirm's own trusted,
+     * past-dwell click, merged into {@link ConfirmationToolAction.params} under {@link choicesParam}
+     * at the moment of that click and never before. With no `choices`, the rendered document and the
+     * params confirm posts are byte-identical to a spec written before this field existed.
+     */
+    readonly choices?: readonly ConfirmationChoice[];
+    /**
+     * The params key the ticked ids are posted under, merged into (never replacing) `confirm.params`.
+     * Defaults to `"overwrite"`.
+     */
+    readonly choicesParam?: string;
     /** A callout above the buttons — the consequence that is not obvious from the details alone. */
     readonly warning?: string;
     /** Styles the affirmative button as destructive. Affects presentation only; it changes no behavior. */
@@ -59,6 +85,14 @@ export interface ConfirmationSurfaceSpec {
     readonly lang?: string;
     readonly tokens?: Partial<Record<SurfaceTokenName, string>>;
 }
+/**
+ * How long the dialog must have been visible before a confirm click counts, in ms. A click sooner
+ * than a person could have read the dialog is ignored — the same dwell browsers put on permission
+ * prompts against clickjacking, and a guard against an automated click racing the render. Longer
+ * than the ~1 s render-to-confirm gap of the incident it was added for. The confirm button is
+ * rendered disabled and enabled when the dwell ends, so a person sees why an early click does nothing.
+ */
+export declare const CONFIRM_DWELL_MS = 1500;
 export declare function renderConfirmationDocument(spec: ConfirmationSurfaceSpec): string;
 /**
  * Renders the confirmation dialog as an MCP-UI resource, ready for a tool result's `content` array.

package/dist/features/mcp-ui/surfaces/confirmation.js

@@ -30,10 +30,51 @@
 import { createUIResource } from '../resource.js';
 import { escapeHtml, escapeJsValue } from '../escape.js';
 import { DEFAULT_SURFACE_STATUS_TEXT, SURFACE_SCRIPT_PRELUDE, renderActions, renderDetailList, renderStatusRegion, renderSurfaceDocument, renderSurfaceHeader, } from './document.js';
+import { renderCheckbox } from './checkbox.js';
+/**
+ * How long the dialog must have been visible before a confirm click counts, in ms. A click sooner
+ * than a person could have read the dialog is ignored — the same dwell browsers put on permission
+ * prompts against clickjacking, and a guard against an automated click racing the render. Longer
+ * than the ~1 s render-to-confirm gap of the incident it was added for. The confirm button is
+ * rendered disabled and enabled when the dwell ends, so a person sees why an early click does nothing.
+ */
+export const CONFIRM_DWELL_MS = 1500;
 const DEFAULT_APP = { appName: 'jini-mcp-ui-confirmation', appVersion: '1' };
 function isToolAction(action) {
     return action !== undefined && 'toolName' in action;
 }
+/**
+ * Renders the optional choice checkboxes, one unchecked box per {@link ConfirmationChoice}.
+ *
+ * Named `choice-<index>` in the DOM — never by `choice.id`, which is caller data and may contain
+ * characters `fieldElementId`'s `name` validation rejects — with the real id carried on the
+ * `data-mcpui-choice` attribute instead, which the script reads back on change.
+ *
+ * @returns `''` for an empty list, matching every other optional fragment in this document.
+ */
+function renderChoices(choices) {
+    if (choices.length === 0)
+        return '';
+    // Ticked state is keyed by id, so two boxes sharing one would tick and report as one.
+    const seen = new Set();
+    for (const choice of choices) {
+        if (seen.has(choice.id)) {
+            throw new Error(`Confirmation choices must have unique ids; ${JSON.stringify(choice.id)} appears more than once.`);
+        }
+        seen.add(choice.id);
+    }
+    const boxes = choices
+        .map((choice, index) => renderCheckbox({
+        name: `choice-${index}`,
+        label: choice.label,
+        ...(choice.hint === undefined ? {} : { hint: choice.hint }),
+        dataAttribute: { name: 'data-mcpui-choice', value: choice.id },
+    }))
+        .join('\n');
+    // Reuses form.ts's `.mcpui-fields` spacing rather than inventing a second stylesheet rule for the
+    // same "stack of controls" layout.
+    return `<fieldset class="mcpui-fields">\n${boxes}\n</fieldset>`;
+}
 /**
  * Renders the confirmation dialog as a complete, self-contained HTML document.
  *
@@ -59,13 +100,21 @@ function confirmationActions(spec) {
 }
 export function renderConfirmationDocument(spec) {
     const text = { ...DEFAULT_SURFACE_STATUS_TEXT, ...spec.text };
+    const choicesParam = spec.choicesParam ?? 'overwrite';
+    // The ticked ids are merged into confirm.params at click time; a key already there (the token,
+    // say) would be silently replaced by an array.
+    if ((spec.choices ?? []).length > 0 && Object.prototype.hasOwnProperty.call(spec.confirm.params, choicesParam)) {
+        throw new Error(`choicesParam ${JSON.stringify(choicesParam)} collides with a key already in confirm.params.`);
+    }
     const actions = confirmationActions(spec);
     const warning = spec.warning === undefined ? '' : `<p class="mcpui-warning">${escapeHtml(spec.warning)}</p>`;
     const bodyHtml = [
         renderSurfaceHeader(spec.description === undefined ? { title: spec.title } : { title: spec.title, description: spec.description }),
         renderDetailList(spec.details ?? []),
+        renderChoices(spec.choices ?? []),
         warning,
-        renderActions(actions),
+        // Confirm starts disabled; the script enables it once the dwell has run out.
+        renderActions(actions.map((action) => (action.id === 'confirm' ? { ...action, disabled: true } : action))),
         renderStatusRegion(),
     ]
         .filter((fragment) => fragment !== '')
@@ -86,30 +135,134 @@ export function renderConfirmationDocument(spec) {
 ${SURFACE_SCRIPT_PRELUDE}
   var PLAN = ${escapeJsValue(plan)};
   var TEXT = ${escapeJsValue(text)};
+  var DWELL_MS = ${CONFIRM_DWELL_MS};
+  var CHOICES_PARAM = ${escapeJsValue(choicesParam)};
+
+  // Monotonic where available: a wall clock set backwards would otherwise stretch the dwell.
+  function now() {
+    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+  }
+  // Set while a call is in flight and for good once one settles the dialog. The disabled buttons
+  // already block clicks in a browser; this makes the guarantee not depend on the DOM honoring that.
+  var locked = false;
+
+  // When the dialog last became visible; null while hidden. A dialog that loads in a background tab
+  // has not been seen, so its dwell starts when it is shown, and restarts each time it is shown again.
+  var visibleSince = null;
+  var dwellTimer = null;
+  var confirmButton = document.querySelector('[data-mcpui-action="confirm"]');
+
+  function dwellDone() {
+    return visibleSince !== null && now() - visibleSince >= DWELL_MS;
+  }
+  // Confirm is enabled exactly when the dwell has run out and no call holds the dialog.
+  function syncConfirm() {
+    if (confirmButton !== null && !locked) confirmButton.disabled = !dwellDone();
+  }
+  // Re-checks rather than trusts the timer: setTimeout and now() are different clocks, and a timer
+  // that fired a hair early must not leave confirm disabled for good.
+  function onDwellTimer() {
+    dwellTimer = null;
+    if (visibleSince === null) return;
+    var left = DWELL_MS - (now() - visibleSince);
+    if (left > 0) dwellTimer = setTimeout(onDwellTimer, left);
+    else syncConfirm();
+  }
+  function onVisibilityChange() {
+    if (dwellTimer !== null) clearTimeout(dwellTimer);
+    dwellTimer = null;
+    visibleSince = document.visibilityState === "hidden" ? null : now();
+    syncConfirm();
+    if (visibleSince !== null) dwellTimer = setTimeout(onDwellTimer, DWELL_MS);
+  }
+  onVisibilityChange();
+  document.addEventListener("visibilitychange", onVisibilityChange);
 
   for (var i = 0; i < actionButtons.length; i++) {
     actionButtons[i].addEventListener("click", onClick);
   }
 
+  // Ticked state, tracked ourselves rather than trusted from each input's own \`.checked\` at
+  // confirm-time -- the same "only a browser-attributed action counts" rule \`onClick\` applies to
+  // the buttons, extended to the one other interactive element this document can contain. Keyed by
+  // \`data-mcpui-choice\` (the caller's id), not DOM order, so a checkbox reordering upstream could
+  // never silently swap which id a tick reports.
+  var choiceInputs = Array.prototype.slice.call(document.querySelectorAll("[data-mcpui-choice]"));
+  var checkedIds = {};
+  for (var c = 0; c < choiceInputs.length; c++) {
+    choiceInputs[c].addEventListener("change", onChoiceChange);
+  }
+
+  function onChoiceChange(event) {
+    var id = event.currentTarget.getAttribute("data-mcpui-choice");
+    if (event.isTrusted !== true) {
+      // Put the box back to what we last recorded, so a script-driven toggle from anywhere in this
+      // document can never leave the visible box and the ids confirm would send disagreeing.
+      event.currentTarget.checked = checkedIds[id] === true;
+      return;
+    }
+    if (event.currentTarget.checked) checkedIds[id] = true;
+    else delete checkedIds[id];
+  }
+
+  // Frozen with the buttons while a call is in flight and for good once one settles the dialog, so
+  // the ticks on screen are always the ones that were sent.
+  function setChoicesDisabled(disabled) {
+    for (var k = 0; k < choiceInputs.length; k++) choiceInputs[k].disabled = disabled;
+  }
+
+  // DOM order, not \`for...in\` over checkedIds: object key order for arbitrary caller-supplied
+  // strings is not something to depend on, even where every engine we run on happens to preserve it.
+  function checkedChoiceIds() {
+    var ids = [];
+    for (var j = 0; j < choiceInputs.length; j++) {
+      var choiceId = choiceInputs[j].getAttribute("data-mcpui-choice");
+      // Both: a trusted tick recorded, and the box still showing it. Never send what isn't on screen.
+      if (checkedIds[choiceId] === true && choiceInputs[j].checked) ids.push(choiceId);
+    }
+    return ids;
+  }
+
   function onClick(event) {
-    var step = PLAN[event.currentTarget.getAttribute("data-mcpui-action")];
+    // Only a click the browser attributes to the user counts. element.click() and dispatchEvent
+    // from any script in this document produce isTrusted === false.
+    if (event.isTrusted !== true || locked) return;
+    var action = event.currentTarget.getAttribute("data-mcpui-action");
+    var step = PLAN[action];
     if (step === undefined) return;
+    // Cancel is exempt: backing out early is never the harm this guards against.
+    if (action === "confirm" && !dwellDone()) return;
+    locked = true;
+    setChoicesDisabled(true);
     if (step === null) {
       setBusy(true);
       setStatus(TEXT.dismissed, "dismissed");
       api.requestTeardown();
       return;
     }
+    // Choices ride only on confirm, and only when this document has any -- with none, \`params\` stays
+    // the exact \`step.params\` reference PLAN was built from, byte-identical to before this existed.
+    var params = step.params;
+    if (action === "confirm" && choiceInputs.length > 0) {
+      var merged = {};
+      var key;
+      for (key in step.params) if (Object.prototype.hasOwnProperty.call(step.params, key)) merged[key] = step.params[key];
+      merged[CHOICES_PARAM] = checkedChoiceIds();
+      params = merged;
+    }
     setBusy(true);
     setStatus(TEXT.working, "pending");
-    api.callTool(step.toolName, step.params).then(function () {
+    api.callTool(step.toolName, params).then(function () {
       setStatus(TEXT.done, "done");
       api.requestTeardown();
     }, function (error) {
-      // Re-enabled on failure: a rejected call did not happen, so the human must be able to retry
-      // or cancel rather than be left with a dead dialog reporting an error it cannot act on.
-      setBusy(false);
-      setStatus(TEXT.failedPrefix + describeError(error), "failed");
+      // Re-enabled on failure (a rejected call did not happen, so the human must be able to retry
+      // or cancel), unless the Host says this dialog is no longer pending -- see reportCallFailure.
+      if (!reportCallFailure(error)) return;
+      locked = false;
+      setChoicesDisabled(false);
+      // reportCallFailure re-enabled every button; confirm still waits out an unfinished dwell.
+      syncConfirm();
     });
   }
 }());`;

package/dist/features/mcp-ui/surfaces/document.d.ts

@@ -8,7 +8,7 @@ import { type SurfaceTokenName } from './tokens.js';
  * be a color no caller could reskin. `var(--x, fallback)` appears only where a value is genuinely
  * optional.
  */
-export declare const SURFACE_BASE_CSS = "*, *::before, *::after { box-sizing: border-box; }\nhtml, body { margin: 0; padding: 0; }\nbody {\n  /* Transparent, not var(--jini-mcpui-bg): this document has no page of its own to paint. It is an\n     allow-scripts-only sandboxed iframe embedded directly in a host's chat transcript, and html's\n     background is left at its (also transparent) initial value, so the host's own pane shows\n     straight through to .mcpui-surface below rather than through a second, unrelated rectangle of\n     fill color sitting between the two. --jini-mcpui-bg stays declared for a caller styling\n     something else via extraCss -- nothing in this stylesheet reads it anymore. */\n  background: transparent;\n  color: var(--jini-mcpui-text);\n  font-family: var(--jini-mcpui-font);\n  font-size: 14px;\n  line-height: 1.5;\n  padding: 16px;\n  -webkit-font-smoothing: antialiased;\n}\n.mcpui-surface {\n  background: linear-gradient(135deg,\n    color-mix(in srgb, var(--jini-mcpui-accent) 5%, var(--jini-mcpui-panel)) 0%,\n    var(--jini-mcpui-panel) 60%);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 18%, var(--jini-mcpui-border));\n  border-radius: var(--jini-mcpui-radius-md);\n  box-shadow: var(--jini-mcpui-surface-shadow);\n  padding: 18px 20px 16px;\n  max-width: 640px;\n  margin: 0 auto;\n}\n.mcpui-title {\n  margin: 0;\n  font-size: 16px;\n  font-weight: 600;\n  letter-spacing: -0.01em;\n  color: var(--jini-mcpui-text-strong);\n}\n.mcpui-description { margin: 6px 0 0; color: var(--jini-mcpui-text-muted); }\n.mcpui-details {\n  display: grid;\n  grid-template-columns: max-content minmax(0, 1fr);\n  gap: 4px 14px;\n  margin: 14px 0 0;\n}\n.mcpui-details dt { color: var(--jini-mcpui-text-soft); font-weight: 500; }\n.mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }\n.mcpui-warning {\n  margin: 14px 0 0;\n  padding: 9px 11px;\n  border-radius: var(--jini-mcpui-radius-md);\n  border: 1px solid var(--jini-mcpui-danger);\n  background: var(--jini-mcpui-danger-tint);\n  color: var(--jini-mcpui-text-strong);\n}\n.mcpui-fields { display: flex; flex-direction: column; gap: 12px; margin: 16px 0 0; border: 0; padding: 0; }\n.mcpui-field { display: flex; flex-direction: column; gap: 4px; }\n.mcpui-field-inline { flex-direction: row; align-items: flex-start; gap: 8px; }\n.mcpui-label { font-weight: 500; color: var(--jini-mcpui-text-strong); }\n.mcpui-required { color: var(--jini-mcpui-accent); margin-left: 2px; }\n.mcpui-hint { color: var(--jini-mcpui-text-soft); font-size: 13px; }\n.mcpui-input, .mcpui-select, .mcpui-textarea {\n  font: inherit;\n  color: var(--jini-mcpui-text);\n  background: var(--jini-mcpui-panel);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));\n  border-radius: var(--jini-mcpui-radius-sm);\n  padding: 7px 9px;\n  width: 100%;\n  min-width: 0;\n}\n.mcpui-textarea { resize: vertical; min-height: 72px; font-family: var(--jini-mcpui-font); }\n.mcpui-checkbox { margin: 3px 0 0; accent-color: var(--jini-mcpui-accent); }\n.mcpui-choice-group { border: 0; padding: 0; margin: 0; min-width: 0; }\n.mcpui-choice { display: flex; flex-direction: row; align-items: flex-start; gap: 8px; margin: 6px 0 0; }\n.mcpui-choice-label { color: var(--jini-mcpui-text); font-weight: 400; }\n.mcpui-input:focus-visible, .mcpui-select:focus-visible, .mcpui-textarea:focus-visible,\n.mcpui-checkbox:focus-visible, .mcpui-button:focus-visible {\n  outline: 2px solid var(--jini-mcpui-accent-ring);\n  outline-offset: 1px;\n  border-color: var(--jini-mcpui-accent);\n}\n.mcpui-actions { display: flex; flex-wrap: wrap; gap: 8px; margin: 18px 0 0; }\n.mcpui-button {\n  font: inherit;\n  font-weight: 500;\n  padding: 7px 15px;\n  border-radius: var(--jini-mcpui-radius-pill);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));\n  background: var(--jini-mcpui-panel);\n  color: var(--jini-mcpui-text);\n  cursor: pointer;\n}\n.mcpui-button:hover:not([disabled]) { background: var(--jini-mcpui-accent-tint); }\n.mcpui-button-primary {\n  background: var(--jini-mcpui-accent);\n  border-color: var(--jini-mcpui-accent);\n  color: var(--jini-mcpui-panel);\n}\n.mcpui-button-primary:hover:not([disabled]) { background: var(--jini-mcpui-accent-hover); border-color: var(--jini-mcpui-accent-hover); }\n.mcpui-button-danger {\n  background: var(--jini-mcpui-danger);\n  border-color: var(--jini-mcpui-danger);\n  color: var(--jini-mcpui-panel);\n}\n.mcpui-button-danger:hover:not([disabled]) { background: var(--jini-mcpui-danger-hover); border-color: var(--jini-mcpui-danger-hover); }\n.mcpui-button[disabled] { opacity: 0.55; cursor: default; }\n.mcpui-status { margin: 12px 0 0; min-height: 1.4em; color: var(--jini-mcpui-text-muted); }\n.mcpui-status[data-state=\"failed\"], .mcpui-status[data-state=\"invalid\"] { color: var(--jini-mcpui-danger); }\n.mcpui-status[data-state=\"done\"] { color: var(--jini-mcpui-text-strong); }\n/* Neither a plain success nor a failure \u2014 e.g. an outcome surface reporting \"uploaded, not yet\n   reachable\" (outcome.ts's own state: partial). Distinct from both --jini-mcpui-danger (would\n   wrongly read as \"this failed\") and --jini-mcpui-text-strong (would wrongly read as \"this is\n   fully done\"); the accent token reads as \"worth a second look\" without asserting either. */\n.mcpui-status[data-state=\"partial\"] { color: var(--jini-mcpui-accent); }\n.mcpui-code { font-family: var(--jini-mcpui-font-mono); font-size: 13px; color: var(--jini-mcpui-text-faint); }";
+export declare const SURFACE_BASE_CSS = "*, *::before, *::after { box-sizing: border-box; }\nhtml, body { margin: 0; padding: 0; }\nbody {\n  /* Transparent, not var(--jini-mcpui-bg): this document has no page of its own to paint. It is an\n     allow-scripts-only sandboxed iframe embedded directly in a host's chat transcript, and html's\n     background is left at its (also transparent) initial value, so the host's own pane shows\n     straight through to .mcpui-surface below rather than through a second, unrelated rectangle of\n     fill color sitting between the two. --jini-mcpui-bg stays declared for a caller styling\n     something else via extraCss -- nothing in this stylesheet reads it anymore. */\n  background: transparent;\n  color: var(--jini-mcpui-text);\n  font-family: var(--jini-mcpui-font);\n  font-size: 14px;\n  line-height: 1.5;\n  padding: 16px;\n  -webkit-font-smoothing: antialiased;\n}\n.mcpui-surface {\n  background: linear-gradient(135deg,\n    color-mix(in srgb, var(--jini-mcpui-accent) 5%, var(--jini-mcpui-panel)) 0%,\n    var(--jini-mcpui-panel) 60%);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 18%, var(--jini-mcpui-border));\n  border-radius: var(--jini-mcpui-radius-md);\n  box-shadow: var(--jini-mcpui-surface-shadow);\n  padding: 18px 20px 16px;\n  max-width: 640px;\n  margin: 0 auto;\n}\n.mcpui-title {\n  margin: 0;\n  font-size: 16px;\n  font-weight: 600;\n  letter-spacing: -0.01em;\n  color: var(--jini-mcpui-text-strong);\n}\n.mcpui-description { margin: 6px 0 0; color: var(--jini-mcpui-text-muted); }\n.mcpui-details {\n  display: grid;\n  grid-template-columns: max-content minmax(0, 1fr);\n  gap: 4px 14px;\n  margin: 14px 0 0;\n}\n.mcpui-details dt { color: var(--jini-mcpui-text-soft); font-weight: 500; }\n.mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }\n.mcpui-warning {\n  margin: 14px 0 0;\n  padding: 9px 11px;\n  border-radius: var(--jini-mcpui-radius-md);\n  border: 1px solid var(--jini-mcpui-danger);\n  background: var(--jini-mcpui-danger-tint);\n  color: var(--jini-mcpui-text-strong);\n}\n.mcpui-fields { display: flex; flex-direction: column; gap: 12px; margin: 16px 0 0; border: 0; padding: 0; }\n.mcpui-field { display: flex; flex-direction: column; gap: 4px; }\n.mcpui-field-inline { flex-direction: row; align-items: flex-start; gap: 8px; }\n.mcpui-label { font-weight: 500; color: var(--jini-mcpui-text-strong); }\n.mcpui-required { color: var(--jini-mcpui-accent); margin-left: 2px; }\n.mcpui-hint { color: var(--jini-mcpui-text-soft); font-size: 13px; }\n.mcpui-input, .mcpui-select, .mcpui-textarea {\n  font: inherit;\n  color: var(--jini-mcpui-text);\n  background: var(--jini-mcpui-panel);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));\n  border-radius: var(--jini-mcpui-radius-sm);\n  padding: 7px 9px;\n  width: 100%;\n  min-width: 0;\n}\n.mcpui-textarea { resize: vertical; min-height: 72px; font-family: var(--jini-mcpui-font); }\n.mcpui-checkbox { margin: 3px 0 0; accent-color: var(--jini-mcpui-accent); }\n.mcpui-choice-group { border: 0; padding: 0; margin: 0; min-width: 0; }\n.mcpui-choice { display: flex; flex-direction: row; align-items: flex-start; gap: 8px; margin: 6px 0 0; }\n.mcpui-choice-label { color: var(--jini-mcpui-text); font-weight: 400; }\n.mcpui-input:focus-visible, .mcpui-select:focus-visible, .mcpui-textarea:focus-visible,\n.mcpui-checkbox:focus-visible, .mcpui-button:focus-visible {\n  outline: 2px solid var(--jini-mcpui-accent-ring);\n  outline-offset: 1px;\n  border-color: var(--jini-mcpui-accent);\n}\n.mcpui-actions { display: flex; flex-wrap: wrap; gap: 8px; margin: 18px 0 0; }\n.mcpui-button {\n  font: inherit;\n  font-weight: 500;\n  padding: 7px 15px;\n  border-radius: var(--jini-mcpui-radius-pill);\n  border: 1px solid color-mix(in srgb, var(--jini-mcpui-accent) 14%, var(--jini-mcpui-border-strong));\n  background: var(--jini-mcpui-panel);\n  color: var(--jini-mcpui-text);\n  cursor: pointer;\n}\n.mcpui-button:hover:not([disabled]) { background: var(--jini-mcpui-accent-tint); }\n.mcpui-button-primary {\n  background: var(--jini-mcpui-accent);\n  border-color: var(--jini-mcpui-accent);\n  color: var(--jini-mcpui-panel);\n}\n.mcpui-button-primary:hover:not([disabled]) { background: var(--jini-mcpui-accent-hover); border-color: var(--jini-mcpui-accent-hover); }\n.mcpui-button-danger {\n  background: var(--jini-mcpui-danger);\n  border-color: var(--jini-mcpui-danger);\n  color: var(--jini-mcpui-panel);\n}\n.mcpui-button-danger:hover:not([disabled]) { background: var(--jini-mcpui-danger-hover); border-color: var(--jini-mcpui-danger-hover); }\n.mcpui-button[disabled] { opacity: 0.55; cursor: default; }\n.mcpui-status { margin: 12px 0 0; min-height: 1.4em; color: var(--jini-mcpui-text-muted); }\n.mcpui-status[data-state=\"failed\"], .mcpui-status[data-state=\"invalid\"], .mcpui-status[data-state=\"expired\"] { color: var(--jini-mcpui-danger); }\n.mcpui-status[data-state=\"done\"] { color: var(--jini-mcpui-text-strong); }\n/* Neither a plain success nor a failure \u2014 e.g. an outcome surface reporting \"uploaded, not yet\n   reachable\" (outcome.ts's own state: partial). Distinct from both --jini-mcpui-danger (would\n   wrongly read as \"this failed\") and --jini-mcpui-text-strong (would wrongly read as \"this is\n   fully done\"); the accent token reads as \"worth a second look\" without asserting either. */\n.mcpui-status[data-state=\"partial\"] { color: var(--jini-mcpui-accent); }\n.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>`.
  *
@@ -76,6 +76,12 @@ export interface SurfaceDetail {
 export declare function renderDetailList(details: readonly SurfaceDetail[]): string;
 /** Renders the polite live region every surface reports outcomes through. Its id is fixed so surface scripts can find it. */
 export declare function renderStatusRegion(): string;
+/**
+ * The `error.data.code` a Host relays when the dialog a call came from is no longer waiting for an
+ * answer (answered elsewhere, expired, or its run is gone). Retrying cannot succeed, so a surface
+ * that sees it keeps its buttons disabled instead of re-arming them.
+ */
+export declare const SURFACE_NOT_PENDING_ERROR_CODE = "SURFACE_NOT_PENDING";
 /** The id {@link renderStatusRegion} emits and {@link SURFACE_SCRIPT_PRELUDE} looks up. */
 export declare const SURFACE_STATUS_ELEMENT_ID = "mcpui-status";
 /**
@@ -96,6 +102,8 @@ export interface SurfaceStatusText {
     readonly dismissed: string;
     /** Prefixed to the comma-joined labels of unfilled required fields. */
     readonly missingPrefix: string;
+    /** Shown when the Host says the dialog is no longer pending; the buttons stay disabled. */
+    readonly expired: string;
 }
 export declare const DEFAULT_SURFACE_STATUS_TEXT: SurfaceStatusText;
 /**
@@ -150,6 +158,8 @@ export interface SurfaceAction {
      * than that sandbox; every current builder passes `button` (the default).
      */
     readonly type?: 'button' | 'submit';
+    /** Renders the button `disabled`; the surface script decides when to enable it. */
+    readonly disabled?: boolean;
 }
 /**
  * Renders the action row.

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

@@ -128,7 +128,7 @@ body {
 .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="failed"], .mcpui-status[data-state="invalid"], .mcpui-status[data-state="expired"] { 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
@@ -217,6 +217,12 @@ export function renderDetailList(details) {
 export function renderStatusRegion() {
     return `<p class="mcpui-status" id="${SURFACE_STATUS_ELEMENT_ID}" role="status" aria-live="polite" data-state="idle"></p>`;
 }
+/**
+ * The `error.data.code` a Host relays when the dialog a call came from is no longer waiting for an
+ * answer (answered elsewhere, expired, or its run is gone). Retrying cannot succeed, so a surface
+ * that sees it keeps its buttons disabled instead of re-arming them.
+ */
+export const SURFACE_NOT_PENDING_ERROR_CODE = 'SURFACE_NOT_PENDING';
 /** 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 = {
@@ -225,6 +231,7 @@ export const DEFAULT_SURFACE_STATUS_TEXT = {
     failedPrefix: 'Failed: ',
     dismissed: 'Dismissed.',
     missingPrefix: 'Please complete: ',
+    expired: 'This dialog expired. Ask again.',
 };
 /**
  * The JavaScript preamble every surface script opens with: the bridge handle, the status region,
@@ -248,6 +255,19 @@ function setBusy(busy) {
 }
 function describeError(error) {
   return error && typeof error.message === "string" ? error.message : String(error);
+}
+// Reports a rejected tool call and returns whether the human may try again. A rejected call did not
+// happen, so normally the buttons re-arm; but a dialog the Host no longer waits on cannot succeed,
+// and live-looking buttons there only invite clicks that fail the same way. Reads TEXT, which each
+// surface script declares after this prelude.
+function reportCallFailure(error) {
+  if (error && error.data && error.data.code === ${JSON.stringify(SURFACE_NOT_PENDING_ERROR_CODE)}) {
+    setStatus(TEXT.expired, "expired");
+    return false;
+  }
+  setBusy(false);
+  setStatus(TEXT.failedPrefix + describeError(error), "failed");
+  return true;
 }`;
 /**
  * A field name that is simultaneously an HTML `name`, part of a DOM `id`, and a key in the JSON
@@ -319,7 +339,7 @@ export function renderActions(actions) {
         // 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>`;
+        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}"${action.disabled === true ? ' disabled' : ''}>${label}</button>`;
     })
         .join('\n');
     return `<div class="mcpui-actions">\n${buttons}\n</div>`;

package/dist/features/mcp-ui/surfaces/form.js

@@ -120,7 +120,8 @@ ${SURFACE_SCRIPT_PRELUDE}
   //
   // Deliberately NOT cleared on success -- the success path tears the surface down, so re-arming
   // would only reopen the window. Cleared on failure, matching what setBusy(false) already does
-  // there: a rejected call did not happen, and the human must be able to retry.
+  // there: a rejected call did not happen, and the human must be able to retry -- unless the Host
+  // says the dialog is no longer pending, where a retry cannot succeed (see reportCallFailure).
   var pending = false;
 
   function runSubmit() {
@@ -145,9 +146,7 @@ ${SURFACE_SCRIPT_PRELUDE}
       setStatus(TEXT.done, "done");
       api.requestTeardown();
     }, function (error) {
-      pending = false;
-      setBusy(false);
-      setStatus(TEXT.failedPrefix + describeError(error), "failed");
+      if (reportCallFailure(error)) pending = false;
     });
   }
 
@@ -155,8 +154,10 @@ ${SURFACE_SCRIPT_PRELUDE}
   // native behavior a single-line text input gets inside a real form. Scoped to the same controls
   // the browser would have honored it for -- type=text/type=number inputs -- so Enter still inserts
   // a newline in a multi-line textarea and still just toggles a checkbox.
+  // Only what the browser attributes to a person counts: element.click(), dispatchEvent and a
+  // synthetic keydown from any script produce isTrusted === false, and submit and cancel call tools.
   form.addEventListener("keydown", function (event) {
-    if (event.key !== "Enter") return;
+    if (event.isTrusted !== true || event.key !== "Enter") return;
     var target = event.target;
     if (!target || target.tagName !== "INPUT") return;
     var type = (target.getAttribute("type") || "text").toLowerCase();
@@ -168,12 +169,14 @@ ${SURFACE_SCRIPT_PRELUDE}
   for (var b = 0; b < actionButtons.length; b++) {
     var action = actionButtons[b].getAttribute("data-mcpui-action");
     if (action === "submit") {
-      actionButtons[b].addEventListener("click", runSubmit);
+      actionButtons[b].addEventListener("click", function (event) {
+        if (event.isTrusted === true) runSubmit();
+      });
       continue;
     }
     if (action !== "cancel") continue;
-    actionButtons[b].addEventListener("click", function () {
-      if (pending) return;
+    actionButtons[b].addEventListener("click", function (event) {
+      if (event.isTrusted !== true || pending) return;
       pending = true;
       setBusy(true);
       if (CANCEL === null) {
@@ -186,9 +189,7 @@ ${SURFACE_SCRIPT_PRELUDE}
         setStatus(TEXT.dismissed, "dismissed");
         api.requestTeardown();
       }, function (error) {
-        pending = false;
-        setBusy(false);
-        setStatus(TEXT.failedPrefix + describeError(error), "failed");
+        if (reportCallFailure(error)) pending = false;
       });
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/ui",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Generic, product-neutral React UI primitives and feature domains. Framework-free types, decision rules, catalogs, and host port contracts live behind ./core (no React, no DOM). The Excalidraw and Lexical editors live behind ./sketch-editor and ./lexical-rich-text-editor; the GrapesJS-backed inline HTML editor lives behind ./html-editor.",
   "license": "Apache-2.0",
   "repository": {
@@ -107,8 +107,8 @@
     "shiki": "^1.24.4",
     "tailwind-merge": "^2.6.0",
     "zod": "^3.25.76",
-    "@jini-ai/agentic": "0.3.6",
     "@jini-ai/platform": "0.3.0",
+    "@jini-ai/agentic": "0.3.6",
     "@jini-ai/protocol": "0.3.0"
   },
   "devDependencies": {