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, afterEach } from 'vitest';
import {
attachTerminalTouchScroll,
attachTerminalWheelScroll,
measureTerminalGeometry,
planTouchScrollSteps,
resetTerminalWheelScroll,
scrollTerminalLines,
scrollTerminalPage,
sendTerminalPageKey,
} from './terminalScroll.js';
// A stand-in for the xterm instance carrying only what this module reads. The real
// Terminal is not needed here: these tests pin the event ownership and key sequence
// that the Shell's xterm instance exposes to the PTY.
const makeTerminal = ({ alt = true, rows = 24, height = 480, mouseTrackingMode = 'none' } = {}) => {
const el = document.createElement('div');
const screen = document.createElement('div');
screen.className = 'xterm-screen';
el.appendChild(screen);
document.body.appendChild(el);
screen.getBoundingClientRect = () => ({ left: 100, top: 50, width: 800, height, right: 900, bottom: 50 + height });
return {
element: el,
rows,
buffer: { active: { type: alt ? 'alternate' : 'normal' } },
modes: { mouseTrackingMode },
input: vi.fn(),
scrollLines: vi.fn(),
};
};
const touchEvent = (type, touches) => {
const ev = new Event(type, { bubbles: true, cancelable: true });
ev.touches = touches.map((clientY) => ({ clientX: 150, clientY }));
return ev;
};
afterEach(() => { vi.useRealTimers(); document.body.innerHTML = ''; });
describe('measureTerminalGeometry', () => {
it('derives the row height from the rendered screen, not the outer container', () => {
expect(measureTerminalGeometry(makeTerminal({ rows: 24, height: 480 }))).toEqual({ rowHeightPx: 20 });
});
it('falls back to a nominal row height before the terminal has been laid out', () => {
expect(measureTerminalGeometry(makeTerminal({ rows: 24, height: 0 }))).toEqual({ rowHeightPx: 18 });
expect(measureTerminalGeometry(null)).toEqual({ rowHeightPx: 18 });
});
});
describe('planTouchScrollSteps', () => {
it('holds back a sub-row drag and carries the remainder into the next one', () => {
expect(planTouchScrollSteps(8, 20)).toEqual({ steps: 0, remainderPx: 8 });
expect(planTouchScrollSteps(24, 20)).toEqual({ steps: 1, remainderPx: 4 });
});
it('truncates toward zero in both directions', () => {
expect(planTouchScrollSteps(-45, 20)).toEqual({ steps: -2, remainderPx: -5 });
expect(planTouchScrollSteps(45, 20)).toEqual({ steps: 2, remainderPx: 5 });
});
it('is inert without a usable row height', () => {
expect(planTouchScrollSteps(120, 0)).toEqual({ steps: 0, remainderPx: 120 });
});
});
describe('alternate-screen page keys', () => {
it('sends standard PageUp/PageDown sequences through xterm input', () => {
const term = makeTerminal();
expect(sendTerminalPageKey(term, -1)).toBe(true);
expect(sendTerminalPageKey(term, 1)).toBe(true);
expect(term.input.mock.calls).toEqual([['\x1b[5~', false], ['\x1b[6~', false]]);
});
it('returns false when the terminal cannot accept input', () => {
expect(sendTerminalPageKey(null, -1)).toBe(false);
expect(sendTerminalPageKey({ input: null }, -1)).toBe(false);
expect(sendTerminalPageKey({ input: vi.fn() }, 0)).toBe(false);
});
});
describe('scrollTerminalLines', () => {
it('uses the real scrollback API in the normal buffer', () => {
const term = makeTerminal({ alt: false });
expect(scrollTerminalLines(term, -5)).toBe(-5);
expect(term.scrollLines).toHaveBeenCalledWith(-5);
expect(term.input).not.toHaveBeenCalled();
});
it('uses the app page key for each alternate-buffer step', () => {
const term = makeTerminal();
expect(scrollTerminalLines(term, -3)).toBe(-3);
expect(term.input.mock.calls).toEqual([
['\x1b[5~', false],
['\x1b[5~', false],
['\x1b[5~', false],
]);
});
it('bounds a large alternate-buffer request', () => {
const term = makeTerminal();
expect(scrollTerminalLines(term, -5000)).toBe(-64);
expect(term.input).toHaveBeenCalledTimes(64);
});
it('is a no-op for zero, a fractional delta, or no terminal', () => {
const term = makeTerminal();
expect(scrollTerminalLines(term, 0)).toBe(0);
expect(scrollTerminalLines(term, 0.4)).toBe(0);
expect(scrollTerminalLines(null, -3)).toBe(0);
expect(term.input).not.toHaveBeenCalled();
});
});
describe('scrollTerminalPage', () => {
it('moves a normal-buffer screenful minus one row of overlap', () => {
const term = makeTerminal({ alt: false, rows: 24 });
scrollTerminalPage(term, -1);
expect(term.scrollLines).toHaveBeenCalledWith(-23);
scrollTerminalPage(term, 1);
expect(term.scrollLines).toHaveBeenCalledWith(23);
});
it('uses one app page key in an alternate buffer', () => {
const term = makeTerminal({ rows: 24 });
expect(scrollTerminalPage(term, -1)).toBe(-1);
expect(term.input).toHaveBeenCalledWith('\x1b[5~', false);
});
it('still moves a line on a one-row normal terminal', () => {
const term = makeTerminal({ alt: false, rows: 1 });
scrollTerminalPage(term, -1);
expect(term.scrollLines).toHaveBeenCalledWith(-1);
});
});
describe('attachTerminalWheelScroll', () => {
it('translates alternate-buffer wheel input before xterm can send mouse input', () => {
const term = makeTerminal();
const xtermListener = vi.fn();
term.element.addEventListener('wheel', xtermListener);
const detach = attachTerminalWheelScroll(term);
const event = new WheelEvent('wheel', { deltaY: -120, bubbles: true, cancelable: true });
term.element.dispatchEvent(event);
expect(term.input).toHaveBeenCalledWith('\x1b[5~', false);
expect(xtermListener).not.toHaveBeenCalled();
expect(event.defaultPrevented).toBe(true);
detach();
});
it('accumulates small pixel-mode deltas before sending a page key', () => {
const term = makeTerminal({ rows: 24, height: 480 }); // 20px rows, four-line threshold
const xtermListener = vi.fn();
term.element.addEventListener('wheel', xtermListener);
const detach = attachTerminalWheelScroll(term);
for (let i = 0; i < 3; i++) {
const event = new WheelEvent('wheel', { deltaY: -20, bubbles: true, cancelable: true });
term.element.dispatchEvent(event);
expect(event.defaultPrevented).toBe(true);
}
expect(term.input).not.toHaveBeenCalled();
term.element.dispatchEvent(new WheelEvent('wheel', { deltaY: -20, bubbles: true, cancelable: true }));
expect(term.input).toHaveBeenCalledWith('\x1b[5~', false);
expect(xtermListener).not.toHaveBeenCalled();
detach();
});
it('maps a downward wheel to PageDown', () => {
const term = makeTerminal();
const detach = attachTerminalWheelScroll(term);
term.element.dispatchEvent(new WheelEvent('wheel', { deltaY: 80, bubbles: true, cancelable: true }));
expect(term.input).toHaveBeenCalledWith('\x1b[6~', false);
detach();
});
it('resets fractional wheel state when the terminal session changes', () => {
const term = makeTerminal({ rows: 24, height: 480 });
const detach = attachTerminalWheelScroll(term);
term.element.dispatchEvent(new WheelEvent('wheel', { deltaY: -20, bubbles: true, cancelable: true }));
resetTerminalWheelScroll(term);
term.element.dispatchEvent(new WheelEvent('wheel', { deltaY: -60, bubbles: true, cancelable: true }));
expect(term.input).not.toHaveBeenCalled();
detach();
});
it('leaves normal-buffer wheel input to xterm', () => {
const term = makeTerminal({ alt: false });
const xtermListener = vi.fn();
term.element.addEventListener('wheel', xtermListener);
const detach = attachTerminalWheelScroll(term);
const event = new WheelEvent('wheel', { deltaY: -120, bubbles: true, cancelable: true });
term.element.dispatchEvent(event);
expect(term.input).not.toHaveBeenCalled();
expect(xtermListener).toHaveBeenCalledTimes(1);
expect(event.defaultPrevented).toBe(false);
detach();
});
it('leaves shift-wheel input alone for browser horizontal-scroll behavior', () => {
const term = makeTerminal();
const xtermListener = vi.fn();
term.element.addEventListener('wheel', xtermListener);
const detach = attachTerminalWheelScroll(term);
const event = new WheelEvent('wheel', { deltaY: -120, bubbles: true, cancelable: true });
// WheelEvent inherits its modifier state from MouseEvent, and not every DOM
// implementation carries `shiftKey` through the WheelEvent constructor — pin it
// on the instance so the shift branch is actually the one exercised (#6144).
Object.defineProperty(event, 'shiftKey', { value: true });
term.element.dispatchEvent(event);
expect(term.input).not.toHaveBeenCalled();
expect(xtermListener).toHaveBeenCalledTimes(1);
detach();
});
it('leaves wheel input to xterm when the app enabled mouse tracking', () => {
const term = makeTerminal({ mouseTrackingMode: 'any' });
const xtermListener = vi.fn();
term.element.addEventListener('wheel', xtermListener);
const detach = attachTerminalWheelScroll(term);
const event = new WheelEvent('wheel', { deltaY: -120, bubbles: true, cancelable: true });
term.element.dispatchEvent(event);
expect(term.input).not.toHaveBeenCalled();
expect(xtermListener).toHaveBeenCalledTimes(1);
expect(event.defaultPrevented).toBe(false);
detach();
});
it('detaches the wheel listener', () => {
const term = makeTerminal();
const detach = attachTerminalWheelScroll(term);
detach();
term.element.dispatchEvent(new WheelEvent('wheel', { deltaY: -120, bubbles: true, cancelable: true }));
expect(term.input).not.toHaveBeenCalled();
});
});
describe('attachTerminalTouchScroll', () => {
it('scrolls an alternate buffer after a half-viewport drag', () => {
const term = makeTerminal({ rows: 24, height: 480 }); // 20px rows, 240px page threshold
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
// Finger moves DOWN 260px → pull older output into view.
const move = touchEvent('touchmove', [560]);
term.element.dispatchEvent(move);
expect(term.input).toHaveBeenCalledWith('\x1b[5~', false);
expect(move.defaultPrevented).toBe(true);
detach();
});
it('scrolls down when the alternate-buffer finger moves up', () => {
const term = makeTerminal({ rows: 24, height: 480 });
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [40]));
expect(term.input).toHaveBeenCalledWith('\x1b[6~', false);
detach();
});
it('scrolls an ordinary shell session row-by-row', () => {
const term = makeTerminal({ alt: false, rows: 24, height: 480 });
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
const move = touchEvent('touchmove', [360]);
term.element.dispatchEvent(move);
expect(term.scrollLines).toHaveBeenCalledWith(-3);
expect(move.defaultPrevented).toBe(true);
detach();
});
it('claims sub-row movement before the browser starts panning an ancestor', () => {
const term = makeTerminal({ rows: 24, height: 480 });
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
const move = touchEvent('touchmove', [305]);
term.element.dispatchEvent(move);
expect(term.input).not.toHaveBeenCalled();
expect(move.defaultPrevented).toBe(true);
detach();
});
it('routes small bidirectional drags through mouse wheel input, not page keys', () => {
const term = makeTerminal({ mouseTrackingMode: 'vt200' });
// happy-dom's WheelEvent omits MouseEvent coordinates; assert constructor
// options as well as delivery until its inheritance matches browsers.
const wheelConstructor = vi.spyOn(globalThis, 'WheelEvent');
const wheelEvents = [];
term.element.addEventListener('wheel', event => wheelEvents.push(event));
const detachWheel = attachTerminalWheelScroll(term);
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [325]));
term.element.dispatchEvent(touchEvent('touchmove', [300]));
expect(wheelEvents.map(event => [event.deltaY, event.deltaMode]))
.toEqual([[-1, 1], [1, 1]]);
expect(wheelConstructor).toHaveBeenNthCalledWith(1, 'wheel', expect.objectContaining({ clientX: 150, clientY: 325 }));
expect(wheelConstructor).toHaveBeenNthCalledWith(2, 'wheel', expect.objectContaining({ clientX: 150, clientY: 300 }));
expect(term.input).not.toHaveBeenCalled();
expect(term.scrollLines).not.toHaveBeenCalled();
detach();
detachWheel();
wheelConstructor.mockRestore();
});
it('reserves panning while preserving pinch zoom, taps, and the previous style on detach', () => {
const term = makeTerminal();
term.element.style.touchAction = 'auto';
const detach = attachTerminalTouchScroll(term);
expect(term.element.style.touchAction).toBe('pinch-zoom');
const start = touchEvent('touchstart', [300]);
term.element.dispatchEvent(start);
expect(start.defaultPrevented).toBe(false);
const pinch = touchEvent('touchmove', [280, 400]);
term.element.dispatchEvent(pinch);
expect(pinch.defaultPrevented).toBe(false);
term.element.dispatchEvent(touchEvent('touchmove', [600]));
expect(term.input).not.toHaveBeenCalled();
detach();
expect(term.element.style.touchAction).toBe('auto');
});
it('still scrolls an alternate buffer before layout is available', () => {
const term = makeTerminal({ rows: 24, height: 0 }); // 18px fallback, 216px threshold
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [520]));
expect(term.input).toHaveBeenCalledWith('\x1b[5~', false);
detach();
});
it('measures once per gesture rather than on every move', () => {
const term = makeTerminal({ rows: 24, height: 480 });
const screen = term.element.querySelector('.xterm-screen');
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
const measure = vi.spyOn(screen, 'getBoundingClientRect');
for (let y = 320; y <= 500; y += 20) term.element.dispatchEvent(touchEvent('touchmove', [y]));
expect(measure).not.toHaveBeenCalled();
detach();
});
it('ignores a two-finger gesture (pinch-zoom belongs to the browser)', () => {
const term = makeTerminal();
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300, 400]));
term.element.dispatchEvent(touchEvent('touchmove', [200, 500]));
expect(term.input).not.toHaveBeenCalled();
detach();
});
it('does not carry drag distance across separate gestures', () => {
const term = makeTerminal({ alt: false, rows: 24, height: 480 });
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [315]));
term.element.dispatchEvent(touchEvent('touchend', []));
expect(term.scrollLines).not.toHaveBeenCalled();
// A fresh 15px drag must not combine with the first gesture's remainder.
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [315]));
expect(term.scrollLines).not.toHaveBeenCalled();
detach();
});
it('coasts a shell flick and stops at the scrollback boundary', () => {
vi.useFakeTimers();
const term = makeTerminal({ alt: false });
term.buffer.active.viewportY = 20;
term.scrollLines.mockImplementation(lines => {
term.buffer.active.viewportY = Math.max(0, term.buffer.active.viewportY + lines);
});
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
vi.advanceTimersByTime(20);
term.element.dispatchEvent(touchEvent('touchmove', [340]));
expect(term.buffer.active.viewportY).toBe(18);
term.element.dispatchEvent(touchEvent('touchend', []));
vi.advanceTimersByTime(48);
expect(term.buffer.active.viewportY).toBeLessThan(18);
vi.advanceTimersByTime(2000);
const settled = term.scrollLines.mock.calls.length;
vi.advanceTimersByTime(2000);
expect(term.scrollLines).toHaveBeenCalledTimes(settled);
detach();
vi.useRealTimers();
});
it.each(['touchstart', 'touchcancel', 'wheel', 'detach', 'buffer', 'session reset'])('cancels a shell flick on %s', action => {
vi.useFakeTimers();
const term = makeTerminal({ alt: false });
term.buffer.active.viewportY = 100;
term.scrollLines.mockImplementation(lines => { term.buffer.active.viewportY += lines; });
const detach = attachTerminalTouchScroll(term);
term.element.dispatchEvent(touchEvent('touchstart', [300]));
vi.advanceTimersByTime(20);
term.element.dispatchEvent(touchEvent('touchmove', [340]));
term.element.dispatchEvent(touchEvent('touchend', []));
if (action === 'session reset') resetTerminalWheelScroll(term);
else if (action === 'detach') detach();
else if (action === 'buffer') term.buffer.active = { type: 'alternate' };
else if (action === 'wheel') term.element.dispatchEvent(new WheelEvent('wheel'));
else term.element.dispatchEvent(touchEvent(action, action === 'touchstart' ? [340] : []));
vi.advanceTimersByTime(1000);
expect(term.scrollLines).toHaveBeenCalledTimes(1);
expect(term.input).not.toHaveBeenCalled();
detach();
vi.useRealTimers();
});
it('detaches every listener', () => {
const term = makeTerminal();
const detach = attachTerminalTouchScroll(term);
detach();
term.element.dispatchEvent(touchEvent('touchstart', [300]));
term.element.dispatchEvent(touchEvent('touchmove', [600]));
expect(term.input).not.toHaveBeenCalled();
});
it('returns a safe no-op when the terminal has no element yet', () => {
expect(() => attachTerminalTouchScroll(null)()).not.toThrow();
expect(() => attachTerminalTouchScroll({})()).not.toThrow();
});
});