gui/pkg/display/docs/backend.md

# Backend Documentation

The backend is written in Go and uses the `forge.lthn.ai/core/gui/pkg/display` package. It uses Wails v3 to bridge Go and the web frontend.

## Core Types

### `Service`
The `Service` struct is the main entry point for the display logic.

- **Initialization:**
  - `NewService() (*Service, error)`: Creates a new instance of the service.
  - `Register(wailsApp *application.App) func(*core.Core) (any, error)`: Captures the Wails app and registers the service with Core.
  - `OnStartup(ctx context.Context) error`: Loads config and registers IPC handlers.

- **Window Management:**
  - `OpenWindow(spec window.Window) error`: Opens the default window using manager defaults.
  - `CreateWindow(spec window.Window) (*window.WindowInfo, error)`: Opens a named window and returns its info.
  - `GetWindowInfo(name string) (*window.WindowInfo, error)`: Queries a single window.
  - `ListWindowInfos() []window.WindowInfo`: Queries all tracked windows.
  - `SetWindowBounds(name string, x, y, width, height int) error` - preferred when position and size change together.
  - `SetWindowPosition(name string, x, y int) error`
  - `SetWindowSize(name string, width, height int) error`
  - `MaximizeWindow(name string) error`
  - `MinimizeWindow(name string) error`
  - `RestoreWindow(name string) error`
  - `FocusWindow(name string) error`
  - `SetWindowFullscreen(name string, fullscreen bool) error`
  - `SetWindowAlwaysOnTop(name string, alwaysOnTop bool) error`
  - `SetWindowVisibility(name string, visible bool) error`
  - `SetWindowTitle(name, title string) error`
  - `SetWindowBackgroundColour(name string, r, g, b, a uint8) error`
  - `GetFocusedWindow() string`
  - `ResetWindowState() error`
  - `GetSavedWindowStates() map[string]window.WindowState`

Example:

```go
svc.CreateWindow(window.Window{
    Name:  "editor",
    Title: "Editor",
    URL:   "/#/editor",
    Width: 1200,
    Height: 800,
})

svc.SetWindowBounds("editor", 100, 200, 1280, 720)
```

## Subsystems

### Menu (`menu.go`)
The `buildMenu()` method constructs the application's main menu, adding standard roles like File, Edit, Window, and Help. It also dispatches the app-specific developer actions used by the frontend.

### System Tray (`tray.go`)
The `setupTray()` method initializes the system tray icon and its context menu. It supports:
- Showing/Hiding all windows.
- Displaying environment info.
- Quitting the application.
- Attaching tray actions that are broadcast as IPC events.

### Actions (`messages.go`)
Defines structured messages for Inter-Process Communication (IPC) and internal event handling, including `window.ActionWindowOpened`, `window.ActionWindowClosed`, and `display.ActionIDECommand`.