@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,281 +0,0 @@
-import { createContext, useContext, type ReactNode } from 'react';
-
-import type { CapabilityPort } from '../capabilities';
-import type { SystemBus } from '../system-bus';
-import type { I18nSource } from './i18n-port';
-import type { RealtimeSource } from './realtime-port';
-import type { QueryClient } from '@tanstack/react-query';
-
-/**
- * `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;
-  /**
-   * Hook returning the current URL query string as a read-only
-   * `URLSearchParams`. Must be a stable React hook implemented by the host
-   * against its router (`react-router-dom`'s `useSearchParams`, the App
-   * Router's `useSearchParams`, …).
-   *
-   * This is the router primitive biomes could not previously reach through
-   * the bridge — without it they were forced to import `next/navigation`
-   * directly, defeating the host decoupling that `useLocation` /
-   * `useRouteParams` already provide. Read-only on purpose: query mutation
-   * goes through `push` / `replace` so the host owns history semantics.
-   */
-  useSearchParams(): URLSearchParams;
-}
-
-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;
-  /**
-   * Proactively refresh the actor token if it is within `minValiditySeconds`
-   * of expiry, then return a guaranteed-valid bearer. The refresh + any
-   * redirect-on-failure stays HOST-owned (the host owns the auth client and
-   * the single-flight login guard) — biomes only reach it through this method
-   * so an Orval client's `getAuthToken` can be wired against the SAME refresh
-   * path the host uses, instead of each biome re-implementing token freshness.
-   *
-   * @param minValiditySeconds Refresh when fewer than this many seconds of
-   *   validity remain. Defaults to a host-chosen safe window.
-   * @returns A valid bearer token string. Implementations that cannot produce
-   *   one (session expired) trigger the host login redirect and reject.
-   */
-  ensureFreshToken(minValiditySeconds?: number): Promise<string>;
-  /**
-   * Handle a 401 from a downstream API call: force-refresh the token and, if
-   * that fails, redirect to login. HOST-owned for the same reason as
-   * {@link HostBridgeAuth.ensureFreshToken} — there is ONE login-redirect
-   * single-flight guard and one refresh-dedup path in the host; biomes funnel
-   * 401 recovery through here rather than forking that logic.
-   */
-  onUnauthorized(): Promise<void>;
-}
-
-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;
-}
-
-/**
- * Error-decoding surface — the canonical "turn a thrown value into a
- * user-facing message" decoder, exposed on the bridge so biomes use ONE
- * implementation instead of each re-deriving envelope/status-code copy.
- *
- * The decoder is a PURE function (no host context), so the kernel also ships it
- * directly as {@link getUserFacingErrorMessage} and {@link ErrorCard} defaults
- * to it. It is ALSO hung off the bridge so a host can override it with a
- * shell-specific decoder (extra error codes, i18n) without every biome wiring a
- * prop — the bridge value is the single override point.
- */
-export interface HostBridgeErrors {
-  /**
-   * Decode any thrown value into a user-facing message. `fallback` is returned
-   * when nothing better can be extracted. Defaults (in the kernel default
-   * bridge wiring) to {@link getUserFacingErrorMessage}.
-   */
-  getUserFacingErrorMessage(error: unknown, fallback?: string): 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;
-  /**
-   * Server-authoritative capability port — how a biome UI gates on the
-   * caller's effective capability set (`GET /bff/me/capabilities`) instead of
-   * cosmetic role booleans. The HOST implements this against its Orval client
-   * and maps the response onto the kernel's `MeCapabilitiesSnapshot` shape so
-   * the kernel stays fetch-free and host-agnostic. Consumed by
-   * `<CapabilityProvider>` + `useCapability()` (see `../capabilities`).
-   */
-  readonly capabilities: CapabilityPort;
-  /**
-   * Realtime (CloudEvents over SSE) port. The HOST injects a concrete
-   * {@link RealtimeSource} backed by its realtime transport
-   * (`@xemahq/realtime-client`); biomes reach it through the kernel
-   * `useCloudEvent` / `useRealtimeStatus` / `useEventScope` hooks so biome code
-   * never imports the SSE client directly — same decoupling as `navigation`.
-   *
-   * OPTIONAL: a host without a realtime transport simply omits it; the kernel
-   * `useCloudEvent`/`useRealtimeStatus`/`useEventScope` hooks fail fast with an
-   * actionable error if a biome uses them before the host wires `bridge.realtime`.
-   */
-  readonly realtime?: RealtimeSource;
-  /**
-   * Localization port. The HOST injects a concrete {@link I18nSource} backed by
-   * its locale provider (authoritative locale from org/app/user settings +
-   * catalog loading); biomes reach it through the kernel `useT` / `useLocale`
-   * hooks so biome code never imports an i18n library directly — same decoupling
-   * as `navigation` / `realtime`.
-   *
-   * OPTIONAL: a host without localization omits it; the kernel `useT`/`useLocale`
-   * hooks fail fast with an actionable error if a biome uses them before the host
-   * wires `bridge.i18n`.
-   */
-  readonly i18n?: I18nSource;
-  /**
-   * Error-decoding surface — the canonical user-facing error decoder. Defaults
-   * (in the kernel default bridge wiring) to {@link getUserFacingErrorMessage};
-   * a host MAY override it. Biomes + {@link ErrorCard} read ONE decoder instead
-   * of each re-deriving message extraction.
-   *
-   * OPTIONAL: when omitted, consumers fall back to the kernel default
-   * {@link getUserFacingErrorMessage} (which ErrorCard already uses directly).
-   */
-  readonly errors?: HostBridgeErrors;
-}
-
-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

