@frankieai/react 0.2.8 → 0.2.10

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { ReactNode, CSSProperties, MutableRefObject, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
 import { PublicWidgetConfig, CreateSessionResponse, ChatAttachment, FrankieServerEvent, WidgetTheme, LoadedSkill, ApiToolInventory } from '@frankieai/core';
 export { FrankieServerEvent, PublicWidgetConfig, WidgetTheme } from '@frankieai/core';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -7,6 +7,26 @@ import { VariantProps } from 'class-variance-authority';
 import { ClassValue } from 'clsx';
 
 type PageContext = Record<string, string | number | boolean | null>;
+/**
+ * How the widget reaches the host's own API for client-side tool execution.
+ *
+ * When a workspace marks an API source `execution: "client"`, Frankie asks the
+ * browser to make the call itself — from the user's existing session — instead
+ * of calling the API from Frankie's servers. This says where that API lives and
+ * how the browser authenticates to it: normally the app's own cookies
+ * (`credentials: "include"` on a same-origin or CORS-allowed API), or a bearer
+ * token the app already holds, added via `headers`. Frankie sends no credential
+ * of its own; the host API authorizes the call exactly as it would any request
+ * from the host's frontend.
+ */
+interface HostApiClientOptions {
+    /** Base URL that operation paths resolve against, e.g. "/api" or "https://api.acme.com". */
+    baseUrl: string;
+    /** fetch credentials mode. "include" sends the app's cookies. Defaults to "same-origin". */
+    credentials?: RequestCredentials;
+    /** Extra headers for every host call (e.g. an app access token). Awaited per call. */
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+}
 /**
  * The hosted Frankie data plane. Embedding needs only a publishable key, so
  * `baseUrl` defaults here — override it only when self-hosting the server.
@@ -24,6 +44,13 @@ interface FrankieClientOptions {
      */
     getUserToken?: () => Promise<string | undefined> | string | undefined;
     fetchImpl?: typeof fetch;
+    /**
+     * Reaches the host's own API for `execution: "client"` tool calls (see
+     * `HostApiClientOptions`). Required only for workspaces that use client-side
+     * execution; omit it and a client-mode tool reports that no host API is
+     * configured rather than calling anything.
+     */
+    api?: HostApiClientOptions;
     /**
      * Remember the session (and, in the hook, the transcript) in localStorage so a
      * page reload resumes the same anonymous conversation. Authenticated chat
@@ -51,7 +78,8 @@ declare class FrankieClient {
     private readonly baseUrl;
     private readonly doFetch;
     private session?;
-    private sessionUserToken?;
+    /** Identity (JWT `sub`, else the raw token) the cached session was issued for. */
+    private sessionUserKey?;
     constructor(options: FrankieClientOptions);
     get sessionId(): string | undefined;
     get conversationId(): string | undefined;
@@ -79,6 +107,14 @@ declare class FrankieClient {
         attachments?: ChatAttachment[];
         signal?: AbortSignal;
     }, onEvent: (event: FrankieServerEvent) => void): Promise<void>;
+    /**
+     * Execute one host API call in the browser and report the outcome back to the
+     * server. Never throws: a transport failure or a missing `api` client becomes
+     * a result the model can see and explain, exactly like a non-2xx status.
+     */
+    private runClientTool;
+    private callHostApi;
+    private postToolResult;
     private unwrap;
 }
 declare function readEventStream(body: ReadableStream<Uint8Array>): AsyncGenerator<FrankieServerEvent>;
