npm - @checkmate-monitor/frontend - Versions diffs - 0.1.0 - Mend

@checkmate-monitor/frontend 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/CHANGELOG.md +57 -0
package/index.html +27 -0
package/package.json +45 -0
package/postcss.config.js +6 -0
package/public/.gitkeep +0 -0
package/src/App.tsx +181 -0
package/src/apis/fetch-api.ts +27 -0
package/src/apis/logger-api.ts +16 -0
package/src/apis/rpc-api.ts +33 -0
package/src/hooks/usePluginLifecycle.ts +46 -0
package/src/index.css +35 -0
package/src/main.tsx +17 -0
package/src/plugin-loader.test.ts +74 -0
package/src/plugin-loader.ts +209 -0
package/src/plugin-registry.test.ts +108 -0
package/tailwind.config.js +80 -0
package/tsconfig.json +6 -0
package/vite.config.ts +63 -0
package/vite.config.vendor.ts +40 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,57 @@
+# @checkmate-monitor/frontend
+## 0.1.0
+### Minor Changes
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+  ## New Packages
+  - **@checkmate-monitor/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkmate-monitor/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkmate-monitor/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+  ## Changes
+  - **@checkmate-monitor/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkmate-monitor/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+  ## Usage
+  Backend plugins can emit signals:
+  ```typescript
+  import { coreServices } from "@checkmate-monitor/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkmate-monitor/notification-common";
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+  Frontend components subscribe to signals:
+  ```tsx
+  import { useSignal } from "@checkmate-monitor/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkmate-monitor/notification-common";
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+### Patch Changes
+- Updated dependencies [eff5b4e]
+- Updated dependencies [ffc28f6]
+- Updated dependencies [32f2535]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+  - @checkmate-monitor/ui@0.1.0
+  - @checkmate-monitor/common@0.1.0
+  - @checkmate-monitor/auth-frontend@0.1.0
+  - @checkmate-monitor/signal-common@0.1.0
+  - @checkmate-monitor/signal-frontend@0.1.0
+  - @checkmate-monitor/catalog-frontend@0.0.2
+  - @checkmate-monitor/command-frontend@0.0.2
+  - @checkmate-monitor/frontend-api@0.0.2

package/index.html ADDED Viewed

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Checkmate</title>
+  <!-- Import Map for runtime plugins to share React with host app -->
+  <!-- Runtime plugins use standard `import React from "react"` and browser resolves via this map -->
+  <script type="importmap">
+    {
+      "imports": {
+        "react": "/vendor/react.js",
+        "react-dom": "/vendor/react-dom.js",
+        "react-dom/client": "/vendor/react-dom-client.js",
+        "react-router-dom": "/vendor/react-router-dom.js"
+      }
+    }
+  </script>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,45 @@
+{
+  "name": "@checkmate-monitor/frontend",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build:vendor": "vite build --config vite.config.vendor.ts",
+    "build": "bun run build:vendor && vite build",
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "preview": "vite preview",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkmate-monitor/auth-frontend": "workspace:*",
+    "@checkmate-monitor/catalog-frontend": "workspace:*",
+    "@checkmate-monitor/command-frontend": "workspace:*",
+    "@checkmate-monitor/common": "workspace:*",
+    "@checkmate-monitor/frontend-api": "workspace:*",
+    "@checkmate-monitor/signal-common": "workspace:*",
+    "@checkmate-monitor/signal-frontend": "workspace:*",
+    "@checkmate-monitor/ui": "workspace:*",
+    "@orpc/client": "^1.13.2",
+    "better-auth": "^1.1.8",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "lucide-react": "^0.344.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.22.0",
+    "tailwind-merge": "^2.2.0"
+  },
+  "devDependencies": {
+    "@checkmate-monitor/scripts": "workspace:*",
+    "@checkmate-monitor/tsconfig": "workspace:*",
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.21",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.18",
+    "postcss": "^8.4.35",
+    "tailwindcss": "^3.4.1",
+    "tailwindcss-animate": "^1.0.7",
+    "vite": "^5.1.6"
+  }
+}

package/postcss.config.js ADDED Viewed

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/public/.gitkeep ADDED Viewed

