feat(mobile): Start screen setting — Home, or where you left off

Settings › Appearance › Start screen (phones): "Where I left off" keeps
the cold-launch landing as it was; "Home" lands on Home on every cold
launch. Switching to another app and back is not a launch and never
moves the user. Stored like the gesture prefs and mirrored natively in
bootstrap.ts so it is back in localStorage before main.tsx reads it. The
Play review of 1.1.15 asked for exactly this; same setting as iPhone
1.9.7 (zennotesiphone 45a72f8).

Author: adibhanna

src/bootstrap.ts

@@ -1,5 +1,5 @@
 import { Preferences } from '@capacitor/preferences'
-import { GESTURES_KEY, HIDE_STATUS_BAR_KEY, LAYOUT_MODE_KEY } from './viewport'
+import { GESTURES_KEY, HIDE_STATUS_BAR_KEY, LAYOUT_MODE_KEY, START_SCREEN_KEY } from './viewport'
 
 const WEB_PREFERENCES_KEY = 'zen:prefs:v2'
 const NATIVE_PREFERENCES_KEY = 'zn-app-preferences-v2'
@@ -10,11 +10,15 @@ const NATIVE_LAYOUT_MODE_KEY = 'zn-layout-mode'
 const NATIVE_HIDE_STATUS_BAR_KEY = 'zn-hide-status-bar'
 // The swipe-gesture assignments (#24) ride along too.
 const NATIVE_GESTURES_KEY = 'zn-gestures'
+// And the Start screen choice (start-screen.ts): read at cold launch, so it
+// must be back in localStorage before main.tsx evaluates.
+const NATIVE_START_SCREEN_KEY = 'zn-start-screen'
 const MIRRORED_KEYS: Record<string, string> = {
   [WEB_PREFERENCES_KEY]: NATIVE_PREFERENCES_KEY,
   [LAYOUT_MODE_KEY]: NATIVE_LAYOUT_MODE_KEY,
   [HIDE_STATUS_BAR_KEY]: NATIVE_HIDE_STATUS_BAR_KEY,
-  [GESTURES_KEY]: NATIVE_GESTURES_KEY
+  [GESTURES_KEY]: NATIVE_GESTURES_KEY,
+  [START_SCREEN_KEY]: NATIVE_START_SCREEN_KEY
 }
 
 let persistenceQueue = Promise.resolve()
@@ -84,6 +88,14 @@ async function restoreNativePreferences(): Promise<void> {
     } else if (webGestures) {
       await Preferences.set({ key: NATIVE_GESTURES_KEY, value: webGestures })
     }
+
+    const nativeStartScreen = await Preferences.get({ key: NATIVE_START_SCREEN_KEY })
+    const webStartScreen = localStorage.getItem(START_SCREEN_KEY)
+    if (nativeStartScreen.value) {
+      localStorage.setItem(START_SCREEN_KEY, nativeStartScreen.value)
+    } else if (webStartScreen) {
+      await Preferences.set({ key: NATIVE_START_SCREEN_KEY, value: webStartScreen })
+    }
   } catch {
     // Continue with WebView storage when native preferences are unavailable.
   }

src/ui-mobile/MobileShell.tsx

@@ -46,6 +46,7 @@ import { installNoteRowGestures, NOTE_ROW_SELECTOR } from './note-row-gestures'
 import { NoteActionSheet } from './note-actions'
 import { installEditorKeyboardScroll } from './editor-keyboard-scroll'
 import { installEditorNativeTyping } from './editor-native-typing'
