@promptbook/javascript 0.111.0-4 → 0.112.0-11

package/esm/src/book-components/Chat/CodeBlock/CodeBlock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Props for `<CodeBlock/>`.
+ *
+ * @private Internal utility of `<ChatMessage />` component
+ */
+type CodeBlockProps = {
+    code: string;
+    language?: string;
+    className?: string;
+    onCreateAgent?: (bookContent: string) => void;
+};
+/**
+ * Component to render a code block with syntax highlighting, copy, download, and create agent options.
+ *
+ * @private Internal utility of `<ChatMessage />` component
+ */
+export declare function CodeBlock({ code, language, className, onCreateAgent }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/src/book-components/Chat/CodeBlock/resolveCodeBlockLanguage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Monaco language identifiers supported for markdown code snippets.
+ *
+ * @private internal helper of `<CodeBlock/>`
+ */
+export type MonacoCodeBlockLanguage = 'javascript' | 'typescript' | 'html' | 'css' | 'python' | 'shell' | 'json' | 'sql' | 'book' | 'plaintext';
+/**
+ * Resolves a markdown fenced-code language label into a Monaco language identifier.
+ *
+ * Unknown languages intentionally resolve to `plaintext` so unsupported snippets render
+ * as readable text without syntax highlighting.
+ *
+ * @param language - Raw markdown code fence language label (for example `ts`, `typescript`, `bash`).
+ * @returns Canonical Monaco language identifier.
+ *
+ * @private internal helper of `<CodeBlock/>`
+ */
+export declare function resolveCodeBlockLanguage(language: string | undefined): MonacoCodeBlockLanguage;

package/esm/src/book-components/Chat/LlmChat/LlmChatProps.d.ts

@@ -0,0 +1,122 @@
+import type { LlmExecutionTools } from '../../../execution/LlmExecutionTools';
+import type { id } from '../../../types/typeAliases';
+import type { ChatProps } from '../Chat/ChatProps';
+import type { SendMessageToLlmChatFunction } from '../hooks/useSendMessageToLlmChat';
+import type { ChatMessage } from '../types/ChatMessage';
+import type { ChatParticipant } from '../types/ChatParticipant';
+import type { AgentChipData } from '../AgentChip/AgentChip';
+/**
+ * Determines how the chat reset action should behave when user clicks "New chat".
+ */
+type LlmChatResetMode = 'reset-current' | 'delegate';
+/**
+ * Props for LlmChat component, derived from ChatProps but with LLM-specific modifications
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type LlmChatProps = Omit<ChatProps, 'messages' | 'onMessage' | 'onChange'> & {
+    /**
+     * Optional thread (full chat history) to be passed to LLM execution tools.
+     * If not provided, the internal messages state will be used.
+     */
+    readonly thread?: ReadonlyArray<ChatMessage>;
+    /**
+     * LLM execution tools for chatting with the model
+     */
+    readonly llmTools: LlmExecutionTools;
+    /**
+     * Optional key for persisting conversation in localStorage
+     * When provided, the conversation will be saved and restored from localStorage
+     */
+    readonly persistenceKey?: string;
+    /**
+     * Optional initial messages to pre-populate the chat.
+     * - They can include both USER and ASSISTANT messages.
+     * - They are only used when there is no persisted conversation (persistence takes precedence).
+     * - They are not automatically persisted until the user sends a new message.
+     */
+    readonly initialMessages?: ReadonlyArray<ChatMessage>;
+    /**
+     * Called when the chat state changes (messages, participants, etc.)
+     */
+    onChange?(messages: ReadonlyArray<ChatMessage>, participants: ReadonlyArray<ChatParticipant>): void;
+    /**
+     * Called every time the user types in the input field (for draft message persistence).
+     * This is passed through to the underlying Chat component's onChange handler.
+     *
+     * @private internal utility of <AgentChatHistoryClient/>
+     */
+    onInputTextChange?(messageContent: string): void;
+    /**
+     * Optional external sendMessage function produced by useSendMessageToLlmChat hook.
+     * When provided, LlmChat will attach its internal handler to it (no React context needed).
+     */
+    readonly sendMessage?: SendMessageToLlmChatFunction;
+    /**
+     * Name of the USER as participant in the chat
+     *
+     * @default 'USER'
+     */
+    readonly userParticipantName?: id;
+    /**
+     * Name of the LLM as participant in the chat
+     *
+     * @default 'ASSISTANT'
+     */
+    readonly llmParticipantName?: id;
+    /**
+     * Optional message to be automatically sent as if the user typed it.
+     * This is useful for seamless transitions from other pages.
+     */
+    readonly autoExecuteMessage?: string;
+    /**
+     * Optional attachments that should be sent alongside the auto-executed message.
+     */
+    readonly autoExecuteMessageAttachments?: ChatMessage['attachments'];
+    /**
+     * Optional mapping of technical tool names to human-readable titles.
+     * e.g., { "web_search": "Searching the web..." }
+     */
+    readonly toolTitles?: Record<string, string>;
+    /**
+     * Optional pre-fetched team agent metadata keyed by TEAM tool name.
+     */
+    readonly teamAgentProfiles?: Record<string, AgentChipData>;
+    /**
+     * Custom variants for the placeholder thinking message shown while the agent buffers its response.
+     *
+     * @default Shared thinking message variants
+     */
+    readonly thinkingMessages?: ReadonlyArray<string>;
+    /**
+     * Extra prompt parameters to merge into every chat request.
+     */
+    readonly promptParameters?: Record<string, unknown>;
+    /**
+     * Human-friendly text shown when `LlmChat` fails to process a message.
+     * Use metadata overrides in apps (like Agents Server) instead of copying this string.
+     */
+    readonly chatFailMessage?: string;
+    /**
+     * Controls reset behavior for the action-bar "New chat" button.
+     *
+     * - `'reset-current'`: clears current message state and persistence key (default behavior).
+     * - `'delegate'`: skips internal clearing and only calls `onReset`, letting the host app
+     *   switch/create another immutable chat session.
+     *
+     * @default 'reset-current'
+     */
+    readonly resetMode?: LlmChatResetMode;
+    /**
+     * Optional custom error handler that will be called when an error occurs during chat.
+     * If not provided, errors will be displayed as messages in the chat.
+     *
+     * @param error - The error that occurred
+     * @param retry - Function to retry the last failed message
+     */
+    onError?(error: unknown, retry: () => void, failedMessage: {
+        content: string;
+        attachments: ChatMessage['attachments'];
+    }): void;
+};
+export {};

