syntax = "proto3";
package bldr.desktop.tray;

option go_package = "github.com/s4wave/spacewave/bldr/desktop/tray;desktop_tray";

// DesktopTrayResourceService exposes a watchable desktop tray tree.
service DesktopTrayResourceService {
  // RegisterDesktopTrayEntry registers one resource-backed tray entry.
  rpc RegisterDesktopTrayEntry(RegisterDesktopTrayEntryRequest) returns (RegisterDesktopTrayEntryResponse);

  // WatchDesktopTray streams the full ordered tray tree.
  rpc WatchDesktopTray(WatchDesktopTrayRequest) returns (stream WatchDesktopTrayResponse);

  // InvokeDesktopTrayEntry invokes an action entry by id.
  rpc InvokeDesktopTrayEntry(InvokeDesktopTrayEntryRequest) returns (InvokeDesktopTrayEntryResponse);
}

// DesktopTrayEntryResourceService updates one registered tray entry.
service DesktopTrayEntryResourceService {
  // SetDesktopTrayEntry replaces the registered entry.
  rpc SetDesktopTrayEntry(SetDesktopTrayEntryRequest) returns (SetDesktopTrayEntryResponse);

  // SetDesktopTrayEntryActive updates the entry active flag.
  rpc SetDesktopTrayEntryActive(SetDesktopTrayEntryActiveRequest) returns (SetDesktopTrayEntryActiveResponse);

  // SetDesktopTrayEntryEnabled updates the entry enabled flag.
  rpc SetDesktopTrayEntryEnabled(SetDesktopTrayEntryEnabledRequest) returns (SetDesktopTrayEntryEnabledResponse);
}

// DesktopTrayActionHandlerService handles caller-owned tray actions.
service DesktopTrayActionHandlerService {
  // HandleDesktopTrayAction handles a native tray action invocation.
  rpc HandleDesktopTrayAction(HandleDesktopTrayActionRequest) returns (HandleDesktopTrayActionResponse);
}

// DesktopTrayState is the full tray tree snapshot.
message DesktopTrayState {
  // Entries contains the registered tray entries.
  repeated DesktopTrayEntry entries = 1;
  // IconState describes the collapsed platform icon status.
  DesktopTrayIconState icon_state = 2;
  // StatusText is short platform icon tooltip text.
  string status_text = 3;
}

// DesktopTrayEntry describes one platform-neutral tray row.
message DesktopTrayEntry {
  // Id identifies the entry within the tray tree.
  string id = 1;
  // Kind describes how the entry maps to a native menu item.
  DesktopTrayEntryKind kind = 2;
  // Path places the entry under nested submenu labels.
  repeated string path = 3;
  // Group orders related entries and creates section breaks between groups.
  string group = 4;
  // Order sorts entries within a path and group.
  int32 order = 5;
  // Label is primary display text.
  string label = 6;
  // Detail is secondary display text.
  string detail = 7;
  // StatusText is compact status text for the row.
  string status_text = 8;
  // IconName is a platform-neutral icon hint.
  string icon_name = 9;
  // IconState is a platform-neutral status hint.
  DesktopTrayIconState icon_state = 10;
  // Severity describes attention urgency for status and action rows.
  DesktopTraySeverity severity = 11;
  // Active is set when the row describes active foreground work.
  bool active = 12;
  // Enabled indicates whether an action row can run.
  bool enabled = 13;
  // Action describes what happens when an action row is selected.
  DesktopTrayAction action = 14;
}

// DesktopTrayAction describes a selectable tray action.
message DesktopTrayAction {
  // Kind describes the platform-neutral action category.
  DesktopTrayActionKind kind = 1;
  // Route is the app route used by route-opening actions.
  string route = 2;
  // Value is action-specific text such as copy text or a filesystem path.
  string value = 3;
}

// RegisterDesktopTrayEntryRequest is the request for RegisterDesktopTrayEntry.
message RegisterDesktopTrayEntryRequest {
  // Entry is the tray entry to register.
  DesktopTrayEntry entry = 1;
  // AttachedActionResourceId is an optional attached DesktopTrayActionHandlerService resource.
  uint32 attached_action_resource_id = 2;
}

// RegisterDesktopTrayEntryResponse is the response for RegisterDesktopTrayEntry.
message RegisterDesktopTrayEntryResponse {
  // ResourceId is the registered DesktopTrayEntryResourceService resource.
  uint32 resource_id = 1;
}

// WatchDesktopTrayRequest is the request for WatchDesktopTray.
message WatchDesktopTrayRequest {}

// WatchDesktopTrayResponse is the response for WatchDesktopTray.
message WatchDesktopTrayResponse {
  // State is the current tray tree snapshot.
  DesktopTrayState state = 1;
}

// InvokeDesktopTrayEntryRequest is the request for InvokeDesktopTrayEntry.
message InvokeDesktopTrayEntryRequest {
  // EntryId is the entry id to invoke.
  string entry_id = 1;
}

// InvokeDesktopTrayEntryResponse is the response for InvokeDesktopTrayEntry.
message InvokeDesktopTrayEntryResponse {}

// SetDesktopTrayEntryRequest is the request for SetDesktopTrayEntry.
message SetDesktopTrayEntryRequest {
  // Entry is the replacement entry state.
  DesktopTrayEntry entry = 1;
}

// SetDesktopTrayEntryResponse is the response for SetDesktopTrayEntry.
message SetDesktopTrayEntryResponse {}

// SetDesktopTrayEntryActiveRequest is the request for SetDesktopTrayEntryActive.
message SetDesktopTrayEntryActiveRequest {
  // Active is the replacement active flag.
  bool active = 1;
}

