@ringg/react-native 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { FC, ReactNode } from 'react';
+import { Room, RoomOptions } from 'livekit-client';
+import { StyleProp, ViewStyle } from 'react-native';
+
 /**
  * Theme types for the widget.
  * Covers both widget-level theming and per-component theming.
@@ -77,6 +81,28 @@ interface SlashCommand {
     description: string;
 }
 
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: tokens/tokens.json + tokens/defaults.json
+ * Regenerate: node scripts/generate-tokens.mjs
+ */
+
+declare const DEFAULT_WIDGET_THEME: ResolvedWidgetTheme;
+declare const WIDGET_PRESET_THEMES: Record<string, WidgetTheme>;
+declare const WIDGET_DEFAULTS: {
+    readonly mode: "prod";
+    readonly title: "Ringg AI Support";
+    readonly description: "Ringg AI offers 24/7 voice support to handle your business calls efficiently and professionally";
+    readonly defaultTab: "audio";
+    readonly hideTabSelector: false;
+    readonly defaultExpanded: false;
+    readonly bypassStartScreen: false;
+    readonly bypassFeedbackScreen: false;
+    readonly voiceCallShowAnimation: false;
+    readonly voiceCallShowTranscript: true;
+    readonly notificationTuneUrl: "https://assets.ringg.ai/audios/misc/widget_notification.mp3";
+};
+
 /**
  * Widget configuration types.
  * These define the public API surface for consumers initializing the widget.
@@ -177,6 +203,16 @@ interface RinggWidgetConfig {
     xApiKey?: string;
     /** JWT for authentication (Authorization header) — wins over xApiKey when both are set */
     authorization?: string;
+    /**
+     * `Origin` to present to the backend, which allow-lists an agent's callers
+     * by that value. Browsers send it themselves, so web leaves this unset and
+     * MUST NOT set it — `Origin` is a forbidden header there. Native callers
+     * send nothing on their own and have to supply their own identity, by
+     * convention `<platform>://<bundleId>` (see @ringg/react-native's
+     * `appOrigin`). Whatever string is given is sent verbatim; only the backend
+     * decides whether it is allowed.
+     */
+    clientOrigin?: string;
     /** Custom variables passed to the agent (e.g., user name, role) */
     variables?: WidgetVariables;
     /** Environment mode — selects which UrlResolver entry to use */
@@ -249,6 +285,11 @@ interface CalendarBookingPayload extends BaseComponent {
     component_type: "calendar_booking";
     data: CalendarBookingData;
 }
+interface GroupedSlots {
+    date: string;
+    dateLabel: string;
+    slots: CalendarSlot[];
+}
 type FormFieldType = "text" | "email" | "tel" | "number" | "select" | "multiselect" | "textarea" | "date" | "boolean";
 interface FormFieldOption {
     value: string;
@@ -547,6 +588,8 @@ interface EventBus {
     /** Remove all listeners for one event, or all events if omitted. */
     off(event?: WidgetEventName): void;
 }
+/** Web implementation — dispatches/listens via DOM CustomEvents on `window`. */
+declare function createDomEventBus(): EventBus;
 /** In-memory event bus — for React Native or testing. */
 declare function createCallbackEventBus(): EventBus;
 
@@ -564,6 +607,7 @@ interface Clock {
     setTimeout(fn: () => void, ms: number): TimerHandle;
     clearTimeout(handle: TimerHandle): void;
 }
+declare function createSystemClock(): Clock;
 
 /**
  * Small platform ports — capabilities core needs but cannot implement
@@ -580,6 +624,9 @@ interface NotificationPlayer {
     /** Best-effort playback; must never throw (autoplay policies etc.) */
     play(): void;
 }
