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/__tests__/initialize.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { initializePlugins } from "../plugins/index.js";
+
+const splashCtorMock = vi.fn();
+const splashInitializeMock = vi.fn();
+const splashDestroyMock = vi.fn();
+
+const statusCtorMock = vi.fn();
+const statusInitializeMock = vi.fn();
+const statusDestroyMock = vi.fn();
+
+const networkCtorMock = vi.fn();
+const networkInitializeMock = vi.fn();
+const networkStopMonitoringMock = vi.fn();
+const networkDestroyMock = vi.fn();
+
+vi.mock("../plugins/splash-screen.js", () => ({
+  SplashScreenManager: vi.fn().mockImplementation(function (options) {
+    splashCtorMock(options);
+    this.initialize = splashInitializeMock;
+    this.destroy = splashDestroyMock;
+  }),
+}));
+
+vi.mock("../plugins/status-bar.js", () => ({
+  StatusBarManager: vi.fn().mockImplementation(function (options) {
+    statusCtorMock(options);
+    this.initialize = statusInitializeMock;
+    this.destroy = statusDestroyMock;
+  }),
+}));
+
+vi.mock("../plugins/network.js", () => ({
+  NetworkManager: vi.fn().mockImplementation(function () {
+    networkCtorMock();
+    this.initialize = networkInitializeMock;
+    this.stopMonitoring = networkStopMonitoringMock;
+    this.destroy = networkDestroyMock;
+  }),
+}));
+
+describe("initializePlugins", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    splashInitializeMock.mockResolvedValue(undefined);
+    splashDestroyMock.mockResolvedValue(undefined);
+
+    statusInitializeMock.mockResolvedValue(undefined);
+    statusDestroyMock.mockResolvedValue(undefined);
+
+    networkInitializeMock.mockResolvedValue(undefined);
+    networkStopMonitoringMock.mockResolvedValue(undefined);
+    networkDestroyMock.mockResolvedValue(undefined);
+  });
+
+  it("initializePlugins() returns all managers", async () => {
+    const { splashScreen, statusBar, network } = await initializePlugins();
+
+    expect(splashScreen).toBeDefined();
+    expect(statusBar).toBeDefined();
+    expect(network).toBeDefined();
+  });
+
+  it("initializePlugins() reports success for all plugins", async () => {
+    const { result } = await initializePlugins();
+
+    expect(result.splashScreen).toBe(true);
+    expect(result.statusBar).toBe(true);
+    expect(result.network).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("initializePlugins() passes options to managers", async () => {
+    await initializePlugins({
+      splashAutoHide: false,
+      splashHideDelay: 1500,
+      themeMode: "dark",
+      startNetworkMonitoring: false,
+    });
+
+    expect(splashCtorMock).toHaveBeenCalledWith({ autoHide: false, hideDelay: 1500 });
+    expect(statusCtorMock).toHaveBeenCalledWith({ themeMode: "dark" });
+    expect(networkCtorMock).toHaveBeenCalledTimes(1);
+    expect(networkStopMonitoringMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("initializePlugins() continues if one manager fails", async () => {
+    statusInitializeMock.mockRejectedValue(new Error("status failed"));
+
+    const { result } = await initializePlugins();
+
+    expect(result.splashScreen).toBe(true);
+    expect(result.statusBar).toBe(false);
+    expect(result.network).toBe(true);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]?.plugin).toBe("statusBar");
+    expect(result.errors[0]?.error.message).toBe("status failed");
+  });
+
+  it("initializePlugins() collects errors without throwing", async () => {
+    splashInitializeMock.mockRejectedValue(new Error("splash failed"));
+    networkInitializeMock.mockRejectedValue("network failed");
+
+    const execution = initializePlugins();
+
+    await expect(execution).resolves.toBeDefined();
+
+    const { result } = await execution;
+    expect(result.splashScreen).toBe(false);
+    expect(result.statusBar).toBe(true);
+    expect(result.network).toBe(false);
+    expect(result.errors).toHaveLength(2);
+    expect(result.errors[0]?.plugin).toBe("splashScreen");
+    expect(result.errors[1]?.plugin).toBe("network");
+    expect(result.errors[1]?.error).toBeInstanceOf(Error);
+  });
+});

packages/dashboard/src/__tests__/network.test.ts

@@ -0,0 +1,163 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Network } from "@capacitor/network";
+import { NetworkManager } from "../plugins/network.js";
+
+const { getStatusMock, addListenerMock, removeListenerMock } = vi.hoisted(() => ({
+  getStatusMock: vi.fn(),
+  addListenerMock: vi.fn(),
+  removeListenerMock: vi.fn(),
+}));
+
+let networkStatusChangeHandler:
+  | ((status: { connected: boolean; connectionType: "wifi" | "cellular" | "none" | "unknown" }) => void)
+  | null = null;
+
+vi.mock("@capacitor/network", () => ({
+  Network: {
+    getStatus: getStatusMock,
+    addListener: addListenerMock,
+  },
+}));
+
+describe("NetworkManager", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    networkStatusChangeHandler = null;
+
+    getStatusMock.mockResolvedValue({
+      connected: true,
+      connectionType: "wifi",
+    });
+
+    removeListenerMock.mockResolvedValue(undefined);
+
+    addListenerMock.mockImplementation(async (
+      eventName: string,
+      callback: (status: { connected: boolean; connectionType: "wifi" | "cellular" | "none" | "unknown" }) => void,
+    ) => {
+      if (eventName === "networkStatusChange") {
+        networkStatusChangeHandler = callback;
+      }
+      return { remove: removeListenerMock };
+    });
+  });
+
+  it("initialize() queries current network status", async () => {
+    const manager = new NetworkManager();
+
+    await manager.initialize();
+
+    expect(Network.getStatus).toHaveBeenCalledTimes(1);
+    expect(manager.getStatus()).toEqual({ connected: true, connectionType: "wifi" });
+  });
+
+  it("startMonitoring() registers network listener", async () => {
+    const manager = new NetworkManager();
+
+    await manager.startMonitoring();
+
+    expect(Network.addListener).toHaveBeenCalledTimes(1);
+    expect(Network.addListener).toHaveBeenCalledWith("networkStatusChange", expect.any(Function));
+    expect(manager.isMonitoring).toBe(true);
+  });
+
+  it("status change callback fires on network change", async () => {
+    const manager = new NetworkManager();
+    const callback = vi.fn();
+
+    manager.onStatusChange(callback);
+    await manager.initialize();
+
+    networkStatusChangeHandler?.({ connected: false, connectionType: "none" });
+
+    expect(callback).toHaveBeenCalled();
+    expect(callback).toHaveBeenLastCalledWith({ connected: false, connectionType: "none" });
+  });
+
+  it("going offline triggers callback with connected=false", async () => {
+    const manager = new NetworkManager();
+    const callback = vi.fn();
+
+    manager.onStatusChange(callback);
+    await manager.initialize();
+
+    networkStatusChangeHandler?.({ connected: false, connectionType: "none" });
+
+    expect(callback).toHaveBeenCalledWith({ connected: false, connectionType: "none" });
+    expect(manager.isOnline).toBe(false);
+  });
+
+  it("going online triggers callback with connected=true", async () => {
+    getStatusMock.mockResolvedValue({ connected: false, connectionType: "none" });
+    const manager = new NetworkManager();
+    const callback = vi.fn();
+
+    manager.onStatusChange(callback);
+    await manager.initialize();
+
+    networkStatusChangeHandler?.({ connected: true, connectionType: "wifi" });
+
+    expect(callback).toHaveBeenCalledWith({ connected: true, connectionType: "wifi" });
+    expect(manager.isOnline).toBe(true);
+  });
+
+  it("stopMonitoring() removes listener handle", async () => {
+    const manager = new NetworkManager();
+
+    await manager.initialize();
+    await manager.stopMonitoring();
+
+    expect(removeListenerMock).toHaveBeenCalledTimes(1);
+    expect(manager.isMonitoring).toBe(false);
+  });
+
+  it("getStatus() returns copy (not reference)", async () => {
+    const manager = new NetworkManager();
+
+    await manager.initialize();
+
+    const status = manager.getStatus();
+    status.connected = false;
+    status.connectionType = "none";
+
+    expect(manager.getStatus()).toEqual({ connected: true, connectionType: "wifi" });
+  });
+
+  it("onStatusChange unsubscribe works", async () => {
+    const manager = new NetworkManager();
+    const callback = vi.fn();
+
+    const unsubscribe = manager.onStatusChange(callback);
+    await manager.initialize();
+    unsubscribe();
+
+    networkStatusChangeHandler?.({ connected: false, connectionType: "none" });
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("initialize() swallows errors", async () => {
+    getStatusMock.mockRejectedValue(new Error("network unavailable"));
+    const manager = new NetworkManager();
+
+    await expect(manager.initialize()).resolves.toBeUndefined();
+
+    expect(manager.getStatus()).toEqual({ connected: true, connectionType: "unknown" });
+  });
+
+  it("destroy() stops monitoring and clears listeners", async () => {
+    const manager = new NetworkManager();
+    const callback = vi.fn();
+
+    manager.onStatusChange(callback);
+    await manager.initialize();
+    await manager.destroy();
+
+    networkStatusChangeHandler?.({ connected: false, connectionType: "none" });
+
+    expect(removeListenerMock).toHaveBeenCalledTimes(1);
+    expect(callback).not.toHaveBeenCalled();
+    expect(manager.isMonitoring).toBe(false);
+    expect(manager.isInitialized).toBe(false);
+  });
+});

