@promptbook/javascript 0.113.0-9 → 0.114.0-1

package/umd/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.d.ts

@@ -1,4 +1,46 @@
+import type { string_book } from '../agent-source/string_book';
 import type { string_markdown } from '../../types/string_markdown';
+import type { string_language } from '../../types/string_token';
+/**
+ * Agent source incorporated into a server-specific Book language manual.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type BookLanguageDocumentationAgent = {
+    /**
+     * Human-readable title shown above the baked example.
+     */
+    readonly agentName: string;
+    /**
+     * Current Book source used both as an example and to detect used commitments.
+     */
+    readonly agentSource: string_book;
+};
+/**
+ * Optional context used to tailor a standalone Book language manual.
+ *
+ * An empty `agents` array deliberately has the same effect as omitting this
+ * option, which keeps the non-customized manual portable between servers.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type CreateStandaloneBookLanguageMarkdownOptions = {
+    /**
+     * Server agents whose sources should be baked into examples and usage priority.
+     */
+    readonly agents?: ReadonlyArray<BookLanguageDocumentationAgent>;
+    /**
+     * Language the manual should be written in, English is used as the fallback.
+     */
+    readonly language?: string_language;
+    /**
+     * Whether the closing chapter with low-level commitments should be generated.
+     *
+     * Low-level commitments are intended for advanced use only, so they are
+     * omitted unless they are explicitly requested.
+     */
+    readonly isLowLevelCommitmentsIncluded?: boolean;
+};
 /**
  * Creates one standalone markdown guide for Book language (Book 2.0 / agent language).
  *
@@ -11,4 +53,4 @@ import type { string_markdown } from '../../types/string_markdown';
  *
  * @public exported from `@promptbook/core`
  */
-export declare function createStandaloneBookLanguageMarkdown(): string_markdown;
+export declare function createStandaloneBookLanguageMarkdown(options?: CreateStandaloneBookLanguageMarkdownOptions): string_markdown;

package/umd/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/book-2.0/book-language-documentation/czechBookLanguageManualDictionary.d.ts

@@ -0,0 +1,10 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Czech translation of the standalone Book language manual.
+ *
+ * Commitment keywords are intentionally kept in English, because they are part
+ * of the Book language syntax and must be written exactly as-is.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+export declare const czechBookLanguageManualDictionary: BookLanguageManualDictionary;

package/umd/src/book-2.0/book-language-documentation/englishBookLanguageManualDictionary.d.ts

@@ -0,0 +1,10 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Canonical English wording of the standalone Book language manual.
+ *
+ * Every other language pack is a translation of this dictionary and is resolved
+ * through `getBookLanguageManualDictionary`.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+export declare const englishBookLanguageManualDictionary: BookLanguageManualDictionary;

package/umd/src/book-2.0/book-language-documentation/getBookLanguageManualCommitmentGroups.d.ts

