2026-09-26 17:06:11 -04:00
|
|
|
/**
|
|
|
|
|
* @fileoverview In-terminal preview of IME composition text on iOS Safari.
|
|
|
|
|
*
|
|
|
|
|
* On iOS WebKit touch devices the text an IME is composing (Japanese, Chinese,
|
|
|
|
|
* Korean, dictation) is not visible inside the terminal until it commits, so
|
|
|
|
|
* the user types blind. The controller listens to the helper textarea's
|
|
|
|
|
* composition events and asks the caller to render the latest composition
|
|
|
|
|
* (`phase: 'provisional'`), coalesced to one render per animation frame and
|
|
|
|
|
* capped at 2048 characters. When xterm emits the committed text through
|
|
|
|
|
* onData, the caller hands it to `consumeTerminalData()`, which switches the
|
|
|
|
|
* preview to `phase: 'committed'` until something else shows the text: the
|
|
|
|
|
* local echo overlay or a prediction (`completeCommit`), authoritative
|
2026-09-26 22:47:48 -04:00
|
|
|
* terminal output (`noteAuthoritativeOutput`), or a 2 s fallback timer. The
|
|
|
|
|
* same 2 s bound applies while waiting for a commit that never reaches onData
|
|
|
|
|
* (the user deleted the whole composition), so a later unrelated chunk is never
|
|
|
|
|
* mistaken for it.
|
|
|
|
|
*
|
|
|
|
|
* Keydown ordering: xterm registers its textarea keydown listener in the
|
|
|
|
|
* capture phase inside terminal.open() and finalizes the composition there
|
|
|
|
|
* (CompositionHelper.keydown), emitting the commit through onData
|
|
|
|
|
* synchronously. The controller therefore observes keydown in the capture
|
|
|
|
|
* phase on an ANCESTOR (`keydownTarget`, the terminal element), which runs
|
|
|
|
|
* before any listener on the textarea itself, and finalizes on exactly the
|
|
|
|
|
* keys xterm does.
|
2026-09-26 17:06:11 -04:00
|
|
|
*
|
|
|
|
|
* VISUAL ONLY: the controller never sends, consumes or reorders input bytes,
|
|
|
|
|
* and every callback is wrapped so a failing render cannot block the wire.
|
|
|
|
|
* `isIosWebKitTouch()` gates creation; other platforms keep xterm's own
|
|
|
|
|
* composition view untouched.
|
|
|
|
|
*
|
|
|
|
|
* @dependency none (standalone IIFE; consumed by terminal-ui.js)
|
|
|
|
|
* @loadorder 5.52 (before app.js/terminal-ui.js, which create the controller)
|
|
|
|
|
*/
|
|
|
|
|
(function (global) {
|
|
|
|
|
'use strict';
|
|
|
|
|
|
|
|
|
|
const COMMITTED_VISUAL_TTL = 2000;
|
|
|
|
|
const PREVIEW_CAP = 2048;
|
2026-09-26 22:47:48 -04:00
|
|
|
// keyCodes on which xterm 6's CompositionHelper.keydown keeps composing
|
|
|
|
|
// (CapsLock, the IME "composition character", Shift/Ctrl/Alt). Any other
|
|
|
|
|
// keydown during a composition finalizes it.
|
|
|
|
|
const KEEP_COMPOSING_KEYCODES = new Set([20, 229, 16, 17, 18]);
|
2026-09-26 17:06:11 -04:00
|
|
|
const CONTROL_OR_LINE_BREAK = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
|
|
|
|
|
|
|
|
|
|
function isIosWebKitTouch(nav = navigator) {
|
|
|
|
|
const userAgent = String(nav && nav.userAgent ? nav.userAgent : '');
|
|
|
|
|
const platform = String(nav && nav.platform ? nav.platform : '');
|
|
|
|
|
const touchPoints = Number(nav && nav.maxTouchPoints ? nav.maxTouchPoints : 0);
|
|
|
|
|
const iosDevice = /iPhone|iPad|iPod/.test(userAgent);
|
|
|
|
|
const desktopIpad = platform === 'MacIntel' && touchPoints > 1;
|
|
|
|
|
return touchPoints > 0 && /AppleWebKit/.test(userAgent) && (iosDevice || desktopIpad);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function create(options) {
|
|
|
|
|
const textarea = options.textarea;
|
2026-09-26 22:47:48 -04:00
|
|
|
// Must be the textarea or an ancestor of it, so its capture listener runs
|
|
|
|
|
// before xterm's capture listener on the textarea.
|
|
|
|
|
const keydownTarget = options.keydownTarget || textarea;
|
2026-09-26 17:06:11 -04:00
|
|
|
const render = typeof options.render === 'function' ? options.render : function () {};
|
|
|
|
|
const clear = typeof options.clear === 'function' ? options.clear : function () {};
|
|
|
|
|
const onCommit = typeof options.onCommit === 'function' ? options.onCommit : function () {};
|
|
|
|
|
const scheduleFrame = options.scheduleFrame || global.requestAnimationFrame.bind(global);
|
|
|
|
|
const cancelFrame = options.cancelFrame || global.cancelAnimationFrame.bind(global);
|
|
|
|
|
const setTimer = options.setTimer || global.setTimeout.bind(global);
|
|
|
|
|
const clearTimer = options.clearTimer || global.clearTimeout.bind(global);
|
|
|
|
|
|
|
|
|
|
let generation = 0;
|
|
|
|
|
let composing = false;
|
|
|
|
|
let awaitingCommit = false;
|
|
|
|
|
let committed = false;
|
|
|
|
|
let latestValue = '';
|
|
|
|
|
let renderPhase = null;
|
|
|
|
|
let frameToken = null;
|
|
|
|
|
let timerToken = null;
|
|
|
|
|
let finalizedByKeydown = false;
|
|
|
|
|
let destroyed = false;
|
|
|
|
|
let invokingClear = false;
|
|
|
|
|
|
|
|
|
|
function safely(callback, ...args) {
|
|
|
|
|
try {
|
|
|
|
|
return callback(...args);
|
|
|
|
|
} catch (_error) {
|
|
|
|
|
return undefined;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function cancelScheduledFrame() {
|
|
|
|
|
const token = frameToken;
|
|
|
|
|
frameToken = null;
|
|
|
|
|
if (token && token.id !== undefined) safely(cancelFrame, token.id);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function cancelCommittedTimer() {
|
|
|
|
|
const token = timerToken;
|
|
|
|
|
timerToken = null;
|
|
|
|
|
if (token && token.id !== undefined) safely(clearTimer, token.id);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function clearVisual() {
|
|
|
|
|
if (invokingClear) return;
|
|
|
|
|
invokingClear = true;
|
|
|
|
|
safely(clear);
|
|
|
|
|
invokingClear = false;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function cleanup() {
|
|
|
|
|
generation += 1;
|
|
|
|
|
cancelScheduledFrame();
|
|
|
|
|
cancelCommittedTimer();
|
|
|
|
|
composing = false;
|
|
|
|
|
awaitingCommit = false;
|
|
|
|
|
committed = false;
|
|
|
|
|
latestValue = '';
|
|
|
|
|
renderPhase = null;
|
|
|
|
|
finalizedByKeydown = false;
|
|
|
|
|
clearVisual();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function scheduleLatestPreview(phase) {
|
|
|
|
|
if (destroyed) return;
|
|
|
|
|
renderPhase = phase;
|
|
|
|
|
if (frameToken) return;
|
|
|
|
|
const token = { generation, id: undefined };
|
|
|
|
|
frameToken = token;
|
|
|
|
|
const callback = function () {
|
|
|
|
|
if (destroyed || frameToken !== token || token.generation !== generation || renderPhase === null) return;
|
|
|
|
|
frameToken = null;
|
|
|
|
|
const value = latestValue.slice(0, PREVIEW_CAP);
|
|
|
|
|
const phaseToRender = renderPhase;
|
|
|
|
|
safely(render, { text: value, phase: phaseToRender });
|
|
|
|
|
};
|
|
|
|
|
const id = safely(scheduleFrame, callback);
|
|
|
|
|
if (frameToken === token) {
|
|
|
|
|
if (id === undefined) frameToken = null;
|
|
|
|
|
else token.id = id;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function beginComposition() {
|
|
|
|
|
cleanup();
|
|
|
|
|
if (destroyed) return;
|
|
|
|
|
composing = true;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function updateComposition(event) {
|
|
|
|
|
if (!composing) return;
|
|
|
|
|
latestValue = event.data == null ? '' : String(event.data);
|
|
|
|
|
scheduleLatestPreview('provisional');
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function onComposingInput(event) {
|
|
|
|
|
if (!event.isComposing) return;
|
|
|
|
|
updateComposition({ data: event.data == null ? textarea.value : event.data });
|
|
|
|
|
}
|
|
|
|
|
|
2026-09-26 22:47:48 -04:00
|
|
|
function armFallbackTimer(isCurrent) {
|
|
|
|
|
const token = { generation, id: undefined };
|
|
|
|
|
timerToken = token;
|
|
|
|
|
const callback = function () {
|
|
|
|
|
if (destroyed || timerToken !== token || token.generation !== generation || !isCurrent()) return;
|
|
|
|
|
timerToken = null;
|
|
|
|
|
cleanup();
|
|
|
|
|
};
|
|
|
|
|
const id = safely(setTimer, callback, COMMITTED_VISUAL_TTL);
|
|
|
|
|
if (timerToken === token) {
|
|
|
|
|
if (id === undefined) {
|
|
|
|
|
timerToken = null;
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
token.id = id;
|
|
|
|
|
}
|
|
|
|
|
return true;
|
|
|
|
|
}
|
|
|
|
|
|
2026-09-26 17:06:11 -04:00
|
|
|
function finalizeComposition(value, fromKeydown) {
|
|
|
|
|
if (!composing) return;
|
|
|
|
|
composing = false;
|
|
|
|
|
awaitingCommit = true;
|
|
|
|
|
committed = false;
|
|
|
|
|
finalizedByKeydown = fromKeydown;
|
|
|
|
|
latestValue = value == null ? latestValue : String(value);
|
|
|
|
|
scheduleLatestPreview('provisional');
|
2026-09-26 22:47:48 -04:00
|
|
|
// A commit that never reaches onData (the composition was deleted, so
|
|
|
|
|
// xterm emits nothing) must not leave the controller waiting forever.
|
|
|
|
|
cancelCommittedTimer();
|
|
|
|
|
const owner = generation;
|
|
|
|
|
armFallbackTimer(function () {
|
|
|
|
|
return awaitingCommit && generation === owner;
|
|
|
|
|
});
|
2026-09-26 17:06:11 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function onCompositionEnd(event) {
|
|
|
|
|
if (finalizedByKeydown) {
|
|
|
|
|
finalizedByKeydown = false;
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
finalizeComposition(event.data, false);
|
|
|
|
|
}
|
|
|
|
|
|
2026-09-26 22:47:48 -04:00
|
|
|
// Mirrors CompositionHelper.keydown in @xterm/xterm 6.0.0
|
|
|
|
|
// (src/browser/input/CompositionHelper.ts:94-108): while composing, keyCode
|
|
|
|
|
// 20/229 and 16/17/18 keep the composition open and every other keyCode
|
|
|
|
|
// finalizes it. `isComposing` and `key` are deliberately not consulted,
|
|
|
|
|
// because xterm does not consult them.
|
2026-09-26 17:06:11 -04:00
|
|
|
function onKeydown(event) {
|
2026-09-26 22:47:48 -04:00
|
|
|
if (keydownTarget !== textarea && event.target !== textarea) return;
|
|
|
|
|
if (!composing || KEEP_COMPOSING_KEYCODES.has(event.keyCode)) return;
|
|
|
|
|
finalizeComposition(latestValue, true);
|
2026-09-26 17:06:11 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function reset() {
|
|
|
|
|
if (destroyed) return;
|
|
|
|
|
cleanup();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function consumeTerminalData(data) {
|
|
|
|
|
if (
|
|
|
|
|
destroyed ||
|
|
|
|
|
!awaitingCommit ||
|
|
|
|
|
typeof data !== 'string' ||
|
|
|
|
|
data.length === 0 ||
|
|
|
|
|
CONTROL_OR_LINE_BREAK.test(data)
|
|
|
|
|
) {
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
generation += 1;
|
|
|
|
|
const owner = generation;
|
|
|
|
|
cancelScheduledFrame();
|
|
|
|
|
cancelCommittedTimer();
|
|
|
|
|
composing = false;
|
|
|
|
|
awaitingCommit = false;
|
|
|
|
|
committed = true;
|
|
|
|
|
latestValue = data;
|
|
|
|
|
renderPhase = 'committed';
|
|
|
|
|
safely(onCommit, data);
|
|
|
|
|
if (destroyed || generation !== owner || !committed) return true;
|
|
|
|
|
|
|
|
|
|
scheduleLatestPreview('committed');
|
|
|
|
|
if (destroyed || generation !== owner || !committed) return true;
|
|
|
|
|
|
2026-09-26 22:47:48 -04:00
|
|
|
const armed = armFallbackTimer(function () {
|
|
|
|
|
return committed;
|
|
|
|
|
});
|
|
|
|
|
if (!armed && !destroyed && generation === owner && committed) cleanup();
|
2026-09-26 17:06:11 -04:00
|
|
|
return true;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function completeCommit(result) {
|
|
|
|
|
if (destroyed || !result || result.predicted !== true || !committed) return;
|
|
|
|
|
cleanup();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
function noteAuthoritativeOutput() {
|
|
|
|
|
if (destroyed || !committed) return;
|
|
|
|
|
cleanup();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const listeners = [
|
2026-09-26 22:47:48 -04:00
|
|
|
[textarea, 'compositionstart', beginComposition],
|
|
|
|
|
[textarea, 'compositionupdate', updateComposition],
|
|
|
|
|
[textarea, 'input', onComposingInput],
|
|
|
|
|
[textarea, 'compositionend', onCompositionEnd],
|
|
|
|
|
[keydownTarget, 'keydown', onKeydown, true],
|
|
|
|
|
[textarea, 'blur', reset],
|
2026-09-26 17:06:11 -04:00
|
|
|
];
|
2026-09-26 22:47:48 -04:00
|
|
|
for (const [target, type, listener, capture] of listeners) target.addEventListener(type, listener, capture);
|
2026-09-26 17:06:11 -04:00
|
|
|
|
|
|
|
|
function destroy() {
|
|
|
|
|
if (destroyed) return;
|
|
|
|
|
destroyed = true;
|
2026-09-26 22:47:48 -04:00
|
|
|
for (const [target, type, listener, capture] of listeners) target.removeEventListener(type, listener, capture);
|
2026-09-26 17:06:11 -04:00
|
|
|
cleanup();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return {
|
|
|
|
|
consumeTerminalData,
|
|
|
|
|
completeCommit,
|
|
|
|
|
noteAuthoritativeOutput,
|
|
|
|
|
reset,
|
|
|
|
|
destroy,
|
|
|
|
|
get state() {
|
|
|
|
|
return {
|
|
|
|
|
generation,
|
|
|
|
|
composing,
|
|
|
|
|
awaitingCommit,
|
|
|
|
|
committed,
|
|
|
|
|
latest: latestValue,
|
|
|
|
|
framePending: frameToken !== null,
|
|
|
|
|
timerPending: timerToken !== null,
|
|
|
|
|
};
|
|
|
|
|
},
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
global.MobileImePreview = { create, isIosWebKitTouch };
|
|
|
|
|
})(globalThis);
|