@promptbook/cli 0.112.0-99 → 0.113.0-0

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

@@ -0,0 +1,78 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import styles from './Chat.module.css';
+
+/**
+ * Props for the citation iframe preview component.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export type CitationIframePreviewProps = {
+    src: string;
+    title: string;
+};
+
+/**
+ * Internal status of the iframe embed check.
+ *
+ * @private type of `<CitationIframePreview/>`
+ */
+type EmbedStatus = 'loading' | 'embed' | 'screenshot';
+
+/**
+ * Renders a citation URL preview as an iframe when the target page allows embedding,
+ * or falls back to a server-side screenshot with an "Open in new tab" link when it
+ * does not (e.g. X-Frame-Options: DENY / SAMEORIGIN).
+ *
+ * Embedding capability is determined by `GET /api/page-preview/check?url=<url>`.
+ * If that endpoint is unavailable the component falls back to the iframe directly.
+ *
+ * @private component of `<ChatCitationModal/>`
+ */
+export function CitationIframePreview({ src, title }: CitationIframePreviewProps) {
+    const [status, setStatus] = useState<EmbedStatus>('loading');
+
+    useEffect(() => {
+        let cancelled = false;
+
+        fetch(`/api/page-preview/check?url=${encodeURIComponent(src)}`)
+            .then((response) => response.json())
+            .then((data: { canEmbed: boolean }) => {
+                if (!cancelled) {
+                    setStatus(data.canEmbed ? 'embed' : 'screenshot');
+                }
+            })
+            .catch(() => {
+                // API not available — fall back to iframe (e.g. outside agents-server)
+                if (!cancelled) {
+                    setStatus('embed');
+                }
+            });
+
+        return () => {
+            cancelled = true;
+        };
+    }, [src]);
+
+    if (status === 'loading') {
+        return <div className={styles.citationIframeLoading}>Loading preview…</div>;
+    }
+
+    if (status === 'screenshot') {
+        return (
+            <div className={styles.citationScreenshotFallback}>
+                <img
+                    src={`/api/page-preview/screenshot?url=${encodeURIComponent(src)}`}
+                    alt={`Screenshot of ${title}`}
+                    className={styles.citationScreenshotImage}
+                />
+                <a href={src} target="_blank" rel="noopener noreferrer" className={styles.citationScreenshotLink}>
+                    Open in new tab ↗
+                </a>
+            </div>
+        );
+    }
+
+    return <iframe src={src} className={styles.citationIframe} title={title} />;
+}

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/createChatMessageToolCallRenderModel.ts

@@ -1,5 +1,4 @@
 import type { ToolCall } from '../../../types/ToolCall';
-import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../types/ToolCall';
 import { resolveToolCallIdempotencyKey } from '../../../utils/toolCalls/resolveToolCallIdempotencyKey';
 import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { ChatMessage } from '../types/ChatMessage';
@@ -8,6 +7,7 @@ import { collectTeamToolCallSummary } from '../utils/collectTeamToolCallSummary'
 import { isTeamToolName } from '../utils/createTeamToolNameFromUrl';
 import type { ToolCallChipletInfo } from '../utils/getToolCallChipletInfo';
 import { buildToolCallChipText, getToolCallChipletInfo } from '../utils/getToolCallChipletInfo';
+import { isVisibleChatToolCall } from '../utils/isVisibleChatToolCall';
 import { resolveToolCallState } from '../utils/resolveToolCallState';
 import { createDeduplicatedWalletCredentialToolCalls } from '../utils/walletCredentialToolCall';
 import type { ChatProps } from './ChatProps';
@@ -121,13 +121,6 @@ export function createChatMessageToolCallRenderModel(
     };
 }
 
