Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { getCollector } from '../lib/perf/collector';
import {
centeredScrollTop,
type LandingCancelReason,
type LandingHandle,
type LandingOutcome,
type LandingPlacement,
type StartLandingParams,
startLanding,
type TargetMetrics,
} from './landing-controller';
import {
__resetScrollRestoreCoordination,
getDocScrollState,
isScrollRestoreSuppressed,
runScrollNavigation,
} from './scroll-restore-coordination';
const TOOLBAR = 56;
const VIEWPORT = 800;
const handles: LandingHandle[] = [];
function buildScroller(scrollHeight = 6000): { container: HTMLElement; content: HTMLElement } {
const container = document.createElement('div');
const content = document.createElement('div');
container.appendChild(content);
Object.defineProperty(container, 'clientHeight', { value: VIEWPORT, configurable: true });
Object.defineProperty(container, 'scrollHeight', { value: scrollHeight, configurable: true });
Object.defineProperty(container, 'scrollTop', { value: 0, writable: true, configurable: true });
container.style.overflowAnchor = 'auto';
document.body.appendChild(container);
return { container, content };
}
const OVERFLOW_ANCHOR_SUPPORTED = (() => {
const probe = document.createElement('div');
probe.style.overflowAnchor = 'none';
return probe.style.overflowAnchor === 'none';
})();
type StartOverrides = Partial<StartLandingParams> &
Pick<StartLandingParams, 'container' | 'measureTarget'>;
function startLandingWith(overrides: StartOverrides): LandingHandle {
const placement: LandingPlacement = overrides.placement ?? 'center';
const params: StartLandingParams = {
docName: 'doc',
grade: 'exact',
placement,
intent: 'toggle',
landedMode: 'source',
toolbarOffset: TOOLBAR,
...overrides,
};
const handle = startLanding(params);
handles.push(handle);
return handle;
}
function markNamed(name: string): { properties?: Record<string, unknown> } | undefined {
return getCollector()
?.marks.toArray()
.find((m) => m.name === name);
}
beforeEach(() => {
vi.useFakeTimers();
vi.stubGlobal('requestAnimationFrame', () => 0);
vi.stubGlobal('cancelAnimationFrame', () => {});
getCollector()?.reset();
__resetScrollRestoreCoordination();
});
afterEach(() => {
for (const handle of handles.splice(0)) handle.cancel('superseded');
vi.useRealTimers();
vi.unstubAllGlobals();
document.body.replaceChildren();
});
describe('centeredScrollTop', () => {
test('lands the target center at the center of the region below the toolbar', () => {
const m: TargetMetrics = { top: 1000, height: 100 };
const scrollTop = centeredScrollTop(m, VIEWPORT, TOOLBAR);
expect(scrollTop).toBe(622);
const targetCenterOnScreen = m.top + m.height / 2 - scrollTop;
expect(targetCenterOnScreen).toBe((TOOLBAR + VIEWPORT) / 2);
});
test('the toolbar offset biases the landing down by half the toolbar height', () => {
const m: TargetMetrics = { top: 1000, height: 100 };
expect(centeredScrollTop(m, VIEWPORT, TOOLBAR)).toBe(
centeredScrollTop(m, VIEWPORT, 0) - TOOLBAR / 2,
);
});
});
describe('startLanding — dispatch and settle', () => {
test('dispatches the centered target immediately, then lands and releases its holds', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
onOutcome: (o) => outcomes.push(o),
});
const expected = centeredScrollTop({ top: 2000, height: 60 }, VIEWPORT, TOOLBAR);
expect(container.scrollTop).toBe(expected);
expect(isScrollRestoreSuppressed('doc')).toBe(true);
if (OVERFLOW_ANCHOR_SUPPORTED) expect(container.style.overflowAnchor).toBe('none');
vi.advanceTimersByTime(150);
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
const landMark = markNamed('ok/landing/land');
expect(landMark?.properties?.grade).toBe('exact');
expect(landMark?.properties?.delta).toBe(0);
expect(isScrollRestoreSuppressed('doc')).toBe(false);
if (OVERFLOW_ANCHOR_SUPPORTED) expect(container.style.overflowAnchor).toBe('auto');
});
test('persists the landing so a later scroll restore reproduces it', () => {
const { container } = buildScroller();
expect(getDocScrollState('doc')).toBeUndefined();
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
landedMode: 'wysiwyg',
});
const expected = centeredScrollTop({ top: 2000, height: 60 }, VIEWPORT, TOOLBAR);
vi.advanceTimersByTime(150);
expect(getDocScrollState('doc')?.offset).toBe(expected);
expect(getDocScrollState('doc')?.mode).toBe('wysiwyg');
});
test('holds the queued target while the editor is still mounting, then lands it', () => {
const { container } = buildScroller();
let metrics: TargetMetrics | null = null;
startLandingWith({ container, measureTarget: () => metrics });
expect(container.scrollTop).toBe(0);
expect(isScrollRestoreSuppressed('doc')).toBe(true);
metrics = { top: 3000, height: 50 };
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
expect(container.scrollTop).toBe(centeredScrollTop(metrics, VIEWPORT, TOOLBAR));
});
test('re-dispatches when the target drifts beyond the threshold', () => {
const { container } = buildScroller();
let top = 1000;
startLandingWith({ container, measureTarget: () => ({ top, height: 40 }), grade: 'ordinal' });
const first = centeredScrollTop({ top: 1000, height: 40 }, VIEWPORT, TOOLBAR);
expect(container.scrollTop).toBe(first);
top = 500;
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
const second = centeredScrollTop({ top: 500, height: 40 }, VIEWPORT, TOOLBAR);
expect(second).not.toBe(first);
expect(container.scrollTop).toBe(second);
});
test('re-dispatches on a content-column resize', () => {
let fire: (() => void) | undefined;
class FakeResizeObserver {
constructor(cb: () => void) {
fire = cb;
}
observe(): void {}
disconnect(): void {}
}
vi.stubGlobal('ResizeObserver', FakeResizeObserver);
const { container, content } = buildScroller();
let top = 1000;
const handle = startLandingWith({
container,
contentColumn: content,
measureTarget: () => ({ top, height: 40 }),
});
const first = container.scrollTop;
top = 1400;
fire?.();
const second = centeredScrollTop({ top: 1400, height: 40 }, VIEWPORT, TOOLBAR);
expect(second).not.toBe(first);
expect(container.scrollTop).toBe(second);
handle.cancel('mode-flip');
});
test("'top' placement pins the block top just below the toolbar", () => {
const { container } = buildScroller();
startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
placement: 'top',
});
expect(container.scrollTop).toBe(1000 - TOOLBAR);
});
test('emits a mode-switch transition mark when a transition is provided', () => {
const { container } = buildScroller();
startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
placement: 'top',
transition: { from: 'wysiwyg', to: 'source' },
});
const transitionMark = markNamed('ok/mode-switch/transition');
expect(transitionMark?.properties?.from).toBe('wysiwyg');
expect(transitionMark?.properties?.to).toBe('source');
});
});
describe('startLanding — cancel and abandon', () => {
test('cancels on the user wheel and does not re-dispatch afterward', () => {
const { container } = buildScroller();
let top = 1000;
const outcomes: LandingOutcome[] = [];
const discard = vi.fn();
startLandingWith({
container,
measureTarget: () => ({ top, height: 40 }),
onOutcome: (o) => outcomes.push(o),
onDiscardQueuedTarget: discard,
});
const afterDispatch = container.scrollTop;
container.dispatchEvent(new Event('wheel'));
expect(outcomes).toEqual([{ status: 'cancelled', reason: 'user-scroll' }]);
expect(isScrollRestoreSuppressed('doc')).toBe(false);
expect(discard).not.toHaveBeenCalled();
top = 200;
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
expect(container.scrollTop).toBe(afterDispatch);
});
test.each(['End', 'e'])(
'keyboard %s keeps the newer viewport after pending landing work',
(key) => {
const { container, content } = buildScroller();
startLandingWith({
container,
contentColumn: content,
measureTarget: () => ({ top: TOOLBAR, height: 40 }),
placement: 'top',
});
expect(isScrollRestoreSuppressed('doc')).toBe(true);
content.addEventListener('keydown', (event) => event.stopPropagation());
content.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
container.scrollTop = 1843;
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
vi.runAllTimers();
expect(getDocScrollState('doc')).toBeUndefined();
expect(container.scrollTop).toBe(1843);
},
);
test('does not cancel when the initiating keydown starts the landing during window capture', () => {
const { container, content } = buildScroller();
const outcomes: LandingOutcome[] = [];
const startFromWindow = (): void => {
startLandingWith({
container,
contentColumn: content,
measureTarget: () => ({ top: TOOLBAR, height: 40 }),
placement: 'top',
onOutcome: (o) => outcomes.push(o),
});
};
const stopAtDescendant = (event: KeyboardEvent): void => event.stopPropagation();
content.addEventListener('keydown', stopAtDescendant);
window.addEventListener('keydown', startFromWindow, true);
content.dispatchEvent(new KeyboardEvent('keydown', { key: 'm', bubbles: true }));
window.removeEventListener('keydown', startFromWindow, true);
content.removeEventListener('keydown', stopAtDescendant);
expect(outcomes).toEqual([]);
vi.advanceTimersByTime(150);
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
});
test('keyboard input outside the landing container leaves its landing active', () => {
const { container } = buildScroller();
const outside = document.createElement('div');
document.body.append(outside);
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
onOutcome: (outcome) => outcomes.push(outcome),
});
outside.dispatchEvent(new KeyboardEvent('keydown', { key: 'e', bubbles: true }));
expect(isScrollRestoreSuppressed('doc')).toBe(true);
expect(outcomes).toEqual([]);
vi.advanceTimersByTime(150);
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
});
test('cancels on a touch gesture', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
onOutcome: (o) => outcomes.push(o),
});
container.dispatchEvent(new Event('touchstart'));
expect(outcomes).toEqual([{ status: 'cancelled', reason: 'user-scroll' }]);
});
test('cancels on a mode flip and discards the queued target', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
const discard = vi.fn();
const handle = startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
onOutcome: (o) => outcomes.push(o),
onDiscardQueuedTarget: discard,
});
const reason: LandingCancelReason = 'mode-flip';
handle.cancel(reason);
expect(outcomes).toEqual([{ status: 'cancelled', reason: 'mode-flip' }]);
expect(discard).toHaveBeenCalledTimes(1);
expect(isScrollRestoreSuppressed('doc')).toBe(false);
});
test('abandons after the window when the target never settles, marking target and delta', () => {
const { container } = buildScroller();
let top = 1000;
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => ({ top, height: 40 }),
onOutcome: (o) => outcomes.push(o),
});
for (let elapsed = 0; elapsed < 2000; elapsed += 100) {
top = top === 1000 ? 2500 : 1000;
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
vi.advanceTimersByTime(100);
}
expect(outcomes.some((o) => o.status === 'abandoned')).toBe(true);
expect(outcomes.some((o) => o.status === 'landed')).toBe(false);
const abandonMark = markNamed('ok/landing/abandoned');
expect(typeof abandonMark?.properties?.target).toBe('number');
expect(typeof abandonMark?.properties?.delta).toBe('number');
expect(isScrollRestoreSuppressed('doc')).toBe(false);
});
test('terminates exactly once — a cancel after landing is a no-op', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
const handle = startLandingWith({
container,
measureTarget: () => ({ top: 1000, height: 40 }),
onOutcome: (o) => outcomes.push(o),
});
vi.advanceTimersByTime(150);
handle.cancel('mode-flip');
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
});
test('abandons (not lands) when the target is never measurable', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => null,
onOutcome: (o) => outcomes.push(o),
});
expect(container.scrollTop).toBe(0);
vi.advanceTimersByTime(2000);
expect(outcomes).toEqual([{ status: 'abandoned', delta: 0 }]);
});
});
describe('startLanding — explicit navigation pre-emption', () => {
const NAV_SCROLL_TOP = 1189;
test('supersedes a toggle landing, and the navigation keeps the scroller', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
const discard = vi.fn();
let top = 2000;
startLandingWith({
container,
measureTarget: () => ({ top, height: 60 }),
placement: 'top',
intent: 'toggle',
onOutcome: (o) => outcomes.push(o),
onDiscardQueuedTarget: discard,
});
expect(container.scrollTop).toBe(2000 - TOOLBAR);
const ran = runScrollNavigation('doc', 'outline', () => {
container.scrollTop = NAV_SCROLL_TOP;
});
expect(ran).toBe(true);
expect(container.scrollTop).toBe(NAV_SCROLL_TOP);
expect(outcomes).toEqual([{ status: 'cancelled', reason: 'superseded' }]);
expect(isScrollRestoreSuppressed('doc')).toBe(true);
expect(discard).not.toHaveBeenCalled();
top = 400;
container.dispatchEvent(new Event('contentvisibilityautostatechange'));
vi.advanceTimersByTime(2000);
expect(container.scrollTop).toBe(NAV_SCROLL_TOP);
expect(outcomes).toHaveLength(1);
expect(isScrollRestoreSuppressed('doc')).toBe(false);
});
test('does not persist the position it would have erased', () => {
const { container } = buildScroller();
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
placement: 'top',
intent: 'toggle',
});
runScrollNavigation('doc', 'outline', () => {
container.scrollTop = NAV_SCROLL_TOP;
});
vi.advanceTimersByTime(2000);
expect(getDocScrollState('doc')).toBeUndefined();
});
test('a jump landing keeps the scroller and the navigation stands down', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
const scroll = vi.fn();
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
placement: 'center',
intent: 'jump',
onOutcome: (o) => outcomes.push(o),
});
const landingTarget = container.scrollTop;
const ran = runScrollNavigation('doc', 'outline', scroll);
expect(ran).toBe(false);
expect(scroll).not.toHaveBeenCalled();
expect(container.scrollTop).toBe(landingTarget);
expect(outcomes).toEqual([]);
vi.advanceTimersByTime(150);
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
});
test('a navigation on another document leaves the landing alone', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
placement: 'top',
intent: 'toggle',
onOutcome: (o) => outcomes.push(o),
});
expect(runScrollNavigation('some-other-doc', 'outline', () => {})).toBe(true);
expect(outcomes).toEqual([]);
vi.advanceTimersByTime(150);
expect(outcomes).toEqual([{ status: 'landed', delta: 0 }]);
});
test('a landing that already terminated no longer holds the scroller', () => {
const { container } = buildScroller();
startLandingWith({
container,
measureTarget: () => ({ top: 2000, height: 60 }),
placement: 'center',
intent: 'jump',
});
vi.advanceTimersByTime(150);
const scroll = vi.fn();
expect(runScrollNavigation('doc', 'outline', scroll)).toBe(true);
expect(scroll).toHaveBeenCalledTimes(1);
});
});
describe('startLanding — a throwing measurer releases every hold', () => {
const BOOM = 'view destroyed mid-settle';
function expectHoldsReleased(): void {
expect(isScrollRestoreSuppressed('doc')).toBe(false);
const scroll = vi.fn();
expect(runScrollNavigation('doc', 'outline', scroll)).toBe(true);
expect(scroll).toHaveBeenCalledTimes(1);
}
test('when the first dispatch throws, before any handle is returned', () => {
const { container } = buildScroller();
expect(() =>
startLandingWith({
container,
measureTarget: () => {
throw new Error(BOOM);
},
placement: 'center',
intent: 'jump',
}),
).toThrow(BOOM);
expectHoldsReleased();
});
test('when the measurer starts throwing before the settle lands', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
let throwing = false;
startLandingWith({
container,
measureTarget: (): TargetMetrics | null => {
if (throwing) throw new Error(BOOM);
return { top: 2000, height: 60 };
},
placement: 'center',
intent: 'jump',
onOutcome: (o) => outcomes.push(o),
});
throwing = true;
expect(() => vi.advanceTimersByTime(150)).toThrow(BOOM);
expectHoldsReleased();
expect(outcomes).toEqual([]);
});
test('when the measurer throws at the abandon deadline', () => {
const { container } = buildScroller();
const outcomes: LandingOutcome[] = [];
let throwing = false;
startLandingWith({
container,
measureTarget: (): TargetMetrics | null => {
if (throwing) throw new Error(BOOM);
return null;
},
placement: 'center',
intent: 'jump',
onOutcome: (o) => outcomes.push(o),
});
throwing = true;
expect(() => vi.advanceTimersByTime(2000)).toThrow(BOOM);
expectHoldsReleased();
expect(outcomes).toEqual([]);
});
});