@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,112 +0,0 @@
-/**
- * Frontend-biome route/biome builders.
- *
- * The `createElement(Suspense, { fallback: null }, createElement(LazyPage))`
- * wrapper is hand-repeated ~74× across biome `index.ts` files — once per lazy
- * route. `lazyRoute` collapses it to one call; `defineSinglePageBiome` builds
- * the whole one-page biome (nav item + single route) that the vast majority of
- * biomes are. Host-framework-agnostic: pure React (`lazy` / `Suspense` /
- * `createElement`), no router and no Next.js.
- */
-import {
-  Suspense,
-  createElement,
-  lazy,
-  type ComponentType,
-  type ReactNode,
-} from 'react';
-
-import type {
-  FrontendBiome,
-  NavItemContribution,
-  RouteAccess,
-  RouteContribution,
-} from './frontend-biome';
-
-/** A dynamic import of a module whose default export is a React component. */
-export type LazyComponentImport = () => Promise<{ default: ComponentType }>;
-
-/**
- * Wrap a dynamic page import as a `RouteContribution['element']` factory: lazy
- * import + `<Suspense>` boundary. Replaces the hand-written
- * `createElement(Suspense, { fallback }, createElement(lazy(importFn)))` block.
- *
- * The `lazy(...)` call is hoisted out of the returned thunk so the component is
- * created ONCE (not on every route render), matching how biomes hand-declare
- * `const Page = lazy(() => import('./Page'))` at module scope.
- *
- * @param importFn Dynamic import of the page module (`() => import('./Page')`).
- * @param fallback Suspense fallback. Defaults to `null` (the prevailing biome
- *   convention) — pass a skeleton to be explicit.
- */
-export function lazyRoute(
-  importFn: LazyComponentImport,
-  fallback: ReactNode = null,
-): () => ReactNode {
-  const Lazy = lazy(importFn);
-  const LazyRoute = () =>
-    createElement(Suspense, { fallback }, createElement(Lazy));
-  LazyRoute.displayName = 'LazyRoute';
-  return LazyRoute;
-}
-
-export interface SinglePageBiomeRoute {
-  /** Route path. May include `:param` segments. */
-  readonly path: string;
-  /** Dynamic import of the page module. */
-  readonly page: LazyComponentImport;
-  /**
-   * Whether the route mounts under `/projects/:projectId` (project-scoped) or
-   * at the org root. REQUIRED — mirrors {@link RouteContribution.projectScoped}.
-   */
-  readonly projectScoped: boolean;
-  /** Access tier required to render. Defaults to `'member'`. */
-  readonly access?: RouteAccess;
-  /** Suspense fallback for the lazy page. Defaults to `null`. */
-  readonly fallback?: ReactNode;
-}
-
-export interface SinglePageBiomeSpec {
-  /** Stable biome id; matches `xema-biome.json` `xema.id`. */
-  readonly id: string;
-  /** Displayed name. */
-  readonly displayName: string;
-  /** The single nav item this biome contributes. */
-  readonly nav: NavItemContribution;
-  /** The single route this biome contributes. */
-  readonly route: SinglePageBiomeRoute;
-}
-
-/**
- * Build a `FrontendBiome` for the common one-nav-item / one-route biome.
- *
- * Most biomes are exactly this shape — a nav entry plus a single lazy page —
- * yet each re-declares the nav array, the route array, the `lazy(...)`, and the
- * `Suspense` wrapper by hand. This builder centralizes all four.
- *
- * @example
- *   const biome: FrontendBiomeFactory = () =>
- *     defineSinglePageBiome({
- *       id: 'org-databases',
- *       displayName: 'Organization Databases',
- *       nav: { id: 'org-databases', label: 'Databases', route: 'org-databases',
- *              icon: Database, section: 'Organization', weight: 30 },
- *       route: { path: 'org-databases', projectScoped: false,
- *                page: () => import('./pages/DatabasesListPage') },
- *     });
- */
-export function defineSinglePageBiome(spec: SinglePageBiomeSpec): FrontendBiome {
-  const { route } = spec;
-  const contribution: RouteContribution = {
-    path: route.path,
-    projectScoped: route.projectScoped,
-    element: lazyRoute(route.page, route.fallback ?? null),
-    ...(route.access ? { access: route.access } : {}),
-  };
-  return {
-    id: spec.id,
-    displayName: spec.displayName,
-    navItems: [spec.nav],
-    routes: [contribution],
-  };
-}

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

