@promptbook/utils 0.112.0-99 → 0.112.0

package/esm/src/_packages/core.index.d.ts

@@ -221,7 +221,6 @@ import { normalizeChatAttachments } from '../utils/chat/chatAttachments/normaliz
 import { resolveChatAttachmentContents } from '../utils/chat/chatAttachments/resolveChatAttachmentContents';
 import { aboutPromptbookInformation } from '../utils/misc/aboutPromptbookInformation';
 import { $generateBookBoilerplate } from '../utils/random/$generateBookBoilerplate';
-import { CORE_AGENTS_SERVER } from '../../servers';
 import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../servers';
 import { PUBLIC_AGENTS_SERVERS } from '../../servers';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
@@ -447,6 +446,5 @@ export { normalizeChatAttachments };
 export { resolveChatAttachmentContents };
 export { aboutPromptbookInformation };
 export { $generateBookBoilerplate };
-export { CORE_AGENTS_SERVER };
 export { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES };
 export { PUBLIC_AGENTS_SERVERS };

package/esm/src/_packages/node.index.d.ts

@@ -1,4 +1,24 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { AGENT_BOOK_FILE_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FAILED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
+import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
+import type { CliAgentHarness } from '../book-3.0/CliAgent';
+import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
+import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
+import type { CliAgentOptions } from '../book-3.0/CliAgent';
+import { CliAgent } from '../book-3.0/CliAgent';
+import { CLI_AGENT_HARNESS_NAMES } from '../book-3.0/cliAgentEnv';
+import { CLI_AGENT_THINKING_LEVEL_VALUES } from '../book-3.0/cliAgentEnv';
+import { PTBK_HARNESS_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_MODEL_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_THINKING_LEVEL_ENV } from '../book-3.0/cliAgentEnv';
+import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
+import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
+import { LiteAgent } from '../book-3.0/LiteAgent';
 import { createPipelineCollectionFromDirectory } from '../collection/pipeline-collection/constructors/createPipelineCollectionFromDirectory';
 import { getAllCommitmentsToolFunctionsForNode } from '../commitments/_common/getAllCommitmentsToolFunctionsForNode';
 import { $provideExecutablesForNode } from '../executables/$provideExecutablesForNode';
@@ -12,6 +32,26 @@ import { FileCacheStorage } from '../storage/file-cache-storage/FileCacheStorage
 import { $execCommand } from '../utils/execCommand/$execCommand';
 import { $execCommands } from '../utils/execCommand/$execCommands';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
+export { AGENT_BOOK_FILE_PATH };
+export { AGENT_MESSAGES_DIRECTORY_PATH };
+export { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FAILED_MESSAGES_DIRECTORY_PATH };
+export type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export { CliAgent };
+export { CLI_AGENT_HARNESS_NAMES };
+export { CLI_AGENT_THINKING_LEVEL_VALUES };
+export { PTBK_HARNESS_ENV };
+export { PTBK_MODEL_ENV };
+export { PTBK_THINKING_LEVEL_ENV };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
+export { LiteAgent };
 export { createPipelineCollectionFromDirectory };
 export { getAllCommitmentsToolFunctionsForNode };
 export { $provideExecutablesForNode };

package/esm/src/_packages/types.index.d.ts

@@ -4,6 +4,14 @@ import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicI
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
 import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import type { string_book } from '../book-2.0/agent-source/string_book';
+import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
+import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
+import type { CliAgentHarness } from '../book-3.0/CliAgent';
+import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
+import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
+import type { CliAgentOptions } from '../book-3.0/CliAgent';
+import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
+import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
 import type { AvatarChipProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChip';
 import type { AvatarChipFromSourceProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChipFromSource';
 import type { AvatarProfileProps } from '../book-components/AvatarProfile/AvatarProfile/AvatarProfile';
@@ -47,6 +55,7 @@ import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
+import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
@@ -437,6 +446,14 @@ export type { AgentBasicInformation };
 export type { AgentModelRequirements };
 export type { CreateAgentModelRequirementsOptions };
 export type { string_book };
+export type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
 export type { AvatarChipProps };
 export type { AvatarChipFromSourceProps };
 export type { AvatarProfileProps };
@@ -480,6 +497,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { TeamToolResult };

package/esm/src/avatars/avatarAnimationScheduler.d.ts

@@ -7,6 +7,10 @@ type AvatarAnimationListener = (now: number) => void;
 /**
  * Registers one avatar animation callback in the shared animation loop.
  *
+ * Each listener is staggered at registration time so it does not fire on the same animation
+ * frame as the existing listeners, and the shared loop further caps how many listeners run
+ * per frame, keeping the main thread responsive when many avatars are mounted.
+ *
  * @param avatarAnimationListener Frame callback invoked on every animation frame.
  * @returns Cleanup function that unregisters the callback.
  *

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -7,7 +7,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'octopus3d3' | 'octopus3d4' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
 /**
  * Derived color palette used by avatar visuals.
  *

package/esm/src/avatars/visuals/octopus3d3AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus 3D 3 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3d3AvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/octopus3d4AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus 3D 4 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3d4AvatarVisual: AvatarVisualDefinition;

package/esm/src/book-3.0/BookNodeAgentSource.d.ts

@@ -0,0 +1,38 @@
+import type { string_book } from '../book-2.0/agent-source/string_book';
+import { Book } from './Book';
+/**
+ * Book source value accepted by Node-backed Book agents.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSource = Book | string_book;
+/**
+ * Common source options shared by Node-backed Book agents.
+ *
+ * Provide either `agentPath` or `book`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSourceOptions = {
+    readonly agentPath?: string;
+    readonly book?: string | BookNodeAgentSource;
+    readonly currentWorkingDirectory?: string;
+};
+/**
+ * Normalized source snapshot used internally by Node-backed Book agents.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export type ResolvedBookNodeAgentSource = {
+    readonly agentName: string;
+    readonly agentPath: string | null;
+    readonly agentSource: string_book;
+    readonly currentWorkingDirectory: string;
+    readonly sourceDirectoryPath: string;
+};
+/**
+ * Resolves shared Node-backed Book source options into one normalized source snapshot.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export declare function resolveBookNodeAgentSource(options: BookNodeAgentSourceOptions): Promise<ResolvedBookNodeAgentSource>;

package/esm/src/book-3.0/CliAgent.d.ts

@@ -0,0 +1,66 @@
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+import { CLI_AGENT_HARNESS_NAMES, CLI_AGENT_THINKING_LEVEL_VALUES } from './cliAgentEnv';
+/**
+ * CLI harness names supported by `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
+/**
+ * Thinking levels supported by CLI coding harnesses.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
+/**
+ * Per-run CLI options exposed by `CliAgent`.
+ *
+ * `noUi` defaults to `true` so command output stays suitable for JavaScript callers.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentRunOptions = {
+    readonly allowCredits?: boolean;
+    readonly context?: string;
+    readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
+    readonly model?: string;
+    readonly noUi?: boolean;
+    readonly thinkingLevel?: CliAgentThinkingLevel;
+};
+/**
+ * Constructor options for `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
+/**
+ * Lightweight JavaScript wrapper around the Promptbook agent execution pipeline.
+ *
+ * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
+ *
+ * When no `harness` is provided in the constructor or per-run options, `CliAgent` falls back
+ * to the `PTBK_HARNESS` environment variable, mirroring `ptbk agent exec` behavior.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class CliAgent {
+    private readonly options;
+    private temporaryAgentPath;
+    constructor(options: CliAgentOptions);
+    /**
+     * Runs one non-interactive agent turn through the selected harness.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional per-run overrides.
+     * @returns Final agent answer.
+     */
+    run(message: string, options?: CliAgentRunOptions): Promise<string>;
+    /**
+     * Resolves the agent path passed to the runner, materializing one temporary `.book` file when needed.
+     *
+     * @private internal utility of `CliAgent`
+     */
+    private resolveExecutableAgentPath;
+}

package/esm/src/book-3.0/CliAgent.test.d.ts

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

package/esm/src/book-3.0/LiteAgent.d.ts

@@ -0,0 +1,68 @@
+import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
+import type { ScriptExecutionTools } from '../execution/ScriptExecutionTools';
+import type { string_model_name } from '../types/string_model_name';
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+/**
+ * Options for constructing one `LiteAgent`.
+ *
+ * `LiteAgent` is intentionally smaller than the CLI harnesses. It runs the Book through the
+ * OpenAI Agents SDK directly, while keeping Promptbook tool definitions and hosted knowledge
+ * whenever those features fit inside the lighter runtime.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type LiteAgentOptions = BookNodeAgentSourceOptions & {
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+    readonly createAgentModelRequirementsOptions?: CreateAgentModelRequirementsOptions;
+    readonly isVerbose?: boolean;
+    readonly maxRequestsPerMinute?: number;
+    readonly modelName?: string_model_name;
+    readonly organization?: string;
+    readonly project?: string;
+    readonly scriptExecutionTools?: ScriptExecutionTools | ReadonlyArray<ScriptExecutionTools>;
+    readonly userId?: string;
+};
+/**
+ * Per-run options for `LiteAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type LiteAgentRunOptions = {
+    readonly context?: string;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Lightweight Node.js wrapper around the OpenAI Agents SDK for Promptbook Books.
+ *
+ * This path is intentionally simpler than `ptbk agent exec`: it prepares one SDK agent in-process
+ * and reuses it across calls, which keeps JavaScript integration small while still honoring the
+ * compiled Promptbook system message, prompt suffix, tools, and hosted knowledge when supported.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class LiteAgent {
+    private readonly options;
+    private preparedAgentPromise;
+    constructor(options: LiteAgentOptions);
+    /**
+     * Runs one user message through the prepared OpenAI Agents SDK agent.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional context and cancellation signal.
+     * @returns Final text returned by the SDK agent.
+     */
+    run(message: string, options?: LiteAgentRunOptions): Promise<string>;
+    /**
+     * Lazily prepares and caches the underlying OpenAI Agents SDK runtime.
+     *
+     * @private internal utility of `LiteAgent`
+     */
+    private prepareAgent;
+    /**
+     * Builds the in-process OpenAI Agents SDK runtime from the Book source.
+     *
+     * @private internal utility of `LiteAgent`
+     */
+    private createPreparedAgent;
+}

package/esm/src/book-3.0/LiteAgent.test.d.ts

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

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

@@ -0,0 +1,30 @@
+/**
+ * Relative path to the local agent source used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to the message queue root used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
+/**
+ * Relative path to queued user messages consumed by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to answered messages written by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to messages that the agent runner stopped retrying.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;

package/esm/src/book-3.0/cliAgentEnv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_THINKING_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
+ *
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
+ * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_HARNESS_ENV = "PTBK_HARNESS";
+/**
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
+/**
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";

package/esm/src/book-components/BookEditor/BookEditor.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties } from 'react';
+import { type CSSProperties } from 'react';
 import type { Promisable } from 'type-fest';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 import type { number_percent } from '../../types/number_percent';
@@ -6,6 +6,7 @@ import type { number_positive } from '../../types/number_positive';
 import type { string_knowledge_source_content } from '../../types/string_knowledge_source_content';
 import type { string_css_value } from '../../types/string_markdown';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Monaco diagnostic shown inside `BookEditor`.
  *
@@ -94,14 +95,14 @@ export type BookEditorProps = {
      */
     readonly style?: CSSProperties;
     /**
-     * Resolved visual theme used for the editor wrapper and Monaco instance.
+     * Resolved host application theme.
      *
-     * Host applications should pass the final light/dark theme instead of relying on
-     * browser media-query inference inside `<BookEditor/>`.
+     * `<BookEditor/>` accepts this for integration compatibility, but the notebook
+     * editor itself is intentionally rendered as light paper in every app theme.
      *
      * @default 'LIGHT'
      */
-    readonly theme?: 'LIGHT' | 'DARK';
+    readonly theme?: BookEditorTheme;
     /**
      * Height of the `BookEditor` component
      *

package/esm/src/book-components/BookEditor/BookEditorAboutPromptbookInformation.d.ts

@@ -0,0 +1,12 @@
+import type { AboutPromptbookInformationOptions } from '../../utils/misc/aboutPromptbookInformation';
+/**
+ * Browser-safe Promptbook information used by `BookEditor`.
+ *
+ * The shared `AboutPromptbookInformation` component renders markdown through the
+ * chat markdown pipeline, which has a server-side JSDOM sanitizer path. Keeping
+ * this component plain JSX prevents BookEditor from pulling JSDOM into client
+ * bundles.
+ *
+ * @private Internal component used by `BookEditorActionbar`
+ */
+export declare function BookEditorAboutPromptbookInformation(props?: AboutPromptbookInformationOptions): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/BookEditor/BookEditorBrowserConfig.d.ts

@@ -0,0 +1,2 @@
+export { NAME, CLAIM, PROMPTBOOK_LEGAL_ENTITY, IS_COST_PREVENTED, DEFAULT_IS_VERBOSE, DEFAULT_MAX_CONCURRENT_UPLOADS, PROMPTBOOK_SYNTAX_COLORS, } from '../../config';
+export { PUBLIC_AGENTS_SERVERS } from '../../../servers';

package/esm/src/book-components/BookEditor/BookEditorForClient.d.ts

@@ -0,0 +1,7 @@
+import type { BookEditorProps } from './BookEditor';
+/**
+ * Renders a book editor
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function BookEditorForClient(props: BookEditorProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/BookEditor/BookEditorMonacoTokenization.d.ts

@@ -15,6 +15,7 @@ type AgentReferenceMatch = {
  * @private function of BookEditorMonaco
  */
 export declare const BookEditorMonacoTokenization: {
+    DYNAMIC_COMMITMENT_REGEX: RegExp;
     AGENT_URL_REFERENCE_REGEX: RegExp;
     AGENT_REFERENCE_TOKEN_REGEX: RegExp;
     AGENT_REFERENCE_BRACED_REGEX: RegExp;

package/esm/src/book-components/BookEditor/BookEditorTheme.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Visual theme accepted by `<BookEditor/>` integrations.
+ *
+ * @private internal type of `BookEditor`
+ */
+export type BookEditorTheme = 'LIGHT' | 'DARK';
+/**
+ * Theme used for the actual notebook editor surface.
+ *
+ * The host application can still pass its resolved app theme, but book sources
+ * are intentionally rendered as light paper in both light and dark app modes.
+ *
+ * @private internal constant of `BookEditor`
+ */
+export declare const BOOK_EDITOR_RENDER_THEME = "LIGHT";
+/**
+ * Resolves an app-level theme into the visual theme used by `<BookEditor/>`.
+ *
+ * @param hostTheme - Resolved theme from the embedding application.
+ * @returns Light theme used by the Book editor surface.
+ *
+ * @private internal utility of `BookEditor`
+ */
+export declare function resolveBookEditorRenderTheme(hostTheme?: BookEditorTheme): BookEditorTheme;

package/esm/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-compatible stub for `createDeprecatedCommitmentDiagnostics`.
+ *
+ * In the browser build the full Node.js implementation is not available,
+ * so this stub always returns an empty array to keep the editor functional.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export declare function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [];

package/esm/src/book-components/BookEditor/useBookEditorMonacoLanguage.d.ts

@@ -1,14 +1,9 @@
 import type { editor } from 'monaco-editor';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Type describing monaco editor.
  */
 type MonacoEditor = typeof import('monaco-editor');
-/**
- * Resolved visual theme supported by the Book editor.
- *
- * @private function of BookEditorMonaco
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
 /**
  * Props for use book editor monaco language.
  */

package/esm/src/book-components/BookEditor/useBookEditorMonacoLifecycle.d.ts

@@ -1,12 +1,9 @@
 import type { editor } from 'monaco-editor';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Type describing monaco editor.
  */
 type MonacoEditor = typeof import('monaco-editor');
-/**
- * Resolved visual theme supported by the Book editor.
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
 /**
  * Props for use book editor monaco lifecycle.
  */

package/esm/src/book-components/BookEditor/useBookEditorMonacoStyles.d.ts

@@ -1,3 +1,4 @@
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Props for use book editor monaco styles.
  */
@@ -7,7 +8,7 @@ type UseBookEditorMonacoStylesProps = {
     readonly scaledContentPaddingLeft: number;
     readonly scaledVerticalLineLeft: number;
     readonly zoomLevel: number;
-    readonly theme: 'LIGHT' | 'DARK';
+    readonly theme: BookEditorTheme;
 };
 /**
  * Injects notebook-inspired styling that is unique per `BookEditorMonaco` instance.

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

@@ -1,4 +1,5 @@
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import type { ChatSoundSystem } from './ChatProps';
 /**
@@ -10,6 +11,7 @@ export type ChatCitationModalProps = {
     isOpen: boolean;
     citation: ParsedCitation | null;
     participants: ReadonlyArray<ChatParticipant>;
+    resolveCitationLabel?: CitationLabelResolver;
     soundSystem?: ChatSoundSystem;
     onClose: () => void;
 };

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

@@ -38,6 +38,10 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
      * Optional localized labels used by timestamp metadata.
      */
     timingTranslations?: ChatProps['timingTranslations'];
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    resolveCitationLabel?: ChatProps['resolveCitationLabel'];
     /**
      * Optional moment locale used to format message timestamps.
      */

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

@@ -32,6 +32,10 @@ export type ChatMessageListProps = {
      * Optional localized labels used by timestamp metadata.
      */
     timingTranslations?: ChatProps['timingTranslations'];
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    resolveCitationLabel?: ChatProps['resolveCitationLabel'];
     /**
      * Optional moment locale used to format message timestamps.
      */

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

@@ -8,6 +8,7 @@ import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { string_chat_format_name } from '../save/_common/string_chat_format_name';
 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';
 /**
  * Response data returned by the optional `onFeedback` handler.
@@ -715,6 +716,10 @@ export type ChatProps = {
      * Optional localized labels used by timestamp metadata shown under messages.
      */
     readonly timingTranslations?: ChatTimingTranslations;
+    /**
+     * Optional resolver for turning technical citation sources into page/document titles.
+     */
+    readonly resolveCitationLabel?: CitationLabelResolver;
     /**
      * Optional localized labels for general Chat UI elements such as button labels,
      * lifecycle state badges, tool call modal strings, and the default input placeholder.

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

@@ -3,6 +3,7 @@ import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 /**
  * Props for the tool call details modal.
  *
@@ -20,6 +21,7 @@ export type ChatToolCallModalProps = {
     toolCallIdentity?: string | null;
     onClose: () => void;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
     /**