@dev-blinq/bvt-playwright-js 1.0.0-dev.2 → 1.0.0-dev.4

package/index.d.mts

@@ -13,6 +13,85 @@ declare const apiResponseSnapshotSchema: z.ZodObject<{
 	bodyJson: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 type ApiResponseSnapshot = z.infer<typeof apiResponseSnapshotSchema>;
+declare const apiRequestSchema: z.ZodObject<{
+	method: z.ZodEnum<{
+		GET: "GET";
+		POST: "POST";
+		PUT: "PUT";
+		PATCH: "PATCH";
+		DELETE: "DELETE";
+	}>;
+	url: z.ZodString;
+	headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+	body: z.ZodOptional<z.ZodString>;
+	saveAs: z.ZodOptional<z.ZodString>;
+	capturedResponse: z.ZodOptional<z.ZodObject<{
+		status: z.ZodNumber;
+		statusText: z.ZodString;
+		timeMs: z.ZodNumber;
+		sizeBytes: z.ZodNumber;
+		headers: z.ZodRecord<z.ZodString, z.ZodString>;
+		bodyText: z.ZodString;
+		bodyJson: z.ZodOptional<z.ZodUnknown>;
+	}, z.core.$strict>>;
+	options: z.ZodOptional<z.ZodObject<{
+		timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+	}, z.core.$strict>>;
+}, z.core.$strict>;
+type ApiRequest = z.infer<typeof apiRequestSchema>;
+declare const apiResponseAssertionCommandData: z.ZodDiscriminatedUnion<[
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		target: z.ZodLiteral<"status">;
+		expected: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		target: z.ZodLiteral<"responseTime">;
+		expected: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		expected: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+		target: z.ZodLiteral<"header">;
+		path: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		expected: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+		target: z.ZodLiteral<"bodyField">;
+		path: z.ZodString;
+	}, z.core.$strict>
+], "target">;
+type ApiResponseAssertionCommandData = z.infer<typeof apiResponseAssertionCommandData>;
 declare const elementActionSchema: z.ZodDiscriminatedUnion<[
 	z.ZodObject<{
 		type: z.ZodLiteral<"click">;
@@ -1797,9 +1876,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -2557,9 +2636,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -3201,9 +3280,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -3290,6 +3369,23 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 			}, z.core.$strict>>;
 		}, z.core.$strict>>>;
 	}, z.core.$strict>,
+	z.ZodObject<{
+		_id: z.ZodString;
+		type: z.ZodLiteral<"custom.code">;
+		runtime: z.ZodDefault<z.ZodLiteral<"secure-exec-v1">>;
+		language: z.ZodDefault<z.ZodLiteral<"javascript">>;
+		code: z.ZodString;
+		config: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+			continueOnFailure: z.ZodDefault<z.ZodBoolean>;
+			preCommandDelay: z.ZodDefault<z.ZodNumber>;
+			postCommandDelay: z.ZodDefault<z.ZodNumber>;
+			sideEffectPolicy: z.ZodOptional<z.ZodObject<{
+				isDestructive: z.ZodDefault<z.ZodBoolean>;
+				isIdempotent: z.ZodDefault<z.ZodBoolean>;
+				requiresOptIn: z.ZodDefault<z.ZodBoolean>;
+			}, z.core.$strict>>;
+		}, z.core.$strict>>>;
+	}, z.core.$strict>,
 	z.ZodObject<{
 		_id: z.ZodString;
 		type: z.ZodLiteral<"api.action">;
@@ -4779,9 +4875,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -5539,9 +5635,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -6183,9 +6279,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -6272,6 +6368,23 @@ declare const StepDefinitionSchema: z.ZodObject<{
 				}, z.core.$strict>>;
 			}, z.core.$strict>>>;
 		}, z.core.$strict>,
