Skip to content

Shell Surfaces Capability (Flow)

This document describes the end-to-end technical flow for SmrtHub’s Windows shell surfaces:

  • HubWindow system tray integration (left-click restore, right-click command menu)
  • Taskbar Jump List tasks (right-click taskbar icon → Tasks)
  • Single-instance routing so shell actions always target the primary HubWindow

This is intentionally a cross-component flow doc. HubWindow implementation details remain in the HubWindow component README.

Purpose and scope

  • Provide a stable contract for how tray/taskbar actions route into SmrtHub.
  • Document the shutdown and diagnostics command pathways (Supervisor, Support Bundle, logging export).
  • Describe the required single-instance and IPC behaviors.

Entry points

  • User left-clicks tray icon (restore window).
  • User uses tray context menu commands (Diagnostics, Legal & Compliance, Exit).
  • User invokes Jump List Tasks from the taskbar.
  • User launches the app again via shortcuts or Jump List (secondary instance routes the command to the primary).

Participating Components/Subsystems

  • HubWindow (shell UI + tray + Jump List): SmrtApps/CSApps/HubWindow/README.md
  • Supervisor (orchestration + shutdown execution): SmrtApps/CSApps/SmrtHubSupervisor/README.md
  • Supervision Subsystem (contracts): README.Files/Subsystems/Supervision/README.md
  • Logging Subsystem (observability): README.Files/Subsystems/Logging/README.md
  • Logging Reference Guide (HTML export behavior and schema): README.Files/Reference-Guides/SmrtHub.Logging.README.md
  • Support Bundle (diagnostics packaging): SmrtApps/src/Smrt.SupportBundle/README.md

Configuration, operational data, and paths

  • Not documented yet: any shell-surface-specific configuration inputs.
  • When configuration exists, it must live under canonical Operational Data Policy locations and be resolved via Smrt.Config (do not invent ad-hoc paths).

Sequence / flow

A) Restore (tray click)

  1. User left-clicks the tray icon.
  2. HubWindow restores the primary window.
  3. HubWindow logs the interaction (action, timing) via the unified logger.

B) Jump List action (taskbar Tasks)

  1. User selects a task from the taskbar Jump List.
  2. Windows Shell launches HubWindow with an action argument (e.g., --action exit-smrthub).
  3. Single-instance guard detects a primary instance:
  4. Secondary instance sends the action to the primary via IPC.
  5. Secondary instance exits promptly.
  6. Primary HubWindow executes the action and logs:
  7. IPC receive
  8. action dispatch
  9. downstream results (success/failure)

C) Exit SmrtHub (tray or Jump List)

  1. User triggers Exit in tray or Jump List.
  2. HubWindow publishes a non-UI notification (best-effort) so UI surfaces can inform the user.
  3. HubWindow requests Supervisor shutdown via the approved control channel.
  4. HubWindow exits promptly (perceived responsiveness).
  5. Supervisor continues headless:
  6. suppresses restarts
  7. drains/shuts down components in dependency order
  8. enforces timeouts and teardown containment

D) Diagnostics actions (tray)

  1. User selects a diagnostics action (for example HTML logs export or Support Bundle).
  2. HubWindow runs the action headless and logs progress.
  3. Logging export produces HTML output as a convenience view; raw logs remain authoritative.
  4. Support Bundle exports collect logs and related evidence within configured caps/redaction rules.

Contracts and expected behaviors

  • Only one primary HubWindow instance exists at a time.
  • Shell actions must never spawn duplicate visible windows.
  • Shutdown is coordinated through Supervisor (not by killing arbitrary processes).
  • Actions must emit structured logs for traceability.

Failure modes and expected behaviors

  • Supervisor unreachable: HubWindow logs a clear warning and exits after a bounded grace period.
  • IPC failure: secondary instance falls back to a legacy restore/event mechanism where applicable, then exits.
  • Jump List mis-association: verify AppUserModelID is set early; log the AppID + command line on startup.
  • DPI/theme glitches: tray/menu creation must run under the correct DPI awareness scopes; theme changes are debounced.

Testing & validation expectations

  • Validate single-instance routing (secondary invocation routes action and exits).
  • Validate Jump List tasks dispatch to the same action handlers as tray menu.
  • Validate shutdown command routes through Supervisor and completes cleanly.
  • Validate diagnostic actions (HTML export, Support Bundle) emit expected artifacts and log outcomes.