@xemahq/ui-kernel 0.11.0 → 0.11.2

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

@@ -1,299 +0,0 @@
-import { Registry } from '@xemahq/registry';
-import { useSyncExternalStore } from 'react';
-
-import {
-  DuplicateContributionPolicy,
-  createContributionRegistry,
-} from '../contribution-registry';
-
-import type {
-  FrontendBiome,
-  FrontendBiomeFactory,
-  OutputRendererContribution,
-  PanelContribution,
-} from './frontend-biome';
-import type { HostBridge } from './host-bridge';
-
-/**
- * Singleton frontend biome registry. Populated at app bootstrap by
- * `registerFrontendBiome()` (factory form) or `registerFrontendBiomeInstance()`
- * (already-built form). Bootstrap order: fetch enabled biome ids from
- * `GET /platform/biomes/web`, dynamically `import()` each biome module
- * from the auto-generated loader map (`xema:web-biome-loaders`), then
- * call its default export with the host's concrete `HostBridge` and
- * register the result.
- *
- * Reactivity: components consume registry data via `useBiomeRegistryRevision()`
- * (or `<BiomeSlot>` / `useBiomeRoutes()` which use it internally) so a
- * re-render fires automatically when a biome registers or unregisters —
- * no race between Sidebar mount and async bootstrap, no manual subscription
- * wiring per consumer.
- *
- * Master-disable: hosts that embed `@xemahq/ui-kernel` without
- * participating in Xema's biome ecosystem flip
- * `biomeRegistry.setEnabled(false)` (typically via
- * `<BiomeHostProvider biomes="disabled">`). When disabled, every
- * register/unregister/bootstrap call is a no-op — a single flag controls
- * the entire surface.
- */
-class FrontendBiomeRegistry extends Registry<
-  string,
-  FrontendBiome & { key: string }
-> {
-  private revisionCount = 0;
-  private readonly listeners = new Set<() => void>();
-  /**
-   * Biome ids whose `init()` callback has been invoked. Tracked
-   * separately from the registry entries so `init()` runs exactly once
-   * per biome per SPA session even if `registerBiome` is called
-   * multiple times (HMR, strict-mode double-mount, retries). Biome
-   * authors get an at-most-once execution guarantee.
-   */
-  private readonly initialized = new Set<string>();
-  private enabled = true;
-
-  constructor() {
-    super({ name: 'FrontendBiomeRegistry' });
-  }
-
-  registerBiome(biome: FrontendBiome): void {
-    if (!this.enabled) {
-      return;
-    }
-    this.register({ ...biome, key: biome.id });
-    this.revisionCount += 1;
-    this.notify();
-  }
-
-  /**
-   * Invoke a biome's `init()` callback exactly once per SPA session.
-   * The caller (bootstrap) is responsible for catching/logging promise
-   * rejections — the registry intentionally does not swallow them.
-   */
-  async runInit(biomeId: string, bridge: HostBridge): Promise<void> {
-    const entry = this.get(biomeId);
-    if (!entry || !entry.init) {
-      return;
-    }
-    if (this.initialized.has(biomeId)) {
-      return;
-    }
-    this.initialized.add(biomeId);
-    await entry.init({ bridge, biomeId });
-  }
-
-  unregisterBiome(id: string): boolean {
-    if (!this.enabled) {
-      return false;
-    }
-    const entry = this.get(id);
-    const removed = this.unregister(id);
-    if (removed) {
-      this.revisionCount += 1;
-      this.initialized.delete(id);
-      if (entry?.dispose) {
-        // Fire-and-forget; teardown errors are logged by callers but
-        // never block the unregister path — disposal is best-effort
-        // because the biome is being torn down anyway.
-        void Promise.resolve(entry.dispose()).catch((error: unknown) => {
-          // Surface for devtools without crashing the unregister flow.
-          console.error(
-            `[xema-ui-kernel] dispose() failed for '${id}':`,
-            error,
-          );
-        });
-      }
-      this.notify();
-    }
-    return removed;
-  }
-
-  /**
-   * Snapshot of currently-registered biome ids. Useful for the admin UI
-   * to detect "registered in this session" vs "enabled in catalog".
-   */
-  snapshot(): readonly string[] {
-    return this.list().map((b) => b.id);
-  }
-
-  setEnabled(enabled: boolean): void {
-    if (this.enabled === enabled) {
-      return;
-    }
-    this.enabled = enabled;
-    if (!enabled) {
-      // When master-disabling, drop any previously-registered biomes so
-      // BiomeSlot/useBiomeRoutes consumers re-render to empty.
-      const had = this.size() > 0;
-      this.clear();
-      this.initialized.clear();
-      if (had) {
-        this.revisionCount += 1;
-        this.notify();
-      }
-    }
-  }
-
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  revision(): number {
-    return this.revisionCount;
-  }
-
-  /**
-   * Subscribe to revision-counter changes. Returns an unsubscribe
-   * function. Used internally by `useBiomeRegistryRevision()` (via
-   * `useSyncExternalStore`) so components automatically re-render when
-   * a biome is added or removed.
-   */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  panelsForSlot(slot: string): readonly PanelContribution[] {
-    if (!this.enabled) {
-      return [];
-    }
-    const out: PanelContribution[] = [];
-    for (const biome of this.list()) {
-      for (const panel of biome.panels ?? []) {
-        if (panel.slot === slot) {
-          out.push(panel);
-        }
-      }
-    }
-    return out.sort((a, b) => (a.weight ?? 100) - (b.weight ?? 100));
-  }
-
-  /**
-   * Flatten every registered biome's `outputRenderers[]` contributions
-   * into a `(outputKind → factory)` map. The host's renderer registry
-   * overlays this on top of the built-in set so biome-defined kinds
-   * light up the moment the biome's frontend loads. Duplicate kinds
-   * across biomes are surfaced as a console error and the first
-   * registration wins (deterministic + fail-loud, not silent).
-   *
-   * Built on the shared `createContributionRegistry` core — the same
-   * closed+open two-layer bookkeeping the ChatWidget, reply-variant and
-   * Vista-surface registries use. This overlay is rebuilt on every call
-   * (it is read during render), so it takes the `FirstWins` duplicate
-   * policy rather than `Throw`: a duplicate must not take down a render.
-   * `FirstWins` still REQUIRES the `onDuplicate` reporter below — the
-   * rejected contribution is never dropped silently.
-   */
-  outputRenderers(): ReadonlyMap<string, OutputRendererContribution> {
-    if (!this.enabled) {
-      return new Map<string, OutputRendererContribution>();
-    }
-    // `onDuplicate` fires SYNCHRONOUSLY from inside `register()`, so this
-    // cursor always names the biome whose contribution was rejected — the
-    // contribution object itself does not carry its owner.
-    let contributingBiomeId = '';
-    const overlay = createContributionRegistry<OutputRendererContribution>({
-      name: 'biome outputRenderer',
-      duplicatePolicy: DuplicateContributionPolicy.FirstWins,
-      onDuplicate: (outputKind) => {
-        console.error(
-          `[xema-ui-kernel] duplicate outputRenderer for kind '${outputKind}' ` +
-            `from biome '${contributingBiomeId}'; first registration wins.`,
-        );
-      },
-    });
-    for (const biome of this.list()) {
-      contributingBiomeId = biome.id;
-      for (const entry of biome.outputRenderers ?? []) {
-        overlay.register(entry.outputKind, entry);
-      }
-    }
-    return overlay.entries();
-  }
-
-  private notify(): void {
-    for (const listener of this.listeners) {
-      listener();
-    }
-  }
-}
-
-export const biomeRegistry = new FrontendBiomeRegistry();
-
-function isFrontendBiome(value: unknown): value is FrontendBiome {
-  return (
-    value !== null &&
-    typeof value === 'object' &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'displayName' in value &&
-    typeof value.displayName === 'string'
-  );
-}
-
-/**
- * Register an already-built `FrontendBiome` instance. Prefer
- * `registerFrontendBiome(factory, bridge)` for biomes shipped via
- * the factory contract.
- */
-export function registerFrontendBiomeInstance(biome: FrontendBiome): void {
-  biomeRegistry.registerBiome(biome);
-}
-
-/**
- * Invoke a `FrontendBiomeFactory` with the host's `HostBridge` and
- * register the resulting `FrontendBiome`. This is the standard
- * registration path for biomes shipped as workspace packages.
- *
- * Fail-fast: a factory that returns a non-`FrontendBiome` value, or
- * that produces a duplicate id, propagates the underlying registry
- * error — no swallowing.
- */
-export function registerFrontendBiome(
-  factory: FrontendBiomeFactory,
-  bridge: HostBridge,
-): void {
-  if (!biomeRegistry.isEnabled()) {
-    return;
-  }
-  const biome: unknown = factory(bridge);
-  if (!isFrontendBiome(biome)) {
-    throw new Error(
-      '[xema-ui-kernel] FrontendBiomeFactory returned a non-FrontendBiome value. ' +
-        'A biome module must default-export `(bridge) => FrontendBiome`.',
-    );
-  }
-  biomeRegistry.registerBiome(biome);
-}
-
-/**
- * Unregister a biome by id. Triggered by the admin UI's runtime
- * disable flow so BiomeSlot / useBiomeRoutes consumers reflow without
- * a page reload. Returns `true` if a registration was removed.
- */
-export function unregisterFrontendBiome(id: string): boolean {
-  return biomeRegistry.unregisterBiome(id);
-}
-
-/**
- * React hook that subscribes the calling component to the biome
- * registry's revision counter. Returns the current revision (a number
- * that increments by 1 on every biome registration or unregistration).
- * Use the return value as a `useMemo` dep when computing data derived
- * from the registry — the memo recomputes on every change.
- *
- * Implemented with `useSyncExternalStore` so it integrates cleanly with
- * React 18 concurrent rendering and SSR.
- *
- * `<BiomeSlot>` uses this hook internally so any host page that mounts
- * a slot re-renders automatically when biomes arrive or leave.
- */
-export function useBiomeRegistryRevision(): number {
-  return useSyncExternalStore(
-    (listener) => biomeRegistry.subscribe(listener),
-    () => biomeRegistry.revision(),
-    () => biomeRegistry.revision(),
-  );
-}

