cbrowser 18.70.0 → 18.71.0

package/dist/recording/contact-sheet.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Default byte budget, tracking the MCP response limit
+ * (`MAX_RESPONSE_SIZE` in src/mcp-tools/screenshot-utils.ts) so the two cannot
+ * drift apart.
+ */
+export declare const MAX_CONTACT_SHEET_BYTES = 150000;
+/** Default number of frames sampled into the sheet. */
+export declare const DEFAULT_MAX_FRAMES = 12;
+/**
+ * Longest edge of the assembled sheet before the compression ladder starts.
+ * Capping here keeps the ladder cheap: a 12-tile grid of 1280x720 frames would
+ * otherwise be re-encoded at 5120x2160 several times before shrinking.
+ */
+export declare const MAX_SHEET_EDGE = 1600;
+export interface ContactSheetOptions {
+    /** Paths of every frame in the recording, in capture order. */
+    framePaths: string[];
+    /** Where to write the sheet. A non-JPEG extension is rewritten to `.jpg`. */
+    outPath: string;
+    /** Grid columns. Defaults to `ceil(sqrt(frames sampled))`. */
+    columns?: number;
+    /** How many frames to sample. Default {@link DEFAULT_MAX_FRAMES}. */
+    maxFrames?: number;
+    /** Byte budget for the written file. Default {@link MAX_CONTACT_SHEET_BYTES}. */
+    maxBytes?: number;
+    /** Burn each frame's index into its tile. Default true. */
+    labelIndices?: boolean;
+}
+export interface ContactSheetResult {
+    /** Path actually written (may differ from `outPath` by extension). */
+    path: string;
+    /** Size of the written file in bytes; always <= the requested budget. */
+    bytes: number;
+    /** Indices into `framePaths` that were sampled, ascending. */
+    frameIndices: number[];
+}
+/**
+ * Pick `k` evenly spaced indices across `n` items.
+ *
+ * Always includes the first item, and the last item whenever more than one is
+ * requested — the ends of a recording are the two frames a reviewer always
+ * wants. Returns `min(n, k)` strictly increasing indices, so asking for more
+ * frames than exist yields every frame exactly once.
+ *
+ * @throws if `n` or `k` is not a positive integer.
+ */
+export declare function pickEvenlySpaced(n: number, k: number): number[];
+/**
+ * Build a contact sheet from a recording's frames.
+ *
+ * Samples with {@link pickEvenlySpaced}, tiles into a grid, optionally labels
+ * each tile with its frame index, then walks a scale x quality ladder until the
+ * encoded sheet fits `maxBytes`.
+ *
+ * @throws if `framePaths` is empty, if options are out of range, or if the
+ *         sheet cannot be squeezed under the budget even at the floor of the
+ *         ladder — the message names the smallest size achieved.
+ */
+export declare function buildContactSheet(opts: ContactSheetOptions): Promise<ContactSheetResult>;
+//# sourceMappingURL=contact-sheet.d.ts.map

package/dist/recording/contact-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-sheet.d.ts","sourceRoot":"","sources":["../../src/recording/contact-sheet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAAoB,CAAC;AAEzD,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAcnC,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAoB/D;AAgDD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkH9F"}

package/dist/recording/contact-sheet.js