@@ -88,6 +124,15 @@ interface FrankieProviderProps extends FrankieClientOptions {
     context?: PageContext;
     theme?: WidgetTheme;
     config?: PublicWidgetConfig;
+    /**
+     * Set to `false` if the host compiles Frankie's classes itself instead of
+     * loading `@frankieai/react/styles.css` — e.g. a Tailwind v4 host that
+     * `@source`s this package — so it isn't given a second, independently-themed
+     * copy of the stylesheet when its own build never sets the styles-ready
+     * sentinel. Defaults to `true`: a host that simply forgot the import, or
+     * whose CSS chunk hasn't landed yet, still gets a correctly-styled widget.
+     */
+    injectStyles?: boolean;
 }
 interface FrankieContextValue {
     client: FrankieClient;
@@ -96,8 +141,9 @@ interface FrankieContextValue {
     loading: boolean;
     context?: PageContext;
     theme?: WidgetTheme;
+    injectStyles: boolean;
 }
-declare function FrankieProvider({ children, context, theme, config: providedConfig, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
+declare function FrankieProvider({ children, context, theme, config: providedConfig, injectStyles, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
 declare function useFrankie(): FrankieContextValue;
 declare function useFrankieTheme(): WidgetTheme | undefined;
 
@@ -265,8 +311,10 @@ interface ComposerProps {
     attachments?: ComposerAttachmentsConfig;
     /** Enables a model dropdown when provided with at least one model. */
     modelPicker?: ComposerModelPicker;
+    /** Populated with a function that focuses the input, so a "type your own" choice can jump here. */
+    focusHandleRef?: MutableRefObject<(() => void) | null>;
 }
-declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker }: ComposerProps): react.JSX.Element;
+declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker, focusHandleRef }: ComposerProps): react.JSX.Element;
 
 interface MessageBubbleProps {
     message: ChatMessage;
@@ -274,22 +322,53 @@ interface MessageBubbleProps {
     avatarUrl?: string;
     showToolActivity: boolean;
     renderTool?: (tool: ToolActivity) => ReactNode;
+    /** Send a picked choice as the next message. Omitted when the host renders its own. */
+    onChoose?: (choice: string) => void;
+    /** Focus the composer so the user can type their own answer instead of picking. */
+    onRequestInput?: () => void;
+    /** True only for the newest message, so stale choices from earlier turns aren't clickable. */
+    active?: boolean;
+    /** A turn is in flight, so choices should be disabled. */
+    busy?: boolean;
 }
-declare function MessageBubble({ message, assistantName, avatarUrl, showToolActivity, renderTool, }: MessageBubbleProps): react.JSX.Element;
+declare const MessageBubble: react.NamedExoticComponent<MessageBubbleProps>;
 declare function TypingDots(): react.JSX.Element;
+/**
+ * A shimmering skeleton shown while the reply is still being produced — before
+ * the first words, or during the pause after a tool result while the model
+ * composes its answer — so those gaps read as "loading" rather than frozen.
+ */
+declare function Thinking(): react.JSX.Element;
 
 /**
- * A deliberately small Markdown subset — paragraphs, lists, fenced code, bold,
- * italic, inline code and links.
+ * A deliberately small Markdown subset — headings, paragraphs, lists, fenced
+ * code, bold, italic, inline code and links.
  *
  * Everything is rendered as React elements; nothing goes through
  * `dangerouslySetInnerHTML`. Model output lands in someone else's production
  * page, so it is never trusted as markup.
+ *
+ * Memoized on `text`: while a reply streams, the parent re-renders every frame,
+ * but the block tree is only recomputed when the text actually grows — the
+ * settled messages above never re-parse at all.
  */
-declare function Markdown({ text, className }: {
+declare const Markdown: react.NamedExoticComponent<{
     text: string;
     className?: string;
-}): react.JSX.Element;
+}>;
+
+/**
+ * Clickable answer options the agent offered via a `frankie:choices` block.
+ * Picking one sends it as the next message. A trailing "Something else" row
+ * doesn't send — it moves the caret to the composer so the user can type their
+ * own answer, while the offered options stay put in case they change their mind.
+ */
+declare function Choices({ options, onPick, onSomethingElse, disabled, }: {
+    options: string[];
+    onPick: (choice: string) => void;
+    onSomethingElse?: () => void;
+    disabled?: boolean;
+}): react.JSX.Element | null;
 
 declare function SuggestedPrompts({ prompts, onPick, disabled, }: {
     prompts: string[];
@@ -351,6 +430,31 @@ declare function Separator({ className }: {
 /** `forwardRef` rather than React 19's ref-as-prop, so React 18 hosts work too. */
 declare const Textarea: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
 
+/**
+ * Interactive choice blocks.
+ *
+ * The agent can end a reply with a fenced block to offer the user a small set
+ * of discrete answers:
+ *
+ *     ```frankie:choices
+ *     British
+ *     Indian
+ *     Australian
+ *     ```
+ *
+ * The SDK lifts that block out of the prose and renders it as clickable options
+ * (the composer stays open, so the user can always type their own answer). The
+ * block is a plain fenced code block, so a host that doesn't understand it just
+ * shows a harmless code listing instead — never broken markup.
+ */
+interface ExtractedChoices {
+    /** The reply text with the choices block removed. */
+    body: string;
+    /** The offered options, or null when there is no complete block. */
+    options: string[] | null;
+}
+declare function extractChoices(text: string): ExtractedChoices;
+
 /**
  * Map a theme to the CSS custom properties the widget's styles read.
  *
@@ -365,4 +469,4 @@ declare function resolveMode(mode: WidgetTheme["mode"]): "light" | "dark";
 /** shadcn/ui's class helper: conditional classes with Tailwind conflict resolution. */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };
+export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Choices, Composer, type ExtractedChoices, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, Thinking, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, extractChoices, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { ReactNode, CSSProperties, MutableRefObject, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
 import { PublicWidgetConfig, CreateSessionResponse, ChatAttachment, FrankieServerEvent, WidgetTheme, LoadedSkill, ApiToolInventory } from '@frankieai/core';
 export { FrankieServerEvent, PublicWidgetConfig, WidgetTheme } from '@frankieai/core';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -7,6 +7,26 @@ import { VariantProps } from 'class-variance-authority';
 import { ClassValue } from 'clsx';
 
 type PageContext = Record<string, string | number | boolean | null>;
+/**
+ * How the widget reaches the host's own API for client-side tool execution.
+ *
+ * When a workspace marks an API source `execution: "client"`, Frankie asks the
+ * browser to make the call itself — from the user's existing session — instead
+ * of calling the API from Frankie's servers. This says where that API lives and
+ * how the browser authenticates to it: normally the app's own cookies
+ * (`credentials: "include"` on a same-origin or CORS-allowed API), or a bearer
+ * token the app already holds, added via `headers`. Frankie sends no credential
+ * of its own; the host API authorizes the call exactly as it would any request
+ * from the host's frontend.
+ */
+interface HostApiClientOptions {
+    /** Base URL that operation paths resolve against, e.g. "/api" or "https://api.acme.com". */
+    baseUrl: string;
+    /** fetch credentials mode. "include" sends the app's cookies. Defaults to "same-origin". */
+    credentials?: RequestCredentials;
+    /** Extra headers for every host call (e.g. an app access token). Awaited per call. */
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+}
 /**
  * The hosted Frankie data plane. Embedding needs only a publishable key, so
  * `baseUrl` defaults here — override it only when self-hosting the server.
@@ -24,6 +44,13 @@ interface FrankieClientOptions {
      */
     getUserToken?: () => Promise<string | undefined> | string | undefined;
     fetchImpl?: typeof fetch;
+    /**
+     * Reaches the host's own API for `execution: "client"` tool calls (see
+     * `HostApiClientOptions`). Required only for workspaces that use client-side
+     * execution; omit it and a client-mode tool reports that no host API is
+     * configured rather than calling anything.
+     */
+    api?: HostApiClientOptions;
     /**
      * Remember the session (and, in the hook, the transcript) in localStorage so a
      * page reload resumes the same anonymous conversation. Authenticated chat
@@ -51,7 +78,8 @@ declare class FrankieClient {
     private readonly baseUrl;
     private readonly doFetch;
     private session?;
-    private sessionUserToken?;
+    /** Identity (JWT `sub`, else the raw token) the cached session was issued for. */
+    private sessionUserKey?;
     constructor(options: FrankieClientOptions);
     get sessionId(): string | undefined;
     get conversationId(): string | undefined;
@@ -79,6 +107,14 @@ declare class FrankieClient {
         attachments?: ChatAttachment[];
         signal?: AbortSignal;
     }, onEvent: (event: FrankieServerEvent) => void): Promise<void>;
+    /**
+     * Execute one host API call in the browser and report the outcome back to the
+     * server. Never throws: a transport failure or a missing `api` client becomes
+     * a result the model can see and explain, exactly like a non-2xx status.
+     */
+    private runClientTool;
+    private callHostApi;
+    private postToolResult;
     private unwrap;
 }
 declare function readEventStream(body: ReadableStream<Uint8Array>): AsyncGenerator<FrankieServerEvent>;
@@ -88,6 +124,15 @@ interface FrankieProviderProps extends FrankieClientOptions {
     context?: PageContext;
     theme?: WidgetTheme;
     config?: PublicWidgetConfig;
+    /**
+     * Set to `false` if the host compiles Frankie's classes itself instead of
+     * loading `@frankieai/react/styles.css` — e.g. a Tailwind v4 host that
+     * `@source`s this package — so it isn't given a second, independently-themed
+     * copy of the stylesheet when its own build never sets the styles-ready
+     * sentinel. Defaults to `true`: a host that simply forgot the import, or
+     * whose CSS chunk hasn't landed yet, still gets a correctly-styled widget.
+     */
+    injectStyles?: boolean;
 }
 interface FrankieContextValue {
     client: FrankieClient;
@@ -96,8 +141,9 @@ interface FrankieContextValue {
     loading: boolean;
     context?: PageContext;
     theme?: WidgetTheme;
+    injectStyles: boolean;
 }
-declare function FrankieProvider({ children, context, theme, config: providedConfig, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
+declare function FrankieProvider({ children, context, theme, config: providedConfig, injectStyles, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
 declare function useFrankie(): FrankieContextValue;
 declare function useFrankieTheme(): WidgetTheme | undefined;
 
@@ -265,8 +311,10 @@ interface ComposerProps {
     attachments?: ComposerAttachmentsConfig;
     /** Enables a model dropdown when provided with at least one model. */
     modelPicker?: ComposerModelPicker;
+    /** Populated with a function that focuses the input, so a "type your own" choice can jump here. */
+    focusHandleRef?: MutableRefObject<(() => void) | null>;
 }
-declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker }: ComposerProps): react.JSX.Element;
+declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker, focusHandleRef }: ComposerProps): react.JSX.Element;
 
 interface MessageBubbleProps {
     message: ChatMessage;
@@ -274,22 +322,53 @@ interface MessageBubbleProps {
     avatarUrl?: string;
     showToolActivity: boolean;
     renderTool?: (tool: ToolActivity) => ReactNode;
+    /** Send a picked choice as the next message. Omitted when the host renders its own. */
+    onChoose?: (choice: string) => void;
+    /** Focus the composer so the user can type their own answer instead of picking. */
+    onRequestInput?: () => void;
+    /** True only for the newest message, so stale choices from earlier turns aren't clickable. */
+    active?: boolean;
+    /** A turn is in flight, so choices should be disabled. */
+    busy?: boolean;
 }
-declare function MessageBubble({ message, assistantName, avatarUrl, showToolActivity, renderTool, }: MessageBubbleProps): react.JSX.Element;
+declare const MessageBubble: react.NamedExoticComponent<MessageBubbleProps>;
 declare function TypingDots(): react.JSX.Element;
+/**
+ * A shimmering skeleton shown while the reply is still being produced — before
+ * the first words, or during the pause after a tool result while the model
+ * composes its answer — so those gaps read as "loading" rather than frozen.
+ */
+declare function Thinking(): react.JSX.Element;
 
 /**
- * A deliberately small Markdown subset — paragraphs, lists, fenced code, bold,
- * italic, inline code and links.
+ * A deliberately small Markdown subset — headings, paragraphs, lists, fenced
+ * code, bold, italic, inline code and links.
  *
  * Everything is rendered as React elements; nothing goes through
  * `dangerouslySetInnerHTML`. Model output lands in someone else's production
  * page, so it is never trusted as markup.
+ *
+ * Memoized on `text`: while a reply streams, the parent re-renders every frame,
+ * but the block tree is only recomputed when the text actually grows — the
+ * settled messages above never re-parse at all.
  */
-declare function Markdown({ text, className }: {
+declare const Markdown: react.NamedExoticComponent<{
     text: string;
     className?: string;
-}): react.JSX.Element;
+}>;
+
+/**
+ * Clickable answer options the agent offered via a `frankie:choices` block.
+ * Picking one sends it as the next message. A trailing "Something else" row
+ * doesn't send — it moves the caret to the composer so the user can type their
+ * own answer, while the offered options stay put in case they change their mind.
+ */
+declare function Choices({ options, onPick, onSomethingElse, disabled, }: {
+    options: string[];
+    onPick: (choice: string) => void;
+    onSomethingElse?: () => void;
+    disabled?: boolean;
+}): react.JSX.Element | null;
 
 declare function SuggestedPrompts({ prompts, onPick, disabled, }: {
     prompts: string[];
@@ -351,6 +430,31 @@ declare function Separator({ className }: {
 /** `forwardRef` rather than React 19's ref-as-prop, so React 18 hosts work too. */
 declare const Textarea: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
 
+/**
+ * Interactive choice blocks.
+ *
+ * The agent can end a reply with a fenced block to offer the user a small set
+ * of discrete answers:
+ *
+ *     ```frankie:choices
+ *     British
+ *     Indian
+ *     Australian
+ *     ```
+ *
+ * The SDK lifts that block out of the prose and renders it as clickable options
+ * (the composer stays open, so the user can always type their own answer). The
+ * block is a plain fenced code block, so a host that doesn't understand it just
+ * shows a harmless code listing instead — never broken markup.
+ */
+interface ExtractedChoices {
+    /** The reply text with the choices block removed. */
+    body: string;
+    /** The offered options, or null when there is no complete block. */
+    options: string[] | null;
+}
+declare function extractChoices(text: string): ExtractedChoices;
+
 /**
  * Map a theme to the CSS custom properties the widget's styles read.
  *
@@ -365,4 +469,4 @@ declare function resolveMode(mode: WidgetTheme["mode"]): "light" | "dark";
 /** shadcn/ui's class helper: conditional classes with Tailwind conflict resolution. */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };
+export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Choices, Composer, type ExtractedChoices, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, Thinking, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, extractChoices, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };