@promptbook/cli 0.113.0-1 → 0.113.0-3

package/umd/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/umd/src/book-components/Chat/Chat/CitationIframePreview.test.d.ts

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

package/umd/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/apps/agents-server/src/app/api/page-preview/interact/route.ts

@@ -1,179 +0,0 @@
-import { serializeError } from '@promptbook-local/utils';
-import type { NextRequest } from 'next/server';
-import { NextResponse } from 'next/server';
-import { assertsError } from '../../../../../../../src/errors/assertsError';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
-import {
-    applyLivePagePreviewInteraction,
-    isLivePagePreviewSessionId,
-    type LivePagePreviewInteraction,
-} from '../../../../utils/pagePreview/livePagePreviewSessions';
-
-/**
- * Maximum wheel delta accepted from one live-preview UI event.
- */
-const MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA = 4_000;
-
-/**
- * Maximum keyboard key name length accepted from one live-preview UI event.
- */
-const MAX_LIVE_PAGE_PREVIEW_KEY_LENGTH = 40;
-
-/**
- * Parsed live-preview interaction request body.
- */
-type ParsedLivePagePreviewInteractionRequest = {
-    readonly sessionId: string;
-    readonly interaction: LivePagePreviewInteraction;
-};
-
-/**
- * Constant for dynamic route rendering.
- */
-export const dynamic = 'force-dynamic';
-
-/**
- * Applies one UI interaction to an active live browser preview.
- *
- * Requires authentication because interaction targets are opened by the authenticated preview route.
- */
-export async function POST(request: NextRequest): Promise<NextResponse> {
-    const currentUser = await getCurrentUser();
-    if (!currentUser) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    const parsedRequest = await parseLivePagePreviewInteractionRequest(request);
-    if (!parsedRequest) {
-        return NextResponse.json({ error: 'Invalid live preview interaction request.' }, { status: 400 });
-    }
-
-    try {
-        const isApplied = await applyLivePagePreviewInteraction(parsedRequest);
-        if (!isApplied) {
-            return NextResponse.json({ error: 'Live preview session not found.' }, { status: 404 });
-        }
-
-        return NextResponse.json({ ok: true });
-    } catch (error) {
-        assertsError(error);
-        console.error('Error applying live page preview interaction:', error);
-        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
-    }
-}
-
-/**
- * Parses and validates a live-preview interaction request.
- *
- * @param request - Incoming interaction request.
- * @returns Parsed request or null when the payload is invalid.
- */
-async function parseLivePagePreviewInteractionRequest(
-    request: NextRequest,
-): Promise<ParsedLivePagePreviewInteractionRequest | null> {
-    let body: unknown;
-
-    try {
-        body = await request.json();
-    } catch {
-        return null;
-    }
-
-    if (!isRecord(body)) {
-        return null;
-    }
-
-    const sessionId = typeof body.sessionId === 'string' ? body.sessionId : null;
-    if (!sessionId || !isLivePagePreviewSessionId(sessionId)) {
-        return null;
-    }
-
-    const interaction = parseLivePagePreviewInteraction(body);
-    if (!interaction) {
-        return null;
-    }
-
-    return {
-        sessionId,
-        interaction,
-    };
-}
-
-/**
- * Parses one normalized live-preview interaction from an object payload.
- *
- * @param body - Request body record.
- * @returns Interaction payload or null when invalid.
- */
-function parseLivePagePreviewInteraction(body: Record<string, unknown>): LivePagePreviewInteraction | null {
-    if (body.type === 'click') {
-        const x = readFiniteNumber(body.x);
-        const y = readFiniteNumber(body.y);
-
-        if (x === null || y === null) {
-            return null;
-        }
-
-        return { type: 'click', x, y };
-    }
-
-    if (body.type === 'wheel') {
-        const deltaX = readFiniteNumber(body.deltaX);
-        const deltaY = readFiniteNumber(body.deltaY);
-
-        if (deltaX === null || deltaY === null) {
-            return null;
-        }
-
-        return {
-            type: 'wheel',
-            deltaX: clampWheelDelta(deltaX),
-            deltaY: clampWheelDelta(deltaY),
-        };
-    }
-
-    if (body.type === 'keyDown') {
-        const key = typeof body.key === 'string' ? body.key : null;
-        if (!key || key.length > MAX_LIVE_PAGE_PREVIEW_KEY_LENGTH) {
-            return null;
-        }
-
-        return { type: 'keyDown', key };
-    }
-
-    return null;
-}
-
-/**
- * Checks whether a value is a plain object record.
- *
- * @param value - Candidate value.
- * @returns True when the value can be read as a JSON object.
- */
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Reads one finite number from a JSON value.
- *
- * @param value - Candidate JSON value.
- * @returns Number or null when invalid.
- */
-function readFiniteNumber(value: unknown): number | null {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return null;
-    }
-
-    return value;
-}
-
-/**
- * Clamps one wheel delta to a bounded value.
- *
- * @param value - Raw wheel delta.
- * @returns Delta safe to forward to Playwright.
- */
-function clampWheelDelta(value: number): number {
-    return Math.min(Math.max(value, -MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA), MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA);
-}

