autokap 1.8.9 → 1.9.1

package/dist/analytics-blocklist.d.ts

@@ -0,0 +1,85 @@
+import type { BrowserContext } from 'playwright';
+/**
+ * Privacy-signal request headers attached to every capture context.
+ *
+ * These are standard, widely-sent browser headers (Firefox sends `DNT`, Brave
+ * sends `Sec-GPC`), so they're invisible to origin anti-bot defenses — they
+ * only ever observe a normal first-party page load. Privacy-first analytics
+ * (Plausible, Fathom, …) honor them and suppress the pageview, which
+ * complements the network-level blocking below for the providers that respect
+ * the signal. Free, zero-risk belt-and-suspenders.
+ */
+export declare const PRIVACY_HEADERS: Record<string, string>;
+/**
+ * Hostnames of DEDICATED web-analytics / product-telemetry / session-replay
+ * endpoints. These domains serve ONLY analytics, so aborting requests to them
+ * during a capture has zero functional impact on the page being screenshotted —
+ * it only prevents AutoKap's automated visit from registering as a phantom
+ * "visitor" in the site owner's analytics (AUT-234).
+ *
+ * Matched by exact host OR sub-domain suffix
+ * (`host === h || host.endsWith('.' + h)`), so regional shards
+ * (`eu.i.posthog.com`, `region1.google-analytics.com`, `*.matomo.cloud`, …) are
+ * covered without enumerating each one.
+ *
+ * Deliberately ABSENT: `googletagmanager.com`. GTM can inject functional tags,
+ * and loading `gtm.js` does NOT itself record a visit — the GA *beacon* to
+ * `google-analytics.com` does, and that host IS blocked. So we neutralize the
+ * GA visit without risking a broken page.
+ *
+ * Self-hosted / first-party-proxied analytics (e.g. Plausible reverse-proxied
+ * on the site's own domain) is intentionally NOT covered: it reads as
+ * first-party (see the `isFirstPartyUrl` guard in {@link installAnalyticsBlock})
+ * and is impossible to detect universally. That edge case is out of scope by
+ * design — catching it would depend on per-site configuration.
+ */
+export declare const ANALYTICS_HOSTS: readonly string[];
+/**
+ * True when `url` targets a dedicated web-analytics *ingestion* endpoint (see
+ * {@link ANALYTICS_HOSTS}). Host-suffix aware so regional/sub-domain shards
+ * match their parent. Fail-CLOSED on unparseable or non-http(s) URLs (returns
+ * `false`): we never abort a request we can't confidently classify.
+ *
+ * For hosts that co-serve functional config on the same domain as their
+ * analytics (PostHog), only the event-capture paths count — feature-flag /
+ * config / library paths are preserved so the captured UI never changes
+ * (see {@link POSTHOG_FUNCTIONAL_PATH_RE}).
+ */
+export declare function isAnalyticsRequest(url: string): boolean;
+/**
+ * The per-request block decision, factored out of {@link installAnalyticsBlock}
+ * so the guard composition is unit-testable without a real browser context.
+ *
+ * Blocks ONLY a third-party analytics request. A first-party one — analytics
+ * self-hosted or reverse-proxied on the captured site's OWN domain — is
+ * preserved so we can never break the site's own functionality.
+ *
+ * `pageUrl` is the request's frame URL. When it's empty/unknown (a request in
+ * flight before the first navigation commits, a detached/teardown frame, some
+ * worker-originated requests) `isFirstPartyUrl` fail-OPENS to first-party, so
+ * the beacon is NOT aborted. That's the deliberate safe direction — never break
+ * a page — at the cost of a rare phantom-visit leak in that narrow window; real
+ * analytics beacons fire after navigation commits, so the frame URL is present.
+ */
+export declare function shouldBlockAnalyticsRequest(pageUrl: string, requestUrl: string): boolean;
+/**
+ * Install a context-level route that aborts outgoing requests to dedicated
+ * third-party analytics endpoints, so capturing a site never registers a
+ * phantom "visit" in its analytics (AUT-234).
+ *
+ * Only THIRD-party analytics is blocked (the `!isFirstPartyUrl` guard): a
+ * first-party request is never aborted, so we can never break the captured
+ * site's own functionality. Aborting a third-party beacon is invisible to the
+ * origin's anti-bot (it only ever sees a normal first-party page load) — exactly
+ * what an ad-blocker does — so this carries no risk of tripping bot defenses.
+ *
+ * Registered at the CONTEXT level so it (a) covers every page/frame in the
+ * context, (b) survives `page.unrouteAll()` from `clearRouteInterception()`
+ * (which only clears page-level routes), and (c) composes with the page-level
+ * mock routes from `setupRouteInterception()` — page routes run first; this
+ * catch-all `fallback()`s every non-analytics request back to the network (or
+ * the next handler). Aborting also lowers in-flight count, which only helps
+ * `networkidle` settle. The adaptive-wait progress signal already ignores
+ * third-party traffic (AUT-240), so there's no interaction there.
+ */
+export declare function installAnalyticsBlock(context: BrowserContext): Promise<void>;

