# Screens & Navigation

> All screens, navigation hierarchy, and deep link paths. See [Architecture](./architecture.md) for context.

## Navigation Hierarchy

```
AppNavigator (Native Stack Navigator)
│
├── OnboardingScreen              # First-run onboarding flow
├── MainTabs (TabNavigator)       # Bottom tab navigator (5 tabs)
│   ├── HomeTab → HomeScreen
│   ├── NotesTab → NotesListScreen
│   ├── ExploreTab → ExploreScreen
│   ├── TodosTab → TodoListScreen
│   ├── SettingsTab → SettingsScreen
│   └── CanvasList → CanvasListScreen  (hidden tab)
│
├── NoteEditorScreen              # Stack screen — note/:noteId
├── CanvasEditorScreen            # Stack screen — canvas/:canvasId
├── ChatThreadListScreen          # Stack screen — chat
├── ChatScreen                   # Stack screen — chat/:threadId
├── SyncStatusScreen             # Stack screen
├── AddReminderScreen            # Stack screen
├── TemplateManagerScreen        # Stack screen
├── RenderStyleSettingsScreen    # Stack screen
├── RenderStyleEditorScreen      # Stack screen
├── GraphViewScreen              # Stack screen
├── PaywallScreen                # Stack screen (interstitial or direct)
├── ThoughtDumpScreen            # Stack screen — thought-dump
├── ImageViewerScreen            # Stack screen
├── FileViewerScreen             # Stack screen
├── PdfViewerScreen              # Stack screen
├── VideoViewerScreen            # Stack screen
├── ExploreCommitScreen          # Stack screen
├── ExploreDiffScreen           # Stack screen
├── ExploreFileScreen            # Stack screen
├── ExploreRepoInfoScreen        # Stack screen
├── ExploreIssuesScreen          # Stack screen
├── ExplorePullRequestsScreen    # Stack screen
└── NeumorphicGallery            # __dev__/neumorphic (dev only)
```

## Deep Linking

GitNotēs uses the custom scheme `gitnotes://` for deep links.

### URL Structure

| Route | URL Pattern | Example |
|-------|------------|---------|
| Note | `gitnotes://note/:noteId` | `gitnotes://note/1699876543-abc123` |
| Canvas | `gitnotes://canvas/:canvasId` | `gitnotes://canvas/1699876543-def456` |
| Chat thread list | `gitnotes://chat` | `gitnotes://chat` |
| Chat thread | `gitnotes://chat/:threadId` | `gitnotes://chat/1699876543-ghi789` |
| Home | `gitnotes://home` | `gitnotes://home` |
| Notes list | `gitnotes://notes` | `gitnotes://notes` |
| Explore | `gitnotes://explore` | `gitnotes://explore` |
| Settings | `gitnotes://settings` | `gitnotes://settings` |
| Thought dump | `gitnotes://thought-dump` | `gitnotes://thought-dump` |

> **Note:** Tab bar screens (Home, Notes, Explore, Todos, Settings) ARE reachable via `gitnotes://home`, `gitnotes://notes`, etc. Universal links (`https://gitnotes.app/...`) require associated domains entitlement configuration — see [Architecture](./architecture.md).

### Actual Route Param Types

The canonical route param types are in `src/navigation/types.ts`:

| Screen | Route Param Type |
|--------|-----------------|
| `NoteEditor` | `{ noteId?, format?, initialTitle?, initialContent?, initialTags?, repo?, branch?, folderPath?, anchor? }` |
| `CanvasEditor` | `{ canvasId?, canvasWidth?, canvasHeight?, canvasTitle? }` |
| `ChatScreen` | `{ threadId: string }` |
| `ThoughtDump` | `{ openVoiceOnMount? }` |
| `Explore` | `{ repoId? }` |
| `ExploreDiff` | `{ repoId: string; path: string }` |
| `ExploreCommit` | `{ repoId: string; commitId: string }` |
| `ExploreFile` | `{ repoId: string; path: string }` |
| `ConflictResolve` | `{ repoId: string; path: string }` *(in types, no screen component — navigation target only)* |
| `PdfViewer` | `{ owner: string; repo: string; branch?; path: string; title? }` |

