@promptbook/cli 0.113.0-9 → 0.114.0-0

package/src/book-components/Chat/Chat/pagePreview/normalizePagePreviewInputEvent.ts

@@ -0,0 +1,242 @@
+import type { PagePreviewInputEvent, PagePreviewPointerButton } from './PagePreviewInputEvent';
+import { clampPagePreviewViewport } from './PagePreviewViewport';
+
+/**
+ * Maximum absolute wheel delta accepted from one preview input event.
+ *
+ * @private constant of `normalizePagePreviewInputEvent`
+ */
+const PAGE_PREVIEW_MAX_WHEEL_DELTA = 1600;
+
+/**
+ * Maximum `KeyboardEvent.key` length accepted from one preview input event.
+ *
+ * @private constant of `normalizePagePreviewInputEvent`
+ */
+const PAGE_PREVIEW_MAX_KEY_LENGTH = 32;
+
+/**
+ * Maximum click count accepted from one preview pointer event.
+ *
+ * @private constant of `normalizePagePreviewInputEvent`
+ */
+const PAGE_PREVIEW_MAX_CLICK_COUNT = 3;
+
+/**
+ * Maximum URL length accepted from one preview `goto` event.
+ *
+ * @private constant of `normalizePagePreviewInputEvent`
+ */
+const PAGE_PREVIEW_MAX_GOTO_URL_LENGTH = 2048;
+
+/**
+ * Validates and normalizes one untrusted page-preview input payload into a typed input event.
+ *
+ * Note: This performs only structural validation shared by client and server — the Agents Server
+ * additionally re-checks `goto` URLs against private/internal targets before navigating.
+ *
+ * @param payload - Unknown JSON payload (usually the parsed request body).
+ * @returns Normalized input event or `null` when the payload is invalid.
+ *
+ * @private utility shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export function normalizePagePreviewInputEvent(payload: unknown): PagePreviewInputEvent | null {
+    if (typeof payload !== 'object' || payload === null) {
+        return null;
+    }
+
+    const candidate = payload as Record<string, unknown>;
+
+    switch (candidate.type) {
+        case 'move':
+        case 'click': {
+            const pointer = normalizePointerRatios(candidate);
+            if (!pointer) {
+                return null;
+            }
+
+            return { type: candidate.type, ...pointer };
+        }
+
+        case 'down':
+        case 'up': {
+            const pointer = normalizePointerRatios(candidate);
+            const button = normalizePointerButton(candidate.button);
+            const clickCount = normalizeClickCount(candidate.clickCount);
+            if (!pointer || !button) {
+                return null;
+            }
+
+            return { type: candidate.type, ...pointer, button, clickCount };
+        }
+
+        case 'wheel': {
+            const pointer = normalizePointerRatios(candidate);
+            const deltaX = normalizeWheelDelta(candidate.deltaX);
+            const deltaY = normalizeWheelDelta(candidate.deltaY);
+            if (!pointer || deltaX === null || deltaY === null) {
+                return null;
+            }
+
+            return { type: 'wheel', ...pointer, deltaX, deltaY };
+        }
+
+        case 'keydown':
+        case 'keyup': {
+            const key = normalizeKey(candidate.key);
+            if (!key) {
+                return null;
+            }
+
+            return { type: candidate.type, key };
+        }
+
+        case 'resize': {
+            const viewport = clampPagePreviewViewport(candidate.width, candidate.height);
+            if (!viewport) {
+                return null;
+            }
+
+            return { type: 'resize', ...viewport };
+        }
+
+        case 'navigate': {
+            if (candidate.action !== 'back' && candidate.action !== 'forward' && candidate.action !== 'reload') {
+                return null;
+            }
+
+            return { type: 'navigate', action: candidate.action };
+        }
+
+        case 'goto': {
+            const url = normalizeGotoUrl(candidate.url);
+            if (!url) {
+                return null;
+            }
+
+            return { type: 'goto', url };
+        }
+
+        default:
+            return null;
+    }
+}
+
+/**
+ * Normalizes the pointer coordinate ratios of one payload.
+ *
+ * @param candidate - Raw payload fields.
+ * @returns Ratios clamped to the viewport bounds, or `null` when invalid.
+ */
+function normalizePointerRatios(
+    candidate: Record<string, unknown>,
+): { readonly xRatio: number; readonly yRatio: number } | null {
+    const xRatio = normalizeRatio(candidate.xRatio);
+    const yRatio = normalizeRatio(candidate.yRatio);
+
+    if (xRatio === null || yRatio === null) {
+        return null;
+    }
+
+    return { xRatio, yRatio };
+}
+
+/**
+ * Normalizes one pointer coordinate ratio.
+ *
+ * @param value - Unknown payload value.
+ * @returns Ratio clamped to `0..1`, or `null` when invalid.
+ */
+function normalizeRatio(value: unknown): number | null {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+
+    return Math.max(0, Math.min(1, value));
+}
+
+/**
+ * Normalizes one mouse-wheel delta.
+ *
+ * @param value - Unknown payload value.
+ * @returns Clamped wheel delta, or `null` when invalid.
+ */
+function normalizeWheelDelta(value: unknown): number | null {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+
+    return Math.max(-PAGE_PREVIEW_MAX_WHEEL_DELTA, Math.min(PAGE_PREVIEW_MAX_WHEEL_DELTA, value));
+}
+
+/**
+ * Normalizes one pointer button name.
+ *
+ * @param value - Unknown payload value.
+ * @returns Pointer button, or `null` when invalid.
+ */
+function normalizePointerButton(value: unknown): PagePreviewPointerButton | null {
+    if (value === undefined) {
+        return 'left';
+    }
+
+    return value === 'left' || value === 'middle' || value === 'right' ? value : null;
+}
+
+/**
+ * Normalizes one pointer click count.
+ *
+ * @param value - Unknown payload value.
+ * @returns Click count clamped to `1..3`.
+ */
+function normalizeClickCount(value: unknown): number {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return 1;
+    }
+
+    return Math.max(1, Math.min(PAGE_PREVIEW_MAX_CLICK_COUNT, value));
+}
+
+/**
+ * Normalizes one `KeyboardEvent.key` value.
+ *
+ * @param value - Unknown payload value.
+ * @returns Key name, or `null` when invalid.
+ */
+function normalizeKey(value: unknown): string | null {
+    if (typeof value !== 'string' || value.length === 0 || value.length > PAGE_PREVIEW_MAX_KEY_LENGTH) {
+        return null;
+    }
+    // Note: The spacebar key value is a single space, so only real control characters are rejected
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(value)) {
+        return null;
+    }
+
+    return value;
+}
+
+/**
+ * Normalizes one `goto` navigation URL.
+ *
+ * @param value - Unknown payload value.
+ * @returns Absolute HTTP(S) URL, or `null` when invalid.
+ */
+function normalizeGotoUrl(value: unknown): string | null {
+    if (typeof value !== 'string' || value.length === 0 || value.length > PAGE_PREVIEW_MAX_GOTO_URL_LENGTH) {
+        return null;
+    }
+
+    let parsedUrl: URL;
+    try {
+        parsedUrl = new URL(value);
+    } catch {
+        return null;
+    }
+
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        return null;
+    }
+
+    return parsedUrl.href;
+}

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