@@ -0,0 +1,33 @@
+import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
+/**
+ * One grouped commitment definition as returned by the runtime registry.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroup = ReturnType<typeof getGroupedCommitmentDefinitions>[number];
+/**
+ * Commitment groups of the manual, split by how prominently they are documented.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroups = {
+    /**
+     * Commitments documented in the main catalog.
+     */
+    readonly documented: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+    /**
+     * Low-level and unfinished commitments documented in their own closing chapter.
+     */
+    readonly lowLevel: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+};
+/**
+ * Splits the commitment registry into the groups documented by the manual.
+ *
+ * Deprecated commitments are intentionally left out completely, so that the
+ * manual never teaches a keyword that should no longer be written into a book.
+ *
+ * @returns Commitment groups for the main catalog and for the low-level chapter.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getBookLanguageManualCommitmentGroups(): BookLanguageManualCommitmentGroups;

package/umd/src/book-2.0/book-language-documentation/getBookLanguageManualDictionary.d.ts

@@ -0,0 +1,15 @@
+import type { string_language } from '../../types/string_token';
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Resolves the manual dictionary for one requested language.
+ *
+ * Unknown and region-qualified codes (for example `cs-CZ`) fall back to the
+ * closest available pack and finally to English, so an export never fails
+ * because of an unsupported language.
+ *
+ * @param language - Requested language code.
+ * @returns Manual dictionary for the requested language or the English fallback.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getBookLanguageManualDictionary(language: string_language | null | undefined): BookLanguageManualDictionary;

package/umd/src/book-2.0/book-language-documentation/getSafeCodeBlock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a safe markdown fenced code block even when content contains backticks.
+ *
+ * @param content - Raw code content.
+ * @param language - Optional info-string language label.
+ * @returns Fenced code block.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getSafeCodeBlock(content: string, language?: string): string;

package/umd/src/book-2.0/book-language-documentation/renderCommitmentCatalogSection.d.ts

@@ -0,0 +1,30 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+import type { BookLanguageManualCommitmentGroup } from './getBookLanguageManualCommitmentGroups';
+/**
+ * Options for rendering one commitment section of the generated catalog.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type RenderCommitmentCatalogSectionOptions = {
+    /**
+     * Grouped commitment definition with aliases.
+     */
+    readonly groupedCommitment: BookLanguageManualCommitmentGroup;
+    /**
+     * Number of uses across the selected server agents.
+     */
+    readonly usageCount: number;
+    /**
+     * Translated labels of the manual.
+     */
+    readonly dictionary: BookLanguageManualDictionary;
+};
+/**
+ * Renders one commitment section in the generated catalog.
+ *
+ * @param options - Commitment group, usage statistics, and translated labels.
+ * @returns Markdown section for a single commitment.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function renderCommitmentCatalogSection(options: RenderCommitmentCatalogSectionOptions): string;

package/umd/src/book-2.0/book-language-documentation/renderGroupedCommitmentDocumentationMarkdown.d.ts

@@ -35,9 +35,10 @@ type GroupedCommitmentDocumentationSource = {
  * surfaces present them as one conceptual switch instead of two isolated pages.
  *
  * @param group - Grouped commitment metadata.
+ * @param headingLevelShift - How many levels the entry is nested by its host document.
  * @returns Markdown body for the docs page/catalog entry.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-export declare function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommitmentDocumentationSource): string;
+export declare function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommitmentDocumentationSource, headingLevelShift?: number): string;
 export {};

package/umd/src/book-2.0/book-language-documentation/toStableAnchorId.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a heading label into a stable markdown anchor id.
+ *
+ * Anchors are generated from language-neutral identifiers, so deep links into
+ * the manual keep working in every translation.
+ *
+ * @param value - Raw heading/identifier text.
+ * @returns Stable lowercase anchor id.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function toStableAnchorId(value: string): string;

package/umd/src/book-3.0/AgentMessageRunReport.d.ts

@@ -0,0 +1,78 @@
+import type { Usage } from '../execution/Usage';
+import type { CodexLoginMethod } from './codexLoginMethod';
+/**
+ * File suffix appended to one answered message book to store its run report sidecar.
+ *
+ * For example `messages/finished/2026-07-16-thread.book` is reported in
+ * `messages/finished/2026-07-16-thread.book.report.json`.
+ *
+ * @private internal constant of the agent folder convention
+ */
+export declare const AGENT_MESSAGE_RUN_REPORT_FILE_SUFFIX = ".report.json";
+/**
+ * Report describing how one queued agent message was answered by a CLI harness runner.
+ *
+ * The agent runner writes it next to the answered message book so consumers
+ * (for example the Agents Server task details) can show which runner, authentication
+ * method and usage one answer cost without re-parsing the runner output.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent folder convention
+ */
+export type AgentMessageRunReport = {
+    /**
+     * Report schema version for forward compatibility.
+     */
+    readonly version: 1;
+    /**
+     * Name of the harness runner which answered the message, for example `codex` or `claude-code`.
+     */
+    readonly runnerName: string;
+    /**
+     * Model identifier used by the runner, when known.
+     */
+    readonly modelName?: string;
+    /**
+     * Authentication method the runner used, when it can be determined.
+     *
+     * Currently only the OpenAI Codex runner reports this (its ChatGPT account vs. `OPENAI_API_KEY`);
+     * other runners leave it `undefined`.
+     */
+    readonly loginMethod?: CodexLoginMethod;
+    /**
+     * Usage statistics of the run (price, token counts, duration).
+     */
+    readonly usage: Usage;
+};
+/**
+ * Builds the run-report sidecar path for one message book path.
+ *
+ * Works for absolute and relative paths because the suffix is simply appended.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function buildAgentMessageRunReportPath(messageFilePath: string): string;
+/**
+ * Serializes one run report into the stable JSON format persisted next to the answered message book.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function serializeAgentMessageRunReport(report: AgentMessageRunReport): string;
+/**
+ * Validates one already-parsed JSON value as a run report.
+ *
+ * @returns The typed report, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip malformed or foreign sidecar files.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function normalizeAgentMessageRunReport(value: unknown): AgentMessageRunReport | null;
+/**
+ * Parses one run-report sidecar file content.
+ *
+ * @returns The typed report, or `null` when the content is not valid JSON or does not match the expected shape.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function parseAgentMessageRunReport(reportFileContent: string): AgentMessageRunReport | null;

package/umd/src/book-3.0/AgentMessageRunReport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/book-3.0/agentFolderPaths.d.ts

@@ -28,3 +28,12 @@ export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
  * @public exported from `@promptbook/node`
  */
 export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to the agent-owned projects root used by the agent folder convention.
