@xemahq/ui-kernel 0.1.4

package/src/lib/biome-host/composition-validation.ts

@@ -0,0 +1,215 @@
+/**
+ * Lightweight cross-biome composition validation.
+ *
+ * After the host bootstrap registers every enabled web biome, the merged
+ * surface must be internally consistent: no two biomes may claim the same
+ * route, no two may claim the same nav id, and every panel must target a
+ * slot the composition can actually render. The runtime tolerates a lot of
+ * this silently (the nav merge last-writer-wins on a duplicate id; a panel
+ * pointing at a non-existent slot simply never renders), which is exactly
+ * the kind of hidden degradation the platform forbids — so we surface it.
+ *
+ * This module is the PURE validator: it takes the registered biomes plus
+ * the set of host-defined slot ids and returns structured diagnostics. It
+ * is host-framework-agnostic and knows nothing about `HostExtensionSlots`
+ * (that catalog lives in `biome-registry-web`, which passes it in). It does
+ * NOT throw and it does NOT log — callers decide the policy (the host
+ * bootstrap fail-fasts on `Error`-severity diagnostics and surfaces
+ * `Warning`-severity ones). This is deliberately NOT a permission matrix:
+ * it validates structural composition only, never authorization.
+ */
+
+import type { FrontendBiome } from './frontend-biome';
+
+/** Closed set — how serious a composition diagnostic is. */
+export enum CompositionDiagnosticSeverity {
+  /**
+   * A genuine composition bug that makes the merged surface ambiguous
+   * (two routes/nav ids collide). Deterministic and author-fixable; the
+   * host fail-fasts so it is caught in dev/CI, never silently shipped.
+   */
+  Error = 'error',
+  /**
+   * A probable mistake that the runtime tolerates (a panel targeting an
+   * unknown or not-yet-loaded slot). Non-fatal because it can also be a
+   * legitimate cross-deployment state (host shell older than the biome,
+   * or the slot-owning biome disabled for this org).
+   */
+  Warning = 'warning',
+}
+
+/** Closed set — the kind of composition problem detected. */
+export enum CompositionDiagnosticCode {
+  /** Two biomes contribute a route with the same `(path, projectScoped)`. */
+  DuplicateRoutePath = 'duplicate_route_path',
+  /** Two biomes contribute a nav item with the same `id`. */
+  DuplicateNavId = 'duplicate_nav_id',
+  /**
+   * A panel targets a slot that is neither a known host slot nor a
+   * well-formed `<owner>/<name>` biome-owned slot — almost always a typo.
+   */
+  UnknownSlot = 'unknown_slot',
+  /**
+   * A panel targets a biome-owned slot (`<owner>/<name>`) whose owning
+   * biome is not registered, so the panel can never render.
+   */
+  OrphanedPanelSlot = 'orphaned_panel_slot',
+}
+
+export interface CompositionDiagnostic {
+  readonly code: CompositionDiagnosticCode;
+  readonly severity: CompositionDiagnosticSeverity;
+  /** The biome id(s) implicated, for actionable reporting. */
+  readonly biomeIds: readonly string[];
+  /** Human-readable, actionable description. */
+  readonly message: string;
+}
+
+export interface ValidateBiomeCompositionOptions {
+  /**
+   * Host-defined slot ids the shell renders (the `HostExtensionSlots`
+   * values). A panel slot that is neither one of these nor a well-formed
+   * `<owner>/<name>` biome-owned slot is flagged as `UnknownSlot`.
+   */
+  readonly knownSlots: ReadonlySet<string>;
+}
+
+/**
+ * Biome-owned slots are namespaced `<owner>/<name>` where `owner` is the
+ * id of the biome that publishes the slot. Exactly one `/`, both segments
+ * non-empty. Returns the owner id, or `null` if the slot is not a
+ * well-formed biome-owned slot.
+ */
+function biomeOwnedSlotOwner(slot: string): string | null {
+  const slashIndex = slot.indexOf('/');
+  if (slashIndex <= 0) return null; // no slash, or leading slash (empty owner)
+  if (slot.indexOf('/', slashIndex + 1) !== -1) return null; // more than one slash
+  const owner = slot.slice(0, slashIndex);
+  const name = slot.slice(slashIndex + 1);
+  if (owner.length === 0 || name.length === 0) return null;
+  return owner;
+}
+
+/**
+ * Validate the merged composition of every registered biome. Pure: returns
+ * diagnostics, never throws, never logs. Diagnostics are returned in a
+ * deterministic order (by code, then by the offending key) so callers and
+ * tests see stable output.
+ */
+export function validateBiomeComposition(
+  biomes: readonly FrontendBiome[],
+  options: ValidateBiomeCompositionOptions,
+): readonly CompositionDiagnostic[] {
+  const diagnostics: CompositionDiagnostic[] = [];
+  const biomeIds = new Set(biomes.map((b) => b.id));
+
+  // ── Duplicate route paths ────────────────────────────────────────────
+  // Routes collide only within the same scope: a project-scoped `/x`
+  // mounts under `/projects/:projectId/x`, an org-scoped `/x` under `/x`,
+  // so they never clash. Key on `(scope, path)`.
+  const routeOwners = new Map<string, string[]>();
+  for (const biome of biomes) {
+    for (const route of biome.routes ?? []) {
+      const scope = route.projectScoped ? 'project' : 'root';
+      const key = `${scope}:${route.path}`;
+      const owners = routeOwners.get(key);
+      if (owners) owners.push(biome.id);
+      else routeOwners.set(key, [biome.id]);
+    }
+  }
+  for (const [key, owners] of routeOwners) {
+    if (owners.length < 2) continue;
+    const [scope, path] = splitFirst(key, ':');
+    diagnostics.push({
+      code: CompositionDiagnosticCode.DuplicateRoutePath,
+      severity: CompositionDiagnosticSeverity.Error,
+      biomeIds: owners,
+      message:
+        `Route path '${path}' (${scope}-scoped) is contributed by multiple biomes: ` +
+        `${owners.join(', ')}. Each route must be unique within its scope — ` +
+        `only one would mount and the others would be unreachable.`,
+    });
+  }
+
+  // ── Duplicate nav ids ────────────────────────────────────────────────
+  // The nav merge keys on `navItem.id`; a duplicate id makes one item
+  // silently overwrite the other in the feature-route map and collide as a
+  // React key in the rendered list.
+  const navOwners = new Map<string, string[]>();
+  for (const biome of biomes) {
+    for (const navItem of biome.navItems ?? []) {
+      const owners = navOwners.get(navItem.id);
+      if (owners) owners.push(biome.id);
+      else navOwners.set(navItem.id, [biome.id]);
+    }
+  }
+  for (const [navId, owners] of navOwners) {
+    if (owners.length < 2) continue;
+    diagnostics.push({
+      code: CompositionDiagnosticCode.DuplicateNavId,
+      severity: CompositionDiagnosticSeverity.Error,
+      biomeIds: owners,
+      message:
+        `Nav id '${navId}' is contributed by multiple biomes: ${owners.join(', ')}. ` +
+        `Nav ids must be unique — a duplicate silently overwrites the ` +
+        `feature-route mapping and collides as a render key.`,
+    });
+  }
+
+  // ── Panel slots: known-slot + dependency-closure ─────────────────────
+  for (const biome of biomes) {
+    for (const panel of biome.panels ?? []) {
+      if (options.knownSlots.has(panel.slot)) continue;
+      const owner = biomeOwnedSlotOwner(panel.slot);
+      if (owner === null) {
+        diagnostics.push({
+          code: CompositionDiagnosticCode.UnknownSlot,
+          severity: CompositionDiagnosticSeverity.Warning,
+          biomeIds: [biome.id],
+          message:
+            `Biome '${biome.id}' panel '${panel.id}' targets slot '${panel.slot}', ` +
+            `which is neither a known host slot nor a well-formed ` +
+            `'<owner>/<name>' biome-owned slot. It will never render — ` +
+            `check for a typo against the host slot catalog.`,
+        });
+        continue;
+      }
+      // Well-formed biome-owned slot — its owner must be registered for the
+      // panel to ever render (dependency-closure sanity). A biome may own
+      // its own slot, which is always satisfied.
+      if (!biomeIds.has(owner)) {
+        diagnostics.push({
+          code: CompositionDiagnosticCode.OrphanedPanelSlot,
+          severity: CompositionDiagnosticSeverity.Warning,
+          biomeIds: [biome.id],
+          message:
+            `Biome '${biome.id}' panel '${panel.id}' targets biome-owned slot ` +
+            `'${panel.slot}', but its owner biome '${owner}' is not registered. ` +
+            `The panel will never render until '${owner}' is enabled.`,
+        });
+      }
+    }
+  }
+
+  return sortDiagnostics(diagnostics);
+}
+
+/** Split on the first occurrence of `sep` into a `[head, tail]` pair. */
+function splitFirst(value: string, sep: string): [string, string] {
+  const idx = value.indexOf(sep);
+  if (idx === -1) return [value, ''];
+  return [value.slice(0, idx), value.slice(idx + sep.length)];
+}
+
+/** Stable ordering: by code, then by the joined biome ids, then message. */
+function sortDiagnostics(
+  diagnostics: CompositionDiagnostic[],
+): CompositionDiagnostic[] {
+  return diagnostics.slice().sort((a, b) => {
+    if (a.code !== b.code) return a.code.localeCompare(b.code);
+    const ai = a.biomeIds.join(',');
+    const bi = b.biomeIds.join(',');
+    if (ai !== bi) return ai.localeCompare(bi);
+    return a.message.localeCompare(b.message);
+  });
+}

