@jini-ai/ui 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @jini-ai/ui
 
+## 0.4.3 — 2026-10-05
+
+- MCP-UI resources can carry an answer deadline: `createUIResource`/`buildConfirmationSurface` take `expiresAtMs`, written to `MCP_UI_EXPIRES_AT_META_KEY`; `readExpiresAt` reads it back (undefined when absent or not a finite number).
+
 ## 0.4.2 — 2026-10-04
 
 - Internal `@jini-ai/*` dependencies are caret ranges (`workspace:^`) instead of exact pins, so a host on `@jini-ai/agentic` 0.4.1 or on a newer patch resolves a single copy without an override.

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

@@ -74,6 +74,16 @@ export declare const JINI_MCP_UI_METADATA_PREFIX = "x-jini-mcp-ui/";
  * `@jini-ai/chat` for the host-side consumer.
  */
 export declare const MCP_UI_ACTION_PLAN_META_KEY = "x-jini-mcp-ui/action-plan";
+/**
+ * The `_meta` key a host reads to count down how long a surface can still be answered.
+ *
+ * A held-open question (a confirmation the tool waits on) stops being answerable when the server
+ * gives up waiting, but nothing in the document said when that would be, so a person could read a
+ * card that had already expired. The value is the deadline in epoch milliseconds on the PRODUCER's
+ * clock: a host whose clock runs ahead of the server's closes the card early by that skew, never late.
+ * See `McpUiSurfaceCard` in `@jini-ai/chat` for the host-side consumer.
+ */
+export declare const MCP_UI_EXPIRES_AT_META_KEY = "x-jini-mcp-ui/expires-at";
 /** One action in a surface's plan — the `_meta`-safe subset of `surfaces/document.ts`'s `SurfaceAction` (no `type`: that field only affects in-frame `<form>` submission, which has no parent-DOM equivalent). */
 export interface McpUiActionPlanAction {
     readonly id: string;
@@ -130,8 +140,9 @@ export interface UIToolResult {
  * @param spec.preferredFrameSize - `[width, height]` CSS lengths, written to the `_meta` key mcp-ui
  * hosts read.
  * @param spec.actionPlan - See {@link McpUiActionPlan}, written to {@link MCP_UI_ACTION_PLAN_META_KEY}.
- * @param spec.meta - Extra `_meta` entries, merged after `preferredFrameSize`/`actionPlan` so a
- * caller can override either.
+ * @param spec.expiresAtMs - When the surface stops being answerable, written to {@link MCP_UI_EXPIRES_AT_META_KEY}.
+ * @param spec.meta - Extra `_meta` entries, merged after `preferredFrameSize`/`actionPlan`/`expiresAtMs`
+ * so a caller can override any of them.
  * @returns The `EmbeddedResource` to place in a tool result's `content` array.
  * @complexity O(1).
  */
@@ -140,6 +151,7 @@ export declare function createUIResource(spec: {
     htmlString: string;
     preferredFrameSize?: readonly [string, string];
     actionPlan?: McpUiActionPlan;
+    expiresAtMs?: number;
     meta?: Readonly<Record<string, unknown>>;
 }): UIResource;
 /**
@@ -189,4 +201,12 @@ export declare function readPreferredFrameSize(resource: UIResource): readonly [
  * @returns The plan, or `undefined` when absent or malformed.
  */
 export declare function readActionPlan(resource: UIResource): McpUiActionPlan | undefined;
+/**
+ * Reads the answer deadline a resource's `_meta` may carry — see {@link MCP_UI_EXPIRES_AT_META_KEY}.
+ *
+ * @returns Epoch milliseconds, or `undefined` when absent or not a finite number — a host that gets
+ * `undefined` shows no countdown rather than one built on a malformed value.
+ * @complexity O(1).
+ */
+export declare function readExpiresAt(resource: UIResource): number | undefined;
 //# sourceMappingURL=resource.d.ts.map

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

@@ -67,6 +67,16 @@ export const JINI_MCP_UI_METADATA_PREFIX = 'x-jini-mcp-ui/';
  * `@jini-ai/chat` for the host-side consumer.
  */
 export const MCP_UI_ACTION_PLAN_META_KEY = `${JINI_MCP_UI_METADATA_PREFIX}action-plan`;
+/**
+ * The `_meta` key a host reads to count down how long a surface can still be answered.
+ *
+ * A held-open question (a confirmation the tool waits on) stops being answerable when the server
+ * gives up waiting, but nothing in the document said when that would be, so a person could read a
+ * card that had already expired. The value is the deadline in epoch milliseconds on the PRODUCER's
+ * clock: a host whose clock runs ahead of the server's closes the card early by that skew, never late.
+ * See `McpUiSurfaceCard` in `@jini-ai/chat` for the host-side consumer.
+ */
+export const MCP_UI_EXPIRES_AT_META_KEY = `${JINI_MCP_UI_METADATA_PREFIX}expires-at`;
 /**
  * Builds a UI resource from self-contained HTML.
  *
@@ -78,8 +88,9 @@ export const MCP_UI_ACTION_PLAN_META_KEY = `${JINI_MCP_UI_METADATA_PREFIX}action
  * @param spec.preferredFrameSize - `[width, height]` CSS lengths, written to the `_meta` key mcp-ui
  * hosts read.
  * @param spec.actionPlan - See {@link McpUiActionPlan}, written to {@link MCP_UI_ACTION_PLAN_META_KEY}.
- * @param spec.meta - Extra `_meta` entries, merged after `preferredFrameSize`/`actionPlan` so a
- * caller can override either.
+ * @param spec.expiresAtMs - When the surface stops being answerable, written to {@link MCP_UI_EXPIRES_AT_META_KEY}.
+ * @param spec.meta - Extra `_meta` entries, merged after `preferredFrameSize`/`actionPlan`/`expiresAtMs`
+ * so a caller can override any of them.
  * @returns The `EmbeddedResource` to place in a tool result's `content` array.
  * @complexity O(1).
  */
@@ -89,6 +100,7 @@ export function createUIResource(spec) {
             ? {}
             : { [MCP_UI_PREFERRED_FRAME_SIZE_META_KEY]: [...spec.preferredFrameSize] }),
         ...(spec.actionPlan === undefined ? {} : { [MCP_UI_ACTION_PLAN_META_KEY]: spec.actionPlan }),
+        ...(spec.expiresAtMs === undefined ? {} : { [MCP_UI_EXPIRES_AT_META_KEY]: spec.expiresAtMs }),
         ...spec.meta,
     };
     return {
@@ -225,4 +237,15 @@ export function readActionPlan(resource) {
     }
     return { title, ...(description === undefined ? {} : { description }), actions };
 }
+/**
+ * Reads the answer deadline a resource's `_meta` may carry — see {@link MCP_UI_EXPIRES_AT_META_KEY}.
+ *
+ * @returns Epoch milliseconds, or `undefined` when absent or not a finite number — a host that gets
+ * `undefined` shows no countdown rather than one built on a malformed value.
+ * @complexity O(1).
+ */
+export function readExpiresAt(resource) {
+    const raw = resource.resource._meta?.[MCP_UI_EXPIRES_AT_META_KEY];
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+}
 //# sourceMappingURL=resource.js.map

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

@@ -120,10 +120,13 @@ export declare function renderConfirmationDocument(spec: ConfirmationSurfaceSpec
  * @param spec.uri - The `ui://` identifier. Key it by entity and version, never by the confirmation
  * token: a URI is something a host may log, cache, or show in devtools.
  * @param spec.preferredFrameSize - `[width, height]` hint for hosts that honor it.
+ * @param spec.expiresAtMs - When the server stops waiting for an answer (epoch ms), so a host can
+ * count it down and close the card when it passes. Omit for a dialog with no deadline.
  * @complexity O(n) in the rendered length.
  */
 export declare function buildConfirmationSurface(spec: ConfirmationSurfaceSpec & {
     uri: UIResourceUri;
     preferredFrameSize?: readonly [string, string];
+    expiresAtMs?: number;
 }): UIResource;
 //# sourceMappingURL=confirmation.d.ts.map

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

@@ -313,6 +313,8 @@ ${SURFACE_SCRIPT_PRELUDE}
  * @param spec.uri - The `ui://` identifier. Key it by entity and version, never by the confirmation
  * token: a URI is something a host may log, cache, or show in devtools.
  * @param spec.preferredFrameSize - `[width, height]` hint for hosts that honor it.
+ * @param spec.expiresAtMs - When the server stops waiting for an answer (epoch ms), so a host can
+ * count it down and close the card when it passes. Omit for a dialog with no deadline.
  * @complexity O(n) in the rendered length.
  */
 export function buildConfirmationSurface(spec) {
@@ -320,6 +322,7 @@ export function buildConfirmationSurface(spec) {
         uri: spec.uri,
         htmlString: renderConfirmationDocument(spec),
         ...(spec.preferredFrameSize === undefined ? {} : { preferredFrameSize: spec.preferredFrameSize }),
+        ...(spec.expiresAtMs === undefined ? {} : { expiresAtMs: spec.expiresAtMs }),
         // Same title/actions the frame itself renders (via confirmationActions) — see that function's
         // doc for why this must never be a second, independently-maintained mapping. A host reads this
         // to build a parent-DOM mirror discoverable by page.find_elements; see MCP_UI_ACTION_PLAN_META_KEY.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/ui",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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": {
@@ -163,7 +163,7 @@
     "tailwind-merge": "^2.6.0",
     "zod": "^3.25.76",
     "@jini-ai/agentic": "^0.4.1",
-    "@jini-ai/core": "^0.4.0"
+    "@jini-ai/core": "^0.4.1"
   },
   "devDependencies": {
     "@excalidraw/excalidraw": "0.18.1",