@xemahq/ui-kernel 0.2.0 → 0.4.0

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

@@ -0,0 +1,74 @@
+/**
+ * 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);
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Host-agnostic realtime (CloudEvents over SSE) port.
+ *
+ * Frontend biomes need to subscribe to server-pushed CloudEvents (session
+ * lifecycle, tool calls, notifications, …). The transport — the unified SSE
+ * connection, the Keycloak-minted bearer, the active-org header, cross-tab
+ * leader election, server-side scope subscriptions — is HOST-owned (today
+ * `@xemahq/realtime-client` wrapped by the host's `RealtimeProvider`). Biomes
+ * must NOT import that client or `EventSource` directly, exactly as they must
+ * not import `next/navigation` or `sonner`.
+ *
+ * Instead the host injects a concrete {@link RealtimeSource} when it builds the
+ * {@link HostBridge}; it is hung off `bridge.realtime`. Biomes reach it through
+ * the {@link useCloudEvent} / {@link useRealtimeStatus} / {@link useEventScope}
+ * kernel hooks — the same decoupling pattern as `bridge.navigation` /
+ * `bridge.capabilities`.
+ *
+ * Framework-agnostic: pure interface contracts, no React, no SSE, no fetch.
+ */
+
+/**
+ * The subset of the CloudEvents-shape envelope a biome handler receives.
+ *
+ * Locally typed in the kernel (deliberately NOT imported from
+ * `@xemahq/realtime-client` / `@xemahq/events`) so `@xemahq/ui-kernel` stays
+ * transport-free and host-agnostic. The host's realtime client emits an object
+ * that is structurally assignable to this — value-identical to the client's
+ * `DeliveredEvent`, kept here as the kernel's stable contract.
+ */
+export interface RealtimeCloudEvent {
+  /** CloudEvents `id` — unique per delivered event, when the server stamps it. */
+  id?: string;
+  /** CloudEvents `type`, e.g. `session.lifecycle.changed`. The subscription key. */
+  type: string;
+  /** CloudEvents `source`, e.g. `/services/activity-feed-api` or `/biomes/<id>`. */
+  source?: string;
+  /** CloudEvents `subject`, e.g. `session/<session-id>`. */
+  subject?: string;
+  /** CloudEvents `data` payload. Biomes narrow this themselves. */
+  data?: unknown;
+  /** Org-id header echoed onto every delivered envelope. */
+  ehorgid: string;
+  /** Project-id header, when the event is project-scoped. */
+  ehprojectid?: string;
+  /** User-id header, when the event is user-scoped. */
+  ehuserid?: string;
+  /** Global delivery cursor. */
+  ehglobalseq?: string;
+  /** Per-org delivery cursor. */
+  ehorgseq?: string;
+  /** Per-project delivery cursor. */
+  ehprojectseq?: string;
+  /** Per-session delivery cursor. */
+  ehsessionseq?: string;
+  /** Frontend-only invalidation hint carried alongside the envelope. */
+  __hint?: unknown;
+}
+
+/** Coarse realtime connection status for status indicators. */
+export type RealtimeStatus =
+  | 'idle'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'closed';
+
+/** Coarse connection state surfaced to status UIs. */
+export interface RealtimeConnectionState {
+  readonly status: RealtimeStatus;
+  /** Latest connectionId returned by the upstream `CONNECTED` frame. */
+  readonly connectionId?: string;
+}
+
+/**
+ * A server-side scope a connection can subscribe to so it only receives the
+ * events for one project or session, rather than the full org firehose. The
+ * host's transport reference-counts identical scopes across mounts.
+ */
+export interface RealtimeScope {
+  readonly kind: 'project' | 'session';
+  readonly id: string;
+}
+
+/**
+ * Host-implemented realtime source. The host wires each method against its
+ * realtime transport (`@xemahq/realtime-client`'s `RealtimeContext`) and passes
+ * it in when building the {@link HostBridge}.
+ *
+ * Every method is a React hook (it reads transport context / state), so it
+ * MUST be called from a biome component's render — the kernel `useCloudEvent` /
+ * `useRealtimeStatus` / `useEventScope` hooks delegate straight through.
+ */
+export interface RealtimeSource {
+  /**
+   * Subscribe `handler` to every delivered CloudEvent whose `type` matches
+   * `eventType`, for the lifetime of the calling component. Per-`data` filtering
+   * (e.g. by `sessionId`) is the handler's responsibility. Mirrors the host
+   * client's `useCloudEvent`.
+   */
+  useCloudEvent(eventType: string, handler: (event: RealtimeCloudEvent) => void): void;
+  /** Coarse connection state for a status indicator. */
+  useRealtimeStatus(): RealtimeConnectionState;
+  /**
+   * Subscribe the connection's unified SSE to a project/session scope while the
+   * calling component is mounted; auto-unsubscribes on unmount. Server-side
+   * subscriptions are reference-counted by the host transport.
+   */
+  useEventScope(scope: RealtimeScope): void;
+}

