autokap 1.1.3 → 1.1.5

package/dist/browser.d.ts

@@ -147,6 +147,7 @@ export declare class Browser {
      * with an overall timeout of `timeoutMs`.
      */
     private waitForDomStability;
+    private waitForFontsBeforeScreenshot;
     takeScreenshot(): Promise<Buffer>;
     takeScreenshotForAI(options?: {
         timeoutMs?: number;

package/dist/browser.js

@@ -689,11 +689,7 @@ export class Browser {
             // Page may have navigated during wait
         }
     }
-    async takeScreenshot() {
-        const page = this.ensurePage();
-        // Move cursor off-screen to avoid hover effects in screenshots
-        await page.mouse.move(0, 0);
-        await ensureCaptureHideStyles(page);
+    async waitForFontsBeforeScreenshot(page) {
         // Wait for web fonts to be loaded AND applied to the rendered page.
         // next/font and other `font-display: swap` setups can report the
         // FontFaceSet as "ready" while visible text is still painted with fallback.
@@ -762,6 +758,13 @@ export class Browser {
             })(),
             new Promise((resolve) => setTimeout(resolve, 8000)),
         ])).catch(() => { });
+    }
+    async takeScreenshot() {
+        const page = this.ensurePage();
+        // Move cursor off-screen to avoid hover effects in screenshots
+        await page.mouse.move(0, 0);
+        await ensureCaptureHideStyles(page);
+        await this.waitForFontsBeforeScreenshot(page);
         await logFontDiagnostics(page, 'before screenshot');
         return Buffer.from(await page.screenshot({ type: 'png', fullPage: false }));
     }