package/src/lib/biome-host/frontend-biome.ts

@@ -0,0 +1,162 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { HostBridge } from './host-bridge';
+import type { SessionContributions } from './session-contributions';
+
+/**
+ * Runtime contribution types a `target: 'web'` biome composes. Web
+ * biomes default-export a `FrontendBiomeFactory` from their package
+ * (the import specifier is `xema-biome.json#name`); the SPA's
+ * auto-generated `xema:web-biome-loaders` virtual module imports each
+ * factory at bootstrap, calls it with the host's `HostBridge`, and
+ * registers the resulting `FrontendBiome` into the singleton
+ * `biomeRegistry`.
+ */
+
+export interface NavItemContribution {
+  /** Stable id used for active-state matching + analytics. */
+  readonly id: string;
+  /** Displayed label. */
+  readonly label: string;
+  /** Route path the nav item links to. */
+  readonly route: string;
+  /**
+   * Optional icon component. Typed with `className: string | undefined` so
+   * any host icon kit whose props include `className` (lucide-react,
+   * heroicons, custom SVG components) is assignable under
+   * `exactOptionalPropertyTypes: true`. The host renders with whatever
+   * className it computes from its own theme.
+   */
+  readonly icon?: ComponentType<{ className?: string | undefined }>;
+  /** Section grouping key (matches host nav-registry sections). */
+  readonly section?: string;
+  /** Sort weight within the section (lower first). Defaults to 100. */
+  readonly weight?: number;
+}
+
+export interface RouteContribution {
+  /** React-router path. May include params. */
+  readonly path: string;
+  /** Element factory — host calls it inside the route tree. */
+  readonly element: () => ReactNode;
+  /** Whether the route is project-scoped (mounted under /projects/:projectId). */
+  readonly projectScoped?: boolean;
+}
+
+/**
+ * Slot fillers — biomes contribute UI fragments rendered by named
+ * `<BiomeSlot name="…">` boundaries placed in the host app shell.
+ * Initial slots: 'org-header-actions', 'project-overview-cards',
+ * 'run-detail-side-panel', 'settings-tabs', 'session-actions'.
+ */
+export interface PanelContribution {
+  /** Slot name the contribution renders into. */
+  readonly slot: string;
+  /** Stable id for ordering + replacement. */
+  readonly id: string;
+  /** React node factory — host calls it inside the slot. */
+  readonly render: () => ReactNode;
+  /** Sort weight within the slot (lower first). Defaults to 100. */
+  readonly weight?: number;
+}
+
+/**
+ * Lifecycle context passed to `FrontendBiome.init`. The host invokes
+ * `init()` exactly once after the biome's factory returns and before
+ * any session contribution is read. Biomes use it to wire any
+ * imperative one-time work (Orval client setup, feature-flag registration,
+ * background-cache prefetch) — declarative contributions go on the
+ * `FrontendBiome` itself, not here.
+ */
+export interface BiomeInitContext {
+  readonly bridge: HostBridge;
+  /** Biome id, mirrored from `FrontendBiome.id` for convenience. */
+  readonly biomeId: string;
+}
+
+export interface FrontendBiome {
+  /** Stable biome id; matches xema-biome.json `xema.id`. */
+  readonly id: string;
+  /** Displayed name. */
+  readonly displayName: string;
+  /**
+   * One-shot initializer invoked after registration. Used for imperative
+   * setup that doesn't fit a declarative contribution (e.g. seeding a
+   * shared cache, mounting a side-effect listener). Idempotent: the
+   * registry guarantees `init()` runs at most once per biome per SPA
+   * session, even across HMR reloads.
+   */
+  readonly init?: (ctx: BiomeInitContext) => void | Promise<void>;
+  /**
+   * Optional teardown counterpart to `init()`. Invoked when the biome
+   * is explicitly unregistered (admin disable flow). Biomes MUST NOT
+   * rely on `dispose()` running on tab close — browsers don't guarantee
+   * it. Use it for live-subscription cleanup, not for persistence.
+   */
+  readonly dispose?: () => void | Promise<void>;
+  readonly navItems?: readonly NavItemContribution[];
+  readonly routes?: readonly RouteContribution[];
+  readonly panels?: readonly PanelContribution[];
+  /**
+   * Declarative contributions to the agent-session shell. See
+   * `session-contributions.ts` for the full taxonomy. Each contribution
+   * is a small data object; the host's session components read them
+   * through typed selector hooks and render the matching primitives.
+   */
+  readonly session?: SessionContributions;
+  /**
+   * Output renderer contributions. Each entry binds a biome-defined
+   * artifact `OutputKind` (e.g. `catalog_entity_info`) to the React
+   * component that renders it inside `<OutputCard>`. The host's renderer
+   * registry overlays biome contributions on top of the built-in set —
+   * built-in kinds (`markdown_doc`, `json_payload`, …) cannot be
+   * overridden, but new kinds light up the moment the biome's frontend
+   * loads.
+   *
+   * See `packages/output-contracts` for the `OutputKind` taxonomy and
+   * `submodules/xema-host-web/src/components/outputs/renderer-registry.tsx`
+   * for the resolver. Biome renderers receive the same `OutputItem`
+   * shape as built-ins.
+   */
+  readonly outputRenderers?: readonly OutputRendererContribution[];
+}
+
+/**
+ * One biome → one renderer for a biome-defined `OutputKind`. The
+ * `outputKind` string MUST be unique across all biomes; the renderer
+ * registry refuses to register a duplicate at bootstrap (fail-fast,
+ * surfaced in the dev console + biome admin UI).
+ *
+ * The `render` factory mirrors `RouteContribution.element` /
+ * `PanelContribution.render` — typed as a thunk so the host can defer
+ * import-cost until the renderer actually fires.
+ */
+export interface OutputRendererContribution {
+  /**
+   * The artifact `OutputKind` this renderer handles. Free-form string
+   * because biome-defined kinds are not in the built-in enum; the
+   * registry validates it doesn't collide with a built-in kind at
+   * registration time.
+   */
+  readonly outputKind: string;
+  /**
+   * React component that renders the artifact body inside `<OutputCard>`.
+   * Receives the resolved `OutputItem` as a prop. Biomes import the
+   * `OutputRendererProps` type from
+   * `submodules/xema-host-web/src/components/outputs/renderer-registry.tsx`
+   * (re-exported through the host's biome SDK barrel).
+   */
+  readonly render: () => ComponentType<{ readonly output: unknown }>;
+}
+
+/**
+ * Biome module export contract. Each biome's entry module exports a
+ * default function of this shape; the host bootstrap calls it with its
+ * concrete `HostBridge` implementation, then registers the returned
+ * `FrontendBiome` with `biomeRegistry`.
+ *
+ * This factory shape keeps biome code free of any direct dependency
+ * on host-shell primitives (router, auth client, toast library), which
+ * is what allows the same biome package to load into a Vite SPA host
+ * today and a Next.js host tomorrow.
+ */
+export type FrontendBiomeFactory = (bridge: HostBridge) => FrontendBiome;

