@xemahq/ui-kernel 0.11.1 → 0.11.2

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

@@ -1,256 +0,0 @@
-import type { HostBridge } from './host-bridge';
-import type { SessionContributions } from './session-contributions';
-import type { ComponentType, ReactNode } from 'react';
-
-/**
- * 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 }>;
-  /**
-   * Semantic menu category the biome declares its INTENT to live in (e.g.
-   * `build`, `operate`, `knowledge`, `account`). The HOST owns the menu
-   * information-architecture: it maps a category to a concrete rail group,
-   * heading, and order. Authors declare WHAT a surface is, not WHERE in the
-   * global menu it renders — so the platform can re-organise the menu without
-   * editing every biome. When omitted, the host falls back to its own
-   * taxonomy (keyed on the nav-item id).
-   */
-  readonly category?: string;
-}
-
-/**
- * Access tier required to render a route. The host resolver enforces it
- * declaratively — nav-hide is NOT a security boundary, a deeplink bypasses it.
- * Precedence (least → most privileged): `member` < `org-admin` <
- * `platform-admin`. Defaults to `member` when a route omits the field.
- *
- * `public` is NOT a privilege tier — it is the *no-auth* marker: a `public`
- * route requires no Keycloak session at all and mounts OUTSIDE the host's
- * authenticated route group. It is value-locked to `RouteScope` `'public'`
- * (`defineWebBiome` rejects any other pairing at define time), so a route is
- * public in BOTH senses or in neither. Closed set — a new member is a
- * one-line change to {@link ROUTE_ACCESS_VALUES} and one `case` in the host
- * resolver's exhaustive `hasRouteAccess` switch (the switch has no `default`,
- * so an unhandled member is a compile error, never a silent allow).
- *
- * The tuple below is the SINGLE source of truth: the type is derived from it,
- * so a member cannot exist in the type without also being enumerable at
- * runtime — which is what lets a host prove exhaustiveness in a test rather
- * than by inspection. Order is least → most privileged; `public` is the
- * no-auth marker and is deliberately last.
- */
-export const ROUTE_ACCESS_VALUES = [
-  'member',
-  'org-admin',
-  'platform-admin',
-  'public',
-] as const;
-
-/** Access tier required to render a route. See {@link ROUTE_ACCESS_VALUES}. */
-export type RouteAccess = (typeof ROUTE_ACCESS_VALUES)[number];
-
-/**
- * Where a route mounts in the host's URL/auth topology. Closed set — adding a
- * member is a one-line change here (and the single mapping in `defineWebBiome`
- * plus one resolver partition in the host).
- *
- * - `org` — mounts at the org root, inside the authenticated group.
- * - `project` — mounts under the project-scoped route prefix, inside the
- *   authenticated group.
- * - `public` — mounts OUTSIDE the authenticated group; no Keycloak session,
- *   no login redirect, no org switcher. Locked to `RouteAccess` `'public'`.
- *
- * Single source of truth for the closed set; the type is derived from it.
- */
-export const ROUTE_SCOPE_VALUES = ['org', 'project', 'public'] as const;
-
-/** Where a route mounts. See {@link ROUTE_SCOPE_VALUES}. */
-export type RouteScope = (typeof ROUTE_SCOPE_VALUES)[number];
-
-/**
- * Whether a page renders wrapped in the host application shell (app rail,
- * topbar, org switcher) or standalone. Closed set — a new member is a one-line
- * change here. Defaults to `'host'` when a page omits it.
- *
- * - `host` — the default; the host renders its chrome around the page.
- * - `none` — the host renders the page with NO app rail, topbar, or org
- *   switcher (a full-bleed surface). `public` routes are structurally
- *   chromeless (their route group ships no shell); `none` also lets an
- *   authenticated route opt out of the shell.
- *
- * Single source of truth for the closed set; the type is derived from it.
- * Chrome is ORTHOGONAL to access: `chrome: 'none'` on an authenticated route
- * is the embedded-app case and grants no privilege change whatsoever.
- */
-export const PAGE_CHROME_VALUES = ['host', 'none'] as const;
-
-/** Host-shell mode a page renders in. See {@link PAGE_CHROME_VALUES}. */
-export type PageChrome = (typeof PAGE_CHROME_VALUES)[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)
-   * or org-scoped (mounted at the org root). REQUIRED — the host nav resolver
-   * partitions the rail strictly by this flag and drops any nav item whose
-   * route can't be matched (fail-loud). A silent default would re-introduce the
-   * "project pages showing at org level" class of bug, so every route MUST
-   * declare its scope explicitly.
-   */
-  readonly projectScoped: boolean;
-  /**
-   * Access tier required to render this route. The host resolver enforces it
-   * declaratively. Defaults to `'member'` when omitted. `'public'` marks a
-   * no-auth route the host mounts outside its authenticated group.
-   */
-  readonly access?: RouteAccess;
-  /**
-   * Whether the host wraps this route in its application shell. Defaults to
-   * `'host'` when omitted; `'none'` renders the page with no app rail,
-   * topbar, or org switcher. See {@link PageChrome}.
-   */
-  readonly chrome?: PageChrome;
-}
-
-/**
- * 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 one host runtime
- * today and a different host runtime tomorrow.
- */
-export type FrontendBiomeFactory = (bridge: HostBridge) => FrontendBiome;

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();
-}