@@ -0,0 +1,204 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Contact sheet: a single tiled image summarising a recording.
+ *
+ * A recording can be hundreds of frames, which no MCP response can carry and no
+ * reviewer wants to page through. The contact sheet picks an evenly spaced
+ * sample, tiles it into a labelled grid, and compresses the result until it
+ * fits the MCP response budget — so one image answers "what happened here?".
+ *
+ * The byte budget is not advisory: an over-budget sheet is never returned, it
+ * throws. Silently handing back something the transport will truncate is worse
+ * than failing loudly.
+ */
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import sharp from "sharp";
+import { MAX_RESPONSE_SIZE } from "../mcp-tools/screenshot-utils.js";
+/**
+ * Default byte budget, tracking the MCP response limit
+ * (`MAX_RESPONSE_SIZE` in src/mcp-tools/screenshot-utils.ts) so the two cannot
+ * drift apart.
+ */
+export const MAX_CONTACT_SHEET_BYTES = MAX_RESPONSE_SIZE;
+/** Default number of frames sampled into the sheet. */
+export const DEFAULT_MAX_FRAMES = 12;
+/**
+ * Longest edge of the assembled sheet before the compression ladder starts.
+ * Capping here keeps the ladder cheap: a 12-tile grid of 1280x720 frames would
+ * otherwise be re-encoded at 5120x2160 several times before shrinking.
+ */
+export const MAX_SHEET_EDGE = 1600;
+/** JPEG quality ladder, mirroring `screenshotCompressed` in src/browser.ts. */
+const QUALITY_STEPS = [85, 70, 55, 45, 35, 25];
+/**
+ * Scale ladder. Runs one step lower than the screenshot ladder because a grid
+ * packs far more detail per pixel than a single capture.
+ */
+const SCALE_STEPS = [1.0, 0.75, 0.5, 0.4, 0.3, 0.2];
+/** Sheet background / letterbox colour. */
+const BACKGROUND = { r: 12, g: 12, b: 14 };
+/**
+ * Pick `k` evenly spaced indices across `n` items.
+ *
+ * Always includes the first item, and the last item whenever more than one is
+ * requested — the ends of a recording are the two frames a reviewer always
+ * wants. Returns `min(n, k)` strictly increasing indices, so asking for more
+ * frames than exist yields every frame exactly once.
+ *
+ * @throws if `n` or `k` is not a positive integer.
+ */
+export function pickEvenlySpaced(n, k) {
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`pickEvenlySpaced: n must be a positive integer, got ${n}`);
+    }
+    if (!Number.isInteger(k) || k < 1) {
+        throw new Error(`pickEvenlySpaced: k must be a positive integer, got ${k}`);
+    }
+    const m = Math.min(n, k);
+    if (m === 1)
+        return [0];
+    const step = (n - 1) / (m - 1);
+    const picked = new Array(m);
+    for (let i = 0; i < m; i++) {
+        picked[i] = Math.round(i * step);
+    }
+    // The ends are pinned rather than derived, so rounding can never move them.
+    picked[0] = 0;
+    picked[m - 1] = n - 1;
+    return picked;
+}
+/**
+ * Overlay carrying every tile's index label.
+ *
+ * One SVG for the whole sheet rather than one per tile: a single composite
+ * layer instead of `k` of them. Text is rendered by sharp's SVG support, so no
+ * font or canvas dependency is required.
+ */
+function buildLabelSvg(sheetWidth, sheetHeight, tiles, tileHeight) {
+    // Floored at 14px: below that, JPEG chroma subsampling at the low end of the
+    // quality ladder smears the glyphs into the badge and the label stops being
+    // readable, which defeats the point of burning it in.
+    const fontSize = Math.min(28, Math.max(14, Math.round(tileHeight * 0.14)));
+    const padding = Math.max(3, Math.round(fontSize * 0.25));
+    const boxHeight = fontSize + padding * 2;
+    const parts = tiles.map(({ left, top, label }) => {
+        const boxWidth = Math.round(fontSize * 0.7 * label.length) + padding * 2;
+        const x = left + padding;
+        const y = top + padding;
+        return (`<rect x="${x}" y="${y}" width="${boxWidth}" height="${boxHeight}" rx="${padding}" ` +
+            `fill="rgba(0,0,0,0.65)"/>` +
+            `<text x="${x + padding}" y="${y + fontSize + padding * 0.5}" ` +
+            `font-family="DejaVu Sans, Helvetica, Arial, sans-serif" font-size="${fontSize}" ` +
+            `fill="#ffffff">${label}</text>`);
+    });
+    return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${sheetWidth}" height="${sheetHeight}">` +
+        parts.join("") +
+        `</svg>`);
+}
+/** Force a JPEG extension, matching `screenshotCompressed`'s behaviour. */
+function jpegPath(outPath) {
+    if (/\.jpe?g$/i.test(outPath))
+        return outPath;
+    return outPath.replace(/\.[^./\\]+$/, "") + ".jpg";
+}
+/**
+ * Build a contact sheet from a recording's frames.
+ *
+ * Samples with {@link pickEvenlySpaced}, tiles into a grid, optionally labels
+ * each tile with its frame index, then walks a scale x quality ladder until the
+ * encoded sheet fits `maxBytes`.
+ *
+ * @throws if `framePaths` is empty, if options are out of range, or if the
+ *         sheet cannot be squeezed under the budget even at the floor of the
+ *         ladder — the message names the smallest size achieved.
+ */
+export async function buildContactSheet(opts) {
+    const { framePaths, outPath, columns, maxFrames = DEFAULT_MAX_FRAMES, maxBytes = MAX_CONTACT_SHEET_BYTES, labelIndices = true, } = opts;
+    if (framePaths.length === 0) {
+        throw new Error("buildContactSheet: framePaths must not be empty");
+    }
+    if (!outPath) {
+        throw new Error("buildContactSheet: outPath is required");
+    }
+    if (!Number.isInteger(maxFrames) || maxFrames < 1) {
+        throw new Error(`buildContactSheet: maxFrames must be a positive integer, got ${maxFrames}`);
+    }
+    if (columns !== undefined && (!Number.isInteger(columns) || columns < 1)) {
+        throw new Error(`buildContactSheet: columns must be a positive integer, got ${columns}`);
+    }
+    if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+        throw new Error(`buildContactSheet: maxBytes must be positive, got ${maxBytes}`);
+    }
+    const frameIndices = pickEvenlySpaced(framePaths.length, maxFrames);
+    const selected = frameIndices.map((i) => framePaths[i]);
+    const cols = columns ?? Math.ceil(Math.sqrt(selected.length));
+    const rows = Math.ceil(selected.length / cols);
+    // Every frame of a recording shares the capture geometry, so the first frame
+    // sets the tile size for the whole sheet.
+    const meta = await sharp(selected[0]).metadata();
+    if (!meta.width || !meta.height) {
+        throw new Error(`buildContactSheet: could not read dimensions of ${selected[0]}`);
+    }
+    let baseWidth = meta.width;
+    let baseHeight = meta.height;
+    const longestEdge = Math.max(cols * baseWidth, rows * baseHeight);
+    if (longestEdge > MAX_SHEET_EDGE) {
+        const preScale = MAX_SHEET_EDGE / longestEdge;
+        baseWidth = Math.max(1, Math.round(baseWidth * preScale));
+        baseHeight = Math.max(1, Math.round(baseHeight * preScale));
+    }
+    const target = jpegPath(outPath);
+    mkdirSync(dirname(target), { recursive: true });
+    const render = async (scale, quality) => {
+        const tileWidth = Math.max(1, Math.round(baseWidth * scale));
+        const tileHeight = Math.max(1, Math.round(baseHeight * scale));
+        const sheetWidth = tileWidth * cols;
+        const sheetHeight = tileHeight * rows;
+        const placements = selected.map((_, i) => ({
+            left: (i % cols) * tileWidth,
+            top: Math.floor(i / cols) * tileHeight,
+        }));
+        const tiles = await Promise.all(selected.map((path) => sharp(path)
+            .resize(tileWidth, tileHeight, { fit: "contain", background: BACKGROUND })
+            .toBuffer()));
+        const layers = tiles.map((input, i) => ({
+            input,
+            left: placements[i].left,
+            top: placements[i].top,
+        }));
+        if (labelIndices) {
+            layers.push({
+                input: buildLabelSvg(sheetWidth, sheetHeight, placements.map((p, i) => ({ ...p, label: String(frameIndices[i]) })), tileHeight),
+                left: 0,
+                top: 0,
+            });
+        }
+        return sharp({
+            create: { width: sheetWidth, height: sheetHeight, channels: 3, background: BACKGROUND },
+        })
+            .composite(layers)
+            .jpeg({ quality, chromaSubsampling: "4:2:0" })
+            .toBuffer();
+    };
+    let smallest = Number.POSITIVE_INFINITY;
+    for (const scale of SCALE_STEPS) {
+        for (const quality of QUALITY_STEPS) {
+            const buffer = await render(scale, quality);
+            if (buffer.length < smallest)
+                smallest = buffer.length;
+            if (buffer.length <= maxBytes) {
+                writeFileSync(target, buffer);
+                return { path: target, bytes: statSync(target).size, frameIndices };
+            }
+        }
+    }
+    throw new Error(`buildContactSheet: cannot fit ${selected.length} frames within ${maxBytes} bytes — ` +
+        `smallest achieved ${smallest} bytes at scale ${SCALE_STEPS[SCALE_STEPS.length - 1]} / ` +
+        `quality ${QUALITY_STEPS[QUALITY_STEPS.length - 1]}. Lower maxFrames or raise maxBytes.`);
+}
+//# sourceMappingURL=contact-sheet.js.map

