# Routing & navigation — handoff

## Summary

React Router drives all app navigation: auth routes, client shell, home/direct/space/inbox/explore paths, room views, lobby/forum feeds, and modal overlays (settings, search, create). Supports hash router mode via client config.

## User-facing behavior

- URL reflects current room, space, inbox tab, explore server
- Mobile vs desktop route layouts (`MobileFriendly` wrappers)
- Deep links and `matrix.to` style joins via join route
- After-login redirect preserves intended destination
- View transitions on supported platforms

## Architecture

```
App.tsx → createRouter(clientConfig, screenSize)
  → Auth routes | ClientLayout + SidebarNav + Outlet
paths.ts — route constants
pathUtils.ts — path builders (getHomeRoomPath, getSpaceDefaultPath, ...)
Router.tsx — route tree + loaders/guards
```

## Key files

| Path | Role |
|------|------|
| `cinny/src/app/pages/Router.tsx` | Full route tree |
| `cinny/src/app/pages/paths.ts` | Path constants |
| `cinny/src/app/pages/pathUtils.ts` | Path builder utilities |
| `cinny/src/app/pages/App.tsx` | RouterProvider setup |
| `cinny/src/app/pages/client/ClientLayout.tsx` | Authenticated layout shell |
| `cinny/src/app/pages/client/SidebarNav.tsx` | Left sidebar tabs |
| `cinny/src/app/pages/MobileFriendly.tsx` | Mobile nav adapters |
| `cinny/src/app/hooks/useRoomNavigate.ts` | Imperative room navigation |
| `cinny/src/app/hooks/useNavToActivePathMapper.ts` | Restore last path |
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Login redirect |
| `cinny/src/app/components/AnimatedOutlet.tsx` | Route transitions |

## Data model

| Key | Purpose |
|-----|---------|
| `navToActivePath` atom | Per-context last URL |
| URL path params | roomId, spaceId, eventId |

## Dependencies

- `react-router-dom` v6
- `clientConfig.hashRouter` for Electron/file protocol

## Integration points

- **forum**: `ForumAwareSpaceLayout`, `ForumFeedPage` routes
- **lobby-forums**: `_LOBBY_PATH`, `Lobby` component
- **join-before-navigate**: `_JOIN_PATH` route
- **local-api**: `setPaarrotNavigate` uses same path utils
- **settings/room-settings**: overlay renderers on client routes

## Testing

### Manual

1. Navigate home → room → back; URL updates correctly.
2. Open space; forum vs lobby path per room type.
3. Hash router mode (if enabled in config).
4. Mobile breakpoints: sidebar vs full-page nav.
5. Refresh on deep room URL — lands in same room.

### Automated

- None

## Known issues & gotchas

- `getSpaceDefaultPath` branches forum vs lobby — must stay in sync with forum handoff
- Hash router needed for some Electron `file://` deployments
- Many path helpers — prefer using `pathUtils` over string concat

## Future work

- Route-level code splitting audit
- Unified join/link handler

## Related docs

- [forum HANDOFF](../forum/HANDOFF.md)
- [lobby-forums HANDOFF](../lobby-forums/HANDOFF.md)
- [join-before-navigate HANDOFF](../join-before-navigate/HANDOFF.md)
- [home-and-sidebar HANDOFF](../home-and-sidebar/HANDOFF.md)

## Add your extra things here

- Key paths: `HOME_PATH`, `DIRECT_PATH`, `SPACE_PATH`, `INBOX_PATH`, `EXPLORE_PATH`, `_FEED_PATH`, `_LOBBY_PATH`
- `getAppPathFromHref` for parsing external links