@xemahq/ui-kernel

Host-agnostic UI kernel for the Xema frontend.

Overview

The host-framework-agnostic UI kernel every frontend biome composes against. It defines the system bus — the orchestration contract for capability invocation, cross-biome intents, the command palette, deeplinks, and window management — and the biome-host contract surface, including the frontend-biome and host-bridge shapes, the singleton biome registry, and session contributions. React is the shared component model, but the kernel carries no router, bundler, or host-specific wiring; concrete host adapters live in separate packages. The system bus is pure orchestration — it never authorizes; policy is enforced by the backend.

When to use it

• Use it to author a frontend biome against the shared host contracts and register it with the biome registry.
• Reach for the system bus to dispatch capability invocations, intents, or deeplinks across biomes.

Installation

pnpm add @xemahq/ui-kernel

Usage

Author a web biome with defineWebBiome — a declarative page list where each slug single-sources both the nav route and the route path, and each page declares its menu category (the host owns where that category renders):

import { defineWebBiome } from '@xemahq/ui-kernel';
import { Layers } from 'lucide-react';

export default defineWebBiome({
  id: 'spaces-web',
  displayName: 'Spaces',
  pages: [
    {
      slug: 'system/spaces',
      label: 'Spaces',
      icon: Layers,
      category: 'knowledge', // primary | build | operate | knowledge | admin | account
      load: () => import('./pages/SpacesPage'),
    },
  ],
});

The helper emits the nav item + route (wrapping the lazily-loaded page in a <Suspense> boundary) and passes through init/panels/session for bespoke biomes. Pass a per-page id to keep a short nav id distinct from the route slug, or navHidden: true to register a route with no nav item.

Lower-level building blocks are also exported:

import { buildSystemBus, biomeRegistry } from '@xemahq/ui-kernel';

const bus = buildSystemBus(hostPorts);

// Register a frontend biome so the host can render its contributions:
biomeRegistry.registerBiome(myBiome);

UI components

Build your pages with the shared design system from @xemahq/ui-kernel/ui so a third-party biome renders pixel-identical to a built-in one (they resolve against the host theme at render):

import {
  Button, Badge, Input, Select, Dialog, Card, Tabs, Table, // primitives
  PageShell, PageHeader, EmptyState, ErrorCard, StateCard, LoadingState, AsyncBoundary,
  StatusBadge, ScopeBadge, ConfirmDeleteDialog, FormStepper, AsyncCombobox,
  getStatusStyle, cn,
} from '@xemahq/ui-kernel/ui';

Host-service hooks (toast, error copy, URL-backed page state) come from the HostBridge — e.g. useMutationWithErrorToast, usePageState from @xemahq/ui-kernel — so biomes never import host internals directly.

Peer requirements

• react — the shared component model.
• @tanstack/react-query — async state for host data hooks.

License

Apache-2.0 © Xema — xema.dev