package/apps/agents-server/src/app/api/page-preview/live/route.ts

@@ -1,67 +0,0 @@
-import { serializeError } from '@promptbook-local/utils';
-import type { NextRequest } from 'next/server';
-import { NextResponse } from 'next/server';
-import { assertsError } from '../../../../../../../src/errors/assertsError';
-import {
-    createLivePagePreviewStream,
-    getOrCreateLivePagePreviewSession,
-    isLivePagePreviewSessionId,
-    LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE,
-} from '../../../../utils/pagePreview/livePagePreviewSessions';
-import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
-
-/**
- * Query parameter containing the browser-side live preview session id.
- */
-const LIVE_PAGE_PREVIEW_SESSION_ID_QUERY_PARAMETER = 'sessionId';
-
-/**
- * Constant for dynamic route rendering.
- */
-export const dynamic = 'force-dynamic';
-
-/**
- * Streams a live browser preview for a knowledge source URL.
- *
- * Query parameters:
- * - `url` — fully-qualified HTTP(S) URL to preview
- * - `sessionId` — client-generated id used for forwarding interactions
- *
- * Requires authentication to prevent unauthenticated SSRF abuse.
- */
-export async function GET(request: NextRequest): Promise<NextResponse> {
-    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
-    if (requestUrlResolution.errorResponse !== null) {
-        return requestUrlResolution.errorResponse;
-    }
-
-    const sessionId = request.nextUrl.searchParams.get(LIVE_PAGE_PREVIEW_SESSION_ID_QUERY_PARAMETER);
-    if (!sessionId || !isLivePagePreviewSessionId(sessionId)) {
-        return NextResponse.json({ error: 'Missing or invalid live preview session id.' }, { status: 400 });
-    }
-
-    try {
-        const page = await getOrCreateLivePagePreviewSession({
-            sessionId,
-            url: requestUrlResolution.url,
-            signal: request.signal,
-        });
-        const stream = createLivePagePreviewStream({
-            sessionId,
-            page,
-            signal: request.signal,
-        });
-
-        return new NextResponse(stream, {
-            headers: {
-                'Content-Type': LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE,
-                'Cache-Control': 'no-cache, no-store, max-age=0',
-                Connection: 'keep-alive',
-            },
-        });
-    } catch (error) {
-        assertsError(error);
-        console.error('Error streaming live page preview:', error);
-        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
-    }
-}

package/apps/agents-server/src/utils/pagePreview/livePagePreviewSessions.ts