package/src/lib/biome-host/host-bridge.ts

@@ -0,0 +1,178 @@
+import type { QueryClient } from '@tanstack/react-query';
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+import type { SystemBus } from '../system-bus';
+
+/**
+ * `HostBridge` is the host-agnostic abstraction every frontend biome
+ * receives at registration time. It decouples biome code from any
+ * particular React shell (Vite SPA today, Next.js tomorrow) and from
+ * any particular auth / toast / router primitive.
+ *
+ * Each concrete host (e.g. `submodules/xema-host-web`) implements this
+ * interface once, against its router (`react-router-dom`), its auth
+ * client (`keycloak-js`), its toast library (`sonner`), its `QueryClient`,
+ * and its request-context store. Biome code is identical across hosts.
+ */
+export interface HostBridgeNavigation {
+  /** Push a new entry on the navigation stack. */
+  push(path: string): void;
+  /** Replace the current entry. */
+  replace(path: string): void;
+  /**
+   * Hook returning the current location. Must be a stable React hook
+   * implemented by the host (e.g. `react-router-dom`'s `useLocation`).
+   */
+  useLocation(): HostLocation;
+  /**
+   * Hook returning the params bound by the host's route matcher for the
+   * currently-rendered biome route (the `:param` segments declared on the
+   * biome's `RouteContribution.path`, plus `projectId` for project-scoped
+   * routes). Must be a stable React hook implemented by the host against
+   * its router (`react-router-dom`'s `useParams`, the App Router's
+   * matcher-bound params context, …).
+   *
+   * Biomes call this INSTEAD of importing a router primitive directly, so
+   * biome code stays decoupled from any particular host shell — the same
+   * decoupling `useLocation` / `push` / `replace` already provide. Values
+   * are `string | undefined` because a param is absent until the route that
+   * declares it is the matched route.
+   */
+  useRouteParams<
+    T extends Record<string, string | undefined> = Record<string, string | undefined>,
+  >(): T;
+}
+
+export interface HostLocation {
+  readonly pathname: string;
+  readonly search: string;
+}
+
+export interface HostBridgeAuth {
+  /** Returns the current actor's bearer token, or null if unauthenticated. */
+  getActorToken(): string | null;
+  /** Returns the current actor's organization id, or null if not selected. */
+  getOrgId(): string | null;
+  /** Returns the current actor's project id, or null if not selected. */
+  getProjectId(): string | null;
+  /** Returns the current actor's user id (subject), or null. */
+  getUserId(): string | null;
+}
+
+export interface HostBridgeToast {
+  /**
+   * Success toast. `detail` is an optional secondary line (rendered as the
+   * toast description) — use it to echo what succeeded (e.g. the deeplink
+   * that was copied) or to carry a load-bearing consequence note. Mirrors
+   * {@link HostBridgeToast.error}'s two-arg shape.
+   */
+  success(message: string, detail?: string): void;
+  error(message: string, detail?: string): void;
+  /** Info toast with an optional secondary description line. */
+  info(message: string, detail?: string): void;
+}
+
+export interface HostBridgeRequestContext {
+  readonly correlationId: string;
+}
+
+/**
+ * Where the topbar's leading back-button takes you. Pages that have a
+ * meaningful "parent context" register this; pages without one omit it
+ * and no back button is shown. `to` is an internal route; `label` is a
+ * screen-reader label (the button itself is icon-only).
+ */
+export interface PageBackTarget {
+  readonly to: string;
+  /** Screen-reader label. Defaults to "Back". */
+  readonly label?: string;
+}
+
+/**
+ * Page chrome registered by a page into the host's topbar store. The host
+ * `AppTopbar` renders the active meta as the single page-chrome bar. This
+ * is the host-agnostic mirror of the host's page-meta store payload —
+ * biomes register through {@link HostBridgePageMeta.usePageMeta} so the
+ * meta reaches the host topbar across a Module-Federation boundary (the
+ * bridge is a shared singleton; a remotely-bundled module store is not).
+ */
+export interface PageMeta {
+  /** Short title rendered in the topbar. e.g. "Sessions", "Documents". */
+  readonly title: string;
+  /** Optional eyebrow rendered before the title (small mono caption). */
+  readonly eyebrow?: string;
+  /** Long-form description shown inside the info popover. */
+  readonly description?: string;
+  /** Optional bullet list of "what you can do here" shown in the info popover. */
+  readonly actions?: readonly string[];
+  /** Leftmost back affordance, rendered as an icon-only button. */
+  readonly backTo?: PageBackTarget;
+  /** Right-aligned action cluster rendered in the topbar (1-3 small buttons). */
+  readonly topbarActions?: ReactNode;
+  /** Short secondary line rendered inline with the title in the topbar. */
+  readonly topbarMeta?: ReactNode;
+}
+
+/**
+ * The page-meta surface — how a biome page drives the host topbar's title,
+ * description, help-actions, back affordance, and action cluster.
+ *
+ * Exposed as a hook (mirroring `navigation.useLocation` / `useRouteParams`)
+ * because registration is lifecycle-bound: the host pushes the meta on mount
+ * and pops it on unmount, restoring the outer page's meta. Biomes call this
+ * INSTEAD of importing the host's page-meta module directly, so the page
+ * component bundles cleanly into an MF remote and still updates the one
+ * host-owned store via the shared bridge singleton.
+ */
+export interface HostBridgePageMeta {
+  /**
+   * Register the current page's meta with the host topbar. Stable React hook
+   * implemented by the host against its page-meta store. Call it from a stable
+   * place at the top of the page component.
+   */
+  usePageMeta(meta: PageMeta): void;
+}
+
+export interface HostBridge {
+  readonly navigation: HostBridgeNavigation;
+  readonly auth: HostBridgeAuth;
+  readonly toast: HostBridgeToast;
+  readonly queryClient: QueryClient;
+  readonly requestContext: HostBridgeRequestContext;
+  /**
+   * Page chrome surface — how a biome page drives the host topbar (title,
+   * description, help-actions, back, action cluster). Backed by the host's
+   * single page-meta store so the topbar is the one source of truth, while
+   * pages stay portable into MF remotes (no module-singleton import).
+   */
+  readonly pageMeta: HostBridgePageMeta;
+  /**
+   * The OS-orchestration plane — capability invocation, cross-biome
+   * intents, command palette, `xema://` deeplinks, and windowing. Every
+   * frontend biome reaches the platform's orchestration surface through
+   * here. Pure orchestration: the SystemBus NEVER authorizes — the
+   * backend capability-router is the single authority on auth / tenancy /
+   * policy / audit (see {@link SystemBus}).
+   */
+  readonly system: SystemBus;
+}
+
+export const HostBridgeContext = createContext<HostBridge | null>(null);
+HostBridgeContext.displayName = 'HostBridgeContext';
+
+/**
+ * Hook biome components use to reach the host. Throws fail-fast if no
+ * `<HostBridgeContext.Provider>` is mounted above — biomes must never
+ * import host primitives directly, so a missing bridge is a wiring bug.
+ */
+export function useHostBridge(): HostBridge {
+  const bridge = useContext(HostBridgeContext);
+  if (!bridge) {
+    throw new Error(
+      '[xema-ui-kernel] useHostBridge() called outside <HostBridgeContext.Provider>. ' +
+        'The host app must wrap biome-rendered subtrees with the bridge provider.',
+    );
+  }
+  return bridge;
+}