@@ -1,6 +0,0 @@
-/**
- * Master switch for the biome subsystem. A host passes `'disabled'` to opt
- * the whole biome runtime out (no biomes load / register) — e.g. for a
- * minimal shell or a degraded mode. Framework-agnostic.
- */
-export type BiomesMode = 'enabled' | 'disabled';

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

@@ -1,37 +0,0 @@
-/**
- * Bridge-backed navigation convenience hooks for frontend biomes.
- *
- * These wrap the host-agnostic `HostBridge.navigation` surface so biome code
- * never imports a router primitive (`next/navigation`, `react-router-dom`)
- * directly — the host wires the concrete implementation once on the bridge and
- * every biome reads it through here. Host-framework-agnostic: no Next.js, no
- * React-Router. React itself IS used (these are React hooks).
- */
-import { useMemo } from 'react';
-
-import { useHostBridge } from './host-bridge';
-
-/**
- * Current URL query string as a read-only `URLSearchParams`, read through the
- * host-provided navigation adapter (`bridge.navigation.useSearchParams`).
- *
- * The one router primitive biomes could not previously reach through the
- * bridge. Use this INSTEAD of `import { useSearchParams } from
- * 'next/navigation'` so biome code stays portable across hosts.
- */
-export function useSearchParams(): URLSearchParams {
-  return useHostBridge().navigation.useSearchParams();
-}
-
-/**
- * Read a single query-string parameter by key, or `null` when absent.
- *
- * Sugar over {@link useSearchParams} for the common "one param" case (e.g.
- * `?tab=overview`, `?runId=…`) that otherwise forces a direct
- * `next/navigation` import. Returns the first value when a key repeats,
- * matching `URLSearchParams.get` semantics.
- */
-export function useQueryParam(key: string): string | null {
-  const searchParams = useSearchParams();
-  return useMemo(() => searchParams.get(key), [searchParams, key]);
-}

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

