@checkstack/frontend 0.6.7 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @checkstack/frontend
 
+## 0.7.0
+
+### Minor Changes
+
+- 9dcc848: Cut initial-load JS: lazy plugin contributions, a hardened lazy-by-default contribution contract, on-demand Monaco, and a lighter icon/chart load.
+
+  - Lazy plugin route pages: each plugin's route `element` references a `React.lazy`-wrapped page rendered inside a shared `<Suspense>` boundary. Plugins still register synchronously, so nav, slots, commands, API factories, and `foreignSignals` are available on first paint. This moves ~37 route-page chunks (~600 KB) out of the entry; the entry chunk drops from ~2.4 MB to ~190 KB. Auth flow pages stay eager. The `@checkstack/scripts` scaffold template generates lazy route pages too.
+  - Hardened contribution contract (BREAKING, frontend plugin contract): plugins declare contributions lazily and let the framework own code-splitting, Suspense, and per-plugin error isolation. Routes use `load: () => import("./Page").then((m) => ({ default: m.Page }))` instead of `element: <Page />` (`element` is still accepted for the rare page that must paint without a chunk fetch; provide exactly one). Slot extensions accept either an eager `component` or a lazy `load`; new `getLazyContribution` + `ExtensionComponent` exports from `@checkstack/frontend-api` render either kind. This also fixes runtime-installed plugins: `ExtensionSlot` subscribes to the plugin registry, and the API registry rebuilds when the plugin set changes (`getPlugins()` returns an immutable snapshot via `useSyncExternalStore`). A per-plugin error boundary contains a bad contribution.
+  - On-demand Monaco: the `@checkstack/ui` barrel no longer pulls the `@codingame/*` / `monaco-languageclient` stack into the initial load. `CodeEditor` lazy-loads its Monaco-backed editor behind `React.lazy` + Suspense, `validateTypeScriptSources` imports the editor API via in-body `await import(...)`, and the "vscode services ready" signal moved to a Monaco-free module. The ~10 MB editor body loads only when a `CodeEditor` mounts. A `react-vendor` `manualChunks` split was added for stable vendor caching.
+  - lucide-react 1.x + lighter icons/charts (BREAKING for icon consumers): lucide-react unified from three drifting ranges to `^1.17.0`. lucide v1 removed brand icons, so the GitHub/GitLab marks are vendored in `@checkstack/ui` (`GithubIcon`, `GitlabIcon`, `brandIcons`); a new `IconName` type (`LucideIconName | BrandIconName`) in `@checkstack/common` is canonical, accepted by `AuthStrategy.icon` and the card components, so data-driven brand names keep working. `DynamicIcon` no longer eagerly imports lucide's ~1600-icon map (~1 MB) - it lives in a `React.lazy` `iconRegistry` chunk fetched on first data-driven render, while statically named-imported icons tree-shake normally. The recharts-backed health-check charts (~300 KB) and the `HealthCheckSystemOverview` drawer leave the initial load.
+
+  BREAKING CHANGES:
+
+  - Frontend plugin contract: routes/slot contributions are lazy-by-default (`load` instead of `element`/eager elements) as described above.
+  - Any external consumer importing a brand icon from `lucide-react` (e.g. `import { Github } from "lucide-react"`) must switch to the vendored `@checkstack/ui` brand icons or a custom SVG.
+
+  This is a beta minor.
+
+- 9dcc848: Move primary navigation into a left sidebar, and serve the user guide in-app.
+
+  Feature navigation (a ~20-item user-menu dropdown) now lives in a persistent left sidebar (a slide-over drawer on mobile), grouped by section with the active route highlighted; the user menu keeps only account actions. A route opts into the sidebar with new `nav` metadata (`{ group, icon, label?, order?, accessRule? }`) on its registration, co-located with path + access + title. The sidebar filters entries with the same access check as page guards. `@checkstack/common` gains `isAccessRuleSatisfied` and a centralized set of in-app doc slugs (`APP_DOC_SLUGS` + `docsPath`, with a test asserting each resolves to a real docs page); `@checkstack/auth-frontend` exports `useAccessRules`.
+
+  The backend now serves the Astro Starlight docs build same-origin at `/checkstack/*` (the same artifact deployed to GitHub Pages), so the user guide is available inside the app including for self-hosted / air-gapped installs (served verbatim, no rebuild, no link rewriting; from `CHECKSTACK_DOCS_DIST`, before the SPA catch-all, degrading gracefully when absent; the Docker image builds and ships `docs/dist`; Vite proxies `/checkstack` in dev). The "Docs" link is a shell-owned external sidebar entry under the Documentation group (book icon), opening `/checkstack/user-guide/` in a new tab; the group renders even when no plugin route contributes to it.
+
+  BREAKING (plugin authors): `UserMenuItemsSlot` is no longer the way to add navigation - registering a top user-menu item no longer surfaces it anywhere. Add `nav` to the page's route instead. `UserMenuItemsBottomSlot` (account items) is unchanged. All bundled plugins have been migrated.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/ui@1.13.0
+  - @checkstack/auth-frontend@0.7.0
+  - @checkstack/catalog-frontend@0.11.0
+  - @checkstack/common@0.13.0
+  - @checkstack/dependency-frontend@0.5.0
+  - @checkstack/frontend-api@0.7.0
+  - @checkstack/about-frontend@0.3.0
+  - @checkstack/announcement-frontend@0.4.0
+  - @checkstack/command-frontend@0.3.0
+  - @checkstack/signal-frontend@0.2.0
+  - @checkstack/signal-common@0.2.6
+
 ## 0.6.7
 
 ### Patch Changes

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@checkstack/frontend",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "frontend"
   },
   "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./tailwind-preset": "./tailwind-preset.js",
