@promptbook/markdown-utils 0.112.0-126 → 0.112.0-128

package/README.md

@@ -508,7 +508,7 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
 -   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
--   **Interactive or unattended runs:** default wait mode, or `--no-wait` for batch execution
+-   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
@@ -530,7 +530,7 @@ npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gp
 
 npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes --no-wait
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -556,7 +556,7 @@ ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh -
 
 ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
 
 ptbk coder find-refactor-candidates
 
@@ -586,7 +586,7 @@ ptbk coder verify
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
 | `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-wait`                | Skips interactive pauses between prompts for unattended execution.                                 |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
 | `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
@@ -599,7 +599,7 @@ ptbk coder verify
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
 3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
-4. Run one prompt at a time interactively, or use `--no-wait` for unattended batches.
+4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 
 

package/esm/index.es.js

@@ -22,7 +22,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-126';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-128';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -66,6 +66,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 { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
@@ -150,6 +151,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export { ArrowIcon };

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

@@ -55,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';
@@ -496,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/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>;
     /**

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

@@ -3,6 +3,7 @@ import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -27,6 +28,7 @@ type ChatToolCallModalContentProps = {
     readonly isAdvancedView: boolean;
     readonly locale?: string;
     readonly mode: 'LIGHT' | 'DARK';
+    readonly resolveCitationLabel?: CitationLabelResolver;
     readonly onClearSelectedTeamToolCall: () => void;
     readonly onRequestAdvancedView: () => void;
     readonly onSelectTeamToolCall: (toolCall: TransitiveToolCall) => void;
@@ -43,5 +45,5 @@ type ChatToolCallModalContentProps = {
  *
  * @private component of `ChatToolCallModal`
  */
-export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
+export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, resolveCitationLabel, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
 export {};

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

@@ -2,6 +2,7 @@ import { type ReactElement } from 'react';
 import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -19,6 +20,7 @@ type TeamToolCallModalContentOptions = {
     onClearSelectedTeamToolCall: () => void;
     teamProfiles: Record<string, AgentProfileData>;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
 };

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

@@ -1,3 +1,4 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 /**
  * Props for SourceChip component
@@ -19,6 +20,10 @@ export type SourceChipProps = {
      * Optional suffix text to display after the citation label.
      */
     suffix?: string;
+    /**
+     * Optional resolver for richer citation labels.
+     */
+    resolveCitationLabel?: CitationLabelResolver;
     /**
      * Controls whether the technical citation id is shown inside the chip label.
      */
@@ -41,4 +46,4 @@ export type SourceChipProps = {
  *
  * @private utility of `ChatMessageItem` component
  */
-export declare function SourceChip({ citation, onClick, className, suffix, isCitationIdVisible }: SourceChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function SourceChip({ citation, onClick, className, suffix, resolveCitationLabel, isCitationIdVisible, }: SourceChipProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Resolves the best available label for one citation.
+ *
+ * @param citation - Citation metadata.
+ * @param resolveCitationLabel - Optional async host resolver.
+ * @returns Current label, starting with a synchronous fallback and updating when the resolver finishes.
+ *
+ * @private hook of `<Chat/>`
+ */
+export declare function useResolvedCitationLabel(citation: ParsedCitation, resolveCitationLabel?: CitationLabelResolver): string;

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

@@ -254,6 +254,10 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          * Optional URL to the source document
          */
         url?: string;
+        /**
+         * Optional human-readable source title.
+         */
+        title?: string;
         /**
          * Optional preview/excerpt from the source
          */

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

@@ -47,7 +47,7 @@ export type ChatParticipant = {
      * Knowledge sources (documents, URLs) used by the agent
      * Used for resolving document citations when the agent references sources
      */
-    knowledgeSources?: Array<{
+    knowledgeSources?: ReadonlyArray<{
         url: string;
         filename: string;
     }>;

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

@@ -0,0 +1,8 @@
+import type { Promisable } from 'type-fest';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Optional host-provided resolver for citation display labels.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type CitationLabelResolver = (citation: ParsedCitation) => Promisable<string | null | undefined>;

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

@@ -37,3 +37,12 @@ export declare function getCitationLabel(citation: ParsedCitation): string;
  * @private utility of `<Chat/>` citation rendering
  */
 export declare function resolveCitationPreviewUrl(citation: ParsedCitation, participants: ReadonlyArray<ChatParticipant>): string | null;
+/**
+ * Creates a readable fallback label from a citation source when no title metadata is available.
+ *
+ * @param source - Raw citation source value.
+ * @returns Human-friendly source label.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createReadableCitationSourceLabel(source: string): string;

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

@@ -0,0 +1,14 @@
+import type { string_markdown } from '../../../types/string_markdown';
+/**
+ * Decodes JSON-style Unicode escape sequences in markdown prose while preserving code.
+ *
+ * Model/tool output can occasionally arrive as already JSON-escaped text, which makes
+ * natural-language replies render `\u00fd` instead of the decoded character. This
+ * keeps code examples intact by skipping fenced code blocks and inline code spans.
+ *
+ * @param markdown - Markdown chat content to normalize for display.
+ * @returns Markdown chat content with non-ASCII JSON Unicode escapes decoded.
+ *
+ * @private internal utility of `<Chat/>`
+ */
+export declare function decodeJsonUnicodeEscapesInMarkdownText(markdown: string_markdown): string_markdown;

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

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

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

@@ -15,6 +15,10 @@ export type ParsedCitation = {
      * Optional URL to the source document
      */
     url?: string;
+    /**
+     * Optional human-readable source title.
+     */
+    title?: string;
     /**
      * Optional preview/excerpt from the source
      */

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-123`).
+ * It follows semantic versioning (e.g., `0.112.0-126`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/markdown-utils",
-    "version": "0.112.0-126",
+    "version": "0.112.0-128",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -25,7 +25,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-126';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-128';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name

package/umd/src/_packages/components.index.d.ts

@@ -66,6 +66,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 { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
@@ -150,6 +151,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export { ArrowIcon };

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

@@ -55,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';
@@ -496,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/umd/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/umd/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/umd/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/umd/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/umd/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/umd/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>;
     /**

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

@@ -3,6 +3,7 @@ import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -27,6 +28,7 @@ type ChatToolCallModalContentProps = {
     readonly isAdvancedView: boolean;
     readonly locale?: string;
     readonly mode: 'LIGHT' | 'DARK';
+    readonly resolveCitationLabel?: CitationLabelResolver;
     readonly onClearSelectedTeamToolCall: () => void;
     readonly onRequestAdvancedView: () => void;
     readonly onSelectTeamToolCall: (toolCall: TransitiveToolCall) => void;
@@ -43,5 +45,5 @@ type ChatToolCallModalContentProps = {
  *
  * @private component of `ChatToolCallModal`
  */
-export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
+export declare function ChatToolCallModalContent({ agentParticipant, availableTools, buttonColor, chatUiTranslations, focusedToolCall, isAdvancedView, locale, mode, resolveCitationLabel, onClearSelectedTeamToolCall, onRequestAdvancedView, onSelectTeamToolCall, selectedTeamToolCall, teamProfiles, teamResult, teamToolCallSummary, toolCall, toolCallDate, toolTitles, }: ChatToolCallModalContentProps): ReactElement;
 export {};

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

@@ -2,6 +2,7 @@ import { type ReactElement } from 'react';
 import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
@@ -19,6 +20,7 @@ type TeamToolCallModalContentOptions = {
     onClearSelectedTeamToolCall: () => void;
     teamProfiles: Record<string, AgentProfileData>;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
 };

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

@@ -1,3 +1,4 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 /**
  * Props for SourceChip component
@@ -19,6 +20,10 @@ export type SourceChipProps = {
      * Optional suffix text to display after the citation label.
      */
     suffix?: string;
+    /**
+     * Optional resolver for richer citation labels.
+     */
+    resolveCitationLabel?: CitationLabelResolver;
     /**
      * Controls whether the technical citation id is shown inside the chip label.
      */
@@ -41,4 +46,4 @@ export type SourceChipProps = {
  *
  * @private utility of `ChatMessageItem` component
  */
-export declare function SourceChip({ citation, onClick, className, suffix, isCitationIdVisible }: SourceChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function SourceChip({ citation, onClick, className, suffix, resolveCitationLabel, isCitationIdVisible, }: SourceChipProps): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/Chat/hooks/useResolvedCitationLabel.d.ts

@@ -0,0 +1,12 @@
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Resolves the best available label for one citation.
+ *
+ * @param citation - Citation metadata.
+ * @param resolveCitationLabel - Optional async host resolver.
+ * @returns Current label, starting with a synchronous fallback and updating when the resolver finishes.
+ *
+ * @private hook of `<Chat/>`
+ */
+export declare function useResolvedCitationLabel(citation: ParsedCitation, resolveCitationLabel?: CitationLabelResolver): string;

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

@@ -254,6 +254,10 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          * Optional URL to the source document
          */
         url?: string;
+        /**
+         * Optional human-readable source title.
+         */
+        title?: string;
         /**
          * Optional preview/excerpt from the source
          */

package/umd/src/book-components/Chat/types/ChatParticipant.d.ts

@@ -47,7 +47,7 @@ export type ChatParticipant = {
      * Knowledge sources (documents, URLs) used by the agent
      * Used for resolving document citations when the agent references sources
      */
-    knowledgeSources?: Array<{
+    knowledgeSources?: ReadonlyArray<{
         url: string;
         filename: string;
     }>;

package/umd/src/book-components/Chat/types/CitationLabelResolver.d.ts

@@ -0,0 +1,8 @@
+import type { Promisable } from 'type-fest';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Optional host-provided resolver for citation display labels.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type CitationLabelResolver = (citation: ParsedCitation) => Promisable<string | null | undefined>;

package/umd/src/book-components/Chat/utils/citationHelpers.d.ts

@@ -37,3 +37,12 @@ export declare function getCitationLabel(citation: ParsedCitation): string;
  * @private utility of `<Chat/>` citation rendering
  */
 export declare function resolveCitationPreviewUrl(citation: ParsedCitation, participants: ReadonlyArray<ChatParticipant>): string | null;
+/**
+ * Creates a readable fallback label from a citation source when no title metadata is available.
+ *
+ * @param source - Raw citation source value.
+ * @returns Human-friendly source label.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createReadableCitationSourceLabel(source: string): string;

package/umd/src/book-components/Chat/utils/decodeJsonUnicodeEscapesInMarkdownText.d.ts

@@ -0,0 +1,14 @@
+import type { string_markdown } from '../../../types/string_markdown';
+/**
+ * Decodes JSON-style Unicode escape sequences in markdown prose while preserving code.
+ *
+ * Model/tool output can occasionally arrive as already JSON-escaped text, which makes
+ * natural-language replies render `\u00fd` instead of the decoded character. This
+ * keeps code examples intact by skipping fenced code blocks and inline code spans.
+ *
+ * @param markdown - Markdown chat content to normalize for display.
+ * @returns Markdown chat content with non-ASCII JSON Unicode escapes decoded.
+ *
+ * @private internal utility of `<Chat/>`
+ */
+export declare function decodeJsonUnicodeEscapesInMarkdownText(markdown: string_markdown): string_markdown;

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

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

package/umd/src/book-components/Chat/utils/parseCitationsFromContent.d.ts

@@ -15,6 +15,10 @@ export type ParsedCitation = {
      * Optional URL to the source document
      */
     url?: string;
+    /**
+     * Optional human-readable source title.
+     */
+    title?: string;
     /**
      * Optional preview/excerpt from the source
      */

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-123`).
+ * It follows semantic versioning (e.g., `0.112.0-126`).
  *
  * @generated
  */