+/** No-op defaults for platforms/tests that don't wire these up */
+declare const grantedMicPermission: MicPermissionPort;
+declare const silentNotificationPlayer: NotificationPlayer;
 
 /**
  * API client for the Ringg backend.
@@ -595,6 +642,101 @@ interface EnvironmentUrls {
 interface UrlResolver {
     resolve(mode: EnvironmentMode): EnvironmentUrls;
 }
+declare function createStaticUrlResolver(urls: Record<EnvironmentMode, EnvironmentUrls>): UrlResolver;
+interface WebcallResponse {
+    call_id: string;
+    user_token: string;
+    enabled_slash_commands?: SlashCommand[];
+}
+interface FeedbackPayload {
+    rating: number;
+    comment: string;
+}
+interface ApiClientConfig {
+    urlResolver: UrlResolver;
+    mode: EnvironmentMode;
+    /** Sent as X-API-KEY */
+    xApiKey?: string;
+    /** Sent as Authorization; wins over xApiKey when both are set */
+    authorization?: string;
+    /** Sent as `Origin`. Omitted entirely when unset — see RinggWidgetConfig. */
+    clientOrigin?: string;
+}
+interface RinggApiClient {
+    readonly backendUrl: string;
+    readonly livekitUrl: string;
+    /** Initiate a webcall — returns the LiveKit token and call ID. */
+    startWebcall(params: {
+        agentId: string;
+        variables: WidgetVariables;
+        mediaType: "audio" | "text";
+    }): Promise<WebcallResponse>;
+    /** Submit post-call feedback. Best-effort — callers decide error handling. */
+    submitFeedback(callId: string, feedback: FeedbackPayload): Promise<void>;
+    /** Call a component API endpoint (for interactive flow on_complete actions). */
+    callComponentApi(method: "POST" | "GET", endpoint: string, payload: Record<string, string>): Promise<ComponentActionResponse>;
+}
+declare function createRinggApiClient(config: ApiClientConfig): RinggApiClient;
+
+/**
+ * Theme engine — resolves, merges, and provides theme values.
+ * Pure functions with no framework dependency.
+ *
+ * Default and preset theme VALUES live in tokens/tokens.json (shared across
+ * all implementations via codegen) — only merging/contrast LOGIC lives here.
+ */
+
+/** Merge a partial user theme with the defaults. Returns a fully resolved theme. */
+declare function mergeWidgetTheme(theme?: WidgetTheme): ResolvedWidgetTheme;
+/** Merge a component-level theme with the widget theme as fallback. */
+declare function mergeComponentTheme(componentTheme?: ComponentTheme, widgetTheme?: ResolvedWidgetTheme): ComponentTheme;
+/** Get button border radius based on style */
+declare function getButtonRadius(style?: ButtonStyle): string;
+/** Check if a color is considered "light" (for auto-contrast) */
+declare function isLightColor(hexColor: string): boolean;
+/** Get a contrasting text color (black or white) for a given background */
+declare function getContrastingTextColor(bgColor: string): string;
+
+/**
+ * Gradient-aware style utilities for the widget theme system.
+ *
+ * CSS `backgroundColor` does not support gradient values — only the
+ * `background` shorthand does. These helpers detect whether a color value is
+ * a solid hex/rgb or a CSS gradient string, and extract a solid fallback
+ * color for surfaces that can't render gradients (borders, React Native).
+ *
+ * Parsing is deliberately explicit — small named steps instead of regexes —
+ * so a bad input can be walked through in a debugger function by function.
+ */
+/** Detect whether a CSS color value is a gradient string. */
+declare function isGradient(color: string): boolean;
+/** Extract all color stops from a gradient string, in order. */
+declare function extractColorsFromGradient(gradient: string): string[];
+/**
+ * Return the dominant (first) color from a gradient, or the color as-is for
+ * solid values. Falls back to the original string if no colors can be extracted.
+ */
+declare function getDominantColor(color: string): string;
+/**
+ * Determine the correct CSS properties for a background color.
+ * Returns `{ backgroundColor }` for solid colors, `{ background }` for gradients.
+ * On React Native, gradients aren't natively supported — use `getDominantColor()`
+ * to fall back to a solid color.
+ */
+declare function colorToBackground(color: string): {
+    backgroundColor?: string;
+    background?: string;
+};
+/**
+ * Always return a solid hex/rgb color string. Use for properties that don't
+ * support gradients: border, box-shadow, accent-color.
+ */
+declare function colorToSolid(color: string): string;
+/**
+ * Return the correct CSS properties for a border color.
+ * Solid colors -> `{ borderColor }`, gradients -> `{ borderImage, borderStyle }`.
+ */
+declare function colorToBorder(color: string): Record<string, string>;
 
 /**
  * RPC message formatting — transforms between backend RPC format and internal
@@ -608,12 +750,61 @@ interface UrlResolver {
  * This module handles both directions.
  */
 
+/**
+ * Transform a backend RPC payload into the internal component format.
+ * Returns null if the component type is unknown.
+ */
+declare function transformRpcToComponent(componentName: string, rpcPayload: Record<string, unknown>): SimpleComponentPayload | InteractiveFlowPayload | null;
+interface RpcMessage {
+    method: string;
+    payload: string;
+}
+/**
+ * Format a component response payload for sending back to the backend via RPC.
+ * Used when the user interacts with a component (selects a slot, submits a
+ * form, taps a button).
+ */
+declare function formatComponentResponse(componentName: string, componentId: string, responseData: Record<string, unknown>, originalConfig: unknown): RpcMessage;
+/** Format a slash command for sending via RPC. */
+declare function formatSlashCommand(command: string): RpcMessage;
 /** A Block Kit action as it goes on the wire (the UI-only `label` never does). */
 interface BlocksActionWire {
     action_id: string;
     value?: unknown;
     values: Record<string, unknown>;
 }