package/src/lib/biome-host/host-sources.ts

@@ -0,0 +1,41 @@
+/**
+ * Pluggable host sources — keep the kernel independent of any specific
+ * auth or toast library. The concrete host adapter (Next.js, React-Router,
+ * …) implements each getter/method against whatever client it uses and
+ * passes them in when building the `HostBridge` + `SystemBus`.
+ *
+ * Framework-agnostic: pure interface contracts, no React, no router.
+ */
+
+/**
+ * Pluggable auth source — keeps the kernel independent of any specific
+ * auth library (keycloak-js, auth0, custom OIDC, …). The host implements
+ * each getter against whatever auth client it uses.
+ *
+ * Only the four call-sites a typical biome needs are exposed; if a host
+ * has no concept of "org id" or "project id" it returns `null`. Biomes
+ * tolerate `null` per the `HostBridge` contract.
+ */
+export interface AuthSource {
+  /** Bearer token for outbound API calls, or null when unauthenticated. */
+  getActorToken(): string | null;
+  /** Active organization id, or null when none is selected. */
+  getOrgId(): string | null;
+  /** Active project id, or null when none is selected. */
+  getProjectId(): string | null;
+  /** Subject (user) id of the actor, or null when unauthenticated. */
+  getUserId(): string | null;
+}
+
+/**
+ * Pluggable toast source — keeps the kernel independent of any specific
+ * toast library (sonner, react-hot-toast, custom). The host wires the three
+ * call-sites the `HostBridge` exposes against whatever it uses.
+ */
+export interface ToastSource {
+  /** Success toast with an optional secondary description line. */
+  success(message: string, detail?: string): void;
+  error(message: string, detail?: string): void;
+  /** Info toast with an optional secondary description line. */
+  info(message: string, detail?: string): void;
+}

package/src/lib/biome-host/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Biome-host contract surface — the framework-agnostic shape every
+ * frontend biome composes against, plus the singleton runtime registry
+ * that hosts populate at bootstrap.
+ *
+ * Host-framework-agnostic: no Vite, no Next.js, no React-Router. React
+ * itself IS used (it is the shared component model for any host) — the
+ * contracts traffic in `ReactNode`/`ComponentType`, expose a React
+ * context (`HostBridgeContext`/`useHostBridge`), and the registry ships
+ * a `useSyncExternalStore` revision hook. The concrete host adapter only
+ * wires framework-specific navigation against these contracts (e.g. the
+ * Next.js App Router host); the agnostic host sources (`AuthSource`,
+ * `ToastSource`), nav merging, and the `SystemBus` builder all live here.
+ */
+export * from './frontend-biome';
+export * from './host-bridge';
+export * from './biome-registry';
+export * from './session-contributions';
+export * from './session-profiles';
+export * from './host-sources';
+export * from './nav';
+export * from './biome-mode';
+export * from './composition-validation';