fix: preserve browser environment continuity

Author: chubes4

README.md

@@ -739,7 +739,7 @@ For synthetic web performance investigations, enable `capture=performance` and u
 
 `wordpress.browser-actions` drives the preview with an ordered interaction script so Codebox can prove a plugin still *works* under interaction, not just that it renders. Pass the script as `steps-json=<array>` (inline JSON, or `@<path>` to read it from a file). Each step is a thin, stable mapping over a Playwright locator action — this is not a test-runner DSL.
 
-Action journeys and adaptive exploration can declare their browser context with `browser-environment-json=<object>` (inline or `@<path>`) or the compatible `device`, `viewport`, `device-scale-factor`, `is-mobile`, `has-touch`, `locale`, `timezone`, and `geolocation-*` arguments. These controls are applied when the Playwright context is created, so mobile/touch emulation and granted, denied, or prompt geolocation remain effective for the full journey. Action summaries record requested and effective environment state, provider capabilities, and explicit unsupported dimensions. `wordpress.browser-scenario` accepts the same arguments or an `environment` object inside `scenario-json` and carries it into authored action steps.
+Action journeys and adaptive exploration can declare their browser context with `browser-environment-json=<object>` (inline or `@<path>`) or the compatible `device`, `viewport`, `device-scale-factor`, `is-mobile`, `has-touch`, `user-agent`, `permissions`, `locale`, `timezone`, and `geolocation-*` arguments. These controls are applied when the Playwright context is created, so mobile/touch emulation and granted, denied, or prompt geolocation remain active for the full journey. Action summaries keep requested configuration, provider-resolved configuration, and browser-observed state separate, with explicit unsupported and inconclusive dimensions. `wordpress.browser-scenario` accepts the same arguments or an `environment` object inside `scenario-json`; probe collection and authored actions share one owned context/page, while multi-actor scenarios create one isolated configured context per actor.
 
 Step kinds: `navigate` (`url`, optional `waitFor=domcontentloaded|load|networkidle`), `click`/`hover` (`selector` or `text`), `fill`/`type` (`selector`, `value`), `press` (`key`, optional `selector`), `drag` (`from` selector, `to` as `{ "selector": ... }` or `{ "x": n, "y": n }`), `select` (`selector`, `value` or `values`), `waitFor` (`selector` or `waitFor=domcontentloaded|load|networkidle|duration|selector:<sel>`), `evaluate` (`expression`, optional `assert` to deep-equal the result), `expect` (`selector`, optional `state=visible|hidden|attached|detached|enabled|disabled|checked|unchecked|editable`), and `screenshot` (optional `name` for a named capture). Every step may set its own `timeout=<n>s`; the command also accepts a global `step-timeout=<n>s` (per step) and `timeout=<n>s` (total-script budget). Both are bounded and deterministic — the run stops cleanly on the first failing step, with no silent partial success.
 

packages/cli/src/recipe-validation.ts

@@ -1,6 +1,6 @@
 import { readFile, stat } from "node:fs/promises"
 import { dirname, join, resolve } from "node:path"
