@xemahq/ui-kernel 0.11.1 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/ui-kernel",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "type": "module",
   "sideEffects": false,
   "description": "Host-framework-agnostic UI kernel for the Xema OS. Defines the SystemBus orchestration contract (capability.invoke, cross-biome intents, command palette, xema:// deeplinks, window manager) AND the biome-host contract surface (FrontendBiome/FrontendBiomeFactory, HostBridge, the singleton biomeRegistry, session contributions) that every frontend biome composes against. No Vite, Next.js, or React-Router — React itself IS allowed as the shared component model (the contracts traffic in ReactNode/ComponentType and a React context). Concrete host adapters (router/auth/toast wiring) live in separate packages that consume this kernel. The SystemBus is pure orchestration: it never authorizes, the backend capability-router enforces all policy.",
@@ -31,7 +31,6 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "src",
     "README.md",
     "LICENSE"
   ],

package/src/index.ts

@@ -1,17 +0,0 @@
-export * from './lib/system-bus';
-export * from './lib/biome-host';
-export * from './lib/capabilities';
-
-// The shared closed-first-party + open-biome contribution registry core (and
-// its versioned/validated renderable flavour). Every plane that lets a biome
-// contribute into a set the platform also ships builtins for is built on this.
-export * from './lib/contribution-registry';
-
-// Guided-capture UX kit (B5). Also available at the `@xemahq/ui-kernel/ui`
-// subpath alongside the rest of the shared UI surface; re-exported here so the
-// capture primitives are reachable from the package root too.
-export * from './ui/capture';
-
-// Offline field-capture kit — durable outbox that queues mutations while
-// disconnected and drains them on reconnect. Also at `@xemahq/ui-kernel/offline`.
-export * from './offline';

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

@@ -1,239 +0,0 @@
-/**
- * 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 `/spaces/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/biome-builders.ts

@@ -1,112 +0,0 @@
-/**
- * Frontend-biome route/biome builders.
- *
- * The `createElement(Suspense, { fallback: null }, createElement(LazyPage))`
- * wrapper is hand-repeated ~74× across biome `index.ts` files — once per lazy
- * route. `lazyRoute` collapses it to one call; `defineSinglePageBiome` builds
- * the whole one-page biome (nav item + single route) that the vast majority of
- * biomes are. Host-framework-agnostic: pure React (`lazy` / `Suspense` /
- * `createElement`), no router and no Next.js.
- */
-import {
-  Suspense,
-  createElement,
-  lazy,
-  type ComponentType,
-  type ReactNode,
-} from 'react';
-
-import type {
-  FrontendBiome,
-  NavItemContribution,
-  RouteAccess,
-  RouteContribution,
-} from './frontend-biome';
-
-/** A dynamic import of a module whose default export is a React component. */
-export type LazyComponentImport = () => Promise<{ default: ComponentType }>;
-
-/**
- * Wrap a dynamic page import as a `RouteContribution['element']` factory: lazy
- * import + `<Suspense>` boundary. Replaces the hand-written
- * `createElement(Suspense, { fallback }, createElement(lazy(importFn)))` block.
- *
- * The `lazy(...)` call is hoisted out of the returned thunk so the component is
- * created ONCE (not on every route render), matching how biomes hand-declare
- * `const Page = lazy(() => import('./Page'))` at module scope.
- *
- * @param importFn Dynamic import of the page module (`() => import('./Page')`).
- * @param fallback Suspense fallback. Defaults to `null` (the prevailing biome
- *   convention) — pass a skeleton to be explicit.
- */
-export function lazyRoute(
-  importFn: LazyComponentImport,
-  fallback: ReactNode = null,
-): () => ReactNode {
-  const Lazy = lazy(importFn);
-  const LazyRoute = () =>
-    createElement(Suspense, { fallback }, createElement(Lazy));
-  LazyRoute.displayName = 'LazyRoute';
-  return LazyRoute;
-}
-
-export interface SinglePageBiomeRoute {
-  /** Route path. May include `:param` segments. */
-  readonly path: string;
-  /** Dynamic import of the page module. */
-  readonly page: LazyComponentImport;
-  /**
-   * Whether the route mounts under `/projects/:projectId` (project-scoped) or
-   * at the org root. REQUIRED — mirrors {@link RouteContribution.projectScoped}.
-   */
-  readonly projectScoped: boolean;
-  /** Access tier required to render. Defaults to `'member'`. */
-  readonly access?: RouteAccess;
-  /** Suspense fallback for the lazy page. Defaults to `null`. */
-  readonly fallback?: ReactNode;
-}
-
-export interface SinglePageBiomeSpec {
-  /** Stable biome id; matches `xema-biome.json` `xema.id`. */
-  readonly id: string;
-  /** Displayed name. */
-  readonly displayName: string;
-  /** The single nav item this biome contributes. */
-  readonly nav: NavItemContribution;
-  /** The single route this biome contributes. */
-  readonly route: SinglePageBiomeRoute;
-}
-
-/**
- * Build a `FrontendBiome` for the common one-nav-item / one-route biome.
- *
- * Most biomes are exactly this shape — a nav entry plus a single lazy page —
- * yet each re-declares the nav array, the route array, the `lazy(...)`, and the
- * `Suspense` wrapper by hand. This builder centralizes all four.
- *
- * @example
- *   const biome: FrontendBiomeFactory = () =>
- *     defineSinglePageBiome({
- *       id: 'org-databases',
- *       displayName: 'Organization Databases',
- *       nav: { id: 'org-databases', label: 'Databases', route: 'org-databases',
- *              icon: Database, section: 'Organization', weight: 30 },
- *       route: { path: 'org-databases', projectScoped: false,
- *                page: () => import('./pages/DatabasesListPage') },
- *     });
- */
-export function defineSinglePageBiome(spec: SinglePageBiomeSpec): FrontendBiome {
-  const { route } = spec;
-  const contribution: RouteContribution = {
-    path: route.path,
-    projectScoped: route.projectScoped,
-    element: lazyRoute(route.page, route.fallback ?? null),
-    ...(route.access ? { access: route.access } : {}),
-  };
-  return {
-    id: spec.id,
-    displayName: spec.displayName,
-    navItems: [spec.nav],
-    routes: [contribution],
-  };
-}

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