File without changes

package/src/App.tsx ADDED Viewed

@@ -0,0 +1,181 @@
+import { useMemo } from "react";
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Link,
+  useNavigate,
+} from "react-router-dom";
+import {
+  ApiProvider,
+  ApiRegistryBuilder,
+  loggerApiRef,
+  permissionApiRef,
+  fetchApiRef,
+  rpcApiRef,
+  useApi,
+  ExtensionSlot,
+  pluginRegistry,
+  DashboardSlot,
+  NavbarSlot,
+  NavbarMainSlot,
+} from "@checkmate-monitor/frontend-api";
+import { ConsoleLoggerApi } from "./apis/logger-api";
+import { CoreFetchApi } from "./apis/fetch-api";
+import { CoreRpcApi } from "./apis/rpc-api";
+import {
+  PermissionDenied,
+  LoadingSpinner,
+  ToastProvider,
+  AmbientBackground,
+} from "@checkmate-monitor/ui";
+import { SignalProvider } from "@checkmate-monitor/signal-frontend";
+import { usePluginLifecycle } from "./hooks/usePluginLifecycle";
+import {
+  useCommands,
+  useGlobalShortcuts,
+} from "@checkmate-monitor/command-frontend";
+/**
+ * Component that registers global keyboard shortcuts for all commands.
+ * Uses react-router's navigate for SPA navigation.
+ */
+function GlobalShortcuts() {
+  const { commands } = useCommands();
+  const navigate = useNavigate();
+  // Pass "*" as permission since backend already filters by permission
+  useGlobalShortcuts(commands, navigate, ["*"]);
+  // This component renders nothing - it only registers event listeners
+  return <></>;
+}
+const RouteGuard: React.FC<{
+  children: React.ReactNode;
+  permission?: string;
+}> = ({ children, permission }) => {
+  const permissionApi = useApi(permissionApiRef);
+  const { allowed, loading } = permissionApi.usePermission(permission || "");
+  if (loading) {
+    return (
+      <div className="h-full flex items-center justify-center p-8">
+        <LoadingSpinner />
+      </div>
+    );
+  }
+  const isAllowed = permission ? allowed : true;
+  if (!isAllowed) {
+    return <PermissionDenied />;
+  }
+  return <>{children}</>;
+};
+/**
+ * Inner component that handles plugin lifecycle and reactive routing.
+ * Must be inside SignalProvider to receive plugin signals.
+ */
+function AppContent() {
+  // Enable dynamic plugin loading/unloading via signals
+  // This causes re-renders when plugins change
+  usePluginLifecycle();
+  return (
+    <BrowserRouter>
+      {/* Global keyboard shortcuts for commands */}
+      <GlobalShortcuts />
+      <AmbientBackground className="text-foreground font-sans">
+        <header className="p-4 bg-card/80 backdrop-blur-sm shadow-sm border-b border-border flex justify-between items-center z-50 relative">
+          <div className="flex items-center gap-8">
+            <Link to="/">
+              <h1 className="text-xl font-bold text-primary">Checkmate</h1>
+            </Link>
+            <nav className="hidden md:flex gap-1">
+              <ExtensionSlot slot={NavbarMainSlot} />
+            </nav>
+          </div>
+          <div className="flex gap-2">
+            <ExtensionSlot slot={NavbarSlot} />
+          </div>
+        </header>
+        <main className="p-8 max-w-7xl mx-auto">
+          <Routes>
+            <Route
+              path="/"
+              element={
+                <div className="space-y-6">
+                  <ExtensionSlot slot={DashboardSlot} />
+                </div>
+              }
+            />
+            {/* Plugin Routes */}
+            {pluginRegistry.getAllRoutes().map((route) => (
+              <Route
+                key={route.path}
+                path={route.path}
+                element={
+                  <RouteGuard permission={route.permission}>
+                    {route.element}
+                  </RouteGuard>
+                }
+              />
+            ))}
+          </Routes>
+        </main>
+      </AmbientBackground>
+    </BrowserRouter>
+  );
+}
+function App() {
+  const apiRegistry = useMemo(() => {
+    // Initialize API Registry with core apiRefs
+    const registryBuilder = new ApiRegistryBuilder()
+      .register(loggerApiRef, new ConsoleLoggerApi())
+      .register(permissionApiRef, {
+        usePermission: () => ({ loading: false, allowed: true }), // Default to allow all if no auth plugin present
+        useResourcePermission: () => ({ loading: false, allowed: true }),
+        useManagePermission: () => ({ loading: false, allowed: true }),
+      })
+      .registerFactory(fetchApiRef, (_registry) => {
+        return new CoreFetchApi();
+      })
+      .registerFactory(rpcApiRef, (_registry) => {
+        return new CoreRpcApi();
+      });
+    // Register API factories from plugins
+    const plugins = pluginRegistry.getPlugins();
+    for (const plugin of plugins) {
+      if (plugin.apis) {
+        for (const api of plugin.apis) {
+          registryBuilder.registerFactory(api.ref, (registry) => {
+            // Adapt registry map to dependency getter
+            const deps = {
+              get: <T,>(ref: { id: string }) => registry.get(ref.id) as T,
+            };
+            return api.factory(deps);
+          });
+        }
+      }
+    }
+    return registryBuilder.build();
+  }, []);
+  return (
+    <ApiProvider registry={apiRegistry}>
+      <SignalProvider>
+        <ToastProvider>
+          <AppContent />
+        </ToastProvider>
+      </SignalProvider>
+    </ApiProvider>
+  );
+}
+export default App;

