# Architecture

## Quick Start

```bash
npm start         # dev server on :8080
npm run build     # production build → dist/
npm run lint      # eslint + prettier
npm run typecheck # tsc --noEmit
```

Build: **Vite 5.4** with vanilla-extract, WASM, PWA plugins.

> **Note:** `.husky/pre-commit` is currently commented out. `npm run check:eslint` is **green** (0 errors, 116 warnings — kept as warn for `no-explicit-any`/`no-non-null-assertion` policy). `npm run typecheck` still has ~32 known errors (residual project bugs after the TS 5.4 + Bundler migration that cleared ~800 module-resolution errors — see `docs/known-tech-debt-lint/`). Use `bash docs/known-tech-debt-lint/diff.sh` to verify your changes added no new typecheck errors, then `npm run build` for the green build check.

## Source Layout

```
src/
├── index.tsx                    # Entry point
├── colors.css.ts                # Custom dark-theme via createTheme(color, …); no light override (uses folds.lightTheme as-is)
├── config.css.ts                # fontWeight overrides
├── client/
│   ├── initMatrix.ts            # Matrix SDK init (createClient, startClient, logout)
│   └── secretStorageKeys.js     # Crypto callbacks
├── types/matrix/                # Matrix protocol types (room.ts, accountData.ts, common.ts)
└── app/
    ├── i18n.ts                  # i18next config
    ├── pages/
    │   ├── App.tsx              # Root component (providers, config loader)
    │   ├── Router.tsx           # createBrowserRouter / createHashRouter, all routes
    │   └── MobileFriendly.tsx   # MobileFriendlyClientNav + MobileFriendlyPageNav (responsive split)
    ├── features/                # Feature modules
    ├── components/              # Shared components
    ├── hooks/                   # ~117 custom hooks
    ├── state/                   # Jotai atoms
    ├── plugins/                 # Content plugins
    ├── utils/                   # Utilities
    └── styles/                  # Vanilla-extract global styles
```

## Pages & Routing (`src/app/pages/`)

