test(examples/chat): stage pin specs step a stubbed animation frame instead of racing the real one

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: blove

examples/chat/angular/src/app/stage/stage-mode.component.spec.ts

@@ -36,57 +36,119 @@ describe('StageMode', () => {
     expect(window.__stageApplied?.t).toBe(25);
   });
 
-  /** The chat's scroll container, with jsdom's zero layout replaced by a tall transcript. */
-  async function bootWithScroller(): Promise<HTMLElement> {
-    // The chat shows its welcome screen until a message lands, so the scroll
-    // container only exists once the first run has been applied.
-    await fx.componentInstance.boot(new URLSearchParams('t=0'));
-    fx.detectChanges();
-    const scroller = (fx.nativeElement as HTMLElement).querySelector<HTMLElement>('chat .chat-scroll');
-    if (!scroller) throw new Error('chat .chat-scroll did not render');
-    // jsdom lays nothing out: stand in for a transcript taller than its box.
-    Object.defineProperty(scroller, 'scrollHeight', { configurable: true, writable: true, value: 2400 });
-    Object.defineProperty(scroller, 'scrollTop', { configurable: true, writable: true, value: 0 });
-    return scroller;
-  }
+  describe('transcript pin', () => {
+    // The pin is a pair of animation frames; the real ~16ms frame races the
+    // controller's macrotask timing, so these specs step a stubbed frame
+    // queue by hand and control exactly where each publish lands.
+    type Frame = { id: number; cb: FrameRequestCallback };
+    let queue: Frame[] = [];
+    let cancelled: number[] = [];
+    let nextId = 0;
+    const realRaf = globalThis.requestAnimationFrame;
+    const realCaf = globalThis.cancelAnimationFrame;
+    const realWindowRaf = window.requestAnimationFrame;
+    const realWindowCaf = window.cancelAnimationFrame;
+
+    beforeEach(() => {
+      queue = [];
+      cancelled = [];
+      nextId = 0;
+      const raf = (cb: FrameRequestCallback): number => {
+        const id = ++nextId;
+        queue.push({ id, cb });
+        return id;
+      };
+      const caf = (id: number): void => {
+        cancelled.push(id);
+        queue = queue.filter((f) => f.id !== id);
+      };
+      globalThis.requestAnimationFrame = raf;
+      globalThis.cancelAnimationFrame = caf;
+      window.requestAnimationFrame = raf;
+      window.cancelAnimationFrame = caf;
+    });
 
-  const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+    afterEach(() => {
+      globalThis.requestAnimationFrame = realRaf;
+      globalThis.cancelAnimationFrame = realCaf;
+      window.requestAnimationFrame = realWindowRaf;
+      window.cancelAnimationFrame = realWindowCaf;
+    });
 
-  /** Polls frame by frame so the test pins the BEHAVIOR, not how many frames deep it lands. */
-  async function pinnedWithin(scroller: HTMLElement, frames: number): Promise<boolean> {
-    for (let i = 0; i < frames; i++) {
-      if (scroller.scrollTop === scroller.scrollHeight) return true;
-      await frame();
+    /** Runs exactly the callbacks queued at the time of the call, in order. */
+    function step(): void {
+      const batch = queue;
+      queue = [];
+      for (const { cb } of batch) cb(performance.now());
     }
-    return scroller.scrollTop === scroller.scrollHeight;
-  }
 
-  it('pins the transcript to its newest content once a seek settles', async () => {
-    const scroller = await bootWithScroller();
-    await fx.componentInstance.controller()?.seek(25);
-    fx.detectChanges();
-    expect(await pinnedWithin(scroller, 6)).toBe(true);
-    expect(scroller.scrollTop).toBe(2400);
-  });
+    /** Steps until nothing is queued: settles whatever boot scheduled. */
+    function flush(): void {
+      for (let i = 0; i < 20 && queue.length > 0; i++) step();
+      if (queue.length > 0) throw new Error('animation frames never settled');
+    }
 
-  it('re-arms one more pin when a publish lands while a pair is in flight', async () => {
-    const scroller = await bootWithScroller();
-    const c = fx.componentInstance.controller();
-    if (!c) throw new Error('no controller');
-    // The first publish schedules the pair; the second lands while that pair
-    // is still in flight, so it must re-arm one more pair rather than be dropped.
-    await c.seek(25);
-    fx.detectChanges();
-    await c.seek(30);
-    fx.detectChanges();
-    // The content that grows AFTER the first pair's inner frame: the two-frame
-    // pair alone would pin at 2400 and leave the new 1200px below the fold.
-    await frame();
-    await frame();
-    expect(scroller.scrollTop).toBe(2400);
-    Object.defineProperty(scroller, 'scrollHeight', { configurable: true, writable: true, value: 3600 });
-    expect(await pinnedWithin(scroller, 6)).toBe(true);
-    expect(scroller.scrollTop).toBe(3600);
+    /** The chat's scroll container, with jsdom's zero layout replaced by a tall transcript. */
+    async function bootWithScroller(): Promise<HTMLElement> {
+      // The chat shows its welcome screen until a message lands, so the scroll
+      // container only exists once the first run has been applied.
+      await fx.componentInstance.boot(new URLSearchParams('t=0'));
+      fx.detectChanges();
+      // Boot publishes too: drain its pair so each spec starts with no pin in flight.
+      flush();
+      const scroller = (fx.nativeElement as HTMLElement).querySelector<HTMLElement>('chat .chat-scroll');
+      if (!scroller) throw new Error('chat .chat-scroll did not render');
+      // jsdom lays nothing out: stand in for a transcript taller than its box.
+      Object.defineProperty(scroller, 'scrollHeight', { configurable: true, writable: true, value: 2400 });
+      Object.defineProperty(scroller, 'scrollTop', { configurable: true, writable: true, value: 0 });
+      return scroller;
+    }
+
+    /** Applies a seek and lets its publish schedule (or re-arm) the pin; no frame runs. */
+    async function publishAt(t: number): Promise<void> {
+      const c = fx.componentInstance.controller();
+      if (!c) throw new Error('no controller');
+      await c.seek(t);
+      fx.detectChanges();
+    }
+
+    it('pins the transcript to its newest content once a seek settles', async () => {
+      const scroller = await bootWithScroller();
+      await publishAt(25);
+      expect(queue.length).toBeGreaterThan(0);
+      step(); // outer frame: views render
+      expect(scroller.scrollTop).toBe(0);
+      step(); // inner frame: layout settled, the write lands
+      expect(scroller.scrollTop).toBe(2400);
+    });
+
+    it('re-arms one more pin when a publish lands while a pair is in flight', async () => {
+      const scroller = await bootWithScroller();
+      await publishAt(25); // schedules the pair
+      step(); // outer frame fires: the pair now owns everything before it
+      await publishAt(30); // lands between outer and inner: must re-arm
+      step(); // inner frame: writes the current height, then re-arms
+      expect(scroller.scrollTop).toBe(2400);
+      // Content that grows AFTER the first pair's inner frame: without the
+      // re-arm nothing is queued and the new 1200px stay below the fold.
+      Object.defineProperty(scroller, 'scrollHeight', { configurable: true, writable: true, value: 3600 });
+      expect(queue.length).toBeGreaterThan(0);
+      step();
+      step();
+      expect(scroller.scrollTop).toBe(3600);
+    });
+
+    it('cancels an in-flight pin on destroy so no frame writes after teardown', async () => {
+      const scroller = await bootWithScroller();
+      await publishAt(25);
+      const pending = queue.map((f) => f.id);
+      expect(pending.length).toBeGreaterThan(0);
+      fx.destroy();
+      expect(cancelled.some((id) => pending.includes(id))).toBe(true);
+      expect(queue.some((f) => cancelled.includes(f.id))).toBe(false);
+      flush();
+      expect(scroller.scrollTop).toBe(0);
+    });
   });
 
   it('posts ready and state through the bridge', async () => {