@devries-cameron20 / t3code Mirror · read-only / commits / 0444aae902
Fork 0

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 +![Wide window as five stacked layers: router, workspace shell, feature screens, design system, native](./images/mobile-workspace-split.png)
8 +
9 +![A compact Android screen as the same five layers](./images/mobile-layers.png)
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