@floegence/floeterm-terminal-web 0.4.32 → 0.5.1

package/dist/core/TerminalCore.js

@@ -1,8 +1,11 @@
 import { filterXtermAutoResponses } from '../utils/xtermAutoResponseFilter';
 import { createConsoleLogger, noopLogger } from '../utils/logger';
+import { cursorToFabricCursor, mapGhosttyRowToFabricCells, renderReasonFromForce, terminalLiveFabric, themeToFabricTheme, } from '../fabric/TerminalLiveFabric';
+import { terminalFabricCoordinator } from '../fabric/TerminalFabricCoordinator';
 import { TerminalState, } from '../types';
 import { resolveTerminalInputElement, TerminalInputBridge } from './TerminalInputBridge';
 import { terminalRenderScheduler } from './TerminalRenderScheduler';
+import { scheduleUiTurn } from '../internal/scheduleUiTurn';
 const TERMINAL_SEARCH_MAX_RESULTS = 5000;
 const PRESENTATION_SCALE_EPSILON = 0.0001;
 const GHOSTTY_DEFAULT_SCROLLBAR_RESERVE_PX = 15;
@@ -77,6 +80,25 @@ function resolveCanvasLocalDisplaySize(canvas, coordinateRoot) {
         dpr: Number.isFinite(dpr) && dpr > 0 ? dpr : 1,
     };
 }
