@checkstack/frontend-api 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @checkstack/frontend-api
 
+## 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]
+  - @checkstack/common@0.13.0
+  - @checkstack/signal-common@0.2.6
+
+## 0.6.0
+
+### Minor Changes
+
+- e2d6f25: feat(automation): connection picker for integration actions + restore Integrations menu
+
+  Connection-backed automation actions (Jira, Teams, Webex) now render a
+  working connection picker plus cascading provider dropdowns in the
+  visual editor, and the Integrations entry is back in the user menu.
+
+  **Contract.** `ActionDefinition` gained an optional
+  `connectionProviderId` (and it is surfaced on `ActionInfoSchema` and
+  mapped in the `listActions` router). It carries the integration
+  provider's fully-qualified id, derived from the provider plugin's own
+  `pluginMetadata.pluginId` (never a hardcoded string), so the editor
+  knows which provider backs an action's dropdowns and it matches the
+  `qualifiedId` the integration provider registry assigns.
+
+  **Providers.** Jira, Teams and Webex each export
+  `*_PROVIDER_LOCAL_ID` / `*_PROVIDER_QUALIFIED_ID`, register their
+  provider with the local id, and add a `CONNECTION_OPTIONS`
+  (`"connectionOptions"`) resolver name. Their `post_message` /
+  issue actions set `connectionProviderId` and expose `connectionId`
+  as an `x-options-resolver` dropdown instead of a hidden field.
+
+  **Frontend bridge.** A new `useConnectionOptionResolvers` hook
+  (`@checkstack/automation-frontend`, which now depends on
+  `@checkstack/integration-common`) turns an action's
+  `x-options-resolver` schema fields into live data: the
+  `connectionOptions` resolver lists the provider's connections via
+  `listConnections`, and every other resolver name is forwarded to
+  `getConnectionOptions` for the selected `connectionId`, passing the
+  live form values as `context` for dependent fields. `ProviderActionBody`
+  now passes this map to `DynamicForm` (it was previously missing
+  entirely, so connection-backed actions had no working dropdowns).
+
+  **frontend-api.** `usePluginClient` procedures now also expose a typed
+  imperative `.call(input)` alongside `.useQuery` / `.useMutation`, for
+  async callbacks that cannot host a hook (such as a `DynamicForm`
+  options resolver). Additive, non-breaking.
+
+  **Integrations menu.** Re-added `IntegrationMenuItem` and a new
+  `IntegrationsLandingPage`, wired into `integration-frontend` as a list
+  route and a `UserMenuItemsSlot` entry under the "Configuration" group.
+
+  **Action card polish.** The action editor's secondary metadata (id,
+  description, failure behaviour) is now grouped into one quiet settings
+  panel with consistent small uppercase "eyebrow" labels, so the action's
+  own configuration stays the focal point. The raw failure checkbox was
+  replaced with the standard `Checkbox` control, and the provider action
+  picker / configuration sections gained consistent section headers and a
+  divider. The per-step "type" dropdown was removed: an action's kind is
+  fixed at creation, so changing it now means adding a new step and
+  deleting the old one (avoids the surprising full-config reset that
+  switching kinds used to trigger).
+
+  **Add-step picker.** Adding a step now opens a Home-Assistant-style
+  dialog where the operator decides the step type up front: an "Actions"
+  tab lists the registered provider actions grouped by category
+  (searchable; picking one presets the step's `action`), and a "Blocks"
+  tab lists the structural building blocks (choose / parallel / repeat /
+  etc.). Because the concrete action is chosen here, the in-card action
+  switcher was removed - a step's action is fixed once created. Composite
+  blocks now start with an empty child list (filled via the nested
+  add-step picker) instead of seeding an unconfigurable empty action.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+  - @checkstack/common@0.12.0
+  - @checkstack/signal-common@0.2.5
+
 ## 0.5.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/frontend-api",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,23 +10,22 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "peerDependencies": {
-    "react": "^18.0.0"
+    "react": "^18.3.1"
   },
   "dependencies": {
-    "@checkstack/common": "0.10.0",
-    "@checkstack/signal-common": "0.2.3",
-    "@orpc/client": "^1.13.14",
-    "@orpc/contract": "^1.13.14",
-    "@orpc/react-query": "1.13.4",
-    "@orpc/tanstack-query": "^1.13.2",
-    "@tanstack/react-query": "^5.64.0"
+    "@checkstack/common": "0.12.0",
+    "@checkstack/signal-common": "0.2.5",
+    "@orpc/client": "^1.14.4",
+    "@orpc/contract": "^1.14.4",
+    "@orpc/tanstack-query": "^1.14.4",
+    "@tanstack/react-query": "^5.100.14"
   },
   "devDependencies": {
     "@types/bun": "^1.3.5",
     "@types/react": "^18.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2"
+    "@checkstack/scripts": "0.3.4"
   },
   "checkstack": {
     "type": "tooling"

package/src/components/ExtensionSlot.tsx

@@ -1,6 +1,47 @@
-import { pluginRegistry } from "../plugin-registry";
-import type { SlotContext } from "../plugin";
+import type { ComponentType } from "react";
+import type { Extension, SlotContext } from "../plugin";
 import type { SlotDefinition } from "../slots";
+import { useSlotExtensions } from "../use-slot-extensions";
+import { getLazyContribution } from "./LazyContribution";
+
+/**
+ * Render a single extension's UI, handling both contribution kinds: an eager
+ * `component` renders directly; a lazy `load` renders through
+ * {@link getLazyContribution} (code-split + Suspense + per-plugin error
+ * boundary). Use this when you drive rendering yourself from
+ * {@link useSlotExtensions} (e.g. a tab bar that renders only the active tab);
+ * for rendering ALL of a slot's extensions, use {@link ExtensionSlot}.
+ */
+export function ExtensionComponent<
+  TSlot extends SlotDefinition<unknown, unknown>
+>({
+  extension,
+  context,
+}: {
+  extension: Extension<TSlot>;
+  context?: SlotContext<TSlot>;
+}) {
+  // The slot's context was type-checked against this extension at registration
+  // time (createSlotExtension); it's erased to a props bag for rendering.
+  const props = (context ?? {}) as Record<string, unknown>;
+
+  if (extension.component) {
+    const Component = extension.component as ComponentType<
+      Record<string, unknown>
+    >;
+    return <Component {...props} />;
+  }
+  if (extension.load) {
+    const Lazy = getLazyContribution({
+      id: extension.id,
+      load: extension.load as () => Promise<{
+        default: ComponentType<Record<string, unknown>>;
+      }>,
+    });
+    return <Lazy {...props} />;
+  }
+  return null;
+}
 
 /**
  * Type-safe props for ExtensionSlot.
@@ -15,6 +56,12 @@ type ExtensionSlotProps<TSlot extends SlotDefinition<unknown, unknown>> =
 /**
  * Renders all extensions registered for the given slot.
  *
+ * Subscribes to the plugin registry (via {@link useSlotExtensions}), so
+ * extensions contributed by plugins loaded AT RUNTIME (installed remotely)
+ * appear without a manual refresh. Eager (`component`) extensions render
+ * directly; lazy (`load`) extensions render through {@link getLazyContribution}
+ * (code-split + Suspense + per-plugin error boundary).
+ *
  * @example
  * ```tsx
  * // Slot with context - context is required and type-checked
@@ -28,7 +75,7 @@ export function ExtensionSlot<TSlot extends SlotDefinition<unknown, unknown>>({
   slot,
   context,
 }: ExtensionSlotProps<TSlot>) {
-  const extensions = pluginRegistry.getExtensions(slot.id);
+  const extensions = useSlotExtensions(slot);
 
   if (extensions.length === 0) {
     return <></>;
@@ -36,10 +83,9 @@ export function ExtensionSlot<TSlot extends SlotDefinition<unknown, unknown>>({
 
   return (
     <>
-      {extensions.map((ext) => {
-        const Component = ext.component as React.ComponentType<Record<string, unknown>>;
-        return <Component key={ext.id} {...(context ?? {})} />;
-      })}
+      {extensions.map((ext) => (
+        <ExtensionComponent key={ext.id} extension={ext} context={context} />
+      ))}
     </>
   );
 }

package/src/components/LazyContribution.tsx

@@ -0,0 +1,104 @@
+import React, { Suspense, type ComponentType } from "react";
+
+/**
+ * Framework-owned wrapper for a lazily-loaded plugin contribution (a route page
+ * or a heavy slot extension declared via a `load` thunk).
+ *
+ * It does three things a plugin should NOT have to reimplement:
+ *  1. `React.lazy(load)` — code-splits the contribution so its chunk is fetched
+ *     on demand, not in the initial app load.
+ *  2. `<Suspense>` — shows a fallback while the chunk loads.
+ *  3. `<PluginErrorBoundary>` — contains a load/render failure to this one
+ *     contribution. A third-party plugin that throws (bad bundle, runtime
+ *     error) degrades to a small inline fallback instead of white-screening the
+ *     whole shell. This is essential once external plugins exist.
+ *
+ * Components are cached by a stable `id` so the same `React.lazy` instance is
+ * reused across renders (recreating it would discard its loaded state and
+ * remount on every parent render).
+ */
+
+interface PluginErrorBoundaryProps {
+  /** Human-readable contribution id, used in the console error + fallback. */
+  label: string;
+  fallback: React.ReactNode;
+  children: React.ReactNode;
+}
+
+interface PluginErrorBoundaryState {
+  hasError: boolean;
+}
+
+class PluginErrorBoundary extends React.Component<
+  PluginErrorBoundaryProps,
+  PluginErrorBoundaryState
+> {
+  state: PluginErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): PluginErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    console.error(
+      `❌ Plugin contribution "${this.props.label}" failed to load/render:`,
+      error,
+    );
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+    return this.props.children;
+  }
+}
+
+/** Props a plugin contribution component may receive (slot context, or none). */
+type ContributionProps = Record<string, unknown>;
+
+type LazyLoader = () => Promise<{ default: ComponentType<ContributionProps> }>;
+
+interface GetLazyContributionArgs {
+  /** Stable identity for caching (route path or extension id). */
+  id: string;
+  load: LazyLoader;
+  /** Shown while the chunk loads. Defaults to nothing (invisible). */
+  suspenseFallback?: React.ReactNode;
+  /** Shown if the chunk fails to load/render. Defaults to nothing. */
+  errorFallback?: React.ReactNode;
+}
+
+// Cache keyed by `id` so the lazy component (and its loaded state) is stable
+// across renders. Contributions have heterogeneous prop shapes, so the cache is
+// typed by the shared `ContributionProps` upper bound.
+const lazyComponentCache = new Map<string, ComponentType<ContributionProps>>();
+
+/**
+ * Return a stable component that lazily loads `load` and renders it inside a
+ * Suspense + error boundary. Safe to call on every render — memoised by `id`.
+ */
+export function getLazyContribution({
+  id,
+  load,
+  suspenseFallback = null,
+  errorFallback = null,
+}: GetLazyContributionArgs): ComponentType<ContributionProps> {
+  const cached = lazyComponentCache.get(id);
+  if (cached) {
+    return cached;
+  }
+
+  const Lazy = React.lazy(load);
+  const Wrapped: ComponentType<ContributionProps> = (props) => (
+    <PluginErrorBoundary label={id} fallback={errorFallback}>
+      <Suspense fallback={suspenseFallback}>
+        <Lazy {...props} />
+      </Suspense>
+    </PluginErrorBoundary>
+  );
+  Wrapped.displayName = `LazyContribution(${id})`;
+
+  lazyComponentCache.set(id, Wrapped);
+  return Wrapped;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./core-apis";
 export * from "./plugin";
 export * from "./plugin-registry";
 export * from "./components/ExtensionSlot";
+export * from "./components/LazyContribution";
 export * from "./use-slot-extensions";
 export * from "./utils";
 export * from "./slots";

package/src/orpc-query.tsx

@@ -3,7 +3,7 @@ import {
   createRouterUtils,
   type RouterUtils,
   type ProcedureUtils,
-} from "@orpc/react-query";
+} from "@orpc/tanstack-query";
 import type { NestedClient, ClientContext } from "@orpc/client";
 import {
   useQuery,
@@ -89,6 +89,12 @@ interface QueryProcedure<TInput, TOutput> {
     input?: TInput,
     options?: Omit<UseQueryOptions<TOutput, Error>, "queryKey" | "queryFn">,
   ) => UseQueryResult<TOutput, Error>;
+  /**
+   * Imperative one-shot call, outside React Query. Use inside async
+   * callbacks that can't host a hook (e.g. a DynamicForm options
+   * resolver). Prefer `useQuery` for anything rendered.
+   */
+  call: (input: TInput) => Promise<TOutput>;
 }
 
 /**
@@ -107,6 +113,12 @@ interface MutationProcedure<TInput, TOutput> {
       "mutationFn" | "mutationKey"
     >,
   ) => UseMutationResult<TOutput, Error, TInput, TContext>;
+  /**
+   * Imperative one-shot call, outside React Query. Use inside async
+   * callbacks that can't host a hook (e.g. a DynamicForm options
+   * resolver). Prefer `useMutation` for anything tied to UI lifecycle.
+   */
+  call: (input: TInput) => Promise<TOutput>;
 }
 
 /**
@@ -355,6 +367,7 @@ function createProcedureHook<TInput, TOutput>(
         const { onSuccess: _, ...restOptions } = options ?? {};
         return useMutation({ ...mutationOpts, ...restOptions });
       },
+      call: (input) => proc.call(input),
     };
   }
 
@@ -367,5 +380,6 @@ function createProcedureHook<TInput, TOutput>(
       // Spread caller options AFTER to ensure they take precedence (e.g., enabled: false)
       return useQuery({ ...queryOpts, ...options });
     },
+    call: (input) => proc.call(input),
   };
 }

package/src/plugin-registry.ts

@@ -1,5 +1,9 @@
+import type { ComponentType, ReactNode } from "react";
 import { FrontendPlugin, Extension } from "./plugin";
 
+/** Lazy page loader, as declared on a {@link PluginRoute}. */
+type RouteLoader = () => Promise<{ default: ComponentType }>;
+
 /**
  * Listener function for registry changes
  */