package/esm/src/book-components/Chat/hooks/useChatAutoScroll.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration for the auto-scroll behavior
+ */
+export type ChatAutoScrollConfig = {
+    /**
+     * Threshold in pixels from bottom to consider as "at bottom"
+     * @default 100
+     */
+    bottomThreshold?: number;
+    /**
+     * Whether to use smooth scrolling
+     * @default true
+     */
+    smoothScroll?: boolean;
+    /**
+     * Delay before checking scroll position after new messages (in milliseconds)
+     * @default 100
+     */
+    scrollCheckDelay?: number;
+};
+/**
+ * Hook for managing auto-scroll behavior in chat components
+ *
+ * This hook provides:
+ * - Automatic scrolling to bottom when new messages arrive (if user is already at bottom)
+ * - Detection of when user scrolls away from bottom
+ * - Scroll-to-bottom functionality with smooth animation
+ * - Mobile-optimized scrolling behavior
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function useChatAutoScroll(config?: ChatAutoScrollConfig): {
+    isAutoScrolling: boolean;
+    chatMessagesRef: (element: HTMLDivElement | null) => void;
+    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+    handleMessagesChange: (isStreaming?: boolean) => void;
+    scrollToBottom: () => void;
+    enableAutoScroll: () => void;
+    disableAutoScroll: () => void;
+    isMobile: boolean;
+};

package/esm/src/book-components/Chat/types/ChatMessage.d.ts

@@ -0,0 +1,119 @@
+import { Message } from '../../../types/Message';
+import type { ToolCall } from '../../../types/ToolCall';
+import type { id, string_date_iso8601, string_markdown } from '../../../types/typeAliases';
+export type ChatToolCall = ToolCall;
+/**
+ * Represents a single message within a chat interface.
+ *
+ * This type extends the base `Message` type by omitting internal routing fields
+ * and adding chat-specific properties like markdown content and generation status.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'threadId' | 'metadata' | 'createdAt'> & {
+    /**
+     * Force the channel to be 'PROMPTBOOK_CHAT'
+     *
+     * @default 'PROMPTBOOK_CHAT'
+     */
+    channel?: 'PROMPTBOOK_CHAT';
+    /**
+     * The content of the message with optional markdown formatting
+     */
+    content: string_markdown;
+    /**
+     * ISO 8601 timestamp for when the message was sent
+     */
+    createdAt?: string_date_iso8601;
+    /**
+     * Optional duration of agent message generation in milliseconds
+     */
+    generationDurationMs?: number;
+    /**
+     * Durable lifecycle state tracked by server-owned chat implementations.
+     */
+    lifecycleState?: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+    /**
+     * Optional failure/cancellation explanation persisted with the message.
+     */
+    lifecycleError?: string;
+    /**
+     * Optional client-generated idempotency key associated with the originating user message.
+     */
+    clientMessageId?: string;
+    /**
+     * Optional durable job id responsible for generating this assistant message.
+     */
+    jobId?: string;
+    /**
+     * Whether the message is complete (for example, if it's still being generated by an AI)
+     *
+     * @default true
+     */
+    isComplete?: boolean;
+    /**
+     * The expected answer for the message (used for testing or validation)
+     */
+    expectedAnswer?: string;
+    /**
+     * Indicates if the message was sent via a voice call
+     */
+    isVoiceCall?: boolean;
+    /**
+     * Optional tool calls made during the execution
+     */
+    readonly ongoingToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls used to produce this message.
+     */
+    readonly toolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls that have been completed
+     *
+     * @deprecated Use `toolCalls` instead.
+     */
+    readonly completedToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional file attachments
+     */
+    attachments?: Array<{
+        /**
+         * The name of the file
+         */
+        name: string;
+        /**
+         * The type of the file
+         */
+        type: string;
+        /**
+         * The URL where the file is stored
+         */
+        url: string;
+    }>;
+    /**
+     * Optional source citations/annotations (from RAG systems like OpenAI Assistants)
+     */
+    readonly citations?: ReadonlyArray<{
+        /**
+         * The unique identifier for the citation (e.g., "5:13")
+         */
+        id: string;
+        /**
+         * The source document name (e.g., "document.pdf")
+         */
+        source: string;
+        /**
+         * Optional URL to the source document
+         */
+        url?: string;
+        /**
+         * Optional preview/excerpt from the source
+         */
+        excerpt?: string;
+    }>;
+};
+/**
+ * TODO: Make all fields readonly
+ * TODO: Delete `expectedAnswer` from ChatMessage
+ * TODO: Rename `date` into `created`+`modified`
+ */