@@ -1,6 +0,0 @@
-/**
- * Master switch for the biome subsystem. A host passes `'disabled'` to opt
- * the whole biome runtime out (no biomes load / register) — e.g. for a
- * minimal shell or a degraded mode. Framework-agnostic.
- */
-export type BiomesMode = 'enabled' | 'disabled';

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

@@ -1,37 +0,0 @@
-/**
- * Bridge-backed navigation convenience hooks for frontend biomes.
- *
- * These wrap the host-agnostic `HostBridge.navigation` surface so biome code
- * never imports a router primitive (`next/navigation`, `react-router-dom`)
- * directly — the host wires the concrete implementation once on the bridge and
- * every biome reads it through here. Host-framework-agnostic: no Next.js, no
- * React-Router. React itself IS used (these are React hooks).
- */
-import { useMemo } from 'react';
-
-import { useHostBridge } from './host-bridge';
-
-/**
- * Current URL query string as a read-only `URLSearchParams`, read through the
- * host-provided navigation adapter (`bridge.navigation.useSearchParams`).
- *
- * The one router primitive biomes could not previously reach through the
- * bridge. Use this INSTEAD of `import { useSearchParams } from
- * 'next/navigation'` so biome code stays portable across hosts.
- */
-export function useSearchParams(): URLSearchParams {
-  return useHostBridge().navigation.useSearchParams();
-}
-
-/**
- * Read a single query-string parameter by key, or `null` when absent.
- *
- * Sugar over {@link useSearchParams} for the common "one param" case (e.g.
- * `?tab=overview`, `?runId=…`) that otherwise forces a direct
- * `next/navigation` import. Returns the first value when a key repeats,
- * matching `URLSearchParams.get` semantics.
- */
-export function useQueryParam(key: string): string | null {
-  const searchParams = useSearchParams();
-  return useMemo(() => searchParams.get(key), [searchParams, key]);
-}