+import { getStartScreen, setStartScreen, type StartScreen } from './start-screen'
 import { useYouTubeLiteEmbeds } from './youtube-embed-shim'
 import { VaultsSheet, promptNewVault } from './MobileDrawer'
 import {
@@ -673,8 +674,9 @@ function usePhoneLayoutBoot(): void {
       // activeTab (or no snapshot, or an unreadable one) means Home;
       // anything else keeps the restored note/view on screen. `null` — the
       // witness read somehow still in flight — falls back to Home, the
-      // pre-#2 behavior, rather than guessing a note.
-      if (persistedHome !== false) goHome()
+      // pre-#2 behavior, rather than guessing a note. The Start screen
+      // setting (start-screen.ts) overrides all of that with Home.
+      if (persistedHome !== false || getStartScreen() === 'home') goHome()
       // First run only: land IN the seeded welcome note (reading mode — no
       // keyboard) instead of on a Home screen with nothing to do. Home stays
       // one Back tap away. The pane mode is set through the store before the
@@ -2739,6 +2741,50 @@ function SettingsLayoutRow(): React.JSX.Element {
   )
 }
 
+const START_SCREEN_CHOICES: Array<{ value: StartScreen; label: string }> = [
+  { value: 'last', label: 'Where I left off' },
+  { value: 'home', label: 'Home' }
+]
+
+/**
+ * Settings → Appearance → Start screen (island beside Layout / Swipe
+ * gestures, phones only — the landing logic is usePhoneLayoutBoot's). A
+ * user asked for Home instead of the last note after quitting the app.
+ */
+function SettingsStartScreenRow(): React.JSX.Element {
+  const [value, setValue] = useState<StartScreen>(() => getStartScreen())
+  const choose = (next: StartScreen): void => {
+    setStartScreen(next)
+    setValue(next)
+  }
+  return (
+    <div className="zn-settings-layout">
+      <div className="zn-settings-layout-text">
+        <div className="zn-settings-layout-title">Start screen</div>
+        <div className="zn-settings-layout-desc">
+          {value === 'home'
+            ? 'Opening the app lands on Home. Switching to another app and back keeps your place.'
+            : 'Opening the app returns to the note or view you left. Choose Home to start fresh every time.'}
+        </div>
+      </div>
+      <div className="zn-settings-layout-seg" role="radiogroup" aria-label="Start screen">
+        {START_SCREEN_CHOICES.map((choice) => (
+          <button
+            key={choice.value}
+            type="button"
+            role="radio"
+            aria-checked={value === choice.value}
+            className={value === choice.value ? 'is-active' : ''}
+            onClick={() => choose(choice.value)}
+          >
+            {choice.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
 function useLayoutSettingsRow(): void {
   useEffect(() => {
     let container: HTMLElement | null = null
@@ -2777,6 +2823,7 @@ function useLayoutSettingsRow(): void {
           <>
             <SettingsLayoutRow />
             <SettingsSystemBarsRow />
+            {isPhoneWidth() && <SettingsStartScreenRow />}
             {isPhoneWidth() && <SettingsGesturesRow />}
           </>
         )

src/ui-mobile/start-screen.test.ts

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+// The module reads localStorage lazily (inside the functions), so a stub
+// installed before the first call is all node needs.
+const store = new Map<string, string>()
+;(globalThis as { localStorage?: unknown }).localStorage = {
+  getItem: (key: string) => store.get(key) ?? null,
+  setItem: (key: string, value: string) => void store.set(key, value),
+  removeItem: (key: string) => void store.delete(key)
+}
+
+const { DEFAULT_START_SCREEN, getStartScreen, setStartScreen } = await import('./start-screen.ts')
+const { START_SCREEN_KEY } = await import('../viewport.ts')
+
+test('nothing stored means where the user left off', () => {
+  store.delete(START_SCREEN_KEY)
+  assert.equal(getStartScreen(), 'last')
+  assert.equal(DEFAULT_START_SCREEN, 'last')
+})
+
+test('an unknown stored value falls back to the default', () => {
+  store.set(START_SCREEN_KEY, 'jetpack')
+  assert.equal(getStartScreen(), 'last')
+})
+
+test('home persists; the default removes the key', () => {
+  setStartScreen('home')
+  assert.equal(store.get(START_SCREEN_KEY), 'home')
+  assert.equal(getStartScreen(), 'home')
+  setStartScreen('last')
+  assert.equal(store.has(START_SCREEN_KEY), false)
+  assert.equal(getStartScreen(), 'last')
+})

src/ui-mobile/start-screen.ts

@@ -0,0 +1,37 @@
+/**
+ * Where a cold launch lands (user request relayed by Adib, 2026-09-08: "I
+ * wish there was a feature to set the home screen as the start screen
+ * instead of the last note when turning the app off and on again").
+ *
+ * 'last' (the default) keeps the #2 behaviour: the note or view that was
+ * open when iOS killed the app comes back, and Home comes back if that is
+ * where the user left. 'home' lands on Home on every cold launch. Switching
+ * away and back is not a launch and never moves the user — the landing
+ * logic in usePhoneLayoutBoot runs once per process.
+ *
+ * Read lazily, like gestures.ts; the Settings card writes through
+ * setStartScreen and the next launch picks it up. The default removes the
+ * key so a fresh install and a reset look identical.
+ */
+import { START_SCREEN_KEY } from '../viewport.ts'
+
+export type StartScreen = 'last' | 'home'
+
+export const DEFAULT_START_SCREEN: StartScreen = 'last'
+
+export function getStartScreen(): StartScreen {
+  try {
+    return localStorage.getItem(START_SCREEN_KEY) === 'home' ? 'home' : DEFAULT_START_SCREEN
+  } catch {
+    return DEFAULT_START_SCREEN
+  }
+}
+
+export function setStartScreen(next: StartScreen): void {
+  try {
+    if (next === DEFAULT_START_SCREEN) localStorage.removeItem(START_SCREEN_KEY)
+    else localStorage.setItem(START_SCREEN_KEY, next)
+  } catch {
+    // Storage unavailable: the choice applies to this session only.
+  }
+}

src/viewport.ts

@@ -94,6 +94,11 @@ export const HIDE_STATUS_BAR_KEY = 'zn:hide-status-bar'
  *  ui-mobile/gestures.ts. Mirrored natively for the same reason as above. */
 export const GESTURES_KEY = 'zn:gestures'
 
+/** localStorage key for where a cold launch lands ('home'; absent = where
+ *  the user left off), see ui-mobile/start-screen.ts. Mirrored natively
+ *  like the other shell prefs. */
+export const START_SCREEN_KEY = 'zn:start-screen'
+
 
 /** Publish the current decision to CSS. Safe to call repeatedly. */
 export function syncPhoneClass(): void {