autokap 1.5.1 → 1.5.2

package/dist/cli-contract.d.ts

@@ -52,6 +52,12 @@ export interface VideoClipMetadata {
             width: number;
             height: number;
         } | null;
+        /**
+         * For TYPE opcodes captured in clipCursor mode: clip-relative ms timestamp
+         * of every keystroke produced by `humanType`. Drives per-keystroke keyboard
+         * SFX in the video compositor.
+         */
+        keystrokeOffsetsMs?: number[];
     }>;
 }
 export interface VideoAudioAsset {

package/dist/cli-runner.js

@@ -748,6 +748,9 @@ export function buildVideoClipMetadata(videoId, result, program, runId) {
                 timecodeStartMs: t.timecodeStartMs,
                 timecodeEndMs: t.timecodeEndMs,
                 bbox: t.bbox ?? null,
+                ...(t.keystrokeOffsetsMs && t.keystrokeOffsetsMs.length > 0
+                    ? { keystrokeOffsetsMs: t.keystrokeOffsetsMs }
+                    : {}),
             }));
             clipsByKey.set(`${variantId}:${artifact.clipId}`, {
                 variantId,

package/dist/execution-types.d.ts

@@ -693,6 +693,13 @@ export interface OpcodeTiming {
         width: number;
         height: number;
     } | null;
+    /**
+     * For TYPE opcodes captured in clipCursor mode: timestamp (ms relative to the
+     * active clip start) of each individual keystroke produced by `humanType`.
+     * Drives keyboard SFX per-keystroke in the video compositor. Empty/undefined
+     * for non-TYPE opcodes and for typing paths that bypass humanType.
+     */
+    keystrokeOffsetsMs?: number[];
 }
 export interface RunResult {
     programId: string;
@@ -749,13 +756,23 @@ export interface RecordingResult {
     mimeType: string;
     trimStartMs?: number;
 }
+export interface TypeOptions {
+    /**
+     * Called once per keystroke produced by `humanType`, with the absolute
+     * wall-clock timestamp (`Date.now()`) of the keystroke. The runner converts
+     * those to clip-relative offsets stored on `OpcodeTiming.keystrokeOffsetsMs`
+     * so the compositor can fire per-keystroke SFX. Only fires in clipCursor
+     * mode (the only path that produces visible per-key animation).
+     */
+    onKeystroke?: (timestampMs: number) => void;
+}
 export interface RuntimeAdapter {
     navigate(url: string): Promise<void>;
     getCurrentUrl(): Promise<string>;
     getAKTree(): Promise<AKTree>;
     getPageSignals(): Promise<VideoPageSignals>;
     click(selector: string, options?: ClickOptions): Promise<void>;
-    type(selector: string, text: string, clearFirst?: boolean): Promise<void>;
+    type(selector: string, text: string, clearFirst?: boolean, opts?: TypeOptions): Promise<void>;
     pressKey(key: string): Promise<void>;
     scroll(direction: 'up' | 'down' | 'left' | 'right', amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;
@@ -808,7 +825,7 @@ export interface RuntimeAdapter {
         selector?: string;
         target?: SemanticTarget;
         selectorAlternates?: string[];
-    }, text: string, clearFirst?: boolean): Promise<void>;
+    }, text: string, clearFirst?: boolean, typeOpts?: TypeOptions): Promise<void>;
     /** Wait for an element by semantic target. */
     waitForTarget?(opts: {
         selector?: string;

package/dist/mouse-animation.d.ts

@@ -52,8 +52,14 @@ 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).
+ *
+ * `onKeystroke` fires after each character with the absolute wall-clock
+ * timestamp (`Date.now()`) of the keystroke. The video pipeline converts
+ * these to clip-relative offsets so keyboard SFX fire in lock-step with the
+ * visible typing.
  */
 export declare function humanType(page: Page, text: string, options?: {
     minDelayMs?: number;
     maxDelayMs?: number;
+    onKeystroke?: (timestampMs: number) => void;
 }): Promise<void>;

package/dist/mouse-animation.js

@@ -132,12 +132,20 @@ 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).
+ *
+ * `onKeystroke` fires after each character with the absolute wall-clock
+ * timestamp (`Date.now()`) of the keystroke. The video pipeline converts
+ * these to clip-relative offsets so keyboard SFX fire in lock-step with the
+ * visible typing.
  */
 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);
+        if (options.onKeystroke) {
+            options.onKeystroke(Date.now());
+        }
         // 60–120 WPM → ~80–130ms between characters (5 chars per word)
         const delay = minDelay + Math.random() * (maxDelay - minDelay);
         if (delay > 0) {

package/dist/opcode-actions.d.ts

@@ -40,5 +40,11 @@ export declare function findUnresolvedCredentialPlaceholders(text: string, crede
 export interface OpcodeActionResult {
     success: boolean;
     error?: string;
+    /**
+     * For TYPE opcodes: absolute wall-clock timestamps (`Date.now()`) of each
+     * keystroke produced by `humanType`. The runner converts these to
+     * clip-relative offsets so the video compositor can fire per-keystroke SFX.
+     */
+    keystrokeTimestampsMs?: number[];
 }
 export declare function executeOpcodeCoreAction(opcode: ExecutionOpcode, adapter: RuntimeAdapter, context?: OpcodeActionContext): Promise<OpcodeActionResult>;

package/dist/opcode-actions.js

@@ -81,8 +81,12 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                     ? opcode.textByLocale[context.currentVariant.locale] ?? opcode.text
                     : opcode.text);
                 const text = substituteCredentialPlaceholders(rawText, context.credentials);
+                const keystrokeTimestampsMs = [];
+                const onKeystroke = (timestampMs) => {
+                    keystrokeTimestampsMs.push(timestampMs);
+                };
                 try {
-                    await adapter.type(opcode.selector, text, opcode.clearFirst);
+                    await adapter.type(opcode.selector, text, opcode.clearFirst, { onKeystroke });
                 }
                 catch (error) {
                     if (!opcode.target || !adapter.typeByTarget)
@@ -91,9 +95,9 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                         selector: opcode.selector,
                         target: opcode.target,
                         selectorAlternates: opcode.selectorAlternates,
-                    }, text, opcode.clearFirst);
+                    }, text, opcode.clearFirst, { onKeystroke });
                 }
