The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 04:30 UTC
docs(mobile): the five layers of the mobile layout, with x-ray diagrams (#27107)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 3, 2026 at 16:53 UTC
0444aae90284c5482838b96bca633a9bc0616342
5 files changed
+50
-1
docs/README.md
+1
@@ -52,6 +52,7 @@ source alone does not explain. Most code changes do not need an internal documen
52
- [Environment auth](./internals/environment-auth.md)
53
- [T3 Connect](./internals/t3-connect.md)
54
- [Assistant citations](./internals/assistant-citations.md)
55
+- [Mobile layout](./internals/mobile-layout.md)
56
- [Mobile navigation](./internals/mobile-navigation.md)
57
- [Mobile development lifecycle](./internals/mobile-development.md)
58
- [Terminal runtime](./internals/terminal-runtime.md)
docs/internals/images/mobile-layers.png
Binary files /dev/null and b/docs/internals/images/mobile-layers.png differ
docs/internals/images/mobile-workspace-split.png
Binary files /dev/null and b/docs/internals/images/mobile-workspace-split.png differ
docs/internals/mobile-layout.md
new
+47
@@ -0,0 +1,47 @@
1
+# Mobile layout
2
+
3
+The mobile app runs on phones, foldables, tablets and resizable iPad windows. One rule keeps
4
+that manageable: each layer below makes one decision, and no layer makes another's. A feature
5
+screen never asks which platform or window width it is on.
6
+
7
+
8
+
9
+
10
+
11
+## The layers
12
+
13
+1. **Router.** The [root stack](../../apps/mobile/src/Stack.tsx) is the layout state: what is
14
+ selected, what is pushed, which sheet is open. Rotating, folding or resizing renders the same
15
+ stack differently. Nothing remembers which column a page was in. See
16
+ [Mobile navigation](./mobile-navigation.md).
17
+2. **Workspace shell.** The [adaptive layout](../../apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsx)
18
+ owns placement and widths, from the width class in [`layout.ts`](../../apps/mobile/src/lib/layout.ts):
19
+ - _Expanded_: sidebar, content and inspector columns.
20
+ - _Medium_ (600–720pt wide): the sidebar sits beside a list and floats over a page.
21
+ - _Compact_ (under 600pt either way): the sidebar is the root, and pages push.
22
+ - Where the inspector column does not fit, the inspector is a sheet.
23
+3. **Feature screens.** A screen places content by role. It renders its page and declares side
24
+ content with `<Inspector>`, and asks for it with `showInspector()`. The shell decides
25
+ between column and sheet. Choosing a route or a component by width or platform here is the bug
26
+ this structure exists to prevent.
27
+4. **Design system.** Every pane has an `AppBar` with the same contract as a full screen.
28
+ [`PaneContext`](../../apps/mobile/src/components/ui/Pane.tsx) tells the bar which column it is
29
+ in, so it adds that column's controls, such as the sidebar toggle. Chrome branches by platform
30
+ only here.
31
+5. **Native.** On iOS 26, the columns are `UISplitViewController` columns with a navigation bar
32
+ each. On Android and on iPadOS 18–25, the shell draws the same columns in JS from the window
33
+ and hinge metrics.
34
+
35
+Platform splits live in layers 1, 2 and 4, as `.ios` and `.android` files.
36
+
37
+## Traps
38
+
39
+- iPadOS 18–25 runs the JS columns, and the iOS deployment target is 18. Code that looks
40
+ Android-only in the JS column path is still live on those iPads.
41
+- Android renders `Home` twice: in the sidebar column and as the root of the content stack. The
42
+ sidebar copy is never the focused route, so hooks that gate on focus (such as Back handling)
43
+ must also accept `usePaneRole() === "sidebar"`.
44
+- Modals and full-screen pages are presented over the columns and render with no pane role, so
45
+ they get no column chrome.
46
+- A route opened from the inspector sheet must wait for the sheet to close, through
47
+ `InspectorSheetContext`. Presenting over a closing sheet races its dismissal on iOS.
docs/internals/mobile-navigation.md
+2
-1
@@ -3,7 +3,8 @@
3
Home and thread routes share the [root native stack](../../apps/mobile/src/Stack.tsx)
4
so UIKit can animate the header within one navigation controller. The iPad sidebar
5
has its own stack. Splitting Home and threads between controllers loses that
6
-continuous transition.
6
+continuous transition. How the stack becomes columns, sheets and panes is in
7
+[Mobile layout](./mobile-layout.md).
8
9
## Selecting versus drilling in
10