-import { RUNTIME_BACKED_FUZZ_SUITE_RUNNER_CAPABILITIES, assertFixtureImportDeterministicIdsSupported, assertWorkspaceRecipeJsonSchema, browserEnvironment, commandArgValue, normalizeRuntimeBackendKind, normalizeRuntimeMountTarget, parseCommandJson, safeArtifactRelativePath, validateBrowserInteractionScript, validateRuntimePolicy, validateSourcePackage, workspaceRecipeRuntimeCollectedArtifacts, type MountSpec, type RuntimeAssetSpec, type RuntimePolicy, type RuntimePreviewSpec, type WorkspaceRecipe, type WorkspaceRecipeDeclaredArtifact, type WorkspaceRecipeDependencyOverlay, type WorkspaceRecipeDistribution, type WorkspaceRecipeDistributionStartupProbe, type WorkspaceRecipeFixtureDatabase, type WorkspaceRecipeFuzzCasePhase, type WorkspaceRecipeMount, type WorkspaceRecipePluginRuntime, type WorkspaceRecipePluginRuntimeHealthProbe, type WorkspaceRecipeProbe, type WorkspaceRecipeRuntimeBackendPackage, type WorkspaceRecipeRuntimeOverlay, type WorkspaceRecipeSiteSeed } from "@automattic/wp-codebox-core"
+import { BROWSER_PROBE_CHROMIUM_PROFILE_IDS, RUNTIME_BACKED_FUZZ_SUITE_RUNNER_CAPABILITIES, assertFixtureImportDeterministicIdsSupported, assertWorkspaceRecipeJsonSchema, browserEnvironment, commandArgValue, normalizeRuntimeBackendKind, normalizeRuntimeMountTarget, parseCommandJson, safeArtifactRelativePath, validateBrowserInteractionScript, validateRuntimePolicy, validateSourcePackage, workspaceRecipeRuntimeCollectedArtifacts, type MountSpec, type RuntimeAssetSpec, type RuntimePolicy, type RuntimePreviewSpec, type WorkspaceRecipe, type WorkspaceRecipeDeclaredArtifact, type WorkspaceRecipeDependencyOverlay, type WorkspaceRecipeDistribution, type WorkspaceRecipeDistributionStartupProbe, type WorkspaceRecipeFixtureDatabase, type WorkspaceRecipeFuzzCasePhase, type WorkspaceRecipeMount, type WorkspaceRecipePluginRuntime, type WorkspaceRecipePluginRuntimeHealthProbe, type WorkspaceRecipeProbe, type WorkspaceRecipeRuntimeBackendPackage, type WorkspaceRecipeRuntimeOverlay, type WorkspaceRecipeSiteSeed } from "@automattic/wp-codebox-core"
 import { commandValidationDescriptorFor, effectivePolicyCommandsFor, type CommandArgValidationDescriptor } from "@automattic/wp-codebox-core/contracts"
 import { composerPackageVendorPath, evaluateRecipeSourcePolicy, isComposerPackageName, pluginTarget, recipeExtraPluginSlug, recipeExtraPluginSource, recipeExtraPluginSourceRoot, recipeExtraPluginSourceSubpath, recipeExtraPlugins, recipeSource, resolveRecipeExtraPluginFile } from "./recipe-sources.js"
 import { loadConfiguredRuntimeOverlayDescriptors, registeredRuntimeOverlayDescriptors, runtimeOverlayDescriptor, runtimeOverlayTarget } from "./runtime-overlay-registry.js"
@@ -582,7 +582,7 @@ export async function validateWorkspaceRecipeSemantics(recipe: WorkspaceRecipe,
       continue
     }
 