@@ -1,365 +0,0 @@
-import type { Page } from 'playwright';
-import { spaceTrim } from 'spacetrim';
-import {
-    LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
-    LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
-} from '../../../../../src/book-components/Chat/utils/livePagePreviewConstants';
-import { KnowledgeScrapeError } from '../../../../../src/errors/KnowledgeScrapeError';
-import { $provideBrowserForServer } from '../../tools/$provideBrowserForServer';
-
-/**
- * Pattern for live-preview session identifiers created by the browser client.
- */
-const LIVE_PAGE_PREVIEW_SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;
-
-/**
- * Navigation timeout for opening a live knowledge preview page.
- */
-const LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS = 30_000;
-
-/**
- * Playwright action timeout for live-preview interactions.
- */
-const LIVE_PAGE_PREVIEW_ACTION_TIMEOUT_MS = 5_000;
-
-/**
- * Idle session lifetime before a stale live-preview page is closed.
- */
-const LIVE_PAGE_PREVIEW_SESSION_IDLE_TIMEOUT_MS = 60_000;
-
-/**
- * Multipart response boundary used by the live-preview image stream.
- */
-const LIVE_PAGE_PREVIEW_STREAM_BOUNDARY = 'page-preview-frame';
-
-/**
- * Delay between live-preview browser frames.
- */
-const LIVE_PAGE_PREVIEW_FRAME_INTERVAL_MS = 500;
-
-/**
- * JPEG quality for live-preview browser frames.
- */
-const LIVE_PAGE_PREVIEW_JPEG_QUALITY = 65;
-
-/**
- * Browser page stored for a live knowledge preview session.
- */
-type LivePagePreviewSession = {
-    readonly page: Page;
-    readonly url: string;
-    lastAccessedAt: number;
-};
-
-/**
- * Pointer interaction sent from the live preview image to the browser page.
- */
-type LivePagePreviewClickInteraction = {
-    readonly type: 'click';
-    readonly x: number;
-    readonly y: number;
-};
-
-/**
- * Wheel interaction sent from the live preview image to the browser page.
- */
-type LivePagePreviewWheelInteraction = {
-    readonly type: 'wheel';
-    readonly deltaX: number;
-    readonly deltaY: number;
-};
-
-/**
- * Keyboard interaction sent from the live preview image to the browser page.
- */
-type LivePagePreviewKeyDownInteraction = {
-    readonly type: 'keyDown';
-    readonly key: string;
-};
-
-/**
- * Supported interaction payload for a live knowledge preview session.
- */
-export type LivePagePreviewInteraction =
-    | LivePagePreviewClickInteraction
-    | LivePagePreviewWheelInteraction
-    | LivePagePreviewKeyDownInteraction;
-
-/**
- * Active browser pages for live knowledge previews.
- */
-const LIVE_PAGE_PREVIEW_SESSIONS = new Map<string, LivePagePreviewSession>();
-
-/**
- * Content type for the live-preview multipart image stream.
- */
-export const LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE = `multipart/x-mixed-replace; boundary=${LIVE_PAGE_PREVIEW_STREAM_BOUNDARY}`;
-
-/**
- * Checks whether a live-preview session identifier is safe to use as a map key.
- *
- * @param sessionId - Candidate session identifier.
- * @returns True when the value is a valid live-preview session id.
- */
-export function isLivePagePreviewSessionId(sessionId: string): boolean {
-    return LIVE_PAGE_PREVIEW_SESSION_ID_PATTERN.test(sessionId);
-}
-
-/**
- * Opens or reuses the browser page for one live knowledge preview.
- *
- * @param options - Session, target URL, and request cancellation signal.
- * @returns Playwright page backing the live preview.
- */
-export async function getOrCreateLivePagePreviewSession(options: {
-    readonly sessionId: string;
-    readonly url: string;
-    readonly signal: AbortSignal;
-}): Promise<Page> {
-    pruneExpiredLivePagePreviewSessions();
-
-    const existingSession = LIVE_PAGE_PREVIEW_SESSIONS.get(options.sessionId);
-    if (existingSession && existingSession.url === options.url && !existingSession.page.isClosed()) {
-        existingSession.lastAccessedAt = Date.now();
-        return existingSession.page;
-    }
-
-    if (existingSession) {
-        await closeLivePagePreviewSession(options.sessionId);
-    }
-
-    const browserContext = await $provideBrowserForServer({
-        signal: options.signal,
-        sessionId: options.sessionId,
-    });
-    const page = await browserContext.newPage();
-
-    try {
-        page.setDefaultNavigationTimeout(LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS);
-        page.setDefaultTimeout(LIVE_PAGE_PREVIEW_ACTION_TIMEOUT_MS);
-        await page.setViewportSize({
-            width: LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
-            height: LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
-        });
-        await page.goto(options.url, {
-            waitUntil: 'domcontentloaded',
-            timeout: LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS,
-        });
-    } catch {
-        await closeLivePagePreviewPage(page);
-        throw new KnowledgeScrapeError(
-            spaceTrim(`
-                Failed to open live knowledge preview for \`${options.url}\`.
-
-                The browser session could not navigate to the requested source.
-            `),
-        );
-    }
-
-    LIVE_PAGE_PREVIEW_SESSIONS.set(options.sessionId, {
-        page,
-        url: options.url,
-        lastAccessedAt: Date.now(),
-    });
-
-    return page;
-}
-
-/**
- * Closes one live knowledge preview session if it exists.
- *
- * @param sessionId - Live-preview session identifier.
- */
-export async function closeLivePagePreviewSession(sessionId: string): Promise<void> {
-    const existingSession = LIVE_PAGE_PREVIEW_SESSIONS.get(sessionId);
-    if (!existingSession) {
-        return;
-    }
-
-    LIVE_PAGE_PREVIEW_SESSIONS.delete(sessionId);
-    await closeLivePagePreviewPage(existingSession.page);
-}
-
-/**
- * Creates an MJPEG stream from an active live-preview browser page.
- *
- * @param options - Session identifier, browser page, and request cancellation signal.
- * @returns Readable stream that emits JPEG browser frames until the client disconnects.
- */
-export function createLivePagePreviewStream(options: {
-    readonly sessionId: string;
-    readonly page: Page;
-    readonly signal: AbortSignal;
-}): ReadableStream<Uint8Array> {
-    const encoder = new TextEncoder();
-    let isStreamClosed = false;
-    let isSessionClosed = false;
-
-    const closeSessionOnce = async (): Promise<void> => {
-        if (isSessionClosed) {
-            return;
-        }
-
-        isSessionClosed = true;
-        await closeLivePagePreviewSession(options.sessionId);
-    };
-
-    return new ReadableStream<Uint8Array>({
-        async start(controller) {
-            const handleAbort = (): void => {
-                isStreamClosed = true;
-                void closeSessionOnce();
-            };
-
-            options.signal.addEventListener('abort', handleAbort, { once: true });
-
-            try {
-                while (!isStreamClosed && !options.signal.aborted && !options.page.isClosed()) {
-                    const buffer = await options.page.screenshot({
-                        type: 'jpeg',
-                        quality: LIVE_PAGE_PREVIEW_JPEG_QUALITY,
-                    });
-
-                    if (isStreamClosed || options.signal.aborted || options.page.isClosed()) {
-                        break;
-                    }
-
-                    const header = [
-                        '',
-                        `--${LIVE_PAGE_PREVIEW_STREAM_BOUNDARY}`,
-                        'Content-Type: image/jpeg',
-                        `Content-Length: ${buffer.length}`,
-                        '',
-                        '',
-                    ].join('\r\n');
-
-                    controller.enqueue(encoder.encode(header));
-                    controller.enqueue(buffer);
-
-                    await waitForLivePagePreviewFrame(options.signal);
-                }
-            } catch (error) {
-                if (!isStreamClosed && !options.signal.aborted) {
-                    console.error('Error streaming live page preview:', error);
-                }
-            } finally {
-                isStreamClosed = true;
-                options.signal.removeEventListener('abort', handleAbort);
-                await closeSessionOnce();
-
-                try {
-                    controller.close();
-                } catch {
-                    // The client can disconnect before the server closes the stream.
-                }
-            }
-        },
-        async cancel() {
-            isStreamClosed = true;
-            await closeSessionOnce();
-        },
-    });
-}
-
-/**
- * Applies one browser interaction to an active live preview session.
- *
- * @param options - Session identifier and normalized interaction.
- * @returns True when the interaction was applied to an active session.
- */
-export async function applyLivePagePreviewInteraction(options: {
-    readonly sessionId: string;
-    readonly interaction: LivePagePreviewInteraction;
-}): Promise<boolean> {
-    const session = LIVE_PAGE_PREVIEW_SESSIONS.get(options.sessionId);
-    if (!session || session.page.isClosed()) {
-        LIVE_PAGE_PREVIEW_SESSIONS.delete(options.sessionId);
-        return false;
-    }
-
-    session.lastAccessedAt = Date.now();
-
-    switch (options.interaction.type) {
-        case 'click':
-            await session.page.mouse.click(
-                clampLivePagePreviewCoordinate(options.interaction.x, LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH),
-                clampLivePagePreviewCoordinate(options.interaction.y, LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT),
-            );
-            return true;
-
-        case 'wheel':
-            await session.page.mouse.wheel(options.interaction.deltaX, options.interaction.deltaY);
-            return true;
-
-        case 'keyDown':
-            await session.page.keyboard.press(options.interaction.key);
-            return true;
-    }
-}
-
-/**
- * Removes stale live-preview sessions left behind by disconnected clients.
- */
-function pruneExpiredLivePagePreviewSessions(): void {
-    const now = Date.now();
-    for (const [sessionId, session] of LIVE_PAGE_PREVIEW_SESSIONS) {
-        const isExpired = now - session.lastAccessedAt > LIVE_PAGE_PREVIEW_SESSION_IDLE_TIMEOUT_MS;
-        if (isExpired || session.page.isClosed()) {
-            LIVE_PAGE_PREVIEW_SESSIONS.delete(sessionId);
-            void closeLivePagePreviewPage(session.page);
-        }
-    }
-}
-
-/**
- * Waits between streamed browser frames, resolving early when the request is aborted.
- *
- * @param signal - Request cancellation signal.
- */
-async function waitForLivePagePreviewFrame(signal: AbortSignal): Promise<void> {
-    if (signal.aborted) {
-        return;
-    }
-
-    await new Promise<void>((resolve) => {
-        const timeout = setTimeout(() => {
-            signal.removeEventListener('abort', handleAbort);
-            resolve();
-        }, LIVE_PAGE_PREVIEW_FRAME_INTERVAL_MS);
-
-        function handleAbort(): void {
-            clearTimeout(timeout);
-            resolve();
-        }
-
-        signal.addEventListener('abort', handleAbort, { once: true });
-    });
-}
-
-/**
- * Closes a Playwright page while ignoring cleanup errors.
- *
- * @param page - Browser page to close.
- */
-async function closeLivePagePreviewPage(page: Page): Promise<void> {
-    if (page.isClosed()) {
-        return;
-    }
-
-    await page.close().catch(() => undefined);
-}
-
-/**
- * Clamps a pointer coordinate to the configured live-preview viewport.
- *
- * @param value - Raw coordinate from the web UI.
- * @param maximum - Maximum coordinate value for one axis.
- * @returns Coordinate safe to pass into Playwright.
- */
-function clampLivePagePreviewCoordinate(value: number, maximum: number): number {
-    if (!Number.isFinite(value)) {
-        return 0;
-    }
-
-    return Math.min(Math.max(value, 0), maximum);
-}

