autokap 1.0.8 → 1.1.0

package/dist/clip-runtime.js

@@ -0,0 +1,67 @@
+export const CLIP_BACKEND_ENV_VAR = 'AUTOKAP_CLIP_BACKEND';
+export const CLIP_HEADLESS_POLICY_ENV_VAR = 'AUTOKAP_CLIP_HEADLESS_POLICY';
+const BEGIN_FRAME_LAUNCH_ARGS = [
+    '--enable-begin-frame-control',
+    '--run-all-compositor-stages-before-draw',
+];
+function normalizeClipCaptureMethod(raw) {
+    switch (raw?.trim().toLowerCase()) {
+        case 'begin_frame':
+        case 'frame_sequence':
+        case 'playwright_video':
+            return raw.trim().toLowerCase();
+        default:
+            return null;
+    }
+}
+function normalizeHeadlessPolicy(raw) {
+    switch (raw?.trim().toLowerCase()) {
+        case 'headless':
+            return 'headless';
+        case 'headed':
+            return 'headed';
+        default:
+            return 'auto';
+    }
+}
+export function resolveRequestedClipCaptureMethod() {
+    return normalizeClipCaptureMethod(process.env[CLIP_BACKEND_ENV_VAR]) ?? 'begin_frame';
+}
+export function resolveClipHeadlessPolicy() {
+    return normalizeHeadlessPolicy(process.env[CLIP_HEADLESS_POLICY_ENV_VAR]);
+}
+export async function resolveClipRuntimeSelection(options = {}) {
+    const requestedMethod = resolveRequestedClipCaptureMethod();
+    const headlessPolicy = resolveClipHeadlessPolicy();
+    const platform = options.platform ?? process.platform;
+    const browserHeaded = headlessPolicy === 'headed'
+        ? true
+        : headlessPolicy === 'headless'
+            ? false
+            : options.headed ?? false;
+    let captureMethod = requestedMethod;
+    let fallbackReason;
+    let browserLaunchArgs;
+    if (requestedMethod === 'begin_frame') {
+        if (platform === 'darwin') {
+            captureMethod = 'frame_sequence';
+            fallbackReason = 'begin_frame is unsupported on macOS Chromium targets; falling back to frame sequence capture';
+        }
+        else if (browserHeaded) {
+            captureMethod = 'frame_sequence';
+            fallbackReason = 'begin_frame requires headless Chromium; falling back to frame sequence capture';
+        }
+        else {
+            browserLaunchArgs = [...BEGIN_FRAME_LAUNCH_ARGS];
+        }
+    }
+    return {
+        requestedMethod,
+        captureMethod,
+        browserHeaded,
+        headlessPolicy,
+        fallbackReason,
+        browserLaunchArgs,
+    };
+}
+//# sourceMappingURL=clip-runtime.js.map

package/dist/clip-scale.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_CAPTURE_OUTPUT_SCALE = 2;
+export declare function normalizeCaptureOutputScale(value?: number | null): number | null;
+export declare function resolveEffectiveCaptureOutputScale(requestedScale?: number | null, fallbackScale?: number): number;
+export declare function resolvePhysicalCaptureSize(viewport: {
+    width: number;
+    height: number;
+} | null, scale: number | null | undefined): {
+    width: number;
+    height: number;
+} | null;

package/dist/clip-scale.js