-                break;
+                return { success: true, keystrokeTimestampsMs };
             }
             case 'PRESS_KEY':
                 await adapter.pressKey(opcode.key);

package/dist/opcode-runner.js

@@ -287,6 +287,9 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
         const result = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), actionBudgetMs);
         logger.debug(`[opcode ${index}] action exec end — took ${Date.now() - actionStart}ms, success=${result.success}${result.error ? `, error=${result.error}` : ''}`);
         if (preTiming) {
+            const keystrokeOffsetsMs = result.keystrokeTimestampsMs && result.keystrokeTimestampsMs.length > 0
+                ? result.keystrokeTimestampsMs.map((t) => Math.max(0, t - preTiming.clipStartedAt))
+                : undefined;
             opcodeTimings.push({
                 stepIndex: index,
                 stepId: opcode.stepId,
@@ -296,6 +299,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
                 timecodeStartMs: preTiming.timecodeStartMs,
                 timecodeEndMs: Math.max(0, Date.now() - preTiming.clipStartedAt),
                 bbox: preTiming.bbox,
+                ...(keystrokeOffsetsMs ? { keystrokeOffsetsMs } : {}),
             });
         }
         if (!result.success) {

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

@@ -38,7 +38,9 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
     /**
      * Type into an element using semantic target resolution.
      */
-    typeByTarget(opts: ResolveOptions, text: string, clearFirst?: boolean): Promise<void>;
+    typeByTarget(opts: ResolveOptions, text: string, clearFirst?: boolean, typeOpts?: {
+        onKeystroke?: (timestampMs: number) => void;
+    }): Promise<void>;
     /**
      * Wait for an element using semantic target resolution.
      */
@@ -47,7 +49,9 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
      * Scroll an element into view using semantic target resolution.
      */
     scrollIntoViewByTarget(opts: ResolveOptions): Promise<void>;
-    type(selector: string, text: string, clearFirst?: boolean): Promise<void>;
+    type(selector: string, text: string, clearFirst?: boolean, opts?: {
+        onKeystroke?: (timestampMs: number) => void;
+    }): Promise<void>;
     pressKey(key: string): Promise<void>;
     scroll(direction: 'up' | 'down' | 'left' | 'right', amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;

package/dist/web-playwright-local.js

@@ -152,14 +152,14 @@ export class WebPlaywrightLocal {
     /**
      * Type into an element using semantic target resolution.
      */
-    async typeByTarget(opts, text, clearFirst = true) {
+    async typeByTarget(opts, text, clearFirst = true, typeOpts) {
         const page = await this.browser.currentPage;
         const resolved = await resolveTarget(page, opts);
         if (!resolved) {
             throw new Error(`cannot find target for typing: ${describeResolveOptions(opts)}`);
         }
         if (this.clipCursor) {
-            await this.typeIntoLocator(resolved.locator, text, clearFirst);
+            await this.typeIntoLocator(resolved.locator, text, clearFirst, typeOpts?.onKeystroke);
             return;
         }
         if (clearFirst) {
@@ -196,10 +196,10 @@ export class WebPlaywrightLocal {
         }
         await resolved.locator.scrollIntoViewIfNeeded({ timeout: 5000 });
     }
-    async type(selector, text, clearFirst = true) {
+    async type(selector, text, clearFirst = true, opts) {
         if (this.clipCursor) {
             const page = await this.browser.currentPage;
-            await this.typeIntoLocator(page.locator(selector).first(), text, clearFirst);
+            await this.typeIntoLocator(page.locator(selector).first(), text, clearFirst, opts?.onKeystroke);
             return;
         }
         await this.browser.typeText(text, { selector, clearFirst });
@@ -878,7 +878,7 @@ export class WebPlaywrightLocal {
     async close() {
         await this.browser.close();
     }
-    async typeIntoLocator(locator, text, clearFirst) {
+    async typeIntoLocator(locator, text, clearFirst, onKeystroke) {
         const page = await this.browser.currentPage;
         await locator.waitFor({ state: 'visible', timeout: 5000 });
         await locator.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => undefined);
@@ -895,8 +895,8 @@ export class WebPlaywrightLocal {
         }
         await page.waitForTimeout(70);
         await humanType(page, text, this.clipCursor
-            ? { minDelayMs: 20, maxDelayMs: 45 }
-            : undefined);
+            ? { minDelayMs: 20, maxDelayMs: 45, onKeystroke }
+            : { onKeystroke });
     }
     async seedClipCursor(position) {
         if (!this.clipCursor)

package/package.json

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