+ *
+ * Each direct child directory is one project — an isolated folder the agent fully controls
+ * (files, scripts, optionally its own git repository).
+ *
+ * @private internal constant of the agent folder convention, used by agent runners and the Agents Server
+ */
+export declare const AGENT_PROJECTS_DIRECTORY_PATH = "projects";

package/umd/src/book-3.0/codexLoginMethod.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Authentication method that the OpenAI Codex CLI used for one run.
+ *
+ * - `chatgpt` — the server's ChatGPT account (subscription) login was used.
+ * - `api` — `OPENAI_API_KEY` API-key authentication was used.
+ * - `unknown` — the runner could not determine which method Codex used.
+ *
+ * @private internal type of the OpenAI Codex runner and the Agents Server task details
+ */
+export type CodexLoginMethod = 'chatgpt' | 'api' | 'unknown';
+/**
+ * Stable stdout marker printed by the generated Codex runner script to report which login method it used.
+ *
+ * The marker is followed by the resolved method keyword, for example `ptbk-codex-login-method: chatgpt`,
+ * so `parseCodexLoginMethodFromOutput` can recover it from the captured runner output.
+ *
+ * @private internal constant of the OpenAI Codex runner
+ */
+export declare const CODEX_LOGIN_METHOD_MARKER = "ptbk-codex-login-method:";
+/**
+ * Substring that the `codex login status` command prints when the Codex CLI is signed in with a
+ * ChatGPT subscription account instead of an `OPENAI_API_KEY`.
+ *
+ * This is the single source of truth for detecting an active ChatGPT login, reused by the Codex runner
+ * script and by the Agents Server harness authentication status resolver.
+ *
+ * @private internal constant of the OpenAI Codex runner and the Agents Server Harness Auth
+ */
+export declare const CODEX_CHATGPT_LOGIN_STATUS_NEEDLE = "Logged in using ChatGPT";
+/**
+ * Formats one Codex login method as a short human-readable label for prompt status lines and task details.
+ *
+ * @returns The label to append to a status line, or `undefined` when there is no meaningful method to show
+ * (for example the runner is not Codex or the method could not be determined), so callers can omit the suffix.
+ *
+ * @private internal utility of the OpenAI Codex runner and the Agents Server task details
+ */
+export declare function formatCodexLoginMethod(loginMethod: CodexLoginMethod | undefined): string | undefined;

