@floegence/floeterm-terminal-web 0.9.0 → 0.10.0

package/README.md

@@ -53,6 +53,27 @@ const core = new TerminalCore(
 await core.initialize();
 ```
 
+Floeterm projects one renderer-neutral DOM scrollbar for both canvas and WebGL terminals while Ghostty remains the only scrollback and viewport owner:
+
+```ts
+const core = new TerminalCore(container, {
+  rendererType: 'webgl',
+  fit: { scrollbarReservePx: 15 },
+  scrollbar: {
+    visibility: 'persistent', // "auto" by default, or "hidden"
+    minThumbPx: 24,
+    ariaLabel: 'Terminal history',
+  },
+});
+
+// Keep a long-lived Core aligned with a runtime locale change.
+core.setScrollbarOptions({ ariaLabel: localizedTerminalHistoryLabel });
+```
+
+The scrollbar uses a 12px visual and fine-pointer rail. Reserve at least 12px when the last terminal column must remain fully unobstructed; the default 15px reserve provides a stable gutter. An explicit `scrollbarReservePx: 0` remains supported as an overlay mode and may cover the rightmost 12px. The visual overlay itself never owns pointer hit testing: Floeterm captures fine-pointer track and thumb gestures at the viewport boundary, while wheel and touch events continue to target Ghostty's terminal surface exactly once. `persistent` automatically behaves as `auto` on coarse-pointer-only devices. Mixed-pointer devices keep mouse and pen interaction without creating a dead touch strip.
+
+`auto` reveals on terminal wheel activity, keyboard focus, or fine-pointer movement into the right-edge rail, then fades after 1,200ms of inactivity. `persistent` remains visible on fine-pointer layouts and `hidden` removes the control from pointer, tab, and accessibility access. Alternate-screen programs and empty buffers also hide it. Theme-derived idle and hover/focus colors meet 3:1 and 4.5:1 contrast targets. Drag color targets 7:1; when that ratio is mathematically impossible against the configured background, Floeterm chooses whichever of black or white provides the highest available contrast. Forced-colors and reduced-motion preferences are honored.
+
 After a host-owned layout transition or history recovery, request an explicit
 presentation fence before declaring the terminal surface ready:
 
@@ -132,7 +153,7 @@ the foreground revision that was active at that exact byte boundary.
 - Each `TerminalCore` owns an isolated `ghostty-web` WASM runtime; consumers must not provide or share a Ghostty runtime.
 - `scrollback` is measured in terminal buffer rows, including separately wrapped rows, and accepts integers from 1 through 10,000. Within the supported geometry, Floeterm preserves at least the requested number of buffer rows; it does not trim to an exact physical row count. Floeterm maps that contract to a bounded byte budget for the exact pinned `ghostty-web@0.4.0-next.14.g6a1a50d` release, which currently interprets the value as bytes. The 81,920,000-byte cap limits Ghostty's scrollback arena, not the total memory of a WASM runtime. The mapping is temporary and must be reviewed and removed or updated with any Ghostty upgrade.
 - Supported terminal geometry is limited to 500 columns. Explicit dimensions above that limit fail, while automatic fitting reports at most 500 columns.
-- Consumer dependency overrides for `ghostty-web` are unsupported. Floeterm's compatibility guard requires the exact package pin so an upstream behavior change cannot silently apply the row-to-byte mapping twice.
+- Consumer dependency overrides for `ghostty-web` are unsupported. Floeterm's compatibility guard requires the exact package pin so an upstream behavior change cannot silently apply the row-to-byte mapping twice or reactivate the native canvas scrollbar beneath the renderer-neutral DOM control.
 - `TerminalCore` bridges the hidden textarea used by `ghostty-web`, so soft-keyboard and composition input continue to work on touch devices.
 - The hidden terminal input is mounted in the document viewport plane and anchored from rendered cursor geometry, so native IME candidate windows stay aligned without expanding transformed terminal hosts.
 - Programmatic terminal focus uses no-scroll focus by default, keeping embedded terminals stable inside scaled, projected, or otherwise transformed host surfaces.

package/dist/core/TerminalCore.d.ts

@@ -1,4 +1,4 @@
-import { TerminalState, type Logger, type TerminalConfig, type TerminalCopySelectionResult, type TerminalCopySelectionSource, type TerminalDimensions, type TerminalEventHandlers, type TerminalFocusOptions, type TerminalAppearance, type TerminalLinkProvider, type TerminalRuntimeLineSnapshot, type TerminalRestorableSnapshot, type TerminalRestorableSnapshotOptions, type TerminalResourceEstimate, type TerminalTouchScrollRuntime, type TerminalInitializationOptions, type TerminalVisualSuspendHandle, type TerminalVisualSuspendOptions } from '../types.js';
+import { TerminalState, type Logger, type TerminalConfig, type TerminalCopySelectionResult, type TerminalCopySelectionSource, type TerminalDimensions, type TerminalEventHandlers, type TerminalFocusOptions, type TerminalAppearance, type TerminalLinkProvider, type TerminalScrollbarOptions, type TerminalRuntimeLineSnapshot, type TerminalRestorableSnapshot, type TerminalRestorableSnapshotOptions, type TerminalResourceEstimate, type TerminalTouchScrollRuntime, type TerminalInitializationOptions, type TerminalVisualSuspendHandle, type TerminalVisualSuspendOptions } from '../types.js';
 export { preloadTerminalResources } from '../internal/TerminalResourceLoader.js';
 export declare class TerminalCore {
     private container;
@@ -24,6 +24,7 @@ export declare class TerminalCore {
     private inputElement;
     private viewportHost;
     private renderHost;
+    private scrollbarOverlay;
     private resizeObserver;
     private resizeDebounceTimer;
     private resizeRaf;
@@ -51,6 +52,7 @@ export declare class TerminalCore {
     private suppressResizeNotifications;
     private clearResizeSuppressionRaf;
     private readonly scrollbackRows;
+    private scrollbarOptions;
     private hasFocus;
     private resizeNotifySeq;
     private lastNotifiedSize;
@@ -79,6 +81,7 @@ export declare class TerminalCore {
     private loadAddons;
     private openTerminal;
     private mountInputElement;
+    private mountScrollbarOverlay;
     private installLinkDetector;
     private installFitAddonGeometryPatch;
     private proposeFitDimensions;
@@ -216,6 +219,7 @@ export declare class TerminalCore {
     private forceResizeAndWaitForCommittedFrame;
     setFixedDimensions(dimensions: TerminalDimensions | null): void;
     setAppearance(appearance: TerminalAppearance): void;
+    setScrollbarOptions(options: Partial<TerminalScrollbarOptions>): void;
     setTheme(theme: Record<string, unknown>): void;
     setFontSize(size: number): void;
     setPresentationScale(scale: number): void;

package/dist/core/TerminalCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerminalCore.d.ts","sourceRoot":"","sources":["../../src/core/TerminalCore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TerminalCore.d.ts","sourceRoot":"","sources":["../../src/core/TerminalCore.ts"],"names":[],"mappings":"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"}

package/dist/core/TerminalCore.js

@@ -6,10 +6,13 @@ import { TerminalState, } from '../types.js';
 import { terminalInitializationScheduler, } from '../internal/TerminalInitializationScheduler.js';
 import { acquireGhosttyRuntime, getGhosttyFitAddonConstructor, getGhosttyLinkConstructors, getGhosttyTerminalConstructor, inspectGhosttyRuntimeMemory, loadGhosttyModules, waitWithAbort, } from '../internal/TerminalResourceLoader.js';
 import { capAutoFitTerminalColumns, mapGhosttyScrollbackRowsForPinnedVersion, validateTerminalColumns, validateTerminalScrollbackRows, } from '../internal/GhosttyScrollbackCompat.js';
+import { installPinnedGhosttyAlternateScreenProjection, suppressPinnedGhosttyScrollbarBeforeOpen, suppressPinnedGhosttyScrollbarRenderer, } from '../internal/GhosttyScrollbarCompat.js';
 import { createUnicodeSafeUrlProviderTerminal, } from '../internal/UnicodeSafeUrlProvider.js';
 import { resolveTerminalInputElement, TerminalInputBridge } from './TerminalInputBridge.js';
 import { terminalRenderScheduler } from './TerminalRenderScheduler.js';
 import { scheduleUiTurn } from '../internal/scheduleUiTurn.js';
+import { parseThemeColor } from '../utils/themeColor.js';
+import { normalizeTerminalScrollbarOptions, TerminalScrollbarOverlay, } from './TerminalScrollbarOverlay.js';
 const TERMINAL_SNAPSHOT_VERSION = 1;
 const DEFAULT_TERMINAL_SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
 const ESTIMATED_RENDERER_BYTES = 4 * 1024 * 1024;
@@ -131,41 +134,6 @@ const mapThemeToGhostty = (theme) => {
     }
     return mapped;
 };
-function normalizeThemeColor(value) {
-    if (!value) {
-        return null;
-    }
-    const trimmed = value.trim();
-    const shortHex = /^#([0-9a-fA-F]{3})$/.exec(trimmed);
-    if (shortHex) {
-        const [r, g, b] = shortHex[1].split('');
-        return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
-    }
-    if (/^#[0-9a-fA-F]{6}$/.test(trimmed)) {
-        return trimmed.toLowerCase();
-    }
-    const rgb = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/.exec(trimmed);
-    if (!rgb) {
-        return null;
-    }
-    const channels = rgb.slice(1).map(channel => Number(channel));
-    if (channels.some(channel => !Number.isInteger(channel) || channel < 0 || channel > 255)) {
-        return null;
-    }
-    return `#${channels.map(channel => channel.toString(16).padStart(2, '0')).join('')}`;
-}
-function parseThemeColor(value) {
-    const normalized = normalizeThemeColor(value);
-    if (!normalized) {
-        return null;
-    }
-    const hex = normalized.slice(1);
-    return {
-        r: Number.parseInt(hex.slice(0, 2), 16),
-        g: Number.parseInt(hex.slice(2, 4), 16),
-        b: Number.parseInt(hex.slice(4, 6), 16),
-    };
-}
 function colorKey(color) {
     return `${color.r},${color.g},${color.b}`;
 }
