@xemahq/ui-kernel 0.1.12 → 0.3.0

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/lib/capabilities/capability-provider.tsx

@@ -0,0 +1,95 @@
+import { useQuery } from '@tanstack/react-query';
+import { createContext, useContext, type ReactNode } from 'react';
+
+import { useHostBridge } from '../biome-host/host-bridge';
+
+import type { CapabilityPort, MeCapabilitiesSnapshot } from './types';
+
+/**
+ * The value exposed by {@link CapabilityProvider} through React context.
+ * `snapshot` is `undefined` until the first successful fetch; `isLoading`
+ * and `error` let callers distinguish "still unknown" and "fetch failed"
+ * from "explicitly denied" — the gate hook must NOT treat an errored fetch
+ * as "no capabilities".
+ */
+export interface CapabilityContextValue {
+  readonly snapshot: MeCapabilitiesSnapshot | undefined;
+  readonly isLoading: boolean;
+  readonly error: unknown;
+}
+
+const CapabilityContext = createContext<CapabilityContextValue | null>(null);
+CapabilityContext.displayName = 'CapabilityContext';
+
+/**
+ * Stable query-key root for the capability snapshot. Folded with the active
+ * org so each org caches independently and a re-fetch fires when the org
+ * changes — same tenant-isolation discipline as `useScopedQuery`.
+ */
+const CAPABILITIES_QUERY_ROOT = ['xema', 'capabilities', 'me'] as const;
+
+export interface CapabilityProviderProps {
+  readonly children: ReactNode;
+  /**
+   * Override the host-provided port. Defaults to `bridge.capabilities`. Exists
+   * for tests and for hosts that compose the provider outside a bridge subtree;
+   * production wiring reads it OFF the bridge so biomes need no extra prop.
+   */
+  readonly port?: CapabilityPort;
+  /**
+   * Override the active org. Defaults to `null` (the host's
+   * currently-selected org). When provided, the port is asked for that org and
+   * the cache key includes it.
+   */
+  readonly orgId?: string | null;
+}
+
+/**
+ * Fetches the caller's server-authoritative capability set once per active org
+ * and exposes it (plus loading/error) to descendants via React context.
+ *
+ * Wiring: the {@link CapabilityPort} is read OFF `HostBridge.capabilities`
+ * (not prop-drilled) — the same decoupling the rest of the kernel uses to
+ * reach the host. The active org is read from the bridge's auth source. The
+ * bridge's `QueryClient` (TanStack Query) owns caching/refetch; the kernel
+ * rolls no bespoke state. The query re-runs when the org changes because the
+ * org is part of the query key.
+ *
+ * Rendering is fail-soft (callers can show a loading state), but failures are
+ * SURFACED via `error` rather than masquerading as an empty capability set.
+ */
+export function CapabilityProvider(props: CapabilityProviderProps): JSX.Element {
+  const bridge = useHostBridge();
+  const port = props.port ?? bridge.capabilities;
+  const orgId = props.orgId !== undefined ? props.orgId : bridge.auth.getOrgId();
+
+  const query = useQuery<MeCapabilitiesSnapshot>({
+    queryKey: [...CAPABILITIES_QUERY_ROOT, orgId],
+    queryFn: () => port.list(orgId ? { orgId } : undefined),
+  });
+
+  const value: CapabilityContextValue = {
+    snapshot: query.data,
+    isLoading: query.isLoading,
+    error: query.error,
+  };
+
+  return <CapabilityContext.Provider value={value}>{props.children}</CapabilityContext.Provider>;
+}
+
+/**
+ * Internal accessor for the capability context. Throws fail-fast if used
+ * outside {@link CapabilityProvider} — a missing provider is a wiring bug,
+ * not a "deny everything" condition.
+ */
+export function useCapabilityContext(): CapabilityContextValue {
+  const ctx = useContext(CapabilityContext);
+  if (!ctx) {
+    throw new Error(
+      '[xema-ui-kernel] useCapability()/useCapabilities() called outside ' +
+        '<CapabilityProvider>. The host (or biome shell) must mount the ' +
+        'capability provider above any capability-gated subtree.',
+    );
+  }
+  return ctx;
+}

