kandev/docs/specs/ui/requirements/transcript-auto-scroll.md

---
status: active
system: ui
created: 2026-07-30
updated: 2026-09-07
owners:
  - cfl
---

# Transcript Auto-scroll Stability Requirements

## Overview

Users expect an enabled transcript to follow the newest message, including when
they activate a long-running session tab that was mounted outside the visible
Dockview layout or return to a task whose environment rebuilds that layout.
When cached history is already available, task entry must not expose the
browser's default top position while a latest-window refresh is pending.
Users who turn off transcript auto-scroll expect the visible conversation to
stay fixed while new content arrives and to reopen at that session's own saved
position. Chrome can still adjust the view through its native overflow
anchoring when the toggle is disabled from the bottom. Separately, the
clarification-recovery regression test must reliably observe the asynchronous
hand-off it is designed to protect.

## Requirements

### REQ-UI-TRANSCRIPT-AUTO-SCROLL-001: Transcript Auto-scroll Stability

**Intent:** Users who turn off transcript auto-scroll expect the visible conversation to stay fixed while new content arrives. Chrome can still adjust the view through its native overflow anchoring when the toggle is disabled from the bottom. Separately, the clarification-recovery regression test must reliably observe the asynchronous hand-off it is designed to protect.

#### Acceptance criteria

- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.1:** A disabled native transcript auto-scroll preference prevents browser scroll anchoring from moving the transcript when appended content arrives, including when the user disabled it while already at the bottom.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.2:** Re-enabling auto-scroll retains the existing catch-up behavior.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.3:** The clarification-recovery concurrency regression waits for its asynchronous completion signal within a bounded interval instead of treating scheduler timing as a product failure.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.4:** **GIVEN** an overflowing native transcript at its bottom with auto-scroll disabled, **WHEN** a new message is appended, **THEN** the transcript's `scrollTop` remains at the pre-append position.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.5:** **GIVEN** an overflowing native transcript with auto-scroll enabled, **WHEN** new content arrives, **THEN** the transcript follows the bottom. With chat motion enabled, bounded settling follows [chat motion](chat-motion.md); otherwise pinning is immediate.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.6:** **GIVEN** clarification recovery has accepted its retry prompt, **WHEN** its asynchronous dispatch is scheduled, **THEN** the recovery call completes before the intentionally blocked prompt is released.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.7:** **GIVEN** an enabled transcript that is
  pinned to the bottom, **WHEN** streamed content commits, **THEN** the
  transcript retains bottom-follow intent without a synchronous content-size
  read in the message-commit path. Enabled chat motion uses the bounded settling
  contract in [chat motion](chat-motion.md).
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.8:** **GIVEN** an enabled, overflowing
  transcript that was mounted while its desktop session tab was inactive,
  **WHEN** the user activates that tab after initial load or page refresh,
  **THEN** the visible transcript settles at its newest message.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.9:** **GIVEN** an enabled transcript that
  was following the newest message before its desktop session tab became
  inactive, **WHEN** content arrives while the tab is inactive and the user
  activates it again, **THEN** the transcript catches up to the newest message.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.10:** **GIVEN** a transcript whose
  auto-scroll preference is disabled or whose reader moved away from the newest
  message, **WHEN** its desktop session tab becomes inactive and visible again,
  **THEN** the transcript preserves the reader-owned position instead of
  forcing the newest message into view.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.11:** **GIVEN** an enabled transcript for
  a task in a different environment, **WHEN** the user switches to that task
  and its message history finishes loading, **THEN** the transcript settles at
  its newest message.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.12:** **GIVEN** a disabled transcript for
  a task in a different environment with a saved reader position, **WHEN** the
  user switches to that task, **THEN** the transcript restores that session's
  saved position and does not apply the outgoing session's position.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.13:** **GIVEN** a task switch that rebuilds
  the Dockview layout, **WHEN** the incoming transcript is placed and
  pagination becomes eligible, **THEN** automatic older-history pagination
  does not start from transient or stale pre-placement geometry.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.14:** **GIVEN** an incoming transcript with
  cached messages and no active unread-divider target, **WHEN** a task switch
  starts a latest-window refresh, **THEN** an enabled transcript shows its
  newest cached message and a disabled transcript shows its saved reader
  position as soon as the panel is measurable, without first exposing the
  browser's default top position.
