Others
@@ -1299,14 +1095,14 @@ Fixes for MacOS and Windows builds. ### Updated Electron to 0.31.0 -- New demo URL +- New demo URL ## 0.5.0 - 2015-Jul-27 ### Upgrade electron to 0.30.2 - Better error message -- Disabled _tray.setTitle(title); until it can be optional +- Disabled \_tray.setTitle(title); until it can be optional - Fix crash when closing app from try in OS X - Fixed oAuth logins - Increase start window size diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..b32549f531 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Claude Instructions + +See [AGENTS.md](./AGENTS.md) for development guidelines. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 13c93becc2..0b4e9380c3 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -14,21 +14,21 @@ and orientation. Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or +- The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities diff --git a/LICENSE b/LICENSE index 41deab4110..00f22618cf 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015-2025 Rocket.Chat Technologies Corp. +Copyright (c) 2015-2026 Rocket.Chat Technologies Corp. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 63a65091e8..a906183bb9 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ # Rocket.Chat Desktop App -[](https://travis-ci.org/RocketChat/Rocket.Chat.Electron) -[](https://ci.appveyor.com/project/RocketChat/rocket-chat-electron) -[](https://www.codacy.com/app/tassoevan/Rocket.Chat.Electron?utm_source=github.com&utm_medium=referral&utm_content=RocketChat/Rocket.Chat.Electron&utm_campaign=Badge_Grade) -[](https://david-dm.org/RocketChat/Rocket.Chat.Electron) +[](https://github.com/RocketChat/Rocket.Chat.Electron/actions) + [](https://github.com/RocketChat/Rocket.Chat.Electron/releases/latest)  @@ -14,13 +12,25 @@ using [Electron][]. --- +## Supported Platforms + +| Platform | Minimum Version | Architectures | Formats | +| -------- | --------------------------- | ------------------------------- | -------------------------------- | +| Windows | 10 | x64, ia32, arm64 | NSIS, MSI | +| macOS | 12 (Monterey) | Universal (x64 + Apple Silicon) | DMG, PKG, ZIP | +| Linux | Ubuntu 22.04+ or equivalent | x64 | AppImage, deb, rpm, snap, tar.gz | + +--- + ## Engage with us ### Share your story -We’d love to hear about [your experience][] and potentially feature it on our + +We'd love to hear about [your experience][] and potentially feature it on our [Blog][]. ### Subscribe for Updates + Once a month our marketing team releases an email update with news about product releases, company related topics, events and use cases. [Sign Up!][] @@ -30,7 +40,9 @@ releases, company related topics, events and use cases. [Sign Up!][] You can download the latest version from the [Releases][] page. -[](https://snapcraft.io/rocketchat-desktop) +
+ 
+
fetchState = loading"] --> CheckServer{"Retry Server
3x with 2s delay"} + + CheckServer -->|Success| ServerOK["Use Server data
Save to localStorage
fetchState = success"] + ServerOK --> Dispatch1["Dispatch UPDATED
Done"] + + CheckServer -->|All 3 fail| CheckCloud{"Retry Cloud
3x with 2s delay"} + + CheckCloud -->|Success| CloudOK["Use Cloud data
Save to localStorage
fetchState = success"] + CloudOK --> Dispatch2["Dispatch UPDATED
Done"] + + CheckCloud -->|All 3 fail| CheckCache{"Try localStorage
supportedVersions:url"} + + CheckCache -->|Found| CacheOK["Use Cached data
fetchState = error"] + CacheOK --> Dispatch3["Dispatch UPDATED
Allow access"] + + CheckCache -->|Not found| UseBuiltin["Use Builtin data
fetchState = error"] + UseBuiltin --> Dispatch3 + + Dispatch1 --> EvalBlock + Dispatch2 --> EvalBlock + Dispatch3 --> EvalBlock + + EvalBlock{"Blocking Decision
isSupported === false
AND
fetchState !== loading"} + + EvalBlock -->|No| AllowAccess["✅ ALLOW ACCESS
User can access webview"] + EvalBlock -->|Yes| BlockAccess["❌ BLOCK ACCESS
Show UnsupportedServer overlay"] + + style Start fill:#e1f5ff + style ServerOK fill:#c8e6c9 + style CloudOK fill:#c8e6c9 + style CacheOK fill:#fff9c4 + style UseBuiltin fill:#fff9c4 + style AllowAccess fill:#c8e6c9 + style BlockAccess fill:#ffcdd2 +``` + +--- + +## Retry Logic Detail + +Each source (Server and Cloud) is retried 3 times with 2-second delays: + +```mermaid +sequenceDiagram + participant Desktop + participant Server + participant Delay + + Desktop->>+Server: Attempt 1 (fetch) + Server-->>-Desktop: Timeout/Error + Desktop->>Delay: Wait 2 seconds + Delay-->>Desktop: ✓ Ready + + Desktop->>+Server: Attempt 2 (fetch) + Server-->>-Desktop: Timeout/Error + Desktop->>Delay: Wait 2 seconds + Delay-->>Desktop: ✓ Ready + + Desktop->>+Server: Attempt 3 (fetch) + Server-->>-Desktop: Timeout/Error + Desktop->>Delay: Move to Cloud +``` + +**Total wait per source**: Up to 4 seconds (3 attempts with 2 waits × 2s delays) + +--- + +## Blocking Decision Logic + +```mermaid +graph TD + Check{"Is server
unsupported?"} + + Check -->|isSupported = true| Allow["✅ ALLOW"] + Check -->|isSupported = false| CheckState + + CheckState{"What is
fetchState?"} + + CheckState -->|loading| Allow2["✅ ALLOW
Still fetching, not proven"] + CheckState -->|success| Block["❌ BLOCK
Fresh data confirms unsupported"] + CheckState -->|error| Block2["❌ BLOCK
Block if fallback confirms unsupported; otherwise allow (uncertain data)"] + + style Allow fill:#c8e6c9 + style Allow2 fill:#c8e6c9 + style Block fill:#ffcdd2 + style Block2 fill:#ffcdd2 +``` + +--- + +## Validation Throttling (30-Minute Window) + +To reduce expensive validation checks on every navigation, the app implements a **30-minute throttle** on the `isServerVersionSupported()` validation logic (independent from the 12-hour dialog suppression). + +### How it Works + +```mermaid +timeline + title Validation Throttle Timeline + 0min: User navigates → Full validation runs + 0min: supportedVersionsValidatedAt = now + 10min: User navigates again → Check throttle + 10min: Time since last validation < 30min → SKIP validation + 10min: Still check 12-hour dialog suppression + 30min: User navigates → 30min has passed → Run full validation + 30min: supportedVersionsValidatedAt = now + 40min: User navigates → SKIP validation (within 30min window) + 12h: User navigates → Even within throttle, show dialog if suppression expired +``` + +### Throttle Behavior + +| Navigation | Time Since Last Validation | Action | +| --------------------- | -------------------------- | ----------------------------------------------- | +| First load | N/A | ✅ Run full validation | +| Within 30 minutes | < 30 min | ⏸️ Skip validation, check 12h timer | +| After 30 minutes | ≥ 30 min | ✅ Run full validation again | +| Dialog showing timing | Independent | ✅ Can show if 12h passed, even within throttle | + +### Benefits + +- **Reduces API load**: Validation runs at most once per 30 minutes per server +- **Maintains accuracy**: Fresh check every 30 minutes ensures data isn't stale +- **Preserves warning display**: 12-hour dialog suppression works independently +- **Navigation performance**: Repeated navigation within 30 min doesn't trigger expensive checks + +### When Throttle is Bypassed + +- ✅ Server reload (manual or forced) - Always validates fresh +- ✅ Server switch - Different server always validates +- ✅ Dialog dismissed - Triggers fetch, resets validation timer +- ✅ App startup (WEBVIEW_READY) - Always validates first time + +--- + +## Modal Display Logic + +The version support modal (warning dialog) appears independently from the blocking overlay. It shows version expiration information and is controlled by the `fetchState`: + +```mermaid +graph TD + Check{"Has version
data available?"} + + Check -->|No| NoModal["❌ NO MODAL
supportedVersions = undefined"] + Check -->|Yes| CheckFetch + + CheckFetch{"Is data
currently loading?"} + + CheckFetch -->|loading| NoModal2["❌ NO MODAL
fetchState = loading
Wait for data"] + CheckFetch -->|not loading| HasModal + + HasModal["✅ SHOW MODAL
if expiration warning exists
(any data source: fresh, cached, builtin)"] + + style NoModal fill:#fff9c4 + style NoModal2 fill:#fff9c4 + style HasModal fill:#c8e6c9 +``` + +**Modal shows when**: + +- `supportedVersions` data exists AND +- `fetchState !== 'loading'` (not actively fetching) AND +- 12 hours have passed since last shown (independent timer) AND +- Server version is expiring soon (has expiration message) + +**Modal skips when**: + +- No data available (`supportedVersions` undefined) +- Currently fetching (`fetchState === 'loading'`) +- Within 12-hour display suppression window (shows max once per 12 hours) + +**Data sources that trigger modal**: + +- ✅ Fresh server data (`fetchState === 'success'`) +- ✅ Fresh cloud data (`fetchState === 'success'`) +- ✅ Stale cached data (`fetchState === 'error'`) +- ✅ Generic builtin fallback (`fetchState === 'error'`) + +**Key difference from blocking overlay**: + +- **Overlay blocks access** - only when definitely unsupported with fresh data +- **Modal warns users** - shows expiration info from any available data, but not while actively loading +- **Modal has separate suppression** - shows max once per 12 hours independent of validation throttle + +--- + +## Per-Server State Structure + +```typescript +// Redux state for each server +{ + url: "https://chat.example.com", + version: "7.1.0", + + // Version support data + supportedVersionsData: SupportedVersions | undefined, + supportedVersionsFetchState: 'idle' | 'loading' | 'success' | 'error', + isSupportedVersion: boolean | undefined, + supportedVersionsValidatedAt?: Date, // Timestamp of last validation (for 30-min throttle) + + // Warning display management + expirationMessageLastTimeShown?: Date, // 12-hour dialog suppression timer + + // Other fields... + title: string, + failed: boolean, + // ... +} + +// localStorage structure (per server) +localStorage['supportedVersions:https://chat.example.com'] = { + versions: [...], + exceptions: {...}, + timestamp: "2024-10-31T...", + enforcementStartDate: "2024-11-15T..." +} +``` + +**New field `supportedVersionsValidatedAt`**: + +- Tracks when the last version validation check occurred +- Used to implement 30-minute validation throttle (see "Validation Throttling" section) +- Independent from the 12-hour dialog suppression timer + +--- + +## Scenario Examples + +### Scenario 1: Fast Network (Server Responds) + +```mermaid +timeline + title Fast Network - Server Available + 0s: User opens server → fetchState = loading + 1s: Server responds ✓ + 1s: Save to localStorage + 1s: fetchState = success + 1s: Evaluate blocking + 1s: User sees webview (or overlay if unsupported) +``` + +**Total time**: ~1 second + +--- + +### Scenario 2: Slow Server + Fast Cloud + +```mermaid +timeline + title Slow Server - Cloud Available + 0s: User opens server → fetchState = loading + 2s: Server attempt 1 timeout + 2s: Wait 2s + 4s: Server attempt 2 timeout + 4s: Wait 2s + 6s: Server attempt 3 timeout + 6s: Try Cloud + 7s: Cloud responds ✓ + 7s: Save to localStorage + 7s: fetchState = success + 7s: User sees webview +``` + +**Total time**: ~7 seconds + +--- + +### Scenario 3: Offline with Cached Data + +```mermaid +timeline + title Offline - Cache Available + 0s: User opens server → fetchState = loading + 2s: Server attempt 1 timeout + 2s: Wait 2s + 4s: Server attempt 2 timeout + 4s: Wait 2s + 6s: Server attempt 3 timeout + 6s: Try Cloud + 8s: Cloud attempt 1 timeout + 8s: Wait 2s + 10s: Cloud attempt 2 timeout + 10s: Wait 2s + 12s: Cloud attempt 3 timeout + 12s: Try localStorage + 12s: Found cached data ✓ + 12s: fetchState = error + 12s: User sees webview (using cache) +``` + +**Total time**: ~12 seconds +**Result**: User can work, using last-known-good data + +--- + +### Scenario 4: Offline + No Cache + Builtin Blocks + +```mermaid +timeline + title Offline, No Cache, Unsupported + 0s: User opens server → fetchState = loading + 6s: Server retries fail + 12s: Cloud retries fail + 12s: localStorage check → not found + 12s: Use Builtin + 12s: Builtin says unsupported + 12s: fetchState = error + 12s: Blocking condition met + 12s: UnsupportedServer overlay shown +``` + +**Total time**: ~12 seconds +**Result**: User blocked (builtin confirms unsupported) + +--- + +### Scenario 5: Airgapped Network (Server Available) + +```mermaid +timeline + title Airgapped - Local Server Only + 0s: User opens server → fetchState = loading + 1s: Server responds ✓ + 1s: Save to localStorage + 1s: fetchState = success + 1s: Cloud not attempted (server succeeded) + 1s: User sees webview +``` + +**Total time**: ~1 second +**Key**: Cloud retries skipped because Server already succeeded + +--- + +## Data Flow Architecture + +```mermaid +graph LR + A["Update triggered
(WEBVIEW_READY,
manual refresh)"] + + A --> B["Dispatch
LOADING"] + B --> C["Set fetchState
= loading"] + + C --> D["updateSupportedVersionsData()
Start fetch sequence"] + + D --> E1["Retry Server
3x with delays"] + E1 -->|Success| F["Dispatch UPDATED
fetchState = success"] + E1 -->|Fail| E2["Retry Cloud
3x with delays"] + + E2 -->|Success| F + E2 -->|Fail| E3["Load localStorage"] + + E3 -->|Found| G["Dispatch UPDATED
fetchState = error"] + E3 -->|Not found| E4["Use Builtin
always available"] + E4 --> G + + F --> H["Update Redux state"] + G --> H + + H --> I["Component re-renders"] + I --> J{"Blocking
condition?"} + + J -->|No| K["Show webview"] + J -->|Yes| L["Show UnsupportedServer
overlay"] + + style A fill:#e1f5ff + style B fill:#e1f5ff + style C fill:#e1f5ff + style D fill:#fff3e0 + style E1 fill:#fff3e0 + style E2 fill:#fff3e0 + style E3 fill:#fff9c4 + style E4 fill:#fff9c4 + style F fill:#c8e6c9 + style G fill:#fff9c4 + style H fill:#e1f5ff + style K fill:#c8e6c9 + style L fill:#ffcdd2 +``` + +--- + +## Component Integration + +```mermaid +graph TD + SV["ServersView
maps servers"] + SP["ServerPane
per server UI"] + US["UnsupportedServer
overlay component"] + + SV --> SP + SP --> US + + Props["Props passed down:
- isSupportedVersion
- supportedVersionsFetchState"] + + SP -.->|passes| Props + Props --> US + + US --> Logic["if fetchState !== 'loading'
AND isSupported === false
→ show overlay"] + + style SV fill:#e1f5ff + style SP fill:#e3f2fd + style US fill:#f3e5f5 + style Logic fill:#ffcdd2 +``` + +--- + +## URL Encoding & Cloud API Requirements + +### URL Parameter Encoding + +The app constructs API URLs with proper URL encoding to ensure reliable server communication: + +```typescript +// Query parameter for uniqueID lookup (< v7.0.0) +// ✅ Properly encoded: +`${serverUrl}api/v1/settings.public?query=${encodeURIComponent(JSON.stringify({ _id: 'uniqueID' }))}`; +// Results in: ?query=%7B%22_id%22%3A%20%22uniqueID%22%7D + +// ❌ Would fail if unencoded (causes "Invalid query parameter" errors): +// `${serverUrl}api/v1/settings.public?query={"_id": "uniqueID"}` +``` + +**Why encoding matters**: + +- Servers validate query parameters strictly +- Special characters in JSON (quotes, braces) must be URL-encoded +- Without encoding, older Rocket.Chat versions (especially v6.x) reject the request +- With proper encoding, all server versions handle it reliably + +### Cloud API Domain Requirement + +The Cloud API endpoint requires a valid **domain** (not IP address) to look up server-specific version policies: + +```text +https://releases.rocket.chat/v2/server/supportedVersions?domain={domain}&uniqueId={uniqueId}&source=desktop +``` + +**Domain requirement**: + +- ✅ Works: `domain=chat.company.com` +- ✅ Works: `domain=ngrok-provided-url.ngrok.io` (tunneled service) +- ❌ Fails: `domain=192.168.1.100:3000` (IP addresses not recognized by Cloud API) +- ❌ Fails: `domain=192.168.1.100:3000:3620` (malformed) + +**Workarounds for local/internal servers**: + +1. Use a reverse proxy with domain routing (ngrok, Caddy, nginx) +2. Add DNS record pointing to the server IP +3. Configure local `/etc/hosts` entry if only for local access + +**Impact when domain is unavailable**: + +- Cloud API returns generic/default version policies +- Server may not be correctly identified +- Version validation uses fallback data (cache or builtin) +- May not reflect server-specific policies + +--- + +## Cache Management + +### Storage Strategy + +- **Key format**: `supportedVersions:${serverUrl}` +- **Value**: Complete `SupportedVersions` object with timestamp +- **Per-server**: Each server has its own cache entry +- **On success**: Automatically saved to localStorage +- **On failure**: Automatically loaded if available + +### Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> NoCache: App loads
no data + + NoCache --> Fetch: User opens server + Fetch --> Success: Server/Cloud succeeds + Fetch --> NoCacheFail: All fail + + Success --> Cached: Save to localStorage + + NoCacheFail --> Builtin: Use builtin + Builtin --> Cached2: If builtin saved + + Cached --> Ready: Data available + Cached2 --> Ready + + Ready --> UseCached: On next open
or on fetch fail + UseCached --> Ready + + note right of Cached + Data persists across + app sessions + end note + + note right of UseCached + Faster recovery on + network issues + end note +``` + +--- + +## Summary + +### Fetch Scenarios + +| Scenario | Server | Cloud | Cache | Builtin | Result | Time | +| ------------------ | ------ | ----- | ----- | ------- | ---------------------------- | ---- | +| Fast network | ✓ | - | - | - | Allow/Block based on data | ~1s | +| Slow server | ✗ | ✓ | - | - | Allow/Block based on data | ~7s | +| Offline + cache | ✗ | ✗ | ✓ | - | ALLOW (uncertain) | ~10s | +| Offline + no cache | ✗ | ✗ | ✗ | ✓ | Allow/Block based on builtin | ~12s | +| Airgapped | ✓ | ✗ | - | - | Allow/Block (Cloud skipped) | ~1s | + +### Validation Throttle Scenarios + +| Scenario | Last Validation | Time Elapsed | Action | +| ------------------------ | --------------- | ------------ | ------------------------------------ | +| First navigation | None | N/A | ✅ Run full validation | +| Subsequent nav (quick) | 5 min ago | 5 min | ⏸️ Skip validation (within 30 min) | +| Subsequent nav (delayed) | 35 min ago | 35 min | ✅ Run validation (30 min passed) | +| Server reload | Any time | Any time | ✅ Always validate (bypass throttle) | +| Dialog dismissed | Any time | Any time | ✅ Always validate (bypass throttle) | + +### Key Principles + +1. **Blocking decision**: Block only on fresh `success` state with confirmed unsupported version. Allow on `loading` state. On `error` state, block if fallback data (cache or builtin) confirms unsupported version. + +2. **Validation throttle**: Expensive validation checks run max once per 30 minutes per server. Reduces API load while maintaining accuracy. + +3. **Warning display**: Modal shows max once per 12 hours (independent of validation throttle). Can appear even within 30-minute validation window if 12 hours have passed. + +4. **False positive prevention**: With proper URL encoding and Cloud API integration, supported servers no longer show false unsupported warnings due to transient failures. + +5. **Fallback reliability**: Multiple fallback sources (cache, builtin) ensure users can always access servers, even in offline scenarios. diff --git a/docs/video-call-screen-sharing.md b/docs/video-call-screen-sharing.md new file mode 100644 index 0000000000..2d3bec6080 --- /dev/null +++ b/docs/video-call-screen-sharing.md @@ -0,0 +1,485 @@ +# Video Call Screen Sharing + +## Overview + +This document shows how screen sharing works within an active video call in Rocket.Chat Electron. + +## Cache Architecture + +The screen sharing system uses a **stale-while-revalidate** caching pattern for optimal performance: + +``` +Desktop Capturer Cache +├── Always returns cached data immediately (instant UX) +├── If data older than 3s, triggers background refresh +├── Next request gets fresh data +└── Cache persists indefinitely (never expires) +``` + +## Screen Sharing Flow + +```mermaid +flowchart TD + %% Pre-warming Phase (on Video Call Load) + START[Video Call Window Loaded] --> PW1[did-finish-load Event] + PW1 --> PW2[Trigger prewarm-capturer-cache IPC] + PW2 --> PW3[Call refreshDesktopCapturerCache] + PW3 --> PW4[Fetch Sources in Background] + PW4 --> PW5[Populate Cache with Timestamp] + PW5 --> PW6[Cache Ready for Instant Access] + + %% Screen Sharing Initiation + A[Video Call Active] --> B[User Requests Screen Share] + B --> C[Webview Calls requestScreenSharing API] + C --> D[Preload Script Receives Request] + + %% IPC to Renderer + D --> E[Send video-call-window/open-screen-picker IPC] + E --> F[Renderer Receives Request] + F --> G{ScreenSharePicker Mounted?} + G -->|No| G1[Lazy Import React Module] + G1 --> G2[Mount ScreenSharePicker Hidden] + G -->|Yes| H[Show ScreenSharePicker] + G2 --> H + + %% Stale-While-Revalidate Cache + H --> I[Request Desktop Capturer Sources] + I --> J{Cache Exists?} + J -->|No| K[First Fetch - Wait for Sources] + J -->|Yes| L[Return Cached Sources Immediately] + + %% Staleness Check + L --> M{Cache Age > 3 seconds?} + M -->|No| N[Use Fresh Cache] + M -->|Yes| O[Trigger Background Refresh] + O --> P[refreshDesktopCapturerCache Async] + P --> Q[Fetch New Sources] + Q --> R[Update Cache with New Data] + R --> S[Next Request Gets Fresh Data] + N --> T[Display Sources in UI] + L --> T + + %% First Fetch Path + K --> K1[Call desktopCapturer.getSources] + K1 --> K2[System Returns Sources] + K2 --> K3[Filter Invalid Sources] + K3 --> K4[Cache Sources with Timestamp] + K4 --> T + + %% Source Selection UI + T --> U[Display Sources in Tabs] + U --> V[Windows Tab - Application Windows] + U --> W[Screens Tab - Desktop Displays] + V --> X[User Selects Window] + W --> Y[User Selects Screen] + X --> Z[Validate Selected Source] + Y --> Z + + %% Source Validation with Caching + Z --> AA{Source in Validation Cache?} + AA -->|Yes - Within 30s| AB[Return Cached Validation] + AA -->|No| AC[Validate Source Availability] + AC --> AD[Check Source Still Exists] + AD --> AE{Source Valid?} + AE -->|Yes| AF[Cache Validation 30s] + AE -->|No| AG[Show Source Unavailable Error] + AF --> AB + AB --> AH[Return Source ID] + + %% IPC Response to Webview + AH --> AI[Send Source ID via IPC Response] + AI --> AJ[Preload Script Receives Source ID] + AJ --> AK[Return Source to Webview] + AK --> AL[Webview Gets Stream Access] + AL --> AM[Screen Share Active] + + %% Error Recovery + AG --> AN[User Selects Different Source] + AN --> Z + + %% User Closes Picker Without Selecting + H --> AO[User Closes Picker] + AO --> AP[Hide ScreenSharePicker] + AP --> AQ[Component Stays Mounted] + AQ --> A + + %% Cache Persistence + AM --> AR[Video Call Continues] + AR --> AS{User Requests Screen Share Again?} + AS -->|Yes| B + AS -->|No| AT[Video Call Ends] + AT --> AU[Window Closes] + AU --> AV[Cache Persists in Memory] + AV --> AW{App Quit or Error?} + AW -->|Yes| AX[Clear All Caches] + AW -->|No| AY[Cache Available for Next Call] + + %% Background Refresh Details + P --> BA{Fetch Already in Progress?} + BA -->|Yes| BB[Skip - Deduplication] + BA -->|No| BC[Start Async Fetch] + BC --> Q + + %% Styling + classDef mainProcess fill:#e1f5fe,stroke:#0277bd,stroke-width:2px + classDef renderer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + classDef webview fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px + classDef cache fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + classDef ui fill:#fff3e0,stroke:#f57c00,stroke-width:2px + classDef validation fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px + classDef error fill:#ffebee,stroke:#c62828,stroke-width:2px + classDef success fill:#e8f5e8,stroke:#388e3c,stroke-width:2px + classDef prewarm fill:#fff8e1,stroke:#ffa000,stroke-width:2px + + class PW2,PW3,K1,K2,K3,AI mainProcess + class D,E,F,G,G1,G2,AJ,AK renderer + class A,C,AL,AM,AR webview + class I,J,K4,L,M,N,O,P,Q,R,S,BA,BB,BC,AV,AW,AX,AY cache + class H,T,U,V,W,X,Y,AO,AP,AQ ui + class Z,AA,AB,AC,AD,AE,AF validation + class AG,AN error + class AH,AL,AM success + class START,PW1,PW2,PW3,PW4,PW5,PW6 prewarm +``` + +## Explanation + +**What this diagram shows:** + +- Cache pre-warming when video call loads +- Stale-while-revalidate pattern for instant display +- Background refresh keeping thumbnails current +- Deferred React loading for the picker component + +**Key parts:** + +1. **Pre-warming** - Cache populated when video call loads +2. **Instant Display** - Always returns cached data immediately +3. **Background Refresh** - Updates stale cache without blocking UI +4. **Source Selection** - Tabbed interface for windows and screens +5. **Validation** - Ensures selected source still exists +6. **Persistence** - Cache survives window close for next call + +**Cache Behavior:** + +- **Stale threshold**: 3 seconds +- **Validation cache**: 30 seconds +- **Expiration**: Never (persists until app quit or error) +- **Memory**: Varies based on number of sources and thumbnail sizes + +**Color Guide:** + +- **Blue** - Main process operations +- **Purple** - Renderer process & Validation +- **Green** - Webview & Success states +- **Light Blue** - Cache operations +- **Orange** - User interface elements +- **Yellow** - Pre-warming phase +- **Red** - Error states + +## Detailed Step-by-Step Explanation + +### 1. Cache Pre-warming + +When the video call webview finishes loading, the app proactively populates the cache. + +**What happens:** + +- `did-finish-load` event triggers pre-warming +- `video-call-window/prewarm-capturer-cache` IPC called +- `refreshDesktopCapturerCache()` fetches sources in background +- Cache populated before user ever clicks screen share +- First screen picker open shows sources instantly + +### 2. Starting Screen Sharing + +When you click the screen share button during a video call. + +**What happens:** + +- Video call website detects your click +- Calls the screen sharing API provided by the preload script +- IPC message sent to renderer process +- ScreenSharePicker component shown (or mounted if first time) + +### 3. Deferred React Loading + +The ScreenSharePicker React component is loaded lazily. + +**What happens:** + +- First screen share request triggers dynamic import +- `screenSharePickerMount.tsx` loaded asynchronously +- React component mounted and kept in DOM +- Subsequent opens just toggle visibility (instant) + +### 4. Stale-While-Revalidate Cache + +The core caching strategy that makes screen sharing feel instant. + +**What happens:** + +- Request comes in for desktop capturer sources +- **If cache exists**: Return immediately (no waiting) +- **If cache older than 3s**: Trigger background refresh +- **Background refresh**: Fetches new sources asynchronously +- **Next request**: Gets the fresh data +- **Cache never expires**: Only cleared on error or app quit + +**Example flow (illustrative timings):** + +``` +T=0s: User opens picker → Cache returns instantly (2s old) +T=0s: Background refresh starts (async) +T=1s: Background refresh completes, cache updated +T=5s: User opens picker again → Gets fresh data instantly +``` + +### 5. Source Filtering and Validation + +Sources are filtered and validated before display. + +**Filtering (during fetch):** + +- Removes sources with empty names +- Removes sources with empty thumbnails +- Only valid sources cached + +**Validation (on selection):** + +- Checks if selected source still exists +- Cached for 30 seconds to avoid repeated checks +- Shows error if source no longer available + +### 6. Source Selection UI + +Clean tabbed interface for choosing what to share. + +**What happens:** + +- **Windows tab**: Shows application windows with thumbnails +- **Screens tab**: Shows connected displays +- Preview thumbnails help identify correct source +- Click to select, picker closes automatically + +### 7. Cache Persistence + +Cache survives beyond the video call window lifecycle. + +**What happens:** + +- Video call window closes +- Cache remains in memory +- Next video call benefits from existing cache +- Only cleared on: + - Application quit + - Explicit cleanup call + - Fetch error (keeps last good data on error) + +### 8. Promise Deduplication + +Prevents multiple simultaneous fetches. + +**What happens:** + +- If fetch already in progress, new requests wait for it +- Single system call even with rapid requests +- Reduces CPU and memory pressure + +## Why Stale-While-Revalidate? + +### Previous Approach (TTL-based) + +``` +Cache hit within 3s → Return cached data +Cache expired → Fetch new data (blocking) +Window close → Schedule 60s cleanup timer +``` + +**Problems:** + +- Empty state possible if cache expired +- Blocking fetch when cache expired +- Complex cleanup logic + +### Current Approach (Stale-While-Revalidate) + +``` +Cache exists → Return immediately (always instant) +Cache stale → Background refresh (non-blocking) +Window close → Keep cache (no cleanup timer) +``` + +**Benefits:** + +- Never shows empty/loading state +- Thumbnails stay current through background refresh +- Simpler code, better UX + +## Performance Characteristics + +### Response Times + +| Scenario | Behavior | +| --------------------- | --------------------------------------------- | +| Pre-warmed cache | Instant (no delay) | +| Cache hit (fresh) | Instant (no delay) | +| Cache hit (stale) | Instant return with background refresh | +| Cold start (no cache) | Requires initial system call to fetch sources | + +### Memory Usage + +| Component | Behavior | +| ---------------- | ------------------------------------------------------ | +| Source metadata | Minimal overhead per source | +| Thumbnails | Varies with number of sources and thumbnail resolution | +| Validation cache | Negligible overhead | + +### Cache Lifecycle + +``` +App Start + │ + ▼ +Video Call Opens + │ + ├─► did-finish-load → Pre-warm cache + │ + ▼ +Screen Share Request + │ + ├─► Return cached (instant) + ├─► Background refresh if stale + │ + ▼ +Video Call Closes + │ + ├─► Cache persists + │ + ▼ +Next Video Call + │ + ├─► Cache still available + │ + ▼ +App Quit + │ + └─► Cache cleared +``` + +## Technical Implementation + +### Stale-While-Revalidate Logic + +```typescript +const DESKTOP_CAPTURER_STALE_THRESHOLD = 3000; + +handle('desktop-capturer-get-sources', async (_webContents, opts) => { + const options = Array.isArray(opts) ? opts[0] : opts; + + if (desktopCapturerCache) { + const isStale = + Date.now() - desktopCapturerCache.timestamp > + DESKTOP_CAPTURER_STALE_THRESHOLD; + if (isStale && !desktopCapturerPromise) { + refreshDesktopCapturerCache(options); // Fire and forget + } + return desktopCapturerCache.sources; // Always return immediately + } + + // No cache - wait for initial fetch + refreshDesktopCapturerCache(options); + if (desktopCapturerPromise) { + return await desktopCapturerPromise; + } + return []; +}); +``` + +### Background Refresh Function + +```typescript +const refreshDesktopCapturerCache = ( + options: Electron.SourcesOptions +): void => { + if (desktopCapturerPromise) return; // Deduplication + + desktopCapturerPromise = (async () => { + try { + const sources = await desktopCapturer.getSources(options); + const validSources = sources.filter(/* validation logic */); + + desktopCapturerCache = { + sources: validSources, + timestamp: Date.now(), + }; + return validSources; + } catch (error) { + console.error('Background cache refresh failed:', error); + return desktopCapturerCache?.sources || []; // Keep last good data + } finally { + desktopCapturerPromise = null; + } + })(); +}; +``` + +### Pre-warming Handler + +```typescript +handle('video-call-window/prewarm-capturer-cache', async () => { + refreshDesktopCapturerCache({ types: ['window', 'screen'] }); + return { success: true }; +}); +``` + +### Source Validation Cache + +```typescript +const SOURCE_VALIDATION_CACHE_TTL = 30000; + +// Validates selected source still exists +// Cached for 30 seconds to avoid repeated system calls +const sourceValidationCache: Set
+ {t('logViewer.fileInfo.entries', {
+ count: filteredLogs.length,
+ })}
+
+