autokap 1.1.6 → 1.1.7

package/dist/browser.js

@@ -120,6 +120,138 @@ async function withHelperTimeout(label, timeoutMs, work) {
 function isLikelyFontUrl(url) {
     return /\.(?:woff2?|ttf|otf)(?:[?#]|$)/i.test(url);
 }
+/**
+ * In-page metric probe gate: measure the width of a sample string rendered with
+ * the inherited font-family vs a deliberately-divergent baseline (monospace by
+ * default, serif when the primary is monospace). When inherited width diverges
+ * from both the divergent baseline AND the sans-serif fallback, we have proof
+ * that a real custom face is in the paint — not a system fallback dressed up
+ * with size-adjust (e.g. next/font's "Geist Fallback").
+ */
+async function runMetricFontGate(page, deadlineMs) {
+    return await page.evaluate((deadlineDuration) => new Promise((resolve) => {
+        try {
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+            const sample = 'AutoKap Aa 0123456789';
+            const candidates = Array.from(document.querySelectorAll('h1,h2,h3,p,a,button,label,span,[data-ak]'));
+            const target = candidates.find((node) => {
+                const text = (node.textContent ?? '').replace(/\s+/g, ' ').trim();
+                const rect = node.getBoundingClientRect();
+                return text.length >= 3 && rect.width > 10 && rect.height > 8;
+            }) ?? document.body;
+            const inheritedFF = getComputedStyle(target).fontFamily;
+            const isMonoPrimary = /\b(?:mono(?:space)?|courier|consolas|menlo|sf\s*mono)\b/i.test(inheritedFF);
+            // Monospace is guaranteed divergent from any proportional Geist-like face.
+            // For mono-primary targets, swap to serif as the divergent baseline.
+            const divergentBaseline = isMonoPrimary ? 'serif' : 'monospace';
+            const fallbackBaseline = isMonoPrimary ? 'monospace' : 'sans-serif';
+            const probe = document.createElement('span');
+            probe.setAttribute('aria-hidden', 'true');
+            probe.style.cssText = 'position:fixed;left:-99999px;top:0;visibility:hidden;white-space:nowrap;pointer-events:none;font-size:16px;font-weight:400;font-style:normal;';
+            probe.textContent = sample;
+            document.body.appendChild(probe);
+            const measure = (ff) => {
+                probe.style.fontFamily = ff;
+                void probe.offsetHeight;
+                return probe.getBoundingClientRect().width;
+            };
+            (async () => {
+                const deadline = performance.now() + deadlineDuration;
+                while (performance.now() < deadline) {
+                    const inherited = measure(inheritedFF);
+                    const divergent = measure(divergentBaseline);
+                    const fallback = measure(fallbackBaseline);
+                    // Inherited must diverge from the divergent baseline (proves a non-mono
+                    // shape is in the paint) AND from the bare sans-serif fallback (proves
+                    // it isn't the system fallback that next/font's adjustFontFallback
+                    // tunes to match Geist within ~1px).
+                    if (Math.abs(inherited - divergent) > 2 && Math.abs(inherited - fallback) > 0.5) {
+                        probe.remove();
+                        resolve('metric');
+                        return;
+                    }
+                    await sleep(80);
+                }
+                probe.remove();
+                resolve(null);
+            })().catch(() => {
+                probe.remove();
+                resolve(null);
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    }), deadlineMs).catch(() => null);
+}
+/**
+ * CDP-based gate via CSS.getPlatformFontsForNode. This is the authoritative
+ * oracle: Chromium reports the actual fonts used to paint each node, with
+ * isCustomFont=true marking fonts loaded via @font-face (vs system fonts).
+ * Resolves as soon as a non-Fallback custom face is in the paint of any
+ * representative text node.
+ */
+async function runCdpFontGate(page, deadlineMs) {
+    let client = null;
+    try {
+        client = await page.context().newCDPSession(page);
+        await client.send('DOM.enable');
+        await client.send('CSS.enable');
+        const deadline = Date.now() + deadlineMs;
+        const SELECTORS = ['h1', 'h2', 'h3', 'p', 'button', 'a', '[data-ak]', 'body'];
+        while (Date.now() < deadline) {
+            const docRes = await client.send('DOM.getDocument', { depth: 1, pierce: true });
+            for (const selector of SELECTORS) {
+                const q = await client.send('DOM.querySelector', {
+                    nodeId: docRes.root.nodeId,
+                    selector,
+                });
+                if (!q.nodeId)
+                    continue;
+                const fontsRes = await client.send('CSS.getPlatformFontsForNode', {
+                    nodeId: q.nodeId,
+                });
+                const fonts = fontsRes.fonts ?? [];
+                const hasPrimary = fonts.some((f) => f.glyphCount > 0
+                    && f.isCustomFont === true
+                    && !/\bFallback\b/i.test(f.familyName));
+                if (hasPrimary)
+                    return 'cdp';
+            }
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (client)
+            await client.detach().catch(() => { });
+    }
+}
+/**
+ * Race metric probe (in-page) and CDP query (Node-side). Resolves with the
+ * first signal that converges, or 'timeout' if neither does within the
+ * deadline. Never throws — caller always proceeds.
+ */
+async function gateOnPaintedFont(page, gateMs) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (via) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ via, elapsedMs: Date.now() - startedAt });
+        };
+        runMetricFontGate(page, gateMs).then((v) => { if (v === 'metric')
+            finish('metric'); }).catch(() => { });
+        runCdpFontGate(page, gateMs).then((v) => { if (v === 'cdp')
+            finish('cdp'); }).catch(() => { });
+        setTimeout(() => finish('timeout'), gateMs + 500);
+    });
+}
 async function logFontDiagnostics(page, stage) {
     if (!isDebugEnabled())
         return;
@@ -193,6 +325,178 @@ async function logFontDiagnostics(page, stage) {
         logger.debug(`[capture] font diagnostics ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function collectPlatformFontDiagnostics(page) {
+    try {
+        const client = await page.context().newCDPSession(page);
+        try {
+            await client.send('DOM.enable');
+            await client.send('CSS.enable');
+            const documentResponse = await client.send('DOM.getDocument', { depth: 1, pierce: true });
+            const selectors = [
+                'body',
+                'h1',
+                'h2',
+                'p',
+                'button',
+                'a',
+                '[data-ak]',
+                'span',
+            ];
+            const diagnostics = [];
+            for (const selector of selectors) {
+                const queryResponse = await client.send('DOM.querySelector', {
+                    nodeId: documentResponse.root.nodeId,
+                    selector,
+                });
+                if (!queryResponse.nodeId)
+                    continue;
+                const text = await page.locator(selector).first().evaluate((node) => (node.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 80)).catch(() => '');
+                const fontsResponse = await client.send('CSS.getPlatformFontsForNode', {
+                    nodeId: queryResponse.nodeId,
+                });
+                diagnostics.push({
+                    selector,
+                    text,
+                    fonts: (fontsResponse.fonts ?? []).map((font) => ({
+                        familyName: font.familyName,
+                        postScriptName: font.postScriptName,
+                        isCustomFont: font.isCustomFont,
+                        glyphCount: font.glyphCount,
+                    })),
+                });
+                if (diagnostics.length >= 6)
+                    break;
+            }
+            return diagnostics;
+        }
+        finally {
+            await client.detach().catch(() => { });
+        }
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function logCaptureRenderDiagnostics(page, screenshot, options, stage) {
+    const viewport = page.viewportSize();
+    const deviceScaleFactor = normalizeDeviceScaleFactor(options.deviceScaleFactor);
+    const metadata = await sharp(screenshot).metadata().catch(() => null);
+    const screenshotSize = {
+        width: metadata?.width ?? 0,
+        height: metadata?.height ?? 0,
+    };
+    const expectedScreenshotSize = viewport
+        ? {
+            width: Math.round(viewport.width * deviceScaleFactor),
+            height: Math.round(viewport.height * deviceScaleFactor),
+        }
+        : null;
+    if (expectedScreenshotSize
+        && (Math.abs(screenshotSize.width - expectedScreenshotSize.width) > 1
+            || Math.abs(screenshotSize.height - expectedScreenshotSize.height) > 1)) {
+        logger.warn(`[capture] Screenshot pixel size mismatch: expected ` +
+            `${expectedScreenshotSize.width}x${expectedScreenshotSize.height} ` +
+            `(viewport ${viewport?.width}x${viewport?.height} @${deviceScaleFactor}x), ` +
+            `got ${screenshotSize.width}x${screenshotSize.height}. Text may appear rescaled.`);
+    }
+    if (!isDebugEnabled())
+        return;
+    try {
+        const [runtime, platformFonts] = await Promise.all([
+            page.evaluate(() => {
+                const normalizeFamily = (family) => family.trim().replace(/^['"]|['"]$/g, '');
+                const isGenericFamily = (family) => /^(serif|sans-serif|monospace|cursive|fantasy|system-ui|ui-|emoji|math|fangsong|-apple-system)$/i.test(family);
+                const candidates = Array.from(document.querySelectorAll('h1,h2,h3,p,a,button,label,span,[data-ak]'));
+                const representative = candidates.find((node) => {
+                    const rect = node.getBoundingClientRect();
+                    const text = (node.textContent ?? '').replace(/\s+/g, ' ').trim();
+                    return text.length >= 3 && rect.width > 10 && rect.height > 8;
+                }) ?? document.body;
+                const style = getComputedStyle(representative);
+                const sample = 'AutoKap dashboard Aa 0123456789';
+                const families = style.fontFamily
+                    .split(',')
+                    .map(normalizeFamily)
+                    .filter(Boolean);
+                const primaryFamily = families.find((family) => !/\bFallback\b/i.test(family) && !isGenericFamily(family)) ?? families[0] ?? 'sans-serif';
+                const probe = document.createElement('span');
+                probe.textContent = sample;
+                probe.style.position = 'absolute';
+                probe.style.left = '-99999px';
+                probe.style.top = '0';
+                probe.style.visibility = 'hidden';
+                probe.style.whiteSpace = 'nowrap';
+                probe.style.fontSize = style.fontSize;
+                probe.style.fontWeight = style.fontWeight;
+                probe.style.fontStyle = style.fontStyle;
+                probe.style.letterSpacing = style.letterSpacing;
+                probe.style.fontFeatureSettings = style.fontFeatureSettings;
+                probe.style.fontVariationSettings = style.fontVariationSettings;
+                document.body.appendChild(probe);
+                const measure = (fontFamily) => {
+                    probe.style.fontFamily = fontFamily;
+                    return Number(probe.getBoundingClientRect().width.toFixed(3));
+                };
+                const rect = representative.getBoundingClientRect();
+                const metrics = {
+                    inherited: measure(style.fontFamily),
+                    primary: measure(`"${primaryFamily}", sans-serif`),
+                    system: measure('system-ui, sans-serif'),
+                    sans: measure('sans-serif'),
+                };
+                probe.remove();
+                return {
+                    url: location.href,
+                    dpr: window.devicePixelRatio,
+                    innerWidth: window.innerWidth,
+                    innerHeight: window.innerHeight,
+                    outerWidth: window.outerWidth,
+                    outerHeight: window.outerHeight,
+                    visualViewport: window.visualViewport
+                        ? {
+                            width: window.visualViewport.width,
+                            height: window.visualViewport.height,
+                            scale: window.visualViewport.scale,
+                        }
+                        : null,
+                    representative: {
+                        tagName: representative.tagName,
+                        text: (representative.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 80),
+                        width: Number(rect.width.toFixed(3)),
+                        height: Number(rect.height.toFixed(3)),
+                        fontFamily: style.fontFamily,
+                        primaryFamily,
+                        fontSize: style.fontSize,
+                        fontWeight: style.fontWeight,
+                        letterSpacing: style.letterSpacing,
+                        lineHeight: style.lineHeight,
+                        fontFeatureSettings: style.fontFeatureSettings,
+                        fontVariationSettings: style.fontVariationSettings,
+                    },
+                    metricProbe: {
+                        sample,
+                        ...metrics,
+                        inheritedMatchesPrimary: Math.abs(metrics.inherited - metrics.primary) < 0.01,
+                        inheritedDiffersFromSystem: Math.abs(metrics.inherited - metrics.system) >= 0.01,
+                    },
+                };
+            }),
+            collectPlatformFontDiagnostics(page),
+        ]);
+        logger.debug(`[capture] render diagnostics ${stage}: ${JSON.stringify({
+            viewport,
+            requestedDeviceScaleFactor: options.deviceScaleFactor ?? null,
+            normalizedDeviceScaleFactor: deviceScaleFactor,
+            screenshotSize,
+            expectedScreenshotSize,
+            runtime,
+            platformFonts,
+        })}`);
+    }
+    catch (error) {
+        logger.debug(`[capture] render diagnostics ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /**
  * Map a BCP-47 language tag to a Playwright-compatible locale string.
  * Playwright accepts both "fr" and "fr-FR". We normalize 2-char codes to their
@@ -694,8 +998,9 @@ export class Browser {
         // next/font and other `font-display: swap` setups can report the
         // FontFaceSet as "ready" while visible text is still painted with fallback.
         // We force-load declared and currently computed families, verify the
-        // primary rendered families with document.fonts.check(), then wait for a
-        // committed repaint.
+        // primary rendered families with document.fonts.check(), then run a paint
+        // gate (metric probe + CDP) to confirm a real custom face is in the paint.
+        const startedAt = Date.now();
         await page.evaluate(() => Promise.race([
             (async () => {
                 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -758,6 +1063,22 @@ export class Browser {
             })(),
             new Promise((resolve) => setTimeout(resolve, 8000)),
         ])).catch(() => { });
+        // Paint gate: race in-page metric probe + CDP CSS.getPlatformFontsForNode.
+        // FontFaceSet "loaded" can lie when Blink keeps a stale shaping cache after
+        // a font swap (notably on CI Linux without GPU). The gate observes the
+        // actual paint state, not the FontFaceSet state. Hard 4s ceiling, never
+        // blocks the screenshot — on timeout we proceed and warn so
+        // logCaptureRenderDiagnostics can flag the capture for review.
+        const gate = await gateOnPaintedFont(page, 4000);
+        // Triple rAF — software rasterization (CI Linux, --disable-gpu) sometimes
+        // needs the extra commit before the screenshot pipeline reads the buffer.
+        await page.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))))).catch(() => { });
+        if (gate.via === 'timeout') {
+            logger.warn(`[capture] font paint gate timed out after ${gate.elapsedMs}ms — capture may show fallback metrics`);
+        }
+        else if (isDebugEnabled()) {
+            logger.debug(`[capture] font paint gate resolved via=${gate.via} elapsedMs=${gate.elapsedMs} totalMs=${Date.now() - startedAt}`);
+        }
     }
     async takeScreenshot() {
         const page = this.ensurePage();
@@ -766,7 +1087,9 @@ export class Browser {
         await ensureCaptureHideStyles(page);
         await this.waitForFontsBeforeScreenshot(page);
         await logFontDiagnostics(page, 'before screenshot');
-        return Buffer.from(await page.screenshot({ type: 'png', fullPage: false }));
+        const screenshot = Buffer.from(await page.screenshot({ type: 'png', fullPage: false }));
+        await logCaptureRenderDiagnostics(page, screenshot, this.options, 'after screenshot');
+        return screenshot;
     }
     async takeScreenshotForAI(options = {}) {
         const page = this.ensurePage();

package/dist/cli-runner.js

@@ -29,6 +29,9 @@ import { normalizeAllowedOrigins, normalizeHttpOrigin, verifySignedExecutionProg
 const MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR = 1;
 const FETCH_PROGRAM_MAX_ATTEMPTS = 4;
 const FETCH_PROGRAM_RETRY_DELAYS_MS = [1000, 3000, 5000];
+const DEFAULT_SCREENSHOT_ARTIFACT_UPLOAD_CONCURRENCY = 4;
+const DEFAULT_MEDIA_ARTIFACT_UPLOAD_CONCURRENCY = 2;
+const MAX_ARTIFACT_UPLOAD_CONCURRENCY = 8;
 const HEALER_SYSTEM_PROMPT = 'You repair failed deterministic browser opcodes. Respond only with JSON.';
 // ── Main entry point ────────────────────────────────────────────────
 export async function runCapture(options) {
@@ -271,86 +274,22 @@ function sleep(ms) {
 }
 async function uploadResults(config, program, result) {
     const runId = randomUUID();
-    const totalArtifacts = result.variantResults.reduce((sum, v) => sum + v.artifacts.length, 0);
-    let uploadedCount = 0;
-    // Upload artifacts
-    for (const variant of result.variantResults) {
+    const artifactJobs = result.variantResults.flatMap((variant) => {
         const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);
-        for (const artifact of variant.artifacts) {
-            const formData = new FormData();
-            const filename = buildArtifactFilename(program.presetId, variant.variantId, artifact);
-            uploadedCount += 1;
-            const label = artifact.captureName ?? artifact.clipName ?? filename;
-            logger.info(`[capture] Exporting capture ${uploadedCount}/${totalArtifacts}: ${label}`);
-            formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
-            formData.append('presetId', program.presetId);
-            formData.append('programVersion', String(program.programVersion));
-            formData.append('compileFingerprint', program.compileFingerprint);
-            formData.append('runId', runId);
-            formData.append('variantId', variant.variantId);
-            formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
-            formData.append('targetLabel', variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId);
-            formData.append('mediaMode', artifact.mediaMode);
-            formData.append('mimeType', artifact.mimeType);
-            formData.append('captureType', artifact.captureType ?? 'fullpage');
-            formData.append('captureUrl', artifact.captureUrl ?? program.baseUrl);
-            formData.append('lang', variantSpec?.locale ?? 'en');
-            formData.append('theme', variantSpec?.theme ?? 'light');
-            if (variantSpec?.deviceFrame) {
-                formData.append('deviceFrame', variantSpec.deviceFrame);
-            }
-            const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
-            const deviceScaleFactor = artifact.mediaMode === 'clip' && Number.isFinite(requestedDeviceScaleFactor)
-                ? Math.min(Number(requestedDeviceScaleFactor), MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR)
-                : requestedDeviceScaleFactor;
-            if (Number.isFinite(deviceScaleFactor)) {
-                formData.append('deviceScaleFactor', String(deviceScaleFactor));
-            }
-            formData.append('viewport', JSON.stringify(variantSpec?.viewport ?? null));
-            formData.append('artifactPlan', JSON.stringify(program.artifactPlan));
-            if (artifact.altText) {
-                formData.append('altText', artifact.altText);
-            }
-            if (artifact.elementSelector) {
-                formData.append('elementSelector', artifact.elementSelector);
-            }
-            if (artifact.captureId) {
-                formData.append('captureId', artifact.captureId);
-            }
-            if (artifact.captureName) {
-                formData.append('captureName', artifact.captureName);
-            }
-            if (artifact.clipId) {
-                formData.append('clipId', artifact.clipId);
-            }
-            if (artifact.clipName) {
-                formData.append('clipName', artifact.clipName);
-            }
-            if (artifact.stepDescription) {
-                formData.append('stepDescription', artifact.stepDescription);
-            }
-            if (typeof artifact.stepIndex === 'number') {
-                formData.append('stepIndex', String(artifact.stepIndex));
-            }
-            if (artifact.tabIconData) {
-                formData.append('tabIcon', new Blob([new Uint8Array(artifact.tabIconData)], { type: artifact.tabIconMimeType ?? 'image/png' }), 'favicon');
-            }
-            if (typeof artifact.durationMs === 'number') {
-                formData.append('durationMs', String(artifact.durationMs));
-            }
-            if (typeof artifact.trimStartMs === 'number') {
-                formData.append('trimStartMs', String(artifact.trimStartMs));
-            }
-            const response = await fetch(`${config.apiBaseUrl}/api/cli/artifacts`, {
-                method: 'POST',
-                headers: { 'Authorization': `Bearer ${config.apiKey}` },
-                body: formData,
-            });
-            if (!response.ok) {
-                throw new Error(`artifact upload failed for ${variant.variantId}: ${await formatServerError(response, `${config.apiBaseUrl}/api/cli/artifacts`)}`);
-            }
-        }
+        return variant.artifacts.map((artifact) => ({
+            artifact,
+            variant,
+            variantSpec,
+        }));
+    });
+    const totalArtifacts = artifactJobs.length;
+    const artifactUploadConcurrency = resolveArtifactUploadConcurrency(program, totalArtifacts);
+    if (totalArtifacts > 1) {
+        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);
+    });
     // Strip binary buffers from artifacts before sending. The raw PNG/video
     // buffers were already uploaded via /api/cli/artifacts above, and the
     // server strips them again before persisting. Sending them in the JSON
@@ -405,6 +344,110 @@ async function uploadResults(config, program, result) {
         throw new Error(`telemetry upload failed: ${await formatServerError(telemetryResponse, `${config.apiBaseUrl}/api/cli/telemetry`)}`);
     }
 }
+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}`);
+    formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
+    formData.append('presetId', program.presetId);
+    formData.append('programVersion', String(program.programVersion));
+    formData.append('compileFingerprint', program.compileFingerprint);
+    formData.append('runId', runId);
+    formData.append('variantId', variant.variantId);
+    formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
+    formData.append('targetLabel', variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId);
+    formData.append('mediaMode', artifact.mediaMode);
+    formData.append('mimeType', artifact.mimeType);
+    formData.append('captureType', artifact.captureType ?? 'fullpage');
+    formData.append('captureUrl', artifact.captureUrl ?? program.baseUrl);
+    formData.append('lang', variantSpec?.locale ?? 'en');
+    formData.append('theme', variantSpec?.theme ?? 'light');
+    if (variantSpec?.deviceFrame) {
+        formData.append('deviceFrame', variantSpec.deviceFrame);
+    }
+    const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
+    const deviceScaleFactor = artifact.mediaMode === 'clip' && Number.isFinite(requestedDeviceScaleFactor)
+        ? Math.min(Number(requestedDeviceScaleFactor), MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR)
+        : requestedDeviceScaleFactor;
+    if (Number.isFinite(deviceScaleFactor)) {
+        formData.append('deviceScaleFactor', String(deviceScaleFactor));
+    }
+    formData.append('viewport', JSON.stringify(variantSpec?.viewport ?? null));
+    formData.append('artifactPlan', JSON.stringify(program.artifactPlan));
+    if (artifact.altText) {
+        formData.append('altText', artifact.altText);
+    }
+    if (artifact.elementSelector) {
+        formData.append('elementSelector', artifact.elementSelector);
+    }
+    if (artifact.captureId) {
+        formData.append('captureId', artifact.captureId);
+    }
+    if (artifact.captureName) {
+        formData.append('captureName', artifact.captureName);
+    }
+    if (artifact.clipId) {
+        formData.append('clipId', artifact.clipId);
+    }
+    if (artifact.clipName) {
+        formData.append('clipName', artifact.clipName);
+    }
+    if (artifact.stepDescription) {
+        formData.append('stepDescription', artifact.stepDescription);
+    }
+    if (typeof artifact.stepIndex === 'number') {
+        formData.append('stepIndex', String(artifact.stepIndex));
+    }
+    if (artifact.tabIconData) {
+        formData.append('tabIcon', new Blob([new Uint8Array(artifact.tabIconData)], { type: artifact.tabIconMimeType ?? 'image/png' }), 'favicon');
+    }
+    if (typeof artifact.durationMs === 'number') {
+        formData.append('durationMs', String(artifact.durationMs));
+    }
+    if (typeof artifact.trimStartMs === 'number') {
+        formData.append('trimStartMs', String(artifact.trimStartMs));
+    }
+    const response = await fetch(`${config.apiBaseUrl}/api/cli/artifacts`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${config.apiKey}` },
+        body: formData,
+    });
+    if (!response.ok) {
+        throw new Error(`artifact upload failed for ${variant.variantId}: ${await formatServerError(response, `${config.apiBaseUrl}/api/cli/artifacts`)}`);
+    }
+}
+async function runWithConcurrency(items, concurrency, worker) {
+    if (items.length === 0) {
+        return;
+    }
+    const workerCount = Math.max(1, Math.min(concurrency, items.length));
+    let nextIndex = 0;
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length) {
+                return;
+            }
+            await worker(items[index], index);
+        }
+    }));
+}
+function resolveArtifactUploadConcurrency(program, totalArtifacts) {
+    if (totalArtifacts <= 1) {
+        return 1;
+    }
+    const envValue = process.env.AUTOKAP_UPLOAD_CONCURRENCY?.trim();
+    const parsedEnvValue = envValue ? Number(envValue) : NaN;
+    const requested = Number.isFinite(parsedEnvValue) && parsedEnvValue > 0
+        ? parsedEnvValue
+        : program.mediaMode === 'screenshot'
+            ? DEFAULT_SCREENSHOT_ARTIFACT_UPLOAD_CONCURRENCY
+            : DEFAULT_MEDIA_ARTIFACT_UPLOAD_CONCURRENCY;
+    return Math.min(totalArtifacts, MAX_ARTIFACT_UPLOAD_CONCURRENCY, Math.max(1, Math.floor(requested)));
+}
 async function formatServerError(response, requestedUrl) {
     const contentType = response.headers?.get?.('content-type') ?? '';
     const rawBody = (await response.text()).trim();

package/dist/mockup.js

@@ -555,6 +555,18 @@ export async function applyDeviceFrame(screenshot, deviceId, options) {
     const physicalContentW = Math.round(contentW * os);
     const physicalContentH = Math.round(contentH * os);
     console.log(`[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: ` +
+            `${screenshotMeta.width}x${screenshotMeta.height} -> ` +
+            `${physicalContentW}x${physicalContentH} ` +
+            `(x=${ratioX.toFixed(4)}, y=${ratioY.toFixed(4)}). ` +
+            `Text metrics may appear distorted if the capture viewport does not match the mockup content area.`);
+    }
     // Sample edge colors from the ORIGINAL screenshot before resize.
     // Resizing (especially large downscales with fit:'fill') averages edge pixels,
     // producing grayish artifacts that make safe area fills look darker than intended.

package/package.json

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