autokap 1.8.6 → 1.8.8

package/dist/program-migrations.js

@@ -0,0 +1,93 @@
+/**
+ * Capture Agent — Program FORM migrations (migrate-on-read)
+ *
+ * Old presets are stored at whatever `programSchemaVersion` (FORM) was current
+ * when they were authored. `upgradeProgram` runs a chain of pure
+ * `migrate_vN→vN+1` functions to bring any stored program up to the current
+ * form BEFORE strict schema validation, so the runner only ever sees one shape.
+ *
+ * Properties of this layer (decisions locked in AUT-242):
+ * - Compat forever: the chain is kept indefinitely; no support window.
+ * - Migrate-on-read only: programs are NEVER rewritten back to storage. The
+ *   stored form changes only when the generator recompiles (create/modify).
+ * - Pure + idempotent: a program already at the current form is a no-op.
+ *
+ * This module is intentionally free of Node-only imports so it can be pulled
+ * into the schema validation chain on any runtime. Content hashing
+ * (`node:crypto`) lives in program-hash.ts.
+ */
+import { CURRENT_PROGRAM_SCHEMA_VERSION } from './engine-version.js';
+/** Canonical video capture/delivery resolution (1920×1080 @1×). */
+const VIDEO_RESOLUTION = { width: 1920, height: 1080 };
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Reads the FORM version a raw (pre-migration) program was stored at.
+ * Absent / non-finite ⇒ 0 (the oldest form). Used to stamp run provenance
+ * (`program_schema_version_origin`) before `upgradeProgram` bumps it.
+ */
+export function readOriginSchemaVersion(raw) {
+    if (isRecord(raw) &&
+        typeof raw.programSchemaVersion === 'number' &&
+        Number.isFinite(raw.programSchemaVersion)) {
+        return raw.programSchemaVersion;
+    }
+    return 0;
+}
+/**
+ * v0 → v1: fold the legacy video capture-resolution normalization (formerly the
+ * runtime `normalizeVideoCaptureProgram` in cli-runner.ts) into the program
+ * FORM. Legacy video presets carrying viewport=2560×1440 / DPR=1.3333 /
+ * captureResolution=2560×1440 are normalized to 1920×1080 @1×. Non-video
+ * programs pass through unchanged. Defensive on malformed shapes — anything it
+ * can't normalize is left for the strict schema to reject with a clean error.
+ */
+function migrate_0_to_1(prog) {
+    if (prog.mediaMode !== 'video')
+        return prog;
+    const artifactPlan = isRecord(prog.artifactPlan) ? prog.artifactPlan : undefined;
+    const format = artifactPlan && isRecord(artifactPlan.format) ? artifactPlan.format : {};
+    const variants = Array.isArray(prog.variants)
+        ? prog.variants.map((v) => isRecord(v) ? { ...v, viewport: { ...VIDEO_RESOLUTION }, deviceScaleFactor: 1 } : v)
+        : prog.variants;
+    return {
+        ...prog,
+        outputScale: 1,
+        variants,
+        artifactPlan: {
+            ...(artifactPlan ?? {}),
+            format: {
+                ...format,
+                captureResolution: { ...VIDEO_RESOLUTION },
+                deliveryResolution: { ...VIDEO_RESOLUTION },
+            },
+        },
+    };
+}
+/** Ordered FORM migrations. `MIGRATIONS[n]` upgrades a vN program to vN+1. */
+const MIGRATIONS = {
+    0: migrate_0_to_1,
+};
+/**
+ * Brings any stored program up to {@link CURRENT_PROGRAM_SCHEMA_VERSION} (form)
+ * before strict validation. Pure: clones, never mutates `raw`. Idempotent: a
+ * program already at the current form is returned with only its version stamped.
+ * Non-object input is returned untouched so the schema raises a clean error.
+ */
+export function upgradeProgram(raw) {
+    if (!isRecord(raw))
+        return raw;
+    let prog = { ...raw };
+    let v = readOriginSchemaVersion(raw);
+    while (v < CURRENT_PROGRAM_SCHEMA_VERSION) {
+        const migrate = MIGRATIONS[v];
+        if (!migrate)
+            break; // no path forward; let the schema reject a wrong shape
+        prog = migrate(prog);
+        v += 1;
+    }
+    prog.programSchemaVersion = CURRENT_PROGRAM_SCHEMA_VERSION;
+    return prog;
+}
+//# sourceMappingURL=program-migrations.js.map

