cbrowser 18.69.3 → 18.71.0

package/dist/mcp-tools/base/capture-tools.d.ts

@@ -0,0 +1,189 @@
+/**
+ * CBrowser MCP Tools - Screen Capture Tools
+ *
+ * Screen capture (pixels -> GIF/WebP/video), exposed as `capture_start`,
+ * `capture_stop`, `capture_status`.
+ *
+ * Distinct from the `record` feature, which records user ACTIONS for test
+ * generation. Nothing here touches that.
+ *
+ * The response discipline is the point of this module: a recording is hundreds
+ * of frames and tens of megabytes of video, none of which can cross an MCP
+ * boundary. Frames and artifacts are returned as PATHS; the only inlined pixels
+ * are a contact sheet sized to whatever is left of the response budget after
+ * the JSON payload is measured.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { z } from "zod";
+import { type CaptureFormat } from "../../recording/engine.js";
+import type { RecordingManifest } from "../../recording/types.js";
+import type { CBrowser, McpServer, ToolRegistrationContext } from "../types.js";
+/** Exposed for tests and for `reset_browser`-style teardown. */
+export declare function clearCaptureSessions(): void;
+/** Parse "5s", "2m", "1500ms" or a bare millisecond count. */
+export declare function parseDurationMs(input: string): number;
+/** Parse "gif,webp,mp4" into validated formats. */
+export declare function parseFormats(input: string): CaptureFormat[];
+/**
+ * Resolve a viewport argument: either `WxH` or the name of a built-in preset
+ * (`mobile`, `tablet`, `desktop-lg`, ...).
+ */
+export declare function parseViewport(input: string): {
+    width: number;
+    height: number;
+};
+/** Parse "x,y,width,height" into a rect. */
+export declare function parseRegion(input: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export interface CaptureStopPayload {
+    success: true;
+    slug: string;
+    manifest_path: string;
+    out_dir: string;
+    frames: number;
+    target_fps: number;
+    actual_fps: number;
+    duration_ms: number;
+    capture_method: string;
+    engine: string;
+    output_dims: {
+        width: number;
+        height: number;
+    };
+    target: RecordingManifest["target"];
+    region_clamped?: boolean;
+    artifacts: Record<string, string>;
+    encode_errors?: Record<string, string>;
+    change_points: number[];
+    change_points_total: number;
+    frame_gaps: {
+        after_index: number;
+        gap_ms: number;
+    }[];
+    frame_gaps_total: number;
+    console_errors: string[];
+    console_errors_total: number;
+    network_requests_total: number;
+    frames_dir: string;
+    contact_sheet?: string;
+    contact_sheet_note?: string;
+    note: string;
+}
+/**
+ * Build the `capture_stop` JSON payload from a manifest.
+ *
+ * Deliberately excludes the frame array: 500 frames of paths, crops, SSIM
+ * scores and per-frame console/network records is megabytes of JSON that would
+ * blow the response budget and tell the model nothing it can act on. The frames
+ * live on disk and the directory is named instead. Unbounded lists
+ * (change points, gaps, console errors) are truncated with their true totals
+ * reported alongside, so the model can tell "3 change points" from
+ * "200 shown of 4,812".
+ *
+ * Pure and exported so the budget can be tested without running a browser.
+ */
+export declare function buildCaptureStopPayload(manifest: RecordingManifest, extra: {
+    manifestPath: string;
+    outDir: string;
+    encodeErrors?: Record<string, string>;
+    contactSheet?: string;
+    contactSheetNote?: string;
+}): CaptureStopPayload;
+/**
+ * Last line of defence on the response budget.
+ *
+ * The payload builder and the contact-sheet budget already keep the response
+ * small, but "small by construction" is a claim about code that can drift. This
+ * measures the actual serialized content blocks and sheds until they fit:
+ * image blocks first (the sheet is a convenience, the paths are the payload),
+ * then the text block itself, replaced by a minimal pointer to the manifest.
+ *
+ * An over-budget response is therefore not merely unlikely, it cannot be
+ * returned — the tool would have to skip this function to emit one.
+ */
+export declare function enforceResponseBudget<T extends {
+    type: string;
+    text?: string;
+    data?: string;
+}>(content: T[], maxBytes?: number, fallbackText?: string): T[];
+/**
+ * Byte budget left for an inlined contact sheet once the JSON payload is
+ * accounted for. Returns 0 when there is no room worth using.
+ */
+export declare function contactSheetBudget(payloadBytes: number, totalBudget?: number): number;
+export interface CaptureStartArgs {
+    url?: string;
+    fps?: number;
+    duration?: string;
+    viewport?: string;
+    region?: string;
+    element?: string;
+    padding?: number;
+    format?: string;
+    quality?: number;
+    max_frames?: number;
+    name?: string;
+    out_dir?: string;
+}
+/** Start a capture on the given browser. Returns the payload object. */
+export declare function startCapture(browser: CBrowser, args: CaptureStartArgs, token?: string): Promise<Record<string, unknown>>;
+/**
+ * Stop the capture and build the response payload plus a budget-fitted contact
+ * sheet. Returns the payload and the sheet path (if one was produced).
+ */
+export declare function stopCapture(token?: string): Promise<{
+    payload: CaptureStopPayload;
+    contactSheet?: string;
+}>;
+/**
+ * Report the running or most recent capture for this browser session.
+ *
+ * Two rules, in tension, both honoured:
+ *   - A running capture is never invisible. If one is live on another token or
+ *     in another process, it is always surfaced.
+ *   - The caller's own capture is never masked by someone else's. A session
+ *     that just finished a recording is told about its own run first, with the
+ *     other capture attached alongside rather than in place of it.
+ *
+ * The failure this replaces: after `capture_stop`, status reported
+ * "No capture has been started on this browser session" — the completed run
+ * vanished with the session object, reading as though it never happened.
+ */
+export declare function captureStatus(token?: string): Record<string, unknown>;
+/** Input schema shared by both servers, so the two cannot drift. */
+export declare const captureStartSchema: {
+    url: z.ZodOptional<z.ZodString>;
+    fps: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    element: z.ZodOptional<z.ZodString>;
+    padding: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodString>;
+    quality: z.ZodOptional<z.ZodNumber>;
+    max_frames: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    out_dir: z.ZodOptional<z.ZodString>;
+    _browserToken: z.ZodOptional<z.ZodString>;
+};
+export declare const captureStopSchema: {
+    _browserToken: z.ZodOptional<z.ZodString>;
+};
+export declare const captureStatusSchema: {
+    _browserToken: z.ZodOptional<z.ZodString>;
+};
+declare const CAPTURE_START_DESCRIPTION: string;
+declare const CAPTURE_STOP_DESCRIPTION: string;
+declare const CAPTURE_STATUS_DESCRIPTION: string;
+/**
+ * Register capture tools (3 tools: capture_start, capture_stop, capture_status)
+ */
+export declare function registerCaptureTools(server: McpServer, { getBrowser, getBrowserByToken }: ToolRegistrationContext): void;
+export { CAPTURE_START_DESCRIPTION, CAPTURE_STOP_DESCRIPTION, CAPTURE_STATUS_DESCRIPTION };
+//# sourceMappingURL=capture-tools.d.ts.map

package/dist/mcp-tools/base/capture-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/capture-tools.ts"],"names":[],"mappings":"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"}