autokap 1.6.0 → 1.6.2

package/dist/browser-pool.d.ts

@@ -19,6 +19,7 @@ declare class BrowserPool {
         lang?: string;
         colorScheme?: 'light' | 'dark';
         storageState?: BrowserStorageState;
+        extraHttpHeaders?: Record<string, string>;
     }): Promise<BrowserContext>;
     /**
      * Release a context back to the pool. Closes the context and unblocks

package/dist/browser-pool.js

@@ -67,12 +67,14 @@ class BrowserPool {
             await new Promise((resolve) => this.queue.push(resolve));
         }
         await this.ensureBrowser();
+        const extra = options?.extraHttpHeaders;
         const context = await this.browser.newContext({
             viewport,
             deviceScaleFactor: normalizeDeviceScaleFactor(deviceScaleFactor),
             locale: options?.lang ? options.lang : 'en-US',
             colorScheme: options?.colorScheme ?? 'light',
             storageState: options?.storageState,
+            ...(extra && Object.keys(extra).length > 0 ? { extraHTTPHeaders: extra } : {}),
         });
         this.activeContexts++;
         this.captureCount++;

package/dist/browser.js

@@ -911,6 +911,7 @@ export class Browser {
             lang: langToLocale(options.lang ?? 'en'),
             colorScheme: options.colorScheme ?? 'light',
             storageState: options.storageState,
+            extraHttpHeaders: options.extraHttpHeaders,
         });
         instance.page = await instance.context.newPage();
         instance.poolContext = true;
@@ -1030,6 +1031,9 @@ export class Browser {
             locale: langToLocale(options.lang ?? 'en'),
             colorScheme: options.colorScheme ?? 'light',
             storageState: options.storageState,
+            ...(options.extraHttpHeaders && Object.keys(options.extraHttpHeaders).length > 0
+                ? { extraHTTPHeaders: options.extraHttpHeaders }
+                : {}),
         };
         // Dedicated browser process for clip capture. Not pooled because clip
         // capture installs context-level init scripts (cursor overlay). Cloud Run
@@ -5368,7 +5372,13 @@ export class Browser {
     async setLanguage(lang) {
         const context = this.ensureContext();
         const page = this.ensurePage();
-        await context.setExtraHTTPHeaders({ 'Accept-Language': lang });
+        // `setExtraHTTPHeaders` REPLACES the header map — merge with the
+        // environment-level auth headers so a SET_LOCALE opcode doesn't strip
+        // them mid-run.
+        await context.setExtraHTTPHeaders({
+            ...(this.options.extraHttpHeaders ?? {}),
+            'Accept-Language': lang,
+        });
         await page.addInitScript((locale) => {
             Object.defineProperty(navigator, 'language', { get: () => locale, configurable: true });
             Object.defineProperty(navigator, 'languages', { get: () => [locale], configurable: true });
@@ -5485,12 +5495,14 @@ export class Browser {
         return this.context;
     }
     buildContextOptions() {
+        const extra = this.options.extraHttpHeaders;
         return {
             viewport: this.options.viewport,
             deviceScaleFactor: normalizeDeviceScaleFactor(this.options.deviceScaleFactor),
             locale: langToLocale(this.options.lang ?? 'en'),
             colorScheme: this.options.colorScheme ?? 'light',
             storageState: this.options.storageState,
+            ...(extra && Object.keys(extra).length > 0 ? { extraHTTPHeaders: extra } : {}),
         };
     }
 }

package/dist/cli-contract.d.ts

@@ -114,6 +114,12 @@ export interface ArtifactUploadMetadata {
     mimeType: string;
     captureType: "fullpage" | "element";
     captureUrl: string;
+    /**
+     * Document title captured from the page at screenshot time (Playwright's
+     * `page.title()`). Server uses it as the tab title in browser mockups; falls
+     * back to `parsed.hostname` when absent (older CLIs do not send it).
+     */
+    pageTitle?: string | null;
     lang: string;
     theme: "light" | "dark";
     deviceFrame?: string | null;

package/dist/cli-doctor.d.ts

@@ -1,4 +1,5 @@
 export declare function runDoctor(opts: {
     fix: boolean;
     agent?: string;
+    json?: boolean;
 }, currentVersion: string): Promise<void>;

package/dist/cli-doctor.js

@@ -148,8 +148,28 @@ async function detectAgent() {
     }
     return null;
 }