package/esm/src/book-components/Chat/utils/ChatPersistence.d.ts

@@ -0,0 +1,41 @@
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Utility functions for persisting chat conversations in localStorage
+ *
+ * @private util of `LlmChat`
+ */
+export declare class ChatPersistence {
+    private static readonly STORAGE_PREFIX;
+    /**
+     * In-memory fallback storage used when browser storage is unavailable or throws.
+     */
+    private static readonly MEMORY_STORAGE;
+    /**
+     * Builds normalized storage key for one persistence scope.
+     */
+    private static resolveStorageKey;
+    /**
+     * Stores serialized payload in the in-memory fallback store.
+     */
+    private static saveToMemoryStorage;
+    /**
+     * Resolves serialized payload from localStorage and falls back to in-memory storage.
+     */
+    private static loadSerializedMessages;
+    /**
+     * Save messages to localStorage under the given key
+     */
+    static saveMessages(persistenceKey: string, messages: ReadonlyArray<ChatMessage>): void;
+    /**
+     * Load messages from localStorage for the given key
+     */
+    static loadMessages(persistenceKey: string): ChatMessage[];
+    /**
+     * Clear messages from localStorage for the given key
+     */
+    static clearMessages(persistenceKey: string): void;
+    /**
+     * Check if localStorage is available
+     */
+    static isAvailable(): boolean;
+}