## Screens

### HomeScreen

**Purpose:** Dashboard with quick access to recent notes, daily quote, and sync status.

**Key components:**
- `BentoRecent` — bento-grid layout of recent notes
- `DailyQuoteCard` — philosopher quote from `DailyQuoteService`
- `QuickAccessShelf` — pinned/favorite notes
- `FloatingGitButton` — floating sync button

---

### NotesListScreen

**Purpose:** Browse and search all notes in the selected repo/folder.

**Key components:**
- `NoteCard` — note preview card with title, excerpt, tags, color
- `NotesFilterModal` — filter by folder, tag, color, date
- `NotesViewModePicker` — list vs grid view toggle
- `ActiveFilterStrip` — shows active filters
- `BulkActionBar` — bulk delete, move, tag operations

**Navigation:** Tapping a note → `NoteEditorScreen`. Long-press → context menu.

---

### NoteEditorScreen

**Purpose:** Full note editing with toolbar, tag input, and AI assist.

**Key components:**
- `NoteEditorForm` — main editor (Markdown input)
- `EditorToolbar` — formatting toolbar (bold, italic, heading, list, code)
- `EditorHeader` — title input, folder breadcrumb
- `MarkdownBody` — rendered Markdown preview pane
- `TagInput` — tag editor
- `BacklinksSection` — notes that link to this note
- `FloatingAIButton` — AI assist trigger

**States:** Editing, Preview, Split (edit + preview side-by-side)

---

### TodoListScreen

**Purpose:** Browse, filter, and manage todos.

**Key components:**
- `TodoCard` — todo with checkbox, title, due date, tags
- `TodoEditorModal` — create/edit todo
- `TodosListHeader` — filter tabs (All, Today, Upcoming, Overdue)

---

### CanvasListScreen

**Purpose:** Browse all canvas documents.

**Key components:**
- `CanvasThumbnail` — grid thumbnail of canvas
- `CanvasPreview` — preview on tap
- `CanvasPickerModal` — embed canvas picker in note editor

**Navigation:** Tapping → `CanvasEditorScreen`

---

### CanvasEditorScreen

**Purpose:** Infinite canvas with tile-based layout, drawing, and AI vision.

**Key components:**
- Sparse tile canvas (handled by native Skia/canvas layer)
- `AtlasComposer` — tile composition
- `HotspotGrid` — tappable regions
- AI vision toolbar (OCR, object detection)

---

### ChatScreen

**Purpose:** AI chat with context from the current note or repo.

**Key components:**
- `ChatMessageBubble` — user and AI message bubbles
- `ChatInputBar` — message input with send button
- `FloatingAIHubMenu` — AI provider picker
- `ContextPickerModal` — pick which note/repo to chat about
- `ModelSelector` — pick AI model

---

### ChatThreadListScreen

**Purpose:** List all AI chat threads.

**Key components:**
- `ChatThreadCard` — thread preview with last message, timestamp
- `ChatThreadContextMenu` — delete, rename thread

---

### ExploreScreen

**Purpose:** Git repository explorer — view commits, diffs, files, branches, and pull requests. Branch-aware: shows the active checked-out branch from `activeBranchStore`, and all branch operations are routed through `GitBranchCoordinator` for checkout safety.

**Wraps ExploreScreen** — gates mutation operations during branch checkout via `CheckoutSafetyProvider`. Components inside can call `useCheckoutSafety()` to access checkout state and show blocking overlays.

**Git → Branches ownership:** The Explore tab (Git UI) is the sole authority for branch operations. The Git tab owns all branch state — no external UI (note editors, sync services, or other tabs) may trigger or control branch switches. Note editing never triggers implicit branch switches.

**Branch UI:** Only the Explore screen exposes branch selection. No branch selector exists in the note editor or elsewhere. When checking out a remote branch, GitBranchCoordinator fetches the remote ref first and retries checkout locally.