@@ -1,299 +0,0 @@
-import { Registry } from '@xemahq/registry';
-import { useSyncExternalStore } from 'react';
-
-import {
-  DuplicateContributionPolicy,
-  createContributionRegistry,
-} from '../contribution-registry';
-
-import type {
-  FrontendBiome,
-  FrontendBiomeFactory,
-  OutputRendererContribution,
-  PanelContribution,
-} from './frontend-biome';
-import type { HostBridge } from './host-bridge';
-
-/**
- * Singleton frontend biome registry. Populated at app bootstrap by
- * `registerFrontendBiome()` (factory form) or `registerFrontendBiomeInstance()`
- * (already-built form). Bootstrap order: fetch enabled biome ids from
- * `GET /platform/biomes/web`, dynamically `import()` each biome module
- * from the auto-generated loader map (`xema:web-biome-loaders`), then
- * call its default export with the host's concrete `HostBridge` and
- * register the result.
- *
- * Reactivity: components consume registry data via `useBiomeRegistryRevision()`
- * (or `<BiomeSlot>` / `useBiomeRoutes()` which use it internally) so a
- * re-render fires automatically when a biome registers or unregisters —
- * no race between Sidebar mount and async bootstrap, no manual subscription
- * wiring per consumer.
- *
- * Master-disable: hosts that embed `@xemahq/ui-kernel` without
- * participating in Xema's biome ecosystem flip
- * `biomeRegistry.setEnabled(false)` (typically via
- * `<BiomeHostProvider biomes="disabled">`). When disabled, every
- * register/unregister/bootstrap call is a no-op — a single flag controls
- * the entire surface.
- */
-class FrontendBiomeRegistry extends Registry<
-  string,
-  FrontendBiome & { key: string }
-> {
-  private revisionCount = 0;
-  private readonly listeners = new Set<() => void>();
-  /**
-   * Biome ids whose `init()` callback has been invoked. Tracked
-   * separately from the registry entries so `init()` runs exactly once
-   * per biome per SPA session even if `registerBiome` is called
-   * multiple times (HMR, strict-mode double-mount, retries). Biome
-   * authors get an at-most-once execution guarantee.
-   */
-  private readonly initialized = new Set<string>();
-  private enabled = true;
-
-  constructor() {
-    super({ name: 'FrontendBiomeRegistry' });
-  }
-
-  registerBiome(biome: FrontendBiome): void {
-    if (!this.enabled) {
-      return;
-    }
-    this.register({ ...biome, key: biome.id });
-    this.revisionCount += 1;
-    this.notify();
-  }
-
-  /**
-   * Invoke a biome's `init()` callback exactly once per SPA session.
-   * The caller (bootstrap) is responsible for catching/logging promise
-   * rejections — the registry intentionally does not swallow them.
-   */
-  async runInit(biomeId: string, bridge: HostBridge): Promise<void> {
-    const entry = this.get(biomeId);
-    if (!entry || !entry.init) {
-      return;
-    }
-    if (this.initialized.has(biomeId)) {
-      return;
-    }
-    this.initialized.add(biomeId);
-    await entry.init({ bridge, biomeId });
-  }
-
-  unregisterBiome(id: string): boolean {
-    if (!this.enabled) {
-      return false;
-    }
-    const entry = this.get(id);
-    const removed = this.unregister(id);
-    if (removed) {
-      this.revisionCount += 1;
-      this.initialized.delete(id);
-      if (entry?.dispose) {
-        // Fire-and-forget; teardown errors are logged by callers but
-        // never block the unregister path — disposal is best-effort
-        // because the biome is being torn down anyway.
-        void Promise.resolve(entry.dispose()).catch((error: unknown) => {
-          // Surface for devtools without crashing the unregister flow.
-          console.error(
-            `[xema-ui-kernel] dispose() failed for '${id}':`,
-            error,
-          );
-        });
-      }
-      this.notify();
-    }
-    return removed;
-  }
-
-  /**
-   * Snapshot of currently-registered biome ids. Useful for the admin UI
-   * to detect "registered in this session" vs "enabled in catalog".
-   */
-  snapshot(): readonly string[] {
-    return this.list().map((b) => b.id);
-  }
-
-  setEnabled(enabled: boolean): void {
-    if (this.enabled === enabled) {
-      return;
-    }
-    this.enabled = enabled;
-    if (!enabled) {
-      // When master-disabling, drop any previously-registered biomes so
-      // BiomeSlot/useBiomeRoutes consumers re-render to empty.
-      const had = this.size() > 0;
-      this.clear();
-      this.initialized.clear();
-      if (had) {
-        this.revisionCount += 1;
-        this.notify();
-      }
-    }
-  }
-
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  revision(): number {
-    return this.revisionCount;
-  }
-
-  /**
-   * Subscribe to revision-counter changes. Returns an unsubscribe
-   * function. Used internally by `useBiomeRegistryRevision()` (via
-   * `useSyncExternalStore`) so components automatically re-render when
-   * a biome is added or removed.
-   */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  panelsForSlot(slot: string): readonly PanelContribution[] {
-    if (!this.enabled) {
-      return [];
-    }
-    const out: PanelContribution[] = [];
-    for (const biome of this.list()) {
-      for (const panel of biome.panels ?? []) {
-        if (panel.slot === slot) {
-          out.push(panel);
-        }
-      }
-    }
-    return out.sort((a, b) => (a.weight ?? 100) - (b.weight ?? 100));
-  }
-
-  /**
-   * Flatten every registered biome's `outputRenderers[]` contributions
-   * into a `(outputKind → factory)` map. The host's renderer registry
-   * overlays this on top of the built-in set so biome-defined kinds
-   * light up the moment the biome's frontend loads. Duplicate kinds
-   * across biomes are surfaced as a console error and the first
-   * registration wins (deterministic + fail-loud, not silent).
-   *
-   * Built on the shared `createContributionRegistry` core — the same
-   * closed+open two-layer bookkeeping the ChatWidget, reply-variant and
-   * Vista-surface registries use. This overlay is rebuilt on every call
-   * (it is read during render), so it takes the `FirstWins` duplicate
-   * policy rather than `Throw`: a duplicate must not take down a render.
-   * `FirstWins` still REQUIRES the `onDuplicate` reporter below — the
-   * rejected contribution is never dropped silently.
-   */
-  outputRenderers(): ReadonlyMap<string, OutputRendererContribution> {
-    if (!this.enabled) {
-      return new Map<string, OutputRendererContribution>();
-    }
-    // `onDuplicate` fires SYNCHRONOUSLY from inside `register()`, so this
-    // cursor always names the biome whose contribution was rejected — the
-    // contribution object itself does not carry its owner.
-    let contributingBiomeId = '';
-    const overlay = createContributionRegistry<OutputRendererContribution>({
-      name: 'biome outputRenderer',
-      duplicatePolicy: DuplicateContributionPolicy.FirstWins,
-      onDuplicate: (outputKind) => {
-        console.error(
-          `[xema-ui-kernel] duplicate outputRenderer for kind '${outputKind}' ` +
-            `from biome '${contributingBiomeId}'; first registration wins.`,
-        );
-      },
-    });
-    for (const biome of this.list()) {
-      contributingBiomeId = biome.id;
-      for (const entry of biome.outputRenderers ?? []) {
-        overlay.register(entry.outputKind, entry);
-      }
-    }
-    return overlay.entries();
-  }
-
-  private notify(): void {
-    for (const listener of this.listeners) {
-      listener();
-    }
-  }
-}
-
-export const biomeRegistry = new FrontendBiomeRegistry();
-
-function isFrontendBiome(value: unknown): value is FrontendBiome {
-  return (
-    value !== null &&
-    typeof value === 'object' &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'displayName' in value &&
-    typeof value.displayName === 'string'
-  );
-}
-
-/**
- * Register an already-built `FrontendBiome` instance. Prefer
- * `registerFrontendBiome(factory, bridge)` for biomes shipped via
- * the factory contract.
- */
-export function registerFrontendBiomeInstance(biome: FrontendBiome): void {
-  biomeRegistry.registerBiome(biome);
-}
-
-/**
- * Invoke a `FrontendBiomeFactory` with the host's `HostBridge` and
- * register the resulting `FrontendBiome`. This is the standard
- * registration path for biomes shipped as workspace packages.
- *
- * Fail-fast: a factory that returns a non-`FrontendBiome` value, or
- * that produces a duplicate id, propagates the underlying registry
- * error — no swallowing.
- */
-export function registerFrontendBiome(
-  factory: FrontendBiomeFactory,
-  bridge: HostBridge,
-): void {
-  if (!biomeRegistry.isEnabled()) {
-    return;
-  }
-  const biome: unknown = factory(bridge);
-  if (!isFrontendBiome(biome)) {
-    throw new Error(
-      '[xema-ui-kernel] FrontendBiomeFactory returned a non-FrontendBiome value. ' +
-        'A biome module must default-export `(bridge) => FrontendBiome`.',
-    );
-  }
-  biomeRegistry.registerBiome(biome);
-}
-
-/**
- * Unregister a biome by id. Triggered by the admin UI's runtime
- * disable flow so BiomeSlot / useBiomeRoutes consumers reflow without
- * a page reload. Returns `true` if a registration was removed.
- */
-export function unregisterFrontendBiome(id: string): boolean {
-  return biomeRegistry.unregisterBiome(id);
-}
-
-/**
- * React hook that subscribes the calling component to the biome
- * registry's revision counter. Returns the current revision (a number
- * that increments by 1 on every biome registration or unregistration).
- * Use the return value as a `useMemo` dep when computing data derived
- * from the registry — the memo recomputes on every change.
- *
- * Implemented with `useSyncExternalStore` so it integrates cleanly with
- * React 18 concurrent rendering and SSR.
- *
- * `<BiomeSlot>` uses this hook internally so any host page that mounts
- * a slot re-renders automatically when biomes arrive or leave.
- */
-export function useBiomeRegistryRevision(): number {
-  return useSyncExternalStore(
-    (listener) => biomeRegistry.subscribe(listener),
-    () => biomeRegistry.revision(),
-    () => biomeRegistry.revision(),
-  );
-}

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

