Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

18.1 KB
Raw Blame
// @vitest-environment jsdom

import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { getCollector } from '@/lib/perf/collector';
import {
  __resetScrollRestoreCoordination,
  acquireScrollRestoreSuppression,
  BODY_ANCHOR_ATTR,
  claimScrollerForNavigation,
  type DocScrollState,
  getDocScrollState,
  isScrollRestoreSuppressed,
  type LandingScrollOwner,
  MAX_TRACKED_DECLINE_DOCS,
  MAX_TRACKED_DOC_SCROLL,
  registerLandingScrollOwner,
  rememberDocScrollState,
  runScrollNavigation,
  scrollFraction,
  scrollSuppressionHolder,
  writeLandingResult,
} from './scroll-restore-coordination';
import type { EditorModeValue } from './use-editor-mode';

function state(offset: number, mode: EditorModeValue = 'wysiwyg', fraction = 0): DocScrollState {
  return { offset, mode, fraction };
}

beforeEach(() => {
  __resetScrollRestoreCoordination();
});

afterEach(() => {
  __resetScrollRestoreCoordination();
  vi.restoreAllMocks();
});

function elementAt(top: number, scrollTop = 0, boxes = 1): HTMLElement {
  const el = document.createElement('div');
  vi.spyOn(el, 'getClientRects').mockReturnValue({ length: boxes } as DOMRectList);
  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
    top,
    bottom: top,
    left: 0,
    right: 0,
    width: 0,
    height: 0,
    x: 0,
    y: top,
    toJSON: () => ({}),
  } as DOMRect);
  Object.defineProperty(el, 'scrollTop', { configurable: true, writable: true, value: scrollTop });
  return el;
}

describe('scroll-restore state persistence', () => {
  test('a document with no remembered state reads back undefined', () => {
    expect(getDocScrollState('never-written')).toBeUndefined();
  });

  test('remembers and reads back a document offset', () => {
    rememberDocScrollState('doc', state(42));
    expect(getDocScrollState('doc')?.offset).toBe(42);
  });

  test('records the mode the position was captured in so a restore can tell same- from cross-mode', () => {
    rememberDocScrollState('doc', state(42, 'source', 0.4));
    expect(getDocScrollState('doc')?.mode).toBe('source');
    expect(getDocScrollState('doc')?.fraction).toBe(0.4);
  });

  test('a later write for the same document overwrites the earlier one', () => {
    rememberDocScrollState('doc', state(42, 'wysiwyg'));
    rememberDocScrollState('doc', state(99, 'source'));
    expect(getDocScrollState('doc')?.offset).toBe(99);
    expect(getDocScrollState('doc')?.mode).toBe('source');
  });

  test('evicts the least-recently-written document once capacity is exceeded', () => {
    for (let i = 0; i <= MAX_TRACKED_DOC_SCROLL; i++) rememberDocScrollState(`k${i}`, state(i));
    expect(getDocScrollState('k0')).toBeUndefined();
    expect(getDocScrollState(`k${MAX_TRACKED_DOC_SCROLL}`)?.offset).toBe(MAX_TRACKED_DOC_SCROLL);
  });

  test('re-writing a document refreshes its recency so it is not the next evicted', () => {
    for (let i = 0; i < MAX_TRACKED_DOC_SCROLL; i++) rememberDocScrollState(`k${i}`, state(i));
    rememberDocScrollState('k0', state(1000));
    rememberDocScrollState('overflow', state(-1));
    expect(getDocScrollState('k0')?.offset).toBe(1000);
    expect(getDocScrollState('k1')).toBeUndefined();
  });
});

describe('scrollFraction', () => {
  test('is the ratio of scrollTop to the scrollable range', () => {
    expect(scrollFraction(1000, 5000, 1000)).toBe(0.25);
  });

  test('is zero when the content does not overflow (no scrollable range)', () => {
    expect(scrollFraction(0, 800, 800)).toBe(0);
    expect(scrollFraction(50, 500, 800)).toBe(0);
  });

  test('clamps into [0,1] for out-of-range inputs', () => {
    expect(scrollFraction(-100, 5000, 1000)).toBe(0);
    expect(scrollFraction(9999, 5000, 1000)).toBe(1);
  });
});

describe('writeLandingResult', () => {
  test('persists the target as a body-relative offset using an explicit anchor', () => {
    const container = elementAt(100, 50);
    const anchor = elementAt(300);
    writeLandingResult({
      docName: 'doc',
      container,
      targetScrollTop: 1000,
      mode: 'source',
      anchor,
    });
    expect(getDocScrollState('doc')?.offset).toBe(750);
  });

  test('stamps the mode the landing landed in', () => {
    const container = elementAt(100, 50);
    writeLandingResult({ docName: 'doc', container, targetScrollTop: 1000, mode: 'source' });
    expect(getDocScrollState('doc')?.mode).toBe('source');
  });

  test('records the landing fraction from the container scroll range', () => {
    const container = elementAt(100, 0);
    Object.defineProperty(container, 'scrollHeight', { configurable: true, value: 5000 });
    Object.defineProperty(container, 'clientHeight', { configurable: true, value: 1000 });
    writeLandingResult({ docName: 'doc', container, targetScrollTop: 1000, mode: 'source' });
    expect(getDocScrollState('doc')?.fraction).toBe(0.25);
  });

  test('finds the body anchor via its marker attribute when none is passed', () => {
    const container = elementAt(100, 50);
    const anchor = elementAt(300);
    anchor.setAttribute(BODY_ANCHOR_ATTR, '');
    container.appendChild(anchor);
    writeLandingResult({ docName: 'doc', container, targetScrollTop: 1000, mode: 'wysiwyg' });
    expect(getDocScrollState('doc')?.offset).toBe(750);
  });

  test('falls back to the raw target when the container has no body anchor', () => {
    const container = elementAt(100, 50);
    writeLandingResult({ docName: 'doc', container, targetScrollTop: 1000, mode: 'wysiwyg' });
    expect(getDocScrollState('doc')?.offset).toBe(1000);
  });

  test('takes the raw fallback for an anchor with no layout boxes, never its zero rect', () => {
    const container = elementAt(100, 50);
    const hiddenAnchor = elementAt(0, 0, 0);
    writeLandingResult({
      docName: 'doc',
      container,
      targetScrollTop: 1000,
      mode: 'wysiwyg',
      anchor: hiddenAnchor,
    });
    expect(getDocScrollState('doc')?.offset).toBe(1000);
  });
});