package/dist/analytics-blocklist.js

@@ -0,0 +1,201 @@
+import { isFirstPartyUrl } from './security.js';
+/**
+ * Privacy-signal request headers attached to every capture context.
+ *
+ * These are standard, widely-sent browser headers (Firefox sends `DNT`, Brave
+ * sends `Sec-GPC`), so they're invisible to origin anti-bot defenses — they
+ * only ever observe a normal first-party page load. Privacy-first analytics
+ * (Plausible, Fathom, …) honor them and suppress the pageview, which
+ * complements the network-level blocking below for the providers that respect
+ * the signal. Free, zero-risk belt-and-suspenders.
+ */
+export const PRIVACY_HEADERS = {
+    DNT: '1',
+    'Sec-GPC': '1',
+};
+/**
+ * Hostnames of DEDICATED web-analytics / product-telemetry / session-replay
+ * endpoints. These domains serve ONLY analytics, so aborting requests to them
+ * during a capture has zero functional impact on the page being screenshotted —
+ * it only prevents AutoKap's automated visit from registering as a phantom
+ * "visitor" in the site owner's analytics (AUT-234).
+ *
+ * Matched by exact host OR sub-domain suffix
+ * (`host === h || host.endsWith('.' + h)`), so regional shards
+ * (`eu.i.posthog.com`, `region1.google-analytics.com`, `*.matomo.cloud`, …) are
+ * covered without enumerating each one.
+ *
+ * Deliberately ABSENT: `googletagmanager.com`. GTM can inject functional tags,
+ * and loading `gtm.js` does NOT itself record a visit — the GA *beacon* to
+ * `google-analytics.com` does, and that host IS blocked. So we neutralize the
+ * GA visit without risking a broken page.
+ *
+ * Self-hosted / first-party-proxied analytics (e.g. Plausible reverse-proxied
+ * on the site's own domain) is intentionally NOT covered: it reads as
+ * first-party (see the `isFirstPartyUrl` guard in {@link installAnalyticsBlock})
+ * and is impossible to detect universally. That edge case is out of scope by
+ * design — catching it would depend on per-site configuration.
+ */
+export const ANALYTICS_HOSTS = [
+    // Google Analytics / GA4 / Universal Analytics collection endpoints
+    'google-analytics.com',
+    'analytics.google.com',
+    'ssl.google-analytics.com',
+    'region1.google-analytics.com',
+    'stats.g.doubleclick.net',
+    // Plausible
+    'plausible.io',
+    // PostHog — only its event-ingestion paths are blocked; feature-flag / config
+    // / library paths (/decide, /flags, /static, /array) are preserved so a
+    // flag-gated app never renders with default flags (see isAnalyticsRequest).
+    'posthog.com',
+    'i.posthog.com',
+    // Matomo / Piwik (cloud)
+    'matomo.cloud',
+    'matomo.org',
+    // Segment
+    'segment.io',
+    'segment.com',
+    // Mixpanel
+    'mixpanel.com',
+    'mxpnl.com',
+    // Amplitude
+    'amplitude.com',
+    // Heap
+    'heapanalytics.com',
+    'heap.io',
+    // Hotjar (heatmaps / session replay)
+    'hotjar.com',
+    'hotjar.io',
+    // Microsoft Clarity (session replay)
+    'clarity.ms',
+    // Cloudflare Web Analytics
+    'cloudflareinsights.com',
+    // Vercel Analytics / Speed Insights
+    'vercel-insights.com',
+    'va.vercel-scripts.com',
+    // Fathom
+    'usefathom.com',
+    // Session replay / heatmaps
+    'fullstory.com',
+    'mouseflow.com',
+    'crazyegg.com',
+    // Yandex Metrica
+    'mc.yandex.ru',
+    // Quantcast
+    'quantserve.com',
+    'quantcount.com',
+    // Adobe Analytics (Omniture)
+    'omtrdc.net',
+    '2o7.net',
+    // Misc product analytics
+    'pendo.io',
+    'woopra.com',
+    'kissmetrics.io',
+];
+const ANALYTICS_HOST_SET = new Set(ANALYTICS_HOSTS.map((h) => h.toLowerCase()));
+/**
+ * Path prefixes on PostHog hosts that are NOT analytics ingestion: feature
+ * flags (`/decide`, `/flags`), the JS library and its remote config
+ * (`/static`, `/array`). PostHog co-serves these from the SAME host as its
+ * event capture, so blocking them would make a flag-gated app render with
+ * default flags during capture — a visible change to the captured UI. We only
+ * block the ingestion paths (`/e/`, `/i/v0/e/`, `/batch/`, `/capture/`, `/s/`),
+ * which is what records the phantom visit.
+ */
+const POSTHOG_FUNCTIONAL_PATH_RE = /^\/(decide|flags|static|array)\b/i;
+function matchesAnalyticsHost(host) {
+    if (ANALYTICS_HOST_SET.has(host))
+        return true;
+    for (const h of ANALYTICS_HOST_SET) {
+        if (host.endsWith(`.${h}`))
+            return true;
+    }
+    return false;
+}
+function isPosthogHost(host) {
+    return host === 'posthog.com' || host.endsWith('.posthog.com');
+}
+/**
+ * True when `url` targets a dedicated web-analytics *ingestion* endpoint (see
+ * {@link ANALYTICS_HOSTS}). Host-suffix aware so regional/sub-domain shards
+ * match their parent. Fail-CLOSED on unparseable or non-http(s) URLs (returns
+ * `false`): we never abort a request we can't confidently classify.
+ *
+ * For hosts that co-serve functional config on the same domain as their
+ * analytics (PostHog), only the event-capture paths count — feature-flag /
+ * config / library paths are preserved so the captured UI never changes
+ * (see {@link POSTHOG_FUNCTIONAL_PATH_RE}).
+ */
+export function isAnalyticsRequest(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return false;
+    const host = parsed.hostname.toLowerCase();
+    if (!matchesAnalyticsHost(host))
+        return false;
+    if (isPosthogHost(host) && POSTHOG_FUNCTIONAL_PATH_RE.test(parsed.pathname)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * The per-request block decision, factored out of {@link installAnalyticsBlock}
+ * so the guard composition is unit-testable without a real browser context.
+ *
+ * Blocks ONLY a third-party analytics request. A first-party one — analytics
+ * self-hosted or reverse-proxied on the captured site's OWN domain — is
+ * preserved so we can never break the site's own functionality.
+ *
+ * `pageUrl` is the request's frame URL. When it's empty/unknown (a request in
+ * flight before the first navigation commits, a detached/teardown frame, some
+ * worker-originated requests) `isFirstPartyUrl` fail-OPENS to first-party, so
+ * the beacon is NOT aborted. That's the deliberate safe direction — never break
+ * a page — at the cost of a rare phantom-visit leak in that narrow window; real
+ * analytics beacons fire after navigation commits, so the frame URL is present.
+ */
+export function shouldBlockAnalyticsRequest(pageUrl, requestUrl) {
+    return isAnalyticsRequest(requestUrl) && !isFirstPartyUrl(pageUrl, requestUrl);
+}
+/**
+ * Install a context-level route that aborts outgoing requests to dedicated
+ * third-party analytics endpoints, so capturing a site never registers a
+ * phantom "visit" in its analytics (AUT-234).
+ *
+ * Only THIRD-party analytics is blocked (the `!isFirstPartyUrl` guard): a
+ * first-party request is never aborted, so we can never break the captured
+ * site's own functionality. Aborting a third-party beacon is invisible to the
+ * origin's anti-bot (it only ever sees a normal first-party page load) — exactly
+ * what an ad-blocker does — so this carries no risk of tripping bot defenses.
+ *
+ * Registered at the CONTEXT level so it (a) covers every page/frame in the
+ * context, (b) survives `page.unrouteAll()` from `clearRouteInterception()`
+ * (which only clears page-level routes), and (c) composes with the page-level
+ * mock routes from `setupRouteInterception()` — page routes run first; this
+ * catch-all `fallback()`s every non-analytics request back to the network (or
+ * the next handler). Aborting also lowers in-flight count, which only helps
+ * `networkidle` settle. The adaptive-wait progress signal already ignores
+ * third-party traffic (AUT-240), so there's no interaction there.
+ */
+export async function installAnalyticsBlock(context) {
+    await context.route('**/*', (route) => {
+        const request = route.request();
+        const url = request.url();
+        // Derive the page origin from the request's own frame so analytics
+        // self-hosted on the captured site's domain reads as first-party and is
+        // left untouched. `'blockedbyclient'` mimics an ad-blocker (the page just
+        // sees a failed beacon, like every uBlock user).
+        const pageUrl = request.frame()?.url() || '';
+        if (shouldBlockAnalyticsRequest(pageUrl, url)) {
+            return route.abort('blockedbyclient').catch(() => undefined);
+        }
+        return route.fallback();
+    });
+}
+//# sourceMappingURL=analytics-blocklist.js.map

package/dist/browser-pool.d.ts

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

package/dist/browser-pool.js

@@ -1,4 +1,5 @@
 import { chromium } from 'playwright';
+import { installAnalyticsBlock, PRIVACY_HEADERS } from './analytics-blocklist.js';
 /** Chromium flags for server-side headless operation (used by pool and standalone launches). */
 export const CHROMIUM_ARGS = [
     // Linux/Docker-only: required when running Chromium as root or with limited /dev/shm
@@ -74,8 +75,16 @@ class BrowserPool {
             locale: options?.lang ? options.lang : 'en-US',
             colorScheme: options?.colorScheme ?? 'light',
             storageState: options?.storageState,
-            ...(extra && Object.keys(extra).length > 0 ? { extraHTTPHeaders: extra } : {}),
+            // Privacy signals first, then merge user/env auth headers (which win on
+            // any conflict). See PRIVACY_HEADERS / installAnalyticsBlock (AUT-234).
+            extraHTTPHeaders: { ...PRIVACY_HEADERS, ...(extra ?? {}) },
         });
+        // Block third-party analytics so pooled (server-side) captures don't
+        // register a phantom visit in the captured site's analytics (AUT-234).
+        // Skippable per-project via blockAnalytics === false.
+        if (options?.blockAnalytics !== false) {
+            await installAnalyticsBlock(context);
+        }
         this.activeContexts++;
         this.captureCount++;
         return context;

package/dist/browser.js

@@ -6,6 +6,7 @@ import { join } from 'path';
 import { DOM_QUIET_WINDOW_MS, GLOBAL_WAIT_CAP_MS, PIXEL_FALLBACK_DIFF_THRESHOLD, PIXEL_FALLBACK_MAX_PASSES, } from './wait-contract.js';
 import { buildAKNodeRuntimeIndex, deriveInteractiveElementsFromAKTree, disambiguateFingerprint, focusAKTree, fingerprintAKNode, serializeAKTree, } from './ak-tree.js';
 import { isFirstPartyUrl } from './security.js';
+import { installAnalyticsBlock, PRIVACY_HEADERS } from './analytics-blocklist.js';
 /**
  * Set-of-Marks (SoM) annotation: overlays colored [N] badges on each visible
  * interactive element so the vision model can reference elements by their badge index.
@@ -949,6 +950,7 @@ export class Browser {
             colorScheme: options.colorScheme ?? 'light',
             storageState: options.storageState,
             extraHttpHeaders: options.extraHttpHeaders,
+            blockAnalytics: options.blockAnalytics,
         });
         instance.page = await instance.context.newPage();
         instance.poolContext = true;
@@ -1068,9 +1070,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 }
-                : {}),
+            // Privacy signals first, then merge user/env auth headers (which win on
+            // any conflict). See PRIVACY_HEADERS / installAnalyticsBlock (AUT-234).
+            extraHTTPHeaders: { ...PRIVACY_HEADERS, ...(options.extraHttpHeaders ?? {}) },
         };
         // Dedicated browser process for clip capture. Not pooled because clip
         // capture installs context-level init scripts (cursor overlay). Cloud Run
@@ -1109,6 +1111,13 @@ export class Browser {
             });
             instance.context = await instance.browser.newContext(contextOptions);
         }
+        // Block third-party analytics beacons so clip/video capture doesn't
+        // register a phantom visit either (AUT-234). Context-level so it covers
+        // every page in both the persistent (cloud) and incognito (local) paths.
+        // Skippable per-project via blockAnalytics === false.
+        if (options.blockAnalytics !== false) {
+            await installAnalyticsBlock(instance.context);
+        }
         // Cloud Run only: inject the notranslate meta on every navigation so
         // Chromium's translate UI never prompts. The --disable-features=Translate*
         // launch flags are unreliable across Chromium versions (some translate
@@ -1244,6 +1253,9 @@ export class Browser {
             args: CHROMIUM_ARGS,
         });
         this.context = await this.browser.newContext(this.buildContextOptions());
+        if (this.options.blockAnalytics !== false) {
+            await installAnalyticsBlock(this.context);
+        }
         this.page = await this.context.newPage();
         this.attachDebugLifecycleListeners();
     }
@@ -1333,6 +1345,9 @@ export class Browser {
             this.context = null;
         }
         this.context = await this.browser.newContext(this.buildContextOptions());
+        if (this.options.blockAnalytics !== false) {
+            await installAnalyticsBlock(this.context);
+        }
         this.page = await this.context.newPage();
         this.elementMap.clear();
         this.attachDebugLifecycleListeners();
@@ -5631,10 +5646,11 @@ export class Browser {
     async setLanguage(lang) {
         const context = this.ensureContext();
         const page = this.ensurePage();
-        // `setExtraHTTPHeaders` REPLACES the header map — merge with the
-        // environment-level auth headers so a SET_LOCALE opcode doesn't strip
-        // them mid-run.
+        // `setExtraHTTPHeaders` REPLACES the header map — merge with the privacy
+        // signals and the environment-level auth headers so a SET_LOCALE opcode
+        // doesn't strip them mid-run.
         await context.setExtraHTTPHeaders({
+            ...PRIVACY_HEADERS,
             ...(this.options.extraHttpHeaders ?? {}),
             'Accept-Language': lang,
         });
@@ -5761,7 +5777,9 @@ export class Browser {
             locale: langToLocale(this.options.lang ?? 'en'),
             colorScheme: this.options.colorScheme ?? 'light',
             storageState: this.options.storageState,
-            ...(extra && Object.keys(extra).length > 0 ? { extraHTTPHeaders: extra } : {}),
+            // Privacy signals first, then merge user/env auth headers (which win on
+            // any conflict). See PRIVACY_HEADERS / installAnalyticsBlock (AUT-234).
+            extraHTTPHeaders: { ...PRIVACY_HEADERS, ...(extra ?? {}) },
         };
     }
 }

package/dist/cli-contract.d.ts

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

package/dist/cli-runner.d.ts

@@ -49,6 +49,13 @@ export interface CLIRunnerOptions {
      * When `false`, skips the failed-run debug logs export (AUT-149).
      */
     exportDebugLogs?: boolean;
+    /**
+     * Shared invocation id for billing. A multi-preset invocation (`run --outdated`,
+     * `auto-recapture`) passes one sessionId for every preset so all their charges
+     * group into a single "CLI capture" entry (migration 267). Defaults to the
+     * run's own id for a single-preset invocation.
+     */
+    sessionId?: string;
 }
 export interface CLIRunResult {
     success: boolean;

package/dist/cli-runner.js

@@ -156,6 +156,10 @@ export async function runCapture(options) {
     // here; we seed mockup.ts so the export pipeline can apply them locally.
     seedDeviceConfigs(program.deviceConfigs ?? null);
     const runId = randomUUID();
+    // A multi-preset invocation shares one sessionId so every preset's charges
+    // group into one "CLI capture" billing entry; a lone run groups under its own
+    // runId (migration 267).
+    const sessionId = options.sessionId ?? runId;
     let videoAudioAssets;
     let videoAudioAssetsByLocale;
     try {
@@ -170,7 +174,7 @@ export async function runCapture(options) {
     // durations + audio assets are only consumed on the upload path (signalVideoComplete), which a dry
     // run never reaches, so skipping prep here is side-effect-free for dry.
     if (!options.dryRun && !options.program && program.mediaMode === 'video') {
-        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false);
+        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false, sessionId);
         if (!prepareResult.success) {
             return { success: false, runId, error: prepareResult.error };
         }
@@ -254,6 +258,7 @@ export async function runCapture(options) {
             colorScheme: variant.theme,
             storageState: program.preconditions.storageState,
             extraHttpHeaders: program.environmentHttpHeaders,
+            blockAnalytics: program.blockAnalytics,
         };
         let recordingDir;
         let browser;
@@ -308,7 +313,7 @@ export async function runCapture(options) {
                     message: 'saving captures',
                 });
                 const provenance = buildRunProvenance(program, schemaVersionOrigin);
-                const uploadOutcome = await uploadResults(config, program, runResult, runId, provenance);
+                const uploadOutcome = await uploadResults(config, program, runResult, runId, sessionId, provenance);
                 if (program.mediaMode === 'video' && runResult.success) {
                     await signalVideoComplete(config, program, runResult, uploadOutcome.runId, videoAudioAssets, videoAudioAssetsByLocale);
                 }
@@ -356,7 +361,7 @@ export async function runCapture(options) {
             && (runResult ? !runResult.success : true);
         if (shouldExport) {
             logger.info('[debug-logs] Exporting debug logs to AutoKap…');
-            await logCollector.flushTo(runId, program.presetId, config.apiBaseUrl, config.apiKey, options.env);
+            await logCollector.flushTo(runId, program.presetId, config.apiBaseUrl, config.apiKey, options.env, runResult?.failureKind);
         }
         logCollector.stop();
     }
@@ -430,7 +435,7 @@ async function fetchProgram(config, presetId, environmentName) {
     }
     return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
 }
-async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts) {
+async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId) {
     if (regenerateTts) {
         logger.info('[capture] Forcing TTS regeneration — all cached segments will be re-synthesized and billed.');
     }
@@ -445,7 +450,9 @@ async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts) {
                 'Content-Type': 'application/json',
                 [CLI_VERSION_HEADER]: APP_VERSION,
             },
-            body: JSON.stringify(regenerateTts ? { videoId, runId, regenerateTts: true } : { videoId, runId }),
+            body: JSON.stringify(regenerateTts
+                ? { videoId, runId, sessionId, regenerateTts: true }
+                : { videoId, runId, sessionId }),
         });
     }
     catch (err) {
@@ -686,7 +693,7 @@ async function postRunStart(config, runId, presetId, variantCount, env) {
         logger.warn(`[capture] Run registration error: ${message}`);
     }
 }
