@jini-ai/ui 0.4.4 → 0.4.5

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

@@ -1,21 +1,9 @@
 /**
- * The atomic `@mention` node. Extends `TextNode` so the node's *text* remains
- * the literal `@token` and serialization back to the wire format is free:
- * `getTextContent()` already yields `@token`. Lexical token mode deletes the
- * node as one entity but still allows character-by-character caret
- * navigation, so `rules.ts` adds explicit keyboard normalization for arrows.
- *
- * Origin: `apps/web/src/components/composer/MentionNode.ts`. The origin
- * imported OD's `connectorBrandColor`/`resolveBrandTheme` directly to color
- * a `connector`-kind pill's `--m-hue` CSS custom property, and installed a
- * document-wide `MutationObserver` to re-stamp every mounted pill on a live
- * theme flip. Both are dropped from this node entirely — no per-instance
- * color logic and no global observer belong on a generic Lexical node class.
- * A host that wants per-kind/per-entity coloring supplies a
- * `resolveMentionColor` callback to `RichTextInput`, applied by
- * `react/hooks/useMentionColorStamping.ts` via Lexical's own
- * `registerMutationListener` (scoped to that one editor instance, not the
- * whole document) — see that file for the replacement mechanism.
+ * Atomic @mention extends TextNode so getTextContent preserves the wire token. Token mode deletes
+ * one entity but still permits character-level caret movement; rules.ts normalizes arrow navigation.
+ * Generic nodes own no brand resolution or document-wide observer. Host colors enter through
+ * RichTextInput.resolveMentionColor and an editor-scoped Lexical mutation listener; see
+ * react/hooks/useMentionColorStamping.ts.
  */
 import { TextNode, } from 'lexical';
 export class MentionNode extends TextNode {

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

@@ -5,10 +5,8 @@
  * mention nodes, and available to hosts that need the same rule to fold
  * plain-text-typed `@token`s into a "currently referenced" entity list.
  *
- * Origin: `apps/web/src/utils/inlineMentions.ts`. Ported verbatim (trie-based
- * longest-match lookup, left/right boundary rules) — the only OD-specific
- * surface was `InlineMentionKind`'s fixed union, replaced by `MentionEntity`'s
- * free-form `kind: string` (see `types.ts`).
+ * Trie lookup prefers the longest token subject to left/right boundaries. MentionEntity.kind
+ * is host-defined rather than a fixed product vocabulary.
  */
 import type { MentionEntity, MentionPart } from './types.js';
 export declare function buildMentionToken(label: string): string;

package/dist/features/lexical-rich-text-editor/serialize.d.ts

@@ -1,7 +1,3 @@
-/**
- * Origin: `apps/web/src/components/composer/serialize.ts`. Ported verbatim —
- * no OD-specific surface (it only ever touched the generic `MentionNode`).
- */
 import { type EditorState } from 'lexical';
 import type { SerializedRichText } from './types.js';
 export declare function serializeRichText(state: EditorState): SerializedRichText;

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

@@ -1,7 +1,3 @@
-/**
- * Origin: `apps/web/src/components/composer/serialize.ts`. Ported verbatim —
- * no OD-specific surface (it only ever touched the generic `MentionNode`).
- */
 import { $getRoot, $isElementNode, $isLineBreakNode, $isParagraphNode, $isTextNode, } from 'lexical';
 import { $isMentionNode } from './mention-node.js';
 // Walk the tree by hand rather than calling `root.getTextContent()`, which

package/dist/features/lexical-rich-text-editor/types.d.ts

@@ -1,16 +1,6 @@
-/**
- * Generic types for a Lexical-backed rich text input: a plain-text-with-
- * atomic-mention-tokens editor (not a full block/marks rich text editor —
- * the origin used Lexical's `PlainTextPlugin`, not `RichTextPlugin`).
- *
- * Origin: `apps/web/src/components/composer/*` (OD's chat composer). The
- * only OD-specific piece was the `@mention` pill's brand color, resolved
- * via a direct import of OD's connector-brand-theme logic — replaced here
- * by a host-injected `resolveMentionColor` callback (see
- * `react/hooks/useMentionColorStamping.ts`). Everything else (trigger
- * detection, atomic-node keyboard navigation, caret-floating-layer
- * positioning, serialize/deserialize) is genuinely generic and ported as-is.
- */
+/** PlainTextPlugin-backed editing with atomic mentions, rather than block/mark rich text.
+ * Mention colors are host-injected through resolveMentionColor; generic trigger/navigation/caret
+ * and wire serialization rules stay independent of a product's connector branding. */
 /** A single mention-able entity: any host-owned capability/entity with a
  *  stable id, a display label, and a free-form category ("kind"). Unlike
  *  the origin's fixed `plugin | skill | mcp | file | workspace | connector`

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

@@ -1,15 +1,5 @@
-/**
- * Generic types for a Lexical-backed rich text input: a plain-text-with-
- * atomic-mention-tokens editor (not a full block/marks rich text editor —
- * the origin used Lexical's `PlainTextPlugin`, not `RichTextPlugin`).
- *
- * Origin: `apps/web/src/components/composer/*` (OD's chat composer). The
- * only OD-specific piece was the `@mention` pill's brand color, resolved
- * via a direct import of OD's connector-brand-theme logic — replaced here
- * by a host-injected `resolveMentionColor` callback (see
- * `react/hooks/useMentionColorStamping.ts`). Everything else (trigger
- * detection, atomic-node keyboard navigation, caret-floating-layer
- * positioning, serialize/deserialize) is genuinely generic and ported as-is.
- */
+/** PlainTextPlugin-backed editing with atomic mentions, rather than block/mark rich text.
+ * Mention colors are host-injected through resolveMentionColor; generic trigger/navigation/caret
+ * and wire serialization rules stay independent of a product's connector branding. */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/features/mcp-ui/early-message-buffer.d.ts

@@ -16,8 +16,7 @@
  * DOM types and no React, so it is testable in a plain Node environment. The module-scope
  * `window.addEventListener` that feeds it belongs to the React half; see
  * `../../react/mcp-ui/host-message-source.ts`.
- *
- * Ported from `examples/reference-web/src/mcpui-lab-message-buffer.ts` unchanged in behavior.
+
  */
 /**
  * A raw `MessageEvent`, narrowed to the fields this module needs. `source` stays `unknown` (rather

package/dist/features/mcp-ui/early-message-buffer.js

@@ -16,8 +16,7 @@
  * DOM types and no React, so it is testable in a plain Node environment. The module-scope
  * `window.addEventListener` that feeds it belongs to the React half; see
  * `../../react/mcp-ui/host-message-source.ts`.
- *
- * Ported from `examples/reference-web/src/mcpui-lab-message-buffer.ts` unchanged in behavior.
+
  */
 /**
  * Bound so a hostile or confused page flooding `postMessage` at a tab that never subscribes cannot

package/dist/features/mcp-ui/escape.d.ts

@@ -47,5 +47,9 @@ export declare function escapeJsValue(value: unknown): string;
  * `string`-typed signature makes a caller that accidentally passes an object a compile error rather
  * than a silently-inlined `[object Object]`-free-but-surprising literal.
  */
+export declare function escapeJsString(required: {
+    value: string;
+}, optional?: {}): string;
+/** Existing string call retained for published surface builders. */
 export declare function escapeJsString(value: string): string;
 //# sourceMappingURL=escape.d.ts.map

package/dist/features/mcp-ui/escape.js

@@ -55,14 +55,7 @@ export function escapeJsValue(value) {
         .replace(/\u2028/g, '\\u2028')
         .replace(/\u2029/g, '\\u2029');
 }
-/**
- * {@link escapeJsValue} narrowed to strings.
- *
- * Kept as its own export because the overwhelmingly common call is "inline this one string", and a
- * `string`-typed signature makes a caller that accidentally passes an object a compile error rather
- * than a silently-inlined `[object Object]`-free-but-surprising literal.
- */
-export function escapeJsString(value) {
-    return escapeJsValue(value);
+export function escapeJsString(required, _optional = {}) {
+    return escapeJsValue(typeof required === "string" ? required : required.value);
 }
 //# sourceMappingURL=escape.js.map

package/dist/features/mcp-ui/index.d.ts

@@ -23,6 +23,7 @@ export * from './early-message-buffer.js';
 export * from './escape.js';
 export * from './protocol.js';
 export * from './resource.js';
+export * from './secret-card.js';
 export * from './sandbox-proxy.js';
 export * from './surfaces/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/features/mcp-ui/index.js

@@ -23,6 +23,7 @@ export * from './early-message-buffer.js';
 export * from './escape.js';
 export * from './protocol.js';
 export * from './resource.js';
+export * from './secret-card.js';
 export * from './sandbox-proxy.js';
 export * from './surfaces/index.js';
 //# sourceMappingURL=index.js.map

package/dist/features/mcp-ui/protocol.d.ts

@@ -4,11 +4,8 @@
  * The MCP Apps wire vocabulary, re-exported from `@jini-ai/agentic`'s `mcp-ui-apps.ts` rather than
  * restated here.
  *
- * `mcp-ui-apps.ts` is the spec-verified module (re-checked 2026-07-28 against
- * `github.com/modelcontextprotocol/ext-apps`, both the 2026-01-26 [Stable] text and the draft), and
- * it already carries the two things a second copy would immediately lose: the audit history for
- * which lifecycle messages travel in which direction, and `isJsonRpcMessage`'s hardening against
- * malformed `postMessage` input found by live adversarial testing. Duplicating any of it would
+ * `mcp-ui-apps.ts` owns message direction and isJsonRpcMessage's malformed-postMessage guards.
+ * Duplicating those rules would
  * create a second surface to keep in sync with a moving spec, so this module owns nothing of the
  * envelope — it only re-exports it, plus adds the one constant that genuinely belongs to *this*
  * package: {@link MCP_UI_VIEW_SANDBOX}.

package/dist/features/mcp-ui/protocol.js

@@ -4,11 +4,8 @@
  * The MCP Apps wire vocabulary, re-exported from `@jini-ai/agentic`'s `mcp-ui-apps.ts` rather than
  * restated here.
  *
- * `mcp-ui-apps.ts` is the spec-verified module (re-checked 2026-07-28 against
- * `github.com/modelcontextprotocol/ext-apps`, both the 2026-01-26 [Stable] text and the draft), and
- * it already carries the two things a second copy would immediately lose: the audit history for
- * which lifecycle messages travel in which direction, and `isJsonRpcMessage`'s hardening against
- * malformed `postMessage` input found by live adversarial testing. Duplicating any of it would
+ * `mcp-ui-apps.ts` owns message direction and isJsonRpcMessage's malformed-postMessage guards.
+ * Duplicating those rules would
  * create a second surface to keep in sync with a moving spec, so this module owns nothing of the
  * envelope — it only re-exports it, plus adds the one constant that genuinely belongs to *this*
  * package: {@link MCP_UI_VIEW_SANDBOX}.

package/dist/features/mcp-ui/resource.d.ts

@@ -12,11 +12,8 @@
  * ``ui://${string}`` URI scheme and the wider MIME union reproduced in
  * {@link UIResourceMimeType}.
  *
- * Ported from the reference implementation's `mcp-ui.ts`, minus that file's hand-rolled copy of the
- * JSON-RPC envelope and its `UIActionResult` union: the reference implementation declared those
- * because its tsconfig's
- * `moduleResolution: "Node"` cannot read a modern package's `exports` map, and this package has no
- * such constraint — the envelope comes from `protocol.ts`'s re-exports instead. See
+ * The envelope comes from protocol.ts's re-exports, so this resource layer has no parallel
+ * JSON-RPC or UIActionResult definition. See
  * `surfaces/bridge.ts` for why the legacy `{type:'tool', payload}` action shape is not emitted.
  */
 /** The `ui://` URI scheme MCP Apps fixes for UI resources. */
@@ -153,7 +150,7 @@ export declare function createUIResource(spec: {
     actionPlan?: McpUiActionPlan;
     expiresAtMs?: number;
     meta?: Readonly<Record<string, unknown>>;
-}): UIResource;
+}, _optional?: {}): UIResource;
 /**
  * Assembles the two-part tool result: what the MODEL is told, and what the HUMAN is shown.
  *
@@ -167,7 +164,7 @@ export declare function buildUIToolResult(spec: {
     modelText: string;
     ui: UIResource;
     meta?: Readonly<Record<string, unknown>>;
-}): UIToolResult;
+}, _optional?: {}): UIToolResult;
 /**
  * Narrows an arbitrary value to a {@link UIResource}.
  *
@@ -209,4 +206,47 @@ export declare function readActionPlan(resource: UIResource): McpUiActionPlan |
  * @complexity O(1).
  */
 export declare function readExpiresAt(resource: UIResource): number | undefined;