@@ -1,54 +0,0 @@
-/**
- * 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;
-  /**
-   * Proactively refresh the token if it is within `minValiditySeconds` of
-   * expiry and return a valid bearer. Backed by the host's auth client
-   * (keycloak-js `updateToken`, …) and its single-flight login redirect.
-   * Mirrors {@link HostBridgeAuth.ensureFreshToken} — the bridge delegates
-   * straight through to this source.
-   */
-  ensureFreshToken(minValiditySeconds?: number): Promise<string>;
-  /**
-   * Force-refresh on a 401 and redirect to login on failure. Backed by the
-   * host's auth-guard. Mirrors {@link HostBridgeAuth.onUnauthorized}.
-   */
-  onUnauthorized(): Promise<void>;
-}
-
-/**
- * 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/i18n-hooks.ts

@@ -1,51 +0,0 @@
-/**
- * Kernel-side i18n hooks. Biomes call these INSTEAD of importing an i18n library
- * or the host's locale provider directly, so biome code stays decoupled from the
- * i18n implementation — the same decoupling `useHostBridge` provides for
- * navigation / auth / realtime / capabilities.
- *
- * Each hook reads the host-injected {@link I18nSource} off `bridge.i18n` and
- * delegates straight through. The host owns the authoritative locale + catalog
- * loading; the kernel owns only the contract + this thin delegation.
- */
-
-import { useHostBridge } from './host-bridge';
-
-import type { I18nSource, Translator } from './i18n-port';
-
-/**
- * Resolve the host-injected i18n source, failing fast with an actionable message
- * if the host has not wired `bridge.i18n`. `bridge.i18n` is an optional port (a
- * host without localization omits it), so the kernel hooks must not silently
- * no-op — a biome that calls them expects translated copy.
- */
-function requireI18n(i18n: I18nSource | undefined): I18nSource {
-  if (!i18n) {
-    throw new Error(
-      'useT/useLocale require an i18n source, but the host has not wired ' +
-        '`bridge.i18n`. The host must provide an I18nSource (locale + catalogs) ' +
-        'on the HostBridge to use kernel i18n hooks.',
-    );
-  }
-  return i18n;
-}
-
-/**
- * A {@link Translator} for the active locale, scoped to an optional namespace.
- * Call at render; the returned `t(key, params?)` interpolates `{name}` tokens.
- *
- * @example
- *   const t = useT('radar');
- *   return <h1>{t('title')}</h1>;              // radar.title
- *   return <p>{t('greeting', { name })}</p>;   // "Hello, {name}"
- */
-export function useT(namespace?: string): Translator {
-  const bridge = useHostBridge();
-  return requireI18n(bridge.i18n).useTranslator(namespace);
-}
-
-/** The active BCP-47 locale tag (e.g. `"pt-PT"`) for date/number formatting. */
-export function useLocale(): string {
-  const bridge = useHostBridge();
-  return requireI18n(bridge.i18n).useLocale();
-}

package/src/lib/biome-host/i18n-port.test.ts