**Sections:**
- `FilesSection` — repo file tree
- `ChangesSection` — unstaged/staged changes in working tree
- `StagingSection` — staged files ready to commit
- `CommitsSection` — recent commit history
- `BranchesSection` — local and remote branches; checkout via `GitBranchCoordinator`
- `RemotesSection` — configured remotes
- `ConflictsSection` — unresolved merge conflicts
- `PullRequestsSection` — open PRs (GitHub only)
- `IssuesSection` — repo issues (GitHub only)
- `RepoInfoSection` — repo metadata (name, URL, branch, ahead/behind)

---

### ExploreCommitScreen

**Purpose:** View a single commit — message, author, changed files, diff.

**Route params:** `{ repoId: string; commitId: string }`

**Navigation:** Tapped from `ExploreScreen` commit list.

---

### ExploreDiffScreen

**Purpose:** View diff between two commits or branch state.

**Route params:** `{ repoId: string; path: string }` — `path` is the file path

**Navigation:** Tapped from `ExploreScreen` changes list.

---

### ExploreFileScreen

**Purpose:** View and edit a text file from the local working tree. Binary files and LFS pointer files are read-only. Text files are editable as plain text via a multiline editor.

**Route params:** `{ repoId: string; path: string }`

**Save behavior:** Save writes raw UTF-8 content directly to the working tree without staging, committing, or pushing. The file appears as an unstaged modification in the Git workspace. User reviews, stages, commits, and pushes from the existing Git workspace.

**Navigation:** Tapped from `ExploreScreen` file tree.

---

### SettingsScreen

**Purpose:** App settings hub.

**Sections:**
- Account management (`AccountsContext`)
- GitHub connection (`GitHubAuthContext`)
- Theme selection (`ThemeContext`)
- Sync settings (`ForegroundSyncSettings`)
- Notification preferences
- Pro/paywall access (`PaywallScreen`)
- Biometric lock toggle (`BiometricLockContext`)
- Language (i18n)

---

### SyncStatusScreen

**Purpose:** Detailed sync status — pending changes, last sync time, push/pull controls.

**Navigation:** From `SettingsScreen` or floating git button.

---

### OnboardingScreen

**Purpose:** First-run setup — clone a repo or create a new one.

**Flow:**
1. Welcome + feature intro
2. GitHub sign-in (optional)
3. Clone existing repo or create new
4. Initial sync
5. Done → `HomeScreen`

---

### PaywallScreen

**Purpose:** Pro subscription purchase UI.

**Components:**
- `PaywallPlanGrid` — monthly/yearly/lifetime plan cards
- `PaywallFeatureGrid` — feature comparison (free vs Pro)
- Purchase flow handled by `RevenueCatService`
- Restore purchases button

---

### GraphViewScreen

**Purpose:** Note/wiki-link graph visualization.

---

### RenderStyleSettingsScreen / RenderStyleEditorScreen

**Purpose:** Configure how notes are rendered (Markdown, rich text, plaintext).

---

### TemplateManagerScreen

**Purpose:** Create and manage note templates.

**Key components:**
- `TemplateListItem` — template preview
- `TemplateEditorModal` — create/edit template

---

### ThoughtDumpScreen

**Purpose:** Rapid capture mode — voice or text input that dumps into a note as stream-of-consciousness.

**Flow:** User talks/types → captured as draft note → saved to selected repo.

---

### ImageViewerScreen / FileViewerScreen / PdfViewerScreen / VideoViewerScreen

**Purpose:** Full-screen viewer for attachments.

**Supported formats:**
- Images: JPEG, PNG, GIF, WebP, HEIC
- Files: generic file preview
- PDF: multi-page PDF renderer
- Video: MP4, MOV (native playback)

---

### BiometricLockScreen

**Purpose:** App lock screen shown when app returns from background.

**Trigger:** `BiometricLockContext` — enabled in settings.

---

## See Also

- [Navigation types](../../navigation/types.ts) — TypeScript type definitions for route params
- [Architecture](./architecture.md) — Context