@checkstack/frontend 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @checkstack/frontend
 
+## 0.8.0
+
+### Minor Changes
+
+- 968c12f: Show a loading spinner on initial app load instead of a blank screen. The host
+  boots by awaiting plugin registration + Module Federation init before React
+  mounts, which left `#root` empty for a few seconds. `index.html` now renders an
+  inline, theme-aware boot splash (visible before the JS/CSS bundles load, with a
+  no-flash light/dark head start mirroring the saved theme, and reduced-motion
+  safe) that `main.tsx` removes once the app has rendered.
+- 968c12f: Make installed (runtime) frontend plugins actually load, via Module Federation 2.0. Previously a packed external plugin's frontend could not run: the host only shared React/router with runtime plugins, and there was no working way to share the framework/UI singletons (hand-rolled import-map externalisation hit an unsolvable rolldown CJS-interop wall).
+
+  - **Host (`@checkstack/frontend`)** now uses `@module-federation/vite` as an MF host and loads runtime plugins through the MF runtime (`registerRemotes` + `loadRemote`) instead of a raw `import()`. The shared set (react, react-dom, react-router-dom, @tanstack/react-query, @checkstack/frontend-api) is owned by the host; plugins reuse those exact instances via the share scope. The old hand-rolled vendor build + import map are removed.
+  - **`@checkstack/ui`** is bundled per consumer (tree-shaken); its Theme / Toast / Performance React contexts are unified across the host and bundled-in-plugin copies via a registered (globalThis-keyed) context, so a plugin's `useTheme`/`useToast`/`usePerformance` resolve to the host's providers. The ONE exception is the Monaco / VS Code **CodeEditor**, now exposed as the `@checkstack/ui/code-editor` subpath and shared as an MF singleton: the host owns the single editor instance (and builds its `?worker&url` workers), and plugins reuse it. A plugin can now render `<CodeEditor>` (directly or via `ScriptTestPanel` / template/JSON fields) without bundling Monaco.
+  - **Scaffold + pack (`@checkstack/scripts`)** build frontend plugins as MF remotes (`vite build` with the federation plugin, exposing `./plugin`, manifest enabled, DTS disabled). The CodeEditor is shared with `import: false` so the plugin is a consume-only participant - it never bundles a local fallback of the editor, keeping the heavy `@codingame/*` / `monaco-languageclient` / `vscode` subtree out of the plugin entirely (so no `vscode` alias or ES-worker config is needed in the plugin build). `plugin-pack` builds frontend packages with `NODE_ENV=production` (the MF plugin skips the remote under `NODE_ENV=test`) and ships only `dist/`. The scaffolded route now declares a `nav` entry so it appears in the sidebar.
+  - **Backend (`@checkstack/backend`)** serves a plugin's MF assets under its (possibly scoped) package name (`/assets/plugins/@scope/name/*`), with correct content types, and the SPA catch-all defers those paths so the federation manifest/remoteEntry are not shadowed by `index.html`.
+
+  Verified end-to-end by the external-plugin install E2E (scaffold → pack → install via the Plugin Manager UI → frontend + backend + co-loaded core plugins all work).
+
+### Patch Changes
+
+- ed251b6: Make `@checkstack/ui`'s Monaco `CodeEditor` render in standalone `bun run dev`, and consolidate the Monaco editor Vite settings into one shared helper so they can't drift.
+
+  - **Shared config (now in `@checkstack/ui`).** `@checkstack/ui` exports a `monacoViteConfig` helper (`@checkstack/ui/src/vite-monaco`) with the editor's Vite settings - `worker.format: "es"` and the `vscode` resolve alias (so `require("vscode")` doesn't leak into the browser). `@checkstack/ui` owns `CodeEditor` and the editor dependencies, so all three consumers now share one source: the app's `vite.config.ts`, `@checkstack/dev-server`, and `@checkstack/ui`'s own Storybook config (each previously hand-rolled its own copy).
+  - **Pre-built workers (dev server).** In a standalone plugin, `@checkstack/ui` is a _pre-bundled npm dependency_, and Vite's dependency optimizer can't process the Monaco language workers it imports via `?worker&url` - the dev server used to crash (and serving `@checkstack/ui` as source instead broke the CJS/ESM interop of its other deps). The dev server now pre-builds the three Monaco workers (editor / TypeScript / JSON) into static ES-module bundles, serves them, and redirects the `?worker&url` imports to them via `resolve.alias` (which applies during pre-bundling). `@checkstack/ui` stays pre-bundled and the workers resolve, so the editor renders. Builds are content-addressed and cached under `node_modules/.cache/checkstack-dev-monaco` (concurrency-safe atomic promotion), so only the first run after a dependency change pays the build cost. React is deduped so the editor's hooks share the dev shell's React instance.
+
+- Updated dependencies [ed251b6]
+- Updated dependencies [968c12f]
+  - @checkstack/ui@1.14.0
+  - @checkstack/about-frontend@0.3.3
+  - @checkstack/announcement-frontend@0.4.3
+  - @checkstack/auth-frontend@0.7.3
+  - @checkstack/catalog-frontend@0.11.3
+  - @checkstack/command-frontend@0.3.3
+  - @checkstack/dependency-frontend@0.5.3
+  - @checkstack/common@0.14.1
+  - @checkstack/frontend-api@0.7.2
+  - @checkstack/signal-common@0.2.8
+  - @checkstack/signal-frontend@0.2.2
+
+## 0.7.2
+
+### Patch Changes
+
+- Updated dependencies [1fee9da]
+  - @checkstack/common@0.14.1
+  - @checkstack/about-frontend@0.3.2
+  - @checkstack/announcement-frontend@0.4.2
+  - @checkstack/auth-frontend@0.7.2
+  - @checkstack/catalog-frontend@0.11.2
+  - @checkstack/command-frontend@0.3.2
+  - @checkstack/dependency-frontend@0.5.2
+  - @checkstack/frontend-api@0.7.2
+  - @checkstack/signal-common@0.2.8
+  - @checkstack/ui@1.13.2
+  - @checkstack/signal-frontend@0.2.2
+
 ## 0.7.1
 
 ### Patch Changes

