@promptbook/cli 0.113.0-8 → 0.114.0-0

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

@@ -1,7 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Promisable } from 'type-fest';
 import type { id } from '../../../types/string_token';
+import { resolveChatRatingMessageKey } from '../Chat/resolveChatRatingMessageKey';
 import type { ChatFeedbackMode, ChatFeedbackResponse, ChatProps } from '../Chat/ChatProps';
 import type { ChatMessage } from '../types/ChatMessage';
 
@@ -123,15 +124,6 @@ const DEFAULT_FEEDBACK_ERROR_MESSAGE = 'Failed to save feedback. Please try agai
  */
 const FEEDBACK_STATUS_TIMEOUT_IN_MILLISECONDS = 3000;
 
-/**
- * Resolves the key used to keep one message rating in the local map.
- *
- * @private function of `useChatRatings`
- */
-function resolveChatRatingMessageKey(message: Pick<ChatMessage, 'id' | 'content'>) {
-    return message.id || message.content /* <- TODO: [??][??] Is `message.content` good replacement for the ID */;
-}
-
 /**
  * Normalizes the stored rating for the current feedback mode.
  *

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

@@ -5,6 +5,23 @@ import type { CitationLabelResolver } from '../types/CitationLabelResolver';
 import { getCitationLabel } from '../utils/citationHelpers';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 
+/**
+ * Resolved label state scoped to the citation key it belongs to.
+ *
+ * @private hook type of `<Chat/>`
+ */
+type ResolvedCitationLabelState = {
+    readonly citationKey: string;
+    readonly label: string;
+};
+
+/**
+ * Cache of resolved citation labels keyed by stable citation metadata.
+ *
+ * @private hook constant of `<Chat/>`
+ */
+const RESOLVED_CITATION_LABELS_BY_KEY = new Map<string, string>();
+
 /**
  * Creates a stable key for one citation label lookup.
  *
@@ -17,6 +34,78 @@ function createCitationLabelLookupKey(citation: ParsedCitation): string {
     return [citation.id, citation.source, citation.url || '', citation.title || '', citation.excerpt || ''].join('\n');
 }
 
+/**
+ * Keeps a stable citation object while parent components recreate equivalent citation literals.
+ *
+ * @param citation - Citation metadata from the render tree.
+ * @returns Citation lookup payload.
+ *
+ * @private hook helper of `<Chat/>`
+ */
+function createCitationLookupPayload(citation: ParsedCitation): ParsedCitation {
+    return {
+        id: citation.id,
+        source: citation.source,
+        url: citation.url,
+        title: citation.title,
+        excerpt: citation.excerpt,
+    };
+}
+
+/**
+ * Normalizes one resolved citation label before storing it.
+ *
+ * @param label - Raw resolver result.
+ * @returns Trimmed label or null.
+ *
+ * @private hook helper of `<Chat/>`
+ */
+function normalizeResolvedCitationLabel(label: string | null | undefined): string | null {
+    const normalizedLabel = label?.trim();
+
+    return normalizedLabel || null;
+}
+
+/**
+ * Creates and caches resolved label state for one citation key.
+ *
+ * @param citationKey - Stable citation lookup key.
+ * @param label - Raw resolver result.
+ * @returns Label state or null when the resolver did not provide a label.
+ *
+ * @private hook helper of `<Chat/>`
+ */
+function createResolvedCitationLabelState(
+    citationKey: string,
+    label: string | null | undefined,
+): ResolvedCitationLabelState | null {
+    const normalizedLabel = normalizeResolvedCitationLabel(label);
+    if (!normalizedLabel) {
+        return null;
+    }
+
+    RESOLVED_CITATION_LABELS_BY_KEY.set(citationKey, normalizedLabel);
+
+    return {
+        citationKey,
+        label: normalizedLabel,
+    };
+}
+
+/**
+ * Reads one resolved label from the shared citation-label cache.
+ *
+ * @param citationKey - Stable citation lookup key.
+ * @returns Cached label state or null.
+ *
+ * @private hook helper of `<Chat/>`
+ */
+function createCachedResolvedCitationLabelState(citationKey: string): ResolvedCitationLabelState | null {
+    const cachedLabel = RESOLVED_CITATION_LABELS_BY_KEY.get(citationKey);
+
+    return cachedLabel ? { citationKey, label: cachedLabel } : null;
+}
+
 /**
  * Resolves the best available label for one citation.
  *
@@ -30,28 +119,43 @@ 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);
+    const citationLookupPayload = useMemo(
+        () => createCitationLookupPayload(citation),
+        [citation.excerpt, citation.id, citation.source, citation.title, citation.url],
+    );
+    const fallbackLabel = useMemo(() => getCitationLabel(citationLookupPayload), [citationLookupPayload]);
+    const citationKey = useMemo(() => createCitationLabelLookupKey(citationLookupPayload), [citationLookupPayload]);
+    const [resolvedLabelState, setResolvedLabelState] = useState<ResolvedCitationLabelState | null>(() =>
+        createCachedResolvedCitationLabelState(citationKey),
+    );
 
     useEffect(() => {
-        setResolvedLabel(null);
-
         if (!resolveCitationLabel) {
             return;
         }
 
+        const cachedLabelState = createCachedResolvedCitationLabelState(citationKey);
+        if (cachedLabelState) {
+            setResolvedLabelState((currentLabelState) =>
+                currentLabelState?.citationKey === cachedLabelState.citationKey &&
+                currentLabelState.label === cachedLabelState.label
+                    ? currentLabelState
+                    : cachedLabelState,
+            );
+            return;
+        }
+
         let isCurrent = true;
 
-        Promise.resolve(resolveCitationLabel(citation))
+        Promise.resolve(resolveCitationLabel(citationLookupPayload))
             .then((label) => {
                 if (!isCurrent) {
                     return;
                 }
 
-                const normalizedLabel = label?.trim();
-                if (normalizedLabel) {
-                    setResolvedLabel(normalizedLabel);
+                const nextLabelState = createResolvedCitationLabelState(citationKey, label);
+                if (nextLabelState) {
+                    setResolvedLabelState(nextLabelState);
                 }
             })
             .catch(() => undefined);
@@ -59,7 +163,10 @@ export function useResolvedCitationLabel(
         return () => {
             isCurrent = false;
         };
-    }, [citation, citationKey, resolveCitationLabel]);
+    }, [citationKey, citationLookupPayload, resolveCitationLabel]);
+
+    const resolvedLabel =
+        resolveCitationLabel && resolvedLabelState?.citationKey === citationKey ? resolvedLabelState.label : null;
 
     return resolvedLabel || fallbackLabel;
 }

package/src/book-components/Chat/save/html/htmlSaveFormatDefinition.ts

@@ -4,7 +4,7 @@ import type { ChatParticipant } from '../../types/ChatParticipant';
 import { resolveCitationPreviewUrl } from '../../utils/citationHelpers';
 import { parseMessageButtons } from '../../utils/parseMessageButtons';
 import { renderMarkdown } from '../../utils/renderMarkdown';
-import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
+import type { ChatExportCitationFootnoteRegistry, ChatExportCitationRenderModel } from '../_common/chatExportRendering';
 import {
     buildChatExportParticipantMap,
     createChatExportCitationFootnoteRegistry,
@@ -12,9 +12,8 @@ import {
     formatChatExportCitationFootnoteLabel,
     formatChatExportTimestamp,
     resolveChatExportParticipantVisuals,
-    type ChatExportCitationFootnoteRegistry,
-    type ChatExportCitationRenderModel,
 } from '../_common/chatExportRendering';
+import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
 import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**

package/src/book-components/Chat/save/markdown/mdSaveFormatDefinition.ts

@@ -2,7 +2,7 @@ import { spaceTrim } from 'spacetrim';
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
 import { resolveCitationPreviewUrl } from '../../utils/citationHelpers';
-import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
+import type { ChatExportCitationFootnoteRegistry } from '../_common/chatExportRendering';
 import {
     buildChatExportParticipantMap,
     createChatExportCitationFootnoteRegistry,
@@ -10,8 +10,8 @@ import {
     formatChatExportCitationFootnoteLabel,
     formatChatExportTimestamp,
     resolveChatExportParticipantVisuals,
-    type ChatExportCitationFootnoteRegistry,
 } from '../_common/chatExportRendering';
+import type { ChatSaveFormatDefinition } from '../_common/ChatSaveFormatDefinition';
 import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**

package/src/book-components/Chat/save/pdf/buildChatPdf.ts

@@ -4,8 +4,8 @@ import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../../../errors/UnexpectedError';
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
-import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 import { buildChatHtml, CHAT_HTML_EXPORT_RENDER_ROOT_CLASS_NAME } from '../html/htmlSaveFormatDefinition';
+import { getPromptbookExportBranding } from '../_common/getPromptbookExportBranding';
 
 /**
  * Pixel width used while the standalone HTML document is laid out for PDF pages.

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

@@ -1,62 +1,13 @@
-import { simplifyKnowledgeLabel } from '../../../utils/knowledge/simplifyKnowledgeLabel';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import type { ParsedCitation } from './parseCitationsFromContent';
+import {
+    createReadableCitationSourceDisplayLabel,
+    isCitationSourceUrl,
+    isPlainTextCitationSource,
+    resolveCitationSourceDisplay,
+} from './resolveCitationSourceDisplay';
 import { resolveCitationUrl } from './resolveCitationUrl';
 
-/**
- * Maximum length of plain-text citation labels before truncation.
- */
-const TEXT_LABEL_LENGTH = 30;
-/**
- * Ellipsis appended to truncated citation labels.
- */
-const LABEL_ELLIPSIS = '…';
-/**
- * Pattern matching file extensions at the end of a citation source.
- */
-const FILE_EXTENSION_REGEX = /\.([a-z0-9]{1,10})$/i;
-/**
- * Pattern matching punctuation that should be trimmed from citation tails.
- */
-const TRAILING_PUNCTUATION_REGEX = /[.,;:!?)+\]]+$/;
-/**
- * Pattern matching filename separators that should become spaces in source labels.
- */
-const FILENAME_SEPARATOR_REGEX = /[-_]+/g;
-/**
- * Pattern matching consecutive whitespace in display labels.
- */
-const WHITESPACE_REGEX = /\s+/g;
-
-/**
- * Collapses consecutive whitespace into single spaces.
- */
-function collapseWhitespace(value: string): string {
-    return value.replace(WHITESPACE_REGEX, ' ');
-}
-
-/**
- * Trims a value before further citation normalization.
- */
-function trimToNormalized(value: string): string {
-    return value.trim();
-}
-
-/**
- * Checks whether a citation source ends with a file extension.
- */
-function hasFileExtension(value: string): boolean {
-    const trimmed = trimToNormalized(value);
-    if (!trimmed) {
-        return false;
-    }
-    const withoutFragments = trimmed.split(/[\\?\x23]/)[0] ?? '';
-    const segments = withoutFragments.split(/[\\/]/).filter(Boolean);
-    const lastSegment = (segments.pop() || withoutFragments).replace(TRAILING_PUNCTUATION_REGEX, '').trim();
-
-    return FILE_EXTENSION_REGEX.test(lastSegment);
-}
-
 /**
  * Returns whether the provided value is a valid HTTP(S) URL.
  *
@@ -66,17 +17,7 @@ function hasFileExtension(value: string): boolean {
  * @private utility of `<Chat/>` citation rendering
  */
 export function isCitationUrl(value: string): boolean {
-    const trimmed = trimToNormalized(value);
-    if (!trimmed) {
-        return false;
-    }
-
-    try {
-        const url = new URL(trimmed);
-        return url.protocol === 'http:' || url.protocol === 'https:';
-    } catch (error) {
-        return false;
-    }
+    return isCitationSourceUrl(value);
 }
 
 /**
@@ -88,20 +29,7 @@ export function isCitationUrl(value: string): boolean {
  * @private utility of `<Chat/>` citation rendering
  */
 export function isPlainTextCitation(citation: ParsedCitation): boolean {
-    const trimmed = trimToNormalized(citation.source);
-    if (!trimmed) {
-        return false;
-    }
-
-    if (isCitationUrl(trimmed) || hasFileExtension(trimmed)) {
-        return false;
-    }
-
-    if (/\s/.test(trimmed)) {
-        return true;
-    }
-
-    return trimmed.length > TEXT_LABEL_LENGTH;
+    return isPlainTextCitationSource(citation);
 }
 
 /**
@@ -113,26 +41,7 @@ export function isPlainTextCitation(citation: ParsedCitation): boolean {
  * @private utility of `<Chat/>` citation rendering
  */
 export function getCitationLabel(citation: ParsedCitation): string {
-    const title = normalizeCitationDisplayLabel(citation.title);
-    if (title) {
-        return title;
-    }
-
-    const trimmed = trimToNormalized(citation.source);
-    if (!trimmed) {
-        return citation.source;
-    }
-
-    if (isPlainTextCitation(citation)) {
-        const collapsed = collapseWhitespace(trimmed);
-        if (collapsed.length <= TEXT_LABEL_LENGTH) {
-            return collapsed;
-        }
-
-        return collapsed.slice(0, TEXT_LABEL_LENGTH) + LABEL_ELLIPSIS;
-    }
-
-    return createReadableCitationSourceLabel(trimmed);
+    return resolveCitationSourceDisplay(citation).label;
 }
 
 /**
@@ -148,7 +57,7 @@ export function resolveCitationPreviewUrl(
     citation: ParsedCitation,
     participants: ReadonlyArray<ChatParticipant>,
 ): string | null {
-    const trimmed = trimToNormalized(citation.source);
+    const trimmed = citation.source.trim();
     const explicitUrl = citation.url?.trim() || null;
     const literalUrl = isCitationUrl(trimmed) ? trimmed : null;
     const knowledgeUrl = resolveCitationUrl(trimmed, participants);
@@ -165,70 +74,7 @@ export function resolveCitationPreviewUrl(
  * @private utility of `<Chat/>` citation rendering
  */
 export function createReadableCitationSourceLabel(source: string): string {
-    const trimmed = trimToNormalized(source);
-    if (!trimmed) {
-        return source;
-    }
-
-    const parsedUrl = parseCitationUrl(trimmed);
-    const filenameCandidate = parsedUrl
-        ? getUrlLabelCandidate(parsedUrl) || parsedUrl.hostname.replace(/^www\./i, '')
-        : simplifyKnowledgeLabel(trimmed);
-
-    return normalizeCitationDisplayLabel(filenameCandidate) || simplifyKnowledgeLabel(trimmed);
-}
-
-/**
- * Normalizes a citation label candidate for display.
- *
- * @param label - Raw candidate label.
- * @returns Cleaned label or `null` when empty.
- *
- * @private utility of `<Chat/>` citation rendering
- */
-function normalizeCitationDisplayLabel(label: string | undefined): string | null {
-    const normalized = collapseWhitespace((label || '').replace(FILENAME_SEPARATOR_REGEX, ' ')).trim();
-
-    return normalized || null;
-}
-
-/**
- * Parses one HTTP(S) citation URL, returning null for non-URL values.
- *
- * @param value - Candidate URL value.
- * @returns Parsed URL or null.
- *
- * @private utility of `<Chat/>` citation rendering
- */
-function parseCitationUrl(value: string): URL | null {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'http:' || url.protocol === 'https:' ? url : null;
-    } catch {
-        return null;
-    }
-}
-
-/**
- * Extracts a readable candidate from a URL path.
- *
- * @param url - Parsed citation URL.
- * @returns URL path label candidate or null.
- *
- * @private utility of `<Chat/>` citation rendering
- */
-function getUrlLabelCandidate(url: URL): string | null {
-    const pathSegments = url.pathname.split('/').filter(Boolean);
-    const lastPathSegment = pathSegments[pathSegments.length - 1];
-    if (!lastPathSegment) {
-        return null;
-    }
-
-    try {
-        return simplifyKnowledgeLabel(decodeURIComponent(lastPathSegment));
-    } catch {
-        return simplifyKnowledgeLabel(lastPathSegment);
-    }
+    return createReadableCitationSourceDisplayLabel(source);
 }
 
 // TODO: [💞] Spread into multiple files