@@ -4135,6 +4138,8 @@ export class Browser {
             if (clip.width <= 0 || clip.height <= 0) {
                 throw new Error(`Element index ${index} is still outside the viewport after alignment`);
             }
+            await this.waitForFontsBeforeScreenshot(page);
+            await logFontDiagnostics(page, 'before element screenshot');
             return Buffer.from(await page.screenshot({ type: 'png', clip }));
         }
         finally {
@@ -4160,6 +4165,8 @@ export class Browser {
         // Hide fixed/sticky overlays (navbars, banners) that could cover the region
         await this.hideFixedOverlays();
         try {
+            await this.waitForFontsBeforeScreenshot(page);
+            await logFontDiagnostics(page, 'before region screenshot');
             const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
             const image = sharp(fullPage);
             const meta = await image.metadata();
@@ -4281,6 +4288,8 @@ export class Browser {
         await this.hideFixedOverlays();
         try {
             const dpr = pageInfo.dpr;
+            await this.waitForFontsBeforeScreenshot(page);
+            await logFontDiagnostics(page, 'before selector screenshot');
             const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
             const image = sharp(fullPage);
             const meta = await image.metadata();
@@ -4343,6 +4352,8 @@ export class Browser {
         await this.hideFixedOverlays();
         try {
             const dpr = pageInfo.dpr;
+            await this.waitForFontsBeforeScreenshot(page);
+            await logFontDiagnostics(page, 'before bounding-region screenshot');
             const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
             const image = sharp(fullPage);
             const meta = await image.metadata();

package/dist/cli-runner.js

@@ -27,6 +27,8 @@ import { callLLM } from './llm-provider.js';
 import { APP_VERSION } from './version.js';
 import { normalizeAllowedOrigins, normalizeHttpOrigin, verifySignedExecutionProgramEnvelope, } from './program-signing.js';
 const MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR = 1;
+const FETCH_PROGRAM_MAX_ATTEMPTS = 4;
+const FETCH_PROGRAM_RETRY_DELAYS_MS = [1000, 3000, 5000];
 const HEALER_SYSTEM_PROMPT = 'You repair failed deterministic browser opcodes. Respond only with JSON.';
 // ── Main entry point ────────────────────────────────────────────────
 export async function runCapture(options) {
@@ -92,10 +94,13 @@ export async function runCapture(options) {
         credentials: program.preconditions.credentials,
     });
     // Step 4: Execute the program
+    const maxParallelVariants = program.mediaMode === 'clip'
+        ? 1
+        : program.maxParallelCaptures;
     const runOptions = {
         recoveryChain,
         abortSignal: options.abortSignal,
-        maxParallelVariants: program.maxParallelCaptures,
+        maxParallelVariants,
         llmConfig,
         presetName: program.presetId,
         onProgress: (event) => {
@@ -106,8 +111,12 @@ export async function runCapture(options) {
         },
     };
     const captureStart = Date.now();
-    if (program.maxParallelCaptures) {
-        logger.info(`[capture] Concurrency cap resolved to ${program.maxParallelCaptures} parallel variant(s)`);
+    if (maxParallelVariants) {
+        logger.info(`[capture] Concurrency cap resolved to ${maxParallelVariants} parallel variant(s)`);
+        if (program.mediaMode === 'clip' && program.maxParallelCaptures && program.maxParallelCaptures > 1) {
+            logger.info(`[capture] Clip capture concurrency capped at 1 ` +
+                `(requested ${program.maxParallelCaptures}) to avoid CI CPU contention`);
+        }
     }
     const createAdapter = async (variant) => {
         const recordable = program.mediaMode === 'clip';
@@ -177,22 +186,55 @@ export async function runCapture(options) {
 }
 // ── Server communication ────────────────────────────────────────────
 async function fetchProgram(config, presetId, environmentName) {
-    try {
-        const url = new URL(`${config.apiBaseUrl}/api/cli/programs/${presetId}`);
-        if (environmentName) {
-            url.searchParams.set('env', environmentName);
+    const url = new URL(`${config.apiBaseUrl}/api/cli/programs/${presetId}`);
+    if (environmentName) {
+        url.searchParams.set('env', environmentName);
+    }
+    const requestedUrl = url.toString();
+    for (let attempt = 1; attempt <= FETCH_PROGRAM_MAX_ATTEMPTS; attempt += 1) {
+        let response;
+        try {
+            response = await fetch(requestedUrl, {
+                headers: {
+                    'Authorization': `Bearer ${config.apiKey}`,
+                    'Content-Type': 'application/json',
+                    [CLI_VERSION_HEADER]: APP_VERSION,
+                },
+            });
+        }
+        catch (err) {
+            const error = `failed to fetch program: ${err instanceof Error ? err.message : String(err)}`;
+            if (attempt < FETCH_PROGRAM_MAX_ATTEMPTS) {
+                await retryProgramFetch(attempt, error);
+                continue;
+            }
+            return { success: false, error };
         }
-        const response = await fetch(url.toString(), {
-            headers: {
-                'Authorization': `Bearer ${config.apiKey}`,
-                'Content-Type': 'application/json',
-                [CLI_VERSION_HEADER]: APP_VERSION,
-            },
-        });
         if (!response.ok) {
-            return { success: false, error: await formatServerError(response, url.toString()) };
+            const error = await formatServerError(response, requestedUrl);
+            if (shouldRetryProgramFetch(response.status, error) && attempt < FETCH_PROGRAM_MAX_ATTEMPTS) {
+                await retryProgramFetch(attempt, error);
+                continue;
+            }
+            return { success: false, error };
+        }
+        const contentType = response.headers?.get?.('content-type') ?? '';
+        let data;
+        try {
+            if (contentType.includes('text/html')) {
+                const htmlPreview = (await response.text()).replace(/\s+/g, ' ').trim().slice(0, 120);
+                throw new Error(`unexpected HTML response from ${requestedUrl}${htmlPreview ? `: ${htmlPreview}` : ''}`);
+            }
+            data = await response.json();
+        }
+        catch (err) {
+            const error = `failed to fetch program: ${err instanceof Error ? err.message : String(err)}`;
+            if (attempt < FETCH_PROGRAM_MAX_ATTEMPTS) {
+                await retryProgramFetch(attempt, error);
+                continue;
+            }
+            return { success: false, error };
         }
-        const data = await response.json();
         const envelope = verifySignedExecutionProgramEnvelope({
             apiKey: config.apiKey,
             envelope: data,
@@ -203,9 +245,29 @@ async function fetchProgram(config, presetId, environmentName) {
         }
         return { success: true, program: envelope.program, security: envelope.security };
     }
-    catch (err) {
-        return { success: false, error: `failed to fetch program: ${err instanceof Error ? err.message : String(err)}` };
+    return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
+}
+function shouldRetryProgramFetch(status, error) {
+    if ([408, 429, 500, 502, 503, 504].includes(status)) {
+        return true;
     }
+    return status >= 500 && error.includes('unexpected HTML response');
+}
+async function retryProgramFetch(attempt, error) {
+    const delayMs = getProgramFetchRetryDelayMs(attempt);
+    logger.warn(`[capture] Program fetch failed (attempt ${attempt}/${FETCH_PROGRAM_MAX_ATTEMPTS}): ${error}. Retrying in ${delayMs}ms...`);
+    if (delayMs > 0) {
+        await sleep(delayMs);
+    }
+}
+function getProgramFetchRetryDelayMs(attempt) {
+    if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true') {
+        return 0;
+    }
+    return FETCH_PROGRAM_RETRY_DELAYS_MS[Math.max(0, attempt - 1)] ?? FETCH_PROGRAM_RETRY_DELAYS_MS.at(-1) ?? 0;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function uploadResults(config, program, result) {
     const runId = randomUUID();

package/dist/clip-capture-loop.d.ts

@@ -24,10 +24,21 @@ export interface ClipCaptureLoopOptions {
      * content (high-contrast text, flat colors) but unlocks a 33% fluidity gain.
      */
     jpegQuality?: number;
+    /**
+     * Maximum capture attempts per second. The loop also yields after every frame
+     * so Playwright input and page JS can make progress while a clip is recording.
+     */
+    targetFps?: number;
+    /** Minimum rest after each CDP screenshot, even when capture is already slow. */
+    minRestMs?: number;
 }
 export interface ClipCaptureLoopResult {
     framesDir: string;
     frameCount: number;
+    /** Configured capture attempt ceiling. Actual FPS may be lower when CDP is slow. */
+    targetFps: number;
+    /** Minimum idle time yielded after each CDP screenshot. */
+    minRestMs: number;
     /** (frameCount - 1) * 1000 / (lastTs - firstTs); 0 if < 2 frames. */
     measuredFps: number;
     actualDurationMs: number;
@@ -41,16 +52,26 @@ export interface ClipCaptureLoopResult {
      * loop keeps trying, producing bursts and gaps).
      */
     frameOffsetsMs: number[];
+    /** CDP Page.captureScreenshot wall time in milliseconds. */
+    captureTimingMs: {
+        p50: number;
+        p95: number;
+        max: number;
+    };
 }
 export declare class ClipCaptureLoop {
     private readonly page;
     private readonly framesDir;
     private readonly jpegQuality;
+    private readonly targetFps;
+    private readonly targetFrameIntervalMs;
+    private readonly minRestMs;
     private cdp;
     private running;
     private loopPromise;
     private frames;
     private frameTimestamps;
+    private frameCaptureDurationsMs;
     private startedAt;
     private firstFrameAt;
     private lastFrameAt;

package/dist/clip-capture-loop.js

@@ -18,11 +18,15 @@ export class ClipCaptureLoop {
     page;
     framesDir;
     jpegQuality;
+    targetFps;
+    targetFrameIntervalMs;
+    minRestMs;
     cdp = null;
     running = false;
     loopPromise = null;
     frames = [];
     frameTimestamps = [];
+    frameCaptureDurationsMs = [];
     startedAt = 0;
     firstFrameAt = 0;
     lastFrameAt = 0;
@@ -30,6 +34,10 @@ export class ClipCaptureLoop {
         this.page = opts.page;
         this.framesDir = opts.framesDir;
         this.jpegQuality = opts.jpegQuality ?? 80;
+        const targetFps = Math.max(1, Math.min(30, opts.targetFps ?? (process.platform === 'linux' ? 8 : 15)));
+        this.targetFps = targetFps;
+        this.targetFrameIntervalMs = 1000 / targetFps;
+        this.minRestMs = Math.max(0, Math.min(250, opts.minRestMs ?? (process.platform === 'linux' ? 50 : 16)));
     }
     async start() {
         this.cdp = await this.page.context().newCDPSession(this.page);
@@ -64,22 +72,28 @@ export class ClipCaptureLoop {
         const trimStartMs = this.firstFrameAt > 0 ? Math.max(0, this.firstFrameAt - this.startedAt) : 0;
         // Snapshot offsets (ms from first frame) for VFR encoding downstream.
         const frameOffsetsMs = this.frameTimestamps.map(ts => ts - this.firstFrameAt);
+        const captureTimingMs = summarizeTiming(this.frameCaptureDurationsMs);
         // Release memory — the caller owns framesDir from here on.
         this.frames = [];
         this.frameTimestamps = [];
+        this.frameCaptureDurationsMs = [];
         return {
             framesDir: this.framesDir,
             frameCount,
+            targetFps: this.targetFps,
+            minRestMs: this.minRestMs,
             measuredFps,
             actualDurationMs,
             trimStartMs,
             frameOffsetsMs,
+            captureTimingMs,
         };
     }
     async loop() {
         while (this.running) {
             if (!this.cdp)
                 return;
+            const frameStartedAt = performance.now();
             let data;
             try {
                 const r = await this.cdp.send('Page.captureScreenshot', {
@@ -105,7 +119,30 @@ export class ClipCaptureLoop {
             // Decode+write happens in stop().
             this.frames.push(data);
             this.frameTimestamps.push(ts);
+            const elapsed = performance.now() - frameStartedAt;
+            this.frameCaptureDurationsMs.push(elapsed);
+            const restMs = Math.max(this.minRestMs, this.targetFrameIntervalMs - elapsed);
+            if (restMs > 0 && this.running) {
+                await new Promise(resolve => setTimeout(resolve, restMs));
+            }
         }
     }
 }
+function summarizeTiming(values) {
+    if (values.length === 0)
+        return { p50: 0, p95: 0, max: 0 };
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        p50: roundMs(percentile(sorted, 0.5)),
+        p95: roundMs(percentile(sorted, 0.95)),
+        max: roundMs(sorted[sorted.length - 1] ?? 0),
+    };
+}
+function percentile(sorted, ratio) {
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * ratio) - 1));
+    return sorted[index] ?? 0;
+}
+function roundMs(value) {
+    return Math.round(value * 10) / 10;
+}
 //# sourceMappingURL=clip-capture-loop.js.map

package/dist/mouse-animation.d.ts

@@ -43,4 +43,7 @@ export declare function animatedHover(page: Page, target: {
  * Type text into the currently focused element at a human-like typing speed.
  * Assumes the field is already focused (via a preceding click).
  */
-export declare function humanType(page: Page, text: string): Promise<void>;
+export declare function humanType(page: Page, text: string, options?: {
+    minDelayMs?: number;
+    maxDelayMs?: number;
+}): Promise<void>;

package/dist/mouse-animation.js

@@ -103,12 +103,16 @@ export async function animatedHover(page, target, fromCurrent, options = {}) {
  * Type text into the currently focused element at a human-like typing speed.
  * Assumes the field is already focused (via a preceding click).
  */
-export async function humanType(page, text) {
+export async function humanType(page, text, options = {}) {
+    const minDelay = Math.max(0, options.minDelayMs ?? 60);
+    const maxDelay = Math.max(minDelay, options.maxDelayMs ?? 140);
     for (const char of text) {
         await page.keyboard.type(char);
         // 60–120 WPM → ~80–130ms between characters (5 chars per word)
-        const delay = 60 + Math.random() * 80;
-        await page.waitForTimeout(delay);
+        const delay = minDelay + Math.random() * (maxDelay - minDelay);
+        if (delay > 0) {
+            await page.waitForTimeout(delay);
+        }
     }
 }
 //# sourceMappingURL=mouse-animation.js.map

package/dist/web-playwright-local.js

@@ -278,7 +278,12 @@ export class WebPlaywrightLocal {
             ?? await fs.mkdtemp(path.join(os.tmpdir(), 'autokap-recording-'));
         const framesDir = path.join(baseDir, 'frames');
         await fs.mkdir(framesDir, { recursive: true });
-        const loop = new ClipCaptureLoop({ page, framesDir });
+        const loop = new ClipCaptureLoop({
+            page,
+            framesDir,
+            targetFps: process.platform === 'linux' ? 8 : 15,
+            minRestMs: process.platform === 'linux' ? 50 : 16,
+        });
         await loop.start();
         this.recording = {
             mediaMode: options.mediaMode,
@@ -306,7 +311,10 @@ export class WebPlaywrightLocal {
         }
         const result = await this.recording.loop.stop();
         logger.info(`[capture] Clip frame capture: ${result.frameCount} frame(s), ` +
-            `${result.measuredFps.toFixed(1)} fps over ${(result.actualDurationMs / 1000).toFixed(2)}s`);
+            `${result.measuredFps.toFixed(1)} fps over ${(result.actualDurationMs / 1000).toFixed(2)}s ` +
+            `(target ${result.targetFps} fps, rest >= ${result.minRestMs}ms; ` +
+            `CDP frame time p50=${result.captureTimingMs.p50}ms ` +
+            `p95=${result.captureTimingMs.p95}ms max=${result.captureTimingMs.max}ms)`);
         await this.browser.closeContext();
         await assembleMp4FromFrames({
             framesDir: this.recording.framesDir,
@@ -651,7 +659,9 @@ export class WebPlaywrightLocal {
             await page.keyboard.press('Control+A');
         }
         await page.waitForTimeout(70);
-        await humanType(page, text);
+        await humanType(page, text, this.clipCursor
+            ? { minDelayMs: 20, maxDelayMs: 45 }
+            : undefined);
     }
     async seedClipCursor() {
         if (!this.clipCursor)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",

package/dist/agent-action-recovery.d.ts

@@ -1,45 +0,0 @@
-/**
- * Action recovery, guard inference, and login detection utilities for the capture agent.
- * Extracted from agent.ts — these are pure functions with no closure dependencies.
- */
-import type { ExecutedAction, ActionType } from './types.js';
-export declare const META_ACTIONS: Set<ActionType>;
-export declare const BOOTSTRAP_ACTIONS: Set<ActionType>;
-export declare const REPLAYABLE_ACTIONS: ReadonlyArray<ActionType>;
-export declare function isNoEffectAction(action: ExecutedAction): boolean;
-export declare function isBootstrapStabilizationAction(action: ExecutedAction): boolean;
-export declare function hasMeaningfulBrowserAction(actionHistory: ExecutedAction[]): boolean;
-export declare function buildRecoveryActionSignature(action: ExecutedAction): string;
-export declare function isExplicitLoginAction(action: ExecutedAction): boolean;
-export declare function hasRecentExplicitLoginAction(previousActions: ExecutedAction[]): boolean;
-export declare function isLoginAction(action: ExecutedAction, previousActions?: ExecutedAction[]): boolean;
-export declare function compactReplayActions(recordedActions: ExecutedAction[], params?: {
-    currentUrl?: string;
-    targetUrl?: string;
-    currentViewport?: {
-        width: number;
-        height: number;
-    } | null;
-    isAuthenticated?: boolean;
-    ignoreRecordedViewport?: boolean;
-}): ExecutedAction[];
-export declare function countRecentNoEffectActions(actionHistory: ExecutedAction[]): number;
-export declare function shouldTriggerRecovery(actionHistory: ExecutedAction[]): boolean;
-export declare function inferPrematureGiveUpCorrection(params: {
-    reason: string;
-    actionHistory: ExecutedAction[];
-    lastVerificationFailure?: string;
-    iteration: number;
-    maxIterations: number;
-}): string | null;
-export declare function inferSearchScrollLoopGuard(params: {
-    actionHistory: ExecutedAction[];
-    action: ActionType;
-    args: Record<string, unknown>;
-}): string | null;
-export declare function inferRepeatedActionGuard(params: {
-    actionHistory: ExecutedAction[];
-    action: ActionType;
-    args: Record<string, unknown>;
-    currentUrl?: string;
-}): string | null;