package/umd/src/book-components/BookEditor/BookEditorSyntaxTokenStyles.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One token emitted while highlighting Book source.
+ *
+ * @private internal type of `BookEditor`
+ */
+export type BookEditorSyntaxTokenName = 'title' | 'commitment' | 'note-commitment' | 'todo-commitment' | 'parameter' | 'agent-reference' | 'code-block';
+/**
+ * Visual style of one Book syntax token.
+ *
+ * @private internal type of `BookEditor`
+ */
+export type BookEditorSyntaxTokenStyle = {
+    /**
+     * Token this style belongs to.
+     */
+    readonly token: BookEditorSyntaxTokenName;
+    /**
+     * Text color of the token.
+     */
+    readonly foreground: string;
+    /**
+     * Optional background color of the token.
+     */
+    readonly background?: string;
+    /**
+     * Optional space-separated font style, for example `bold underline`.
+     */
+    readonly fontStyle?: string;
+};
+/**
+ * Single source of truth for how Book source is colored.
+ *
+ * The Monaco theme of `<BookEditor/>` and every static rendering of Book source
+ * (for example the Book language manual PDF) are derived from these styles, so
+ * a book always looks the same no matter where it is displayed.
+ *
+ * @private internal constant of `BookEditor`
+ */
+export declare const BOOK_EDITOR_SYNTAX_TOKEN_STYLES: ReadonlyArray<BookEditorSyntaxTokenStyle>;

package/umd/src/book-components/BookEditor/createBookSourceHighlightStyles.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates the CSS matching the markup of `highlightBookSourceToHtml`.
+ *
+ * Both the stylesheet and the markup are derived from the shared
+ * `BOOK_EDITOR_SYNTAX_TOKEN_STYLES`, therefore a statically rendered book keeps
+ * the exact colors of `<BookEditor/>`.
+ *
+ * @returns CSS rules for every Book syntax token.
+ *
+ * @private internal utility of `BookEditor`
+ */
+export declare function createBookSourceHighlightStyles(): string;

package/umd/src/book-components/BookEditor/highlightBookSourceToHtml.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Prefix of the CSS class names emitted for highlighted Book source.
+ *
+ * @private internal constant of `BookEditor`
+ */
+export declare const BOOK_SYNTAX_TOKEN_CLASS_NAME_PREFIX = "book-syntax-";
+/**
+ * Highlights Book source into static HTML using the `<BookEditor/>` token colors.
+ *
+ * `<BookEditor/>` itself is a Monaco-based browser component and cannot run
+ * where a book has to be rendered as plain markup (server-side exports such as
+ * the Book language manual PDF). This function reuses the very same
+ * tokenization patterns and token names, so both surfaces stay in sync.
+ *
+ * @param bookSource - Raw Book source to highlight.
+ * @returns HTML with one `<span>` per highlighted token, safe to place into `<pre>`.
+ *
+ * @private internal utility of `BookEditor`
+ */
+export declare function highlightBookSourceToHtml(bookSource: string): string;

package/umd/src/book-components/Chat/Chat/ChatCitationModal.d.ts