packages/dashboard/src/__tests__/splash-screen.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+import { SplashScreen } from "@capacitor/splash-screen";
+import { SplashScreenManager } from "../plugins/splash-screen.js";
+
+vi.mock("@capacitor/splash-screen", () => ({
+  SplashScreen: {
+    hide: vi.fn(),
+    show: vi.fn(),
+  },
+}));
+
+describe("SplashScreenManager", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(SplashScreen.hide).mockResolvedValue(undefined);
+    vi.mocked(SplashScreen.show).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("initialize() with autoHide=true triggers hide after delay", async () => {
+    vi.useFakeTimers();
+    const manager = new SplashScreenManager({ autoHide: true, hideDelay: 100 });
+
+    await manager.initialize();
+    expect(SplashScreen.hide).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(SplashScreen.hide).toHaveBeenCalledTimes(1);
+    expect(SplashScreen.hide).toHaveBeenCalledWith({ fadeOutDuration: 300 });
+  });
+
+  it("initialize() with autoHide=false does not auto-hide", async () => {
+    vi.useFakeTimers();
+    const manager = new SplashScreenManager({ autoHide: false, hideDelay: 100 });
+
+    await manager.initialize();
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(SplashScreen.hide).not.toHaveBeenCalled();
+  });
+
+  it("hide() delegates to SplashScreen.hide()", async () => {
+    const manager = new SplashScreenManager();
+
+    await manager.hide();
+
+    expect(SplashScreen.hide).toHaveBeenCalledTimes(1);
+    expect(SplashScreen.hide).toHaveBeenCalledWith({ fadeOutDuration: 300 });
+  });
+
+  it("show() delegates to SplashScreen.show()", async () => {
+    const manager = new SplashScreenManager();
+
+    await manager.show();
+
+    expect(SplashScreen.show).toHaveBeenCalledTimes(1);
+    expect(SplashScreen.show).toHaveBeenCalledWith({ autoHide: false });
+  });
+
+  it("initialize() is idempotent", async () => {
+    vi.useFakeTimers();
+    const manager = new SplashScreenManager({ autoHide: true, hideDelay: 50 });
+
+    await manager.initialize();
+    await manager.initialize();
+    await vi.advanceTimersByTimeAsync(50);
+
+    expect(SplashScreen.hide).toHaveBeenCalledTimes(1);
+  });
+
+  it("hide() swallows errors gracefully", async () => {
+    vi.mocked(SplashScreen.hide).mockRejectedValue(new Error("unavailable"));
+    const manager = new SplashScreenManager();
+
+    await expect(manager.hide()).resolves.toBeUndefined();
+  });
+
+  it("destroy() resets initialized state", async () => {
+    const manager = new SplashScreenManager({ autoHide: false });
+    await manager.initialize();
+
+    expect(manager.isInitialized).toBe(true);
+
+    await manager.destroy();
+
+    expect(manager.isInitialized).toBe(false);
+  });
+});

