@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/lib/biome-host/define-web-biome.spec.ts

@@ -1,221 +0,0 @@
-/**
- * `defineWebBiome` — define-time scope/access locking, the fail-closed
- * defaults, and closed-set completeness.
- *
- * This suite replaces an earlier `define-web-biome.test.js` written for
- * Node's test runner against `dist/`. That file ran NOWHERE: the package's
- * `test` script is a notice (the kernel carries no test runner by design) and
- * the host-web vitest `include` is `*.{test,spec}.{ts,tsx}` — so a `.js` file
- * was invisible to both. A security test that never executes reads as
- * coverage while proving nothing, so it is gone; this vitest spec is synced
- * into the host mirror by the frontend bridge and runs there with everything
- * else.
- *
- * The invariant under test is the security one: a route is public ONLY when
- * its author said so twice, explicitly. Nothing defaulted, inferred, or
- * coerced can produce a public route.
- */
-import { describe, expect, it } from 'vitest';
-
-import { defineWebBiome } from './define-web-biome';
-import {
-  PAGE_CHROME_VALUES,
-  ROUTE_ACCESS_VALUES,
-  ROUTE_SCOPE_VALUES,
-  type PageChrome,
-  type RouteAccess,
-  type RouteScope,
-} from './frontend-biome';
-
-import type { HostBridge } from './host-bridge';
-
-const load = () => Promise.resolve({ default: () => null });
-const bridge = {} as HostBridge;
-
-describe('defineWebBiome — public/chromeless scope', () => {
-  it('rejects a public page whose access defaults to member', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
-      }),
-    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
-  });
-
-  it('rejects a public page with an explicit non-public access tier', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [
-          {
-            slug: 'ext/:id',
-            label: 'Ext',
-            scope: 'public',
-            access: 'org-admin',
-            load,
-          },
-        ],
-      }),
-    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
-  });
-
-  it('rejects a non-public page that declares access public', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
-      }),
-    ).toThrow(/access: 'public' is only valid on a 'public' scope page/);
-  });
-
-  it('accepts a public + access:public page and emits no nav item', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        {
-          slug: 'ext/:id',
-          label: 'Ext',
-          scope: 'public',
-          access: 'public',
-          load,
-        },
-      ],
-    })(bridge);
-
-    expect(biome.routes).toHaveLength(1);
-    const route = biome.routes?.[0];
-    expect(route?.path).toBe('ext/:id');
-    expect(route?.access).toBe('public');
-    expect(route?.projectScoped).toBe(false);
-    // A public route is un-authenticated; it never belongs in the authed rail.
-    expect(biome.navItems).toHaveLength(0);
-  });
-
-  it('chrome defaults to host and none passes through', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        { slug: 'system/a', label: 'A', load },
-        { slug: 'system/b', label: 'B', chrome: 'none', load },
-      ],
-    })(bridge);
-
-    expect(biome.routes?.find((r) => r.path === 'system/a')?.chrome).toBe(
-      'host',
-    );
-    expect(biome.routes?.find((r) => r.path === 'system/b')?.chrome).toBe(
-      'none',
-    );
-  });
-});
-
-describe('defineWebBiome — public is opt-in, never a default', () => {
-  /**
-   * THE fail-closed invariant. An ordinarily-declared page (no `scope`, no
-   * `access`) must emit a route that carries NO `access` marker at all — the
-   * host then applies its own `member` default. If the kernel ever started
-   * defaulting `access` (or `scope`) to `'public'`, every existing biome route
-   * in the fleet would silently become reachable without a session.
-   *
-   * Mutation-proof (recorded 2026-07-22): flipping the emit in
-   * `defineWebBiome` to `access: page.access ?? 'public'` turns this test RED
-   * ("expected 'public' to be undefined"), and flipping the validator default
-   * `page.access ?? 'member'` to `?? 'public'` makes the ordinary page throw
-   * at define time — RED in this test and in the two below. There is no
-   * mutation of a default that makes a route public and keeps the suite green.
-   */
-  it('an ordinary page emits NO access marker (host defaults to member)', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [{ slug: 'system/a', label: 'A', load }],
-    })(bridge);
-
-    const route = biome.routes?.[0];
-    expect(route?.access).toBeUndefined();
-    expect(route?.projectScoped).toBe(false);
-    // …and it DOES contribute a nav item, unlike a public route.
-    expect(biome.navItems).toHaveLength(1);
-  });
-
-  it('an authenticated page can be chromeless without becoming public', () => {
-    // Chrome and access are orthogonal axes: the embedded-app case.
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        {
-          slug: 'apps/:appId/embed',
-          label: 'Embedded app',
-          chrome: 'none',
-          navHidden: true,
-          load,
-        },
-      ],
-    })(bridge);
-
-    const route = biome.routes?.[0];
-    expect(route?.chrome).toBe('none');
-    expect(route?.access).toBeUndefined();
-  });
-
-  it('every non-public access tier is rejected on a public page', () => {
-    for (const access of ROUTE_ACCESS_VALUES.filter((a) => a !== 'public')) {
-      expect(() =>
-        defineWebBiome({
-          id: 'test-biome',
-          displayName: 'Test',
-          pages: [{ slug: 'ext', label: 'Ext', scope: 'public', access, load }],
-        }),
-      ).toThrow(/MUST declare access: 'public'/);
-    }
-  });
-
-  it('every non-public scope rejects access public', () => {
-    for (const scope of ROUTE_SCOPE_VALUES.filter((s) => s !== 'public')) {
-      expect(() =>
-        defineWebBiome({
-          id: 'test-biome',
-          displayName: 'Test',
-          pages: [{ slug: 'x', label: 'X', scope, access: 'public', load }],
-        }),
-      ).toThrow(/only valid on a 'public' scope page/);
-    }
-  });
-});
-
-describe('closed-set completeness', () => {
-  /**
-   * The runtime tuples ARE the types (`RouteAccess = typeof
-   * ROUTE_ACCESS_VALUES[number]`), so a new member cannot be added to the type
-   * without appearing here — which is what makes the exhaustive iteration in
-   * this file, and the host resolver's `default`-less switch, complete by
-   * construction. These assertions are the compile-time proof made executable:
-   * the `satisfies` widening below fails to compile if a tuple ever drifts
-   * from its type.
-   */
-  it('the access tuple enumerates exactly the RouteAccess union', () => {
-    const all: readonly RouteAccess[] =
-      ROUTE_ACCESS_VALUES satisfies readonly RouteAccess[];
-    expect([...all].sort()).toEqual(
-      ['member', 'org-admin', 'platform-admin', 'public'].sort(),
-    );
-  });
-
-  it('the scope tuple enumerates exactly the RouteScope union', () => {
-    const all: readonly RouteScope[] =
-      ROUTE_SCOPE_VALUES satisfies readonly RouteScope[];
-    expect([...all].sort()).toEqual(['org', 'project', 'public'].sort());
-  });
-
-  it('the chrome tuple enumerates exactly the PageChrome union', () => {
-    const all: readonly PageChrome[] =
-      PAGE_CHROME_VALUES satisfies readonly PageChrome[];
-    expect([...all].sort()).toEqual(['host', 'none'].sort());
-  });
-});

