@promptbook/cli 0.112.0-126 → 0.112.0-127

package/src/book-components/Chat/Chat/ChatMessageItem.tsx

@@ -18,6 +18,7 @@ import { SourceChip } from '../SourceChip/SourceChip';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import { createCitationFootnoteRenderModel } from '../utils/createCitationFootnoteRenderModel';
+import { resolveCitationPreviewUrl } from '../utils/citationHelpers';
 import { getChatMessageTimingDisplay } from '../utils/getChatMessageTimingDisplay';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import type { MessageButton } from '../utils/parseMessageButtons';
@@ -78,6 +79,10 @@ type ChatMessageItemProps = Pick<
      * 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.
      */
@@ -248,6 +253,7 @@ export const ChatMessageItem = memo(
             feedbackMode = 'stars',
             feedbackTranslations,
             timingTranslations,
+            resolveCitationLabel,
             chatLocale,
             onCopy,
             onCreateAgent,
@@ -340,6 +346,14 @@ export const ChatMessageItem = memo(
                 }),
             [message.citations, sanitizedContentWithoutButtons],
         );
+        const enrichCitationForRendering = useCallback(
+            (citation: ParsedCitation): ParsedCitation => {
+                const previewUrl = resolveCitationPreviewUrl(citation, participants ?? []);
+
+                return previewUrl && !citation.url ? { ...citation, url: previewUrl } : citation;
+            },
+            [participants],
+        );
         const contentSegments = useMemo(
             () => splitMessageContentIntoSegments(citationFootnoteRenderModel.content),
             [citationFootnoteRenderModel.content],
@@ -951,8 +965,9 @@ export const ChatMessageItem = memo(
                                     >
                                         <span className={styles.citationFootnoteNumber}>{footnote.number}</span>
                                         <SourceChip
-                                            citation={footnote.citation}
+                                            citation={enrichCitationForRendering(footnote.citation)}
                                             onClick={onCitationClick}
+                                            resolveCitationLabel={resolveCitationLabel}
                                             isCitationIdVisible={false}
                                         />
                                     </div>
@@ -964,9 +979,10 @@ export const ChatMessageItem = memo(
                                 {transitiveCitations.map((citation, index) => (
                                     <SourceChip
                                         key={`team-source-${citation.source}-${index}`}
-                                        citation={citation}
+                                        citation={enrichCitationForRendering(citation)}
                                         suffix={`by ${citation.origin.label}`}
                                         onClick={onCitationClick}
+                                        resolveCitationLabel={resolveCitationLabel}
                                     />
                                 ))}
                             </div>
@@ -1178,6 +1194,10 @@ export const ChatMessageItem = memo(
             return false;
         }
 
+        if (prev.resolveCitationLabel !== next.resolveCitationLabel) {
+            return false;
+        }
+
         if (prev.handleRating !== next.handleRating) {
             return false;
         }

package/src/book-components/Chat/Chat/ChatMessageList.tsx

@@ -38,6 +38,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.
      */
@@ -87,6 +91,7 @@ export function ChatMessageList(props: ChatMessageListProps) {
         feedbackMode,
         feedbackTranslations,
         timingTranslations,
+        resolveCitationLabel,
         chatLocale,
         onCopy,
         onMessage,
@@ -156,6 +161,7 @@ export function ChatMessageList(props: ChatMessageListProps) {
                         feedbackMode={feedbackMode}
                         feedbackTranslations={feedbackTranslations}
                         timingTranslations={timingTranslations}
+                        resolveCitationLabel={resolveCitationLabel}
                         chatLocale={chatLocale}
                         onCopy={onCopy}
                         onCreateAgent={onCreateAgent}

package/src/book-components/Chat/Chat/ChatProps.tsx

@@ -12,6 +12,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';
 
 /**
@@ -830,6 +831,11 @@ export type ChatProps = {
      */
     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/src/book-components/Chat/Chat/ChatToolCallModal.tsx

@@ -8,6 +8,7 @@ import { CloseIcon } from '../../icons/CloseIcon';
 import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import styles from './Chat.module.css';
 import { ChatToolCallModalContent } from './ChatToolCallModalContent';
 import { useChatToolCallModalState } from './useChatToolCallModalState';
@@ -29,6 +30,7 @@ export type ChatToolCallModalProps = {
     toolCallIdentity?: string | null;
     onClose: () => void;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
     /**
@@ -77,6 +79,7 @@ export function ChatToolCallModal(props: ChatToolCallModalProps) {
         toolCallIdentity,
         onClose,
         toolTitles,
+        resolveCitationLabel,
         agentParticipant,
         buttonColor,
         teamAgentProfiles,
@@ -157,6 +160,7 @@ export function ChatToolCallModal(props: ChatToolCallModalProps) {
                     onClearSelectedTeamToolCall={clearSelectedTeamToolCall}
                     teamProfiles={teamProfiles}
                     toolTitles={toolTitles}
+                    resolveCitationLabel={resolveCitationLabel}
                     agentParticipant={agentParticipant}
                     buttonColor={buttonColor}
                     locale={locale}

package/src/book-components/Chat/Chat/ChatToolCallModalContent.tsx

@@ -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';
@@ -32,6 +33,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;
@@ -58,6 +60,7 @@ export function ChatToolCallModalContent({
     isAdvancedView,
     locale,
     mode,
+    resolveCitationLabel,
     onClearSelectedTeamToolCall,
     onRequestAdvancedView,
     onSelectTeamToolCall,
@@ -89,6 +92,7 @@ export function ChatToolCallModalContent({
                 onClearSelectedTeamToolCall={onClearSelectedTeamToolCall}
                 teamProfiles={teamProfiles}
                 toolTitles={toolTitles}
+                resolveCitationLabel={resolveCitationLabel}
                 agentParticipant={agentParticipant}
                 buttonColor={buttonColor}
             />

package/src/book-components/Chat/Chat/TeamToolCallModalContent.tsx

@@ -8,6 +8,7 @@ import { FAST_FLOW } from '../MockedChat/constants';
 import { MockedChat } from '../MockedChat/MockedChat';
 import { SourceChip } from '../SourceChip/SourceChip';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import type { TeamToolCallSummary, TransitiveToolCall } from '../utils/collectTeamToolCallSummary';
 import { buildToolCallChipText, getToolCallChipletInfo } from '../utils/getToolCallChipletInfo';
 import type { AgentProfileData } from '../utils/loadAgentProfile';
@@ -59,6 +60,7 @@ type TeamToolCallModalContentOptions = {
     onClearSelectedTeamToolCall: () => void;
     teamProfiles: Record<string, AgentProfileData>;
     toolTitles?: Record<string, string>;
+    resolveCitationLabel?: CitationLabelResolver;
     agentParticipant?: ChatParticipant;
     buttonColor: WithTake<Color>;
 };
@@ -408,8 +410,11 @@ function TeamToolCallActionsGroup(props: {
  *
  * @private component of ChatToolCallModal
  */
-function TeamToolCallSourcesGroup(props: { readonly teamCitations: TeamToolCallSummary['citations'] }) {
-    const { teamCitations } = props;
+function TeamToolCallSourcesGroup(props: {
+    readonly teamCitations: TeamToolCallSummary['citations'];
+    readonly resolveCitationLabel?: CitationLabelResolver;
+}) {
+    const { teamCitations, resolveCitationLabel } = props;
 
     if (teamCitations.length === 0) {
         return null;
@@ -424,6 +429,7 @@ function TeamToolCallSourcesGroup(props: { readonly teamCitations: TeamToolCallS
                         key={`team-source-${citation.source}-${index}`}
                         citation={citation}
                         suffix={`by ${citation.origin.label}`}
+                        resolveCitationLabel={resolveCitationLabel}
                     />
                 ))}
             </div>
@@ -483,6 +489,7 @@ function TeamToolCallSummarySection(props: {
     readonly selectedTeamToolCall: TransitiveToolCall | null;
     readonly teamToolCallSummary: TeamToolCallSummary;
     readonly toolTitles?: Record<string, string>;
+    readonly resolveCitationLabel?: CitationLabelResolver;
 }) {
     const {
         agentParticipant,
@@ -492,6 +499,7 @@ function TeamToolCallSummarySection(props: {
         selectedTeamToolCall,
         teamToolCallSummary,
         toolTitles,
+        resolveCitationLabel,
     } = props;
     const hasSummaryContent = teamToolCallSummary.toolCalls.length > 0 || teamToolCallSummary.citations.length > 0;
 
@@ -506,7 +514,10 @@ function TeamToolCallSummarySection(props: {
                 onSelectTeamToolCall={onSelectTeamToolCall}
                 toolTitles={toolTitles}
             />
-            <TeamToolCallSourcesGroup teamCitations={teamToolCallSummary.citations} />
+            <TeamToolCallSourcesGroup
+                teamCitations={teamToolCallSummary.citations}
+                resolveCitationLabel={resolveCitationLabel}
+            />
             <TeamToolCallDetailsPanel
                 selectedTeamToolCall={selectedTeamToolCall}
                 onClearSelectedTeamToolCall={onClearSelectedTeamToolCall}
@@ -533,6 +544,7 @@ export function TeamToolCallModalContent(options: TeamToolCallModalContentOption
         onClearSelectedTeamToolCall,
         teamProfiles,
         toolTitles,
+        resolveCitationLabel,
         agentParticipant,
         buttonColor,
     } = options;
@@ -561,6 +573,7 @@ export function TeamToolCallModalContent(options: TeamToolCallModalContentOption
                     onSelectTeamToolCall={onSelectTeamToolCall}
                     onClearSelectedTeamToolCall={onClearSelectedTeamToolCall}
                     toolTitles={toolTitles}
+                    resolveCitationLabel={resolveCitationLabel}
                     agentParticipant={agentParticipant}
                     buttonColor={buttonColor}
                 />

package/src/book-components/Chat/Chat/useChatPostprocessedMessages.ts

@@ -4,6 +4,7 @@ import { useMemo } from 'react';
 import { humanizeAiText } from '../../../utils/markdown/humanizeAiText';
 import { promptbookifyAiText } from '../../../utils/markdown/promptbookifyAiText';
 import type { ChatMessage } from '../types/ChatMessage';
+import { decodeJsonUnicodeEscapesInMarkdownText } from '../utils/decodeJsonUnicodeEscapesInMarkdownText';
 import { extractCitationsFromMessage } from '../utils/parseCitationsFromContent';
 
 /**
@@ -29,17 +30,27 @@ function postprocessChatMessage(message: ChatMessage): ChatMessage {
     const normalizedReplyingTo = messageWithCitations.replyingTo
         ? {
               ...messageWithCitations.replyingTo,
-              content: promptbookifyAiText(humanizeAiText(messageWithCitations.replyingTo.content)),
+              content: postprocessChatMessageContent(messageWithCitations.replyingTo.content),
           }
         : undefined;
 
     return {
         ...messageWithCitations,
-        content: promptbookifyAiText(humanizeAiText(messageWithCitations.content)),
+        content: postprocessChatMessageContent(messageWithCitations.content),
         ...(normalizedReplyingTo ? { replyingTo: normalizedReplyingTo } : {}),
     };
 }
 
+/**
+ * Applies markdown-safe text normalization to one chat message content value.
+ *
+ * @private utility of `useChatPostprocessedMessages`
+ */
+function postprocessChatMessageContent(content: ChatMessage['content']): ChatMessage['content'] {
+    const decodedContent = decodeJsonUnicodeEscapesInMarkdownText(content);
+    return promptbookifyAiText(humanizeAiText(decodedContent));
+}
+
 /**
  * Memoizes the render-only message normalization used by `<Chat/>`.
  *

package/src/book-components/Chat/SourceChip/SourceChip.module.css

@@ -2,6 +2,7 @@
     display: inline-flex;
     align-items: center;
     gap: 6px;
+    max-width: min(100%, 32rem);
     font-size: 0.8rem;
     font-weight: 600;
     padding: 5px 11px;
@@ -36,6 +37,13 @@
     display: flex;
     align-items: center;
     gap: 5px;
+    min-width: 0;
+}
+
+.labelText {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .citationId {

package/src/book-components/Chat/SourceChip/SourceChip.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { getCitationLabel, isCitationUrl, isPlainTextCitation } from '../utils/citationHelpers';
+import { useResolvedCitationLabel } from '../hooks/useResolvedCitationLabel';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import { isCitationUrl, isPlainTextCitation } from '../utils/citationHelpers';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import styles from './SourceChip.module.css';
 
@@ -26,6 +28,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.
      */
@@ -49,7 +55,14 @@ export type SourceChipProps = {
  *
  * @private utility of `ChatMessageItem` component
  */
-export function SourceChip({ citation, onClick, className, suffix, isCitationIdVisible = true }: SourceChipProps) {
+export function SourceChip({
+    citation,
+    onClick,
+    className,
+    suffix,
+    resolveCitationLabel,
+    isCitationIdVisible = true,
+}: SourceChipProps) {
     const handleClick = (event: React.MouseEvent) => {
         event.stopPropagation();
         if (onClick) {
@@ -59,7 +72,8 @@ export function SourceChip({ citation, onClick, className, suffix, isCitationIdV
 
     // Keep source chips concise and human-readable for CDN-backed knowledge files.
     const normalizedSource = citation.source.trim();
-    const displayName = getCitationLabel(citation);
+    const displayName = useResolvedCitationLabel(citation, resolveCitationLabel);
+    const title = displayName === citation.source ? citation.source : `${displayName}\n${citation.source}`;
 
     // Get file extension for icon
     const fileExtension = (normalizedSource || citation.source).split('.').pop()?.toLowerCase() || 'file';
@@ -70,10 +84,10 @@ export function SourceChip({ citation, onClick, className, suffix, isCitationIdV
         : getFileIcon(fileExtension);
 
     return (
-        <button className={`${styles.sourceChip} ${className || ''}`} onClick={handleClick} title={citation.source}>
+        <button className={`${styles.sourceChip} ${className || ''}`} onClick={handleClick} title={title}>
             <span className={styles.icon}>{icon}</span>
             <span className={styles.label}>
-                {displayName}
+                <span className={styles.labelText}>{displayName}</span>
                 {isCitationIdVisible && <span className={styles.citationId}> [{citation.id}]</span>}
             </span>
             {suffix && <span className={styles.suffix}>{suffix}</span>}

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

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import { getCitationLabel } from '../utils/citationHelpers';
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+
+/**
+ * Creates a stable key for one citation label lookup.
+ *
+ * @param citation - Citation metadata.
+ * @returns Stable citation key.
+ *
+ * @private hook helper of `<Chat/>`
+ */
+function createCitationLabelLookupKey(citation: ParsedCitation): string {
+    return [citation.id, citation.source, citation.url || '', citation.title || '', citation.excerpt || ''].join('\n');
+}
+
+/**
+ * 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 function useResolvedCitationLabel(
+    citation: ParsedCitation,
+    resolveCitationLabel?: CitationLabelResolver,
+): string {
+    const fallbackLabel = useMemo(() => getCitationLabel(citation), [citation]);
+    const citationKey = useMemo(() => createCitationLabelLookupKey(citation), [citation]);
+    const [resolvedLabel, setResolvedLabel] = useState<string | null>(null);
+
+    useEffect(() => {
+        setResolvedLabel(null);
+
+        if (!resolveCitationLabel) {
+            return;
+        }
+
+        let isCurrent = true;
+
+        Promise.resolve(resolveCitationLabel(citation))
+            .then((label) => {
+                if (!isCurrent) {
+                    return;
+                }
+
+                const normalizedLabel = label?.trim();
+                if (normalizedLabel) {
+                    setResolvedLabel(normalizedLabel);
+                }
+            })
+            .catch(() => undefined);
+
+        return () => {
+            isCurrent = false;
+        };
+    }, [citation, citationKey, resolveCitationLabel]);
+
+    return resolvedLabel || fallbackLabel;
+}