react

Import

Import

import * as api from "@fungi.computer/agar/react";

Exports

Kind	Export	Description
Ttype alias	AppMountState	The App connection state passed to mountApp’s render callback: live once connected, or connecting/standalone/ended while there is no usable App. An embedded page whose handshake fails is not-hosted, never standalone; Agar also renders that failure visibly.
Ttype alias	AppMountOptions	Options passed to mountApp.
Ttype alias	HostNavigationOptions	What an App’s router can do now, and how it goes back.
fnfunction	mountApp()	Own this page’s React root, authenticated App connection and host theme.
fnfunction	useStore()	Read an SDK snapshot and release its subscription when the store changes.
fnfunction	useAppContext()	Read the App’s live context (focus, visibility, Computer selection, any pending open request), or null while there is no connected App.
fnfunction	useComputerId()	Read the id of the Computer currently selected for this App, or null when no App is connected or no Computer is selected yet.
fnfunction	useWindowStatus()	Keep this window’s status bar items current in the host while mounted, and hear the person use them. Items compare by value; the bar clears on unmount.
fnfunction	useAppCommandCatalog()	Own one catalog’s local slash runtime and host registrations. Memoize build with useCallback; changing it replaces the catalog and its availability.
fnfunction	useHostNavigation()	Publish an App’s navigation state to its host and own the host’s Back requests while mounted. Pass app?.window.navigation; with no connected App it does nothing. Unmounting withdraws Back from the host chrome.

AppMountStateTtype alias

Signature

type AppMountState = Readonly<
  | {
      app: AppRoot;
      status: "live";
    }
  | {
      app: null;
      status: "connecting" | "standalone" | "ended";
    }
  | {
      app: null;
      status: "not-hosted";
      error: AppError;
    }
>;

The App connection state passed to mountApp’s render callback: live once connected, or connecting/standalone/ended while there is no usable App. An embedded page whose handshake fails is not-hosted, never standalone; Agar also renders that failure visibly.

---

AppMountOptionsTtype alias

Signature

type AppMountOptions = Readonly<{
  name: string;
  queryClient?: QueryClient;
}>;

Options passed to mountApp.

---

HostNavigationOptionsTtype alias

Signature

type HostNavigationOptions = Readonly<{
  canGoBack: boolean;
  title?: string;
  crumbs?: readonly AppCrumb[];
  primary?: readonly AppHeaderCommand[];
  menu?: readonly AppHeaderCommand[];
  status?: readonly AppHeaderStatus[];
  onBack: AppBackHandler;
  onCrumb?: (crumbId, siblingId?) => void;
  onAction?: (actionId) => void;
}>;

What an App’s router can do now, and how it goes back.

mountApp()fnfunction

Signature

function mountApp(element, options, render): Disposer;

Own this page’s React root, authenticated App connection and host theme.

Parameters

Parameter	Type
element	HTMLElement
options	AppMountOptions
render	(state) => ReactNode

Returns

Disposer

---

useStore()fnfunction

Signature

function useStore<T>(store): T | undefined;

Read an SDK snapshot and release its subscription when the store changes.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
store	ReadonlyStore<T> | undefined

Returns

T | undefined

---

useAppContext()fnfunction

Signature

function useAppContext(app): AppContext | null;

Read the App’s live context (focus, visibility, Computer selection, any pending open request), or null while there is no connected App.

Parameters

Parameter	Type
app	AppRoot | null | undefined

Returns

AppContext | null

---

useComputerId()fnfunction

Signature

function useComputerId(app): string | null;

Read the id of the Computer currently selected for this App, or null when no App is connected or no Computer is selected yet.

Parameters

Parameter	Type
app	AppRoot | null | undefined

Returns

string | null

---

useWindowStatus()fnfunction

Signature

function useWindowStatus(app, items, onAction?, onReportFailure?): void;

Keep this window’s status bar items current in the host while mounted, and hear the person use them. Items compare by value; the bar clears on unmount.

Parameters

Parameter	Type	Description
app	Pick<AppRoot, "ui"> | null | undefined	-
items	readonly AppStatusItem[]	-
onAction?	AppStatusActionHandler	-
onReportFailure?	(cause) => void	Hear a report the host refused, so the App can say so.

Returns

void

---

useAppCommandCatalog()fnfunction

Signature

function useAppCommandCatalog(app, __namedParameters, build): WhistleRuntime;

Own one catalog’s local slash runtime and host registrations. Memoize build with useCallback; changing it replaces the catalog and its availability.

Parameters

Parameter	Type
app	AppRoot | null | undefined
__namedParameters	Pick<WhistleContribution, "sourceId" | "namespace">
build	() => readonly Readonly<{ id: string; title: string; category: string; description?: string; projections?: { bindings?: { order?: number; values: readonly string[]; }; agent?: { keybind?: string; order?: number; }; help?: { order?: number; }; menu?: { order?: number; }; palette?: { order?: number; }; slash?: { aliases: readonly string[]; consumesDraft?: boolean; order?: number; arguments?: { hint: string; words?: … | …; text?: … | …; }; }; }; action?: { inputSchema?: { [key: string]: | string | number | boolean | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | … 4 more … | null)[] | { …; } | null)[] | { …; } | null)[] | { …; } | …[] | { [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | … 4 more … | null)[] | { …; } | null)[] | { …; } | null)[] | { …; } | …; } | null; }; outputSchema?: { [key: string]: | string | number | boolean | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | … 4 more … | null)[] | { …; } | null)[] | { …; } | null)[] | { …; } | …[] | { [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | … 4 more … | null)[] | { …; } | null)[] | { …; } | null)[] | { …; } | …; } | null; }; presentation?: | { type: "action"; } | { type: "custom"; data: { [key: string]: | string | number | boolean | readonly …[] | { [key: …]: …; } | null; }; } | { type: "choice"; options: readonly object[]; } | { type: "form"; submitLabel?: string; } | { type: "confirmation"; message: string; confirmLabel?: string; cancelLabel?: string; }; }; availability?: () => WhistleAvailability; handler: (input) => unknown; }>[]

Returns

WhistleRuntime

---

useHostNavigation()fnfunction

Signature

function useHostNavigation(navigation, __namedParameters): void;

Publish an App’s navigation state to its host and own the host’s Back requests while mounted. Pass app?.window.navigation; with no connected App it does nothing. Unmounting withdraws Back from the host chrome.

Parameters

Parameter	Type
navigation	| Readonly<{ publish: Promise<void>; onBack: Disposer; onActivate: Disposer; }> | null | undefined
__namedParameters	HostNavigationOptions

Returns

void