Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

28.6 KB
Raw Blame
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import ts from 'typescript';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import * as scrollModel from '@/session/messageScroll';
import { createMobileTailFollower } from '@/session/messageTailFollower';
import { RichContentRuntime } from '@/session/richContentRuntime';
import { mobileDebugEnabled, mobileDebugLog, setMobileDebugSink } from '@/debug/mobileDebugLog';
import { createScrollDebugSampler } from '@/debug/scrollDebugSampler';

// Execute the production callbacks without mounting Markdown/media/native views. Unlike source
// assertions, this harness interleaves touch, native scroll, content-size, timers and frame delivery.
const source = ts.createSourceFile('MessageRenderer.tsx', readFileSync(
  resolve(process.cwd(), 'src/session/MessageRenderer.tsx'), 'utf8',
), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
const renderer = source.statements.find((node): node is ts.FunctionDeclaration => (
  ts.isFunctionDeclaration(node) && node.name?.text === 'MessageRenderer'
));
const callbackNames = [
  'markProgrammaticScroll', 'clearProgrammaticScroll', 'markMobileMvcpSettle',
  'isUserControllingScroll', 'revealPositionedHistory', 'getTailFollower', 'scrollToEndProgrammatically', 'runStickToLatestVerify',
  'scrollToOffsetProgrammatically', 'scrollToIndexProgrammatically',
  'scrollToBottom', 'handleScroll', 'handleHistoryTouchStart', 'maybeTriggerHistoryTouch',
  'handleHistoryTouchMove', 'handleHistoryTouchEnd', 'handleHistoryTouchCancel',
  'handleScrollBeginDrag', 'handleScrollEndDrag', 'handleMomentumScrollBegin',
  'handleMomentumScrollEnd', 'handleContentSize', 'reconcileReopeningAnchor',
] as const;
type CallbackName = typeof callbackNames[number];
const declarations = renderer!.body!.statements.filter((node) => (
  ts.isVariableStatement(node) && node.declarationList.declarations.some((declaration) => (
    ts.isIdentifier(declaration.name) && callbackNames.includes(declaration.name.text as CallbackName)
  ))
));
const constants = source.statements.filter((node) => (
  ts.isVariableStatement(node) && node.declarationList.declarations.some((declaration) => (
    ts.isIdentifier(declaration.name) && /^MOBILE_PROGRAMMATIC_.*_MS$/.test(declaration.name.text)
  ))
));
const compiled = ts.transpileModule([
  ...constants.map((node) => node.getText(source)),
  ...declarations.map((node) => node.getText(source)),
  `return { ${callbackNames.join(', ')} };`,
].join('\n'), { compilerOptions: { target: ts.ScriptTarget.ES2022 } }).outputText;

const opacityDeclaration = renderer!.body!.statements.flatMap(node => (
  ts.isVariableStatement(node) ? [...node.declarationList.declarations] : []
)).find(node => ts.isIdentifier(node.name) && node.name.text === 'initialRevealOpacity')!;
const renderOpacity = new Function('listRevealed', 'initialRevealProgress',
  `return ${opacityDeclaration.initializer!.getText(source)};`) as (revealed: boolean, progress: object) => unknown;

function harness(richContent: RichContentRuntime | null = new RichContentRuntime()) {
  const ref = <T>(current: T) => ({ current });
  const state = {
    historyActiveRef: ref(true),
    historyPositioningRef: ref(true),
    nearBottomRef: ref(true), readingOlderRef: ref(false),
    isDraggingRef: ref(false), isMomentumScrollingRef: ref(false),
    historyTouchStartYRef: ref<number | null>(null), historyTouchTriggeredRef: ref(false),
    dragStartOffsetYRef: ref<number | null>(null), userScrollForOlderRef: ref(false),
    lastAutoLoadEarlierKeyRef: ref<string | null>(null),
    programmaticScrollGenerationRef: ref(0), programmaticScrollTimerRef: ref<unknown>(null),
    programmaticScrollInFlightRef: ref(false), programmaticAnimatedScrollInFlightRef: ref(false),
    programmaticScrollSettleAtRef: ref(0), mvcpSettleAtRef: ref(0),
    tailFollowerRef: ref(null),
    initialAnchorDoneRef: ref(true),
    reopeningAnchorRef: ref<{ anchor: { key: string; viewportOffset: number }; expires: number; corrections: number } | null>(null),
    reopeningFrameRef: ref<number | null>(null),
    readingPositionActiveRef: ref(() => true),
    initialRevealAnimationRef: ref<{ stop: () => void } | null>({ stop: vi.fn() }),
    historyPrependTransactionRef: ref(null), nativeScrollEventSequenceRef: ref(0),
    // Companion receipt behavior is covered by the mounted MessageRenderer tests.
    acknowledgeCompanionReadRef: ref(vi.fn()),
    shareSelectionActiveRef: ref(false),
    itemsForStructureRef: ref([]),
    scrollMetricsRef: ref({ contentHeight: 2000, offsetY: 1200, viewportHeight: 800 }),
  };
  const tailScroll = vi.fn((_options: { animated: boolean }) => {
    const metrics = state.scrollMetricsRef.current;
    metrics.offsetY = metrics.contentHeight - metrics.viewportHeight;
  });
  const environment = {
    richContent,
    remoteDeviceId: 'remote-device', scrollResetKey: 'session',
    readingPosition: { write: vi.fn() }, reopeningPosition: undefined,
    captureCurrentHistoryAnchor: vi.fn((): { key: string; viewportOffset: number } | null => null),
    getCurrentHistoryTopOffsetAdjustment: vi.fn(() => 0),
    resolveMobileMessageHistoryAnchorOffset: vi.fn(() => 600),
    ...scrollModel, ...state, createMobileTailFollower, mobileDebugEnabled, mobileDebugLog,
    sampleScrollDebug: createScrollDebugSampler(),
    initialRevealProgress: { setValue: vi.fn() }, setListRevealed: vi.fn(),
    listRef: ref({
      getState: () => ({ scrollLength: 800, scroll: state.scrollMetricsRef.current.offsetY,
        data: [{ key: 'saved' }], sizeAtIndex: () => 1000 }),
      scrollToEnd: tailScroll,
      scrollToIndex: vi.fn(),
      scrollToOffset: ({ offset, animated }: { offset: number; animated: boolean }) => {
        tailScroll({ animated });
        state.scrollMetricsRef.current.offsetY = offset;
      },
    }), bottomOverlayHeight: undefined,
    useCallback: (callback: unknown) => callback,
    attemptAutoLoadEarlier: vi.fn(), handoffHistoryPrependToUser: vi.fn(),
    scheduleHistoryPrependUserHandoffSettle: vi.fn(), scheduleQueuedLoadEarlierFlush: vi.fn(),
    refreshPreviousUserTarget: vi.fn(), scheduleStickyShareCheck: vi.fn(),
    scheduleHistoryAnchorRestore: vi.fn(), restoreHistoryAnchorOnce: vi.fn(),
    cancelHistoryPrependTransaction: vi.fn(),
    setIsAwayFromBottom: vi.fn(), setHasNewMessages: vi.fn(), setPreviousUserTarget: vi.fn(),
  };
  const callbacks = new Function(...Object.keys(environment), compiled)(
    ...Object.values(environment),
  ) as Record<CallbackName, (...args: unknown[]) => void>;
  const scrollEvent = (offsetY: number) => ({ nativeEvent: {
    contentSize: { height: state.scrollMetricsRef.current.contentHeight },
    contentOffset: { y: offsetY }, layoutMeasurement: { height: 800 },
  } });
  return {
    ...callbacks, state, tailScroll, scrollEvent,
    readingPosition: environment.readingPosition,
    captureCurrentHistoryAnchor: environment.captureCurrentHistoryAnchor,
    initialRevealProgress: environment.initialRevealProgress,
    setListRevealed: environment.setListRevealed,
    handleScrollEndDrag: (event = scrollEvent(state.scrollMetricsRef.current.offsetY)) => (
      callbacks.handleScrollEndDrag(event)
    ),
  };
}
const touch = (pageY = 400) => ({ nativeEvent: { pageY } });
const settle = () => vi.advanceTimersByTime(4000);

beforeEach(() => {
  vi.useFakeTimers();
  vi.stubGlobal('requestAnimationFrame', (callback: () => void) => setTimeout(callback, 16));
  vi.stubGlobal('cancelAnimationFrame', (timer: ReturnType<typeof setTimeout>) => clearTimeout(timer));
});
afterEach(() => { setMobileDebugSink(undefined); vi.useRealTimers(); vi.unstubAllGlobals(); vi.restoreAllMocks(); });

describe('streaming follow yields to the reader', () => {
  it('defers rich content during a drag without preventing reader ownership', () => {
    const richContent = new RichContentRuntime();
    const h = harness(richContent);
    const render = vi.fn();
    richContent.request(render);
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    vi.advanceTimersByTime(150);
    h.handleScroll(h.scrollEvent(1100));
    expect(h.state.nearBottomRef.current).toBe(false);
    vi.advanceTimersByTime(179);
    expect(render).not.toHaveBeenCalled();
    vi.advanceTimersByTime(1);
    expect(render).toHaveBeenCalledOnce();
  });
  it('preserves reader ownership without an Android rich content runtime', () => {
    const h = harness(null);
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1100));
    h.handleScrollEndDrag();
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });
  it('ignores scroll and content growth while its retained task is hidden', () => {
    const h = harness();
    h.state.historyActiveRef.current = false;
    h.state.historyPositioningRef.current = false;
    h.handleScroll(h.scrollEvent(50));
    h.handleContentSize(400, 2600);
    settle();
    expect(h.state.scrollMetricsRef.current.offsetY).toBe(1200);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });
  it('finishes preload geometry before focus without publishing the offscreen position', () => {
    const h = harness();
    h.state.historyActiveRef.current = false;
    h.handleScroll(h.scrollEvent(700));
    expect(h.state.scrollMetricsRef.current.offsetY).toBe(700);
    h.handleContentSize(400, 2600);
    settle();
    expect(h.state.scrollMetricsRef.current.offsetY).toBe(1800);
    expect(h.setListRevealed).toHaveBeenCalledWith(true);
    const calls = h.tailScroll.mock.calls.length;
    h.state.historyActiveRef.current = true;
    h.runStickToLatestVerify();
    settle();
    expect(h.tailScroll).toHaveBeenCalledTimes(calls);
  });
  it('saves user movement during an older-page request and its final momentum sample', () => {
    const h = harness();
    h.state.readingOlderRef.current = true;
    h.state.isMomentumScrollingRef.current = true;
    h.captureCurrentHistoryAnchor.mockImplementation(() => ({
      key: 'long', viewportOffset: -h.state.scrollMetricsRef.current.offsetY,
    }));
    h.handleScroll(h.scrollEvent(600));
    expect(h.readingPosition.write).toHaveBeenLastCalledWith({
      anchor: { key: 'long', viewportOffset: -600 }, atEnd: false,
    });
    h.handleMomentumScrollEnd(h.scrollEvent(650));
    expect(h.readingPosition.write).toHaveBeenLastCalledWith({
      anchor: { key: 'long', viewportOffset: -650 }, atEnd: false,
    });
    h.readingPosition.write.mockClear();
    h.handleScroll(h.scrollEvent(900)); // Layout-only event during prepend.
    expect(h.readingPosition.write).not.toHaveBeenCalled();
  });
  it.each([true, false])('ends bookmark correction after native acknowledgment (focused=%s)', (focused) => {
    const h = harness();
    h.state.historyActiveRef.current = focused;
    h.state.nearBottomRef.current = false;
    h.state.reopeningAnchorRef.current = {
      anchor: { key: 'saved', viewportOffset: -20 }, expires: Date.now() + 1500, corrections: 0,
    };
    // Reveal timeout is not proof of positioning, and must not block later acknowledgment.
    h.state.initialRevealAnimationRef.current = null;
    h.handleScroll(h.scrollEvent(500));
    expect(h.state.reopeningAnchorRef.current).not.toBeNull();
    h.reconcileReopeningAnchor(); // A correction is already queued before native acknowledgment.
    h.handleScroll(h.scrollEvent(600));
    expect(h.state.reopeningAnchorRef.current).toBeNull();
    h.handleContentSize(400, 2600);
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
  });
  it('keeps revealed history opaque after a delayed native stop value and keyboard rerenders', () => {
    const h = harness();
    const progress = { value: 0 };
    let revealed = false;
    h.initialRevealProgress.setValue.mockImplementation((value: number) => { progress.value = value; });
    h.setListRevealed.mockImplementation((value: boolean) => { revealed = value; });
    h.state.initialRevealAnimationRef.current!.stop = () => {
      setTimeout(() => { progress.value = 0; }, 1);
    };
    expect(renderOpacity(revealed, progress)).toBe(progress);
    h.revealPositionedHistory();
    expect(progress.value).toBe(1);
    expect(renderOpacity(revealed, progress)).toBe(1);
    vi.advanceTimersByTime(1);
    expect(progress.value).toBe(0); // Native completion delivers its old hidden value.
    for (const viewportHeight of [500, 912]) {
      h.state.scrollMetricsRef.current.viewportHeight = viewportHeight;
      h.handleContentSize(400, 2000);
      expect(renderOpacity(revealed, progress)).toBe(1);
    }
    // A task switch resets revealed state and uses a fresh animation value.
    const nextProgress = { value: 0 };
    expect(renderOpacity(false, nextProgress)).toBe(nextProgress);
  });
  it.each(['off', 'on', 'failed'])('preserves reader ownership with Debug recording %s', (recording) => {
    const sink = vi.fn(() => { if (recording === 'failed') throw new Error('storage unavailable'); });
    setMobileDebugSink(recording === 'off' ? undefined : sink);
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1180));
    h.handleScrollEndDrag();
    h.handleContentSize(400, 2500);
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
    expect(sink.mock.calls.length > 0).toBe(recording !== 'off');
  });

  it('reveals positioned history immediately once, cancelling the fallback before opacity changes', () => {
    const h = harness();
    const stop = h.state.initialRevealAnimationRef.current!.stop;
    h.scrollToEndProgrammatically(false);
    vi.advanceTimersByTime(64);
    expect(stop).toHaveBeenCalledTimes(1);
    expect(h.initialRevealProgress.setValue).toHaveBeenCalledExactlyOnceWith(1);
    expect(h.setListRevealed).toHaveBeenCalledExactlyOnceWith(true);
    expect(vi.mocked(stop).mock.invocationCallOrder[0]).toBeLessThan(h.initialRevealProgress.setValue.mock.invocationCallOrder[0]);
    h.handleContentSize(400, 2500);
    vi.advanceTimersByTime(300);
    expect(h.setListRevealed).toHaveBeenCalledTimes(1);
  });

  it('does not reveal a not-yet-started initial history from unrelated layout callbacks', () => {
    const h = harness();
    h.state.initialAnchorDoneRef.current = false;
    h.runStickToLatestVerify();
    vi.advanceTimersByTime(300);
    expect(h.initialRevealProgress.setValue).not.toHaveBeenCalled();
  });
  it.each([1196, 1180].flatMap((offset) => ['missing', 'before-verify', 'after-verify'].map((end) => ({ offset, end }))))(
    'releases a cancelled drag at $offset with end event $end', ({ offset, end }) => {
      const h = harness();
      h.handleHistoryTouchStart(touch());
      h.handleScrollBeginDrag(h.scrollEvent(1200));
      h.handleScroll(h.scrollEvent(end === 'missing' ? offset : 1196));
      h.handleContentSize(400, 2500);
      h.handleHistoryTouchCancel();
      h.handleHistoryTouchCancel();
      if (end === 'after-verify') {
        settle();
        expect(h.tailScroll).toHaveBeenCalledTimes(1);
        h.tailScroll.mockClear();
      }
      if (end !== 'missing') h.handleScrollEndDrag(h.scrollEvent(offset));
      settle();
      expect(h.state.nearBottomRef.current).toBe(offset === 1196);
      expect(h.tailScroll).toHaveBeenCalledTimes(offset === 1196 ? 1 : 0);
      expect(h.state.isDraggingRef.current).toBe(false);
      if (end !== 'missing') expect(h.state.dragStartOffsetYRef.current).toBeNull();
    },
  );

  it('consumes a late final sample even after a no-op cancellation verification', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleHistoryTouchCancel();
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScrollEndDrag(h.scrollEvent(1180));
    h.handleContentSize(400, 2500);
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it('ignores layout corrections after cancel but consumes the final drag sample', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleContentSize(400, 2500);
    h.handleHistoryTouchCancel();
    h.handleScroll(h.scrollEvent(900));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleScrollEndDrag(h.scrollEvent(1180));
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it.each(['end', 'index'])('discards the cancelled drag sample when explicit %s takes over', (target) => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleHistoryTouchCancel();
    if (target === 'end') h.scrollToBottom();
    else h.scrollToIndexProgrammatically(10, 0.45);
    h.handleScrollEndDrag(h.scrollEvent(1180));
    expect(h.state.nearBottomRef.current).toBe(true);
    if (target === 'end') expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: true });
  });

  it('keeps the cancelled drag sample through automatic offset compensation', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleHistoryTouchCancel();
    h.scrollToOffsetProgrammatically(900, false);
    h.handleScroll(h.scrollEvent(900));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleScrollEndDrag(h.scrollEvent(1180));
    expect(h.state.nearBottomRef.current).toBe(false);
  });

  it('can return to the bottom in the final drag sample after cancellation', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1180));
    h.handleHistoryTouchCancel();
    h.handleScrollEndDrag(h.scrollEvent(1200));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleContentSize(400, 2500);
    settle();
    expect(h.tailScroll).toHaveBeenCalledTimes(1);
  });

  it('allows native scrolling to take ownership after Android cancels the JS touch', () => {
    const h = harness();
    h.handleHistoryTouchStart(touch());
    h.handleHistoryTouchCancel();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleContentSize(400, 2500);
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScroll(h.scrollEvent(1180));
    h.handleScrollEndDrag();
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it('waits for independently reported momentum after cancelling a touch', () => {
    const h = harness();
    h.handleHistoryTouchStart(touch());
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleMomentumScrollBegin();
    h.handleHistoryTouchCancel();
    h.handleContentSize(400, 2500);
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleMomentumScrollEnd();
    settle();
    expect(h.tailScroll).toHaveBeenCalledTimes(1);
  });

  it('keeps an active drag when another finger touches the list', () => {
    const h = harness();
    h.handleHistoryTouchStart(touch());
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleHistoryTouchStart(touch());
    h.handleContentSize(400, 2500);
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScroll(h.scrollEvent(1180));
    h.handleHistoryTouchEnd(touch());
    h.handleScrollEndDrag();
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it.each([false, true])('preserves an explicit animated jump when touchEnd precedes onPress: %s', (releaseFirst) => {
    const h = harness();
    h.state.nearBottomRef.current = false;
    h.state.scrollMetricsRef.current.offsetY = 300;
    // Native animation has not landed yet; command dispatch does not acknowledge its offset.
    h.tailScroll.mockImplementation(() => {});
    h.handleHistoryTouchStart(touch());
    if (releaseFirst) h.handleHistoryTouchEnd(touch());
    h.scrollToBottom();
    expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: true });
    if (!releaseFirst) h.handleHistoryTouchEnd(touch());
    h.handleContentSize(400, 2200);
    const remaining = h.state.programmaticScrollSettleAtRef.current - Date.now();
    vi.advanceTimersByTime(remaining - 1);
    // Releasing the button and receiving new content must not truncate the animation.
    expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: true });
    h.handleScroll(h.scrollEvent(1400));
    settle();
    expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: true });
  });

  it('lets a new upward drag interrupt verification after an explicit animated jump', () => {
    const h = harness();
    h.scrollToBottom();
    h.handleHistoryTouchStart(touch());
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1180));
    h.handleContentSize(400, 2200);
    h.handleHistoryTouchEnd(touch(420));
    h.handleScrollEndDrag();
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: true });
  });

  it('allows an upward drag to unpin while content grows before the first scroll event', () => {
    const h = harness();
    h.handleHistoryTouchStart(touch());
    h.handleContentSize(400, 2040);
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleContentSize(400, 2080);
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScroll(h.scrollEvent(1180));
    expect(h.state.nearBottomRef.current).toBe(false);
    h.handleHistoryTouchEnd(touch(420));
    h.handleScrollEndDrag();
    h.handleMomentumScrollBegin();
    h.handleContentSize(400, 2200);
    h.handleMomentumScrollEnd();
    settle();
    h.handleContentSize(400, 2240);
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.scrollToBottom();
    expect(h.tailScroll).toHaveBeenLastCalledWith({ animated: true });
  });

  it.each(['handleHistoryTouchEnd', 'handleHistoryTouchCancel'] as const)(
    'catches up after %s when output ended during a stationary touch', (release) => {
      const h = harness();
      h.handleHistoryTouchStart(touch());
      h.handleContentSize(400, 2300);
      settle();
      expect(h.tailScroll).not.toHaveBeenCalled();
      h[release](touch());
      settle();
      expect(h.tailScroll).toHaveBeenCalledTimes(1);
      expect(h.state.scrollMetricsRef.current.offsetY).toBe(1500);
    },
  );

  it.each([1196, 1194, 1192, 1190])('applies the cumulative drag threshold to a trailing offset of %i after large growth', (trailingOffset) => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleContentSize(400, 2500);
    h.handleScrollEndDrag(h.scrollEvent(trailingOffset));
    // End-drag carries the final offset even when the matching onScroll is delivered later.
    h.handleScroll(h.scrollEvent(trailingOffset));
    expect(h.state.nearBottomRef.current).toBe(trailingOffset >= 1192);
    settle();
    if (trailingOffset < 1192) {
      expect(h.tailScroll).not.toHaveBeenCalled();
      return;
    }
    expect(h.tailScroll).toHaveBeenCalledTimes(1);
    h.handleScroll(h.scrollEvent(1700));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleContentSize(400, 2540);
    expect(h.tailScroll).toHaveBeenCalledTimes(2);
  });

  it.each([false, true])('unpins a trailing drag across momentum-start ordering: %s', (momentumFirst) => {
    const h = harness();
    h.handleHistoryTouchStart(touch());
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleHistoryTouchEnd(touch());
    h.handleScrollEndDrag(h.scrollEvent(1190));
    if (momentumFirst) h.handleMomentumScrollBegin();
    h.handleScroll(h.scrollEvent(1190));
    if (!momentumFirst) h.handleMomentumScrollBegin();
    h.handleMomentumScrollEnd();
    h.handleContentSize(400, 2500);
    settle();
    expect(h.state.nearBottomRef.current).toBe(false);
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it('retires a completed drag after a no-op release verification', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1200));
    h.handleScrollEndDrag();
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScroll(h.scrollEvent(1190));
    h.handleContentSize(400, 2500);
    settle();
    expect(h.state.nearBottomRef.current).toBe(true);
    expect(h.tailScroll).toHaveBeenCalledTimes(1);
  });

  it.each([1180, 900])('preserves a short drag through a post-release layout correction to %i', (offset) => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleContentSize(400, 2500);
    h.handleScrollEndDrag(h.scrollEvent(1196));
    // MVCP may correct the visible anchor before the release verifier runs.
    h.handleScroll(h.scrollEvent(offset));
    expect(h.state.nearBottomRef.current).toBe(true);
    settle();
    expect(h.tailScroll).toHaveBeenCalledExactlyOnceWith({ animated: false });
    expect(h.state.scrollMetricsRef.current.offsetY).toBe(1700);
  });

  it('can unpin again after returning to the bottom within the same drag', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1180));
    expect(h.state.nearBottomRef.current).toBe(false);
    h.handleScroll(h.scrollEvent(1200));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleScroll(h.scrollEvent(1180));
    expect(h.state.nearBottomRef.current).toBe(false);
  });

  it('forgets the previous drag when an explicit command owns native scroll events', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleScrollEndDrag();
    h.scrollToBottom();
    h.handleScroll(h.scrollEvent(1190));
    expect(h.state.nearBottomRef.current).toBe(true);
  });

  it('measures a new drag from its own starting offset', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleScrollEndDrag();
    h.handleHistoryTouchStart(touch());
    h.handleScrollBeginDrag(h.scrollEvent(1196));
    h.handleScroll(h.scrollEvent(1190));
    expect(h.state.nearBottomRef.current).toBe(true);
    h.handleScroll(h.scrollEvent(1186));
    expect(h.state.nearBottomRef.current).toBe(false);
  });

  it('pauses already queued verification and waits for momentum to end before catching up', () => {
    const h = harness();
    h.state.scrollMetricsRef.current.contentHeight = 2200;
    h.runStickToLatestVerify();
    h.handleHistoryTouchStart(touch());
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleHistoryTouchEnd(touch());
    h.handleMomentumScrollBegin();
    h.handleContentSize(400, 2300);
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleMomentumScrollEnd();
    settle();
    expect(h.tailScroll).toHaveBeenCalledTimes(1);
  });

  it('keeps the drag dead zone authoritative when the tail grows beyond the distance threshold', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleContentSize(400, 2500);
    h.handleScroll(h.scrollEvent(1194));
    expect(h.state.nearBottomRef.current).toBe(true);
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleScroll(h.scrollEvent(1190));
    expect(h.state.nearBottomRef.current).toBe(false);
    h.handleScrollEndDrag();
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it('still unpins a real momentum fling after a short drag', () => {
    const h = harness();
    h.handleScrollBeginDrag(h.scrollEvent(1200));
    h.handleScroll(h.scrollEvent(1196));
    h.handleScrollEndDrag();
    h.handleMomentumScrollBegin();
    h.handleScroll(h.scrollEvent(900));
    expect(h.state.nearBottomRef.current).toBe(false);
    h.handleContentSize(400, 2500);
    h.handleMomentumScrollEnd();
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
  });

  it('blocks a previously scheduled circuit recovery while the finger owns the viewport', () => {
    const h = harness();
    vi.spyOn(console, 'warn').mockImplementation(() => {});
    for (let i = 0; i < 12; i++) h.handleContentSize(400, i % 2 ? 2100 : 2200);
    expect(console.warn).toHaveBeenCalledTimes(1);
    h.tailScroll.mockClear();
    h.handleHistoryTouchStart(touch());
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
    h.handleHistoryTouchEnd(touch());
    settle();
    expect(h.state.scrollMetricsRef.current.offsetY).toBe(1300);
  });

  it('does not resume tail follow while a history page owns the anchor', () => {
    const h = harness();
    h.state.readingOlderRef.current = true;
    h.state.nearBottomRef.current = false;
    h.handleHistoryTouchStart(touch());
    h.handleContentSize(400, 2500);
    h.handleHistoryTouchEnd(touch());
    settle();
    expect(h.tailScroll).not.toHaveBeenCalled();
  });
});