Files
kandev/docs/plans/frontend-runtime-cpu/task-03-remove-pinned-scroll-layout-reads.md
T
2026-08-27 16:04:59 +00:00

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.