package/dist/recording/contact-sheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-sheet.js","sourceRoot":"","sources":["../../src/recording/contact-sheet.ts"],"names":[],"mappings":"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"}

package/dist/recording/encoders.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Recording encoders — turn a directory of captured frames into an animated
+ * GIF, an animated WebP, or a video.
+ *
+ * Two hard constraints shape this module:
+ *
+ * 1. Frames arrive from a CDP screencast, so they are JPEGs of *differing*
+ *    byte length and occasionally differing pixel dimensions (a viewport
+ *    change mid-capture re-sizes the stream). Every frame is therefore
+ *    normalised to one locked output size before encoding. Do not "optimise"
+ *    this into raw-buffer stacking — sharp's animated encoders need a joined
+ *    input, and a stacked raw buffer silently produces a single tall page.
+ *
+ * 2. Capture is event-driven, so frames are *not* evenly spaced. Per-frame
+ *    delays come from the caller (derived from frame timestamps), never from
+ *    a constant cadence.
+ *
+ * @since v18.70.0
+ */
+/** Result of a successful encode. */
+export interface EncodeResult {
+    /** Absolute path to the encoded artifact. */
+    path: string;
+    /** Size of the artifact in bytes. */
+    bytes: number;
+    /** Number of frames encoded. */
+    frames: number;
+    /** Locked output width in pixels. */
+    width: number;
+    /** Locked output height in pixels. */
+    height: number;
+}
+export interface EncodeOptions {
+    /** Locked output width. Defaults to the first frame's width. */
+    width?: number;
+    /** Locked output height. Defaults to the first frame's height. */
+    height?: number;
+    /**
+     * Per-frame source crop, parallel to `frames`. Screencast frames are written
+     * to disk full-viewport so a capture can be re-cropped later, so region and
+     * element captures crop here at encode time rather than at capture time.
+     * A crop that falls outside its frame is trimmed to the frame.
+     */
+    crops?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
+    /** Downscale factor applied to the locked size (0 < scale <= 1). */
+    scale?: number;
+    /** Loop count for animated formats (0 = infinite, the default). */
+    loop?: number;
+}
+/**
+ * Thrown when an encoder's external dependency is missing. Callers surface the
+ * message verbatim and exit non-zero — recording itself has already succeeded
+ * at this point, so this must never be swallowed into a silent partial result.
+ */
+export declare class MissingEncoderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Encode frames into an animated GIF with per-frame delays.
+ *
+ * A single-frame recording (a static page that emitted no screencast events)
+ * encodes to a one-page GIF rather than failing.
+ */
+export declare function encodeGif(frames: string[], delays: number[], outPath: string, options?: EncodeOptions): Promise<EncodeResult>;
+/** Encode frames into an animated WebP with per-frame delays. */
+export declare function encodeWebp(frames: string[], delays: number[], outPath: string, options?: EncodeOptions): Promise<EncodeResult>;
+/**
+ * Locate Playwright's bundled ffmpeg. A bare `ffmpeg` is never invoked: the
+ * PATH binary is not guaranteed to exist on deploy targets, and silently
+ * picking up an arbitrary system build makes output non-reproducible.
+ *
+ * Probe order: $PLAYWRIGHT_BROWSERS_PATH, then the per-user cache directories.
+ */
+export declare function resolveFfmpegPath(): string | null;
+/**
+ * Resample variable-delay frames onto a constant-rate timeline by repeating
+ * each frame for as long as it was on screen. Video containers assume a fixed
+ * frame rate; repeating is how event-driven capture maps onto one without
+ * inventing content that was never displayed.
+ */
+export declare function resampleToConstantRate(frames: string[], delays: number[], fps: number): string[];
+/** Encode frames into a WebM/VP8 video. Works with Playwright's bundled ffmpeg. */
+export declare function encodeWebm(frames: string[], delays: number[], outPath: string, options?: EncodeOptions & {
+    fps?: number;
+}): Promise<EncodeResult>;
+/**
+ * Encode frames into an MP4.
+ *
+ * Requires an ffmpeg with the mp4 muxer and an H.264-family encoder. Playwright's
+ * bundled binary has neither, so this throws {@link MissingEncoderError} unless a
+ * fuller ffmpeg is installed.
+ */
+export declare function encodeMp4(frames: string[], delays: number[], outPath: string, options?: EncodeOptions & {
+    fps?: number;
+}): Promise<EncodeResult>;
+//# sourceMappingURL=encoders.d.ts.map

package/dist/recording/encoders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoders.d.ts","sourceRoot":"","sources":["../../src/recording/encoders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAoGD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED,iEAAiE;AACjE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAUvB;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAwBjD;AA+CD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAQhG;AAkFD,mFAAmF;AACnF,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,YAAY,CAAC,CAEvB"}