This commit is contained in:
151
apps/web/src/hooks/useStreamCadence.test.ts
Normal file
151
apps/web/src/hooks/useStreamCadence.test.ts
Normal file
@@ -0,0 +1,151 @@
|
||||
/**
|
||||
* Pillar 3.1 — render-side streaming cadence buffer.
|
||||
*
|
||||
* Locks the four contract points from the lane spec:
|
||||
* 1. Not-streaming / history text is whole on first paint (no cadence).
|
||||
* 2. Zero added latency: the first chunk's first chars reveal within one rAF,
|
||||
* and a live stream drains fully within ≤1 frame of stream end.
|
||||
* 3. Reduced-motion snaps to full text (REDUCED.streamingCaret = static).
|
||||
* 4. A chunked code-block + list reveals monotonically as an escaped prefix —
|
||||
* no whole-block pop, never chars beyond the accumulated raw.
|
||||
*
|
||||
* rAF is stubbed with a manual queue so the reveal is deterministic frame-by-frame.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
import { renderHook, act, cleanup } from '@testing-library/react';
|
||||
|
||||
const motionMock = vi.hoisted(() => ({ reduce: false }));
|
||||
vi.mock('framer-motion', () => ({ useReducedMotion: () => motionMock.reduce }));
|
||||
|
||||
import { useStreamCadence, MIN_CHARS_PER_FRAME } from './useStreamCadence';
|
||||
|
||||
let rafQueue: Map<number, FrameRequestCallback>;
|
||||
let rafId: number;
|
||||
let vt: number;
|
||||
|
||||
beforeEach(() => {
|
||||
motionMock.reduce = false;
|
||||
rafQueue = new Map();
|
||||
rafId = 0;
|
||||
vt = 0;
|
||||
vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
|
||||
const id = ++rafId;
|
||||
rafQueue.set(id, cb);
|
||||
return id;
|
||||
});
|
||||
vi.stubGlobal('cancelAnimationFrame', (id: number) => {
|
||||
rafQueue.delete(id);
|
||||
});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
cleanup();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
/** Advance `n` animation frames, running each pending callback inside act(). */
|
||||
function flushFrames(n = 1) {
|
||||
for (let i = 0; i < n; i++) {
|
||||
vt += 16;
|
||||
const pending = [...rafQueue.entries()];
|
||||
rafQueue.clear();
|
||||
act(() => {
|
||||
for (const [, cb] of pending) cb(vt);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
describe('useStreamCadence', () => {
|
||||
it('renders settled / history text whole on the first paint (no cadence when not streaming)', () => {
|
||||
const { result } = renderHook(() => useStreamCadence('A finished reply.', false));
|
||||
expect(result.current.shown).toBe('A finished reply.');
|
||||
expect(result.current.caretVisible).toBe(false);
|
||||
});
|
||||
|
||||
it('shows the first chars within a single rAF — zero buffering before first paint', () => {
|
||||
const { result } = renderHook(() => useStreamCadence('Hello', true));
|
||||
// Nothing buffered on mount; the reveal begins on the first frame, not before.
|
||||
expect(result.current.shown).toBe('');
|
||||
expect(result.current.caretVisible).toBe(false);
|
||||
flushFrames(1);
|
||||
expect(result.current.shown.length).toBeGreaterThanOrEqual(MIN_CHARS_PER_FRAME);
|
||||
expect('Hello'.startsWith(result.current.shown)).toBe(true);
|
||||
expect(result.current.caretVisible).toBe(true);
|
||||
});
|
||||
|
||||
it('reduced-motion snaps to full text with a (static) caret while streaming', () => {
|
||||
motionMock.reduce = true;
|
||||
const { result } = renderHook(() => useStreamCadence('Reduced stream', true));
|
||||
// No frame flush needed — reduced motion reveals everything at once.
|
||||
expect(result.current.shown).toBe('Reduced stream');
|
||||
expect(result.current.caretVisible).toBe(true);
|
||||
});
|
||||
|
||||
it('backlog scales the per-frame reveal so a whole-block dump accretes (never pops)', () => {
|
||||
const dump = 'x'.repeat(600); // an echo-provider whole-block arrival
|
||||
const { result } = renderHook(() => useStreamCadence(dump, true));
|
||||
flushFrames(1);
|
||||
const afterOne = result.current.shown.length;
|
||||
// First frame reveals far more than the per-char floor (backlog / CATCHUP),
|
||||
// yet never the whole block at once — a smooth accretion, not a pop.
|
||||
expect(afterOne).toBeGreaterThan(MIN_CHARS_PER_FRAME);
|
||||
expect(afterOne).toBeLessThan(dump.length);
|
||||
});
|
||||
|
||||
it('reveals a chunked code block + list monotonically as an escaped prefix', () => {
|
||||
const chunks = [
|
||||
'Here is a snippet:\n',
|
||||
'```\nconst x = 1;\n',
|
||||
'console.log(x);\n```\n',
|
||||
'- first item\n',
|
||||
'- second item',
|
||||
];
|
||||
let acc = '';
|
||||
const { result, rerender } = renderHook(
|
||||
({ r, s }: { r: string; s: boolean }) => useStreamCadence(r, s),
|
||||
{ initialProps: { r: '', s: true } },
|
||||
);
|
||||
const lengths: number[] = [result.current.shown.length];
|
||||
for (const c of chunks) {
|
||||
acc += c;
|
||||
rerender({ r: acc, s: true });
|
||||
for (let f = 0; f < 8; f++) {
|
||||
flushFrames(1);
|
||||
// `shown` is always a prefix of the accumulated raw — the cadence never
|
||||
// reveals unbuffered chars, so partial markdown can only form as text.
|
||||
expect(acc.startsWith(result.current.shown)).toBe(true);
|
||||
lengths.push(result.current.shown.length);
|
||||
}
|
||||
}
|
||||
for (let i = 1; i < lengths.length; i++) {
|
||||
expect(lengths[i]).toBeGreaterThanOrEqual(lengths[i - 1]);
|
||||
}
|
||||
// Stream end snaps to the whole text within ≤1 frame; caret clears.
|
||||
rerender({ r: acc, s: false });
|
||||
expect(result.current.shown).toBe(acc);
|
||||
expect(result.current.caretVisible).toBe(false);
|
||||
});
|
||||
|
||||
it('drains to the whole text within ≤1 frame of stream end', () => {
|
||||
const full = 'partial reveal that is still in progress here';
|
||||
const { result, rerender } = renderHook(
|
||||
({ r, s }: { r: string; s: boolean }) => useStreamCadence(r, s),
|
||||
{ initialProps: { r: full, s: true } },
|
||||
);
|
||||
flushFrames(1); // only a small prefix revealed so far
|
||||
expect(result.current.shown.length).toBeLessThan(full.length);
|
||||
rerender({ r: full, s: false }); // stream ends
|
||||
expect(result.current.shown).toBe(full);
|
||||
});
|
||||
|
||||
it('never reveals past a shrunk target (defensive prefix clamp on reset)', () => {
|
||||
const { result, rerender } = renderHook(
|
||||
({ r, s }: { r: string; s: boolean }) => useStreamCadence(r, s),
|
||||
{ initialProps: { r: 'a long streaming string here', s: true } },
|
||||
);
|
||||
flushFrames(30); // caught up to the long target
|
||||
rerender({ r: 'short', s: true }); // target shrank underneath us
|
||||
expect(result.current.shown.length).toBeLessThanOrEqual('short'.length);
|
||||
expect('short'.startsWith(result.current.shown)).toBe(true);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user