+		z.ZodObject<{
+			_id: z.ZodString;
+			type: z.ZodLiteral<"custom.code">;
+			runtime: z.ZodDefault<z.ZodLiteral<"secure-exec-v1">>;
+			language: z.ZodDefault<z.ZodLiteral<"javascript">>;
+			code: z.ZodString;
+			config: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+				continueOnFailure: z.ZodDefault<z.ZodBoolean>;
+				preCommandDelay: z.ZodDefault<z.ZodNumber>;
+				postCommandDelay: z.ZodDefault<z.ZodNumber>;
+				sideEffectPolicy: z.ZodOptional<z.ZodObject<{
+					isDestructive: z.ZodDefault<z.ZodBoolean>;
+					isIdempotent: z.ZodDefault<z.ZodBoolean>;
+					requiresOptIn: z.ZodDefault<z.ZodBoolean>;
+				}, z.core.$strict>>;
+			}, z.core.$strict>>>;
+		}, z.core.$strict>,
 		z.ZodObject<{
 			_id: z.ZodString;
 			type: z.ZodLiteral<"api.action">;
@@ -6765,9 +6878,9 @@ declare const ReplayLocatorCandidateSchema: z.ZodObject<{
 	], "type">;
 	score: z.ZodNumber;
 	source: z.ZodEnum<{
+		role: "role";
 		xpath: "xpath";
 		testId: "testId";
-		role: "role";
 		accessibleName: "accessibleName";
 		visibleText: "visibleText";
 		stableAttribute: "stableAttribute";
@@ -7047,9 +7160,9 @@ declare const StepReplayTelemetrySchema: z.ZodObject<{
 		], "type">;
 		score: z.ZodNumber;
 		source: z.ZodEnum<{
+			role: "role";
 			xpath: "xpath";
 			testId: "testId";
-			role: "role";
 			accessibleName: "accessibleName";
 			visibleText: "visibleText";
 			stableAttribute: "stableAttribute";
@@ -7251,8 +7364,8 @@ declare const RecoveryDecisionSchema: z.ZodDiscriminatedUnion<[
 			}, z.core.$strip>
 		], "type">;
 		repairContext: z.ZodEnum<{
-			"local-run": "local-run";
 			"recorder-replay": "recorder-replay";
+			"local-run": "local-run";
 			"execution-planner": "execution-planner";
 		}>;
 		rcaLabel: z.ZodOptional<z.ZodString>;
@@ -7308,10 +7421,10 @@ type ExecutionStartedEventData = {
 };
 declare const ScopeTypeSchema: z.ZodEnum<{
 	environment: "environment";
+	runtime: "runtime";
 	global: "global";
 	feature: "feature";
 	scenario: "scenario";
-	runtime: "runtime";
 }>;
 type ScopeType = z.infer<typeof ScopeTypeSchema>;
 declare const TestDataTypeSchema: z.ZodEnum<{
@@ -7343,10 +7456,10 @@ declare const TestDataEntrySchema: z.ZodObject<{
 	scope: z.ZodObject<{
 		type: z.ZodEnum<{
 			environment: "environment";
+			runtime: "runtime";
 			global: "global";
 			feature: "feature";
 			scenario: "scenario";
-			runtime: "runtime";
 		}>;
 		environmentId: z.ZodOptional<z.ZodString>;
 		featureId: z.ZodOptional<z.ZodString>;
@@ -7376,8 +7489,8 @@ declare const BrowserObserverStateKSchema: z.ZodUnion<readonly [
 		input: "input";
 		text: "text";
 		context: "context";
-		hover: "hover";
 		ai: "ai";
+		hover: "hover";
 		none: "none";
 		snapshot: "snapshot";
 		element: "element";
@@ -7732,9 +7845,9 @@ declare const PickedElementSchema: z.ZodObject<{
 		], "type">;
 		score: z.ZodNumber;
 		source: z.ZodEnum<{
+			role: "role";
 			xpath: "xpath";
 			testId: "testId";
-			role: "role";
 			accessibleName: "accessibleName";
 			visibleText: "visibleText";
 			stableAttribute: "stableAttribute";
@@ -7773,6 +7886,69 @@ declare const PickedElementSchema: z.ZodObject<{
 	stale: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 type PickedElement = z.infer<typeof PickedElementSchema>;
+declare const ExecutionResultSchema: z.ZodObject<{
+	success: z.ZodBoolean;
+	result: z.ZodOptional<z.ZodUnknown>;
+	error: z.ZodOptional<z.ZodString>;
+	userMessage: z.ZodOptional<z.ZodString>;
+	logs: z.ZodArray<z.ZodString>;
+	checkpoints: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+		label: z.ZodString;
+		timestampMs: z.ZodNumber;
+		data: z.ZodOptional<z.ZodUnknown>;
+	}, z.core.$strict>>>>;
+	duration: z.ZodNumber;
+	screenshotAfter: z.ZodOptional<z.ZodString>;
+	mutationSignals: z.ZodOptional<z.ZodObject<{
+		httpMutations: z.ZodArray<z.ZodObject<{
+			method: z.ZodEnum<{
+				POST: "POST";
+				PUT: "PUT";
+				PATCH: "PATCH";
+				DELETE: "DELETE";
+			}>;
+			url: z.ZodString;
+			status: z.ZodNumber;
+			timestampMs: z.ZodNumber;
+		}, z.core.$strict>>;
+		cookieChanges: z.ZodArray<z.ZodObject<{
+			name: z.ZodString;
+			action: z.ZodEnum<{
+				added: "added";
+				modified: "modified";
+				deleted: "deleted";
+			}>;
+			suspectedAuth: z.ZodBoolean;
+		}, z.core.$strict>>;
+		storageMutations: z.ZodObject<{
+			localStorage: z.ZodObject<{
+				added: z.ZodArray<z.ZodString>;
+				modified: z.ZodArray<z.ZodString>;
+				deleted: z.ZodArray<z.ZodString>;
+			}, z.core.$strict>;
+			sessionStorage: z.ZodObject<{
+				added: z.ZodArray<z.ZodString>;
+				modified: z.ZodArray<z.ZodString>;
+				deleted: z.ZodArray<z.ZodString>;
+			}, z.core.$strict>;
+		}, z.core.$strict>;
+		navigationEvents: z.ZodArray<z.ZodObject<{
+			url: z.ZodString;
+			timestampMs: z.ZodNumber;
+		}, z.core.$strict>>;
+		dialogEvents: z.ZodArray<z.ZodObject<{
+			type: z.ZodEnum<{
+				alert: "alert";
+				confirm: "confirm";
+				prompt: "prompt";
+			}>;
+			message: z.ZodString;
+		}, z.core.$strict>>;
+		downloadCount: z.ZodNumber;
+		pageErrorCount: z.ZodNumber;
+	}, z.core.$strict>>;
+}, z.core.$strict>;
+type ExecutionResult = z.infer<typeof ExecutionResultSchema>;
 declare const RecoveryArtifactSchema: z.ZodObject<{
 	rootCauseAnalysis: z.ZodString;
 	aiLog: z.ZodString;
@@ -7844,6 +8020,207 @@ declare class DownloadStore {
 	 */
 	cancelAll(): void;
 }
+type CustomCodeAllowedHost = {
+	readonly protocol: "http:" | "https:" | "pg:";
+	readonly hostname: string;
+};
+type CustomCodePolicy = {
+	readonly maxDurationMs: number;
+	readonly memoryMb: number;
+	readonly outputBytes: number;
+	readonly payloadBytes: number;
+	readonly packages: readonly string[];
+	readonly env: {
+		readonly allowedKeys: readonly string[];
+	};
+	readonly network: {
+		readonly allowedHosts: readonly CustomCodeAllowedHost[];
+		readonly blockPrivateIpRanges: boolean;
+		readonly requirePgTls: boolean;
+	};
+	readonly filesystem: {
+		readonly root: string;
+		readonly maxBytesPerFile: number;
+		readonly maxFiles: number;
+	};
+	readonly process: {
+		readonly allowedCommands: readonly string[];
+		readonly maxOutputBytes: number;
+	};
+	readonly browser: {
+		readonly pageMethods: readonly string[];
+		readonly locatorMethods: readonly string[];
+		readonly expectMethods: readonly string[];
+	};
+};
+type CustomCodeDriverRunInput = {
+	readonly code: string;
+	readonly filePath: string;
+	readonly policy: CustomCodePolicy;
+	readonly bindings: Readonly<Record<string, unknown>>;
+	readonly onStdout: (message: string) => void;
+	readonly onStderr: (message: string) => void;
+};
+type CustomCodeDriverRunResult = {
+	readonly exitCode: number;
+	readonly errorMessage?: string;
+};
+interface CustomCodeDriver {
+	run(input: CustomCodeDriverRunInput): Promise<CustomCodeDriverRunResult>;
+}
+type LogMethod = (...args: any[]) => void;
+type LogContext = any;
+type MetricTags = Record<string, string>;
+type EventProperties = Record<string, unknown>;
+type ObservabilityLoggerLike = {
+	info: LogMethod;
+	warn: LogMethod;
+	error: LogMethod;
+	withContext?: (context: LogContext) => ObservabilityLoggerLike;
+	log?: LogMethod;
+};
+type ObservabilityMetricsLike = {
+	count: (name: string, value?: number, tags?: MetricTags, context?: LogContext) => void;
+	gauge: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
+	histogram: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
+	latency: (name: string, startMs: number, tags?: MetricTags, context?: LogContext) => void;
+	withContext?: (context: LogContext) => ObservabilityMetricsLike;
+};
+type ObservabilityEventsLike = {
+	track: (name: string, properties?: EventProperties, context?: any) => void;
+	withContext?: (context: any) => ObservabilityEventsLike;
+};
+type ConsoleLikeLogger = Partial<Record<"log" | "info" | "warn" | "error", LogMethod>>;
+interface AgentLogger {
+	log: LogMethod;
+	info: LogMethod;
+	warn: LogMethod;
+	error: LogMethod;
+	withContext: (context: LogContext) => AgentLogger;
+}
+interface AgentMetrics {
+	count: (name: string, value?: number, tags?: MetricTags, context?: LogContext) => void;
+	gauge: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
+	histogram: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
+	latency: (name: string, startMs: number, tags?: MetricTags, context?: LogContext) => void;
+	withContext: (context: LogContext) => AgentMetrics;
+}
+interface AgentEvents {
+	track: (name: string, properties?: EventProperties, context?: any) => void;
+	withContext: (context: any) => AgentEvents;
+}
+interface AgentObservability {
+	logger: AgentLogger;
+	metrics: AgentMetrics;
+	events: AgentEvents;
+	withContext: (context: LogContext) => AgentObservability;
+}
+type AgentLoggerInput = AgentLogger | ObservabilityLoggerLike | ConsoleLikeLogger | undefined;
+type AgentObservabilityInput = AgentObservability | {
+	logger?: AgentLoggerInput;
+	metrics?: AgentMetrics | ObservabilityMetricsLike;
+	events?: AgentEvents | ObservabilityEventsLike;
+} | AgentLoggerInput;
+interface TestDataApiOptions {
+	/**
+	 * Called after every successful write. Used by WorkerRuntime to fan out
+	 * snapshots over the sessionTestData subscription.
+	 */
+	onChange?: () => void;
+	/**
+	 * Optional logger. When supplied, every setRuntime/getRuntime call emits a
+	 * structured info log so the operator can trace test-data writes without
+	 * grepping for `provider.upsert`.
+	 */
+	logger?: AgentLoggerInput;
+}
+declare class TestDataApi {
+	private readonly provider;
+	private readonly context;
+	private readonly options;
+	private readonly logger?;
+	constructor(provider: ITestDataProvider, context: ResolutionContext, options?: TestDataApiOptions);
+	/**
+	 * Save a value to runtime test data.
+	 *
+	 * Runtime values:
+	 *  - resolvable as `{{key}}` in subsequent steps within the same execution
+	 *  - scoped to the current scenario; cleared when the scenario or environment changes
+	 *  - last write wins for the same key inside one run (idempotent)
+	 *
+	 * @example  in AI-chat-generated custom code
+	 *   const orderId = await page.locator('[data-order-id]').getAttribute('data-order-id');
+	 *   await context.testData.setRuntime('orderId', orderId ?? '');
+	 *
+	 * @example  with explicit dataType
+	 *   await context.testData.setRuntime('authToken', token, { dataType: 'secret' });
+	 */
+	setRuntime(key: string, value: string, opts?: {
+		dataType?: TestDataType;
+	}): Promise<void>;
+	/**
+	 * Shorthand for {@link setRuntime}. Saves a value to the current session's
+	 * runtime scope, resolvable as `{{key}}` in subsequent steps.
+	 */
+	set(key: string, value: string, opts?: {
+		dataType?: TestDataType;
+	}): Promise<void>;
+	/**
+	 * Shorthand for {@link getRuntime}. Reads a value from the current session's
+	 * runtime scope. Returns `null` if no entry exists for `key`.
+	 */
+	get(key: string): Promise<string | null>;
+	/**
+	 * Read a runtime value previously saved via setRuntime or an extract step.
+	 *
+	 * Returns `null` if no entry exists for `key` in the current runtime scope.
+	 * Does NOT walk the scope chain. For full resolution including environment +
+	 * global, use the `{{key}}` token syntax with the resolver.
+	 */
+	getRuntime(key: string): Promise<string | null>;
+	/**
+	 * Read a value through the full runtime → scenario → feature → environment → global
+	 * scope chain. This is used by built-in utility commands that need the raw value
+	 * rather than `{{key}}` token interpolation.
+	 */
+	getScoped(key: string): Promise<string | null>;
+}
+type CustomCodeLogEntry = {
+	readonly level: "info" | "warn" | "error";
+	readonly message: string;
+};
+type CustomCodeCheckpoint = {
+	readonly label: string;
+	readonly timestampMs: number;
+	readonly data?: unknown;
+};
+type CustomCodeExecutionResult = Omit<ExecutionResult, "logs" | "checkpoints" | "duration"> & {
+	readonly logs?: readonly CustomCodeLogEntry[];
+	readonly checkpoints?: readonly CustomCodeCheckpoint[];
+	readonly errorKind?: string;
+};
+type ExecuteCustomCodeInput = {
+	readonly commandId: string;
+	readonly code: string;
+	readonly variables: Readonly<Record<string, string>>;
+	readonly page: Page;
+	readonly testData?: Pick<TestDataApi, "set" | "get" | "setRuntime" | "getRuntime" | "getScoped">;
+	readonly fetchImpl: typeof fetch;
+	readonly checkpoint: (label: string, data?: unknown) => Promise<void>;
+	readonly signal?: AbortSignal;
+};
+type CustomCodeRuntimeOptions = {
+	readonly driver?: CustomCodeDriver;
+	readonly policy?: CustomCodePolicy;
+	readonly logger?: AgentLoggerInput;
+};
+declare class CustomCodeRuntime {
+	private readonly driver;
+	private readonly policy;
+	private readonly logger?;
+	constructor(options?: CustomCodeRuntimeOptions);
+	execute(input: ExecuteCustomCodeInput): Promise<CustomCodeExecutionResult>;
+}
 type AriaRole = "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "mark" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem";
 type AriaProps = {
 	checked?: boolean | "mixed";
@@ -8659,111 +9036,6 @@ type TesterApiClient = {
 		};
 	};
 };
-type LogMethod = (...args: any[]) => void;
-type LogContext = any;
-type MetricTags = Record<string, string>;
-type EventProperties = Record<string, unknown>;
-type ObservabilityLoggerLike = {
-	info: LogMethod;
-	warn: LogMethod;
-	error: LogMethod;
-	withContext?: (context: LogContext) => ObservabilityLoggerLike;
-	log?: LogMethod;
-};
-type ObservabilityMetricsLike = {
-	count: (name: string, value?: number, tags?: MetricTags, context?: LogContext) => void;
-	gauge: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
-	histogram: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
-	latency: (name: string, startMs: number, tags?: MetricTags, context?: LogContext) => void;
-	withContext?: (context: LogContext) => ObservabilityMetricsLike;
-};
-type ObservabilityEventsLike = {
-	track: (name: string, properties?: EventProperties, context?: any) => void;
-	withContext?: (context: any) => ObservabilityEventsLike;
-};
-type ConsoleLikeLogger = Partial<Record<"log" | "info" | "warn" | "error", LogMethod>>;
-interface AgentLogger {
-	log: LogMethod;
-	info: LogMethod;
-	warn: LogMethod;
-	error: LogMethod;
-	withContext: (context: LogContext) => AgentLogger;
-}
-interface AgentMetrics {
-	count: (name: string, value?: number, tags?: MetricTags, context?: LogContext) => void;
-	gauge: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
-	histogram: (name: string, value: number, unit?: any, tags?: MetricTags, context?: LogContext) => void;
-	latency: (name: string, startMs: number, tags?: MetricTags, context?: LogContext) => void;
-	withContext: (context: LogContext) => AgentMetrics;
-}
-interface AgentEvents {
-	track: (name: string, properties?: EventProperties, context?: any) => void;
-	withContext: (context: any) => AgentEvents;
-}
-interface AgentObservability {
-	logger: AgentLogger;
-	metrics: AgentMetrics;
-	events: AgentEvents;
-	withContext: (context: LogContext) => AgentObservability;
-}
-type AgentLoggerInput = AgentLogger | ObservabilityLoggerLike | ConsoleLikeLogger | undefined;
-type AgentObservabilityInput = AgentObservability | {
-	logger?: AgentLoggerInput;
-	metrics?: AgentMetrics | ObservabilityMetricsLike;
-	events?: AgentEvents | ObservabilityEventsLike;
-} | AgentLoggerInput;
-interface TestDataApiOptions {
-	/**
-	 * Called after every successful write. Used by WorkerRuntime to fan out
-	 * snapshots over the sessionTestData subscription.
-	 */
-	onChange?: () => void;
-	/**
-	 * Optional logger. When supplied, every setRuntime/getRuntime call emits a
-	 * structured info log so the operator can trace test-data writes without
-	 * grepping for `provider.upsert`.
-	 */
-	logger?: AgentLoggerInput;
-}
-declare class TestDataApi {
-	private readonly provider;
-	private readonly context;
-	private readonly options;
-	private readonly logger?;
-	constructor(provider: ITestDataProvider, context: ResolutionContext, options?: TestDataApiOptions);
-	/**
-	 * Save a value to runtime test data.
-	 *
-	 * Runtime values:
-	 *  - resolvable as `{{key}}` in subsequent steps within the same execution
-	 *  - scoped to the current scenario; cleared when the scenario or environment changes
-	 *  - last write wins for the same key inside one run (idempotent)
-	 *
-	 * @example  in AI-chat-generated custom code
-	 *   const orderId = await page.locator('[data-order-id]').getAttribute('data-order-id');
-	 *   await context.testData.setRuntime('orderId', orderId ?? '');
-	 *
-	 * @example  with explicit dataType
-	 *   await context.testData.setRuntime('authToken', token, { dataType: 'secret' });
-	 */
-	setRuntime(key: string, value: string, opts?: {
-		dataType?: TestDataType;
-	}): Promise<void>;
-	/**
-	 * Read a runtime value previously saved via setRuntime or an extract step.
-	 *
-	 * Returns `null` if no entry exists for `key` in the current runtime scope.
-	 * Does NOT walk the scope chain. For full resolution including environment +
-	 * global, use the `{{key}}` token syntax with the resolver.
-	 */
-	getRuntime(key: string): Promise<string | null>;
-	/**
-	 * Read a value through the full runtime → scenario → feature → environment → global
-	 * scope chain. This is used by built-in utility commands that need the raw value
-	 * rather than `{{key}}` token interpolation.
-	 */
-	getScoped(key: string): Promise<string | null>;
-}
 type ApiExecutionResponse = ApiResponseSnapshot;
 type CommandExecutionContext = {
 	stepParameters?: Record<string, string>;
@@ -8874,6 +9146,7 @@ type TesterOptions = {
 	 * an absolute path. Lets the caller (worker / planner) own FS layout.
 	 */
 	getDownloadTargetPath?: (fileName: string) => string;
+	customCodeRuntime?: CustomCodeRuntime;
 };
 type TesterTraceConfig = {
 	mode?: "upload";
@@ -8923,6 +9196,7 @@ declare class Tester {
 	private readonly fileResolver?;
 	private readonly downloadStore?;
 	private readonly getDownloadTargetPath?;
+	private readonly customCodeRuntime?;
 	private pageList;
 	private sessionToken;
 	private activeBrowserContext;
@@ -9077,7 +9351,7 @@ declare class Tester {
 			downloadCount: number;
 			pageErrorCount: number;
 		} | undefined;
-	} | {
+	} | CustomCodeExecutionResult | {
 		status: number;
 		statusText: string;
 		timeMs: number;
@@ -9086,6 +9360,14 @@ declare class Tester {
 		bodyText: string;
 		bodyJson?: unknown;
 	} | undefined>;
+	/**
+	 * Runtime test-data accessor bound to the tester's current data provider and
+	 * resolution context. Returns `undefined` when no provider/context is
+	 * configured (e.g. a tester constructed without a test-data layer). A fresh
+	 * instance is returned each access so it always reflects the latest context
+	 * set via `setContext`.
+	 */
+	get testDataApi(): TestDataApi | undefined;
 	extractToTestData(input: {
 		key: string;
 		value: string;
@@ -9120,13 +9402,106 @@ export type PlaywrightRunnerParameters = {
 export type PlaywrightRunnerOptions = {
 	readonly parameters?: PlaywrightRunnerParameters;
 };
-export type PlaywrightRunnerTester = Pick<Tester, "executeCommand"> & Partial<Pick<Tester, "setContext">>;
+export type PlaywrightRunnerTester = Pick<Tester, "executeCommand"> & Partial<Pick<Tester, "setContext" | "testDataApi">>;
 export type PlaywrightRunnerDependencies = {
 	readonly tester?: PlaywrightRunnerTester;
 	readonly testDataProvider?: ITestDataProvider;
 	readonly logger?: Pick<Console, "error" | "info" | "log" | "warn">;
 };
-type GeneratedCommand = Parameters<PlaywrightRunnerTester["executeCommand"]>[0]["command"];
+/**
+ * Tagged union the recorder stores in `command.data.value` for assertions
+ * that accept a string-or-regex (`toHaveText`, `toHaveURL`, ...) or a
+ * primitive-or-regex (`toHaveJSProperty`). Mirrors the `StringOrRegex` /
+ * `PrimitiveOrRegex` schemas in `@blinq/schemas/base.schema`.
+ */
+export type MatcherValueInput = {
+	type: "string";
+	value: string;
+} | {
+	type: "number";
+	value: number;
+} | {
+	type: "boolean";
+	value: boolean;
+} | {
+	type: "regex";
+	source: string;
+	flags?: string;
+};
+/**
+ * Resolve the recorder's tagged value into the form Playwright's matchers
+ * expect: a plain string/number/boolean, or a `RegExp` for `{ type: "regex" }`.
+ *
+ * Generated spec code calls this on `resolvedCommand.data.value` before
+ * passing it to `expect(locator).toHaveText(...)`, `.toHaveJSProperty(...)`,
+ * etc. Returns `undefined` when given `undefined` so it composes cleanly with
+ * optional fields (e.g. `toHaveAttribute`'s `value`).
+ */
+export declare function toMatcherValue(value: MatcherValueInput): string | number | boolean | RegExp;
+export declare function toMatcherValue(value: undefined): undefined;
+export declare function toMatcherValue(value: MatcherValueInput | undefined): string | number | boolean | RegExp | undefined;
+type GeneratedCommand = Command;
+/**
+ * Stateful API helper for generated `api.action` / `api.assertion` steps.
+ * Mirrors the Tester's runtime: a request stores its response as `lastResponse`
+ * (and writes `saveAs` to runtime test data), and an assertion runs against
+ * that stored response. The shared state lives here because the request and
+ * assertion are emitted as separate `test.step` blocks with no shared scope.
+ */
+export type BlinqApi = {
+	/** Run the request, store it as `lastResponse`, and persist `saveAs` if set. */
+	request(request: ApiRequest): Promise<ApiResponseSnapshot>;
+	/** Assert against `lastResponse`; throws if no request has run yet. */
+	assert(assertion: ApiResponseAssertionCommandData): Promise<void>;
+	readonly lastResponse: ApiResponseSnapshot | undefined;
+};
+/**
+ * The `context` object AI-chat (`custom`) command code receives. Mirrors the
+ * recorder sandbox's `context`: the resolution-scope fields plus a `testData`
+ * accessor (which is the runner's `TestDataApi`, exposing
+ * `set`/`get`/`setRuntime`/`getRuntime`).
+ */
+export type AiChatContext = {
+	readonly testData: TestDataApi;
+	readonly projectId?: string;
+	readonly environmentId?: string;
+	readonly featureId?: string;
+	readonly scenarioId?: string;
+	readonly executionId?: string;
+};
+/**
+ * The globals AI-chat custom code expects beyond `page` / `expect` / `console`.
+ * Generated specs declare `context`, `checkpoint`, `onCommandStart`, and
+ * `onCommandPass` above the inlined code, sourced from the bvt fixture.
+ *
+ * Recovery helpers (`helpers.getPreferredInteractiveTarget`, etc.) are
+ * intentionally NOT provided — they depend on bvt-agent's runtime recovery and
+ * have no standalone equivalent.
+ */
+export type AiChatGlobals = {
+	readonly context: AiChatContext;
+	checkpoint(label: string, data?: unknown): void;
+	onCommandStart(label: string): Promise<void>;
+	onCommandPass(opts?: {
+		delayMs?: number;
+	}): Promise<void>;
+};
+/**
+ * Build the AI-chat command globals. Mirrors the recorder sandbox:
+ * `onCommandStart` waits the watch-delay then records the command boundary,
+ * `onCommandPass` waits the (overridable) watch-delay, and `checkpoint`
+ * records a labelled marker. In a standalone Playwright run the sandbox's
+ * live-timeline bridge is replaced by Playwright test annotations (via the
+ * injected `annotate` callback).
+ */
+export declare function createAiChatGlobals(input: {
+	testDataApi: TestDataApi;
+	parameters: PlaywrightRunnerParameters;
+	annotate: (annotation: {
+		type: string;
+		description: string;
+	}) => void;
+}): AiChatGlobals;
 export declare class TempFileTestDataProvider implements ITestDataProvider {
 	readonly filePath: string;
 	readonly seedFilePath?: string | undefined;
@@ -9158,6 +9533,7 @@ export declare class PlaywrightRunner {
 	private readonly scopeManager?;
 	private readonly preprocessors;
 	private resolutionContext;
+	private apiRuntime?;
 	constructor(options?: PlaywrightRunnerOptions, dependencies?: PlaywrightRunnerDependencies);
 	private applyResolutionContext;
 	/**
@@ -9166,63 +9542,14 @@ export declare class PlaywrightRunner {
 	 */
 	attach(page: Page): void;
 	detach(): void;
-	executeCommand(command: GeneratedCommand, parameters?: Record<string, string>): Promise<{
-		success: boolean;
-		logs: string[];
-		checkpoints: {
-			label: string;
-			timestampMs: number;
-			data?: unknown;
-		}[];
-		duration: number;
-		result?: unknown;
-		error?: string | undefined;
-		userMessage?: string | undefined;
-		screenshotAfter?: string | undefined;
-		mutationSignals?: {
-			httpMutations: {
-				method: "POST" | "PUT" | "PATCH" | "DELETE";
-				url: string;
-				status: number;
-				timestampMs: number;
-			}[];
-			cookieChanges: {
-				name: string;
-				action: "added" | "modified" | "deleted";
-				suspectedAuth: boolean;
-			}[];
-			storageMutations: {
-				localStorage: {
-					added: string[];
-					modified: string[];
-					deleted: string[];
-				};
-				sessionStorage: {
-					added: string[];
-					modified: string[];
-					deleted: string[];
-				};
-			};
-			navigationEvents: {
-				url: string;
-				timestampMs: number;
-			}[];
-			dialogEvents: {
-				type: "alert" | "confirm" | "prompt";
-				message: string;
-			}[];
-			downloadCount: number;
-			pageErrorCount: number;
-		} | undefined;
-	} | {
-		status: number;
-		statusText: string;
-		timeMs: number;
-		sizeBytes: number;
-		headers: Record<string, string>;
-		bodyText: string;
-		bodyJson?: unknown;
-	} | undefined>;
+	/**
+	 * Stateful API helper for `api.action` / `api.assertion` steps. Lazily built
+	 * and held for the runner's lifetime so a request and its following assertion
+	 * share `lastResponse`. Throws if no test-data provider/context is available
+	 * (the `saveAs` path needs it).
+	 */
+	get api(): BlinqApi;
+	executeCommand(command: GeneratedCommand, parameters?: Record<string, string>): Promise<unknown>;
 	/**
 	 * Run the preprocessor pipeline (step parameters, data-resolver tokens,
 	 * ai-chat code tokens, test-data API) over `command` and validate the
@@ -9288,6 +9615,31 @@ export type CreateBlinqTestOptions = {
 export type BlinqTestRuntime = {
 	readonly page: Page;
 	readonly parameters: PlaywrightRunnerParameters;
+	/**
+	 * Runtime test-data accessor. Extract steps write the extracted value via
+	 * `bvt.testDataApi.setRuntime(key, value, { dataType })` so it resolves as
+	 * `{{key}}` in later steps.
+	 */
+	readonly testDataApi: TestDataApi;
+	/**
+	 * Stateful API helper. `api.action` steps call `bvt.api.request(...)` and
+	 * `api.assertion` steps call `bvt.api.assert(...)`; the request's response is
+	 * shared with the following assertion via `bvt.api.lastResponse`.
+	 */
+	readonly api: BlinqApi;
+	/**
+	 * The `context` object AI-chat (`custom`) command code receives; generated
+	 * specs declare `const context = bvt.aiChatContext` above the inlined code.
+	 */
+	readonly aiChatContext: AiChatContext;
+	/** AI-chat `checkpoint(label, data?)` global — records a Playwright annotation. */
+	checkpoint(label: string, data?: unknown): void;
+	/** AI-chat `onCommandStart(label)` global — watch-delay then a boundary annotation. */
+	onCommandStart(label: string): Promise<void>;
+	/** AI-chat `onCommandPass(opts?)` global — watch-delay (overridable via `delayMs`). */
+	onCommandPass(opts?: {
+		delayMs?: number;
+	}): Promise<void>;
 	executeCommand(command: GeneratedCommand, parameters?: Record<string, string>): Promise<unknown>;
 	resolveCommand(command: unknown, parameters?: Record<string, string>): Promise<Command>;
 	find(command: Command): Promise<Locator | Page | FrameLocator | null>;