autokap 1.4.3 → 1.5.2

package/dist/cli-runner.js

@@ -13,7 +13,8 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import sharp from 'sharp';
 import { Browser } from './browser.js';
 import { API_BASE_URL_ENV_VAR, requireConfig } from './cli-config.js';
 import { WebPlaywrightLocal } from './web-playwright-local.js';
@@ -22,6 +23,9 @@ import { RecoveryChainImpl } from './recovery-chain.js';
 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 { localizeStatusBar } from './status-bar-l10n.js';
 import { logger } from './logger.js';
 import { callLLM } from './llm-provider.js';
 import { APP_VERSION } from './version.js';
@@ -175,6 +179,12 @@ export async function runCapture(options) {
     }
     logger.info(`[capture] Running preset "${options.presetId}" — ${program.steps.length} opcodes, ${program.variants.length} variant(s)`);
     logger.info(`[capture] Resolved API origin ${resolvedProgram.security.expectedApiOrigin}; navigation scope: ${resolvedProgram.security.allowedNavigationOrigins.join(', ')}`);
+    if (program.mediaMode === 'clip' || program.mediaMode === 'video') {
+        const label = program.mediaMode === 'video' ? 'Demo video' : 'Clip';
+        logger.warn(`[capture] ${label} fluidity depends on this machine's CPU. For smoother output, ` +
+            `re-run this preset via Cloud Recapture (dashboard → Recapture, or ` +
+            `\`autokap auto-recapture --project <id> --cloud\`).`);
+    }
     const llmConfig = resolveCliLLMConfig(resolvedProgram.security);
     // Step 3: Set up recovery chain
     const recoveryChain = new RecoveryChainImpl({
@@ -738,6 +748,9 @@ export function buildVideoClipMetadata(videoId, result, program, runId) {
                 timecodeStartMs: t.timecodeStartMs,
                 timecodeEndMs: t.timecodeEndMs,
                 bbox: t.bbox ?? null,
+                ...(t.keystrokeOffsetsMs && t.keystrokeOffsetsMs.length > 0
+                    ? { keystrokeOffsetsMs: t.keystrokeOffsetsMs }
+                    : {}),
             }));
             clipsByKey.set(`${variantId}:${artifact.clipId}`, {
                 variantId,
@@ -763,10 +776,82 @@ function inferVariantTheme(variantId) {
 }
 async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumber, job) {
     const { artifact, variant, variantSpec } = job;
-    const formData = new FormData();
     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);
+        return;
+    }
+    const prepared = await prepareDirectArtifactUpload({
+        program,
+        runId,
+        artifact,
+        variant,
+        variantSpec,
+    });
+    const uploadsUrl = `${config.apiBaseUrl}/api/cli/artifacts/uploads`;
+    const initResponse = await fetch(uploadsUrl, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+            [CLI_VERSION_HEADER]: APP_VERSION,
+        },
+        body: JSON.stringify({ metadata: prepared.metadata }),
+    });
+    if (!initResponse.ok) {
+        throw new Error(`artifact upload init failed for ${variant.variantId}: ${await formatServerError(initResponse, uploadsUrl)}`);
+    }
+    const initPayload = (await initResponse.json());
+    const uploadTargets = new Map(initPayload.uploads.map((target) => [target.id, target]));
+    const uploadedObjects = [];
+    for (const part of prepared.parts) {
+        const target = uploadTargets.get(part.id);
+        if (!target) {
+            throw new Error(`artifact upload init did not return a target for ${part.id}`);
+        }
+        const uploadResponse = await fetch(target.signedUrl, {
+            method: target.method,
+            headers: {
+                'content-type': part.contentType,
+                'cache-control': 'max-age=3600',
+            },
+            body: new Uint8Array(part.buffer),
+        });
+        if (!uploadResponse.ok) {
+            throw new Error(`artifact storage upload failed for ${part.id}: ${await formatServerError(uploadResponse, target.signedUrl)}`);
+        }
+        uploadedObjects.push({
+            id: part.id,
+            bucket: target.bucket,
+            path: target.path,
+            contentType: target.contentType,
+            sizeBytes: part.buffer.length,
+            sha256: sha256Hex(part.buffer),
+        });
+    }
+    const completeUrl = `${config.apiBaseUrl}/api/cli/artifacts/complete`;
+    const completeResponse = await fetch(completeUrl, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+            [CLI_VERSION_HEADER]: APP_VERSION,
+        },
+        body: JSON.stringify({
+            uploadId: initPayload.uploadId,
+            metadata: prepared.metadata,
+            objects: uploadedObjects,
+        }),
+    });
+    if (!completeResponse.ok) {
+        throw new Error(`artifact completion failed for ${variant.variantId}: ${await formatServerError(completeResponse, completeUrl)}`);
+    }
+}
+async function uploadArtifactMultipart(config, program, runId, job, filename) {
+    const { artifact, variant, variantSpec } = job;
+    const formData = new FormData();
     formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
     formData.append('presetId', program.presetId);
     formData.append('programVersion', String(program.programVersion));
@@ -836,6 +921,237 @@ async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumb
         throw new Error(`artifact upload failed for ${variant.variantId}: ${await formatServerError(response, `${config.apiBaseUrl}/api/cli/artifacts`)}`);
     }
 }
