React integration

This guide covers the standard React integration pattern used across Scenaro experience apps and platform-spa.

Provider stack

import { ScenaroProvider, FeatureProvider } from '@scenaro/sdk/react';

export function ScenaroLiveProviders({ children, registry }) {
  return (
    <ScenaroProvider apiUrl={process.env.NEXT_PUBLIC_API_URL!}>
      <FeatureProvider registry={registry}>
        {children}
      </FeatureProvider>
    </ScenaroProvider>
  );
}

ScenaroProvider

Owns the session, creates a shared ScenaroClient and scoped ScenaroEventBus, and injects the current Transport implementation’s RoomContext (LiveKit today) silently — no manual RoomContext.Provider wiring needed.

Prop	Type	Description
`client`	`ScenaroClient`	Pre-built client instance (preferred for shared config)
`apiUrl`	`string`	API base URL (alternative to `client`)
`apiPathPrefix`	`string`	Path prefix, default `/v1`
`storagePrefix`	`string`	Prefix for localStorage keys (multi-tenant embeds)
`storage`	`StorageAdapter \| null`	Custom storage (default: `localStorage`)

Hooks:

useScenaro() — full context (client + events)
useScenaroClient() — HTTP client only
useScenaroEvents() — event bus only

useScenaroSession

The single entry point for a session. It handles the full lifecycle — identify, start session, Transport connect/disconnect — plus the data channel, config handshake, and tool RPC internally.

import { useScenaroSession } from '@scenaro/sdk/react';

const {
  status,        // 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'ended'
  agentState,    // 'idle' | 'listening' | 'thinking' | 'speaking'
  messages,      // ConversationMessage[]
  config,        // SessionConfig | null (curated)
  rawConfig,     // ConfigPayload | null (wire format)
  conversationId,
  error,         // ScenaroError | null
  start,         // (overrides?) => Promise<void>
  end,           // () => Promise<void>
  sendText,      // (text) => Promise<void>
  setMicrophoneEnabled,
} = useScenaroSession({
  scenario: 'publication-uuid',
  onMessage: (m) => console.log(m),
  onError: (e) => console.error(e.code),
  onSessionEnd: (info) => {},
});

Options

Option	Description
`scenario`	Publication UUID (required, cannot be overridden in `start`)
`language`	Optional BCP-47 tag; omit to use the scenario’s configured language
`tools`	Frontend tool handlers (see below)
`onMessage`	Called for each `ConversationMessage`
`onError`	Called with a `ScenaroError` (has `.code`)
`onSessionEnd`	Called when the session ends

start(overrides?) accepts option overrides for the session being started — everything except scenario.

Frontend tools

Tools are plain async functions — no requestId plumbing:

useScenaroSession({
  scenario: 'publication-uuid',
  tools: {
    search_products: async (args, context) => {
      // context: { toolName, settings, collections: Collection[], signal: AbortSignal }
      return await searchCatalog(args, { signal: context.signal });
    },
  },
});

Session config

After the config handshake:

config — curated { features, collections, avatarEnabled, audioDictationEnabled }
rawConfig — full wire payload (restore_state, tool wiring, snake_case fields)

See Tools and features for when to use each.

Advanced: engine handle access

The hook also returns room — the current Transport implementation’s engine handle (LiveKit Room | null) — for advanced use cases. Most apps never need it — see Advanced: Transport extensions.

The hook is powered by the headless ScenaroSession class from @scenaro/sdk, usable outside React. See the ScenaroSession reference.

Next.js

Add the SDK to transpilePackages:

// next.config.js
module.exports = {
  transpilePackages: ['@scenaro/sdk'],
};

​Provider stack

​ScenaroProvider

​useScenaroSession

​Options

​Frontend tools

​Session config

​Advanced: engine handle access

​Next.js

​Next steps

Provider stack

ScenaroProvider

useScenaroSession

Options

Frontend tools

Session config

Advanced: engine handle access

Next.js

Next steps