package/src/apis/fetch-api.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import { FetchApi } from "@checkmate-monitor/frontend-api";
+export class CoreFetchApi implements FetchApi {
+  constructor() {}
+  async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const headers = new Headers(init?.headers);
+    return fetch(input, {
+      ...init,
+      headers,
+      credentials: "include",
+    });
+  }
+  forPlugin(pluginId: string): {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+  } {
+    return {
+      fetch: (path: string, init?: RequestInit) => {
+        const baseUrl =
+          import.meta.env.VITE_API_BASE_URL || "http://localhost:3000";
+        return this.fetch(`${baseUrl}/api/${pluginId}${path}`, init);
+      },
+    };
+  }
+}

package/src/apis/logger-api.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { LoggerApi } from "@checkmate-monitor/frontend-api";
+export class ConsoleLoggerApi implements LoggerApi {
+  info(message: string, ...args: unknown[]) {
+    console.info(`[INFO] ${message}`, ...args);
+  }
+  error(message: string, ...args: unknown[]) {
+    console.error(`[ERROR] ${message}`, ...args);
+  }
+  warn(message: string, ...args: unknown[]) {
+    console.warn(`[WARN] ${message}`, ...args);
+  }
+  debug(message: string, ...args: unknown[]) {
+    console.debug(`[DEBUG] ${message}`, ...args);
+  }
+}

package/src/apis/rpc-api.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import { RpcApi } from "@checkmate-monitor/frontend-api";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ClientDefinition, InferClient } from "@checkmate-monitor/common";
+export class CoreRpcApi implements RpcApi {
+  public client: unknown;
+  private pluginClientCache: Map<string, unknown> = new Map();
+  constructor() {
+    const baseUrl =
+      import.meta.env.VITE_API_BASE_URL || "http://localhost:3000";
+    const link = new RPCLink({
+      url: `${baseUrl}/api`,
+      fetch: (input: RequestInfo | URL, init?: RequestInit) =>
+        fetch(input, { ...init, credentials: "include" }),
+    });
+    this.client = createORPCClient(link);
+  }
+  forPlugin<T extends ClientDefinition>(def: T): InferClient<T> {
+    const { pluginId } = def;
+    if (!this.pluginClientCache.has(pluginId)) {
+      this.pluginClientCache.set(
+        pluginId,
+        (this.client as Record<string, unknown>)[pluginId]
+      );
+    }
+    return this.pluginClientCache.get(pluginId) as InferClient<T>;
+  }
+}

