@jini-ai/ui 0.6.15-rc.2 → 0.6.16

package/dist/features/integrations/react/components/IntegrationsTab.js

@@ -96,7 +96,9 @@ function DeeplinkInstallRow({ deeplink, info, agentHandle }) {
 /** The generated snippet, or a loading / could-not-resolve placeholder while there is none. */
 function InstallSnippet({ resolved, loading, error }) {
     const t = useT();
-    return (_jsx(SnippetBlock, { snippet: resolved?.snippet ?? '', language: resolved?.language ?? 'json', placeholder: loading ? t('Loading install paths…') : error ? t('Could not resolve install paths.') : '' }));
+    const errorPlaceholder = error ? t('Could not resolve install paths.') : '';
+    const placeholder = loading ? t('Loading install paths…') : errorPlaceholder;
+    return (_jsx(SnippetBlock, { snippet: resolved?.snippet ?? '', language: resolved?.language ?? 'json', placeholder: placeholder }));
 }
 /** Build/Node warning, shown only once install info has loaded and reports a missing prerequisite. */
 function PrerequisiteWarning({ info }) {

package/dist/features/integrations/rules.js

@@ -1,3 +1,4 @@
+import { unhandledCase } from '../../utils/unhandled-case.js';
 /** Path hint per OS — a Windows user shouldn't see a `~/...` path their
  *  shell won't expand, and vice versa. */
 export function homeConfigPath(platform, posix, windows) {
@@ -36,7 +37,8 @@ export function buildCodexEnvToml(serverName, info) {
     const entries = Object.entries(info.env ?? {});
     if (entries.length === 0)
         return '';
-    return `\n\n[mcp_servers.${serverName}.env]\n${entries.map(([key, value]) => `${key} = ${JSON.stringify(value)}`).join('\n')}`;
+    const lines = entries.map(([key, value]) => `${key} = ${JSON.stringify(value)}`).join('\n');
+    return `\n\n[mcp_servers.${serverName}.env]\n${lines}`;
 }
 /** The `{"mcpServers": {"<serverName>": {...}}}` shape shared by Cursor,
  *  Antigravity, and Windsurf. */
@@ -186,8 +188,8 @@ export function snippetForClient(clientId, serverName, info) {
     // refactored away rather than kept behind a coverage-suppression comment.
     // TypeScript still catches a missing case if `McpClientId` grows a member
     // and only `methodLabelForClient` gets updated: with every current case
-    // returning, `tsc` requires this switch to be exhaustive too, or the
-    // function's declared `McpClientSnippet` return type is violated on the
-    // "falls through" path.
+    // returning, `unhandledCase`'s `never` parameter makes `tsc` require this
+    // switch to be exhaustive too.
+    return unhandledCase(clientId);
 }
 //# sourceMappingURL=rules.js.map

package/dist/features/interactive-ui/providers/shadcn/data-table.js

@@ -2,6 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from 'react';
 import { getNumericColumnKeys, sortTableRows } from '../../table-data.js';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from './table.js';
+/** Header glyph per column sort state; `none` marks a sortable but unsorted column. */
+const SORT_GLYPHS = { ascending: '↑', descending: '↓', none: '↕' };
 function resolveTablePage({ pageSize, rowCount, requestedPage }, _options = {}) {
     const requestedSize = pageSize !== undefined && Number.isInteger(pageSize) && pageSize > 0 ? pageSize : null;
     const paging = requestedSize !== null;
@@ -20,11 +22,14 @@ export function DataTable({ columns, rows, onRowClick, sortable = true, pageSize
     const sortedRows = useMemo(() => sortTableRows({ rows, sort: activeSort, numericKeys }), [rows, activeSort, numericKeys]);
     const { paging, size, pageCount, page, start } = resolveTablePage({ pageSize, rowCount: rows.length, requestedPage });
     const visibleRows = sortedRows.slice(start, start + size);
-    return (_jsxs("div", { className: "jini-data-table-frame", "data-table-provider": "shadcn", children: [_jsxs(Table, { className: "jini-data-table", children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => (_jsx(TableHead, { scope: "col", "data-numeric": numericKeys.has(column.key), "aria-sort": sortable ? (activeSort?.key === column.key ? activeSort.direction : 'none') : undefined, children: sortable ? (_jsxs("button", { type: "button", className: "jini-data-table-sort", onClick: () => {
-                                        setSort({ key: column.key, direction: activeSort?.key === column.key && activeSort.direction === 'ascending'
-                                                ? 'descending' : 'ascending' });
-                                        setPage(0);
-                                    }, children: [_jsx("span", { children: column.label }), _jsx("span", { "aria-hidden": "true", children: activeSort?.key === column.key ? (activeSort.direction === 'ascending' ? '↑' : '↓') : '↕' })] })) : column.label }, column.key))) }) }), _jsxs(TableBody, { children: [rows.length === 0 && _jsx(TableRow, { children: _jsx(TableCell, { className: "jini-data-table-empty", colSpan: columns.length, children: "No results." }) }), visibleRows.map(({ row, index }) => (_jsx(TableRow, { onClick: onRowClick ? () => onRowClick(row, index) : undefined, role: onRowClick ? 'button' : undefined, tabIndex: onRowClick ? 0 : undefined, onKeyDown: onRowClick ? (event) => {
+    return (_jsxs("div", { className: "jini-data-table-frame", "data-table-provider": "shadcn", children: [_jsxs(Table, { className: "jini-data-table", children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => {
+                                const columnSort = activeSort?.key === column.key ? activeSort.direction : undefined;
+                                return (_jsx(TableHead, { scope: "col", "data-numeric": numericKeys.has(column.key), "aria-sort": sortable ? (columnSort ?? 'none') : undefined, children: sortable ? (_jsxs("button", { type: "button", className: "jini-data-table-sort", onClick: () => {
+                                            setSort({ key: column.key, direction: activeSort?.key === column.key && activeSort.direction === 'ascending'
+                                                    ? 'descending' : 'ascending' });
+                                            setPage(0);
+                                        }, children: [_jsx("span", { children: column.label }), _jsx("span", { "aria-hidden": "true", children: SORT_GLYPHS[columnSort ?? 'none'] })] })) : column.label }, column.key));
+                            }) }) }), _jsxs(TableBody, { children: [rows.length === 0 && _jsx(TableRow, { children: _jsx(TableCell, { className: "jini-data-table-empty", colSpan: columns.length, children: "No results." }) }), visibleRows.map(({ row, index }) => (_jsx(TableRow, { onClick: onRowClick ? () => onRowClick(row, index) : undefined, role: onRowClick ? 'button' : undefined, tabIndex: onRowClick ? 0 : undefined, onKeyDown: onRowClick ? (event) => {
                                     if (event.target === event.currentTarget && (event.key === 'Enter' || event.key === ' ')) {
                                         event.preventDefault();
                                         onRowClick(row, index);

package/dist/features/interactive-ui/table-data.js

@@ -1,7 +1,7 @@
 function isNumericValue(value) {
     if (typeof value === 'number')
         return Number.isFinite(value);
-    return typeof value === 'string' && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(value.trim())
+    return typeof value === 'string' && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value.trim())
         && Number.isFinite(Number(value));
 }
 /** Infer numeric columns once for both providers; empty cells do not turn a numeric column into text.

package/dist/features/lexical-rich-text-editor/deserialize.js

@@ -37,10 +37,10 @@ export function setRichTextFromPlainText(editor, text, knownMentions) {
                         label: part.entity.label,
                         title: part.entity.title,
                     }));
+                    continue;
                 }
-                else if (part.text) {
+                if (part.text)
                     p.append($createTextNode(part.text));
-                }
             }
         });
         root.append(p);

package/dist/features/lexical-rich-text-editor/mention-parser.js

@@ -232,10 +232,10 @@ export function foldPresentMentions(text, present, known) {
         if (part.kind !== 'mention' || part.entity.kind === 'unknown')
             continue;
         const key = `${part.entity.kind}:${part.entity.id}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        result.push(part.entity);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(part.entity);
+        }
     }
     return result;
 }

package/dist/features/lexical-rich-text-editor/react/components/RichTextInput.js

@@ -68,6 +68,7 @@ function EditorSurface(props, ref) {
             }, { discrete: true });
         },
         insertMention(insert) {
+            const isActiveTrigger = (trigger) => trigger.id === mentionTriggerIdRef.current;
             editor.update(() => {
                 let sel = $getSelection();
                 if (!$isRangeSelection(sel)) {
@@ -80,7 +81,7 @@ function EditorSurface(props, ref) {
                 // The cast documents that instead of an unreachable
                 // early-return branch no real document state can trigger.
                 const rangeSel = sel;
-                const mentionTrigger = triggersRef.current.find((t) => t.id === mentionTriggerIdRef.current) ??
+                const mentionTrigger = triggersRef.current.find(isActiveTrigger) ??
                     triggersRef.current[0];
                 if (mentionTrigger) {
                     deleteActiveTrigger(rangeSel, buildTriggerDeletionRegex(mentionTrigger));

package/dist/features/lexical-rich-text-editor/react/hooks/useCaretFloatingLayerPosition.js

@@ -30,7 +30,7 @@ export function useCaretFloatingLayerPosition(caret, open, boundaryRef) {
     }, [open, caret, reposition]);
     useEffect(() => {
         if (!open)
-            return;
+            return undefined;
         let raf = 0;
         const onMove = () => {
             if (raf)

package/dist/features/lexical-rich-text-editor/react/hooks/useMentionColorStamping.js

@@ -23,7 +23,7 @@ export function useMentionColorStamping(resolveMentionColor) {
     const [editor] = useLexicalComposerContext();
     useEffect(() => {
         if (!resolveMentionColor)
-            return;
+            return undefined;
         const stampByKey = (key) => {
             const dom = editor.getElementByKey(key);
             if (!dom)

package/dist/features/lexical-rich-text-editor/serialize.js

@@ -26,17 +26,20 @@ export function serializeRichText(state) {
 function serializeParagraph(at) {
     let line = '';
     for (const child of at.paragraph.getChildren()) {
-        if ($isMentionNode(child)) {
-            line += child.getToken();
-            at.mentions.push(child.getEntity());
-        }
-        else if ($isLineBreakNode(child)) {
-            line += '\n';
-        }
-        else if ($isTextNode(child) || $isElementNode(child)) {
-            line += child.getTextContent();
-        }
+        line += serializedChildText(child, at.mentions);
     }
     return line;
 }
+/** One paragraph child's plain-text contribution; a mention also records its entity. Other node kinds add nothing. */
+function serializedChildText(child, mentions) {
+    if ($isMentionNode(child)) {
+        mentions.push(child.getEntity());
+        return child.getToken();
+    }
+    if ($isLineBreakNode(child))
+        return '\n';
+    if ($isTextNode(child) || $isElementNode(child))
+        return child.getTextContent();
+    return '';
+}
 //# sourceMappingURL=serialize.js.map

package/dist/features/list-detail-panel/react/components/ListDetailPanel.js

@@ -18,6 +18,6 @@ export function ListDetailPanel({ items, selectedId, onSelect, renderItem, rende
                                 const state = { active };
                                 const resolvedItemClassName = typeof itemClassName === 'function' ? itemClassName(item, state) : itemClassName;
                                 return (_jsx("button", { type: "button", className: join('jini-list-detail-panel-item', active && 'jini-list-detail-panel-item-active', resolvedItemClassName), "aria-pressed": active, "aria-label": getItemAriaLabel?.(item), "data-active": active, "data-testid": `${testId}-item-${item.id}`, onClick: () => onSelect(item.id), children: renderItem(item, state) }, item.id));
-                            }) }))] }), _jsx("section", { className: join('jini-list-detail-panel-detail', detailClassName), "data-testid": `${testId}-detail`, children: loading ? (_jsx("div", { className: "jini-list-detail-panel-loading-detail", role: "status", "aria-busy": "true", "aria-label": t('Loading'), "data-testid": `${testId}-loading-detail`, children: loadingDetailContent })) : selectedItem ? (renderDetail(selectedItem)) : (emptyDetailContent) })] }));
+                            }) }))] }), _jsxs("section", { className: join('jini-list-detail-panel-detail', detailClassName), "data-testid": `${testId}-detail`, children: [loading ? (_jsx("div", { className: "jini-list-detail-panel-loading-detail", role: "status", "aria-busy": "true", "aria-label": t('Loading'), "data-testid": `${testId}-loading-detail`, children: loadingDetailContent })) : null, !loading && selectedItem ? renderDetail(selectedItem) : null, !loading && !selectedItem ? emptyDetailContent : null] })] }));
 }
 //# sourceMappingURL=ListDetailPanel.js.map

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

@@ -1,3 +1,4 @@
+import { trimTrailingChars } from '../../utils/trim-chars.js';
 /**
  * @module features/mcp-ui/confirmation-store
  *
@@ -66,11 +67,7 @@ function bindingsMatch(minted, presented) {
         // does not — the type check below is what keeps those apart, and it is exact on purpose: a
         // binding that silently coerces is a binding that can be satisfied by a value the minter never
         // agreed to.
-        if (typeof left !== typeof right) {
-            matched = false;
-            continue;
-        }
-        if (!constantTimeEquals(String(left), String(right)))
+        if (typeof left !== typeof right || !constantTimeEquals(String(left), String(right)))
             matched = false;
     }
     return matched;
@@ -89,7 +86,7 @@ function defaultRandomToken() {
     let binary = '';
     for (const byte of bytes)
         binary += String.fromCharCode(byte);
-    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    return trimTrailingChars(btoa(binary).replace(/\+/g, '-').replace(/\//g, '_'), '=');
 }
 /**
  * Creates an in-process confirmation store.

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

@@ -13,6 +13,8 @@ export interface CheckboxProps {
      */
     readonly required?: boolean;
     readonly disabled?: boolean;
+    /** Visually hide the label (it repeats the card title); it stays the accessible name. */
+    readonly labelHidden?: 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

package/dist/features/mcp-ui/surfaces/choice-group.d.ts

@@ -22,6 +22,8 @@ export interface ChoiceGroupProps {
      */
     readonly required?: boolean;
     readonly disabled?: boolean;
+    /** Visually hide the legend (it repeats the card title); it stays the group's accessible name. */
+    readonly labelHidden?: boolean;
 }
 /**
  * Renders one grouped-choice field.

package/dist/features/mcp-ui/surfaces/choice-group.js

@@ -30,7 +30,7 @@
  * value unless normalised — see `form.ts`'s `readChecked`, which is written against this fact.
  */
 import { escapeHtml } from '../escape.js';
-import { fieldElementId } from './document.js';
+import { fieldElementId, VISUALLY_HIDDEN_CLASS } from './document.js';
 /**
  * Renders one grouped-choice field.
  *
@@ -63,7 +63,7 @@ export function renderChoiceGroup(props) {
     })
         .join('\n');
     return (`<fieldset class="mcpui-field mcpui-choice-group"${describedBy}>\n` +
-        `<legend class="mcpui-label">${escapeHtml(props.label)}${required}</legend>${hint}\n` +
+        `<legend class="mcpui-label${props.labelHidden === true ? ` ${VISUALLY_HIDDEN_CLASS}` : ''}">${escapeHtml(props.label)}${required}</legend>${hint}\n` +
         `${options}\n` +
         `</fieldset>`);
 }

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

@@ -67,6 +67,11 @@ export interface ConfirmationSurfaceSpec {
     readonly description?: string;
     /** The facts being agreed about. A dialog that says "delete this?" without naming *this* is not consent. */
     readonly details?: readonly SurfaceDetail[];
+    /** Technical identifiers and input stay available without crowding out the consent wording. */
+    readonly detailDisclosure?: {
+        readonly label: string;
+        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

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

@@ -133,6 +133,7 @@ function confirmationBodyHtml(spec, required) {
     return [
         renderSurfaceHeader(spec.description === undefined ? { title: spec.title } : { title: spec.title, description: spec.description }),
         renderDetailList(spec.details ?? []),
+        spec.detailDisclosure === undefined ? '' : `<details class="mcpui-detail-disclosure mcpui-technical-details"><summary aria-expanded="false">${escapeHtml(spec.detailDisclosure.label)}</summary>${renderDetailList(spec.detailDisclosure.details)}</details>`,
         renderChoices(spec.choices ?? []),
         warning,
         // Confirm starts disabled; the script enables it once the dwell has run out.

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

@@ -1,5 +1,7 @@
 import { type BridgeScriptSpec } from './bridge.js';
 import { type SurfaceTokenName } from './tokens.js';
+import { type SurfaceDetail } from './structured-details.js';
+export type { SurfaceDetail } from './structured-details.js';
 /**
  * The base stylesheet, applied after the token block.
  *
@@ -8,7 +10,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/* fit-content(40%), not max-content: one long label used to take the whole row and squeeze every\n   value to one character per line. Labels wrap at 40% instead. */\n.mcpui-details {\n  display: grid;\n  grid-template-columns: fit-content(40%) 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; overflow-wrap: anywhere; }\n.mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }\n.mcpui-details-outcome { display: flex; flex-direction: column; gap: 8px; }\n.mcpui-outcome-row { display: flex; align-items: flex-start; gap: 14px; }\n.mcpui-outcome-row dt { flex: 1; min-width: 0; overflow-wrap: anywhere; }\n.mcpui-outcome-row dt .mcpui-hint { display: block; font-weight: 400; }\n.mcpui-outcome-row dd { flex: 1; min-width: 0; }\n/* Capped so a long status cannot squeeze the label back to one character per line; the full text\n   stays in the cell's title. */\n.mcpui-outcome-row dd.mcpui-detail-status {\n  flex: 0 1 auto; max-width: 60%; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;\n}\n/* Frames up to 480px: stack each label above its value so the value gets the full width.\n   Outcome lists keep their own row layout. */\n@media (max-width: 480px) {\n  .mcpui-details:not(.mcpui-details-outcome) { grid-template-columns: minmax(0, 1fr); row-gap: 0; }\n  .mcpui-details:not(.mcpui-details-outcome) dd { margin-bottom: 8px; }\n}\n/* The iframe has 16px body padding on each side: 352px viewport = 320px card. Stacked, the value\n   has the full width, so it wraps between words instead of truncating. */\n@media (max-width: 352px) {\n  .mcpui-outcome-row { flex-direction: column; gap: 2px; }\n  .mcpui-outcome-row dd.mcpui-detail-status { max-width: 100%; white-space: normal; overflow-wrap: normal; }\n}\n.mcpui-code {\n  margin: 0;\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n  max-height: 16em;\n  overflow: auto;\n  font-family: var(--jini-mcpui-font-mono);\n  font-size: 12.5px;\n  line-height: 1.45;\n  padding: 6px 8px;\n  border: 1px solid var(--jini-mcpui-border);\n  border-radius: var(--jini-mcpui-radius-sm);\n  background: var(--jini-mcpui-bg);\n}\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/* A secret control's eye toggle sits inside the field's right edge. The control is padded so long\n   values never run under it; the button is a 40px tap target centred on the input, transparent,\n   so it overhangs the ~36px input invisibly instead of resizing the field. */\n.mcpui-secret { position: relative; display: flex; flex-direction: column; }\n.mcpui-secret > .mcpui-input, .mcpui-secret > .mcpui-textarea { padding-right: 44px; }\n.mcpui-secret-toggle {\n  position: absolute;\n  top: 50%;\n  right: 0;\n  width: 40px;\n  height: 40px;\n  margin-top: -20px;\n  padding: 0;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  border: 0;\n  border-radius: var(--jini-mcpui-radius-sm);\n  background: transparent;\n  color: var(--jini-mcpui-text-soft);\n  cursor: pointer;\n}\n.mcpui-secret > .mcpui-textarea + .mcpui-secret-toggle { top: 0; margin-top: -2px; }\n.mcpui-secret-toggle:hover:not([disabled]) { color: var(--jini-mcpui-text-strong); }\n.mcpui-secret-toggle[disabled] { opacity: 0.55; cursor: default; }\n.mcpui-secret-toggle:focus-visible { outline: 2px solid var(--jini-mcpui-accent-ring); outline-offset: -6px; }\n.mcpui-secret-toggle[aria-pressed=\"true\"] .mcpui-secret-icon-show,\n.mcpui-secret-toggle:not([aria-pressed=\"true\"]) .mcpui-secret-icon-hide { display: none; }\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-accent-ink);\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); }";
+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/* fit-content(40%), not max-content: one long label used to take the whole row and squeeze every\n   value to one character per line. Labels wrap at 40% instead. */\n.mcpui-details {\n  display: grid;\n  grid-template-columns: fit-content(40%) 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; overflow-wrap: anywhere; }\n.mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }\n.mcpui-details dt .mcpui-hint { display: block; font-weight: 400; }\n/* A nested group (a tool's input fields) gets the card's full width, not the narrow value column. */\n.mcpui-details > dt:has(+ dd > .mcpui-detail-group),\n.mcpui-details > dd:has(> .mcpui-detail-group) { grid-column: 1 / -1; }\n.mcpui-details > dt:has(+ dd > .mcpui-detail-group) { margin-bottom: 6px; }\n.mcpui-details-outcome { display: flex; flex-direction: column; gap: 8px; }\n.mcpui-outcome-row { display: flex; align-items: flex-start; gap: 14px; }\n.mcpui-outcome-row dt { flex: 1; min-width: 0; overflow-wrap: anywhere; }\n.mcpui-outcome-row dt .mcpui-hint { display: block; font-weight: 400; }\n.mcpui-outcome-row dd { flex: 1; min-width: 0; }\n/* Capped so a long status cannot squeeze the label back to one character per line; the full text\n   stays in the cell's title. */\n.mcpui-outcome-row dd.mcpui-detail-status {\n  flex: 0 1 auto; max-width: 60%; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;\n}\n/* Frames up to 480px: stack each label above its value so the value gets the full width.\n   Outcome lists keep their own row layout. */\n@media (max-width: 480px) {\n  .mcpui-details:not(.mcpui-details-outcome) { grid-template-columns: minmax(0, 1fr); row-gap: 0; }\n  .mcpui-details:not(.mcpui-details-outcome) dd { margin-bottom: 8px; }\n}\n/* The iframe has 16px body padding on each side: 352px viewport = 320px card. Stacked, the value\n   has the full width, so it wraps between words instead of truncating. */\n@media (max-width: 352px) {\n  .mcpui-outcome-row { flex-direction: column; gap: 2px; }\n  .mcpui-outcome-row dd.mcpui-detail-status { max-width: 100%; white-space: normal; overflow-wrap: normal; }\n}\n.mcpui-code {\n  margin: 0;\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n  max-height: 16em;\n  overflow: auto;\n  font-family: var(--jini-mcpui-font-mono);\n  font-size: 12.5px;\n  line-height: 1.45;\n  padding: 6px 8px;\n  border: 1px solid var(--jini-mcpui-border);\n  border-radius: var(--jini-mcpui-radius-sm);\n  background: var(--jini-mcpui-bg);\n}\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-visually-hidden { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }\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/* A secret control's eye toggle sits inside the field's right edge. The control is padded so long\n   values never run under it; the button is a 40px tap target centred on the input, transparent,\n   so it overhangs the ~36px input invisibly instead of resizing the field. */\n.mcpui-secret { position: relative; display: flex; flex-direction: column; }\n.mcpui-secret > .mcpui-input, .mcpui-secret > .mcpui-textarea { padding-right: 44px; }\n.mcpui-secret-toggle {\n  position: absolute;\n  top: 50%;\n  right: 0;\n  width: 40px;\n  height: 40px;\n  margin-top: -20px;\n  padding: 0;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  border: 0;\n  border-radius: var(--jini-mcpui-radius-sm);\n  background: transparent;\n  color: var(--jini-mcpui-text-soft);\n  cursor: pointer;\n}\n.mcpui-secret > .mcpui-textarea + .mcpui-secret-toggle { top: 0; margin-top: -2px; }\n.mcpui-secret-toggle:hover:not([disabled]) { color: var(--jini-mcpui-text-strong); }\n.mcpui-secret-toggle[disabled] { opacity: 0.55; cursor: default; }\n.mcpui-secret-toggle:focus-visible { outline: 2px solid var(--jini-mcpui-accent-ring); outline-offset: -6px; }\n.mcpui-secret-toggle[aria-pressed=\"true\"] .mcpui-secret-icon-show,\n.mcpui-secret-toggle:not([aria-pressed=\"true\"]) .mcpui-secret-icon-hide { display: none; }\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-accent-ink);\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>`.
  *
@@ -62,27 +64,13 @@ export declare function renderSurfaceHeader(spec: {
     title: string;
     description?: string;
 }): string;
-/** One row of a surface's detail list. */
-export interface SurfaceDetail {
-    readonly label: string;
-    readonly value: string;
-    /** Optional secondary context beneath the label, using the shared muted hint style. */
-    readonly description?: string;
-    /**
-     * `code` renders the value in a monospace `<pre>` that keeps its line breaks and scrolls inside
-     * its own box past a fixed height, so a long SQL statement or JSON argument stays readable without
-     * stretching the dialog past its frame. `status` reserves one line for a short outcome value.
-     * Omitted (or `text`) keeps the plain inline value.
-     */
-    readonly format?: 'text' | 'code' | 'status';
-}
 /**
  * Renders a `label: value` description list.
  *
  * @param options.layout - Outcome rows size independently and stack in narrow cards.
  * @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.
- * @complexity O(n) in the rendered length; no effects or input mutation.
+ * @complexity O(n * depth) with previous snapshots, otherwise O(n) rendered bytes; no effects or input mutation.
  */
 export declare function renderDetailList(details: readonly SurfaceDetail[], options?: {
     layout?: 'outcome';
@@ -130,6 +118,14 @@ export declare const DEFAULT_SURFACE_STATUS_TEXT: SurfaceStatusText;
  * the builders make no assumption about it beyond ES5.
  */
 export declare const SURFACE_SCRIPT_PRELUDE: string;
+/**
+ * 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.
+ */
+/** Hides an element visually while keeping it in the accessibility tree (see `.mcpui-visually-hidden` in {@link SURFACE_BASE_CSS}). */
+export declare const VISUALLY_HIDDEN_CLASS = "mcpui-visually-hidden";
 /**
  * Builds the DOM id for a field's control, validating the name on the way through.
  *
@@ -148,6 +144,8 @@ export declare function renderFieldLabel(spec: {
     label: string;
     required?: boolean;
     hint?: string;
+    /** Visually hide the label (it repeats the card title); it stays the control's accessible name. */
+    labelHidden?: boolean;
 }): string;
 /** The `aria-describedby` attribute pointing at a field's hint, or `''` when it has none. */
 export declare function fieldDescribedBy(spec: {

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

@@ -15,6 +15,7 @@ import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE }
 import { escapeHtml } from '../escape.js';
 import { SURFACE_BRIDGE_GLOBAL, renderBridgeScript } from './bridge.js';
 import { renderTokenBlock } from './tokens.js';
+import { DETAIL_DISCLOSURE_SCRIPT, renderStructuredDetail } from './structured-details.js';
 /**
  * The base stylesheet, applied after the token block.
  *
@@ -69,6 +70,11 @@ body {
 }
 .mcpui-details dt { color: var(--jini-mcpui-text-soft); font-weight: 500; overflow-wrap: anywhere; }
 .mcpui-details dd { margin: 0; overflow-wrap: anywhere; color: var(--jini-mcpui-text); }
+.mcpui-details dt .mcpui-hint { display: block; font-weight: 400; }
+/* A nested group (a tool's input fields) gets the card's full width, not the narrow value column. */
+.mcpui-details > dt:has(+ dd > .mcpui-detail-group),
+.mcpui-details > dd:has(> .mcpui-detail-group) { grid-column: 1 / -1; }
+.mcpui-details > dt:has(+ dd > .mcpui-detail-group) { margin-bottom: 6px; }
 .mcpui-details-outcome { display: flex; flex-direction: column; gap: 8px; }
 .mcpui-outcome-row { display: flex; align-items: flex-start; gap: 14px; }
 .mcpui-outcome-row dt { flex: 1; min-width: 0; overflow-wrap: anywhere; }
@@ -117,6 +123,7 @@ body {
 .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-visually-hidden { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
 .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 {
@@ -202,6 +209,34 @@ body {
    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); }`;
+/** Structured details extend the same token system; legacy short-string documents keep their layout. */
+const STRUCTURED_DETAILS_CSS = `
+.mcpui-details { gap: 8px 16px; margin-top: 16px; }
+.mcpui-details dt { font-weight: 400; }
+.mcpui-details dd { min-width: 0; font-weight: 400; }
+.mcpui-detail-group { margin: 0; padding: 0; padding-inline-start: 8px; border-inline-start: 1px solid var(--jini-mcpui-border); }
+.mcpui-detail-row { display: grid; grid-template-columns: minmax(0, 2fr) minmax(0, 3fr); gap: 8px; padding: 8px 0; }
+.mcpui-detail-row:first-child { padding-top: 0; }
+.mcpui-detail-row:last-child { padding-bottom: 0; }
+.mcpui-detail-row:has(> dd > .mcpui-detail-group) { grid-template-columns: minmax(0, 1fr); }
+.mcpui-detail-array { margin: 0; padding-inline-start: 16px; }
+.mcpui-detail-array li + li { margin-top: 8px; }
+.mcpui-detail-disclosure { min-width: 0; margin-top: 8px; }
+.mcpui-detail-disclosure:first-child { margin-top: 0; }
+.mcpui-detail-disclosure > summary { color: var(--jini-mcpui-text-muted); cursor: pointer; overflow-wrap: anywhere; }
+.mcpui-detail-disclosure > summary:focus-visible { outline: 2px solid var(--jini-mcpui-accent-ring); outline-offset: 2px; }
+.mcpui-detail-disclosure > .mcpui-code, .mcpui-detail-disclosure > .mcpui-detail-group,
+.mcpui-detail-full { margin-top: 8px; }
+.mcpui-detail-preview { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 3; overflow: hidden; color: var(--jini-mcpui-text); }
+.mcpui-detail-long > summary { list-style: none; }
+.mcpui-detail-long > summary::-webkit-details-marker { display: none; }
+.mcpui-detail-less, .mcpui-detail-long[open] .mcpui-detail-more,
+.mcpui-detail-long[open] .mcpui-detail-preview { display: none; }
+.mcpui-detail-long[open] .mcpui-detail-less { display: inline; }
+.mcpui-detail-change { display: flex; flex-direction: column; gap: 8px; }
+.mcpui-detail-change > div > .mcpui-hint { display: block; }
+.mcpui-detail-raw { font-size: 12px; }
+.mcpui-detail-disclosure .mcpui-code { color: var(--jini-mcpui-text); }`;
 /**
  * The Content-Security-Policy every generated surface declares in its own `<head>`.
  *
@@ -229,6 +264,9 @@ export const SURFACE_CSP = "default-src 'none'; script-src 'unsafe-inline'; styl
  */
 export function renderSurfaceDocument(spec) {
     const extraCss = spec.extraCss === undefined ? '' : `\n${spec.extraCss}`;
+    const hasDisclosures = spec.bodyHtml.includes('<details class="mcpui-detail-disclosure');
+    const detailCss = hasDisclosures ? STRUCTURED_DETAILS_CSS : '';
+    const detailScript = hasDisclosures ? `\n${DETAIL_DISCLOSURE_SCRIPT}` : '';
     return `<!doctype html>
 <html lang="${escapeHtml(spec.lang ?? 'en')}">
 <head>
@@ -238,7 +276,7 @@ export function renderSurfaceDocument(spec) {
 <title>${escapeHtml(spec.title)}</title>
 <style>
 ${renderTokenBlock(spec.tokens)}
-${SURFACE_BASE_CSS}${extraCss}
+${SURFACE_BASE_CSS}${detailCss}${extraCss}
 </style>
 </head>
 <body>
@@ -249,7 +287,7 @@ ${spec.bodyHtml}
 ${renderBridgeScript(spec.app)}
 </script>
 <script>
-${spec.script}
+${spec.script}${detailScript}
 </script>
 </body>
 </html>`;
@@ -271,7 +309,7 @@ export function renderSurfaceHeader(spec) {
  * @param options.layout - Outcome rows size independently and stack in narrow cards.
  * @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.
- * @complexity O(n) in the rendered length; no effects or input mutation.
+ * @complexity O(n * depth) with previous snapshots, otherwise O(n) rendered bytes; no effects or input mutation.
  */
 export function renderDetailList(details, options = {}) {
     if (details.length === 0)
@@ -279,10 +317,9 @@ export function renderDetailList(details, options = {}) {
     const outcome = options.layout === 'outcome';
     const rows = details
         .map((detail) => {
-        const value = escapeHtml(detail.value);
-        const body = detail.format === 'code' ? `<pre class="mcpui-code">${value}</pre>` : value;
+        const body = renderStructuredDetail({ detail });
         const description = detail.description === undefined ? '' : `<span class="mcpui-hint">${escapeHtml(detail.description)}</span>`;
-        const valueClass = detail.format === 'status' ? ` class="mcpui-detail-status" title="${value}"` : '';
+        const valueClass = detail.format === 'status' && typeof detail.value === 'string' ? ` class="mcpui-detail-status" title="${escapeHtml(detail.value)}"` : '';
         const pair = `<dt>${escapeHtml(detail.label)}${description}</dt><dd${valueClass}>${body}</dd>`;
         return outcome ? `  <div class="mcpui-outcome-row">${pair}</div>` : `  ${pair}`;
     })
@@ -351,6 +388,8 @@ function reportCallFailure(error) {
  * 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.
  */
+/** Hides an element visually while keeping it in the accessibility tree (see `.mcpui-visually-hidden` in {@link SURFACE_BASE_CSS}). */
+export const VISUALLY_HIDDEN_CLASS = 'mcpui-visually-hidden';
 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.
@@ -375,7 +414,7 @@ export function renderFieldLabel(spec) {
     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}`;
+    return `<label class="mcpui-label${spec.labelHidden === true ? ` ${VISUALLY_HIDDEN_CLASS}` : ''}" 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) {

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

@@ -72,15 +72,21 @@ export interface MultiEnumField extends SurfaceFieldBase {
     readonly options: readonly SelectOption[];
 }
 export type SurfaceField = StringField | NumberField | BooleanField | EnumField | MultiEnumField;
+/** Presentation the form decides for a field, not part of the field's own data. */
+export interface FieldRenderOptions {
+    /** The label repeats the card title: keep it as the accessible name, but don't show it twice. */
+    readonly labelHidden?: boolean;
+}
 /**
  * Renders the control fragment for one field, dispatching on its kind.
  *
  * @param field - See {@link SurfaceField}.
  * @param text - Optional host translations for secret reveal controls.
+ * @param options - See {@link FieldRenderOptions}.
  * @returns An HTML fragment.
  * @complexity O(n) in the rendered length.
  */
-export declare function renderFieldControl(field: SurfaceField, text?: Partial<SecretInputText>): string;
+export declare function renderFieldControl(field: SurfaceField, text?: Partial<SecretInputText>, options?: FieldRenderOptions): 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;

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

@@ -14,6 +14,7 @@
  * 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 { unhandledCase } from '../../../utils/unhandled-case.js';
 import { renderCheckbox } from './checkbox.js';
 import { renderChoiceGroup } from './choice-group.js';
 import { renderSelect } from './select.js';
@@ -30,42 +31,44 @@ function present(source, keys) {
     }
     return picked;
 }
-function base(field) {
-    return { name: field.name, label: field.label, ...present(field, ['hint', 'required', 'disabled']) };
+function base(field, options = {}) {
+    return { name: field.name, label: field.label, ...present(field, ['hint', 'required', 'disabled']), ...(options.labelHidden === true ? { labelHidden: true } : {}) };
 }
 /** One-of-N, drawn as radios or a select per {@link EnumField.presentation}. @complexity O(n) in the rendered length. */
-function renderEnumField(field) {
+function renderEnumField(field, options) {
     if (field.presentation === 'radio') {
         return renderChoiceGroup({
-            ...base(field),
+            ...base(field, options),
             selection: 'single',
             options: field.options,
             ...(field.value === undefined ? {} : { value: [field.value] }),
         });
     }
-    return renderSelect({ ...base(field), options: field.options, ...present(field, ['value', 'placeholder']) });
+    return renderSelect({ ...base(field, options), options: field.options, ...present(field, ['value', 'placeholder']) });
 }
 /**
  * Renders the control fragment for one field, dispatching on its kind.
  *
  * @param field - See {@link SurfaceField}.
  * @param text - Optional host translations for secret reveal controls.
+ * @param options - See {@link FieldRenderOptions}.
  * @returns An HTML fragment.
  * @complexity O(n) in the rendered length.
  */
-export function renderFieldControl(field, text) {
+export function renderFieldControl(field, text, options = {}) {
     switch (field.kind) {
         case 'string':
-            return renderTextInput({ ...base(field), ...text, ...present(field, ['value', 'placeholder', 'multiline', 'rows', 'secret']) });
+            return renderTextInput({ ...base(field, options), ...text, ...present(field, ['value', 'placeholder', 'multiline', 'rows', 'secret']) });
         case 'number':
-            return renderTextInput({ ...base(field), inputType: 'number', ...present(field, ['value', 'placeholder', 'min', 'max', 'step']) });
+            return renderTextInput({ ...base(field, options), inputType: 'number', ...present(field, ['value', 'placeholder', 'min', 'max', 'step']) });
         case 'boolean':
-            return renderCheckbox({ ...base(field), ...present(field, ['value']) });
+            return renderCheckbox({ ...base(field, options), ...present(field, ['value']) });
         case 'enum':
-            return renderEnumField(field);
+            return renderEnumField(field, options);
         case 'multi-enum':
-            return renderChoiceGroup({ ...base(field), selection: 'multiple', options: field.options, ...present(field, ['value']) });
+            return renderChoiceGroup({ ...base(field, options), selection: 'multiple', options: field.options, ...present(field, ['value']) });
     }
+    return unhandledCase(field);
 }
 /** Projects fields to runtime validation data; conditional requirements also carry their guidance. */
 export function toFieldReadSpecs(fields) {