// SetDesktopTrayEntryActiveResponse is the response for SetDesktopTrayEntryActive.
message SetDesktopTrayEntryActiveResponse {}

// SetDesktopTrayEntryEnabledRequest is the request for SetDesktopTrayEntryEnabled.
message SetDesktopTrayEntryEnabledRequest {
  // Enabled is the replacement enabled flag.
  bool enabled = 1;
}

// SetDesktopTrayEntryEnabledResponse is the response for SetDesktopTrayEntryEnabled.
message SetDesktopTrayEntryEnabledResponse {}

// HandleDesktopTrayActionRequest is the request for HandleDesktopTrayAction.
message HandleDesktopTrayActionRequest {
  // EntryId identifies the invoked tray entry.
  string entry_id = 1;
  // Action is the action payload from the registered entry.
  DesktopTrayAction action = 2;
}

// HandleDesktopTrayActionResponse is the response for HandleDesktopTrayAction.
message HandleDesktopTrayActionResponse {}

// DesktopTrayEntryKind describes native menu mapping semantics.
enum DesktopTrayEntryKind {
  // DESKTOP_TRAY_ENTRY_KIND_UNSPECIFIED leaves row semantics unset.
  DESKTOP_TRAY_ENTRY_KIND_UNSPECIFIED = 0;
  // DESKTOP_TRAY_ENTRY_KIND_SECTION renders a disabled section heading.
  DESKTOP_TRAY_ENTRY_KIND_SECTION = 1;
  // DESKTOP_TRAY_ENTRY_KIND_SEPARATOR renders a native separator.
  DESKTOP_TRAY_ENTRY_KIND_SEPARATOR = 2;
  // DESKTOP_TRAY_ENTRY_KIND_STATUS renders a disabled status row.
  DESKTOP_TRAY_ENTRY_KIND_STATUS = 3;
  // DESKTOP_TRAY_ENTRY_KIND_ACTION renders an invokable action row.
  DESKTOP_TRAY_ENTRY_KIND_ACTION = 4;
  // DESKTOP_TRAY_ENTRY_KIND_SUBMENU renders a submenu container.
  DESKTOP_TRAY_ENTRY_KIND_SUBMENU = 5;
}

// DesktopTrayActionKind describes selectable action semantics.
enum DesktopTrayActionKind {
  // DESKTOP_TRAY_ACTION_KIND_UNSPECIFIED leaves action semantics unset.
  DESKTOP_TRAY_ACTION_KIND_UNSPECIFIED = 0;
  // DESKTOP_TRAY_ACTION_KIND_OPEN_ROUTE opens or focuses an app route.
  DESKTOP_TRAY_ACTION_KIND_OPEN_ROUTE = 1;
  // DESKTOP_TRAY_ACTION_KIND_NEW_WINDOW opens an app route in a new window.
  DESKTOP_TRAY_ACTION_KIND_NEW_WINDOW = 2;
  // DESKTOP_TRAY_ACTION_KIND_COPY_TEXT copies text to the native clipboard.
  DESKTOP_TRAY_ACTION_KIND_COPY_TEXT = 3;
  // DESKTOP_TRAY_ACTION_KIND_REVEAL_PATH reveals a local filesystem path.
  DESKTOP_TRAY_ACTION_KIND_REVEAL_PATH = 4;
  // DESKTOP_TRAY_ACTION_KIND_QUIT requests explicit runtime quit.
  DESKTOP_TRAY_ACTION_KIND_QUIT = 5;
  // DESKTOP_TRAY_ACTION_KIND_ATTACHED_HANDLER invokes the attached action resource.
  DESKTOP_TRAY_ACTION_KIND_ATTACHED_HANDLER = 6;
}

// DesktopTrayIconState describes collapsed tray icon status.
enum DesktopTrayIconState {
  // DESKTOP_TRAY_ICON_STATE_UNSPECIFIED leaves icon status unset.
  DESKTOP_TRAY_ICON_STATE_UNSPECIFIED = 0;
  // DESKTOP_TRAY_ICON_STATE_NORMAL indicates steady healthy state.
  DESKTOP_TRAY_ICON_STATE_NORMAL = 1;
  // DESKTOP_TRAY_ICON_STATE_ACTIVE indicates useful background activity.
  DESKTOP_TRAY_ICON_STATE_ACTIVE = 2;
  // DESKTOP_TRAY_ICON_STATE_ATTENTION indicates user action is needed.
  DESKTOP_TRAY_ICON_STATE_ATTENTION = 3;
  // DESKTOP_TRAY_ICON_STATE_DISCONNECTED indicates runtime disconnection.
  DESKTOP_TRAY_ICON_STATE_DISCONNECTED = 4;
  // DESKTOP_TRAY_ICON_STATE_QUITTING indicates explicit shutdown is running.
  DESKTOP_TRAY_ICON_STATE_QUITTING = 5;
}

// DesktopTraySeverity describes row urgency.
enum DesktopTraySeverity {
  // DESKTOP_TRAY_SEVERITY_UNSPECIFIED leaves severity unset.
  DESKTOP_TRAY_SEVERITY_UNSPECIFIED = 0;
  // DESKTOP_TRAY_SEVERITY_INFO marks informational status.
  DESKTOP_TRAY_SEVERITY_INFO = 1;
  // DESKTOP_TRAY_SEVERITY_WARNING marks a recoverable warning.
  DESKTOP_TRAY_SEVERITY_WARNING = 2;
  // DESKTOP_TRAY_SEVERITY_CRITICAL marks a blocking issue.
  DESKTOP_TRAY_SEVERITY_CRITICAL = 3;
}