Router in `Router.tsx`. Each top-level tab (`/home/`, `/direct/`, `/space/...`, `/explore/`, `/inbox/`) is wrapped in `PageRoot` with a `nav` prop (the tab's PageNav — e.g. `Home`, `Direct`) and an `<Outlet/>` for the active room/sub-route.

- **Auth** (`auth/login/`, `auth/register/`, `auth/reset-password/`) — NOTE: bistable layout fragility, see `bugs.md`. Recent fixes: c466848, e6623b2, cf5ee9a, 9b41cbb. **Don't change `body`/`#root` background CSS-vars** — auth uses computed sizes for safe-area painting.
- **Client** (`client/`) — main layout after login (wrapped by `ClientLayout` = nav + content)
  - `home/` — Home timeline (path: `/home/`, root `/` redirects here)
  - `direct/` — DMs (path: `/direct/`)
  - `space/` — Space view (path: `/:spaceIdOrAlias/`)
  - `explore/` — Public rooms (path: `/explore/`)
  - `inbox/` — Notifications, invites (path: `/inbox/`)
  - `create/` — New room/space (path: `/create/`)
  - `sidebar/` — Tab components (`HomeTab`, `DirectTab`, `SpaceTabs`, `ExploreTab`, `CreateTab`, `SearchTab`, `UnverifiedTab`, `InboxTab`, `SettingsTab`)
  - `WelcomePage.tsx` — Empty state (vojo SVG + version). **Mobile is intentionally null** at the index route (`{mobile ? null : <Route index element={<WelcomePage />} />}`) — by design, not a bug.
  - `SidebarNav.tsx` — global 66px icon-rail (DirectTab, HomeTab, SpaceTabs, …, sticky bottom: SearchTab, UnverifiedTab, InboxTab, SettingsTab)
  - `SyncStatus.tsx`, `SpecVersions.tsx` — Connection status

### DM-specific routing path

```
/direct/:roomIdOrAlias
  → PageRoot (nav=Direct, outlet=…)
    → DirectRouteRoomProvider (sets IsDirectRoomProvider=true, runs useAutoDirectSync)
      → Room.tsx (RoomViewHeader + RoomView, screen-size branching for MembersDrawer)
        → RoomTimeline + RoomViewTyping + RoomInput
```

`useAutoDirectSync` (commit 84eeac9) round-trips `m.direct` on join — **important**: for invited users the room renders first as non-direct, then flips to direct when sync resolves. Any DM-only branching must therefore go through the **shared four-source predicate `isDirectStreamRoom(mx, room, mDirects)` in [src/app/utils/room.ts](../../src/app/utils/room.ts)** (introduced in DM redesign P3a). The four sources, all synchronous and first-frame-safe, are:

1. `mDirectAtom.has(roomId)` — returning user, populated on first paint via `IndexedDBStore.startup()` await before `startClient()`. Hydrated by `useBindMDirectAtom` from a `useEffect`, so empty for one frame on cold start.
2. `room.getDMInviter()` — matrix-js-sdk SDK helper for invite-state with `is_direct: true` in member content's `prev_content`.
3. `isDirectInvite(room, myUserId)` — reads current member content for `is_direct: true`, covering the just-joined case before `useAutoDirectSync` round-trips.
4. `mx.getAccountData('m.direct')` — direct SDK fallback for the cold-start one-frame race when the atom is still being hydrated; the SDK has the data synchronously after `IndexedDBStore.startup()`.

Four call sites use this predicate symmetrically: `useIsDirectStream(room)` (render-side gate in `RoomTimeline.tsx`), `HomeRouteRoomProvider` (cold-start push redirect from `/home/{DM}/` to `/direct/`), `DirectRouteRoomProvider` (validates the destination), `useRoomNavigate.navigateRoom` (imperative routing). All four agree on the first frame so cold-start push for an invited DM lands on `/direct/` with the Stream layout already mounted, no transient `JoinBeforeNavigate` flash.

For the per-row Stream gate, prefer the `isStream` prop chain (RoomTimeline computes `useIsDirectStream(room)` once and threads it through `<Message>` / `<Event>` props) over calling the hook per row — this avoids subscribing every row to the `mDirectAtom` in non-DM rooms. Don't gate on `useIsDirectRoom()` alone — it misses the invited-user case. Bridged Telegram DMs that lack `is_direct: true` on invite are deferred to a future plan (separate Telegram tab/namespace). See `docs/plans/dm_1x1_redesign.md` §6.5 for the full rationale.

## Features (`src/app/features/`)

| Dir | Purpose |
|-----|---------|
| `room/` | Core room view — **RoomTimeline.tsx** (~1890 LOC), **RoomInput.tsx** (~691 LOC), **RoomViewHeader.tsx** (~587 LOC), MembersDrawer, MessageEditor, RoomTombstone, RoomViewTyping, CallChatView, CommandAutocomplete |
| `room/message/` | `Message.tsx` (~1335 LOC) — selects layout per the `isStream` prop (DM rooms → `<StreamLayout/>`) or per the persisted `messageLayout` setting (non-DM → Compact/Bubble/Modern), renders edit/delete/react menu, mention/hashtag links, reactions viewer. The DM-stream gate is computed once in `RoomTimeline.tsx` via `useIsDirectStream(room)` and threaded as a prop so we don't subscribe every row to `mDirectAtom`. |
| `room-nav/` | `RoomNavItem.tsx` (~435 LOC) — list-row component, used by Home/Direct/Spaces. Carries call-room behaviour (`useCallSession`, `useCallMembers`, `useCallStart`) |
| `room-settings/` | Room-specific settings page |
| `common-settings/` | Shared settings: general, members, permissions, emojis-stickers, developer-tools |
| `space-settings/` | Space-specific settings |
| `settings/` | User settings (general, account, notifications, devices, emojis, about, dev-tools). The `MessageLayout` dropdown was removed in DM redesign P3a — non-DM rooms still honour the persisted enum, but no UI surfaces it. General now hosts a `Settings.message_spacing_dm_note` description explaining the spacing override in DM rooms. **Logout lives here only.** |
| `lobby/` | Space/room lobby view |
| `search/` | Global search |
| `message-search/` | In-room message search |
| `create-chat/` | DM creation flow (recent commit 58ec12d split it into username + server fields) |
| `create-room/` | Room creation |
| `create-space/` | Space creation |
| `add-existing/` | Join existing rooms |
| `join-before-navigate/` | Pre-join navigation logic |
| `call/` | Element Call integration. **Vojo-DM voice call lifecycle lives here** (phases 0..5.35). Don't touch unless redesigning calls. |
| `call-status/` | Call state display + IncomingCallStrip (mounted as sibling in `Router.tsx:184`, **not** inside RoomViewHeader). |

### Virtualization in features/room/

`RoomTimeline.tsx` does **not** use `@tanstack/react-virtual`. It uses **`useVirtualPaginator`** + `IntersectionObserver` for pagination + scroll-anchoring. There is no `estimateSize` to retune; row heights are measured live. (The tanstack `useVirtualizer` is used elsewhere — e.g. `Direct.tsx:199` for the DM-list column with `estimateSize: () => 38`.)

## Key Components (`src/app/components/`)

- `message/` — Message rendering. Layout variants live in `message/layout/{Modern,Compact,Bubble,Stream}.tsx` + `layout.css.ts` recipes. **DM rooms** render the Stream layout unconditionally (gated by `useIsDirectStream` four-source predicate, see DM-specific routing path above). **Non-DM rooms** select per `MessageLayout` enum in `state/settings.ts` (Modern=0, Compact=1, Bubble=2). `EventContent.tsx` has its own layout switch for membership/state events plus a `IsStreamProvider` context that flips it to the thin Stream sysline render in DM rooms.
- `message/MessageStatus.tsx` — **Vojo-specific**: WhatsApp-style delivery checkmarks (commit 0c4cfb9). Pairs with `hooks/useMessageStatus.ts` (receipt-derivation).
- `editor/` — Slate-based rich text editor. Autocomplete: `RoomMentionAutocomplete`, `UserMentionAutocomplete`, `EmoticonAutocomplete`, `CommandAutocomplete`. `Editor.tsx` is the Slate root — preserve.
- `emoji-board/` — Emoji picker
- `image-pack-view/` — Custom emoji pack management
- `image-viewer/`, `Pdf-viewer/` — Media viewers
- `sidebar/` — `Sidebar.tsx` (66px wrapper), `SidebarItem.tsx`, `SidebarStack.tsx`, `SidebarContent.tsx`, `Sidebar.css.ts`
- `user-profile/` — User info, power chips, moderation
- `member-tile/` — Member list items
- `power/` — Power level UI
- `upload-card/` — Upload progress cards
- `url-preview/` — Link previews
- `page/` — Page layout wrapper (`Page`, `PageRoot`, `PageNav`, `PageHeader`, `PageContent`, `PageHero`)
- `setting-tile/` — Settings list item pattern
- `sequence-card/`, `cutout-card/` — Card layouts
- `uia-stages/` — User-interactive auth stages (email, captcha, token)
- `room-intro/` — Room introduction card
- `invite-user-prompt/`, `join-address-prompt/`, `leave-room-prompt/` — Dialogs
- `BackRouteHandler.tsx` — Web back-button → back-stack collapse via `replace` (commit dce6be9)

## Vojo-specific code paths (preserve when redesigning)

These are vojo additions on top of stock Cinny — they crossed many recent stabilization commits and are now load-bearing.

| Path | Commits | Notes |
|---|---|---|
| `features/room/RoomViewHeader.tsx::DmCallButton` | calls phases 0-5.35 | Outgoing DM voice call entry point |
| `features/call/*` (CallEmbed, CallView) | 91afffc, e8188d7, fab533e | Element Call widget; **don't unmount/remount the widget root on header redesign** — Android FGS is keyed on `joined` state |
| `features/call-status/IncomingCallStrip.tsx` | dabe5ca, 91afffc | Mounted as sibling in `Router.tsx:184` (not inside header). Decline / accept / mid-ring backgrounding handled here |
| `state/callEmbed.ts` (`callEmbedAtom`, `callChatAtom`) | call phases | Embed lifecycle |
| `components/message/MessageStatus.tsx` + `hooks/useMessageStatus.ts` | 0c4cfb9 | WhatsApp checkmarks |
| `hooks/usePushNotifications.ts` | dabe5ca, 84eeac9 | Push tap routing: warm web/native paths resolve DMs to Direct via `navigateRoom` / `getDirectRoomPath` (lines 309 / 387); SW cold-start opens `/home/{roomId}/` and `HomeRouteRoomProvider` redirects to `/direct/` when `mDirectAtom` has the room. FSI hand-off |
| `hooks/useRoomNavigate.ts` | dce6be9 | Back-stack collapse via `replace`. **Path-based** (`pathnameRef.current === target ? replace : push`, line 49-55) — not tab-ID-keyed, so removing `*Tab.tsx` rendering does not break back-stack |
| `hooks/useAndroidBackButton.ts`, `components/BackRouteHandler.tsx` | dce6be9 | Hardware back integration |
| `hooks/useAutoDirectSync.ts` + `utils/matrix.ts` | 84eeac9 | m.direct sync on join (DM rooms shown correctly for invited users) |
| `pages/auth/*` | c466848, e6623b2, cf5ee9a, 9b41cbb | Bistable layout — don't change body/root background CSS-vars; see `bugs.md` |
| `MainActivity.java::EdgeToEdge.enable(this)` + `src/index.css` lines 45-65 + `styles.xml` `windowLayoutInDisplayCutoutMode=shortEdges` | 1edaf60 | **Android edge-to-edge compensation** (white-bar fix). WebView draws under status/nav bars; compensation triad: `body { background-color: var(--oq6d070) }` (currently folds `color.Background.Container` — **but `--oq6d070` is folds@2.6.2 internal implementation detail, not public API**; can break on folds upgrade), `#root { padding: env(safe-area-inset-*) }`, and the manifest cutout mode. Break any one and white bars return or status text overlaps content. **DM redesign P0 replaces with Vojo-owned `--vojo-safe-area-bg` variable** + matching `WindowCompat.setAppearanceLight{Status,Navigation}Bars(false)` in `MainActivity.onCreate` to keep system-bar icons visible across uiMode. See `dm_1x1_redesign.md` §6.6 / R13 (safe-area var) and R19 (Android icon tint) for full risk matrix. |
| `scripts/gen-push-strings.mjs` + `android/app/build.gradle` | 19d3dc0, 7af04a4 | Gradle task generates `push_strings.xml` from i18n `Push.json`. **Don't put non-push i18n keys in the `Push` namespace** or they leak into lockscreen XML. EN+RU must be added together (web SW falls back to EN if RU missing) |
| `android/app/src/main/java/**` | calls phases 5.35 | FGS, FCM, ring registry, declined-IDs tracker |

## State Management

**Jotai** atoms in `src/app/state/`:

- `settings.ts` — User preferences (`MessageLayout` enum: Modern=0, Compact=1, Bubble=2; `themeId`, `useSystemTheme`, `monochromeMode`, …). Persisted to `localStorage['settings']`. The `MessageLayout` enum is canonical for non-DM rooms; **DM rooms ignore it entirely** and force the Stream layout regardless. The default for new users is `MessageLayout.Bubble`.
- `sessions.ts` — Active session
- `upload.ts` — Upload progress (in-memory)
- `room/` — `roomInputDrafts` (in-memory), `roomToParents`, `roomToUnread`
- `room-list/` — `roomList`, `mDirectAtom`, `inviteList`, sorting/filtering
- `callEmbed.ts` — `callEmbedAtom`, `callChatAtom` (call lifecycle)
- `closedNavCategories.ts` — `closedNavCategoriesAtom` (collapsed/expanded folders)

Some atoms persist to localStorage (e.g. `settings.ts`, `navToActivePath.ts`), others are in-memory only (e.g. `upload.ts`, `roomInputDrafts.ts`). Access via hooks in `state/hooks/`.

## Theming

Stock Cinny had multiple themes; vojo simplified to System / Light / Dark (commit 00935ae).

- `src/colors.css.ts` defines **only** `darkTheme` via `createTheme(color, darkThemeData)`. There is no separate light-theme override — light = stock `folds.lightTheme` imported as-is.
- `src/app/hooks/useTheme.ts` selects `LightTheme` or `DarkTheme` based on `useSystemTheme` + `themeId` settings. Class-name-based application — **runtime theme switch requires page reload** (vanilla-extract is compile-time).
- Folds tokens (`color.*`, `config.space`, `config.radii`, `config.borderWidth`) are read-only inside folds compiled CSS. Re-skinning colours via `createTheme()` works; re-skinning radii or spacing requires CSS overrides outside folds.
- Brand accent in v4.11.x: `Primary.Main = #BDB6EC` (lavender) — referenced in unread-badge, focus-ring, NavLink active state, MessageBase highlight keyframe.

## Responsive design

**No CSS media queries** for layout. Responsive behaviour goes through `hooks/useScreenSize.ts`:

```ts
ScreenSize.Mobile  // ≤750px
ScreenSize.Tablet  // >750 ≤1124px
ScreenSize.Desktop // >1124px
```

`useScreenSizeContext()` returns the current size; components branch their JSX on it.

`pages/MobileFriendly.tsx` provides two wrappers:

- **`MobileFriendlyClientNav`** — hides global `SidebarNav` on Mobile unless URL matches a top-level route (`/home/`, `/direct/`, `/{spaceId}/`, `/explore/`, `/inbox/`)
- **`MobileFriendlyPageNav`** — hides per-tab `PageNav` (e.g. the Direct chat list) on Mobile unless URL matches the exact root path (e.g. exactly `/direct/`)

Result: on Mobile, navigating to a room hides both nav levels — only RoomView is visible. Back-button via `useRoomNavigate` collapses these into the back-stack via `history.replace` (commit dce6be9).

The only CSS `@media` queries in the app target `(hover: hover) and (pointer: fine)` to disable hover-only effects on touch devices.

## Matrix SDK Patterns

```tsx
const mx = useMatrixClient();                               // Get SDK instance
const room = useRoom();                                     // Current room
const isDirect = useIsDirectRoom();                         // From IsDirectRoomProvider context
const stateEvent = useStateEvent(room, StateEvent.Type);    // Room state
const powerLevels = usePowerLevels(room);                   // Permissions
```

## i18n

i18next + `react-i18next`. Translations in `public/locales/{en,ru}/*.json`, organised by namespace (`Direct`, `Room`, `Settings`, `Push`, …).

- **`Push` namespace is special**: `scripts/gen-push-strings.mjs` (run as a Gradle task, commit 19d3dc0) reads it and emits `android/app/src/main/res/values{,-ru}/push_strings.xml` for Android lockscreen. **Don't put non-push UI keys in `Push`.** UI strings → `Direct`/`Room`/`User`/etc.
- Web SW push falls back to **EN** if a key is missing in RU. Always add EN + RU in the same commit.
- Russian-language quality: see `i18n.md` for tone, register, verb-vs-noun rules.

## Key Libraries

- **React 18.2** + React Router DOM 6
- **matrix-js-sdk 38.2** — Matrix protocol
- **folds 2.6** — UI component library
- **jotai 2.6** — State management
- **vanilla-extract** — Type-safe CSS (compile-time → no runtime theme switching without reload)
- **slate 0.123** — Rich text editor
- **@tanstack/react-query 5** — Data fetching
- **@tanstack/react-virtual 3** — Virtual scrolling — used for **list panels** (`Direct.tsx`, `Home`, etc.). Note: `RoomTimeline.tsx` does NOT use this; it uses an in-house `useVirtualPaginator` + `IntersectionObserver`.
- **i18next 23 + react-i18next 15** — Localisation
- **Capacitor 8.3** — Native Android wrapper
- **@capacitor/browser 8.0** — External link handling in native
- **vite-plugin-pwa** — Custom service worker via `injectManifest` strategy with `injectionPoint: undefined` (`vite.config.js:132-140`). **No automatic Workbox precache** — the SW is hand-written in `src/sw.ts`, vite-pwa just builds and registers it. There is no precache size limit to worry about; new font assets are loaded on demand via fetch, not bundled into a precache manifest.
- **`@fontsource/inter`** in `dependencies`. Other `@fontsource/*` additions must also go in `dependencies` (not dev) to land in production bundle.

## Git

- Main branch: `dev`
- Current vojo work branch: `vojo/dev`
- Semantic-release on `dev` branch
- CI: GitHub Actions (build, deploy, docker, netlify)
- **Husky pre-commit is currently disabled** — `npm run typecheck` and `npm run check:eslint` do not run automatically. `check:eslint` is green; `typecheck` still has ~32 known errors. Use `bash docs/known-tech-debt-lint/diff.sh` to check your changes don't add new typecheck errors. Re-enable husky once typecheck residual is cleared.
- **Android `versionCode` is monotonic** (commit 8064760, derived from commit count). Don't squash or rebase across release boundaries — Play store rejects downgrades
- **Commit message style** (vojo memory): one sentence ≤25 words; no body; no Co-Authored-By trailer

## Build & deploy

- Web: `npm run build` → `dist/` → `scp` to `~/vojo/cinny/` on the production VPS (Caddy serves it)
- Android debug: `npm run build:android:debug` (composite of `npm run build && npm run android:sync && cd android && ./gradlew assembleDebug`)
- Android release / AAB: similar but `assembleRelease` / `bundleRelease`
- VSCode task `Deploy to vojo.chat` (Ctrl+Shift+D) automates web deploy
- Android-specific build chain, edge-to-edge, safe-area, FGS, FCM ring registry, push-strings Gradle task — see `android.md`