@floegence/floeterm-terminal-web 0.4.32 → 0.5.1

package/dist/manager/TerminalInstanceController.js

@@ -0,0 +1,670 @@
+import { TerminalCore } from '../core/TerminalCore';
+import { SequenceBuffer } from '../internal/SequenceBuffer';
+import { createTerminalError } from '../utils/errors';
+import { getDefaultTerminalConfig, getThemeColors } from '../utils/config';
+import { createConsoleLogger, noopLogger } from '../utils/logger';
+import { concatChunks } from '../utils/history';
+import { terminalInitializationScheduler } from '../internal/TerminalInitializationScheduler';
+import { TerminalState, computeConnectionState, computeTerminalState, } from '../types';
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["IDLE"] = "idle";
+    ConnectionState["CONNECTING"] = "connecting";
+    ConnectionState["CONNECTED"] = "connected";
+    ConnectionState["DISCONNECTED"] = "disconnected";
+    ConnectionState["RETRYING"] = "retrying";
+    ConnectionState["FAILED"] = "failed";
+    ConnectionState["ABORTED"] = "aborted";
+})(ConnectionState || (ConnectionState = {}));
+const MAX_WRITE_BATCH_CHUNKS = 64;
+const MAX_WRITE_BATCH_BYTES = 256 * 1024;
+const createDefaultScheduler = () => ({
+    requestFrame: callback => {
+        if (typeof requestAnimationFrame === 'function') {
+            return requestAnimationFrame(callback);
+        }
+        return setTimeout(() => callback(Date.now()), 0);
+    },
+    cancelFrame: id => {
+        if (typeof cancelAnimationFrame === 'function') {
+            cancelAnimationFrame(id);
+            return;
+        }
+        clearTimeout(id);
+    },
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: id => clearTimeout(id),
+});
+export class FrameworkNeutralTerminalInstanceController {
+    constructor(options) {
+        this.listeners = new Set();
+        this.container = null;
+        this.terminalCore = null;
+        this.isInitializing = false;
+        this.terminalDataUnsubscribe = null;
+        this.sequenceBuffer = new SequenceBuffer();
+        this.replayCompleteReceived = false;
+        this.isReplayActive = false;
+        this.lastAppliedSequence = 0;
+        this.loadingState = 'idle';
+        this.loadingMessage = '';
+        this.connectionState = ConnectionState.IDLE;
+        this.connectionError = null;
+        this.retryCount = 0;
+        this.retryTimeout = null;
+        this.initializeTimeout = null;
+        this.initializationAbortController = null;
+        this.queueRetryTimeout = null;
+        this.state = {
+            state: TerminalState.IDLE,
+            error: undefined,
+            dimensions: { cols: 80, rows: 24 }
+        };
+        this.dimensions = { cols: 80, rows: 24 };
+        this.dataQueue = [];
+        this.isProcessing = false;
+        this.queueGeneration = 0;
+        this.flushRaf = null;
+        this.disposed = false;
+        this.actions = {
+            write: data => {
+                const chunk = {
+                    data: new TextEncoder().encode(data),
+                    sequence: 0,
+                    timestampMs: Date.now()
+                };
+                this.addChunkToQueue(chunk);
+            },
+            clear: () => {
+                this.terminalCore?.clear();
+                this.dataQueue = [];
+                const sessionId = this.options.sessionId;
+                if (!sessionId) {
+                    return;
+                }
+                this.options.transport.clear(sessionId)
+                    .catch(error => this.logger.warn('[TerminalInstanceController] Clear history failed', { error }))
+                    .finally(() => {
+                    this.options.transport.sendInput(sessionId, '\r')
+                        .catch(error => this.logger.warn('[TerminalInstanceController] Clear redraw failed', { error }));
+                });
+            },
+            findNext: (term, options) => this.terminalCore?.findNext(term, options) ?? false,
+            findPrevious: (term, options) => this.terminalCore?.findPrevious(term, options) ?? false,
+            clearSearch: () => this.terminalCore?.clearSearch(),
+            serialize: () => this.terminalCore?.serialize() ?? '',
+            getSelectionText: () => this.terminalCore?.getSelectionText() ?? '',
+            hasSelection: () => this.terminalCore?.hasSelection() ?? false,
+            copySelection: source => this.terminalCore?.copySelection(source) ?? Promise.resolve({
+                copied: false,
+                reason: 'empty_selection',
+                source: source ?? 'command'
+            }),
+            setConnected: connected => this.terminalCore?.setConnected(connected),
+            forceResize: () => this.terminalCore?.forceResize(),
+            setSearchResultsCallback: callback => this.terminalCore?.setSearchResultsCallback(callback),
+            focus: () => this.terminalCore?.focus(),
+            getTerminalInfo: () => this.terminalCore?.getTerminalInfo() ?? null,
+            sendInput: data => this.handleUserInput(data),
+            setAppearance: appearance => this.applyCoreAppearance(appearance),
+            setTheme: theme => this.applyCoreAppearance({ themeName: theme }),
+            setFontSize: size => this.applyCoreAppearance({ fontSize: size }),
+            setPresentationScale: scale => this.applyCoreAppearance({ presentationScale: scale }),
+            reinitialize: () => this.reinitialize(),
+        };
+        this.handleStateChange = (newState) => {
+            this.updateState({ state: newState });
+        };
+        this.handleResize = async (size) => {
+            this.dimensions = size;
+            this.updateState({ dimensions: size });
+            this.options.onResize?.(size.cols, size.rows);
+            const sessionId = this.options.sessionId;
+            if (!sessionId) {
+                return;
+            }
+            try {
+                await this.options.transport.resize(sessionId, size.cols, size.rows);
+            }
+            catch (error) {
+                this.logger.warn('[TerminalInstanceController] Resize request failed', { error });
+            }
+        };
+        this.handleError = (error) => {
+            this.updateState({ error, state: TerminalState.ERROR });
+            this.options.onError?.(error);
+        };
+        this.options = { ...options };
+        this.logger = options.logger ?? createConsoleLogger();
+        this.scheduler = options.scheduler ?? createDefaultScheduler();
+        this.subscribeToTerminalData();
+    }
+    get connection() {
+        return computeConnectionState(this.createConnectionState());
+    }
+    async mount(container) {
+        if (this.disposed) {
+            throw new Error('Cannot mount a disposed TerminalInstanceController');
+        }
+        this.container = container;
+        this.scheduleInitialize();
+    }
+    unmount() {
+        this.clearInitializeTimeout();
+        this.initializationAbortController?.abort();
+        this.initializationAbortController = null;
+        this.cleanupTerminal();
+        this.container = null;
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.clearInitializeTimeout();
+        this.initializationAbortController?.abort();
+        this.initializationAbortController = null;
+        this.clearRetryTimeout();
+        this.clearQueueRetryTimeout();
+        this.cancelDataQueueFlush();
+        this.terminalDataUnsubscribe?.();
+        this.terminalDataUnsubscribe = null;
+        this.cleanupTerminal();
+        this.updateState({ state: TerminalState.DISPOSED });
+        this.listeners.clear();
+    }
+    updateOptions(options) {
+        if (this.disposed) {
+            return;
+        }
+        const previousSessionId = this.options.sessionId;
+        const previousIsActive = this.options.isActive;
+        const previousTheme = this.options.themeName;
+        const previousFontSize = this.options.fontSize;
+        const previousFontFamily = this.options.config?.fontFamily;
+        const previousPresentationScale = this.options.presentationScale;
+        this.options = {
+            ...this.options,
+            ...options,
+            config: options.config !== undefined ? options.config : this.options.config,
+        };
+        if (options.sessionId !== undefined && options.sessionId !== previousSessionId) {
+            this.resetSessionState();
+            this.subscribeToTerminalData();
+            if (this.terminalCore) {
+                void this.reinitialize();
+            }
+            return;
+        }
+        if (options.isActive !== undefined && options.isActive !== previousIsActive) {
+            if (this.options.isActive) {
+                this.scheduleInitialize();
+                if (this.terminalCore && this.options.sessionId) {
+                    void this.connectToSession();
+                }
+            }
+            else {
+                this.terminalCore?.setConnected(false);
+            }
+        }
+        const nextFontFamily = this.options.config?.fontFamily;
+        if (previousTheme !== this.options.themeName
+            || previousFontSize !== this.options.fontSize
+            || previousFontFamily !== nextFontFamily
+            || previousPresentationScale !== this.options.presentationScale) {
+            this.applyCoreAppearance({
+                themeName: this.options.themeName,
+                ...(typeof this.options.fontSize === 'number' ? { fontSize: this.options.fontSize } : {}),
+                ...(typeof nextFontFamily === 'string' ? { fontFamily: nextFontFamily } : {}),
+                presentationScale: this.options.presentationScale ?? 1
+            });
+        }
+    }
+    getSnapshot() {
+        return {
+            state: computeTerminalState(this.state),
+            connection: computeConnectionState(this.createConnectionState()),
+            loadingState: this.loadingState,
+            loadingMessage: this.loadingMessage,
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.getSnapshot());
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    getCore() {
+        return this.terminalCore;
+    }
+    emit() {
+        if (this.disposed) {
+            return;
+        }
+        const snapshot = this.getSnapshot();
+        for (const listener of this.listeners) {
+            listener(snapshot);
+        }
+    }
+    updateState(updates) {
+        this.state = { ...this.state, ...updates };
+        this.emit();
+    }
+    setLoading(state, message) {
+        this.loadingState = state;
+        this.loadingMessage = message;
+        this.emit();
+    }
+    setConnectionState(state) {
+        this.connectionState = state;
+        this.terminalCore?.setConnected(state === ConnectionState.CONNECTED);
+        this.emit();
+    }
+    setConnectionError(error) {
+        this.connectionError = error;
+        this.emit();
+    }
+    createConnectionState() {
+        return {
+            state: this.connectionState,
+            error: this.connectionError,
+            retryCount: this.retryCount,
+            connect: () => void this.connectToSession(),
+            disconnect: () => {
+                this.clearRetryTimeout();
+                this.setConnectionState(ConnectionState.ABORTED);
+            },
+            retry: () => {
+                this.clearRetryTimeout();
+                this.retryCount = 0;
+                this.setConnectionError(null);
+                this.setConnectionState(ConnectionState.IDLE);
+                void this.connectToSession();
+            },
+            clearError: () => this.setConnectionError(null),
+        };
+    }
+    resetSessionState() {
+        this.queueGeneration += 1;
+        this.sequenceBuffer.reset(1);
+        this.replayCompleteReceived = false;
+        this.isReplayActive = false;
+        this.lastAppliedSequence = 0;
+        this.dataQueue = [];
+        this.isProcessing = false;
+        this.cancelDataQueueFlush();
+        this.clearQueueRetryTimeout();
+        this.setConnectionState(ConnectionState.IDLE);
+        this.setConnectionError(null);
+        this.retryCount = 0;
+        this.clearRetryTimeout();
+    }
+    handleUserInput(data) {
+        const sessionId = this.options.sessionId;
+        if (!sessionId) {
+            return;
+        }
+        this.options.transport.sendInput(sessionId, data).catch(error => {
+            this.logger.warn('[TerminalInstanceController] sendInput failed', { error });
+        });
+    }
+    scheduleFocus() {
+        if (!this.options.autoFocus) {
+            return;
+        }
+        this.scheduler.requestFrame(() => {
+            this.scheduler.requestFrame(() => {
+                this.terminalCore?.focus();
+            });
+        });
+    }
+    cleanupTerminal() {
+        this.initializationAbortController?.abort();
+        this.initializationAbortController = null;
+        this.isInitializing = false;
+        if (this.terminalCore) {
+            this.terminalCore.dispose();
+            this.terminalCore = null;
+        }
+        this.dataQueue = [];
+        this.isProcessing = false;
+    }
+    finishReplayIfIdle() {
+        if (!this.replayCompleteReceived || this.dataQueue.length > 0 || this.isProcessing) {
+            return;
+        }
+        if (this.isReplayActive) {
+            this.terminalCore?.endHistoryReplay?.();
+            this.isReplayActive = false;
+        }
+        this.setLoading('ready', '');
+        this.scheduleFocus();
+    }
+    scheduleDataQueueFlush() {
+        if (this.flushRaf !== null) {
+            return;
+        }
+        const generation = this.queueGeneration;
+        this.flushRaf = this.scheduler.requestFrame(() => {
+            this.flushRaf = null;
+            if (this.queueGeneration !== generation) {
+                return;
+            }
+            void this.processDataQueue();
+        });
+    }
+    cancelDataQueueFlush() {
+        if (this.flushRaf === null) {
+            return;
+        }
+        this.scheduler.cancelFrame(this.flushRaf);
+        this.flushRaf = null;
+    }
+    async processDataQueue() {
+        const generation = this.queueGeneration;
+        if (this.isProcessing || !this.terminalCore || this.dataQueue.length === 0) {
+            return;
+        }
+        const terminalState = this.terminalCore.getState();
+        if (terminalState !== TerminalState.READY && terminalState !== TerminalState.CONNECTED) {
+            this.clearQueueRetryTimeout();
+            this.queueRetryTimeout = this.scheduler.setTimer(() => {
+                this.queueRetryTimeout = null;
+                if (this.queueGeneration !== generation) {
+                    return;
+                }
+                void this.processDataQueue();
+            }, 100);
+            return;
+        }
+        this.isProcessing = true;
+        try {
+            let batchLength = 0;
+            let batchBytes = 0;
+            for (const chunk of this.dataQueue) {
+                if (batchLength >= MAX_WRITE_BATCH_CHUNKS) {
+                    break;
+                }
+                if (batchLength > 0 && batchBytes + chunk.data.byteLength > MAX_WRITE_BATCH_BYTES) {
+                    break;
+                }
+                batchLength += 1;
+                batchBytes += chunk.data.byteLength;
+            }
+            const batch = this.dataQueue.splice(0, Math.max(1, batchLength));
+            if (this.queueGeneration !== generation) {
+                return;
+            }
+            const payload = batch.length === 1 ? batch[0].data : concatChunks(batch.map(chunk => chunk.data));
+            this.terminalCore.write(payload);
+            for (const chunk of batch) {
+                if (this.queueGeneration !== generation) {
+                    return;
+                }
+                if (chunk.sequence > this.lastAppliedSequence) {
+                    this.lastAppliedSequence = chunk.sequence;
+                }
+            }
+        }
+        finally {
+            this.isProcessing = false;
+            if (this.dataQueue.length > 0) {
+                this.scheduleDataQueueFlush();
+            }
+            else {
+                this.finishReplayIfIdle();
+            }
+        }
+    }
+    addChunkToQueue(chunk) {
+        if (chunk.sequence > 0 && chunk.sequence <= this.lastAppliedSequence) {
+            return;
+        }
+        const ready = this.sequenceBuffer.push(chunk);
+        if (ready.length === 0) {
+            return;
+        }
+        this.dataQueue.push(...ready);
+        if (!this.isProcessing) {
+            this.scheduleDataQueueFlush();
+        }
+    }
+    applyCoreAppearance(appearance) {
+        const core = this.terminalCore;
+        if (!core) {
+            return;
+        }
+        const theme = appearance.themeName ? getThemeColors(appearance.themeName) : undefined;
+        if (core.setAppearance) {
+            core.setAppearance({
+                ...(theme ? { theme } : {}),
+                ...(typeof appearance.fontSize === 'number' ? { fontSize: appearance.fontSize } : {}),
+                ...(typeof appearance.fontFamily === 'string' ? { fontFamily: appearance.fontFamily } : {}),
+                ...(typeof appearance.presentationScale === 'number' ? { presentationScale: appearance.presentationScale } : {})
+            });
+            return;
+        }
+        if (theme) {
+            core.setTheme(theme);
+        }
+        if (typeof appearance.fontSize === 'number') {
+            core.setFontSize(appearance.fontSize);
+        }
+        if (typeof appearance.fontFamily === 'string') {
+            core.setFontFamily?.(appearance.fontFamily);
+        }
+        if (typeof appearance.presentationScale === 'number') {
+            core.setPresentationScale(appearance.presentationScale);
+        }
+    }
+    scheduleInitialize() {
+        if (!this.options.isActive || !this.container || this.terminalCore || this.isInitializing || this.initializeTimeout) {
+            return;
+        }
+        this.initializeTimeout = this.scheduler.setTimer(() => {
+            this.initializeTimeout = null;
+            void this.initializeTerminal();
+        }, 100);
+    }
+    clearInitializeTimeout() {
+        if (!this.initializeTimeout) {
+            return;
+        }
+        this.scheduler.clearTimer(this.initializeTimeout);
+        this.initializeTimeout = null;
+    }
+    async initializeTerminal() {
+        if (!this.container || this.isInitializing || this.terminalCore || this.disposed) {
+            return;
+        }
+        this.isInitializing = true;
+        const abortController = new AbortController();
+        this.initializationAbortController = abortController;
+        this.setLoading('initializing_terminal', 'Initializing terminal...');
+        try {
+            const permit = await terminalInitializationScheduler.acquire(abortController.signal);
+            if (!permit || abortController.signal.aborted || this.disposed || !this.container) {
+                return;
+            }
+            try {
+                const configOverrides = {
+                    ...(this.options.config ?? {}),
+                    sessionId: this.options.sessionId,
+                    ...(this.options.fontSize ? { fontSize: this.options.fontSize } : {}),
+                    ...(this.options.presentationScale ? { presentationScale: this.options.presentationScale } : {}),
+                };
+                const config = getDefaultTerminalConfig(this.options.themeName ?? 'dark', configOverrides);
+                const CoreCtor = this.options.coreConstructor ?? TerminalCore;
+                this.terminalCore = new CoreCtor(this.container, config, {
+                    onData: data => this.handleUserInput(data),
+                    onResize: size => void this.handleResize(size),
+                    onStateChange: this.handleStateChange,
+                    onError: this.handleError
+                }, this.logger ?? noopLogger);
+                await this.terminalCore.initialize();
+                if (this.isReplayActive) {
+                    this.terminalCore.startHistoryReplay(30000);
+                }
+                const sessionId = this.options.sessionId;
+                if (sessionId) {
+                    const dimensions = this.terminalCore.getDimensions();
+                    await this.options.transport.resize(sessionId, dimensions.cols, dimensions.rows);
+                }
+                void this.processDataQueue();
+                if (!this.isReplayActive || this.replayCompleteReceived) {
+                    this.setLoading('ready', '');
+                }
+                else {
+                    this.setLoading('processing_history', 'Restoring terminal...');
+                }
+                if (this.options.isActive && sessionId) {
+                    await this.connectToSession();
+                }
+            }
+            finally {
+                permit.release();
+            }
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                return;
+            }
+            this.handleError(error instanceof Error ? error : new Error(String(error)));
+            this.setLoading('ready', '');
+        }
+        finally {
+            if (this.initializationAbortController === abortController) {
+                this.initializationAbortController = null;
+                this.isInitializing = false;
+            }
+        }
+    }
+    async connectToSession() {
+        const sessionId = this.options.sessionId;
+        if (!sessionId || this.disposed) {
+            return;
+        }
+        this.clearRetryTimeout();
+        this.setConnectionState(ConnectionState.CONNECTING);
+        this.setConnectionError(null);
+        this.setLoading('attaching', 'Attaching to session...');
+        try {
+            const dims = this.terminalCore?.getDimensions() ?? this.dimensions;
+            await this.options.transport.attach(sessionId, dims.cols, dims.rows);
+            this.setConnectionState(ConnectionState.CONNECTED);
+            this.retryCount = 0;
+            this.emit();
+            if (!this.isReplayActive || this.replayCompleteReceived) {
+                this.setLoading('ready', '');
+            }
+            else {
+                this.setLoading('processing_history', 'Restoring terminal...');
+            }
+        }
+        catch (error) {
+            const terminalError = createTerminalError('transport', error);
+            this.setConnectionState(ConnectionState.FAILED);
+            this.setConnectionError(terminalError);
+            this.setLoading('ready', '');
+            this.scheduleConnectionRetry();
+        }
+    }
+    scheduleConnectionRetry() {
+        if (this.connectionState !== ConnectionState.FAILED || this.disposed) {
+            return;
+        }
+        const delay = Math.min(5000, 1000 * Math.pow(2, this.retryCount));
+        this.clearRetryTimeout();
+        this.retryTimeout = this.scheduler.setTimer(() => {
+            this.retryTimeout = null;
+            this.retryCount += 1;
+            this.setConnectionState(ConnectionState.RETRYING);
+            void this.connectToSession();
+        }, delay);
+    }
+    clearRetryTimeout() {
+        if (!this.retryTimeout) {
+            return;
+        }
+        this.scheduler.clearTimer(this.retryTimeout);
+        this.retryTimeout = null;
+    }
+    clearQueueRetryTimeout() {
+        if (!this.queueRetryTimeout) {
+            return;
+        }
+        this.scheduler.clearTimer(this.queueRetryTimeout);
+        this.queueRetryTimeout = null;
+    }
+    subscribeToTerminalData() {
+        this.terminalDataUnsubscribe?.();
+        this.terminalDataUnsubscribe = null;
+        const sessionId = this.options.sessionId;
+        if (!sessionId) {
+            return;
+        }
+        this.isReplayActive = true;
+        this.replayCompleteReceived = false;
+        this.terminalCore?.startHistoryReplay(30000);
+        this.setLoading('processing_history', 'Restoring terminal...');
+        const lastSeq = this.terminalCore ? this.lastAppliedSequence : 0;
+        const unsubscribe = this.options.eventSource.onTerminalData(sessionId, (payload) => {
+            if (payload.type === 'error') {
+                const message = payload.error || 'Terminal stream failed';
+                const terminalError = createTerminalError('connection', new Error(message));
+                this.setConnectionState(ConnectionState.FAILED);
+                this.setConnectionError(terminalError);
+                this.setLoading('ready', '');
+                this.updateState({ error: new Error(message), state: TerminalState.ERROR });
+                this.options.onError?.(new Error(message));
+                return;
+            }
+            if (payload.type === 'replay-complete') {
+                this.replayCompleteReceived = true;
+                const ready = this.sequenceBuffer.flushPending();
+                if (ready.length > 0) {
+                    this.dataQueue.push(...ready);
+                    this.scheduleDataQueueFlush();
+                }
+                else if (typeof payload.sequence === 'number'
+                    && payload.sequence > this.lastAppliedSequence
+                    && this.dataQueue.length === 0
+                    && !this.isProcessing) {
+                    this.lastAppliedSequence = payload.sequence;
+                    this.sequenceBuffer.reset(payload.sequence + 1);
+                }
+                this.finishReplayIfIdle();
+                return;
+            }
+            const chunk = {
+                data: payload.data,
+                sequence: payload.sequence ?? 0,
+                timestampMs: payload.timestampMs ?? Date.now()
+            };
+            this.addChunkToQueue(chunk);
+        }, { lastSeq });
+        this.terminalDataUnsubscribe = unsubscribe;
+    }
+    async reinitialize() {
+        this.terminalDataUnsubscribe?.();
+        this.terminalDataUnsubscribe = null;
+        this.queueGeneration += 1;
+        this.sequenceBuffer.reset(1);
+        this.replayCompleteReceived = false;
+        this.isReplayActive = true;
+        this.lastAppliedSequence = 0;
+        this.dataQueue = [];
+        this.isProcessing = false;
+        this.cancelDataQueueFlush();
+        this.clearQueueRetryTimeout();
+        this.setLoading('processing_history', 'Restoring terminal...');
+        this.cleanupTerminal();
+        this.subscribeToTerminalData();
+        await this.initializeTerminal();
+    }
+}
+export const createTerminalInstance = (options) => {
+    return new FrameworkNeutralTerminalInstanceController(options);
+};
+//# sourceMappingURL=TerminalInstanceController.js.map