fix(mobile): stabilize iOS header item transitions

[juliusmarminge]

What Changed

This updates the mobile native-stack header patches so iOS can preserve header item identity during transitions. Custom header items now forward an optional identifier through React Navigation and react-native-screens, and the workspace brand/connection header item uses a shared identifier so UIKit does not confuse it with navigation controls.

The react-native-screens patch also caches leading, trailing, and center item groups independently to avoid rebuilding unrelated UIBarButtonItemGroups while UIKit is animating them. Internal mobile navigation docs were added to capture the constraints around Liquid Glass headers, custom item identifiers, and native rebuild requirements.

Why

On iOS, replacing or regrouping bar button items during push/pop or menu transitions can leave visible header artifacts, including stuck glass capsules and malformed back button transitions. Giving the brand item a stable identity and preserving unchanged item groups lets UIKit match the right header elements across route transitions.

This keeps the fix scoped to the mobile native header integration while documenting the behavior so future header changes do not accidentally reintroduce the issue.

UI Changes

This is a mobile UI behavior fix for iOS header transitions. Before/after screenshots or video should be included with the PR if available from simulator or device verification.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Touches patched native navigation stack code on iOS 26+ where incorrect header caching or identifiers could cause visible bar glitches; scope is mobile headers only, not auth or data paths.

Overview
Stabilizes Liquid Glass iOS navigation headers by giving the workspace brand a stable UIKit bar-button identity and avoiding unnecessary native header rebuilds during transitions.

The app exports BRAND_HEADER_ITEM_IDENTIFIER (workspace-brand) and assigns it to the custom leading brand item in both the static brand header and the connection-status swap, so UIKit can match the same slot across route changes instead of treating it like a new control.

Patches extend @react-navigation/native-stack and react-native-screens to forward optional identifier on custom header subviews into UIBarButtonItem.identifier, and to cache leading, trailing, and center UIBarButtonItemGroups separately so unrelated header updates do not regroup items UIKit may still be animating. New internals doc mobile-navigation.md records Liquid Glass header constraints and notes that identifiers require a native rebuild, not OTA JS alone.

^{Reviewed by Cursor Bugbot for commit 5752498. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Stabilize iOS header item transitions via BRAND_HEADER_ITEM_IDENTIFIER and react-native-screens caching

• Adds exported constant BRAND_HEADER_ITEM_IDENTIFIER ("workspace-brand") in CompactBrandTitle.tsx and assigns it to the custom header item in renderCompactBrandHeaderItems and getConnectionAwareBrandHeaderOptions in WorkspaceConnectionTitle.tsx
• Patches @react-navigation/native-stack to propagate an identifier field on custom header items through useHeaderConfigProps to native left/right/center header subviews, emit a navigator-level finishTransitioning event, and support custom center header items
• Patches react-native-screens so iOS caches and reuses UIBarButtonItem groups per placement (leading/trailing/center) keyed by config and item values, avoiding recreation during transitions; on iOS 26+ forwards identifier to UIBarButtonItem.identifier; Android accepts the identifier prop as a no-op
• Documents the navigation header architecture and identifier usage in mobile-navigation.md
• Behavioral Change: iOS header item rendering now relies on cached bar button item groups; on iOS 16+ uses leadingItemGroups/trailingItemGroups and on iOS 26+ uses centerItemGroups, with fallback to leftBarButtonItems/rightBarButtonItems on older platforms. The finishTransitioning event and custom center header item support are new native-stack behaviors introduced by the patch.

^{Macroscope summarized 5752498.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 231f126c-235e-42ab-8aa1-7119fbc225ef

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	−12 B (−0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	−9 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	−3 B (−0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	11	11	0 (0.0%)	21	✅
Claude	Total thread wire	13.3 KiB	13.3 KiB	+22 B (+0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	+1 B (+0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+21 B (+0.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	10	11	+1 (+10.0%)	21	✅

Baseline: 702a6ad · PR result: 5752498 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a native iOS navigation integration change that adds identifier plumbing, transition callbacks, and shared header-group caching, affecting more than the workspace brand alone. Its transition-sensitive behavior spans existing native-stack headers and requires a new mobile build, making the runtime surface broader than a small isolated UI fix.

^{You can add or adjust custom eligibility rules. Learn more.}