cli-jaw 2.17.38 → 2.17.39

package/public/js/features/trace-drawer.ts

@@ -1,4 +1,4 @@
-import { api } from '../api.js';
+import { requestBoundedJson } from '../bounded-api.js';
 import { providerLabel } from '../provider-icons.js';
 import { escapeHtml } from '../render.js';
 
@@ -14,21 +14,40 @@ interface TraceEventDetail extends TraceEventListItem { runId: string; raw: stri
 interface TraceEventsPage { total: number; events: TraceEventListItem[]; }
 
 const PAGE_SIZE = 80;
+const MAX_READ_BYTES = 16 * 1024 * 1024;
 let currentRunId = '';
-let loadedCount = 0;
+let pageOffset = 0;
+let pageLength = 0;
+let pageLoaded = false;
+let failedOffset: number | null = null;
 let totalCount = 0;
 let loading = false;
 let openRequestId = 0;
 let selectedSeq: number | null = null;
+let traceSession: string | null = null;
+let traceController: AbortController | null = null;
+let detailController: AbortController | null = null;
+let returnFocus: HTMLElement | null = null;
 
 function eventTypeOf(event: TraceEventListItem): string { return event.eventType || event.event_type || 'event'; }
 function isCurrentRequest(requestId: number, runId = currentRunId): boolean {
     return requestId === openRequestId && runId === currentRunId;
 }
 
-function requestedOffset(seq?: number): number {
-    if (!seq || !Number.isInteger(seq) || seq < 1) return 0;
-    return Math.floor((seq - 1) / PAGE_SIZE) * PAGE_SIZE;
+function tracePath(path: string): string {
+    if (!traceSession) return path;
+    return path + (path.includes('?') ? '&' : '?') + new URLSearchParams({session:traceSession});
+}
+
+async function readTrace<T>(path: string, signal: AbortSignal): Promise<T> {
+    const response = await requestBoundedJson(path, { method: 'GET' }, signal, MAX_READ_BYTES);
+    // Preserve the existing API wrapper's envelope/bare-response compatibility.
+    if (response && typeof response === 'object' && 'ok' in response) {
+        if (response.ok !== true || !('data' in response)) throw new Error('trace_unavailable');
+        return response.data as T;
+    }
+    if (!response || typeof response !== 'object') throw new Error('trace_unavailable');
+    return response as T;
 }
 
 function ensureDrawer(): HTMLElement {
@@ -47,7 +66,12 @@ function ensureDrawer(): HTMLElement {
             <div class="trace-event-list" id="traceEventList"></div>
             <pre class="trace-event-raw" id="traceEventRaw">Select an event.</pre>
         </section>
-        <footer class="trace-drawer-footer"><button class="trace-load-more" type="button">Load more</button></footer>
+        <footer class="trace-drawer-footer">
+            <button class="trace-page-button trace-page-previous" type="button" disabled>Previous</button>
+            <span class="trace-page-status" role="status" aria-live="polite"></span>
+            <button class="trace-page-button trace-page-retry" type="button" hidden>Retry</button>
+            <button class="trace-page-button trace-load-more" type="button" disabled>Next</button>
+        </footer>
     </aside>`;
     document.body.appendChild(overlay);
     overlay.addEventListener('click', event => {
@@ -62,10 +86,24 @@ function ensureDrawer(): HTMLElement {
             markSelectedRow(selectedSeq);
             void loadEventDetail(runId, seq, openRequestId);
         }
-        if (target.closest('.trace-load-more')) void loadNextPage(openRequestId, currentRunId);
+        const pager = target.closest<HTMLButtonElement>('.trace-page-button');
+        if (!pager || pager.disabled || loading) return;
+        const offset = pager.classList.contains('trace-page-retry') ? failedOffset
+            : pager.classList.contains('trace-page-previous') ? Math.max(0, pageOffset - PAGE_SIZE)
+                : pageOffset + pageLength;
+        if (offset !== null) void loadPage(openRequestId, currentRunId, offset, pager);
     });
     document.addEventListener('keydown', event => {
         if (event.key === 'Escape' && overlay?.classList.contains('open')) closeTraceDrawer();
+        if (event.key !== 'Tab' || !overlay?.classList.contains('open')) return;
+        const controls = [...overlay.querySelectorAll<HTMLElement>('button:not([disabled]), a[href], input:not([disabled]), textarea:not([disabled]), [tabindex="0"]')]
+            .filter(node => !node.closest('[hidden]') && node.getClientRects().length > 0);
+        const first=controls[0], last=controls[controls.length-1];
+        if (!first || !last) return;
+        const active=document.activeElement;
+        if (!overlay.contains(active) || (event.shiftKey && active===first) || (!event.shiftKey && active===last)) {
+            event.preventDefault();(event.shiftKey?last:first).focus({preventScroll:true});
+        }
     });
     return overlay;
 }
@@ -74,7 +112,16 @@ function setRaw(text: string): void {
     const raw = document.getElementById('traceEventRaw');
     if (raw) raw.textContent = text;
 }
-function closeTraceDrawer(): void { document.getElementById('traceDrawerOverlay')?.classList.remove('open'); }
+export function closeTraceDrawer(): void {
+    if (!document.getElementById('traceDrawerOverlay')?.classList.contains('open')) return;
+    ++openRequestId;
+    traceController?.abort(); traceController = null;
+    detailController?.abort(); detailController = null;
+    loading = false;
+    document.getElementById('traceDrawerOverlay')?.classList.remove('open');
+    if (returnFocus?.isConnected) returnFocus.focus({preventScroll:true});
+    returnFocus = null;
+}
 
 function renderSummary(summary: TraceSummary): void {
     const title = document.getElementById('traceDrawerTitle');
@@ -114,65 +161,120 @@ function renderEventRows(events: TraceEventListItem[], runId: string): void {
             <span class="trace-event-type">${escapeHtml(eventTypeOf(event))}</span><span class="trace-event-preview">${escapeHtml(event.preview || '')}</span>
         </button>`;
     }).join('');
-    list.insertAdjacentHTML('beforeend', html);
+    list.innerHTML = html;
     markSelectedRow(selectedSeq);
 }
 
-async function loadNextPage(requestId = openRequestId, runId = currentRunId, offset = loadedCount): Promise<void> {
-    if (!runId || loading || (loadedCount >= totalCount && totalCount > 0 && offset >= loadedCount)) return;
+function updatePager(message?: string): void {
+    const previous = document.querySelector<HTMLButtonElement>('.trace-page-previous');
+    const next = document.querySelector<HTMLButtonElement>('.trace-load-more');
+    const retry = document.querySelector<HTMLButtonElement>('.trace-page-retry');
+    if (previous) previous.disabled = !pageLoaded || pageOffset === 0;
+    if (next) next.disabled = !pageLoaded || pageLength === 0 || pageOffset + pageLength >= totalCount;
+    if (retry) retry.hidden = failedOffset === null;
+    // Keep focus on the clicked button during a read; the click handler is singleflight.
+    for (const button of [previous, next, retry]) button?.setAttribute('aria-disabled', String(loading || button.disabled));
+    const status = document.querySelector('.trace-page-status');
+    if (status) status.textContent = message ?? (pageLength
+        ? `Events ${pageOffset + 1}–${pageOffset + pageLength} of ${totalCount}` : 'No retained events.');
+}
+
+function restorePageFocus(initiator: HTMLButtonElement | undefined, focused: Element | null): void {
+    // Capture focus before replacement/disable: browsers may blur a disabled button.
+    const lostControl = initiator && focused === initiator && (initiator.disabled || initiator.hidden);
+    if (!lostControl && (!focused || focused.isConnected)) return;
+    const target = document.querySelector<HTMLElement>('.trace-load-more:not([disabled])')
+        ?? document.querySelector<HTMLElement>('.trace-page-previous:not([disabled])')
+        ?? document.querySelector<HTMLElement>('.trace-drawer-close');
+    target?.focus({ preventScroll: true });
+}
+
+async function loadPage(requestId: number, runId: string, offset: number, initiator?: HTMLButtonElement): Promise<void> {
+    if (!runId || loading || !traceController || !isCurrentRequest(requestId, runId)) return;
     loading = true;
-    const page = await api<TraceEventsPage>(`/api/traces/${encodeURIComponent(runId)}/events?offset=${offset}&limit=${PAGE_SIZE}`);
-    loading = false;
-    if (!isCurrentRequest(requestId, runId)) return;
-    if (!page) {
-        if (!selectedSeq) setRaw('Trace events could not be loaded.');
+    updatePager('Loading trace events...');
+    try {
+        const page = await readTrace<TraceEventsPage>(tracePath(`/api/traces/${encodeURIComponent(runId)}/events?offset=${offset}&limit=${PAGE_SIZE}`), traceController.signal);
+        if (!isCurrentRequest(requestId, runId)) return;
+        if (!page || !Number.isSafeInteger(page.total) || page.total < 0 || !Array.isArray(page.events)
+            || page.events.length > PAGE_SIZE || page.events.some(event => !event || !Number.isSafeInteger(event.seq)
+                || event.seq < 1 || typeof event.source !== 'string')) throw new Error('invalid_trace_page');
+        const focused = document.activeElement;
+        // Commit navigation only after a successful bounded read. Selection/detail is independent.
+        renderEventRows(page.events, runId);
+        totalCount = page.total;
+        pageOffset = offset; pageLength = page.events.length; pageLoaded = true; failedOffset = null;
+        loading = false; updatePager(); restorePageFocus(initiator, focused);
+    } catch {
+        if (!isCurrentRequest(requestId, runId)) return;
+        loading = false; failedOffset = offset;
+        updatePager('Trace events could not be loaded. Retry this page.');
         return;
     }
-    totalCount = page.total || 0;
-    loadedCount = Math.max(loadedCount, offset + page.events.length);
-    renderEventRows(page.events, runId);
-    const more = document.querySelector('.trace-load-more') as HTMLButtonElement | null;
-    if (more) more.disabled = loadedCount >= totalCount;
+    if (selectedSeq === null && pageLength > 0) {
+        const first = document.querySelector<HTMLElement>('#traceEventList .trace-event-row');
+        selectedSeq = Number(first?.dataset['seq']);
+        markSelectedRow(selectedSeq);
+        await loadEventDetail(runId, selectedSeq, requestId);
+    } else if (selectedSeq === null) setRaw('No retained events.');
 }
 
 async function loadEventDetail(runId: string, seq: number, requestId = openRequestId): Promise<void> {
     if (!runId || !Number.isInteger(seq) || seq < 1) return;
-    if (!isCurrentRequest(requestId, runId)) return;
+    if (!isCurrentRequest(requestId, runId) || !traceController) return;
+    detailController?.abort();
+    const controller = new AbortController(); detailController = controller;
+    const signal = AbortSignal.any([traceController.signal, controller.signal]);
     setRaw('Loading event...');
-    const detail = await api<TraceEventDetail>(`/api/traces/${encodeURIComponent(runId)}/events/${seq}`);
-    if (!isCurrentRequest(requestId, runId) || selectedSeq !== seq) return;
-    setRaw(detail?.raw || (detail ? '(empty trace event)' : 'Trace event could not be loaded.'));
+    try {
+        const detail = await readTrace<TraceEventDetail>(tracePath(`/api/traces/${encodeURIComponent(runId)}/events/${seq}`), signal);
+        if (!isCurrentRequest(requestId, runId) || selectedSeq !== seq || signal.aborted) return;
+        if (!detail || detail.runId !== runId || detail.seq !== seq || typeof detail.raw !== 'string') throw new Error('invalid_trace_detail');
+        setRaw(detail.raw || '(empty trace event)');
+    } catch {
+        if (isCurrentRequest(requestId, runId) && selectedSeq === seq && !signal.aborted)
+            setRaw('Trace event could not be loaded. Select the event to retry.');
+    } finally { if (detailController === controller) detailController = null; }
 }
 
-export async function openTraceDrawer(runId: string, seq?: number): Promise<void> {
+export async function openTraceDrawer(runId: string, seq?: number, sessionId: string | null = null): Promise<void> {
     const overlay = ensureDrawer();
     const requestId = ++openRequestId;
-    const startOffset = requestedOffset(seq);
+    // Sequence is a sparse trace identity, not an ordinal in the retained row list.
+    traceController?.abort(); traceController = new AbortController();
+    detailController?.abort(); detailController = null;
+    traceSession = sessionId;
+    if (!overlay.contains(document.activeElement)) {
+        returnFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    }
     currentRunId = runId;
-    loadedCount = startOffset;
+    pageOffset = 0; pageLength = 0; pageLoaded = false; failedOffset = null;
     totalCount = 0;
     loading = false;
     selectedSeq = seq && Number.isInteger(seq) && seq > 0 ? seq : null;
     const list = document.getElementById('traceEventList');
     if (list) list.innerHTML = '';
+    document.getElementById('traceDrawerMeta')?.replaceChildren();
+    const title = document.getElementById('traceDrawerTitle');
+    if (title) title.textContent = 'Trace';
+    updatePager('Loading trace...');
     setRaw('Loading trace...');
     overlay.classList.add('open');
-    const summary = await api<TraceSummary>(`/api/traces/${encodeURIComponent(runId)}`);
-    if (!isCurrentRequest(requestId, runId)) return;
-    if (!summary) { setRaw('Trace is unavailable or internal-only.'); return; }
-    renderSummary(summary);
-    totalCount = summary.eventCount || 0;
+    overlay.querySelector<HTMLElement>('.trace-drawer-close')?.focus({preventScroll:true});
+    try {
+        const summary = await readTrace<TraceSummary>(tracePath(`/api/traces/${encodeURIComponent(runId)}`), traceController.signal);
+        if (!isCurrentRequest(requestId, runId)) return;
+        if (!summary || summary.id !== runId) throw new Error('invalid_trace_summary');
+        renderSummary(summary);
+        totalCount = summary.eventCount || 0;
+    } catch {
+        if (isCurrentRequest(requestId, runId)) {
+            setRaw('Trace is unavailable or internal-only.'); updatePager('Trace is unavailable.');
+        }
+        return;
+    }
     if (selectedSeq) {
         void loadEventDetail(runId, selectedSeq, requestId);
     }
-    await loadNextPage(requestId, runId, startOffset);
-    if (!selectedSeq && totalCount > 0) {
-        const firstRow = document.querySelector<HTMLElement>('.trace-event-row');
-        const firstSeq = Number(firstRow?.dataset['seq'] || 0);
-        if (firstSeq > 0) {
-            selectedSeq = firstSeq;
-            markSelectedRow(selectedSeq);
-            await loadEventDetail(runId, firstSeq, requestId);
-        }
-    }
+    await loadPage(requestId, runId, 0);
 }

package/public/js/features/ui-status.ts

@@ -10,6 +10,11 @@ export function setStatus(s: string): void {
     const btn = document.getElementById('btnSend');
     const label = document.getElementById('typingIndicator')?.querySelector('.label') as HTMLElement | null;
     state.agentBusy = s === 'running' || s === 'steering';
+    if (btn) {
+        btn.setAttribute('aria-label', state.agentBusy ? t('btn.stop') : 'Send message');
+        if (state.agentBusy) btn.setAttribute('data-i18n-aria', 'btn.stop');
+        else btn.removeAttribute('data-i18n-aria');
+    }
     document.getElementById('typingIndicator')?.classList.toggle('active', state.agentBusy);
     if (s === 'running') {
         if (badge) { badge.className = 'status-badge status-running'; badge.textContent = 'running'; }

package/public/js/state.ts

@@ -3,6 +3,7 @@
 // Object reference ensures mutations are seen across modules.
 
 import type { ProcessBlockState } from './features/process-block.js';
+import type { ActivityIdentity } from '../../src/shared/presentation.js';
 
 export type HeartbeatSchedule =
     | {
@@ -59,6 +60,7 @@ export interface ActiveGoalState {
 }
 
 export interface AppState {
+    activityIdentity: ActivityIdentity | null;
     agentBusy: boolean;
     orcState: OrcStateName;
     employees: unknown[];
@@ -82,6 +84,7 @@ export interface AppState {
 }
 
 export const state: AppState = {
+    activityIdentity: null,
     agentBusy: false,
     employees: [],
     allSkills: [],

package/public/js/ui.ts

@@ -1,6 +1,6 @@
 import { state } from './state.js';
 import { renderMarkdown, escapeHtml, stripOrchestration, linkifyFilePaths } from './render.js';
-import { renderMermaidBlocks } from './render.js';
+import { renderMermaidBlocks, releaseMermaidNodes } from './render.js';
 import { generateId } from './uuid.js';
 import { getAppName } from './features/appname.js';
 import { getAgentAvatarMarkup, getUserAvatarMarkup } from './features/avatar.js';
@@ -15,7 +15,7 @@ import { renderLiveToolActivity, cleanupToolElements, type ToolLogEntry } from '
 import { initMessageActions } from './features/message-actions.js';
 import { addSystemMsg, addMessage, removeSkeleton } from './features/chat-messages.js';
 import { buildLazyVirtualMessageItem } from './features/message-item-html.js';
-import { loadMessages } from './features/message-history.js';
+import { loadMessages, registerVirtualScrollCallbacks, ensureActivityVirtualCallbacks } from './features/message-history.js';
 import { isChatNearBottom, reconcileChatBottomAfterLayout, showChatRestoreIndicator, hideChatRestoreIndicator, hideChatRestoreIndicatorAfterSettle, reconcileChatBottomAfterRestore, scrollToBottom, ensureScrollTracking, canFollowAfterRestore, markFollowingBottom } from './features/chat-scroll.js';
 import { currentProcessBlockFromDom, hasAgentToolBlock, normalizeAgentToolBlocks, removeAgentToolBlocks, serializeProcessStepsForToolLog } from './features/process-block-dom.js';
 import { mergeExplicitAndLiveToolLogs, normalizeMessageToolLog, parseToolLog, sanitizedToolLogEntries, sanitizedToolLogJson, sanitizedToolLogJsonFromEntries, toProcessSteps, type ActiveRunSnapshot, type MessageItem, type QueuedOverlayItem } from './features/process-log-adapter.js';
@@ -429,7 +429,22 @@ function clearMermaidTransientState(root: HTMLElement): void {
     });
 }
 
-export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
+/** Correct an already-owned message without replaying final lifecycle effects. */
+export function replaceAgentAnswer(message: HTMLElement, text: string): void {
+    const content = message.querySelector<HTMLElement>('.msg-content');
+    if (!content) return;
+    const raw = stripOrchestration(text);
+    if (content.getAttribute('data-raw') === raw && (raw || content.childNodes.length === 0)) return;
+    releaseMermaidNodes(content);
+    content.innerHTML = raw ? renderMarkdown(text) : '';
+    content.setAttribute('data-raw', raw);
+    content.classList.remove('lazy-pending');
+    activateWidgets(content);
+    void renderMermaidBlocks(content, { immediate: true });
+}
+
+export function finalizeAgent(text: string | null, toolLog?: ToolLogEntry[], runtimeFinality?: 'present' | 'absent', traceRunId?: string, cacheScope?: string, cacheSessionId?: string): void {
+    const nativeFinal = runtimeFinality === 'present' || runtimeFinality === 'absent';
     // Guard: prevent double-render when both agent_done + orchestrate_done fire
     const now = Date.now();
     if (!state.currentAgentDiv && now - lastFinalizeTs < 500) return;
@@ -455,17 +470,27 @@ export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
         state.currentProcessBlock = null;
     }
     const hasTools = durableToolLog.length > 0;
-    if (text || hasTools) {
+    if (text || hasTools || nativeFinal) {
         if (!state.currentAgentDiv || !state.currentAgentDiv.isConnected) {
             state.currentAgentDiv = addMessage('agent', '');
         }
+        // Exact current-run recovery preserves the original row even when its
+        // journal has no Activity model and the first saved-answer read succeeds.
+        const preserveActivityHost = !!(state.currentAgentDiv.dataset['activityKey']
+            || state.currentAgentDiv.dataset['activityAnswerPending']
+            || traceRunId && cacheSessionId && state.currentAgentDiv.dataset['traceRunId'] === traceRunId
+                && state.currentAgentDiv.dataset['messageSessionId'] === cacheSessionId);
+        if (traceRunId) state.currentAgentDiv.dataset['traceRunId'] = traceRunId;
+        delete state.currentAgentDiv.dataset['activityRecovering'];
         state.currentAgentDiv.removeAttribute(ACTIVE_RUN_HYDRATED_ATTR);
         const content = (state.currentAgentDiv as HTMLElement)?.querySelector('.msg-content');
         // Live stream is preview-only; agent_done text is always authoritative.
         const streamedText = currentStream ? finalizeStream(currentStream, true) : '';
-        const finalText = text || streamedText;
+        const finalText = nativeFinal ? text ?? '' : text || streamedText;
         currentStream = null;
-        if (content) content.innerHTML = renderMarkdown(finalText);
+        // Empty Markdown renders a "dispatching" placeholder; native empty is a
+        // terminal result, not a loading state.
+        if (content) content.innerHTML = nativeFinal && !finalText ? '' : renderMarkdown(finalText);
         if (hasTools && state.currentAgentDiv && !hadProcessBlock && !hasAgentToolBlock(state.currentAgentDiv)) {
             const contentEl = state.currentAgentDiv.querySelector('.msg-content') as HTMLElement | null;
             if (contentEl) {
@@ -504,29 +529,37 @@ export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
                 else if (encoded) pending.dataset['diagramHtml'] = encoded;
                 widget.replaceWith(pending);
             });
-            if (durableToolLogJson) {
+            if (durableToolLogJson && !preserveActivityHost) {
+                // A first/cleared chat can activate VS from an already-rendered
+                // user row without the history loader's lazy callback.
+                if (!vs.onLazyRender) registerVirtualScrollCallbacks(vs);
                 vs.appendItem(buildLazyVirtualMessageItem({
                     role: 'assistant',
                     content: finalText,
                     cli: null,
                     tool_log: durableToolLogJson,
+                    trace_run_id: div.dataset['traceRunId'] ?? null,
                 }, vs.count));
                 releaseProcessBlockDetails(div);
                 vs.scrollToBottom();
             } else {
                 div.dataset['turnIndex'] = String(vs.count);
                 if (!div.dataset['messageId']) div.dataset['messageId'] = generateId();
+                if (preserveActivityHost) ensureActivityVirtualCallbacks(vs);
                 vs.appendLiveItem(div);
             }
             div.remove();
         }
 
         // Cache agent response for offline (use finalText to capture stream-only responses)
-        if (finalText) upsertMessage({
+        if (finalText || (traceRunId && preserveActivityHost)) upsertMessage({
             role: 'assistant',
             content: finalText,
             tool_log: durableToolLogJson,
+            trace_run_id: state.currentAgentDiv?.dataset['traceRunId'] ?? null,
             timestamp: Date.now(),
+            ...(cacheScope === undefined ? {} : { scope: cacheScope }),
+            ...(cacheSessionId === undefined ? {} : { session_id: cacheSessionId }),
         }).catch(() => {});
     }
     currentStream = null;

package/public/js/virtual-scroll.ts

@@ -28,6 +28,7 @@ export type RestoreReason =
 
 export interface VirtualItem {
     id: string;
+    messageId?: string;
     html: string;
     height: number; // used as estimateSize hint; tanstack measures real heights
     rehydratesProcessDetails?: boolean;
@@ -35,6 +36,10 @@ export interface VirtualItem {
 
 export type LazyRenderCallback = (targets: HTMLElement[]) => void;
 export type RestoreFollowPredicate = () => boolean;
+export interface VirtualLifecycleHooks {
+    postRender(root: HTMLElement): void;
+    recycle(element: HTMLElement): void;
+}
 type MeasurableVirtualElement = Pick<HTMLElement, 'getBoundingClientRect'>;
 interface ScrollAnchor {
     el: HTMLElement;
@@ -82,6 +87,23 @@ export class VirtualScroll {
 
     onLazyRender: LazyRenderCallback | null = null;
     onPostRender: ((viewport: HTMLElement) => void) | null = null;
+    onRecycle: ((element: HTMLElement) => void) | null = null;
+    private lifecycleHooks = new Set<VirtualLifecycleHooks>();
+
+    /** Add a stable owner's hooks without replacing caller-owned callbacks. */
+    addLifecycleHooks(hooks: VirtualLifecycleHooks): void {
+        this.lifecycleHooks.add(hooks);
+    }
+
+    private postRender(root: HTMLElement): void {
+        this.onPostRender?.(root);
+        for (const hooks of this.lifecycleHooks) hooks.postRender(root);
+    }
+
+    private recycle(element: HTMLElement): void {
+        this.onRecycle?.(element);
+        for (const hooks of this.lifecycleHooks) hooks.recycle(element);
+    }
 
     constructor(containerId: string) {
         this.container = document.getElementById(containerId)!;
@@ -212,15 +234,37 @@ export class VirtualScroll {
         releaseMermaidNodes(div);
         const html = div.outerHTML;
         const id = generateId();
-        this.items.push({ id, html, height: EST_HEIGHT });
+        const messageId = div.dataset['messageId'];
+        this.items.push({ id, ...(messageId ? { messageId } : {}), html, height: EST_HEIGHT });
         if (this.virtualizer) {
             this.virtualizer.setOptions({
                 ...this.virtualizer.options,
                 count: this.items.length,
             });
+            // Promotion must mount even if neither viewport nor scroll offset changed.
+            this.renderItems();
         }
     }
 
+    /** Reconcile one uniquely identified row, including an offscreen retained row. */
+    reconcileMessage(messageId: string, update: (message: HTMLElement) => void): boolean {
+        const index = this.items.findIndex(item => item.messageId === messageId);
+        if (index < 0 || this.items.some((item, i) => i !== index && item.messageId === messageId)) return false;
+        const item = this.items[index]!;
+        const mounted = this.mounted.get(index);
+        const wrapper = this.container.ownerDocument.createElement('div');
+        if (!mounted) wrapper.innerHTML = item.html;
+        const message = mounted ?? wrapper.firstElementChild as HTMLElement | null;
+        if (!message || message.dataset['messageId'] !== messageId) return false;
+        update(message);
+        item.html = message.outerHTML;
+        if (mounted && this.virtualizer) {
+            syncMeasuredItemHeight(this.items, index, mounted);
+            this.virtualizer.measureElement(mounted);
+        }
+        return true;
+    }
+
     updateItemHtml(idx: number, html: string): void {
         if (this.items[idx]) {
             this.items[idx].html = html;
@@ -376,6 +420,7 @@ export class VirtualScroll {
         if (!this._active) return;
         this.deactivate();
         this.container.innerHTML = this.items.map(it => it.html).join('');
+        this.postRender(this.container);
         this.items = [];
     }
 
@@ -385,6 +430,8 @@ export class VirtualScroll {
         this.itemGap = 0;
         this.onLazyRender = null;
         this.onPostRender = null;
+        this.onRecycle = null;
+        this.lifecycleHooks.clear();
     }
 
     // ── Activation / Deactivation ──
@@ -557,6 +604,7 @@ export class VirtualScroll {
         this.virtualizer = null;
         this._active = false;
         for (const el of this.mounted.values()) {
+            this.recycle(el);
             releaseMermaidNodes(el);
             releaseProcessBlockDetails(el);
         }
@@ -584,6 +632,7 @@ export class VirtualScroll {
 
         for (const [idx, el] of this.mounted) {
             if (!wantedSet.has(idx)) {
+                this.recycle(el);
                 releaseMermaidNodes(el);
                 const item = this.items[idx];
                 if (item?.rehydratesProcessDetails) releaseProcessBlockDetails(el);
@@ -613,6 +662,21 @@ export class VirtualScroll {
             el.style.transform = `translateY(${vItem.start}px)`;
         }
 
+        // Absolute positioning does not determine reading or keyboard order.
+        // Put new older rows before retained rows without replacing their hosts.
+        const focused = this.innerEl.contains(document.activeElement)
+            ? document.activeElement as HTMLElement : null;
+        let cursor = this.innerEl.firstElementChild;
+        for (const vItem of virtualItems) {
+            const el = this.mounted.get(vItem.index);
+            if (!el) continue;
+            if (el !== cursor) this.innerEl.insertBefore(el, cursor);
+            cursor = el.nextElementSibling;
+        }
+        if (focused?.isConnected && document.activeElement !== focused) {
+            focused.focus({ preventScroll: true });
+        }
+
         // Lazy render before measuring; markdown/code/math change heights.
         if (this.onLazyRender) {
             const lazyTargets = this.innerEl.querySelectorAll<HTMLElement>('.lazy-pending');
@@ -621,9 +685,7 @@ export class VirtualScroll {
             }
         }
 
-        if (this.onPostRender) {
-            this.onPostRender(this.innerEl);
-        }
+        this.postRender(this.innerEl);
 
         // Newly mounted elements now have their final rendered content.
         for (const el of newlyMounted) {