package/esm/src/book-components/Chat/utils/ChatPersistence.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment jsdom
+ */
+export {};

package/esm/src/book-components/Chat/utils/createTeamToolNameFromUrl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds a TEAM tool name from teammate identity.
+ *
+ * @private utility of chat components
+ */
+export declare function createTeamToolNameFromUrl(url: string, teammateLabel?: string): string;
+/**
+ * Checks whether a tool name belongs to a TEAM tool.
+ *
+ * @private utility of chat components
+ */
+export declare function isTeamToolName(name: string): boolean;

package/esm/src/book-components/Chat/utils/parseMessageButtons.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Represents a quick message button parsed from chat markdown.
+ *
+ * @private internal helper type of `MessageButton`
+ */
+export type MessageQuickButton = {
+    type: 'message';
+    text: string;
+    message: string;
+};
+/**
+ * Represents a quick action button parsed from chat markdown.
+ *
+ * @private internal helper type of `MessageButton`
+ */
+export type ActionQuickButton = {
+    type: 'action';
+    text: string;
+    code: string;
+};
+/**
+ * Represents one parsed quick button from chat markdown.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MessageButton = MessageQuickButton | ActionQuickButton;
+/**
+ * Parses markdown quick buttons in the format `[Button Text](?message=...)` or `[Button Text](?action=...)`.
+ * Returns both the content without supported quick buttons and the extracted button definitions.
+ *
+ * @param content The markdown content that may contain buttons
+ * @returns Object with contentWithoutButtons and buttons array
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function parseMessageButtons(content: string): {
+    contentWithoutButtons: string;
+    buttons: MessageButton[];
+};

package/esm/src/book-components/Chat/utils/resolveToolCallFromChatMessages.d.ts

@@ -0,0 +1,13 @@
+import type { ToolCall } from '../../../types/ToolCall';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Resolves the latest known snapshot of one tool call from rendered chat messages.
+ *
+ * @param messages - Chat messages currently rendered in the UI.
+ * @param toolCallIdentity - Stable tool-call identity.
+ * @param fallbackToolCall - Optional fallback snapshot used before live state is found.
+ * @returns Latest matching tool call or the fallback snapshot.
+ *
+ * @private internal helper for chat tool-call modal state
+ */
+export declare function resolveToolCallFromChatMessages(messages: ReadonlyArray<ChatMessage>, toolCallIdentity: string | null, fallbackToolCall: ToolCall | null): ToolCall | null;

package/esm/src/book-components/Chat/utils/resolveToolCallState.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCall, ToolCallState } from '../../../types/ToolCall';
+/**
+ * Resolves one explicit or inferred lifecycle state for a tool call snapshot.
+ *
+ * @param toolCall - Tool call snapshot to inspect.
+ * @returns Resolved lifecycle state.
+ *
+ * @private internal helper for chat tool-call rendering
+ */
+export declare function resolveToolCallState(toolCall: ToolCall): ToolCallState;

