kandev/docs/plans/webkit-transcript-auto-scroll/task-01-use-webkit-safe-bottom-offset.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
01-use-webkit-safe-bottom-offset	Use a WebKit-safe bottom offset	done	1		plan.md	REQ-UI-TRANSCRIPT-AUTO-SCROLL-001	AC-UI-TRANSCRIPT-AUTO-SCROLL-001.5 AC-UI-TRANSCRIPT-AUTO-SCROLL-001.7	../../specs/ui/system-design/transcript-auto-scroll.md

Task 01: Use a WebKit-safe Bottom Offset

Summary

Use the largest signed 32-bit integer for write-only bottom placement. Add a regression that protects WebKit behavior and the no-layout-read contract.

Failing regression first

Add a test named uses a WebKit-safe maximum offset for pinned appends. Require the setter to receive 2_147_483_647. The current test receives Number.MAX_SAFE_INTEGER, so the regression fails before the correction.

In scope

• Change the native bottom offset constant.
• Keep scrollNativeToBottom write-only.
• Update the focused unit regression.
• Run the existing desktop and mobile live-message scenarios.
• Update the transcript auto-scroll design with the WebKit range constraint.

Out of scope

• Other transcript scroll paths or controls.
• Pagination, prepend restoration, and explicit message navigation.
• New user-facing copy or responsive composition.
• Playwright configuration and CI browser installation.

Acceptance

• Live append writes 2_147_483_647 without reading content size.
• Safari-compatible WebKit clamps the request to the transcript bottom.
• Existing desktop and mobile live-message scenarios remain green.

Verification

cd apps && pnpm --filter @kandev/web test -- components/task/chat/message-list-native.test.tsx
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
python3 scripts/lint-spec-files.py --all
git diff --check -- docs/specs docs/plans apps/web/components/task/chat
cd apps/web && pnpm e2e:run --host --project chromium tests/chat/auto-scroll-toggle.spec.ts -- --grep "enabled auto-scroll stays at the bottom for live messages" --retries=0
cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/chat/mobile-auto-scroll-toggle.spec.ts -- --grep "enabled auto-scroll stays at the bottom for live messages on mobile" --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
• docs/specs/ui/system-design/transcript-auto-scroll.md
• docs/plans/webkit-transcript-auto-scroll/plan.md
• docs/plans/webkit-transcript-auto-scroll/task-01-use-webkit-safe-bottom-offset.md

Dependencies

None.

Risks

• The sentinel must remain positive after WebKit converts the scroll offset.
• A regression that only checks Chromium cannot detect this browser difference.

Parallelism

sequential

Inputs

• REQ-UI-TRANSCRIPT-AUTO-SCROLL-001 acceptance criteria 5 and 7.
• The bottom-placement section in the transcript auto-scroll design.
• The existing native-scroll unit harness and live-message browser scenarios.

Results

• Changed the native bottom sentinel from Number.MAX_SAFE_INTEGER to 2_147_483_647.
• Added a regression that keeps the append path write-only and requires the WebKit-safe offset.
• The regression failed on the old sentinel and passed after the correction.
• All 27 focused unit tests passed.
• Typecheck, targeted ESLint, specification lint, and diff checks passed.
• The desktop Chromium and mobile Chrome live-message scenarios passed with retries disabled.
• Direct Chromium, Firefox, and WebKit probes accepted the new offset and placed the 900 px test container at its bottom.