package/src/lib/capabilities/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Host-agnostic capabilities SDK for `@xemahq/ui-kernel`.
+ *
+ * Lets a biome UI gate on SERVER-AUTHORITATIVE capabilities (the caller's
+ * effective set from `GET /bff/me/capabilities`) instead of cosmetic role
+ * booleans. The kernel defines the contract and the React surface; it never
+ * fetches — the HOST implements {@link CapabilityPort} (hung off
+ * `HostBridge.capabilities`) and maps its Orval client response onto the
+ * local {@link MeCapabilitiesSnapshot} shape.
+ *
+ * Biome usage:
+ *   import { CapabilityProvider, useCapability } from '@xemahq/ui-kernel';
+ */
+export * from './types';
+export * from './capability-provider';
+export * from './use-capability';

package/src/lib/capabilities/types.ts

@@ -0,0 +1,69 @@
+import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
+
+/**
+ * One server-authoritative capability the caller holds, mirroring the
+ * FROZEN `GET /bff/me/capabilities` wire entry.
+ *
+ * These types are defined LOCALLY in the kernel — deliberately NOT imported
+ * from a backend DTO or an Orval client — so `@xemahq/ui-kernel` stays
+ * host-agnostic (no fetch lib, no generated client). The concrete host
+ * (`submodules/xema-host-web`) maps its client response onto this shape when
+ * it implements {@link CapabilityPort}.
+ */
+export interface CapabilityEntry {
+  /**
+   * The capability reference (e.g. `capability:session.launch`). Matched
+   * verbatim by {@link useCapability}; the kernel does not parse it.
+   */
+  readonly ref: string;
+  /**
+   * The execution environments in which the caller holds this capability.
+   * A gate that names an `environment` is allowed only if it appears here.
+   */
+  readonly environments: ExecutionEnvironmentKind[];
+  /**
+   * When `true`, holding the capability still requires a human approval step
+   * before the side-effect runs — so a UI affordance should route through the
+   * approval flow rather than acting directly.
+   */
+  readonly approvalRequired: boolean;
+}
+
+/**
+ * The caller's effective capability set for one active org, mirroring the
+ * FROZEN `MeCapabilitiesResponse` wire shape.
+ */
+export interface MeCapabilitiesSnapshot {
+  /** The subject (user) the snapshot was resolved for. */
+  readonly subjectId: string;
+  /** The org the snapshot is scoped to. */
+  readonly orgId: string;
+  /** Every capability the subject effectively holds in this org. */
+  readonly capabilities: CapabilityEntry[];
+}
+
+/**
+ * Host-implemented port that fetches the caller's effective capability set.
+ *
+ * The kernel never calls an API directly — the HOST implements this against
+ * its Orval client (`GET /bff/me/capabilities`) and maps the response onto
+ * {@link MeCapabilitiesSnapshot}. The implementation is hung off
+ * {@link HostBridge.capabilities}; {@link CapabilityProvider} reads it from
+ * the bridge and uses the bridge's `QueryClient` for caching/refetch.
+ */
+export interface CapabilityPort {
+  /**
+   * Return the caller's effective capability set for the active org.
+   *
+   * @param options.orgId The org to resolve for. When omitted the host
+   *   resolves against its currently-selected org.
+   * @param options.environment Optional environment hint the host MAY pass to
+   *   the backend to narrow the set. Callers gate by environment client-side
+   *   via {@link useCapability}, so a host MAY ignore this and return the full
+   *   set; it exists so a host can request a pre-filtered snapshot.
+   */
+  list(options?: {
+    orgId?: string;
+    environment?: ExecutionEnvironmentKind;
+  }): Promise<MeCapabilitiesSnapshot>;
+}

package/src/lib/capabilities/use-capability.ts