package/esm/src/book-components/Chat/utils/sanitizeStreamingMessageContent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Options that customize how streaming message content is sanitized.
+ */
+type SanitizeStreamingMessageContentOptions = {
+    /**
+     * Whether the chat message has finished streaming.
+     */
+    isComplete?: boolean;
+};
+type FenceDelimiter = '```' | '~~~';
+type CodeFenceStreamingBoundary = {
+    readonly kind: 'codeFence';
+    readonly index: number;
+    readonly delimiter: FenceDelimiter;
+};
+type MathStreamingBoundary = {
+    readonly kind: 'math';
+    readonly index: number;
+};
+type ImagePromptStreamingBoundary = {
+    readonly kind: 'imagePrompt';
+    readonly index: number;
+};
+/**
+ * Metadata describing the most-recently introduced rich feature that is still streaming.
+ *
+ * @private internal helper of <ChatMessageItem/>
+ */
+export type StreamingFeatureBoundary = CodeFenceStreamingBoundary | MathStreamingBoundary | ImagePromptStreamingBoundary;
+/**
+ * Examines the latest streaming feature boundary so rich placeholders can be rendered while content is still being produced.
+ *
+ * @param content - Message text that may still be streaming.
+ * @returns Metadata describing the richest streaming feature or `null` when nothing is being hidden.
+ * @private internal helper of <ChatMessageItem/>
+ */
+export declare function getLatestStreamingFeatureBoundary(content: string): StreamingFeatureBoundary | null;
+/**
+ * Trims trailing rich-feature markup from streaming messages so users do not see the raw source while the feature loads.
+ *
+ * @param content - Full markdown text produced by the assistant.
+ * @param options - Sanitization options (streaming state).
+ * @returns Text that is safe to render during streaming.
+ * @private internal helper of <ChatMessageItem/>
+ */
+export declare function sanitizeStreamingMessageContent(content: string, options?: SanitizeStreamingMessageContentOptions): string;
+export {};

package/esm/src/book-components/Chat/utils/splitMessageContentIntoSegments.d.ts

@@ -0,0 +1,54 @@
+import type { GeoJsonObject } from 'geojson';
+import type { ImagePromptSegment } from './parseImagePrompts';
+/**
+ * Segment that represents plain markdown text inside a chat message.
+ */
+/**
+ * Segment that represents plain markdown text inside a chat message.
+ *
+ * @private internal helper of `<ChatMessageItem/>`
+ */
+export type ChatTextSegment = {
+    type: 'text';
+    content: string;
+};
+/**
+ * Segment that represents a Leaflet-ready map rendered from GeoJSON data.
+ */
+/**
+ * Segment that represents a Leaflet-ready map rendered from GeoJSON data.
+ *
+ * @private internal helper of `<ChatMessageItem/>`
+ */
+export type ChatMapSegment = {
+    type: 'map';
+    data: GeoJsonObject;
+};
+/**
+ * Segment that represents a fenced code block inside a chat message.
+ */
+/**
+ * Segment that represents a fenced code block inside a chat message.
+ *
+ * @private internal helper of `<ChatMessageItem/>`
+ */
+export type ChatCodeSegment = {
+    type: 'code';
+    language?: string;
+    code: string;
+};
+/**
+ * Composite segment type that covers text, image prompts, map features, and code blocks.
+ */
+/**
+ * Composite segment type that covers text, image prompts, map features, and code blocks.
+ *
+ * @private internal helper of `<ChatMessageItem/>`
+ */
+export type ChatMessageContentSegment = ImagePromptSegment | ChatTextSegment | ChatMapSegment | ChatCodeSegment;
+/**
+ * Splits chat message content into markdown, image prompt, and map segments while preserving their order.
+ *
+ * @private internal helper of `<ChatMessageItem/>`
+ */
+export declare function splitMessageContentIntoSegments(content: string): ReadonlyArray<ChatMessageContentSegment>;

