112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
---
|
|
id: "03-remove-pinned-scroll-layout-reads"
|
|
title: "Remove pinned-scroll layout reads"
|
|
status: completed
|
|
wave: 3
|
|
depends_on:
|
|
- "02-batch-message-frame-mutations"
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-UI-TRANSCRIPT-AUTO-SCROLL-001
|
|
acceptance_criteria:
|
|
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.1
|
|
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.2
|
|
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.5
|
|
- AC-UI-TRANSCRIPT-AUTO-SCROLL-001.7
|
|
system_design:
|
|
- ../../specs/ui/system-design/transcript-auto-scroll.md
|
|
---
|
|
|
|
# Task 03: Remove Pinned-scroll Layout Reads
|
|
|
|
## Summary
|
|
|
|
Place a pinned transcript at the native maximum offset with a write-only
|
|
operation. Keep all current auto-scroll guards and responsive behavior.
|
|
|
|
## Failing regression first
|
|
|
|
Add a unit test named `pins an appended message without reading content size`.
|
|
Make the transcript `scrollHeight` getter throw, append a message while the
|
|
near-bottom guard is true, and prove that the scroll setter receives the
|
|
maximum-offset request.
|
|
|
|
## In scope
|
|
|
|
- Add one write-only native bottom-placement helper.
|
|
- Use it for the work-start and pinned message-update paths.
|
|
- Preserve near-bottom, programmatic-lock, and layout-restore guards.
|
|
- Preserve disabled-state freezing and re-enable catch-up.
|
|
- Extend desktop and mobile auto-scroll browser scenarios.
|
|
- Confirm that the native transcript remains the only scroll owner.
|
|
|
|
## Out of scope
|
|
|
|
- Removing geometry reads from user scroll detection, pagination, prepend
|
|
restoration, or catch-up decisions.
|
|
- Changing smooth navigation to a prompt or message.
|
|
- Changing transcript controls, layout, copy, or touch targets.
|
|
|
|
## Acceptance
|
|
|
|
- A pinned message append performs no content-size read in its commit effect.
|
|
- Enabled auto-scroll remains at the bottom after a live message arrives.
|
|
- Disabled auto-scroll retains the same `scrollTop` after content arrives.
|
|
- Desktop and mobile produce the same outcome through shared logic.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd apps && pnpm --filter @kandev/web test -- components/task/chat/message-list-native.test.tsx components/task/chat/transcript-auto-scroll.test.ts
|
|
cd apps && pnpm --filter @kandev/web run typecheck
|
|
cd apps/web && pnpm exec eslint components/task/chat/message-list-native-scroll.ts components/task/chat/message-list-native.test.tsx 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 -- --retries=0
|
|
cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/chat/mobile-auto-scroll-toggle.spec.ts -- --retries=0
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/web/components/task/chat/message-list-native-scroll.ts`
|
|
- `apps/web/components/task/chat/message-list-native.test.tsx`
|
|
- `apps/web/components/task/chat/transcript-auto-scroll.test.ts`
|
|
- `apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts`
|
|
- `apps/web/e2e/tests/chat/mobile-auto-scroll-toggle.spec.ts`
|
|
|
|
## Dependencies
|
|
|
|
- Task 02 completes first so the browser scenario exercises the final store
|
|
notification cadence.
|
|
|
|
## Risks
|
|
|
|
- A large offset can be written while a user-owned scroll is active if a guard
|
|
is lost.
|
|
- Unit DOM behavior can differ from browser clamping.
|
|
- Sticky prompt geometry can settle after the first bottom placement.
|
|
- Mobile touch scrolling can expose a different lock-release timing.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- Transcript auto-scroll acceptance criteria 1, 2, 5, and 7.
|
|
- The native transcript auto-scroll system design.
|
|
- Existing desktop and mobile auto-scroll tests.
|
|
|
|
## Results
|
|
|
|
Implemented the write-only native bottom-placement helper and wired it into
|
|
work-start, pinned message updates, and re-enable catch-up. Initial placement,
|
|
user detection, pagination, prepend restoration, and explicit scroll decisions
|
|
retain their required geometry reads.
|
|
|
|
Verification passed:
|
|
|
|
- Native transcript unit suites: 2 files and 57 tests.
|
|
- Desktop auto-scroll browser suite: 9 tests passed.
|
|
- Mobile auto-scroll browser suite: 5 tests passed.
|
|
- The new enabled-live-message scenarios confirm both layouts remain at the
|
|
bottom after incoming content.
|