# TASK-054: C++ header/source pairs and unfolded-window layouts

Status: implemented; required checks pass; confirmed by the human product owner on their Z Fold7 (2026-09-29)
Owner: Claude
Reviewer: human product owner

## Outcome

C++ keeps a declaration in a header and its definition in a source file, and many of the team
use a Z Fold7 or Fold8. A header or source file now knows its counterpart: on a phone it is one tap
away, and a method can be followed to the same method in the other file; on a window 600dp or wider
the two are shown side by side. The wide layouts also put the directory's files and the outline
beside the code, and show a diff as before and after, side by side.

## Scope

- Included: `counterpartOf`, `CodeBrowserViewModel.openSibling` / `loadCounterpart`, the pair switch and jump
  button, the two-pane pair with the panes following each other, the side pane of files and outline,
  the side-by-side diff, and Home's two-pane layout.
- Excluded: a pair whose halves are in different directories (`include/` and `src/`); more than one source
  file for one header.

## Writable paths

- `app/src/main/java/com/ubisam/ubgitea/feature/codebrowser/`
- `app/src/main/java/com/ubisam/ubgitea/feature/history/FileDiffScreen.kt`
- `app/src/main/java/com/ubisam/ubgitea/feature/home/HomeScreen.kt`
- `app/src/main/java/com/ubisam/ubgitea/ui/shell/`

## Acceptance criteria

- [x] A `.h .hpp .hh .hxx` file pairs with a `.cpp .cc .cxx .c` file of the same name in the same directory.
- [x] On a phone the counterpart opens from a switch under the title, and from a button that goes to the same method.
- [x] At 600dp and wider the pair is side by side, header on the left, and can be turned off.
- [x] The counterpart is fetched only when it is going to be shown.
- [x] A counterpart that fails to load, or is not text, says so in its own pane and leaves the other usable.
- [x] At 600dp and wider a diff is before and after, side by side, with rows kept level.
- [x] Below 700dp the side pane is narrower, for the Z Fold8's narrower inner display.
- [x] Build, unit tests and lint pass.
- [ ] Confirmed on the human product owner's device (phone and unfolded Z Fold).

## Security and privacy

No additional concerns.

## Required checks

```text
./gradlew compileDebugKotlin compileDebugUnitTestKotlin testDebugUnitTest assembleDebug lintDebug
```

## Evidence

Recorded on 2026-09-28 in the worktree `awesome-pascal-3f2ada`, with Android Studio's bundled JDK (`D:\AndroidStudio\jbr`, OpenJDK 21). TASK-050 to TASK-054 were built together and checked together:

- `./gradlew compileDebugKotlin compileDebugUnitTestKotlin testDebugUnitTest assembleDebug lintDebug` -- passed.
- Unit tests: 409 in 45 suites, 0 failures, 0 errors (289 before this work).
- Lint: 0 errors, 55 warnings (dependency updates, unused resources, KTX suggestions).
- Emulator (API 36, `sdk_gphone64_x86_64`): the debug APK installs and launches without a crash and shows the sign-in screen with the logo and the new palette. Nothing past sign-in could be reached: that needs a company account.
- Not done: any check on a physical device. None was visible to `adb` during this work.
- Covered by `CodeSearchTest` (counterpart lookup) and `SymbolOutlineTest` (matching a method across a header and its source). The layouts themselves have no automated test.
- Unit tests were written by a delegated worker from `handoff/2026-09-28_unit-tests-redesign.md`; the full run above was repeated here afterwards.

## Known limitations

- Inner-display sizes used for design (Fold7 / Fold8 Ultra about 750x832dp, Fold8 about 650x870dp) are estimated from panel resolution; the real value depends on the screen-zoom setting. Layouts switch on width, not on device.
- The panes follow each other only while one is being dragged, not during the fling after it.

## Review findings

None yet.