Freesail ReactUI

The Freesail ReactUI package provides the context, providers, and hooks necessary to render Freesail surfaces in a React application.

<FreesailProvider>

The root component that manages the connection to the Gateway and registers component catalogs.

Props:

• sseUrl (string, required): The endpoint URL for the Server-Sent Events stream (e.g., http://localhost:3001/sse).
• postUrl (string, required): The endpoint URL for sending user actions via HTTP POST (e.g., http://localhost:3001/message).
• catalogDefinitions (CatalogDefinition[]): An array of catalog definitions to register. This is the primary way to provide component schemas to the agent.
• autoConnect (boolean): Whether to automatically connect to the gateway on mount. Defaults to true.
• onConnectionChange ((connected: boolean) => void): Callback fired when connection state changes.

Hooks

The SDK exports several hooks for interacting with the Freesail state.

• useSurface(surfaceId): Subscribes to a specific surface. Returns the Surface object (containing components and dataModel) or undefined if it doesn’t exist.
• useSurfaceData(surfaceId, path?): Returns data from a surface’s data model at the specified JSON pointer path. Updates automatically when the data model changes.
• useAction(surfaceId): Returns a dispatch function to send user actions to the agent.
  • dispatch(name, sourceComponentId, context).
• useSessionId(): Returns the current session ID assigned by the Gateway, or null if not connected.
• useConnectionStatus(): Returns { isConnected: boolean }.