# Architecture

> Last actualized 2026-05-30 against the code on `vojo/dev` (HEAD `a84c5341`). The
> Dawn redesign that this doc tracks has progressed well past the "P3c" baseline
> the older revision described: **Channels**, **Bots**, **threads**, a first-class
> **/settings/** route, the **mobile swipe pager**, and the **share-target** flow
> have all shipped. Where a plan doc (`docs/plans/*.md`) says something was
> "deferred", check the code first — much of it landed.

## Quick Start

```bash
npm start         # dev server on :8080 (strictPort, host:true)
npm run build     # production build → dist/
npm run lint      # check:eslint (eslint --max-warnings 0 src) + check:prettier
npm run typecheck # tsc --noEmit
```

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

> **Note:** `.husky/pre-commit` runs `tsc --noEmit` + `lint-staged` (which calls `eslint --max-warnings 0` on staged JS/TS files — NOT the full `npm run lint`). Both gates are zero: `npm run typecheck` and `npm run check:eslint` are green. Custom Matrix event-types live in [`src/types/matrix/sdkAugmentation.d.ts`](../../src/types/matrix/sdkAugmentation.d.ts) — it augments `AccountDataEvents` with `in.vojo.spaces`, `io.element.recent_emoji`, `im.ponies.user_emotes`, `im.ponies.emote_rooms` and `StateEvents` with `im.ponies.room_emotes`, `in.vojo.room.power_level_tags`, `m.bridge`, `uk.half-shot.bridge` (all typed `unknown`; callsites use `.getContent<T>()`). Add new custom event-type strings there to keep `mx.getAccountData` / `mx.getStateEvent` type-safe.

## Source Layout

```
src/
├── index.tsx                    # Entry point (calls pushSessionToSW, capacitor/electron link handlers)
├── colors.css.ts                # darkTheme (Dawn) + lightTheme (Vojo) via createTheme(color, …) — both Vojo-owned
├── config.css.ts                # onDarkFontWeight / onLightFontWeight overrides
├── sw.ts                        # hand-written service worker (auth media, push, language bridge)
├── sw-session.ts                # pushSessionToSW(): re-posts setSession on controllerchange
├── client/
│   ├── initMatrix.ts            # Matrix SDK init (createClient, startClient, logout)
│   └── secretStorageKeys.js     # Crypto callbacks
├── types/matrix/                # Matrix protocol types + sdkAugmentation.d.ts
└── app/
    ├── i18n.ts                  # i18next config (single-file locales)
    ├── pages/
    │   ├── App.tsx              # Root component (ScreenSizeProvider, query client, config loader)
    │   ├── Router.tsx           # createBrowserRouter / createHashRouter, all routes (~497 LOC)
    │   ├── paths.ts             # canonical path constants (DIRECT_PATH, CHANNELS_*, BOTS_*, …)
    │   ├── pathUtils.ts         # getXxxPath builders
    │   ├── ThemeManager.tsx     # UnAuthRouteThemeManager + AuthRouteThemeManager (body-class swap)
    │   ├── HorseshoeContainer.tsx   # app-shell wrapper + bottom call rail + share strip
    │   ├── CallStatusRenderer.tsx / IncomingCallStripRenderer.tsx  # global call surfaces
    │   ├── MobileFriendly.tsx   # MobileFriendlyPageNav (live) + MobileFriendlyClientNav (dead)
    │   └── client/              # per-tab pages (direct, channels, bots, explore, space, home, create, settings, sidebar)
    ├── features/                # Feature modules
    ├── components/              # Shared components (~70 dirs)
    ├── hooks/                   # ~132 custom hooks
    ├── state/                   # Jotai atoms (~35 top-level files + room/, room-list/, hooks/, utils/)
    ├── plugins/                 # Content plugins (call widget driver, emoji-data, color, react-prism)
    ├── utils/                   # Utilities (room.ts, matrix.ts, time.ts, capacitor.ts, electron.ts)
    └── styles/                  # Vanilla-extract global styles (global.css.ts, horseshoe.ts)
electron/                        # Electron desktop wrapper (see electron.md)
apps/widget-{telegram,discord,whatsapp}/  # Preact bot-widget apps (see overview.md)
apps/ai-bot/                     # Go Synapse appservice — "Vojo AI" (@ai), xAI-Grok backend (server-side, NOT client; see its README + server-side.md)
```

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

Router in `Router.tsx::createRouter(clientConfig, screenSize)`. All authed routes hang
off one big `<Route>` whose `element` is the provider stack:

```
AuthRouteThemeManager → ClientRoot → ClientInitStorageAtom →
ClientRoomsNotificationPreferences → ClientBindAtoms → ClientNonUIFeatures →
CallEmbedProvider → HorseshoeContainer → ClientLayout(nav={null}) → <Outlet/>
```

**The global 66px `SidebarNav` rail is no longer mounted** — `ClientLayout` gets `nav={null}` (Router.tsx:249, with a Russian comment explaining its 5 buttons will be redistributed in a `sidebar_cleanup` pass). `SidebarNav.tsx` + `pages/client/sidebar/*` survive as **dead code**.

Each visible top-level tab is still wrapped in `PageRoot` with a `nav` prop (the tab's PageNav) and an `<Outlet/>` for the active room/sub-route.

### Top-level tabs / routes

| Route | Path const | What it is |
|---|---|---|
| `direct/` | `DIRECT_PATH = /direct/` | Universal room list — every joined "orphan" non-space room (1:1 DMs, group DMs, group rooms, bridged chats) ∪ every `m.direct`-tagged non-space room. `useOrphanRooms ∪ useDirects`. Non-`m.direct` space children stay only in the parent workspace. |
| `channels/` | `CHANNELS_PATH = /channels/` | **NEW.** Mattermost-style surface presenting **Spaces as "workspaces"**. Active workspace selection + room list + thread routing. |
| `bots/` | `BOTS_PATH = /bots/` | **NEW.** Bridge-bot catalog + per-bot widget/chat host. |
| `explore/` | `EXPLORE_PATH = /explore/` | Public rooms (featured + per-server). |
| `:spaceIdOrAlias/` | `SPACE_PATH = /:spaceIdOrAlias/` | **Legacy** space tab — still fully live (lobby + child rooms). Coexists with `/channels/`; both render the Channel timeline. |
| `create/` | `CREATE_PATH = /create` (no trailing slash) | New room/space. |
| `settings/` | `SETTINGS_PATH = /settings/` | **NEW first-class route.** Reuses the `/direct/` shell (DM list as left nav) with `SettingsScreen` in the right pane. `?page=` deep-links a sub-screen. On mobile it redirects to `/direct/` and opens `MobileSettingsHorseshoe` via `settingsSheetAtom`. Replaces the old `Modal500` settings dialog. |
| `home/` | `HOME_PATH = /home/` | **Redirect-only shim.** `HomeRouteRoomProvider` redirects `/home/{roomId}/` → `/direct/{roomId}/`, OR → `/channels/{space}/{roomId}/` when the room has orphan-space parents. `/home/create` → `/direct/create/`, `/home/{join,search}` → `/direct/`. Keeps cold-start push deep links + old bookmarks resolving. No Home page / HomeTab. |
| `u/:userIdOrLocalPart` | `USER_LINK_PATH` | `UserLinkRedirect` normalizes `vojo.chat/u/<user>` → `/direct/create?userId=<mxid>`. |
| `inbox/*` | — | **GONE.** Only a literal `'/inbox/*'` → `Navigate to /direct/` redirect remains (Router.tsx:485). No `INBOX_PATH`, no InboxTab. (The `Inbox` *i18n namespace* still exists for notification-card previews.) |

`pages/client/sidebar/` exports only `DirectTab, SpaceTabs, ExploreTab, SettingsTab, UnverifiedTab, SearchTab` (CreateTab, InboxTab, HomeTab all removed). `WelcomePage.tsx` is the desktop empty state; at index routes it is intentionally `mobile ? null` by design.

### Channels tab (`pages/client/channels/`)

- `Channels.tsx` exports **two** components: `ChannelsRootNav` (the `/channels/` index nav — `StreamHeader` segment switcher + `ChannelsLanding` empty-state, Plus = create space) and `Channels` (the workspace listing — `ChannelsWorkspaceHorseshoe` > `StreamHeader pinKey="channels"` > `ChannelsList`, `WorkspaceFooter`, Plus = create channel in active space; writes `activeChannelsSpaceAtom`).
- `ChannelsLanding.tsx` resolves the active space (URL > localStorage via `useActiveSpace` > first joined orphan) and `Navigate`-redirects to `/channels/:space/`.
- `ChannelPickPlaceholder.tsx` is the desktop center-pane stub when no room is selected.
- `WorkspaceSwitcherSheet.tsx` / `WorkspaceFooter.tsx` / `SpaceAvatar.tsx` build the workspace switcher.
- Rooms under `/channels/` are wrapped in `ChannelsModeProvider value={true}` and rendered through `SpaceRouteRoomProvider` (shared with the legacy space tree). The `/channels/` route is declared **before** the `/:spaceIdOrAlias/` catch-all so the prefix isn't swallowed.

### Bots tab (`pages/client/bots/`)

- `Bots.tsx` (listing) renders `StreamHeader pinKey="bots"` + `BotCard` rows from `useBotPresets()`. Catalog-only, no Matrix listeners.
- `/bots/:botId` → `BotExperienceHost.tsx` (lazy): resolves the preset, runs `useBotRoom(preset)` state machine (`none / self-invite / bot-invite / bot-kicked / unsafe-membership / ready`) → renders `BotNotConnected / BotInvitePending / BotKicked / BotUnsafeRoom / BotStatePage`, or on `ready` wraps `BotRoomProvider` → `BotExperienceRoute` which branches on `botShowChatAtomFamily(roomId)`: chat → `<Room renderRoomView={BotChatFallback}>`, else `<BotShell>` (the widget). See `features/bots/` for the host internals.

### Mobile responsive nav

- `MobileFriendlyPageNav(path)` (LIVE) — on Mobile renders the per-tab PageNav only when `useMatch(path, {end:true})` matches exactly; otherwise null (navigating into a room hides the list).
- `MobileFriendlyClientNav` is **dead code** (never invoked since `nav={null}`).
- `components/mobile-tabs-pager/` drives the mobile listing nav: `MobileTabsLayout` (a no-path layout route) renders `MobileTabsPager` only on **mobile + native + a listing-root URL** (`/direct/`, `/channels/`, `/channels/:space/`, `/bots/`); everywhere else it falls through to `<Outlet/>`. `MobileTabsPager` mounts Direct + (Channels|ChannelsRootNav) + Bots panes once and slides between them via CSS transform + swipe gesture, navigating with `replace`. It's intentionally **not** exported (only `MobileTabsLayout` is). Gesture is disabled while `settingsSheetAtom` / `channelsWorkspaceSheetAtom` are open. State: `activeChannelsSpace.ts`, `mobilePagerHeader.ts`, `settingsSheet.ts`, `channelsWorkspaceSheet.ts`.

### Lazy vs eager loading (load-bearing perf invariant)

**Eager** (top-level imports, NOT `React.lazy`): `Bots`, `Channels` + `ChannelsRootNav`, `Direct`/`DirectCreate`/`DirectRouteRoomProvider`, `Space`/`SpaceSearch`/`RouteSpaceProvider`/`SpaceRouteRoomProvider`, `HomeRouteRoomProvider`, `ChannelPickPlaceholder`, `WelcomePage`, `SettingsScreen`.
**Lazy** (`React.lazy` + `routeSuspense()`): `Room`, `Lobby`, `Explore`, `FeaturedRooms`, `PublicRooms`, `BotExperienceHost`, `Create`.

The Channels/Bots **listing** tabs must stay eager — lazy-splitting them reintroduced a web tab-switch flicker (a `grow="Yes"` Suspense fallback in the fixed-width nav slot reflowed the content column). See `bugs.md`. `BotExperienceHost` stays lazy and must be imported from the concrete file `./client/bots/BotExperienceHost`, not the barrel.

### Universal Stream routing + DM classification

```
/direct/:roomIdOrAlias
  → PageRoot (nav=Direct, outlet=…)
    → DirectRouteRoomProvider (ResolvedRoomProvider sets IsOneOnOneProvider reactively)
      → Room.tsx (RoomViewHeader + RoomView, screen-size branching for side panels)
        → RoomTimeline + RoomTimelineTyping + RoomInput
```

The timeline picks a layout via a single **member-count** check (Element-Web's tier-2 pattern). The authoritative decision lives in `RoomTimeline.tsx`:

```ts
const isOneOnOne   = useIsOneOnOne();      // member-count === 2 (from IsOneOnOneProvider)
const channelsMode = useChannelsMode();    // true for any room under /channels/
const channelStyleLayout = channelsMode || !isOneOnOne;
const messageLayout: 'stream' | 'channel' = channelStyleLayout ? 'channel' : 'stream';
```

- **Stream** layout (rail + dot + bubble, the DM "VS Code chat" look) = **1:1 non-channels rooms only**.
- **Channel** layout (avatar + in-bubble header + bubble, Discord-style) = **every group room (>2)** in any surface **AND every room under `/channels/`** regardless of member count.
- `channelsMode` additionally enables channels-only filtering (thread surfacing via `ThreadSummaryCard`, hiding thread-replies/edits/reactions/RTC from the centre column via `isChannelsModeHidden`).
- Bridged Telegram puppet rooms classify correctly because the gate is server-side authoritative; `isBridged = channelsMode && isBridgedRoom(room)` disables thread/RTC affordances.

Route providers each wrap an inner `ResolvedRoomProvider` that runs the reactive `useIsOneOnOneRoom(room)` (subscribes `RoomStateEvent.Members`) and sets `<RoomProvider><IsOneOnOneProvider value=…>`:
- `DirectRouteRoomProvider` (`direct/RoomProvider.tsx`) — bounces invite rooms to `/direct/`, missing/space rooms to `JoinBeforeNavigate`.
- `SpaceRouteRoomProvider` (`space/RoomProvider.tsx`) — used by **both** legacy `/:space/:room` AND `/channels/:space/:room`; validates parent-child membership.
- `BotRoomProvider` — for bot rooms.
- `HomeRouteRoomProvider` only redirects (sets no IsOneOnOne context).

Use **`useIsOneOnOne()`** from `hooks/useRoom.ts` whenever you need the 1:1 vs group split. The old four-source `m.direct` gate (`isDirectStreamRoom`, `useIsDirectStream`, `IsDirectRoomProvider`, `useIsDirectRoom`, `IsStreamProvider`) is **fully removed** (zero grep hits) — do NOT reintroduce it. `useAutoDirectSync` still round-trips `m.direct` on join for **interop only** (so Element/FluffyChat agree); `mDirectAtom` is kept alive for `useDirectRooms` ordering and the `useDmCallVisible` ring gate, but is not load-bearing for layout.

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

| Dir | Purpose |
|-----|---------|
| `room/` | Core room view. **RoomTimeline.tsx** (~2516 LOC), **RoomInput.tsx** (~828 LOC), **RoomViewHeader.tsx** (11-line wrapper → **RoomViewHeaderDm.tsx**, ~791 LOC — the real Dawn header for *every* room class; identity area branches 3 ways: 1:1 → peer-profile sheet, group → members sheet, callView → static; subline shows `local:server` + presence for 1:1 or `N members` for groups; phone button via `useDmCallVisible`; search/pinned/invite/leave/settings/jump-to-time live in the `…` `RoomMenu`). Also **ThreadDrawer.tsx** (~1344 LOC, full thread surface with its own composer), `ThreadSummaryCard.tsx`, `RoomView.tsx` (composer-overlay pattern), `RoomViewMembersPanel`/`MembersSidePanel`, `RoomViewProfilePanel`/`ProfileSidePanel`, `RoomViewMediaSidePanel`/`MobileMediaViewerHorseshoe`, `RoomTimelineTyping.tsx`, `EmptyTimeline.tsx`, `RoomTombstone`, `CallChatView`, `CommandAutocomplete`, `room-pin-menu/`, `jump-to-time/`, `reaction-viewer/`. `MembersDrawer.tsx` still exists but is used **only** by lobby + `members-list/`, not Room.tsx. |
| `room/message/` | `Message.tsx` (~1506 LOC). The Stream/Channel branch is `Message.tsx:1160` (`layout === 'channel' ? <ChannelLayout/> : <StreamLayout/>`), driven by the `layout` prop from `RoomTimeline`. Hosts the edit/delete/react/report/pin/copy-link/source menu, `useDotColor` (Stream rail dot only), thread reply handler. Also `MessageEditor`, `CallMessage`, `SyslineMessage`, `Reactions`, `EncryptedContent`. |
| `room-nav/` | **Three** list-row components now: `RoomNavItem.tsx` (~434 LOC, channels + spaces lists), `DmStreamRow.tsx` (~496 LOC, the Direct-list row), `DirectInviteRow.tsx` (~282 LOC, inline accept/decline invite row in the Direct list). |
| `bots/` | **NEW.** Bridge-bot widget host (a bot's control room = the DM with its mxid). `catalog.ts` loads `BotPreset[]` from `config.json` `bots[]` (validates widget-origin allowlist + command prefix). `useBotRoom.ts` classifies control-room membership into a 6-state union. `BotShell` mounts a `matrix-widget-api` iframe (`BotWidgetEmbed`/`BotWidgetDriver`, tight `m.text`/`m.notice`-only capability allowlist). `botShowChatAtomFamily` toggles widget vs chat-fallback. `room.ts` = single source for portal-vs-control-room (`isBotControlRoom`). Pairs with `pages/client/bots/`. |
| `share-target/` | **NEW.** Android/web system share-sheet hand-off. `ShareTargetStrip.tsx` is a top banner (mounted in `HorseshoeContainer`) shown while `pendingShareAtom` holds a payload; the next `RoomInput` mount consumes it (injects files + text, then nulls the atom). Native slot drained by `hooks/useShareTargetReceiver.ts`. |
| `call/` | **In-room call pane** — `CallView` (prescreen/join screen + member list + livekit checks), `CallControls`/`Controls`/`PrescreenControls`/`CallMemberCard`. Mounted in `Room.tsx` via `<CallView/>`. Consumes `plugins/call` CallEmbed + `state/callEmbed`. Don't unmount/remount the widget root carelessly — Android FGS is keyed on `joined`. |
| `call-status/` | **Global bottom call rail** — `IncomingCallStrip` (incoming-ring row) + `CallStatus` (active-call pill) + `CallControl`. Mounted via `pages/CallStatusRenderer.tsx` + `pages/IncomingCallStripRenderer.tsx` inside `HorseshoeContainer` (NOT directly in Router). Call **lifecycle** hooks (`useIncomingRtcNotifications`, `useCallerAutoHangup`, `usePendingCallActionConsumer`) run in Router's `IncomingCallsFeature()`. |
| `settings/` | User settings as 7 pages (`GeneralPage, AccountPage, NotificationPage, DevicesPage, EmojisStickersPage, DeveloperToolsPage, AboutPage`; `SETTINGS_PAGE_PARAM` deep-links). `MessageLayout` / `messageSpacing` / `legacyUsernameColor` / `hour24Clock` / `dateFormatString` were removed — layout is no longer user-configurable and time/date derive from the runtime locale (`utils/time.ts`). `hideMembershipEvents` / `hideNickAvatarEvents` survive (gate group-room syslines). **Logout lives here only** (`LogoutDialog`). `MobileSettingsHorseshoe` + `SettingsScreen` are the mobile sheet / route entry. |
| `common-settings/` | **Shared** settings modules reused by both room and space settings: `general/` (RoomProfile, Address, Encryption, HistoryVisibility, JoinRules, Publish, Upgrade), `members/`, `permissions/` (Powers, PowersEditor, PermissionGroups), `emojis-stickers/` (RoomPacks), `developer-tools/` (SendRoomEvent, StateEventEditor). |
| `room-settings/` / `space-settings/` | Each defines only its own General + Permissions and **imports** Members/EmojisStickers/DeveloperTools from `common-settings`. Mounted globally via `RoomSettingsRenderer` / `SpaceSettingsRenderer`. |
| `lobby/` | Space lobby (`Lobby` + Hierarchy/Item + pragmatic-drag-and-drop reordering). Still routed under `SPACE_PATH/_LOBBY_PATH` and reached from the **legacy** Space tab — the new Channels surface does **not** use it. |
| `search/` | Unified switcher (Cmd+K modal `Search.tsx` via `SearchModalRenderer` + the StreamHeader's `InlineRoomSearch`, both on `useRoomSearch.ts`). Searches local rooms/DMs/spaces (`useAsyncSearch`) **and** a **"People" section** from the homeserver user directory (`mx.searchUserDirectory`, debounced 300ms / ≥2 chars; exact `@user:server` falls back to `mx.getProfileInfo`, then a soft-added raw id). People are deduped against existing DMs (`getDMRoomFor`); clicking one opens-or-creates a DM via `create-chat/useCreateDirect.ts`. This is how you reach someone you haven't chatted with — the old "+ new chat" form is gone from the listing headers (see `stream-header/`). Findability of who appears is the server's lever: Synapse `user_directory.search_all_users` (federation only surfaces remote users the server already knows). |
| `message-search/` | In-room message search (`MessageSearch` + filters/input/`SearchResultGroup`). |
| `create-chat/` | DM creation. `CreateChat.tsx` = the explicit username + server form (`FALLBACK_SERVER='vojo.chat'`, dedup via `getDMRoomFor`), now reached only by the `/u/<user>` deep link (`UserLinkRedirect` → `/direct/create`) and the Direct empty-state CTA — NOT from the listing-header Plus (retired; people are found in `search/`). `useCreateDirect.ts` = the shared open-or-create-DM hook used by both `CreateChat` and the search People section. |
| `create-room/` / `create-space/` | Room/space creation (`CreateRoom`/`CreateSpace` + their modal wrappers, mounted via `*ModalRenderer`). |
| `add-existing/` | Add existing rooms to a space. |
| `join-before-navigate/` | Pre-join room card (`JoinBeforeNavigate.tsx`, ~82 LOC). |

### Virtualization in features/room/

`RoomTimeline.tsx` does **not** use `@tanstack/react-virtual`. It uses **`useVirtualPaginator`** + `IntersectionObserver` for pagination + scroll-anchoring; row heights are measured live (no `estimateSize`). The tanstack `useVirtualizer` is used elsewhere for **list panels** (e.g. the DM-list column in `Direct.tsx`, via `components/virtualizer/VirtualTile.tsx`).

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

### Message rendering — `message/`

- `message/layout/` — **three shipping layouts** + base: `Stream.tsx` (1:1/Bots rail+dot+bubble, `STREAM_MESSAGE_SPACING='400'`), `Channel.tsx` (groups + channels: avatar + in-bubble header, `CHANNEL_MESSAGE_SPACING='300'`, `headerInBubble` compact mode for the thread drawer), `Modern.tsx` (card-preview only — pin-menu, message-search, `DefaultPlaceholder`; inbox is gone), `Base.tsx` (MessageBase/AvatarBase/Username primitives). `Compact.tsx`/`Bubble.tsx` and the `MessageLayout` enum are deleted. Also `layout.css.ts`, `Channel.css.ts`, `streamDebug.ts`.
- `message/content/` — `EventContent.tsx` is now a **two-branch** sysline renderer (`layout?: 'stream'|'channel'`; `'channel'` → `<ChannelEventContent>`, else the Stream rail/dot grid). The legacy `IsStreamProvider` context is gone; rail metadata flows via `railStart`/`railEnd` props. Plus `Image/Video/Audio/File/Thumbnail/FallbackContent`.
- `message/attachment/` — `Attachment.tsx` + the Stream-media bubble shells (`StreamMediaShell` aspect-clamped 320px, `StreamMediaImage`, `StreamMediaVideo`).
- `message/placeholder/` — `DefaultPlaceholder`, `LinePlaceholder`.
- Top-level: `MessageStatus.tsx` (kept, **not rendered in timeline** — consumed only by `hooks/useMessageStatus.ts` → `hooks/useDotColor.ts`, which encodes delivery/read state on the Stream rail dot, **per side**: OWN dots are **white** (`--vojo-stream-name-own`, matching the own nick), except **green=read & not yet answered** (prominent — demotes back to white once the peer replies, tracked reactively via `RoomEvent.Timeline`); **PEER (incoming) dots are gray** (`--vojo-dot-neutral`); gold=mention / red=failed override either side. Nicks: own=white, peer=brand purple), `Reaction`, `Reply`, `Time`, `RenderBody`, `FileHeader`.

### Editor — `editor/`

Slate-based. `Editor.tsx` (Slate root — preserve), `Editor.preview.tsx`, `Elements`, `Toolbar`, `input/output/keyboard/utils`. `editor/autocomplete/`: `RoomMentionAutocomplete`, `UserMentionAutocomplete`, `EmoticonAutocomplete`, `AutocompleteMenu`. **`CommandAutocomplete` is NOT here** — it lives in `features/room/`.

### Media / viewers

- `media/` (**NEW**) — primitive `<Image>`/`<Video>` wrappers + `MediaControls` layout shell.
- `image-viewer/`, `Pdf-viewer/`, `text-viewer/` (**NEW**, lazy Prism), `image-editor/` (**NEW**, currently a stub — `handleApply` is a no-op), `ImageOverlay.tsx` (Modal viewer wrapper used by url-preview).
- `emoji-board/` — emoji picker. `image-pack-view/` — custom emoji/sticker pack management.

### Avatars / user / member (mostly NEW dirs)

- `user-avatar/`, `room-avatar/` (also exports `RoomIcon`), `stacked-avatar/` — avatar primitives (force circle via globalStyle).
- `user-profile/` — Dawn profile card: `UserRoomProfile` (root), `UserHero`, `UserInfoRows`, `UserChips` (UserActionsMenu + MutualRoomsChip), `UserModeration`, `PowerChip`, `CreatorChip`.
- `member-tile/`, `members-list/` (**NEW** — `MembersList` Dawn members-sheet body + `RoomMembersHero`), `power/` (PowerColorBadge/Icon/Selector), `presence/` (**NEW** — PresenceBadge online/away/offline dot), `event-readers/` (**NEW** — read-receipt popout).

### Navigation / list (mostly NEW dirs)

- `nav/` (**NEW**, heavily used) — generic list-row primitives (`NavCategory`, `NavCategoryHeader`, `NavItem`/`NavLink`, `NavItemContent`, `NavItemOptions`, `NavEmptyLayout`). The lower-level layer beneath `features/room-nav/`.
- `stream-header/` (**NEW**) — the **tab curtain header** for the Direct/Channels/Bots listing tabs (`StreamHeader` + `Chip`/`Segment` + `useCurtain*` gestures + `forms/InlineRoomSearch`). **Not** the room header — don't confuse with `RoomViewHeaderDm`. The Plus/new-chat action is **gone on Direct** (people are found in search); the Plus only renders where a tab supplies a `primaryAction` (Channels' create-channel/community). The curtain has a single form (`form-search`); its peek geometry is **chip-count-aware** — `peekTravelPx(chipRows)` (1 on Direct, 2 on Channels) is threaded into `snapTopPx` + both gesture hooks so rest position and commit scale stay in lockstep.
- `mobile-tabs-pager/` (**NEW**) — the mobile swipe pager (see Routing).
- `sidebar/` — `Sidebar` (66px wrapper), `SidebarItem`, `SidebarStack`, `SidebarStackSeparator`, `SidebarContent` (currently mounted only via dead `SidebarNav`).
- `virtualizer/` (`VirtualTile`), `scroll-top-container/`.

### Cards / layout primitives

`page/Page.tsx` (exports `Page, PageRoot, PageNav, PageNavHeader, PageNavContent, PageHeader, PageContent, PageHero…, HorseshoeEnabledContext`), `sequence-card/`, `cutout-card/`, `info-card/` (**NEW**), `room-card/` (**NEW**, ~328-LOC joinable-room card with join flow), `room-topic-viewer/` (**NEW**, topic Modal), `setting-tile/`.

### Badges / indicators / upload / preview

`unread-badge/`, `server-badge/` (**NEW**), `typing-indicator/` (**NEW**), `time-date/` (**NEW** — DatePicker/TimePicker/PickerColumn), `upload-card/`, `upload-board/` (**NEW**), `url-preview/`.

### Prompts / dialogs

`invite-user-prompt/`, `leave-room-prompt/`, `leave-space-prompt/` (**NEW**), `full-screen-intent-prompt/` (**NEW** — Android FSI permission, 7-day cooldown), `push-permission-prompt/` (**NEW** — push permission, 7-day cooldown), `uia-stages/` (Dummy/Email/Password/ReCaptcha/RegistrationToken/SSO/Terms), `LogoutDialog`. (`join-address-prompt/` from the old doc **does not exist**.)

### Boot/runtime Loaders & Providers (top-level render-prop components)

- `ClientConfigLoader` (fetch `/config.json`, 10s timeout), `MediaConfigLoader`, `CapabilitiesLoader`, `ServerConfigsLoader` (allSettled capabilities+mediaConfig+authMetadata), `SpecVersionsLoader` (CS-API probe, soft-degrade), `AuthFlowsLoader`, `SupportedUIAFlowsLoader`.
- `RoomSummaryLoader` (+ `LocalRoomSummaryLoader`, `HierarchyRoomSummaryLoader`, react-query), `RoomUnreadProvider`/`RoomsUnreadProvider` (`roomToUnreadAtom`), `SpaceChildDirectsProvider`/`SpaceChildRoomsProvider`, `UseStateProvider`.
- `CallEmbedProvider.tsx` (**NEW**, Vojo call surface) — mounts the fixed-position Element Call widget container, provides `CallEmbedContext`/`CallEmbedRefContext`, runs `CallUtils` + `useAndroidCallForegroundSync`. **Load-bearing — Android FGS is keyed on `callEmbedAtom`.**
- Crypto/verification cluster: `SecretStorage`, `BackupRestore`, `DeviceVerification`/`Setup`/`Status`, `ManualVerification`.
- Misc: `AccountDataEditor`, `JoinRulesSwitcher`, `RoomNotificationSwitcher`, `MemberSortMenu`, `MembershipFilterMenu`, `HexColorPickerPopOut`, `BetaNoticeBadge`, `Modal500` (mobile horseshoe modal shell), `RenderMessageContent` (msgtype dispatcher + `StreamMediaContext`), `password-input/PasswordInput`, `ConfirmPasswordMatch`, `ActionUIA`/`UIAFlowOverlay`, `BackRouteHandler` (web back-button → back-stack collapse via `replace`).

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

| Path | Notes |
|---|---|
| `hooks/useDmCallVisible.ts` | **Single source of truth for the DM call button.** FOUR gates: `useIsOneOnOne() && mDirectAtom.has(roomId) && !useIsBridgedRoom(room) && !isCatalogBotControlRoom(...)`. Consumed by both `RoomViewHeaderDm::DmCallButton` (+ `!callView`) and `UserRoomProfile`'s Call action so they can't drift. (The bot-control-room gate excludes bridge bots; the bridge gate excludes mautrix puppet rooms via MSC2346 `m.bridge`.) Lifecycle hooks (`useIncomingRtcNotifications`, `useCallerAutoHangup`) still gate ring delivery on `m.direct`. |
| `features/call/*` + `components/CallEmbedProvider.tsx` | Element Call widget; **don't unmount/remount the widget root on header redesign** — Android FGS is keyed on `joined`. |
| `features/call-status/*` via `pages/CallStatusRenderer.tsx` + `pages/IncomingCallStripRenderer.tsx` | The incoming-ring strip + active-call pill render inside `HorseshoeContainer`'s bottom rail (mounted at `Router.tsx:242` inside `CallEmbedProvider`), **not** directly in Router. |
| `state/callEmbed.ts`, `state/incomingCalls.ts`, `state/pendingCallAction.ts` | Call embed lifecycle, ring queue (`incomingCallsAtom` + derived `isRingingAtom`), native push-action bridge (answer/decline). |
| `components/message/MessageStatus.tsx` + `hooks/useMessageStatus.ts` | Kept but not rendered — feeds `useDotColor` for the Stream rail dot. |
| `hooks/usePushNotifications.ts` | Push tap routing: warm web/native paths resolve DMs to Direct via `navigateRoom`/`getDirectRoomPath`; SW cold-start opens `/home/{roomId}/` and `HomeRouteRoomProvider` redirects to `/direct/` or `/channels/`. Invite-state rooms bounce to bare `/direct/`. FSI hand-off. |
| `hooks/useRoomNavigate.ts` | Back-stack collapse via `replace` — **path-based** (`pathnameRef.current === target ? replace : push`), so removing tab rendering doesn't break the back-stack. |
| `hooks/useAndroidBackButton.ts`, `components/BackRouteHandler.tsx` | Hardware back integration. |
| `hooks/useAutoDirectSync.ts` + `utils/matrix.ts` | `m.direct` sync on join (interop), skips bridged + >2-member rooms. |
| `src/sw.ts` + `src/sw-session.ts` | Authenticated Matrix media (Bearer-token fetch on `/_matrix/client/v1/media/*`), push notifications with EN/RU fallback, IndexedDB language bridge. `pushSessionToSW()` re-posts `setSession` on `controllerchange` + `sw.ready` to survive the first-load null-controller race (logout passes `undefined` to clear). |
| `pages/auth/*` | Bistable layout — don't change body/root background CSS-vars; see `bugs.md`. |
| Android edge-to-edge / safe-area | `body { background-color: var(--vojo-safe-area-bg, #0d0e11) }` (`--vojo-safe-area-bg` bound to `color.Background.Container` in `styles/global.css.ts`); `#root { padding: env(safe-area-inset-{left,right}) }` (top/bottom zero); `--vojo-safe-top: env(safe-area-inset-top)` padded down by ~15 top-anchored components (reset to 0 inside the mobile horseshoes). `MainActivity.java` + `windowLayoutInDisplayCutoutMode=shortEdges`. See `android.md`. |
| `scripts/gen-push-strings.mjs` + `android/app/build.gradle` | Gradle task generates `push_strings.xml` from i18n `Push` namespace. Don't put non-push keys in `Push`; add EN+RU together. |

## State Management

**Jotai** atoms in `src/app/state/` (~35 top-level files + `room/`, `room-list/`, `hooks/`, `utils/`). Helpers: `utils/atomWithLocalStorage.ts` (hydrate + persist + cross-tab `storage` sync), `list.ts` (`createListAtom` PUT/REPLACE/DELETE factory). Access via hooks in `state/hooks/`; `useBindAtoms.ts` wires the matrix-listener atoms once at boot.

**Persisted to localStorage:**
- `settings.ts` → `settingsAtom` (key `settings`; custom `getSettings`/`setSettings`, see below).
- `sidebarWidth.ts` / `threadDrawerWidth.ts` / `mediaSidePanelWidth.ts` — desktop column widths with clamp helpers (sidebar MIN 384/DEF 416; thread MIN 320/DEF 420; media MIN 360/DEF 520/HARD_MAX 880, max accounts for rail + pageNav + void gaps + chat reserve).
- `activeChannelsSpace.ts` → `activeChannelsSpaceAtom` (key `vojo.activeSpaceId`, stored RAW not JSON for back-compat) — Channels active workspace.
- `spaceRooms.ts` (Set of space-summary child rooms), `navToActivePath.ts`, `closedNavCategories.ts`, `closedLobbyCategories.ts`, `openedSidebarFolder.ts`, `callPreferences.ts` — most are `make…Atom(userId)` per-user factories.

**In-memory only:**
- `incomingCalls.ts` (`incomingCallsAtom` + `isRingingAtom`), `pendingCallAction.ts`, `pendingShare.ts`.
- Right-pane sheet atoms (**mutually exclusive** — opening one clears the others via `state/hooks/`): `userRoomProfileAtom`, `mediaViewerAtom`, `roomMembersSheetAtom`, plus `settingsSheetAtom` (mobile-only Settings) and `channelsWorkspaceSheetAtom`.
- `mobilePagerHeader.ts` (`mobilePagerCurtainAtom`, `curtainPinnedByTabAtom`, `mobileHorseshoeActiveAtom`), `viewedRoom.ts` (`viewedRoomIdAtom` — cross-route "room on screen" for URL-less routes like `/bots/:botId`).
- `mDirectList.ts` (`mDirectAtom` + `useBindMDirectAtom`), `callEmbed.ts` (`callEmbedAtom`, `callChatAtom`), `typingMembers.ts` (gated on `hideActivity`), `upload.ts`, `lastCompositionEnd.ts`, `searchModal.ts`, `backupRestore.ts`, `createRoomModal.ts`/`createSpaceModal.ts`, `roomSettings.ts`/`spaceSettings.ts`.
- `state/room/` — `roomInputDrafts.ts` (draft families keyed by **tuple `[roomId, threadKey]`** so the thread drawer keeps independent drafts), `roomToParents.ts`, `roomToUnread.ts`.
- `state/room-list/` — `roomList.ts` (`allRoomsAtom`), `inviteList.ts` (`allInvitesAtom`), `utils.ts`.
- `sessions.ts` — **no live atom** (all atom code is commented out); only `getFallbackSession`/`setFallbackSession`/`removeFallbackSession` + the legacy cinny→vojo localStorage key migration remain active.

### settings.ts fields & migrations

Current `Settings` fields: `themeId? ('light-theme'|'dark-theme')`, `useSystemTheme`, `monochromeMode?`, `isMarkdown`, `editorToolbar`, `twitterEmoji`, `pageZoom`, `hideActivity`, `isPeopleDrawer`, `memberSortFilterIndex`, `enterForNewline`, `hideMembershipEvents`, `hideNickAvatarEvents` (default true), `mediaAutoLoad`, `urlPreview`, `encUrlPreview`, `showHiddenEvents`, `isNotificationSounds`, `inviteSpamFilter`, `developerTools`, `migrationsApplied?`.

`getSettings()` runs three one-shot migrations: `dawn-redesign-v1` (pins **existing** users — stored JSON present — to dark; brand-new users keep `useSystemTheme:true`), `dawn-p3c-cleanup` (drops `messageLayout`/`messageSpacing`/`legacyUsernameColor`), `system-time-format-cleanup` (drops `hour24Clock`/`dateFormatString` — time/date now derive from the runtime locale via `Intl.DateTimeFormat` in `utils/time.ts`). **Known platform limitation**: Android's manual "24-hour" toggle is invisible to `Intl`; only a native bridge to `DateFormat.is24HourFormat` would respect it.

## Theming

Stock Cinny had multiple themes; Vojo simplified to **System / Light / Dark**.

- `src/colors.css.ts` defines `darkTheme` (Dawn palette) and `lightTheme` (Vojo light) via `createTheme(color, …)` — both Vojo-owned (folds default `lightTheme` not imported). `config.css.ts` adds `onDarkFontWeight`/`onLightFontWeight`.
- `hooks/useTheme.ts`: `DarkTheme.classNames = ['dark-theme', darkTheme, onDarkFontWeight, 'prism-dark']`, `LightTheme` mirror. `useActiveTheme()` picks on `useSystemTheme` + `themeId`.
- `pages/ThemeManager.tsx` exports **two** components (no single `ThemeManager`): `UnAuthRouteThemeManager` (auth routes — follows OS `prefers-color-scheme` only) and `AuthRouteThemeManager` (authed routes — reads `useActiveTheme()`, swaps body class, applies `monochromeMode` as `document.body.style.filter = 'grayscale(1)'`, provides `ThemeContext`). Both do `body.className=''` then re-add the theme classes. Runtime switching is live (body-class swap, no reload), but adding new tokens still needs a rebuild.
- Brand accent: dark `Primary.Main = #9580ff` (Dawn lavender), light `#5b6aff` (indigo).
- The Appearance picker (Settings → General) offers System / Light / Dark.
- **Stream/bubble CSS vars** live in `src/index.css` (`:root` light defaults, `.dark-theme` overrides): `--vojo-horseshoe-void`, `--vojo-peer-bubble-bg`, `--vojo-timeline-rail`, `--vojo-stream-name-own`, `--vojo-stream-name-peer`, `--vojo-dot-neutral`. The incoming-call orbit needs `@property --vojo-orbit-angle` + `@keyframes vojo-orbit-sweep` declared in raw `index.css` (vanilla-extract lacks `@property`).
- Horseshoe seam: `--vojo-horseshoe-void` is `#d6d6e3` (light) / **`#000000`** (dark). `styles/horseshoe.ts` exports `VOJO_HORSESHOE_VOID_COLOR`, `VOJO_HORSESHOE_GAP_PX = 12`, `VOJO_HORSESHOE_RADIUS_PX = 32`; consumed by `HorseshoeContainer`.

### Known follow-ups for light theme

The **web** theme switch is wired end-to-end (palette, picker, runtime body-class swap, mxid colours, prism highlighting, `--vojo-safe-area-bg`, cold-start `prefers-color-scheme` fallback in `index.css`, dual `<meta theme-color>` `#0d0e11`/`#f2f2f7`). Native and PWA chrome are NOT yet bound to the active theme (all verified still hardcoded dark):

- **Android system bars** — `MainActivity.java::onCreate` hardcodes `setAppearanceLight{Status,Navigation}Bars(false)`.
- **Android native splash** — `res/values/colors.xml::splash_bg = #0d0e11` + `styles.xml::windowBackground`; no `values-night/`.
- **Capacitor WebView paint** — `capacitor.config.ts::android.backgroundColor = '#0d0e11'`.
- **PWA manifest** — `public/manifest.json` `theme_color`/`background_color` = `#0d0e11` (no media-query support).
- **AuthLayout** — `pages/auth/styles.css.ts` hardcodes `#0d0e11` (tied to the auth bistable-layout refactor; the file also carries its own `max-width`/`max-height` layout media queries).
- **Bot widgets** — `BotShell.css.ts` / `BotWidgetMount.css.ts` / `BotCard.tsx` hardcode `#9580ff` / `#7ab6d9` / `#0c0c0e`; each widget is a separate Preact app without Vojo's folds tokens.

## Composer card geometry

Load-bearing pixel values for the main chat composer + thread-drawer composer (both wrap `RoomInput` with the `ChatComposer` class). Floating rounded card with **32px corner radius** (`VOJO_HORSESHOE_RADIUS_PX`); paddings tuned so visible glyphs stay outside the curve clip. Source of truth: [`RoomView.css.ts`](../../src/app/features/room/RoomView.css.ts), [`RoomInput.tsx`](../../src/app/features/room/RoomInput.tsx), [`Editor.css.ts`](../../src/app/components/editor/Editor.css.ts). **All values below verified unchanged 2026-05-30.**

| Element | Value | Where |
|---|---|---|
| Card corner radius | 32px | `VOJO_HORSESHOE_RADIUS_PX` |
| Card outer padding | `6px / 16px` (vertical / horizontal) | `RoomView.css.ts` → `.ChatComposer .Editor` |
| Textarea vertical padding | 13px (folds default — do NOT override) | `Editor.css.ts` → `EditorTextarea` |
| Textarea horizontal padding | 12px left, 12px right | `RoomView.css.ts` → `:first-child` / `:last-child` rules |
| Placeholder paddingTop | 13px (must match textarea padding) | `Editor.css.ts` → `EditorPlaceholderTextVisual` |
| Action-row padding | `2px / 8px / 4px` (top / sides / bottom) | `RoomInput.tsx` bottom slot |
| IconButton size | 32×32 (folds `size="300"`, `fill="None"`) | `RoomInput.tsx` |

`RoomView.css.ts` also defines `ComposerDesktopClamp` (maxWidth 75%, centered on desktop) and `ComposerOverlay` (absolute slide/fade wrapper, `prefers-reduced-motion`-gated) — the composer is positioned as a bottom-stuck overlay reporting its height to `RoomTimeline`, and is **unmounted entirely when the thread drawer is open** (single-Slate-at-a-time).

**Don't override the textarea's vertical padding (13px) without retuning `EditorPlaceholderTextVisual.paddingTop` in lockstep** — folds tuned the pair so the placeholder span and typed-text caret land on the same y. The textarea-padding compact override is scoped to `.ChatComposer`; the message-edit overlay and `Editor.preview.tsx` keep the folds-default `padding: 13px 1px`. If you re-tune any number here, update both the CSS comments and this table.

## Responsive design

Layout responsiveness goes through `hooks/useScreenSize.ts` (NOT CSS layout media queries):

```ts
ScreenSize.Mobile  // ≤750px   (MOBILE_BREAKPOINT = 750)
ScreenSize.Tablet  // >750 ≤1124px  (TABLET_BREAKPOINT = 1124)
ScreenSize.Desktop // >1124px
```

`useScreenSizeContext()` returns the current size (observed on `document.body`; `ScreenSizeProvider` mounted in `App.tsx`); components branch their JSX on it.

- `MobileFriendlyPageNav(path)` hides the per-tab PageNav on Mobile unless the URL matches the exact root path.
- Mobile **listing** nav (Direct/Channels/Bots) is driven by `components/mobile-tabs-pager/` (swipe pager, native only).
- Mobile room **side panels** (members / profile / media / settings) render as bottom-up **curtain horseshoes**; desktop/tablet render them as resizable right-side panes.

> **Caveat:** the old claim "the only `@media` queries target `(hover: hover)`" is **false**. Layout is JS-driven, but the codebase does use `@media`: `(prefers-reduced-motion: reduce)` (RoomView/RoomTimeline/HorseshoeContainer/…), `(prefers-color-scheme: light)` (`index.css` light cold-start fallback), `(hover: hover) and (pointer: fine)` hover-gates (Sidebar/Channel.css), and a few `max-width`/`max-height` queries inside `BotShell.css.ts` and `auth/styles.css.ts`.

## Matrix SDK Patterns

```tsx
const mx = useMatrixClient();                               // SDK instance (throws if no provider)
const room = useRoom();                                     // Current room
const isOneOnOne = useIsOneOnOne();                         // From IsOneOnOneProvider context (member-count===2)
const stateEvent = useStateEvent(room, StateEvent.Type);    // Room state (default stateKey '')
const powerLevels = usePowerLevels(room);                   // Permissions
```

`isOneOnOneRoom(room)` (`utils/room.ts`) = `!isSpace(room) && room.getInvitedAndJoinedMemberCount() === 2`. `useIsOneOnOneRoom(room)` is the reactive wrapper (subscribes `RoomStateEvent.Members`) that feeds each route's `IsOneOnOneProvider`.

## i18n

i18next + `react-i18next`. **Single-file locales**: [`public/locales/en.json`](../../public/locales/en.json) + [`public/locales/ru.json`](../../public/locales/ru.json) (loadPath `…/public/locales/{{lng}}.json` — **no per-namespace directories**). Namespaces are **top-level keys** in each file: `Organisms, App, Boot, Auth, Settings, Search, Home, Direct, Channels, Call, Room, Inbox, Explore, Create, RoomSettings, Push, Bots, User, Share`. (`App`, `Channels`, `Call`, `Bots`, `User`, `Share` are recent; `Home` is post-redesign cruft, `Inbox` survives for notification-card previews.)

- `supportedLngs: ['en','ru']`, `fallbackLng: 'en'`, detection `['navigator','htmlTag']` with `caches:[]` (tracks system language each launch — no in-app selector).
- **`Push` namespace is special**: `scripts/gen-push-strings.mjs` (Gradle task) reads it and emits `android/.../values{,-ru}/push_strings.xml` for the Android lockscreen. Don't put non-push UI keys in `Push`. Web SW push falls back to **EN** if a key is missing in RU — always add EN + RU together.
- Russian-language quality: see `i18n.md`.

## Key Libraries

- **React 18.2** + **React Router DOM 6.30.3**
- **matrix-js-sdk 41.4.0** — exact pin (see `docs/plans/matrix_js_sdk_upgrade.md`)
- **folds 2.6.2** — UI component library (peerDep pins React 17 — see `bugs.md`)
- **jotai 2.6.0** — state
- **vanilla-extract** — type-safe CSS (compile-time tokens; theme switch is live via body-class swap)
- **slate 0.123** — rich text editor
- **@tanstack/react-query 5** — data fetching; **@tanstack/react-virtual 3** — list virtualization (NOT used by RoomTimeline)
- **i18next 23 + react-i18next 15** — localisation
- **Capacitor 8.3** + **@capacitor/browser 8.0** — native Android
- **vite-plugin-pwa** — `injectManifest` strategy with `injectionPoint: undefined` → **no Workbox precache**; the SW is the hand-written `src/sw.ts`.
- **`@fontsource/inter`** + **`@fontsource-variable/jetbrains-mono`** in `dependencies` (other `@fontsource/*` must also go in deps to land in the bundle).
- Newer notable deps: **`@atlaskit/pragmatic-drag-and-drop`** (lobby/space reordering), **`matrix-widget-api 1.17`** (bot widget driver + call embed), **`@element-hq/element-call-embedded 0.16.3`** (call widget — its ~9.5MB blur wasm is stripped at copy time, DM calls are voice-only), **`chroma-js`** (`plugins/color.ts`), **`react-aria 3.29`** (message + nav row interactions), **`electron` + `electron-builder`** (desktop, see `electron.md`).

## Build & deploy

- **Web (local)**: `npm run build` → `dist/` → `rsync`/`scp` to `~/vojo/cinny/` on the VPS (Caddy serves it). VSCode task `Deploy to vojo.chat` (Ctrl+Shift+D) automates it. `Deploy widgets` builds the three Preact bot-widget apps.
- **Web (CI)**: `.github/workflows/prod-deploy.yml` — `workflow_dispatch` only → `git describe --tags` → build → Netlify production deploy → GPG-signed `tar.gz` GitHub release → multi-arch Docker push (Docker Hub + GHCR). Other workflows: `build-pull-request`, `deploy-pull-request`, `docker-pr`, `netlify-dev`, `lockfile`, `pr-title`.
- **Android**: `npm run build:android:debug` (build → strip-sourcemaps → `cap sync` → `gradlew assembleDebug`); release/AAB analogues. App version from `git describe --tags --match 'v*'` mirrored in `vite.config.js::resolveAppVersion()` and `android/app/build.gradle`. See `android.md`.
- **Electron**: `npm run build:electron:win` (or `:win:docker` from WSL). See `electron.md`.
- Build tooling: Node engine `>=22.12.0`, but `.node-version` pins **24.13.1** (used by CI) — match it locally. Vite manual chunks split emoji-data (~506KB), matrix-sdk, editor; react/folds/react-aria deliberately not split (boot-critical wasm/top-level-await reorder risk). `package.json` `version` field (`0.2.0`) is stale relative to git tags — the runtime version comes from `git describe`.

## Git

- **Upstream Cinny** main branch is `dev`; **Vojo** work branch is **`vojo/dev`** (the `origin` remote, `git.vojo.chat`). Local `dev` tracks stale upstream Cinny. PRs target **`main`** per the working environment.
- **No semantic-release** — releases are **tag-driven** via the manual `prod-deploy.yml` workflow.
- **Android `versionCode` is monotonic**: `major*1_000_000 + minor*1_000 + patch`, where `patch` = commit count since the `v*` tag. Don't squash/rebase across release boundaries — Play store rejects downgrades.
- **Husky pre-commit runs `tsc --noEmit` + `lint-staged` (`eslint --max-warnings 0`)** — both must be green. `no-explicit-any` / `no-non-null-assertion` are `'warn'` but blocked by `--max-warnings 0`; when unavoidable (matrix-js-sdk boundary, generic helper, third-party callback), add an inline `// eslint-disable-next-line` with a one-line justification rather than relaxing the rule.
- **Commit message style** (vojo memory): one sentence ≤25 words; no body; no Co-Authored-By trailer.

## Refactor checklist for AI agents

Encoded from the P3c retrospective (2026-04-28) — three classes of bug that ate
three rounds of code review. Hit this checklist **before** declaring a
refactor done; each item is cheap to verify and would have caught a real
BLOCKER if applied earlier.

### 1. Plan-trust = trust-but-verify

When a plan says "X is automatic" or "Y migrates correctly," **don't
believe it without grepping the affected subsystem**. Plans encode
intentions; the actual code may have load-bearing assumptions the plan
didn't audit.

- For each "handle Y по новому пути", `grep -rn` for the OLD path (atom,
  helper, gate function) and ensure no lingering callsites read it with the
  OLD semantic.
- Especially for **load-bearing surfaces** (calls, push, FSI, edge-to-edge,
  service worker, native bridges): a plan's "не трогаем" list is a **hint
  that the surface contains hidden coupling**, not a license to ignore it.
  If your refactor changes _any_ visibility/classification gate that touches
  calls or push, walk every call/push hook by hand.

P3c blocker example: plan §6.8 said "DmCallButton gated on `useIsOneOnOne()`"
without auditing `useIncomingRtcNotifications` / `useCallerAutoHangup` which
still gated on `m.direct`. Caught three rounds later.

### 2. Systematic consumer audit before renaming/repurposing

Before changing the **semantic** of a hook, atom, or context-value (not
just renaming — semantic shift), run `grep -rn` for every consumer and
classify each:

```
grep -rn "useFoo\|fooAtom\|FooContext" src/
```

For each callsite: (a) Does the new semantic still match its intent? (b)
Does it use the symbol for ITS original semantic, or a DIFFERENT one that
happens to overlap with the old name?

P3c examples missed initially: `useDirectRooms` in `MutualRoomsChip` needed
the m.direct semantic, not universal-Direct; `mDirects.has(roomId)` in
`RoomSettings`/`RoomProfile`/`SpaceSettings` for peer-avatar fallback needed
the member-count semantic consistent with the header.

### 3. Reactivity audit for context values from mutable objects

If you put a `room.X()`-style call into a Provider's `value=`, and `room`
is the matrix-js-sdk `Room` object (mutable, fires events), **the value is
a static snapshot at first render**. Subsequent state changes won't flow
through until the Provider re-renders for another reason.

Symptoms: "UI не обновляется когда X меняется", "надо перезайти в комнату".

Fix pattern: extract the Provider into an inner component that subscribes to
the relevant matrix-js-sdk event (`RoomStateEvent.Members`,
`RoomEvent.Receipt`, `MatrixEventEvent.Decrypted`) via `useState + useEffect`,
capturing the emitter ref **inside** the effect for cleanup leak-safety.
Reference impl: [`hooks/useIsOneOnOneRoom.ts`](../../src/app/hooks/useIsOneOnOneRoom.ts)
+ [`pages/client/direct/RoomProvider.tsx`](../../src/app/pages/client/direct/RoomProvider.tsx)
(the `ResolvedRoomProvider` split pattern).

P3c blocker example: `IsOneOnOneProvider` value computed once at mount froze
for the route — inviting a 3rd into a 1:1 didn't flip chrome until navigation.

### 4. Don't defer mechanical cleanups "to a later phase" when one-pass is cheap

Each `// TODO: rename X` left in the diff multiplies into a multi-file rename
sweep later. If a prop name diverges from its semantic during refactor, fix
it in the same commit if it's < 5 callsites. (Live examples of deferred
renames still in tree: `RoomViewHeader.tsx` → `RoomViewHeaderDm` is a thin
wrapper whose `Dm` suffix is now historical; the global `SidebarNav` rail is
dead-but-mounted-nowhere awaiting `sidebar_cleanup`.)