TypeScript
docs(mobile): the five layers of the mobile layout, with x-ray diagrams (#27107)
Julius Marminge0444aae90284
diff --git a/docs/README.md b/docs/README.mdindex f332da947f5..48eb4deec9d 100644--- a/docs/README.md+++ b/docs/README.md@@ -52,6 +52,7 @@ source alone does not explain. Most code changes do not need an internal documen- [Environment auth](./internals/environment-auth.md)- [T3 Connect](./internals/t3-connect.md)- [Assistant citations](./internals/assistant-citations.md)+- [Mobile layout](./internals/mobile-layout.md)- [Mobile navigation](./internals/mobile-navigation.md)- [Mobile development lifecycle](./internals/mobile-development.md)- [Terminal runtime](./internals/terminal-runtime.md)diff --git a/docs/internals/images/mobile-layers.png b/docs/internals/images/mobile-layers.pngnew file mode 100644index 00000000000..5b43552d9adBinary files /dev/null and b/docs/internals/images/mobile-layers.png differdiff --git a/docs/internals/images/mobile-workspace-split.png b/docs/internals/images/mobile-workspace-split.pngnew file mode 100644index 00000000000..71297685854Binary files /dev/null and b/docs/internals/images/mobile-workspace-split.png differdiff --git a/docs/internals/mobile-layout.md b/docs/internals/mobile-layout.mdnew file mode 100644index 00000000000..c5e7b28b391--- /dev/null+++ b/docs/internals/mobile-layout.md@@ -0,0 +1,47 @@+# Mobile layout++The mobile app runs on phones, foldables, tablets and resizable iPad windows. One rule keeps+that manageable: each layer below makes one decision, and no layer makes another's. A feature+screen never asks which platform or window width it is on.++++++## The layers++1. **Router.** The [root stack](../../apps/mobile/src/Stack.tsx) is the layout state: what is+ selected, what is pushed, which sheet is open. Rotating, folding or resizing renders the same+ stack differently. Nothing remembers which column a page was in. See+ [Mobile navigation](./mobile-navigation.md).+2. **Workspace shell.** The [adaptive layout](../../apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsx)+ owns placement and widths, from the width class in [`layout.ts`](../../apps/mobile/src/lib/layout.ts):+ - _Expanded_: sidebar, content and inspector columns.+ - _Medium_ (600–720pt wide): the sidebar sits beside a list and floats over a page.+ - _Compact_ (under 600pt either way): the sidebar is the root, and pages push.+ - Where the inspector column does not fit, the inspector is a sheet.+3. **Feature screens.** A screen places content by role. It renders its page and declares side+ content with `<Inspector>`, and asks for it with `showInspector()`. The shell decides+ between column and sheet. Choosing a route or a component by width or platform here is the bug+ this structure exists to prevent.+4. **Design system.** Every pane has an `AppBar` with the same contract as a full screen.+ [`PaneContext`](../../apps/mobile/src/components/ui/Pane.tsx) tells the bar which column it is+ in, so it adds that column's controls, such as the sidebar toggle. Chrome branches by platform+ only here.+5. **Native.** On iOS 26, the columns are `UISplitViewController` columns with a navigation bar+ each. On Android and on iPadOS 18–25, the shell draws the same columns in JS from the window+ and hinge metrics.++Platform splits live in layers 1, 2 and 4, as `.ios` and `.android` files.++## Traps++- iPadOS 18–25 runs the JS columns, and the iOS deployment target is 18. Code that looks+ Android-only in the JS column path is still live on those iPads.+- Android renders `Home` twice: in the sidebar column and as the root of the content stack. The+ sidebar copy is never the focused route, so hooks that gate on focus (such as Back handling)+ must also accept `usePaneRole() === "sidebar"`.+- Modals and full-screen pages are presented over the columns and render with no pane role, so+ they get no column chrome.+- A route opened from the inspector sheet must wait for the sheet to close, through+ `InspectorSheetContext`. Presenting over a closing sheet races its dismissal on iOS.diff --git a/docs/internals/mobile-navigation.md b/docs/internals/mobile-navigation.mdindex 33030073d50..65e551fa40c 100644--- a/docs/internals/mobile-navigation.md+++ b/docs/internals/mobile-navigation.md@@ -3,7 +3,8 @@Home and thread routes share the [root native stack](../../apps/mobile/src/Stack.tsx)so UIKit can animate the header within one navigation controller. The iPad sidebarhas its own stack. Splitting Home and threads between controllers loses that-continuous transition.+continuous transition. How the stack becomes columns, sheets and panes is in+[Mobile layout](./mobile-layout.md).## Selecting versus drilling in