@@ -359,6 +327,7 @@ export class TerminalCore {
         this.inputElement = null;
         this.viewportHost = null;
         this.renderHost = null;
+        this.scrollbarOverlay = null;
         this.resizeObserver = null;
         this.resizeDebounceTimer = null;
         this.resizeRaf = null;
@@ -416,6 +385,7 @@ export class TerminalCore {
         this.eventHandlers = eventHandlers;
         this.clipboard = TerminalCore.normalizeClipboardConfig(config?.clipboard);
         this.fit = TerminalCore.normalizeFitConfig(config?.fit);
+        this.scrollbarOptions = normalizeTerminalScrollbarOptions(config?.scrollbar);
         this.logger = logger ?? noopLogger;
         this.responsive = TerminalCore.normalizeResponsiveConfig(config?.responsive);
         this.logicalFontSize = TerminalCore.normalizeFontSize(config?.fontSize);
@@ -426,6 +396,7 @@ export class TerminalCore {
             ...(explicitCols === undefined ? {} : { cols: explicitCols }),
             fixedDimensions: this.fixedDimensions,
             scrollback: this.scrollbackRows,
+            scrollbar: this.scrollbarOptions,
         };
         this.renderTask = {
             id: TerminalCore.nextRenderTaskId,
@@ -567,6 +538,8 @@ export class TerminalCore {
         this.resizeObserver = null;
         this.disposeInputBridge();
         this.disposeTerminalEventListeners();
+        this.scrollbarOverlay?.dispose();
+        this.scrollbarOverlay = null;
         this.fabricView?.dispose();
         this.fabricView = null;
         this.terminal?.dispose();
@@ -653,7 +626,11 @@ export class TerminalCore {
         const renderHost = this.ensurePresentationHosts();
         this.applyPresentationScaleStyles();
         this.installDemandRenderPatchBeforeOpen();
+        suppressPinnedGhosttyScrollbarBeforeOpen(this.terminal);
         this.terminal.open(renderHost);
+        installPinnedGhosttyAlternateScreenProjection(this.terminal);
+        const renderer = this.terminal.renderer;
+        suppressPinnedGhosttyScrollbarRenderer(renderer ?? {});
         this.installLinkDetector();
         if (this.config.rendererType === 'webgl') {
             const canvas = this.terminal
@@ -667,6 +644,7 @@ export class TerminalCore {
         this.patchSelectionManagerClipboardBehavior();
         this.patchSelectionManagerRenderingBehavior();
         this.setupInputBridge(renderHost);
+        this.mountScrollbarOverlay();
         this.applyRegisteredLinkProviders();
         void this.refreshFontMetricsAfterLoad('open');
     }
@@ -682,6 +660,30 @@ export class TerminalCore {
         body.appendChild(input);
         this.inputElement = input;
     }
+    mountScrollbarOverlay() {
+        if (!this.terminal || !this.viewportHost || !this.renderHost) {
+            throw new Error('Terminal scrollbar requires an initialized presentation host');
+        }
+        this.scrollbarOverlay?.dispose();
+        const terminal = this.terminal;
+        const surfaceId = `${this.fabricViewId}-surface`;
+        this.renderHost.id = surfaceId;
+        this.scrollbarOverlay = new TerminalScrollbarOverlay(this.viewportHost, {
+            get rows() {
+                return terminal.rows;
+            },
+            getScrollbackLength: () => terminal.getScrollbackLength(),
+            getViewportY: () => terminal.getViewportY(),
+            isAlternateScreen: () => terminal.isAlternateScreen(),
+            scrollToLine: line => terminal.scrollToLine(line),
+            scrollToTop: () => terminal.scrollToTop(),
+            scrollToBottom: () => terminal.scrollToBottom(),
+            scrollLines: amount => terminal.scrollLines(amount),
+            scrollPages: amount => terminal.scrollPages(amount),
+            focusTerminal: () => this.scheduleInputSurfaceRefocus({ preventScroll: true }),
+        }, this.scrollbarOptions, surfaceId);
+        this.scrollbarOverlay.setBackgroundColor(this.terminalThemeSource.background);
+    }
     installLinkDetector() {
         if (!this.terminal) {
             throw new Error('Terminal instance not created');
@@ -742,7 +744,13 @@ export class TerminalCore {
         if (!geometry) {
             return null;
         }
-        const cols = Math.floor(Number(geometry.cols));
+        const cellWidth = Number(geometry.cellWidth);
+        const hostWidth = Number(this.viewportHost?.clientWidth ?? this.container.clientWidth);
+        const visibleCellWidth = cellWidth / this.presentationScale;
+        const cols = Number.isFinite(hostWidth) && hostWidth > 0
+            && Number.isFinite(visibleCellWidth) && visibleCellWidth > 0
+            ? Math.floor(Math.max(0, hostWidth - this.fit.scrollbarReservePx) / visibleCellWidth)
+            : 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;
@@ -1566,6 +1574,8 @@ export class TerminalCore {
         if (typeof this.terminal.onScroll === 'function') {
             const disposable = this.terminal.onScroll(() => {
                 this.syncImeInputAnchor();
+                this.scrollbarOverlay?.reveal();
+                this.scrollbarOverlay?.sync();
                 this.requestDemandRender(false);
             });
             this.trackTerminalEventDisposable(disposable);
@@ -1853,6 +1863,7 @@ export class TerminalCore {
                 else {
                     this.requestDemandRender(shouldForceAfterWrite);
                 }
+                this.scrollbarOverlay?.sync();
                 callback?.();
                 probe?.onTerminalWriteProfile?.({
                     totalMs: performance.now() - profileStartedAt,
@@ -2790,11 +2801,19 @@ export class TerminalCore {
             this.setPresentationScale(appearance.presentationScale);
         }
     }
+    setScrollbarOptions(options) {
+        normalizeTerminalScrollbarOptions(options);
+        const next = normalizeTerminalScrollbarOptions({ ...this.scrollbarOptions, ...options });
+        this.scrollbarOptions = next;
+        this.config = { ...this.config, scrollbar: next };
+        this.scrollbarOverlay?.setOptions(next);
+    }
     setTheme(theme) {
         const mapped = mapThemeToGhostty(theme);
         // Persist latest theme so a future re-initialization can reuse it.
         this.config = { ...this.config, theme: mapped };
         this.themeColorTranslator = buildThemeColorTranslator(this.terminalThemeSource, mapped);
+        this.scrollbarOverlay?.setBackgroundColor(mapped.background);
         if (!this.terminal) {
             return;
         }
@@ -2934,6 +2953,8 @@ export class TerminalCore {
         this.disposeInputBridge();
         this.disposeTerminalEventListeners();
         this.disposeSearchOverlay();
+        this.scrollbarOverlay?.dispose();
+        this.scrollbarOverlay = null;
         this.fabricAttachSeq += 1;
         this.cancelFabricAttachSchedule?.();
         this.cancelFabricAttachSchedule = null;
@@ -3203,6 +3224,7 @@ export class TerminalCore {
                 terminalAny.cursorMoveEmitter?.fire?.();
             }
             this.syncImeInputAnchor();
+            this.scrollbarOverlay?.sync();
             const durationMs = performance.now() - startedAt;
             getPerfProbe()?.onTerminalRender?.(durationMs);
             if (this.config.rendererType !== 'webgl'