@@ -0,0 +1,21 @@
+export const DEFAULT_CAPTURE_OUTPUT_SCALE = 2;
+export function normalizeCaptureOutputScale(value) {
+    if (!Number.isFinite(value))
+        return null;
+    return Math.max(0.5, Math.min(4, Number(value)));
+}
+export function resolveEffectiveCaptureOutputScale(requestedScale, fallbackScale = DEFAULT_CAPTURE_OUTPUT_SCALE) {
+    return normalizeCaptureOutputScale(requestedScale)
+        ?? normalizeCaptureOutputScale(fallbackScale)
+        ?? DEFAULT_CAPTURE_OUTPUT_SCALE;
+}
+export function resolvePhysicalCaptureSize(viewport, scale) {
+    if (!viewport)
+        return null;
+    const effectiveScale = resolveEffectiveCaptureOutputScale(scale);
+    return {
+        width: Math.max(2, Math.round(viewport.width * effectiveScale)) & ~1,
+        height: Math.max(2, Math.round(viewport.height * effectiveScale)) & ~1,
+    };
+}
+//# sourceMappingURL=clip-scale.js.map

package/dist/clip-screencast-recorder.d.ts

@@ -0,0 +1,42 @@
+import type { Page } from 'playwright';
+import type { RecordingResult } from './execution-types.js';
+import type { ClipOptions } from './types.js';
+export interface CdpScreencastClipRecorderOptions {
+    baseDir?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    requestedScale?: number;
+    effectiveScale: number;
+    clipOptions?: ClipOptions;
+    sourceFps?: number;
+    outputFps?: number;
+}
+export declare class CdpScreencastClipRecorder {
+    private readonly page;
+    private readonly options;
+    private readonly sourceFps;
+    private readonly outputFps;
+    private readonly workingDirPromise;
+    private readonly frames;
+    private readonly startedAt;
+    private finalResult;
+    private frameDimensions;
+    private pendingWriteError;
+    private readonly pendingWrites;
+    private cdpSession;
+    private stopRequested;
+    private started;
+    constructor(page: Page, options: CdpScreencastClipRecorderOptions);
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    abort(): Promise<void>;
+    private captureInitialFrame;
+    private handleScreencastFrame;
+    private consumeFrame;
+    private queueFrameWrite;
+    private waitForPendingWriteCapacity;
+    private flushPendingWrites;
+    private cleanup;
+}

package/dist/clip-screencast-recorder.js