package/src/hooks/usePluginLifecycle.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import { useEffect, useReducer } from "react";
+import { useSignal } from "@checkmate-monitor/signal-frontend";
+import {
+  PLUGIN_INSTALLED,
+  PLUGIN_DEREGISTERED,
+} from "@checkmate-monitor/signal-common";
+import { pluginRegistry } from "@checkmate-monitor/frontend-api";
+import { loadSinglePlugin, unloadPlugin } from "../plugin-loader";
+/**
+ * Hook that listens to plugin lifecycle signals and dynamically loads/unloads plugins.
+ * Must be used within SignalProvider context.
+ *
+ * Returns the current registry version to trigger re-renders when plugins change.
+ */
+export function usePluginLifecycle(): { version: number } {
+  // Force re-render when registry changes
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+  // Subscribe to registry changes
+  useEffect(() => {
+    return pluginRegistry.subscribe(forceUpdate);
+  }, []);
+  // Listen for plugin installation signal
+  useSignal(PLUGIN_INSTALLED, async ({ pluginId }) => {
+    console.log(`📥 Received PLUGIN_INSTALLED signal for: ${pluginId}`);
+    // Only load if not already registered
+    if (!pluginRegistry.hasPlugin(pluginId)) {
+      try {
+        await loadSinglePlugin(pluginId);
+      } catch (error) {
+        console.error(`❌ Failed to load plugin ${pluginId}:`, error);
+      }
+    }
+  });
+  // Listen for plugin deregistration signal
+  useSignal(PLUGIN_DEREGISTERED, ({ pluginId }) => {
+    console.log(`📥 Received PLUGIN_DEREGISTERED signal for: ${pluginId}`);
+    unloadPlugin(pluginId);
+  });
+  return { version: pluginRegistry.getVersion() };
+}

package/src/index.css ADDED Viewed

@@ -0,0 +1,35 @@
+@import "@checkmate-monitor/ui/src/themes.css";
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+/* Prism JSON highlighting */
+.token.property {
+  color: #4f46e5;
+}
+.token.string {
+  color: #059669;
+}
+.token.number {
+  color: #d97706;
+}
+.token.boolean {
+  color: #2563eb;
+}
+.token.punctuation {
+  color: #4b5563;
+}
+.token.operator {
+  color: #4b5563;
+}
+.editor pre,
+.editor code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace !important;
+}

package/src/main.tsx ADDED Viewed

@@ -0,0 +1,17 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App.tsx";
+import "./index.css";
+import { loadPlugins } from "./plugin-loader.ts";
+import { ThemeProvider } from "@checkmate-monitor/ui";
+// Initialize plugins before rendering
+await loadPlugins();
+ReactDOM.createRoot(document.querySelector("#root")!).render(
+  <React.StrictMode>
+    <ThemeProvider defaultTheme="light" storageKey="checkmate-ui-theme">
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);

package/src/plugin-loader.test.ts ADDED Viewed

@@ -0,0 +1,74 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { loadPlugins } from "./plugin-loader";
+// Note: We don't mock @checkmate-monitor/frontend-api module-wide here because
+// it causes test isolation issues with other tests that use the real pluginRegistry.
+// Instead, we just verify behavior based on the function's outputs.
+// Mock fetch
+const mockFetch = mock((url: string) => {
+  if (url === "/api/plugins") {
+    return Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve([{ name: "remote-plugin", path: "/dist" }]),
+    } as unknown as Response);
+  }
+  // Mock HEAD request for CSS
+  if (url.endsWith(".css")) {
+    return Promise.resolve({ ok: true } as unknown as Response);
+  }
+  return Promise.resolve({ ok: false } as unknown as Response);
+});
+(global as any).fetch = mockFetch;
+// Mock document
+global.document = {
+  createElement: mock(() => ({})),
+  head: {
+    append: mock(),
+  },
+} as unknown as Document;
+describe("frontend loadPlugins", () => {
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+  it("should discover and register local and remote plugins", async () => {
+    // Import the real pluginRegistry to verify registration
+    const { pluginRegistry } = await import("@checkmate-monitor/frontend-api");
+    // Reset registry before test
+    pluginRegistry.reset();
+    // With eager loading, modules are already resolved objects, not async functions
+    const mockModules = {
+      "../../../plugins/local-frontend/src/index.tsx": {
+        default: { metadata: { pluginId: "local" }, extensions: [] },
+      },
+    };
+    // We also need to mock dynamic import() for remote plugins
+    mock.module("/assets/plugins/remote-plugin/index.js", () => ({
+      default: { metadata: { pluginId: "remote-plugin" }, extensions: [] },
+    }));
+    await loadPlugins(mockModules);
+    // Verify plugins are registered
+    const registeredPlugins = pluginRegistry.getPlugins();
+    expect(registeredPlugins.some((p) => p.metadata.pluginId === "local")).toBe(
+      true
+    );
+    // Verify CSS loading was attempted
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/assets/plugins/remote-plugin/index.css",
+      expect.objectContaining({ method: "HEAD" })
+    );
+    // Clean up
+    pluginRegistry.reset();
+  });
+});

