fix(examples/chat): stage pin re-arms, stills look beats up by name, e2e guards the pinned viewport

The transcript pin scheduled one two-frame pair per seek and dropped any
publish that landed while that pair was in flight, so content rendering
after the pending pair's inner frame could stay below the fold. pinTranscript
now keeps one pair in flight at a time and a publish during the pair re-arms
exactly one more pair after it (pinPending). The destroy hook still cancels
whichever frame is pending and clears the flag, so nothing runs after
destroy. The docblock now also states that this deliberately overrides the
chat's unpin-on-user-scroll for a scrubbed display surface.

The pin still reaches into the chat's private .chat-scroll container. The
proper fix is a public scrollToBottom() on ChatComponent (today the
protected onScrollBubbleClick); that touches libs/ and is deferred, recorded
as a TODO at the call site.

The unit spec polls frame by frame instead of hard-coding "two frames deep",
and gains a re-arm case whose scrollHeight grows after the first pair's inner
frame. Mutation-checked: removing the re-arm fails only the new case;
removing the publish() call fails both.

The still recorder looks beats up by name (StageBeat) rather than by index,
collects oversized files and asserts once after both loops so a failure
cannot leave a half-rewritten set, and its header says deviceScaleFactor 2
applies to both sizes. stage.spec.ts asserts the interrupt panel and the
A2UI surface are in the viewport, guarding the pin end to end, and explains
the +1 on the hold boundary. The shared window augmentation moves to
e2e/stage-globals.d.ts.

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

Author: blove

apps/website/public/screenshots/stage-persist.webp

@@ -14,24 +14,17 @@
  * the devtools docked right. Below 768px the stage renders NO devtools (see
  * `readStageDock` — the phone path is chat only, a docked panel would eat the
  * transcript), so the phone still is the chat at 390x650 (3:5, the phone
- * ratio the hero poster uses), captured at deviceScaleFactor 2 so the shipped
- * 585-wide file is a crisp downscale rather than a 1.5x upscale of a 390px
- * raster.
+ * ratio the hero poster uses). `deviceScaleFactor: 2` applies to BOTH sizes:
+ * the desktop still is a 2400-wide raster downscaled to 1200, and the phone
+ * still a 780-wide raster downscaled to 585 — crisp downscales rather than a
+ * 1x raster shipped as-is or a 1.5x upscale of a 390px one.
  */
 import { expect, test } from '@playwright/test';
 import { resolve } from 'node:path';
 import sharp from 'sharp';
-import type { StageState } from '../src/app/stage/stage-bridge';
+import type { StageBeat } from '../src/app/stage/stage-recording.types';
 import type { StageTimeline } from '../src/app/stage/stage-timeline';
 