@@ -0,0 +1,72 @@
+import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
+
+import { useCapabilityContext, type CapabilityContextValue } from './capability-provider';
+import type { MeCapabilitiesSnapshot } from './types';
+
+export interface UseCapabilityOptions {
+  /**
+   * Gate against a specific execution environment. When set, the capability
+   * counts only if the snapshot lists it for this environment.
+   */
+  readonly environment?: ExecutionEnvironmentKind;
+}
+
+export interface CapabilityDecision {
+  /**
+   * `true` only when the caller holds the capability, holds it in the named
+   * environment (if one was given), AND it does NOT require approval. A gate
+   * that should let the user act directly checks this.
+   */
+  readonly allowed: boolean;
+  /**
+   * `true` when the caller holds the capability (in the named environment, if
+   * given) but it requires a human approval step first — render the
+   * approval-routed affordance instead of acting directly.
+   */
+  readonly approvalRequired: boolean;
+  /** The snapshot is still being fetched; treat as "unknown", not "denied". */
+  readonly isLoading: boolean;
+  /** The fetch failed; surfaced so callers never conflate failure with denial. */
+  readonly error: unknown;
+}
+
+/**
+ * Server-authoritative capability gate.
+ *
+ * Resolves `ref` against the cached {@link CapabilityProvider} snapshot:
+ * - `allowed`  = entry exists AND (no environment asked OR listed for it) AND NOT approvalRequired.
+ * - `approvalRequired` = entry exists AND (no environment asked OR listed for it) AND approvalRequired.
+ *
+ * While the snapshot is loading, `allowed` is `false` and `isLoading` is
+ * `true` — callers gate on `isLoading` to distinguish "unknown" from "denied".
+ * On error, `allowed` is `false` and `error` is set; the hook never silently
+ * degrades a failed fetch into a confident denial.
+ */
+export function useCapability(ref: string, opts?: UseCapabilityOptions): CapabilityDecision {
+  const { snapshot, isLoading, error } = useCapabilityContext();
+
+  const entry = snapshot?.capabilities.find((c) => c.ref === ref);
+  const inEnvironment =
+    !!entry && (!opts?.environment || entry.environments.includes(opts.environment));
+
+  return {
+    allowed: inEnvironment && !entry.approvalRequired,
+    approvalRequired: inEnvironment && entry.approvalRequired,
+    isLoading,
+    error,
+  };
+}
+
+/**
+ * Accessor for the raw capability snapshot plus its loading/error state.
+ * Use when a component needs to enumerate capabilities rather than gate on a
+ * single `ref`.
+ */
+export function useCapabilities(): {
+  snapshot: MeCapabilitiesSnapshot | undefined;
+  isLoading: boolean;
+  error: unknown;
+} {
+  const ctx: CapabilityContextValue = useCapabilityContext();
+  return { snapshot: ctx.snapshot, isLoading: ctx.isLoading, error: ctx.error };
+}

package/src/ui/chrome/AsyncBoundary.tsx

@@ -0,0 +1,66 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import ErrorCard, { type ErrorMessageFormatter } from './ErrorCard';
+import EmptyState from './EmptyState';
+import LoadingState, { type LoadingStateVariant } from './LoadingState';
+
+interface AsyncBoundaryEmpty {
+  icon: LucideIcon;
+  title: string;
+  description?: ReactNode;
+}
+
+interface AsyncBoundaryProps {
+  /** Async in flight — renders the loading affordance. */
+  isLoading: boolean;
+  /** Resolved error, if any — renders an `ErrorCard`. */
+  error?: Error | string | unknown | null;
+  /**
+   * When true, the resolved data is empty — renders an `EmptyState`. Only
+   * checked when `empty` config is supplied; otherwise children render.
+   */
+  isEmpty?: boolean;
+  /** Empty-state config; omit to never render an empty state. */
+  empty?: AsyncBoundaryEmpty;
+  /** Retry handler threaded to `ErrorCard`. */
+  onRetry?: () => void;
+  /** Loading affordance variant. */
+  loadingVariant?: LoadingStateVariant;
+  /** Host error decoder threaded to `ErrorCard`. */
+  formatError?: ErrorMessageFormatter;
+  children: ReactNode;
+}
+
+/**
+ * Declarative loading / error / empty wrapper. Collapses the
+ * `if (isLoading) … if (error) … if (empty) … else children` ladder that
+ * every biome list/detail surface re-implements into one component built on
+ * the shared `LoadingState` / `ErrorCard` / `EmptyState` primitives.
+ *
+ * Precedence: loading → error → empty → children.
+ */
+export default function AsyncBoundary({
+  isLoading,
+  error,
+  isEmpty,
+  empty,
+  onRetry,
+  loadingVariant,
+  formatError,
+  children,
+}: Readonly<AsyncBoundaryProps>) {
+  if (isLoading) {
+    return <LoadingState variant={loadingVariant} />;
+  }
+
+  if (error) {
+    return <ErrorCard error={error} onRetry={onRetry} formatError={formatError} />;
+  }
+
+  if (isEmpty && empty) {
+    return <EmptyState icon={empty.icon} title={empty.title} description={empty.description} />;
+  }
+
+  return <>{children}</>;
+}

