@checkstack/frontend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# @checkstack/frontend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/auth-frontend@0.0.2
+  - @checkstack/catalog-frontend@0.0.2
+  - @checkstack/command-frontend@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/frontend-api@0.0.2
+  - @checkstack/signal-common@0.0.2
+  - @checkstack/signal-frontend@0.0.2
+  - @checkstack/ui@0.0.2
+
+## 0.1.4
+
+### Patch Changes
+
+- ae33df2: Move command palette from dashboard to centered navbar position
+
+  - Converted `command-frontend` into a plugin with `NavbarCenterSlot` extension
+  - Added compact `NavbarSearch` component with responsive search trigger
+  - Moved `SearchDialog` from dashboard-frontend to command-frontend
+  - Keyboard shortcut (⌘K / Ctrl+K) now works on every page
+  - Renamed navbar slots for clarity:
+    - `NavbarSlot` → `NavbarRightSlot`
+    - `NavbarMainSlot` → `NavbarLeftSlot`
+    - Added new `NavbarCenterSlot` for centered content
+
+- Updated dependencies [52231ef]
+- Updated dependencies [b0124ef]
+- Updated dependencies [54cc787]
+- Updated dependencies [a65e002]
+- Updated dependencies [ae33df2]
+- Updated dependencies [a65e002]
+- Updated dependencies [32ea706]
+  - @checkstack/auth-frontend@0.3.0
+  - @checkstack/ui@0.1.2
+  - @checkstack/catalog-frontend@0.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/command-frontend@0.1.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/signal-common@0.1.1
+  - @checkstack/signal-frontend@0.1.1
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [1bf71bb]
+  - @checkstack/auth-frontend@0.2.1
+  - @checkstack/catalog-frontend@0.0.5
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [e26c08e]
+  - @checkstack/auth-frontend@0.2.0
+  - @checkstack/catalog-frontend@0.0.4
+
+## 0.1.1
+
+### Patch Changes
+
+- 0f8cc7d: Add runtime configuration API for Docker deployments
+
+  - Backend: Add `/api/config` endpoint serving `BASE_URL` at runtime
+  - Backend: Update CORS to use `BASE_URL` and auto-allow Vite dev server
+  - Backend: `INTERNAL_URL` now defaults to `localhost:3000` (no BASE_URL fallback)
+  - Frontend API: Add `RuntimeConfigProvider` context for runtime config
+  - Frontend: Use `RuntimeConfigProvider` from `frontend-api`
+  - Auth Frontend: Add `useAuthClient()` hook using runtime config
+
+- Updated dependencies [0f8cc7d]
+  - @checkstack/frontend-api@0.0.3
+  - @checkstack/auth-frontend@0.1.1
+  - @checkstack/catalog-frontend@0.0.3
+  - @checkstack/command-frontend@0.0.3
+  - @checkstack/ui@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/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]
+  - @checkstack/ui@0.1.0
+  - @checkstack/common@0.1.0
+  - @checkstack/auth-frontend@0.1.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/signal-frontend@0.1.0
+  - @checkstack/catalog-frontend@0.0.2
+  - @checkstack/command-frontend@0.0.2
+  - @checkstack/frontend-api@0.0.2

package/index.html

@@ -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>Checkstack Health Monitor</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