@@ -13,6 +13,11 @@ export type ChatCitationModalProps = {
     participants: ReadonlyArray<ChatParticipant>;
     resolveCitationLabel?: CitationLabelResolver;
     soundSystem?: ChatSoundSystem;
+    /**
+     * Optional agent identifier (name or permanent id) scoping the live browser fallback
+     * to the agent's persistent server-side browser profile.
+     */
+    agentIdentifier?: string;
     onClose: () => void;
 };
 /**

package/umd/src/book-components/Chat/Chat/ChatCitationModal.test.d.ts

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

package/umd/src/book-components/Chat/Chat/ChatFeedbackStar.d.ts

@@ -0,0 +1,37 @@
+import type { MouseEventHandler } from 'react';
+/**
+ * Star values available in the chat feedback UI.
+ *
+ * @private constant of `<Chat/>`
+ */
+export declare const CHAT_FEEDBACK_STAR_RATINGS: readonly [1, 2, 3, 4, 5];
+/**
+ * Props for the shared chat feedback star icon.
+ *
+ * @private type of `<Chat/>`
+ */
+type ChatFeedbackStarProps = {
+    readonly isActive: boolean;
+    readonly inactiveColor: string;
+    readonly className?: string;
+    readonly onClick?: MouseEventHandler<HTMLSpanElement>;
+    readonly onMouseEnter?: MouseEventHandler<HTMLSpanElement>;
+    readonly onMouseLeave?: MouseEventHandler<HTMLSpanElement>;
+};
+/**
+ * Resolves the inactive color for stars in the feedback controls.
+ *
+ * @param mode Current chat color mode.
+ * @param tone Visual weight for the inactive star.
+ * @returns Hex color for an inactive star.
+ *
+ * @private function of `<Chat/>`
+ */
+export declare function resolveChatFeedbackStarInactiveColor(mode: 'LIGHT' | 'DARK', tone?: 'subtle' | 'muted'): "#888" | "#666" | "#ccc" | "#555";
+/**
+ * Renders one CSS-colored feedback star.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatFeedbackStar({ isActive, inactiveColor, className, onClick, onMouseEnter, onMouseLeave, }: ChatFeedbackStarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/umd/src/book-components/Chat/Chat/ChatMessageItem.d.ts

@@ -76,6 +76,10 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
      * Optional cached metadata keyed by TEAM tool names to enrich tool call chips.
      */
     teamAgentProfiles?: ChatProps['teamAgentProfiles'];
+    /**
+     * Optional inline references rendered from `[[reference]]` tokens in message markdown.
+     */
+    markdownInlineReferences?: ChatProps['markdownInlineReferences'];
     /**
      * Controls whether assistant replies render as bubbles or article blocks.
      */

package/umd/src/book-components/Chat/Chat/ChatMessageList.d.ts

@@ -51,6 +51,10 @@ export type ChatMessageListProps = {
     toolTitles?: Record<string, string>;
     teammates?: ChatProps['teammates'];
     teamAgentProfiles?: ChatProps['teamAgentProfiles'];
+    /**
+     * Optional inline references rendered from `[[reference]]` tokens in message markdown.
+     */
+    markdownInlineReferences?: ChatProps['markdownInlineReferences'];
     visualMode?: ChatProps['visualMode'];
     onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
     onCitationClick?: (citation: ParsedCitation) => void;

package/umd/src/book-components/Chat/Chat/ChatMessageRichContent.d.ts

@@ -1,4 +1,5 @@
 import type { ChatMessage } from '../types/ChatMessage';
+import type { MarkdownInlineReference } from '../utils/renderMarkdown';
 import type { ChatMessageContentSegment } from '../utils/splitMessageContentIntoSegments';
 import type { StreamingFeaturePlaceholderKind } from './StreamingFeaturePlaceholder';
 /**
@@ -23,6 +24,10 @@ export type ChatMessageRichContentProps = {
      * Optional callback for creating a new agent from a book code block.
      */
     readonly onCreateAgent?: (bookContent: string) => void;
+    /**
+     * Optional inline references rendered from `[[reference]]` tokens in message markdown.
+     */
+    readonly markdownInlineReferences?: ReadonlyArray<MarkdownInlineReference>;
     /**
      * Resolved theme used by nested code blocks and editors.
      */

package/umd/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -10,6 +10,7 @@ import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ChatSaveFormatHandlerMap } from '../save/_common/ChatSaveFormatHandler';
+import type { MarkdownInlineReference } from '../utils/renderMarkdown';
 /**
  * Response data returned by the optional `onFeedback` handler.
  *
@@ -440,6 +441,14 @@ export type ChatProps = {
      * The title of the chat
      */
     readonly title?: string;
+    /**
+     * Optional identifier (name or permanent id) of the agent owning this chat.
+     *
+     * When set, server-side live browser previews opened from the chat (for example from
+     * knowledge citation chips) run inside the agent's persistent browser profile, so logins
+     * performed by the user in the live session are saved for the agent's future browsing.
+     */
+    readonly agentIdentifier?: string;
     /**
      * Messages to render - they are rendered as they are
      */