package/src/book-components/Chat/utils/isVisibleChatToolCall.ts

@@ -1,4 +1,5 @@
-import { ASSISTANT_PREPARATION_TOOL_CALL_NAME, type ToolCall } from '../../../types/ToolCall';
+import type { ToolCall } from '../../../types/ToolCall';
+import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../types/ToolCall';
 
 /**
  * Tool calls that stay available in message data but should not be surfaced as user-facing chat progress.

package/src/book-components/Chat/utils/messagesToHtml.ts

@@ -1,6 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { PROMPTBOOK_LOGO_URL } from '../../../config';
-import { escapeHtml } from '../../_common/react-utils/escapeHtml';
+import { escapeHtml } from '../../../utils/html/escapeHtml';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import { getChatMessageTimingDisplay } from './getChatMessageTimingDisplay';

package/src/book-components/Chat/utils/parseMessageButtons.ts

@@ -9,6 +9,20 @@ export type MessageQuickButton = {
     message: string;
 };
 
+/**
+ * Represents a quick draft-message button parsed from chat markdown.
+ *
+ * Unlike `MessageQuickButton`, clicking this button prefills the composer with an
+ * editable draft instead of sending the message immediately.
+ *
+ * @private internal helper type of `MessageButton`
+ */
+export type MessageDraftQuickButton = {
+    type: 'messageDraft';
+    text: string;
+    messageDraft: string;
+};
+
 /**
  * Represents a quick action button parsed from chat markdown.
  *
@@ -25,7 +39,7 @@ export type ActionQuickButton = {
  *
  * @public exported from `@promptbook/components`
  */
-export type MessageButton = MessageQuickButton | ActionQuickButton;
+export type MessageButton = MessageQuickButton | MessageDraftQuickButton | ActionQuickButton;
 
 /**
  * Extracts one quick button definition from a markdown link query string.
@@ -48,6 +62,16 @@ function parseQuickButtonDefinition(text: string, query: string): MessageButton
         };
     }
 
+    const messageDraft = searchParams.get('messageDraft');
+
+    if (messageDraft !== null) {
+        return {
+            type: 'messageDraft',
+            text,
+            messageDraft,
+        };
+    }
+
     const code = searchParams.get('action');
 
     if (code !== null) {
@@ -62,7 +86,8 @@ function parseQuickButtonDefinition(text: string, query: string): MessageButton
 }
 
 /**
- * Parses markdown quick buttons in the format `[Button Text](?message=...)` or `[Button Text](?action=...)`.
+ * Parses markdown quick buttons in the format `[Button Text](?message=...)`, `[Button Text](?messageDraft=...)`
+ * or `[Button Text](?action=...)`.
  * Returns both the content without supported quick buttons and the extracted button definitions.
  *
  * @param content The markdown content that may contain buttons