@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/app/system/settings/KeybindingsSettingsClient.tsx

@@ -14,19 +14,25 @@ export function KeybindingsSettingsClient() {
     return (
         <div className="space-y-8">
             <div className="space-y-2">
-                <p className="text-xs uppercase tracking-[0.4em] text-gray-400">{t('header.systemMenuLabel')}</p>
-                <h1 className="text-3xl font-semibold text-gray-900">{t('header.settings')}</h1>
-                <p className="max-w-3xl text-sm text-gray-600">{t('systemSettings.pageDescription')}</p>
+                <p className="text-xs uppercase tracking-[0.4em] text-gray-400 dark:text-slate-500">
+                    {t('header.systemMenuLabel')}
+                </p>
+                <h1 className="text-3xl font-semibold text-gray-900 dark:text-slate-100">{t('header.settings')}</h1>
+                <p className="max-w-3xl text-sm text-gray-600 dark:text-slate-300">
+                    {t('systemSettings.pageDescription')}
+                </p>
             </div>
 
-            <section className="rounded-[32px] border border-slate-200 bg-[radial-gradient(circle_at_top_left,_rgba(191,219,254,0.4),_transparent_34%),linear-gradient(155deg,_rgba(255,255,255,0.98),_rgba(248,250,252,0.96))] p-6 shadow-[0_20px_60px_rgba(15,23,42,0.08)]">
+            <section className="rounded-[32px] border border-slate-200 bg-[radial-gradient(circle_at_top_left,_rgba(191,219,254,0.4),_transparent_34%),linear-gradient(155deg,_rgba(255,255,255,0.98),_rgba(248,250,252,0.96))] p-6 shadow-[0_20px_60px_rgba(15,23,42,0.08)] dark:border-slate-700 dark:bg-[radial-gradient(circle_at_top_left,_rgba(56,189,248,0.14),_transparent_34%),linear-gradient(155deg,_rgba(15,23,42,0.98),_rgba(8,15,28,0.96))] dark:shadow-[0_24px_70px_rgba(2,6,23,0.42)]">
                 <div className="space-y-3">
-                    <p className="text-[0.7rem] font-semibold uppercase tracking-[0.34em] text-slate-500">
+                    <p className="text-[0.7rem] font-semibold uppercase tracking-[0.34em] text-slate-500 dark:text-slate-400">
                         {t('chatEnterBehavior.sectionEyebrow')}
                     </p>
                     <div className="space-y-2">
-                        <h2 className="text-2xl font-semibold text-slate-950">{t('chatEnterBehavior.sectionTitle')}</h2>
-                        <p className="max-w-3xl text-sm leading-7 text-slate-600">
+                        <h2 className="text-2xl font-semibold text-slate-950 dark:text-slate-100">
+                            {t('chatEnterBehavior.sectionTitle')}
+                        </h2>
+                        <p className="max-w-3xl text-sm leading-7 text-slate-600 dark:text-slate-300">
                             {t('chatEnterBehavior.sectionDescription')}
                         </p>
                     </div>

package/apps/agents-server/src/app/system/user-memory/UserMemoryClient.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import { showConfirm } from '@/src/components/AsyncDialogs/asyncDialogs';
+import { useServerLanguage } from '@/src/components/ServerLanguage/ServerLanguageProvider';
+import { formatServerLanguageHumanReadableDate } from '@/src/utils/localization/formatServerLanguageHumanReadableDate';
 import { useEffect, useMemo, useState } from 'react';
 
 /**
@@ -42,6 +44,7 @@ type UserMemoryClientProps = {
  */
 export function UserMemoryClient(props: UserMemoryClientProps) {
     const { agents } = props;
+    const { language } = useServerLanguage();
     const [memories, setMemories] = useState<UserMemoryEntry[]>([]);
     const [loading, setLoading] = useState<boolean>(true);
     const [saving, setSaving] = useState<boolean>(false);
@@ -445,7 +448,7 @@ export function UserMemoryClient(props: UserMemoryClientProps) {
                                             )}
                                         </td>
                                         <td className="px-4 py-3 text-xs text-gray-500">
-                                            {new Date(memory.updatedAt).toLocaleString()}
+                                            {formatServerLanguageHumanReadableDate(memory.updatedAt, language)}
                                         </td>
                                         <td className="px-4 py-3 text-right text-sm">
                                             {isEditing ? (
@@ -491,4 +494,3 @@ export function UserMemoryClient(props: UserMemoryClientProps) {
         </div>
     );
 }
-

package/apps/agents-server/src/app/system/user-wallet/UserWalletClient.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { WalletRecordDialog } from '@/src/components/WalletRecordDialog/WalletRecordDialog';
+import { useServerLanguage } from '@/src/components/ServerLanguage/ServerLanguageProvider';
 import type { GithubAppStatusResponse } from '@/src/utils/githubAppClient';
 import { UserWalletCreateCard } from './UserWalletCreateCard';
 import type { UserWalletAgentOption } from './UserWalletAgentOption';
@@ -34,6 +35,7 @@ function resolveGithubAppStatusDescription(status: GithubAppStatusResponse | nul
  */
 export function UserWalletClient(props: UserWalletClientProps) {
     const { agents } = props;
+    const { language } = useServerLanguage();
     const state = useUserWalletClientState({ agents });
 
     return (
@@ -118,6 +120,7 @@ export function UserWalletClient(props: UserWalletClientProps) {
 
             <UserWalletRecordsTable
                 agents={agents}
+                language={language}
                 editingDraft={state.editingDraft}
                 isEditingSmtpRecord={state.isEditingSmtpRecord}
                 isLoading={state.loading}

package/apps/agents-server/src/app/system/user-wallet/UserWalletRecordsTable.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import type { UserWalletRecord } from '@/src/utils/userWallet';
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import { formatServerLanguageHumanReadableDate } from '@/src/utils/localization/formatServerLanguageHumanReadableDate';
 import type { UserWalletAgentOption } from './UserWalletAgentOption';
 import { formatWalletJsonSchemaForTextarea, type EditingUserWalletDraft, type UpdateUserWalletDraft } from './UserWalletDraft';
 import { UserWalletRecordFormFields } from './UserWalletRecordFormFields';
@@ -11,6 +13,7 @@ import { UserWalletRecordValue } from './UserWalletRecordValue';
  */
 type UserWalletRecordsTableProps = {
     agents: ReadonlyArray<UserWalletAgentOption>;
+    language: ServerLanguageCode;
     editingDraft: EditingUserWalletDraft | null;
     isEditingSmtpRecord: boolean;
     isLoading: boolean;
@@ -31,6 +34,7 @@ type UserWalletRecordsTableProps = {
  */
 export function UserWalletRecordsTable({
     agents,
+    language,
     editingDraft,
     isEditingSmtpRecord,
     isLoading,
@@ -118,7 +122,7 @@ export function UserWalletRecordsTable({
                                         )}
                                     </td>
                                     <td className="px-4 py-3 text-xs text-gray-500">
-                                        {new Date(record.updatedAt).toLocaleString()}
+                                        {formatServerLanguageHumanReadableDate(record.updatedAt, language)}
                                     </td>
                                     <td className="px-4 py-3 text-right text-sm">
                                         {isEditing ? (

package/apps/agents-server/src/app/system/utilities/mocked-chats/MockedChatsEditorClient.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { useEffect, useMemo, useState } from 'react';
+import { useServerLanguage } from '@/src/components/ServerLanguage/ServerLanguageProvider';
 import type { MockedChatPreset } from '@/src/utils/mockedChatsSchema';
 import { MockedChatsEditorForm } from './MockedChatsEditorForm';
 import { MockedChatsEditorSidebar } from './MockedChatsEditorSidebar';
@@ -17,6 +18,7 @@ type MockedChatsEditorClientProps = {
  * Mocked chat editor under `System -> Utilities`.
  */
 export function MockedChatsEditorClient({ initialMockedChats }: MockedChatsEditorClientProps) {
+    const { language } = useServerLanguage();
     const mockedChatsEditorState = useMockedChatsEditorState({ initialMockedChats });
     const viewerHref = useMemo(
         () => buildMockedChatViewerHref(mockedChatsEditorState.draftChat.id),
@@ -47,6 +49,7 @@ export function MockedChatsEditorClient({ initialMockedChats }: MockedChatsEdito
 
                 <div className="grid gap-6 lg:grid-cols-[340px_minmax(0,1fr)]">
                     <MockedChatsEditorSidebar
+                        language={language}
                         savedChats={mockedChatsEditorState.savedChats}
                         selectedChatId={mockedChatsEditorState.selectedChatId}
                         createNewDraft={mockedChatsEditorState.createNewDraft}

package/apps/agents-server/src/app/system/utilities/mocked-chats/MockedChatsEditorSidebar.tsx

@@ -1,4 +1,6 @@
 import Link from 'next/link';
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import { formatServerLanguageHumanReadableDate } from '@/src/utils/localization/formatServerLanguageHumanReadableDate';
 import type { UseMockedChatsEditorState } from './useMockedChatsEditorState';
 
 /**
@@ -8,6 +10,7 @@ type MockedChatsEditorSidebarProps = Pick<
     UseMockedChatsEditorState,
     'savedChats' | 'selectedChatId' | 'createNewDraft' | 'selectSavedChat'
 > & {
+    language: ServerLanguageCode;
     buildViewerHref: (mockedChatId: string) => string;
 };
 
@@ -16,13 +19,8 @@ type MockedChatsEditorSidebarProps = Pick<
  *
  * @private function of <MockedChatsEditorClient/>
  */
-function formatMockedChatUpdatedAt(updatedAt: string): string {
-    const date = new Date(updatedAt);
-    if (Number.isNaN(date.getTime())) {
-        return 'just now';
-    }
-
-    return date.toLocaleString();
+function formatMockedChatUpdatedAt(updatedAt: string, language: ServerLanguageCode): string {
+    return formatServerLanguageHumanReadableDate(updatedAt, language, { fallbackLabel: 'just now' });
 }
 
 /**
@@ -31,6 +29,7 @@ function formatMockedChatUpdatedAt(updatedAt: string): string {
  * @private function of <MockedChatsEditorClient/>
  */
 export function MockedChatsEditorSidebar({
+    language,
     savedChats,
     selectedChatId,
     createNewDraft,
@@ -74,7 +73,7 @@ export function MockedChatsEditorSidebar({
                                         <div className="min-w-0">
                                             <p className="truncate text-sm font-semibold text-slate-900">{chat.name}</p>
                                             <p className="mt-1 text-xs text-slate-500">
-                                                Updated {formatMockedChatUpdatedAt(chat.updatedAt)}
+                                                Updated {formatMockedChatUpdatedAt(chat.updatedAt, language)}
                                             </p>
                                         </div>
                                         <Link

package/apps/agents-server/src/components/AdminTerminal/AdminTerminalCard.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import { Loader2, Play, Send, SquareTerminal } from 'lucide-react';
+import { Loader2, Play, SquareTerminal } from 'lucide-react';
 import type { ReactNode } from 'react';
-import { useEffect, useRef } from 'react';
 import { Card } from '../Homepage/Card';
 import type { AdminTerminalSession } from './useAdminTerminalSession';
+import { AdminXtermTerminal } from './AdminXtermTerminal';
 
 /**
  * One quick terminal action rendered next to the input box.
@@ -45,16 +45,6 @@ type AdminTerminalCardProps<TSession extends AdminTerminalSession> = {
      */
     readonly session: TSession | null;
 
-    /**
-     * Controlled terminal input value.
-     */
-    readonly input: string;
-
-    /**
-     * Updates the controlled terminal input.
-     */
-    readonly onInputChange: (value: string) => void;
-
     /**
      * Starts or reconnects to the terminal session.
      */
@@ -115,11 +105,6 @@ type AdminTerminalCardProps<TSession extends AdminTerminalSession> = {
      */
     readonly outputEmptyState: string;
 
-    /**
-     * Placeholder used by the terminal input control.
-     */
-    readonly inputPlaceholder: string;
-
     /**
      * Optional shortcut buttons that send raw terminal input.
      */
@@ -131,9 +116,6 @@ type AdminTerminalCardProps<TSession extends AdminTerminalSession> = {
     readonly children?: ReactNode;
 };
 
-const INPUT_CLASS_NAME =
-    'w-full rounded-md border border-gray-300 px-3 py-2 text-sm text-gray-900 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-200 disabled:bg-gray-50 disabled:text-gray-500';
-
 /**
  * Shared terminal card used by super-admin pages that expose interactive browser terminals.
  */
@@ -142,8 +124,6 @@ export function AdminTerminalCard<TSession extends AdminTerminalSession>({
     description,
     hint,
     session,
-    input,
-    onInputChange,
     onStart,
     onStop,
     onSend,
@@ -156,20 +136,9 @@ export function AdminTerminalCard<TSession extends AdminTerminalSession>({
     stopLabel,
     outputLabel,
     outputEmptyState,
-    inputPlaceholder,
     quickActions = [],
     children,
 }: AdminTerminalCardProps<TSession>) {
-    const outputReference = useRef<HTMLPreElement | null>(null);
-
-    useEffect(() => {
-        if (!outputReference.current) {
-            return;
-        }
-
-        outputReference.current.scrollTop = outputReference.current.scrollHeight;
-    }, [session?.output]);
-
     return (
         <Card className="hover:border-gray-200 hover:shadow-md">
             <div className="space-y-4">
@@ -221,45 +190,18 @@ export function AdminTerminalCard<TSession extends AdminTerminalSession>({
                             <span className="text-xs text-slate-500">No session started yet.</span>
                         )}
                     </div>
-                    <pre
-                        ref={outputReference}
-                        className="max-h-96 overflow-auto rounded-xl border border-slate-200 bg-slate-950 p-4 text-xs text-slate-100"
-                    >
-                        {session?.output || outputEmptyState}
-                    </pre>
+                    <AdminXtermTerminal
+                        terminalId={session?.id || `${title}:empty`}
+                        output={session?.output || ''}
+                        emptyState={outputEmptyState}
+                        isRunning={Boolean(session?.isRunning)}
+                        ariaLabel={outputLabel}
+                        onData={onSend}
+                    />
                 </div>
 
-                <form
-                    className="flex flex-col gap-3 md:flex-row"
-                    onSubmit={(event) => {
-                        event.preventDefault();
-
-                        if (!input.trim()) {
-                            return;
-                        }
-
-                        const formattedInput = input.endsWith('\n') ? input : `${input}\n`;
-                        onSend(formattedInput);
-                        onInputChange('');
-                    }}
-                >
-                    <input
-                        type="text"
-                        value={input}
-                        onChange={(event) => onInputChange(event.target.value)}
-                        disabled={!session?.isRunning || isSending}
-                        placeholder={inputPlaceholder}
-                        className={INPUT_CLASS_NAME}
-                    />
+                {quickActions.length > 0 ? (
                     <div className="flex flex-wrap gap-3">
-                        <button
-                            type="submit"
-                            disabled={!session?.isRunning || isSending || input.trim() === ''}
-                            className="inline-flex items-center justify-center gap-2 rounded-md bg-blue-600 px-4 py-2 text-sm font-semibold text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-60"
-                        >
-                            {isSending ? <Loader2 className="h-4 w-4 animate-spin" /> : <Send className="h-4 w-4" />}
-                            Send
-                        </button>
                         {quickActions.map((quickAction) => (
                             <button
                                 key={`${quickAction.label}:${quickAction.input}`}
@@ -268,11 +210,12 @@ export function AdminTerminalCard<TSession extends AdminTerminalSession>({
                                 disabled={!session?.isRunning || isSending}
                                 className="inline-flex items-center justify-center rounded-md border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-60"
                             >
+                                {isSending ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
                                 {quickAction.label}
                             </button>
                         ))}
                     </div>
-                </form>
+                ) : null}
             </div>
         </Card>
     );

package/apps/agents-server/src/components/AdminTerminal/AdminXtermTerminal.tsx

@@ -0,0 +1,330 @@
+'use client';
+
+import type { FitAddon } from '@xterm/addon-fit';
+import type { IDisposable, Terminal } from '@xterm/xterm';
+import type { MutableRefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+/**
+ * Shared xterm color palette for embedded admin terminals.
+ */
+const ADMIN_XTERM_THEME = {
+    background: '#020617',
+    foreground: '#e2e8f0',
+    cursor: '#38bdf8',
+    cursorAccent: '#020617',
+    selectionBackground: '#334155',
+    black: '#0f172a',
+    red: '#f87171',
+    green: '#34d399',
+    yellow: '#fbbf24',
+    blue: '#60a5fa',
+    magenta: '#c084fc',
+    cyan: '#22d3ee',
+    white: '#e5e7eb',
+    brightBlack: '#64748b',
+    brightRed: '#fb7185',
+    brightGreen: '#4ade80',
+    brightYellow: '#fde047',
+    brightBlue: '#93c5fd',
+    brightMagenta: '#d8b4fe',
+    brightCyan: '#67e8f9',
+    brightWhite: '#ffffff',
+};
+
+/**
+ * Disposable callback shape used by browser event listeners.
+ */
+type AdminXtermDisposable = IDisposable;
+
+/**
+ * Props accepted by the shared xterm renderer.
+ */
+type AdminXtermTerminalProps = {
+    /**
+     * Stable logical terminal identifier. Changing it resets the xterm screen.
+     */
+    readonly terminalId: string;
+
+    /**
+     * Full buffered output for the current terminal session or read-only log.
+     */
+    readonly output: string;
+
+    /**
+     * Placeholder shown inside the terminal before output arrives.
+     */
+    readonly emptyState: string;
+
+    /**
+     * Whether the attached process is currently running.
+     */
+    readonly isRunning?: boolean;
+
+    /**
+     * Whether keyboard input should be blocked.
+     */
+    readonly isReadOnly?: boolean;
+
+    /**
+     * Whether plain LF characters should be rendered as terminal line endings.
+     */
+    readonly isPlainTextOutput?: boolean;
+
+    /**
+     * Terminal height class.
+     */
+    readonly heightClassName?: string;
+
+    /**
+     * Accessible label for the terminal container.
+     */
+    readonly ariaLabel: string;
+
+    /**
+     * Sends user input bytes back to the server-side terminal session.
+     */
+    readonly onData?: (data: string) => void;
+};
+
+/**
+ * Shared xterm.js terminal renderer used by interactive admin shells and read-only log views.
+ */
+export function AdminXtermTerminal({
+    terminalId,
+    output,
+    emptyState,
+    isRunning = false,
+    isReadOnly = false,
+    isPlainTextOutput = false,
+    heightClassName = 'h-[28rem]',
+    ariaLabel,
+    onData,
+}: AdminXtermTerminalProps) {
+    const containerReference = useRef<HTMLDivElement | null>(null);
+    const terminalReference = useRef<Terminal | null>(null);
+    const fitAddonReference = useRef<FitAddon | null>(null);
+    const writtenOutputReference = useRef('');
+    const terminalIdReference = useRef(terminalId);
+    const currentTerminalIdReference = useRef(terminalId);
+    const outputReference = useRef(output);
+    const emptyStateReference = useRef(emptyState);
+    const isReadOnlyReference = useRef(isReadOnly);
+    const isRunningReference = useRef(isRunning);
+    const onDataReference = useRef(onData);
+    const isPlainTextOutputReference = useRef(isPlainTextOutput);
+
+    currentTerminalIdReference.current = terminalId;
+    outputReference.current = output;
+    emptyStateReference.current = emptyState;
+
+    useEffect(() => {
+        isReadOnlyReference.current = isReadOnly;
+        isRunningReference.current = isRunning;
+        onDataReference.current = onData;
+        isPlainTextOutputReference.current = isPlainTextOutput;
+
+        const terminal = terminalReference.current;
+        if (!terminal) {
+            return;
+        }
+
+        terminal.options.disableStdin = isReadOnly || !isRunning || !onData;
+        terminal.options.cursorBlink = !isReadOnly && isRunning;
+    }, [isPlainTextOutput, isReadOnly, isRunning, onData]);
+
+    useEffect(() => {
+        let isDisposed = false;
+        const disposables: AdminXtermDisposable[] = [];
+
+        /**
+         * Initializes xterm and its addons after the browser container is mounted.
+         */
+        async function initializeTerminal(): Promise<void> {
+            const container = containerReference.current;
+            if (!container) {
+                return;
+            }
+
+            const [{ Terminal: XtermTerminal }, { FitAddon: XtermFitAddon }] = await Promise.all([
+                import('@xterm/xterm'),
+                import('@xterm/addon-fit'),
+            ]);
+
+            if (isDisposed) {
+                return;
+            }
+
+            const terminal = new XtermTerminal({
+                allowProposedApi: false,
+                cursorBlink: !isReadOnlyReference.current && isRunningReference.current,
+                disableStdin: isReadOnlyReference.current || !isRunningReference.current || !onDataReference.current,
+                fontFamily: '"Cascadia Mono", "Fira Code", Consolas, "Liberation Mono", Menlo, monospace',
+                fontSize: 13,
+                lineHeight: 1.28,
+                scrollback: 10_000,
+                tabStopWidth: 8,
+                theme: ADMIN_XTERM_THEME,
+            });
+            const fitAddon = new XtermFitAddon();
+
+            terminal.loadAddon(fitAddon);
+            terminal.open(container);
+            terminalReference.current = terminal;
+            fitAddonReference.current = fitAddon;
+
+            disposables.push(
+                terminal.onData((data) => {
+                    if (isReadOnlyReference.current || !isRunningReference.current) {
+                        return;
+                    }
+
+                    onDataReference.current?.(data);
+                }),
+                terminal.onBinary((data) => {
+                    if (isReadOnlyReference.current || !isRunningReference.current) {
+                        return;
+                    }
+
+                    onDataReference.current?.(data);
+                }),
+            );
+
+            const fitTerminal = () => {
+                try {
+                    fitAddon.fit();
+                } catch (error) {
+                    console.warn('[admin-terminal] Failed to fit xterm terminal:', error);
+                }
+            };
+
+            window.requestAnimationFrame(fitTerminal);
+
+            if (typeof ResizeObserver !== 'undefined') {
+                const resizeObserver = new ResizeObserver(() => {
+                    window.requestAnimationFrame(fitTerminal);
+                });
+                resizeObserver.observe(container);
+                disposables.push({ dispose: () => resizeObserver.disconnect() });
+            } else {
+                window.addEventListener('resize', fitTerminal);
+                disposables.push({ dispose: () => window.removeEventListener('resize', fitTerminal) });
+            }
+
+            synchronizeTerminalOutput({
+                terminal,
+                terminalId: currentTerminalIdReference.current,
+                output: outputReference.current,
+                emptyState: emptyStateReference.current,
+                writtenOutputReference,
+                terminalIdReference,
+                isPlainTextOutput: isPlainTextOutputReference.current,
+            });
+        }
+
+        void initializeTerminal();
+
+        return () => {
+            isDisposed = true;
+            disposables.forEach((disposable) => disposable.dispose());
+            terminalReference.current?.dispose();
+            terminalReference.current = null;
+            fitAddonReference.current = null;
+            writtenOutputReference.current = '';
+        };
+    }, []);
+
+    useEffect(() => {
+        const terminal = terminalReference.current;
+        if (!terminal) {
+            return;
+        }
+
+        synchronizeTerminalOutput({
+            terminal,
+            terminalId,
+            output,
+            emptyState,
+            writtenOutputReference,
+            terminalIdReference,
+            isPlainTextOutput,
+        });
+    }, [emptyState, isPlainTextOutput, output, terminalId]);
+
+    return (
+        <div
+            className={`overflow-hidden rounded-lg border border-slate-800 bg-slate-950 shadow-sm ${heightClassName}`}
+            aria-label={ariaLabel}
+            role="region"
+            onClick={() => terminalReference.current?.focus()}
+        >
+            <div ref={containerReference} className="h-full p-3" />
+        </div>
+    );
+}
+
+/**
+ * Inputs used while synchronizing React's full output buffer into xterm's incremental writer.
+ */
+type SynchronizeTerminalOutputOptions = {
+    readonly terminal: Terminal;
+    readonly terminalId: string;
+    readonly output: string;
+    readonly emptyState: string;
+    readonly writtenOutputReference: MutableRefObject<string>;
+    readonly terminalIdReference: MutableRefObject<string>;
+    readonly isPlainTextOutput: boolean;
+};
+
+/**
+ * Writes only the appended output chunk when possible, resetting xterm when the buffer changed wholesale.
+ */
+function synchronizeTerminalOutput({
+    terminal,
+    terminalId,
+    output,
+    emptyState,
+    writtenOutputReference,
+    terminalIdReference,
+    isPlainTextOutput,
+}: SynchronizeTerminalOutputOptions): void {
+    const displayOutput = createTerminalDisplayOutput({
+        output,
+        emptyState,
+        isPlainTextOutput,
+    });
+    const previousDisplayOutput = writtenOutputReference.current;
+    const isSameTerminal = terminalIdReference.current === terminalId;
+    const isAppendOutputPossible = isSameTerminal && displayOutput.startsWith(previousDisplayOutput);
+
+    if (!isAppendOutputPossible) {
+        terminal.reset();
+        terminal.write(displayOutput);
+    } else if (displayOutput.length > previousDisplayOutput.length) {
+        terminal.write(displayOutput.slice(previousDisplayOutput.length));
+    }
+
+    terminalIdReference.current = terminalId;
+    writtenOutputReference.current = displayOutput;
+}
+
+/**
+ * Converts buffered output into a stream suitable for xterm.
+ */
+function createTerminalDisplayOutput({
+    output,
+    emptyState,
+    isPlainTextOutput,
+}: {
+    readonly output: string;
+    readonly emptyState: string;
+    readonly isPlainTextOutput: boolean;
+}): string {
+    const rawOutput = output || `\x1b[2m${emptyState}\x1b[0m\r\n`;
+
+    if (!isPlainTextOutput) {
+        return rawOutput;
+    }
+
+    return rawOutput.replace(/\r?\n/gu, '\r\n');
+}