@freesail/react

@freesail/react

React bindings for Freesail — connects your React app to a Freesail gateway and renders agent-driven UI surfaces.

Installation

npm install @freesail/react @freesail/standard-catalog

Quick Start

import { FreesailProvider, FreesailSurface } from '@freesail/react';
import { standardCatalogComponents, standardCatalogFunctions } from '@freesail/standard-catalog';
import standardCatalogSchema from '@freesail/standard-catalog/dist/standard-catalog.json';

function App() {
  return (
    <FreesailProvider
      gateway="http://localhost:3001"
      catalogs={[{
        namespace: 'https://your-catalog-id/catalogs/your-catalog.json',
        components: standardCatalogComponents,
        functions: standardCatalogFunctions,
        schema: standardCatalogSchema,
      }]}
    >
      <FreesailSurface surfaceId="main" />
    </FreesailProvider>
  );
}

Components

FreesailProvider

Root provider that manages the gateway connection and surface state. Must wrap all FreesailSurface components.

Prop	Type	Required	Description
gateway	string	Yes	Base gateway URL (e.g. http://localhost:3001)
catalogs	CatalogDefinition[]	No	Catalogs to register with the provider
transportOptions	object	No	Additional transport configuration
additionalCapabilities	Record<string, unknown>	No	Extra capability key/values advertised to the agent
onConnectionChange	(connected: boolean) => void	No	Called when connection state changes
onError	(error: Error) => void	No	Called when a transport error occurs
onBeforeCreateSurface	interceptor	No	Called before honouring an agent createSurface — return { allowed: false } to block
onBeforeUpdateComponents	interceptor	No	Called before honouring an agent updateComponents — return { allowed: false } to block
onBeforeUpdateDataModel	interceptor	No	Called before honouring an agent updateDataModel — return { allowed: false } to block
onBeforeDeleteSurface	interceptor	No	Called before honouring an agent deleteSurface — return { allowed: false } to block

FreesailSurface

Renders a single agent-driven surface. Subscribes to updates automatically.

Prop	Type	Required	Description
surfaceId	string	Yes	The surface ID to render
className	string	No	CSS class for the container element
loading	ReactNode	No	Shown while the surface has not yet been created by the agent
error	ReactNode	No	Shown when the catalog is not registered
empty	ReactNode	No	Shown when the surface exists but has no components

Hooks

Hook	Returns	Description
useSurface(surfaceId)	Surface | undefined	Subscribe to a surface and re-render on updates
useSurfaceData(surfaceId, path?)	T | undefined	Read a value from the surface data model at an optional JSON Pointer path
useAction(surfaceId)	dispatch	Returns a function to send user actions upstream
useConnectionStatus()	{ isConnected }	Current gateway connection state
useSurfaces()	Surface[]	All active surfaces
useSessionId()	string | null	Session ID assigned by the gateway after connection

Interceptors

Each onBefore* prop lets you validate or block agent operations before they are applied. Return { allowed: false, message: '...' } to block — the message is sent back to the agent as an error. Return { allowed: true, message: '...' } to allow and also notify the agent with a validation message.

<FreesailProvider
  gateway="http://localhost:3001"
  catalogs={[...]}
  onBeforeCreateSurface={(_surfaceId, _catalogId, _sendDataModel, surfaceManager) => {
    if (surfaceManager.getAllSurfaces().length >= 3) {
      return { allowed: false, message: 'Surface limit reached. Please remove a surface first.' };
    }
    return { allowed: true, message: '' };
  }}
  onBeforeUpdateComponents={(surfaceId, components, surfaceManager) => {
    if (components.length > 50) {
      return { allowed: false, message: 'Too many components' };
    }
    return { allowed: true, message: '' };
  }}
>
  ...
</FreesailProvider>

License

MIT — see LICENSE