@@ -1,41 +0,0 @@
-import { useHostBridge } from './host-bridge';
-
-export interface ProjectScope {
-  readonly orgId: string | null;
-  readonly projectId: string | null;
-}
-
-export interface RequiredProjectScope {
-  readonly orgId: string;
-  readonly projectId: string;
-}
-
-function normalize(value: string | null | undefined): string | null {
-  if (typeof value !== 'string') {
-    return null;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-export function useProjectScope(): ProjectScope {
-  const bridge = useHostBridge();
-  const params = bridge.navigation.useRouteParams<{ projectId?: string }>();
-  const orgId = normalize(bridge.auth.getOrgId());
-  const projectId =
-    normalize(params.projectId) ?? normalize(bridge.auth.getProjectId());
-  return { orgId, projectId };
-}
-
-export function useRequiredScope(): RequiredProjectScope {
-  const { orgId, projectId } = useProjectScope();
-  if (!orgId || !projectId) {
-    throw new Error(
-      `[xema-ui-kernel] useRequiredScope() requires both orgId and projectId, ` +
-        `got orgId=${orgId ?? 'null'} projectId=${projectId ?? 'null'}. ` +
-        `Render this component under <ScopeGuard> or use useProjectScope() for ` +
-        `org-scoped surfaces.`,
-    );
-  }
-  return { orgId, projectId };
-}

package/src/lib/biome-host/biome-scope.tsx

@@ -1,52 +0,0 @@
-/**
- * Bridge-backed org/project scope hooks for frontend biomes.
- *
- * Biomes need the active `{ orgId, projectId }` everywhere they call a scoped
- * API or build a scoped query key. Today each biome rolls its own read — some
- * pull `bridge.auth.getOrgId()`, some read `projectId` off route params, some
- * mix both — which drifts and quietly produces null/undefined holes. This
- * module collapses those into ONE normalized read and ONE guard component.
- *
- * Host-framework-agnostic: it only reads the host-implemented bridge surface
- * (`auth.getOrgId` / `auth.getProjectId` and `navigation.useRouteParams`). No
- * Next.js, no React-Router.
- */
-import { Fragment, type ReactElement, type ReactNode } from 'react';
-
-import { useProjectScope, type ProjectScope } from './biome-scope-hooks';
-
-export interface ScopeGuardProps {
-  /**
-   * What to render while the scope is incomplete. Defaults to `null` (render
-   * nothing) — pass a skeleton or an empty-state to be explicit.
-   */
-  readonly fallback?: ReactNode;
-  /**
-   * When `true` (the default) both `orgId` AND `projectId` are required. Set
-   * `false` to gate only on `orgId` — for org-scoped surfaces that still want
-   * to wait for an active org before rendering.
-   */
-  readonly requireProject?: boolean;
-  /**
-   * Children to render once the scope is complete. May be a render-prop that
-   * receives the resolved {@link ProjectScope}, or plain nodes.
-   */
-  readonly children: ReactNode | ((scope: ProjectScope) => ReactNode);
-}
-
-/**
- * Gate a subtree on a complete active scope. Renders `fallback` until the
- * required scope fields are present, then renders `children` (passing the
- * resolved scope when `children` is a render-prop). Collapses the repeated
- * `if (!orgId || !projectId) return null` guard biome pages hand-write.
- */
-export function ScopeGuard(props: ScopeGuardProps): ReactElement {
-  const { fallback = null, requireProject = true, children } = props;
-  const scope = useProjectScope();
-  const ready = Boolean(scope.orgId) && (!requireProject || Boolean(scope.projectId));
-  if (!ready) {
-    return <Fragment>{fallback}</Fragment>;
-  }
-  const resolved = typeof children === 'function' ? children(scope) : children;
-  return <Fragment>{resolved}</Fragment>;
-}

package/src/lib/biome-host/biome-scoped-query.ts

@@ -1,134 +0,0 @@
-/**
- * Bridge-backed scoped-fetch helpers for frontend biomes.
- *
- * Every scoped biome data hook hand-repeats the same three things: build the
- * org/project request headers (`reqOpts`), gate the query on the scope being
- * present (`enabled`), and fold org/project into the query key so cache entries
- * don't bleed across tenants/projects. This module folds those into
- * `useScopedClient()` + `useScopedQuery()` so a biome hook becomes one call.
- *
- * Host-framework-agnostic. TanStack Query is an OPTIONAL peer dependency — it
- * is imported only here, behind the `useScopedQuery` surface, so biomes that
- * don't use it pay nothing and the kernel never hard-requires it.
- */
-import {
-  useQuery,
-  type QueryKey,
-  type UseQueryOptions,
-  type UseQueryResult,
-} from '@tanstack/react-query';
-
-import { useProjectScope, type ProjectScope } from './biome-scope-hooks';
-
-/**
- * The canonical Xema-platform tenant header. Every platform biome-api reads it
- * via `RequestContext`. Mirrors the host's `reqOpts` (see
- * `submodules/xema-host-web/src/lib/api/orval/configure-clients.ts`).
- */
-const ORG_HEADER = 'X-Xema-Org-Id';
-const PROJECT_HEADER = 'X-Project-Id';
-
-/**
- * Build a `RequestInit` carrying the active org/project headers, to pass as the
- * per-call `options` argument of any Orval endpoint function. Single source of
- * the header names so biomes stop hand-rolling `reqOpts` per package.
- */
-export function buildScopedRequestInit(scope: ProjectScope): RequestInit {
-  const headers: Record<string, string> = {};
-  if (scope.orgId) {
-    headers[ORG_HEADER] = scope.orgId;
-  }
-  if (scope.projectId) {
-    headers[PROJECT_HEADER] = scope.projectId;
-  }
-  return { headers };
-}
-
-export interface ScopedClient {
-  /** The resolved active scope (null-normalized). */
-  readonly scope: ProjectScope;
-  /**
-   * Per-call Orval options bound to the active scope. Pass straight into an
-   * endpoint function: `await fooControllerList(client.reqOpts())`.
-   */
-  reqOpts(): RequestInit;
-}
-
-/**
- * A scope-bound request-options factory. Reads the active `{ orgId, projectId }`
- * from the bridge and exposes a `reqOpts()` that stamps the canonical tenant
- * headers — the per-biome `reqOpts(orgId, projectId)` helper, centralized.
- */
-export function useScopedClient(): ScopedClient {
-  const scope = useProjectScope();
-  return {
-    scope,
-    reqOpts: () => buildScopedRequestInit(scope),
-  };
-}
-
-/**
- * Extra options accepted by {@link useScopedQuery} on top of the underlying
- * TanStack `useQuery` options.
- */
-export interface UseScopedQueryExtras {
-  /**
-   * When `true` (the default) the query is gated on `orgId` AND `projectId`.
-   * Set `false` to gate only on `orgId` — for org-scoped reads that don't need
-   * a project. The gate ANDs with any caller-supplied `enabled`.
-   */
-  readonly requireProject?: boolean;
-}
-
-/**
- * The `queryFn` shape `useScopedQuery` calls — it receives the resolved scope
- * plus the scope-bound `reqOpts()` so the body never re-reads the bridge.
- */
-export type ScopedQueryFn<TData> = (ctx: {
-  readonly scope: ProjectScope;
-  reqOpts(): RequestInit;
-}) => TData | Promise<TData>;
-
-/**
- * Scope-aware `useQuery`. Folds the active org/project into:
- *   - the **query key** — `key` is prefixed with `['scope', orgId, projectId]`
- *     so cache entries never leak across tenants/projects;
- *   - the **`enabled` gate** — ANDed with the scope-present check (and any
- *     caller `enabled`), so the query stays idle until the scope resolves;
- *   - the **`queryFn` context** — the resolved scope + a bound `reqOpts()`.
- *
- * Everything else (`staleTime`, `select`, `retry`, …) passes through to the
- * underlying `useQuery`.
- */
-export function useScopedQuery<
-  TQueryFnData,
-  TError = Error,
-  TData = TQueryFnData,
->(
-  key: QueryKey,
-  queryFn: ScopedQueryFn<TQueryFnData>,
-  options: Omit<
-    UseQueryOptions<TQueryFnData, TError, TData>,
-    'queryKey' | 'queryFn'
-  > &
-    UseScopedQueryExtras = {},
-): UseQueryResult<TData, TError> {
-  const scope = useProjectScope();
-  const { requireProject = true, enabled, ...rest } = options;
-
-  const scopeReady =
-    Boolean(scope.orgId) && (!requireProject || Boolean(scope.projectId));
-
-  return useQuery<TQueryFnData, TError, TData>({
-    ...rest,
-    queryKey: ['scope', scope.orgId, scope.projectId, ...key],
-    enabled: scopeReady && (enabled ?? true),
-    queryFn: () =>
-      Promise.resolve(
-        queryFn({
-          scope,
-          reqOpts: () => buildScopedRequestInit(scope),
-        }),
-      ),
-  });
-}