package/src/plugin-loader.ts ADDED Viewed

@@ -0,0 +1,209 @@
+import {
+  FrontendPlugin,
+  pluginRegistry,
+} from "@checkmate-monitor/frontend-api";
+export async function loadPlugins(overrideModules?: Record<string, unknown>) {
+  console.log("🔌 discovering plugins...");
+  // 1. Fetch enabled plugins from backend
+  try {
+    const response = await fetch("/api/plugins");
+    if (!response.ok) {
+      console.error("Failed to fetch enabled plugins:", response.statusText);
+      return;
+    }
+    const enabledPlugins: { name: string; path: string }[] =
+      await response.json();
+    // 2. Get all available local plugins using eager loading
+    // This avoids dynamic import issues in production builds
+    // Load from both core/ (essential) and plugins/ (providers)
+    let modules: Record<string, unknown>;
+    if (overrideModules) {
+      modules = overrideModules;
+    } else {
+      const coreModules =
+        // @ts-expect-error - Vite specific property
+        import.meta.glob("../../*-frontend/src/index.tsx", { eager: true });
+      const pluginModules =
+        // @ts-expect-error - Vite specific property
+        import.meta.glob("../../../plugins/*-frontend/src/index.tsx", {
+          eager: true,
+        });
+      modules = { ...coreModules, ...pluginModules };
+    }
+    console.log(
+      `🔌 Found ${
+        Object.keys(modules).length
+      } locally available frontend plugins.`
+    );
+    // 3. Load and register enabled plugins
+    const registeredNames = new Set<string>();
+    // Phase 1: Local plugins (bundled with eager loading - already loaded)
+    const entries = Object.entries(modules);
+    for (const [path, mod] of entries) {
+      try {
+        if (typeof mod !== "object" || mod === null) {
+          continue;
+        }
+        const pluginExport = Object.values(mod as Record<string, unknown>).find(
+          (exp): exp is FrontendPlugin => isFrontendPlugin(exp)
+        );
+        if (pluginExport) {
+          const pluginId = pluginExport.metadata.pluginId;
+          console.log(`🔌 Registering local plugin: ${pluginId}`);
+          pluginRegistry.register(pluginExport);
+          registeredNames.add(pluginId);
+        } else {
+          console.warn(`⚠️  No valid FrontendPlugin export found in ${path}`);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to load local plugin from ${path}`, error);
+      }
+    }
+    // Phase 2: Remote plugins (runtime)
+    for (const plugin of enabledPlugins) {
+      if (!registeredNames.has(plugin.name)) {
+        console.log(`🔌 Attempting to load remote plugin: ${plugin.name}`);
+        try {
+          // 1. Load CSS if it exists
+          const remoteCssUrl = `/assets/plugins/${plugin.name}/index.css`;
+          try {
+            const cssCheck = await fetch(remoteCssUrl, { method: "HEAD" });
+            if (cssCheck.ok) {
+              console.log(`🎨 Loading remote styles for: ${plugin.name}`);
+              const link = document.createElement("link");
+              link.rel = "stylesheet";
+              link.href = remoteCssUrl;
+              document.head.append(link);
+            }
+          } catch (error) {
+            console.debug(`No separate CSS found for ${plugin.name}`, error);
+          }
+          // 2. Load JS entry point
+          const remoteUrl = `/assets/plugins/${plugin.name}/index.js`;
+          const mod = await import(/* @vite-ignore */ remoteUrl);
+          const pluginExport = Object.values(
+            mod as Record<string, unknown>
+          ).find((exp): exp is FrontendPlugin => isFrontendPlugin(exp));
+          if (pluginExport) {
+            const pluginId = pluginExport.metadata.pluginId;
+            console.log(`🔌 Registering enabled remote plugin: ${pluginId}`);
+            pluginRegistry.register(pluginExport);
+            registeredNames.add(pluginId);
+          } else {
+            console.warn(
+              `⚠️  No valid FrontendPlugin export found for remote plugin ${plugin.name}`
+            );
+          }
+        } catch (error) {
+          console.error(
+            `❌ Failed to load remote plugin ${plugin.name}:`,
+            error
+          );
+        }
+      }
+    }
+  } catch (error) {
+    console.error("❌ Critical error loading plugins:", error);
+  }
+}
+function isFrontendPlugin(candidate: unknown): candidate is FrontendPlugin {
+  if (typeof candidate !== "object" || candidate === null) return false;
+  const p = candidate as Record<string, unknown>;
+  // Check for metadata with pluginId
+  if (typeof p.metadata !== "object" || p.metadata === null) return false;
+  const metadata = p.metadata as Record<string, unknown>;
+  if (typeof metadata.pluginId !== "string") return false;
+  // Must have at least one frontend-specific property
+  return "extensions" in p || "routes" in p || "apis" in p;
+}
+/**
+ * Load a single plugin at runtime (for dynamic installation).
+ * Fetches the plugin from the backend and registers it.
+ *
+ * @param pluginId - The frontend plugin ID (e.g., "my-plugin-frontend")
+ */
+export async function loadSinglePlugin(pluginId: string): Promise<void> {
+  console.log(`🔌 Loading single plugin: ${pluginId}`);
+  // Skip if already registered
+  if (pluginRegistry.hasPlugin(pluginId)) {
+    console.warn(`⚠️ Plugin ${pluginId} already registered`);
+    return;
+  }
+  try {
+    // 1. Load CSS if it exists
+    const remoteCssUrl = `/assets/plugins/${pluginId}/index.css`;
+    try {
+      const cssCheck = await fetch(remoteCssUrl, { method: "HEAD" });
+      if (cssCheck.ok) {
+        console.log(`🎨 Loading remote styles for: ${pluginId}`);
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = remoteCssUrl;
+        link.id = `plugin-css-${pluginId}`;
+        document.head.append(link);
+      }
+    } catch (error) {
+      console.debug(`No separate CSS found for ${pluginId}`, error);
+    }
+    // 2. Load JS entry point
+    const remoteUrl = `/assets/plugins/${pluginId}/index.js`;
+    const mod = await import(/* @vite-ignore */ remoteUrl);
+    const pluginExport = Object.values(mod as Record<string, unknown>).find(
+      (exp): exp is FrontendPlugin => isFrontendPlugin(exp)
+    );
+    if (pluginExport) {
+      const pluginId = pluginExport.metadata.pluginId;
+      console.log(`🔌 Registering plugin: ${pluginId}`);
+      pluginRegistry.register(pluginExport);
+    } else {
+      console.warn(`⚠️ No valid FrontendPlugin export found for ${pluginId}`);
+    }
+  } catch (error) {
+    console.error(`❌ Failed to load plugin ${pluginId}:`, error);
+    throw error;
+  }
+}
+/**
+ * Unload a plugin at runtime (for dynamic deregistration).
+ * Removes the plugin from the registry and cleans up CSS.
+ *
+ * @param pluginId - The frontend plugin ID (e.g., "my-plugin-frontend")
+ */
+export function unloadPlugin(pluginId: string): void {
+  console.log(`🔌 Unloading plugin: ${pluginId}`);
+  // Remove from registry
+  pluginRegistry.unregister(pluginId);
+  // Remove CSS if we added it
+  const cssLink = document.querySelector(`#plugin-css-${pluginId}`);
+  if (cssLink) {
+    cssLink.remove();
+  }
+}

package/src/plugin-registry.test.ts ADDED Viewed

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { pluginRegistry, createSlot } from "@checkmate-monitor/frontend-api";
+import { FrontendPlugin } from "@checkmate-monitor/frontend-api";
+import { createRoutes } from "@checkmate-monitor/common";
+import React from "react";
+// Create test slots
+const slotA = createSlot("slot-a");
+const sharedSlot = createSlot("shared-slot");
+// Create test routes using the new pattern
+const testRoutes = createRoutes("test", {
+  home: "/",
+  config: "/config",
+});
+const pluginBRoutes = createRoutes("plugin-b", {
+  home: "/",
+});
+describe("PluginRegistry", () => {
+  beforeEach(() => {
+    // Clear the registry before each test.
+    // Since it's a singleton, we need to manually clear its private state if possible,
+    // or just accept that it's additive if we don't want to refactor.
+    // Let's refactor the registry to be a class we can instantiate for testing.
+    // For now, I'll just check if I can clear it.
+    pluginRegistry.reset();
+  });
+  const mockPlugin: FrontendPlugin = {
+    metadata: { pluginId: "test" },
+    extensions: [
+      {
+        id: "extension-1",
+        slot: slotA,
+        component: () => React.createElement("div", null, "Hello"),
+      },
+    ],
+    routes: [
+      {
+        route: testRoutes.routes.home,
+        element: React.createElement("div", null, "Test Route"),
+      },
+    ],
+  };
+  it("should register a plugin and its extensions", () => {
+    pluginRegistry.register(mockPlugin);
+    expect(pluginRegistry.getPlugins()).toContain(mockPlugin);
+    const extensions = pluginRegistry.getExtensions(slotA.id);
+    expect(extensions).toHaveLength(1);
+    expect(extensions[0].id).toBe("extension-1");
+  });
+  it("should return empty array for unknown slotId", () => {
+    const extensions = pluginRegistry.getExtensions("unknown-slot");
+    expect(extensions).toEqual([]);
+  });
+  it("should aggregate all routes from registered plugins", () => {
+    const pluginB: FrontendPlugin = {
+      metadata: { pluginId: "plugin-b" },
+      routes: [{ route: pluginBRoutes.routes.home }],
+    };
+    pluginRegistry.register(mockPlugin);
+    pluginRegistry.register(pluginB);
+    const routes = pluginRegistry.getAllRoutes();
+    expect(routes).toHaveLength(2);
+    expect(routes.map((r) => r.path)).toContain("/test/");
+    expect(routes.map((r) => r.path)).toContain("/plugin-b/");
+  });
+  it("should allow multiple plugins to register extensions for the same slot", () => {
+    const pluginA: FrontendPlugin = {
+      metadata: { pluginId: "plugin-a" },
+      extensions: [
+        {
+          id: "ext-a",
+          slot: sharedSlot,
+          component: () => React.createElement("div", null, "A"),
+        },
+      ],
+    };
+    const pluginB: FrontendPlugin = {
+      metadata: { pluginId: "plugin-b" },
+      extensions: [
+        {
+          id: "ext-b",
+          slot: sharedSlot,
+          component: () => React.createElement("div", null, "B"),
+        },
+      ],
+    };
+    pluginRegistry.register(pluginA);
+    pluginRegistry.register(pluginB);
+    const extensions = pluginRegistry.getExtensions(sharedSlot.id);
+    expect(extensions).toHaveLength(2);
+    expect(extensions.map((e) => e.id)).toContain("ext-a");
+    expect(extensions.map((e) => e.id)).toContain("ext-b");
+  });
+});

package/tailwind.config.js ADDED Viewed

@@ -0,0 +1,80 @@
+import tailwindcssAnimate from "tailwindcss-animate";
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: ["class"],
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+    // Core frontend plugins (siblings in core/)
+    "../*-frontend/src/**/*.{js,ts,jsx,tsx}",
+    // External plugins
+    "../../plugins/*-frontend/src/**/*.{js,ts,jsx,tsx}",
+    // Shared UI library
+    "../ui/src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+        chart: {
+          1: "hsl(var(--chart-1))",
+          2: "hsl(var(--chart-2))",
+          3: "hsl(var(--chart-3))",
+          4: "hsl(var(--chart-4))",
+          5: "hsl(var(--chart-5))",
+        },
+        success: {
+          DEFAULT: "hsl(var(--success))",
+          foreground: "hsl(var(--success-foreground))",
+        },
+        warning: {
+          DEFAULT: "hsl(var(--warning))",
+          foreground: "hsl(var(--warning-foreground))",
+        },
+        info: {
+          DEFAULT: "hsl(var(--info))",
+          foreground: "hsl(var(--info-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+    },
+  },
+  plugins: [tailwindcssAnimate],
+};

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkmate-monitor/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ]
+}