package/src/lib/biome-host/define-web-biome.ts

@@ -1,222 +0,0 @@
-/**
- * `defineWebBiome` — the authoring helper for `target: 'web'` biomes.
- *
- * Every web biome used to hand-repeat the same ~30 lines: one
- * `lazy(() => import('./pages/X'))` per page, a `navItems` array, and a
- * parallel `routes` array — writing the slug TWICE (once as `navItem.route`,
- * once as `route.path`), the classic source of "nav points at a path no route
- * serves" bugs.
- *
- * `defineWebBiome` collapses that to one declarative page list. Each
- * {@link WebBiomePage} single-sources its `slug` for BOTH the nav route and the
- * route path, so they can never drift. The helper emits one nav item (unless
- * `navHidden`) and one route per page, wrapping the lazily-loaded page in a
- * `<Suspense fallback={null}>` boundary via {@link lazyRoute}.
- *
- * Authors declare WHAT each surface is (`category`) and let the HOST own WHERE
- * it renders in the global menu. `init`/`dispose`/`panels`/`session`/
- * `outputRenderers` pass through to the `FrontendBiome` untouched, so bespoke
- * biomes (one-shot registrations, slot fillers, session contributions) still
- * use this helper.
- *
- * Host-framework-agnostic: pure React (`lazy`/`Suspense`/`createElement` via
- * `lazyRoute`), no router and no Next.js.
- *
- * @example
- *   export default defineWebBiome({
- *     id: 'spaces-web',
- *     displayName: 'Spaces',
- *     pages: [
- *       {
- *         slug: 'system/spaces',
- *         label: 'Spaces',
- *         icon: Layers,
- *         category: 'knowledge',
- *         load: () => import('./pages/SpacesPage'),
- *       },
- *     ],
- *   });
- */
-
-import { lazyRoute } from './biome-builders';
-
-import type {
-  FrontendBiome,
-  FrontendBiomeFactory,
-  NavItemContribution,
-  PageChrome,
-  RouteAccess,
-  RouteContribution,
-  RouteScope,
-} from './frontend-biome';
-import type { ComponentType } from 'react';
-
-export interface WebBiomePage {
-  /**
-   * Single source of truth for BOTH the nav route AND the route path — the
-   * helper sets `navItem.route === route.path === slug`, so they can never
-   * diverge. May include `:param` segments (e.g. `system/concepts/:slug`).
-   */
-  readonly slug: string;
-  /**
-   * Stable nav-item id used for active-state matching + analytics. Defaults to
-   * {@link slug} when omitted — pass it explicitly only to preserve a
-   * pre-existing short id (e.g. `grants`) that differs from the route slug
-   * (`system/grants`). Must be unique across the biome's pages.
-   */
-  readonly id?: string;
-  /** Displayed nav label. */
-  readonly label: string;
-  /** Optional nav icon. Typed to match {@link NavItemContribution.icon}. */
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  /**
-   * Host menu category — the biome's INTENT (`primary` | `build` | `operate` |
-   * `knowledge` | `admin` | `account`). The host maps it to a concrete rail
-   * group + order.
-   */
-  readonly category?: string;
-  /**
-   * Route scope. `'org'` (default) mounts at the org root; `'project'` mounts
-   * under the canonical project-scoped route prefix; `'public'` mounts OUTSIDE
-   * the host's authenticated group (no Keycloak session, no login redirect, no
-   * org switcher). Maps to {@link RouteContribution.projectScoped} for the
-   * authenticated scopes; a `'public'` page MUST also declare
-   * `access: 'public'` (enforced at define time).
-   */
-  readonly scope?: RouteScope;
-  /**
-   * Access tier required to render the route. Defaults to `'member'`. A
-   * `'public'` page (scope `'public'`) MUST set this to `'public'`; a non-public
-   * page MUST NOT — both contradictions are rejected at define time.
-   */
-  readonly access?: RouteAccess;
-  /**
-   * Whether the host wraps the page in its application shell. Defaults to
-   * `'host'`; `'none'` renders with no app rail, topbar, or org switcher.
-   */
-  readonly chrome?: PageChrome;
-  /** Dynamic import of the page module (`() => import('./pages/X')`). */
-  readonly load: () => Promise<{ default: ComponentType<unknown> }>;
-  /**
-   * When true the route is registered but NO nav item is emitted — for hidden
-   * surfaces such as a `:param` detail route reached only by deeplink.
-   */
-  readonly navHidden?: boolean;
-}
-
-export interface DefineWebBiomeOptions {
-  /** Stable biome id; matches `xema-biome.json` `xema.id`. */
-  readonly id: string;
-  /** Displayed name. */
-  readonly displayName: string;
-  /** One-shot initializer; passed through to {@link FrontendBiome.init}. */
-  readonly init?: FrontendBiome['init'];
-  /** Teardown counterpart; passed through to {@link FrontendBiome.dispose}. */
-  readonly dispose?: FrontendBiome['dispose'];
-  /** The biome's pages — one nav item (unless `navHidden`) + one route each. */
-  readonly pages: readonly WebBiomePage[];
-  /** Slot fillers; passed through to {@link FrontendBiome.panels}. */
-  readonly panels?: FrontendBiome['panels'];
-  /** Session-shell contributions; passed through to {@link FrontendBiome.session}. */
-  readonly session?: FrontendBiome['session'];
-  /** Output renderers; passed through to {@link FrontendBiome.outputRenderers}. */
-  readonly outputRenderers?: FrontendBiome['outputRenderers'];
-}
-
-/** Default host-shell mode a page renders in when it omits `chrome`. */
-const DEFAULT_PAGE_CHROME: PageChrome = 'host';
-
-/**
- * Reject the two `scope`/`access` contradictions at define time (module load,
- * when the biome calls `defineWebBiome(...)` at its top level) — fail fast, do
- * NOT silently coerce:
- *
- *   1. A `public` page with any `access` other than `'public'`: a public route
- *      is un-authenticated, so a privilege tier is meaningless. The author must
- *      set `access: 'public'` explicitly (an omitted `access` defaults to
- *      `'member'`, which is exactly this contradiction).
- *   2. A non-`public` page declaring `access: 'public'`: `'public'` is the
- *      no-auth marker; an org/project route is always authenticated.
- *
- * `scope` defaults to `'org'` and `access` defaults to `'member'` for the
- * purpose of this check, matching the emit defaults below.
- */
-function assertPageScopeAccessLocked(biomeId: string, page: WebBiomePage): void {
-  const scope: RouteScope = page.scope ?? 'org';
-  const access: RouteAccess = page.access ?? 'member';
-  const where = `web biome '${biomeId}' page '${page.slug}'`;
-
-  if (scope === 'public' && access !== 'public') {
-    throw new Error(
-      `${where}: a 'public' scope page MUST declare access: 'public' ` +
-        `(got access: '${access}'). A public route is un-authenticated, so an ` +
-        `authenticated privilege tier is a contradiction. Set access: 'public' ` +
-        `or change the scope.`,
-    );
-  }
-  if (scope !== 'public' && access === 'public') {
-    throw new Error(
-      `${where}: access: 'public' is only valid on a 'public' scope page ` +
-        `(got scope: '${scope}'). '${access}' is the no-auth marker; an ` +
-        `org/project route is always authenticated. Set scope: 'public' or ` +
-        `change the access tier.`,
-    );
-  }
-}
-
-/**
- * Build the `FrontendBiomeFactory` a web biome default-exports. See the
- * module doc-comment for the rationale and an example.
- */
-export function defineWebBiome(
-  options: DefineWebBiomeOptions,
-): FrontendBiomeFactory {
-  // Validate every page's scope/access pairing NOW, at module load, so a
-  // contradiction surfaces the instant the biome module is imported — not
-  // lazily when the host first calls the factory.
-  for (const page of options.pages) {
-    assertPageScopeAccessLocked(options.id, page);
-  }
-
-  return () => {
-    const navItems: NavItemContribution[] = [];
-    const routes: RouteContribution[] = [];
-
-    for (const page of options.pages) {
-      routes.push({
-        path: page.slug,
-        projectScoped: page.scope === 'project',
-        element: lazyRoute(page.load),
-        chrome: page.chrome ?? DEFAULT_PAGE_CHROME,
-        ...(page.access ? { access: page.access } : {}),
-      });
-
-      // Public routes mount OUTSIDE the authenticated group and never belong in
-      // the authenticated app rail — so they contribute no nav item regardless
-      // of `navHidden`. Authenticated pages emit a nav item unless hidden.
-      if (!page.navHidden && page.scope !== 'public') {
-        navItems.push({
-          id: page.id ?? page.slug,
-          label: page.label,
-          route: page.slug,
-          ...(page.icon ? { icon: page.icon } : {}),
-          ...(page.category !== undefined ? { category: page.category } : {}),
-        });
-      }
-    }
-
-    return {
-      id: options.id,
-      displayName: options.displayName,
-      navItems,
-      routes,
-      ...(options.init ? { init: options.init } : {}),
-      ...(options.dispose ? { dispose: options.dispose } : {}),
-      ...(options.panels ? { panels: options.panels } : {}),
-      ...(options.session ? { session: options.session } : {}),
-      ...(options.outputRenderers
-        ? { outputRenderers: options.outputRenderers }
-        : {}),
-    };
-  };
-}

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

