---
title: "Get Browser Assets"
description: "This process describes how the frontend application's BrowserAutomations component, through its interaction with the useBrowserContext hook, ultimately leads to a visual update of the Electron devi..."
last_updated: "2026-05-06T07:30:58.159818+00:00"
canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/how-it-works/get-browser-assets"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/BrowserAutomations.tsx](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/components/BrowserAutomations.tsx)
- [apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/useBrowserContext.ts](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/hooks/useBrowserContext.ts)
- [packages/device-agent/src/main/index.ts](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/index.ts)
- [packages/device-agent/src/main/tray.ts](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts)
</details>

This process describes how the frontend application's `BrowserAutomations` component, through its interaction with the `useBrowserContext` hook, ultimately leads to a visual update of the Electron `device-agent`'s system tray icon. This flow is crucial for providing real-time feedback on the device agent's operational status, such as its authentication state or whether it's actively performing checks.

The high-level goal is to reflect the current state of the browser context (managed by the frontend) in the system tray icon of the background `device-agent`. This involves a cross-process communication where an action in the web application triggers an internal status update within the Electron main process, which then cascades to the UI elements of the system tray, culminating in the loading of the correct icon image from the application's assets.

<Steps>
<Step>
### Frontend Component Initialization
The process begins in the `BrowserAutomations` React component, which is responsible for rendering the user interface related to browser automations. This component utilizes various hooks to manage its state and interactions. One of the key hooks it employs is `useBrowserContext`.
Sources: [BrowserAutomations.tsx:19-115](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/components/BrowserAutomations.tsx#L19-L115)
</Step>

<Step>
### Browser Context Management
The `useBrowserContext` hook is initialized within the `BrowserAutomations` component. This hook is responsible for managing the state and actions related to the browser context, such as checking its status, initiating authentication flows, and handling sessions. While the `useBrowserContext` hook primarily manages frontend state and interacts with a backend API, its actions (e.g., `checkContextStatus`, `startAuth`) can indirectly influence the operational status of the `device-agent`. For instance, if the frontend successfully establishes a browser context or completes an authentication flow, this state change might be observed by the `device-agent` (e.g., via a shared backend service or a polling mechanism), prompting it to update its own internal status.
Sources: [useBrowserContext.ts:16-126](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/hooks/useBrowserContext.ts#L16-L126)
</Step>

<Step>
### Device Agent Status Update
Following an indirect trigger from the frontend's browser context management, the `device-agent`'s main process calls its internal `setStatus` function. This function is central to managing the `device-agent`'s operational state as reflected in the system tray. It takes a `TrayStatus` enum (e.g., `'unauthenticated'`, `'checking'`, `'compliant'`, `'non-compliant'`) as an argument. The primary action of `setStatus` is to update the `currentStatus` variable within the `device-agent` and then immediately invoke `updateTrayMenu` to refresh the system tray's appearance.
Sources: [index.ts:166-169](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/index.ts#L166-L169)
</Step>

<Step>
### Tray Menu Refresh
The `updateTrayMenu` function in `tray.ts` is called by `setStatus` to refresh the Electron system tray icon and its associated context menu. This function receives the current `TrayStatus` along with check results and callback functions for menu actions. Its first critical task is to determine the appropriate icon for the given status by calling `getIconForStatus`. After obtaining the icon, it updates the tray's image using `tray.setImage()` and rebuilds the context menu, ensuring the visual representation and available actions are consistent with the `device-agent`'s current state.
Sources: [tray.ts:110-189](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L110-L189)
</Step>

<Step>
### Icon Selection Based on Status
The `getIconForStatus` function is responsible for mapping the `TrayStatus` to a specific icon file. It uses a `switch` statement to select the correct PNG filename based on the provided status. For example, a `'compliant'` status will result in `16x16-pass.png`, while `'unauthenticated'` or `'checking'` will use `16x16-default.png`. This function then delegates the actual loading and processing of the image to `loadTrayIcon`.
Sources: [tray.ts:77-84](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L77-L84)
</Step>

<Step>
### Tray Icon Loading and Processing
The `loadTrayIcon` function takes the selected icon filename (e.g., `16x16-pass.png`) and performs several steps to prepare it for display in the system tray. First, it determines the base path for assets by calling `getAssetsPath`. It then constructs the full path to the icon file. The image is loaded using `nativeImage.createFromPath`, resized to a standard `16x16` pixel size, and then centered on a `20x20` transparent canvas. This padding ensures the icon has sufficient "breathing room" and appears consistently across different operating systems. Robust error handling is included to return an empty image if the specified file cannot be found or loaded.
Sources: [tray.ts:41-75](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L41-L75)
</Step>

<Step>
### Determining Asset Path
The final step in this trace is `getAssetsPath`, which is called by `loadTrayIcon`. This utility function resolves the absolute path to the `assets` directory. It intelligently adapts its behavior based on whether the Electron application is running in a packaged (production) environment or a development environment. If `app.isPackaged` is true, it constructs the path relative to `process.resourcesPath`. Otherwise, it uses a relative path from the current module's directory (`__dirname`). This ensures that icon files are correctly located regardless of the application's deployment context.
Sources: [tray.ts:33-38](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L33-L38)
</Step>
</Steps>

```mermaid
sequenceDiagram
    participant BrowserAutomations as apps/app/.../BrowserAutomations.tsx
    participant useBrowserContext as apps/app/.../useBrowserContext.ts
    participant DeviceAgentMain as packages/device-agent/src/main/index.ts
    participant TrayModule as packages/device-agent/src/main/tray.ts

    BrowserAutomations->>useBrowserContext: Initializes hook
    useBrowserContext-->>BrowserAutomations: Provides context state and actions
    Note over useBrowserContext, DeviceAgentMain: Frontend action (e.g., auth success) indirectly triggers device agent status update
    DeviceAgentMain->>DeviceAgentMain: setStatus(newStatus)
    DeviceAgentMain->>TrayModule: updateTrayMenu(newStatus, ...)
    TrayModule->>TrayModule: getIconForStatus(newStatus)
    TrayModule->>TrayModule: loadTrayIcon(iconFilename)
    TrayModule->>TrayModule: getAssetsPath()
    TrayModule-->>TrayModule: Returns assets path
    TrayModule-->>TrayModule: Returns loaded NativeImage
    TrayModule-->>TrayModule: Returns NativeImage
    TrayModule->>DeviceAgentMain: Updates tray icon and menu
    DeviceAgentMain-->>DeviceAgentMain: Status updated
```



### Key Observations

*   **Cross-Module Boundaries:** This flow prominently crosses significant architectural boundaries. It starts in a React frontend component (`apps/app`), conceptually triggers an action that leads to the Electron main process (`packages/device-agent/src/main/index.ts`), and then dives into a utility module specifically for tray management (`packages/device-agent/src/main/tray.ts`). The direct link between `useBrowserContext` and `setStatus` in the trace implies an indirect communication mechanism (e.g., API calls to a shared backend, which the device agent monitors, or an explicit IPC call not detailed in the provided code snippets).
*   **Decoupled Status Management:** The frontend manages `BrowserContextStatus` (e.g., 'has-context', 'no-context'), while the device agent manages `TrayStatus` (e.g., 'compliant', 'unauthenticated'). Although distinct, there's an implied mapping or correlation between these states, where frontend actions influence the device agent's perceived status.
*   **Visual Feedback Loop:** The core purpose of this flow is to provide immediate visual feedback to the user via the system tray icon. Any change in the device agent's operational state, often initiated by user interaction in the web app, is quickly reflected in the tray.
*   **Environment Adaptation:** The `getAssetsPath` function demonstrates good practice by adapting to the application's environment (packaged vs. development), ensuring that assets are always correctly located.
*   **Performance Considerations:** Icon loading and processing (`loadTrayIcon`) involves file I/O and image manipulation. While typically fast for small icons, repeated calls or complex image processing could introduce minor delays. The padding logic ensures consistent icon appearance, which is a UX consideration.
*   **Potential Failure Points:**
    *   **IPC/Communication Failure:** If the indirect communication channel between the frontend's `useBrowserContext` and the `device-agent` fails, the tray icon might not update, leading to a stale status display.
    *   **File Not Found:** If `loadTrayIcon` cannot find the specified icon file (e.g., `16x16-pass.png`), it gracefully falls back to an empty image, preventing a crash but resulting in a missing icon.
    *   **Image Processing Errors:** Errors during `nativeImage` creation or resizing are caught, but could lead to an empty or malformed icon.
    *   **Tray Creation Failure:** If `createTray` fails, the application might run without a system tray icon, severely impacting user interaction.

Sources:
- [BrowserAutomations.tsx:19-115](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/components/BrowserAutomations.tsx#L19-L115)
- [useBrowserContext.ts:16-126](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/tasks/%5BtaskId%5D/hooks/useBrowserContext.ts#L16-L126)
- [index.ts:166-169](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/index.ts#L166-L169)
- [tray.ts:110-189](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L110-L189)
- [tray.ts:77-84](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L77-L84)
- [tray.ts:41-75](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L41-L75)
- [tray.ts:33-38](https://github.com/blade47/comp/blob/main/packages/device-agent/src/main/tray.ts#L33-L38)

## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.