autokap 2.0.0 → 2.0.2

package/dist/cli-runner.js

@@ -174,7 +174,7 @@ export async function runCapture(options) {
     // durations + audio assets are only consumed on the upload path (signalVideoComplete), which a dry
     // run never reaches, so skipping prep here is side-effect-free for dry.
     if (!options.dryRun && !options.program && program.mediaMode === 'video') {
-        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false, sessionId);
+        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false, sessionId, options.onProgress);
         if (!prepareResult.success) {
             return { success: false, runId, error: prepareResult.error };
         }
@@ -524,7 +524,7 @@ async function fetchProgram(config, presetId, environmentName) {
     }
     return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
 }
-async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId) {
+async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId, onProgress) {
     if (regenerateTts) {
         logger.info('[capture] Forcing TTS regeneration — all cached segments will be re-synthesized and billed.');
     }
@@ -578,6 +578,17 @@ async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, s
         }
         if (event.type === 'tts_progress') {
             logTtsProgress(event);
+            // Forward to the caller so cloud runs can surface the narration phase as
+            // checkpoints (local runs only ever logged it — the original blind spot).
+            onProgress?.({
+                type: 'tts_progress',
+                variantId: 'tts',
+                message: '',
+                stage: event.stage,
+                index: event.index,
+                total: event.total,
+                stepId: event.stepId,
+            });
             return;
         }
         if (event.type === 'error') {

package/dist/cli.d.ts

@@ -1,3 +1,24 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import type { ProgressEvent } from './opcode-runner.js';
 export declare const program: Command;
+type CloudCheckpointType = 'preset_progress' | 'upload_start' | 'upload_end';
+/** Interval below which consecutive `granular` checkpoints are coalesced. */
+export declare const GRANULAR_CHECKPOINT_THROTTLE_MS = 1200;
+export declare function cloudCaptureProgressCheckpoint(event: ProgressEvent): {
+    type: CloudCheckpointType;
+    message: string;
+    status?: 'running';
+    /** Fine-grained intra-preset event (per-opcode / per-narration) — throttled
+     *  so a long video's step stream can't bury the coarse structural events in
+     *  the server's bounded timeline window. Structural events are never marked. */
+    granular?: boolean;
+} | null;
+/**
+ * Stateful gate that admits at most one `granular` checkpoint per throttle
+ * window; structural (non-granular) checkpoints always pass. Create one per
+ * preset so each preset streams its own opcode/narration cadence. `now` is
+ * injectable for tests.
+ */
+export declare function createGranularCheckpointThrottle(throttleMs?: number, now?: () => number): (granular: boolean) => boolean;
+export {};

package/dist/cli.js

@@ -51,7 +51,9 @@ function displayPresetName(preset) {
     const name = preset.name?.trim();
     return name && name.length > 0 ? name : preset.id;
 }
-function cloudCaptureProgressCheckpoint(event) {
+/** Interval below which consecutive `granular` checkpoints are coalesced. */
+export const GRANULAR_CHECKPOINT_THROTTLE_MS = 1200;
+export function cloudCaptureProgressCheckpoint(event) {
     switch (event.type) {
         case 'variant_start':
             return {
@@ -66,6 +68,26 @@ function cloudCaptureProgressCheckpoint(event) {
                     : `Capture failed: ${event.variantId}`,
                 status: event.status === 'failed' ? 'running' : undefined,
             };
+        case 'opcode_start': {
+            const position = (event.opcodeIndex ?? 0) + 1;
+            const total = event.opcodeTotal ? `/${event.opcodeTotal}` : '';
+            const label = event.message || event.opcodeKind || '';
+            return {
+                type: 'preset_progress',
+                granular: true,
+                message: label ? `Step ${position}${total}: ${label}` : `Step ${position}${total}`,
+            };
+        }
+        case 'tts_progress': {
+            const position = event.index ?? '?';
+            const total = event.total ?? '?';
+            const suffix = event.stage === 'uploading' ? ' · uploading' : event.stage === 'done' ? ' · done' : '';
+            return {
+                type: 'preset_progress',
+                granular: true,
+                message: `Narration ${position}/${total}${suffix}`,
+            };
+        }
         case 'upload_start':
             return {
                 type: 'upload_start',
@@ -81,6 +103,24 @@ function cloudCaptureProgressCheckpoint(event) {
             return null;
     }
 }
+/**
+ * Stateful gate that admits at most one `granular` checkpoint per throttle
+ * window; structural (non-granular) checkpoints always pass. Create one per
+ * preset so each preset streams its own opcode/narration cadence. `now` is
+ * injectable for tests.
+ */
+export function createGranularCheckpointThrottle(throttleMs = GRANULAR_CHECKPOINT_THROTTLE_MS, now = Date.now) {
+    let lastGranularAt = null;
+    return (granular) => {
+        if (!granular)
+            return true;
+        const current = now();
+        if (lastGranularAt !== null && current - lastGranularAt < throttleMs)
+            return false;
+        lastGranularAt = current;
+        return true;
+    };
+}
 // ── login command ───────────────────────────────────────────────────
 program
     .command('login <key>')
@@ -420,6 +460,9 @@ program
             failedPresets: failures.length,
             message: `Preset started: ${presetDisplayName}`,
         });
+        // Fresh throttle per preset so each preset streams its own opcode/
+        // narration cadence and the window resets at each preset boundary.
+        const admitCheckpoint = createGranularCheckpointThrottle();
         const result = await runCapture({
             presetId: preset.id,
             env: opts.env,
@@ -437,6 +480,10 @@ program
                 const checkpoint = cloudCaptureProgressCheckpoint(event);
                 if (!checkpoint)
                     return;
+                // Coalesce fine-grained (opcode / narration) checkpoints; structural
+                // ones (capture/export start/end) always pass through.
+                if (!admitCheckpoint(checkpoint.granular ?? false))
+                    return;
                 void postCloudCheckpoint({
                     type: checkpoint.type,
                     presetId: preset.id,

package/dist/opcode-runner.d.ts

@@ -52,11 +52,20 @@ export interface RunOptions {
     dryRun?: boolean;
 }
 export interface ProgressEvent {
-    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end';
+    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end' | 'tts_progress';
     variantId: string;
     opcodeIndex?: number;
+    /** Total opcode count in the variant program (set on opcode_start). */
+    opcodeTotal?: number;
     opcodeKind?: string;
     status?: OpcodeResultStatus;
     message: string;
+    /** tts_progress only: 'synthesizing' | 'uploading' | 'done'. */
+    stage?: string;
+    /** tts_progress only: 1-based segment index and total. */
+    index?: number;
+    total?: number;
+    /** tts_progress only: the SLEEP anchor / step id being synthesized. */
+    stepId?: string;
 }
 export declare function executeProgram(program: ExecutionProgram, createAdapter: (variant: VariantSpec) => Promise<RuntimeAdapter>, options?: RunOptions): Promise<RunResult>;

package/dist/opcode-runner.js

@@ -318,6 +318,7 @@ async function executeVariant(program, variant, createAdapter, recoveryChain, te
                 type: 'opcode_start',
                 variantId: variant.id,
                 opcodeIndex: i,
+                opcodeTotal: program.steps.length,
                 opcodeKind: opcode.kind,
                 message: opcode.description,
             });

package/dist/semantic-resolver.d.ts

@@ -41,3 +41,13 @@ export declare function resolveTarget(page: Page, options: ResolveOptions): Prom
  * language subtag → base field → first non-empty map value.
  */
 export declare function localizeSemanticTarget(target: SemanticTarget, locale?: string): SemanticTarget;
+/**
+ * Emits a one-line warning when the active locale has NO entry in any of the
+ * target's `*ByLocale` maps, so the resolver is about to fall back to another
+ * language's string. This is the failure mode behind captures that pass in
+ * every language whose text was captured and fail in the ones that were only
+ * guessed (or never translated): the fallback string doesn't match the
+ * localized UI, and the CLICK/TYPE fails deep in the run instead of surfacing
+ * the real cause. Silent otherwise — no maps or a matching entry logs nothing.
+ */
+export declare function warnOnMissingLocaleEntry(target: SemanticTarget, locale?: string): void;

package/dist/web-playwright-local.d.ts

@@ -203,3 +203,4 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
      */
     private reportClickSfxTimestamps;
 }
+export declare function describeResolveOptions(opts: ResolveOptions): string;

package/dist/web-playwright-local.js

@@ -8,7 +8,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { humanType, moveMouse, } from './mouse-animation.js';
-import { resolveTarget } from './semantic-resolver.js';
+import { resolveTarget, localizeSemanticTarget } from './semantic-resolver.js';
 import { logger } from './logger.js';
 import { ClipCaptureLoop } from './clip-capture-loop.js';
 import { FfmpegX11Recorder } from './ffmpeg-x11-recorder.js';
@@ -1369,18 +1369,44 @@ export class WebPlaywrightLocal {
         }
     }
 }
-function describeResolveOptions(opts) {
+export function describeResolveOptions(opts) {
     const parts = [];
     if (opts.selector)
         parts.push(`selector="${opts.selector}"`);
-    if (opts.target?.text)
-        parts.push(`text="${opts.target.text}"`);
-    if (opts.target?.role)
-        parts.push(`role="${opts.target.role}"`);
-    if (opts.target?.label)
-        parts.push(`label="${opts.target.label}"`);
-    if (opts.target?.placeholder)
-        parts.push(`placeholder="${opts.target.placeholder}"`);
+    if (opts.target) {
+        // Project the target onto the active locale so the message reports what was
+        // actually searched: the `*ByLocale` maps collapse onto their base field.
+        // Without this, a target expressed purely through `textByLocale` (no role,
+        // no plain text) rendered as the misleading "no target specified" even
+        // though a localized string was attempted — which sends debugging down the
+        // wrong path (it looks like the opcode carries no target at all).
+        const projected = localizeSemanticTarget(opts.target, opts.locale);
+        if (projected.role)
+            parts.push(`role="${projected.role}"`);
+        if (projected.text)
+            parts.push(`text="${projected.text}"`);
+        if (projected.label)
+            parts.push(`label="${projected.label}"`);
+        if (projected.placeholder)
+            parts.push(`placeholder="${projected.placeholder}"`);
+        if (projected.near)
+            parts.push(`near="${projected.near}"`);
+        if (opts.locale)
+            parts.push(`locale="${opts.locale}"`);
+        // Echo the raw locale maps so a missing or mistranslated entry for the
+        // active locale is obvious at a glance (e.g. `fr` guessed as "Nouvelle
+        // capture" when the deployed UI reads "Nouveau programme de capture").
+        const describeMap = (name, map) => {
+            const entries = Object.entries(map ?? {});
+            if (entries.length > 0) {
+                parts.push(`${name}={${entries.map(([k, v]) => `${k}:"${v}"`).join(', ')}}`);
+            }
+        };
+        describeMap('textByLocale', opts.target.textByLocale);
+        describeMap('labelByLocale', opts.target.labelByLocale);
+        describeMap('placeholderByLocale', opts.target.placeholderByLocale);
+        describeMap('nearByLocale', opts.target.nearByLocale);
+    }
     return parts.join(', ') || 'no target specified';
 }
 async function captureSurfaceMatches(page, expected) {

package/package.json

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