feat(FN-1116): add Capacitor plugin managers for dashboard

- Add shared plugin types and manager modules for splash screen, status bar, and network handling
- Export plugin initialization from the dashboard entrypoint and configure Capacitor splash/status-bar defaults
- Add unit tests covering plugin initialization and each manager's behavior across supported scenarios
- Document the plugin manager architecture and add required Capacitor plugin dependencies

packages/dashboard/src/plugins/index.ts

@@ -0,0 +1,99 @@
+import { SplashScreenManager } from "./splash-screen.js";
+import { StatusBarManager } from "./status-bar.js";
+import { NetworkManager } from "./network.js";
+import type { PluginInitOptions, PluginInitResult } from "./types.js";
+
+// Types
+export type {
+  NetworkStatus,
+  ThemeMode,
+  StatusBarStyle,
+  PluginInitOptions,
+  NetworkStatusCallback,
+  ThemeChangeCallback,
+  PluginManager,
+  PluginInitResult,
+} from "./types.js";
+
+// Plugin managers
+export { SplashScreenManager } from "./splash-screen.js";
+export type { SplashScreenOptions } from "./splash-screen.js";
+
+export { StatusBarManager } from "./status-bar.js";
+export type { StatusBarOptions } from "./status-bar.js";
+
+export { NetworkManager } from "./network.js";
+
+/**
+ * Initialize all mobile plugin managers.
+ *
+ * Creates manager instances, initializes them in order (splash → status bar → network),
+ * and returns them along with the initialization results.
+ *
+ * Errors in individual managers are caught and reported in the result
+ * without preventing other managers from initializing.
+ */
+export async function initializePlugins(
+  options: PluginInitOptions = {},
+): Promise<{
+  splashScreen: SplashScreenManager;
+  statusBar: StatusBarManager;
+  network: NetworkManager;
+  result: PluginInitResult;
+}> {
+  const splashScreen = new SplashScreenManager({
+    autoHide: options.splashAutoHide,
+    hideDelay: options.splashHideDelay,
+  });
+
+  const statusBar = new StatusBarManager({
+    themeMode: options.themeMode,
+  });
+
+  const network = new NetworkManager();
+
+  const result: PluginInitResult = {
+    splashScreen: false,
+    statusBar: false,
+    network: false,
+    errors: [],
+  };
+
+  // Initialize splash screen first (so it hides after UI loads)
+  try {
+    await splashScreen.initialize();
+    result.splashScreen = true;
+  } catch (error) {
+    result.errors.push({
+      plugin: "splashScreen",
+      error: error instanceof Error ? error : new Error(String(error)),
+    });
+  }
+
+  // Initialize status bar
+  try {
+    await statusBar.initialize();
+    result.statusBar = true;
+  } catch (error) {
+    result.errors.push({
+      plugin: "statusBar",
+      error: error instanceof Error ? error : new Error(String(error)),
+    });
+  }
+
+  // Initialize network monitoring
+  try {
+    await network.initialize();
+    if (options.startNetworkMonitoring === false) {
+      await network.stopMonitoring();
+    }
+    result.network = true;
+  } catch (error) {
+    result.errors.push({
+      plugin: "network",
+      error: error instanceof Error ? error : new Error(String(error)),
+    });
+  }
+
+  return { splashScreen, statusBar, network, result };
+}

packages/dashboard/src/plugins/network.ts

