autokap 1.2.0 → 1.3.1

package/dist/execution-schema.js

@@ -53,12 +53,24 @@ export const RecoveryPolicySchema = z.object({
     allowHealer: z.boolean(),
 }).strict();
 // ── Opcode base fields ──────────────────────────────────────────────
+/**
+ * Stable identifier used to anchor narration overlays in `mediaMode='video'`
+ * runs. Constraints (per AUT-57 R8 mitigation):
+ *   - kebab-case lowercase ASCII: `[a-z0-9-]+`
+ *   - 1..64 characters
+ *   - optional everywhere; required only on opcodes whose narration must
+ *     survive program rewrites during run-time speech generation.
+ */
+const StepIdSchema = z.string().regex(/^[a-z0-9-]+$/, {
+    message: 'stepId must match /^[a-z0-9-]+$/ (lowercase kebab-case)',
+}).min(1).max(64);
 const opcodeBase = {
     description: z.string().min(1),
     postcondition: PostconditionSpecSchema,
     recovery: RecoveryPolicySchema,
     timeoutMs: z.number().int().positive(),
     maxFailures: z.number().int().positive(),
+    stepId: StepIdSchema.optional(),
 };
 /**
  * Strict URL validator: rejects schemes without a host (e.g. `"https://"`),
@@ -145,6 +157,32 @@ const WaitForOpcodeSchema = z.object({
         });
     }
 });
+const SleepOpcodeSchema = z.object({
+    kind: z.literal('SLEEP'),
+    ...opcodeBase,
+    /** 1ms..60s. The video run step produces these from audio durations. */
+    durationMs: z.number().int().min(1).max(60_000),
+    /**
+     * Spoken narration to play during this pause (AUT-57 anchor). Authored by
+     * the IDE assistant — it has full project context (real product copy,
+     * design system, etc.) and writes natural conversational lines. The
+     * run-time TTS step renders the text and rewrites `durationMs` to match the
+     * resulting audio length. Required when `stepId` is set; ignored when
+     * `stepId` is absent (decorative pause without narration).
+     */
+    narrationText: z.string().min(1).max(2000).optional(),
+    narrationTextByLocale: z.record(z.string().min(1).max(16), z.string().min(1).max(2000)).optional(),
+}).strict().superRefine((value, ctx) => {
+    const hasLocaleText = value.narrationTextByLocale
+        && Object.values(value.narrationTextByLocale).some((text) => text.trim().length > 0);
+    if (value.stepId && (!value.narrationText || !value.narrationText.trim()) && !hasLocaleText) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['narrationText'],
+            message: 'SLEEP anchors with a stepId must carry `narrationText` or `narrationTextByLocale` — the IDE assistant authors the spoken line; AutoKap will TTS it at run time and rewrite durationMs.',
+        });
+    }
+});
 const storageHintSchema = z.object({
     storage: z.enum(['localStorage', 'sessionStorage', 'cookie']),
     key: z.string().min(1),
@@ -392,6 +430,7 @@ export const ExecutionOpcodeSchema = z.discriminatedUnion('kind', [
     TypeOpcodeSchema,
     PressKeyOpcodeSchema,
     WaitForOpcodeSchema,
+    SleepOpcodeSchema,
     SetLocaleOpcodeSchema,
     SetThemeOpcodeSchema,
     ScrollOpcodeSchema,
@@ -526,22 +565,48 @@ export const PreconditionSpecSchema = z.object({
     cookies: z.array(cookieSchema).optional(),
 }).strict();
 // ── Artifact spec ───────────────────────────────────────────────────
+const ResolutionSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+}).strict();
+const DEFAULT_VIDEO_DELIVERY_RESOLUTION = { width: 1920, height: 1080 };
+const LEGACY_VIDEO_CAPTURE_RESOLUTION = { width: 2560, height: 1440 };
+function resolutionEquals(a, b) {
+    return a.width === b.width && a.height === b.height;
+}
 export const ArtifactSpecSchema = z.object({
-    mediaMode: z.enum(['screenshot', 'clip']),
+    mediaMode: z.enum(['screenshot', 'clip', 'video']),
     format: z.object({
         clipFormat: z.enum(['gif', 'mp4', 'both']).optional(),
         screenshotFormat: z.enum(['png', 'jpeg']).optional(),
+        captureResolution: ResolutionSchema.optional(),
+        captureFps: z.number().int().min(1).max(60).optional(),
+        deliveryResolution: ResolutionSchema.optional(),
     }).strict().optional(),
     cursorTheme: z.enum(['minimal', 'macos', 'windows']).optional(),
     maxClipDurationSec: z.number().positive().optional(),
     applyMockup: z.boolean().optional(),
     applyStatusBar: z.boolean().optional(),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    if (value.mediaMode === 'video') {
+        const res = value.format?.captureResolution;
+        const matchesDefault = res ? resolutionEquals(res, DEFAULT_VIDEO_DELIVERY_RESOLUTION) : false;
+        const matchesLegacy = res ? resolutionEquals(res, LEGACY_VIDEO_CAPTURE_RESOLUTION) : false;
+        if (!res || (!matchesDefault && !matchesLegacy)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['format', 'captureResolution'],
+                message: "mediaMode='video' requires format.captureResolution = { width: 1920, height: 1080 }; " +
+                    'legacy 2560x1440 programs are accepted and normalized at runtime',
+            });
+        }
+    }
+});
 // ── Full program ────────────────────────────────────────────────────
 export const ExecutionProgramSchema = z.object({
     presetId: z.string().min(1),
     programVersion: z.number().int().positive(),
-    mediaMode: z.enum(['screenshot', 'clip']),
+    mediaMode: z.enum(['screenshot', 'clip', 'video']),
     baseUrl: StrictUrlSchema,
     maxParallelCaptures: z.number().int().positive().optional(),
     variants: z.array(VariantSpecSchema).min(1),
@@ -554,7 +619,15 @@ export const ExecutionProgramSchema = z.object({
     compiledAt: z.string().datetime(),
     compiledWith: z.string().optional(),
     mockDataGroups: z.array(MockDataGroupSchema).optional(),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    if (value.mediaMode !== value.artifactPlan.mediaMode) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['artifactPlan', 'mediaMode'],
+            message: `artifactPlan.mediaMode (${value.artifactPlan.mediaMode}) must match top-level mediaMode (${value.mediaMode})`,
+        });
+    }
+});
 // ── Healer patch ────────────────────────────────────────────────────
 export const HealerPatchSchema = z.object({
     opcodeIndex: z.number().int().min(0),

package/dist/execution-types.d.ts

@@ -8,7 +8,7 @@ import type { AKTree, BrowserStorageState, BrowserSessionStorageState, VideoCurs
 import type { MockupOptions } from './mockup.js';
 /** Sentinel value that resolves to the current variant's locale or theme at runtime */
 export declare const VARIANT_PLACEHOLDER: "$variant";
-export declare const OPCODE_KINDS: readonly ["NAVIGATE", "DISMISS_OVERLAYS", "ASSERT_ROUTE", "ASSERT_SURFACE", "CLICK", "TYPE", "PRESS_KEY", "WAIT_FOR", "SET_LOCALE", "SET_THEME", "SCROLL", "CAPTURE_SCREENSHOT", "BEGIN_CLIP", "END_CLIP", "HOVER", "SELECT_OPTION", "CHECK", "DOUBLE_CLICK", "DRAG", "CLONE_ELEMENT", "INJECT_MOCK_DATA", "REMOVE_ELEMENT", "SET_ATTRIBUTE"];
+export declare const OPCODE_KINDS: readonly ["NAVIGATE", "DISMISS_OVERLAYS", "ASSERT_ROUTE", "ASSERT_SURFACE", "CLICK", "TYPE", "PRESS_KEY", "WAIT_FOR", "SLEEP", "SET_LOCALE", "SET_THEME", "SCROLL", "CAPTURE_SCREENSHOT", "BEGIN_CLIP", "END_CLIP", "HOVER", "SELECT_OPTION", "CHECK", "DOUBLE_CLICK", "DRAG", "CLONE_ELEMENT", "INJECT_MOCK_DATA", "REMOVE_ELEMENT", "SET_ATTRIBUTE"];
 export type OpcodeKind = (typeof OPCODE_KINDS)[number];
 /**
  * Soft opcodes are non-blocking — if their action or postcondition fails at
@@ -109,6 +109,13 @@ interface OpcodeBase {
     timeoutMs: number;
     /** Max recovery attempts before this opcode is considered failed. Default: 3 */
     maxFailures: number;
+    /**
+     * Stable identifier used to anchor narration overlays in `mediaMode='video'`
+     * runs. Kebab-case, 1-64 chars. Optional — only required for opcodes whose
+     * narration segment must survive program rewrites (e.g. WAIT_FOR insertions
+     * before run-time speech generation). Ignored in `screenshot` and `clip` modes.
+     */
+    stepId?: string;
 }
 export interface NavigateOpcode extends OpcodeBase {
     kind: 'NAVIGATE';
@@ -170,6 +177,32 @@ export interface WaitForOpcode extends OpcodeBase {
     /** 'visible' = element visible in viewport, 'attached' = exists in DOM. Default: 'visible' */
     state: 'visible' | 'attached';
 }
+/**
+ * Pause execution for a fixed duration. Used by the video run-time TTS step to
+ * align visible actions with the narration audio window. Postcondition is
+ * implicitly `always` — the runtime sleeps then advances.
+ */
+export interface SleepOpcode extends OpcodeBase {
+    kind: 'SLEEP';
+    /** Sleep duration in milliseconds. Capped at 60_000 by the schema. */
+    durationMs: number;
+    /**
+     * Spoken narration to play during this pause (AUT-57 anchor). Authored by
+     * the IDE assistant — it has full project context (real product copy,
+     * design system, etc.) and writes natural conversational lines. The
+     * run-time TTS step renders the text and rewrites `durationMs` to match the
+     * resulting audio length. Required when `stepId` is set; ignored when
+     * `stepId` is absent (decorative pause without narration).
+     */
+    narrationText?: string;
+    /**
+     * Locale-keyed spoken narration overrides for multivariant demo videos.
+     * Keys are BCP-47-ish locale tags such as `en`, `fr`, `fr-FR`. At prepare
+     * time AutoKap first tries the exact current locale, then its primary
+     * language subtag. `narrationText` remains the single-locale legacy fallback.
+     */
+    narrationTextByLocale?: Record<string, string>;
+}
 export interface SetLocaleOpcode extends OpcodeBase {
     kind: 'SET_LOCALE';
     /** Target BCP-47 locale (e.g. "fr", "en-US") */
@@ -390,7 +423,7 @@ export interface SetAttributeOpcode extends OpcodeBase {
     /** Attribute value */
     value: string;
 }
-export type ExecutionOpcode = NavigateOpcode | DismissOverlaysOpcode | AssertRouteOpcode | AssertSurfaceOpcode | ClickOpcode | TypeOpcode | PressKeyOpcode | WaitForOpcode | SetLocaleOpcode | SetThemeOpcode | ScrollOpcode | CaptureScreenshotOpcode | BeginClipOpcode | EndClipOpcode | HoverOpcode | SelectOptionOpcode | CheckOpcode | DoubleClickOpcode | DragOpcode | CloneElementOpcode | InjectMockDataOpcode | RemoveElementOpcode | SetAttributeOpcode;
+export type ExecutionOpcode = NavigateOpcode | DismissOverlaysOpcode | AssertRouteOpcode | AssertSurfaceOpcode | ClickOpcode | TypeOpcode | PressKeyOpcode | WaitForOpcode | SleepOpcode | SetLocaleOpcode | SetThemeOpcode | ScrollOpcode | CaptureScreenshotOpcode | BeginClipOpcode | EndClipOpcode | HoverOpcode | SelectOptionOpcode | CheckOpcode | DoubleClickOpcode | DragOpcode | CloneElementOpcode | InjectMockDataOpcode | RemoveElementOpcode | SetAttributeOpcode;
 export interface VariantSpec {
     id: string;
     viewport: {
@@ -452,7 +485,7 @@ export interface PreconditionSpec {
         path?: string;
     }>;
 }
-export declare const MEDIA_MODES: readonly ["screenshot", "clip"];
+export declare const MEDIA_MODES: readonly ["screenshot", "clip", "video"];
 export type MediaMode = (typeof MEDIA_MODES)[number];
 export interface ArtifactSpec {
     mediaMode: MediaMode;
@@ -462,10 +495,34 @@ export interface ArtifactSpec {
         clipFormat?: 'gif' | 'mp4' | 'both';
         /** For screenshots: 'png' | 'jpeg'. Default: 'png' */
         screenshotFormat?: 'png' | 'jpeg';
+        /**
+         * Physical capture surface used while recording. Required when
+         * `mediaMode='video'` and fixed at the delivery frame (1920×1080).
+         * Legacy 2560×1440 programs are accepted for compatibility and normalized
+         * by the CLI before recording.
+         */
+        captureResolution?: {
+            width: number;
+            height: number;
+        };
+        /**
+         * Frame rate used by the capture loop. Defaults to platform-tuned values
+         * for `clip` (8 Linux / 15 elsewhere). For `mediaMode='video'` the runtime
+         * pins this to 30 fps unless explicitly overridden.
+         */
+        captureFps?: number;
+        /**
+         * Final delivery resolution after compositing. Defaults to 1920×1080 for
+         * `mediaMode='video'`.
+         */
+        deliveryResolution?: {
+            width: number;
+            height: number;
+        };
     };
     /** Cursor style for clip recordings. Default: 'minimal'. */
     cursorTheme?: VideoCursorTheme;
-    /** Max clip duration in seconds. Clips are trimmed if they exceed this. Default: 8. */
+    /** Max clip duration in seconds. Clips are trimmed if they exceed this. Default: 8. Ignored when `mediaMode='video'`. */
     maxClipDurationSec?: number;
     /** Whether to apply device frame mockup. Default: false */
     applyMockup?: boolean;
@@ -613,6 +670,30 @@ export interface RunTelemetry {
     /** Per-group mock data application result */
     mockDataGroupResults?: Record<string, 'applied' | 'skipped'>;
 }
+/**
+ * Per-opcode timing entry emitted when `mediaMode='video'`. Consumed by the
+ * compositor and telemetry tooling to align narration overlays and retain
+ * interaction metadata. `bbox` is captured BEFORE the action runs (the
+ * targeted element may move or disappear after).
+ */
+export interface OpcodeTiming {
+    stepIndex: number;
+    stepId?: string;
+    opcodeKind: OpcodeKind;
+    variantId: string;
+    /** clipId of the active BEGIN_CLIP context, if any */
+    clipId?: string;
+    /** Wall-clock ms relative to the start of the active clip recording */
+    timecodeStartMs: number;
+    timecodeEndMs: number;
+    /** Bounding box of the targeted element at action time (page coords). null if no DOM target. */
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
 export interface RunResult {
     programId: string;
     success: boolean;
@@ -622,6 +703,11 @@ export interface RunResult {
     healerPatches: HealerPatch[];
     /** Total run duration (ms) */
     totalDurationMs: number;
+    /**
+     * Per-opcode timing entries — populated when `mediaMode='video'`. Empty
+     * array for `screenshot` and `clip` modes.
+     */
+    opcodeTimings: OpcodeTiming[];
     error?: string;
 }
 export interface WaitCondition {
@@ -645,7 +731,17 @@ export interface ClickOptions {
     button?: 'left' | 'right' | 'middle';
 }
 export interface RecordingOptions {
-    mediaMode: 'clip';
+    mediaMode: 'clip' | 'video';
+    /**
+     * Physical recording surface. Video capture records the delivery surface
+     * directly (1920×1080 by default).
+     */
+    captureResolution?: {
+        width: number;
+        height: number;
+    };
+    /** Override the capture loop frame rate. Clamped to 1..30 by the loop. */
+    captureFps?: number;
 }
 export interface RecordingResult {
     buffer: Buffer;
@@ -673,6 +769,19 @@ export interface RuntimeAdapter {
     takeCleanScreenshot(): Promise<Buffer>;
     beginRecording(options: RecordingOptions): Promise<void>;
     endRecording(): Promise<RecordingResult>;
+    /**
+     * Page-coord bounding box of the first element matching `selector`. Returns
+     * null if the selector does not match a visible element. Used by the
+     * `mediaMode='video'` runtime to capture interaction metadata before each
+     * visible action. Optional — implementations that cannot resolve a bbox
+     * should leave this method off and the runtime will record `bbox: null`.
+     */
+    getElementBoundingBox?(selector: string): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
     setLocale(locale: string): Promise<void>;
     setColorScheme(scheme: 'light' | 'dark'): Promise<void>;
     reloadPage?(): Promise<void>;

package/dist/execution-types.js

@@ -16,6 +16,7 @@ export const OPCODE_KINDS = [
     'TYPE',
     'PRESS_KEY',
     'WAIT_FOR',
+    'SLEEP',
     'SET_LOCALE',
     'SET_THEME',
     'SCROLL',
@@ -55,7 +56,7 @@ export const DEFAULT_RECOVERY_POLICY = {
     allowHealer: false,
 };
 // ── Artifact spec ───────────────────────────────────────────────────
-export const MEDIA_MODES = ['screenshot', 'clip'];
+export const MEDIA_MODES = ['screenshot', 'clip', 'video'];
 export const DEFAULT_CIRCUIT_BREAKER = {
     maxPerOpcode: 3,
     maxPerPage: 5,

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export type { ExecutionProgram, ExecutionOpcode, OpcodeKind, SemanticTarget, PostconditionSpec, PostconditionType, RecoveryPolicy, VariantSpec, PreconditionSpec, ArtifactSpec, MediaMode, CircuitBreakerConfig, HealerPatch, OpcodeResult, OpcodeResultStatus, VariantResult, ArtifactResult, RunResult, RunTelemetry, LLMStepUsage, LLMStepType, RuntimeAdapter, ClickOptions, WaitCondition, RecordingOptions, RecordingResult, HoverOpcode, SelectOptionOpcode, CheckOpcode, DoubleClickOpcode, CloneElementOpcode, InjectMockDataOpcode, RemoveElementOpcode, SetAttributeOpcode, MockDataSlot, MockDataRow, MockDataGroup, } from './execution-types.js';
+export type { ExecutionProgram, ExecutionOpcode, OpcodeKind, SemanticTarget, PostconditionSpec, PostconditionType, RecoveryPolicy, VariantSpec, PreconditionSpec, ArtifactSpec, MediaMode, CircuitBreakerConfig, HealerPatch, OpcodeResult, OpcodeResultStatus, VariantResult, ArtifactResult, RunResult, RunTelemetry, LLMStepUsage, LLMStepType, RuntimeAdapter, ClickOptions, WaitCondition, RecordingOptions, RecordingResult, OpcodeTiming, HoverOpcode, SelectOptionOpcode, CheckOpcode, DoubleClickOpcode, CloneElementOpcode, InjectMockDataOpcode, RemoveElementOpcode, SetAttributeOpcode, MockDataSlot, MockDataRow, MockDataGroup, } from './execution-types.js';
 export { DEFAULT_RECOVERY_POLICY, DEFAULT_CIRCUIT_BREAKER, VARIANT_PLACEHOLDER, SOFT_OPCODE_KINDS, isSoftOpcodeKind, } from './execution-types.js';
 export { ExecutionProgramSchema, ExecutionOpcodeSchema, parseProgram, parseOpcode, safeParseProgramResult, MockDataSlotSchema, MockDataRowSchema, MockDataGroupSchema, } from './execution-schema.js';
+export { NarrationSegmentSchema, VideoNarrationOverlaySchema, VideoIngestPayloadSchema, parseVideoIngestPayload, SUPPORTED_TTS_LOCALES, normalizeLocaleTag, primaryLocaleSubtag, resolveSupportedTtsLocale, VIDEO_STATUSES, VIDEO_FLOW_KIND_OPCODE, VIDEO_FLOW_KIND_LEGACY, } from './video-narration-schema.js';
+export type { NarrationSegment, VideoNarrationOverlay, VideoIngestPayload, SupportedTtsLocale, VideoStatus, } from './video-narration-schema.js';
+export { generateTtsChunk, probeAudioDurationMs, ttsTestHooks, TtsError, } from './openrouter-tts.js';
+export type { TtsClientConfig, TtsRequest, TtsResponse, TtsResponseFormat, } from './openrouter-tts.js';
 export { callLLM } from './llm-provider.js';
 export type { LLMProviderConfig, LLMCallResult } from './llm-provider.js';
 export { normalizeAllowedOrigins, normalizeHttpOrigin, signExecutionProgramEnvelope, verifySignedExecutionProgramEnvelope, } from './program-signing.js';

package/dist/index.js

@@ -4,6 +4,8 @@
 // Server-side callers must use specific subpaths (ESLint enforces this).
 export { DEFAULT_RECOVERY_POLICY, DEFAULT_CIRCUIT_BREAKER, VARIANT_PLACEHOLDER, SOFT_OPCODE_KINDS, isSoftOpcodeKind, } from './execution-types.js';
 export { ExecutionProgramSchema, ExecutionOpcodeSchema, parseProgram, parseOpcode, safeParseProgramResult, MockDataSlotSchema, MockDataRowSchema, MockDataGroupSchema, } from './execution-schema.js';
+export { NarrationSegmentSchema, VideoNarrationOverlaySchema, VideoIngestPayloadSchema, parseVideoIngestPayload, SUPPORTED_TTS_LOCALES, normalizeLocaleTag, primaryLocaleSubtag, resolveSupportedTtsLocale, VIDEO_STATUSES, VIDEO_FLOW_KIND_OPCODE, VIDEO_FLOW_KIND_LEGACY, } from './video-narration-schema.js';
+export { generateTtsChunk, probeAudioDurationMs, ttsTestHooks, TtsError, } from './openrouter-tts.js';
 // ── LLM-backed helpers (OpenAI, no browser) ─────────────────────────
 export { callLLM } from './llm-provider.js';
 export { normalizeAllowedOrigins, normalizeHttpOrigin, signExecutionProgramEnvelope, verifySignedExecutionProgramEnvelope, } from './program-signing.js';

package/dist/mouse-animation.d.ts

@@ -1,10 +1,20 @@
 import type { Page } from 'playwright';
 export interface BezierMoveOptions {
-    /** Total duration in milliseconds. Default: proportional to distance (300–800ms) */
+    /** Total duration in milliseconds. Default: proportional to distance + pace. */
     durationMs?: number;
-    /** Number of intermediate points. Default: 30 */
+    /** Number of intermediate points. Default: derived from durationMs (one step per 16ms). */
     steps?: number;
+    /**
+     * Pace profile when `durationMs` is not explicit. AUT-57 video demos use
+     * `'natural'` for deliberate, human-readable cursor motion; the default
+     * `'fast'` keeps short clip GIFs snappy.
+     *
+     * Both profiles use the same √distance · factor formula but different
+     * (min, max, factor) tuples — see `paceProfile`.
+     */
+    pace?: BezierMovePace;
 }
+export type BezierMovePace = 'fast' | 'natural';
 /**
  * Move the mouse from `from` to `to` along a cubic Bezier curve with
  * smooth controlled motion: ease-in-out timing, gentle proportional curves.

package/dist/mouse-animation.js

@@ -1,3 +1,29 @@
+const FAST_PROFILE = {
+    minMs: 80,
+    maxMs: 700,
+    factor: 28,
+    hoverPauseMs: { min: 80, max: 160 },
+    pressMs: 70,
+    hoverDwellMs: { min: 200, max: 400 },
+};
+/**
+ * Natural pace — used by `mediaMode='video'` demos. The min floor is high
+ * enough that *any* cursor move reads as deliberate (a flash to a 100px-away
+ * nav link still takes >500ms), the cap leaves long traverses at ~1.5s
+ * (further than that drags), and the post-arrival beats are wider so each
+ * click feels like a real person committing to it.
+ */
+const NATURAL_PROFILE = {
+    minMs: 600,
+    maxMs: 1500,
+    factor: 50,
+    hoverPauseMs: { min: 200, max: 350 },
+    pressMs: 90,
+    hoverDwellMs: { min: 400, max: 700 },
+};
+function paceProfile(pace) {
+    return pace === 'natural' ? NATURAL_PROFILE : FAST_PROFILE;
+}
 /** Ease-in-out cubic timing function */
 function easeInOut(t) {
     return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
@@ -23,7 +49,9 @@ export async function moveMouse(page, from, to, options = {}) {
     const distance = Math.sqrt(dx * dx + dy * dy);
     if (distance < 2)
         return; // Already there
-    const durationMs = options.durationMs ?? Math.min(700, Math.max(80, Math.sqrt(distance) * 28));
+    const profile = paceProfile(options.pace);
+    const durationMs = options.durationMs
+        ?? Math.min(profile.maxMs, Math.max(profile.minMs, Math.sqrt(distance) * profile.factor));
     const steps = options.steps ?? Math.max(4, Math.ceil(durationMs / 16));
     const msPerStep = durationMs / steps;
     // Control points: straight line for short moves, gentle proportional arc for longer ones.
@@ -74,30 +102,32 @@ export async function moveMouse(page, from, to, options = {}) {
  *   is performed at `target` without a preceding Bezier move (first action).
  */
 export async function animatedClick(page, target, fromCurrent, options = {}) {
+    const profile = paceProfile(options.pace);
     if (fromCurrent) {
         await moveMouse(page, fromCurrent, target, options);
     }
     else {
         await page.mouse.move(target.x, target.y);
     }
-    // Brief hover pause before clicking (human-like)
-    await page.waitForTimeout(80 + Math.random() * 80);
+    const hoverSpread = profile.hoverPauseMs.max - profile.hoverPauseMs.min;
+    await page.waitForTimeout(profile.hoverPauseMs.min + Math.random() * hoverSpread);
     await page.mouse.down();
-    await page.waitForTimeout(70);
+    await page.waitForTimeout(profile.pressMs);
     await page.mouse.up();
 }
 /**
  * Move the mouse to `target` (for hover/highlight actions) without clicking.
  */
 export async function animatedHover(page, target, fromCurrent, options = {}) {
+    const profile = paceProfile(options.pace);
     if (fromCurrent) {
         await moveMouse(page, fromCurrent, target, options);
     }
     else {
         await page.mouse.move(target.x, target.y);
     }
-    // Brief pause at hover position
-    await page.waitForTimeout(200 + Math.random() * 200);
+    const dwellSpread = profile.hoverDwellMs.max - profile.hoverDwellMs.min;
+    await page.waitForTimeout(profile.hoverDwellMs.min + Math.random() * dwellSpread);
 }
 /**
  * Type text into the currently focused element at a human-like typing speed.

package/dist/opcode-actions.d.ts

@@ -7,6 +7,8 @@
 import type { ExecutionOpcode, MockDataGroup, RuntimeAdapter, VariantSpec } from './execution-types.js';
 export interface OpcodeActionContext {
     currentVariant?: VariantSpec;
+    /** Disallow opcodes that would reload the page while a clip is being recorded. */
+    suppressPageReloads?: boolean;
     /** Mock data groups available to INJECT_MOCK_DATA. Plumbed from ExecutionProgram. */
     mockDataGroups?: MockDataGroup[];
     /**

package/dist/opcode-actions.js

@@ -121,10 +121,19 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                 }
                 break;
             }
+            case 'SLEEP': {
+                // Hold execution for the configured duration. Demo video runs rewrite
+                // narration anchors before execution so visible actions align with
+                // audio windows. The opcode `timeoutMs` budget is independent — schema
+                // pins durationMs to 60s and the runner gives us a slightly larger
+                // budget so the await doesn't trip the per-opcode deadline.
+                await new Promise((resolve) => setTimeout(resolve, opcode.durationMs));
+                break;
+            }
             case 'SET_LOCALE':
-                return applyLocaleOpcode(opcode, adapter, context.currentVariant);
+                return applyLocaleOpcode(opcode, adapter, context.currentVariant, context.suppressPageReloads);
             case 'SET_THEME':
-                return applyThemeOpcode(opcode, adapter, context.currentVariant);
+                return applyThemeOpcode(opcode, adapter, context.currentVariant, context.suppressPageReloads);
             case 'SCROLL':
                 if (opcode.targetSelector) {
                     await adapter.scrollIntoView(opcode.targetSelector);
@@ -252,16 +261,25 @@ function resolveStorageHintValues(hints, replacement, fieldName) {
     }
     return { resolvedHints };
 }
-async function applyLocaleOpcode(opcode, adapter, currentVariant) {
+async function applyLocaleOpcode(opcode, adapter, currentVariant, suppressPageReloads = false) {
     const localeResult = resolveVariantPlaceholder(opcode.locale, currentVariant?.locale, 'SET_LOCALE.locale');
     if ('error' in localeResult)
         return { success: false, error: localeResult.error };
     const resolvedLocale = localeResult.resolved;
     if (opcode.method === 'browser_context') {
-        await adapter.setLocale(resolvedLocale);
         if (adapter.reloadPage) {
+            if (suppressPageReloads) {
+                return {
+                    success: false,
+                    error: 'SET_LOCALE browser_context would reload during active recording; move it before BEGIN_CLIP',
+                };
+            }
+            await adapter.setLocale(resolvedLocale);
             await adapter.reloadPage();
         }
+        else {
+            await adapter.setLocale(resolvedLocale);
+        }
         return { success: true };
     }
     if (opcode.method === 'ui_interaction') {
@@ -278,6 +296,14 @@ async function applyLocaleOpcode(opcode, adapter, currentVariant) {
     if ('error' in resolvedHints) {
         return { success: false, error: resolvedHints.error };
     }
+    if (adapter.reloadPage) {
+        if (suppressPageReloads) {
+            return {
+                success: false,
+                error: 'SET_LOCALE storage mode would reload during active recording; move it before BEGIN_CLIP',
+            };
+        }
+    }
     const writes = await Promise.all(resolvedHints.resolvedHints.map((hint) => adapter.writeStorageHint({
         storage: hint.storage,
         key: hint.key,
@@ -482,7 +508,7 @@ async function applyInjectMockDataTriggerStrategy(opcode, adapter, group) {
     });
     return { success: true };
 }
-async function applyThemeOpcode(opcode, adapter, currentVariant) {
+async function applyThemeOpcode(opcode, adapter, currentVariant, suppressPageReloads = false) {
     const themeResult = resolveVariantPlaceholder(opcode.theme, currentVariant?.theme, 'SET_THEME.theme');
     if ('error' in themeResult)
         return { success: false, error: themeResult.error };
@@ -505,6 +531,14 @@ async function applyThemeOpcode(opcode, adapter, currentVariant) {
     if ('error' in resolvedHints) {
         return { success: false, error: resolvedHints.error };
     }
+    if (adapter.reloadPage) {
+        if (suppressPageReloads) {
+            return {
+                success: false,
+                error: 'SET_THEME storage mode would reload during active recording; move it before BEGIN_CLIP',
+            };
+        }
+    }
     const writes = await Promise.all(resolvedHints.resolvedHints.map((hint) => adapter.writeStorageHint({
         storage: hint.storage,
         key: hint.key,

package/dist/opcode-runner.d.ts

@@ -21,6 +21,8 @@ export interface RecoveryAttemptOptions {
     remainingTimeMs?: number;
     maxDeterministicRetries?: number;
     currentVariant?: VariantSpec;
+    allowPageReload?: boolean;
+    suppressPageReloads?: boolean;
 }
 /** Default recovery chain for consumers that do not inject one. */
 export declare class NoOpRecoveryChain implements RecoveryChain {