package/vite.config.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "node:path";
+// Monorepo root is 2 levels up from core/frontend
+const monorepoRoot = path.resolve(__dirname, "../..");
+// https://vitejs.dev/config/
+export default defineConfig(({ mode }) => {
+  // Load env from monorepo root
+  const env = loadEnv(mode, monorepoRoot, "");
+  const target = env.VITE_API_BASE_URL || "http://localhost:3000";
+  return {
+    // Tell Vite to look for .env files in monorepo root
+    envDir: monorepoRoot,
+    plugins: [react()],
+    server: {
+      proxy: {
+        // Proxy API requests and WebSocket connections to backend
+        // Use regex to ensure /api-docs doesn't match (it starts with /api but isn't an API call)
+        "^/api/": {
+          target,
+          ws: true, // Enable WebSocket proxy
+        },
+        "/assets": target,
+      },
+    },
+    // ============================================================
+    // React Instance Sharing Strategy
+    // ============================================================
+    // This config works with two complementary mechanisms:
+    //
+    // 1. BUNDLED PLUGINS (core/* and plugins/*):
+    //    - resolve.dedupe forces Rollup to use single React copy
+    //    - Works at build time when all imports are visible
+    //
+    // 2. RUNTIME PLUGINS (loaded dynamically via import()):
+    //    - Import Maps in index.html resolve "react" → /vendor/react.js
+    //    - Vendor bundles built by vite.config.vendor.ts
+    //    - dedupe can't help here since plugins load AFTER build
+    //
+    // Both mechanisms ensure all code uses the same React instance.
+    // ============================================================
+    // Pre-bundle React deps for faster dev server startup (dev mode only)
+    optimizeDeps: {
+      include: ["react", "react-dom", "react-router-dom"],
+    },
+    build: {
+      // Use esnext to support top-level await and modern ES features
+      target: "esnext",
+    },
+    resolve: {
+      // Force all monorepo packages to use the same React copy at build time.
+      // Without this, each workspace package can bundle its own React copy,
+      // causing "useContext is null" errors from context mismatch.
+      dedupe: ["react", "react-dom", "react-router-dom", "react/jsx-runtime"],
+      alias: {
+        "@": path.resolve(__dirname, "./src"),
+      },
+    },
+  };
+});

package/vite.config.vendor.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { defineConfig } from "vite";
+import path from "node:path";
+/**
+ * Vite config for building vendor bundles as ESM.
+ * These bundles are served via Import Maps so runtime plugins
+ * can use standard `import React from "react"` syntax.
+ *
+ * We point directly to node_modules - no custom entry files needed.
+ */
+export default defineConfig({
+  build: {
+    outDir: "public/vendor",
+    emptyOutDir: true,
+    lib: {
+      formats: ["es"],
+      // Point directly to node_modules packages
+      entry: {
+        react: path.resolve(__dirname, "node_modules/react/index.js"),
+        "react-dom": path.resolve(__dirname, "node_modules/react-dom/index.js"),
+        "react-dom-client": path.resolve(
+          __dirname,
+          "node_modules/react-dom/client.js"
+        ),
+        "react-router-dom": path.resolve(
+          __dirname,
+          "node_modules/react-router-dom/dist/index.js"
+        ),
+      },
+    },
+    rollupOptions: {
+      output: {
+        entryFileNames: "[name].js",
+        chunkFileNames: "[name]-[hash].js",
+      },
+    },
+    minify: false,
+    sourcemap: true,
+  },
+});