@promptbook/cli 0.113.0-0 → 0.113.0-1

package/esm/src/book-components/Chat/utils/livePagePreviewConstants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Width of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export declare const LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH = 1280;
+/**
+ * Height of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export declare const LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT = 800;

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.113.0-0",
+    "version": "0.113.0-1",
     "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,23 +3322,32 @@
     font-size: 0.9em;
 }
 
-.citationScreenshotFallback {
+.citationBrowserPreviewFallback {
     width: 100%;
     position: relative;
     display: flex;
     flex-direction: column;
 }
 
-.citationScreenshotImage {
+.citationBrowserPreviewImage {
     width: 100%;
+    aspect-ratio: 16 / 10;
     max-height: 60vh;
     min-height: 400px;
-    object-fit: cover;
+    object-fit: contain;
     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 {
+.citationBrowserPreviewLink {
     display: block;
     text-align: center;
     padding: 10px 16px;
@@ -3351,7 +3360,7 @@
     transition: background 0.15s;
 }
 
-.citationScreenshotLink:hover {
+.citationBrowserPreviewLink:hover {
     background: #e0e0e0;
     text-decoration: underline;
 }

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

@@ -1,6 +1,8 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+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 styles from './Chat.module.css';
 
 /**
@@ -18,12 +20,48 @@ export type CitationIframePreviewProps = {
  *
  * @private type of `<CitationIframePreview/>`
  */
-type EmbedStatus = 'loading' | 'embed' | 'screenshot';
+type EmbedStatus = 'loading' | 'embed' | 'browser';
+
+/**
+ * Browser-preview interaction sent to the Agents Server preview route.
+ *
+ * @private type 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;
+      };
+
+/**
+ * Pointer position translated into the live-preview browser viewport.
+ *
+ * @private type of `<CitationIframePreview/>`
+ */
+type LivePagePreviewPointerPosition = {
+    readonly x: number;
+    readonly y: number;
+};
+
+/**
+ * Keyboard keys that should not be forwarded as standalone browser actions.
+ */
+const LIVE_PAGE_PREVIEW_IGNORED_KEYS = new Set(['Alt', 'CapsLock', 'Control', 'Meta', 'Shift']);
 
 /**
  * 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).
+ * or falls back to a live server-side browser preview 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.
@@ -34,24 +72,24 @@ export function CitationIframePreview({ src, title }: CitationIframePreviewProps
     const [status, setStatus] = useState<EmbedStatus>('loading');
 
     useEffect(() => {
-        let cancelled = false;
+        let isCancelled = false;
 
         fetch(`/api/page-preview/check?url=${encodeURIComponent(src)}`)
             .then((response) => response.json())
             .then((data: { canEmbed: boolean }) => {
-                if (!cancelled) {
-                    setStatus(data.canEmbed ? 'embed' : 'screenshot');
+                if (!isCancelled) {
+                    setStatus(data.canEmbed ? 'embed' : 'browser');
                 }
             })
             .catch(() => {
                 // API not available — fall back to iframe (e.g. outside agents-server)
-                if (!cancelled) {
+                if (!isCancelled) {
                     setStatus('embed');
                 }
             });
 
         return () => {
-            cancelled = true;
+            isCancelled = true;
         };
     }, [src]);
 
@@ -59,20 +97,157 @@ export function CitationIframePreview({ src, title }: CitationIframePreviewProps
         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>
-        );
+    if (status === 'browser') {
+        return <LiveBrowserPreview src={src} title={title} />;
     }
 
     return <iframe src={src} className={styles.citationIframe} title={title} />;
 }
+
+/**
+ * Renders and controls a streamed browser preview for non-embeddable citation URLs.
+ *
+ * @private component of `<CitationIframePreview/>`
+ */
+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>
+    );
+}
+
+/**
+ * Creates one browser-preview session id from React's hydration-stable id.
+ *
+ * @param reactSessionId - React-generated id for the component instance.
+ * @returns Session id shared by the stream and interaction endpoints.
+ */
+function createLivePagePreviewSessionId(reactSessionId: string): string {
+    return `preview-${reactSessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+}
+
+/**
+ * Converts one pointer event over the stream image to browser viewport coordinates.
+ *
+ * @param event - Pointer event from the stream image.
+ * @returns Browser viewport position or null when the image has no layout box.
+ */
+function resolveLivePagePreviewPointerPosition(
+    event: MouseEvent<HTMLImageElement>,
+): LivePagePreviewPointerPosition | 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,
+    };
+}
+
+/**
+ * Normalizes one browser keyboard key before forwarding it to Playwright.
+ *
+ * @param key - Browser KeyboardEvent key.
+ * @returns Playwright-compatible key name or null when the key should be ignored.
+ */
+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', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            sessionId,
+            ...interaction,
+        }),
+    }).catch(() => undefined);
+}

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

@@ -0,0 +1,17 @@
+/* eslint-disable no-magic-numbers */
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
+/**
+ * Width of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export const LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH = 1280;
+
+/**
+ * Height of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export const LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT = 800;