-/**
- * Tool calls that should stay available in message data but never render as chips under the message.
- *
- * @private internal helper of `<ChatMessageItem/>`
- */
-const HIDDEN_TOOL_CALL_CHIP_NAMES = new Set([ASSISTANT_PREPARATION_TOOL_CALL_NAME, 'agent_progress']);
-
 /**
  * Ongoing tool call entry used for grouping.
  *
@@ -141,7 +134,7 @@ type OngoingToolCall = NonNullable<ChatMessage['ongoingToolCalls']>[number];
  * @private internal helper of `<ChatMessageItem/>`
  */
 function shouldRenderToolCallChip(toolCall: ToolCall): boolean {
-    return !HIDDEN_TOOL_CALL_CHIP_NAMES.has(toolCall.name);
+    return isVisibleChatToolCall(toolCall);
 }
 
 /**

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/MarkdownContent/MarkdownContent.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { memo, useEffect, useMemo, useRef } from 'react';
+import { memo, useEffect, useMemo, useRef, useState } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { string_markdown } from '../../../types/string_markdown';
 import { classNames } from '../../_common/react-utils/classNames';
@@ -23,8 +23,37 @@ type MarkdownContentProps = {
 
     className?: string;
     onCreateAgent?: (bookContent: string) => void;
+    theme?: 'LIGHT' | 'DARK';
 };
 
+/**
+ * Visual theme consumed by nested code-block renderers.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+type MarkdownContentTheme = NonNullable<MarkdownContentProps['theme']>;
+
+/**
+ * Resolves the active document theme when a host application does not pass an explicit theme.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+function resolveMarkdownContentTheme(explicitTheme?: MarkdownContentTheme): MarkdownContentTheme {
+    if (explicitTheme) {
+        return explicitTheme;
+    }
+
+    if (typeof document !== 'undefined') {
+        const resolvedTheme = document.documentElement.dataset.themeResolved;
+
+        if (resolvedTheme === 'dark' || document.documentElement.classList.contains('dark')) {
+            return 'DARK';
+        }
+    }
+
+    return 'LIGHT';
+}
+
 /**
  * Returns a stable key for a `<details>` element based on its `<summary>` text.
  * Used to identify and restore open state across re-renders.
@@ -85,7 +114,7 @@ function resolveClickedDetailsElement(target: EventTarget | null, container: HTM
  * @public exported from `@promptbook/components`
  */
 export const MarkdownContent = memo(function MarkdownContent(props: MarkdownContentProps) {
-    const { content, className, onCreateAgent } = props;
+    const { content, className, onCreateAgent, theme } = props;
     const htmlContent = useMemo(
         () =>
             renderMarkdown(content, {
@@ -93,6 +122,7 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
             }),
         [content],
     );
+    const [resolvedTheme, setResolvedTheme] = useState<MarkdownContentTheme>(() => resolveMarkdownContentTheme(theme));
     const containerRef = useRef<HTMLDivElement>(null);
     const rootsRef = useRef<Root[]>([]);
     /** Tracks which `<details>` elements (by summary key) are currently open */
@@ -100,6 +130,28 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
     const onCreateAgentRef = useRef(onCreateAgent);
     onCreateAgentRef.current = onCreateAgent;
 
+    useEffect(() => {
+        if (theme) {
+            setResolvedTheme(theme);
+            return;
+        }
+
+        const updateTheme = () => setResolvedTheme(resolveMarkdownContentTheme());
+        updateTheme();
+
+        if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') {
+            return;
+        }
+
+        const observer = new MutationObserver(updateTheme);
+        observer.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ['class', 'data-theme-resolved'],
+        });
+
+        return () => observer.disconnect();
+    }, [theme]);
+
     useEffect(() => {
         // Cleanup previous roots
         rootsRef.current.forEach((root) => root.unmount());
@@ -191,7 +243,14 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
 
             // Render CodeBlock
             const root = createRoot(mountPoint);
-            root.render(<CodeBlock code={code} language={language} onCreateAgent={onCreateAgentRef.current} />);
+            root.render(
+                <CodeBlock
+                    code={code}
+                    language={language}
+                    onCreateAgent={onCreateAgentRef.current}
+                    theme={resolvedTheme}
+                />,
+            );
             rootsRef.current.push(root);
         });
 
@@ -203,7 +262,7 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
             rootsRef.current.forEach((root) => root.unmount());
             rootsRef.current = [];
         };
-    }, [htmlContent]);
+    }, [htmlContent, resolvedTheme]);
 
     return (
         <div

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;
+}