- **AC-UI-TRANSCRIPT-AUTO-SCROLL-001.15:** **GIVEN** a desktop transcript is the
  selected tab in its Dockview group while another visible group owns global
  focus, **WHEN** a task switch restores that layout, **THEN** the transcript
  is treated as visible and completes its enabled or disabled initial
  placement.

## Migrated source detail

## Why

Users who turn off transcript auto-scroll expect the visible conversation to
stay fixed while new content arrives. Chrome can still adjust the view through
its native overflow anchoring when the toggle is disabled from the bottom.
Separately, the clarification-recovery regression test must reliably observe
the asynchronous hand-off it is designed to protect.

## What

- A disabled native transcript auto-scroll preference prevents browser scroll
  anchoring from moving the transcript when appended content arrives, including
  when the user disabled it while already at the bottom.
- Re-enabling auto-scroll retains the existing catch-up behavior.
- Activating an enabled desktop session transcript after initial load, refresh,
  or hidden message delivery places a bottom-following reader at the newest
  message after the panel becomes measurable.
- Activating a reader-owned transcript position preserves that position.
- Returning to a task in another environment repeats initial placement after
  its cached history becomes measurable and reconciles placement after the
  latest-window refresh without replaying the outgoing transcript's absolute
  offset.
- Automatic older-history pagination waits until environment-switch placement
  has completed and validates current sentinel geometry before retrying.
- The clarification-recovery concurrency regression waits for its asynchronous
  completion signal within a bounded interval instead of treating scheduler
  timing as a product failure.

## Scenarios

- **GIVEN** an overflowing native transcript at its bottom with auto-scroll
  disabled, **WHEN** a new message is appended, **THEN** the transcript's
  `scrollTop` remains at the pre-append position.
- **GIVEN** an overflowing native transcript with auto-scroll enabled,
  **WHEN** new content arrives, **THEN** the transcript remains pinned to the
  bottom.
- **GIVEN** clarification recovery has accepted its retry prompt,
  **WHEN** its asynchronous dispatch is scheduled, **THEN** the recovery call
  completes before the intentionally blocked prompt is released.
- **GIVEN** a task with two overflowing session transcripts, **WHEN** the page
  refreshes with one session inactive and the user activates that session,
  **THEN** the session opens at the newest message when auto-scroll is enabled.
- **GIVEN** a bottom-following session receives content while its desktop tab is
  inactive, **WHEN** the user activates the session, **THEN** its transcript
  catches up to the newest message.
- **GIVEN** the reader disabled auto-scroll or scrolled away from the newest
  message before switching desktop session tabs, **WHEN** the reader returns,
  **THEN** the prior reading position remains visible.
- **GIVEN** two tasks in different environments with overflowing transcripts,
  **WHEN** the user switches between them and returns, **THEN** the incoming
  enabled transcript shows the newest cached message immediately and remains
  at the newest message after its history refresh.
- **GIVEN** the Changes panel owns Dockview focus while Chat remains the
  selected center tab, **WHEN** the user returns to that task, **THEN** Chat
  completes initial transcript placement without requiring an agent update.
- **GIVEN** the incoming transcript has auto-scroll disabled, **WHEN** that
  environment-switch placement runs, **THEN** it restores the incoming
  session's saved position rather than the outgoing transcript's position.
- **GIVEN** incoming history and layout are still settling, **WHEN** the
  older-history sentinel was temporarily at the viewport top, **THEN** the
  sentinel does not start an automatic pagination cascade unless its current
  geometry remains inside the preload region.

## Out of scope

- Changing the transcript toggle's location, labels, or persisted preference.
- Changing clarification recovery production behavior or ownership rules.