package/src/lib/biome-host/response-envelope.ts

@@ -0,0 +1,69 @@
+/**
+ * Frontend mirror of the backend `ResponseEnvelopeInterceptor`.
+ *
+ * Every 2xx body the platform returns is wrapped as `{ data: T }`, or
+ * `{ data: T[], pagination }` for a paginated list (single source of truth:
+ * `@xemahq/platform-common`'s `ResponseEnvelopeInterceptor`). Orval's
+ * `custom-fetch` mutators usually peel that envelope at the HTTP boundary, but
+ * spec drift (a controller typed `T[]` that emits `{ data }`), public clients
+ * that DON'T peel, and transient partial responses leave a `.data`-wrapped or
+ * mis-shaped value where biome code expects a bare value/array — and a raw
+ * `.map` on it white-screens the route.
+ *
+ * These are the ONE shared, pure unwrap helpers — no host context, no fetch.
+ * Biomes (and the host shell's own `unwrap-list.ts`) should adopt these instead
+ * of re-implementing the guard. This is the shared helper only; adopters are
+ * migrated incrementally, not in a blanket rewrite.
+ */
+
+/**
+ * Resilient list unwrap for DISPLAY surfaces — normalises a React-Query `.data`
+ * to an array so the page renders its empty/error state instead of crashing:
+ *
+ *   - already an array        → returned as-is
+ *   - `{ data: T[] }` envelope → `value.data`
+ *   - anything else            → `[]`
+ *
+ * Deliberately NON-throwing: the query's own `isError`/`isLoading` flags drive
+ * the visible error/empty UI; this only guards the render path. For
+ * mutation/single-resource flows where an unexpected shape is a real bug, use
+ * {@link unwrapData} (fail-fast) instead.
+ */
+export function unwrapList<T>(value: unknown): T[] {
+  if (Array.isArray(value)) {
+    return value as T[];
+  }
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Array.isArray((value as { data?: unknown }).data)
+  ) {
+    return (value as { data: T[] }).data;
+  }
+  return [];
+}
+
+/**
+ * Fail-fast single-resource unwrap. Returns `value.data` when the value is a
+ * `{ data }` envelope; returns the value unchanged when it is already the
+ * unwrapped resource (an Orval client that peeled the envelope at the boundary).
+ *
+ * Use this on mutation / single-resource flows where the response SHOULD be a
+ * concrete object — unlike {@link unwrapList}, it does not silently coerce, so
+ * a genuinely-unexpected shape surfaces as the value rather than being masked.
+ *
+ * A paginated envelope (`{ data, pagination }`) is returned INTACT — callers
+ * that need both fields read them off the returned object; peeling only `data`
+ * would drop the pagination cursor.
+ */
+export function unwrapData<T>(value: unknown): T {
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    'data' in (value as Record<string, unknown>) &&
+    !('pagination' in (value as Record<string, unknown>))
+  ) {
+    return (value as { data: T }).data;
+  }
+  return value as T;
+}