-// Mirrors the augmentation in stage-mode.component.ts, which the e2e tsconfig does not pull in.
-declare global {
-  interface Window {
-    __stageTimeline?: StageTimeline;
-    __stageApplied?: StageState;
-  }
-}
-
 const OUT_DIR = resolve(__dirname, '../../../../apps/website/public/screenshots');
 const SIZES = [
   { suffix: '', width: 1200, height: 720, ship: 1200 },
@@ -46,12 +39,20 @@ test('capture stage stills', async ({ page }) => {
   await page.goto('/stage?t=0');
   await page.waitForFunction(() => !!window.__stageTimeline);
   const tl = await page.evaluate(() => window.__stageTimeline as StageTimeline);
+  const endOf = (b: StageBeat) => {
+    const hit = tl.beats.find((x) => x.beat === b);
+    if (!hit) throw new Error(`recording has no "${b}" beat`);
+    return hit.endMs;
+  };
   const settle: Record<string, number> = {
-    stream: tl.beats[0].endMs,
-    persist: tl.beats[1].endMs,
+    stream: endOf('stream'),
+    persist: endOf('persist'),
     approve: tl.hold.startMs + Math.round((tl.hold.endMs - tl.hold.startMs) / 2),
     render: tl.totalMs,
   };
+  // Collected, not asserted per file: a throw mid-loop would leave the set
+  // half rewritten. Every offender is listed once after both loops.
+  const oversized: string[] = [];
   for (const size of SIZES) {
     await page.setViewportSize({ width: size.width, height: size.height });
     for (const [beat, t] of Object.entries(settle)) {
@@ -75,8 +76,9 @@ test('capture stage stills', async ({ page }) => {
         .resize({ width: size.ship })
         .webp({ quality: 60, effort: 6 })
         .toFile(out);
-      expect(info.size, `${out} exceeds ${MAX_BYTES} bytes`).toBeLessThanOrEqual(MAX_BYTES);
+      if (info.size > MAX_BYTES) oversized.push(`${out} (${info.size} bytes)`);
       console.log(`wrote ${out} (${Math.round(info.size / 1024)} KB)`);
     }
   }
+  expect(oversized, `stills over ${MAX_BYTES} bytes:\n${oversized.join('\n')}`).toEqual([]);
 });

examples/chat/angular/e2e/record-stage-stills.record.ts

@@ -0,0 +1,11 @@
+import type { StageState } from '../src/app/stage/stage-bridge';
+import type { StageTimeline } from '../src/app/stage/stage-timeline';
+
+// Mirrors the augmentation in stage-mode.component.ts: the e2e tsconfig does
+// not compile src/, so the stage specs and the still recorder share this copy.
+declare global {
+  interface Window {
+    __stageTimeline?: StageTimeline;
+    __stageApplied?: StageState;
+  }
+}

examples/chat/angular/e2e/stage-globals.d.ts

@@ -1,16 +1,7 @@
 import { test, expect, type Page } from '@playwright/test';
 import { attachBrowserHygiene } from './test-helpers';
-import type { StageState } from '../src/app/stage/stage-bridge';
 import type { StageTimeline } from '../src/app/stage/stage-timeline';
 
-// Mirrors the augmentation in stage-mode.component.ts, which the e2e tsconfig does not pull in.
-declare global {
-  interface Window {
-    __stageTimeline?: StageTimeline;
-    __stageApplied?: StageState;
-  }
-}
-
 /**
  * The /stage route replays the committed `public/stage-replay.json` beside the
  * real devtools, seekable by `?t=<ms>`. The page publishes its timeline on
@@ -33,8 +24,12 @@ test.describe('stage replay', () => {
     const hygiene = attachBrowserHygiene(page);
     const tl = await timeline(page);
     await expect(page.getByRole('region', { name: 'Chat devtools' })).toBeVisible();
+    // +1: strictly inside the hold. The boundary instant still belongs to the
+    // outgoing run (phaseReachedAt in stage-timeline.ts renders t minus an epsilon).
     await page.goto(`/stage?t=${tl.hold.startMs + 1}`);
     await expect(page.locator('chat-interrupt-panel')).toBeAttached({ timeout: 60_000 });
+    // Guards the transcript pin: the panel and the newest content sit in view.
+    await expect(page.locator('chat-interrupt-panel')).toBeInViewport({ timeout: 60_000 });
     // The pause comes from delete_backups, after list_backups has rendered its
     // registered tool view — the inventory the visitor is being asked about.
     await expect(page.locator('app-backup-table [data-state="rows"]')).toBeAttached();
@@ -55,6 +50,8 @@ test.describe('stage replay', () => {
     const tl = await timeline(page);
     await page.goto(`/stage?t=${tl.totalMs}`);
     await expect(page.locator('a2ui-surface').first()).toBeAttached({ timeout: 90_000 });
+    // Guards the transcript pin: the generated form is the newest content.
+    await expect(page.locator('a2ui-surface').first()).toBeInViewport({ timeout: 90_000 });
     await expect(page.locator('chat-interrupt-panel')).toHaveCount(0);
     await page.getByRole('tab', { name: 'Timeline' }).click();
     await expect(page.getByRole('region', { name: 'Chat devtools' })).toContainText(/checkpoint/i);

examples/chat/angular/e2e/stage.spec.ts

@@ -36,20 +36,57 @@ describe('StageMode', () => {
     expect(window.__stageApplied?.t).toBe(25);
   });
 
-  it('pins the transcript to its newest content once a seek settles', async () => {
+  /** 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');
-    expect(scroller).toBeTruthy();
+    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, value: 2400 });
+    Object.defineProperty(scroller, 'scrollHeight', { configurable: true, writable: true, value: 2400 });
     Object.defineProperty(scroller, 'scrollTop', { configurable: true, writable: true, value: 0 });
+    return scroller;
+  }
+
+  const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+
+  /** 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();
+    }
+    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();
-    await new Promise<void>((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
-    expect(scroller?.scrollTop).toBe(2400);
+    expect(await pinnedWithin(scroller, 6)).toBe(true);
+    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();
+    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);
   });
 
   it('posts ready and state through the bridge', async () => {

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

@@ -297,6 +297,8 @@ export class StageMode {
   private seekTarget: number | null = null;
   private seekFrame: number | null = null;
   private pinFrame: number | null = null;
+  /** A publish landed while a pin pair was in flight; one more pair follows it. */
+  private pinPending = false;
 
   constructor() {
     this.watchDock();
@@ -307,6 +309,7 @@ export class StageMode {
       }
       this.seekFrame = null;
       this.pinFrame = null;
+      this.pinPending = false;
     });
     afterNextRender(() => {
       if (StageMode.autoBoot) {
@@ -419,19 +422,43 @@ export class StageMode {
    * (the backup table), the A2UI surface, and the interrupt panel — which sits
    * above the chat and shrinks it — have rendered, and the newest content ends
    * up below the fold: at the hold the transcript sat ~700px above its bottom.
-   * Live token cadence hides the same gap. One frame per seek, last wins; two
-   * frames deep so the views render in the first and layout settles in the
-   * second. `.chat-scroll` is the chat's own scroll container
+   * Live token cadence hides the same gap.
+   *
+   * Scheduling: one pair of frames is in flight at a time — the views render
+   * in the first, layout settles in the second, and the scroll write lands at
+   * the end of the second. A publish that arrives while a pair is in flight
+   * re-arms exactly one more pair after it, so content that renders after
+   * the pending pair's inner frame is still pinned rather than dropped.
+   *
+   * This deliberately overrides the chat's own unpin-on-user-scroll: the
+   * stage is a scrubbed display surface, not a reading surface, so a viewer
+   * who scrolls up is re-pinned on the next applied seek.
+   *
+   * `.chat-scroll` is the chat's own scroll container
    * (libs/chat/.../chat.component.ts, `#scrollContainer`); it exposes no
    * scroll API.
+   * TODO: replace with a public scrollToBottom() on ChatComponent
+   * (libs/chat/src/lib/compositions/chat/chat.component.ts, today protected
+   * onScrollBubbleClick) so this stops depending on the private .chat-scroll
+   * class.
    */
   private pinTranscript(): void {
-    if (typeof requestAnimationFrame !== 'function' || this.pinFrame !== null) return;
+    if (typeof requestAnimationFrame !== 'function') return;
+    if (this.pinFrame !== null) {
+      this.pinPending = true;
+      return;
+    }
     this.pinFrame = requestAnimationFrame(() => {
+      // The pair now owns every publish that arrived before this frame fired.
+      this.pinPending = false;
       this.pinFrame = requestAnimationFrame(() => {
         this.pinFrame = null;
         const el = this.host.nativeElement.querySelector<HTMLElement>('chat .chat-scroll');
         if (el) el.scrollTop = el.scrollHeight;
+        if (this.pinPending) {
+          this.pinPending = false;
+          this.pinTranscript();
+        }
       });
     });
   }