@@ -0,0 +1,127 @@
+import { Network, type ConnectionType } from "@capacitor/network";
+import type {
+  PluginManager,
+  NetworkStatus,
+  NetworkStatusCallback,
+  PluginNetworkListenerHandle,
+} from "./types.js";
+
+export class NetworkManager implements PluginManager {
+  private status: NetworkStatus;
+  private listeners: Array<NetworkStatusCallback> = [];
+  private networkListenerHandle: PluginNetworkListenerHandle | null = null;
+  private initialized = false;
+  private monitoring = false;
+
+  constructor() {
+    this.status = { connected: true, connectionType: "unknown" };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      const currentStatus = await Network.getStatus();
+      this.status = this.toNetworkStatus(currentStatus.connected, currentStatus.connectionType);
+    } catch {
+      // Network plugin may not be available in browser context
+      this.status = { connected: true, connectionType: "unknown" };
+    }
+
+    await this.startMonitoring();
+    this.initialized = true;
+  }
+
+  async startMonitoring(): Promise<void> {
+    if (this.monitoring) {
+      return;
+    }
+
+    try {
+      this.networkListenerHandle = await Network.addListener(
+        "networkStatusChange",
+        (status) => {
+          const nextStatus = this.toNetworkStatus(status.connected, status.connectionType);
+          const previousConnected = this.status.connected;
+          this.status = nextStatus;
+
+          // Emit specific events for going online/offline
+          if (!previousConnected && nextStatus.connected) {
+            this.emit("network:online", nextStatus);
+          } else if (previousConnected && !nextStatus.connected) {
+            this.emit("network:offline", nextStatus);
+          }
+
+          // Always emit general status change
+          this.emit("network:change", nextStatus);
+        },
+      );
+      this.monitoring = true;
+    } catch {
+      // Network plugin may not be available in browser context
+      this.networkListenerHandle = null;
+      this.monitoring = false;
+    }
+  }
+
+  async stopMonitoring(): Promise<void> {
+    if (this.networkListenerHandle) {
+      try {
+        await this.networkListenerHandle.remove();
+      } catch {
+        // Ignore listener cleanup errors
+      }
+      this.networkListenerHandle = null;
+    }
+
+    this.monitoring = false;
+  }
+
+  getStatus(): NetworkStatus {
+    return { ...this.status };
+  }
+
+  get isOnline(): boolean {
+    return this.status.connected;
+  }
+
+  get isMonitoring(): boolean {
+    return this.monitoring;
+  }
+
+  onStatusChange(callback: NetworkStatusCallback): () => void {
+    this.listeners.push(callback);
+    return () => {
+      this.listeners = this.listeners.filter((cb) => cb !== callback);
+    };
+  }
+
+  private emit(_event: string, status: NetworkStatus): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(status);
+      } catch {
+        // Prevent one listener error from breaking others
+      }
+    }
+  }
+
+  private toNetworkStatus(connected: boolean, connectionType: ConnectionType): NetworkStatus {
+    return {
+      connected,
+      connectionType: connectionType as NetworkStatus["connectionType"],
+    };
+  }
+
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async destroy(): Promise<void> {
+    await this.stopMonitoring();
+    this.listeners = [];
+    this.initialized = false;
+  }
+}

packages/dashboard/src/plugins/splash-screen.ts

@@ -0,0 +1,59 @@
+import { SplashScreen } from "@capacitor/splash-screen";
+import type { PluginManager } from "./types.js";
+
+export interface SplashScreenOptions {
+  autoHide?: boolean;
+  hideDelay?: number;
+}
+
+export class SplashScreenManager implements PluginManager {
+  private options: Required<SplashScreenOptions>;
+  private initialized = false;
+
+  constructor(options: SplashScreenOptions = {}) {
+    this.options = {
+      autoHide: options.autoHide ?? true,
+      hideDelay: options.hideDelay ?? 500,
+    };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    if (this.options.autoHide) {
+      setTimeout(() => {
+        this.hide().catch(() => {
+          // Splash screen may already be hidden or not available (e.g., in browser)
+        });
+      }, this.options.hideDelay);
+    }
+
+    this.initialized = true;
+  }
+
+  async hide(): Promise<void> {
+    try {
+      await SplashScreen.hide({ fadeOutDuration: 300 });
+    } catch {
+      // Ignore errors — splash screen may not be available in browser/web context
+    }
+  }
+
+  async show(): Promise<void> {
+    try {
+      await SplashScreen.show({ autoHide: false });
+    } catch {
+      // Ignore errors — splash screen may not be available in browser/web context
+    }
+  }
+
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async destroy(): Promise<void> {
+    this.initialized = false;
+  }
+}

