fix(stage): make chat scroll exploration explicit

Author: blove

apps/website/e2e/home-stage.spec.ts

@@ -81,8 +81,25 @@ test.describe('homepage stage', () => {
     const y = await page.evaluate(() => scrollY);
     await frame.getByRole('tab', { name: 'State', exact: true }).hover();
     await page.mouse.wheel(0, 150);
-    await expect.poll(() => page.evaluate(() => scrollY)).toBe(y);
+    await expect.poll(() => page.evaluate(() => scrollY)).toBeGreaterThan(y);
+    await expect(act).toHaveAttribute('data-interactive', '', { timeout: 30_000 });
+    await page.getByRole('button', { name: 'Explore chat', exact: true }).click();
+    await expect(act).toHaveAttribute('data-exploring', '');
+    const exploringY = await page.evaluate(() => scrollY);
+    await frame.getByRole('tab', { name: 'State', exact: true }).hover();
+    await page.mouse.wheel(0, 150);
+    await page.waitForTimeout(400);
+    expect(await page.evaluate(() => scrollY)).toBe(exploringY);
+    await frame.getByRole('tab', { name: 'State', exact: true }).click();
+    await page.keyboard.press('Escape');
+    await expect(act).not.toHaveAttribute('data-exploring');
+    await expect(page.getByRole('button', { name: 'Explore chat', exact: true })).toBeFocused();
+    await page.getByRole('button', { name: 'Explore chat', exact: true }).click();
+    await page.getByRole('button', { name: 'Resume walkthrough', exact: true }).click();
+    await expect(act).not.toHaveAttribute('data-exploring');
+    await page.getByRole('button', { name: 'Explore chat', exact: true }).click();
     await scrollAct(page, 1);
+    await expect(act).not.toHaveAttribute('data-exploring');
     await expect(act).toHaveAttribute('data-interactive', '', { timeout: 30_000 });
     await expect(frame.getByRole('tab', { name: 'State', exact: true })).toHaveAttribute('aria-selected', 'true');
     const notes = frame.getByRole('textbox', { name: 'Follow-up notes' });

apps/website/src/components/landing/StageAct.tsx

@@ -177,14 +177,19 @@ export function StageAct({ onFallback }: Props) {
                 />
               </div>
             </BrowserFrame>
-            <a
-              className="stage-frame-open"
-              href={STAGE_DEMO_ORIGIN}
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Open the live demo →
-            </a>
+            <div className="stage-frame-actions">
+              <button type="button" className="stage-explore" data-stage-explore aria-pressed="false" disabled>
+                Explore chat
+              </button>
+              <a
+                className="stage-frame-open"
+                href={STAGE_DEMO_ORIGIN}
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                Open the live demo →
+              </a>
+            </div>
           </div>
           <div className="stage-rail">
             <nav className="stage-checklist" aria-label="Workflow capabilities">

apps/website/src/components/landing/use-stage-publisher.spec.ts

@@ -91,6 +91,38 @@ function fromDemo(data: unknown) {
   );
 }
 
+describe('explicit exploration', () => {
+  it('routes wheel to the page by default and restores it after Escape', () => {
+    let now = 0;
+    const clock = vi.spyOn(performance, 'now').mockImplementation(() => now);
+    const scroll = vi.spyOn(window, 'scrollBy').mockImplementation(() => undefined);
+    const { section, pub, posted } = setup({ rail: s => {
+      s.innerHTML = '<button data-stage-explore aria-pressed="false">Explore chat</button>';
+    } });
+    pub.tick();
+    fromDemo({ type: STAGE_MESSAGE_TYPE, applied: 0, phase: 'stream', t: 0, settled: true });
+    now = 300;
+    pub.tick();
+    fromDemo({ type: STAGE_MESSAGE_TYPE, wheel: { deltaX: 0, deltaY: 80 } });
+    expect(scroll).toHaveBeenCalledWith({ left: 0, top: 80, behavior: 'instant' });
+    now = 600;
+    pub.tick();
+    const button = section.querySelector('button')!;
+    button.click();
+    expect(button.textContent).toBe('Resume walkthrough');
+    expect(posted.at(-1)?.m).toEqual({ type: STAGE_MESSAGE_TYPE, explore: true });
+    fromDemo({ type: STAGE_MESSAGE_TYPE, wheel: { deltaX: 0, deltaY: 80 } });
+    expect(scroll).toHaveBeenCalledTimes(1);
+    fromDemo({ type: STAGE_MESSAGE_TYPE, explore: false });
+    expect(button.textContent).toBe('Explore chat');
+    button.click();
+    window.dispatchEvent(new Event('scroll'));
+    expect(section.hasAttribute('data-exploring')).toBe(false);
+    clock.mockRestore();
+    scroll.mockRestore();
+  });
+});
+
 function setup(
   opts: {
     frameWindow?: () => Window | null;

apps/website/src/components/landing/use-stage-publisher.ts

@@ -114,14 +114,39 @@ export function createStagePublisher(deps: StagePublisherDeps): StagePublisher {
   let lastMovement = performance.now();
   let appliedT = -1;
   const iframe = deps.section.querySelector<HTMLIFrameElement>('.stage-frame-iframe');
+  const exploreButton = deps.section.querySelector<HTMLButtonElement>('[data-stage-explore]');
+  let exploring = false;
+  const setExploring = (value: boolean) => {
+    if (exploring === value) return;
+    exploring = value;
+    deps.section.toggleAttribute('data-exploring', value);
+    if (exploreButton) {
+      exploreButton.textContent = value ? 'Resume walkthrough' : 'Explore chat';
+      exploreButton.setAttribute('aria-pressed', String(value));
+    }
+    deps.frameWindow()?.postMessage({ type: STAGE_MESSAGE_TYPE, explore: value }, STAGE_DEMO_ORIGIN);
+  };
+  const toggleExploring = () => {
+    if (deps.section.hasAttribute('data-interactive')) setExploring(!exploring);
+  };
+  const onKey = (event: KeyboardEvent) => {
+    if (event.key === 'Escape' && exploring) {
+      setExploring(false);
+      exploreButton?.focus({ preventScroll: true });
+    }
+  };
+  exploreButton?.addEventListener('click', toggleExploring);
+  window.addEventListener('keydown', onKey);
   const setInteractive = (enabled: boolean) => {
     deps.section.toggleAttribute('data-interactive', enabled);
+    if (exploreButton) exploreButton.disabled = !enabled;
     if (iframe) {
       iframe.toggleAttribute('inert', !enabled);
       iframe.tabIndex = enabled ? 0 : -1;
     }
   };
   const onScroll = () => {
+    setExploring(false);
     lastMovement = performance.now();
     setInteractive(false);
   };
@@ -148,6 +173,22 @@ export function createStagePublisher(deps: StagePublisherDeps): StagePublisher {
       return;
     const d = e.data as Record<string, unknown> | null;
     if (!d || typeof d !== 'object' || d['type'] !== STAGE_MESSAGE_TYPE) return;
+    if (d['explore'] === false) {
+      setExploring(false);
+      exploreButton?.focus({ preventScroll: true });
+      return;
+    }
+    const wheel = d['wheel'] as { deltaX?: unknown; deltaY?: unknown } | undefined;
+    if (ready && !exploring && wheel && isFiniteNumber(wheel.deltaX) && isFiniteNumber(wheel.deltaY)) {
+      onScroll();
+      const limit = window.innerHeight * 2;
+      window.scrollBy({
+        left: Math.max(-limit, Math.min(limit, wheel.deltaX)),
+        top: Math.max(-limit, Math.min(limit, wheel.deltaY)),
+        behavior: 'instant',
+      });
+      return;
+    }
     if (d['ready'] === true) {
       if (!isReady(d)) return;
       const first = ready === null;
@@ -249,6 +290,9 @@ export function createStagePublisher(deps: StagePublisherDeps): StagePublisher {
     },
     dispose() {
       disposed = true;
+      setExploring(false);
+      exploreButton?.removeEventListener('click', toggleExploring);
+      window.removeEventListener('keydown', onKey);
       window.removeEventListener('message', onMessage);
       window.removeEventListener('scroll', onScroll);
       setInteractive(false);

apps/website/src/styles/landing.css

@@ -1106,6 +1106,11 @@
   font-size: 13px;
   justify-self: end;
 }
+.stage-frame-actions { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.stage-explore { font: inherit; font-size: 13px; color: inherit; background: transparent; border: 1px solid #b8b8b8; border-radius: 6px; padding: 3px 10px; cursor: pointer; }
+.stage-explore:disabled { opacity: .45; cursor: default; }
+.stage-explore[aria-pressed='true'] { background: #eef3ff; border-color: #7289b9; }
+.stage-explore:focus-visible { outline: 2px solid #3963a8; outline-offset: 3px; }
 /* Persistent capability checklist; only the hold cue and final CTA fade. */
 .stage-rail {
   display: grid;

examples/chat/angular/src/app/stage/stage-bridge.ts

@@ -21,6 +21,9 @@ export interface StageState {
 
 export interface StageBridge {
   onSeek(cb: (t: number) => void): () => void;
+  onExplore(cb: (explore: boolean) => void): () => void;
+  postExplore(explore: boolean): void;
+  postWheel(deltaX: number, deltaY: number): boolean;
   postReady(ready: StageReady): void;
   postState(state: StageState): void;
 }
@@ -54,10 +57,22 @@ export function createStageBridge(env: BridgeEnv): StageBridge {
   // arrived with an empty referrer still receives the handshake.
   let lastReady: Record<string, unknown> | null = null;
   const post = (msg: Record<string, unknown>) => {
-    if (!embedded || parentOrigin === null) return;
+    if (!embedded || parentOrigin === null) return false;
     env.parent.postMessage({ type: STAGE_MESSAGE_TYPE, ...msg }, parentOrigin);
+    return true;
   };
   return {
+    onExplore(cb) {
+      const handler = (e: MessageEvent) => {
+        if (e.source !== env.parent || !isAllowedParentOrigin(e.origin)) return;
+        const d = e.data;
+        if (d?.type === STAGE_MESSAGE_TYPE && typeof d.explore === 'boolean') cb(d.explore);
+      };
+      env.self.addEventListener('message', handler);
+      return () => env.self.removeEventListener('message', handler);
+    },
+    postExplore(explore) { post({ explore }); },
+    postWheel(deltaX, deltaY) { return post({ wheel: { deltaX, deltaY } }); },
     onSeek(cb) {
       const handler = (e: MessageEvent) => {
         if (e.source !== env.parent) return;

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

@@ -158,6 +158,9 @@ describe('StageMode', () => {
       onSeek: () => () => undefined,
       postReady: (r) => posted.push(r),
       postState: (s) => posted.push(s),
+      onExplore: () => () => undefined,
+      postExplore: () => undefined,
+      postWheel: () => false,
     };
     await fx.componentInstance.boot(new URLSearchParams('t=0'));
     fx.detectChanges();

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

@@ -22,6 +22,7 @@ import {
 } from '@threadplane/chat';
 import { ChatDebugComponent } from '@threadplane/chat/debug';
 import { stagePresentationAgent } from './stage-interaction';
+import { stageWheelOwnership } from './stage-wheel';
 import {
   FetchStreamTransport,
   injectAgent,
@@ -273,6 +274,7 @@ export class StageMode {
     ? this.agent
     : stagePresentationAgent(this.agent, () => this.openLiveDemo());
   protected readonly debugOpen = signal(true);
+  private exploring = false;
   protected readonly inspectionDock = signal<'left' | 'right' | 'bottom' | null>(null);
 
   protected openLiveDemo(): void {
@@ -307,7 +309,14 @@ export class StageMode {
   /** TEST SEAM. Replaced by the spec; browser bridge by default. */
   bridge: StageBridge =
     typeof window === 'undefined'
-      ? { onSeek: () => () => undefined, postReady: () => undefined, postState: () => undefined }
+      ? {
+          onSeek: () => () => undefined,
+          onExplore: () => () => undefined,
+          postReady: () => undefined,
+          postState: () => undefined,
+          postExplore: () => undefined,
+          postWheel: () => false,
+        }
       : browserStageBridge();
 
   private lastPosted = '';
@@ -320,6 +329,12 @@ export class StageMode {
 
   constructor() {
     this.watchDock();
+    if (!this.recording && typeof window !== 'undefined') {
+      this.destroyRef.onDestroy(this.bridge.onExplore((value) => { this.exploring = value; }));
+      this.destroyRef.onDestroy(stageWheelOwnership(window, () => this.exploring,
+        (x, y) => this.bridge.postWheel(x, y),
+        () => { this.exploring = false; this.bridge.postExplore(false); }));
+    }
     this.destroyRef.onDestroy(() => {
       if (typeof cancelAnimationFrame === 'function') {
         if (this.seekFrame !== null) cancelAnimationFrame(this.seekFrame);

examples/chat/angular/src/app/stage/stage-wheel.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+import { stageWheelOwnership } from './stage-wheel';
+
+describe('stage wheel ownership', () => {
+  it('forwards wheel units to the page until exploration is explicitly enabled', () => {
+    let exploring = false;
+    const forward = vi.fn(() => true);
+    const stop = stageWheelOwnership(window, () => exploring, forward, vi.fn());
+    const wheel = new WheelEvent('wheel', { deltaY: 3, deltaMode: 1, cancelable: true });
+    window.dispatchEvent(wheel);
+    expect(forward).toHaveBeenCalledWith(0, 48);
+    expect(wheel.defaultPrevented).toBe(true);
+    exploring = true;
+    const local = new WheelEvent('wheel', { deltaY: 80, cancelable: true });
+    window.dispatchEvent(local);
+    expect(local.defaultPrevented).toBe(false);
+    expect(forward).toHaveBeenCalledTimes(1);
+    stop();
+  });
+
+  it('preserves pinch zoom and standalone scrolling; Escape exits exploration', () => {
+    const forward = vi.fn(() => false);
+    const resume = vi.fn();
+    let exploring = false;
+    const stop = stageWheelOwnership(window, () => exploring, forward, resume);
+    const zoom = new WheelEvent('wheel', { deltaY: 50, ctrlKey: true, cancelable: true });
+    window.dispatchEvent(zoom);
+    expect(forward).not.toHaveBeenCalled();
+    const standalone = new WheelEvent('wheel', { deltaY: 50, cancelable: true });
+    window.dispatchEvent(standalone);
+    expect(standalone.defaultPrevented).toBe(false);
+    exploring = true;
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+    expect(resume).toHaveBeenCalledOnce();
+    stop();
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+    expect(resume).toHaveBeenCalledOnce();
+  });
+});

examples/chat/angular/src/app/stage/stage-wheel.ts

@@ -0,0 +1,26 @@
+/** Wheel ownership is explicit; a pause only unlocks clicks, not local scrolling. */
+export function stageWheelOwnership(
+  host: Window,
+  exploring: () => boolean,
+  forward: (deltaX: number, deltaY: number) => boolean,
+  resume: () => void,
+): () => void {
+  const wheel = (event: WheelEvent) => {
+    if (exploring() || event.ctrlKey || !event.cancelable) return;
+    const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? host.innerHeight : 1;
+    if (forward(event.deltaX * unit, event.deltaY * unit)) event.preventDefault();
+  };
+  const key = (event: KeyboardEvent) => {
+    if (event.key === 'Escape' && exploring()) {
+      resume();
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  };
+  host.addEventListener('wheel', wheel, { capture: true, passive: false });
+  host.addEventListener('keydown', key, true);
+  return () => {
+    host.removeEventListener('wheel', wheel, true);
+    host.removeEventListener('keydown', key, true);
+  };
+}