@@ -0,0 +1,242 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { postProcessClipFrames } from './clip-postprocess.js';
+import { buildCdpViewportClip } from './clip-frame-recorder.js';
+import { resolvePhysicalCaptureSize } from './clip-scale.js';
+const DEFAULT_CLIP_SOURCE_FPS = 30;
+const DEFAULT_CLIP_OUTPUT_FPS = 30;
+const SCREENCAST_FRAME_FORMAT = 'jpeg';
+const SCREENCAST_FRAME_QUALITY = 92;
+const MAX_PENDING_FRAME_WRITES = 8;
+export class CdpScreencastClipRecorder {
+    page;
+    options;
+    sourceFps;
+    outputFps;
+    workingDirPromise;
+    frames = [];
+    startedAt = Date.now();
+    finalResult = null;
+    frameDimensions = null;
+    pendingWriteError = null;
+    pendingWrites = new Set();
+    cdpSession = null;
+    stopRequested = false;
+    started = false;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+        this.sourceFps = Math.max(1, Math.round(options.sourceFps ?? DEFAULT_CLIP_SOURCE_FPS));
+        this.outputFps = Math.max(1, Math.round(options.outputFps ?? DEFAULT_CLIP_OUTPUT_FPS));
+        this.workingDirPromise = options.baseDir
+            ? Promise.resolve(options.baseDir)
+            : fs.mkdtemp(path.join(os.tmpdir(), 'autokap-clip-screencast-'));
+        this.frameDimensions = resolvePhysicalCaptureSize(options.viewport, options.effectiveScale)
+            ?? {
+                width: Math.max(2, Math.round(options.viewport.width)) & ~1,
+                height: Math.max(2, Math.round(options.viewport.height)) & ~1,
+            };
+    }
+    async start() {
+        const workingDir = await this.workingDirPromise;
+        await fs.mkdir(path.join(workingDir, 'frames'), { recursive: true });
+        const context = this.page.context();
+        if (typeof context.newCDPSession !== 'function') {
+            throw new Error('CDP screencast is not available on this browser context');
+        }
+        this.cdpSession = await context.newCDPSession(this.page);
+        this.cdpSession.on('Page.screencastFrame', this.handleScreencastFrame);
+        await this.cdpSession.send('Page.enable').catch(() => undefined);
+        await this.captureInitialFrame();
+        await this.cdpSession.send('Page.startScreencast', {
+            format: SCREENCAST_FRAME_FORMAT,
+            quality: SCREENCAST_FRAME_QUALITY,
+            maxWidth: this.frameDimensions?.width,
+            maxHeight: this.frameDimensions?.height,
+            everyNthFrame: 1,
+        });
+        this.started = true;
+    }
+    async stop() {
+        if (this.finalResult) {
+            return this.finalResult;
+        }
+        if (!this.started || !this.cdpSession) {
+            throw new Error('CDP screencast recording was not started');
+        }
+        this.stopRequested = true;
+        const stopAt = Date.now();
+        try {
+            await this.cdpSession.send('Page.stopScreencast').catch(() => undefined);
+            await sleep(100);
+            await this.flushPendingWrites();
+            if (this.frames.length === 0) {
+                throw this.pendingWriteError ?? new Error('clip screencast ended before any frame was recorded');
+            }
+            if (this.pendingWriteError) {
+                throw this.pendingWriteError;
+            }
+            const workingDir = await this.workingDirPromise;
+            const outputDimensions = this.frameDimensions
+                ?? resolvePhysicalCaptureSize(this.options.viewport, this.options.effectiveScale)
+                ?? this.options.viewport;
+            const frameEntries = buildFrameEntries(this.frames, stopAt, this.sourceFps, this.outputFps);
+            const actualSourceFps = resolveActualSourceFps(this.frames, stopAt);
+            const processed = await postProcessClipFrames(frameEntries, workingDir, 'clip', {
+                ...this.options.clipOptions,
+                mp4Width: outputDimensions.width,
+                mp4Height: outputDimensions.height,
+            });
+            if (!processed.mp4Path || !processed.thumbnailPath) {
+                throw new Error('clip packaging failed: missing MP4 or thumbnail output');
+            }
+            const [mp4Buffer, gifBuffer, thumbnailBuffer] = await Promise.all([
+                fs.readFile(processed.mp4Path),
+                processed.gifPath ? fs.readFile(processed.gifPath) : Promise.resolve(null),
+                fs.readFile(processed.thumbnailPath),
+            ]);
+            const clipPackage = {
+                mp4: {
+                    buffer: mp4Buffer,
+                    mimeType: 'video/mp4',
+                },
+                ...(gifBuffer
+                    ? {
+                        gif: {
+                            buffer: gifBuffer,
+                            mimeType: 'image/gif',
+                        },
+                    }
+                    : {}),
+                thumbnail: {
+                    buffer: thumbnailBuffer,
+                    mimeType: 'image/png',
+                },
+                captureMethod: 'cdp_screencast',
+                requestedScale: this.options.requestedScale,
+                effectiveScale: this.options.effectiveScale,
+                sourceFps: this.sourceFps,
+                actualSourceFps,
+                outputFps: this.outputFps,
+                frameCount: this.frames.length,
+                dimensions: outputDimensions,
+            };
+            this.finalResult = {
+                buffer: mp4Buffer,
+                mimeType: 'video/mp4',
+                durationMs: processed.durationMs,
+                trimStartMs: 0,
+                clipPackage,
+            };
+            return this.finalResult;
+        }
+        finally {
+            await this.cleanup();
+        }
+    }
+    async abort() {
+        this.stopRequested = true;
+        await this.cleanup();
+    }
+    async captureInitialFrame() {
+        const session = this.cdpSession;
+        if (!session) {
+            return;
+        }
+        const scrollOffset = await this.page.evaluate(() => ({
+            x: window.scrollX || window.pageXOffset || 0,
+            y: window.scrollY || window.pageYOffset || 0,
+        })).catch(() => ({ x: 0, y: 0 }));
+        const screenshot = await session.send('Page.captureScreenshot', {
+            format: SCREENCAST_FRAME_FORMAT,
+            quality: SCREENCAST_FRAME_QUALITY,
+            clip: buildCdpViewportClip(this.options.viewport, this.options.effectiveScale, scrollOffset),
+        }).catch(() => null);
+        if (!screenshot?.data) {
+            return;
+        }
+        await this.consumeFrame(Buffer.from(screenshot.data, 'base64'), this.startedAt);
+    }
+    handleScreencastFrame = (payload) => {
+        const session = this.cdpSession;
+        if (!session || this.stopRequested) {
+            return;
+        }
+        const ack = session.send('Page.screencastFrameAck', { sessionId: payload.sessionId }).catch(() => undefined);
+        void ack;
+        void this.consumeFrame(Buffer.from(payload.data, 'base64'), Date.now());
+    };
+    async consumeFrame(frameBuffer, capturedAt) {
+        if (this.pendingWriteError) {
+            return;
+        }
+        const workingDir = await this.workingDirPromise;
+        const frameIndex = this.frames.length;
+        const framePath = path.join(workingDir, 'frames', `frame-${String(frameIndex).padStart(6, '0')}.jpg`);
+        this.frames.push({ path: framePath, capturedAt });
+        await this.queueFrameWrite(framePath, frameBuffer);
+    }
+    async queueFrameWrite(framePath, frameBuffer) {
+        await this.waitForPendingWriteCapacity();
+        if (this.pendingWriteError) {
+            throw this.pendingWriteError;
+        }
+        let writePromise;
+        writePromise = fs.writeFile(framePath, frameBuffer)
+            .catch((error) => {
+            this.pendingWriteError = error instanceof Error ? error : new Error(String(error));
+            throw this.pendingWriteError;
+        })
+            .finally(() => {
+            this.pendingWrites.delete(writePromise);
+        });
+        this.pendingWrites.add(writePromise);
+    }
+    async waitForPendingWriteCapacity() {
+        while (this.pendingWrites.size >= MAX_PENDING_FRAME_WRITES) {
+            await Promise.race(this.pendingWrites);
+            if (this.pendingWriteError) {
+                throw this.pendingWriteError;
+            }
+        }
+    }
+    async flushPendingWrites() {
+        while (this.pendingWrites.size > 0) {
+            await Promise.allSettled(Array.from(this.pendingWrites));
+        }
+    }
+    async cleanup() {
+        const workingDir = await this.workingDirPromise;
+        this.cdpSession?.off?.('Page.screencastFrame', this.handleScreencastFrame);
+        await this.cdpSession?.detach().catch(() => undefined);
+        this.cdpSession = null;
+        this.started = false;
+        await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function buildFrameEntries(frames, stopAt, sourceFps, outputFps) {
+    const entries = [];
+    const minFrameDurationMs = Math.max(1, Math.min(Math.round(1000 / sourceFps), Math.round(1000 / outputFps)));
+    for (let index = 0; index < frames.length; index += 1) {
+        const frame = frames[index];
+        const nextTimestamp = frames[index + 1]?.capturedAt ?? stopAt;
+        entries.push({
+            path: frame.path,
+            durationMs: Math.max(minFrameDurationMs, nextTimestamp - frame.capturedAt),
+        });
+    }
+    return entries;
+}
+function resolveActualSourceFps(frames, stopAt) {
+    if (frames.length <= 1) {
+        return frames.length;
+    }
+    const firstTimestamp = frames[0].capturedAt;
+    const durationSec = Math.max(0.001, (stopAt - firstTimestamp) / 1000);
+    return Math.round((frames.length / durationSec) * 100) / 100;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=clip-screencast-recorder.js.map

package/dist/clip-sidecar.d.ts

@@ -0,0 +1,54 @@
+export interface ClipSidecarProbeResult {
+    supported: boolean;
+    supportsHeadless: boolean;
+    permissionGranted?: boolean;
+    executablePath?: string;
+    version?: string;
+    backend?: string;
+    reason?: string;
+}
+export interface NativeClipSidecarStartParams {
+    targetId: string;
+    outputPath: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    effectiveScale: number;
+    outputWidth: number;
+    outputHeight: number;
+    targetFps: number;
+    includeCursor: boolean;
+    headed: boolean;
+    windowTitle: string;
+    cropRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface NativeClipSidecarStopResult {
+    mp4Path: string;
+    actualSourceFps?: number;
+    frameCount?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+}
+interface NativeClipSidecarSessionOptions {
+    executablePath: string;
+}
+export declare class NativeClipSidecarSession {
+    private readonly child;
+    private readonly pending;
+    private stderr;
+    private closed;
+    constructor(options: NativeClipSidecarSessionOptions);
+    request<T>(command: string, payload?: object): Promise<T>;
+    close(): Promise<void>;
+    private handleEnvelope;
+    private rejectAll;
+}
+export declare function probeNativeClipSidecar(): Promise<ClipSidecarProbeResult>;
+export {};

package/dist/clip-sidecar.js

@@ -0,0 +1,208 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getConfigDir } from './cli-config.js';
+const SIDECAR_BINARY_ENV_VAR = 'AUTOKAP_CLIP_SIDECAR_PATH';
+const SIDECAR_BASE_URL_ENV_VAR = 'AUTOKAP_CLIP_SIDECAR_BASE_URL';
+const DEFAULT_SIDECAR_BASE_URL = 'https://github.com/mangue-dev/screenshot-agent/releases/latest/download';
+const SIDECAR_NAME = 'autokap-clip-capture-sidecar';
+function resolveSidecarAssetSpec() {
+    const ext = process.platform === 'win32' ? '.exe' : '';
+    const platform = process.platform;
+    const arch = process.arch;
+    if (!['darwin', 'linux', 'win32'].includes(platform)) {
+        return null;
+    }
+    if (!['arm64', 'x64'].includes(arch)) {
+        return null;
+    }
+    const fileName = `${SIDECAR_NAME}-${platform}-${arch}${ext}`;
+    return {
+        fileName,
+        executableName: `${SIDECAR_NAME}${ext}`,
+    };
+}
+async function fileExists(filePath) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDownloadedSidecar() {
+    const explicitPath = process.env[SIDECAR_BINARY_ENV_VAR]?.trim();
+    if (explicitPath) {
+        return explicitPath;
+    }
+    const workspaceBinary = path.resolve(process.cwd(), 'native', 'clip-capture-sidecar', 'target', 'release', resolveSidecarAssetSpec()?.executableName ?? SIDECAR_NAME);
+    if (await fileExists(workspaceBinary)) {
+        return workspaceBinary;
+    }
+    const asset = resolveSidecarAssetSpec();
+    if (!asset) {
+        throw new Error(`native clip sidecar is not available on ${process.platform}/${process.arch}`);
+    }
+    const sidecarDir = path.join(getConfigDir(), 'sidecars', 'clip-capture');
+    const binaryPath = path.join(sidecarDir, asset.executableName);
+    if (await fileExists(binaryPath)) {
+        return binaryPath;
+    }
+    const baseUrl = process.env[SIDECAR_BASE_URL_ENV_VAR]?.trim() || DEFAULT_SIDECAR_BASE_URL;
+    const response = await fetch(`${baseUrl.replace(/\/+$/, '')}/${asset.fileName}`);
+    if (!response.ok) {
+        throw new Error(`failed to download native clip sidecar (${response.status})`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    await fs.mkdir(sidecarDir, { recursive: true });
+    await fs.writeFile(binaryPath, bytes);
+    if (process.platform !== 'win32') {
+        await fs.chmod(binaryPath, 0o755);
+    }
+    return binaryPath;
+}
+function parseLineDelimitedJson(stream, onMessage, onInvalid) {
+    let buffer = '';
+    stream.on('data', (chunk) => {
+        buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        while (true) {
+            const newlineIndex = buffer.indexOf('\n');
+            if (newlineIndex === -1) {
+                break;
+            }
+            const line = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (!line) {
+                continue;
+            }
+            try {
+                onMessage(JSON.parse(line));
+            }
+            catch {
+                onInvalid(line);
+            }
+        }
+    });
+}
+export class NativeClipSidecarSession {
+    child;
+    pending = new Map();
+    stderr = '';
+    closed = false;
+    constructor(options) {
+        this.child = spawn(options.executablePath, [], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        parseLineDelimitedJson(this.child.stdout, (payload) => this.handleEnvelope(payload), (raw) => this.rejectAll(new Error(`native sidecar emitted invalid JSON: ${raw}`)));
+        this.child.stderr.on('data', (chunk) => {
+            this.stderr += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        });
+        this.child.on('error', (error) => {
+            this.rejectAll(error instanceof Error ? error : new Error(String(error)));
+        });
+        this.child.on('exit', (code, signal) => {
+            this.closed = true;
+            if (this.pending.size === 0) {
+                return;
+            }
+            const suffix = this.stderr.trim() ? ` — ${this.stderr.trim()}` : '';
+            this.rejectAll(new Error(`native sidecar exited before completing a request (code=${code ?? 'null'}, signal=${signal ?? 'null'})${suffix}`));
+        });
+    }
+    async request(command, payload = {}) {
+        if (this.closed) {
+            throw new Error('native sidecar session is already closed');
+        }
+        const id = randomUUID();
+        const request = JSON.stringify({
+            id,
+            command,
+            ...payload,
+        });
+        const responsePromise = new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+            });
+        });
+        this.child.stdin.write(`${request}\n`);
+        return responsePromise;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.child.kill();
+    }
+    handleEnvelope(payload) {
+        if (!payload.id) {
+            return;
+        }
+        const pending = this.pending.get(payload.id);
+        if (!pending) {
+            return;
+        }
+        this.pending.delete(payload.id);
+        if (payload.ok) {
+            pending.resolve(payload.result);
+            return;
+        }
+        pending.reject(new Error(payload.error?.message ?? 'native sidecar request failed'));
+    }
+    rejectAll(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+export async function probeNativeClipSidecar() {
+    let executablePath;
+    try {
+        executablePath = await ensureDownloadedSidecar();
+    }
+    catch (error) {
+        return {
+            supported: false,
+            supportsHeadless: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const session = new NativeClipSidecarSession({ executablePath });
+    try {
+        const result = await session.request('probe');
+        if (result.supported !== true || typeof result.supportsHeadless !== 'boolean') {
+            return {
+                supported: false,
+                supportsHeadless: false,
+                executablePath,
+                reason: 'native clip sidecar returned an invalid probe response',
+            };
+        }
+        return {
+            supported: true,
+            supportsHeadless: result.supportsHeadless,
+            permissionGranted: result.permissionGranted !== false,
+            executablePath,
+            version: result.version,
+            backend: result.backend,
+            reason: result.reason,
+        };
+    }
+    catch (error) {
+        return {
+            supported: false,
+            supportsHeadless: false,
+            executablePath,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=clip-sidecar.js.map

package/dist/cost-logging.d.ts

@@ -7,7 +7,7 @@ export interface CostLogContext {
     presetId?: string;
     lang?: string;
     theme?: string;
-    captureType?: 'fullpage' | 'element' | 'video';
+    captureType?: 'fullpage' | 'element';
     elementName?: string;
     targetId?: string;
     captureId?: string | null;