+function syncCanvasOverlaySize(overlay, termCanvas, coordinateRoot) {
+    const { cssWidth, cssHeight, dpr } = resolveCanvasLocalDisplaySize(termCanvas, coordinateRoot);
+    if (overlay.canvas.width === termCanvas.width
+        && overlay.canvas.height === termCanvas.height
+        && overlay.cssWidth === cssWidth
+        && overlay.cssHeight === cssHeight
+        && overlay.dpr === dpr) {
+        return;
+    }
+    overlay.dpr = dpr;
+    overlay.cssWidth = cssWidth;
+    overlay.cssHeight = cssHeight;
+    overlay.canvas.style.width = `${cssWidth}px`;
+    overlay.canvas.style.height = `${cssHeight}px`;
+    overlay.canvas.width = termCanvas.width;
+    overlay.canvas.height = termCanvas.height;
+    overlay.ctx.setTransform(1, 0, 0, 1, 0, 0);
+    overlay.ctx.scale(dpr, dpr);
+}
 const getPerfProbe = () => {
     if (typeof window === 'undefined') {
         return undefined;
@@ -240,6 +262,11 @@ function canSkipCachedRowRender(renderer, row) {
     }
     return true;
 }
+function canSkipNativeCanvasRowRender(renderer, row, fabricActive) {
+    void renderer;
+    void row;
+    return fabricActive;
+}
 function samePresentationScale(left, right) {
     return Math.abs(left - right) <= PRESENTATION_SCALE_EPSILON;
 }
@@ -268,11 +295,61 @@ function normalizeNonNegativePixels(value, fallback) {
 function hasUsableClientSize(element) {
     return Boolean(element && element.clientWidth > 0 && element.clientHeight > 0);
 }
+function formatCssPixelValue(value) {
+    const normalized = Number.isFinite(value) ? Math.max(1, value) : 1;
+    return `${Math.round(normalized * 1000) / 1000}px`;
+}
 function hasTransientRendererState(renderer) {
     return Boolean(renderer.currentSelectionCoords
         || (renderer.hoveredHyperlinkId ?? 0) > 0
         || renderer.hoveredLinkRange);
 }
+function forceTransientRowsOnExit(renderer) {
+    const active = hasTransientRendererState(renderer);
+    const previous = Boolean(renderer.__floetermRowRenderCacheHadTransientState);
+    renderer.__floetermRowRenderCacheHadTransientState = active;
+    return previous && !active;
+}
+function normalizeNumberField(record, key) {
+    if (!record || typeof record !== 'object') {
+        return null;
+    }
+    const value = Number(record[key]);
+    return Number.isFinite(value) ? value : null;
+}
+function normalizeSelectionRange(value) {
+    const startCol = normalizeNumberField(value, 'startCol');
+    const startRow = normalizeNumberField(value, 'startRow');
+    const endCol = normalizeNumberField(value, 'endCol');
+    const endRow = normalizeNumberField(value, 'endRow');
+    if (startCol === null || startRow === null || endCol === null || endRow === null) {
+        return null;
+    }
+    return {
+        startCol: Math.max(0, Math.floor(startCol)),
+        startRow: Math.max(0, Math.floor(startRow)),
+        endCol: Math.max(0, Math.floor(endCol)),
+        endRow: Math.max(0, Math.floor(endRow)),
+    };
+}
+function normalizeHoverRange(value) {
+    const startX = normalizeNumberField(value, 'startX');
+    const startY = normalizeNumberField(value, 'startY');
+    const endX = normalizeNumberField(value, 'endX');
+    const endY = normalizeNumberField(value, 'endY');
+    if (startX === null || startY === null || endX === null || endY === null) {
+        return null;
+    }
+    return {
+        startX: Math.max(0, Math.floor(startX)),
+        startY: Math.max(0, Math.floor(startY)),
+        endX: Math.max(0, Math.floor(endX)),
+        endY: Math.max(0, Math.floor(endY)),
+    };
+}
+function normalizeFabricIdentifier(value) {
+    return value.trim().replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'terminal';
+}
 // TerminalCore provides a focused wrapper around ghostty-web (xterm.js API-compatible) and its fit addon.
 export class TerminalCore {
     constructor(container, config = {}, eventHandlers = {}, logger = createConsoleLogger()) {
@@ -282,6 +359,9 @@ export class TerminalCore {
         this.fitAddon = null;
         this.needsFullRenderOnNextWrite = false;
         this.demandRenderForceAll = false;
+        this.fabricView = null;
+        this.fabricAttachSeq = 0;
+        this.cancelFabricAttachSchedule = null;
         this.viewportHost = null;
         this.renderHost = null;
         this.resizeObserver = null;
@@ -345,6 +425,7 @@ export class TerminalCore {
                 this.renderDemandFrame(forceAll);
             },
         };
+        this.fabricViewId = `floeterm-view-${this.renderTask.id}`;
         TerminalCore.nextRenderTaskId += 1;
     }
     // initialize creates the ghostty-web terminal instance and binds addons.
@@ -459,6 +540,10 @@ export class TerminalCore {
         fitAddon.proposeDimensions = () => this.proposeFitDimensions();
     }
     proposeFitDimensions() {
+        const fabricDimensions = this.proposeFabricFitDimensions();
+        if (fabricDimensions) {
+            return fabricDimensions;
+        }
         const terminalAny = this.terminal;
         const renderer = terminalAny?.renderer;
         const metrics = typeof renderer?.getMetrics === 'function' ? renderer.getMetrics() : null;
@@ -488,12 +573,90 @@ export class TerminalCore {
             rows: Math.max(MIN_TERMINAL_ROWS, Math.floor(availableHeight / cellHeight)),
         };
     }
+    proposeFabricFitDimensions() {
+        if (this.config.rendererType !== 'webgl') {
+            return null;
+        }
+        const geometry = this.fabricView?.renderer.getGeometry();
+        if (!geometry) {
+            return null;
+        }
+        const cols = Math.floor(Number(geometry.cols));
+        const rows = Math.floor(Number(geometry.rows));
+        if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols <= 0 || rows <= 0) {
+            return null;
+        }
+        return {
+            cols: Math.max(MIN_TERMINAL_COLS, cols),
+            rows: Math.max(MIN_TERMINAL_ROWS, rows),
+        };
+    }
+    syncGhosttyInputGeometryToFabric() {
+        if (!this.terminal || !this.isFabricRendererActive()) {
+            return;
+        }
+        const geometry = this.fabricView?.renderer.getGeometry();
+        if (!geometry) {
+            return;
+        }
+        const terminalAny = this.terminal;
+        const renderer = terminalAny.renderer;
+        const canvas = renderer?.getCanvas?.();
+        const cols = Math.floor(Number(terminalAny.cols ?? geometry.cols));
+        const rows = Math.floor(Number(terminalAny.rows ?? geometry.rows));
+        const cellWidth = Number(geometry.cellWidth);
+        const cellHeight = Number(geometry.cellHeight);
+        if (!renderer
+            || !canvas
+            || !Number.isFinite(cols)
+            || !Number.isFinite(rows)
+            || !Number.isFinite(cellWidth)
+            || !Number.isFinite(cellHeight)
+            || cols <= 0
+            || rows <= 0
+            || cellWidth <= 0
+            || cellHeight <= 0) {
+            return;
+        }
+        const currentMetrics = renderer.getMetrics?.() ?? renderer.metrics ?? {};
+        const baselineRatio = Number(currentMetrics.height) > 0
+            ? Number(currentMetrics.baseline ?? cellHeight * 0.8) / Number(currentMetrics.height)
+            : 0.8;
+        const nextMetrics = {
+            ...currentMetrics,
+            width: cellWidth,
+            height: cellHeight,
+            baseline: Math.max(1, Math.round(cellHeight * baselineRatio)),
+        };
+        renderer.metrics = nextMetrics;
+        const gridWidth = cols * cellWidth;
+        const gridHeight = rows * cellHeight;
+        canvas.style.width = formatCssPixelValue(gridWidth);
+        canvas.style.height = formatCssPixelValue(gridHeight);
+        canvas.style.maxWidth = 'none';
+        canvas.style.maxHeight = 'none';
+        const canvasDpr = canvas.width > 0 && gridWidth > 0
+            ? canvas.width / gridWidth
+            : window.devicePixelRatio ?? 1;
+        const dpr = Number.isFinite(canvasDpr) && canvasDpr > 0 ? canvasDpr : 1;
+        const expectedWidth = Math.max(1, Math.round(gridWidth * dpr));
+        const expectedHeight = Math.max(1, Math.round(gridHeight * dpr));
+        if (canvas.width !== expectedWidth || canvas.height !== expectedHeight) {
+            canvas.width = expectedWidth;
+            canvas.height = expectedHeight;
+        }
+        canvas.style.position = 'absolute';
+        canvas.style.left = '0';
+        canvas.style.top = '0';
+        canvas.style.inset = '0 auto auto 0';
+        canvas.style.zIndex = '1';
+    }
     resolveFitElement(terminalElement) {
         const candidates = [
-            terminalElement,
             this.renderHost,
             this.viewportHost,
             this.container,
+            terminalElement,
         ];
         return candidates.find(hasUsableClientSize) ?? terminalElement ?? this.renderHost ?? this.container;
     }
@@ -591,16 +754,26 @@ export class TerminalCore {
             const viewportChanged = Number.isFinite(incomingViewportY)
                 && Number.isFinite(currentViewportY)
                 && incomingViewportY !== currentViewportY;
-            renderer.__floetermRowRenderCacheForceAll = Boolean(args[1]) || viewportChanged;
+            const forceTransientExit = forceTransientRowsOnExit(renderer);
+            const forceAll = Boolean(args[1]) || viewportChanged || forceTransientExit;
+            renderer.__floetermRowRenderCacheForceAll = forceAll;
+            const fabricFrame = this.beginFabricFrame(forceAll, args[0]);
             try {
-                return originalRender(...args);
+                const renderArgs = [...args];
+                renderArgs[1] = forceAll;
+                return originalRender(...renderArgs);
             }
             finally {
+                this.finishFabricFrame(fabricFrame);
                 renderer.__floetermRowRenderCacheForceAll = false;
             }
         };
         renderer.renderLine = (cells, row, cols) => {
             const themedCells = this.translateCellsForTheme(cells);
+            const fabricActive = this.writeFabricRow(renderer, row, themedCells, cols);
+            if (canSkipNativeCanvasRowRender(renderer, row, fabricActive)) {
+                return undefined;
+            }
             const signature = buildRowSignature(renderer, themedCells, row, cols);
             if (canSkipCachedRowRender(renderer, row) && cache.get(row) === signature) {
                 return undefined;
@@ -614,6 +787,95 @@ export class TerminalCore {
             return result;
         };
     }
+    beginFabricFrame(forceAll, buffer) {
+        const renderer = this.fabricView?.renderer;
+        if (!renderer?.isActive()) {
+            return null;
+        }
+        const dimensions = this.resolveFabricDimensions(buffer);
+        if (!dimensions) {
+            return null;
+        }
+        const frame = terminalFabricCoordinator.beginFrame(renderReasonFromForce(forceAll), forceAll);
+        const theme = this.resolveFabricTheme();
+        renderer.startFrame(frame, {
+            cols: dimensions.cols,
+            rows: dimensions.rows,
+            theme: themeToFabricTheme(theme),
+        });
+        return frame;
+    }
+    resolveFabricDimensions(buffer) {
+        const raw = buffer;
+        const dimensions = raw?.getDimensions?.();
+        const cols = Math.floor(Number(dimensions?.cols ?? this.terminal?.cols ?? 0));
+        const rows = Math.floor(Number(dimensions?.rows ?? this.terminal?.rows ?? 0));
+        if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols <= 0 || rows <= 0) {
+            return null;
+        }
+        return { cols, rows };
+    }
+    writeFabricRow(renderer, row, cells, cols) {
+        const fabricRenderer = this.fabricView?.renderer;
+        if (!fabricRenderer?.isActive()) {
+            return false;
+        }
+        fabricRenderer.writeRow(row, mapGhosttyRowToFabricCells(renderer, row, cells, cols, this.resolveFabricRowRenderHints(renderer)), cols);
+        return true;
+    }
+    resolveFabricRowRenderHints(renderer) {
+        return {
+            selection: this.resolveFabricSelectionHint(renderer),
+            hover: {
+                hyperlinkId: Number(renderer.hoveredHyperlinkId ?? 0),
+                range: normalizeHoverRange(renderer.hoveredLinkRange),
+            },
+        };
+    }
+    resolveFabricSelectionHint(renderer) {
+        const range = normalizeSelectionRange(renderer.currentSelectionCoords);
+        if (!range) {
+            return null;
+        }
+        const theme = this.resolveFabricTheme();
+        return {
+            ...range,
+            background: parseThemeColor(theme.selectionBackground ?? TERMINAL_SELECTION_BACKGROUND)
+                ?? parseThemeColor(TERMINAL_SELECTION_BACKGROUND),
+            foreground: parseThemeColor(theme.selectionForeground ?? TERMINAL_SELECTION_FOREGROUND)
+                ?? parseThemeColor(TERMINAL_SELECTION_FOREGROUND),
+        };
+    }
+    syncFabricSelectionState() {
+        const renderer = this.terminal?.renderer;
+        const selectionManager = this.terminal?.selectionManager;
+        if (!renderer || !selectionManager) {
+            return;
+        }
+        renderer.currentSelectionCoords = selectionManager.hasSelection?.()
+            ? selectionManager.getSelectionCoords?.() ?? null
+            : null;
+        renderer.__floetermRowRenderCache?.clear();
+        this.demandRenderForceAll = true;
+    }
+    finishFabricFrame(frame) {
+        const fabricRenderer = this.fabricView?.renderer;
+        if (!frame || !fabricRenderer?.isActive()) {
+            return;
+        }
+        const terminalAny = this.terminal;
+        const result = fabricRenderer.finishFrame(cursorToFabricCursor(terminalAny?.wasmTerm?.getCursor?.()));
+        if (result.rendered) {
+            terminalFabricCoordinator.completeFrame(frame, result.renderedRows, result.dirtyCells);
+        }
+    }
+    resolveFabricTheme() {
+        if (this.searchQuery.trim().length > 0 && this.searchThemeRestore) {
+            return this.applySearchThemeOverride(this.searchThemeRestore);
+        }
+        const configured = mapThemeToGhostty(this.config.theme);
+        return Object.keys(configured).length > 0 ? configured : this.terminalThemeSource;
+    }
     translateCellsForTheme(cells) {
         const translator = this.themeColorTranslator;
         if (!translator) {
@@ -706,9 +968,72 @@ export class TerminalCore {
             : null;
         selectionManager.requestRender = () => {
             originalRequestRender?.();
+            this.syncFabricSelectionState();
             this.requestDemandRender(false);
         };
     }
+    async attachFabricRenderer() {
+        if (this.fabricView || this.config.rendererType !== 'webgl' || !this.terminal) {
+            return;
+        }
+        const terminalAny = this.terminal;
+        const theme = Object.keys(this.terminalThemeSource).length > 0
+            ? this.terminalThemeSource
+            : mapThemeToGhostty(this.config.theme);
+        const fontFamily = typeof terminalAny.options?.fontFamily === 'string'
+            ? terminalAny.options.fontFamily
+            : typeof this.config.fontFamily === 'string'
+                ? this.config.fontFamily
+                : '"JetBrains Mono", monospace';
+        const fontSize = Number(terminalAny.options?.fontSize ?? this.resolveEffectiveFontSize());
+        const sessionId = normalizeFabricIdentifier(typeof this.config.sessionId === 'string' ? this.config.sessionId : this.fabricViewId);
+        this.fabricView = await terminalLiveFabric.attachView({
+            sessionId,
+            viewId: this.fabricViewId,
+            container: this.renderHost ?? this.container,
+            logger: this.logger,
+            fontFamily,
+            fontSize: Number.isFinite(fontSize) && fontSize > 0 ? fontSize : this.resolveEffectiveFontSize(),
+            theme,
+            getGhosttyCanvas: () => terminalAny.renderer?.getCanvas?.() ?? null,
+            focusInputSurface: () => this.inputBridge?.focus(),
+            forwardWheel: event => {
+                this.container.dispatchEvent(new WheelEvent(event.type, event));
+            },
+        });
+        this.fabricView.renderer.setAppearance({ theme, fontFamily, fontSize });
+        this.performResize('force');
+        this.syncGhosttyInputGeometryToFabric();
+        this.forceFullRender();
+    }
+    scheduleFabricRendererAttach() {
+        if (this.config.rendererType !== 'webgl' || this.fabricView || !this.terminal) {
+            return;
+        }
+        if (this.cancelFabricAttachSchedule !== null) {
+            return;
+        }
+        const seq = ++this.fabricAttachSeq;
+        const attach = () => {
+            this.cancelFabricAttachSchedule = null;
+            if (this.isDisposed || seq !== this.fabricAttachSeq || this.fabricView) {
+                return;
+            }
+            this.attachFabricRenderer().catch(error => {
+                if (this.isDisposed || seq !== this.fabricAttachSeq) {
+                    return;
+                }
+                this.logger.warn('[TerminalCore] Beamterm live fabric attach failed; keeping ghostty canvas live', { error });
+            });
+        };
+        this.cancelFabricAttachSchedule = scheduleUiTurn(() => {
+            if (this.isDisposed || seq !== this.fabricAttachSeq || this.fabricView) {
+                this.cancelFabricAttachSchedule = null;
+                return;
+            }
+            this.cancelFabricAttachSchedule = scheduleUiTurn(attach);
+        });
+    }
     setupInputBridge() {
         this.disposeInputBridge();
         const input = resolveTerminalInputElement(this.container);
@@ -853,6 +1178,7 @@ export class TerminalCore {
         }
         if (typeof this.terminal.onSelectionChange === 'function') {
             const disposable = this.terminal.onSelectionChange(() => {
+                this.syncFabricSelectionState();
                 this.requestDemandRender(false);
             });
             this.trackTerminalEventDisposable(disposable);
@@ -950,7 +1276,16 @@ export class TerminalCore {
         const startSeq = this.resizeNotifySeq;
         const before = this.lastNotifiedSize;
         try {
+            if (this.isFabricRendererActive()) {
+                this.resizeFabricToHost();
+            }
             this.fitAddon.fit();
+            if (this.isFabricRendererActive()) {
+                this.syncGhosttyInputGeometryToFabric();
+            }
+            if (!this.isFabricRendererActive()) {
+                this.resizeFabricToHost();
+            }
         }
         catch (error) {
             this.logger.debug('[TerminalCore] Resize failed', { error });
@@ -979,6 +1314,7 @@ export class TerminalCore {
         if (changed) {
             try {
                 this.terminal.resize(dims.cols, dims.rows);
+                this.resizeFabricToHost();
             }
             catch (error) {
                 this.logger.debug('[TerminalCore] Fixed-dimension resize failed', { error });
@@ -1254,6 +1590,82 @@ export class TerminalCore {
             bufferLength: this.terminal.buffer.active.length
         };
     }
+    readBufferLine(row, options = {}) {
+        if (!this.terminal) {
+            return '';
+        }
+        const normalizedRow = Math.floor(Number(row));
+        if (!Number.isFinite(normalizedRow) || normalizedRow < 0) {
+            return '';
+        }
+        try {
+            const line = this.terminal.buffer?.active?.getLine?.(normalizedRow);
+            const text = line?.translateToString?.(options.trimRight ?? false);
+            return typeof text === 'string' ? text : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    readBufferLines(startRow, endRowInclusive, options = {}) {
+        const start = Math.floor(Number(startRow));
+        const end = Math.floor(Number(endRowInclusive));
+        if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) {
+            return [];
+        }
+        const lines = [];
+        for (let row = Math.max(0, start); row <= end; row += 1) {
+            const text = this.readBufferLine(row, options);
+            if (text.length > 0) {
+                lines.push({ row, text });
+            }
+        }
+        return lines;
+    }
+    getTouchScrollRuntime() {
+        const terminal = this.terminal;
+        if (!terminal) {
+            return null;
+        }
+        return {
+            scrollLines: amount => {
+                const normalizedAmount = Math.trunc(Number(amount));
+                if (!Number.isFinite(normalizedAmount) || normalizedAmount === 0) {
+                    return false;
+                }
+                if (typeof terminal.scrollLines !== 'function') {
+                    return false;
+                }
+                terminal.scrollLines(normalizedAmount);
+                this.requestDemandRender(false);
+                return true;
+            },
+            getScrollbackLength: () => {
+                if (typeof terminal.getScrollbackLength !== 'function') {
+                    return 0;
+                }
+                const length = Number(terminal.getScrollbackLength());
+                return Number.isFinite(length) && length > 0 ? length : 0;
+            },
+            isAlternateScreen: () => {
+                if (typeof terminal.isAlternateScreen !== 'function') {
+                    return false;
+                }
+                return Boolean(terminal.isAlternateScreen());
+            },
+            sendAlternateScreenInput: data => {
+                const text = String(data ?? '');
+                if (!text) {
+                    return;
+                }
+                if (typeof terminal.input === 'function') {
+                    terminal.input(text, true);
+                    return;
+                }
+                this.eventHandlers.onData?.(text);
+            },
+        };
+    }
     findNext(term, options) {
         return this.findInternal(term, options, 1);
     }
@@ -1534,6 +1946,7 @@ export class TerminalCore {
         const restore = this.searchThemeRestore;
         this.searchThemeRestore = null;
         this.applyRendererTheme(terminalAny, restore);
+        this.forceFullRender();
     }
     applySearchThemeOverride(theme) {
         return {
@@ -1550,6 +1963,7 @@ export class TerminalCore {
             this.terminal.options.theme = theme;
         }
         terminalAny.renderer?.setTheme?.(theme);
+        this.fabricView?.renderer.setAppearance({ theme });
         if (this.isVisualRenderSuspended()) {
             this.markPendingDemandRender(true);
             return;
@@ -1642,6 +2056,43 @@ export class TerminalCore {
         }
         this.searchOverlay = null;
     }
+    createCanvasOverlay(zIndex) {
+        const t = this.terminal;
+        if (!t)
+            return null;
+        const renderer = t?.renderer;
+        const termCanvas = renderer?.getCanvas?.();
+        if (!termCanvas)
+            return null;
+        try {
+            const style = getComputedStyle(this.container);
+            if (style.position === 'static')
+                this.container.style.position = 'relative';
+        }
+        catch {
+        }
+        const overlay = document.createElement('canvas');
+        overlay.style.position = 'absolute';
+        overlay.style.top = '0';
+        overlay.style.left = '0';
+        overlay.style.pointerEvents = 'none';
+        overlay.style.zIndex = zIndex;
+        overlay.style.mixBlendMode = 'normal';
+        const ctx = overlay.getContext('2d');
+        if (!ctx)
+            return null;
+        this.container.appendChild(overlay);
+        const state = {
+            canvas: overlay,
+            ctx,
+            dpr: 1,
+            cssWidth: 0,
+            cssHeight: 0,
+            termCanvas,
+        };
+        syncCanvasOverlaySize(state, termCanvas, this.container);
+        return state;
+    }
     ensureSearchOverlay() {
         const t = this.terminal;
         if (!t)
@@ -1662,40 +2113,10 @@ export class TerminalCore {
             this.disposeSearchOverlay();
         }
         if (!this.searchOverlay) {
-            const overlay = document.createElement('canvas');
-            overlay.style.position = 'absolute';
-            overlay.style.top = '0';
-            overlay.style.left = '0';
-            overlay.style.pointerEvents = 'none';
-            overlay.style.zIndex = '5';
-            const ctx = overlay.getContext('2d');
-            if (!ctx)
-                return null;
-            this.container.appendChild(overlay);
-            this.searchOverlay = {
-                canvas: overlay,
-                ctx,
-                dpr: 1,
-                cssWidth: 0,
-                cssHeight: 0,
-                termCanvas
-            };
+            this.searchOverlay = this.createCanvasOverlay('5');
         }
-        const { cssWidth, cssHeight, dpr } = resolveCanvasLocalDisplaySize(termCanvas, this.container);
-        if (this.searchOverlay.canvas.width !== termCanvas.width ||
-            this.searchOverlay.canvas.height !== termCanvas.height ||
-            this.searchOverlay.cssWidth !== cssWidth ||
-            this.searchOverlay.cssHeight !== cssHeight ||
-            this.searchOverlay.dpr !== dpr) {
-            this.searchOverlay.dpr = dpr;
-            this.searchOverlay.cssWidth = cssWidth;
-            this.searchOverlay.cssHeight = cssHeight;
-            this.searchOverlay.canvas.style.width = `${cssWidth}px`;
-            this.searchOverlay.canvas.style.height = `${cssHeight}px`;
-            this.searchOverlay.canvas.width = termCanvas.width;
-            this.searchOverlay.canvas.height = termCanvas.height;
-            this.searchOverlay.ctx.setTransform(1, 0, 0, 1, 0, 0);
-            this.searchOverlay.ctx.scale(this.searchOverlay.dpr, this.searchOverlay.dpr);
+        if (this.searchOverlay) {
+            syncCanvasOverlaySize(this.searchOverlay, termCanvas, this.container);
         }
         return this.searchOverlay;
     }
@@ -1712,16 +2133,16 @@ export class TerminalCore {
         });
     }
     renderSearchOverlay() {
-        const overlay = this.ensureSearchOverlay();
-        if (!overlay)
-            return;
         const t = this.terminal;
         const queryActive = this.searchQuery.trim().length > 0;
         const rowIndex = this.searchRowIndex;
         if (!queryActive || rowIndex.size === 0 || !t) {
-            overlay.ctx.clearRect(0, 0, overlay.cssWidth, overlay.cssHeight);
+            this.searchOverlay?.ctx.clearRect(0, 0, this.searchOverlay.cssWidth, this.searchOverlay.cssHeight);
             return;
         }
+        const overlay = this.ensureSearchOverlay();
+        if (!overlay)
+            return;
         const renderer = t?.renderer;
         const charW = typeof renderer?.charWidth === 'number' ? renderer.charWidth : 0;
         const charH = typeof renderer?.charHeight === 'number' ? renderer.charHeight : 0;
@@ -1759,6 +2180,9 @@ export class TerminalCore {
     }
     setConnected(isConnected) {
         this.setState(isConnected ? TerminalState.CONNECTED : TerminalState.READY);
+        if (isConnected) {
+            this.scheduleFabricRendererAttach();
+        }
     }
     forceResize() {
         this.flushPendingPresentationScale();
@@ -1819,6 +2243,7 @@ export class TerminalCore {
             return;
         }
         this.terminal.options.fontSize = this.resolveEffectiveFontSize();
+        this.fabricView?.renderer.setAppearance({ fontSize: this.resolveEffectiveFontSize() });
         this.performResize('font');
         void this.refreshFontMetricsAfterLoad('font_size');
     }
@@ -1855,6 +2280,10 @@ export class TerminalCore {
             return;
         }
         this.terminal.options.fontFamily = nextFamily;
+        this.fabricView?.renderer.setAppearance({
+            fontFamily: nextFamily,
+            fontSize: this.resolveEffectiveFontSize(),
+        });
         this.performResize('font');
         this.forceFullRender();
         void this.refreshFontMetricsAfterLoad('font_family');
@@ -1866,6 +2295,9 @@ export class TerminalCore {
         let disposed = false;
         this.visualRenderState.suspendDepth += 1;
         this.visualRenderState.activeReasons.set(id, reason);
+        // Legacy compatibility: keep the handle lifecycle observable, but never
+        // freeze visible terminal rendering in the live fabric path.
+        this.visualRenderState.suspendDepth = Math.max(0, this.visualRenderState.suspendDepth - 1);
         return {
             id,
             reason,
@@ -1925,6 +2357,11 @@ export class TerminalCore {
         this.disposeInputBridge();
         this.disposeTerminalEventListeners();
         this.disposeSearchOverlay();
+        this.fabricAttachSeq += 1;
+        this.cancelFabricAttachSchedule?.();
+        this.cancelFabricAttachSchedule = null;
+        this.fabricView?.dispose();
+        this.fabricView = null;
         this.terminal?.dispose();
         this.terminal = null;
         this.viewportHost = null;
@@ -2098,16 +2535,28 @@ export class TerminalCore {
             this.suppressResizeNotifications = false;
         });
         this.terminal.options.fontSize = this.resolveEffectiveFontSize(nextScale);
+        this.fabricView?.renderer.setAppearance({ fontSize: this.resolveEffectiveFontSize(nextScale) });
         if (this.isVisualRenderSuspended()) {
             this.markPendingResize('force');
             this.markPendingDemandRender(true);
             this.scheduleRenderSearchOverlay();
             return;
         }
-        this.fitAddon?.fit();
+        this.performResize('force');
         this.forceFullRender();
         this.scheduleRenderSearchOverlay();
     }
+    resizeFabricToHost() {
+        const host = this.renderHost ?? this.container;
+        if (!host) {
+            return;
+        }
+        this.fabricView?.renderer.resize(host.clientWidth, host.clientHeight);
+        this.syncGhosttyInputGeometryToFabric();
+    }
+    isFabricRendererActive() {
+        return Boolean(this.fabricView?.renderer.isActive());
+    }
     forceFullRender() {
         if (!this.terminal || !this.isReady()) {
             return;