kandev/docs/plans/frontend-runtime-cpu/task-03-remove-pinned-scroll-layout-reads.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
03-remove-pinned-scroll-layout-reads	Remove pinned-scroll layout reads	completed	3	02-batch-message-frame-mutations	plan.md	REQ-UI-TRANSCRIPT-AUTO-SCROLL-001	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	../../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

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.