packages/dashboard/src/plugins/status-bar.ts

@@ -0,0 +1,80 @@
+import { StatusBar, Style } from "@capacitor/status-bar";
+import type {
+  PluginManager,
+  ThemeMode,
+  ThemeChangeCallback,
+} from "./types.js";
+
+export interface StatusBarOptions {
+  themeMode?: ThemeMode;
+}
+
+export class StatusBarManager implements PluginManager {
+  private currentTheme: ThemeMode;
+  private listeners: Array<ThemeChangeCallback> = [];
+  private initialized = false;
+
+  constructor(options: StatusBarOptions = {}) {
+    this.currentTheme = options.themeMode ?? "system";
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      await this.applyTheme(this.currentTheme);
+    } catch {
+      // StatusBar plugin may not be available in browser context
+    }
+
+    this.initialized = true;
+  }
+
+  async setTheme(mode: ThemeMode): Promise<void> {
+    this.currentTheme = mode;
+    await this.applyTheme(mode);
+    this.listeners.forEach((callback) => callback(mode));
+  }
+
+  getTheme(): ThemeMode {
+    return this.currentTheme;
+  }
+
+  onThemeChange(callback: ThemeChangeCallback): () => void {
+    this.listeners.push(callback);
+    return () => {
+      this.listeners = this.listeners.filter((cb) => cb !== callback);
+    };
+  }
+
+  private async applyTheme(mode: ThemeMode): Promise<void> {
+    const isDark = mode === "dark" || (mode === "system" && this.isSystemDark());
+
+    try {
+      await StatusBar.setStyle({
+        style: isDark ? Style.Dark : Style.Light,
+      });
+    } catch {
+      // StatusBar plugin may not be available in browser context
+    }
+  }
+
+  private isSystemDark(): boolean {
+    if (typeof window === "undefined") {
+      return false;
+    }
+
+    return window.matchMedia("(prefers-color-scheme: dark)").matches;
+  }
+
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async destroy(): Promise<void> {
+    this.listeners = [];
+    this.initialized = false;
+  }
+}

packages/dashboard/src/plugins/types.ts

@@ -0,0 +1,50 @@
+import type { PluginListenerHandle } from "@capacitor/core";
+
+/** Network connectivity status */
+export interface NetworkStatus {
+  connected: boolean;
+  connectionType: "wifi" | "cellular" | "none" | "unknown";
+}
+
+/** Theme mode for status bar styling */
+export type ThemeMode = "light" | "dark" | "system";
+
+/** Status bar style mapping */
+export type StatusBarStyle = "light" | "dark";
+
+/** Plugin initialization options */
+export interface PluginInitOptions {
+  /** Auto-hide splash screen after initialization (default: true) */
+  splashAutoHide?: boolean;
+  /** Splash screen hide delay in milliseconds (default: 500) */
+  splashHideDelay?: number;
+  /** Initial theme mode for status bar (default: "system") */
+  themeMode?: ThemeMode;
+  /** Whether to start network monitoring immediately (default: true) */
+  startNetworkMonitoring?: boolean;
+}
+
+/** Callback for network status changes */
+export type NetworkStatusCallback = (status: NetworkStatus) => void;
+
+/** Callback for theme mode changes */
+export type ThemeChangeCallback = (mode: ThemeMode) => void;
+
+/** Generic plugin manager interface */
+export interface PluginManager {
+  /** Initialize the plugin manager */
+  initialize(): Promise<void>;
+  /** Clean up listeners and resources */
+  destroy(): Promise<void>;
+}
+
+/** Shared network listener handle type for manager implementations. */
+export type PluginNetworkListenerHandle = PluginListenerHandle;
+
+/** Result of initializing all plugins */
+export interface PluginInitResult {
+  splashScreen: boolean;
+  statusBar: boolean;
+  network: boolean;
+  errors: Array<{ plugin: string; error: Error }>;
+}