+/** Legacy host action vocabulary retained for consumers that negotiate pre-Apps messages. */
+export type UIActionType = "tool" | "prompt" | "link" | "intent" | "notify";
+/**
+ * mcp-ui's `UIActionResult` union — the `postMessage` payload an iframe sends to the host.
+ *
+ * `messageId` is what makes the round trip observable: mcp-ui's client answers a message carrying
+ * one with `ui-message-received` and then `ui-message-response` (same `messageId`). A host's
+ * confirmation dialog sets one so the rendered UI can show "deleted" or an error instead of
+ * silently appearing to do nothing.
+ */
+export type UIActionResult = {
+    messageId?: string;
+    type: "tool";
+    payload: {
+        toolName: string;
+        params: Record<string, unknown>;
+    };
+} | {
+    messageId?: string;
+    type: "prompt";
+    payload: {
+        prompt: string;
+    };
+} | {
+    messageId?: string;
+    type: "link";
+    payload: {
+        url: string;
+    };
+} | {
+    messageId?: string;
+    type: "intent";
+    payload: {
+        intent: string;
+        params: Record<string, unknown>;
+    };
+} | {
+    messageId?: string;
+    type: "notify";
+    payload: {
+        message: string;
+    };
+};
 //# sourceMappingURL=resource.d.ts.map

