feat(mobile): experiment with v5 stacks and native iPad columns

apps/mobile/fingerprint.config.cjs

@@ -0,0 +1,3 @@
+// SDK 58 fingerprints native packages by version by default. Our pinned
+// Screens PoC needs native source changes to invalidate the development client.
+module.exports = { nativeModuleSourceType: "files" };

apps/mobile/modules/t3-markdown-text/ios/T3MarkdownText.mm

@@ -287,6 +287,7 @@ @implementation T3MarkdownText {
   UILongPressGestureRecognizer *_longPressGestureRecognizer;
   UITapGestureRecognizer *_pressGestureRecognizer;
   NSArray *_contextAccessibilityElements;
+  BOOL _textLayoutNeedsUpdate;
 }
 
 + (ComponentDescriptorProvider)componentDescriptorProvider
@@ -378,16 +379,18 @@ - (void)prepareForRecycle
   _textView.frame = CGRectZero;
   _textView.attributedText = nil;
   _contextAccessibilityElements = nil;
+  _textLayoutNeedsUpdate = YES;
 }
 
 - (void)layoutSubviews
 {
   [super layoutSubviews];
-  // _textView's frame is assigned inside drawRect, which only fires when
-  // state changes. Trigger a redraw whenever the host frame moves out from
-  // under it (rotation, parent relayout) so the text view resizes and
-  // onTextLayout re-fires with the new line wrapping.
+  // Resize during UIKit's layout pass. Doing this in drawRect can leave the
+  // text view's drawing surface clipped to its previous width after a pane
+  // expands, even though TextKit has already rewrapped the lines.
   if (!CGRectEqualToRect(_textView.frame, _view.frame)) {
+    _textView.frame = _view.frame;
+    _textLayoutNeedsUpdate = YES;
     [self setNeedsDisplay];
   }
 }
@@ -449,7 +452,7 @@ - (void)drawRect:(CGRect)rect
   // entirely when nothing actually changed so a JS-side state update made in
   // response to onSelectionChange doesn't deselect what the user is selecting.
   const BOOL textChanged = ![_textView.attributedText isEqualToAttributedString:convertedAttrString];
-  const BOOL frameChanged = !CGRectEqualToRect(_textView.frame, _view.frame);
+  const BOOL frameChanged = _textLayoutNeedsUpdate;
   if (!textChanged && !frameChanged) {
     return;
   }
@@ -475,9 +478,7 @@ - (void)drawRect:(CGRect)rect
     }
     _suppressSelectionChange = NO;
   }
-  if (frameChanged) {
-    _textView.frame = _view.frame;
-  }
+  _textLayoutNeedsUpdate = NO;
 
   // Text attachments have no native link element. Expose their existing runs
   // at the measured glyph bounds, without inserting views into text layout.

apps/mobile/modules/t3-native-controls/ios/T3LayoutMetricsView.swift

@@ -0,0 +1,48 @@
+import ExpoModulesCore
+import UIKit
+
+/// Reports the body geometry of a native navigation column.
+final class T3LayoutMetricsView: ExpoView {
+  let onMetricsChange = EventDispatcher()
+  private var lastMetrics: NSDictionary?
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    isUserInteractionEnabled = false
+    registerForTraitChanges([UITraitHorizontalSizeClass.self, UITraitVerticalSizeClass.self]) { (view: T3LayoutMetricsView, _: UITraitCollection) in
+      view.publishMetrics()
+    }
+  }
+
+  override func didMoveToWindow() {
+    super.didMoveToWindow()
+    lastMetrics = nil
+    publishMetrics()
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    publishMetrics()
+  }
+
+  override func safeAreaInsetsDidChange() {
+    super.safeAreaInsetsDidChange()
+    publishMetrics()
+  }
+
+  private func publishMetrics() {
+    guard window != nil, bounds.width > 0, bounds.height > 0 else { return }
+    let metrics: [String: Any] = [
+      "width": bounds.width, "height": bounds.height,
+      "horizontalSizeClass": traitCollection.horizontalSizeClass == .regular ? "regular" : "compact",
+      "safeArea": [
+        "top": safeAreaInsets.top, "bottom": safeAreaInsets.bottom,
+        "left": safeAreaInsets.left, "right": safeAreaInsets.right,
+      ],
+    ]
+    let next = metrics as NSDictionary
+    guard lastMetrics?.isEqual(next) != true else { return }
+    lastMetrics = next
+    onMetricsChange(metrics)
+  }
+}

