Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { Terminal } from '@xterm/xterm';
import { TERMINAL_DEL as DEL, planFieldEdit, attachDictationBridge } from './terminalDictation.js';
// Replay an emitted terminal-input stream the way a line editor would, so a test
// can assert "the prompt ends up holding what was dictated" rather than pinning
// the exact byte sequence that gets it there.
const render = (chunks) => chunks.join('').split('').reduce(
(acc, ch) => (ch === DEL ? acc.slice(0, -1) : acc + ch),
'',
);
describe('planFieldEdit', () => {
const data = (...args) => planFieldEdit(...args).data;
it('emits nothing when the field did not change', () => {
expect(data('hello', 'hello')).toBe('');
});
it('emits only the appended text when the field grew', () => {
expect(data('determin', 'determines')).toBe('es');
});
it('erases the replaced tail before retyping it', () => {
expect(data('their', 'there')).toBe(`${DEL}${DEL}re`);
});
it('emits pure deletions when the field shrank', () => {
expect(data('hello', 'hell')).toBe(DEL);
expect(data('hello', '')).toBe(DEL.repeat(5));
});
it('never rewinds below the floor — it retypes instead of eating prior text', () => {
// 'ls ' reached the PTY as keystrokes (floor 3); only 'foo' is ours.
expect(data('ls foo', 'ls bar', 3)).toBe(`${DEL.repeat(3)}bar`);
// Divergence below the floor: retype from the floor, delete nothing under it.
expect(data('ls foo', 'xx bar', 3)).toBe(`${DEL.repeat(3)}bar`);
// A floor past the end of the mirror clamps instead of emitting a negative run.
expect(data('ab', 'abc', 99)).toBe('c');
});
it('reports what the PTY holds, which is not the field when the floor blocked a rewind', () => {
// Normally the PTY ends up holding exactly what the field shows.
expect(planFieldEdit('their', 'there').committed).toBe('there');
// But 'ls ' is below the floor and was never rewound, so the PTY holds
// 'ls bar' even though the field reads 'xx bar'. Tracking the field here
// would make every later diff rewind against a baseline that never existed.
expect(planFieldEdit('ls foo', 'xx bar', 3).committed).toBe('ls bar');
});
it('does not split a surrogate pair', () => {
// 😀 and 😂 share a high surrogate; cutting between the halves would send a
// lone surrogate, which serializes to U+FFFD instead of the emoji.
const plan = planFieldEdit('hi 😀', 'hi 😂');
expect(plan.committed).toBe('hi 😂');
expect([...plan.data].every((ch) => ch.charCodeAt(0) < 0xd800 || ch.codePointAt(0) > 0xffff)).toBe(true);
});
it('erases one DEL per code point, not per UTF-16 unit', () => {
// The far end erases a whole character per DEL. Counting JS string length
// would send two for one emoji and eat the space before it.
expect(planFieldEdit('hi 😀', 'hi ').data).toBe(DEL);
expect(planFieldEdit('hi 😀', 'hi 😂').data).toBe(`${DEL}😂`);
expect(planFieldEdit('a😀b😀', 'a').data).toBe(DEL.repeat(3));
});
});
describe('attachDictationBridge', () => {
let container;
let textarea;
let terminal;
let sent;
let dispose;
// Faithful to what a browser dispatches: dictation/soft-keyboard edits arrive
// as InputEvents carrying inputType, and the field value is already updated.
const fireInput = (inputType, data = null) => {
textarea.dispatchEvent(new InputEvent('input', { inputType, data, bubbles: true }));
};
// Key events the latch reads. 84 is 'T' — a capital, the case this bridge exists
// for, so the tests that don't care about the specific key take it by default.
const fireKey = (type, keyCode = 84) => {
textarea.dispatchEvent(new KeyboardEvent(type, { keyCode, bubbles: true }));
};
// Stands in for xterm's own textarea listener, which appends the raw insertion.
const attachXtermStub = () => {
const spy = vi.fn();
textarea.addEventListener('input', spy);
return spy;
};
beforeEach(() => {
vi.useFakeTimers();
container = document.createElement('div');
textarea = document.createElement('textarea');
container.appendChild(textarea);
document.body.appendChild(container);
terminal = { element: container, textarea, options: {} };
sent = [];
dispose = attachDictationBridge(terminal, (d) => { sent.push(d); });
});
afterEach(() => {
dispose();
container.remove();
vi.useRealTimers();
});
it('does not attach or throw when the terminal has no DOM yet', () => {
expect(() => attachDictationBridge({}, () => {})()).not.toThrow();
expect(() => attachDictationBridge(terminal, null)()).not.toThrow();
});
it('forwards a streaming dictation phrase without duplicating it', () => {
// Exactly the reported failure: Apple dictation rewrites its own guess.
for (const partial of ['dde', 'deter', 'determin', 'determine', 'determines', 'determines if any code']) {
textarea.value = partial;
fireInput('insertText');
}
expect(render(sent)).toBe('determines if any code');
});
it('stops the event before xterm can append the raw insertion', () => {
const xterm = attachXtermStub();
textarea.value = 'hi';
fireInput('insertText');
expect(xterm).not.toHaveBeenCalled();
expect(sent).toEqual(['hi']);
});
it('translates a dictation replacement into erase + retype', () => {
textarea.value = 'their';
fireInput('insertText');
textarea.value = 'there';
fireInput('insertReplacementText');
expect(sent).toEqual(['their', `${DEL}${DEL}re`]);
});
it('forwards soft-keyboard deletions', () => {
textarea.value = 'abc';
fireInput('insertText');
textarea.value = 'ab';
fireInput('deleteContentBackward');
textarea.value = '';
fireInput('deleteWordBackward');
expect(sent).toEqual(['abc', DEL, DEL.repeat(2)]);
});
it('leaves unowned input types to xterm and resyncs the mirror', () => {
const xterm = attachXtermStub();
textarea.value = 'pasted';
fireInput('insertFromPaste');
expect(sent).toEqual([]);
expect(xterm).toHaveBeenCalledTimes(1);
// The paste is now part of the untouchable floor: a later dictation appends
// rather than erasing text xterm already sent.
textarea.value = 'pasted more';
fireInput('insertText');
expect(sent).toEqual([' more']);
});
it('ignores input that belongs to an in-progress composition', () => {
const xterm = attachXtermStub();
textarea.value = 'か';
textarea.dispatchEvent(new InputEvent('input', {
inputType: 'insertCompositionText', data: 'か', isComposing: true, bubbles: true,
}));
expect(sent).toEqual([]);
expect(xterm).toHaveBeenCalledTimes(1);
});
it('forwards dictation in screen-reader mode', () => {
// xterm ignores every insertText in this mode, so the bridge is the only
// path a dictated phrase has to the PTY.
terminal.options.screenReaderMode = true;
textarea.value = 'abc';
fireInput('insertText');
expect(sent).toEqual(['abc']);
});
it('leaves a keydown-sent insertion to xterm in screen-reader mode', () => {
// xterm sends the key from keydown without cancelling it, so the browser
// then inserts it into the field — no keypress involved.
terminal.options.screenReaderMode = true;
fireKey('keydown', 65);
textarea.value = 'a';
fireInput('insertText');
fireKey('keyup', 65);
fireKey('keydown', 8);
textarea.value = '';
fireInput('deleteContentBackward');
fireKey('keyup', 8);
expect(sent).toEqual([]);
});
it('does not claim text the sink reports as dropped', () => {
dispose();
let delivered = false;
dispose = attachDictationBridge(terminal, (d) => { if (delivered) sent.push(d); return delivered; });
// Mid session-switch: the emit is refused, so the PTY never saw 'abc'.
textarea.value = 'abc';
fireInput('insertText');
delivered = true;
// Once sends land again the whole phrase goes out — no DELs for characters
// that never arrived, and no silently swallowed words.
textarea.value = 'abd';
fireInput('insertReplacementText');
expect(sent).toEqual(['abd']);
});
it('resyncs after a keystroke xterm handles itself', () => {
textarea.value = 'abc';
fireInput('insertText');
// Enter: xterm sends CR and clears the textarea.
fireKey('keydown', 13);
textarea.value = '';
vi.runAllTimers();
// Next dictation starts from a clean mirror — no phantom DELs for 'abc'.
textarea.value = 'next';
fireInput('insertText');
expect(sent).toEqual(['abc', 'next']);
});
it('leaves an insertion the keypress path already sent to xterm', () => {
// Capitals and space are the keys xterm forwards from `keypress` without
// cancelling it, so the character lands in the textarea and fires `input`
// AFTER the PTY already has it. Diffing that insertion doubled every one.
fireKey('keydown');
fireKey('keypress');
textarea.value = 'T';
fireInput('insertText');
expect(sent).toEqual([]);
// It counts as floor, not as ours: dictating on top appends instead of
// erasing the capital xterm sent.
textarea.value = 'There';
fireInput('insertText');
expect(sent).toEqual(['here']);
});
it('does not let a keypress that inserted nothing disown the next phrase', () => {
// The insertion a keypress produces can fail to arrive. Dictation then follows
// with no key events at all, so only keyup can clear the latch in time —
// waiting for the next keydown would swallow the phrase into the floor.
fireKey('keypress');
fireKey('keyup');
textarea.value = 'ab';
fireInput('insertText');
expect(sent).toEqual(['ab']);
});
it('disarms the latch when focus leaves mid-keystroke', () => {
// Blur can land between the keypress and the keyup that would have cleared it.
fireKey('keypress');
textarea.dispatchEvent(new FocusEvent('blur'));
vi.runAllTimers();
textarea.value = 'ab';
fireInput('insertText');
expect(sent).toEqual(['ab']);
});
it('does not resync on the composition keycode soft keyboards report', () => {
fireKey('keydown', 229);
textarea.value = 'ab';
fireInput('insertText');
vi.runAllTimers();
textarea.value = 'abc';
fireInput('insertText');
expect(sent).toEqual(['ab', 'c']);
});
it('resyncs on blur, which clears xterm\'s textarea', () => {
textarea.value = 'abc';
fireInput('insertText');
textarea.dispatchEvent(new FocusEvent('blur'));
textarea.value = '';
vi.runAllTimers();
textarea.value = 'fresh';
fireInput('insertText');
expect(sent).toEqual(['abc', 'fresh']);
});
it('cancels a pending resync when it reconciles the field itself', () => {
// A keystroke xterm handled arms a resync; the dictation event that follows
// reconciles the field first. If the stale timer still fired it would pin the
// floor to the whole phrase and silently swallow every later correction.
textarea.value = 'their';
fireInput('insertText');
// Field is non-empty now, so this keystroke really does arm a resync.
fireKey('keydown', 32);
textarea.value = 'there';
fireInput('insertReplacementText');
vi.runAllTimers();
// A stale resync would have pinned floor to 'there'.length, and this
// correction would emit nothing at all.
textarea.value = 'their';
fireInput('insertReplacementText');
expect(sent).toEqual(['their', `${DEL}${DEL}re`, `${DEL}${DEL}ir`]);
});
it('arms no timer while typing leaves nothing to reconcile', () => {
const timer = vi.spyOn(globalThis, 'setTimeout');
fireKey('keydown', 65);
expect(timer).not.toHaveBeenCalled();
timer.mockRestore();
});
it('detaches every listener on dispose', () => {
dispose();
const xterm = attachXtermStub();
textarea.value = 'after';
fireInput('insertText');
expect(sent).toEqual([]);
expect(xterm).toHaveBeenCalledTimes(1);
});
});
// The bridge's whole seam is "our capture-phase listener on terminal.element runs
// before xterm's own listener on the textarea inside it". The stub above can't
// prove that — only a real Terminal can, and this is what fails loudly if an
// xterm upgrade moves or re-phases that listener.
describe('attachDictationBridge against a real xterm Terminal', () => {
let container;
let terminal;
beforeEach(() => {
// xterm reads the device pixel ratio on open(); jsdom ships no matchMedia.
window.matchMedia = vi.fn(() => ({ matches: false, addListener() {}, removeListener() {} }));
container = document.createElement('div');
document.body.appendChild(container);
terminal = new Terminal({ allowProposedApi: true });
terminal.open(container);
});
afterEach(() => {
terminal.dispose();
container.remove();
delete window.matchMedia;
});
// Each refinement replaces the field's whole contents, which is what Apple
// dictation does — `data` carries the text the field gained, exactly the value
// xterm's own handler forwards verbatim.
const dictate = (partials) => {
for (const partial of partials) {
terminal.textarea.value = partial;
terminal.textarea.dispatchEvent(new InputEvent('input', {
inputType: 'insertText', data: partial, bubbles: true,
}));
}
};
// The bug, pinned upstream. If a future @xterm/xterm starts reconciling these
// events itself this fails — at which point the bridge is double-handling and
// should go, rather than quietly fighting xterm for the same input.
it('garbles the phrase when xterm handles the events alone', () => {
const sent = [];
terminal.onData((d) => sent.push(d));
dictate(['dde', 'deter', 'determin', 'determine', 'determines']);
expect(sent.join('')).toBe('ddedeterdetermindeterminedetermines');
});
// A keystroke xterm defers to keypress, exactly as Chrome delivers it: xterm
// ignores the keydown, forwards the character from keypress WITHOUT cancelling
// it, and the browser then inserts it into the textarea and fires `input`. Two
// senders, one character.
const typeThroughKeypress = (ch) => {
const code = ch.charCodeAt(0);
const { textarea } = terminal;
textarea.dispatchEvent(new KeyboardEvent('keydown', { key: ch, keyCode: code, bubbles: true }));
textarea.dispatchEvent(new KeyboardEvent('keypress', { key: ch, keyCode: code, charCode: code, bubbles: true }));
textarea.value += ch;
textarea.dispatchEvent(new InputEvent('input', { inputType: 'insertText', data: ch, bubbles: true }));
textarea.dispatchEvent(new KeyboardEvent('keyup', { key: ch, keyCode: code, bubbles: true }));
};
it('does not double a character xterm sent from keypress', () => {
const sent = [];
terminal.onData((d) => sent.push(d));
// Capitals land here through xterm's A-Z hack, space because its keyCode falls
// below the printable range xterm's keyboard map claims — two mechanisms, and
// the changelog claims both. Proves xterm really is the sender on this path: if
// an upgrade moves either to keydown-with-cancel, this fails and the bridge's
// keypress seam can go.
typeThroughKeypress('T');
typeThroughKeypress(' ');
expect(sent).toEqual(['T', ' ']);
const dispose = attachDictationBridge(terminal, (d) => { sent.push(d); });
typeThroughKeypress('X');
typeThroughKeypress(' ');
dispose();
expect(sent).toEqual(['T', ' ', 'X', ' ']);
});
// The Shell page runs xterm in screen-reader mode (createShellTerminal), where
// xterm drops every insertText event: dictation, which fires no key events,
// never reached the PTY at all. If an upgrade starts forwarding these, the
// first assertion fails and the bridge would double-send in this mode.
it('delivers dictation in screen-reader mode, where xterm alone drops it', () => {
terminal.options.screenReaderMode = true;
const sent = [];
terminal.onData((d) => sent.push(d));
dictate(['hello']);
expect(sent).toEqual([]);
terminal.textarea.value = '';
const dispose = attachDictationBridge(terminal, (d) => { sent.push(d); });
dictate(['dde', 'deter', 'determines']);
// A lowercase key xterm sends from keydown without cancelling it: the browser
// then inserts it into the field, and it must not go out twice.
const { textarea } = terminal;
textarea.dispatchEvent(new KeyboardEvent('keydown', { key: 'x', keyCode: 88, bubbles: true }));
textarea.value += 'x';
textarea.dispatchEvent(new InputEvent('input', { inputType: 'insertText', data: 'x', bubbles: true }));
textarea.dispatchEvent(new KeyboardEvent('keyup', { key: 'x', keyCode: 88, bubbles: true }));
dispose();
expect(render(sent)).toBe('determinesx');
});
it('sends the dictated phrase once, not the accumulated garble', () => {
const sent = [];
// onData is where xterm's own textarea handling would surface, so anything it
// forwards behind our back shows up here too.
terminal.onData((d) => sent.push(d));
const dispose = attachDictationBridge(terminal, (d) => { sent.push(d); });
dictate(['dde', 'deter', 'determin', 'determine', 'determines']);
dispose();
expect(render(sent)).toBe('determines');
});
});