package/dist/features/mcp-ui/resource.js

@@ -12,11 +12,8 @@
  * ``ui://${string}`` URI scheme and the wider MIME union reproduced in
  * {@link UIResourceMimeType}.
  *
- * Ported from the reference implementation's `mcp-ui.ts`, minus that file's hand-rolled copy of the
- * JSON-RPC envelope and its `UIActionResult` union: the reference implementation declared those
- * because its tsconfig's
- * `moduleResolution: "Node"` cannot read a modern package's `exports` map, and this package has no
- * such constraint — the envelope comes from `protocol.ts`'s re-exports instead. See
+ * The envelope comes from protocol.ts's re-exports, so this resource layer has no parallel
+ * JSON-RPC or UIActionResult definition. See
  * `surfaces/bridge.ts` for why the legacy `{type:'tool', payload}` action shape is not emitted.
  */
 /**
@@ -94,7 +91,7 @@ export const MCP_UI_EXPIRES_AT_META_KEY = `${JINI_MCP_UI_METADATA_PREFIX}expires
  * @returns The `EmbeddedResource` to place in a tool result's `content` array.
  * @complexity O(1).
  */
-export function createUIResource(spec) {
+export function createUIResource(spec, _optional = {}) {
     const meta = {
         ...(spec.preferredFrameSize === undefined
             ? {}
@@ -109,7 +106,7 @@ export function createUIResource(spec) {
             uri: spec.uri,
             mimeType: MCP_UI_MIME_TYPE,
             text: spec.htmlString,
-            ...(Object.keys(meta).length === 0 ? {} : { _meta: meta }),
+            ...(Object.keys(meta).length === 0 && spec.meta === undefined ? {} : { _meta: meta }),
         },
     };
 }
@@ -122,7 +119,7 @@ export function createUIResource(spec) {
  * @param spec.meta - Optional result-level `_meta`.
  * @complexity O(1).
  */
-export function buildUIToolResult(spec) {
+export function buildUIToolResult(spec, _optional = {}) {
     return {
         content: [{ type: 'text', text: spec.modelText }, spec.ui],
         ...(spec.meta === undefined ? {} : { _meta: spec.meta }),

package/dist/features/mcp-ui/secret-card.d.ts

@@ -0,0 +1,115 @@
+/**
+ * One human-only secret-card lifecycle. Keystrokes go directly to the held exchange and save
+ * port, never through model input, chat text, or logs. Saved values must stay in the host's
+ * sealed store; save returns only a safe summary for result/outcome projections.
+ *
+ * Fail closed without an emitter: returning a form or accepting a second model call would
+ * strand the held call or route a secret through model context. Cancel posts a dismissal so
+ * the call wakes immediately instead of waiting for its TTL. askThenReport keeps the exchange
+ * open until the real save finishes; reusing the form URI replaces premature "Done." with its
+ * actual outcome. The host supplies the daemon's existing helper, never a second store.
+ */
+import { type SurfaceAskThenReport, type SurfaceExchangeStore, type ToolExecutionContext, type ToolExecutionOptions } from '@jini-ai/core';
+import { type FormSurfaceSpec } from './surfaces/form.js';
+import { type SurfaceOutcomeSpec } from './surfaces/outcome.js';
+import type { StringField, SurfaceField } from './surfaces/fields.js';
+/** Secret fields cannot carry a value, even through a previously declared variable.
+ * `allowBlank` permits an empty string for stored-value preservation or public-client auth. */
+export type SecretCardField = (SurfaceField & {
+    readonly secret?: false;
+}) | (Omit<StringField, 'value' | 'secret'> & {
+    readonly secret: true;
+    readonly value?: never;
+    readonly allowBlank?: boolean;
+});
+/** The host controls copy, field construction and display; routing/dismissal belong to the engine. */
+export type SecretCardForm = Omit<FormSurfaceSpec, 'fields' | 'toolName' | 'baseParams' | 'cancel'> & {
+    readonly fields: readonly SecretCardField[];
+    readonly cancelLabel?: string;
+};
+export type SecretCardRun<Saved> = {
+    readonly status: 'saved';
+    readonly saved: Saved;
+} | {
+    readonly status: 'cancelled';
+} | {
+    readonly status: 'expired';
+} | {
+    readonly status: 'abandoned';
+} | {
+    readonly status: 'blank';
+} | {
+    readonly status: 'failed';
+    readonly safeMessage: string;
+};
+/** A domain spec, with authorization and target resolution in prepare and persistence in save.
+ * Projections must contain safe metadata only. Neither projection receives the submitted values. */
+export interface SecretCardSpec<Prep, Saved, Result> {
+    readonly toolId: string;
+    /** Validate public model input, authorize and resolve the target before opening a card.
+     * Reject secret-bearing input; never read stored plaintext for form construction. */
+    prepare(required: {
+        ctx: ToolExecutionContext;
+    }): Promise<Prep>;
+    form(required: {
+        prep: Prep;
+    }): SecretCardForm;
+    /** Only declared field names are forwarded. Domain validation remains authoritative.
+     * Values keep their native field types and exact bytes; stored secrets are never needed here. */
+    save(required: {
+        values: Readonly<Record<string, unknown>>;
+        prep: Prep;
+        signal: AbortSignal;
+    }): Promise<Saved>;
+    /** Return undefined for cancellation/expiry when the form already reports that state locally. */
+    outcome(required: {
+        prep: Prep;
+        run: SecretCardRun<Saved>;
+    }): SurfaceOutcomeSpec | undefined;
+    result(required: {
+        prep: Prep;
+        run: SecretCardRun<Saved>;
+    }): Result;
+}
+export interface SecretCardText {
+    readonly noEmitter?: string;
+    readonly saveFailure?: string;
+    readonly cancelLabel?: string;
+}
+export interface SecretCardOptions {
+    /** Allowlist known error kinds to fixed text. Never return raw error.message. */
+    readonly safeError?: (error: unknown) => string | undefined;
+    readonly text?: SecretCardText;
+    readonly frameSize?: readonly [string, string];
+    readonly uriHost?: string;
+    /** Fixed metadata only: errors and submitted values are deliberately absent. */
+    readonly logFailure?: (metadata: {
+        toolId: string;
+        exchangeId: string;
+        saved: false;
+    }) => void;
+}
+export interface SecretCardDeps {
+    readonly surfaceExchanges: Pick<SurfaceExchangeStore, 'open'>;
+    readonly askThenReport: SurfaceAskThenReport;
+}
+export type SecretCardHandler<Result> = (required: ToolExecutionContext, optional?: ToolExecutionOptions) => Promise<Result>;
+export interface SecretCardTool<Prep, Result> {
+    readonly toolId: string;
+    secretFieldNames(prep: Prep): string[];
+    handler(deps: SecretCardDeps): SecretCardHandler<Result>;
+}
+/**
+ * Define a secret card once; inject the exchange store and daemon askThenReport at composition.
+ * @param required - Domain fields, permission/target checks, save port and safe projections.
+ * @param options - Optional copy, error allowlist, fixed-metadata logger and resource framing.
+ * @returns Tool identity, dynamic secret-field metadata and a typed registry-compatible handler.
+ * @throws ToolInputError if the emitter is missing or fields violate the secret/routing contract.
+ * Prepare/transport failures propagate; save failures become a fixed safe outcome.
+ * @complexity O(n + h + b) locally in fields, rendered HTML and submitted secret bytes, plus host I/O.
+ * @example
+ * const tool = defineSecretCardTool(spec);
+ * registry.register({ descriptor, policy, handler: tool.handler({ surfaceExchanges, askThenReport }) });
+ */
+export declare function defineSecretCardTool<Prep, Saved, Result>(required: SecretCardSpec<Prep, Saved, Result>, options?: SecretCardOptions): SecretCardTool<Prep, Result>;
+//# sourceMappingURL=secret-card.d.ts.map

package/dist/features/mcp-ui/secret-card.js

@@ -0,0 +1,137 @@
+/**
+ * One human-only secret-card lifecycle. Keystrokes go directly to the held exchange and save
+ * port, never through model input, chat text, or logs. Saved values must stay in the host's
+ * sealed store; save returns only a safe summary for result/outcome projections.
+ *
+ * Fail closed without an emitter: returning a form or accepting a second model call would
+ * strand the held call or route a secret through model context. Cancel posts a dismissal so
+ * the call wakes immediately instead of waiting for its TTL. askThenReport keeps the exchange
+ * open until the real save finishes; reusing the form URI replaces premature "Done." with its
+ * actual outcome. The host supplies the daemon's existing helper, never a second store.
+ */
+import { ToolInputError, redactSecrets, SURFACE_DISMISSED_PARAM, SURFACE_EXCHANGE_ID_PARAM, SURFACE_TYPED_ANSWER_PARAM, } from '@jini-ai/core';
+import { buildFormSurface } from './surfaces/form.js';
+import { buildOutcomeSurface } from './surfaces/outcome.js';
+/** Reject ambiguous or protocol-reserved names and runtime attempts to prefill secrets.
+ * @complexity O(n) time/space in the field count. Throws fixed ToolInputError text only. */
+function checkedFields(form) {
+    const names = new Set([SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWER_PARAM]);
+    for (const field of form.fields) {
+        if (!field.name || names.has(field.name))
+            throw new ToolInputError({ message: 'Secret card field names must be unique and cannot use exchange parameters.' });
+        names.add(field.name);
+        if (field.secret === true && field.value !== undefined)
+            throw new ToolInputError({ message: 'Secret fields cannot have a pre-filled value. Omit value.' });
+    }
+    // Snapshot policies before waiting: host mutation must not change which submitted fields are secret.
+    return form.fields.map(field => ({ ...field }));
+}
+/** Classify before persistence; an abort wins over an already-buffered answer.
+ * Trimming tests blankness only: rewriting a provider secret can corrupt intentional newlines.
+ * @complexity O(n + b) before save in fields and submitted secret bytes; failure text delegates
+ * to core's exact-secret redaction scan. Host persistence cost is external. */
+async function saveAnswer(required) {
+    const { answer, fields, prep, ctx, spec, options, exchangeId } = required;
+    if (ctx.signal.aborted)
+        return { status: 'abandoned' };
+    if (answer.status !== 'received')
+        return { status: answer.status };
+    if (answer.params[SURFACE_DISMISSED_PARAM] === true)
+        return { status: 'cancelled' };
+    const values = Object.fromEntries(fields.map(field => [field.name, answer.params[field.name]]));
+    const secrets = [];
+    for (const field of fields) {
+        if (field.secret !== true)
+            continue;
+        const value = values[field.name];
+        if (value !== undefined && typeof value !== 'string')
+            return { status: 'blank' };
+        const secret = typeof value === 'string' ? value : '';
+        if (secret.trim() === '' && (secret !== '' || field.allowBlank !== true))
+            return { status: 'blank' };
+        values[field.name] = secret;
+        secrets.push(secret);
+    }
+    if (ctx.signal.aborted)
+        return { status: 'abandoned' };
+    try {
+        return { status: 'saved', saved: await spec.save({ values, prep, signal: ctx.signal }) };
+    }
+    catch (error) {
+        if (ctx.signal.aborted)
+            return { status: 'abandoned' };
+        let safeMessage = options.text?.saveFailure ?? 'Saving failed. Nothing was saved.';
+        try {
+            safeMessage = options.safeError?.(error) ?? safeMessage;
+        }
+        catch { /* An error mapper must not disclose a second exception containing the submitted value. */ }
+        // Even an accidentally permissive allowlist must not echo the submitted secret.
+        safeMessage = redactSecrets({ input: safeMessage }, { exactSecrets: secrets });
+        try {
+            options.logFailure?.({ toolId: spec.toolId, exchangeId, saved: false });
+        }
+        catch { /* Logging must not replace the safe model result with an opaque logger exception. */ }
+        return { status: 'failed', safeMessage };
+    }
+}
+/**
+ * Define a secret card once; inject the exchange store and daemon askThenReport at composition.
+ * @param required - Domain fields, permission/target checks, save port and safe projections.
+ * @param options - Optional copy, error allowlist, fixed-metadata logger and resource framing.
+ * @returns Tool identity, dynamic secret-field metadata and a typed registry-compatible handler.
+ * @throws ToolInputError if the emitter is missing or fields violate the secret/routing contract.
+ * Prepare/transport failures propagate; save failures become a fixed safe outcome.
+ * @complexity O(n + h + b) locally in fields, rendered HTML and submitted secret bytes, plus host I/O.
+ * @example
+ * const tool = defineSecretCardTool(spec);
+ * registry.register({ descriptor, policy, handler: tool.handler({ surfaceExchanges, askThenReport }) });
+ */
+export function defineSecretCardTool(required, options = {}) {
+    const spec = required;
+    return {
+        toolId: spec.toolId,
+        secretFieldNames: prep => checkedFields(spec.form({ prep })).filter(field => field.secret === true).map(field => field.name),
+        handler: deps => async (ctx, optional = {}) => {
+            if (!optional.emitSurface)
+                throw new ToolInputError({ message: options.text?.noEmitter ?? `${spec.toolId}: this execution context has no interactive form channel (no emitSurface), so this form cannot be shown here. Nothing was changed.` });
+            const prep = await spec.prepare({ ctx });
+            if (ctx.signal.aborted)
+                return spec.result({ prep, run: { status: 'abandoned' } });
+            const form = spec.form({ prep });
+            const fields = checkedFields(form);
+            if (ctx.signal.aborted)
+                return spec.result({ prep, run: { status: 'abandoned' } });
+            const exchange = deps.surfaceExchanges.open({ binding: { toolId: spec.toolId, principalId: ctx.principal.id, channel: 'mcp-ui' }, emit: optional.emitSurface });
+            const closeOnAbort = () => exchange.close({});
+            ctx.signal.addEventListener('abort', closeOnAbort, { once: true });
+            try {
+                // Close the open/register race as well as the prepare/abort race.
+                if (ctx.signal.aborted)
+                    return spec.result({ prep, run: { status: 'abandoned' } });
+                const uri = `ui://${options.uriHost ?? 'jini'}/secret-card/${encodeURIComponent(spec.toolId)}/${encodeURIComponent(exchange.id)}`;
+                const framing = options.frameSize === undefined ? {} : { preferredFrameSize: options.frameSize };
+                const resource = buildFormSurface({ ...form, fields, uri, ...framing, toolName: spec.toolId,
+                    baseParams: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id },
+                    cancel: { label: form.cancelLabel ?? options.text?.cancelLabel ?? 'Cancel', toolName: spec.toolId,
+                        params: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id, [SURFACE_DISMISSED_PARAM]: true } },
+                });
+                return await deps.askThenReport({ exchange, confirmationEmission: { channel: 'mcp-ui', payload: { resource } },
+                    handle: async (answer) => {
+                        const run = await saveAnswer({ answer, fields, prep, ctx, spec, options, exchangeId: exchange.id });
+                        const result = spec.result({ prep, run });
+                        const outcome = spec.outcome({ prep, run });
+                        if (outcome === undefined)
+                            return { result };
+                        return { result, outcome: { channel: 'mcp-ui', payload: { resource: buildOutcomeSurface({ ...outcome, uri, ...framing }) } } };
+                    },
+                });
+            }
+            finally {
+                ctx.signal.removeEventListener('abort', closeOnAbort);
+                // Also covers rendering/projection failures before or inside askThenReport; close is idempotent.
+                exchange.close({});
+            }
+        },
+    };
+}
+//# sourceMappingURL=secret-card.js.map

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

@@ -209,6 +209,11 @@ ${SURFACE_SCRIPT_PRELUDE}
   }
   onVisibilityChange();
   document.addEventListener("visibilitychange", onVisibilityChange);
+  // Published Jini started the dwell during document.write. If the iframe is hidden then, no
+  // timer is armed; becoming visible by sandbox initialization need not send visibilitychange
+  // to that new document. Re-check at the bridge ready boundary, preserving the original
+  // visibility, dwell, trusted-click and single-call gates. whenReady is already in every bridge.
+  api.whenReady(onVisibilityChange);
 
   for (var i = 0; i < actionButtons.length; i++) {
     actionButtons[i].addEventListener("click", onClick);

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

@@ -1,4 +1,5 @@
 import { type SelectOption } from './select.js';
+import { type SecretInputText } from './text-input.js';
 interface SurfaceFieldBase {
     /** HTML `name`, DOM `id` suffix, and the params key the value is posted under. */
     readonly name: string;
@@ -14,7 +15,8 @@ export interface StringField extends SurfaceFieldBase {
     readonly placeholder?: string;
     readonly multiline?: boolean;
     readonly rows?: number;
-    /** Renders as a masked `<input type="password">` — see {@link TextInputProps.secret}. */
+    /** Renders as a masked input or multiline textarea; pre-filled values are forbidden.
+     *  See {@link TextInputProps.secret}. */
     readonly secret?: boolean;
 }
 export interface NumberField extends SurfaceFieldBase {
@@ -60,10 +62,11 @@ export type SurfaceField = StringField | NumberField | BooleanField | EnumField
  * 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.
  * @returns An HTML fragment.
  * @complexity O(n) in the rendered length.
  */
-export declare function renderFieldControl(field: SurfaceField): string;
+export declare function renderFieldControl(field: SurfaceField, text?: Partial<SecretInputText>): 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

@@ -32,14 +32,16 @@ function base(field) {
  * 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.
  * @returns An HTML fragment.
  * @complexity O(n) in the rendered length.
  */
-export function renderFieldControl(field) {
+export function renderFieldControl(field, text) {
     switch (field.kind) {
         case 'string':
             return renderTextInput({
                 ...base(field),
+                ...text,
                 ...(field.value === undefined ? {} : { value: field.value }),
                 ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
                 ...(field.multiline === undefined ? {} : { multiline: field.multiline }),