@@ -1,6 +1,10 @@
 import { type ReactElement } from 'react';
 import type { TODO_any } from '../../../utils/organization/TODO_any';
-import { buildTimeoutToolPrimarySentence, buildTimeoutToolScheduleSentence, resolveTimeoutToolCallPresentation } from '../utils/timeoutToolCallPresentation';
+import {
+    buildTimeoutToolPrimarySentence,
+    buildTimeoutToolScheduleSentence,
+    resolveTimeoutToolCallPresentation,
+} from '../utils/timeoutToolCallPresentation';
 import styles from './Chat.module.css';
 import { renderToolCallClockPanel } from './renderToolCallClockPanel';
 

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

@@ -0,0 +1,11 @@
+import type { id } from '../../../types/string_token';
+import type { ChatMessage } from '../types/ChatMessage';
+
+/**
+ * Resolves the stable key used for local chat feedback state.
+ *
+ * @private utility of `<Chat/>`
+ */
+export function resolveChatRatingMessageKey(message: Pick<ChatMessage, 'id' | 'content'>): id {
+    return message.id || message.content /* <- TODO: [??][??] Is `message.content` good replacement for the ID */;
+}

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

@@ -1,13 +1,13 @@
 'use client';
 
 import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-  type ChangeEvent,
-  type KeyboardEvent as ReactKeyboardEvent,
-  type MutableRefObject
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    type ChangeEvent,
+    type KeyboardEvent as ReactKeyboardEvent,
+    type MutableRefObject,
 } from 'react';
 import { spaceTrim } from 'spacetrim';
 import type { ChatMessage } from '../types/ChatMessage';

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

@@ -1,13 +1,13 @@
 'use client';
 
 import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-  type Dispatch,