-    await validateRecipeStepArgs(step, path, addIssue)
+    await validateRecipeStepArgs(step, path, addIssue, recipeDirectory)
   }
 
   for (const [index, mount] of (recipe.inputs?.mounts ?? []).entries()) {
@@ -693,7 +693,7 @@ export async function validateWorkspaceRecipeSemantics(recipe: WorkspaceRecipe,
     validateAbsoluteSandboxPath(`${pluginTarget(overlay.consumer, loadAs)}/vendor/${composerPackageVendorPath(overlay.package)}`, `${path}.target`, addIssue)
   }
 
-  await validateRecipePluginRuntime(recipe.inputs?.pluginRuntime, addIssue)
+  await validateRecipePluginRuntime(recipe.inputs?.pluginRuntime, addIssue, recipeDirectory)
 
   for (const [index, fixture] of (recipe.inputs?.fixtureDatabases ?? []).entries()) {
     const path = `$.inputs.fixtureDatabases[${index}]`
@@ -711,7 +711,7 @@ export async function validateWorkspaceRecipeSemantics(recipe: WorkspaceRecipe,
       addIssue("unsupported-command", `${path}.command`, `Unsupported recipe probe command: ${probe.step.command}`)
       continue
     }
-    await validateRecipeStepArgs(probe.step, path, addIssue)
+    await validateRecipeStepArgs(probe.step, path, addIssue, recipeDirectory)
   }
 
   for (const [index, name] of (recipe.inputs?.secretEnv ?? []).entries()) {
@@ -1318,7 +1318,7 @@ export function recipeWpCliCommandFromArgs(args: string[]): string {
   return recipeStepArgValue(args, "command")?.trim() ?? args.join(" ").trim()
 }
 
-async function validateRecipePluginRuntime(pluginRuntime: WorkspaceRecipePluginRuntime | undefined, addIssue: (code: string, path: string, message: string) => void): Promise<void> {
+async function validateRecipePluginRuntime(pluginRuntime: WorkspaceRecipePluginRuntime | undefined, addIssue: (code: string, path: string, message: string) => void, recipeDirectory: string): Promise<void> {
   if (!pluginRuntime) {
     return
   }
@@ -1366,7 +1366,7 @@ async function validateRecipePluginRuntime(pluginRuntime: WorkspaceRecipePluginR
       addIssue("unsupported-plugin-runtime-setup-command", `${path}.command`, `Unsupported plugin runtime setup command: ${step.command}`)
       continue
     }
-    await validateRecipeStepArgs(step, path, addIssue)
+    await validateRecipeStepArgs(step, path, addIssue, recipeDirectory)
   }
 
   for (const [index, probe] of (pluginRuntime.healthProbes ?? []).entries()) {
@@ -1501,7 +1501,7 @@ export function hasExplicitSiteSeedSelectors(scope: NonNullable<WorkspaceRecipeS
   return [scope.ids, scope.slugs, scope.names].some((values) => Array.isArray(values) && values.length > 0)
 }
 
-async function validateRecipeStepArgs(step: WorkspaceRecipe["workflow"]["steps"][number], path: string, addIssue: (code: string, path: string, message: string) => void): Promise<void> {
+async function validateRecipeStepArgs(step: WorkspaceRecipe["workflow"]["steps"][number], path: string, addIssue: (code: string, path: string, message: string) => void, recipeDirectory: string): Promise<void> {
   validateRecipeStepDescriptorArgs(step, path, addIssue)
 
   if (step.command === "wordpress.run-php" || step.command === "wordpress.phpunit" || step.command === "wordpress.core-phpunit") {
@@ -1563,14 +1563,17 @@ async function validateRecipeStepArgs(step: WorkspaceRecipe["workflow"]["steps"]
       addIssue("incomplete-geolocation", `${path}.args`, `${step.command} geolocation-permission requires geolocation-latitude and geolocation-longitude.`)
     }
     const environmentJson = recipeStepArgValue(step.args ?? [], "browser-environment-json")
-    if (environmentJson && !environmentJson.startsWith("@")) {
+    if (environmentJson) {
       try {
-        browserEnvironment(JSON.parse(environmentJson))
+        const rawEnvironment = environmentJson.startsWith("@") ? await readFile(resolve(recipeDirectory, environmentJson.slice(1)), "utf8") : environmentJson
+        browserEnvironment(JSON.parse(rawEnvironment))
       } catch (error) {
         addIssue("invalid-browser-environment", `${path}.args`, `${step.command} browser-environment-json is invalid: ${error instanceof Error ? error.message : String(error)}`)
       }
     }
-    if (step.command !== "wordpress.browser-probe") return
+  }
+
+  if (step.command === "wordpress.browser-probe") {
     for (const assertion of (step.args ?? []).filter((arg) => arg.startsWith("assert=")).map((arg) => arg.slice("assert=".length).trim())) {
       const rawNormalized = assertion.startsWith("advisory:") ? assertion.slice("advisory:".length).trim() : assertion
       const frameSeparator = rawNormalized.startsWith("frame:") || rawNormalized.startsWith("frame-url:") ? rawNormalized.indexOf("|") : -1
@@ -1673,6 +1676,18 @@ async function validateRecipeStepArgs(step: WorkspaceRecipe["workflow"]["steps"]
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
           addIssue("invalid-scenario-json", `${path}.args`, "wordpress.browser-scenario scenario-json must be a JSON object.")
         } else {
+          const profile = (parsed as { profile?: unknown }).profile
+          if (profile !== undefined && (typeof profile !== "string" || !(BROWSER_PROBE_CHROMIUM_PROFILE_IDS as readonly string[]).includes(profile))) {
+            addIssue("invalid-profile", `${path}.args`, `wordpress.browser-scenario profile is unsupported: ${String(profile)}`)
+          }
+          const environment = (parsed as { environment?: unknown }).environment
+          if (environment !== undefined) {
+            try {
+              browserEnvironment(environment as Parameters<typeof browserEnvironment>[0])
+            } catch (error) {
+              addIssue("invalid-browser-environment", `${path}.args`, `wordpress.browser-scenario environment is invalid: ${error instanceof Error ? error.message : String(error)}`)
+            }
+          }
           const steps = (parsed as { steps?: unknown }).steps
           if (steps !== undefined) {
             const result = validateBrowserInteractionScript(normalizeBrowserScenarioStepsForValidation(steps))

packages/runtime-core/src/browser-adaptive-exploration.ts

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto"
 import type { BrowserActionCorpusDescriptor, BrowserInteractionStep, BrowserRandomWalkContext } from "./browser-interaction.js"
 import { browserAccessibilityContract, type BrowserAccessibilityContract, type BrowserAccessibilityEvidence } from "./browser-accessibility.js"
 import { isPlainObject, stableJson, stripUndefined } from "./object-utils.js"
+import { browserEnvironment, browserEnvironmentDigest, type BrowserEnvironment } from "./browser-environment-matrix.js"
 
 export const BROWSER_ADAPTIVE_EXPLORATION_SCHEMA = "wp-codebox/browser-adaptive-exploration/v1" as const
 export const BROWSER_ADAPTIVE_EXPLORATION_ARTIFACT_SCHEMA = "wp-codebox/browser-adaptive-exploration-artifact/v1" as const
@@ -36,6 +37,8 @@ export interface BrowserAdaptiveExplorationContract {
   failOnFinding: boolean
   accessibility?: BrowserAccessibilityContract
   metadata?: Record<string, unknown>
+  environment: BrowserEnvironment
+  environmentDigest: string
 }
 
 export interface BrowserAdaptiveFrameIdentity {
@@ -116,6 +119,8 @@ export interface BrowserAdaptiveFinding {
     expectedStateDigest?: string
     actions: BrowserAdaptiveAction[]
     resetPolicy: BrowserAdaptiveExplorationContract["resetPolicy"]
+    environment: BrowserEnvironment
+    environmentDigest: string
   }
 }
 
@@ -138,7 +143,7 @@ export interface BrowserAdaptiveExplorationResult {
     findings: number
     budgetExhausted?: keyof BrowserAdaptiveExplorationContract["budgets"] | "maxKeyboardActions" | "cancelled" | "frontier"
   }
-  replay: { schema: typeof BROWSER_ADAPTIVE_EXPLORATION_SCHEMA; seed: string; startUrl: string; contract: BrowserAdaptiveExplorationContract }
+  replay: { schema: typeof BROWSER_ADAPTIVE_EXPLORATION_SCHEMA; seed: string; startUrl: string; environment: BrowserEnvironment; environmentDigest: string; contract: BrowserAdaptiveExplorationContract }
 }
 
 export interface BrowserAdaptiveExplorationArtifact {
@@ -162,6 +167,7 @@ export function browserAdaptiveExplorationContract(input: Record<string, unknown
     : []
   const actionFamilies = [...new Set(families.filter((value): value is BrowserAdaptiveActionFamily => (BROWSER_ADAPTIVE_ACTION_FAMILIES as readonly unknown[]).includes(value)))]
   const startUrl = string(input.startUrl ?? input.start_url) ?? (context === "admin" ? "/wp-admin/" : context === "editor" ? "/wp-admin/post-new.php" : "/")
+  const environment = browserEnvironment(isPlainObject(input.environment) ? input.environment as BrowserEnvironment : {})
   return stripUndefined({
     schema: BROWSER_ADAPTIVE_EXPLORATION_SCHEMA,
     context,
@@ -196,6 +202,8 @@ export function browserAdaptiveExplorationContract(input: Record<string, unknown
     failOnFinding: input.failOnFinding !== false && input.fail_on_finding !== false,
     accessibility,
     metadata: isPlainObject(input.metadata) ? input.metadata : undefined,
+    environment,
+    environmentDigest: browserEnvironmentDigest(environment),
   })
 }