describe('scroll-restore suppression registry', () => {
  test('a document is not suppressed until a handle is acquired', () => {
    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('acquiring a handle suppresses the document; releasing it re-enables restore', () => {
    const handle = acquireScrollRestoreSuppression('doc', 'landing');
    expect(isScrollRestoreSuppressed('doc')).toBe(true);
    handle.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('overlapping holders each keep suppression until all release', () => {
    const first = acquireScrollRestoreSuppression('doc', 'landing');
    const second = acquireScrollRestoreSuppression('doc', 'landing');
    first.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(true);
    second.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('releasing the same handle twice does not underflow another holder', () => {
    const first = acquireScrollRestoreSuppression('doc', 'landing');
    const second = acquireScrollRestoreSuppression('doc', 'landing');
    first.release();
    first.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(true);
    second.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('suppression is scoped per document', () => {
    const handle = acquireScrollRestoreSuppression('a', 'landing');
    expect(isScrollRestoreSuppressed('a')).toBe(true);
    expect(isScrollRestoreSuppressed('b')).toBe(false);
    handle.release();
  });
});

describe('the holder behind a document suppression', () => {
  test('nobody holds an unsuppressed document', () => {
    expect(scrollSuppressionHolder('doc')).toBeNull();
  });

  test('each kind names itself', () => {
    const landing = acquireScrollRestoreSuppression('doc', 'landing');
    expect(scrollSuppressionHolder('doc')).toBe('landing');
    landing.release();

    const navigation = acquireScrollRestoreSuppression('doc', 'navigation');
    expect(scrollSuppressionHolder('doc')).toBe('navigation');
    navigation.release();
    expect(scrollSuppressionHolder('doc')).toBeNull();
  });

  test('a landing outranks a navigation while both hold', () => {
    const navigation = acquireScrollRestoreSuppression('doc', 'navigation');
    const landing = acquireScrollRestoreSuppression('doc', 'landing');

    expect(scrollSuppressionHolder('doc')).toBe('landing');

    navigation.release();
    expect(scrollSuppressionHolder('doc')).toBe('landing');
    landing.release();
    expect(scrollSuppressionHolder('doc')).toBeNull();
  });

  test('releasing one kind does not clear the other, in either order', () => {
    const landingFirst = acquireScrollRestoreSuppression('doc', 'landing');
    acquireScrollRestoreSuppression('doc', 'navigation');
    landingFirst.release();
    expect(scrollSuppressionHolder('doc')).toBe('navigation');
  });

  test('a handle issued before a reset cannot decrement what came after', () => {
    const stale = acquireScrollRestoreSuppression('doc', 'landing');
    __resetScrollRestoreCoordination();
    const fresh = acquireScrollRestoreSuppression('doc', 'landing');

    stale.release();

    expect(scrollSuppressionHolder('doc')).toBe('landing');
    fresh.release();
    expect(scrollSuppressionHolder('doc')).toBeNull();
  });
});

describe('landing scroll owners and explicit navigation', () => {
  function ownLanding(docName: string, yieldsToNavigation: boolean): () => number {
    let superseded = 0;
    const registration = registerLandingScrollOwner(docName, {
      yieldsToNavigation,
      supersede: () => {
        superseded += 1;
        registration.release();
      },
    });
    return () => superseded;
  }

  test('an unowned scroller is free for a navigation', () => {
    const scroll = vi.fn();
    expect(runScrollNavigation('doc', 'outline', scroll)).toBe(true);
    expect(scroll).toHaveBeenCalledTimes(1);
  });

  test('a yielding owner is superseded and the navigation runs', () => {
    const superseded = ownLanding('doc', true);
    const scroll = vi.fn();

    expect(runScrollNavigation('doc', 'outline', scroll)).toBe(true);

    expect(superseded()).toBe(1);
    expect(scroll).toHaveBeenCalledTimes(1);
    expect(claimScrollerForNavigation('doc', 'find-match')).toBe(true);
    expect(superseded()).toBe(1);
  });

  test('a non-yielding owner keeps the scroller and the navigation does not run', () => {
    const superseded = ownLanding('doc', false);
    const scroll = vi.fn();

    expect(runScrollNavigation('doc', 'outline', scroll)).toBe(false);

    expect(superseded()).toBe(0);
    expect(scroll).not.toHaveBeenCalled();
  });

  test('overlapping yielding owners are all superseded', () => {
    const first = ownLanding('doc', true);
    const second = ownLanding('doc', true);

    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(true);

    expect(first()).toBe(1);
    expect(second()).toBe(1);
  });

  test('one non-yielding owner blocks the claim, superseding none of them', () => {
    const yielding = ownLanding('doc', true);
    const holding = ownLanding('doc', false);

    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(false);

    expect(yielding()).toBe(0);
    expect(holding()).toBe(0);
  });

  test('a released owner no longer holds the scroller', () => {
    const supersede = vi.fn();
    const owner: LandingScrollOwner = { yieldsToNavigation: false, supersede };
    const registration = registerLandingScrollOwner('doc', owner);
    expect(claimScrollerForNavigation('doc', 'find-match')).toBe(false);

    registration.release();
    registration.release();

    expect(claimScrollerForNavigation('doc', 'find-match')).toBe(true);
    expect(supersede).not.toHaveBeenCalled();
  });

  test('ownership is scoped per document', () => {
    ownLanding('a', false);
    expect(claimScrollerForNavigation('a', 'find-match')).toBe(false);
    expect(claimScrollerForNavigation('b', 'find-match')).toBe(true);
  });
});

describe('an explicit navigation stands the scroll-restore loop down', () => {
  const OWNERSHIP_LAPSES_WITHIN_MS = 2_000;

  const NAVIGATION_DECLINED_MARK = 'ok/scroll-nav/declined';

  beforeEach(() => {
    vi.useFakeTimers({
      toFake: [
        'setTimeout',
        'clearTimeout',
        'setInterval',
        'clearInterval',
        'requestAnimationFrame',
        'cancelAnimationFrame',
      ],
    });
    getCollector()?.reset();
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  function lapseOwnership(): void {
    vi.advanceTimersByTime(OWNERSHIP_LAPSES_WITHIN_MS);
  }

  function ownLandingThatNeverYields(docName: string): void {
    registerLandingScrollOwner(docName, { yieldsToNavigation: false, supersede: () => {} });
  }

  function declinedNavigations(): unknown[] {
    return (getCollector()?.marks.toArray() ?? [])
      .filter((m) => m.name === NAVIGATION_DECLINED_MARK)
      .map((m) => m.properties);
  }

  test('the restore loop is suppressed for the whole of the caller write', () => {
    let suppressedDuringWrite: boolean | undefined;

    const ran = runScrollNavigation('doc', 'outline', () => {
      suppressedDuringWrite = isScrollRestoreSuppressed('doc');
    });

    expect(ran).toBe(true);
    expect(suppressedDuringWrite).toBe(true);
  });

  test('the suppression outlives the call, because the loop measures a frame later', () => {
    runScrollNavigation('doc', 'outline', () => {});

    expect(isScrollRestoreSuppressed('doc')).toBe(true);
  });

  test('and then lapses — a navigation borrows the scroller, it does not keep it', () => {
    runScrollNavigation('doc', 'outline', () => {});

    lapseOwnership();

    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('successive navigations each release their own hold', () => {
    runScrollNavigation('doc', 'outline', () => {});
    runScrollNavigation('doc', 'outline', () => {});

    lapseOwnership();

    expect(isScrollRestoreSuppressed('doc')).toBe(false);
    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(true);
    expect(isScrollRestoreSuppressed('doc')).toBe(true);
  });

  test('suppression is scoped to the navigated document', () => {
    runScrollNavigation('doc', 'outline', () => {});

    expect(isScrollRestoreSuppressed('other')).toBe(false);
  });

  test('the hold is taken before a superseded landing lets go of its own', () => {
    const landing = acquireScrollRestoreSuppression('doc', 'landing');
    let suppressedDuringHandover: boolean | undefined;
    registerLandingScrollOwner('doc', {
      yieldsToNavigation: true,
      supersede: () => {
        landing.release();
        suppressedDuringHandover = isScrollRestoreSuppressed('doc');
      },
    });

    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(true);

    expect(suppressedDuringHandover).toBe(true);
  });

  test('a refused navigation suppresses nothing', () => {
    ownLandingThatNeverYields('doc');

    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(false);

    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('a refused navigation is recorded, not silently swallowed', () => {
    ownLandingThatNeverYields('doc');

    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(false);

    expect(declinedNavigations()).toEqual([
      expect.objectContaining({ docName: 'doc', seam: 'outline', ownerCount: 1 }),
    ]);
  });

  test('a completed navigation is not recorded as refused', () => {
    runScrollNavigation('doc', 'outline', () => {});

    expect(declinedNavigations()).toEqual([]);
  });

  test('a polling seam records one refusal episode, not one entry per attempt', () => {
    ownLandingThatNeverYields('doc');

    for (let attempt = 0; attempt < 25; attempt += 1) {
      expect(runScrollNavigation('doc', 'deep-link', () => {})).toBe(false);
    }

    expect(declinedNavigations()).toHaveLength(1);
  });

  test('a second seam refused in the same window is recorded separately', () => {
    ownLandingThatNeverYields('doc');

    runScrollNavigation('doc', 'deep-link', () => {});
    runScrollNavigation('doc', 'outline', () => {});

    expect(declinedNavigations().map((p) => (p as { seam: string }).seam)).toEqual([
      'deep-link',
      'outline',
    ]);
  });

  test('a navigation that gets through re-arms the next refusal', () => {
    const registration = registerLandingScrollOwner('doc', {
      yieldsToNavigation: false,
      supersede: () => {},
    });
    runScrollNavigation('doc', 'outline', () => {});
    registration.release();
    expect(runScrollNavigation('doc', 'outline', () => {})).toBe(true);
    ownLandingThatNeverYields('doc');

    runScrollNavigation('doc', 'outline', () => {});

    expect(declinedNavigations()).toHaveLength(2);
  });

  test('the refusal streak map does not grow without bound', () => {
    const first = 'doc-0';
    ownLandingThatNeverYields(first);
    expect(runScrollNavigation(first, 'outline', () => {})).toBe(false);
    expect(runScrollNavigation(first, 'deep-link', () => {})).toBe(false);

    for (let i = 1; i <= MAX_TRACKED_DECLINE_DOCS; i += 1) {
      const later = `doc-${i}`;
      ownLandingThatNeverYields(later);
      runScrollNavigation(later, 'outline', () => {});
    }

    runScrollNavigation(first, 'outline', () => {});
    runScrollNavigation(first, 'deep-link', () => {});

    expect(
      declinedNavigations().filter((props) => (props as { docName: string }).docName === first),
    ).toHaveLength(4);
  });

  test('the bare claim carries the same guarantee', () => {
    expect(claimScrollerForNavigation('doc', 'find-match')).toBe(true);
    expect(isScrollRestoreSuppressed('doc')).toBe(true);

    lapseOwnership();

    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('a refused bare claim suppresses nothing', () => {
    ownLandingThatNeverYields('doc');

    expect(claimScrollerForNavigation('doc', 'find-match')).toBe(false);

    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });

  test('a reset revokes a pending release, so it cannot cut short the next hold', () => {
    runScrollNavigation('doc', 'outline', () => {});

    __resetScrollRestoreCoordination();
    const landing = acquireScrollRestoreSuppression('doc', 'landing');
    lapseOwnership();

    expect(isScrollRestoreSuppressed('doc')).toBe(true);
    landing.release();
    expect(isScrollRestoreSuppressed('doc')).toBe(false);
  });
});