-  type MutableRefObject,
-  type SetStateAction
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    type Dispatch,
+    type MutableRefObject,
+    type SetStateAction,
 } from 'react';
 import type { SpeechRecognitionErrorCode, SpeechRecognitionEvent } from '../../../types/SpeechRecognition';
 import type { ChatProps } from './ChatProps';

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

@@ -13,7 +13,10 @@ import { getToolCallTimestamp } from '../utils/toolCallParsing/getToolCallTimest
 import { parseTeamToolResult } from '../utils/toolCallParsing/parseTeamToolResult';
 import { parseToolCallResult } from '../utils/toolCallParsing/parseToolCallResult';
 import type { TeamToolResult } from '../utils/toolCallParsing/TeamToolResult';
-import { createAdvancedToolCallReportFilename, createAdvancedToolCallReportMarkdown } from './renderAdvancedToolCallDetails';
+import {
+    createAdvancedToolCallReportFilename,
+    createAdvancedToolCallReportMarkdown,
+} from './renderAdvancedToolCallDetails';
 
 /**
  * Tool-call snapshot rendered by the modal.

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

@@ -175,6 +175,141 @@
     text-decoration-thickness: 2px;
 }
 
+.MarkdownContent a.inlineReferenceChip,
+.MarkdownContent details.inlineReferenceChip > summary {
+    display: inline-flex;
+    max-width: 100%;
+    align-items: center;
+    gap: 0.42em;
+    padding: 0.16em 0.58em;
+    border: 1px solid color-mix(in srgb, var(--md-link-color) 28%, rgba(148, 163, 184, 0.45));
+    border-radius: 8px;
+    background: color-mix(in srgb, var(--md-link-color) 9%, rgba(255, 255, 255, 0.9));
+    color: var(--md-link-color);
+    font-size: 0.92em;
+    font-weight: 650;
+    line-height: 1.35;
+    text-decoration: none;
+    vertical-align: baseline;
+    white-space: nowrap;
+    box-shadow: 0 1px 2px rgba(15, 23, 42, 0.08);
+}
+
+.MarkdownContent a.inlineReferenceChip {
+    margin: 0 0.08em;
+}
+
+.MarkdownContent details.inlineReferenceChip {
+    position: relative;
+    display: inline-block;
+    max-width: 100%;
+    margin: 0 0.08em;
+    vertical-align: baseline;
+}
+
+.MarkdownContent details.inlineReferenceChip > summary {
+    cursor: pointer;
+    list-style: none;
+}
+
+.MarkdownContent details.inlineReferenceChip > summary::-webkit-details-marker {
+    display: none;
+}
+
+.MarkdownContent :is(a.inlineReferenceChip, details.inlineReferenceChip > summary)::before {
+    content: '';
+    display: inline-block;
+    box-sizing: border-box;
+    width: 0.9em;
+    height: 0.62em;
+    flex: 0 0 auto;
+    border: 1.8px solid currentColor;
+    border-radius: 0.16em;
+    opacity: 0.86;
+    transform: translateY(0.03em);
+}
+
+.MarkdownContent :is(a.inlineReferenceChip, details.inlineReferenceChip > summary):hover,
+.MarkdownContent :is(a.inlineReferenceChip, details.inlineReferenceChip > summary):focus-visible {
+    border-color: color-mix(in srgb, var(--md-link-color) 52%, rgba(148, 163, 184, 0.35));
+    background: color-mix(in srgb, var(--md-link-color) 14%, rgba(255, 255, 255, 0.94));
+    opacity: 1;
+}
+
+.MarkdownContent details.inlineReferenceChip > div {
+    position: absolute;
+    z-index: 20;
+    top: calc(100% + 0.45em);
+    left: 0;
+    display: grid;
+    min-width: 15rem;
+    padding: 0.45rem;
+    border: 1px solid color-mix(in srgb, var(--md-link-color) 22%, rgba(148, 163, 184, 0.45));
+    border-radius: 0.65rem;
+    background: color-mix(in srgb, var(--md-table-bg) 92%, white);
+    box-shadow: 0 10px 24px rgba(15, 23, 42, 0.16);
+}
+
+.MarkdownContent :global(.inlineReferenceMenuStatus) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.38em;
+    color: var(--md-muted-color);
+    font-size: 0.78em;
+    font-weight: 650;
+}
+
+.MarkdownContent details.inlineReferenceChip > summary :global(.inlineReferenceMenuStatus) {
+    width: 0.52em;
+    height: 0.52em;
+    margin-left: 0.05em;
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--md-muted-color) 55%, transparent);
+}
+
+.MarkdownContent :global(.inlineReferenceMenuStatus--active) {
+    color: #047857;
+}
+
+.MarkdownContent details.inlineReferenceChip > summary :global(.inlineReferenceMenuStatus--active) {
+    background: #10b981;
+    box-shadow: 0 0 0 0.16em color-mix(in srgb, #10b981 20%, transparent);
+}
+
+.MarkdownContent :global(.inlineReferenceMenuStatus)::before {
+    content: '';
+    width: 0.55em;
+    height: 0.55em;
+    border-radius: 999px;
+    background: currentColor;
+}
+
+.MarkdownContent details.inlineReferenceChip > summary :global(.inlineReferenceMenuStatus)::before {
+    display: none;
+}
+
+.MarkdownContent :global(.inlineReferenceMenuOption) {
+    display: block;
+    padding: 0.45rem 0.55rem;
+    border-radius: 0.4rem;
+    color: var(--md-link-color);
+    font-size: 0.82em;
+    font-weight: 650;
+    line-height: 1.35;
+    text-decoration: none;
+}
+
+.MarkdownContent a:global(.inlineReferenceMenuOption):hover,
+.MarkdownContent a:global(.inlineReferenceMenuOption):focus-visible {
+    background: color-mix(in srgb, var(--md-link-color) 10%, transparent);
+    text-decoration: none;
+}
+
+.MarkdownContent :global(.inlineReferenceMenuOption--disabled) {
+    cursor: not-allowed;
+    color: var(--md-muted-color);
+}
+
 .MarkdownContent img {
     display: block;
     max-width: 100%;

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

@@ -5,6 +5,7 @@ import { createRoot, type Root } from 'react-dom/client';
 import type { string_markdown } from '../../../types/string_markdown';
 import { classNames } from '../../_common/react-utils/classNames';
 import { CodeBlock } from '../CodeBlock/CodeBlock';
+import type { MarkdownInlineReference } from '../utils/renderMarkdown';
 import { renderMarkdown } from '../utils/renderMarkdown';
 import styles from './MarkdownContent.module.css';
 
@@ -22,6 +23,7 @@ type MarkdownContentProps = {
     content: string_markdown;
 
     className?: string;
+    inlineReferences?: ReadonlyArray<MarkdownInlineReference>;
     onCreateAgent?: (bookContent: string) => void;
     theme?: 'LIGHT' | 'DARK';
 };
@@ -114,13 +116,15 @@ function resolveClickedDetailsElement(target: EventTarget | null, container: HTM
  * @public exported from `@promptbook/components`
  */
 export const MarkdownContent = memo(function MarkdownContent(props: MarkdownContentProps) {
-    const { content, className, onCreateAgent, theme } = props;
+    const { content, className, inlineReferences, onCreateAgent, theme } = props;
     const htmlContent = useMemo(
         () =>
             renderMarkdown(content, {
                 citationReferenceClassName: styles.citationRef,
+                inlineReferences,
+                inlineReferenceClassName: styles.inlineReferenceChip,
             }),
-        [content],
+        [content, inlineReferences],
     );
     const [resolvedTheme, setResolvedTheme] = useState<MarkdownContentTheme>(() => resolveMarkdownContentTheme(theme));
     const containerRef = useRef<HTMLDivElement>(null);

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

@@ -26,9 +26,28 @@
 }
 
 .icon {
-    font-size: 1.1em;
+    width: 1.25rem;
+    height: 1.25rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: color-mix(in srgb, var(--message-text-color, #0f172a) 76%, #2563eb 24%);
     flex-shrink: 0;
-    font-family: 'OpenMojiColor', 'OpenMojiBlack';
+    overflow: hidden;
+    border-radius: 5px;
+}
+
+.iconSvg {
+    width: 0.95rem;
+    height: 0.95rem;
+}
+
+.thumbnail {
+    width: 100%;
+    height: 100%;
+    display: block;
+    object-fit: cover;
+    background: color-mix(in srgb, var(--message-text-color, #0f172a) 10%, transparent);
 }
 
 .label {

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

@@ -1,11 +1,56 @@
 'use client';
 
+import {
+    Archive,
+    File,
+    FileCode,
+    FileJson,
+    FileSpreadsheet,
+    FileText,
+    Globe2,
+    ImageIcon,
+    Music,
+    Presentation,
+    Table,
+    Video,
+    type LucideIcon,
+} from 'lucide-react';
+import { useEffect, useState } from 'react';
 import { useResolvedCitationLabel } from '../hooks/useResolvedCitationLabel';
 import type { CitationLabelResolver } from '../types/CitationLabelResolver';
-import { isCitationUrl, isPlainTextCitation } from '../utils/citationHelpers';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+import type { CitationSourceDisplay, CitationSourceKind } from '../utils/resolveCitationSourceDisplay';
+import { resolveCitationSourceDisplay } from '../utils/resolveCitationSourceDisplay';
 import styles from './SourceChip.module.css';
 
+/**
+ * Icon size used by source-chip SVG graphics.
+ *
+ * @private utility constant of `<SourceChip/>`
+ */
+const SOURCE_CHIP_ICON_SIZE = 15;
+
+/**
+ * Source kind to icon map used when no thumbnail is available.
+ *
+ * @private utility constant of `<SourceChip/>`
+ */
+const SOURCE_CHIP_ICON_BY_KIND: Readonly<Record<CitationSourceKind, LucideIcon>> = {
+    archive: Archive,
+    audio: Music,
+    code: FileCode,
+    document: FileText,
+    file: File,
+    image: ImageIcon,
+    json: FileJson,
+    'plain-text': FileText,
+    presentation: Presentation,
+    spreadsheet: FileSpreadsheet,
+    table: Table,
+    video: Video,
+    website: Globe2,
+};
+
 /**
  * Props for SourceChip component
  */
@@ -71,21 +116,13 @@ export function SourceChip({
     };
 
     // Keep source chips concise and human-readable for CDN-backed knowledge files.
-    const normalizedSource = citation.source.trim();
     const displayName = useResolvedCitationLabel(citation, resolveCitationLabel);
+    const sourceDisplay = resolveCitationSourceDisplay(citation);
     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';
-    const icon = isPlainTextCitation(citation)
-        ? '📝'
-        : isCitationUrl(normalizedSource)
-        ? '🌐'
-        : getFileIcon(fileExtension);
-
     return (
-        <button className={`${styles.sourceChip} ${className || ''}`} onClick={handleClick} title={title}>
-            <span className={styles.icon}>{icon}</span>
+        <button type="button" className={`${styles.sourceChip} ${className || ''}`} onClick={handleClick} title={title}>
+            <SourceChipVisual sourceDisplay={sourceDisplay} />
             <span className={styles.label}>
                 <span className={styles.labelText}>{displayName}</span>
                 {isCitationIdVisible && <span className={styles.citationId}> [{citation.id}]</span>}
@@ -96,39 +133,41 @@ export function SourceChip({
 }
 
 /**
- * Gets an appropriate emoji icon for a file type
+ * Renders either an image thumbnail or a semantic source icon.
+ *
+ * @private component of `<SourceChip/>`
  */
-function getFileIcon(extension: string): string {
-    const iconMap: Record<string, string> = {
-        pdf: '📄',
-        doc: '📝',
-        docx: '📝',
-        txt: '📝',
-        md: '📝',
-        html: '🌐',
-        htm: '🌐',
-        json: '📋',
-        xml: '📋',
-        csv: '📊',
-        xls: '📊',
-        xlsx: '📊',
-        ppt: '📊',
-        pptx: '📊',
-        jpg: '🖼️',
-        jpeg: '🖼️',
-        png: '🖼️',
-        gif: '🖼️',
-        svg: '🖼️',
-        mp4: '🎥',
-        mov: '🎥',
-        avi: '🎥',
-        mp3: '🎵',
-        wav: '🎵',
-        zip: '📦',
-        rar: '📦',
-        tar: '📦',
-        gz: '📦',
-    };
+function SourceChipVisual(props: { readonly sourceDisplay: CitationSourceDisplay }) {
+    const { sourceDisplay } = props;
+    const [isThumbnailUnavailable, setIsThumbnailUnavailable] = useState(false);
 
-    return iconMap[extension] || '📄';
+    useEffect(() => {
+        setIsThumbnailUnavailable(false);
+    }, [sourceDisplay.thumbnailUrl]);
+
+    if (sourceDisplay.thumbnailUrl && !isThumbnailUnavailable) {
+        return (
+            <span className={styles.icon} aria-hidden="true">
+                <img
+                    src={sourceDisplay.thumbnailUrl}
+                    alt=""
+                    className={styles.thumbnail}
+                    loading="lazy"
+                    decoding="async"
+                    referrerPolicy="no-referrer"
+                    onError={() => {
+                        setIsThumbnailUnavailable(true);
+                    }}
+                />
+            </span>
+        );
+    }
+
+    const Icon = SOURCE_CHIP_ICON_BY_KIND[sourceDisplay.kind];
+
+    return (
+        <span className={styles.icon} aria-hidden="true">
+            <Icon size={SOURCE_CHIP_ICON_SIZE} className={styles.iconSvg} strokeWidth={2.35} />
+        </span>
+    );
 }