@@ -685,6 +694,10 @@ export type ChatProps = {
      * Optional cached agent metadata keyed by TEAM tool names to improve chip rendering.
      */
     readonly teamAgentProfiles?: Record<string, AgentChipData>;
+    /**
+     * Optional inline references rendered from `[[reference]]` tokens in message markdown.
+     */
+    readonly markdownInlineReferences?: ReadonlyArray<MarkdownInlineReference>;
     /**
      * Optional callback to create a new agent from the template.
      * If provided, renders the [Create Agent] button for book code blocks.

package/umd/src/book-components/Chat/Chat/ChatRatingModal.test.d.ts

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

package/umd/src/book-components/Chat/Chat/CitationIframePreview.d.ts

@@ -6,10 +6,33 @@
 export type CitationIframePreviewProps = {
     src: string;
     title: string;
+    /**
+     * Optional agent identifier (name or permanent id) scoping the live browser fallback
+     * to the agent's persistent server-side browser profile.
+     */
+    agentIdentifier?: string;
+    /**
+     * Optional close handler passed to the live browser toolbar when the preview fills a modal.
+     */
+    onClose?: () => void;
+    /**
+     * Reports whether the URL is embedded directly or shown through the live browser fallback.
+     */
+    onStatusChange?: (status: CitationIframePreviewStatus) => void;
+    /**
+     * Initial preview status used when the parent already knows the resolved mode.
+     */
+    initialStatus?: CitationIframePreviewStatus;
 };
+/**
+ * Internal status of the iframe embed check.
+ *
+ * @private type of `<CitationIframePreview/>`
+ */
+export type CitationIframePreviewStatus = 'loading' | 'embed' | 'browser-stream';
 /**
  * Renders a citation URL preview as an iframe when the target page allows embedding,
- * or falls back to a live server-side browser stream with an "Open in new tab" link
+ * or falls back to an interactive live server-side browser session (`<LiveBrowserPreview/>`)
  * when it does not (e.g. X-Frame-Options: DENY / SAMEORIGIN).
  *
  * Embedding capability is determined by `GET /api/page-preview/check?url=<url>`.
@@ -17,4 +40,4 @@ export type CitationIframePreviewProps = {
  *
  * @private component of `<ChatCitationModal/>`
  */
-export declare function CitationIframePreview({ src, title }: CitationIframePreviewProps): import("react/jsx-runtime").JSX.Element;
+export declare function CitationIframePreview({ src, title, agentIdentifier, onClose, onStatusChange, initialStatus, }: CitationIframePreviewProps): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/Chat/Chat/pagePreview/LiveBrowserPreview.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Props of the live browser preview.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export type LiveBrowserPreviewProps = {
+    /**
+     * URL opened in the remote headless browser.
+     */
+    readonly src: string;
+    /**
+     * Human-readable title of the previewed source.
+     */
+    readonly title: string;
+    /**
+     * Optional agent identifier (name or permanent id).
+     *
+     * When set, the live session runs inside the agent's persistent server-side browser profile,
+     * so actions like logging into a website are saved for the agent's future browsing.
+     */
+    readonly agentIdentifier?: string;
+    /**
+     * Optional close handler for modal-hosted previews.
+     */
+    readonly onClose?: () => void;
+};
+/**
+ * Remote-desktop-like live preview of one server-side headless browser session.
+ *
+ * Renders the MJPEG stream of the Agents Server page-preview route and forwards natural
+ * browser interactions to it — hovering, clicking, double-clicking, dragging and text
+ * selection (raw pointer presses with click counts), scrolling, typing and keyboard
+ * shortcuts. A browser-like toolbar adds history navigation, an editable address bar,
+ * local zoom (Ctrl+wheel or buttons), and a full screen mode. The remote viewport follows
+ * the size of the preview area, so the page is always rendered at the size the user sees.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export declare function LiveBrowserPreview({ src, title, agentIdentifier, onClose }: LiveBrowserPreviewProps): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/Chat/Chat/pagePreview/LiveBrowserPreview.test.d.ts

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