package/dist/program-signing.d.ts

@@ -13,6 +13,13 @@ export interface SignedExecutionProgramEnvelope {
     signature: string;
     meta?: {
         stale?: boolean;
+        /**
+         * FORM version the stored program was at BEFORE the server migrated it
+         * (0 = legacy / no version field). Debug-only run provenance; lives in the
+         * UNSIGNED meta because it carries no security weight — the server reads it
+         * from the raw preset config before `extractExecutionProgram` normalizes.
+         */
+        programSchemaVersionOrigin?: number;
     };
 }
 export declare const ProgramSecurityMetadataSchema: z.ZodObject<{
@@ -31,6 +38,8 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
     program: z.ZodObject<{
         presetId: z.ZodString;
         programVersion: z.ZodNumber;
+        programSchemaVersion: z.ZodOptional<z.ZodNumber>;
+        engineVersion: z.ZodOptional<z.ZodNumber>;
         mediaMode: z.ZodEnum<{
             video: "video";
             clip: "clip";
@@ -141,6 +150,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
                 domain: z.ZodString;
                 path: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
+            scenario: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             url: z.ZodString;
@@ -1133,6 +1143,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
     signature: z.ZodString;
     meta: z.ZodOptional<z.ZodObject<{
         stale: z.ZodOptional<z.ZodBoolean>;
+        programSchemaVersionOrigin: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare function normalizeAllowedOrigins(origins: Iterable<string>): string[];

package/dist/program-signing.js

@@ -30,6 +30,7 @@ export const SignedExecutionProgramEnvelopeSchema = z.object({
     signature: z.string().regex(/^[a-f0-9]{64}$/i),
     meta: z.object({
         stale: z.boolean().optional(),
+        programSchemaVersionOrigin: z.number().int().nonnegative().optional(),
     }).strict().optional(),
 }).strict();
 function stableNormalize(value) {

package/dist/recovery-chain.js

@@ -9,7 +9,7 @@
  * 5. LLM Healer (last resort)
  */
 import { resolveSelector } from './selector-resolver.js';
-import { evaluatePostcondition } from './postcondition.js';
+import { evaluatePostcondition, evaluatePostconditionWithProgress } from './postcondition.js';
 import { LLMHealer } from './llm-healer.js';
 import { serializeAKTree } from './ak-tree.js';
 import { executeOpcodeCoreAction } from './opcode-actions.js';
@@ -35,7 +35,7 @@ export class RecoveryChainImpl {
         const retryBudget = Math.max(0, Math.min(recovery.retries, options.maxDeterministicRetries ?? recovery.retries));
         if (retryBudget > 0) {
             logger.debug(`[recovery ${opcodeIndex}] strategy 1 (retry x${retryBudget})`);
-            const result = await retryOpcode(failedOpcode, adapter, retryBudget, options.remainingTimeMs, options.currentVariant, this.credentials, options.suppressPageReloads);
+            const result = await retryOpcode(failedOpcode, adapter, retryBudget, options.remainingTimeMs, options.currentVariant, this.credentials, options.suppressPageReloads, options.globalDeadlineMs, options.getProgress);
             logger.debug(`[recovery ${opcodeIndex}] strategy 1 → recovered=${result.recovered}, reason=${result.reason}`);
             if (result.recovered)
                 return result;
@@ -86,7 +86,7 @@ export class RecoveryChainImpl {
     }
 }
 // ── Strategy 1: Deterministic retry ─────────────────────────────────
-async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, currentVariant, credentials, suppressPageReloads = false) {
+async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, currentVariant, credentials, suppressPageReloads = false, globalDeadlineMs, getProgress) {
     const deadlineMs = typeof remainingTimeMs === 'number'
         ? Date.now() + remainingTimeMs
         : Number.POSITIVE_INFINITY;
@@ -97,7 +97,11 @@ async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, current
         await sleep(500 * (i + 1)); // backoff
         try {
             await executeRawAction(opcode, adapter, currentVariant, credentials, suppressPageReloads);
-            const postcondition = await evaluatePostcondition(adapter, clampPostconditionWait(opcode.postcondition, deadlineMs));
+            // AUT-240 (Phase 5): the re-check extends-on-progress up to the global
+            // deadline instead of replaying a fixed clamped budget. Without the global
+            // deadline (legacy callers), `getProgress` is dropped so it degrades to the
+            // compiled postcondition budget.
+            const postcondition = await evaluatePostconditionWithProgress(adapter, opcode.postcondition, Date.now(), globalDeadlineMs ?? deadlineMs, globalDeadlineMs !== undefined ? getProgress : undefined);
             if (postcondition.passed) {
                 return { recovered: true, strategy: 'retry', reason: `retry ${i + 1}/${maxRetries} succeeded` };
             }
@@ -363,11 +367,4 @@ async function resolveSelectorCoordinates(adapter, selector) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
-function clampPostconditionWait(spec, deadlineMs) {
-    const remainingTimeMs = Math.max(1, deadlineMs - Date.now());
-    return {
-        ...spec,
-        waitMs: Math.max(1, Math.min(spec.waitMs ?? remainingTimeMs, remainingTimeMs)),
-    };
-}
 //# sourceMappingURL=recovery-chain.js.map

package/dist/scenario-cookie.d.ts

@@ -0,0 +1,36 @@
+import type { PreconditionSpec } from './execution-types.js';
+/**
+ * AUT-239 — signing side of the AutoKap Scenario cookie.
+ *
+ * The runner (this CLI) signs; the client app's `@autokap/scenario` package
+ * verifies. At runtime these live in two separate processes/deployments, so the
+ * only thing they share is the WIRE FORMAT, not a module. We therefore keep a
+ * tiny local signer here rather than taking a runtime dependency on the
+ * published `@autokap/scenario` package. `scenario-cookie.test.ts` locks the
+ * format against the real resolver so the two can never drift.
+ *
+ * Format: `<id>.<base64url(HMAC-SHA256(secret, id))>`.
+ */
+export declare const SCENARIO_COOKIE_NAME = "__ak_scenario";
+export declare function signScenarioCookie(id: string, secret: string): string;
+/** A cookie ready for Playwright's `context.addCookies`. */
+export interface PreconditionCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure: boolean;
+}
+/**
+ * Build the cookie set injected before navigation: the preset's seed cookies
+ * plus, when configured, the signed scenario switch.
+ *
+ * `secure` is derived from the target protocol — a Secure cookie is never sent
+ * over http://localhost, so the runner must NOT default it to true (that would
+ * silently drop seed/scenario cookies in local captures and fall back to real
+ * data). Returns a `warning` when a scenario is requested but unsignable.
+ */
+export declare function buildPreconditionCookies(preconditions: Pick<PreconditionSpec, 'cookies' | 'scenario'>, baseUrl: string, secret: string | undefined): {
+    cookies: PreconditionCookie[];
+    warning?: string;
+};

package/dist/scenario-cookie.js

@@ -0,0 +1,62 @@
+import { createHmac } from 'node:crypto';
+/**
+ * AUT-239 — signing side of the AutoKap Scenario cookie.
+ *
+ * The runner (this CLI) signs; the client app's `@autokap/scenario` package
+ * verifies. At runtime these live in two separate processes/deployments, so the
+ * only thing they share is the WIRE FORMAT, not a module. We therefore keep a
+ * tiny local signer here rather than taking a runtime dependency on the
+ * published `@autokap/scenario` package. `scenario-cookie.test.ts` locks the
+ * format against the real resolver so the two can never drift.
+ *
+ * Format: `<id>.<base64url(HMAC-SHA256(secret, id))>`.
+ */
+export const SCENARIO_COOKIE_NAME = '__ak_scenario';
+export function signScenarioCookie(id, secret) {
+    const sig = createHmac('sha256', secret).update(id).digest('base64url');
+    return `${id}.${sig}`;
+}
+/**
+ * Build the cookie set injected before navigation: the preset's seed cookies
+ * plus, when configured, the signed scenario switch.
+ *
+ * `secure` is derived from the target protocol — a Secure cookie is never sent
+ * over http://localhost, so the runner must NOT default it to true (that would
+ * silently drop seed/scenario cookies in local captures and fall back to real
+ * data). Returns a `warning` when a scenario is requested but unsignable.
+ */
+export function buildPreconditionCookies(preconditions, baseUrl, secret) {
+    let secure = true;
+    let hostname = '';
+    try {
+        const url = new URL(baseUrl);
+        secure = url.protocol === 'https:';
+        hostname = url.hostname;
+    }
+    catch {
+        /* baseUrl is validated upstream; fall back to Secure on parse failure */
+    }
+    const cookies = (preconditions.cookies ?? []).map((c) => ({
+        ...c,
+        secure,
+    }));
+    let warning;
+    if (preconditions.scenario) {
+        if (!secret) {
+            warning =
+                `preconditions.scenario="${preconditions.scenario}" set but AUTOKAP_SCENARIO_SECRET ` +
+                    `is missing — scenario cookie NOT injected; capture will use real data`;
+        }
+        else {
+            cookies.push({
+                name: SCENARIO_COOKIE_NAME,
+                value: signScenarioCookie(preconditions.scenario, secret),
+                domain: hostname,
+                path: '/',
+                secure,
+            });
+        }
+    }
+    return { cookies, warning };
+}
+//# sourceMappingURL=scenario-cookie.js.map

package/dist/security.d.ts

@@ -16,6 +16,27 @@ export interface SecurityDecision {
     reason?: string;
     target?: InteractiveElement | null;
 }
+/**
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
+ * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
+ * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
+ * NOT same-site), sub-domain family match for real registrable domains.
+ *
+ * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
+ * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
+ * Sentry, …) no longer reads as "the page is making progress" and the stuck
+ * watchdog can still cut a wait whose condition will never be met.
+ *
+ * Fail-OPEN by design: a false "first-party" only makes the watchdog slightly
+ * more patient (still bounded by the per-media cap), whereas a false "foreign"
+ * could suppress a real progress signal and cut a legitimately-slow page early.
+ * So when in doubt we count it as first-party:
+ *  - unparseable / non-http(s) `scopeUrl` (e.g. `about:blank` before the first
+ *    navigation commits) ⇒ true (don't filter);
+ *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
+ *    resource).
+ */
+export declare function isFirstPartyUrl(scopeUrl: string | null | undefined, candidateUrl: string): boolean;
 export declare function evaluateResolvedActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext, target: InteractiveElement | null): SecurityDecision;
 export declare function evaluateActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext): SecurityDecision;
 export declare function describeSecurityTarget(target: InteractiveElement | null | undefined): string;

package/dist/security.js

@@ -109,6 +109,16 @@ function isSharedHostingHostname(hostname) {
 function normalizeScopeHostname(hostname) {
     return hostname.startsWith('www.') ? hostname.slice(4) : hostname;
 }
+function scopeFromParsedUrl(parsed) {
+    const hostname = parsed.hostname.toLowerCase();
+    const exactHost = isLocalHostname(hostname) || isIpv4Hostname(hostname) || isIpv6Hostname(hostname) || isSharedHostingHostname(hostname);
+    const scopeHostname = exactHost ? hostname : normalizeScopeHostname(hostname);
+    return {
+        hostname: scopeHostname,
+        port: effectivePort(parsed),
+        exactHost,
+    };
+}
 function buildNavigationScopes(context) {
     const sources = [
         context.rootUrl,
@@ -119,18 +129,46 @@ function buildNavigationScopes(context) {
         const parsed = parseHttpUrl(value);
         if (!parsed)
             continue;
-        const hostname = parsed.hostname.toLowerCase();
-        const exactHost = isLocalHostname(hostname) || isIpv4Hostname(hostname) || isIpv6Hostname(hostname) || isSharedHostingHostname(hostname);
-        const scopeHostname = exactHost ? hostname : normalizeScopeHostname(hostname);
-        const scope = {
-            hostname: scopeHostname,
-            port: effectivePort(parsed),
-            exactHost,
-        };
+        const scope = scopeFromParsedUrl(parsed);
         dedup.set(`${scope.hostname}:${scope.port}:${scope.exactHost ? 'exact' : 'family'}`, scope);
     }
     return Array.from(dedup.values());
 }
+/**
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
+ * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
+ * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
+ * NOT same-site), sub-domain family match for real registrable domains.
+ *
+ * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
+ * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
+ * Sentry, …) no longer reads as "the page is making progress" and the stuck
+ * watchdog can still cut a wait whose condition will never be met.
+ *
+ * Fail-OPEN by design: a false "first-party" only makes the watchdog slightly
+ * more patient (still bounded by the per-media cap), whereas a false "foreign"
+ * could suppress a real progress signal and cut a legitimately-slow page early.
+ * So when in doubt we count it as first-party:
+ *  - unparseable / non-http(s) `scopeUrl` (e.g. `about:blank` before the first
+ *    navigation commits) ⇒ true (don't filter);
+ *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
+ *    resource).
+ */
+export function isFirstPartyUrl(scopeUrl, candidateUrl) {
+    const scopeParsed = parseHttpUrl(scopeUrl ?? undefined);
+    if (!scopeParsed)
+        return true;
+    let candidate;
+    try {
+        candidate = new URL(candidateUrl);
+    }
+    catch {
+        return true;
+    }
+    if (candidate.protocol !== 'http:' && candidate.protocol !== 'https:')
+        return true;
+    return isWithinProjectScope(candidate, [scopeFromParsedUrl(scopeParsed)]);
+}
 function isWithinProjectScope(candidate, scopes) {
     const hostname = candidate.hostname.toLowerCase();
     const port = effectivePort(candidate);

package/dist/server-credit-usage.d.ts

@@ -1,5 +1,5 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
-export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'cloud_recapture' | 'ai_chat' | 'studio_creation' | 'studio_iteration' | 'error_analysis' | 'obsolescence_analysis';
+export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'cloud_recapture' | 'ai_chat' | 'studio_creation' | 'studio_iteration' | 'error_analysis' | 'obsolescence_analysis' | 'pr_generation';
 export declare function recordCreditUsage(supabase: SupabaseClient, params: {
     userId: string;
     projectId: string | null;

package/dist/version.d.ts

@@ -1 +1,2 @@
+/** npm package version of the CLI, transmitted as the `x-autokap-cli-version` header. */
 export declare const APP_VERSION: string;

package/dist/version.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
+/** npm package version of the CLI, transmitted as the `x-autokap-cli-version` header. */
 export const APP_VERSION = pkg.version;
 //# sourceMappingURL=version.js.map

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

@@ -57,6 +57,8 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
     program: z.ZodObject<{
         presetId: z.ZodString;
         programVersion: z.ZodNumber;
+        programSchemaVersion: z.ZodOptional<z.ZodNumber>;
+        engineVersion: z.ZodOptional<z.ZodNumber>;
         mediaMode: z.ZodEnum<{
             video: "video";
             clip: "clip";
@@ -167,6 +169,7 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
                 domain: z.ZodString;
                 path: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
+            scenario: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             url: z.ZodString;

package/dist/video-narration-schema.js

@@ -83,6 +83,9 @@ export const VideoNarrationOverlaySchema = z.object({
  *      match a `program.steps[*].stepId`.
  */
 export const VideoIngestPayloadSchema = z.object({
+    // Strict by design: this is a legacy compatibility-test ingest schema with no
+    // live consumer (test-only + barrel re-export), so it validates the raw form
+    // without migrate-on-read. Live program validation goes through parseProgram.
     program: ExecutionProgramSchema,
     narration: VideoNarrationOverlaySchema.optional(),
 }).strict().superRefine((value, ctx) => {

package/dist/wait-contract.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Capture Agent — Wait Contract (AUT-240)
+ *
+ * Single source of truth for the engine's adaptive waiting behaviour. Zero user
+ * configuration: every budget/deadline below is an internal constant. Versioned
+ * (`WAIT_CONTRACT_VERSION`) so runs can be debugged and future migrations
+ * reasoned about; the global engine-versioning infrastructure is a separate
+ * effort.
+ *
+ * The model has three layers (see the AUT-240 issue):
+ *  - Layer A — actionability & semantic postconditions.
+ *  - Layer B — `waitForVisuallyStable` (screenshot stabilization).
+ *  - Layer C — dynamic budgets: a wait extends while the page is making progress
+ *    (network / DOM) and is cut once it is genuinely stuck, up to a hard
+ *    per-media global deadline. This is the real cure for the engine's #1 pain —
+ *    a slow-but-progressing page no longer trips a fixed timeout.
+ */
+import type { MediaMode, ProgressSnapshot } from './execution-types.js';
+/** Bump when the wait semantics change in a way worth tracing on a run. */
+export declare const WAIT_CONTRACT_VERSION = 1;
+/**
+ * Hard ceiling on adaptive waiting, per media mode. Applied as a FLOOR via
+ * `max()` with the compiled opcode timeout (see `resolveGlobalWaitDeadlineMs`)
+ * so it never shortens an intentionally-long opcode (`SLEEP`, `END_CLIP`).
+ */
+export declare const GLOBAL_WAIT_CAP_MS: Record<MediaMode, number>;
+/** No observed progress for this long ⇒ the wait is "stuck" and gets cut. */
+export declare const STUCK_WINDOW_MS = 4000;
+/** Watchdog poll cadence while a wait is in flight. */
+export declare const PROGRESS_POLL_INTERVAL_MS = 250;
+/**
+ * A timed-out wait cannot be cancelled through the adapter API. Before recovery
+ * or the next opcode starts, give the orphaned operation this long to settle so
+ * it does not mutate the page concurrently. Mirrors the runner's drain.
+ */
+export declare const ORPHAN_DRAIN_MS = 2000;
+/** DOM-quiet settle window for visual stabilization (Layer B). */
+export declare const DOM_QUIET_WINDOW_MS = 250;
+/** Bounded pixel-convergence fallback (Layer B). */
+export declare const PIXEL_FALLBACK_MAX_PASSES = 3;
+export declare const PIXEL_FALLBACK_DIFF_THRESHOLD = 0.01;
+/**
+ * Resolve the per-opcode global wait deadline (absolute ms timestamp).
+ * `compiledTimeoutMs` is the opcode's compiled `timeoutMs` — treated as a FLOOR,
+ * never a ceiling, so the deadline can only ever be extended past the compiled
+ * value, never shortened below it.
+ */
+export declare function resolveGlobalWaitDeadlineMs(startedAtMs: number, compiledTimeoutMs: number, mediaMode: MediaMode): number;
+/**
+ * Did the page make observable progress between two snapshots? Any of: a
+ * navigation in flight, new network events, in-flight count change, network
+ * activity advancing, readyState change, or DOM node-count change. A null
+ * current reading is treated conservatively as "no progress"; the first real
+ * reading (null `prev`) counts as progress to seed the watchdog window.
+ *
+ * The network fields are first-party-scoped at the source (see
+ * `getProgressSnapshot` / `isFirstPartyUrl`): background third-party telemetry
+ * (analytics beacons, ad pixels, polling to other origins) is excluded, so it
+ * cannot keep this `true` forever and starve the stuck-cut.
+ */
+export declare function hasProgress(prev: ProgressSnapshot | null | undefined, cur: ProgressSnapshot | null | undefined): boolean;
+export type ProgressBudgetCut = 'stuck' | 'deadline';
+export interface ProgressBudgetOptions {
+    /** `Date.now()` when the surrounding opcode started (for elapsed/min-budget). */
+    startedAtMs: number;
+    /** Absolute hard deadline — the wait never runs past this. */
+    globalDeadlineMs: number;
+    /**
+     * Minimum patience (the compiled `timeoutMs` floor) before the stuck-cut may
+     * fire. A slow page that produces no early signal still gets at least this
+     * long before being judged stuck.
+     */
+    minBudgetMs: number;
+    /** No-progress window before cutting "stuck". Defaults to `STUCK_WINDOW_MS`. */
+    stuckWindowMs?: number;
+    /** Watchdog cadence. Defaults to `PROGRESS_POLL_INTERVAL_MS`. */
+    pollIntervalMs?: number;
+    /**
+     * Progress probe. When omitted, the stuck-cut is disabled and the operation
+     * simply runs with its compiled floor budget (legacy fixed-timeout behaviour)
+     * — graceful degradation for adapters with no progress signal.
+     */
+    getProgress?: () => Promise<ProgressSnapshot | null>;
+}
+export interface ProgressBudgetResult<T> {
+    /** Present when the wrapped operation resolved before any cut. */
+    result?: T;
+    /** Present when the watchdog cut the wait early. */
+    cut?: ProgressBudgetCut;
+    /** Total time spent (ms). */
+    waitedMs: number;
+}
+/**
+ * Run an adaptive wait that extends while the page is making progress and is cut
+ * once it is genuinely stuck or the global deadline is reached.
+ *
+ * `run(budgetMs)` is given a generous budget (up to the global deadline) and is
+ * expected to resolve as soon as its condition is met (or to time out at the
+ * budget). A concurrent watchdog races it: while `run` is still pending, the
+ * watchdog cuts the wait if no progress is observed for `stuckWindowMs` (after
+ * `minBudgetMs` has elapsed) or once the global deadline passes. If `run`
+ * resolves first, its result is returned and the watchdog is moot.
+ */
+export declare function runWithProgressBudget<T>(run: (budgetMs: number) => Promise<T>, options: ProgressBudgetOptions): Promise<ProgressBudgetResult<T>>;