package/apps/agents-server/src/utils/pagePreview/resolvePagePreviewRequestUrl.ts

@@ -1,74 +0,0 @@
-import type { NextRequest } from 'next/server';
-import { NextResponse } from 'next/server';
-import { assertsError } from '../../../../../src/errors/assertsError';
-import { assertSafeUrl } from '../assertSafeUrl';
-import { getCurrentUser } from '../getCurrentUser';
-
-/**
- * Query parameter used by page-preview API endpoints.
- */
-const PAGE_PREVIEW_URL_QUERY_PARAMETER = 'url';
-
-/**
- * Successful page-preview request URL resolution.
- */
-type PagePreviewRequestUrlSuccess = {
-    readonly url: string;
-    readonly errorResponse: null;
-};
-
-/**
- * Failed page-preview request URL resolution.
- */
-type PagePreviewRequestUrlFailure = {
-    readonly url: null;
-    readonly errorResponse: NextResponse;
-};
-
-/**
- * Result of authenticating and validating a page-preview request URL.
- */
-export type PagePreviewRequestUrlResolution = PagePreviewRequestUrlSuccess | PagePreviewRequestUrlFailure;
-
-/**
- * Authenticates a page-preview request and validates its target URL against SSRF-sensitive destinations.
- *
- * @param request - Incoming Next.js request.
- * @returns Valid target URL or a ready-made error response.
- */
-export async function resolvePagePreviewRequestUrl(request: NextRequest): Promise<PagePreviewRequestUrlResolution> {
-    const currentUser = await getCurrentUser();
-    if (!currentUser) {
-        return {
-            url: null,
-            errorResponse: NextResponse.json({ error: 'Unauthorized' }, { status: 401 }),
-        };
-    }
-
-    const url = request.nextUrl.searchParams.get(PAGE_PREVIEW_URL_QUERY_PARAMETER);
-
-    if (!url) {
-        return {
-            url: null,
-            errorResponse: NextResponse.json(
-                { error: `Missing required query parameter: ${PAGE_PREVIEW_URL_QUERY_PARAMETER}` },
-                { status: 400 },
-            ),
-        };
-    }
-
-    try {
-        assertSafeUrl(url);
-    } catch (error) {
-        assertsError(error);
-        return {
-            url: null,
-            errorResponse: NextResponse.json({ error: error.message }, { status: 400 }),
-        };
-    }
-
-    return {
-        url,
-        errorResponse: null,
-    };
-}