@@ -1,50 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { makeTranslator } from './i18n-port';
-
-const en = {
-  title: 'Dashboard',
-  greeting: 'Hello, {name}',
-  radar: { title: 'Radar', empty: 'No leads yet' },
-} as const;
-
-describe('makeTranslator', () => {
-  it('resolves flat and nested dot-path keys', () => {
-    const t = makeTranslator(en);
-    expect(t('title')).toBe('Dashboard');
-    expect(t('radar.title')).toBe('Radar');
-  });
-
-  it('interpolates {name} placeholders', () => {
-    const t = makeTranslator(en);
-    expect(t('greeting', { name: 'Ada' })).toBe('Hello, Ada');
-  });
-
-  it('leaves an unknown placeholder verbatim (visible authoring bug)', () => {
-    const t = makeTranslator({ msg: 'Hi {who}' });
-    expect(t('msg', {})).toBe('Hi {who}');
-  });
-
-  it('applies a namespace prefix', () => {
-    const t = makeTranslator(en, { namespace: 'radar' });
-    expect(t('title')).toBe('Radar');
-    expect(t('empty')).toBe('No leads yet');
-  });
-
-  it('returns the raw key for a missing message (never blank, never throws)', () => {
-    const t = makeTranslator(en);
-    expect(t('does.not.exist')).toBe('does.not.exist');
-  });
-
-  it('falls back message-by-message to the default-locale catalog', () => {
-    const pt = { title: 'Painel' }; // partial locale — no greeting
-    const t = makeTranslator(pt, { fallback: en });
-    expect(t('title')).toBe('Painel'); // primary wins
-    expect(t('greeting', { name: 'Ada' })).toBe('Hello, Ada'); // fallback fills the gap
-  });
-
-  it('coerces numeric params to strings', () => {
-    const t = makeTranslator({ count: '{n} items' });
-    expect(t('count', { n: 3 })).toBe('3 items');
-  });
-});

package/src/lib/biome-host/i18n-port.ts

@@ -1,96 +0,0 @@
-/**
- * Kernel i18n contract + a framework-free translator core.
- *
- * Xema's locale is DATA-driven (per-org / per-app / per-user settings), not
- * URL-driven, so the kernel deliberately does NOT depend on next-intl / react-
- * intl. A biome localises its UI through the host-injected {@link I18nSource}
- * (reached via the `useT` / `useLocale` kernel hooks) exactly the way it reaches
- * realtime / navigation — the biome never imports an i18n library, and the host
- * owns catalog loading + the authoritative locale source.
- *
- * The {@link makeTranslator} core here is pure and host-agnostic: a host (or a
- * biome, or a test) builds a `Translator` from a nested-JSON catalog with no
- * framework in the loop.
- */
-
-/** Interpolation values for a message's `{name}` placeholders. */
-export type TranslateParams = Readonly<Record<string, string | number>>;
-
-/**
- * Resolve one message key to a localized string, interpolating `{name}`
- * placeholders. Missing keys return the key itself (visible, never a throw or a
- * blank) — the standard i18n contract, not a silent business-logic fallback.
- */
-export type Translator = (key: string, params?: TranslateParams) => string;
-
-/** A nested message catalog: dot-path keys map to strings (or sub-catalogs). */
-export interface Catalog {
-  readonly [segment: string]: string | Catalog;
-}
-
-export interface MakeTranslatorOptions {
-  /** Prefix every lookup with this namespace path (e.g. `"radar"`). */
-  readonly namespace?: string;
-  /**
-   * Default-locale catalog consulted per-key when the primary catalog lacks a
-   * message — so a partially-translated locale falls back message-by-message
-   * instead of dropping to the raw key.
-   */
-  readonly fallback?: Catalog;
-}
-
-function lookup(catalog: Catalog, path: readonly string[]): string | undefined {
-  let node: string | Catalog | undefined = catalog;
-  for (const segment of path) {
-    if (node === undefined || typeof node === 'string') {
-      return undefined;
-    }
-    node = node[segment];
-  }
-  return typeof node === 'string' ? node : undefined;
-}
-
-function interpolate(message: string, params?: TranslateParams): string {
-  if (!params) {
-    return message;
-  }
-  // Replace `{name}` tokens; an unknown token is left verbatim (visible), never
-  // blanked — a missing param is an authoring bug that should be obvious.
-  return message.replaceAll(/\{(\w+)\}/g, (whole, name: string) =>
-    Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : whole,
-  );
-}
-
-/**
- * Build a {@link Translator} over a catalog. Pure — no React, no framework, no
- * global state. Resolution order per key: primary catalog → fallback catalog →
- * the key itself.
- */
-export function makeTranslator(
-  catalog: Catalog,
-  options?: MakeTranslatorOptions,
-): Translator {
-  const prefix = options?.namespace ? options.namespace.split('.') : [];
-  const fallback = options?.fallback;
-  return (key, params) => {
-    const path = [...prefix, ...key.split('.')];
-    const message =
-      lookup(catalog, path) ?? (fallback ? lookup(fallback, path) : undefined) ?? key;
-    return interpolate(message, params);
-  };
-}
-
-/**
- * Host-implemented i18n source. The host wires these against its locale provider
- * (authoritative locale from org/app/user settings + catalog loading); biomes
- * reach them through the kernel {@link useT} / {@link useLocale} hooks.
- *
- * Every method is a React hook (reads locale/catalog context), so it MUST be
- * called from a component's render.
- */
-export interface I18nSource {
-  /** A {@link Translator} for the active locale, optionally namespaced. */
-  useTranslator(namespace?: string): Translator;
-  /** The active BCP-47 locale tag (e.g. `"pt-PT"`). */
-  useLocale(): string;
-}

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

