autokap 1.8.8 → 1.9.0

package/dist/cli-contract.d.ts

@@ -117,6 +117,8 @@ export type ArtifactUploadObjectId = "screenshotRaw" | "screenshot" | "clipGif"
 export interface ArtifactUploadMetadata {
     presetId: string;
     runId: string;
+    /** Per-invocation session id grouping every charge of one CLI run (migration 267). */
+    sessionId?: string | null;
     variantId: string;
     targetId?: string | null;
     targetLabel?: string | null;

package/dist/cli-runner.d.ts

@@ -49,6 +49,13 @@ export interface CLIRunnerOptions {
      * When `false`, skips the failed-run debug logs export (AUT-149).
      */
     exportDebugLogs?: boolean;
+    /**
+     * Shared invocation id for billing. A multi-preset invocation (`run --outdated`,
+     * `auto-recapture`) passes one sessionId for every preset so all their charges
+     * group into a single "CLI capture" entry (migration 267). Defaults to the
+     * run's own id for a single-preset invocation.
+     */
+    sessionId?: string;
 }
 export interface CLIRunResult {
     success: boolean;
@@ -58,3 +65,4 @@ export interface CLIRunResult {
 }
 export declare function runCapture(options: CLIRunnerOptions): Promise<CLIRunResult>;
 export declare function buildVideoClipMetadata(videoId: string, result: RunResult, program?: ExecutionProgram, runId?: string): VideoClipMetadata[];
+export declare function resolveEffectiveCliArtifactPlan(artifactPlan: ExecutionProgram['artifactPlan'], deviceFrame?: string | null): ExecutionProgram['artifactPlan'];

package/dist/cli-runner.js

@@ -25,7 +25,7 @@ import { parseProgram } from './execution-schema.js';
 import { buildCursorOverlayScript } from './cursor-overlay-script.js';
 import { CLI_VERSION_HEADER, } from './cli-contract.js';
 import { postProcessClipRecording } from './clip-postprocess.js';
-import { applyDeviceFrame, seedDeviceConfigs } from './mockup.js';
+import { applyDeviceFrame, resolveVariantFrameOptions, seedDeviceConfigs } from './mockup.js';
 import { transformBrowserUrl } from './transform-browser-url.js';
 import { localizeStatusBar } from './status-bar-l10n.js';
 import { logger } from './logger.js';
@@ -156,6 +156,10 @@ export async function runCapture(options) {
     // here; we seed mockup.ts so the export pipeline can apply them locally.
     seedDeviceConfigs(program.deviceConfigs ?? null);
     const runId = randomUUID();
+    // A multi-preset invocation shares one sessionId so every preset's charges
+    // group into one "CLI capture" billing entry; a lone run groups under its own
+    // runId (migration 267).
+    const sessionId = options.sessionId ?? runId;
     let videoAudioAssets;
     let videoAudioAssetsByLocale;
     try {
@@ -164,8 +168,13 @@ export async function runCapture(options) {
     catch (error) {
         return { success: false, runId, error: error instanceof Error ? error.message : String(error) };
     }
-    if (!options.program && program.mediaMode === 'video') {
-        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false);
+    // TTS synthesis is real, billed work — it belongs to a real run only. A dry run validates
+    // navigation/opcodes (capture opcodes + upload are skipped below) and must NOT synthesize speech:
+    // doing so would bill TTS credits while the run reports "0 credits charged". The rewritten SLEEP
+    // 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);
         if (!prepareResult.success) {
             return { success: false, runId, error: prepareResult.error };
         }
@@ -303,7 +312,7 @@ export async function runCapture(options) {
                     message: 'saving captures',
                 });
                 const provenance = buildRunProvenance(program, schemaVersionOrigin);
-                const uploadOutcome = await uploadResults(config, program, runResult, runId, provenance);
+                const uploadOutcome = await uploadResults(config, program, runResult, runId, sessionId, provenance);
                 if (program.mediaMode === 'video' && runResult.success) {
                     await signalVideoComplete(config, program, runResult, uploadOutcome.runId, videoAudioAssets, videoAudioAssetsByLocale);
                 }
@@ -351,7 +360,7 @@ export async function runCapture(options) {
             && (runResult ? !runResult.success : true);
         if (shouldExport) {
             logger.info('[debug-logs] Exporting debug logs to AutoKap…');
-            await logCollector.flushTo(runId, program.presetId, config.apiBaseUrl, config.apiKey, options.env);
+            await logCollector.flushTo(runId, program.presetId, config.apiBaseUrl, config.apiKey, options.env, runResult?.failureKind);
         }
         logCollector.stop();
     }
@@ -425,7 +434,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) {
+async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId) {
     if (regenerateTts) {
         logger.info('[capture] Forcing TTS regeneration — all cached segments will be re-synthesized and billed.');
     }
@@ -440,7 +449,9 @@ async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts) {
                 'Content-Type': 'application/json',
                 [CLI_VERSION_HEADER]: APP_VERSION,
             },
-            body: JSON.stringify(regenerateTts ? { videoId, runId, regenerateTts: true } : { videoId, runId }),
+            body: JSON.stringify(regenerateTts
+                ? { videoId, runId, sessionId, regenerateTts: true }
+                : { videoId, runId, sessionId }),
         });
     }
     catch (err) {
@@ -681,7 +692,7 @@ async function postRunStart(config, runId, presetId, variantCount, env) {
         logger.warn(`[capture] Run registration error: ${message}`);
     }
 }
