[Feature] Split session page controllers and fix composer dock scrolling

[Astro-Han]

Problem

packages/app/src/pages/session.tsx has grown into a 2,145-line session-page controller. It now owns route state, visible-session state, message history, timeline scrolling, composer dock layout, follow-up queueing, revert/restore, review mode, VCS diff loading, artifact files, desktop context sync, keyboard focus, mobile tabs, and right-panel wiring.

This makes local fixes risky because related state is split across distant blocks. The current composer dock scroll bug is the motivating defect: the timeline scroll container padding is written in one place, composer dock height is measured in two places, and only one path performs bottom-scroll compensation. In some mount or height-change paths, the CSS variable updates but the scroll position is not corrected, so the latest message can still be covered by the composer and the user cannot fully scroll past it.

Current evidence

packages/app/src/pages/session.tsx:1546 writes scroll container bottom padding with calc(var(--composer-dock-height, 0px) + 16px).

packages/app/src/pages/session.tsx:1898 observes the composer dock, writes --composer-dock-height, and performs bottom-scroll compensation when the dock height changes.

packages/app/src/pages/session.tsx:2028 also measures the prompt dock and writes the same CSS variable, but it does not perform bottom-scroll compensation. This creates two writers for the same layout state with different side effects.

Goal

Make the session page easier for humans and AI agents to maintain by turning session.tsx into a composition root instead of a mixed controller. The first implementation should fix the composer dock scrolling bug, then extract the directly related controller logic behind small, named hooks and components.

Scope

The first implementation PR may include both the scroll fix and the first controller extraction, but commits must stay review-sized. Behavior fixes, tests, refactors, visual spacing adjustments, and docs updates should be separate commits.

The first PR should focus on composer dock scrolling, scroll-dock ownership extraction, and final-turn spacing. Broader extractions such as history windowing, review state, follow-up state, and revert/restore are follow-up candidates under this issue, not required in the first PR.

The main target is packages/app/src/pages/session.tsx and closely related session-page modules. SessionSidePanel is intentionally out of scope for implementation in this issue. Right-panel product redesign is tracked separately in #154, and terminal-specific right-panel polish is tracked in #65.

Ownership rules

session.tsx should become the route-level composition root. It may read app context and wire controllers together, but the target architecture is that it should not directly own DOM measurement, timer-based loading retries, SDK mutations, VCS refresh state, scroll math, or composer dock layout state.

Shared layout state must have a single owner. In particular, composer dock height, --composer-dock-height, scroll container bottom padding, and bottom-scroll compensation should be owned by one controller.

New hooks and controllers should target roughly 200 lines where practical. This is a soft maintainability target, not a mechanical rule. Business cohesion wins over splitting purely to satisfy a line count.

Hooks should expose small public interfaces. They should not expose internal store setters unless the caller genuinely owns that state.

Acceptance criteria

When the timeline is already at the bottom, composer dock height changes keep the latest turn fully visible above the composer.

When the user has intentionally scrolled upward, composer dock height changes do not force the timeline back to the bottom.

The timeline can scroll fully past the composer dock, with no latest-message text hidden behind the composer.

After the correctness fix, the excessive final-turn gap is reduced in a separate visual commit and verified by screenshot, Browser Use, or Playwright smoke.

session.tsx no longer directly owns composer dock measurement and scroll compensation.

The first extracted controller has a clear name and narrow public API.

Unit tests cover the scroll-dock invariants. A browser or Playwright smoke check verifies the visible composer overlap case.

Non-goals

Do not rewrite the session UI.

Do not change the backend session protocol.

Do not redesign the right panel in this issue. See #154 and #65.

Do not move unrelated SessionSidePanel complexity into this PR.

Do not enforce a hard 200-line rule across all files.

[Astro-Han]

Current assembly map

Session route loading starts at packages/app/src/entry.tsx, goes through packages/app/src/app.tsx, and lazy-loads packages/app/src/pages/session.tsx for session routes.

session.tsx currently acts as the session page composition root and several controllers at once. It reads useGlobalSync, useLayout, useLocal, useFile, useSync, useDialog, useLanguage, useSDK, useSettings, usePrompt, useComments, useTerminal, route state, search params, and session layout state.

Its rendered surface is three major regions:

1. Main timeline: MessageTimeline from packages/app/src/pages/session/message-timeline.tsx.
2. Bottom composer region: SessionComposerRegion from packages/app/src/pages/session/composer/session-composer-region.tsx.
3. Right utility panel: SessionSidePanel from packages/app/src/pages/session/session-side-panel.tsx.

Some good boundaries already exist:

1. session-view-controller.ts owns route-session versus visible-session transition state.
2. session-composer-state.ts owns question, permission, and todo dock state.
3. use-session-hash-scroll.ts owns URL hash to message scrolling.
4. helpers.ts owns tab helpers, file open helpers, sizing helpers, and terminal focus helpers.

The large remaining mixed responsibilities inside session.tsx are:

1. Desktop context sync and retry state.
2. Workspace tab handoff.
3. VCS review state and refresh tasks.
4. Artifact history loading and fallback file derivation.
5. Active message cursor and keyboard message navigation.
6. Scroll gesture detection and auto-scroll state.
7. Composer dock height measurement and timeline padding.
8. Session history windowing and backfill.
9. Follow-up queue state and mutation.
10. Revert and restore mutations.
11. Review panel rendering, review comment actions, and review diff navigation.
12. Session keyboard focus and auto-focus behavior.