@@ -1,35 +0,0 @@
-/**
- * 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-navigation';
-export * from './biome-scope';
-export * from './biome-scope-hooks';
-export * from './biome-scoped-query';
-export * from './biome-builders';
-export * from './define-web-biome';
-export * from './create-biome-orval-config';
-export * from './biome-registry';
-export * from './session-contributions';
-export * from './host-sources';
-export * from './biome-mode';
-export * from './agent-validation';
-export * from './realtime-port';
-export * from './realtime-hooks';
-export * from './i18n-port';
-export * from './i18n-hooks';
-export * from './errors';
-export * from './use-mutation-with-error-toast';
-export * from './use-page-state';

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

@@ -1,75 +0,0 @@
-/**
- * Kernel-side realtime hooks. Biomes call these INSTEAD of importing the host's
- * realtime client (`@xemahq/realtime-client`) directly, so biome code stays
- * decoupled from the SSE transport — the same decoupling `useHostBridge`
- * already provides for navigation / auth / capabilities.
- *
- * Each hook reads the host-injected {@link RealtimeSource} off
- * `bridge.realtime` and delegates straight through. The host owns the transport
- * (connection, token refresh, org header, scope refcounting); the kernel owns
- * only the contract + this thin delegation.
- */
-
-import { useHostBridge } from './host-bridge';
-
-import type {
-  RealtimeCloudEvent,
-  RealtimeConnectionState,
-  RealtimeScope,
-  RealtimeSource,
-} from './realtime-port';
-
-/**
- * Resolve the host-injected realtime transport, failing fast with an actionable
- * message if the host has not wired `bridge.realtime`. `bridge.realtime` is an
- * optional port (a host without a realtime transport omits it), so the kernel
- * hooks must not silently no-op — a biome that calls them expects live events.
- */
-function requireRealtime(realtime: RealtimeSource | undefined): RealtimeSource {
-  if (!realtime) {
-    throw new Error(
-      'useCloudEvent/useRealtimeStatus/useEventScope require a realtime ' +
-        'transport, but the host has not wired `bridge.realtime`. The host ' +
-        'must provide a RealtimeSource (e.g. backed by @xemahq/realtime-client) ' +
-        'on the HostBridge to use kernel realtime hooks.',
-    );
-  }
-  return realtime;
-}
-
-/**
- * Subscribe to delivered CloudEvents of a given `type` for the lifetime of the
- * calling component. Pass a stable `handler` (e.g. via `useCallback`) — the
- * host re-subscribes when the handler identity changes. Narrow `event.data`
- * inside the handler; the kernel does not parse payloads.
- *
- * @example
- *   useCloudEvent('session.lifecycle.changed', (event) => {
- *     const data = event.data as { sessionId?: string } | undefined;
- *     if (data?.sessionId !== sessionId) return;
- *     refetch();
- *   });
- */
-export function useCloudEvent(
-  eventType: string,
-  handler: (event: RealtimeCloudEvent) => void,
-): void {
-  const bridge = useHostBridge();
-  requireRealtime(bridge.realtime).useCloudEvent(eventType, handler);
-}
-
-/** Coarse realtime connection state for a status indicator. */
-export function useRealtimeStatus(): RealtimeConnectionState {
-  const bridge = useHostBridge();
-  return requireRealtime(bridge.realtime).useRealtimeStatus();
-}
-
-/**
- * Subscribe the connection to a project/session {@link RealtimeScope} while the
- * calling component is mounted. Scopes are reference-counted by the host, so
- * multiple components asking for the same scope share one server subscription.
- */
-export function useEventScope(scope: RealtimeScope): void {
-  const bridge = useHostBridge();
-  requireRealtime(bridge.realtime).useEventScope(scope);
-}