package/src/ui/chrome/EmptyState.tsx

@@ -0,0 +1,184 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ComponentType, ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Button } from '../primitives/button';
+import { Card, CardContent } from '../primitives/card';
+
+export type EmptyStateVariant = 'not-configured' | 'no-results' | 'disabled-context';
+
+/**
+ * Visual density.
+ *  - `comfortable` (default): hero empty state for full-page surfaces —
+ *    big 64px icon, generous padding, hero copy. Use when the page has
+ *    nothing else to render.
+ *  - `dense`: inline empty state for surfaces nested inside other
+ *    content (tabs, sub-panels). Smaller icon, tighter padding, no
+ *    dashed card frame — reads as a calm placeholder, not a banner.
+ *  - `inline`: single-line text-only message, no icon, no card. Use
+ *    inside list sub-sections where even the dense frame is too much.
+ */
+export type EmptyStateSize = 'comfortable' | 'dense' | 'inline';
+
+/**
+ * Polymorphic link element. The host shell renders Next.js `<Link>`;
+ * pass it via `linkComponent` to get client-side routing. Defaults to a
+ * plain anchor so the primitive stays host-framework-agnostic.
+ */
+export type EmptyStateLinkComponent = ComponentType<{
+  href: string;
+  children: ReactNode;
+}>;
+
+const DefaultLink: EmptyStateLinkComponent = ({ href, children }) => (
+  <a href={href}>{children}</a>
+);
+
+interface EmptyStateAction {
+  label: string;
+  onClick: () => void;
+  icon?: LucideIcon;
+}
+
+interface EmptyStateSecondaryAction {
+  label: string;
+  href: string;
+}
+
+interface EmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  description?: ReactNode;
+  /** Optional illustration or extra content above the title */
+  illustration?: ReactNode;
+  /** Visual variant — drives default iconBg/iconColor unless overridden. */
+  variant?: EmptyStateVariant;
+  size?: EmptyStateSize;
+  /** Icon tint — overrides variant defaults */
+  iconBg?: string;
+  iconColor?: string;
+  action?: EmptyStateAction;
+  secondaryAction?: EmptyStateSecondaryAction;
+  /** Host link component for `secondaryAction.href` (defaults to `<a>`). */
+  linkComponent?: EmptyStateLinkComponent;
+  className?: string;
+}
+
+const VARIANT_DEFAULTS: Record<EmptyStateVariant, { iconBg: string; iconColor: string }> = {
+  'not-configured': { iconBg: 'bg-info/10', iconColor: 'text-info' },
+  'no-results': { iconBg: 'bg-warning/10', iconColor: 'text-warning' },
+  'disabled-context': { iconBg: 'bg-muted', iconColor: 'text-ink-3' },
+};
+
+export default function EmptyState({
+  icon: Icon,
+  title,
+  description,
+  illustration,
+  variant = 'not-configured',
+  size = 'comfortable',
+  iconBg,
+  iconColor,
+  action,
+  secondaryAction,
+  linkComponent,
+  className,
+}: Readonly<EmptyStateProps>) {
+  const Link = linkComponent ?? DefaultLink;
+  const defaults = VARIANT_DEFAULTS[variant];
+  const resolvedIconBg = iconBg ?? defaults.iconBg;
+  const resolvedIconColor = iconColor ?? defaults.iconColor;
+
+  if (size === 'inline') {
+    return (
+      <div className={cn('flex items-center justify-center px-3 py-6 text-center text-body-2 text-ink-4', className)}>
+        <div className="max-w-sm space-y-1">
+          <p className="text-ink-3">{title}</p>
+          {description && <p className="text-ink-4">{description}</p>}
+          {(action || secondaryAction) && (
+            <div className="mt-3 flex items-center justify-center gap-2">
+              {action && (
+                <Button size="sm" variant="outline" onClick={action.onClick} className="h-7 gap-1.5 text-body-2">
+                  {action.icon && <action.icon className="h-3.5 w-3.5" />}
+                  {action.label}
+                </Button>
+              )}
+              {secondaryAction && (
+                <Button asChild size="sm" variant="ghost" className="h-7 px-2 text-body-2">
+                  <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+                </Button>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (size === 'dense') {
+    return (
+      <div
+        className={cn(
+          'flex flex-col items-center justify-center px-4 py-8 text-center',
+          className,
+        )}
+      >
+        {illustration ?? (
+          <div className={cn('h-9 w-9 rounded-xl flex items-center justify-center mb-3', resolvedIconBg)}>
+            <Icon className={cn('h-4 w-4', resolvedIconColor)} />
+          </div>
+        )}
+        <p className="text-body-1 font-semibold text-ink">{title}</p>
+        {description && (
+          <p className="mt-1 max-w-md text-body-2 leading-snug text-ink-3">{description}</p>
+        )}
+        {(action || secondaryAction) && (
+          <div className="mt-3 flex items-center gap-2">
+            {action && (
+              <Button size="sm" variant="outline" onClick={action.onClick} className="h-7 gap-1.5 text-body-2">
+                {action.icon && <action.icon className="h-3.5 w-3.5" />}
+                {action.label}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button asChild size="sm" variant="ghost" className="h-7 px-2 text-body-2">
+                <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <Card className={cn('border-2 border-dashed border-border/50 rounded-xl', className)}>
+      <CardContent className="flex flex-col items-center justify-center py-16 text-center">
+        {illustration ?? (
+          <div className={`h-16 w-16 rounded-2xl flex items-center justify-center mb-5 ${resolvedIconBg}`}>
+            <Icon className={`h-7 w-7 ${resolvedIconColor}`} />
+          </div>
+        )}
+        <p className="text-subtitle font-semibold text-ink">{title}</p>
+        {description && (
+          <p className="text-body-1 mt-2 max-w-sm text-ink-3 leading-relaxed">{description}</p>
+        )}
+        {(action || secondaryAction) && (
+          <div className="mt-6 flex items-center gap-3">
+            {action && (
+              <Button size="sm" variant="outline" onClick={action.onClick} className="gap-2 h-10 px-5">
+                {action.icon && <action.icon className="h-4 w-4" />}
+                {action.label}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button asChild size="sm" variant="ghost" className="h-10 px-3">
+                <Link href={secondaryAction.href}>{secondaryAction.label}</Link>
+              </Button>
+            )}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/ui/chrome/ErrorCard.tsx

@@ -0,0 +1,63 @@
+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 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) =>
+  getUserFacingErrorMessage(error, fallback);
+
+interface ErrorCardProps {
+  error: Error | string | unknown;
+  title?: string;
+  onRetry?: () => void;
+  /**
+   * Optional host error-decoder. Defaults to a plain message extractor.
+   * The host shell should pass `getUserFacingErrorMessage` to keep its
+   * envelope-aware messaging.
+   */
+  formatError?: ErrorMessageFormatter;
+  fallbackMessage?: string;
+}
+
+export default function ErrorCard({
+  error,
+  title = 'Something went wrong',
+  onRetry,
+  formatError = defaultFormatError,
+  fallbackMessage = 'Unable to load this content right now.',
+}: ErrorCardProps) {
+  const message = formatError(error, fallbackMessage);
+
+  return (
+    <Card className="border-destructive/25 bg-destructive/[0.03] rounded-xl">
+      <CardContent className="flex flex-col items-center py-14 text-center">
+        <div className="h-14 w-14 rounded-2xl bg-destructive/10 flex items-center justify-center mb-4">
+          <AlertCircle className="h-6 w-6 text-destructive" />
+        </div>
+        <p className="text-subtitle font-semibold text-ink">{title}</p>
+        <p className="text-body-1 text-ink-3 mt-2 max-w-md leading-relaxed">{message}</p>
+        {onRetry && (
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={onRetry}
+            className="mt-5 gap-2 h-10 border-destructive/20 text-destructive hover:bg-destructive/5"
+          >
+            <RefreshCw className="h-4 w-4" />
+            Retry
+          </Button>
+        )}
+      </CardContent>
+    </Card>
+  );
+}