+    "./*": "./*"
+  },
   "scripts": {
     "dev": "vite",
     "build:vendor": "vite build --config vite.config.vendor.ts",
@@ -16,39 +21,39 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/about-frontend": "0.2.22",
-    "@checkstack/announcement-frontend": "0.3.6",
-    "@checkstack/auth-frontend": "0.6.6",
-    "@checkstack/catalog-frontend": "0.10.6",
-    "@checkstack/command-frontend": "0.2.41",
+    "@checkstack/about-frontend": "0.2.23",
+    "@checkstack/announcement-frontend": "0.3.7",
+    "@checkstack/auth-frontend": "0.6.7",
+    "@checkstack/catalog-frontend": "0.10.7",
+    "@checkstack/command-frontend": "0.2.42",
     "@checkstack/common": "0.12.0",
-    "@checkstack/dependency-frontend": "0.4.7",
+    "@checkstack/dependency-frontend": "0.4.8",
     "@checkstack/frontend-api": "0.6.0",
     "@checkstack/signal-common": "0.2.5",
     "@checkstack/signal-frontend": "0.1.5",
-    "@checkstack/ui": "1.11.0",
-    "@orpc/client": "^1.13.14",
-    "@tanstack/react-query": "^5.64.0",
-    "@tanstack/react-query-devtools": "^5.64.0",
-    "better-auth": "^1.1.8",
+    "@checkstack/ui": "1.12.0",
+    "@orpc/client": "^1.14.4",
+    "@tanstack/react-query": "^5.100.14",
+    "@tanstack/react-query-devtools": "^5.100.14",
+    "autoprefixer": "^10.4.18",
+    "better-auth": "^1.6.13",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
-    "lucide-react": "^0.344.0",
-    "react": "^18.2.0",
+    "lucide-react": "^1.17.0",
+    "react": "^18.3.1",
     "react-dom": "^18.2.0",
-    "react-router-dom": "^6.22.0",
-    "tailwind-merge": "^2.2.0"
+    "react-router-dom": "^7.16.0",
+    "tailwind-merge": "^2.2.0",
+    "tailwindcss": "^3.4.1",
+    "tailwindcss-animate": "^1.0.7"
   },
   "devDependencies": {
     "@checkstack/scripts": "0.3.4",
     "@checkstack/tsconfig": "0.0.7",
     "@types/react": "^18.2.64",
     "@types/react-dom": "^18.2.21",
-    "@vitejs/plugin-react": "^6.0.1",
-    "autoprefixer": "^10.4.18",
-    "postcss": "^8.4.35",
-    "tailwindcss": "^3.4.1",
-    "tailwindcss-animate": "^1.0.7",
-    "vite": "^8.0.8"
+    "@vitejs/plugin-react": "^6.0.2",
+    "postcss": "^8.5.15",
+    "vite": "^8.0.16"
   }
 }

