fix(web): preserve transcript position on task switch (#3405)

This commit is contained in:
Carlos Florêncio
2026-09-05 16:18:21 +00:00
committed by GitHub
parent fe8db466c3
commit 59a01b60c4
11 changed files with 1103 additions and 68 deletions
@@ -0,0 +1,178 @@
---
created: 2026-09-04
status: completed
requirements:
- ../../specs/ui/requirements/transcript-auto-scroll.md
- ../../specs/ui/requirements/task-prompt-transcript-visibility.md
system_design:
- ../../specs/ui/system-design/transcript-auto-scroll.md
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
legacy_specs: []
---
# Implementation Plan: Transcript Task-switch Continuity
## Overview
Make an incoming task transcript appear at its intended reading position as
soon as cached rows are measurable. Keep that position correct when the latest
message window arrives, and prevent the older-history sentinel from turning a
stale pre-placement intersection into an unnecessary pagination request.
The confirmed failure has two parts. First, cached rows stay visible at the
browser-default top while the latest-window refresh blocks initial placement.
Second, releasing the placement block can replay an intersection recorded at
that temporary top without checking the sentinel's current geometry.
## Scope
### In scope
- Provisional task-entry placement from cached transcript rows.
- Final placement after the latest-window refresh settles.
- Enabled auto-scroll placement at the newest message.
- Disabled auto-scroll restoration from the incoming session's saved position.
- Placement-token ownership through both phases.
- Current-geometry validation before an observed sentinel intersection can
start or transfer older-history pagination.
- Development diagnostics for placement phase, owner, token, and geometry.
- Focused unit, desktop browser, and mobile browser regression coverage.
### Out of scope
- Unread-divider behavior or its setting.
- The auto-scroll control, persistence format, or same-environment activation
semantics.
- Backend message ordering, cursor contracts, or page size.
- Explicit transcript navigation and saved-layout behavior except for
regressions caused by shared scroll ownership.
- Dockview architecture, mobile navigation, layout, or user-facing copy.
## Technical approach
### Split task-entry placement into provisional and final phases
Extend the initial-placement coordinator in
`apps/web/components/task/chat/message-list-native-scroll.ts` with
token-scoped provisional and final completion state. When cached rows exist,
the panel is measurable, and no unread-divider target owns entry, run a
provisional placement without clearing the environment-switch token:
- enabled auto-scroll selects the newest cached message;
- disabled auto-scroll restores the incoming session's saved position.
After the latest-window refresh settles, run the existing ownership decision
against the reconciled rows and conditionally clear the same token. Re-check
the live session, visibility, and competing scroll owners before both writes.
If no cached rows exist, keep the existing loading path and perform only the
final phase.
Keep `useSessionMessages` as the source of cached-history and refresh readiness.
Do not copy history state into a second store or replay the outgoing
transcript's absolute offset.
### Require live geometry before pagination replay
Update `useLazyLoadSentinel` so eligibility retries and stale-view handoffs
invoke `isCurrentGeometryEligible` when a consumer supplies it. A historical
`IntersectionObserver` entry remains a wake-up signal, not proof that the
sentinel is currently inside the preload region. Preserve existing behavior for
consumers that do not supply a current-geometry predicate.
The transcript already owns the scroll-root-aware geometry predicate. Keep the
placement token active through final placement so the sentinel cannot paginate
between the provisional and final phases. A transcript restored at its actual
top must still load older history.
### Add bounded diagnostics
Add development logging for provisional placement, final placement, request
completion, and pagination eligibility. Include the session identifier,
placement token, selected owner, and scroll geometry. Do not log message
content or saved offsets.
## Tests
| Acceptance criteria | Evidence |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `AC-UI-TRANSCRIPT-AUTO-SCROLL-001.11` and `.14` | Coordinator tests hold the refresh pending while cached rows are measurable, then prove immediate enabled placement and final reconciliation. |
| `AC-UI-TRANSCRIPT-AUTO-SCROLL-001.12` and `.14` | Coordinator and browser tests prove disabled task entry uses the incoming session's saved position before and after refresh. |
| `AC-UI-TRANSCRIPT-AUTO-SCROLL-001.13` | Sentinel tests prove eligibility release and stale-view transfer reject old intersections when current geometry is outside the preload region. |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10` | Browser request tracing proves task entry does not request older pages before real upward navigation. |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.14` | Existing and focused sentinel coverage proves a transcript currently restored at the top still paginates. |
Use TDD. Add the pending-refresh and stale-intersection regressions first and
record their failures before changing production behavior.
## E2E tests
- Extend `apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts` with a cached
environment-changing task switch. Hold the return task's latest-window
`message.list` response, prove the transcript is already at the newest cached
message, release the response, and prove it remains at the final newest
message.
- Capture outgoing `message.list` requests and prove no request with an older
`before` cursor occurs during entry or block release.
- Cover disabled auto-scroll by proving the incoming task's saved reading
position is used while refresh is held and after it settles.
- Extend `apps/web/e2e/tests/chat/mobile-auto-scroll-toggle.spec.ts` with the
same cached-entry contract through the current mobile task switcher.
- Reuse the current WebSocket routing helpers. Add a narrowly scoped response
hold helper only if desktop and mobile need the same control.
Use causal waits for the held response and rendered geometry. Do not replace
the regression with a long eventual-bottom poll.
## Mobile design contract
- **Desktop outcome:** the existing Dockview session panel places cached rows
immediately and reconciles them after refresh.
- **Mobile entry:** the existing task switcher opens the full-height task Chat
tab; no new control or navigation surface is introduced.
- **Exemplar:** `TaskLayout` remains the responsive composition owner.
- **Scroll ownership:** the transcript remains the only vertical scroll region;
the header and composer keep their current safe-area behavior.
- **Shared behavior:** cached placement, refresh reconciliation, auto-scroll
preference, and sentinel geometry checks use the same coordinator rules.
Mobile does not consume Dockview's environment-switch token.
- **Mobile proof:** mobile-chrome verifies immediate cached placement, final
reconciliation, disabled position restoration, and no document overflow.
## Work orders
- [x] [Task 01: Stabilize task-switch transcript entry](task-01-stabilize-task-switch-transcript.md)
The work order is sequential because placement ownership and pagination
eligibility share one transcript lifecycle.
## Results
Implemented provisional cached-history placement and final refresh
reconciliation for environment-changing task switches. Enabled transcripts now
open at the newest cached message; disabled transcripts restore the incoming
session's saved reader position. The placement token remains active until the
final phase, and an unread-divider target keeps priority.
Eligibility retries and stale-view handoffs now require the sentinel's current
geometry when the consumer supplies that predicate. The desktop browser
regression holds the latest-window response and proves both placement modes plus
the absence of older-page requests. The mobile regression proves the same user
value through the task-switcher sheet and checks document width.
Verification passed: 142 focused unit tests, targeted ESLint, TypeScript
typecheck, one Chromium E2E, one mobile-chrome E2E, specification lint, Prettier,
and diff checks.
## Risks
- Clearing the placement token after provisional placement can reopen the
original pagination race. Only final placement can clear it.
- A provisional write must not override unread-divider or explicit-navigation
ownership.
- Cached row heights can change after refresh. Final placement must recompute
against current DOM geometry instead of preserving a stale pixel delta.
- Applying the geometry predicate to every sentinel consumer could change
Prompt History behavior. Keep it optional and test the supplied-predicate
path independently.
- Browser tests can pass while still showing a top flash if they only assert an
eventual position. Hold the refresh response and assert before release.
@@ -0,0 +1,149 @@
---
id: "01-stabilize-task-switch-transcript"
title: "Stabilize task-switch transcript entry"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-UI-TRANSCRIPT-AUTO-SCROLL-001
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
acceptance_criteria:
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.11
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.12
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.13
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.14
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.14
system_design:
- ../../specs/ui/system-design/transcript-auto-scroll.md
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
---
# Task 01: Stabilize Task-switch Transcript Entry
## Summary
Place cached transcript rows at the incoming task's intended position before
the latest-window refresh resolves. Reconcile the position afterward, and
require current sentinel geometry before older-history pagination starts.
## In scope
- Add token-scoped provisional and final task-entry placement phases.
- Use the incoming session's auto-scroll preference and saved position.
- Preserve unread-divider, explicit-navigation, and layout-restore priority.
- Keep older-history pagination blocked through final placement.
- Validate current geometry on eligibility retry and stale-view handoff.
- Add bounded development diagnostics.
- Add TDD regressions and desktop/mobile Playwright coverage.
## Out of scope
- Changing unread-divider behavior, auto-scroll persistence, backend cursors,
message page size, or task navigation UI.
## Acceptance
- With cached messages and auto-scroll enabled, switching tasks shows the
incoming task's newest cached message before a held refresh response and the
final newest message after release. The browser-default top is never exposed.
- With auto-scroll disabled, the same flow uses the incoming session's saved
reading position before and after refresh. It never reuses the outgoing
transcript's offset.
- Releasing the placement block or transferring a stale view cannot start
pagination from an old observer entry. A sentinel currently inside the
preload region still loads older history.
- Desktop and mobile browser tests prove the cached-entry behavior, and request
tracing proves task entry sends no unwanted older-page request.
## Files likely touched
- `apps/web/components/task/chat/message-list-native-scroll.ts`
- `apps/web/components/task/chat/message-list-native.tsx`
- `apps/web/components/task/chat/message-list-native.test.tsx`
- `apps/web/components/task/chat/transcript-auto-scroll.ts`
- `apps/web/components/task/chat/transcript-auto-scroll.test.ts`
- `apps/web/hooks/use-lazy-load-sentinel.ts`
- `apps/web/hooks/use-lazy-load-sentinel.test.ts`
- `apps/web/hooks/domains/session/use-session-messages.ts`
- `apps/web/hooks/domains/session/use-session-messages.test.ts`
- `apps/web/e2e/helpers/ws-response-hold.ts`
- `apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts`
- `apps/web/e2e/tests/chat/mobile-auto-scroll-toggle.spec.ts`
The response-hold helper is optional. Keep the WebSocket control local to a
single test file if it is not shared by both viewport suites.
## Verification
Follow TDD. Run the new focused tests before the production change and record
the expected failures. Then run:
```bash
(cd apps && pnpm --filter @kandev/web test -- --run hooks/use-lazy-load-sentinel.test.ts components/task/chat/message-list-native.test.tsx components/task/chat/transcript-auto-scroll.test.ts hooks/domains/session/use-session-messages.test.ts)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm exec eslint hooks/use-lazy-load-sentinel.ts hooks/use-lazy-load-sentinel.test.ts components/task/chat/message-list-native-scroll.ts components/task/chat/message-list-native.tsx components/task/chat/message-list-native.test.tsx components/task/chat/transcript-auto-scroll.ts components/task/chat/transcript-auto-scroll.test.ts hooks/domains/session/use-session-messages.ts hooks/domains/session/use-session-messages.test.ts e2e/helpers/ws-response-hold.ts e2e/tests/chat/auto-scroll-toggle.spec.ts e2e/tests/chat/mobile-auto-scroll-toggle.spec.ts)
(cd apps/web && pnpm e2e:run --host --project chromium tests/chat/auto-scroll-toggle.spec.ts -- --grep "environment-changing task switch" --retries=0)
(cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/chat/mobile-auto-scroll-toggle.spec.ts -- --grep "task switch" --retries=0)
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
git diff --check
```
If the optional helper is not created, omit it from the ESLint command. If the
managed Playwright runner does not accept `--no-build` after the desktop run,
remove only that flag and keep the same mobile project and grep.
## Dependencies
None.
## Parallelism
`sequential`. This task owns the shared placement and pagination lifecycle.
## Risks
- Do not clear the switch token during provisional placement.
- Do not let provisional placement override an unread-divider target.
- Re-resolve the live scroll element and session before every deferred write.
- Keep the geometry predicate optional for non-transcript sentinel consumers.
- Assert geometry while the refresh is held. An eventual-bottom assertion does
not detect the visible top flash.
## Mobile design contract
- Use the current mobile task switcher and full-height Chat tab.
- Keep the transcript as the only vertical scroll owner.
- Keep the existing header, composer, touch targets, and safe-area geometry.
- Exercise the same cached-entry and final-reconciliation contract as desktop.
- Prove the task view has no horizontal document overflow after both phases.
## Output contract
Report the red and green evidence, placement ownership changes, sentinel
geometry rule, changed files, desktop/mobile browser results, and remaining
risks. Update this work order and `plan.md` with implementation results in the
same conversation.
## Results
- Added token-scoped provisional and final transcript placement. Cached enabled
transcripts place at the bottom before refresh; cached disabled transcripts
use the incoming session's saved position. Final placement reconciles current
rows and clears only the matching token.
- Preserved unread-divider, layout-restore, explicit-navigation, and
programmatic-scroll ownership.
- Added current-geometry checks to sentinel eligibility retry and stale-view
handoff. Consumers without a geometry predicate retain their previous
behavior.
- Added a correlated WebSocket latest-window response hold for browser tests.
Desktop and mobile tests exercise both enabled and disabled cached returns.
Desktop request tracing also proves no older-page HTTP request starts during
placement release.
- Red evidence: four focused unit assertions failed on the old behavior. The
desktop E2E remained 1,892 px from the bottom while refresh was held.
- Green evidence: 142 focused unit tests passed; targeted ESLint and typecheck
passed; focused Chromium and mobile-chrome runs each passed one test with
retries disabled; specification lint and diff checks passed.