@@ -12,13 +16,20 @@ interface ResolvedRoute {
   id: string;
   path: string;
   pluginId: string;
-  element?: React.ReactNode;
+  /** Exactly one of `load` (lazy) / `element` (eager) is set. */
+  load?: RouteLoader;
+  element?: ReactNode;
   title?: string;
   accessRule?: string;
 }
 
 class PluginRegistry {
   private plugins: FrontendPlugin[] = [];
+  // Immutable snapshot of `plugins`, rebuilt on every change. `getPlugins()`
+  // returns this so callers (and `useSyncExternalStore`) get a referentially
+  // stable value between changes and a NEW reference when the set changes —
+  // `plugins` itself is mutated in place, so its reference never changes.
+  private pluginsSnapshot: readonly FrontendPlugin[] = [];
   private extensions = new Map<string, Extension[]>();
   private routeMap = new Map<string, ResolvedRoute>();
 
@@ -59,6 +70,7 @@ class PluginRegistry {
         id: route.route.id,
         path: fullPath,
         pluginId: route.route.pluginId,
+        load: route.load,
         element: route.element,
         title: route.title,
         accessRule: route.accessRule?.id,
@@ -151,8 +163,8 @@ class PluginRegistry {
     return this.plugins.some((p) => p.metadata.pluginId === pluginId);
   }
 
-  getPlugins() {
-    return this.plugins;
+  getPlugins(): readonly FrontendPlugin[] {
+    return this.pluginsSnapshot;
   }
 
   getExtensions(slotId: string): Extension[] {
@@ -173,9 +185,23 @@ class PluginRegistry {
 
         return {
           path: fullPath,
+          pluginId: route.route.pluginId,
+          load: route.load,
           element: route.element,
           title: route.title,
           accessRule: route.accessRule?.id,
+          // Resolved sidebar entry (defaults applied) for routes that opt in.
+          // `accessRule` here is the EFFECTIVE rule object (nav override, else
+          // the route's own rule) the sidebar gates visibility on.
+          nav: route.nav
+            ? {
+                group: route.nav.group,
+                icon: route.nav.icon,
+                label: route.nav.label ?? route.title ?? route.route.id,
+                order: route.nav.order ?? 0,
+                accessRule: route.nav.accessRule ?? route.accessRule,
+              }
+            : undefined,
         };
       });
     });
@@ -229,6 +255,9 @@ class PluginRegistry {
 
   private incrementVersion() {
     this.version++;
+    // Rebuild the immutable snapshot so external subscribers see a new
+    // reference (required for useSyncExternalStore / useMemo to recompute).
+    this.pluginsSnapshot = [...this.plugins];
     for (const listener of this.listeners) {
       listener();
     }

package/src/plugin.ts

@@ -41,26 +41,47 @@ export interface Extension<
 > {
   id: string;
   slot: TSlot;
-  component: React.ComponentType<SlotContext<TSlot>>;
+  /**
+   * Eager component. Use for LIGHT, always-rendered contributions (navbar,
+   * user-menu items) where code-splitting would just add a load flash. Exactly
+   * one of `component` / `load` is set.
+   */
+  component?: React.ComponentType<SlotContext<TSlot>>;
+  /**
+   * Lazy loader for HEAVY or page-scoped contributions. The framework wraps it
+   * in React.lazy + Suspense + a per-plugin error boundary (see
+   * `getLazyContribution`), so the chunk loads on demand and a failure is
+   * contained to this contribution. Named exports: `() => import("./X").then(
+   * (m) => ({ default: m.X }))`.
+   */
+  load?: () => Promise<{
+    default: React.ComponentType<SlotContext<TSlot>>;
+  }>;
   metadata?: SlotMetadata<TSlot>;
 }
 
+/** A contribution is provided either eagerly (`component`) or lazily (`load`). */
+type SlotExtensionImpl<TSlot extends SlotDefinition<unknown, unknown>> =
+  | {
+      component: React.ComponentType<SlotContext<TSlot>>;
+      load?: never;
+    }
+  | {
+      load: () => Promise<{
+        default: React.ComponentType<SlotContext<TSlot>>;
+      }>;
+      component?: never;
+    };
+
 /**
  * Input shape for `createSlotExtension`. Requires `metadata` when the slot
- * declares a non-`undefined` metadata type, forbids it otherwise.
+ * declares a non-`undefined` metadata type, forbids it otherwise, and requires
+ * exactly one of `component` (eager) / `load` (lazy).
  */
 type SlotExtensionInput<TSlot extends SlotDefinition<unknown, unknown>> =
   SlotMetadata<TSlot> extends undefined
-    ? {
-        id: string;
-        component: React.ComponentType<SlotContext<TSlot>>;
-        metadata?: undefined;
-      }
-    : {
-        id: string;
-        component: React.ComponentType<SlotContext<TSlot>>;
-        metadata: SlotMetadata<TSlot>;
-      };
+    ? { id: string; metadata?: undefined } & SlotExtensionImpl<TSlot>
+    : { id: string; metadata: SlotMetadata<TSlot> } & SlotExtensionImpl<TSlot>;
 
 /**
  * Helper to create a type-safe extension from a slot definition.
@@ -81,20 +102,57 @@ export function createSlotExtension<
  * Route configuration for a frontend plugin.
  * Uses RouteDefinition from the plugin's common package.
  */
-export interface PluginRoute {
+/**
+ * Sidebar navigation metadata. A route opts into the left sidebar by setting
+ * `nav` on its registration; routes without `nav` are reachable (deep links,
+ * detail pages) but are not listed in the sidebar.
+ */
+export interface NavEntry {
+  /** Sidebar section heading, e.g. "Workspace" / "Reliability" / "Configuration". */
+  group: string;
+  /** Icon component for the entry (lucide-react icons satisfy this shape). */
+  icon: React.ComponentType<{ className?: string }>;
+  /** Sidebar label; defaults to the route's `title`. */
+  label?: string;
+  /** Sort order within the group (lower first; defaults to 0). */
+  order?: number;
+  /**
+   * Access rule gating sidebar VISIBILITY. Defaults to the route's `accessRule`.
+   * Override to surface the entry on a broader rule than the page requires
+   * (e.g. show on `read` while the page itself needs `manage`).
+   */
+  accessRule?: AccessRule;
+}
+
+/** Fields common to every route, regardless of eager/lazy. */
+interface PluginRouteBase {
   /** Route definition from common package */
   route: RouteDefinition;
-
-  /** React element to render */
-  element?: React.ReactNode;
-
   /** Page title */
   title?: string;
-
   /** Access rule required to access this route (use access object from common package) */
   accessRule?: AccessRule;
+  /** Optional sidebar navigation entry for this route. */
+  nav?: NavEntry;
 }
 
+/**
+ * Route configuration for a frontend plugin. Provide EXACTLY one of:
+ *  - `load` (default): a lazy page loader. The framework code-splits the page
+ *    and wraps it in Suspense + a per-plugin error boundary (see
+ *    `getLazyContribution`), so the chunk is fetched on navigation, never in
+ *    the initial load. Named-export pages: `() => import("./pages/Foo").then(
+ *    (m) => ({ default: m.Foo }))`.
+ *  - `element`: an eagerly-rendered element. Reserve for the rare page that
+ *    must paint without a chunk fetch (e.g. the login page on the
+ *    unauthenticated critical path).
+ */
+export type PluginRoute = PluginRouteBase &
+  (
+    | { load: () => Promise<{ default: React.ComponentType }>; element?: never }
+    | { element: React.ReactNode; load?: never }
+  );
+
 /**
  * Frontend plugin configuration.
  * Uses PluginMetadata from the common package for consistent plugin identification.