-async function uploadResults(config, program, result, runId, provenance) {
+async function uploadResults(config, program, result, runId, sessionId, provenance) {
     const artifactJobs = result.variantResults.flatMap((variant) => {
         const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);
         return variant.artifacts.map((artifact) => ({
@@ -696,7 +707,7 @@ async function uploadResults(config, program, result, runId, provenance) {
         logger.info(`[capture] Uploading ${totalArtifacts} capture artifacts with concurrency ${artifactUploadConcurrency}`);
     }
     await runWithConcurrency(artifactJobs, artifactUploadConcurrency, async (job, index) => {
-        await uploadArtifact(config, program, runId, totalArtifacts, index + 1, job, provenance);
+        await uploadArtifact(config, program, runId, sessionId, totalArtifacts, index + 1, job, provenance);
     });
     // Strip binary buffers from artifacts before sending. The raw PNG/video
     // buffers were already uploaded via /api/cli/artifacts above, and the
@@ -857,18 +868,19 @@ function inferVariantLocale(variantId) {
 function inferVariantTheme(variantId) {
     return variantId.endsWith('-dark') ? 'dark' : 'light';
 }
-async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumber, job, provenance) {
+async function uploadArtifact(config, program, runId, sessionId, totalArtifacts, uploadNumber, job, provenance) {
     const { artifact, variant, variantSpec } = job;
     const filename = buildArtifactFilename(program.presetId, variant.variantId, artifact);
     const label = artifact.captureName ?? artifact.clipName ?? filename;
     logger.info(`[capture] Exporting capture ${uploadNumber}/${totalArtifacts}: ${label}`);
     if (process.env.AUTOKAP_USE_LEGACY_MULTIPART_UPLOADS === '1') {
-        await uploadArtifactMultipart(config, program, runId, job, filename, provenance);
+        await uploadArtifactMultipart(config, program, runId, sessionId, job, filename, provenance);
         return;
     }
     const prepared = await prepareDirectArtifactUpload({
         program,
         runId,
+        sessionId,
         artifact,
         variant,
         variantSpec,
@@ -933,7 +945,7 @@ async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumb
         throw new Error(`artifact completion failed for ${variant.variantId}: ${await formatServerError(completeResponse, completeUrl)}`);
     }
 }
-async function uploadArtifactMultipart(config, program, runId, job, filename, provenance) {
+async function uploadArtifactMultipart(config, program, runId, sessionId, job, filename, provenance) {
     const { artifact, variant, variantSpec } = job;
     const formData = new FormData();
     formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
@@ -947,6 +959,7 @@ async function uploadArtifactMultipart(config, program, runId, job, filename, pr
     formData.append('cliVersion', provenance.cliVersion);
     formData.append('programHash', provenance.programHash);
     formData.append('runId', runId);
+    formData.append('sessionId', sessionId);
     formData.append('variantId', variant.variantId);
     formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
     formData.append('targetLabel', variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId);
@@ -962,6 +975,9 @@ async function uploadArtifactMultipart(config, program, runId, job, filename, pr
     if (variantSpec?.deviceFrame) {
         formData.append('deviceFrame', variantSpec.deviceFrame);
     }
+    if (variantSpec?.mockupOptions) {
+        formData.append('mockupOptions', JSON.stringify(variantSpec.mockupOptions));
+    }
     const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
     const isFrameCapture = artifact.mediaMode === 'clip' || artifact.mediaMode === 'video';
     const deviceScaleFactor = isFrameCapture && Number.isFinite(requestedDeviceScaleFactor)
@@ -1015,7 +1031,7 @@ async function uploadArtifactMultipart(config, program, runId, job, filename, pr
     }
 }
 async function prepareDirectArtifactUpload(params) {
-    const { program, runId, artifact, variant, variantSpec, provenance } = params;
+    const { program, runId, sessionId, artifact, variant, variantSpec, provenance } = params;
     const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
     const isFrameCapture = artifact.mediaMode === 'clip' || artifact.mediaMode === 'video';
     const deviceScaleFactor = isFrameCapture && Number.isFinite(requestedDeviceScaleFactor)
@@ -1032,6 +1048,7 @@ async function prepareDirectArtifactUpload(params) {
         cliVersion: provenance.cliVersion,
         programHash: provenance.programHash,
         runId,
+        sessionId,
         variantId: variant.variantId,
         targetId: variantSpec?.targetId ?? variant.variantId,
         targetLabel: variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId,
@@ -1103,22 +1120,24 @@ async function prepareDirectUploadParts(params) {
 async function prepareScreenshotBufferForDirectUpload(input, metadata, program, variantSpec, tabIcon) {
     let output = input;
     const artifactPlan = resolveEffectiveCliArtifactPlan(program.artifactPlan, variantSpec?.deviceFrame ?? null);
-    if (artifactPlan?.applyStatusBar && !artifactPlan?.applyMockup) {
-        throw new Error('applyStatusBar requires applyMockup with a device frame');
-    }
-    if (artifactPlan?.applyMockup) {
-        if (!variantSpec?.deviceFrame) {
-            throw new Error('applyMockup requires a deviceFrame on the variant');
-        }
-        output = await applyDeviceFrame(output, variantSpec.deviceFrame, {
+    // The variant's deviceFrame is the sole gate. Its mockupOptions (orientation, status bar,
+    // safe areas, …) — defined by the user on the preset — drive the frame; the legacy
+    // program-level applyStatusBar only survives as a fallback for old programs without options.
+    if (variantSpec?.deviceFrame) {
+        const mockup = variantSpec.mockupOptions;
+        const frame = resolveVariantFrameOptions(mockup, {
             orientation: inferCliOrientation(metadata.viewport ?? null),
+            showStatusBar: artifactPlan?.applyStatusBar,
+        });
+        output = await applyDeviceFrame(output, variantSpec.deviceFrame, {
+            ...mockup,
+            ...frame,
             viewport: metadata.viewport ?? undefined,
             colorScheme: metadata.theme,
             outputScale: normalizeCliDeviceScaleFactor(metadata.deviceScaleFactor)
                 ?? normalizeCliDeviceScaleFactor(program.outputScale)
                 ?? 2,
-            showStatusBar: artifactPlan.applyStatusBar ?? false,
-            statusBar: localizeStatusBar({}, metadata.lang),
+            statusBar: localizeStatusBar(mockup?.statusBar ?? {}, metadata.lang),
             browserBar: buildCliBrowserBar(metadata.captureUrl, metadata.theme, tabIcon, { publicUrl: program.publicUrl, pageTitle: metadata.pageTitle ?? null }),
         });
     }
@@ -1181,10 +1200,11 @@ async function prepareClipBuffersForDirectUpload(artifact, metadata) {
         await fs.rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
-function resolveEffectiveCliArtifactPlan(artifactPlan, deviceFrame) {
+export function resolveEffectiveCliArtifactPlan(artifactPlan, deviceFrame) {
+    // Device mockups are gated SOLELY by the variant's `deviceFrame` (user-defined, deterministic).
+    // A present deviceFrame always renders its frame; `applyMockup` is a derived value, never a
+    // kill-switch (the legacy `applyMockup: false` toggle is intentionally ignored here).
     if (deviceFrame) {
-        if (artifactPlan.applyMockup === false)
-            return artifactPlan;
         return artifactPlan.applyMockup ? artifactPlan : { ...artifactPlan, applyMockup: true };
     }
     if (!artifactPlan.applyMockup && !artifactPlan.applyStatusBar)

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs/promises';
 const require = createRequire(import.meta.url);
@@ -137,6 +138,9 @@ async function runOutdatedPresetsLocally(opts) {
     const { runCapture } = await import('./cli-runner.js');
     const failures = [];
     logger.info(`[capture] Running ${data.presets.length} outdated preset(s)`);
+    // One session id for the whole invocation so every preset's screenshot/clip/
+    // video charges group into a single "CLI capture" billing entry (migration 267).
+    const sessionId = randomUUID();
     for (const preset of data.presets) {
         const label = preset.name ? `${preset.name} (${preset.id})` : preset.id;
         logger.info(`[capture] Running outdated preset ${label}`);
@@ -147,6 +151,7 @@ async function runOutdatedPresetsLocally(opts) {
             allowUploadFailure: opts.allowUploadFailure,
             dryRun: opts.dry,
             regenerateTts: opts.regenerateTts,
+            sessionId,
         });
         if (!result.success) {
             failures.push({
@@ -397,6 +402,10 @@ program
         failedPresets: 0,
         message: `Runner started: ${data.presets.length} preset(s) to capture`,
     });
+    // One session id for the whole invocation so every preset's charges group
+    // into a single "CLI capture" billing entry (migration 267). For cloud runs
+    // child artifact billing is suppressed server-side, so this is a no-op there.
+    const sessionId = randomUUID();
     for (const [index, preset] of data.presets.entries()) {
         const presetDisplayName = displayPresetName(preset);
         const label = preset.name ? `${preset.name} (${preset.id})` : preset.id;
@@ -417,6 +426,7 @@ program
             headed: opts.headed,
             allowUploadFailure: opts.allowUploadFailure,
             regenerateTts: opts.regenerateTts,
+            sessionId,
             // Each preset runs under its own ephemeral runId, which is NOT a
             // capture_runs row in a cloud batch (the parent cloud run owns the row),
             // so the per-preset error-log export would 404. Failure telemetry for
@@ -457,6 +467,9 @@ program
                 childRunId,
                 status: 'failed',
                 errorMessage: error,
+                ...(result.runResult?.failureKind
+                    ? { failureKind: result.runResult.failureKind }
+                    : {}),
                 message: `Preset failed: ${presetDisplayName}`,
             });
         }

package/dist/execution-schema.d.ts

@@ -1053,7 +1053,7 @@ export declare const VariantSpecSchema: z.ZodObject<{
             light: "light";
             dark: "dark";
         }>>;
-    }, z.core.$strict>>;
+    }, z.core.$strip>>;
 }, z.core.$strict>;
 export declare const PreconditionSpecSchema: z.ZodObject<{
     credentialsId: z.ZodOptional<z.ZodString>;
@@ -1205,7 +1205,7 @@ export declare const ExecutionProgramSchema: z.ZodObject<{
                 light: "light";
                 dark: "dark";
             }>>;
-        }, z.core.$strict>>;
+        }, z.core.$strip>>;
     }, z.core.$strict>>;
     preconditions: z.ZodObject<{
         credentialsId: z.ZodOptional<z.ZodString>;

package/dist/execution-schema.js

@@ -553,7 +553,13 @@ export const VariantSpecSchema = z.object({
             radius: z.number(),
         }).strict().optional(),
         colorScheme: z.enum(['light', 'dark']).optional(),
-    }).strict().optional(),
+        // STRIP (not strict): per-variant mockupOptions are reconciled verbatim from the preset's
+        // CaptureTarget, whose UI-side MockupOptions carries render-irrelevant keys the engine never
+        // consumes (showDock, dockScale, dockMode, userAppIcon, autoBrowserBar, viewport). Strict would
+        // make parseProgram THROW on those — stranding every Mac/browser preset at CLI fetch time.
+        // Dropping unknown keys post-parse is safe: applyDeviceFrame ignores them, and the full set
+        // stays on config.targets for the UI/preview.
+    }).optional(),
 }).strict();
 const cookieSchema = z.object({
     name: z.string().min(1),

package/dist/execution-types.d.ts

@@ -535,9 +535,16 @@ export interface ArtifactSpec {
     cursorTheme?: VideoCursorTheme;
     /** 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 */
+    /**
+     * @deprecated Device mockups are gated SOLELY by a variant's `deviceFrame` (user-defined,
+     * deterministic). The render paths derive mockup application from `deviceFrame` and ignore this
+     * flag as a gate. Kept optional for back-compat with stored programs; do not author it.
+     */
     applyMockup?: boolean;
-    /** Whether to add status bar. Default: false */
+    /**
+     * @deprecated Per-variant `mockupOptions.showStatusBar` drives the status bar now. Retained only
+     * as a fallback for legacy programs that lack per-variant `mockupOptions`. Do not author it.
+     */
     applyStatusBar?: boolean;
 }
 export interface ExecutionProgram {
@@ -647,6 +654,13 @@ export interface OpcodeResult {
     /** Error message if failed */
     error?: string;
 }
+/**
+ * Structured failure category, set on top of the free-text `error`. Lets the
+ * server surface a specific preset state instead of a generic "failed":
+ * `login_failed` = an opcode inside the login window (credential typing → first
+ * post-login assertion) failed, so the credentials are likely wrong.
+ */
+export type RunFailureKind = 'login_failed';
 export interface VariantResult {
     variantId: string;
     success: boolean;
@@ -663,6 +677,8 @@ export interface VariantResult {
      */
     detectedAppVersion?: string | null;
     error?: string;
+    /** Set when the failure falls inside the login window — see RunFailureKind. */
+    failureKind?: RunFailureKind;
 }
 export interface ArtifactResult {
     mediaMode: MediaMode;
@@ -814,6 +830,8 @@ export interface RunResult {
      */
     warnings?: string[];
     error?: string;
+    /** First non-null variant `failureKind` — see RunFailureKind. */
+    failureKind?: RunFailureKind;
 }
 export interface WaitCondition {
     selector: string;

package/dist/log-collector.d.ts

@@ -1,5 +1,6 @@
 import type { LogEntry } from './logger.js';
 import type { ProgressEvent } from './opcode-runner.js';
+import type { RunFailureKind } from './execution-types.js';
 export interface OpcodeContext {
     index: number;
     kind: string;
@@ -24,6 +25,9 @@ export interface ErrorLogsPayload {
     entries: ExportedLogEntry[];
     envName?: string;
     endedAt: string;
+    /** Structured failure category (e.g. 'login_failed'). Lets the server tag the
+     *  preset's capture_failed event with a specific kind. */
+    failureKind?: RunFailureKind;
 }
 export declare class LogCollector {
     private entries;
@@ -35,7 +39,7 @@ export declare class LogCollector {
     onProgress(event: ProgressEvent): void;
     snapshot(): ExportedLogEntry[];
     size(): number;
-    flushTo(runId: string, presetId: string, apiBaseUrl: string, apiKey: string, envName?: string): Promise<{
+    flushTo(runId: string, presetId: string, apiBaseUrl: string, apiKey: string, envName?: string, failureKind?: RunFailureKind): Promise<{
         ok: boolean;
         status?: number;
         error?: string;

package/dist/log-collector.js

@@ -61,7 +61,7 @@ export class LogCollector {
     size() {
         return this.entries.length;
     }
-    async flushTo(runId, presetId, apiBaseUrl, apiKey, envName) {
+    async flushTo(runId, presetId, apiBaseUrl, apiKey, envName, failureKind) {
         if (this.entries.length === 0) {
             return { ok: true, status: 204 };
         }
@@ -71,6 +71,7 @@ export class LogCollector {
             entries: this.entries,
             envName,
             endedAt: new Date().toISOString(),
+            ...(failureKind ? { failureKind } : {}),
         };
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), FLUSH_TIMEOUT_MS);

package/dist/login-detection.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Login detection — pure, dependency-light helpers shared by the opcode runner
+ * (to classify a failure as login-related) and credential substitution
+ * (opcode-actions.ts owns the actual `{{token}}` replacement).
+ *
+ * A program "logs in" when it types credentials: a TYPE opcode whose text (or a
+ * locale override) contains the `{{email}}` / `{{password}}` placeholder. The
+ * server resolves these placeholders at capture time from the preset's linked
+ * credentials account; the stored program only ever holds the placeholders.
+ *
+ * This module imports ONLY types so it stays safe to reference from any layer.
+ */
+import type { ExecutionOpcode } from './execution-types.js';
+/** The credential placeholder tokens — the contract between the authored
+ *  program and the server-side substitution. Single source of truth. */
+export declare const CREDENTIAL_TOKEN_EMAIL = "{{email}}";
+export declare const CREDENTIAL_TOKEN_PASSWORD = "{{password}}";
+export declare const CREDENTIAL_TOKEN_LOGIN_URL = "{{loginUrl}}";
+/**
+ * Which credential fields the program actually requires. Lets a caller compare
+ * against the linked account's available fields (has_email / has_password)
+ * without decrypting anything.
+ */
+export declare function programRequiredCredentialFields(steps: ExecutionOpcode[]): {
+    email: boolean;
+    password: boolean;
+};
+/** True when the program logs in (types an email or password). */
+export declare function programRequiresLogin(steps: ExecutionOpcode[]): boolean;
+/**
+ * The contiguous index range that constitutes the login flow:
+ * - `start` = first credential-typing opcode,
+ * - `end`   = first post-login assertion after the last credential opcode —
+ *             EITHER a standalone assertion opcode (ASSERT_ROUTE /
+ *             ASSERT_SURFACE / WAIT_FOR) OR, as the generator actually emits,
+ *             the submit CLICK whose own postcondition asserts the post-login
+ *             route/element (route_matches / element_visible) — else the last
+ *             credential opcode itself.
+ *
+ * Scanning stops at that FIRST asserting opcode, so the window covers the
+ * credential typing and the submit (which proves login) but does NOT extend
+ * across the post-login navigation. A failure anywhere in `[start, end]` means
+ * the login did not go through: a TYPE failing (form gone/changed), the submit
+ * failing, or its post-login assertion failing (still on /login). Returns null
+ * when the program does not log in.
+ */
+export declare function getLoginWindow(steps: ExecutionOpcode[]): {
+    start: number;
+    end: number;
+} | null;
+/** True when a failure at `failedIndex` falls inside the login window. */
+export declare function isLoginFailureIndex(steps: ExecutionOpcode[], failedIndex: number): boolean;

package/dist/login-detection.js

@@ -0,0 +1,126 @@
+/**
+ * Login detection — pure, dependency-light helpers shared by the opcode runner
+ * (to classify a failure as login-related) and credential substitution
+ * (opcode-actions.ts owns the actual `{{token}}` replacement).
+ *
+ * A program "logs in" when it types credentials: a TYPE opcode whose text (or a
+ * locale override) contains the `{{email}}` / `{{password}}` placeholder. The
+ * server resolves these placeholders at capture time from the preset's linked
+ * credentials account; the stored program only ever holds the placeholders.
+ *
+ * This module imports ONLY types so it stays safe to reference from any layer.
+ */
+/** The credential placeholder tokens — the contract between the authored
+ *  program and the server-side substitution. Single source of truth. */
+export const CREDENTIAL_TOKEN_EMAIL = '{{email}}';
+export const CREDENTIAL_TOKEN_PASSWORD = '{{password}}';
+export const CREDENTIAL_TOKEN_LOGIN_URL = '{{loginUrl}}';
+/** Opcode kinds that prove a login advanced past the form: an explicit route /
+ *  surface assertion, or a wait for a post-login element. The first such opcode
+ *  after the credential typing closes the "login window". */
+const POSTLOGIN_ASSERTION_KINDS = new Set([
+    'ASSERT_ROUTE',
+    'ASSERT_SURFACE',
+    'WAIT_FOR',
+]);
+/** Postcondition types that assert the login advanced past the form. The
+ *  canonical generated login flow does NOT emit a standalone assertion opcode —
+ *  it encodes the post-login check on the submit CLICK's own postcondition
+ *  (route_matches the post-login route, or element_visible a post-login
+ *  element). The first opcode after the credentials whose postcondition is one
+ *  of these closes the window too, so the submit click is inside it. */
+const POSTLOGIN_POSTCONDITION_TYPES = new Set([
+    'route_matches',
+    'element_visible',
+]);
+/** Every text field of an opcode that may carry a credential placeholder. */
+function credentialTexts(opcode) {
+    if (opcode.kind === 'TYPE') {
+        const texts = [opcode.text];
+        if (opcode.textByLocale)
+            texts.push(...Object.values(opcode.textByLocale));
+        return texts;
+    }
+    if (opcode.kind === 'NAVIGATE')
+        return [opcode.url];
+    return [];
+}
+/** True when the opcode types/uses email or password credentials. */
+function isCredentialOpcode(opcode) {
+    return credentialTexts(opcode).some((text) => typeof text === 'string' &&
+        (text.includes(CREDENTIAL_TOKEN_EMAIL) || text.includes(CREDENTIAL_TOKEN_PASSWORD)));
+}
+/**
+ * Which credential fields the program actually requires. Lets a caller compare
+ * against the linked account's available fields (has_email / has_password)
+ * without decrypting anything.
+ */
+export function programRequiredCredentialFields(steps) {
+    let email = false;
+    let password = false;
+    for (const opcode of steps) {
+        for (const text of credentialTexts(opcode)) {
+            if (typeof text !== 'string')
+                continue;
+            if (text.includes(CREDENTIAL_TOKEN_EMAIL))
+                email = true;
+            if (text.includes(CREDENTIAL_TOKEN_PASSWORD))
+                password = true;
+        }
+        if (email && password)
+            break;
+    }
+    return { email, password };
+}
+/** True when the program logs in (types an email or password). */
+export function programRequiresLogin(steps) {
+    const { email, password } = programRequiredCredentialFields(steps);
+    return email || password;
+}
+/**
+ * The contiguous index range that constitutes the login flow:
+ * - `start` = first credential-typing opcode,
+ * - `end`   = first post-login assertion after the last credential opcode —
+ *             EITHER a standalone assertion opcode (ASSERT_ROUTE /
+ *             ASSERT_SURFACE / WAIT_FOR) OR, as the generator actually emits,
+ *             the submit CLICK whose own postcondition asserts the post-login
+ *             route/element (route_matches / element_visible) — else the last
+ *             credential opcode itself.
+ *
+ * Scanning stops at that FIRST asserting opcode, so the window covers the
+ * credential typing and the submit (which proves login) but does NOT extend
+ * across the post-login navigation. A failure anywhere in `[start, end]` means
+ * the login did not go through: a TYPE failing (form gone/changed), the submit
+ * failing, or its post-login assertion failing (still on /login). Returns null
+ * when the program does not log in.
+ */
+export function getLoginWindow(steps) {
+    let start = -1;
+    let lastCred = -1;
+    for (let i = 0; i < steps.length; i++) {
+        if (isCredentialOpcode(steps[i])) {
+            if (start < 0)
+                start = i;
+            lastCred = i;
+        }
+    }
+    if (start < 0)
+        return null;
+    let end = lastCred;
+    for (let i = lastCred + 1; i < steps.length; i++) {
+        const step = steps[i];
+        if (POSTLOGIN_ASSERTION_KINDS.has(step.kind) ||
+            (step.postcondition != null &&
+                POSTLOGIN_POSTCONDITION_TYPES.has(step.postcondition.type))) {
+            end = i;
+            break;
+        }
+    }
+    return { start, end };
+}
+/** True when a failure at `failedIndex` falls inside the login window. */
+export function isLoginFailureIndex(steps, failedIndex) {
+    const window = getLoginWindow(steps);
+    return window !== null && failedIndex >= window.start && failedIndex <= window.end;
+}
+//# sourceMappingURL=login-detection.js.map

package/dist/mockup.d.ts

@@ -204,6 +204,19 @@ export interface MockupOptions {
         height: number;
     };
 }
+/**
+ * Resolve the two per-variant frame decisions shared by both render paths (CLI direct-upload
+ * framing and the cloud legacy-multipart route): a variant's own `mockupOptions` wins, falling
+ * back to the viewport-inferred orientation and the deprecated program-level `applyStatusBar`.
+ * Pure + exported so the precedence is tested once instead of in two duplicated call sites.
+ */
+export declare function resolveVariantFrameOptions(mockupOptions: MockupOptions | undefined, fallback: {
+    orientation?: MockupOrientation;
+    showStatusBar?: boolean;
+}): {
+    orientation?: MockupOrientation;
+    showStatusBar: boolean;
+};
 export interface ResolvedDeviceFrameDescriptor {
     id: string;
     name: string;

package/dist/mockup.js

@@ -17,6 +17,18 @@ function getSupabaseMockupConfig() {
         serviceKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
     };
 }
+/**
+ * Resolve the two per-variant frame decisions shared by both render paths (CLI direct-upload
+ * framing and the cloud legacy-multipart route): a variant's own `mockupOptions` wins, falling
+ * back to the viewport-inferred orientation and the deprecated program-level `applyStatusBar`.
+ * Pure + exported so the precedence is tested once instead of in two duplicated call sites.
+ */
+export function resolveVariantFrameOptions(mockupOptions, fallback) {
+    return {
+        orientation: mockupOptions?.orientation ?? fallback.orientation,
+        showStatusBar: mockupOptions?.showStatusBar ?? fallback.showStatusBar ?? false,
+    };
+}
 const DEFAULT_MOCKUP_OPTIONS = {
     orientation: 'portrait',
     outputScale: 2,

package/dist/opcode-actions.js

@@ -6,6 +6,7 @@
  */
 import { VARIANT_PLACEHOLDER } from './execution-types.js';
 import { dismissAllOverlays } from './overlay-engine.js';
+import { CREDENTIAL_TOKEN_EMAIL, CREDENTIAL_TOKEN_PASSWORD, CREDENTIAL_TOKEN_LOGIN_URL, } from './login-detection.js';
 /**
  * Substitute credential placeholders inside opcode text fields.
  * Only the {{email}}, {{password}} and {{loginUrl}} tokens are replaced.
@@ -16,9 +17,9 @@ export function substituteCredentialPlaceholders(text, credentials) {
         return text;
     }
     return text
-        .replaceAll('{{email}}', credentials?.email ?? '')
-        .replaceAll('{{password}}', credentials?.password ?? '')
-        .replaceAll('{{loginUrl}}', credentials?.loginUrl ?? '');
+        .replaceAll(CREDENTIAL_TOKEN_EMAIL, credentials?.email ?? '')
+        .replaceAll(CREDENTIAL_TOKEN_PASSWORD, credentials?.password ?? '')
+        .replaceAll(CREDENTIAL_TOKEN_LOGIN_URL, credentials?.loginUrl ?? '');
 }
 /**
  * Returns the list of credential placeholders (`{{email}}`, `{{password}}`,
@@ -32,14 +33,14 @@ export function findUnresolvedCredentialPlaceholders(text, credentials) {
     if (typeof text !== 'string' || !text.includes('{{'))
         return [];
     const missing = [];
-    if (text.includes('{{email}}') && !credentials?.email?.trim()) {
-        missing.push('{{email}}');
+    if (text.includes(CREDENTIAL_TOKEN_EMAIL) && !credentials?.email?.trim()) {
+        missing.push(CREDENTIAL_TOKEN_EMAIL);
     }
-    if (text.includes('{{password}}') && !credentials?.password) {
-        missing.push('{{password}}');
+    if (text.includes(CREDENTIAL_TOKEN_PASSWORD) && !credentials?.password) {
+        missing.push(CREDENTIAL_TOKEN_PASSWORD);
     }
-    if (text.includes('{{loginUrl}}') && !credentials?.loginUrl?.trim()) {
-        missing.push('{{loginUrl}}');
+    if (text.includes(CREDENTIAL_TOKEN_LOGIN_URL) && !credentials?.loginUrl?.trim()) {
+        missing.push(CREDENTIAL_TOKEN_LOGIN_URL);
     }
     return missing;
 }

package/dist/opcode-runner.js

@@ -14,6 +14,7 @@ import { smartWaitForStability } from './smart-wait.js';
 import { verifyCaptureQuality } from './capture-verification.js';
 import { generateAltText } from './alt-text.js';
 import { executeOpcodeCoreAction } from './opcode-actions.js';
+import { isLoginFailureIndex } from './login-detection.js';
 import { logger } from './logger.js';
 function formatOpcodeDebug(opcode) {
     const fields = [];
@@ -172,6 +173,7 @@ export async function executeProgram(program, createAdapter, options = {}) {
         detectedAppVersion,
         warnings: aggregatedWarnings.length ? aggregatedWarnings : undefined,
         error: aborted ? 'aborted' : (success ? undefined : completedVariantResults.find(v => !v.success)?.error),
+        failureKind: success ? undefined : completedVariantResults.find(v => v.failureKind)?.failureKind,
     };
 }
 // ── Variant execution ───────────────────────────────────────────────
@@ -247,6 +249,12 @@ async function executeVariant(program, variant, createAdapter, recoveryChain, te
                     durationMs: Date.now() - startTime,
                     artifacts,
                     error: `opcode ${i} (${opcode.kind}) failed: ${result.error}`,
+                    // Tag failures inside the login window (credential typing → first
+                    // post-login assertion) so the server can surface "login failed"
+                    // instead of a generic capture failure.
+                    ...(isLoginFailureIndex(program.steps, i)
+                        ? { failureKind: 'login_failed' }
+                        : {}),
                 };
             }
         }

package/dist/program-signing.d.ts

@@ -111,7 +111,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
                     light: "light";
                     dark: "dark";
                 }>>;
-            }, z.core.$strict>>;
+            }, z.core.$strip>>;
         }, z.core.$strict>>;
         preconditions: z.ZodObject<{
             credentialsId: z.ZodOptional<z.ZodString>;

package/dist/skill-packaging.js

@@ -19,6 +19,7 @@ const PRESET_SKILL_SOURCE = {
         { relativePath: 'OPCODE-REFERENCE.md', title: 'Opcode Reference', anchor: 'reference-opcode-reference' },
         { relativePath: 'references/STANDARDS.md', title: 'Prompt Charter & Quality Standards', anchor: 'reference-prompt-standards' },
         { relativePath: 'references/mock-data.md', title: 'Mock Data Injection', anchor: 'reference-mock-data-injection' },
+        { relativePath: 'references/video-workflow.md', title: 'Demo Video Workflow', anchor: 'reference-demo-video-workflow' },
         { relativePath: 'references/examples.md', title: 'Complete Examples', anchor: 'reference-complete-examples' },
     ],
 };

package/dist/video-narration-schema.d.ts

@@ -130,7 +130,7 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
                     light: "light";
                     dark: "dark";
                 }>>;
-            }, z.core.$strict>>;
+            }, z.core.$strip>>;
         }, z.core.$strict>>;
         preconditions: z.ZodObject<{
             credentialsId: z.ZodOptional<z.ZodString>;

package/package.json

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