+async function prepareDirectArtifactUpload(params) {
+    const { program, runId, artifact, variant, variantSpec } = params;
+    const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
+    const isFrameCapture = artifact.mediaMode === 'clip' || artifact.mediaMode === 'video';
+    const deviceScaleFactor = isFrameCapture && Number.isFinite(requestedDeviceScaleFactor)
+        ? Math.min(Number(requestedDeviceScaleFactor), MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR)
+        : requestedDeviceScaleFactor;
+    const tabIconSha256 = artifact.tabIconData ? sha256Hex(artifact.tabIconData) : null;
+    const metadata = {
+        presetId: program.presetId,
+        programVersion: program.programVersion,
+        compileFingerprint: program.compileFingerprint,
+        runId,
+        variantId: variant.variantId,
+        targetId: variantSpec?.targetId ?? variant.variantId,
+        targetLabel: variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId,
+        mediaMode: artifact.mediaMode,
+        mimeType: artifact.mimeType,
+        captureType: artifact.captureType ?? 'fullpage',
+        captureUrl: artifact.captureUrl ?? program.baseUrl,
+        lang: variantSpec?.locale ?? 'en',
+        theme: variantSpec?.theme ?? 'light',
+        deviceFrame: variantSpec?.deviceFrame ?? null,
+        deviceScaleFactor: Number.isFinite(deviceScaleFactor) ? Number(deviceScaleFactor) : null,
+        viewport: variantSpec?.viewport ?? null,
+        altText: artifact.altText ?? null,
+        elementSelector: artifact.elementSelector ?? null,
+        captureId: artifact.captureId ?? null,
+        captureName: artifact.captureName ?? null,
+        clipId: artifact.clipId ?? null,
+        clipName: artifact.clipName ?? null,
+        stepDescription: artifact.stepDescription ?? null,
+        stepIndex: typeof artifact.stepIndex === 'number' ? artifact.stepIndex : null,
+        durationMs: typeof artifact.durationMs === 'number' ? artifact.durationMs : null,
+        trimStartMs: typeof artifact.trimStartMs === 'number' ? artifact.trimStartMs : null,
+        artifactPlan: program.artifactPlan,
+        tabIconMimeType: artifact.tabIconData ? (artifact.tabIconMimeType ?? 'image/png') : null,
+        tabIconSha256,
+    };
+    const parts = await prepareDirectUploadParts({
+        metadata,
+        artifact,
+        program,
+        variantSpec,
+    });
+    return { metadata, parts };
+}
+async function prepareDirectUploadParts(params) {
+    const { metadata, artifact, program, variantSpec } = params;
+    if (artifact.mediaMode === 'screenshot') {
+        const finalScreenshot = await prepareScreenshotBufferForDirectUpload(artifact.buffer, metadata, program, variantSpec, artifact.tabIconData
+            ? {
+                buffer: artifact.tabIconData,
+                mimeType: artifact.tabIconMimeType ?? 'image/png',
+            }
+            : null);
+        const parts = [
+            { id: 'screenshotRaw', buffer: artifact.buffer, contentType: 'image/png' },
+            { id: 'screenshot', buffer: finalScreenshot.buffer, contentType: finalScreenshot.contentType },
+        ];
+        if (artifact.tabIconData) {
+            parts.push({
+                id: 'tabIcon',
+                buffer: artifact.tabIconData,
+                contentType: artifact.tabIconMimeType ?? 'image/png',
+            });
+        }
+        return parts;
+    }
+    if (artifact.mediaMode === 'clip') {
+        return prepareClipBuffersForDirectUpload(artifact, metadata);
+    }
+    return [
+        {
+            id: 'videoMp4',
+            buffer: artifact.buffer,
+            contentType: 'video/mp4',
+        },
+    ];
+}
+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, {
+            orientation: inferCliOrientation(metadata.viewport ?? null),
+            colorScheme: metadata.theme,
+            outputScale: normalizeCliDeviceScaleFactor(metadata.deviceScaleFactor)
+                ?? normalizeCliDeviceScaleFactor(program.outputScale)
+                ?? 2,
+            showStatusBar: artifactPlan.applyStatusBar ?? false,
+            statusBar: localizeStatusBar({}, metadata.lang),
+            browserBar: buildCliBrowserBar(metadata.captureUrl, metadata.theme, tabIcon),
+        });
+    }
+    if (artifactPlan?.format?.screenshotFormat === 'jpeg') {
+        return {
+            buffer: await sharp(output).jpeg({ quality: 90 }).toBuffer(),
+            contentType: 'image/jpeg',
+        };
+    }
+    return { buffer: output, contentType: 'image/png' };
+}
+async function prepareClipBuffersForDirectUpload(artifact, metadata) {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'autokap-cli-direct-clip-'));
+    try {
+        const sourceExtension = mimeToExtension(artifact.mimeType);
+        const sourcePath = path.join(tempDir, `source.${sourceExtension}`);
+        await fs.writeFile(sourcePath, artifact.buffer);
+        const clipId = sanitizeArtifactToken(metadata.clipId ?? `${metadata.variantId}-${metadata.stepIndex ?? 0}`);
+        const postResult = await postProcessClipRecording(sourcePath, tempDir, `${clipId}-${sanitizeArtifactToken(metadata.variantId)}`, {
+            format: metadata.artifactPlan?.format && typeof metadata.artifactPlan.format === 'object'
+                ? metadata.artifactPlan.format.clipFormat
+                : undefined,
+            maxDurationSec: typeof metadata.artifactPlan?.maxClipDurationSec === 'number'
+                ? metadata.artifactPlan.maxClipDurationSec
+                : undefined,
+            gifMaxWidth: metadata.viewport?.width
+                ? Math.min(1440, Math.round(metadata.viewport.width))
+                : undefined,
+            trimStartSec: Math.max(0, (metadata.trimStartMs ?? 0) / 1000),
+            mp4Width: resolveClipMp4Size(metadata.viewport ?? null, metadata.deviceScaleFactor ?? null)?.width,
+            mp4Height: resolveClipMp4Size(metadata.viewport ?? null, metadata.deviceScaleFactor ?? null)?.height,
+            skipMp4Encode: artifact.mimeType === 'video/mp4',
+        });
+        metadata.durationMs = postResult.durationMs;
+        const parts = [];
+        if (postResult.gifPath) {
+            parts.push({
+                id: 'clipGif',
+                buffer: await fs.readFile(postResult.gifPath),
+                contentType: 'image/gif',
+            });
+        }
+        if (postResult.mp4Path) {
+            parts.push({
+                id: 'clipMp4',
+                buffer: await fs.readFile(postResult.mp4Path),
+                contentType: 'video/mp4',
+            });
+        }
+        if (postResult.thumbnailPath) {
+            parts.push({
+                id: 'clipThumbnail',
+                buffer: await fs.readFile(postResult.thumbnailPath),
+                contentType: 'image/png',
+            });
+        }
+        return parts;
+    }
+    finally {
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function resolveEffectiveCliArtifactPlan(artifactPlan, deviceFrame) {
+    if (deviceFrame) {
+        if (artifactPlan.applyMockup === false)
+            return artifactPlan;
+        return artifactPlan.applyMockup ? artifactPlan : { ...artifactPlan, applyMockup: true };
+    }
+    if (!artifactPlan.applyMockup && !artifactPlan.applyStatusBar)
+        return artifactPlan;
+    const { applyMockup: _applyMockup, applyStatusBar: _applyStatusBar, ...rest } = artifactPlan;
+    return rest;
+}
+function inferCliOrientation(viewport) {
+    if (!viewport)
+        return undefined;
+    return viewport.width >= viewport.height ? 'landscape' : 'portrait';
+}
+function normalizeCliDeviceScaleFactor(value) {
+    if (!Number.isFinite(value))
+        return null;
+    return Math.max(0.5, Math.min(4, Number(value)));
+}
+function buildCliBrowserBar(captureUrl, colorScheme, tabIcon) {
+    if (!captureUrl)
+        return undefined;
+    try {
+        const parsed = new URL(captureUrl);
+        return {
+            url: captureUrl,
+            pageTitle: parsed.hostname,
+            colorScheme,
+            tabIconUrl: tabIcon
+                ? `data:${tabIcon.mimeType};base64,${tabIcon.buffer.toString('base64')}`
+                : `https://www.google.com/s2/favicons?domain=${parsed.hostname}&sz=64`,
+        };
+    }
+    catch {
+        return {
+            url: captureUrl,
+            pageTitle: captureUrl,
+            colorScheme,
+            ...(tabIcon
+                ? { tabIconUrl: `data:${tabIcon.mimeType};base64,${tabIcon.buffer.toString('base64')}` }
+                : {}),
+        };
+    }
+}
+function resolveClipMp4Size(viewport, deviceScaleFactor) {
+    if (!viewport)
+        return null;
+    const scale = normalizeCliDeviceScaleFactor(deviceScaleFactor) ?? 1;
+    return {
+        width: Math.max(2, Math.round(viewport.width * scale)) & ~1,
+        height: Math.max(2, Math.round(viewport.height * scale)) & ~1,
+    };
+}
+function sha256Hex(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+function mimeToExtension(mimeType) {
+    if (mimeType.includes('jpeg'))
+        return 'jpg';
+    if (mimeType.includes('png'))
+        return 'png';
+    if (mimeType.includes('gif'))
+        return 'gif';
+    if (mimeType.includes('mp4'))
+        return 'mp4';
+    if (mimeType.includes('webm'))
+        return 'webm';
+    return 'bin';
+}
 async function runWithConcurrency(items, concurrency, worker) {
     if (items.length === 0) {
         return;

package/dist/cli.js

@@ -6,8 +6,9 @@ import fs from 'node:fs/promises';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 import { logger } from './logger.js';
-import { writeConfig, readConfig, deleteConfig, requireConfig, getConfigPath, DEFAULT_API_BASE_URL, getDefaultApiBaseUrl, getDefaultWsUrl, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, } from './cli-config.js';
+import { writeConfig, deleteConfig, requireConfig, getConfigPath, DEFAULT_API_BASE_URL, getDefaultApiBaseUrl, getDefaultWsUrl, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, } from './cli-config.js';
 import { renderSkillSingleFile, writeSkillExport } from './skill-packaging.js';
+import { displayNewVersionNoticeIfAvailable } from './version-check.js';
 // ── Program definition ──────────────────────────────────────────────
 export const program = new Command();
 program
@@ -549,71 +550,6 @@ program
     });
     process.exit(0);
 });