packages/dashboard/src/__tests__/status-bar.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { StatusBar, Style } from "@capacitor/status-bar";
+import { StatusBarManager } from "../plugins/status-bar.js";
+
+vi.mock("@capacitor/status-bar", () => ({
+  StatusBar: {
+    setStyle: vi.fn(),
+  },
+  Style: {
+    Dark: "DARK",
+    Light: "LIGHT",
+  },
+}));
+
+describe("StatusBarManager", () => {
+  const originalMatchMedia = globalThis.window?.matchMedia;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(StatusBar.setStyle).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    if (globalThis.window) {
+      Object.defineProperty(globalThis.window, "matchMedia", {
+        configurable: true,
+        writable: true,
+        value: originalMatchMedia,
+      });
+    }
+  });
+
+  it("initialize() applies current theme", async () => {
+    const manager = new StatusBarManager({ themeMode: "dark" });
+
+    await manager.initialize();
+
+    expect(StatusBar.setStyle).toHaveBeenCalledTimes(1);
+    expect(StatusBar.setStyle).toHaveBeenCalledWith({ style: Style.Dark });
+  });
+
+  it("setTheme('dark') sets dark style", async () => {
+    const manager = new StatusBarManager({ themeMode: "light" });
+
+    await manager.setTheme("dark");
+
+    expect(StatusBar.setStyle).toHaveBeenCalledWith({ style: Style.Dark });
+    expect(manager.getTheme()).toBe("dark");
+  });
+
+  it("setTheme('light') sets light style", async () => {
+    const manager = new StatusBarManager({ themeMode: "dark" });
+
+    await manager.setTheme("light");
+
+    expect(StatusBar.setStyle).toHaveBeenCalledWith({ style: Style.Light });
+    expect(manager.getTheme()).toBe("light");
+  });
+
+  it("setTheme('system') detects system preference", async () => {
+    const manager = new StatusBarManager();
+
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockReturnValue({ matches: true }),
+    });
+
+    await manager.setTheme("system");
+
+    expect(StatusBar.setStyle).toHaveBeenLastCalledWith({ style: Style.Dark });
+
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockReturnValue({ matches: false }),
+    });
+
+    await manager.setTheme("system");
+
+    expect(StatusBar.setStyle).toHaveBeenLastCalledWith({ style: Style.Light });
+  });
+
+  it("onThemeChange callback fires on theme change", async () => {
+    const manager = new StatusBarManager();
+    const callback = vi.fn();
+
+    manager.onThemeChange(callback);
+    await manager.setTheme("dark");
+
+    expect(callback).toHaveBeenCalledWith("dark");
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("onThemeChange unsubscribe stops callbacks", async () => {
+    const manager = new StatusBarManager();
+    const callback = vi.fn();
+
+    const unsubscribe = manager.onThemeChange(callback);
+    await manager.setTheme("dark");
+    unsubscribe();
+    await manager.setTheme("light");
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("initialize() swallows errors", async () => {
+    vi.mocked(StatusBar.setStyle).mockRejectedValue(new Error("not available"));
+    const manager = new StatusBarManager({ themeMode: "dark" });
+
+    await expect(manager.initialize()).resolves.toBeUndefined();
+    expect(manager.isInitialized).toBe(true);
+  });
+
+  it("destroy() clears all listeners", async () => {
+    const manager = new StatusBarManager();
+    const callback = vi.fn();
+
+    manager.onThemeChange(callback);
+    await manager.destroy();
+    await manager.setTheme("dark");
+
+    expect(callback).not.toHaveBeenCalled();
+    expect(manager.isInitialized).toBe(false);
+  });
+});