Files
waggle-os/apps/web/src/hooks/useStreamCadence.test.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

152 lines
5.9 KiB
TypeScript

/**
* 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);
});
});