@@ -1,220 +0,0 @@
-/**
- * Canonical user-facing error decoder — ONE implementation biomes, the host
- * shell, and the kernel's {@link ErrorCard} default all share.
- *
- * Biomes were each re-implementing "pull a human message off an error"
- * (envelope shapes, status-code copy, "failed to fetch"). This is the single
- * host-agnostic decoder. It is a PURE function: no fetch, no i18n, no config,
- * no `instanceof` against host classes. It recognises the two error shapes the
- * Xema frontend produces by their structural signature:
- *
- *   - the host's `ApiClientError` (`name === 'ApiClientError'`, `statusCode`,
- *     `message`, optional `errorType`), thrown by the hand-rolled HTTP client;
- *   - Orval's generated `ClientError` (`name === 'ClientError'`, `status`,
- *     `message`, `body`), thrown by the generated clients. Its `body` carries
- *     the backend `{ message, code, details }` envelope (and the workflow
- *     wallet-missing / `session_busy` special cases).
- *
- * Hosts that previously kept their own `getUserFacingErrorMessage` should
- * re-export THIS one (or delete theirs and import it) so there is a single
- * decoder. {@link ErrorCard} defaults to it, so biomes get envelope-aware copy
- * without wiring anything.
- */
-
-function collapseWhitespace(value: string): string {
-  return value.split(/\s+/).join(' ').trim();
-}
-
-function getGenericErrorMessage(message: string, fallback: string): string {
-  const normalized = collapseWhitespace(message);
-  if (/failed to fetch/i.test(normalized)) {
-    return 'Could not reach the service. Check your connection and try again.';
-  }
-  return normalized || fallback;
-}
-
-function normalizeValidationMessage(rawMessage: string): string {
-  const parts = rawMessage
-    .split(',')
-    .map((part) => collapseWhitespace(part))
-    .filter(Boolean);
-
-  if (parts.length === 0) {
-    return 'Some required fields are missing or invalid. Please review your input and try again.';
-  }
-
-  const preview = parts.slice(0, 2).join('; ');
-  const suffix = parts.length > 2 ? '; and more.' : '.';
-  return `Some required fields are missing or invalid (${preview}${suffix})`;
-}
-
-/** Structural signature of the host's `ApiClientError`. */
-interface ApiClientErrorLike {
-  readonly name: string;
-  readonly statusCode: number;
-  readonly message: string;
-  readonly errorType?: string;
-}
-
-function isApiClientErrorLike(error: unknown): error is ApiClientErrorLike {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const record = error as Record<string, unknown>;
-  return (
-    record['name'] === 'ApiClientError' &&
-    typeof record['statusCode'] === 'number' &&
-    typeof record['message'] === 'string'
-  );
-}
-
-/** Structural signature of an Orval-generated `ClientError`. */
-interface OrvalClientErrorLike {
-  readonly name: string;
-  readonly status: number;
-  readonly message: string;
-  readonly body: unknown;
-}
-
-function isOrvalClientErrorLike(error: unknown): error is OrvalClientErrorLike {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const record = error as Record<string, unknown>;
-  return (
-    record['name'] === 'ClientError' &&
-    typeof record['status'] === 'number' &&
-    typeof record['message'] === 'string' &&
-    Object.hasOwn(record, 'body')
-  );
-}
-
-interface WorkflowErrorEnvelope {
-  readonly code?: string;
-  readonly message?: string;
-  readonly details?: Record<string, unknown>;
-}
-
-function readStringList(value: unknown): string[] | null {
-  if (!Array.isArray(value)) {
-    return null;
-  }
-  if (value.some((entry) => typeof entry !== 'string')) {
-    return null;
-  }
-  return value;
-}
-
-function normalizeWorkflowWalletMissingMessage(envelope: WorkflowErrorEnvelope): string | null {
-  if (envelope.code !== 'WORKFLOW_WALLET_NOT_FOUND') {
-    return null;
-  }
-  const missing = readStringList(envelope.details?.['missing']);
-  if (missing === null || missing.length === 0) {
-    return 'One or more required wallets are missing for this project.';
-  }
-  return `Missing wallet${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. Add ${
-    missing.length > 1 ? 'them' : 'it'
-  } in Project Settings -> Wallets.`;
-}
-
-function getApiClientErrorMessage(error: ApiClientErrorLike, fallback: string): string {
-  if (error.statusCode === 0) {
-    return collapseWhitespace(error.message) || fallback;
-  }
-  if (error.statusCode === 400) {
-    const raw = collapseWhitespace(error.message);
-    if (raw.includes(' must ') || raw.includes('regular expression')) {
-      return normalizeValidationMessage(raw);
-    }
-    return raw || 'The request is invalid. Please check your input and try again.';
-  }
-  if (error.statusCode === 401) {
-    return 'Your session expired. Please sign in again.';
-  }
-  if (error.statusCode === 403) {
-    return 'You do not have permission to perform this action.';
-  }
-  if (error.statusCode === 404) {
-    return 'The requested resource was not found.';
-  }
-  if (error.statusCode >= 500) {
-    return 'The service is temporarily unavailable. Please try again in a moment.';
-  }
-  return collapseWhitespace(error.message) || fallback;
-}
-
-function getOrvalClientErrorMessage(error: OrvalClientErrorLike, fallback: string): string {
-  if (error.status >= 500) {
-    return 'The service is temporarily unavailable. Please try again in a moment.';
-  }
-  // session-api refuses mutations while a prompt turn is in flight; the 409
-  // body is `{ error: 'session_busy', retryAfterTurnDone: true }`. Surface a
-  // clear retry hint instead of the generic "Conflict" copy.
-  if (error.status === 409) {
-    const body = error.body;
-    if (body && typeof body === 'object') {
-      const record = body as Record<string, unknown>;
-      if (record['error'] === 'session_busy') {
-        return 'Your last message is still running. Wait for the agent to finish, then try again.';
-      }
-    }
-  }
-  const body = error.body;
-  if (body && typeof body === 'object') {
-    const record = body as Record<string, unknown>;
-    const payload: WorkflowErrorEnvelope = (() => {
-      const message = record['message'];
-      if (message && typeof message === 'object') {
-        return message;
-      }
-      return {
-        code: typeof record['code'] === 'string' ? record['code'] : undefined,
-        message: typeof record['message'] === 'string' ? record['message'] : undefined,
-        details:
-          record['details'] && typeof record['details'] === 'object'
-            ? (record['details'] as Record<string, unknown>)
-            : undefined,
-      };
-    })();
-
-    const workflowWalletMessage = normalizeWorkflowWalletMissingMessage(payload);
-    if (workflowWalletMessage !== null) {
-      return workflowWalletMessage;
-    }
-    if (typeof payload.message === 'string' && payload.message.trim().length > 0) {
-      return collapseWhitespace(payload.message);
-    }
-    if (typeof record['message'] === 'string' && record['message'].trim().length > 0) {
-      return collapseWhitespace(record['message']);
-    }
-  }
-  return getGenericErrorMessage(error.message, fallback);
-}
-
-/**
- * Decode any thrown value into a human, user-facing message. The single decoder
- * for biomes, the host shell, and {@link ErrorCard}'s default.
- *
- * @param error Any thrown value (string, `Error`, `ApiClientError`, Orval
- *   `ClientError`, or unknown).
- * @param fallback Copy returned when nothing better can be extracted.
- */
-export function getUserFacingErrorMessage(
-  error: unknown,
-  fallback = 'Something went wrong. Please try again.',
-): string {
-  if (typeof error === 'string') {
-    return collapseWhitespace(error) || fallback;
-  }
-  if (isApiClientErrorLike(error)) {
-    return getApiClientErrorMessage(error, fallback);
-  }
-  if (isOrvalClientErrorLike(error)) {
-    return getOrvalClientErrorMessage(error, fallback);
-  }
-  if (error instanceof Error) {
-    return getGenericErrorMessage(error.message, fallback);
-  }
-  return fallback;
-}