+/**
+ * Format a Block Kit interaction for the agent. Envelope mirrors the dashboard
+ * test widget the bot bridge was tested against: `component_id` and `values`
+ * are always present; `tool_id` is omitted when falsy and `value` when
+ * undefined (never sent as null/empty keys).
+ */
+declare function formatBlocksAction(toolId: string | undefined, componentId: string, action: BlocksActionWire): RpcMessage;
+/**
+ * Format a raw dynamic-data payload (client packs: disease search/submit).
+ * The payload already carries its own `component_type` envelope.
+ */
+declare function formatDynamicData(payload: Record<string, unknown>): RpcMessage;
+
+/**
+ * Component data helpers — pure functions for working with interactive
+ * component data. Shared across web and React Native renderers.
+ */
+
+/** Group calendar slots by date for display */
+declare function groupSlotsByDate(slots: CalendarSlot[]): GroupedSlots[];
+/** Format a slot time for display */
+declare function formatSlotTime(datetime: string, timezone?: string): string;
+/** Format a slot date for display */
+declare function formatSlotDate(datetime: string, timezone?: string): string;
+/** Interpolate a payload template with collected values */
+declare function buildPayload(template: Record<string, string>, values: Record<string, string>): Record<string, string>;
+declare function isCalendarBooking(payload: ComponentPayload): payload is CalendarBookingPayload;
+declare function isForm(payload: ComponentPayload): payload is FormPayload;
+declare function isButtons(payload: ComponentPayload): payload is ButtonsPayload;
+declare function isConfirmation(payload: ComponentPayload): payload is ConfirmationPayload;
+declare function isInteractiveFlow(payload: ComponentPayload): payload is InteractiveFlowPayload;
+declare function isBlocks(payload: ComponentPayload): payload is BlocksPayload;
 
 /**
  * Base store — the one state-sharing primitive in core.
@@ -631,6 +822,14 @@ interface Store<T> {
     getSnapshot(): T;
     subscribe(listener: (snapshot: T) => void): () => void;
 }
+/** Internal store handle: the public read API plus commit/dispose. */
+interface StoreHandle<T> extends Store<T> {
+    /** Rebuild the immutable snapshot from current state and notify subscribers. */
+    commit(): void;
+    /** Drop all subscribers. */
+    dispose(): void;
+}
+declare function createStore<T>(build: () => T): StoreHandle<T>;
 
 /**
  * Shell store — widget open/close/feedback lifecycle and the active call id.
@@ -663,6 +862,7 @@ interface ShellStore extends Store<ShellSnapshot> {
     setCurrentCallId(callId: string | null): void;
     dispose(): void;
 }
+declare function createShellStore(eventBus: EventBus, initialCallMode?: MediaType, defaultExpanded?: boolean): ShellStore;
 
 /**
  * Session store — the call lifecycle state machine.
@@ -710,6 +910,7 @@ interface SessionStore extends Store<SessionSnapshot> {
     clearError(): void;
     dispose(): void;
 }
+declare function createSessionStore(api: RinggApiClient, transport: TransportAdapter, mic: MicPermissionPort): SessionStore;
 
 /**
  * Message store — the single ordered conversation timeline.
@@ -768,6 +969,7 @@ interface MessageStore extends Store<MessageSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createMessageStore(clock: Clock): MessageStore;
 
 /**
  * Typing store — drives the "agent is typing" indicator (text mode).
@@ -798,6 +1000,7 @@ interface TypingStore extends Store<TypingSnapshot> {
     waitMinDuration(): Promise<void>;
     dispose(): void;
 }
+declare function createTypingStore(clock: Clock): TypingStore;
 
 /**
  * Component store — interactive components pushed by the backend mid-call.
@@ -845,6 +1048,9 @@ interface ComponentStore extends Store<ComponentSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createComponentStore(clock: Clock, 
+/** Commits a component to the timeline — wired to MessageStore + host events by the controller */
+commitComponent: (component: ComponentPayload) => void): ComponentStore;
 
 /**
  * Slash command store — merges commands declared in config with commands the
@@ -860,6 +1066,22 @@ interface SlashCommandStore extends Store<SlashCommandSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createSlashCommandStore(configCommands?: SlashCommand[]): SlashCommandStore;
+
+/**
+ * Timing constants — every value encodes a UX bug that was found and fixed in
+ * the production widget. Values live in tokens/defaults.json (shared across
+ * all implementations via codegen); change them there, never here.
+ */
+/** Chat-widget RPCs land before the agent's text streams in; buffer them this
+ * long waiting for the text so the widget sorts below it. */
+declare const CHAT_WIDGET_GRACE_MS: number;
+/** Once the agent text lands, release buffered widgets after this beat so the
+ * message paints first. */
+declare const CHAT_WIDGET_AFTER_TEXT_MS: number;
+/** Keep the typing dots visible at least this long — instant replies
+ * otherwise make the indicator flash. */
+declare const MIN_TYPING_INDICATOR_MS: number;
 
 /**
  * RinggWidgetController — the composition root of the widget brain.
@@ -961,4 +1183,438 @@ declare const useRinggShell: (controller: RinggWidgetController) => ShellSnapsho
 declare const useRinggComponents: (controller: RinggWidgetController) => ComponentSnapshot;
 declare const useRinggSlashCommands: (controller: RinggWidgetController) => SlashCommandSnapshot;
 
-export { type ControllerPorts, type RinggWidgetConfig, type RinggWidgetController, type TransportAdapter, createCallbackEventBus, createRinggWidgetController, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot };
+/**
+ * RinggWidget — the assembled React Native widget.
+ *
+ * The native counterpart of the web assembly: the same tree, the same order,
+ * the same branches. It holds NO conversation state — every snapshot comes
+ * from `@ringg/core` via the shared hooks and every intent is forwarded to the
+ * controller. If a behaviour looks like it belongs here, it belongs in core.
+ *
+ * Three things genuinely differ from web, all forced by the platform:
+ *
+ *  1. There is no `position: fixed`. The widget is an absolutely-filled
+ *     overlay with `pointerEvents="box-none"`, so taps pass through everywhere
+ *     except the trigger and the panel. Mount it as the LAST child of the app
+ *     root; `widgetPosition` (a web-only config) is ignored and the panel
+ *     sizes itself to the device.
+ *  2. The keyboard covers the bottom of the screen. The panel lives inside a
+ *     `KeyboardAvoidingView` so the composer stays visible while typing —
+ *     without it the input is simply unreachable in text mode.
+ *  3. The transcript cannot measure a child's offset the way web does to
+ *     anchor the newest turn's first line. It pins to the bottom instead, and
+ *     the "new message" / "typing toggled" distinction is preserved so a long
+ *     reply arriving does not yank the view while the user is reading.
+ */
+
+/**
+ * The managed form: hand it a config and it owns everything underneath.
+ *
+ * This is the RN counterpart of web's `loadAgent({ agentId, authorization })`.
+ * The transport, the endpoint table and the microphone port are ours, not the
+ * integrator's, so the app does not carry our infrastructure in its source.
+ */
+interface ManagedRinggWidgetProps {
+    config: RinggWidgetConfig;
+    /**
+     * Overrides for the ports the widget wires by default. Supply `transport` to
+     * bring your own (a mock in tests, a shared room), `urlResolver` to point at
+     * something other than the Ringg endpoints, `notification` to give the widget
+     * a sound, or `onDomAction` to handle agent-triggered app actions.
+     */
+    ports?: Partial<ControllerPorts>;
+    /**
+     * Called once with the controller the widget built, for hosts that want to
+     * listen for events or drive the panel imperatively without owning its
+     * lifecycle. The controller is destroyed on unmount — do not keep using it.
+     */
+    onReady?: (controller: RinggWidgetController) => void;
+    controller?: never;
+    room?: never;
+}
+/**
+ * The controlled form: you built the controller, you own its lifecycle.
+ *
+ * Reach for it when the widget cannot own the transport — a custom adapter, a
+ * room shared with the rest of the app, or a headless setup where the widget is
+ * one of several views on one controller.
+ */
+interface ControlledRinggWidgetProps {
+    controller: RinggWidgetController;
+    /**
+     * The LiveKit room from `createLiveKitTransport()`. Optional: it only powers
+     * the in-call audio visualizer and the mute button. Without it the widget is
+     * fully functional and the visualizer shows its ambient idle animation.
+     */
+    room?: Room;
+    config?: never;
+    ports?: never;
+    onReady?: never;
+}
+type RinggWidgetProps = ManagedRinggWidgetProps | ControlledRinggWidgetProps;
+/**
+ * The widget. Pass `config` and it owns the transport, endpoints and
+ * microphone; pass `controller` when you built those yourself.
+ */
+declare const RinggWidget: FC<RinggWidgetProps>;
+
+/**
+ * LiveKit React Native transport — the real `TransportAdapter` over
+ * `@livekit/react-native`, behavior-matched to the web adapter (which is
+ * itself matched to production, @desivocal/agents-cdn).
+ *
+ * The wire behavior is deliberately identical to `web/src/transport/
+ * livekit-transport.ts` — same Room options, same double-send chat, same
+ * agent-classification and session-ended rules — because both talk to the same
+ * backend and core drives them through the same port. Read that file's parity
+ * notes; they apply here verbatim.
+ *
+ * Only what the platform forces differs:
+ *  - remote audio needs no elements. Mobile plays subscribed audio through the
+ *    OS, so `<RoomAudioRenderer />`'s job becomes owning an audio SESSION
+ *    (see platform/audio-session.ts) rather than attaching media elements;
+ *  - `registerGlobals()` must run before a Room is constructed — the adapter
+ *    does it so a missing app-entry call is not a mysterious runtime failure;
+ *  - autoplay policy has no mobile equivalent, so the web adapter's
+ *    `startAudio()` recovery has no counterpart.
+ */
+
+interface LiveKitTransportOptions {
+    /**
+     * Extra LiveKit `RoomOptions` merged over the parity defaults
+     * (`dynacast: true, adaptiveStream: true`). Rarely needed.
+     */
+    roomOptions?: RoomOptions;
+    /**
+     * Own the native audio session for the duration of a call — the mobile
+     * equivalent of production's `<RoomAudioRenderer />`. Default true; disable
+     * when the host app already manages an audio session (an in-app player, a
+     * CallKit/ConnectionService integration).
+     */
+    manageAudioSession?: boolean;
+    /**
+     * Call `registerGlobals()` before constructing the Room. Default true.
+     * Set false when the app already calls it at its entry point — it is
+     * idempotent, so this is a formality rather than a correctness switch.
+     */
+    registerGlobals?: boolean;
+}
+interface LiveKitTransport {
+    transport: TransportAdapter;
+    /**
+     * The underlying Room, for presentational concerns the port cannot express
+     * (visualizer track handles, `isMicrophoneEnabled` readback — spec §11).
+     * State-changing calls must keep going through the transport/core.
+     */
+    room: Room;
+    /** Tears down listeners, handlers and the audio session; disconnects the room. */
+    dispose(): void;
+}
+declare const createLiveKitTransport: (options?: LiveKitTransportOptions) => LiveKitTransport;
+
+/**
+ * The Ringg-hosted endpoints, baked into the platform entry point.
+ *
+ * Core deliberately embeds no URLs — they arrive through a `UrlResolver` the
+ * entry point supplies. Every other entry point already carries this table:
+ * web bundles it in `cdn.tsx` so `loadAgent({ agentId, authorization })` needs
+ * nothing else, and Flutter exposes it as `defaultUrlResolver`. React Native
+ * was the only one asking integrators to type endpoints into their own app,
+ * which leaked our infrastructure into their source for no benefit.
+ *
+ * `mode` selects the row; it defaults to `prod`.
+ */
+
+declare const DEFAULT_ENVIRONMENT_URLS: Record<EnvironmentMode, EnvironmentUrls>;
+/** `ControllerPorts.urlResolver` default for the managed `<RinggWidget config />`. */
+declare const defaultUrlResolver: UrlResolver;
+
+/**
+ * Native audio session — React Native's replacement for the web adapter's
+ * hidden `<audio>` elements.
+ *
+ * On web, remote audio needs a DOM element to play into. On mobile it needs
+ * the opposite: nothing to attach, but an OS-level audio session that has to
+ * be configured and activated before the call and released after it, or the
+ * mic indicator stays lit and the app keeps ducking other audio.
+ *
+ * The configuration encodes the mobile audio invariants (AGENTS.md rule 10):
+ * communication mode so the call survives backgrounding and routes through the
+ * earpiece/bluetooth stack rather than the media stream, and a preferred
+ * output list that follows a headset or bluetooth device when one appears.
+ *
+ * Every call is best-effort. A device that refuses to hand over the audio
+ * session must not take the call down with it — the user still gets a
+ * (possibly routed-oddly) conversation, which beats a hard failure.
+ */
+interface AudioSessionPort {
+    /** Configure + activate. Safe to call repeatedly; only the first wins. */
+    start(): Promise<void>;
+    /** Release the session. Safe to call when never started. */
+    stop(): Promise<void>;
+}
+declare const createAudioSession: () => AudioSessionPort;
+
+/**
+ * React Native `MicPermissionPort`.
+ *
+ * Core's session store drives this on audio start: `isGranted()` first, then
+ * `request()`, aborting the call on denial — identical to web. What differs is
+ * how the answer is obtained, and the two platforms genuinely differ:
+ *
+ *  - Android exposes a real permission API, so the state can be READ without
+ *    prompting. That matters: `isGranted()` must never show a dialog, or the
+ *    user gets prompted before they have pressed anything.
+ *  - iOS has no readable pre-check from JS. The only probe is `getUserMedia`,
+ *    which prompts on first use — the same fallback the web port uses for
+ *    browsers without the Permissions API. Once answered, iOS resolves the
+ *    probe from its own record without prompting again.
+ *
+ * The probe must never keep the microphone: every track it opens is stopped
+ * before returning, or the OS recording indicator stays lit before the call
+ * has even started.
+ */
+
+declare const createNativeMicPermission: () => MicPermissionPort;
+
+/**
+ * App identity for the backend's caller allow-list.
+ *
+ * The Ringg backend allow-lists an agent's callers by `Origin`. A browser
+ * attaches it automatically; a native app sends nothing, so it has to present
+ * its own identity — by convention `<platform>://<bundleId>`, the scheme the
+ * backend accepts for app clients. Without it the webcall request is rejected
+ * before authentication even matters (`400 Origin header is required`).
+ *
+ * The bundle id is the INTEGRATOR's, not ours, so the value allow-listed in
+ * the dashboard is their app. React Native cannot read it without a native
+ * module, and this package refuses to grow one for a single string — so the id
+ * is a parameter. Expo apps have it in `expo-application`'s `applicationId`;
+ * bare apps already know their own.
+ *
+ * Mirrors `flutter/lib/src/platform/app_origin.dart`, which derives the same
+ * string from `package_info_plus`.
+ */
+/**
+ * `<platform>://<bundleId>` for the running app — e.g. `android://com.acme.app`.
+ *
+ * Returns undefined on a platform the backend has no scheme for, which
+ * includes react-native-web: there the browser sends a real `Origin` and
+ * setting one from JavaScript is forbidden anyway.
+ */
+declare const appOrigin: (bundleId: string) => string | undefined;
+
+/**
+ * React Native `NotificationPlayer`.
+ *
+ * Core decides WHEN to play (an agent reply or component landing while the
+ * widget is closed); the port only owns the how. On web that is one line —
+ * `new Audio(url)`. RN has no audio playback in the platform at all: every
+ * option (expo-audio, react-native-sound, react-native-video) is a native
+ * module, and forcing one on integrators would mean an extra pod/gradle
+ * dependency and an Expo config plugin for a notification chime.
+ *
+ * So the decision is inverted: the widget ships silent by default and the
+ * integrator opts in with three lines against whichever player their app
+ * already has. `notificationTuneUrl` from the config is handed to that player,
+ * so the URL stays a config concern on every platform.
+ */
+
+/** What an integrator's audio library has to be able to do. */
+type PlayTune = (tuneUrl: string) => void;
+/**
+ * The default. Silent, and deliberately so — a widget that cannot find an
+ * audio library should be quiet, not noisy about it on every reply.
+ */
+declare const createSilentNotificationPlayer: () => NotificationPlayer;
+/**
+ * Bridges the config's tune URL to a host-provided player.
+ *
+ * ```ts
+ * import { createAudioPlayer } from "expo-audio";
+ * const notifications = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());
+ * ```
+ *
+ * Playback failures are swallowed: a chime is best-effort by contract, and a
+ * rejected promise here must never surface mid-conversation.
+ */
+declare const createNotificationPlayer: (tuneUrl: string, playTune: PlayTune) => NotificationPlayer;
+
+/**
+ * Host action dispatcher — the React Native counterpart of the web widget's
+ * `executeDomAction`.
+ *
+ * Core normalises the `execute_dom_action` RPC into a `DomAction` and hands it
+ * to the `onDomAction` port. On web that ends in `window.dispatchEvent`, which
+ * works because the host page is already an event bus. RN has no such ambient
+ * bus, so the integrator supplies the handler and gets the event name plus the
+ * payload the agent sent — the same `{...default_payload, action_id}` detail
+ * the web CustomEvent carries, so a shared backend config drives both.
+ *
+ * Validation, logging and the "unknown kind" path stay identical to web: those
+ * are contract behaviour, not platform detail.
+ */
+
+/** What the host receives — the web CustomEvent, minus the DOM. */
+interface HostAction {
+    /** The agent-configured event name (`CustomEvent.type` on web). */
+    name: string;
+    /** `default_payload` with the action id folded in (`CustomEvent.detail`). */
+    payload: Record<string, unknown>;
+}
+type HostActionHandler = (action: HostAction) => void;
+/**
+ * Builds the `onDomAction` port. `onAction` runs in the caller's context and
+ * is allowed to throw — a broken host handler is reported, never fatal.
+ */
+declare const createHostActionDispatcher: (onAction: HostActionHandler) => (action: DomAction | undefined | null, onLog?: DomActionLogger) => void;
+
+/**
+ * Widget theme for React Native.
+ *
+ * Deliberately thin: the theme VALUES (defaults, presets) and the merge/
+ * contrast LOGIC both come from `@ringg/core` — `mergeWidgetTheme` here is
+ * core's function, not a copy. The web package still carries its own copy of
+ * that table for byte-fidelity with agents-cdn; RN has no such legacy to match
+ * and takes the shared one, so a token change reaches this platform through
+ * codegen (AGENTS.md rule 2).
+ *
+ * What IS local is unit translation. The theme surface is CSS-shaped
+ * (`"16px"`, `"9999px"`, `fontFamily: "inherit"`) because that's the contract
+ * integrators already write against on web; RN needs numbers and a real family
+ * name, so the `resolve*` helpers below are the single conversion point.
+ */
+
+interface WidgetThemeProviderProps {
+    theme?: WidgetTheme;
+    children: ReactNode;
+}
+/** `"16px"` → `16`. Unparseable values fall back rather than laying out as NaN. */
+declare const resolveRadius: (value: string | undefined, fallback?: number) => number;
+/** Button corner radius as an RN number, from core's shared style → CSS mapping. */
+declare const resolveButtonRadius: (style: ButtonStyle | undefined) => number;
+/**
+ * `"inherit"` has no meaning in RN — there is no cascade. Returning undefined
+ * lets `<Text>` fall through to the platform system font, which is what
+ * "inherit" resolves to on web for an unstyled host page.
+ */
+declare const resolveFontFamily: (fontFamily: string | undefined) => string | undefined;
+declare const WidgetThemeProvider: FC<WidgetThemeProviderProps>;
+declare const useWidgetTheme: () => ResolvedWidgetTheme;
+
+/**
+ * Gradient fills for React Native.
+ *
+ * The theme surface is CSS-shaped — `primaryColor` may be a solid hex OR a
+ * `linear-gradient(...)` string (see core `types/theme.ts`, and the gradient
+ * presets in `widget-theme`). The DOM renders those for free; RN has no
+ * gradient primitive at all, so every themed surface goes through here.
+ *
+ * Colour PARSING is not duplicated — `isGradient` / `extractColorsFromGradient`
+ * / `getDominantColor` come from `@ringg/core`, the same functions the web
+ * widget uses (AGENTS.md rule 2: shared values come from core, never a local
+ * re-implementation). Only the two things core cannot know about — the angle in
+ * SVG coordinates, and how to paint it — live in this file.
+ *
+ * Non-linear gradients (radial/conic) degrade to their dominant colour rather
+ * than approximating badly; the theme presets are all linear.
+ */
+
+interface GradientFillProps {
+    /** A theme colour: solid (`#0a0a0b`, `rgb(...)`) or a CSS gradient string. */
+    color: string;
+    /** Applied to the wrapper — size, padding, radius, alignment. */
+    style?: StyleProp<ViewStyle>;
+    children?: ReactNode;
+}
+/**
+ * Paints `color` behind `children`. Solid colours take the cheap path
+ * (`backgroundColor`); gradients get an absolutely-filled SVG layer that
+ * inherits the wrapper's rounding through `overflow: hidden`.
+ */
+declare const GradientFill: FC<GradientFillProps>;
+/**
+ * A guaranteed-solid colour, for the properties RN can only paint flat —
+ * borders, shadows, icon tints, status dots.
+ */
+declare const solidColor: (color: string) => string;
+
+/**
+ * `PortableStyles` → React Native styles.
+ *
+ * `PortableStyles` (core `types/config.ts`) is the deliberately small subset of
+ * CSS the config surface accepts precisely so it can cross platforms. Web hands
+ * the values straight to the DOM; RN cannot — it has no CSS parser, so a
+ * `"16px"` string silently breaks layout instead of throwing.
+ *
+ * This is the one place that converts. Rules, matching the Dart port
+ * (`flutter/lib/src/ui/widgets/portable_styles.dart`):
+ *  - numbers pass through as density-independent pixels;
+ *  - `"16px"` / `"16"` → `16`;
+ *  - `"50%"` survives only where RN accepts percentages (width/height);
+ *  - anything else (`calc()`, `em`, `auto`, gradients in `backgroundColor`) is
+ *    dropped rather than guessed at — a dropped style degrades, a wrong one
+ *    corrupts the layout.
+ */
+
+/** Convert a config `PortableStyles` bag into an RN `ViewStyle`. */
+declare const toViewStyle: (styles: PortableStyles | undefined) => ViewStyle;
+/** Icon sizing from `ButtonIconConfig.size` (same parsing, single value). */
+declare const toSize: (value: string | number | undefined, fallback: number) => number;
+
+/**
+ * Markdown for chat bubbles.
+ *
+ * The web widget hands agent replies to `react-markdown` + `remark-gfm` and
+ * lets Tailwind's prose plugin style the result. Neither of those crosses to
+ * RN, and this package takes no dependency for it, so what lives here is a
+ * renderer for the subset that actually appears in agent replies. Everything
+ * else falls through as the literal text the model wrote — a reply must never
+ * show half-parsed markup.
+ *
+ * Supported: paragraphs, `**bold**`, `*italic*`, inline code, `[links](url)`
+ * (handed to `Linking`), bullet and ordered lists, `#` through `######`
+ * headings, fenced code blocks, blockquotes (which may contain further
+ * blocks), horizontal rules, and backslash escapes.
+ *
+ * Not supported, deliberately: TABLES — GFM's headline feature, but a
+ * phone-width bubble has nowhere to put one, so a table degrades to a
+ * paragraph of its pipe-separated source. Also absent: images (rendered as
+ * their alt text), strikethrough, task lists, footnotes, reference links, raw
+ * HTML, and nested list indentation (nested items flatten into their parent
+ * list).
+ *
+ * Soft line breaks inside a paragraph collapse into spaces, which is what the
+ * browser does for the web widget.
+ */
+
+interface MarkdownProps {
+    content: string;
+    /** Body text. */
+    color: string;
+    /** Chrome that is not text: the rule, the quote bar, the code outline. */
+    mutedColor: string;
+    linkColor: string;
+    fontSize?: number;
+    fontFamily?: string;
+}
+declare const Markdown: FC<MarkdownProps>;
+
+/**
+ * Node identifiers for integrators and end-to-end tests.
+ *
+ * The web widget tags every meaningful node with `data-ringg="..."` and treats
+ * those names as a contract — integrators select on them, so renaming one is a
+ * breaking change. RN has no attribute namespace, but it has `testID`, which
+ * surfaces to the same audiences (Detox, Maestro, Appium, the native view
+ * hierarchy).
+ *
+ * So the mapping is mechanical and total: `data-ringg="header-title"` becomes
+ * `testID="ringg-header-title"`. The prefix keeps widget nodes from colliding
+ * with the host app's own testIDs, and the suffix stays byte-identical to web
+ * so one selector list documents both platforms.
+ */
+/** `"header-title"` → `"ringg-header-title"`. */
+declare const ringgId: (name: string) => string;
+
+export { type ApiClientConfig, type AudioSessionPort, type BaseComponent, type BlocksActionWire, type BlocksData, type BlocksPayload, type ButtonAction, type ButtonIconConfig, type ButtonItem, type ButtonSize, type ButtonStyle, type ButtonsConfig, type ButtonsData, type ButtonsPayload, CHAT_WIDGET_AFTER_TEXT_MS, CHAT_WIDGET_GRACE_MS, type CalendarBookingData, type CalendarBookingEventPayload, type CalendarBookingPayload, type CalendarSlot, type ChatMessage, type Clock, type ComponentAcknowledgementPayload, type ComponentActionResponse, type ComponentPayload, type ComponentSnapshot, type ComponentStore, type ComponentTheme, type ConfirmationData, type ConfirmationPayload, type ConnectionState, type ControlledRinggWidgetProps, type ControllerPorts, type ConversationStatusPayload, type CustomComponentPayload, WIDGET_DEFAULTS as DEFAULT_CONFIG, DEFAULT_ENVIRONMENT_URLS, DEFAULT_WIDGET_THEME, type DomAction, type DomActionKind, type DomActionLogEntry, type DomActionLogger, type DynamicDataExtension, type EnvironmentMode, type EnvironmentUrls, type ErrorState, type EventBus, type EventLogsConfig, type FeedbackPayload, type FeedbackScreenConfig, type FeedbackStatusPayload, type FlowStep, type FormData, type FormField, type FormFieldOption, type FormFieldType, type FormPayload, GradientFill, type GroupedSlots, type HostAction, type HostActionHandler, type IncomingChatMessage, type IncomingTextStream, type InnerWindowConfig, type InteractiveFlowData, type InteractiveFlowPayload, type LegalDisclaimerConfig, type LiveKitTransport, type LiveKitTransportOptions, MIN_TYPING_INDICATOR_MS, type ManagedRinggWidgetProps, Markdown, type MediaType, type MessageSnapshot, type MessageStore, type MicPermissionPort, type NotificationPlayer, type PendingResponse, type PlayTune, type PortableStyles, type ResolvedWidgetTheme, type RinggApiClient, RinggWidget, type RinggWidgetConfig, type RinggWidgetController, type RinggWidgetProps, type RpcInvocation, type RpcMessage, type SessionPhase, type SessionSnapshot, type SessionStartResult, type SessionStore, type ShellSnapshot, type ShellStore, type SimpleComponentPayload, type SlashCommand, type SlashCommandSnapshot, type SlashCommandStore, type SlashCommandToolType, type Store, type StoreHandle, type TimerHandle, type TranscriptionSegment, type TransportAdapter, type TriggerAlignment, type TriggerPlacement, type TypingSnapshot, type TypingStore, type UrlResolver, type VoiceCallConfig, WIDGET_PRESET_THEMES, type WebcallResponse, type WidgetAlignment, type WidgetEventMap, type WidgetEventName, type WidgetPositionConfig, type WidgetStatusPayload, type WidgetTheme, WidgetThemeProvider, type WidgetVariables, type WidgetViewState, appOrigin, buildPayload, colorToBackground, colorToBorder, colorToSolid, createAudioSession, createCallbackEventBus, createComponentStore, createDomEventBus, createHostActionDispatcher, createLiveKitTransport, createMessageStore, createNativeMicPermission, createNotificationPlayer, createRinggApiClient, createRinggWidgetController, createSessionStore, createShellStore, createSilentNotificationPlayer, createSlashCommandStore, createStaticUrlResolver, createStore, createSystemClock, createTypingStore, defaultUrlResolver, extractColorsFromGradient, formatBlocksAction, formatComponentResponse, formatDynamicData, formatSlashCommand, formatSlotDate, formatSlotTime, getButtonRadius, getContrastingTextColor, getDominantColor, grantedMicPermission, groupSlotsByDate, isBlocks, isButtons, isCalendarBooking, isConfirmation, isForm, isGradient, isInteractiveFlow, isLightColor, mergeComponentTheme, mergeWidgetTheme, resolveButtonRadius, resolveFontFamily, resolveRadius, ringgId, silentNotificationPlayer, solidColor, toSize, toViewStyle, transformRpcToComponent, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot, useWidgetTheme };