package/index.html

@@ -6,23 +6,87 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Checkstack Health Monitor</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-  <!-- 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"
+  <!--
+    Resolve the saved theme BEFORE first paint so the boot splash (and the
+    app's first frame) match the user's light/dark choice instead of flashing.
+    Mirrors ThemeProvider (storageKey "checkstack-ui-theme"); ThemeProvider
+    re-applies the class on mount, so this is purely a no-flash head start.
+  -->
+  <script>
+    (function () {
+      try {
+        var t = localStorage.getItem("checkstack-ui-theme") || "system";
+        var dark =
+          t === "dark" ||
+          (t === "system" &&
+            window.matchMedia("(prefers-color-scheme: dark)").matches);
+        if (dark) document.documentElement.classList.add("dark");
+      } catch (e) {
+        /* localStorage unavailable (private mode) - default to light */
       }
-    }
+    })();
   </script>
+  <!--
+    Boot splash styles. Inlined (not in the app CSS bundle) so the spinner is
+    visible during the blank window while main.tsx loads plugins + initialises
+    Module Federation, before React mounts. Colours mirror the theme tokens in
+    core/ui/src/themes.css. Removed by main.tsx once the app renders.
+  -->
+  <style>
+    #boot-splash {
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: hsl(0 0% 100%);
+    }
+
+    html.dark #boot-splash {
+      background: hsl(240 10% 4%);
+    }
+
+    #boot-splash .boot-splash__spinner {
+      width: 2.5rem;
+      height: 2.5rem;
+      border-radius: 9999px;
+      border: 3px solid hsl(262 83% 58% / 0.2);
+      border-top-color: hsl(262 83% 58%);
+      animation: boot-splash-spin 0.7s linear infinite;
+    }
+
+    html.dark #boot-splash .boot-splash__spinner {
+      border-color: hsl(263 70% 65% / 0.2);
+      border-top-color: hsl(263 70% 65%);
+    }
+
+    /* Respect reduced-motion: show a static ring instead of spinning. */
+    @media (prefers-reduced-motion: reduce) {
+      #boot-splash .boot-splash__spinner {
+        animation: none;
+      }
+    }
+
+    @keyframes boot-splash-spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  </style>
 </head>
 
 <body>
   <div id="root"></div>