apps/mobile/modules/t3-native-controls/ios/T3NativeControlsModule.swift

@@ -11,6 +11,14 @@ public final class T3NativeControlsModule: Module {
   private var filePresentation: T3NativeFilePresentation?
 
   public func definition() -> ModuleDefinition {
+    Constants {
+      ["supportsWorkspaceColumns": NSClassFromString("RNSSplitHostComponentView") != nil]
+    }
+    View(T3LayoutMetricsView.self) {
+      ViewName("LayoutMetrics")
+      Events("onMetricsChange")
+    }
+
     AsyncFunction("presentVideo") { (url: URL, title: String, sourceIdentifier: String, identifier: String, promise: Promise) in
       try self.presentVideo(
         url: url,

apps/mobile/package.json

@@ -119,7 +119,7 @@
     "react-native-nitro-modules": "0.35.9",
     "react-native-reanimated": "4.7.0",
     "react-native-safe-area-context": "~5.9.1",
-    "react-native-screens": "~4.28.0",
+    "react-native-screens": "file:deps/react-native-screens-5.0.0-t3.2.tgz",
     "react-native-shiki-engine": "^0.3.12",
     "react-native-svg": "15.15.5",
     "react-native-webview": "14.0.1",
@@ -140,7 +140,8 @@
   "expo": {
     "install": {
       "exclude": [
-        "react-native-keyboard-controller"
+        "react-native-keyboard-controller",
+        "react-native-screens"
       ]
     },
     "autolinking": {

apps/mobile/src/Stack.tsx

@@ -1,3 +1,5 @@
+import { createV5StackNavigator as createNativeStackNavigator } from "./native/createV5StackNavigator";
+import { createWorkspaceStackNavigator } from "./features/layout/createWorkspaceStackNavigator";
 import {
   createPathConfigForStaticNavigation,
   getPathFromState,
@@ -6,7 +8,6 @@ import {
   useNavigation,
 } from "@react-navigation/native";
 import {
-  createNativeStackNavigator,
   createNativeStackScreen,
   type NativeStackNavigationOptions,
 } from "@react-navigation/native-stack";
@@ -602,7 +603,7 @@ function NotFoundScreen() {
   );
 }
 
-const RootStackConfig = createNativeStackNavigator({
+const RootStackConfig = createWorkspaceStackNavigator({
   initialRouteName: "Home",
   layout: RootStackLayout,
   screenOptions: {

apps/mobile/src/components/CompactBrandTitle.tsx

@@ -1,3 +1,4 @@
+import { NATIVE_WORKSPACE_COLUMNS_SUPPORTED } from "../native/NativeWorkspaceColumns";
 import Constants from "expo-constants";
 import type { NativeStackNavigationOptions } from "@react-navigation/native-stack";
 import { Platform, View } from "react-native";
@@ -14,7 +15,7 @@ import { useAndroidControlSizing } from "./useAndroidControlSizing";
  */
 export function brandTitleOffset(): number {
   if (Platform.OS !== "ios") return 0;
-  return Platform.isPad ? IPAD_HOME_TITLE_OFFSET : 0;
+  return Platform.isPad && !NATIVE_WORKSPACE_COLUMNS_SUPPORTED ? IPAD_HOME_TITLE_OFFSET : 0;
 }
 
 /**

apps/mobile/src/components/ScreenHeader.tsx

@@ -53,6 +53,10 @@ export function ScreenHeader(props: ScreenHeaderProps) {
         ]}
         options={{
           headerShown: true,
+          headerBackVisible:
+            !layout.usesSplitView ||
+            !props.backInSplitView ||
+            !(props.backInSplitView.onPress || props.onBack),
           title: props.title,
           unstable_headerSubtitle: props.subtitle || undefined,
           ...(props.matchSearchSurface

apps/mobile/src/features/devices/DevicePreviewRouteScreen.tsx

@@ -4,7 +4,7 @@ import {
   deviceToolUpdatePolicy,
 } from "@t3tools/client-runtime/state/device";
 import { useIsFocused, useNavigation, type StaticScreenProps } from "@react-navigation/native";
-import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import { createV5StackNavigator as createNativeStackNavigator } from "../../native/createV5StackNavigator";
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";

apps/mobile/src/features/files/FileTreeBrowser.tsx

@@ -258,7 +258,12 @@ export function FileTreeBrowser(props: {
       updateCellsBatchingPeriod={16}
       windowSize={5}
       contentContainerStyle={{ paddingTop: 8, paddingBottom: 8 }}
-      refreshControl={<RefreshControl refreshing={props.isPending} onRefresh={props.onRefresh} />}
+      refreshControl={
+        <RefreshControl
+          refreshing={props.isPending && visibleNodes.length > 0}
+          onRefresh={props.onRefresh}
+        />
+      }
       renderItem={renderItem}
       ListHeaderComponent={
         <>

apps/mobile/src/features/home/HomeHeader.tsx

@@ -1,6 +1,8 @@
 import { NativeHeaderToolbar, NativeStackScreenOptions } from "../../native/StackHeader";
-import { useCallback, useRef } from "react";
+import { use, useCallback, useRef } from "react";
+import { Platform } from "react-native";
 import type { SearchBarCommands } from "react-native-screens";
+import { NativePrimaryColumnContext } from "../../native/v5-workspace-context";
 import { useUniwindTheme } from "../../lib/useUniwindTheme";
 import { useHardwareKeyboardCommand } from "../keyboard/hardwareKeyboardCommands";
 import { withNativeGlassHeaderItem } from "../layout/native-glass-header-items";
@@ -9,11 +11,14 @@ import {
   NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
 } from "../layout/native-mail-search-toolbar";
 import { buildHomeListFilterMenu } from "./home-list-filter-menu";
+import { createSidebarHeaderItems } from "../threads/sidebar-native-header-items";
 import type { HomeHeaderProps } from "./HomeHeader.types";
 
 export type { HomeHeaderEnvironment } from "./HomeHeader.types";
 
 export function HomeHeader(props: HomeHeaderProps) {
+  const primaryColumn = use(NativePrimaryColumnContext);
+  const iPadSidebar = Platform.OS === "ios" && Platform.isPad && primaryColumn !== null;
   const searchBarRef = useRef<SearchBarCommands>(null);
   const iconColor = useUniwindTheme()["--color-icon"];
   // The list uses a fixed creation order and ignores sort/group options, so
@@ -36,57 +41,87 @@ export function HomeHeader(props: HomeHeaderProps) {
           // Static header config (glass, title, fonts) lives in Stack.tsx
           // (GLASS_HEADER_OPTIONS). Only dynamic values are set here.
           headerTintColor: iconColor,
-          unstable_headerRightItems: () => [
-            withNativeGlassHeaderItem({
-              accessibilityLabel: "Open settings",
-              icon: { name: "ellipsis", type: "sfSymbol" } as const,
-              identifier: "home-settings",
-              label: "",
-              onPress: props.onOpenSettings,
-              type: "button",
-            }),
-          ],
+          unstable_headerRightItems: () =>
+            iPadSidebar
+              ? createSidebarHeaderItems({
+                  filterIcon: hasCustomListOptions
+                    ? "line.3.horizontal.decrease.circle.fill"
+                    : "line.3.horizontal.decrease.circle",
+                  filterMenu,
+                  onOpenSettings: props.onOpenSettings,
+                })
+              : [
+                  withNativeGlassHeaderItem({
+                    accessibilityLabel: "Open settings",
+                    icon: { name: "ellipsis", type: "sfSymbol" } as const,
+                    identifier: "home-settings",
+                    label: "",
+                    onPress: props.onOpenSettings,
+                    type: "button",
+                  }),
+                ],
           // The keys below are set per-branch (not `undefined`) so a later
           // reapply cannot clobber options owned by NativeHeaderToolbar.
-          ...(NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+          ...(iPadSidebar
             ? {
-                unstable_headerToolbarItems: () => [
-                  createNativeMailSearchToolbarItem({
-                    composeButtonId: "home-new-task",
-                    composeSystemImageName: "square.and.pencil",
-                    filterMenu,
-                    filterButtonId: "home-filter",
-                    filterSystemImageName: hasCustomListOptions
-                      ? "line.3.horizontal.decrease.circle.fill"
-                      : "line.3.horizontal.decrease",
-                    onComposePress: props.onStartNewTask,
-                    onSearchTextChange: props.onSearchQueryChange,
-                    placeholder: "Search",
-                    searchTextChangeId: "home-search-text",
-                    showsSearchDismissButton: true,
-                  }),
-                ],
-              }
-            : {
-                // Pre-Liquid-Glass iOS: standard pull-down search in the nav
-                // bar; create + sort live in the plain bottom toolbar below.
                 headerSearchBarOptions: {
                   ref: searchBarRef,
                   autoCapitalize: "none" as const,
                   hideNavigationBar: false,
+                  hideWhenScrolling: false,
+                  obscureBackground: false,
+                  placement: "stacked" as const,
+                  allowToolbarIntegration: false,
                   placeholder: "Search",
-                  onCancelButtonPress: () => {
-                    props.onSearchQueryChange("");
+                  onCancelButtonPress: () => props.onSearchQueryChange(""),
+                  onChangeText: (event) => props.onSearchQueryChange(event.nativeEvent.text),
+                },
+                unstable_headerToolbarItems: () => [],
+              }
+            : NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+              ? {
+                  headerSearchBarOptions: {
+                    ref: searchBarRef,
+                    autoCapitalize: "none" as const,
+                    onCancelButtonPress: () => props.onSearchQueryChange(""),
                   },
-                  onChangeText: (event) => {
-                    props.onSearchQueryChange(event.nativeEvent.text);
+                  unstable_headerToolbarItems: () => [
+                    createNativeMailSearchToolbarItem({
+                      composeButtonId: "home-new-task",
+                      composeSystemImageName: "square.and.pencil",
+                      filterMenu,
+                      filterButtonId: "home-filter",
+                      filterSystemImageName: hasCustomListOptions
+                        ? "line.3.horizontal.decrease.circle.fill"
+                        : "line.3.horizontal.decrease",
+                      onComposePress: props.onStartNewTask,
+                      onSearchTextChange: props.onSearchQueryChange,
+                      placeholder: "Search",
+                      searchTextChangeId: "home-search-text",
+                      showsSearchDismissButton: true,
+                    }),
+                  ],
+                }
+              : {
+                  // Pre-Liquid-Glass iOS: standard pull-down search in the nav
+                  // bar; create + sort live in the plain bottom toolbar below.
+                  headerSearchBarOptions: {
+                    ref: searchBarRef,
+                    autoCapitalize: "none" as const,
+                    hideNavigationBar: false,
+                    placeholder: "Search",
+                    onCancelButtonPress: () => {
+                      props.onSearchQueryChange("");
+                    },
+                    onChangeText: (event) => {
+                      props.onSearchQueryChange(event.nativeEvent.text);
+                    },
                   },
-                },
-              }),
+                }),
         }}
       />
 
-      {NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED ? null : (
+      {iPadSidebar || NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED ? null : (
         <NativeHeaderToolbar placement="bottom">
           <NativeHeaderToolbar.Menu
             accessibilityLabel="Filter threads"