@jini-ai/chat 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,4 +1,20 @@
-## Unreleased
+## 0.5.2 — 2026-10-05
+
+- `useChatPane` holds a draft typed for a question that has since closed (answered elsewhere, expired, or refused with `'not-pending'`): `send` shows the `'not-pending'` notice instead of queueing it as a new paid run. Only clearing the draft or the new `sendAsNewMessage()` (the notice's "Send as a new message" button in `ChatPane`) lets it out as an ordinary turn. New pure `findAwaitedTypedAnswerId`.
+- A delivered typed answer clears the composer only if its text is unchanged, so a correction typed while the host answered survives; a delivery settling after `reset()`, a conversation switch or unmount changes neither the draft nor the notice.
+
+- `ChatPane`/`useChatPane` accept `deliverTypedAnswer`: text typed while the running agent holds a question card open (a surface whose tool call has not returned) goes to the host instead of the queue. `'delivered'` clears the draft; `'not-pending'`/`'failed'` (or a throw) keep the draft, show a notice (`typedAnswerNotice`) and never queue it, so a closed question can no longer turn an answer into a second paid run. New `createTypedAnswerPoster` posts `{toolName, params: {__typedAnswer}}` to the MCP-UI tool-call route (202 delivered, 409 not-pending). Omitting the prop keeps today's queue-while-streaming behavior.
+
+- `McpUiSurfaceCard` counts down a card's answer deadline (`MCP_UI_EXPIRES_AT_META_KEY`) under the live frame ("Expires in {time}", `role="timer"`) and closes it as "This question expired" when the deadline passes; a card answered in time still reads "Answered". New `useSurfaceExpiry` hook with an injectable `SurfaceExpiryClock` (card prop `expiryClock`), and pure `describeSurfaceExpiry`/`formatRemainingTime` in core.
+
+- A user's own send or retry re-sticks the transcript to the bottom even when they had scrolled up to read history (`MessageList`; scroll rules move to `useMessageListAutoScroll`).
+- The `@jini-ai/db` peer range is `^0.2.0 || ^0.3.0`; chat uses only db's kernel and store entries, which 0.3.0 leaves unchanged.
+
+## 0.5.1 — 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.
+
+### Also shipped in 0.5.1 (was listed under Unreleased)
 
 - Type store fixtures with the shared storage kernel and chat contracts, including host-owned tables;
   align construction, reopening, paging and message fixtures with current API shapes.

package/dist/core/index.d.ts

@@ -24,6 +24,7 @@ export * from './question-form.js';
 export * from './util/index.js';
 export * from './transcript.js';
 export * from './run-activity.js';
+export * from './surface-expiry.js';
 export * from './assistant-content.js';
 export * from './compact-events.js';
 /**

package/dist/core/index.js

@@ -24,6 +24,7 @@ export * from './question-form.js';
 export * from './util/index.js';
 export * from './transcript.js';
 export * from './run-activity.js';
+export * from './surface-expiry.js';
 export * from './assistant-content.js';
 export * from './compact-events.js';
 /**

package/dist/core/surface-expiry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module surface-expiry
+ *
+ * The answer deadline of a pending MCP-UI card (`MCP_UI_EXPIRES_AT_META_KEY` in `@jini-ai/ui`):
+ * whether it has passed, and the time left as the card shows it. Pure — the caller supplies "now",
+ * so the boundary (just before / at / after the deadline) is tested without a real clock.
+ */
+/** How often a live countdown re-reads the clock. Matches the label's whole-second resolution. */
+export declare const SURFACE_EXPIRY_TICK_MS = 1000;
+/** A card still answerable, with the time left, or one whose deadline has passed. */
+export type SurfaceExpiry = {
+    readonly expired: true;
+} | {
+    readonly expired: false;
+    readonly remainingMs: number;
+    readonly remaining: string;
+};
+/**
+ * Describes a card's deadline at one instant.
+ *
+ * Expired AT the deadline, not after it: the server gives up when its timer fires, so a click at
+ * that instant would already find nothing waiting.
+ *
+ * @param input.expiresAtMs - The deadline, epoch milliseconds.
+ * @param input.nowMs - The current time, same clock.
+ * @complexity O(1).
+ */
+export declare function describeSurfaceExpiry({ expiresAtMs, nowMs }: {
+    expiresAtMs: number;
+    nowMs: number;
+}): SurfaceExpiry;
+/**
+ * Formats a positive duration as `m:ss`, or `h:mm:ss` from an hour up.
+ *
+ * Rounds UP to the whole second, so a card with any time left never reads `0:00` while it can still
+ * be answered; it reads `0:01` until the instant it expires.
+ *
+ * @param remainingMs - Milliseconds left, greater than zero.
+ * @complexity O(1).
+ */
+export declare function formatRemainingTime(remainingMs: number): string;
+//# sourceMappingURL=surface-expiry.d.ts.map

package/dist/core/surface-expiry.js

@@ -0,0 +1,42 @@
+/**
+ * @module surface-expiry
+ *
+ * The answer deadline of a pending MCP-UI card (`MCP_UI_EXPIRES_AT_META_KEY` in `@jini-ai/ui`):
+ * whether it has passed, and the time left as the card shows it. Pure — the caller supplies "now",
+ * so the boundary (just before / at / after the deadline) is tested without a real clock.
+ */
+/** How often a live countdown re-reads the clock. Matches the label's whole-second resolution. */
+export const SURFACE_EXPIRY_TICK_MS = 1_000;
+/**
+ * Describes a card's deadline at one instant.
+ *
+ * Expired AT the deadline, not after it: the server gives up when its timer fires, so a click at
+ * that instant would already find nothing waiting.
+ *
+ * @param input.expiresAtMs - The deadline, epoch milliseconds.
+ * @param input.nowMs - The current time, same clock.
+ * @complexity O(1).
+ */
+export function describeSurfaceExpiry({ expiresAtMs, nowMs }) {
+    const remainingMs = expiresAtMs - nowMs;
+    if (remainingMs <= 0)
+        return { expired: true };
+    return { expired: false, remainingMs, remaining: formatRemainingTime(remainingMs) };
+}
+/**
+ * Formats a positive duration as `m:ss`, or `h:mm:ss` from an hour up.
+ *
+ * Rounds UP to the whole second, so a card with any time left never reads `0:00` while it can still
+ * be answered; it reads `0:01` until the instant it expires.
+ *
+ * @param remainingMs - Milliseconds left, greater than zero.
+ * @complexity O(1).
+ */
+export function formatRemainingTime(remainingMs) {
+    const totalSeconds = Math.ceil(remainingMs / 1_000);
+    const hours = Math.floor(totalSeconds / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = String(totalSeconds % 60).padStart(2, '0');
+    return hours > 0 ? `${hours}:${String(minutes).padStart(2, '0')}:${seconds}` : `${minutes}:${seconds}`;
+}
+//# sourceMappingURL=surface-expiry.js.map

package/dist/react/chat-pane.d.ts

@@ -16,6 +16,6 @@
  * `@deprecated`, so every existing `import { ChatPane } from '@jini-ai/chat/react'` keeps working
  * unchanged. New code should import from this subpath directly.
  */
-export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './features/chat-pane/index.js';
-export type { AgentRuntimePickerProps, ByokRuntimeSummary, ChatPaneActivity, ChatPaneAgent, ChatPaneAgentBridgeAccess, ChatPaneAgentControlOptions, ChatPaneAgentOption, ChatPaneAgentSelection, ChatPaneAgentToolAction, ChatPaneAgentToolDef, ChatPaneAgentToolInputSchema, ChatPaneAgentToolRisk, ChatPaneAttachmentUploadOptions, ChatPaneComposerHandle, ChatPaneProps, ChatPaneRunContext, ChatPaneRunContextInput, ChatPaneRuntimeAccess, ChatPaneVariant, ChatPaneWorkingDirectoryAccess, CreateDaemonAttachmentUploaderOptions, CreateMcpUiToolCallerOptions, McpUiToolCallRequest, RuntimePickerPlacement, UseChatPaneAgentControlOptions, UseChatPaneOptions, UseChatPaneResult, UseChatPaneRuntimeInventoryOptions, UseChatPaneRuntimeInventoryResult, UseChatPaneWorkingDirectoryOptions, UseChatPaneWorkingDirectoryResult, } from './features/chat-pane/index.js';
+export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, createTypedAnswerPoster, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './features/chat-pane/index.js';
+export type { AgentRuntimePickerProps, ByokRuntimeSummary, ChatPaneActivity, ChatPaneAgent, ChatPaneAgentBridgeAccess, ChatPaneAgentControlOptions, ChatPaneAgentOption, ChatPaneAgentSelection, ChatPaneAgentToolAction, ChatPaneAgentToolDef, ChatPaneAgentToolInputSchema, ChatPaneAgentToolRisk, ChatPaneAttachmentUploadOptions, ChatPaneComposerHandle, ChatPaneProps, ChatPaneRunContext, ChatPaneRunContextInput, ChatPaneRuntimeAccess, ChatPaneVariant, ChatPaneWorkingDirectoryAccess, CreateDaemonAttachmentUploaderOptions, CreateMcpUiToolCallerOptions, CreateTypedAnswerPosterOptions, DeliverTypedAnswer, McpUiToolCallRequest, RuntimePickerPlacement, TypedAnswerDelivery, TypedAnswerNotice, UseChatPaneAgentControlOptions, UseChatPaneOptions, UseChatPaneResult, UseChatPaneRuntimeInventoryOptions, UseChatPaneRuntimeInventoryResult, UseChatPaneWorkingDirectoryOptions, UseChatPaneWorkingDirectoryResult, } from './features/chat-pane/index.js';
 //# sourceMappingURL=chat-pane.d.ts.map

package/dist/react/chat-pane.js

@@ -16,5 +16,5 @@
  * `@deprecated`, so every existing `import { ChatPane } from '@jini-ai/chat/react'` keeps working
  * unchanged. New code should import from this subpath directly.
  */
-export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './features/chat-pane/index.js';
+export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, createTypedAnswerPoster, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './features/chat-pane/index.js';
 //# sourceMappingURL=chat-pane.js.map

package/dist/react/components/AttachmentPreviewModal.hooks.d.ts

@@ -36,7 +36,7 @@
  * fallback that `onError` can retract - never a second, competing source of truth for a format the
  * server already classified.
  */
-import { type MouseEvent, type RefObject, type SyntheticEvent } from 'react';
+import { type MouseEvent, type RefCallback, type SyntheticEvent } from 'react';
 import type { ChatAttachment } from '../../core/index.js';
 export type AttachmentPreviewStatus = 'image' | 'text' | 'unsupported';
 /** Hard cap on rendered text-preview characters, so a large attached log/CSV cannot hang the tab painting one giant `<pre>`. */
@@ -45,12 +45,25 @@ export declare const MAX_TEXT_PREVIEW_CHARS = 200000;
 export declare function looksLikeImageAttachment({ attachment }: {
     attachment: Pick<ChatAttachment, 'kind' | 'name'>;
 }): boolean;
+/**
+ * Reads `file` as text via `FileReader`, not the newer `Blob.prototype.text()` promise API: both
+ * are supported in every real evergreen browser, but jsdom (this package's test environment,
+ * verified directly - `File`/`Blob` here has no `.text`/`.arrayBuffer` at all) implements
+ * `FileReader.readAsText` while leaving `.text()` unimplemented. Choosing the form the test
+ * environment can actually exercise avoids a test-only monkeypatch of a browser primitive whose
+ * production behavior isn't in question - only its jsdom coverage was.
+ */
+export declare function readFileAsText({ file }: {
+    file: File;
+}, { createReader }?: {
+    createReader?: () => FileReader;
+}): Promise<string>;
 export interface AttachmentTextPreview {
     content: string;
     truncated: boolean;
 }
 export interface AttachmentPreviewController {
-    dialogRef: RefObject<HTMLDialogElement | null>;
+    dialogRef: RefCallback<HTMLDialogElement>;
     status: AttachmentPreviewStatus;
     imageUrl: string | undefined;
     onImageError: () => void;
@@ -71,5 +84,9 @@ export interface AttachmentPreviewController {
 export declare function useAttachmentPreviewModal({ attachment, onClose }: {
     attachment: ChatAttachment;
     onClose: () => void;
+}, { readText }?: {
+    readText?: (required: {
+        file: File;
+    }) => Promise<string>;
 }): AttachmentPreviewController;
 //# sourceMappingURL=AttachmentPreviewModal.hooks.d.ts.map

package/dist/react/components/AttachmentPreviewModal.hooks.js

@@ -36,7 +36,7 @@
  * fallback that `onError` can retract - never a second, competing source of truth for a format the
  * server already classified.
  */
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useState } from 'react';
 import { getAttachmentPreviewSource } from '../hooks/attachment-preview-cache.js';
 import { formatAttachmentSize } from './AttachmentTray.js';
 /** Extensions attempted as an `<img>` even when `attachment.kind` says otherwise — see module doc. */
@@ -64,9 +64,9 @@ function looksLikeTextAttachment(name) {
  * environment can actually exercise avoids a test-only monkeypatch of a browser primitive whose
  * production behavior isn't in question - only its jsdom coverage was.
  */
-function readFileAsText(file) {
+export function readFileAsText({ file }, { createReader = () => new FileReader() } = {}) {
     return new Promise((resolve, reject) => {
-        const reader = new FileReader();
+        const reader = createReader();
         reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '');
         reader.onerror = () => reject(reader.error ?? new Error('Failed to read attachment as text'));
         reader.readAsText(file);
@@ -81,6 +81,47 @@ function readFileAsText(file) {
 function canCreateObjectUrl() {
     return typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function';
 }
+/**
+ * Opens `dialog` as a modal and returns the matching close, which also restores focus to whatever
+ * was focused when it opened — see this module's doc on why the restore is explicit rather than left
+ * to the browser's own (jsdom-absent) default.
+ */
+function openModalDialog(dialog) {
+    const trigger = document.activeElement;
+    if (typeof dialog.showModal === 'function') {
+        if (!dialog.open)
+            dialog.showModal();
+    }
+    else {
+        dialog.setAttribute('open', '');
+    }
+    return () => {
+        if (typeof dialog.close === 'function') {
+            if (dialog.open)
+                dialog.close();
+        }
+        else {
+            dialog.removeAttribute('open');
+        }
+        if (trigger instanceof HTMLElement)
+            trigger.focus();
+    };
+}
+/**
+ * The `<dialog>`'s callback ref: open on attach, close + restore focus on detach. A callback ref
+ * rather than an effect reading a ref object, so the element is always in hand — there is no
+ * "not attached" case to guard. React 18 and 19 both call it with the element on mount and `null`
+ * on unmount, and attach always precedes detach, so `close` is set by the time it is called.
+ */
+function createDialogRef() {
+    let close;
+    return (dialog) => {
+        if (dialog)
+            close = openModalDialog(dialog);
+        else
+            close();
+    };
+}
 /**
  * Drives one `AttachmentPreviewModal` instance for `attachment`. The caller conditionally mounts
  * this (one open attachment at a time per `MessageRow`), so mount = open and unmount = close; there
@@ -89,9 +130,12 @@ function canCreateObjectUrl() {
  * read on mount (bounded in practice by the upload route's own 20 MB per-attachment cap, and by
  * {@link MAX_TEXT_PREVIEW_CHARS} for what actually renders).
  */
-export function useAttachmentPreviewModal({ attachment, onClose }) {
-    const dialogRef = useRef(null);
-    const triggerRef = useRef(null);
+export function useAttachmentPreviewModal({ attachment, onClose }, { readText = readFileAsText } = {}) {
+    // Lazy state, not `useCallback`: a new ref identity would make React detach and re-attach it,
+    // closing and reopening the dialog. The caller mounts a fresh instance per opened attachment (never
+    // reuses one instance across two different open attachments), so there is no "attachment changed
+    // while still open" transition for the ref to react to.
+    const [dialogRef] = useState(createDialogRef);
     const [imageFailed, setImageFailed] = useState(false);
     const [imageUrl, setImageUrl] = useState(undefined);
     const [text, setText] = useState(undefined);
@@ -120,7 +164,7 @@ export function useAttachmentPreviewModal({ attachment, onClose }) {
         }
         let canceled = false;
         setTextLoading(true);
-        readFileAsText(cachedFile)
+        readText({ file: cachedFile })
             .then((full) => {
             if (canceled)
                 return;
@@ -142,36 +186,6 @@ export function useAttachmentPreviewModal({ attachment, onClose }) {
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [attemptText, cachedFile]);
-    // Open on mount, close + restore focus on unmount — see this module's doc on why the restore is
-    // explicit rather than left to the browser's own (jsdom-absent) default.
-    useEffect(() => {
-        const dialog = dialogRef.current;
-        if (!dialog)
-            return undefined;
-        triggerRef.current = document.activeElement;
-        if (typeof dialog.showModal === 'function') {
-            if (!dialog.open)
-                dialog.showModal();
-        }
-        else {
-            dialog.setAttribute('open', '');
-        }
-        return () => {
-            if (typeof dialog.close === 'function') {
-                if (dialog.open)
-                    dialog.close();
-            }
-            else {
-                dialog.removeAttribute('open');
-            }
-            if (triggerRef.current instanceof HTMLElement)
-                triggerRef.current.focus();
-        };
-        // Mount/unmount only: the caller mounts a fresh instance per opened attachment (never reuses one
-        // instance across two different open attachments), so there is no "attachment changed while
-        // still open" transition for this effect to react to.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
     function handleNativeCancel(event) {
         // Always prevented, same reasoning as `ConfirmDialog.hooks.tsx`: the effect above is the single
         // source of truth for open/closed, so Escape still closes — it just does so through `onClose`
@@ -182,7 +196,8 @@ export function useAttachmentPreviewModal({ attachment, onClose }) {
     function handleBackdropClick(event) {
         // A `<dialog>` element's own box is sized to its content; a click landing on the `<dialog>`
         // element itself (rather than a descendant) is a click on the backdrop area outside that box.
-        if (event.target === dialogRef.current)
+        // The handler is bound on the `<dialog>`, so `currentTarget` is that element.
+        if (event.target === event.currentTarget)
             onClose();
     }
     return {

package/dist/react/components/McpUiSurfaceCard.d.ts

@@ -1,5 +1,6 @@
 import { type McpUiToolCallHandler } from '@jini-ai/ui/mcp-ui';
 import { type ExtEventRenderProps } from '../ext-event-renderer-registry.js';
+import { type SurfaceExpiryClock } from '../hooks/useSurfaceExpiry.js';
 /** The `kind: 'ext'` event name this renderer claims. */
 export declare const MCP_UI_EXT_EVENT_NAME = "mcp-ui";
 export interface McpUiSurfaceCardProps extends ExtEventRenderProps {
@@ -22,9 +23,14 @@ export interface McpUiSurfaceCardProps extends ExtEventRenderProps {
      * a fixed-width sidebar should pass a cap sized to its own viewport.
      */
     maxHeight?: number;
+    /**
+     * Time source for a card's answer deadline (`MCP_UI_EXPIRES_AT_META_KEY`). Omit for the wall clock;
+     * a test injects a fake one to step through the countdown.
+     */
+    expiryClock?: SurfaceExpiryClock;
 }
 /** Registered against `ext-event-renderer-registry.ts`'s `'mcp-ui'` name — see module doc. */
-export declare function McpUiSurfaceCard({ events, sandboxProxyUrl, onToolCall, onOpenLink, maxHeight, call, runStreaming }: McpUiSurfaceCardProps): import("react").JSX.Element;
+export declare function McpUiSurfaceCard({ events, sandboxProxyUrl, onToolCall, onOpenLink, maxHeight, call, runStreaming, expiryClock }: McpUiSurfaceCardProps): import("react").JSX.Element;
 /**
  * The ext-event slot key for MCP-UI: one slot per `ui://` URI. Each resource is its own card, so a
  * run's second card renders where it arrived instead of inside the first card's slot, while a

package/dist/react/components/McpUiSurfaceCard.js

@@ -62,9 +62,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * against the real driver in `@jini-ai/agentic`.
  */
 import { Fragment, useMemo } from 'react';
-import { McpUiHost, parseUIResource, readActionPlan, readPreferredFrameSize, } from '@jini-ai/ui/mcp-ui';
+import { McpUiHost, parseUIResource, readActionPlan, readExpiresAt, readPreferredFrameSize, } from '@jini-ai/ui/mcp-ui';
 import { registerExtEventRenderer } from '../ext-event-renderer-registry.js';
 import { useT } from '../hooks/context.js';
+import { useSurfaceExpiry } from '../hooks/useSurfaceExpiry.js';
+import { closedSurfaceLabel } from './mcp-ui-surface-state.js';
 /** The `kind: 'ext'` event name this renderer claims. */
 export const MCP_UI_EXT_EVENT_NAME = 'mcp-ui';
 /** Collapses the event stream to the newest resource per `ui://` URI, in first-appearance order. */
@@ -112,39 +114,22 @@ function pendingMirrorLabel(t, plan) {
 function PendingSurfaceMirror({ uri, plan, t }) {
     return (_jsx("div", { "aria-hidden": "true", style: { display: 'none' }, "data-agent-element": pendingMirrorHandle(uri), "data-agent-role": "status", "data-agent-label": pendingMirrorLabel(t, plan) }));
 }
-/** Words in a finished call's result that mean nobody answered in time. */
-const UNANSWERED_RESULT = /\b(expired|abandoned|did not respond|run ended)\b/i;
-/**
- * Why a card can no longer be answered, or `undefined` while it still can.
- *
- * A held-open question (the tool shows the card and waits) is over once its tool call returns, and
- * dead once its run ends without that return. Its first document stays on screen either way, so
- * without this an expired, answered or orphaned question still looked answerable (host stuck-chat
- * investigation, 2026-09-27). Only a card still showing that FIRST document closes: a tool that sent
- * a follow-up document for the same `ui://` URI (an outcome after the answer) keeps showing it.
- *
- * The labels are read from the call's result text, so they are a best guess for a producer this
- * package has not seen; the card is closed either way, which is the property that matters.
- */
-function closedLabel(t, call, runStreaming, documentsForUri) {
-    if (call === undefined || documentsForUri > 1)
-        return undefined;
-    if (call.result === undefined)
-        return runStreaming ? undefined : t('This question expired');
-    return UNANSWERED_RESULT.test(call.result.content) ? t('This question expired') : t('Answered');
-}
 /** A closed card: the question's title, when the call gave one, and why it is closed. */
 function ClosedSurface({ call, label }) {
     const title = call?.input?.title;
     return (_jsx("div", { className: "mcpui-surface-card mcpui-surface-card-closed", role: "status", children: typeof title === 'string' && title.trim() !== '' ? `${title}: ${label}` : label }));
 }
 /** Registered against `ext-event-renderer-registry.ts`'s `'mcp-ui'` name — see module doc. */
-export function McpUiSurfaceCard({ events, sandboxProxyUrl, onToolCall, onOpenLink, maxHeight, call, runStreaming }) {
+export function McpUiSurfaceCard({ events, sandboxProxyUrl, onToolCall, onOpenLink, maxHeight, call, runStreaming, expiryClock }) {
     const t = useT();
     const resources = useMemo(() => latestResourcesByUri(events), [events]);
     // One card per slot is the registered shape (`mcpUiSurfaceSlotKey`), so `call` belongs to exactly
     // that card. A group holding several URIs has no single call to judge them by, and stays live.
-    const closed = resources.length === 1 ? closedLabel(t, call, runStreaming, events.length) : undefined;
+    const single = resources.length === 1 ? resources[0] : undefined;
+    const expiry = useSurfaceExpiry({ expiresAtMs: single === undefined ? undefined : readExpiresAt(single) }, expiryClock === undefined ? {} : { clock: expiryClock });
+    const closed = single === undefined
+        ? undefined
+        : closedSurfaceLabel({ t, call, runStreaming, documentsForUri: events.length, expired: expiry?.expired === true });
     if (closed !== undefined)
         return _jsx(ClosedSurface, { call: call, label: closed });
     if (resources.length === 0) {
@@ -153,20 +138,20 @@ export function McpUiSurfaceCard({ events, sandboxProxyUrl, onToolCall, onOpenLi
         // looks like an ordinary empty turn.
         return (_jsx("div", { className: "mcpui-surface-card mcpui-surface-card-empty", role: "status", children: t('This MCP-UI event carried no renderable resource.') }));
     }
-    return (_jsx("div", { className: "mcpui-surface-card", children: resources.map((resource) => {
-            const preferred = readPreferredFrameSize(resource);
-            const height = preferred === undefined ? undefined : Number.parseInt(preferred[1], 10);
-            const plan = readActionPlan(resource);
-            return (_jsxs(Fragment, { children: [_jsx(McpUiHost, { title: resource.resource.uri, html: resource.resource.text, sandboxProxyUrl: sandboxProxyUrl, toolName: resource.resource.uri, 
-                        // The whole document, not its LENGTH. `useMcpUiHost` already defaults `sessionKey` to
-                        // `html` — exact by construction — and this override replaced that with a digest so
-                        // coarse that any two documents of equal size under one URI collided: a genuine update
-                        // (a re-rendered dialog with the same-length body, a swapped confirmation token) reused
-                        // the previous iframe session, so the handshake never re-ran and the frame kept serving
-                        // the OLD document's state. The URI stays in the key because it is real identity; the
-                        // length was never a substitute for content.
-                        sessionKey: `${resource.resource.uri}:${resource.resource.text}`, ...(onToolCall === undefined ? {} : { onToolCall }), ...(onOpenLink === undefined ? {} : { onOpenLink }), ...(height === undefined || Number.isNaN(height) ? {} : { initialHeight: height }), ...(maxHeight === undefined ? {} : { maxHeight }) }), plan !== undefined && _jsx(PendingSurfaceMirror, { uri: resource.resource.uri, plan: plan, t: t })] }, resource.resource.uri));
-        }) }));
+    return (_jsxs("div", { className: "mcpui-surface-card", children: [resources.map((resource) => {
+                const preferred = readPreferredFrameSize(resource);
+                const height = preferred === undefined ? undefined : Number.parseInt(preferred[1], 10);
+                const plan = readActionPlan(resource);
+                return (_jsxs(Fragment, { children: [_jsx(McpUiHost, { title: resource.resource.uri, html: resource.resource.text, sandboxProxyUrl: sandboxProxyUrl, toolName: resource.resource.uri, 
+                            // The whole document, not its LENGTH. `useMcpUiHost` already defaults `sessionKey` to
+                            // `html` — exact by construction — and this override replaced that with a digest so
+                            // coarse that any two documents of equal size under one URI collided: a genuine update
+                            // (a re-rendered dialog with the same-length body, a swapped confirmation token) reused
+                            // the previous iframe session, so the handshake never re-ran and the frame kept serving
+                            // the OLD document's state. The URI stays in the key because it is real identity; the
+                            // length was never a substitute for content.
+                            sessionKey: `${resource.resource.uri}:${resource.resource.text}`, ...(onToolCall === undefined ? {} : { onToolCall }), ...(onOpenLink === undefined ? {} : { onOpenLink }), ...(height === undefined || Number.isNaN(height) ? {} : { initialHeight: height }), ...(maxHeight === undefined ? {} : { maxHeight }) }), plan !== undefined && _jsx(PendingSurfaceMirror, { uri: resource.resource.uri, plan: plan, t: t })] }, resource.resource.uri));
+            }), expiry?.expired === false && (_jsx("p", { className: "mcpui-surface-expiry", role: "timer", children: t('Expires in {time}', { time: expiry.remaining }) }))] }));
 }
 /**
  * The ext-event slot key for MCP-UI: one slot per `ui://` URI. Each resource is its own card, so a

package/dist/react/components/MessageList.d.ts

@@ -1,3 +1,14 @@
+/**
+ * @module MessageList
+ *
+ * Renders a conversation's messages via `<MessageRow>`, and — matching
+ * `useConversation`'s `scrollIntent` flag (see
+ * `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §4: "message array, optimistic
+ * user message, scroll-intent flag") — auto-scrolls to the newest content
+ * whenever `scrollIntent` is true, calling `onScrolled` once it has. The
+ * scroll-anchoring state lives in `useMessageListAutoScroll`
+ * (`MessageList.hooks.ts`); see that file for why it is presentational.
+ */
 import type { ChatMessage } from '../../core/index.js';
 import { type MessageRowProps } from './MessageRow.js';
 export interface MessageListProps extends Pick<MessageRowProps, 'projectFileNames' | 'onRequestOpenFile' | 'renderAttachment'> {

package/dist/react/components/MessageList.hooks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file `MessageList`'s scroll-anchoring state, split out of the component per this package's
+ * hooks-file convention (see `AttachmentPreviewModal.hooks.ts`). Pure DOM scroll-anchoring via a ref
+ * lives here (presentational), not in the headless `useConversation` hook, per that hook's own
+ * "transport-agnostic hooks never touch DOM" contract.
+ */
+import { type RefObject, type UIEvent } from 'react';
+import type { ChatMessage } from '../../core/index.js';
+export interface MessageListAutoScroll {
+    containerRef: RefObject<HTMLDivElement | null>;
+    onScroll: (event: UIEvent<HTMLElement>) => void;
+}
+export declare function useMessageListAutoScroll({ messages, scrollIntent }: {
+    messages: ChatMessage[];
+    scrollIntent: boolean;
+}, { onScrolled }?: {
+    onScrolled?: () => void;
+}): MessageListAutoScroll;
+//# sourceMappingURL=MessageList.hooks.d.ts.map

package/dist/react/components/MessageList.hooks.js

@@ -0,0 +1,76 @@
+/**
+ * @file `MessageList`'s scroll-anchoring state, split out of the component per this package's
+ * hooks-file convention (see `AttachmentPreviewModal.hooks.ts`). Pure DOM scroll-anchoring via a ref
+ * lives here (presentational), not in the headless `useConversation` hook, per that hook's own
+ * "transport-agnostic hooks never touch DOM" contract.
+ */
+import { useEffect, useRef } from 'react';
+import { isScrolledToBottom, startsNewTurn } from './MessageList.rules.js';
+export function useMessageListAutoScroll({ messages, scrollIntent }, { onScrolled } = {}) {
+    const containerRef = useRef(null);
+    // Whether the transcript was scrolled to its bottom as of the last user scroll or programmatic
+    // scroll-to-bottom — read by the ResizeObserver effect below, which only ever sees the DOM AFTER a
+    // resize already happened and so cannot recompute "was this at the bottom" from current values.
+    // Starts true: a freshly mounted pane opens on the latest turn, same as scrollIntent's own default.
+    const stickToBottomRef = useRef(true);
+    const previousMessagesRef = useRef(messages);
+    // Runs BEFORE the scroll effect below (effects run in declaration order), so a send re-sticks in
+    // time for that same commit's scroll. The user's own send (or retry) is an explicit "take me to
+    // the latest turn": without this, a user who had scrolled up to read history and then sent stayed
+    // parked up there, because the stick gate below — correct for streamed chatter — also swallowed
+    // their own send (owner-reported "Chat auto-scroll still sticks", todos audit 2026-10-04).
+    useEffect(() => {
+        if (startsNewTurn({ previous: previousMessagesRef.current, next: messages })) {
+            stickToBottomRef.current = true;
+        }
+        previousMessagesRef.current = messages;
+    }, [messages]);
+    useEffect(() => {
+        if (!scrollIntent)
+            return;
+        const el = containerRef.current;
+        // Gated on `stickToBottomRef`, same as the ResizeObserver effect below: `scrollIntent` turns
+        // true on EVERY streamed event (tool-call chatter included, not just a finished reply — see
+        // `useConversation.applyRunToAssistantMessage`), so scrolling unconditionally here yanked a user
+        // who had deliberately scrolled up to read history back to the bottom on the very next chunk
+        // (owner-reported, 2026-08-30). `stickToBottomRef` already reflects the user's own last scroll
+        // gesture via the `onScroll` handler below, captured BEFORE this content change, so it is safe
+        // to trust here.
+        if (el && stickToBottomRef.current) {
+            el.scrollTop = el.scrollHeight;
+        }
+        onScrolled?.();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scrollIntent, messages]);
+    // Re-sticks to the bottom when a message ROW grows after mount with no accompanying `messages`
+    // change — the exact case an embedded MCP-UI/A2UI surface hits: it mounts at an initial guessed
+    // height (`preferredFrameSize` or `DEFAULT_INITIAL_HEIGHT`), then reports its real, often much
+    // taller content height asynchronously via `ui/notifications/size-changed`, entirely inside that
+    // surface's own React state (`McpUiHost`). The effect above never re-runs for that, so without this
+    // a surface which grows after the one-shot scroll leaves its own action buttons — or, once it
+    // resolves, the assistant's next reply — below the stale "bottom" with nothing to bring them back
+    // into view. Observes each direct child (one per message row) rather than the scroll container
+    // itself: the container's own box is held fixed by its flex/overflow layout, so only its CONTENT
+    // grows, which `ResizeObserver` only reports for the element whose box is actually changing.
+    // Re-created per `messages` change so a newly mounted row is observed too. Gated on
+    // `stickToBottomRef` so a human who scrolled up to read history is never yanked back down by an
+    // unrelated row resizing elsewhere in the transcript.
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el || typeof ResizeObserver !== 'function')
+            return;
+        const observer = new ResizeObserver(() => {
+            if (!stickToBottomRef.current)
+                return;
+            el.scrollTop = el.scrollHeight;
+        });
+        for (const child of Array.from(el.children))
+            observer.observe(child);
+        return () => observer.disconnect();
+    }, [messages]);
+    const onScroll = (event) => {
+        stickToBottomRef.current = isScrolledToBottom(event.currentTarget);
+    };
+    return { containerRef, onScroll };
+}
+//# sourceMappingURL=MessageList.hooks.js.map