-async function uploadResults(config, program, result, runId, provenance) {
+async function uploadResults(config, program, result, runId, sessionId, provenance) {
     const artifactJobs = result.variantResults.flatMap((variant) => {
         const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);
         return variant.artifacts.map((artifact) => ({
@@ -701,7 +708,7 @@ async function uploadResults(config, program, result, runId, provenance) {
         logger.info(`[capture] Uploading ${totalArtifacts} capture artifacts with concurrency ${artifactUploadConcurrency}`);
     }
     await runWithConcurrency(artifactJobs, artifactUploadConcurrency, async (job, index) => {
-        await uploadArtifact(config, program, runId, totalArtifacts, index + 1, job, provenance);
+        await uploadArtifact(config, program, runId, sessionId, totalArtifacts, index + 1, job, provenance);
     });
     // Strip binary buffers from artifacts before sending. The raw PNG/video
     // buffers were already uploaded via /api/cli/artifacts above, and the
@@ -862,18 +869,19 @@ function inferVariantLocale(variantId) {
 function inferVariantTheme(variantId) {
     return variantId.endsWith('-dark') ? 'dark' : 'light';
 }
-async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumber, job, provenance) {
+async function uploadArtifact(config, program, runId, sessionId, totalArtifacts, uploadNumber, job, provenance) {
     const { artifact, variant, variantSpec } = job;
     const filename = buildArtifactFilename(program.presetId, variant.variantId, artifact);
     const label = artifact.captureName ?? artifact.clipName ?? filename;
     logger.info(`[capture] Exporting capture ${uploadNumber}/${totalArtifacts}: ${label}`);
     if (process.env.AUTOKAP_USE_LEGACY_MULTIPART_UPLOADS === '1') {
-        await uploadArtifactMultipart(config, program, runId, job, filename, provenance);
+        await uploadArtifactMultipart(config, program, runId, sessionId, job, filename, provenance);
         return;
     }
     const prepared = await prepareDirectArtifactUpload({
         program,
         runId,
+        sessionId,
         artifact,
         variant,
         variantSpec,
@@ -938,7 +946,7 @@ async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumb
         throw new Error(`artifact completion failed for ${variant.variantId}: ${await formatServerError(completeResponse, completeUrl)}`);
     }
 }
-async function uploadArtifactMultipart(config, program, runId, job, filename, provenance) {
+async function uploadArtifactMultipart(config, program, runId, sessionId, job, filename, provenance) {
     const { artifact, variant, variantSpec } = job;
     const formData = new FormData();
     formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
@@ -952,6 +960,7 @@ async function uploadArtifactMultipart(config, program, runId, job, filename, pr
     formData.append('cliVersion', provenance.cliVersion);
     formData.append('programHash', provenance.programHash);
     formData.append('runId', runId);
+    formData.append('sessionId', sessionId);
     formData.append('variantId', variant.variantId);
     formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
     formData.append('targetLabel', variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId);
@@ -1023,7 +1032,7 @@ async function uploadArtifactMultipart(config, program, runId, job, filename, pr
     }
 }
 async function prepareDirectArtifactUpload(params) {
-    const { program, runId, artifact, variant, variantSpec, provenance } = params;
+    const { program, runId, sessionId, artifact, variant, variantSpec, provenance } = params;
     const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
     const isFrameCapture = artifact.mediaMode === 'clip' || artifact.mediaMode === 'video';
     const deviceScaleFactor = isFrameCapture && Number.isFinite(requestedDeviceScaleFactor)
@@ -1040,6 +1049,7 @@ async function prepareDirectArtifactUpload(params) {
         cliVersion: provenance.cliVersion,
         programHash: provenance.programHash,
         runId,
+        sessionId,
         variantId: variant.variantId,
         targetId: variantSpec?.targetId ?? variant.variantId,
         targetLabel: variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId,

package/dist/cli.js

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

package/dist/execution-schema.d.ts

@@ -2233,6 +2233,7 @@ export declare const ExecutionProgramSchema: z.ZodObject<{
     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>>;
+    blockAnalytics: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const HealerPatchSchema: z.ZodObject<{
     opcodeIndex: z.ZodNumber;
@@ -4936,6 +4937,7 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
     deviceConfigs?: Record<string, Record<string, unknown>> | undefined;
     publicUrl?: string | undefined;
     environmentHttpHeaders?: Record<string, string> | undefined;
+    blockAnalytics?: boolean | undefined;
 }>;
 export interface ClipNavigationViolation {
     /** Index of the offending NAVIGATE opcode in `program.steps`. */

package/dist/execution-schema.js

@@ -682,6 +682,12 @@ export const ExecutionProgramSchema = z.object({
     // 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(),
+    // Per-project opt-out for analytics blocking (AUT-234). Optional and WITHOUT a
+    // Zod default for the same signing reason as `programSchemaVersion` above:
+    // this schema is reused in signature verification, so a default would mutate
+    // the signed payload and break symmetry for programs signed without the field.
+    // Absent / true ⇒ block (engine default); only an explicit false disables.
+    blockAnalytics: z.boolean().optional(),
 }).strict().superRefine((value, ctx) => {
     if (value.mediaMode !== value.artifactPlan.mediaMode) {
         ctx.addIssue({

package/dist/execution-types.d.ts

@@ -614,6 +614,14 @@ export interface ExecutionProgram {
      * and embedded in the signed program envelope.
      */
     environmentHttpHeaders?: Record<string, string>;
+    /**
+     * Per-project opt-out for third-party analytics blocking (AUT-234). Default
+     * behavior (field absent / `true`) blocks analytics beacons during capture so
+     * a run never registers a phantom "visit". Set to `false` only when the
+     * project disabled it (`projects.block_analytics_enabled = false`). Server-set
+     * BEFORE signing, so it lives inside the signed envelope.
+     */
+    blockAnalytics?: boolean;
 }
 export interface CircuitBreakerConfig {
     /** Max recovery attempts per opcode. Default: 3 */
@@ -654,6 +662,13 @@ export interface OpcodeResult {
     /** Error message if failed */
     error?: string;
 }
+/**
+ * Structured failure category, set on top of the free-text `error`. Lets the
+ * server surface a specific preset state instead of a generic "failed":
+ * `login_failed` = an opcode inside the login window (credential typing → first
+ * post-login assertion) failed, so the credentials are likely wrong.
+ */
+export type RunFailureKind = 'login_failed';
 export interface VariantResult {
     variantId: string;
     success: boolean;
@@ -670,6 +685,8 @@ export interface VariantResult {
      */
     detectedAppVersion?: string | null;
     error?: string;
+    /** Set when the failure falls inside the login window — see RunFailureKind. */
+    failureKind?: RunFailureKind;
 }
 export interface ArtifactResult {
     mediaMode: MediaMode;
@@ -821,6 +838,8 @@ export interface RunResult {
      */
     warnings?: string[];
     error?: string;
+    /** First non-null variant `failureKind` — see RunFailureKind. */
+    failureKind?: RunFailureKind;
 }
 export interface WaitCondition {
     selector: string;

package/dist/log-collector.d.ts

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

package/dist/log-collector.js

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

package/dist/login-detection.d.ts

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

package/dist/login-detection.js

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

package/dist/opcode-actions.js

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

package/dist/opcode-runner.js

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

package/dist/program-signing.d.ts

@@ -1139,6 +1139,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
         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>>;
+        blockAnalytics: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     signature: z.ZodString;
     meta: z.ZodOptional<z.ZodObject<{

package/dist/types.d.ts

@@ -257,6 +257,13 @@ export interface BrowserOptions {
      * secrets here.
      */
     extraHttpHeaders?: Record<string, string>;
+    /**
+     * When `false`, the engine does NOT block third-party web-analytics beacons
+     * during capture (AUT-234). Default behavior (`undefined` / `true`) blocks
+     * them so a capture never registers a phantom "visit" in the site's
+     * analytics. Opt-out is a per-project setting (`projects.block_analytics_enabled`).
+     */
+    blockAnalytics?: boolean;
 }
 export interface OutscaleConfig {
     /** Uniform padding on all 4 sides (pixels). */

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

@@ -1158,6 +1158,7 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
         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>>;
+        blockAnalytics: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     narration: z.ZodOptional<z.ZodObject<{
         voice: z.ZodString;

package/package.json

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