package/src/session/shell/SessionWorkspaceShell.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode, MouseEvent, RefObject } from 'react';
+import type { CSSProperties, ReactNode, MouseEvent, RefObject } from 'react';
 
 import { cn } from '../lib/cn';
 
@@ -79,28 +79,34 @@ export function SessionWorkspaceShell({
   // surface (Document Buddy). Hide the right pane + resize handle and
   // let the chat pane occupy the full width.
   const hasPreviewSlot = previewSlot !== null;
+  // Below `lg` the two panes stack vertically (flex-col) and each takes the
+  // full width; the chat pane's fixed width / minWidth split only applies at
+  // `lg`+ where the resize handle is available. The width values ride on CSS
+  // variables so the inline style never forces a side-by-side split on a
+  // phone (Tailwind applies them only at the `lg` breakpoint).
+  const leftPaneStyle: CSSProperties | undefined = hasPreviewSlot
+    ? ({
+        '--sws-min-left': `${minLeftPaneWidth}px`,
+        '--sws-chat-pct': `${chatPanePercent}%`,
+      } as CSSProperties)
+    : undefined;
   return (
     <div
       ref={splitContainerRef}
       className={cn(
-        'relative flex h-full w-full overflow-hidden',
+        'relative flex h-full w-full flex-col overflow-hidden lg:flex-row',
         isResizing && 'cursor-col-resize',
       )}
     >
       {!previewFullscreen && (
         <div
           className={cn(
-            'flex h-full w-full flex-col overflow-hidden bg-paper',
-            hasPreviewSlot ? 'lg:flex-none' : '',
-          )}
-          style={
+            'flex w-full min-h-0 flex-col overflow-hidden bg-paper',
             hasPreviewSlot
-              ? {
-                  minWidth: `${minLeftPaneWidth}px`,
-                  width: `${chatPanePercent}%`,
-                }
-              : undefined
-          }
+              ? 'flex-1 lg:h-full lg:w-[var(--sws-chat-pct)] lg:min-w-[var(--sws-min-left)] lg:flex-none'
+              : 'h-full',
+          )}
+          style={leftPaneStyle}
         >
           <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">
             <div className="relative min-h-0 min-w-0 flex-1">{chatSlot}</div>
@@ -131,7 +137,7 @@ export function SessionWorkspaceShell({
       )}
 
       {hasPreviewSlot && (
-        <div className="flex min-w-0 flex-1 flex-col overflow-hidden bg-paper">
+        <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden bg-paper">
           {rightHeaderSlot}
           <div className="min-h-0 flex-1 overflow-hidden">{previewSlot}</div>
         </div>

package/src/ui/chrome/ErrorCard.tsx

@@ -1,25 +1,20 @@
 import { AlertCircle, RefreshCw } from 'lucide-react';
 
+import { getUserFacingErrorMessage } from '../../lib/biome-host/errors';
 import { Button } from '../primitives/button';
 import { Card, CardContent } from '../primitives/card';
 
 /**
- * Host-agnostic error formatter. The host shell owns rich error decoding
- * (Orval envelopes, workflow error codes, …); pass its formatter via
- * `formatError` to preserve that behaviour. The default extracts a plain
- * message and is safe in any consumer.
+ * Host-agnostic error formatter. The default is the canonical, envelope-aware
+ * {@link getUserFacingErrorMessage} decoder — biomes get rich error copy with
+ * zero wiring. Pass `formatError` only to override with a host-specific decoder
+ * (extra codes, i18n); the canonical default already handles Orval envelopes,
+ * `ApiClientError`, workflow error codes, and "failed to fetch".
  */
 export type ErrorMessageFormatter = (error: unknown, fallback: string) => string;
 
-const defaultFormatError: ErrorMessageFormatter = (error, fallback) => {
-  if (typeof error === 'string') {
-    return error || fallback;
-  }
-  if (error instanceof Error && error.message) {
-    return error.message;
-  }
-  return fallback;
-};
+const defaultFormatError: ErrorMessageFormatter = (error, fallback) =>
+  getUserFacingErrorMessage(error, fallback);
 
 interface ErrorCardProps {
   error: Error | string | unknown;