+  <!--
+    Sibling overlay (not a child of #root) so React mounts into an empty
+    container. It covers the viewport until main.tsx removes it after the first
+    render, so the app is already painted underneath when the splash goes away.
+  -->
+  <div id="boot-splash" role="status" aria-label="Loading Checkstack">
+    <div class="boot-splash__spinner"></div>
+  </div>
   <script type="module" src="/src/main.tsx"></script>
 </body>
 
-</html>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/frontend",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "frontend"
@@ -13,25 +13,26 @@
   },
   "scripts": {
     "dev": "vite",
-    "build:vendor": "vite build --config vite.config.vendor.ts",
-    "build": "bun run build:vendor && vite build",
+    "build": "vite build",
     "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "preview": "vite preview",
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/about-frontend": "0.3.0",
-    "@checkstack/announcement-frontend": "0.4.0",
-    "@checkstack/auth-frontend": "0.7.0",
-    "@checkstack/catalog-frontend": "0.11.0",
-    "@checkstack/command-frontend": "0.3.0",
-    "@checkstack/common": "0.13.0",
-    "@checkstack/dependency-frontend": "0.5.0",
-    "@checkstack/frontend-api": "0.7.0",
-    "@checkstack/signal-common": "0.2.6",
-    "@checkstack/signal-frontend": "0.2.0",
-    "@checkstack/ui": "1.13.0",
+    "@checkstack/about-frontend": "0.3.3",
+    "@checkstack/announcement-frontend": "0.4.3",
+    "@checkstack/auth-frontend": "0.7.3",
+    "@checkstack/catalog-frontend": "0.11.3",
+    "@checkstack/command-frontend": "0.3.3",
+    "@checkstack/common": "0.14.1",
+    "@checkstack/dependency-frontend": "0.5.3",
+    "@checkstack/frontend-api": "0.7.2",
+    "@checkstack/signal-common": "0.2.8",
+    "@checkstack/signal-frontend": "0.2.2",
+    "@checkstack/ui": "1.14.0",
+    "@module-federation/runtime": "^2.5",
+    "@module-federation/vite": "^1.16",
     "@orpc/client": "^1.14.4",
     "@tanstack/react-query": "^5.100.14",
     "@tanstack/react-query-devtools": "^5.100.14",
@@ -48,7 +49,7 @@
     "tailwindcss-animate": "^1.0.7"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.4.0",
+    "@checkstack/scripts": "0.5.0",
     "@checkstack/tsconfig": "0.0.7",
     "@types/react": "^18.2.64",
     "@types/react-dom": "^18.2.21",

package/src/main.tsx

@@ -15,3 +15,9 @@ ReactDOM.createRoot(document.querySelector("#root")!).render(
     </ThemeProvider>
   </React.StrictMode>,
 );
+
+// Remove the inline boot splash (see index.html) now that the app has mounted.
+// createRoot's initial render commits synchronously, so the app is already in
+// the DOM underneath the overlay - removing it reveals the app with no blank
+// frame.
+document.querySelector("#boot-splash")?.remove();

package/src/plugin-loader.test.ts

@@ -1,21 +1,30 @@
-import {
-  describe,
-  it,
-  expect,
-  mock,
-  beforeAll,
-  beforeEach,
-  afterAll,
-} from "bun:test";
-import { loadPlugins } from "./plugin-loader";
+import { describe, it, expect, mock, beforeAll, afterAll, beforeEach } from "bun:test";
 
-// 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.
+// The loader registers each runtime (installed) plugin as a Module Federation
+// remote (`registerRemotes`) and loads its exposed `./plugin` (`loadRemote`).
+// Stub both so the test exercises the loader's wiring without a real federation
+// host. `@module-federation/runtime` has exactly one importer in the repo
+// (plugin-loader.ts) and no other test imports it, so this process-wide
+// `mock.module` can't leak into another suite's expectations.
+const registerRemotes = mock(
+  (_remotes: Array<{ name: string; entry: string }>) => {},
+);
+const loadRemote = mock((id: string) => {
+  // The host loads `<remoteName>/plugin`; hand back a valid FrontendPlugin.
+  if (id === "remote_plugin/plugin") {
+    return Promise.resolve({
+      default: { metadata: { pluginId: "remote-plugin" }, extensions: [] },
+    });
+  }
+  return Promise.resolve(undefined);
+});
+
+mock.module("@module-federation/runtime", () => ({
+  registerRemotes,
+  loadRemote,
+}));
 
-// Mock fetch. The `typeof url === "string"` guard means a stray non-string
-// argument can never throw (defensive; the override is also scoped to this
-// suite's lifecycle below).
+// Mock fetch for the enabled-plugins endpoint.
 const mockFetch = mock((url: string) => {
   if (url === "/api/plugins") {
     return Promise.resolve({
@@ -23,73 +32,63 @@ const mockFetch = mock((url: string) => {
       json: () => Promise.resolve([{ name: "remote-plugin", path: "/dist" }]),
     } as unknown as Response);
   }
-  // Mock HEAD request for CSS
-  if (typeof url === "string" && url.endsWith(".css")) {
-    return Promise.resolve({ ok: true } as unknown as Response);
-  }
   return Promise.resolve({ ok: false } as unknown as Response);
 });
 
-// bun test runs every file in ONE shared process, so leaving these overrides on
-// `global` leaks into other files - e.g. the real-HTTP backend auth tests would
-// hit this mock instead of the real fetch and crash. Scope them to this suite.
+// bun test runs every file in ONE shared process, so leaving fetch overridden
+// on `global` leaks into other files - scope it to this suite's lifecycle.
 const originalFetch = global.fetch;
-const originalDocument = global.document;
 
 beforeAll(() => {
   (global as unknown as { fetch: typeof fetch }).fetch = mockFetch as never;
-  global.document = {
-    createElement: mock(() => ({})),
-    head: {
-      append: mock(),
-    },
-  } as unknown as Document;
 });
 
 afterAll(() => {
   (global as unknown as { fetch: typeof fetch }).fetch = originalFetch;
-  (global as unknown as { document: Document }).document = originalDocument;
 });
 
 describe("frontend loadPlugins", () => {
   beforeEach(() => {
     mockFetch.mockClear();
+    registerRemotes.mockClear();
+    loadRemote.mockClear();
   });
 
-  it("should discover and register local and remote plugins", async () => {
-    // Import the real pluginRegistry to verify registration
+  it("registers bundled plugins and loads enabled runtime plugins as MF remotes", async () => {
     const { pluginRegistry } = await import("@checkstack/frontend-api");
+    // Dynamic import so the `mock.module` above is in effect for the loader.
+    const { loadPlugins } = await import("./plugin-loader");
 
-    // Reset registry before test
     pluginRegistry.reset();
 
-    // With eager loading, modules are already resolved objects, not async functions
-    const mockModules = {
+    // Bundled (local) plugins arrive as already-resolved modules from the eager
+    // `import.meta.glob`; the override stands in for that map.
+    const bundledModules = {
       "../../../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);
+    await loadPlugins(bundledModules);
 
-    // Verify plugins are registered
-    const registeredPlugins = pluginRegistry.getPlugins();
-    expect(registeredPlugins.some((p) => p.metadata.pluginId === "local")).toBe(
-      true
-    );
+    const ids = pluginRegistry
+      .getPlugins()
+      .map((p) => p.metadata.pluginId);
+    // Bundled local plugin registered from the eager module map.
+    expect(ids).toContain("local");
+    // Runtime plugin loaded via MF and registered.
+    expect(ids).toContain("remote-plugin");
 
-    // Verify CSS loading was attempted
-    expect(mockFetch).toHaveBeenCalledWith(
-      "/assets/plugins/remote-plugin/index.css",
-      expect.objectContaining({ method: "HEAD" })
-    );
+    // The remote is registered under its identifier-safe name, pointing at the
+    // backend-served manifest, and loaded via its exposed `./plugin`.
+    expect(registerRemotes).toHaveBeenCalledWith([
+      {
+        name: "remote_plugin",
+        entry: "/assets/plugins/remote-plugin/mf-manifest.json",
+      },
+    ]);
+    expect(loadRemote).toHaveBeenCalledWith("remote_plugin/plugin");
 
-    // Clean up
     pluginRegistry.reset();
   });
 });

package/src/plugin-loader.ts

@@ -2,6 +2,48 @@ import {
   FrontendPlugin,
   pluginRegistry,
 } from "@checkstack/frontend-api";
+import { loadRemote, registerRemotes } from "@module-federation/runtime";
+
+/**
+ * Module Federation remote name for a runtime plugin, derived deterministically
+ * from its npm package name so the host and the scaffolded plugin's federation
+ * config agree without coordination. MF remote names must be identifier-safe.
+ * e.g. `@checkstackit/widget-frontend` -> `checkstackit_widget_frontend`.
+ */
+function mfRemoteName(packageName: string): string {
+  return packageName.replace(/^@/, "").replaceAll(/[^a-zA-Z0-9]/g, "_");
+}
+
+/**
+ * Register a runtime plugin as a Module Federation remote (manifest served by
+ * the backend at /assets/plugins/<pkg>/mf-manifest.json) and load its exposed
+ * `./plugin` module. MF's share scope hands the remote the host's React /
+ * Router / QueryClient / framework-api instances, and injects the remote's CSS.
+ */
+async function loadRemotePluginModule(packageName: string): Promise<unknown> {
+  const name = mfRemoteName(packageName);
+  registerRemotes([
+    {
+      name,
+      entry: `/assets/plugins/${packageName}/mf-manifest.json`,
+    },
+  ]);
+  return loadRemote(`${name}/plugin`);
+}
+
+function registerFromModule(mod: unknown, label: string): boolean {
+  if (typeof mod !== "object" || mod === null) return false;
+  const pluginExport = Object.values(mod as Record<string, unknown>).find(
+    (exp): exp is FrontendPlugin => isFrontendPlugin(exp),
+  );
+  if (!pluginExport) {
+    console.warn(`⚠️  No valid FrontendPlugin export found in ${label}`);
+    return false;
+  }
+  console.log(`🔌 Registering plugin: ${pluginExport.metadata.pluginId}`);
+  pluginRegistry.register(pluginExport);
+  return true;
+}
 
 export async function loadPlugins(overrideModules?: Record<string, unknown>) {
   console.log("🔌 discovering plugins...");
@@ -45,24 +87,21 @@ export async function loadPlugins(overrideModules?: Record<string, unknown>) {
     // 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) {
+    // Phase 1: Local plugins (bundled into the host via eager glob — already
+    // loaded). These share React/etc. with the host by virtue of being in the
+    // same build.
+    for (const [path, mod] of Object.entries(modules)) {
       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 (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);
+          registeredNames.add(pluginExport.metadata.pluginId);
+          console.log(
+            `🔌 Registered local plugin: ${pluginExport.metadata.pluginId}`,
+          );
         } else {
           console.warn(`⚠️  No valid FrontendPlugin export found in ${path}`);
         }
@@ -71,50 +110,18 @@ export async function loadPlugins(overrideModules?: Record<string, unknown>) {
       }
     }
 
-    // Phase 2: Remote plugins (runtime)
+    // Phase 2: Runtime (installed) plugins — loaded as Module Federation
+    // remotes so they share the host's singletons.
     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
-          );
+      if (registeredNames.has(plugin.name)) continue;
+      console.log(`🔌 Loading remote plugin: ${plugin.name}`);
+      try {
+        const mod = await loadRemotePluginModule(plugin.name);
+        if (registerFromModule(mod, `remote plugin ${plugin.name}`)) {
+          registeredNames.add(plugin.name);
         }
+      } catch (error) {
+        console.error(`❌ Failed to load remote plugin ${plugin.name}:`, error);
       }
     }
   } catch (error) {
@@ -137,73 +144,30 @@ function isFrontendPlugin(candidate: unknown): candidate is FrontendPlugin {
 }
 
 /**
- * Load a single plugin at runtime (for dynamic installation).
- * Fetches the plugin from the backend and registers it.
+ * Load a single runtime plugin (for dynamic installation without a reload).
  *
- * @param pluginId - The frontend plugin ID (e.g., "my-plugin-frontend")
+ * @param packageName - The plugin's npm package name, matching the
+ *   /assets/plugins/<packageName>/ path the backend serves.
  */
-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;
-  }
-
+export async function loadSinglePlugin(packageName: string): Promise<void> {
+  console.log(`🔌 Loading single plugin: ${packageName}`);
   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}`);
-    }
+    const mod = await loadRemotePluginModule(packageName);
+    registerFromModule(mod, packageName);
   } catch (error) {
-    console.error(`❌ Failed to load plugin ${pluginId}:`, error);
+    console.error(`❌ Failed to load plugin ${packageName}:`, error);
     throw error;
   }
 }
 
 /**
- * Unload a plugin at runtime (for dynamic deregistration).
- * Removes the plugin from the registry and cleans up CSS.
+ * Unload a plugin at runtime (for dynamic deregistration). Removes it from the
+ * registry so its routes/slots stop rendering. (The MF remote container stays
+ * registered for the session; re-installing reuses it.)
  *
- * @param pluginId - The frontend plugin ID (e.g., "my-plugin-frontend")
+ * @param pluginId - The frontend plugin ID (e.g. "widget").
  */
 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/vite.config.ts

@@ -1,47 +1,117 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import path from "node:path";
-import { createRequire } from "node:module";
+import { federation } from "@module-federation/vite";
+// Relative (not the bare `@checkstack/ui/...` specifier): Vite's config loader
+// externalizes bare node_modules imports, which would leave this `.ts` file
+// un-transpiled at config-load time (ERR_UNKNOWN_FILE_EXTENSION). A relative
+// path is bundled into the config instead.
+import { monacoViteConfig } from "../ui/src/vite-monaco";
 
 // Monorepo root is 2 levels up from core/frontend
 const monorepoRoot = path.resolve(__dirname, "../..");
 
-// Resolve the `vscode` npm-alias (= @codingame/monaco-vscode-extension-api) to
-// an absolute path so Vite can alias it. (Migration stage 1.)
-//
-// `@typefox/monaco-editor-react` and `monaco-languageclient` declare
-// `"vscode": "npm:@codingame/monaco-vscode-extension-api"`. Under bun's
-// isolated node_modules that alias is only materialized inside those two
-// packages — but the package that actually does `require("vscode")` at runtime
-// (@codingame/monaco-vscode-api) has no `vscode` in its own scope, so esbuild
-// can't resolve it and leaks a runtime `require` into the browser ("Calling
-// require for vscode in an environment that doesn't expose the require
-// function"). Aliasing every `vscode` specifier to the real package dir fixes
-// it. We resolve the alias *through* @typefox so the path follows bun's store
-// layout on any machine/CI rather than being hardcoded.
-const localRequire = createRequire(path.join(__dirname, "vite.config.ts"));
-const typefoxDir = path.dirname(
-  localRequire.resolve("@typefox/monaco-editor-react", {
-    paths: [path.resolve(__dirname, "../ui")],
-  }),
-);
-const vscodeApiDir = path.dirname(
-  localRequire.resolve("vscode", { paths: [typefoxDir] }),
-);
+// The Monaco / VS Code editor stack (`@checkstack/ui`'s CodeEditor) needs
+// `worker.format: "es"` and a `vscode` resolve alias. Both are produced by this
+// shared helper - also consumed by @checkstack/dev-server - so the app's config
+// and the standalone-plugin dev config never drift. The editor deps live in
+// `core/ui`, so we resolve from there.
+const monaco = monacoViteConfig({
+  resolveFrom: [path.resolve(__dirname, "../ui")],
+});
 
 // https://vitejs.dev/config/
-export default defineConfig(() => {
+export default defineConfig(({ command }) => {
   // Backend URL for proxy - always targets local backend in dev
   const backendUrl = "http://localhost:3000";
+
+  // The shared editor singleton is ONLY wired up for production builds. In dev
+  // (`vite serve`) runtime plugins are compiled straight into the host by
+  // @checkstack/dev-server, so nothing consumes the share - and worse, an
+  // `eager` share forces vite's dep optimizer to crawl the editor's dynamic
+  // `?worker&url` Monaco subtree, whose `@codingame/*` worker files are not
+  // resolvable as bare specifiers from this app root (see the optimizeDeps note
+  // below), which fails dep optimization with UNLOADABLE_DEPENDENCY. In dev the
+  // host just bundles @checkstack/ui's editor normally (worker config + vscode
+  // alias are applied unconditionally below), exactly as before this change.
+  const editorShare =
+    command === "build"
+      ? {
+          // The Monaco / VS Code editor (the only shared piece of
+          // @checkstack/ui). MUST be `eager`: runtime plugins consume it with
+          // `import: false` (no local fallback), and @module-federation/vite's
+          // consume-only shim READS `__mf_module_cache__.share[...]` after
+          // bootstrap rather than lazily invoking the provider - so the host
+          // has to have populated the share scope eagerly or the plugin throws
+          // "imported before federation bootstrap finished". Eager is safe: the
+          // editor's module scope is light (Monaco lives behind a dynamic import
+          // inside CodeEditor.tsx), so this loads the wrapper, NOT Monaco, at
+          // startup. `requiredVersion: false` skips negotiation (workspace:*,
+          // not a semver range). The deep specifier matches the re-export in
+          // core/ui/src/index.ts and the value imports inside @checkstack/ui, so
+          // every editor reference dedupes to one singleton.
+          "@checkstack/ui/code-editor": {
+            singleton: true,
+            eager: true,
+            requiredVersion: false,
+          },
+        }
+      : {};
+
   return {
     // Tell Vite to look for .env files in monorepo root
     envDir: monorepoRoot,
-    plugins: [react()],
+    plugins: [
+      react(),
+      // Module Federation 2.0 host. Runtime (installed) frontend plugins are
+      // built as MF remotes and registered at runtime (see plugin-loader.ts),
+      // so no remotes are declared here. `shared` makes the host the single
+      // owner of these singletons; remotes reuse the host's instances via the
+      // share scope — this is what lets a separately-built plugin share the
+      // host's React / Router / QueryClient / framework contexts (and is why
+      // it works where a hand-rolled import-map externalisation could not).
+      // @checkstack/ui is intentionally NOT shared wholesale: it is bundled per
+      // consumer (tree-shaken) and its few React contexts are unified via a
+      // registered (globalThis-keyed) context — see
+      // core/ui/src/utils/registered-context.ts. The ONE exception is the
+      // CodeEditor (Monaco / VS Code) stack: on a production build it is shared
+      // as a singleton so the host owns the single editor instance (and builds
+      // its `?worker&url` workers) while runtime plugins reuse it instead of
+      // bundling Monaco. See `editorShare` above for why this is build-only.
+      federation({
+        name: "checkstack_host",
+        remotes: {},
+        shared: {
+          react: { singleton: true, eager: true, requiredVersion: "^18.0.0" },
+          "react-dom": {
+            singleton: true,
+            eager: true,
+            requiredVersion: "^18.0.0",
+          },
+          "react-router-dom": {
+            singleton: true,
+            eager: true,
+            requiredVersion: "^7.0.0",
+          },
+          "@tanstack/react-query": {
+            singleton: true,
+            eager: true,
+            requiredVersion: "^5.0.0",
+          },
+          // First-party, version-locked to the host: skip version negotiation
+          // (its dep range is `workspace:*`, not a semver range).
+          "@checkstack/frontend-api": {
+            singleton: true,
+            eager: true,
+            requiredVersion: false,
+          },
+          ...editorShare,
+        },
+      }),
+    ],
     // The @typefox/monaco-editor-react + @codingame/monaco-vscode-* stack
-    // loads its language services in ES module workers. (Migration stage 1.)
-    worker: {
-      format: "es",
-    },
+    // loads its language services in ES module workers.
+    worker: monaco.worker,
     server: {
       proxy: {
         // Proxy API requests and WebSocket connections to backend
@@ -67,20 +137,13 @@ export default defineConfig(() => {
       },
     },
     // ============================================================
-    // React Instance Sharing Strategy
+    // React instance sharing
     // ============================================================
-    // 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.
+    // - BUNDLED plugins (core/* and plugins/*): `resolve.dedupe` forces one
+    //   React copy at build time when all imports are visible.
+    // - RUNTIME (installed) plugins: Module Federation's share scope (see the
+    //   `federation()` plugin above) hands them the host's React instance at
+    //   load time.
     // ============================================================
 
     // Pre-bundle React deps for faster dev server startup (dev mode only)
@@ -95,9 +158,8 @@ export default defineConfig(() => {
         // @checkstack/ui's node_modules under bun's isolated store and are not
         // resolvable as bare specifiers from this app root, so listing them
         // errors ("Failed to resolve dependency ... present in
-        // optimizeDeps.include"). Vite discovers and pre-bundles them through
-        // the import graph instead, and the `require("vscode")` CJS interop is
-        // handled by the `vscode` resolve.alias below.
+        // optimizeDeps.include"). The `require("vscode")` CJS interop is handled
+        // by the `vscode` resolve.alias below.
       ],
     },
     build: {
@@ -105,59 +167,11 @@ export default defineConfig(() => {
       target: "esnext",
       // Generate sourcemaps for production debugging
       sourcemap: true,
-      // Don't wipe dist/ — the vendor build (build:vendor) writes to dist/vendor/
-      // before this build runs, and we need to preserve those files
-      emptyOutDir: false,
-      rollupOptions: {
-        output: {
-          // Split heavy / stable vendor code into dedicated chunks so the
-          // initial (login) load stays small and chunks cache independently.
-          // This complements the `React.lazy(CodeEditor)` split: it does not by
-          // itself keep Monaco off the login page (that's the lazy boundary in
-          // CodeEditor.tsx), but it guarantees the whole `@codingame/*` /
-          // monaco stack lands in ONE chunk that is only fetched when an editor
-          // mounts, rather than smeared across many shared chunks.
-          manualChunks(id) {
-            if (!id.includes("node_modules")) {
-              return;
-            }
-            // NB: do NOT try to hand-group lucide icon modules here. The same
-            // per-icon modules are reached BOTH statically (`import { Plus }
-            // from "lucide-react"` across the app, which must stay eager) and
-            // dynamically (DynamicIcon's lazy icon registry). A manualChunk
-            // keys off module id only, so it can't tell the two apart and ends
-            // up pulling the whole icon set into the eager graph. The lazy
-            // boundary for the data-driven icon set lives in DynamicIcon /
-            // iconRegistry instead (see core/ui).
-            // NOTE: we deliberately do NOT hand-group the Monaco / VS Code
-            // editor stack here. Rollup's natural code-splitting already
-            // isolates it: every `@codingame/*` / `@typefox/*` /
-            // monaco-languageclient module is reachable only through the lazy
-            // `CodeEditor` / `validateScripts` boundaries (see CodeEditor.tsx),
-            // so it lands in dynamically-imported chunks that the initial
-            // (login) load never fetches. A manual `monaco` chunk is actively
-            // harmful: a tiny `@codingame/*` module is pulled in EAGERLY as a
-            // transitive dep of non-editor code, and folding it into one big
-            // chunk with the lazy editor body makes the entire ~10 MB chunk a
-            // static dependency of the entry, re-shipping Monaco to the login
-            // page. Leaving it to natural splitting keeps the heavy editor body
-            // lazy while that tiny eager stub stays inlined where it belongs.
-
-            // The React runtime: one stable chunk shared across the whole app.
-            // `dedupe` above already guarantees a single copy; this only
-            // controls which output file it lands in.
-            if (
-              id.includes("/react/") ||
-              id.includes("/react-dom/") ||
-              id.includes("/react-router") ||
-              id.includes("/scheduler/")
-            ) {
-              return "react-vendor";
-            }
-            return;
-          },
-        },
-      },
+      // Monaco stays off the initial load via the `React.lazy(CodeEditor)`
+      // boundary (see CodeEditor.tsx) — verified preserved under Module
+      // Federation's automatic code-splitting. We do NOT hand-group chunks:
+      // `@module-federation/vite` owns code-splitting and ignores
+      // `manualChunks`.
     },
     resolve: {
       // Force all monorepo packages to use the same React copy at build time.
@@ -172,10 +186,10 @@ export default defineConfig(() => {
       ],
       alias: {
         "@": path.resolve(__dirname, "./src"),
-        // See vscodeApiDir above: alias the `vscode` npm-alias to its real
-        // package dir so @codingame's CJS `require("vscode")` resolves under
-        // bun's isolated store instead of leaking a runtime require.
-        vscode: vscodeApiDir,
+        // Alias the `vscode` npm-alias to its real package dir so @codingame's
+        // CJS `require("vscode")` resolves under bun's isolated store instead
+        // of leaking a runtime require. Resolved by monacoViteConfig above.
+        ...monaco.resolve.alias,
       },
     },
   };

package/vite.config.vendor.ts

@@ -1,42 +0,0 @@
-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({
-  // Don't copy public/ contents — the main build handles that
-  publicDir: false,
-  build: {
-    outDir: "dist/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,
-  },
-});