@promptbook/cli 0.113.0-1 → 0.113.0-3

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

@@ -9,7 +9,7 @@ export type CitationIframePreviewProps = {
 };
 /**
  * Renders a citation URL preview as an iframe when the target page allows embedding,
- * or falls back to a live server-side browser preview with an "Open in new tab" link
+ * or falls back to a live server-side browser stream 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>`.

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

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

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.113.0-0`).
+ * It follows semantic versioning (e.g., `0.113.0-1`).
  *
  * @generated
  */

package/package.json

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

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

@@ -3322,32 +3322,60 @@
     font-size: 0.9em;
 }
 
-.citationBrowserPreviewFallback {
+.citationScreenshotFallback {
     width: 100%;
     position: relative;
     display: flex;
     flex-direction: column;
 }
 
-.citationBrowserPreviewImage {
+.citationScreenshotImage {
     width: 100%;
-    aspect-ratio: 16 / 10;
     max-height: 60vh;
     min-height: 400px;
-    object-fit: contain;
+    object-fit: cover;
     object-position: top;
     display: block;
-    background: #fff;
-    cursor: crosshair;
-    outline: none;
-    touch-action: none;
 }
 
-.citationBrowserPreviewImage:focus-visible {
-    box-shadow: inset 0 0 0 3px rgba(0, 112, 243, 0.35);
+.citationScreenshotLink {
+    display: block;
+    text-align: center;
+    padding: 10px 16px;
+    background: #f0f0f0;
+    color: #333;
+    font-size: 0.9em;
+    font-weight: 500;
+    text-decoration: none;
+    border-top: 1px solid #ddd;
+    transition: background 0.15s;
+}
+
+.citationScreenshotLink:hover {
+    background: #e0e0e0;
+    text-decoration: underline;
+}
+
+.citationBrowserStreamFallback {
+    width: 100%;
+    position: relative;
+    display: flex;
+    flex-direction: column;
+}
+
+.citationBrowserStreamImage {
+    width: 100%;
+    max-height: 60vh;
+    min-height: 400px;
+    object-fit: cover;
+    object-position: top;
+    display: block;
+    cursor: crosshair;
+    user-select: none;
+    touch-action: none;
 }
 
-.citationBrowserPreviewLink {
+.citationBrowserStreamLink {
     display: block;
     text-align: center;
     padding: 10px 16px;
@@ -3360,7 +3388,7 @@
     transition: background 0.15s;
 }
 
-.citationBrowserPreviewLink:hover {
+.citationBrowserStreamLink:hover {
     background: #e0e0e0;
     text-decoration: underline;
 }

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

@@ -1,8 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useId, useMemo, useState } from 'react';
-import type { KeyboardEvent, MouseEvent, WheelEvent } from 'react';
-import { LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT, LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH } from '../utils/livePagePreviewConstants';
+import { useEffect, useMemo, useState, type MouseEvent, type WheelEvent } from 'react';
 import styles from './Chat.module.css';
 
 /**
@@ -20,47 +18,35 @@ export type CitationIframePreviewProps = {
  *
  * @private type of `<CitationIframePreview/>`
  */
-type EmbedStatus = 'loading' | 'embed' | 'browser';
+type EmbedStatus = 'loading' | 'embed' | 'browser-stream';
 
 /**
- * Browser-preview interaction sent to the Agents Server preview route.
+ * Prefix shared with the Agents Server page-preview stream route.
  *
- * @private type of `<CitationIframePreview/>`
+ * @private component constant of `<CitationIframePreview/>`
  */
-type LivePagePreviewInteraction =
-    | {
-          readonly type: 'click';
-          readonly x: number;
-          readonly y: number;
-      }
-    | {
-          readonly type: 'wheel';
-          readonly deltaX: number;
-          readonly deltaY: number;
-      }
-    | {
-          readonly type: 'keyDown';
-          readonly key: string;
-      };
+const BROWSER_PREVIEW_SESSION_ID_PREFIX = 'page-preview-';
 
 /**
- * Pointer position translated into the live-preview browser viewport.
+ * Fallback suffix length used when `crypto.randomUUID` is unavailable.
  *
- * @private type of `<CitationIframePreview/>`
+ * @private component constant of `<CitationIframePreview/>`
  */
-type LivePagePreviewPointerPosition = {
-    readonly x: number;
-    readonly y: number;
-};
+const BROWSER_PREVIEW_RANDOM_SUFFIX_LENGTH = 24;
 
 /**
- * Keyboard keys that should not be forwarded as standalone browser actions.
+ * Pointer ratio resolved from one browser preview interaction.
+ *
+ * @private type of `<CitationIframePreview/>`
  */
-const LIVE_PAGE_PREVIEW_IGNORED_KEYS = new Set(['Alt', 'CapsLock', 'Control', 'Meta', 'Shift']);
+type BrowserPreviewPointerRatio = {
+    readonly xRatio: number;
+    readonly yRatio: number;
+};
 
 /**
  * Renders a citation URL preview as an iframe when the target page allows embedding,
- * or falls back to a live server-side browser preview with an "Open in new tab" link
+ * or falls back to a live server-side browser stream 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>`.
@@ -70,26 +56,27 @@ const LIVE_PAGE_PREVIEW_IGNORED_KEYS = new Set(['Alt', 'CapsLock', 'Control', 'M
  */
 export function CitationIframePreview({ src, title }: CitationIframePreviewProps) {
     const [status, setStatus] = useState<EmbedStatus>('loading');
+    const browserPreviewSessionId = useMemo(() => createBrowserPreviewSessionId(), [src]);
 
     useEffect(() => {
-        let isCancelled = false;
+        let cancelled = false;
 
         fetch(`/api/page-preview/check?url=${encodeURIComponent(src)}`)
             .then((response) => response.json())
             .then((data: { canEmbed: boolean }) => {
-                if (!isCancelled) {
-                    setStatus(data.canEmbed ? 'embed' : 'browser');
+                if (!cancelled) {
+                    setStatus(data.canEmbed ? 'embed' : 'browser-stream');
                 }
             })
             .catch(() => {
                 // API not available — fall back to iframe (e.g. outside agents-server)
-                if (!isCancelled) {
+                if (!cancelled) {
                     setStatus('embed');
                 }
             });
 
         return () => {
-            isCancelled = true;
+            cancelled = true;
         };
     }, [src]);
 
@@ -97,157 +84,122 @@ export function CitationIframePreview({ src, title }: CitationIframePreviewProps
         return <div className={styles.citationIframeLoading}>Loading preview…</div>;
     }
 
-    if (status === 'browser') {
-        return <LiveBrowserPreview src={src} title={title} />;
+    if (status === 'browser-stream') {
+        return (
+            <div className={styles.citationBrowserStreamFallback}>
+                <img
+                    src={`/api/page-preview/stream?url=${encodeURIComponent(src)}&sessionId=${encodeURIComponent(
+                        browserPreviewSessionId,
+                    )}`}
+                    alt={`Live browser preview of ${title}`}
+                    className={styles.citationBrowserStreamImage}
+                    draggable={false}
+                    onClick={(event) => {
+                        const pointerRatio = resolveBrowserPreviewPointerRatio(event);
+                        if (!pointerRatio) {
+                            return;
+                        }
+
+                        sendBrowserPreviewInput({
+                            sessionId: browserPreviewSessionId,
+                            type: 'click',
+                            ...pointerRatio,
+                        });
+                    }}
+                    onWheel={(event) => {
+                        event.preventDefault();
+                        const pointerRatio = resolveBrowserPreviewPointerRatio(event);
+                        if (!pointerRatio) {
+                            return;
+                        }
+
+                        sendBrowserPreviewInput({
+                            sessionId: browserPreviewSessionId,
+                            type: 'wheel',
+                            deltaX: event.deltaX,
+                            deltaY: event.deltaY,
+                            ...pointerRatio,
+                        });
+                    }}
+                />
+                <a href={src} target="_blank" rel="noopener noreferrer" className={styles.citationBrowserStreamLink}>
+                    Open in new tab ↗
+                </a>
+            </div>
+        );
     }
 
     return <iframe src={src} className={styles.citationIframe} title={title} />;
 }
 
 /**
- * Renders and controls a streamed browser preview for non-embeddable citation URLs.
+ * Creates one client-side browser preview session id.
  *
- * @private component of `<CitationIframePreview/>`
+ * @returns Session id accepted by Agents Server page-preview stream routes.
  */
-function LiveBrowserPreview({ src, title }: CitationIframePreviewProps) {
-    const reactSessionId = useId();
-    const sessionId = useMemo(() => createLivePagePreviewSessionId(reactSessionId), [reactSessionId]);
-    const streamSrc = useMemo(
-        () => `/api/page-preview/live?url=${encodeURIComponent(src)}&sessionId=${encodeURIComponent(sessionId)}`,
-        [sessionId, src],
-    );
-
-    const handleClick = useCallback(
-        (event: MouseEvent<HTMLImageElement>) => {
-            event.currentTarget.focus();
-            const position = resolveLivePagePreviewPointerPosition(event);
-            if (!position) {
-                return;
-            }
-
-            void postLivePagePreviewInteraction(sessionId, {
-                type: 'click',
-                x: position.x,
-                y: position.y,
-            });
-        },
-        [sessionId],
-    );
-
-    const handleWheel = useCallback(
-        (event: WheelEvent<HTMLImageElement>) => {
-            event.preventDefault();
-            void postLivePagePreviewInteraction(sessionId, {
-                type: 'wheel',
-                deltaX: event.deltaX,
-                deltaY: event.deltaY,
-            });
-        },
-        [sessionId],
-    );
-
-    const handleKeyDown = useCallback(
-        (event: KeyboardEvent<HTMLImageElement>) => {
-            if (event.altKey || event.ctrlKey || event.metaKey) {
-                return;
-            }
-
-            const key = normalizeLivePagePreviewKey(event.key);
-            if (!key) {
-                return;
-            }
-
-            event.preventDefault();
-            void postLivePagePreviewInteraction(sessionId, {
-                type: 'keyDown',
-                key,
-            });
-        },
-        [sessionId],
-    );
-
-    return (
-        <div className={styles.citationBrowserPreviewFallback}>
-            <img
-                src={streamSrc}
-                alt={`Live browser preview of ${title}`}
-                className={styles.citationBrowserPreviewImage}
-                onClick={handleClick}
-                onWheel={handleWheel}
-                onKeyDown={handleKeyDown}
-                tabIndex={0}
-            />
-            <a href={src} target="_blank" rel="noopener noreferrer" className={styles.citationBrowserPreviewLink}>
-                Open in new tab ↗
-            </a>
-        </div>
-    );
+function createBrowserPreviewSessionId(): string {
+    const randomId =
+        globalThis.crypto && 'randomUUID' in globalThis.crypto
+            ? globalThis.crypto.randomUUID()
+            : createFallbackBrowserPreviewSessionSuffix();
+
+    return `${BROWSER_PREVIEW_SESSION_ID_PREFIX}${randomId}`.toLowerCase();
 }
 
 /**
- * Creates one browser-preview session id from React's hydration-stable id.
+ * Creates a sufficiently long fallback session suffix when Web Crypto UUIDs are unavailable.
  *
- * @param reactSessionId - React-generated id for the component instance.
- * @returns Session id shared by the stream and interaction endpoints.
+ * @returns Lowercase random suffix.
  */
-function createLivePagePreviewSessionId(reactSessionId: string): string {
-    return `preview-${reactSessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+function createFallbackBrowserPreviewSessionSuffix(): string {
+    let suffix = '';
+
+    while (suffix.length < BROWSER_PREVIEW_RANDOM_SUFFIX_LENGTH) {
+        suffix += Math.random().toString(36).slice(2);
+    }
+
+    return suffix.slice(0, BROWSER_PREVIEW_RANDOM_SUFFIX_LENGTH);
 }
 
 /**
- * Converts one pointer event over the stream image to browser viewport coordinates.
+ * Resolves pointer coordinates as ratios inside the streamed preview image.
  *
- * @param event - Pointer event from the stream image.
- * @returns Browser viewport position or null when the image has no layout box.
+ * @param event - Mouse or wheel event fired inside the live preview image.
+ * @returns Pointer ratio or `null` when the image has no measurable size.
  */
-function resolveLivePagePreviewPointerPosition(
-    event: MouseEvent<HTMLImageElement>,
-): LivePagePreviewPointerPosition | null {
+function resolveBrowserPreviewPointerRatio(
+    event: MouseEvent<HTMLImageElement> | WheelEvent<HTMLImageElement>,
+): BrowserPreviewPointerRatio | null {
     const rect = event.currentTarget.getBoundingClientRect();
     if (rect.width <= 0 || rect.height <= 0) {
         return null;
     }
 
     return {
-        x: ((event.clientX - rect.left) / rect.width) * LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
-        y: ((event.clientY - rect.top) / rect.height) * LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+        xRatio: (event.clientX - rect.left) / rect.width,
+        yRatio: (event.clientY - rect.top) / rect.height,
     };
 }
 
 /**
- * Normalizes one browser keyboard key before forwarding it to Playwright.
+ * Sends one browser-preview interaction to the Agents Server stream session.
  *
- * @param key - Browser KeyboardEvent key.
- * @returns Playwright-compatible key name or null when the key should be ignored.
+ * @param payload - Browser-preview input payload.
  */
-function normalizeLivePagePreviewKey(key: string): string | null {
-    if (!key || LIVE_PAGE_PREVIEW_IGNORED_KEYS.has(key)) {
-        return null;
-    }
-
-    if (key === ' ') {
-        return 'Space';
-    }
-
-    return key;
-}
-
-/**
- * Sends one live-preview interaction to the Agents Server.
- *
- * @param sessionId - Active live-preview session id.
- * @param interaction - Interaction to apply to the browser page.
- */
-async function postLivePagePreviewInteraction(
-    sessionId: string,
-    interaction: LivePagePreviewInteraction,
-): Promise<void> {
-    await fetch('/api/page-preview/interact', {
+function sendBrowserPreviewInput(payload: {
+    readonly sessionId: string;
+    readonly type: 'click' | 'wheel';
+    readonly xRatio: number;
+    readonly yRatio: number;
+    readonly deltaX?: number;
+    readonly deltaY?: number;
+}): void {
+    void fetch('/api/page-preview/input', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            sessionId,
-            ...interaction,
-        }),
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
     }).catch(() => undefined);
 }

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

@@ -14,13 +14,6 @@ const PENDING_PROGRESS_MARKER_HTML = '<span data-chat-progress-marker="pending"
  */
 const COMPLETED_PROGRESS_MARKER_HTML = '<span data-chat-progress-marker="completed" aria-hidden="true"></span>';
 
-/**
- * Human-facing label shown for "now" progress updates.
- *
- * @private internal helper of `<ChatMessageItem/>`
- */
-const PROGRESS_NOW_LABEL = "What I'm Doing Now";
-
 /**
  * Human-facing label shown for "next" progress updates.
  *
@@ -85,7 +78,7 @@ function createProgressCardMarkdownSections(progressCard: NonNullable<ChatMessag
     }
 
     if (normalizedNow) {
-        markdownSections.push(`**${PROGRESS_NOW_LABEL}:** ${normalizedNow}`);
+        markdownSections.push(normalizedNow);
     }
 
     const itemLines: Array<string> = [];

package/src/cli/promptbookCli.ts

@@ -48,6 +48,13 @@ const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES: Readonly<Record<string, string>> =
     'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
 };
 
+/**
+ * Raw top-level CLI arguments that print the Promptbook version.
+ *
+ * @private internal constant of `promptbookCli`
+ */
+const VERSION_OPTION_ARGUMENTS: ReadonlySet<string> = new Set(['-v', '--version']);
+
 /**
  * Runs CLI utilities of Promptbook package
  *
@@ -65,8 +72,15 @@ export async function promptbookCli(): Promise<void> {
         );
     }
 
-    const cliArguments = process.argv.slice(2);
-    const isVerbose = cliArguments.some((arg) => arg === '--verbose' || arg === '-v');
+    const commandLineArguments = process.argv.slice(2);
+    const isVersionRequested = isTopLevelVersionRequested(commandLineArguments);
+
+    if (isVersionRequested) {
+        console.info(PROMPTBOOK_ENGINE_VERSION);
+        return process.exit(0);
+    }
+
+    const isVerbose = commandLineArguments.some((argument) => argument === '--verbose' || argument === '-v');
     //     <- TODO: Can be this be done with commander before the commander commands are initialized?
     if (isVerbose) {
         console.info(
@@ -104,7 +118,7 @@ export async function promptbookCli(): Promise<void> {
     // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
     program.commands.forEach($addGlobalOptionsToCommand);
 
-    if (cliArguments.length === 0) {
+    if (commandLineArguments.length === 0) {
         program.outputHelp();
         return process.exit(0);
     }
@@ -112,6 +126,17 @@ export async function promptbookCli(): Promise<void> {
     program.parse(process.argv);
 }
 
+/**
+ * Checks whether the invocation asks for the root Promptbook CLI version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function isTopLevelVersionRequested(commandLineArguments: ReadonlyArray<string>): boolean {
+    const firstCommandLineArgument = commandLineArguments[0];
+
+    return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
+}
+
 /**
  * Adds one deprecation notice to each configured top-level legacy command.
  */