kandev/docs/plans/walkthrough-navigation-layout/plan.md

spec, created, status

spec	created	status
docs/specs/ui/requirements/walkthrough-navigation-layout.md	2026-07-28	done

Fix Plan: Stable Walkthrough Navigation

Root cause

WalkthroughStepInner only constrains its maximum height. Its explanation, navigation, and comment form therefore size the card together; the body's flex-1 has no definite height to fill. A longer or shorter step consequently moves the navigation row.

Overview

Give the walkthrough surface a viewport-bounded, definite height and make the step explanation its single internal scroll owner. Render the navigation as the final fixed card footer so Next has a stable location while the current step changes. Prove the geometry in existing desktop and mobile walkthrough Playwright coverage.

Frontend

Walkthrough card composition

• apps/web/components/diff/walkthrough-step-card.tsx — make the shared inner card a definite-height flex column; preserve a scrollable step body and move the navigation row into the fixed footer after the feedback form.
• apps/web/components/diff/walkthrough-floating-window.tsx — give the desktop floating card and phone bottom sheet the available bounded height, while retaining the desktop drag position, mobile bottom alignment, and app-status-bar clearance.

Mobile design contract

• Outcome / entry point: advance an open walkthrough from its existing bottom-sheet launcher.
• Exemplar: the existing WalkthroughFloatingWindow bottom-sheet presentation supplies the surface and dismissal behavior; this change keeps its primary action visible rather than introducing a new phone pattern.
• Hierarchy / primary action: explanation scrolls above; Next remains the final, visible primary action.
• Surface / rationale: a bottom sheet remains appropriate because the walkthrough is a temporary companion to the open code editor, not a primary route. One bounded sheet and its interior own the vertical scroll.
• Geometry: use dynamic viewport sizing, preserve safe-area/status-bar clearance, keep controls at least their existing touch target size, and keep document horizontal overflow at zero.

Tests

• No new non-trivial pure helper is introduced; the regression is rendered geometry and is covered at the browser level.

E2E Tests

• Scenario: desktop steps with different content lengths. File: apps/web/e2e/tests/review/walkthrough.spec.ts. Proof: compare the navigation-footer bounding box before and after advancing, then assert the next step renders.
• Scenario: mobile bottom-sheet walkthrough. File: apps/web/e2e/tests/review/mobile-walkthrough.spec.ts. Proof: advance through steps and assert the navigation footer remains visible, contained by the viewport, and in the same card position.

Implementation Wave

1. Stable navigation footer — done, sequential.

Risks

• A fixed height can hide long text if the body is not the sole scroll owner.
• Phone viewport and app-status-bar offsets can put a bottom action behind browser chrome if dynamic height and existing bottom clearance are not kept.
• Hiding an occluded anchor must not also hide the editor range indicator; preserve the range while clearing only the connector anchor.