package/src/App.tsx

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useMemo, useState, useSyncExternalStore } from "react";
 import {
   BrowserRouter,
   Routes,
@@ -6,6 +6,7 @@ import {
   Link,
   useNavigate,
 } from "react-router-dom";
+import { Menu } from "lucide-react";
 import {
   ApiProvider,
   ApiRegistryBuilder,
@@ -15,6 +16,7 @@ import {
   rpcApiRef,
   useApi,
   ExtensionSlot,
+  getLazyContribution,
   pluginRegistry,
   DashboardSlot,
   NavbarRightSlot,
@@ -44,6 +46,7 @@ import {
 import { SignalProvider } from "@checkstack/signal-frontend";
 import { SignalAutoInvalidator } from "./components/SignalAutoInvalidator";
 import { SessionProvider } from "@checkstack/auth-frontend";
+import { Sidebar } from "./components/Sidebar";
 import { usePluginLifecycle } from "./hooks/usePluginLifecycle";
 import { useCommands, useGlobalShortcuts } from "@checkstack/command-frontend";
 import { AnnouncementBanner } from "@checkstack/announcement-frontend";
@@ -81,6 +84,26 @@ const queryClient = new QueryClient({
   },
 });
 
+// Stable references for `useSyncExternalStore` subscription to the plugin
+// registry (module scope so they don't change identity across renders).
+const subscribePluginRegistry = (onChange: () => void) =>
+  pluginRegistry.subscribe(onChange);
+const getRegisteredPlugins = () => pluginRegistry.getPlugins();
+
+// Shared fallbacks for lazily-loaded plugin route pages. The loading state
+// mirrors RouteGuard's access-loading look (usePerformance-aware spinner); the
+// error state contains a failed page load instead of white-screening the shell.
+const ROUTE_SUSPENSE_FALLBACK = (
+  <div className="h-full flex items-center justify-center p-8">
+    <LoadingSpinner />
+  </div>
+);
+const ROUTE_ERROR_FALLBACK = (
+  <div className="h-full flex items-center justify-center p-8 text-sm text-muted-foreground">
+    This page failed to load. Try reloading.
+  </div>
+);
+
 /**
  * Component that registers global keyboard shortcuts for all commands.
  * Uses react-router's navigate for SPA navigation.
@@ -132,40 +155,61 @@ function AppContent() {
   // Enable dynamic plugin loading/unloading via signals
   const { isLowPower } = usePerformance();
   usePluginLifecycle();
+  const [mobileNavOpen, setMobileNavOpen] = useState(false);
 
   return (
     <BrowserRouter>
       {/* Global keyboard shortcuts for commands */}
       <GlobalShortcuts />
       <AmbientBackground className="text-foreground font-sans">
-        <AnnouncementBanner />
-        <header className={cn(
-          "p-4 shadow-sm border-b border-border z-50 relative",
-          isLowPower ? "bg-card" : "bg-card/80 backdrop-blur-sm"
-        )}>
-          <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="/" className="flex items-center gap-2">
-                <img src="/favicon.svg" alt="" className="w-7 h-7" />
-                <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="px-3 py-4 md:p-8 max-w-7xl mx-auto">
-          <Routes>
+        {/* App shell: a full-height column - the header spans the FULL width on
+            top, and below it a row holds the left nav (persistent on desktop,
+            drawer on mobile) beside the scrollable content. */}
+        <div className="flex flex-col h-screen overflow-hidden">
+          <AnnouncementBanner />
+          <header
+            className={cn(
+              "shrink-0 p-4 shadow-sm border-b border-border z-40 relative",
+              isLowPower ? "bg-card" : "bg-card/80 backdrop-blur-sm",
+            )}
+          >
+              <div className="flex items-center justify-between gap-4">
+                {/* Left: hamburger (mobile), logo, optional navbar-left slot */}
+                <div className="flex items-center gap-4 md:gap-8 flex-shrink-0">
+                  <button
+                    type="button"
+                    onClick={() => setMobileNavOpen(true)}
+                    aria-label="Open navigation"
+                    className="md:hidden inline-flex items-center justify-center rounded-md p-2 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  >
+                    <Menu className="h-5 w-5" />
+                  </button>
+                  <Link to="/" className="flex items-center gap-2">
+                    <img src="/favicon.svg" alt="" className="w-7 h-7" />
+                    <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 items-center gap-2 flex-shrink-0">
+                  <ExtensionSlot slot={NavbarRightSlot} />
+                </div>
+              </div>
+          </header>
+          <div className="flex flex-1 min-h-0">
+            <Sidebar
+              mobileOpen={mobileNavOpen}
+              onMobileOpenChange={setMobileNavOpen}
+            />
+            <main className="flex-1 min-w-0 overflow-y-auto">
+              <div className="px-3 py-4 md:p-8 w-full max-w-7xl mx-auto">
+                <Routes>
             <Route
               path="/"
               element={
@@ -174,22 +218,46 @@ function AppContent() {
                 </div>
               }
             />
-            {/* Plugin Routes */}
-            {pluginRegistry.getAllRoutes().map((route) => (
-              <Route
-                key={route.path}
-                path={route.path}
-                element={
-                  <RouteGuard accessRule={route.accessRule}>
-                    {route.element}
-                  </RouteGuard>
-                }
-              />
-            ))}
-            {/* Catch-all: show Not Found for unmatched routes */}
-            <Route path="*" element={<NotFound />} />
-          </Routes>
-        </main>
+            {/* Plugin Routes. Each plugin declares its page via a `load` thunk;
+                the framework (`getLazyContribution`) code-splits it and wraps it
+                in Suspense + a per-plugin error boundary, so the page chunk is
+                fetched on navigation (not in the initial load) and a failing
+                page degrades gracefully instead of crashing the shell. */}
+            {pluginRegistry.getAllRoutes().map((route) => {
+              // A route is either lazy (`load`, the default — framework wraps it
+              // in Suspense + error boundary) or eager (`element`, rare — e.g.
+              // the login page on the critical path).
+              let element: React.ReactNode;
+              if (route.load) {
+                const PageElement = getLazyContribution({
+                  id: route.path,
+                  load: route.load,
+                  suspenseFallback: ROUTE_SUSPENSE_FALLBACK,
+                  errorFallback: ROUTE_ERROR_FALLBACK,
+                });
+                element = <PageElement />;
+              } else {
+                element = route.element;
+              }
+              return (
+                <Route
+                  key={route.path}
+                  path={route.path}
+                  element={
+                    <RouteGuard accessRule={route.accessRule}>
+                      {element}
+                    </RouteGuard>
+                  }
+                />
+              );
+            })}
+                  {/* Catch-all: show Not Found for unmatched routes */}
+                  <Route path="*" element={<NotFound />} />
+                </Routes>
+              </div>
+            </main>
+          </div>
+        </div>
       </AmbientBackground>
     </BrowserRouter>
   );
@@ -204,6 +272,15 @@ function AppWithApis() {
     useRuntimeConfigContext();
   const { baseUrl } = useRuntimeConfig();
 
+  // Subscribe to the plugin registry so the API registry below rebuilds when
+  // plugins register/unregister at runtime (e.g. a remotely-installed plugin),
+  // picking up their `apis` factories. `getPlugins()` returns an immutable
+  // snapshot whose reference changes on every registry change.
+  const plugins = useSyncExternalStore(
+    subscribePluginRegistry,
+    getRegisteredPlugins,
+  );
+
   const apiRegistry = useMemo(() => {
     // Initialize API Registry with core apiRefs
     const registryBuilder = new ApiRegistryBuilder()
@@ -219,7 +296,6 @@ function AppWithApis() {
       });
 
     // Register API factories from plugins
-    const plugins = pluginRegistry.getPlugins();
     for (const plugin of plugins) {
       if (plugin.apis) {
         for (const api of plugin.apis) {
@@ -235,7 +311,7 @@ function AppWithApis() {
     }
 
     return registryBuilder.build();
-  }, [baseUrl]);
+  }, [baseUrl, plugins]);
 
   // Show spinner while fetching runtime config and probing baseUrl.
   if (isConfigLoading) {

package/src/components/Sidebar.tsx

@@ -0,0 +1,248 @@
+import React, { useMemo, useState } from "react";
+import { NavLink, useLocation } from "react-router-dom";
+import { pluginRegistry } from "@checkstack/frontend-api";
+import { useAccessRules } from "@checkstack/auth-frontend";
+import {
+  isAccessRuleSatisfied,
+  APP_DOC_SLUGS,
+  docsPath,
+} from "@checkstack/common";
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  cn,
+  usePerformance,
+} from "@checkstack/ui";
+import { LayoutDashboard, ChevronDown, BookOpen } from "lucide-react";
+
+const DOCUMENTATION_GROUP = "Documentation";
+
+/**
+ * Fixed display order for the known nav sections. Unknown groups (e.g. from a
+ * third-party plugin) are appended after these, alphabetically.
+ */
+const GROUP_ORDER = [
+  "Workspace",
+  "Reliability",
+  "Automation",
+  "Configuration",
+  "Documentation",
+] as const;
+
+const COLLAPSED_GROUPS_KEY = "checkstack.sidebar.collapsedGroups";
+
+type AppRoute = ReturnType<typeof pluginRegistry.getAllRoutes>[number];
+type NavRoute = AppRoute & { nav: NonNullable<AppRoute["nav"]> };
+
+interface NavGroup {
+  group: string;
+  items: NavRoute[];
+}
+
+/** Build the access-filtered, grouped, ordered nav model from the route registry. */
+function useNavGroups(): NavGroup[] {
+  const { accessRules } = useAccessRules();
+
+  // getAllRoutes() is recomputed from the registry; plugin load/unload triggers
+  // an App re-render so this stays current. Cheap O(routes) work.
+  const routes = pluginRegistry.getAllRoutes();
+
+  return useMemo(() => {
+    const visible = routes.filter(
+      (route): route is NavRoute =>
+        route.nav !== undefined &&
+        (route.nav.accessRule === undefined ||
+          isAccessRuleSatisfied(accessRules, route.nav.accessRule)),
+    );
+
+    const byGroup = new Map<string, NavRoute[]>();
+    for (const route of visible) {
+      const list = byGroup.get(route.nav.group);
+      if (list) list.push(route);
+      else byGroup.set(route.nav.group, [route]);
+    }
+
+    const orderOf = (group: string): number => {
+      const index = GROUP_ORDER.indexOf(group as (typeof GROUP_ORDER)[number]);
+      return index === -1 ? GROUP_ORDER.length : index;
+    };
+
+    return [...byGroup.entries()]
+      .toSorted(([a], [b]) => orderOf(a) - orderOf(b) || a.localeCompare(b))
+      .map(([group, items]) => ({
+        group,
+        items: items.toSorted(
+          (a, b) =>
+            a.nav.order - b.nav.order || a.nav.label.localeCompare(b.nav.label),
+        ),
+      }));
+  }, [routes, accessRules]);
+}
+
+function loadCollapsedGroups(): Set<string> {
+  try {
+    const raw = globalThis.localStorage?.getItem(COLLAPSED_GROUPS_KEY);
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return new Set(Array.isArray(parsed) ? parsed.filter((g) => typeof g === "string") : []);
+  } catch {
+    return new Set();
+  }
+}
+
+function navItemClass(isActive: boolean): string {
+  return cn(
+    "flex items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors",
+    isActive
+      ? "bg-primary/10 text-primary font-medium"
+      : "text-muted-foreground hover:bg-muted hover:text-foreground",
+  );
+}
+
+interface NavListProps {
+  /** Invoked after a nav link is clicked (used to close the mobile drawer). */
+  onNavigate?: () => void;
+}
+
+/** The shared nav content rendered in both the desktop rail and the mobile drawer. */
+function NavList({ onNavigate }: NavListProps): React.ReactElement {
+  const { isLowPower } = usePerformance();
+  const groups = useNavGroups();
+  const location = useLocation();
+  const [collapsed, setCollapsed] = useState<Set<string>>(loadCollapsedGroups);
+
+  // The in-app user guide is a shell-owned external entry (the backend serves
+  // the static Astro docs at /checkstack/* same-origin), so it lives under the
+  // Documentation group here rather than as a navbar link. Ensure the group
+  // renders even when no plugin route contributes to it.
+  const groupsToRender = useMemo(
+    () =>
+      groups.some((g) => g.group === DOCUMENTATION_GROUP)
+        ? groups
+        : [...groups, { group: DOCUMENTATION_GROUP, items: [] }],
+    [groups],
+  );
+
+  const toggleGroup = (group: string): void => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(group)) next.delete(group);
+      else next.add(group);
+      try {
+        globalThis.localStorage?.setItem(
+          COLLAPSED_GROUPS_KEY,
+          JSON.stringify([...next]),
+        );
+      } catch {
+        // localStorage unavailable (private mode) - in-memory state is enough.
+      }
+      return next;
+    });
+  };
+
+  return (
+    <nav className="flex flex-col gap-1 p-3" aria-label="Primary">
+      {/* Dashboard / home is the one entry the shell owns (route "/"). */}
+      <NavLink to="/" end className={({ isActive }) => navItemClass(isActive)} onClick={onNavigate}>
+        <LayoutDashboard className="h-4 w-4 shrink-0" />
+        <span className="truncate">Dashboard</span>
+      </NavLink>
+
+      {groupsToRender.map(({ group, items }) => {
+        const isCollapsed = collapsed.has(group);
+        const isDocumentation = group === DOCUMENTATION_GROUP;
+        return (
+          <div key={group} className="mt-2">
+            <button
+              type="button"
+              onClick={() => toggleGroup(group)}
+              aria-expanded={!isCollapsed}
+              className="flex w-full items-center justify-between px-3 py-1 text-xs font-semibold uppercase tracking-wide text-muted-foreground/70 hover:text-muted-foreground"
+            >
+              <span className="truncate">{group}</span>
+              <ChevronDown
+                className={cn(
+                  "h-3.5 w-3.5 shrink-0",
+                  !isLowPower && "transition-transform",
+                  isCollapsed && "-rotate-90",
+                )}
+                aria-hidden="true"
+              />
+            </button>
+            {!isCollapsed && (
+              <div className="mt-1 flex flex-col gap-0.5">
+                {items.map((route) => {
+                  const Icon = route.nav.icon;
+                  const active =
+                    location.pathname === route.path ||
+                    location.pathname.startsWith(`${route.path}/`);
+                  return (
+                    <NavLink
+                      key={route.path}
+                      to={route.path}
+                      className={navItemClass(active)}
+                      onClick={onNavigate}
+                    >
+                      <Icon className="h-4 w-4 shrink-0" />
+                      <span className="truncate">{route.nav.label}</span>
+                    </NavLink>
+                  );
+                })}
+                {isDocumentation && (
+                  <a
+                    href={docsPath(APP_DOC_SLUGS.userGuideHome)}
+                    target="_blank"
+                    rel="noreferrer"
+                    title="Open the user guide"
+                    className={navItemClass(false)}
+                    onClick={onNavigate}
+                  >
+                    <BookOpen className="h-4 w-4 shrink-0" />
+                    <span className="truncate">Docs</span>
+                  </a>
+                )}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </nav>
+  );
+}
+
+export interface SidebarProps {
+  /** Whether the mobile drawer is open. */
+  mobileOpen: boolean;
+  onMobileOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Primary app navigation. A persistent rail on >= md screens; a slide-over
+ * drawer (reusing the UI `Sheet`) on small screens, controlled by the navbar
+ * hamburger. Nav entries come from routes that declare `nav` metadata and are
+ * filtered by the user's access rules.
+ */
+export function Sidebar({
+  mobileOpen,
+  onMobileOpenChange,
+}: SidebarProps): React.ReactElement {
+  return (
+    <>
+      {/* Fills the shell row (height comes from the flex parent); scrolls
+          independently of the main content. */}
+      <aside className="hidden md:flex flex-col w-60 shrink-0 border-r border-border overflow-y-auto">
+        <NavList />
+      </aside>
+
+      <Sheet open={mobileOpen} onOpenChange={onMobileOpenChange}>
+        <SheetContent className="p-0 overflow-y-auto">
+          <SheetHeader className="px-4 py-3 border-b border-border">
+            <SheetTitle className="text-base">Navigation</SheetTitle>
+          </SheetHeader>
+          <NavList onNavigate={() => onMobileOpenChange(false)} />
+        </SheetContent>
+      </Sheet>
+    </>
+  );
+}

package/src/plugin-loader.test.ts

@@ -1,11 +1,21 @@
-import { describe, it, expect, mock, beforeEach } from "bun:test";
+import {
+  describe,
+  it,
+  expect,
+  mock,
+  beforeAll,
+  beforeEach,
+  afterAll,
+} 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
+// 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).
 const mockFetch = mock((url: string) => {
   if (url === "/api/plugins") {
     return Promise.resolve({
@@ -14,21 +24,32 @@ const mockFetch = mock((url: string) => {
     } as unknown as Response);
   }
   // Mock HEAD request for CSS
-  if (url.endsWith(".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);
 });
 
-(global as any).fetch = mockFetch;
+// 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.
+const originalFetch = global.fetch;
+const originalDocument = global.document;
 
-// Mock document
-global.document = {
-  createElement: mock(() => ({})),
-  head: {
-    append: mock(),
-  },
-} as unknown as 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(() => {

package/src/plugin-registry.test.ts

@@ -62,7 +62,12 @@ describe("PluginRegistry", () => {
   it("should aggregate all routes from registered plugins", () => {
     const pluginB: FrontendPlugin = {
       metadata: { pluginId: "plugin-b" },
-      routes: [{ route: pluginBRoutes.routes.home }],
+      routes: [
+        {
+          route: pluginBRoutes.routes.home,
+          element: React.createElement("div", null, "Plugin B Route"),
+        },
+      ],
     };
 
     pluginRegistry.register(mockPlugin);
@@ -105,4 +110,56 @@ describe("PluginRegistry", () => {
     expect(extensions.map((e) => e.id)).toContain("ext-a");
     expect(extensions.map((e) => e.id)).toContain("ext-b");
   });
+
+  it("getAllRoutes preserves both eager (element) and lazy (load) routes", () => {
+    const loader = () =>
+      Promise.resolve({
+        default: () => React.createElement("div", null, "Lazy"),
+      });
+    const plugin: FrontendPlugin = {
+      metadata: { pluginId: "test" },
+      routes: [
+        { route: testRoutes.routes.home, element: React.createElement("div") },
+        { route: testRoutes.routes.config, load: loader },
+      ],
+    };
+    pluginRegistry.register(plugin);
+
+    const routes = pluginRegistry.getAllRoutes();
+    const home = routes.find((r) => r.path === "/test/");
+    const config = routes.find((r) => r.path === "/test/config");
+    expect(home?.element).toBeDefined();
+    expect(home?.load).toBeUndefined();
+    expect(config?.load).toBe(loader);
+    expect(config?.element).toBeUndefined();
+  });
+
+  it("getPlugins returns a NEW snapshot reference on every change", () => {
+    // Required for useSyncExternalStore / useMemo consumers to recompute when
+    // a plugin is added or removed at runtime.
+    const before = pluginRegistry.getPlugins();
+    pluginRegistry.register(mockPlugin);
+    const afterRegister = pluginRegistry.getPlugins();
+    expect(afterRegister).not.toBe(before);
+    expect(afterRegister).toContain(mockPlugin);
+
+    pluginRegistry.unregister("test");
+    const afterUnregister = pluginRegistry.getPlugins();
+    expect(afterUnregister).not.toBe(afterRegister);
+    expect(afterUnregister).not.toContain(mockPlugin);
+  });
+
+  it("notifies subscribers on register and unregister", () => {
+    let calls = 0;
+    const unsubscribe = pluginRegistry.subscribe(() => {
+      calls += 1;
+    });
+    pluginRegistry.register(mockPlugin);
+    pluginRegistry.unregister("test");
+    expect(calls).toBe(2);
+
+    unsubscribe();
+    pluginRegistry.register(mockPlugin);
+    expect(calls).toBe(2); // no longer notified after unsubscribe
+  });
 });

package/tailwind-preset.js

@@ -0,0 +1,87 @@
+import tailwindcssAnimate from "tailwindcss-animate";
+
+/**
+ * Shared Checkstack Tailwind preset: the platform's design tokens (colors
+ * mapped to the `@checkstack/ui` CSS variables, border radii) and the
+ * `tailwindcss-animate` plugin. Deliberately carries NO `content` — a
+ * preset must not, so each consumer (the frontend app, the standalone dev
+ * server, a plugin author's own Tailwind setup) supplies its own content
+ * globs.
+ *
+ * Exported as a public subpath (`@checkstack/frontend/tailwind-preset`) so
+ * the standalone dev server can build the dev shell with the platform theme
+ * WITHOUT reaching into frontend internals, and so plugin authors can
+ * `presets: [require("@checkstack/frontend/tailwind-preset")]` in their own
+ * config. `tailwindcss-animate` resolves from `@checkstack/frontend`'s own
+ * (runtime) dependency scope, so this loads correctly from a published
+ * install.
+ *
+ * @type {import('tailwindcss').Config}
+ */
+export default {
+  darkMode: ["class"],
+  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/tailwind.config.js

@@ -1,8 +1,11 @@
-import tailwindcssAnimate from "tailwindcss-animate";
+import checkstackPreset from "./tailwind-preset.js";
 
 /** @type {import('tailwindcss').Config} */
 export default {
-  darkMode: ["class"],
+  // Theme tokens + tailwindcss-animate live in the shared preset (also
+  // exported as `@checkstack/frontend/tailwind-preset`). Only `content`
+  // is app-specific.
+  presets: [checkstackPreset],
   content: [
     "./index.html",
     "./src/**/*.{js,ts,jsx,tsx}",
@@ -13,68 +16,4 @@ export default {
     // 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/vite.config.ts

@@ -59,6 +59,11 @@ export default defineConfig(() => {
         // here for dev convenience so e.g.
         // `curl http://localhost:5173/.checkstack/ready` works.
         "/.checkstack": backendUrl,
+        // In-app user guide: the backend serves the Astro docs build at
+        // /checkstack/* (distinct from /.checkstack above). Proxy it so the
+        // dev SPA shows the same docs. Requires the docs to be built once:
+        // `bun run --filter @checkstack/docs build`.
+        "/checkstack": backendUrl,
       },
     },
     // ============================================================
@@ -103,6 +108,56 @@ export default defineConfig(() => {
       // 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;
+          },
+        },
+      },
     },
     resolve: {
       // Force all monorepo packages to use the same React copy at build time.