-async function checkSkill(agentOverride) {
+async function parseSkillVersion(skillPath) {
+    try {
+        const raw = await fs.readFile(skillPath, 'utf8');
+        const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!match)
+            return null;
+        const yamlText = match[1];
+        for (const line of yamlText.split(/\r?\n/)) {
+            const m = line.match(/^\s*version\s*:\s*(.+?)\s*$/);
+            if (m) {
+                return m[1].replace(/^["']|["']$/g, '').trim() || null;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function checkSkill(extras, agentOverride) {
     const agent = agentOverride ?? (await detectAgent());
+    extras.agentDetected = agent;
     if (!agent) {
         return {
             name: 'AI agent skill',
@@ -160,12 +180,16 @@ async function checkSkill(agentOverride) {
     }
     const skillPath = path.join(process.cwd(), AGENT_PATHS[agent]);
     if (await pathExists(skillPath)) {
+        extras.skillPath = AGENT_PATHS[agent];
+        extras.skillVersion = await parseSkillVersion(skillPath);
+        const versionSuffix = extras.skillVersion ? ` (v${extras.skillVersion})` : '';
         return {
             name: 'AI agent skill',
             status: 'ok',
-            message: `${agent}: ${AGENT_PATHS[agent]}`,
+            message: `${agent}: ${AGENT_PATHS[agent]}${versionSuffix}`,
         };
     }
+    extras.skillPath = AGENT_PATHS[agent];
     return {
         name: 'AI agent skill',
         status: 'warn',
@@ -181,6 +205,55 @@ async function checkSkill(agentOverride) {
         },
     };
 }
+async function checkCliKeyValid() {
+    let config = null;
+    try {
+        config = await readConfig();
+    }
+    catch {
+        config = null;
+    }
+    if (!config || !config.apiKey) {
+        return {
+            name: 'CLI key valid',
+            status: 'warn',
+            message: 'No CLI key configured locally — skipping remote validation.',
+            fixCommand: 'autokap init --cli-key <key>',
+        };
+    }
+    try {
+        const res = await fetch(`${config.apiBaseUrl}/api/cli/validate`, {
+            headers: { Authorization: `Bearer ${config.apiKey}` },
+        });
+        if (res.ok) {
+            return {
+                name: 'CLI key valid',
+                status: 'ok',
+                message: `Key validated against ${config.apiBaseUrl}.`,
+            };
+        }
+        if (res.status === 401 || res.status === 403) {
+            return {
+                name: 'CLI key valid',
+                status: 'fail',
+                message: `Server rejected the CLI key (HTTP ${res.status}). It was likely revoked or rotated.`,
+                fixCommand: 'autokap init --cli-key <new-key>',
+            };
+        }
+        return {
+            name: 'CLI key valid',
+            status: 'warn',
+            message: `Validation endpoint returned HTTP ${res.status}.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'CLI key valid',
+            status: 'warn',
+            message: `Cannot reach validation endpoint: ${err.message}`,
+        };
+    }
+}
 async function checkCliVersion(currentVersion) {
     const latest = await getCachedOrFetchLatest();
     if (!latest) {
@@ -247,28 +320,68 @@ function printCheck(result) {
     }
     console.log('');
 }
+function buildJsonReport(results, extras, currentVersion) {
+    const ok = results.filter(r => r.status === 'ok').length;
+    const warn = results.filter(r => r.status === 'warn').length;
+    const fail = results.filter(r => r.status === 'fail').length;
+    return {
+        cli_version: currentVersion,
+        agent_detected: extras.agentDetected,
+        skill_path: extras.skillPath,
+        skill_version: extras.skillVersion,
+        checks: results.map(r => ({
+            name: r.name,
+            status: r.status,
+            message: r.message,
+            fixable: Boolean(r.fixFn),
+            fix_command: r.fixCommand ?? null,
+        })),
+        summary: { ok, warn, fail, all_ok: fail === 0 && warn === 0 },
+    };
+}
 export async function runDoctor(opts, currentVersion) {
     const agentOverride = opts.agent
         ? opts.agent.toLowerCase()
         : undefined;
+    const jsonMode = Boolean(opts.json);
     if (agentOverride && !(agentOverride in AGENT_PATHS)) {
-        logger.error(`Unknown agent "${opts.agent}". Supported: ${Object.keys(AGENT_PATHS).join(', ')}`);
+        if (jsonMode) {
+            process.stdout.write(JSON.stringify({
+                error: `Unknown agent "${opts.agent}". Supported: ${Object.keys(AGENT_PATHS).join(', ')}`,
+            }) + '\n');
+        }
+        else {
+            logger.error(`Unknown agent "${opts.agent}". Supported: ${Object.keys(AGENT_PATHS).join(', ')}`);
+        }
         process.exit(1);
     }
-    console.log(chalk.bold('\nautokap doctor'));
-    console.log(chalk.gray(`Checking environment for autokap ${currentVersion}...\n`));
+    if (!jsonMode) {
+        console.log(chalk.bold('\nautokap doctor'));
+        console.log(chalk.gray(`Checking environment for autokap ${currentVersion}...\n`));
+    }
+    const extras = {
+        agentDetected: null,
+        skillPath: null,
+        skillVersion: null,
+    };
     const results = [];
     results.push(checkNodeVersion());
     results.push(await checkChromium());
     results.push(await checkFfmpeg());
     results.push(await checkConfig());
-    results.push(await checkSkill(agentOverride));
+    results.push(await checkCliKeyValid());
+    results.push(await checkSkill(extras, agentOverride));
     results.push(await checkCliVersion(currentVersion));
+    const failures = results.filter(r => r.status === 'fail');
+    const warnings = results.filter(r => r.status === 'warn');
+    if (jsonMode) {
+        const report = buildJsonReport(results, extras, currentVersion);
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        process.exit(failures.length > 0 ? 1 : 0);
+    }
     for (const r of results) {
         printCheck(r);
     }
-    const failures = results.filter(r => r.status === 'fail');
-    const warnings = results.filter(r => r.status === 'warn');
     if (opts.fix) {
         const fixable = results.filter(r => r.status !== 'ok' && r.fixFn);
         if (fixable.length === 0) {

package/dist/cli-runner.js

@@ -25,7 +25,8 @@ 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 } from './mockup.js';
+import { applyDeviceFrame, seedDeviceConfigs } from './mockup.js';
+import { transformBrowserUrl } from './transform-browser-url.js';
 import { localizeStatusBar } from './status-bar-l10n.js';
 import { logger } from './logger.js';
 import { callLLM } from './llm-provider.js';
@@ -166,6 +167,11 @@ export async function runCapture(options) {
             presetId: options.presetId,
         };
     }
+    // Custom device frames live in Supabase (table `device_mockups`) and the
+    // end-user CLI does not have the service role key. The server pre-fetches
+    // every device referenced by `variants[].deviceFrame` and embeds the rows
+    // here; we seed mockup.ts so the export pipeline can apply them locally.
+    seedDeviceConfigs(program.deviceConfigs ?? null);
     const runId = randomUUID();
     let videoAudioAssets;
     let videoAudioAssetsByLocale;
@@ -248,6 +254,7 @@ export async function runCapture(options) {
             lang: variant.locale,
             colorScheme: variant.theme,
             storageState: program.preconditions.storageState,
+            extraHttpHeaders: program.environmentHttpHeaders,
         };
         let recordingDir;
         let browser;
@@ -686,6 +693,7 @@ async function uploadResults(config, program, result, runId = randomUUID()) {
             healerPatches: sanitizedHealerPatches,
             runResult: strippedRunResult,
             totalDurationMs: result.totalDurationMs,
+            detectedAppVersion: result.detectedAppVersion ?? undefined,
             variantSummaries: result.variantResults.map(v => ({
                 variantId: v.variantId,
                 success: v.success,
@@ -883,6 +891,9 @@ async function uploadArtifactMultipart(config, program, runId, job, filename) {
     formData.append('mimeType', artifact.mimeType);
     formData.append('captureType', artifact.captureType ?? 'fullpage');
     formData.append('captureUrl', artifact.captureUrl ?? program.baseUrl);
+    if (artifact.pageTitle) {
+        formData.append('pageTitle', artifact.pageTitle);
+    }
     formData.append('lang', variantSpec?.locale ?? 'en');
     formData.append('theme', variantSpec?.theme ?? 'light');
     if (variantSpec?.deviceFrame) {
@@ -960,6 +971,7 @@ async function prepareDirectArtifactUpload(params) {
         mimeType: artifact.mimeType,
         captureType: artifact.captureType ?? 'fullpage',
         captureUrl: artifact.captureUrl ?? program.baseUrl,
+        pageTitle: artifact.pageTitle ?? null,
         lang: variantSpec?.locale ?? 'en',
         theme: variantSpec?.theme ?? 'light',
         deviceFrame: variantSpec?.deviceFrame ?? null,
@@ -1038,7 +1050,7 @@ async function prepareScreenshotBufferForDirectUpload(input, metadata, program,
                 ?? 2,
             showStatusBar: artifactPlan.applyStatusBar ?? false,
             statusBar: localizeStatusBar({}, metadata.lang),
-            browserBar: buildCliBrowserBar(metadata.captureUrl, metadata.theme, tabIcon),
+            browserBar: buildCliBrowserBar(metadata.captureUrl, metadata.theme, tabIcon, { publicUrl: program.publicUrl, pageTitle: metadata.pageTitle ?? null }),
         });
     }
     if (artifactPlan?.format?.screenshotFormat === 'jpeg') {
@@ -1121,14 +1133,16 @@ function normalizeCliDeviceScaleFactor(value) {
         return null;
     return Math.max(0.5, Math.min(4, Number(value)));
 }
-function buildCliBrowserBar(captureUrl, colorScheme, tabIcon) {
+function buildCliBrowserBar(captureUrl, colorScheme, tabIcon, options = {}) {
     if (!captureUrl)
         return undefined;
+    const displayUrl = transformBrowserUrl(captureUrl, options.publicUrl);
+    const explicitTitle = options.pageTitle?.trim() || null;
     try {
-        const parsed = new URL(captureUrl);
+        const parsed = new URL(displayUrl);
         return {
-            url: captureUrl,
-            pageTitle: parsed.hostname,
+            url: displayUrl,
+            pageTitle: explicitTitle ?? parsed.hostname,
             colorScheme,
             tabIconUrl: tabIcon
                 ? `data:${tabIcon.mimeType};base64,${tabIcon.buffer.toString('base64')}`
@@ -1137,8 +1151,8 @@ function buildCliBrowserBar(captureUrl, colorScheme, tabIcon) {
     }
     catch {
         return {
-            url: captureUrl,
-            pageTitle: captureUrl,
+            url: displayUrl,
+            pageTitle: explicitTitle ?? displayUrl,
             colorScheme,
             ...(tabIcon
                 ? { tabIconUrl: `data:${tabIcon.mimeType};base64,${tabIcon.buffer.toString('base64')}` }

package/dist/cli.js

@@ -1637,6 +1637,7 @@ program
     .description('Check environment and dependencies (Node, Chromium, ffmpeg, config, skill, version)')
     .option('--fix', 'Attempt to auto-fix detected issues (Chromium install, skill reinstall)', false)
     .option('--agent <name>', 'Override agent for skill check: claude, codex, cursor, windsurf, copilot')
+    .option('--json', 'Output a structured JSON report to stdout (for AI assistants and tooling)', false)
     .action(async (opts) => {
     const { runDoctor } = await import('./cli-doctor.js');
     await runDoctor(opts, version);

package/dist/execution-schema.d.ts

@@ -2226,6 +2226,9 @@ export declare const ExecutionProgramSchema: z.ZodObject<{
         defaultValues: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>>;
         replaceExisting: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
+    deviceConfigs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    publicUrl: z.ZodOptional<z.ZodString>;
+    environmentHttpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 export declare const HealerPatchSchema: z.ZodObject<{
     opcodeIndex: z.ZodNumber;
@@ -4923,4 +4926,7 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
         defaultValues: Record<string, string>[];
         replaceExisting?: boolean | undefined;
     }[] | undefined;
+    deviceConfigs?: Record<string, Record<string, unknown>> | undefined;
+    publicUrl?: string | undefined;
+    environmentHttpHeaders?: Record<string, string> | undefined;
 }>;

package/dist/execution-schema.js

@@ -652,6 +652,18 @@ export const ExecutionProgramSchema = z.object({
     compiledAt: z.string().datetime(),
     compiledWith: z.string().optional(),
     mockDataGroups: z.array(MockDataGroupSchema).optional(),
+    // Server-embedded device frame configs. Shape is governed by the
+    // `device_mockups.config` JSON column; we accept anything the server stores
+    // and let mockup.ts validate structurally at use time.
+    deviceConfigs: z.record(z.string().min(1), z.record(z.string(), z.unknown())).optional(),
+    // Project-level public URL used to rewrite the captured origin when
+    // decorating browser mockups. Validated only as a non-empty string here;
+    // the runtime parses it with `new URL()` and falls back gracefully.
+    publicUrl: z.string().min(1).optional(),
+    // Auth headers attached to the resolved project environment. Key/value
+    // pairs that Playwright will inject as `extraHTTPHeaders` on the
+    // BrowserContext so protected staging/preview URLs load successfully.
+    environmentHttpHeaders: z.record(z.string().min(1), z.string().min(1)).optional(),
 }).strict().superRefine((value, ctx) => {
     if (value.mediaMode !== value.artifactPlan.mediaMode) {
         ctx.addIssue({

package/dist/execution-types.d.ts

@@ -5,7 +5,8 @@
  * preset (natural language) -> ExecutionProgram (typed IR) -> deterministic runtime
  */
 import type { AKTree, BrowserStorageState, BrowserSessionStorageState, OutscaleConfig, VideoCursorTheme, VideoPageSignals } from './types.js';
-import type { MockupOptions } from './mockup.js';
+import type { DeviceConfig, MockupOptions } from './mockup.js';
+export type { DeviceConfig };
 /** 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", "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"];
@@ -557,6 +558,28 @@ export interface ExecutionProgram {
      * Compiled from PresetConfig.mockDataInjection.groups by the server.
      */
     mockDataGroups?: MockDataGroup[];
+    /**
+     * Server-embedded device frame configs for every `deviceFrame` referenced by
+     * `variants[]`. The CLI seeds its mockup engine with these so it does not
+     * need direct Supabase access (end-users do not have the service role key).
+     * Keyed by the exact deviceFrame string used in the variants.
+     */
+    deviceConfigs?: Record<string, DeviceConfig>;
+    /**
+     * Project-level public URL used to decorate browser mockups. The CLI
+     * substitutes the captured origin (typically a local dev server) with this
+     * value via `transformBrowserUrl` before baking it into the browser bar.
+     * Server-resolved from `projects.public_url`.
+     */
+    publicUrl?: string;
+    /**
+     * Auth headers attached to the resolved project environment (Bearer token,
+     * Vercel protection bypass, x-api-key, etc.). Injected into the Playwright
+     * BrowserContext so requests to protected staging/preview URLs go through.
+     * Decrypted server-side from `project_environments.auth_headers_encrypted`
+     * and embedded in the signed program envelope.
+     */
+    environmentHttpHeaders?: Record<string, string>;
 }
 export interface CircuitBreakerConfig {
     /** Max recovery attempts per opcode. Default: 3 */
@@ -605,6 +628,13 @@ export interface VariantResult {
     durationMs: number;
     /** Artifact buffers produced */
     artifacts: ArtifactResult[];
+    /**
+     * App version detected on the captured page (meta tag, window global, or
+     * data attribute). Sent to the server with telemetry so freshness tracking
+     * picks up the version live during the capture instead of waiting for the
+     * hourly cron.
+     */
+    detectedAppVersion?: string | null;
     error?: string;
 }
 export interface ArtifactResult {
@@ -622,6 +652,8 @@ export interface ArtifactResult {
     altText?: string;
     /** Final URL at the time the artifact was produced */
     captureUrl?: string;
+    /** Document title at the time the artifact was produced (page.title()) */
+    pageTitle?: string;
     /** Step index that produced the artifact */
     stepIndex?: number;
     /** Human-readable label for the artifact */
@@ -725,6 +757,12 @@ export interface RunResult {
      * array for `screenshot` and `clip` modes.
      */
     opcodeTimings: OpcodeTiming[];
+    /**
+     * First non-null `detectedAppVersion` from the variants. Used by the server
+     * telemetry route to bypass the cron-detected version and stamp the preset
+     * with the version actually captured on the page.
+     */
+    detectedAppVersion?: string | null;
     error?: string;
 }
 export interface WaitCondition {
@@ -842,6 +880,19 @@ export interface RuntimeAdapter {
         buffer: Buffer;
         mimeType: string;
     } | null>;
+    /**
+     * Document title of the current page (Playwright's `page.title()`). Captured
+     * at screenshot time and stored on the artifact metadata so browser mockups
+     * can render the actual page title instead of just the hostname. Optional —
+     * adapters that cannot resolve a title should leave this method off.
+     */
+    getPageTitle?(): Promise<string | null>;
+    /**
+     * Read the captured app's version from the live page (meta tag, window
+     * global, or data attribute). Mirrors `extractAppVersionFromHtml` server-side
+     * and `__AUTOKAP_VERSION__` lookup. Returns null if no marker is present.
+     */
+    detectAppVersion?(): Promise<string | null>;
     close(): Promise<void>;
     /** Click an element by semantic target. Falls back to selector if target not found. */
     clickByTarget?(opts: ClickByTargetOptions): Promise<void>;
@@ -939,4 +990,3 @@ export interface RuntimeAdapter {
         selector: string;
     }): Promise<void>;
 }
-export {};

package/dist/mockup.d.ts

@@ -11,7 +11,8 @@ export interface DeviceFrameDefinition {
         height: number;
     };
 }
-interface OrientationConfigData {
+export type DeviceOrientation = 'portrait' | 'landscape';
+export interface OrientationConfigData {
     screen: {
         logicalWidth: number;
         logicalHeight: number;
@@ -103,6 +104,69 @@ interface OrientationConfigData {
         right?: string;
     };
 }
+export interface DeviceConfig {
+    id: string;
+    name: string;
+    category: DeviceCategory;
+    platform: string;
+    frameOrientation?: 'portrait' | 'landscape';
+    supportedOrientations?: ('portrait' | 'landscape')[];
+    orientations?: {
+        portrait?: OrientationConfigData;
+        landscape?: OrientationConfigData;
+    };
+    /** Row-level frame_url (shared fallback for all orientations) */
+    _rowFrameUrl?: string;
+    screen: {
+        logicalWidth: number;
+        logicalHeight: number;
+        scale: number;
+        cornerRadius: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    safeArea?: {
+        top: number;
+        bottom: number;
+        left?: number;
+        right?: number;
+    };
+    statusBar?: {
+        asset: string;
+        height: number;
+        width: number;
+        type?: StatusBarDeviceType;
+        layout?: StatusBarLayout;
+    };
+    homeIndicator?: {
+        width: number;
+        height: number;
+        cornerRadius: number;
+        bottomOffset: number;
+    };
+    frame: {
+        type: 'png' | 'svg';
+        asset: string;
+        width: number;
+        height: number;
+        screenRect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    frameRotation?: number;
+    frameBehindContent?: boolean;
+    windowBorder?: OrientationConfigData['windowBorder'];
+    frameDarkUrl?: string;
+    browserBarZones?: OrientationConfigData['browserBarZones'];
+    browserStyle?: OrientationConfigData['browserStyle'];
+    adminShowStatusBar?: OrientationConfigData['adminShowStatusBar'];
+    adminForcedSafeAreaColors?: OrientationConfigData['adminForcedSafeAreaColors'];
+}
 export type MockupOrientation = 'portrait' | 'landscape';
 export interface MockupOptions {
     orientation?: MockupOrientation;
@@ -184,6 +248,7 @@ export interface ResolvedDeviceFrameDescriptor {
     disableOverlays: boolean;
 }
 export declare function invalidateDeviceConfigCache(): void;
+export declare function seedDeviceConfigs(configs: Record<string, DeviceConfig> | null | undefined): void;
 export declare function resolveDeviceFrameDescriptor(id: DeviceFrameId, options?: {
     orientation?: MockupOrientation;
 }): Promise<ResolvedDeviceFrameDescriptor | null>;
@@ -191,4 +256,3 @@ export declare function rasterizeDeviceFrame(descriptor: ResolvedDeviceFrameDesc
 export declare function getDeviceFrames(): Promise<DeviceFrameDefinition[]>;
 export declare function getDeviceFrame(id: DeviceFrameId): Promise<DeviceFrameDefinition | undefined>;
 export declare function applyDeviceFrame(screenshot: Buffer, deviceId: DeviceFrameId, options?: MockupOptions): Promise<Buffer>;
-export {};

package/dist/mockup.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { renderStatusBarBuffer } from './status-bar-render.js';
 import { generateBrowserBarSvg } from './browser-bar.js';
 import { computeMockupLayout } from './mockup-html.js';
+import { logger } from './logger.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const DEVICES_DIR = path.join(__dirname, '..', 'assets', 'devices');
@@ -144,7 +145,23 @@ function resolveOrientationConfig(config, requestedOrientation) {
         adminForcedSafeAreaColors: config.adminForcedSafeAreaColors,
     };
 }
+// Server-provided device configs embedded in signed execution programs. When
+// set, these short-circuit `loadDeviceConfigs` — the CLI does not need direct
+// Supabase access (and end-users do not have the service role key) because the
+// server already vetted every device referenced by the program's variants and
+// inlined the rows.
+let seededDeviceConfigs = null;
+export function seedDeviceConfigs(configs) {
+    if (!configs || Object.keys(configs).length === 0) {
+        seededDeviceConfigs = null;
+        return;
+    }
+    seededDeviceConfigs = new Map(Object.entries(configs));
+}
 async function loadDeviceConfigs() {
+    if (seededDeviceConfigs && seededDeviceConfigs.size > 0) {
+        return seededDeviceConfigs;
+    }
     if (configCache && configCache.expiresAt > Date.now()) {
         return configCache.configs;
     }
@@ -478,12 +495,12 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
     const isBrowserDevice = config.category === 'browser';
     const os = Math.max(0.5, Math.min(4, opts.outputScale));
     const geometry = computeResolvedFrameGeometry(resolved);
-    console.log(`[mockup] applyDeviceFrame: id=${deviceId}, category=${config.category}, orientation=${requestedOrientation}`);
-    console.log(`[mockup]   hasOrientationConfig=${!!config.orientations?.[requestedOrientation]}, orientations=${JSON.stringify(Object.keys(config.orientations ?? {}))}`);
-    console.log(`[mockup]   resolved.screen:`, JSON.stringify(resolved.screen));
-    console.log(`[mockup]   resolved.frame: w=${resolved.frame.width} h=${resolved.frame.height} asset="${resolved.frame.asset}" url=${resolved.frameUrl ? 'yes' : 'no'}`);
-    console.log(`[mockup]   resolved.safeArea:`, JSON.stringify(resolved.safeArea));
-    console.log(`[mockup]   scale=${scale}, outputScale=${os}`);
+    logger.debug(`[mockup] applyDeviceFrame: id=${deviceId}, category=${config.category}, orientation=${requestedOrientation}`);
+    logger.debug(`[mockup]   hasOrientationConfig=${!!config.orientations?.[requestedOrientation]}, orientations=${JSON.stringify(Object.keys(config.orientations ?? {}))}`);
+    logger.debug(`[mockup]   resolved.screen: ${JSON.stringify(resolved.screen)}`);
+    logger.debug(`[mockup]   resolved.frame: w=${resolved.frame.width} h=${resolved.frame.height} asset="${resolved.frame.asset}" url=${resolved.frameUrl ? 'yes' : 'no'}`);
+    logger.debug(`[mockup]   resolved.safeArea: ${JSON.stringify(resolved.safeArea)}`);
+    logger.debug(`[mockup]   scale=${scale}, outputScale=${os}`);
     // Browser devices can work without a frame image
     const hasFrame = !!(resolved.frameUrl || resolved.frame.asset);
     let frameData = null;
@@ -509,7 +526,7 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
         geo.frameWidth = logicalW;
         geo.frameHeight = logicalH;
         geo.screenRect = { x: 0, y: 0, width: logicalW, height: logicalH };
-        console.log(`[mockup]   frameless browser: logicalW=${logicalW}, logicalH=${logicalH}, os=${os}, geo=${geo.frameWidth}x${geo.frameHeight}`);
+        logger.debug(`[mockup]   frameless browser: logicalW=${logicalW}, logicalH=${logicalH}, os=${os}, geo=${geo.frameWidth}x${geo.frameHeight}`);
     }
     else if (!hasFrame && geo.frameWidth === 0 && geo.frameHeight === 0) {
         // Non-browser frameless fallback
@@ -551,21 +568,21 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
     });
     const contentW = layout.contentArea.width;
     const contentH = layout.contentArea.height;
-    console.log(`[mockup]   hasFrame=${hasFrame}, geo: fw=${geo.frameWidth} fh=${geo.frameHeight} sr=${JSON.stringify(geo.screenRect)}`);
-    console.log(`[mockup]   layout: container=${layout.containerWidth}x${layout.containerHeight} content=${contentW}x${contentH} contentArea=${JSON.stringify(layout.contentArea)}`);
+    logger.debug(`[mockup]   hasFrame=${hasFrame}, geo: fw=${geo.frameWidth} fh=${geo.frameHeight} sr=${JSON.stringify(geo.screenRect)}`);
+    logger.debug(`[mockup]   layout: container=${layout.containerWidth}x${layout.containerHeight} content=${contentW}x${contentH} contentArea=${JSON.stringify(layout.contentArea)}`);
     // Get incoming screenshot dimensions for logging
     const screenshotMeta = await sharp(screenshot).metadata();
-    console.log(`[mockup]   input screenshot: ${screenshotMeta.width}x${screenshotMeta.height}`);
+    logger.debug(`[mockup]   input screenshot: ${screenshotMeta.width}x${screenshotMeta.height}`);
     const physicalContentW = Math.round(contentW * os);
     const physicalContentH = Math.round(contentH * os);
-    console.log(`[mockup]   resize target: ${physicalContentW}x${physicalContentH}`);
+    logger.debug(`[mockup]   resize target: ${physicalContentW}x${physicalContentH}`);
     if (screenshotMeta.width
         && screenshotMeta.height
         && (Math.abs(screenshotMeta.width - physicalContentW) > 1
             || Math.abs(screenshotMeta.height - physicalContentH) > 1)) {
         const ratioX = physicalContentW / screenshotMeta.width;
         const ratioY = physicalContentH / screenshotMeta.height;
-        console.warn(`[mockup]   screenshot will be resampled: ` +
+        logger.debug(`[mockup]   screenshot will be resampled: ` +
             `${screenshotMeta.width}x${screenshotMeta.height} -> ` +
             `${physicalContentW}x${physicalContentH} ` +
             `(x=${ratioX.toFixed(4)}, y=${ratioY.toFixed(4)}). ` +
@@ -597,7 +614,7 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
         colors.leftColor = sanitizeCssColor(opts.safeAreaLeftColor);
     if (opts.safeAreaRightColor)
         colors.rightColor = sanitizeCssColor(opts.safeAreaRightColor);
-    console.log(`[mockup]   sampled colors: top=${colors.topColor} bottom=${colors.bottomColor} left=${colors.leftColor} right=${colors.rightColor}`);
+    logger.debug(`[mockup]   sampled colors: top=${colors.topColor} bottom=${colors.bottomColor} left=${colors.leftColor} right=${colors.rightColor}`);
     // Determine color scheme: use explicit override if provided, otherwise auto-detect from edge colors.
     // Laptops (MacBook) always use dark menu bar (white text on black background).
     const isLaptop = config.category === 'laptop';
@@ -664,7 +681,7 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
     const renderW = Math.round(geo.frameWidth);
     const renderH = Math.round(geo.frameHeight);
     const cornerRadius = (resolved.screen?.cornerRadius ?? 0) * scale;
-    console.log(`[mockup]   composeMockup: ${renderW}x${renderH} @${os}x, showBrowserBar=${isBrowserDevice}, windowBorderWidth=${wbw}`);
+    logger.debug(`[mockup]   composeMockup: ${renderW}x${renderH} @${os}x, showBrowserBar=${isBrowserDevice}, windowBorderWidth=${wbw}`);
     // ── Sharp compositing — layer-by-layer mockup assembly ──
     // All dimensions in physical pixels (logical * os).
     const pw = Math.round(renderW * os);

package/dist/opcode-runner.js

@@ -147,6 +147,7 @@ export async function executeProgram(program, createAdapter, options = {}) {
     const completedVariantResults = variantResults.filter((result) => Boolean(result));
     const aborted = options.abortSignal?.aborted && completedVariantResults.length < program.variants.length;
     const success = !aborted && completedVariantResults.length > 0 && completedVariantResults.every(v => v.success);
+    const detectedAppVersion = completedVariantResults.reduce((acc, variantResult) => acc ?? (variantResult.detectedAppVersion ?? null), null);
     return {
         programId: program.presetId,
         success,
@@ -155,6 +156,7 @@ export async function executeProgram(program, createAdapter, options = {}) {
         healerPatches: success ? healerPatches : [], // Only propagate patches on success
         opcodeTimings,
         totalDurationMs: Date.now() - startTime,
+        detectedAppVersion,
         error: aborted ? 'aborted' : (success ? undefined : completedVariantResults.find(v => !v.success)?.error),
     };
 }
@@ -234,12 +236,25 @@ async function executeVariant(program, variant, createAdapter, recoveryChain, te
                 };
             }
         }
+        // Best-effort: read the app version from the live page so the server can
+        // stamp the preset with what we actually captured (instead of falling back
+        // to whatever the hourly cron last detected).
+        let detectedAppVersion = null;
+        if (adapter.detectAppVersion) {
+            try {
+                detectedAppVersion = await adapter.detectAppVersion();
+            }
+            catch {
+                detectedAppVersion = null;
+            }
+        }
         return {
             variantId: variant.id,
             success: true,
             opcodeResults,
             durationMs: Date.now() - startTime,
             artifacts,
+            detectedAppVersion,
         };
     }
     catch (err) {
@@ -693,12 +708,21 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                         tabIconMimeType = favicon.mimeType;
                     }
                 }
+                // Capture document title so browser mockups can render the real tab
+                // title instead of falling back to the hostname.
+                let pageTitle;
+                if (adapter.getPageTitle) {
+                    const resolved = await adapter.getPageTitle();
+                    if (resolved)
+                        pageTitle = resolved;
+                }
                 artifacts.push({
                     mediaMode: 'screenshot',
                     buffer,
                     mimeType: 'image/png',
                     captureType: opcode.elementSelector ? 'element' : 'fullpage',
                     captureUrl,
+                    pageTitle,
                     dimensions: currentVariant?.viewport,
                     captureId: opcode.captureId,
                     captureName: opcode.captureName ?? opcode.description,

package/dist/program-signing.d.ts

@@ -1126,6 +1126,9 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             defaultValues: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>>;
             replaceExisting: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>>;
+        deviceConfigs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        publicUrl: z.ZodOptional<z.ZodString>;
+        environmentHttpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>;
     signature: z.ZodString;
     meta: z.ZodOptional<z.ZodObject<{

package/dist/program-signing.js

@@ -102,6 +102,10 @@ export function signExecutionProgramEnvelope(params) {
     };
 }
 export function verifySignedExecutionProgramEnvelope(params) {
+    // The Zod schema describes `deviceConfigs` as a loose record (the server is
+    // the source of truth for the rich DeviceConfig shape). Cast to the strongly
+    // typed envelope at this trust boundary — the signature verification below
+    // proves the server produced this payload.
     const envelope = SignedExecutionProgramEnvelopeSchema.parse(params.envelope);
     const payload = {
         signedAt: envelope.signedAt,

package/dist/transform-browser-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Transform a captured URL for display in the browser bar mockup.
+ * 1. Replace the origin with `publicUrl` (if provided).
+ * 2. Strip UUID v4 path segments.
+ */
+export declare function transformBrowserUrl(capturedUrl: string, publicUrl?: string | null): string;

package/dist/transform-browser-url.js

@@ -0,0 +1,28 @@
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Transform a captured URL for display in the browser bar mockup.
+ * 1. Replace the origin with `publicUrl` (if provided).
+ * 2. Strip UUID v4 path segments.
+ */
+export function transformBrowserUrl(capturedUrl, publicUrl) {
+    let parsed;
+    try {
+        parsed = new URL(capturedUrl);
+    }
+    catch {
+        return capturedUrl;
+    }
+    if (publicUrl) {
+        try {
+            const pub = new URL(publicUrl);
+            parsed = new URL(`${pub.origin}${parsed.pathname}${parsed.search}${parsed.hash}`);
+        }
+        catch {
+            // invalid publicUrl — skip origin replacement
+        }
+    }
+    const segments = parsed.pathname.split("/").filter((s) => s && !UUID_RE.test(s));
+    parsed.pathname = "/" + segments.join("/");
+    return parsed.toString().replace(/\/$/, "") || parsed.origin;
+}
+//# sourceMappingURL=transform-browser-url.js.map

package/dist/types.d.ts

@@ -246,6 +246,17 @@ export interface BrowserOptions {
     colorScheme?: 'light' | 'dark';
     /** Optional persisted cookies/localStorage captured during preparation. */
     storageState?: BrowserStorageState;
+    /**
+     * Extra HTTP headers injected on every navigation. Used to carry the
+     * environment-level auth (Bearer token, Vercel protection bypass, x-api-key,
+     * etc.) configured on the resolved `project_environments` row.
+     *
+     * These headers are sent to ALL requests the BrowserContext makes during
+     * capture, including cross-origin requests (third-party CDN, analytics).
+     * The dashboard surfaces a warning so users only put environment-scoped
+     * secrets here.
+     */
+    extraHttpHeaders?: Record<string, string>;
 }
 export interface OutscaleConfig {
     /** Uniform padding on all 4 sides (pixels). */

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

@@ -1152,6 +1152,9 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             defaultValues: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>>;
             replaceExisting: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>>;
+        deviceConfigs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        publicUrl: z.ZodOptional<z.ZodString>;
+        environmentHttpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>;
     narration: z.ZodOptional<z.ZodObject<{
         voice: z.ZodString;

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

@@ -27,6 +27,8 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
     constructor(browser: Browser, recordingDir?: string | undefined);
     navigate(url: string): Promise<void>;
     getCurrentUrl(): Promise<string>;
+    getPageTitle(): Promise<string | null>;
+    detectAppVersion(): Promise<string | null>;
     getAKTree(): Promise<AKTree>;
     getPageSignals(): Promise<VideoPageSignals>;
     click(selector: string, options?: ClickOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",
@@ -181,6 +181,10 @@
     "./program-signing": {
       "types": "./dist/program-signing.d.ts",
       "default": "./dist/program-signing.js"
+    },
+    "./transform-browser-url": {
+      "types": "./dist/transform-browser-url.d.ts",
+      "default": "./dist/transform-browser-url.js"
     }
   },
   "bin": {