@aganzefelicite/responsekit-react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,313 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
+import { Block, AiResponse, AiStreamState, ConversationSummary, MessageResponse, TextBlock as TextBlock$1, KpiBlock as KpiBlock$1, ChartBlock as ChartBlock$1, TableBlock as TableBlock$1, InsightBlock as InsightBlock$1, RecommendationBlock as RecommendationBlock$1, FilterBlock as FilterBlock$1, SseEvent } from '@responsekit/schema';
+export * from '@responsekit/schema';
+
+/**
+ * Actions are the SDK's single outbound channel. Blocks and custom components emit
+ * actions; the host app decides what they mean. The SDK NEVER runs business logic —
+ * it only forwards intent via `onAction`.
+ */
+interface DownloadAction {
+    type: "DOWNLOAD";
+    /** What to download — e.g. a table's rows, a chart's data, or a server-side artifact id. */
+    format?: "CSV" | "JSON" | string;
+    filename?: string;
+    data?: unknown;
+    /** The block that originated the action, when applicable. */
+    blockId?: string;
+}
+interface OpenLinkAction {
+    type: "OPEN_LINK";
+    href: string;
+    target?: "_blank" | "_self";
+    blockId?: string;
+}
+interface RefreshAction {
+    type: "REFRESH";
+    responseId?: string;
+}
+interface CustomAction {
+    type: "CUSTOM";
+    /** A host-defined action name, e.g. "DRILL_DOWN". */
+    name: string;
+    payload?: unknown;
+    blockId?: string;
+}
+/**
+ * Open union: the known actions plus an escape hatch for host- or plugin-defined ones.
+ * Consumers can narrow on `action.type`.
+ */
+type AiAction = DownloadAction | OpenLinkAction | RefreshAction | CustomAction | ({
+    type: string;
+} & Record<string, unknown>);
+type OnAction = (action: AiAction) => void;
+/** A no-op default so components can always call `onAction` safely. */
+declare const noopAction: OnAction;
+
+/** Props every block component receives. */
+interface BlockComponentProps<B extends Block = Block> {
+    block: B;
+    onAction: OnAction;
+}
+type BlockComponent<B extends Block = Block> = ComponentType<BlockComponentProps<B>>;
+/**
+ * Override map passed to `<AiRenderer components={...} />`. Keys are block `type`
+ * strings; values replace the default component for that type. Custom (non-builtin)
+ * types are allowed too.
+ */
+type BlockComponents = Record<string, BlockComponent>;
+
+interface AiRendererProps {
+    /** A complete response object (typically from `useAiStream().response`). */
+    response: AiResponse;
+    /** Per-render component overrides, keyed by block `type`. */
+    components?: BlockComponents;
+    /** Single outbound action channel. */
+    onAction?: OnAction;
+    className?: string;
+}
+/**
+ * Renders a complete `AiResponse`. Switches on `response.type`:
+ *  - TEXT      → Markdown (when `format === "MARKDOWN"`) or plain text
+ *  - ANALYTICS → optional title, then each block via the registry, in order
+ *  - ERROR     → error component
+ *
+ * Every block is wrapped in an error boundary and resolved through the registry, so
+ * unknown types or render failures degrade to a fallback rather than crashing.
+ */
+declare function AiRenderer({ response, components, onAction, className, }: AiRendererProps): react.JSX.Element;
+declare function ErrorView({ message }: {
+    message: string;
+}): react.JSX.Element;
+
+interface UseAiStreamOptions {
+    baseUrl: string;
+    conversationId: string;
+    message: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    /**
+     * Auto-start the stream when `message` (and the endpoint) are set. Default true.
+     * Set false to control start/stop manually via the returned `start()`/`stop()`.
+     */
+    enabled?: boolean;
+}
+interface UseAiStreamResult extends AiStreamState {
+    isStreaming: boolean;
+    /** (Re)start the stream. Aborts any in-flight stream first. */
+    start: () => void;
+    /** Abort the in-flight stream. */
+    stop: () => void;
+}
+/**
+ * Consume the SSE message stream and reduce its events into live `AiStreamState`.
+ * The response is assembled incrementally (blocks appended as they arrive).
+ */
+declare function useAiStream(options: UseAiStreamOptions): UseAiStreamResult;
+
+interface AiStreamProps extends UseAiStreamOptions {
+    components?: BlockComponents;
+    onAction?: OnAction;
+    className?: string;
+    /** Custom loading UI. Receives the live progress state. */
+    renderLoading?: (state: AiStreamState) => ReactNode;
+    /** Custom error UI. */
+    renderError?: (error: string) => ReactNode;
+}
+/**
+ * End-to-end: streams from `POST {baseUrl}/api/conversations/{id}/messages`, shows a
+ * progress-driven loading state, then renders the assembled response with `AiRenderer`.
+ *
+ * As soon as any response content exists it is rendered live (blocks appear in order);
+ * the loading indicator stays visible until the stream finishes.
+ */
+declare function AiStream({ components, onAction, className, renderLoading, renderError, ...streamOptions }: AiStreamProps): react.JSX.Element;
+
+/** One user turn plus the assistant's (streaming or finished) response state. */
+interface ChatTurn {
+    id: string;
+    userMessage: string;
+    /** Live stream state for this turn; `state.response` is the assembled AiResponse. */
+    state: AiStreamState;
+}
+interface UseChatOptions {
+    baseUrl: string;
+    /**
+     * Use an existing conversation. If omitted, a conversation is created lazily on the
+     * first `send()` (via POST /api/conversations).
+     */
+    conversationId?: string;
+    /** Title for the auto-created conversation. Defaults to the first message (truncated). */
+    titleFor?: (firstMessage: string) => string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+interface UseChatResult {
+    conversationId?: string;
+    turns: ChatTurn[];
+    isStreaming: boolean;
+    error?: string;
+    /** Send a message. Creates the conversation first if needed. */
+    send: (message: string) => Promise<void>;
+    /** Abort the in-flight stream (if any). */
+    stop: () => void;
+    /** Clear all turns (keeps the conversation id). */
+    reset: () => void;
+    /** Start a brand-new conversation: clears turns and drops the id so the next
+     * `send()` creates a fresh conversation. */
+    newConversation: () => void;
+}
+/**
+ * Drive a multi-message conversation: one conversation id, an ordered list of turns,
+ * each assistant response assembled incrementally from the SSE stream. Built directly
+ * on `streamMessage` + `streamReducer` so it stays a thin, predictable layer.
+ */
+declare function useChat(options: UseChatOptions): UseChatResult;
+
+/**
+ * Framework-agnostic REST client for the conversation lifecycle.
+ *
+ * The SDK's core job is message → render, but hosts still need to create/list/rename
+ * conversations. These are thin, dependency-free `fetch` wrappers over the backend's
+ * plain REST endpoints, kept optional so the render path stays lean. (Lives next to
+ * `streamMessage`; both are UI-agnostic and could move to a `core` package later.)
+ */
+interface ConversationClientOptions {
+    baseUrl: string;
+    /** Extra headers (e.g. Authorization) merged onto every request. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Injectable fetch (tests / non-browser runtimes). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** POST /api/conversations — create a conversation. */
+declare function createConversation(opts: ConversationClientOptions & {
+    title?: string;
+}): Promise<ConversationSummary>;
+/** GET /api/conversations — list conversations. */
+declare function listConversations(opts: ConversationClientOptions): Promise<ConversationSummary[]>;
+/** GET /api/conversations/{id} — fetch one conversation. */
+declare function getConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<ConversationSummary>;
+/** PATCH /api/conversations/{id} — rename a conversation. */
+declare function renameConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+    title: string;
+}): Promise<ConversationSummary>;
+/** DELETE /api/conversations/{id}. */
+declare function deleteConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<void>;
+/** GET /api/conversations/{id}/messages — load prior messages (history). */
+declare function getMessages(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<MessageResponse[]>;
+
+interface RegisterBlockOptions {
+    type: string;
+    component: BlockComponent;
+    /** When false, does not replace an existing global registration. Default true. */
+    override?: boolean;
+}
+/** Register a custom/unknown block type globally (extension point). */
+declare function registerBlock(options: RegisterBlockOptions): void;
+/** Remove a global registration (mainly for tests/cleanup). */
+declare function unregisterBlock(type: string): void;
+/** Snapshot of globally registered types. */
+declare function registeredBlockTypes(): string[];
+/**
+ * Resolve the component for a block type. Always returns a component — never null —
+ * falling back to `FallbackBlock` so rendering can never crash on an unknown type.
+ */
+declare function resolveBlockComponent(type: string, overrides?: BlockComponents): BlockComponent;
+
+/** A block-level TEXT node. Rendered as (safe) Markdown. */
+declare function TextBlock({ block }: BlockComponentProps<TextBlock$1>): react.JSX.Element;
+
+declare function KpiBlock({ block }: BlockComponentProps<KpiBlock$1>): react.JSX.Element;
+
+declare function ChartBlock({ block }: BlockComponentProps<ChartBlock$1>): react.JSX.Element;
+
+declare function TableBlock({ block, onAction }: BlockComponentProps<TableBlock$1>): react.JSX.Element;
+
+declare function InsightBlock({ block }: BlockComponentProps<InsightBlock$1>): react.JSX.Element;
+
+declare function RecommendationBlock({ block, }: BlockComponentProps<RecommendationBlock$1>): react.JSX.Element;
+
+declare function FilterBlock({ block }: BlockComponentProps<FilterBlock$1>): react.JSX.Element;
+
+/**
+ * The graceful catch-all. Rendered for unknown block types, or known types whose
+ * required fields were missing/invalid (the parser coerces those to UnknownBlock).
+ * Never throws; optionally shows the raw payload in dev to aid debugging.
+ */
+declare function FallbackBlock({ block }: BlockComponentProps<Block>): react.JSX.Element;
+
+/** The built-in block components, keyed by block `type`. */
+declare const defaultBlockComponents: BlockComponents;
+
+interface MarkdownProps {
+    children: string;
+    className?: string;
+}
+/**
+ * Renders AI-authored Markdown safely.
+ *
+ * Security posture (see the prompt's non-negotiables):
+ *  - GitHub-flavored Markdown via `remark-gfm`.
+ *  - NO `rehype-raw`: raw HTML in the source is treated as text, never parsed/injected.
+ *  - `react-markdown` builds a React tree — no `dangerouslySetInnerHTML` anywhere.
+ *  - URLs are passed through react-markdown's default transform, which strips
+ *    dangerous protocols (javascript:, data:, etc.). Links open in a new tab with
+ *    `rel="noopener noreferrer"`.
+ */
+declare function Markdown({ children, className }: MarkdownProps): react.JSX.Element;
+
+interface Props {
+    children: ReactNode;
+    fallback: (error: Error) => ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * Catches render-time errors from a single block/subtree so one bad custom component
+ * (or an unexpected data shape) can degrade to a fallback instead of taking down the
+ * whole host app. This backs the "never crash" guarantee at the render layer, on top
+ * of the schema-level validation.
+ */
+declare class ErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+/**
+ * SSE transport. The message endpoint is POST and streams `text/event-stream`, so the
+ * native `EventSource` (GET-only) cannot be used — we drive `fetch` + `ReadableStream`
+ * and parse the SSE framing by hand.
+ */
+interface StreamMessageOptions {
+    baseUrl: string;
+    conversationId: string;
+    message: string;
+    /** Extra headers (e.g. Authorization) merged onto the request. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Injectable fetch (tests / non-browser runtimes). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Build the POST message URL for a conversation. */
+declare function messageUrl(baseUrl: string, conversationId: string): string;
+/**
+ * Open the stream and yield typed `SseEvent`s as they arrive. Never throws for
+ * transport/parse problems — it yields a terminal `error` event instead, so the
+ * reducer/host always sees a clean signal.
+ */
+declare function streamMessage(options: StreamMessageOptions): AsyncGenerator<SseEvent>;
+
+export { type AiAction, AiRenderer, type AiRendererProps, AiStream, type AiStreamProps, type BlockComponent, type BlockComponentProps, type BlockComponents, ChartBlock, type ChatTurn, type ConversationClientOptions, type CustomAction, type DownloadAction, ErrorBoundary, ErrorView, FallbackBlock, FilterBlock, InsightBlock, KpiBlock, Markdown, type MarkdownProps, type OnAction, type OpenLinkAction, RecommendationBlock, type RefreshAction, type RegisterBlockOptions, type StreamMessageOptions, TableBlock, TextBlock, type UseAiStreamOptions, type UseAiStreamResult, type UseChatOptions, type UseChatResult, createConversation, defaultBlockComponents, deleteConversation, getConversation, getMessages, listConversations, messageUrl, noopAction, registerBlock, registeredBlockTypes, renameConversation, resolveBlockComponent, streamMessage, unregisterBlock, useAiStream, useChat };

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
+import { Block, AiResponse, AiStreamState, ConversationSummary, MessageResponse, TextBlock as TextBlock$1, KpiBlock as KpiBlock$1, ChartBlock as ChartBlock$1, TableBlock as TableBlock$1, InsightBlock as InsightBlock$1, RecommendationBlock as RecommendationBlock$1, FilterBlock as FilterBlock$1, SseEvent } from '@responsekit/schema';
+export * from '@responsekit/schema';
+
+/**
+ * Actions are the SDK's single outbound channel. Blocks and custom components emit
+ * actions; the host app decides what they mean. The SDK NEVER runs business logic —
+ * it only forwards intent via `onAction`.
+ */
+interface DownloadAction {
+    type: "DOWNLOAD";
+    /** What to download — e.g. a table's rows, a chart's data, or a server-side artifact id. */
+    format?: "CSV" | "JSON" | string;
+    filename?: string;
+    data?: unknown;
+    /** The block that originated the action, when applicable. */
+    blockId?: string;
+}
+interface OpenLinkAction {
+    type: "OPEN_LINK";
+    href: string;
+    target?: "_blank" | "_self";
+    blockId?: string;
+}
+interface RefreshAction {
+    type: "REFRESH";
+    responseId?: string;
+}
+interface CustomAction {
+    type: "CUSTOM";
+    /** A host-defined action name, e.g. "DRILL_DOWN". */
+    name: string;
+    payload?: unknown;
+    blockId?: string;
+}
+/**
+ * Open union: the known actions plus an escape hatch for host- or plugin-defined ones.
+ * Consumers can narrow on `action.type`.
+ */
+type AiAction = DownloadAction | OpenLinkAction | RefreshAction | CustomAction | ({
+    type: string;
+} & Record<string, unknown>);
+type OnAction = (action: AiAction) => void;
+/** A no-op default so components can always call `onAction` safely. */
+declare const noopAction: OnAction;
+
+/** Props every block component receives. */
+interface BlockComponentProps<B extends Block = Block> {
+    block: B;
+    onAction: OnAction;
+}
+type BlockComponent<B extends Block = Block> = ComponentType<BlockComponentProps<B>>;
+/**
+ * Override map passed to `<AiRenderer components={...} />`. Keys are block `type`
+ * strings; values replace the default component for that type. Custom (non-builtin)
+ * types are allowed too.
+ */
+type BlockComponents = Record<string, BlockComponent>;
+
+interface AiRendererProps {
+    /** A complete response object (typically from `useAiStream().response`). */
+    response: AiResponse;
+    /** Per-render component overrides, keyed by block `type`. */
+    components?: BlockComponents;
+    /** Single outbound action channel. */
+    onAction?: OnAction;
+    className?: string;
+}
+/**
+ * Renders a complete `AiResponse`. Switches on `response.type`:
+ *  - TEXT      → Markdown (when `format === "MARKDOWN"`) or plain text
+ *  - ANALYTICS → optional title, then each block via the registry, in order
+ *  - ERROR     → error component
+ *
+ * Every block is wrapped in an error boundary and resolved through the registry, so
+ * unknown types or render failures degrade to a fallback rather than crashing.
+ */
+declare function AiRenderer({ response, components, onAction, className, }: AiRendererProps): react.JSX.Element;
+declare function ErrorView({ message }: {
+    message: string;
+}): react.JSX.Element;
+
+interface UseAiStreamOptions {
+    baseUrl: string;
+    conversationId: string;
+    message: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    /**
+     * Auto-start the stream when `message` (and the endpoint) are set. Default true.
+     * Set false to control start/stop manually via the returned `start()`/`stop()`.
+     */
+    enabled?: boolean;
+}
+interface UseAiStreamResult extends AiStreamState {
+    isStreaming: boolean;
+    /** (Re)start the stream. Aborts any in-flight stream first. */
+    start: () => void;
+    /** Abort the in-flight stream. */
+    stop: () => void;
+}
+/**
+ * Consume the SSE message stream and reduce its events into live `AiStreamState`.
+ * The response is assembled incrementally (blocks appended as they arrive).
+ */
+declare function useAiStream(options: UseAiStreamOptions): UseAiStreamResult;
+
+interface AiStreamProps extends UseAiStreamOptions {
+    components?: BlockComponents;
+    onAction?: OnAction;
+    className?: string;
+    /** Custom loading UI. Receives the live progress state. */
+    renderLoading?: (state: AiStreamState) => ReactNode;
+    /** Custom error UI. */
+    renderError?: (error: string) => ReactNode;
+}
+/**
+ * End-to-end: streams from `POST {baseUrl}/api/conversations/{id}/messages`, shows a
+ * progress-driven loading state, then renders the assembled response with `AiRenderer`.
+ *
+ * As soon as any response content exists it is rendered live (blocks appear in order);
+ * the loading indicator stays visible until the stream finishes.
+ */
+declare function AiStream({ components, onAction, className, renderLoading, renderError, ...streamOptions }: AiStreamProps): react.JSX.Element;
+
+/** One user turn plus the assistant's (streaming or finished) response state. */
+interface ChatTurn {
+    id: string;
+    userMessage: string;
+    /** Live stream state for this turn; `state.response` is the assembled AiResponse. */
+    state: AiStreamState;
+}
+interface UseChatOptions {
+    baseUrl: string;
+    /**
+     * Use an existing conversation. If omitted, a conversation is created lazily on the
+     * first `send()` (via POST /api/conversations).
+     */
+    conversationId?: string;
+    /** Title for the auto-created conversation. Defaults to the first message (truncated). */
+    titleFor?: (firstMessage: string) => string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+interface UseChatResult {
+    conversationId?: string;
+    turns: ChatTurn[];
+    isStreaming: boolean;
+    error?: string;
+    /** Send a message. Creates the conversation first if needed. */
+    send: (message: string) => Promise<void>;
+    /** Abort the in-flight stream (if any). */
+    stop: () => void;
+    /** Clear all turns (keeps the conversation id). */
+    reset: () => void;
+    /** Start a brand-new conversation: clears turns and drops the id so the next
+     * `send()` creates a fresh conversation. */
+    newConversation: () => void;
+}
+/**
+ * Drive a multi-message conversation: one conversation id, an ordered list of turns,
+ * each assistant response assembled incrementally from the SSE stream. Built directly
+ * on `streamMessage` + `streamReducer` so it stays a thin, predictable layer.
+ */
+declare function useChat(options: UseChatOptions): UseChatResult;
+
+/**
+ * Framework-agnostic REST client for the conversation lifecycle.
+ *
+ * The SDK's core job is message → render, but hosts still need to create/list/rename
+ * conversations. These are thin, dependency-free `fetch` wrappers over the backend's
+ * plain REST endpoints, kept optional so the render path stays lean. (Lives next to
+ * `streamMessage`; both are UI-agnostic and could move to a `core` package later.)
+ */
+interface ConversationClientOptions {
+    baseUrl: string;
+    /** Extra headers (e.g. Authorization) merged onto every request. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Injectable fetch (tests / non-browser runtimes). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** POST /api/conversations — create a conversation. */
+declare function createConversation(opts: ConversationClientOptions & {
+    title?: string;
+}): Promise<ConversationSummary>;
+/** GET /api/conversations — list conversations. */
+declare function listConversations(opts: ConversationClientOptions): Promise<ConversationSummary[]>;
+/** GET /api/conversations/{id} — fetch one conversation. */
+declare function getConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<ConversationSummary>;
+/** PATCH /api/conversations/{id} — rename a conversation. */
+declare function renameConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+    title: string;
+}): Promise<ConversationSummary>;
+/** DELETE /api/conversations/{id}. */
+declare function deleteConversation(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<void>;
+/** GET /api/conversations/{id}/messages — load prior messages (history). */
+declare function getMessages(opts: ConversationClientOptions & {
+    conversationId: string;
+}): Promise<MessageResponse[]>;
+
+interface RegisterBlockOptions {
+    type: string;
+    component: BlockComponent;
+    /** When false, does not replace an existing global registration. Default true. */
+    override?: boolean;
+}
+/** Register a custom/unknown block type globally (extension point). */
+declare function registerBlock(options: RegisterBlockOptions): void;
+/** Remove a global registration (mainly for tests/cleanup). */
+declare function unregisterBlock(type: string): void;
+/** Snapshot of globally registered types. */
+declare function registeredBlockTypes(): string[];
+/**
+ * Resolve the component for a block type. Always returns a component — never null —
+ * falling back to `FallbackBlock` so rendering can never crash on an unknown type.
+ */
+declare function resolveBlockComponent(type: string, overrides?: BlockComponents): BlockComponent;
+
+/** A block-level TEXT node. Rendered as (safe) Markdown. */
+declare function TextBlock({ block }: BlockComponentProps<TextBlock$1>): react.JSX.Element;
+
+declare function KpiBlock({ block }: BlockComponentProps<KpiBlock$1>): react.JSX.Element;
+
+declare function ChartBlock({ block }: BlockComponentProps<ChartBlock$1>): react.JSX.Element;
+
+declare function TableBlock({ block, onAction }: BlockComponentProps<TableBlock$1>): react.JSX.Element;
+
+declare function InsightBlock({ block }: BlockComponentProps<InsightBlock$1>): react.JSX.Element;
+
+declare function RecommendationBlock({ block, }: BlockComponentProps<RecommendationBlock$1>): react.JSX.Element;
+
+declare function FilterBlock({ block }: BlockComponentProps<FilterBlock$1>): react.JSX.Element;
+
+/**
+ * The graceful catch-all. Rendered for unknown block types, or known types whose
+ * required fields were missing/invalid (the parser coerces those to UnknownBlock).
+ * Never throws; optionally shows the raw payload in dev to aid debugging.
+ */
+declare function FallbackBlock({ block }: BlockComponentProps<Block>): react.JSX.Element;
+
+/** The built-in block components, keyed by block `type`. */
+declare const defaultBlockComponents: BlockComponents;
+
+interface MarkdownProps {
+    children: string;
+    className?: string;
+}
+/**
+ * Renders AI-authored Markdown safely.
+ *
+ * Security posture (see the prompt's non-negotiables):
+ *  - GitHub-flavored Markdown via `remark-gfm`.
+ *  - NO `rehype-raw`: raw HTML in the source is treated as text, never parsed/injected.
+ *  - `react-markdown` builds a React tree — no `dangerouslySetInnerHTML` anywhere.
+ *  - URLs are passed through react-markdown's default transform, which strips
+ *    dangerous protocols (javascript:, data:, etc.). Links open in a new tab with
+ *    `rel="noopener noreferrer"`.
+ */
+declare function Markdown({ children, className }: MarkdownProps): react.JSX.Element;
+
+interface Props {
+    children: ReactNode;
+    fallback: (error: Error) => ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * Catches render-time errors from a single block/subtree so one bad custom component
+ * (or an unexpected data shape) can degrade to a fallback instead of taking down the
+ * whole host app. This backs the "never crash" guarantee at the render layer, on top
+ * of the schema-level validation.
+ */
+declare class ErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+/**
+ * SSE transport. The message endpoint is POST and streams `text/event-stream`, so the
+ * native `EventSource` (GET-only) cannot be used — we drive `fetch` + `ReadableStream`
+ * and parse the SSE framing by hand.
+ */
+interface StreamMessageOptions {
+    baseUrl: string;
+    conversationId: string;
+    message: string;
+    /** Extra headers (e.g. Authorization) merged onto the request. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Injectable fetch (tests / non-browser runtimes). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Build the POST message URL for a conversation. */
+declare function messageUrl(baseUrl: string, conversationId: string): string;
+/**
+ * Open the stream and yield typed `SseEvent`s as they arrive. Never throws for
+ * transport/parse problems — it yields a terminal `error` event instead, so the
+ * reducer/host always sees a clean signal.
+ */
+declare function streamMessage(options: StreamMessageOptions): AsyncGenerator<SseEvent>;
+
+export { type AiAction, AiRenderer, type AiRendererProps, AiStream, type AiStreamProps, type BlockComponent, type BlockComponentProps, type BlockComponents, ChartBlock, type ChatTurn, type ConversationClientOptions, type CustomAction, type DownloadAction, ErrorBoundary, ErrorView, FallbackBlock, FilterBlock, InsightBlock, KpiBlock, Markdown, type MarkdownProps, type OnAction, type OpenLinkAction, RecommendationBlock, type RefreshAction, type RegisterBlockOptions, type StreamMessageOptions, TableBlock, TextBlock, type UseAiStreamOptions, type UseAiStreamResult, type UseChatOptions, type UseChatResult, createConversation, defaultBlockComponents, deleteConversation, getConversation, getMessages, listConversations, messageUrl, noopAction, registerBlock, registeredBlockTypes, renameConversation, resolveBlockComponent, streamMessage, unregisterBlock, useAiStream, useChat };