Floating Sphere UI
Relevant source files
The following files were used as context for generating this wiki page:
The Floating Sphere UI (also referred to as the MiniSphere or minimized mode) is a compact, "always-on-top" interface for the Nudge AI learning assistant. Its primary purpose is to provide a non-intrusive, persistent presence while the user is working, allowing the AI to observe and intervene through "Focus check-ins" without obstructing the user's workspace. Sources: apps/web/src/components/live/MiniSphere.tsx:16, website/src/renderer.js:64
Component Architecture
The minimized interface is managed primarily through the MiniSphere and MiniBar components, which coordinate with an Electron bridge to handle window resizing and state transitions.
MiniSphere and MiniBar
When the application is minimized, it transitions from a full-stage "InCall" UI to a restricted window size.
- MiniSphere: Represents the AI as a single interactive orb when idle or observing. It includes logic to handle "Focus check-in" prompts, which expand the vertical height of the mini-window to accommodate text and buttons. Sources: apps/web/src/components/live/MiniSphere.tsx:21-40
- MiniBar: Used during active calls where basic controls (mute, camera, screen share) and captions must remain accessible in a compact "pill" format. Sources: apps/web/src/components/live/MiniBar.tsx:40-52
The Electron Bridge
The UI communicates with the host Electron application via a Bridge interface (exposed as window.openlive). This bridge allows the React components to request window-level operations.
| Function | Purpose |
|---|---|
mini() | Signals the desktop app to enter minimized/floating mode. |
unmini() | Signals the desktop app to return to a standard window size. |
miniSize(h) | Dynamically adjusts the height of the floating window to fit content. |
Sources: apps/web/src/components/live/MiniSphere.tsx:11-13, apps/web/src/components/live/MiniBar.tsx:11-13
Visual Representation and State
The core of the interface is the Orb component, which visually reflects the AI's current phase and audio levels.
Orb States
The Orb changes size and animation based on whether the UI is in a "hero" stage or a minimized bar.
- Idle/Observing: In the mini-sphere, the orb is typically 52px or 40px depending on the context. Sources: apps/web/src/components/live/MiniSphere.tsx:75, apps/web/src/components/live/MiniSphere.tsx:64
- Active Sharing: While sharing screen or camera, the orb shrinks into the status pill to stay out of the way. Sources: apps/web/src/components/live/InCall.tsx:96-102
This diagram shows the transition flow between the primary UI states of the floating interface.
Sources: apps/web/src/components/live/MiniSphere.tsx:43-80, apps/web/src/components/live/MiniBar.tsx:87-92
Data Flow and Resizing Logic
The Floating Sphere UI must dynamically adapt its size based on the content it displays, such as captions or the "Focus Check-In" utility.
Resize Observer Implementation
In both MiniSphere and MiniBar, a ResizeObserver is used to monitor the height of the contentRef element. Whenever the content changes (e.g., a new caption appears or a focus prompt is shown), the component calls ol().miniSize(height) to update the Electron window dimensions.
Sequence of events during a dynamic height adjustment initiated by an AI intervention.
Sources: apps/web/src/components/live/MiniSphere.tsx:43-53, apps/web/src/components/live/MiniBar.tsx:58-66
Tool and Status Indicators
While minimized, the UI provides feedback on AI background activity using "shimmer" effects for specific states:
- Warming up: Indicated when the AI model is preparing.
- Observing: Shown when the AI is actively watching the user's screen but staying quiet.
- Tool Execution: Displays the active tool name (e.g., "Searching...").
Sources: apps/web/src/components/live/MiniBar.tsx:70-78, apps/web/src/app/globals.css:140-155
Component Configuration
| Property | Default Value | Description |
|---|---|---|
SPHERE | 64px | The base height for the floating sphere window. |
FOCUS_H | 132px | The target height for the mini-window when a Focus check-in is displayed. |
orb size (mini) | 52px | Size of the orb inside the MiniSphere button. |
orb size (sharing) | 26px | Size of the orb inside the status pill while sharing. |
Sources: apps/web/src/components/live/MiniSphere.tsx:15-16, apps/web/src/components/live/MiniSphere.tsx:75, apps/web/src/components/live/InCall.tsx:98
Conclusion
The Floating Sphere UI is a specialized interaction layer designed for the Nudge desktop environment. By leveraging a custom Electron bridge and reactive sizing, it maintains a persistent yet subtle presence that can expand instantly when the AI detects learning friction, ensuring that guidance is always available without being disruptive. Sources: apps/web/src/components/live/MiniSphere.tsx:18, apps/web/src/lib/live/useLiveSession.ts:32-34