package/esm/src/book-components/Chat/utils/thinkingMessageVariants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Normalizes configured thinking-message variants to a non-empty trimmed list.
+ *
+ * @param thinkingMessages Raw thinking-message variants.
+ * @returns Trimmed non-empty variants or the shared defaults.
+ * @private internal helper for Promptbook chat placeholders
+ */
+export declare function normalizeThinkingMessageVariants(thinkingMessages?: ReadonlyArray<string>): ReadonlyArray<string>;
+/**
+ * Returns a random delay used between browser-side thinking-message rotations.
+ *
+ * @returns Delay in milliseconds.
+ * @private internal helper for Promptbook chat placeholders
+ */
+export declare function getRandomThinkingMessageDelayMs(): number;
+/**
+ * Selects one random thinking-message variant, avoiding the previous variant when possible.
+ *
+ * @param variants Available thinking-message variants.
+ * @param excludeVariant Variant to avoid repeating immediately.
+ * @returns Selected thinking-message variant.
+ * @private internal helper for Promptbook chat placeholders
+ */
+export declare function getRandomThinkingMessageVariant(variants: ReadonlyArray<string>, excludeVariant?: string): string;

package/esm/src/book-components/Chat/utils/toolCallParsing/RunBrowserToolResult.d.ts

@@ -0,0 +1,50 @@
+import type { TODO_any } from '../../../../utils/organization/TODO_any';
+/**
+ * Structured browser artifact metadata extracted from `run_browser` tool result.
+ *
+ * @private type of toolCallParsing
+ */
+export type RunBrowserToolArtifact = {
+    kind: 'screenshot' | 'video';
+    path: string;
+    label: string;
+    actionSummary?: string;
+};
+/**
+ * Structured browser action summary extracted from `run_browser` tool result.
+ *
+ * @private type of toolCallParsing
+ */
+export type RunBrowserToolAction = {
+    summary: string;
+};
+/**
+ * Structured browser error metadata extracted from `run_browser` payload.
+ *
+ * @private type of toolCallParsing
+ */
+export type RunBrowserToolError = {
+    code: string;
+    message: string;
+    isRetryable: boolean;
+    suggestedNextSteps: Array<string>;
+    debug: Record<string, TODO_any> | null;
+};
+/**
+ * Parsed `run_browser` tool result normalized for modal rendering.
+ *
+ * @private type of toolCallParsing
+ */
+export type RunBrowserToolResult = {
+    sessionId: string | null;
+    mode: string | null;
+    modeUsed: string | null;
+    initialUrl: string | null;
+    finalUrl: string | null;
+    finalTitle: string | null;
+    warning: string | null;
+    fallbackContent: string | null;
+    error: RunBrowserToolError | null;
+    artifacts: Array<RunBrowserToolArtifact>;
+    actions: Array<RunBrowserToolAction>;
+};

package/esm/src/book-components/Chat/utils/toolCallParsing/TeamToolResult.d.ts

@@ -0,0 +1,30 @@
+import type { ToolCall } from '../../../../types/ToolCall';
+/**
+ * Structured payload emitted by TEAM tool calls.
+ */
+export type TeamToolResult = {
+    teammate?: {
+        url?: string;
+        label?: string;
+        instructions?: string;
+        toolName?: string;
+        pseudoAgentKind?: 'USER' | 'VOID';
+    };
+    request?: string;
+    response?: string;
+    interaction?: {
+        kind?: string;
+        prompt?: string;
+    };
+    /**
+     * Tool calls executed by the teammate while answering.
+     */
+    toolCalls?: ReadonlyArray<ToolCall>;
+    error?: string | null;
+    conversation?: Array<{
+        sender?: string;
+        name?: string;
+        role?: string;
+        content?: string;
+    }>;
+};

package/esm/src/book-components/Chat/utils/toolCallParsing/extractSearchResults.d.ts

@@ -0,0 +1,19 @@
+import type { TODO_any } from '../../../../utils/organization/TODO_any';
+/**
+ * Normalized search extraction result for chat rendering.
+ *
+ * @private type of extractSearchResults
+ */
+type SearchResultsExtraction = {
+    results: Array<TODO_any>;
+    rawText: string | null;
+};
+/**
+ * Extracts search results and optional raw text from mixed payload formats.
+ *
+ * @param resultRaw - Raw search tool output.
+ * @returns Normalized extraction object.
+ * @private function of toolCallParsing
+ */
+export declare function extractSearchResults(resultRaw: TODO_any): SearchResultsExtraction;
+export {};