package/src/lib/biome-host/biome-scope-hooks.ts

@@ -1,41 +0,0 @@
-import { useHostBridge } from './host-bridge';
-
-export interface ProjectScope {
-  readonly orgId: string | null;
-  readonly projectId: string | null;
-}
-
-export interface RequiredProjectScope {
-  readonly orgId: string;
-  readonly projectId: string;
-}
-
-function normalize(value: string | null | undefined): string | null {
-  if (typeof value !== 'string') {
-    return null;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-export function useProjectScope(): ProjectScope {
-  const bridge = useHostBridge();
-  const params = bridge.navigation.useRouteParams<{ projectId?: string }>();
-  const orgId = normalize(bridge.auth.getOrgId());
-  const projectId =
-    normalize(params.projectId) ?? normalize(bridge.auth.getProjectId());
-  return { orgId, projectId };
-}
-
-export function useRequiredScope(): RequiredProjectScope {
-  const { orgId, projectId } = useProjectScope();
-  if (!orgId || !projectId) {
-    throw new Error(
-      `[xema-ui-kernel] useRequiredScope() requires both orgId and projectId, ` +
-        `got orgId=${orgId ?? 'null'} projectId=${projectId ?? 'null'}. ` +
-        `Render this component under <ScopeGuard> or use useProjectScope() for ` +
-        `org-scoped surfaces.`,
-    );
-  }
-  return { orgId, projectId };
-}

package/src/lib/biome-host/biome-scope.tsx

@@ -1,52 +0,0 @@
-/**
- * Bridge-backed org/project scope hooks for frontend biomes.
- *
- * Biomes need the active `{ orgId, projectId }` everywhere they call a scoped
- * API or build a scoped query key. Today each biome rolls its own read — some
- * pull `bridge.auth.getOrgId()`, some read `projectId` off route params, some
- * mix both — which drifts and quietly produces null/undefined holes. This
- * module collapses those into ONE normalized read and ONE guard component.
- *
- * Host-framework-agnostic: it only reads the host-implemented bridge surface
- * (`auth.getOrgId` / `auth.getProjectId` and `navigation.useRouteParams`). No
- * Next.js, no React-Router.
- */
-import { Fragment, type ReactElement, type ReactNode } from 'react';
-
-import { useProjectScope, type ProjectScope } from './biome-scope-hooks';
-
-export interface ScopeGuardProps {
-  /**
-   * What to render while the scope is incomplete. Defaults to `null` (render
-   * nothing) — pass a skeleton or an empty-state to be explicit.
-   */
-  readonly fallback?: ReactNode;
-  /**
-   * When `true` (the default) both `orgId` AND `projectId` are required. Set
-   * `false` to gate only on `orgId` — for org-scoped surfaces that still want
-   * to wait for an active org before rendering.
-   */
-  readonly requireProject?: boolean;
-  /**
-   * Children to render once the scope is complete. May be a render-prop that
-   * receives the resolved {@link ProjectScope}, or plain nodes.
-   */
-  readonly children: ReactNode | ((scope: ProjectScope) => ReactNode);
-}
-
-/**
- * Gate a subtree on a complete active scope. Renders `fallback` until the
- * required scope fields are present, then renders `children` (passing the
- * resolved scope when `children` is a render-prop). Collapses the repeated
- * `if (!orgId || !projectId) return null` guard biome pages hand-write.
- */
-export function ScopeGuard(props: ScopeGuardProps): ReactElement {
-  const { fallback = null, requireProject = true, children } = props;
-  const scope = useProjectScope();
-  const ready = Boolean(scope.orgId) && (!requireProject || Boolean(scope.projectId));
-  if (!ready) {
-    return <Fragment>{fallback}</Fragment>;
-  }
-  const resolved = typeof children === 'function' ? children(scope) : children;
-  return <Fragment>{resolved}</Fragment>;
-}

package/src/lib/biome-host/biome-scoped-query.ts

@@ -1,134 +0,0 @@
-/**
- * Bridge-backed scoped-fetch helpers for frontend biomes.
- *
- * Every scoped biome data hook hand-repeats the same three things: build the
- * org/project request headers (`reqOpts`), gate the query on the scope being
- * present (`enabled`), and fold org/project into the query key so cache entries
- * don't bleed across tenants/projects. This module folds those into
- * `useScopedClient()` + `useScopedQuery()` so a biome hook becomes one call.
- *
- * Host-framework-agnostic. TanStack Query is an OPTIONAL peer dependency — it
- * is imported only here, behind the `useScopedQuery` surface, so biomes that
- * don't use it pay nothing and the kernel never hard-requires it.
- */
-import {
-  useQuery,
-  type QueryKey,
-  type UseQueryOptions,
-  type UseQueryResult,
-} from '@tanstack/react-query';
-
-import { useProjectScope, type ProjectScope } from './biome-scope-hooks';
-
-/**
- * The canonical Xema-platform tenant header. Every platform biome-api reads it
- * via `RequestContext`. Mirrors the host's `reqOpts` (see
- * `submodules/xema-host-web/src/lib/api/orval/configure-clients.ts`).
- */
-const ORG_HEADER = 'X-Xema-Org-Id';
-const PROJECT_HEADER = 'X-Project-Id';
-
-/**
- * Build a `RequestInit` carrying the active org/project headers, to pass as the
- * per-call `options` argument of any Orval endpoint function. Single source of
- * the header names so biomes stop hand-rolling `reqOpts` per package.
- */
-export function buildScopedRequestInit(scope: ProjectScope): RequestInit {
-  const headers: Record<string, string> = {};
-  if (scope.orgId) {
-    headers[ORG_HEADER] = scope.orgId;
-  }
-  if (scope.projectId) {
-    headers[PROJECT_HEADER] = scope.projectId;
-  }
-  return { headers };
-}
-
-export interface ScopedClient {
-  /** The resolved active scope (null-normalized). */
-  readonly scope: ProjectScope;
-  /**
-   * Per-call Orval options bound to the active scope. Pass straight into an
-   * endpoint function: `await fooControllerList(client.reqOpts())`.
-   */
-  reqOpts(): RequestInit;
-}
-
-/**
- * A scope-bound request-options factory. Reads the active `{ orgId, projectId }`
- * from the bridge and exposes a `reqOpts()` that stamps the canonical tenant
- * headers — the per-biome `reqOpts(orgId, projectId)` helper, centralized.
- */
-export function useScopedClient(): ScopedClient {
-  const scope = useProjectScope();
-  return {
-    scope,
-    reqOpts: () => buildScopedRequestInit(scope),
-  };
-}
-
-/**
- * Extra options accepted by {@link useScopedQuery} on top of the underlying
- * TanStack `useQuery` options.
- */
-export interface UseScopedQueryExtras {
-  /**
-   * When `true` (the default) the query is gated on `orgId` AND `projectId`.
-   * Set `false` to gate only on `orgId` — for org-scoped reads that don't need
-   * a project. The gate ANDs with any caller-supplied `enabled`.
-   */
-  readonly requireProject?: boolean;
-}
-
-/**
- * The `queryFn` shape `useScopedQuery` calls — it receives the resolved scope
- * plus the scope-bound `reqOpts()` so the body never re-reads the bridge.
- */
-export type ScopedQueryFn<TData> = (ctx: {
-  readonly scope: ProjectScope;
-  reqOpts(): RequestInit;
-}) => TData | Promise<TData>;
-
-/**
- * Scope-aware `useQuery`. Folds the active org/project into:
- *   - the **query key** — `key` is prefixed with `['scope', orgId, projectId]`
- *     so cache entries never leak across tenants/projects;
- *   - the **`enabled` gate** — ANDed with the scope-present check (and any
- *     caller `enabled`), so the query stays idle until the scope resolves;
- *   - the **`queryFn` context** — the resolved scope + a bound `reqOpts()`.
- *
- * Everything else (`staleTime`, `select`, `retry`, …) passes through to the
- * underlying `useQuery`.
- */
-export function useScopedQuery<
-  TQueryFnData,
-  TError = Error,
-  TData = TQueryFnData,
->(
-  key: QueryKey,
-  queryFn: ScopedQueryFn<TQueryFnData>,
-  options: Omit<
-    UseQueryOptions<TQueryFnData, TError, TData>,
-    'queryKey' | 'queryFn'
-  > &
-    UseScopedQueryExtras = {},
-): UseQueryResult<TData, TError> {
-  const scope = useProjectScope();
-  const { requireProject = true, enabled, ...rest } = options;
-
-  const scopeReady =
-    Boolean(scope.orgId) && (!requireProject || Boolean(scope.projectId));
-
-  return useQuery<TQueryFnData, TError, TData>({
-    ...rest,
-    queryKey: ['scope', scope.orgId, scope.projectId, ...key],
-    enabled: scopeReady && (enabled ?? true),
-    queryFn: () =>
-      Promise.resolve(
-        queryFn({
-          scope,
-          reqOpts: () => buildScopedRequestInit(scope),
-        }),
-      ),
-  });
-}

package/src/lib/biome-host/create-biome-orval-config.ts

@@ -1,82 +0,0 @@
-/**
- * Shared Orval-client wiring for frontend biomes.
- *
- * Every biome that calls a platform API through an Orval-generated client must
- * configure that client with the SAME auth/header/401 behavior the host shell
- * uses for its own clients. Hand-copying a `configureOrgDbClient`-style helper
- * into each biome (as `org-databases` did across three hook files) duplicates
- * the correlation-id + org-header + token logic and lets it drift from the
- * host. This factory centralizes it: a biome builds one config from its
- * `HostBridge` and feeds it straight into the client's `configureClient(...)`.
- *
- * Auth/refresh/redirect stay HOST-owned — this only READS the bridge's
- * host-implemented methods (`getActorToken`, `ensureFreshToken`,
- * `onUnauthorized`, `getOrgId`). It owns no auth state of its own.
- */
-import type { HostBridge } from './host-bridge';
-
-/**
- * The Orval client config shape every generated `configureClient(...)` accepts.
- * Kept structural (not imported from a client package) so the kernel stays free
- * of any concrete service-client dependency — biomes pass the result straight
- * into their own client's `configureClient`, which validates the shape.
- */
-export interface BiomeOrvalConfig {
-  readonly baseUrl: string;
-  readonly maxRetries: number;
-  getAuthToken(): Promise<string>;
-  getHeaders(): Promise<Record<string, string>>;
-  onUnauthorized(): Promise<void>;
-}
-
-export interface CreateBiomeOrvalConfigOptions {
-  /** Absolute base URL of the target service. */
-  readonly baseUrl: string;
-  /**
-   * Retry budget for the underlying fetch wrapper. Defaults to 1 — a single
-   * retry covers the `onUnauthorized` refresh-then-retry path without turning
-   * a hard failure into a retry storm.
-   */
-  readonly maxRetries?: number;
-}
-
-/**
- * Build an Orval client config from a `HostBridge`. Wires:
- *   - `getAuthToken` → `bridge.auth.ensureFreshToken()` (proactive refresh;
- *     the host owns the refresh + login-redirect single-flight).
- *   - `getHeaders` → a fresh `X-Correlation-Id` per call, plus `X-Xema-Org-Id`
- *     (the canonical Xema-platform tenant header every platform service reads
- *     via `RequestContext`) when an org is selected. Biome web clients only ever
- *     call Xema-platform biome-apis, so this is the single correct tenant
- *     header; the previously-sent legacy `X-Org-Id` was dead (the central
- *     read-side was decommissioned) and left context-derived reads without an
- *     org. Per-call headers set by the caller still win in the client's own
- *     header merge.
- *   - `onUnauthorized` → `bridge.auth.onUnauthorized()` (host force-refresh +
- *     redirect-on-failure).
- *
- * @example
- *   configureClient(createBiomeOrvalConfig(bridge, { baseUrl: API_BASE_URL }));
- */
-export function createBiomeOrvalConfig(
-  bridge: HostBridge,
-  opts: CreateBiomeOrvalConfigOptions,
-): BiomeOrvalConfig {
-  return {
-    baseUrl: opts.baseUrl,
-    maxRetries: opts.maxRetries ?? 1,
-    getAuthToken: () => bridge.auth.ensureFreshToken(),
-    getHeaders: () => {
-      const headers: Record<string, string> = {
-        'X-Correlation-Id': crypto.randomUUID(),
-      };
-      const orgId = bridge.auth.getOrgId();
-      if (orgId) {
-        // Canonical header read by every Xema-platform service's RequestContext.
-        headers['X-Xema-Org-Id'] = orgId;
-      }
-      return Promise.resolve(headers);
-    },
-    onUnauthorized: () => bridge.auth.onUnauthorized(),
-  };
-}