This issue should extract those responsibilities gradually. The first slice should focus on composer dock scrolling because it has a known correctness bug.

[Astro-Han]

Target boundaries and ownership rules

session.tsx

Role: route-level composition root.

Allowed responsibilities:

1. Read route params and app contexts.
2. Instantiate session-page controllers.
3. Render SessionMainPanel, SessionSidePanel, and mobile or desktop shell branches.
4. Pass controller outputs into child components.

Target architecture responsibilities to move out:

1. Direct DOM measurement.
2. Direct scroll math.
3. Direct ResizeObserver ownership.
4. SDK mutation workflows.
5. VCS loading and refresh task state.
6. Timer or animation-frame retry loops.
7. Cross-component layout CSS variable writes.

use-session-scroll-dock.ts

Role: single owner for timeline scrolling and composer dock layout compensation.

Owns:

1. Scroll viewport ref.
2. Timeline content ref.
3. Composer dock ref.
4. Composer dock height.
5. --composer-dock-height.
6. Scroll container bottom padding.
7. Bottom detection.
8. Jump-to-latest state.
9. Sticky-bottom behavior when composer height changes.

Candidate public interface, to be reduced during implementation where possible:

1. setScrollRef
2. setContentRef
3. setPromptDockRef
4. scroll
5. resumeScroll
6. scheduleScrollState
7. autoScroll
8. userScrolled

The hook should not expose raw dockHeight, internal store setters, or raw mutable refs unless a caller must pass them to an existing child component.

use-session-history-window.ts

Role: visible message window and older-history backfill.

Owns:

1. Initial rendered turn count.
2. Incremental reveal.
3. Preserve-scroll behavior when revealing older turns.
4. Near-top prefetch and load-more coordination.

This is a follow-up extraction candidate, not required in the first PR.

use-session-review-state.ts

Role: review source selection and diff state.

Owns:

1. Current review change mode.
2. turn, unstaged, staged, and branch diff selection.
3. VCS diff loading and invalidation.
4. Review readiness and count.
5. Artifact file fallback from turn diffs.

Review panel rendering and right-panel product redesign remain separate. This is a follow-up extraction candidate, not required in the first PR.

use-session-followups.ts

Role: queued follow-up drafts.

Owns:

1. Persisted follow-up drafts.
2. Sending state.
3. Failed and paused state.
4. Edit state.
5. Queue eligibility.

This is a follow-up extraction candidate, not required in the first PR.

use-session-revert.ts

Role: revert and restore workflow.

Owns:

1. Revert mutation.
2. Restore mutation.
3. Rolled-message list.
4. Restoring and disabled state.

This is a follow-up extraction candidate, not required in the first PR.

use-session-desktop-context.ts

Role: desktop context IPC sync.

Owns:

1. window.api?.setDesktopContext.
2. Retry timer.
3. Pending context serialization.
4. Cleanup on unmount.

This is a follow-up extraction candidate, not required in the first PR.

File-size guidance

New hooks and controllers should target roughly 200 lines. This is not a hard limit. A cohesive 260-line controller is better than three 90-line files that require cross-reading to understand one behavior.

Page composition files can be longer, but should stay focused on wiring and rendering.

[Astro-Han]

Implementation plan and verification

First PR commit plan

Commit 1: fix composer dock scroll compensation

Add a focused regression test for the composer dock scroll invariants. Then fix the current dual-writer path so composer dock height changes update the CSS variable and bottom-scroll compensation through one code path.

Required behavior:

1. If the timeline is at bottom and composer height changes, stay at bottom.
2. If the user has scrolled upward, do not force-scroll to bottom.
3. The latest message remains fully visible above the composer dock.

Commit 2: extract use-session-scroll-dock.ts

Move the scroll viewport ref, content ref, prompt dock ref, composer dock height, padding write, scroll state scheduling, resume-scroll behavior, and auto-scroll wiring out of session.tsx.

This commit should preserve behavior from Commit 1.

Commit 3: reduce final-turn gap

Adjust timeline bottom spacing after the correctness fix. This should be a separate visual commit. The likely first target is the pb-16 on the timeline turn list in message-timeline.tsx, with the scroll-dock safety gap adjusted only if the correctness tests remain stable.

Follow-up PR candidates under this issue

1. Extract use-session-history-window.ts.
2. Extract use-session-review-state.ts.
3. Extract use-session-followups.ts.
4. Extract use-session-revert.ts.
5. Extract use-session-desktop-context.ts.

These are not required in the first PR. Pick one follow-up candidate per PR unless the earlier commits are small and low risk.

Verification

Run focused unit tests for the new scroll-dock controller.

Run the existing session auto-scroll related tests.

Run package-local typecheck for packages/app.

Run a browser or Playwright smoke that verifies:

1. Open a session with enough content to scroll.
2. Scroll to bottom.
3. Change composer dock height through a visible dock state or controlled test driver.
4. Confirm the latest turn is not hidden behind the composer.
5. Scroll upward.
6. Change composer height again.
7. Confirm the timeline does not force-scroll to bottom.

Do not rely on visual inspection alone for the correctness bug.

PR hygiene

One PR is acceptable for the first slice, but commits must stay review-sized:

1. Behavior fix and regression test.
2. Scroll-dock extraction.
3. Visual spacing adjustment.
4. Issue comment or docs update if needed.

Do not include the right-panel redesign in this PR. That belongs to #154 and related follow-ups.