@promptbook/cli 0.113.0-1 → 0.113.0-3

package/README.md

@@ -23,13 +23,7 @@ Create persistent AI agents that turn your company's scattered knowledge into ac
 
 
 
-[![Vercel](https://img.shields.io/badge/Vercel-Deploy%20Agents%20Server-black?logo=vercel)](https://vercel.com/new/clone?project-name=promptbook-agents-server&repository-name=promptbook-agents-server&repository-url=https%3A%2F%2Fgithub.com%2Fwebgptorg%2Fpromptbook&root-directory=apps%2Fagents-server&demo-title=Promptbook+Agents+Server&demo-description=Persistent+AI+agents+with+a+built-in+admin+UI.+This+deploy+creates+a+Supabase+project+automatically%2C+injects+the+required+database+credentials%2C+and+Promptbook+runs+the+SQL+migrations+on+first+startup.&demo-url=https%3A%2F%2Fgallery.ptbk.io%2F&external-id=https%3A%2F%2Fgithub.com%2Fwebgptorg%2Fpromptbook%2Ftree%2Fmain%2Fapps%2Fagents-server&env=OPENAI_API_KEY%2CADMIN_PASSWORD%2CSUPABASE_AUTO_MIGRATE&envDescription=Supabase+is+created+automatically+by+the+required+Vercel+integration.+Add+OPENAI_API_KEY+from+https%3A%2F%2Fplatform.openai.com%2Fapi-keys%2C+choose+ADMIN_PASSWORD+for+your+first+admin+login%2C+and+leave+SUPABASE_AUTO_MIGRATE+enabled.&envLink=https%3A%2F%2Fgithub.com%2Fwebgptorg%2Fpromptbook%2Fblob%2Fmain%2FREADME.md%23vercel-form-fields&envDefaults=%7B%22SUPABASE_AUTO_MIGRATE%22%3A%22true%22%7D&stores=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22supabase%22%2C%22productSlug%22%3A%22supabase%22%7D%5D)
-
-
-
-### Standalone VPS
-
-Run the standalone VPS installer only on a fresh server. Interactive mode asks for the installation values:
+Run the standalone VPS installer _(for example on DigitalOcean)_ only on a fresh server. Interactive mode asks for the installation values:
 
 ```bash
 sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash
@@ -357,8 +351,6 @@ TEAM You are part of the legal team of Paul Smith & Associés, you discuss with
 
 </td></tr></table>
 
-
-
 ### Promptbook Ecosystem
 
 Promptbook is an ecosystem of tools centered around the **Agents Server** - a production-ready platform for running persistent AI agents.
@@ -381,8 +373,6 @@ The [Promptbook Engine](https://github.com/webgptorg/promptbook) is the open-sou
 
 
 
-
-
 ## 💜 The Promptbook Project
 
 Promptbook project is an ecosystem centered around the **Agents Server** - a platform for creating, deploying, and running persistent AI agents. Following is a list of the most important pieces of the project:
@@ -420,8 +410,6 @@ Promptbook project is an ecosystem centered around the **Agents Server** - a pla
   </tbody>
 </table>
 
-
-
 ### 🌐 Community & Social Media
 
 Join our growing community of developers and users:
@@ -478,8 +466,6 @@ Join our growing community of developers and users:
 
 
 
-
-
 ## 📚 Documentation
 
 See detailed guides and API reference in the [docs](https://github.com/webgptorg/promptbook/discussions/categories/concepts) or [online](https://discord.gg/x3QWNaa89N).
@@ -687,8 +673,6 @@ The following glossary is used to clarify certain concepts:
 
 _Note: This section is not a complete dictionary, more list of general AI / LLM terms that has connection with Promptbook_
 
-
-
 ### 💯 Core concepts
 
 -   [📚 Collection of pipelines](https://github.com/webgptorg/promptbook/discussions/65)

package/agents/default/developer.book

@@ -1,4 +1,7 @@
 Developer
+
+
+
 META VISIBILITY PRIVATE
 
 RULE

package/apps/agents-server/src/app/admin/task-manager/TaskManagerClient.tsx

@@ -22,9 +22,9 @@ export function TaskManagerClient() {
                 <div>
                     <h1 className="text-3xl font-light text-gray-900">Task manager</h1>
                     <p className="mt-1 max-w-3xl text-sm text-gray-500">
-                        Admin-only operational view of durable background chat work across all users, including chat
-                        completions and scheduled timeout wake-ups. This dashboard shows queue and worker state, not
-                        chat transcript content.
+                        Admin-only operational view of background work across all users, including chat completions,
+                        scheduled timeout wake-ups, self-updates, and live browser previews. This dashboard shows queue
+                        and worker state, not chat transcript content.
                     </p>
                 </div>
                 <div className="flex flex-wrap items-center gap-2 text-xs text-gray-500">

package/apps/agents-server/src/app/admin/task-manager/TaskManagerTaskRow.tsx

@@ -134,6 +134,10 @@ function formatTaskKind(kind: AdminChatTaskRecord['kind']): string {
         return 'Self-update';
     }
 
+    if (kind === 'BROWSER_PREVIEW') {
+        return 'Browser preview';
+    }
+
     return kind;
 }
 

package/apps/agents-server/src/app/admin/task-manager/TaskManagerTasksCard.tsx

@@ -20,13 +20,13 @@ type TaskManagerTasksCardProps = {
  */
 function resolveEmptyStateMessage(view: ReturnType<typeof useTaskManagerState>['view'], search: string): string {
     if (search) {
-        return 'No background chat tasks matched the current search.';
+        return 'No background tasks matched the current search.';
     }
     if (view === 'running') {
-        return 'No running background chat tasks right now.';
+        return 'No running background tasks right now.';
     }
     if (view === 'queued') {
-        return 'No queued background chat tasks right now.';
+        return 'No queued background tasks right now.';
     }
     if (view === 'failed') {
         return 'No failed background chat tasks were recorded in the last 24 hours.';
@@ -35,7 +35,7 @@ function resolveEmptyStateMessage(view: ReturnType<typeof useTaskManagerState>['
         return 'No background chat tasks matched the selected time window.';
     }
 
-    return 'No active background chat tasks right now.';
+    return 'No active background tasks right now.';
 }
 
 /**
@@ -51,7 +51,7 @@ export function TaskManagerTasksCard({ language, state }: TaskManagerTasksCardPr
         <Card className="hover:border-gray-200 hover:shadow-md">
             <div className="flex items-center justify-between gap-4">
                 <div>
-                    <h2 className="text-lg font-medium text-gray-900">Background chat tasks ({state.total.toLocaleString()})</h2>
+                    <h2 className="text-lg font-medium text-gray-900">Background tasks ({state.total.toLocaleString()})</h2>
                     <p className="mt-1 text-sm text-gray-500">
                         Sorted by started time for running work and creation time for queued work.
                     </p>

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

@@ -1,8 +1,9 @@
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
 import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
-import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
 
 /**
  * Checks whether a given URL can be embedded in an iframe by inspecting
@@ -17,13 +18,27 @@ import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/reso
  * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
-    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
-    if (requestUrlResolution.errorResponse !== null) {
-        return requestUrlResolution.errorResponse;
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
     }
 
     try {
-        const canEmbed = await checkIfUrlCanBeEmbedded(requestUrlResolution.url);
+        const canEmbed = await checkIfUrlCanBeEmbedded(url);
         return NextResponse.json({ canEmbed });
     } catch (error) {
         assertsError(error);

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

@@ -0,0 +1,161 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import {
+    findUserPagePreviewBrowserSession,
+    normalizePagePreviewBrowserSessionId,
+} from '../../../../utils/pagePreviewBrowserSessions';
+
+/**
+ * Maximum absolute wheel delta accepted from one preview input event.
+ *
+ * @private route constant of `/api/page-preview/input`
+ */
+const MAX_WHEEL_DELTA = 1600;
+
+/**
+ * Payload accepted by the live page-preview input route.
+ *
+ * @private route type of `/api/page-preview/input`
+ */
+type PagePreviewInputPayload = {
+    readonly sessionId?: unknown;
+    readonly type?: unknown;
+    readonly xRatio?: unknown;
+    readonly yRatio?: unknown;
+    readonly deltaX?: unknown;
+    readonly deltaY?: unknown;
+};
+
+/**
+ * Normalized browser input event.
+ *
+ * @private route type of `/api/page-preview/input`
+ */
+type PagePreviewInputEvent =
+    | {
+          readonly sessionId: string;
+          readonly type: 'click';
+          readonly xRatio: number;
+          readonly yRatio: number;
+      }
+    | {
+          readonly sessionId: string;
+          readonly type: 'wheel';
+          readonly xRatio: number;
+          readonly yRatio: number;
+          readonly deltaX: number;
+          readonly deltaY: number;
+      };
+
+/**
+ * Applies one pointer or wheel event to an active live browser preview session.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const payload = (await request.json().catch(() => null)) as PagePreviewInputPayload | null;
+    const inputEvent = normalizePagePreviewInputEvent(payload);
+    if (!inputEvent) {
+        return NextResponse.json({ error: 'Invalid browser preview input.' }, { status: 400 });
+    }
+
+    const session = findUserPagePreviewBrowserSession(inputEvent.sessionId, currentUser);
+    if (!session?.page || !session.viewport) {
+        return NextResponse.json({ error: 'Browser preview session is not active.' }, { status: 404 });
+    }
+
+    const x = inputEvent.xRatio * session.viewport.width;
+    const y = inputEvent.yRatio * session.viewport.height;
+
+    if (inputEvent.type === 'click') {
+        await session.page.mouse.click(x, y);
+    } else {
+        await session.page.mouse.move(x, y);
+        await session.page.mouse.wheel(inputEvent.deltaX, inputEvent.deltaY);
+    }
+
+    return NextResponse.json({ ok: true });
+}
+
+/**
+ * Normalizes and validates one browser-preview input payload.
+ *
+ * @param payload - Unknown JSON payload.
+ * @returns Normalized input event or `null` when invalid.
+ */
+function normalizePagePreviewInputEvent(payload: PagePreviewInputPayload | null): PagePreviewInputEvent | null {
+    if (!payload) {
+        return null;
+    }
+
+    const sessionId = normalizePagePreviewBrowserSessionId(
+        typeof payload.sessionId === 'string' ? payload.sessionId : null,
+    );
+    const xRatio = normalizeRatio(payload.xRatio);
+    const yRatio = normalizeRatio(payload.yRatio);
+
+    if (!sessionId || xRatio === null || yRatio === null) {
+        return null;
+    }
+
+    if (payload.type === 'click') {
+        return {
+            sessionId,
+            type: 'click',
+            xRatio,
+            yRatio,
+        };
+    }
+
+    if (payload.type !== 'wheel') {
+        return null;
+    }
+
+    const deltaX = normalizeWheelDelta(payload.deltaX);
+    const deltaY = normalizeWheelDelta(payload.deltaY);
+    if (deltaX === null || deltaY === null) {
+        return null;
+    }
+
+    return {
+        sessionId,
+        type: 'wheel',
+        xRatio,
+        yRatio,
+        deltaX,
+        deltaY,
+    };
+}
+
+/**
+ * Normalizes a pointer coordinate ratio.
+ *
+ * @param value - Unknown payload value.
+ * @returns Ratio clamped to the viewport bounds, 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(-MAX_WHEEL_DELTA, Math.min(MAX_WHEEL_DELTA, value));
+}
+

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

@@ -2,12 +2,9 @@ import { $provideBrowserForServer } from '@/src/tools/$provideBrowserForServer';
 import { serializeError } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
-import {
-    LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
-    LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
-} from '../../../../../../../src/book-components/Chat/utils/livePagePreviewConstants';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
-import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
 
 /**
  * Takes a screenshot of the given URL using a headless browser.
@@ -21,9 +18,23 @@ import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/reso
  * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
-    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
-    if (requestUrlResolution.errorResponse !== null) {
-        return requestUrlResolution.errorResponse;
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
     }
 
     try {
@@ -31,11 +42,8 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         const page = await browserContext.newPage();
 
         try {
-            await page.setViewportSize({
-                width: LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
-                height: LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
-            });
-            await page.goto(requestUrlResolution.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            await page.setViewportSize({ width: 1280, height: 800 });
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
             const screenshotBuffer = await page.screenshot({ type: 'png' });
 
             // eslint-disable-next-line @typescript-eslint/no-explicit-any

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

@@ -0,0 +1,81 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import {
+    createPagePreviewBrowserStream,
+    PAGE_PREVIEW_STREAM_CONTENT_TYPE,
+} from '../../../../utils/createPagePreviewBrowserStream';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import {
+    normalizePagePreviewBrowserSessionId,
+    registerPagePreviewBrowserSession,
+} from '../../../../utils/pagePreviewBrowserSessions';
+
+/**
+ * Forces this route to stream a fresh live browser session for every request.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Streams a live browser preview of a public URL.
+ *
+ * Query parameters:
+ * - `url` — fully-qualified public HTTP(S) URL to preview
+ * - `sessionId` — client-created browser-preview session id used for interaction events
+ *
+ * Requires authentication to prevent unauthenticated SSRF and browser-process abuse.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const url = request.nextUrl.searchParams.get('url');
+    const sessionId = normalizePagePreviewBrowserSessionId(request.nextUrl.searchParams.get('sessionId'));
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    if (!sessionId) {
+        return NextResponse.json({ error: 'Missing or invalid query parameter: sessionId' }, { status: 400 });
+    }
+
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
+    try {
+        registerPagePreviewBrowserSession({
+            sessionId,
+            url,
+            user: currentUser,
+        });
+
+        const stream = createPagePreviewBrowserStream({
+            request,
+            sessionId,
+            url,
+        });
+
+        return new NextResponse(stream, {
+            headers: {
+                'Content-Type': PAGE_PREVIEW_STREAM_CONTENT_TYPE,
+                'Cache-Control': 'no-cache, no-store, max-age=0, must-revalidate',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no',
+            },
+        });
+    } catch (error) {
+        assertsError(error);
+        console.error('[page-preview] failed to start live browser stream', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}
+

package/apps/agents-server/src/components/Header/HeaderHomepageLink.tsx

@@ -31,7 +31,7 @@ export function HeaderHomepageLink({
     onClick,
 }: HeaderHomepageLinkProps) {
     const compactServerName = serverName.split(' ')[0] || serverName;
-    const mergedLogoClassName = `h-6 w-6 shrink-0 object-contain sm:h-8 sm:w-8 ${logoClassName}`.trim();
+    const mergedLogoClassName = `h-6 w-6 shrink-0 object-contain sm:h-6 sm:w-6 ${logoClassName}`.trim();
     const mergedLabelClassName =
         `min-w-0 truncate text-base font-bold tracking-tight text-gray-900 dark:text-slate-100 ${labelClassName}`.trim();
 

package/apps/agents-server/src/utils/chatTasksAdmin.ts

@@ -11,10 +11,11 @@ export type AdminChatTaskView = 'active' | 'running' | 'queued' | 'failed' | 'al
  * Durable task kinds currently surfaced by the admin task manager.
  *
  * `VPS_SELF_UPDATE` represents the standalone VPS self-update session triggered from `/admin/update`.
+ * `BROWSER_PREVIEW` represents an ephemeral live browser stream used by citation previews.
  *
  * @private internal admin utility of Agents Server
  */
-export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT' | 'VPS_SELF_UPDATE';
+export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT' | 'VPS_SELF_UPDATE' | 'BROWSER_PREVIEW';
 
 /**
  * One row shown in the admin task-manager table.

package/apps/agents-server/src/utils/createPagePreviewBrowserStream.ts

@@ -0,0 +1,179 @@
+import type { Page } from 'playwright';
+import { $provideBrowserForServer } from '../tools/$provideBrowserForServer';
+import type { PagePreviewBrowserViewport } from './pagePreviewBrowserSessions';
+import {
+    attachPagePreviewBrowserSessionPage,
+    finishPagePreviewBrowserSession,
+    markPagePreviewBrowserSessionFrame,
+} from './pagePreviewBrowserSessions';
+
+/**
+ * Boundary used for MJPEG page-preview streams.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_STREAM_BOUNDARY = 'pagepreviewboundary';
+
+/**
+ * Width of the live browser preview viewport.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_VIEWPORT_WIDTH = 1280;
+
+/**
+ * Height of the live browser preview viewport.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_VIEWPORT_HEIGHT = 800;
+
+/**
+ * Milliseconds between streamed browser frames.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_FRAME_INTERVAL_MS = 350;
+
+/**
+ * JPEG quality used by the live browser preview stream.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_JPEG_QUALITY = 60;
+
+/**
+ * Navigation timeout for one page-preview browser stream.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS = 30_000;
+
+/**
+ * Response content type for the live page-preview stream.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+export const PAGE_PREVIEW_STREAM_CONTENT_TYPE = `multipart/x-mixed-replace; boundary=${PAGE_PREVIEW_STREAM_BOUNDARY}`;
+
+/**
+ * Options used when creating one live browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type CreatePagePreviewBrowserStreamOptions = {
+    readonly request: Request;
+    readonly sessionId: string;
+    readonly url: string;
+};
+
+/**
+ * Creates a Playwright-backed MJPEG stream for one page-preview browser session.
+ *
+ * @param options - Stream options.
+ * @returns Readable multipart stream.
+ */
+export function createPagePreviewBrowserStream(options: CreatePagePreviewBrowserStreamOptions): ReadableStream<Uint8Array> {
+    const encoder = new TextEncoder();
+    const viewport: PagePreviewBrowserViewport = {
+        width: PAGE_PREVIEW_VIEWPORT_WIDTH,
+        height: PAGE_PREVIEW_VIEWPORT_HEIGHT,
+    };
+
+    return new ReadableStream<Uint8Array>({
+        async start(controller) {
+            let isStreamOpen = true;
+            let page: Page | null = null;
+
+            const closeStream = async (): Promise<void> => {
+                if (!isStreamOpen) {
+                    return;
+                }
+
+                isStreamOpen = false;
+                finishPagePreviewBrowserSession(options.sessionId);
+                await page?.close().catch(() => undefined);
+
+                try {
+                    controller.close();
+                } catch {
+                    // The browser may close the stream first when the modal is dismissed.
+                }
+            };
+
+            options.request.signal.addEventListener(
+                'abort',
+                () => {
+                    void closeStream();
+                },
+                { once: true },
+            );
+
+            try {
+                const browserContext = await $provideBrowserForServer({ sessionId: options.sessionId });
+                page = await browserContext.newPage();
+                attachPagePreviewBrowserSessionPage(options.sessionId, page, viewport);
+
+                await page.setViewportSize(viewport);
+                await page.goto(options.url, {
+                    waitUntil: 'domcontentloaded',
+                    timeout: PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS,
+                });
+
+                while (isStreamOpen && !options.request.signal.aborted) {
+                    const buffer = await page.screenshot({
+                        type: 'jpeg',
+                        quality: PAGE_PREVIEW_JPEG_QUALITY,
+                    });
+                    const header = createPagePreviewFrameHeader(buffer.byteLength);
+
+                    controller.enqueue(encoder.encode(header));
+                    controller.enqueue(buffer);
+                    markPagePreviewBrowserSessionFrame(options.sessionId);
+                    await waitForNextPagePreviewFrame(options.request.signal);
+                }
+            } catch (error) {
+                if (!options.request.signal.aborted) {
+                    console.error('[page-preview] live browser stream failed', error);
+                    controller.error(error);
+                }
+            } finally {
+                await closeStream();
+            }
+        },
+    });
+}
+
+/**
+ * Creates one multipart frame header.
+ *
+ * @param byteLength - JPEG payload length.
+ * @returns Multipart frame header.
+ */
+function createPagePreviewFrameHeader(byteLength: number): string {
+    return `\r\n--${PAGE_PREVIEW_STREAM_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${byteLength}\r\n\r\n`;
+}
+
+/**
+ * Waits before sending the next stream frame, resolving early on abort.
+ *
+ * @param signal - Request abort signal.
+ */
+function waitForNextPagePreviewFrame(signal: AbortSignal): Promise<void> {
+    if (signal.aborted) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+        const timeout = setTimeout(resolve, PAGE_PREVIEW_FRAME_INTERVAL_MS);
+
+        signal.addEventListener(
+            'abort',
+            () => {
+                clearTimeout(timeout);
+                resolve();
+            },
+            { once: true },
+        );
+    });
+}