# FORK_DIVERGENCE

This document tracks the functional and behavioral differences between this forked repository and its upstream baseline. Each entry represents a deliberate divergence introduced to meet the specific needs of this fork.

---

### **D-0002: Letro colour palette, gradient buttons, URL corrections, and live-location permission**

- **Upstream baseline commit**: `e0ca2acc43649d4c80194d84d2179a7a9310d7eb`
- **Fork commit (merge)**: `bbdee132f18c9bfe90f448aa1f3956ddd79df39b` (PR #4 — `p-num/letroMain`)
- **Type**: `Behavioral`
- **Date**: `2026-04-16`

#### **Description**

Follow-up polish to the D-0001 rebrand: expands Letro's colour tokens and applies them more broadly, replaces flat primary buttons with a gradient, corrects remaining `element.io`/`matrix.org` URLs to `letro.com`, adds the background-location usage description required for live-location sharing, and refines localisation strings.

#### **Upstream vs. Fork Behavior**

| Area | Upstream (Element X) | Fork (Letro) |
|---|---|---|
| Primary button background | Flat fill using `bgActionPrimaryRest` token | Linear gradient (`letroGradient1 → letroGradient5`) via custom `makePrimaryBackground` in `CompoundButtonStyle` |
| Compound colour overrides | Not overridden | Extended: `gradientAction` stops, `bgActionPrimaryRest/Pressed/Disabled`, `textActionPrimary` all mapped to Letro gradient palette |
| `letroPrimary` colour | `#C20000` (D-0001) | `#F32D1B`; `letroSecondary` (`#F9BC15`) and five gradient steps (`#CB2000`–`#F7B000`) added |
| App URLs | Leftover `element.io`/`matrix.org` references | `elementWebHosts`, `accountProvisioningHost`, `pushGatewayBaseURL`, `analyticsTermsURL`, `bugReportApplicationID` corrected to `letro.com`/`letro` |
| App Store link | Element Pro app | Letro Pro app (`id6758909629`) |
| Live-location permission | `NSLocationWhenInUseUsageDescription` only | `NSLocationAlwaysAndWhenInUseUsageDescription` added for background live-location |

#### **Files Modified**

- `ElementX/Sources/Application/Settings/AppSettings.swift`
- `ElementX/Sources/Letro/Extensions/CompoundExtensions.swift`
- `ElementX/Sources/Letro/Extensions/SwiftUIExtensions.swift`
- `ElementX/SupportingFiles/Info.plist`
- `ElementX/SupportingFiles/target.yml`
- `ElementX/Resources/Localizations/en.lproj/Letro.strings`
- `ElementX/Resources/Localizations/en.lproj/Letro.stringsdict`
- `compound-ios/Sources/Compound/BaseStyles/CompoundButtonStyle.swift`

#### **Impact & Risk**

- **Impact**: Visual impact on all primary action buttons and gradient surfaces. URL changes affect bug reporting, analytics, web-link handling, and push gateway routing. Background-location permission is required for live-location feature to work correctly on iOS.
- **Risk Level**: `MEDIUM`. Colour and URL changes are self-contained; gradient button logic modifies a shared Compound component and must be retested on iOS 26.

#### **AGPL Relevance**

Not Applicable

---

### **D-0001: Letro rebranding — identity, UI, configuration, and behaviour customisations**

- **Upstream baseline commit**: `0fc0e68346f90488e4af21fd5528b2e978aa3247`
- **Fork commit (merge)**: `e0ca2acc43649d4c80194d84d2179a7a9310d7eb` (PR #1 — `p-num/letroMain`)
- **Type**: `Behavioral`
- **Date**: `2026-04-10`

#### **Description**

A comprehensive rebrand and product customisation of Element X iOS into "Letro". The changes span the app's identity (name, bundle ID, icons), its visual design (colours, shapes, custom assets), several screens (authentication, home, spaces, settings), and supporting infrastructure (string-override mechanism, SwiftGen template, entitlements).

#### **Upstream vs. Fork Behavior**

| Area | Upstream (Element X) | Fork (Letro) |
|---|---|---|
| App identity | Bundle ID `io.element.elementx`, display name "Element X", dev team `7J4U792NQT` | Bundle ID `com.letro.cloudclient`, display name "Letro", dev team `44TCX5L4G2` |
| Default Matrix server | `matrix.org` | `ess.postnumber.com` |
| Colour theme | System (light/dark) | Forced light theme; Compound gradient/accent tokens overridden with orange palette |
| Avatar shape | Circular throughout | Rounded rectangle throughout |
| Authentication screen | Element-branded scrollable layout with logo and sign-in buttons | Custom background image, logo type, "Get Started" → bottom-sheet flow showing sign-in buttons; hardcoded non-localised promo text |
| String localisation | Standard `Localizable.strings` lookup | Additional `Letro.strings`/`Letro.stringsdict` override table checked first, allowing any string to be shadowed without editing upstream files |
| Icons (tab bar / new button) | Compound icon set | Custom SVGs (`letro-icon-chat`, `letro-icon-space`, `letro-icon-new`); `CompoundIcon` patched with static override registry |
| Tab bar label colours | Default Compound accent | Custom `letroGray` (normal) / `letroPrimary` red (selected) |
| Settings screen | Shows "Report a problem" and "Analytics" rows | Both rows commented out / hidden |
| Onboarding analytics prompt | Shown when analytics consent is pending | Always skipped (`requiresAnalyticsSetup` hardcoded to `false`) |
| New-chat / new-space toolbar button | `CompoundIcon(\.plus)` with `.super` style | Custom `letro-icon-new` image; iOS 26 `sharedBackgroundVisibility` hidden |
| App URLs | All point to `element.io` | All point to `letro.com` (website, copyright, privacy, OIDC redirect, etc.) |
| Push (NSE) entitlement | Present | Temporarily removed to allow TestFlight submission |
| App version | `26.04.1` / build `1` | `1.0.3` / build `3` |

#### **Files Modified**

- `app.yml`
- `project.yml`
- `ElementX/SupportingFiles/target.yml`
- `ElementX/SupportingFiles/ElementX.entitlements`
- `NSE/SupportingFiles/NSE.entitlements`
- `ElementX/Sources/Application/Application.swift`
- `ElementX/Sources/Application/Navigation/NavigationTabCoordinator.swift`
- `ElementX/Sources/Application/Settings/AppSettings.swift`
- `ElementX/Sources/FlowCoordinators/OnboardingFlowCoordinator.swift`
- `ElementX/Sources/Generated/Assets.swift`
- `ElementX/Sources/Generated/Strings.swift`
- `ElementX/Sources/Letro/Extensions/CompoundExtensions.swift` *(new)*
- `ElementX/Sources/Letro/Extensions/SwiftUIExtensions.swift` *(new)*
- `ElementX/Sources/Other/Avatars.swift`
- `ElementX/Sources/Other/SwiftUI/Views/RoomAvatarImage.swift`
- `ElementX/Sources/Other/SwiftUI/Views/TombstonedAvatarImage.swift`
- `ElementX/Sources/Screens/Authentication/StartScreen/View/AuthenticationStartScreen.swift`
- `ElementX/Sources/Screens/HomeScreen/View/Filters/RoomListFilterView.swift`
- `ElementX/Sources/Screens/HomeScreen/View/HomeScreen.swift`
- `ElementX/Sources/Screens/RoomDetailsEditScreen/View/RoomDetailsEditScreen.swift`
- `ElementX/Sources/Screens/Settings/SettingsScreen/View/SettingsScreen.swift`
- `ElementX/Sources/Screens/Spaces/SpacesScreen/View/SpacesScreen.swift`
- `ElementX/Resources/Localizations/en.lproj/Letro.strings` *(new)*
- `ElementX/Resources/Localizations/en.lproj/Letro.stringsdict` *(new)*
- `ElementX/Resources/AppIcon.icon/` *(icon assets replaced)*
- `ElementX/Resources/Assets.xcassets/images/` *(new Letro image assets)*
- `compound-ios/Sources/Compound/Icons/CompoundIcon.swift`
- `Tools/SwiftGen/Templates/Strings/structured-swift5-element.stencil`
- `ElementX.xcodeproj/project.pbxproj`
- `ElementX.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`
- `ElementX.xcodeproj/xcshareddata/xcschemes/*.xcscheme` *(scheme renames/updates)*

#### **Impact & Risk**

- **Impact**: Touches app identity, all major screens, the global colour/icon system, the string localisation pipeline, onboarding flow, and build configuration. Any upstream merge must re-apply or carefully reconcile every change. New image assets and the `Letro.strings` override table must be maintained alongside upstream string additions.
- **Risk Level**: `HIGH`. The breadth of changes (authentication screen, string layer, Compound overrides, entitlements) means upstream updates carry a significant merge-conflict and regression risk.

#### **AGPL Relevance**

Not Applicable