@kb-labs/studio-app 0.6.0

package/src/providers/registry-v2-provider.tsx

@@ -0,0 +1,93 @@
+/**
+ * Registry V2 provider — fetches StudioRegistryV2 and initializes Module Federation.
+ *
+ * Fetches StudioRegistryV2 and initializes Module Federation remotes.
+ */
+
+import * as React from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { initFederation, type StudioRegistryV2 } from '@kb-labs/studio-federation';
+import { studioConfig } from '../config/studio.config';
+
+interface RegistryV2ContextValue {
+  registry: StudioRegistryV2;
+  loading: boolean;
+  error: Error | null;
+}
+
+const EMPTY_REGISTRY: StudioRegistryV2 = {
+  schema: 'kb.studio/2',
+  schemaVersion: 2,
+  generatedAt: new Date().toISOString(),
+  plugins: [],
+};
+
+const RegistryV2Context = React.createContext<RegistryV2ContextValue>({
+  registry: EMPTY_REGISTRY,
+  loading: true,
+  error: null,
+});
+
+async function fetchRegistryV2(apiBaseUrl: string, token?: string): Promise<StudioRegistryV2> {
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (token) {headers['Authorization'] = `Bearer ${token}`;}
+
+  const res = await fetch(`${apiBaseUrl}/studio/registry`, { headers });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch studio registry: ${res.status} ${res.statusText}`);
+  }
+  const json = await res.json() as { ok?: boolean; data?: StudioRegistryV2 } | StudioRegistryV2;
+  // REST API wraps response in { ok, data, meta } envelope
+  if ('data' in json && json.data) {
+    return json.data as StudioRegistryV2;
+  }
+  return json as StudioRegistryV2;
+}
+
+export function RegistryV2Provider({
+  children,
+  apiBaseUrl = '/api/v1',
+}: {
+  children: React.ReactNode;
+  apiBaseUrl?: string;
+}) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['studio-registry-v2', apiBaseUrl],
+    queryFn: () => fetchRegistryV2(apiBaseUrl, studioConfig.gatewayToken),
+    staleTime: 10_000,
+    gcTime: 60_000,
+    retry: 2,
+    retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10_000),
+  });
+
+  const federationInitialized = React.useRef(false);
+
+  // Initialize Module Federation once when registry is first loaded.
+  // Cache invalidation is handled lazily at navigation time via syncRemoteEntry()
+  // inside loadPageComponent — so the running page is never disrupted mid-session.
+  React.useEffect(() => {
+    if (data && data.plugins.length > 0 && !federationInitialized.current) {
+      initFederation(data.plugins);
+      federationInitialized.current = true;
+    }
+  }, [data]);
+
+  const value = React.useMemo<RegistryV2ContextValue>(
+    () => ({
+      registry: data ?? EMPTY_REGISTRY,
+      loading: isLoading,
+      error: error instanceof Error ? error : null,
+    }),
+    [data, isLoading, error],
+  );
+
+  return (
+    <RegistryV2Context.Provider value={value}>
+      {children}
+    </RegistryV2Context.Provider>
+  );
+}
+
+export function useRegistryV2(): RegistryV2ContextValue {
+  return React.useContext(RegistryV2Context);
+}

package/src/providers/settings-provider.tsx

@@ -0,0 +1,158 @@
+import * as React from 'react';
+import type { FeatureId } from '@/config/feature-flags';
+
+export interface NavigationCategory {
+  id: string;
+  label: string;
+  order: number;
+  itemKeys: string[];
+}
+
+export interface UserSettings {
+  appearance: {
+    theme: 'light' | 'dark' | 'auto';
+    compactMode: boolean;
+    fontSize: 'small' | 'medium' | 'large';
+    pageTransition: 'none' | 'fade' | 'slide';
+  };
+  experimental: {
+    /** User-enabled feature flags */
+    enabledFeatures: FeatureId[];
+  };
+  navigation: {
+    categories: NavigationCategory[];
+  };
+}
+
+const DEFAULT_SETTINGS: UserSettings = {
+  appearance: {
+    theme: 'light',
+    compactMode: false,
+    fontSize: 'medium',
+    pageTransition: 'none',
+  },
+  experimental: {
+    enabledFeatures: [],
+  },
+  navigation: {
+    categories: [],
+  },
+};
+
+interface SettingsContextValue {
+  settings: UserSettings;
+  updateSettings: (updates: Partial<UserSettings>) => void;
+  resetSettings: () => void;
+  exportSettings: () => void;
+  importSettings: (jsonString: string) => void;
+}
+
+const SettingsContext = React.createContext<SettingsContextValue | undefined>(undefined);
+
+const STORAGE_KEY = 'kb-studio-settings';
+
+export function SettingsProvider({ children }: { children: React.ReactNode }) {
+  const [settings, setSettings] = React.useState<UserSettings>(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        // Deep merge to ensure new fields are properly initialized
+        return {
+          appearance: { ...DEFAULT_SETTINGS.appearance, ...(parsed.appearance || {}) },
+          experimental: { ...DEFAULT_SETTINGS.experimental, ...(parsed.experimental || {}) },
+          navigation: { ...DEFAULT_SETTINGS.navigation, ...(parsed.navigation || {}) },
+        };
+      }
+    } catch (error) {
+      console.error('Failed to load settings:', error);
+    }
+    return DEFAULT_SETTINGS;
+  });
+
+  // Save to localStorage whenever settings change
+  React.useEffect(() => {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+    } catch (error) {
+      console.error('Failed to save settings:', error);
+    }
+  }, [settings]);
+
+  // Apply settings to document
+  React.useEffect(() => {
+    const { compactMode, fontSize } = settings.appearance;
+
+    // Apply compact mode class
+    if (compactMode) {
+      document.documentElement.classList.add('compact-mode');
+    } else {
+      document.documentElement.classList.remove('compact-mode');
+    }
+
+    // Apply font size class
+    document.documentElement.classList.remove('font-small', 'font-medium', 'font-large');
+    document.documentElement.classList.add(`font-${fontSize}`);
+  }, [settings]);
+
+  const updateSettings = React.useCallback((updates: Partial<UserSettings>) => {
+    setSettings((prev) => ({
+      ...prev,
+      ...updates,
+      appearance: {
+        ...prev.appearance,
+        ...(updates.appearance || {}),
+      },
+      experimental: {
+        ...prev.experimental,
+        ...(updates.experimental || {}),
+      },
+      navigation: {
+        ...prev.navigation,
+        ...(updates.navigation || {}),
+      },
+    }));
+  }, []);
+
+  const resetSettings = React.useCallback(() => {
+    setSettings(DEFAULT_SETTINGS);
+    localStorage.removeItem(STORAGE_KEY);
+  }, []);
+
+  const exportSettings = React.useCallback(() => {
+    const json = JSON.stringify(settings, null, 2);
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `kb-studio-settings-${new Date().toISOString().split('T')[0]}.json`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  }, [settings]);
+
+  const importSettings = React.useCallback((jsonString: string) => {
+    try {
+      const parsed = JSON.parse(jsonString);
+      setSettings({ ...DEFAULT_SETTINGS, ...parsed });
+    } catch {
+      throw new Error('Invalid settings file');
+    }
+  }, []);
+
+  const value = React.useMemo(
+    () => ({ settings, updateSettings, resetSettings, exportSettings, importSettings }),
+    [settings, updateSettings, resetSettings, exportSettings, importSettings]
+  );
+
+  return <SettingsContext.Provider value={value}>{children}</SettingsContext.Provider>;
+}
+
+export function useSettings() {
+  const context = React.useContext(SettingsContext);
+  if (!context) {
+    throw new Error('useSettings must be used within SettingsProvider');
+  }
+  return context;
+}

package/src/router.tsx

@@ -0,0 +1,302 @@
+import * as React from 'react';
+import { createBrowserRouter, Outlet, Link, useLocation, useNavigate } from 'react-router-dom';
+import { useAuth } from './providers/auth-provider';
+import { useRegistryV2 } from './providers/registry-v2-provider';
+import { CommandPaletteProvider, useCommandPalette } from './providers/command-palette-provider';
+import { useNotifications } from '@kb-labs/studio-data-client';
+import { useDataSources } from './providers/data-sources-provider';
+import { HealthBanner } from './components/health-banner';
+import { NotFoundPage } from './pages/not-found-page';
+import { LoginPage } from './pages/login-page';
+import { PluginPageV2 } from './routes/plugin-page-v2';
+import { PageTransition } from './components/page-transition';
+import { createStudioLogger } from './utils/logger';
+import { ErrorBoundary } from './components/error-boundary';
+import { useSettings } from './providers/settings-provider';
+import type { StudioRegistryV2 } from '@kb-labs/studio-federation';
+import { NavigationItemsProvider } from './providers/navigation-items-provider';
+import { applyNavigationCategories } from './utils/apply-navigation-categories';
+import { AVAILABLE_ICONS, KBPageLayout, KBStatusBar, type NavigationItem, StatusBarItem, StatusBarPresets } from '@/components/ui';
+
+// Module routes
+import { dashboardRoutes, dashboardNavigation } from './modules/dashboard/routes';
+// Workflow routes removed — now served via Module Federation from @kb-labs/workflow-cli studio plugin
+import { pluginsRoutes, pluginsNavigation } from './modules/plugins/routes';
+import { analyticsRoutes, analyticsNavigation } from './modules/analytics/routes';
+import { observabilityRoutes, observabilityNavigation } from './modules/observability/routes';
+import { settingsRoutes, settingsNavigation } from './modules/settings/routes';
+import { authRoutes } from './modules/auth/routes';
+
+type PluginNavRoute = {
+  key: string;
+  label: string;
+  path: string;
+  icon?: string;
+  order?: number;
+};
+
+type PluginNavModel = {
+  pluginId: string;
+  displayName: string;
+  icon?: string;
+  routes: PluginNavRoute[];
+};
+
+// Helper function to render icon from available icons registry
+function renderPluginIcon(iconName?: string): React.ReactElement | undefined {
+  if (!iconName) {return undefined;}
+
+  const IconComponent = AVAILABLE_ICONS[iconName];
+
+  if (!IconComponent) {
+    console.warn(`Icon "${iconName}" not available in registry`);
+    return undefined;
+  }
+
+  return React.createElement(IconComponent, { style: { fontSize: 16 } });
+}
+
+// System module navigation items (order matters)
+const systemNavigation: NavigationItem[] = [
+  dashboardNavigation,
+  pluginsNavigation,
+  analyticsNavigation,
+  observabilityNavigation,
+];
+
+function LayoutContent() {
+  const logger = React.useMemo(() => createStudioLogger('router'), []);
+
+  const auth = useAuth();
+  const location = useLocation();
+  const navigate = useNavigate();
+  const { registry, error } = useRegistryV2();
+  const commandPalette = useCommandPalette();
+  const sources = useDataSources();
+  const { settings } = useSettings();
+
+  // Notifications hook
+  const {
+    notifications,
+    unreadCount,
+    markAsRead,
+    markAllAsRead,
+    clearAll,
+    clearNotification,
+  } = useNotifications(sources.observability);
+
+  const handleLogout = React.useCallback(() => {
+    logger.info('User logout initiated');
+    localStorage.removeItem('studio-user-role');
+    navigate('/login');
+  }, [logger, navigate]);
+
+  const hasData = registry.plugins.length > 0;
+
+  // Build plugin nav from V2 registry menus
+  const pluginNavModel = React.useMemo<PluginNavModel[]>(() => {
+    if (!hasData) {return [];}
+    return buildPluginNavModel(registry);
+  }, [registry, hasData]);
+
+  // Build flat navigation items (system modules + plugins + settings)
+  const flatNavigationItems = React.useMemo<NavigationItem[]>(() => {
+    const items: NavigationItem[] = [...systemNavigation];
+
+    // Add plugin navigation items
+    for (const model of pluginNavModel) {
+      if (model.routes.length === 1) {
+        // Single page plugin — flat nav item (no submenu)
+        const route = model.routes[0]!;
+        items.push({
+          key: `plugin-${model.pluginId}`,
+          label: model.displayName,
+          icon: renderPluginIcon(model.icon),
+          path: route.path,
+        });
+      } else if (model.routes.length > 1) {
+        // Multi-page plugin — group with children
+        items.push({
+          key: `plugin-${model.pluginId}`,
+          label: model.displayName,
+          icon: renderPluginIcon(model.icon),
+          children: model.routes.map(route => ({
+            key: route.key,
+            label: route.label,
+            path: route.path,
+            icon: renderPluginIcon(route.icon),
+          })),
+        });
+      }
+    }
+
+    // Settings always at the bottom
+    items.push(settingsNavigation);
+
+    return items;
+  }, [pluginNavModel]);
+
+  // Available items for NavigationSettings UI (top-level items except settings)
+  const availableNavItems = React.useMemo(
+    () =>
+      flatNavigationItems
+        .filter(item => item.key !== 'settings')
+        .map(item => ({ key: item.key, label: item.label })),
+    [flatNavigationItems],
+  );
+
+  // Apply user's category configuration
+  const allNavigationItems = React.useMemo<NavigationItem[]>(
+    () => applyNavigationCategories(flatNavigationItems, settings.navigation.categories),
+    [flatNavigationItems, settings.navigation.categories],
+  );
+
+  React.useEffect(() => {
+    if (error) {
+      logger.error('Registry load failure in router', error);
+    }
+  }, [error, logger]);
+
+  return (
+    <NavigationItemsProvider items={availableNavItems}>
+      <KBPageLayout
+        headerProps={{
+          LinkComponent: Link as any,
+          onLogout: handleLogout,
+          userName: auth.role,
+          onSearchClick: () => commandPalette.open(),
+          // Notifications
+          notifications,
+          unreadNotificationsCount: unreadCount,
+          onMarkNotificationAsRead: markAsRead,
+          onMarkAllNotificationsAsRead: markAllAsRead,
+          onClearAllNotifications: clearAll,
+          onClearNotification: clearNotification,
+          onNotificationClick: (notification) => {
+            navigate(`/observability/logs/${notification.id}`);
+          },
+        }}
+        sidebarProps={{
+          items: allNavigationItems,
+          width: 240,
+          collapsedWidth: 80,
+          currentPath: location.pathname,
+          onNavigate: (path) => navigate(path),
+        }}
+        statusBar={
+          <KBStatusBar
+            leftItems={
+              <>
+                <StatusBarPresets.ApiConnection
+                  connected={hasData}
+                  onClick={() => navigate('/observability/system-events')}
+                />
+                {hasData && (
+                  <StatusBarItem
+                    label={`${registry.plugins.length} extension${registry.plugins.length === 1 ? '' : 's'}`}
+                    tooltip={`${registry.plugins.length} extensions registered`}
+                    status="success"
+                    onClick={() => navigate('/settings')}
+                    clickable
+                  />
+                )}
+              </>
+            }
+            rightItems={
+              <>
+                <StatusBarPresets.User email={auth.role} onClick={() => navigate('/settings')} />
+                <StatusBarPresets.Version version="0.1.0" />
+                <StatusBarPresets.Help onClick={() => window.open('https://github.com/kb-labs', '_blank')} />
+              </>
+            }
+          />
+        }
+      >
+        <HealthBanner />
+        <PageTransition>
+          <div style={{ paddingBottom: '20px' }}>
+            <Outlet />
+          </div>
+        </PageTransition>
+      </KBPageLayout>
+    </NavigationItemsProvider>
+  );
+}
+
+function Layout() {
+  return (
+    <CommandPaletteProvider>
+      <LayoutContent />
+    </CommandPaletteProvider>
+  );
+}
+
+export const router = createBrowserRouter([
+  {
+    path: '/login',
+    element: <LoginPage />,
+    errorElement: <ErrorBoundary />,
+  },
+  ...authRoutes,
+  {
+    element: <Layout />,
+    errorElement: <ErrorBoundary />,
+    children: [
+      ...dashboardRoutes,
+      ...pluginsRoutes,
+      ...analyticsRoutes,
+      ...observabilityRoutes,
+      ...settingsRoutes,
+      {
+        // V2 plugin pages (Module Federation remotes) — inside layout
+        path: '/p/*',
+        element: <PluginPageV2 />,
+        errorElement: <ErrorBoundary />,
+      },
+      {
+        path: '*',
+        element: <NotFoundPage />,
+      },
+    ],
+  },
+]);
+
+function buildPluginNavModel(registry: StudioRegistryV2): PluginNavModel[] {
+  const groups = new Map<string, PluginNavModel>();
+
+  for (const plugin of registry.plugins) {
+    if (!plugin.menus || plugin.menus.length === 0) {continue;}
+
+    const parentMenu = plugin.menus.find(m => !m.parentId);
+
+    if (!groups.has(plugin.pluginId)) {
+      groups.set(plugin.pluginId, {
+        pluginId: plugin.pluginId,
+        displayName: parentMenu?.label ?? plugin.displayName ?? plugin.pluginId,
+        icon: parentMenu?.icon,
+        routes: [],
+      });
+    }
+
+    const group = groups.get(plugin.pluginId)!;
+
+    for (const menu of plugin.menus) {
+      const targetPage = plugin.pages.find(p => p.id === menu.target);
+      const path = targetPage?.route ?? `/p/${menu.target}`;
+
+      group.routes.push({
+        key: menu.id,
+        label: menu.label,
+        path,
+        icon: menu.icon,
+        order: menu.order,
+      });
+    }
+  }
+
+  for (const group of groups.values()) {
+    group.routes.sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+  }
+
+  return Array.from(groups.values()).sort((a, b) => a.displayName.localeCompare(b.displayName));
+}

package/src/routes/helpers.tsx

@@ -0,0 +1,25 @@
+/**
+ * @module @kb-labs/studio-app/routes/helpers
+ * Common helpers for routing
+ */
+
+import * as React from 'react';
+import { AVAILABLE_ICONS } from '@/components/ui';
+
+/**
+ * Render icon from available icons registry
+ */
+export function renderIcon(iconName?: string): React.ReactElement | undefined {
+  if (!iconName) {
+    return undefined;
+  }
+
+  const IconComponent = AVAILABLE_ICONS[iconName];
+
+  if (!IconComponent) {
+    console.warn(`Icon "${iconName}" not available in registry`);
+    return undefined;
+  }
+
+  return React.createElement(IconComponent, { style: { fontSize: 16 } });
+}

package/src/routes/plugin-page-v2.tsx

@@ -0,0 +1,52 @@
+/**
+ * Dynamic plugin page resolver.
+ *
+ * Studio router mounts this component at /p/*. Plugin page routes are declared
+ * as absolute paths like /p/workflows/runs/:runId. We render them as a <Routes>
+ * tree with relative paths (stripping the /p/ prefix) so React Router resolves
+ * them correctly within the /p/* wildcard and sets useParams() for plugin pages.
+ */
+
+import * as React from 'react';
+import { Routes, Route } from 'react-router-dom';
+import { PageContainer } from '@kb-labs/studio-federation';
+import { useRegistryV2 } from '../providers/registry-v2-provider';
+import { NotFoundPage } from '../pages/not-found-page';
+
+const P_PREFIX = /^\/p\//;
+
+export function PluginPageV2() {
+  const { registry, loading } = useRegistryV2();
+
+  if (loading) {return null;}
+
+  const allPages = registry.plugins.flatMap((plugin) =>
+    plugin.pages.map((page) => ({ plugin, page })),
+  );
+
+  return (
+    <Routes>
+      {allPages.map(({ plugin, page }) => {
+        // Strip /p/ prefix → relative path for <Routes> inside /p/*
+        const relativePath = page.route.replace(P_PREFIX, '');
+        return (
+          <Route
+            key={`${plugin.remoteName}::${page.entry}`}
+            path={relativePath}
+            element={
+              <PageContainer
+                remoteName={plugin.remoteName}
+                entry={page.entry}
+                remoteEntryUrl={plugin.remoteEntryUrl}
+                pageId={page.id}
+                pluginId={plugin.pluginId}
+                permissions={page.permissions}
+              />
+            }
+          />
+        );
+      })}
+      <Route path="*" element={<NotFoundPage />} />
+    </Routes>
+  );
+}

package/src/routes/types.ts

@@ -0,0 +1,18 @@
+/**
+ * @module @kb-labs/studio-app/routes/types
+ * Common types for modular routing system
+ */
+
+import type { RouteObject } from 'react-router-dom';
+import type { NavigationItem } from '@/components/ui';
+
+/**
+ * Module routes configuration
+ * Each module exports this to register its routes
+ */
+export interface ModuleRoutes {
+  /** Routes for react-router */
+  routes: RouteObject[];
+  /** Navigation items for sidebar */
+  navigation?: NavigationItem[];
+}