-// ── crm-run command ────────────────────────────────────────────────
-program
-    .command('crm-run')
-    .description('Scrape BetaList launches and feed the CRM (AUT-109 Phase B)')
-    .option('--runId <id>', 'CRM run id (defaults to AUTOKAP_RUN_ID env)')
-    .option('--lookback-days <n>', 'How far back to look for launches', '1')
-    .option('--debug', 'Verbose logging', false)
-    .action(async (opts) => {
-    // Log immediately on boot — before any other call — so Cloud Run logs
-    // show evidence the new command is reachable. If the next line silently
-    // crashes (missing dep, bad import) we at least see the boot.
-    logger.info(`[crm-run] booted — autokap CLI ${version}`);
-    if (opts.debug) {
-        const { setDebugEnabled } = await import('./logger.js');
-        setDebugEnabled(true);
-        logger.info('[crm-run] Debug mode enabled — verbose logging on');
-    }
-    // Self-kill after 20 min so a hung scraper exits before the backend
-    // reconcile cron (25 min) gets to it. Ensures the Cloud Run instance
-    // doesn't leak and the run row gets force-failed quickly.
-    const SELF_TIMEOUT_MS = 20 * 60 * 1000;
-    const selfTimeout = setTimeout(() => {
-        logger.error(`[crm-run] Self-kill: scraper exceeded ${SELF_TIMEOUT_MS / 60000}min budget — exiting non-zero`);
-        process.exit(1);
-    }, SELF_TIMEOUT_MS);
-    selfTimeout.unref?.();
-    const runToken = process.env.AUTOKAP_RUN_TOKEN?.trim();
-    const runId = opts.runId?.trim() || process.env.AUTOKAP_RUN_ID?.trim();
-    const config = await readConfig();
-    const apiBaseUrl = process.env.AUTOKAP_API_BASE_URL?.trim().replace(/\/+$/, '') || config?.apiBaseUrl;
-    logger.info(`[crm-run] env check — runId=${runId ?? '<missing>'} ` +
-        `apiBaseUrl=${apiBaseUrl ?? '<missing>'} ` +
-        `runToken=${runToken ? `${runToken.slice(0, 12)}…` : '<missing>'}`);
-    if (!runToken) {
-        fatal('[crm-run] Missing AUTOKAP_RUN_TOKEN');
-    }
-    if (!runId) {
-        fatal('[crm-run] Missing CRM run id. Set AUTOKAP_RUN_ID or pass --runId <id>.');
-    }
-    if (!apiBaseUrl) {
-        fatal('[crm-run] Missing API base URL. Set AUTOKAP_API_BASE_URL or run autokap init.');
-    }
-    const parsedLookback = Number.parseInt(opts.lookbackDays, 10);
-    const lookbackDays = Math.max(1, Math.min(7, Number.isFinite(parsedLookback) ? parsedLookback : 1));
-    logger.info(`[crm-run] starting campaign — lookbackDays=${lookbackDays}`);
-    try {
-        const { runCampaign } = await import('./crm/run-campaign.js');
-        const result = await runCampaign({
-            runId,
-            lookbackDays,
-            apiBaseUrl,
-            runToken,
-            logger,
-        });
-        clearTimeout(selfTimeout);
-        logger.success(`[crm-run] Done — scraped=${result.scraped} inserted=${result.inserted} ` +
-            `disqualified=${result.disqualified} skipped=${result.skipped}`);
-        process.exit(0);
-    }
-    catch (error) {
-        clearTimeout(selfTimeout);
-        logger.error(`[crm-run] Failed: ${error.message}`);
-        process.exit(1);
-    }
-});
 // ── project commands ───────────────────────────────────────────────
 const projectCmd = program
     .command('project')