@@ -0,0 +1,45 @@
+{
+  "name": "@checkstack/frontend",
+  "version": "0.0.2",
+  "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": {
+    "@checkstack/auth-frontend": "workspace:*",
+    "@checkstack/catalog-frontend": "workspace:*",
+    "@checkstack/command-frontend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/frontend-api": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@checkstack/signal-frontend": "workspace:*",
+    "@checkstack/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": {
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/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

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

package/src/App.tsx

@@ -0,0 +1,216 @@
+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,
+  NavbarRightSlot,
+  NavbarLeftSlot,
+  NavbarCenterSlot,
+  RuntimeConfigProvider,
+  useRuntimeConfigLoading,
+  useRuntimeConfig,
+} from "@checkstack/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 "@checkstack/ui";
+import { SignalProvider } from "@checkstack/signal-frontend";
+import { usePluginLifecycle } from "./hooks/usePluginLifecycle";
+import {
+  useCommands,
+  useGlobalShortcuts,
+} from "@checkstack/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 z-50 relative">
+          <div className="flex items-center justify-between gap-4">
+            {/* Left: Logo and main navigation */}
+            <div className="flex items-center gap-8 flex-shrink-0">
+              <Link to="/">
+                <h1 className="text-xl font-bold text-primary">Checkstack</h1>
+              </Link>
+              <nav className="hidden md:flex gap-1">
+                <ExtensionSlot slot={NavbarLeftSlot} />
+              </nav>
+            </div>
+            {/* Center: Search (flexible width, centered) */}
+            <div className="flex-1 flex justify-center max-w-md">
+              <ExtensionSlot slot={NavbarCenterSlot} />
+            </div>
+            {/* Right: Other navbar items */}
+            <div className="flex gap-2 flex-shrink-0">
+              <ExtensionSlot slot={NavbarRightSlot} />
+            </div>
+          </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>
+  );
+}
+
+/**
+ * App wrapper that provides APIs and waits for runtime config to load.
+ */
+function AppWithApis() {
+  const isConfigLoading = useRuntimeConfigLoading();
+  const { baseUrl } = useRuntimeConfig();
+
+  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(baseUrl);
+      })
+      .registerFactory(rpcApiRef, (_registry) => {
+        return new CoreRpcApi(baseUrl);
+      });
+
+    // 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();
+  }, [baseUrl]);
+
+  // Show loading while fetching runtime config
+  if (isConfigLoading) {
+    return (
+      <div className="h-screen flex items-center justify-center bg-background">
+        <LoadingSpinner />
+      </div>
+    );
+  }
+
+  return (
+    <ApiProvider registry={apiRegistry}>
+      <SignalProvider backendUrl={baseUrl}>
+        <ToastProvider>
+          <AppContent />
+        </ToastProvider>
+      </SignalProvider>
+    </ApiProvider>
+  );
+}
+
+function App() {
+  return (
+    <RuntimeConfigProvider>
+      <AppWithApis />
+    </RuntimeConfigProvider>
+  );
+}
+
+export default App;

package/src/apis/fetch-api.ts

@@ -0,0 +1,29 @@
+import { FetchApi } from "@checkstack/frontend-api";
+
+export class CoreFetchApi implements FetchApi {
+  private baseUrl: string;
+
+  constructor(baseUrl: string = "http://localhost:3000") {
+    this.baseUrl = baseUrl;
+  }
+
+  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) => {
+        return this.fetch(`${this.baseUrl}/api/${pluginId}${path}`, init);
+      },
+    };
+  }
+}

package/src/apis/logger-api.ts

@@ -0,0 +1,16 @@
+import { LoggerApi } from "@checkstack/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

@@ -0,0 +1,30 @@
+import { RpcApi } from "@checkstack/frontend-api";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ClientDefinition, InferClient } from "@checkstack/common";
+
+export class CoreRpcApi implements RpcApi {
+  public client: unknown;
+  private pluginClientCache: Map<string, unknown> = new Map();
+
+  constructor(baseUrl: string = "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

@@ -0,0 +1,46 @@
+import { useEffect, useReducer } from "react";
+import { useSignal } from "@checkstack/signal-frontend";
+import {
+  PLUGIN_INSTALLED,
+  PLUGIN_DEREGISTERED,
+} from "@checkstack/signal-common";
+import { pluginRegistry } from "@checkstack/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

@@ -0,0 +1,48 @@
+@import "@checkstack/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;
+}
+
+/* Subtle pulse animation for navbar search */
+@keyframes pulse-glow {
+
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 hsl(var(--primary) / 0);
+  }
+
+  50% {
+    box-shadow: 0 0 8px 2px hsl(var(--primary) / 0.15);
+  }
+}

package/src/main.tsx

@@ -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 "@checkstack/ui";
+
+// Initialize plugins before rendering
+await loadPlugins();
+
+ReactDOM.createRoot(document.querySelector("#root")!).render(
+  <React.StrictMode>
+    <ThemeProvider defaultTheme="light" storageKey="checkstack-ui-theme">
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);

package/src/plugin-loader.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { loadPlugins } from "./plugin-loader";
+
+// Note: We don't mock @checkstack/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("@checkstack/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

@@ -0,0 +1,209 @@
+import {
+  FrontendPlugin,
+  pluginRegistry,
+} from "@checkstack/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

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { pluginRegistry, createSlot } from "@checkstack/frontend-api";
+import { FrontendPlugin } from "@checkstack/frontend-api";
+import { createRoutes } from "@checkstack/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

@@ -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

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

package/vite.config.ts

@@ -0,0 +1,62 @@
+import { defineConfig } 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(() => {
+  // Backend URL for proxy - always targets local backend in dev
+  const backendUrl = "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: backendUrl,
+          ws: true, // Enable WebSocket proxy
+        },
+        "/assets": backendUrl,
+      },
+    },
+    // ============================================================
+    // 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

@@ -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,
+  },
+});