@@ -1528,6 +1464,125 @@ proxyCmd
     }
     process.exit(0);
 });
+// ── branding command ───────────────────────────────────────────────
+const brandingCmd = program
+    .command('branding')
+    .description('Manage project branding and design system');
+brandingCmd
+    .command('import <file-path>')
+    .description('Import a design.md file as the project design system')
+    .requiredOption('--project <id>', 'Project ID')
+    .option('--dry', 'Validate and extract tokens without persisting', false)
+    .option('--json', 'JSON output for IDE assistants', false)
+    .option('--force-light-only', 'Skip dark-mode AI derivation', false)
+    .action(async (filePath, opts) => {
+    const config = await requireConfig();
+    const resolved = path.resolve(process.cwd(), filePath);
+    let content;
+    try {
+        content = await fs.readFile(resolved, 'utf8');
+    }
+    catch (e) {
+        fatal(`Cannot read file at ${resolved}: ${e.message}`);
+    }
+    if (content.length > 200_000) {
+        fatal(`File too large (${content.length} bytes, max 200000).`);
+    }
+    if (content.trim().length === 0) {
+        fatal(`File at ${resolved} is empty.`);
+    }
+    const result = await requestJson(config, `/api/cli/projects/${opts.project}/design-system/import`, {
+        method: 'POST',
+        headers: authHeaders(config, { 'Content-Type': 'application/json' }),
+        body: JSON.stringify({
+            source_markdown: content,
+            source_path: filePath,
+            options: {
+                dry_run: opts.dry,
+                force_light_only: opts.forceLightOnly,
+            },
+        }),
+    }, 'Failed to import design.md');
+    if (opts.json) {
+        printJson(result);
+        process.exit(0);
+    }
+    const ds = result.design_system;
+    if (ds?.meta?.name) {
+        logger.info(`Design system "${ds.meta.name}" imported for project ${opts.project}.`);
+    }
+    else {
+        logger.info(`Design system imported for project ${opts.project}.`);
+    }
+    const lightColors = ds?.light?.colors ?? {};
+    const colorKeys = Object.keys(lightColors);
+    if (colorKeys.length > 0) {
+        logger.info(`  Colors: ${colorKeys.length} (${colorKeys.slice(0, 5).join(', ')}${colorKeys.length > 5 ? '…' : ''})`);
+    }
+    const titleFont = ds?.light?.typography?.title?.fontFamily;
+    if (titleFont) {
+        logger.info(`  Title font: ${titleFont}`);
+    }
+    if (ds?.dark?.colors) {
+        logger.info(`  Dark mode: derived (${Object.keys(ds.dark.colors).length} colors)`);
+    }
+    if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+        logger.info(`  Warnings:`);
+        for (const w of result.warnings) {
+            logger.info(`    - ${w}`);
+        }
+    }
+    if (opts.dry) {
+        logger.info(`  (dry-run: nothing persisted)`);
+    }
+    process.exit(0);
+});
+brandingCmd
+    .command('export')
+    .description('Export the project design system as design.md (or JSON)')
+    .requiredOption('--project <id>', 'Project ID')
+    .option('--out <path>', 'Write to file instead of stdout')
+    .option('--format <fmt>', 'Output format: md or json', 'md')
+    .action(async (opts) => {
+    if (opts.format !== 'md' && opts.format !== 'json') {
+        fatal('Invalid --format. Use "md" or "json".');
+    }
+    const config = await requireConfig();
+    const searchParams = opts.format === 'json' ? new URLSearchParams({ format: 'json' }) : undefined;
+    if (opts.format === 'json') {
+        const payload = await requestJson(config, `/api/cli/projects/${opts.project}/design-system`, { headers: authHeaders(config) }, 'Failed to export design system', searchParams);
+        const body = JSON.stringify(payload, null, 2);
+        if (opts.out) {
+            await fs.writeFile(path.resolve(process.cwd(), opts.out), body, 'utf8');
+            logger.info(`Wrote design system JSON to ${opts.out}`);
+        }
+        else {
+            process.stdout.write(`${body}\n`);
+        }
+        process.exit(0);
+    }
+    const result = await requestJson(config, `/api/cli/projects/${opts.project}/design-system`, { headers: authHeaders(config) }, 'Failed to export design system');
+    if (opts.out) {
+        await fs.writeFile(path.resolve(process.cwd(), opts.out), result.content, 'utf8');
+        logger.info(`Wrote design.md to ${opts.out}`);
+    }
+    else {
+        process.stdout.write(result.content);
+        if (!result.content.endsWith('\n'))
+            process.stdout.write('\n');
+    }
+    process.exit(0);
+});
+// ── doctor command ──────────────────────────────────────────────────
+program
+    .command('doctor')
+    .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')
+    .action(async (opts) => {
+    const { runDoctor } = await import('./cli-doctor.js');
+    await runDoctor(opts, version);
+});
 // ── Entry point ─────────────────────────────────────────────────────
 const resolvedArgv = process.argv[1] && fs.realpath(process.argv[1]).catch(() => process.argv[1]);
 const isDirectExecution = resolvedArgv && await resolvedArgv.then(p => {
@@ -1535,6 +1590,7 @@ const isDirectExecution = resolvedArgv && await resolvedArgv.then(p => {
     return base === 'cli.js' || base === 'cli.ts';
 });
 if (isDirectExecution) {
+    await displayNewVersionNoticeIfAvailable(version);
     program.parseAsync().catch(async (err) => {
         logger.error(err.message);
         process.exit(1);

package/dist/execution-types.d.ts

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

package/dist/mouse-animation.d.ts

@@ -52,8 +52,14 @@ export declare function animatedHover(page: Page, target: {
 /**
  * Type text into the currently focused element at a human-like typing speed.
  * Assumes the field is already focused (via a preceding click).
+ *
+ * `onKeystroke` fires after each character with the absolute wall-clock
+ * timestamp (`Date.now()`) of the keystroke. The video pipeline converts
+ * these to clip-relative offsets so keyboard SFX fire in lock-step with the
+ * visible typing.
  */
 export declare function humanType(page: Page, text: string, options?: {
     minDelayMs?: number;
     maxDelayMs?: number;
+    onKeystroke?: (timestampMs: number) => void;
 }): Promise<void>;

package/dist/mouse-animation.js

@@ -132,12 +132,20 @@ export async function animatedHover(page, target, fromCurrent, options = {}) {
 /**
  * Type text into the currently focused element at a human-like typing speed.
  * Assumes the field is already focused (via a preceding click).
+ *
+ * `onKeystroke` fires after each character with the absolute wall-clock
+ * timestamp (`Date.now()`) of the keystroke. The video pipeline converts
+ * these to clip-relative offsets so keyboard SFX fire in lock-step with the
+ * visible typing.
  */
 export async function humanType(page, text, options = {}) {
     const minDelay = Math.max(0, options.minDelayMs ?? 60);
     const maxDelay = Math.max(minDelay, options.maxDelayMs ?? 140);
     for (const char of text) {
         await page.keyboard.type(char);
+        if (options.onKeystroke) {
+            options.onKeystroke(Date.now());
+        }
         // 60–120 WPM → ~80–130ms between characters (5 chars per word)
         const delay = minDelay + Math.random() * (maxDelay - minDelay);
         if (delay > 0) {

package/dist/opcode-actions.d.ts

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