Merge pull request #2085 from Automattic/fix/2084-browser-geolocation

Add deterministic browser geolocation contexts

Author: chubes4

packages/cli/src/recipe-validation.ts

@@ -1549,6 +1549,19 @@ async function validateRecipeStepArgs(step: WorkspaceRecipe["workflow"]["steps"]
   }
 
   if (step.command === "wordpress.browser-probe") {
+    const latitude = recipeStepArgValue(step.args ?? [], "geolocation-latitude")
+    const longitude = recipeStepArgValue(step.args ?? [], "geolocation-longitude")
+    const accuracy = recipeStepArgValue(step.args ?? [], "geolocation-accuracy")
+    const permission = recipeStepArgValue(step.args ?? [], "geolocation-permission")
+    if (Boolean(latitude) !== Boolean(longitude)) {
+      addIssue("incomplete-geolocation", `${path}.args`, "wordpress.browser-probe geolocation requires both geolocation-latitude and geolocation-longitude.")
+    }
+    if (accuracy && (!latitude || !longitude)) {
+      addIssue("incomplete-geolocation", `${path}.args`, "wordpress.browser-probe geolocation-accuracy requires geolocation-latitude and geolocation-longitude.")
+    }
+    if (permission && (!latitude || !longitude)) {
+      addIssue("incomplete-geolocation", `${path}.args`, "wordpress.browser-probe geolocation-permission requires geolocation-latitude and geolocation-longitude.")
+    }
     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
@@ -1774,6 +1787,14 @@ function validateRecipeStepDescriptorArgRule(args: string[], rule: CommandArgVal
     return
   }
 
+  if (rule.kind === "number") {
+    const value = Number(raw)
+    if (!Number.isFinite(value) || value < rule.minimum || value > rule.maximum) {
+      addIssue(rule.code, issuePath, rule.message)
+    }
+    return
+  }
+
   if (rule.kind === "enum") {
     if (!(rule.values as readonly string[]).includes(raw) && !(rule.prefixes ?? []).some((prefix) => raw.startsWith(prefix))) {
       addIssue(rule.code, issuePath, descriptorValueMessage(rule, raw))

packages/runtime-core/src/browser-environment-matrix.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto"
 
 import { stableJson, stripUndefined } from "./object-utils.js"
+import { browserGeolocation, type BrowserGeolocation } from "./browser-probe-contract.js"
 
 export const BROWSER_ENVIRONMENT_MATRIX_SCHEMA = "wp-codebox/browser-environment-matrix/v1" as const
 export const BROWSER_ENVIRONMENT_MATRIX_REPORT_SCHEMA = "wp-codebox/browser-environment-matrix-report/v1" as const
@@ -27,6 +28,7 @@ export interface BrowserEnvironment {
   cpuProfile?: string
   online?: boolean
   clock?: { mode: "realtime" | "fixed"; at?: string }
+  geolocation?: BrowserGeolocation
   capabilities?: Record<string, boolean | string | number>
 }
 
@@ -301,7 +303,7 @@ function normalizeDimension(dimension: BrowserEnvironmentDimension): BrowserEnvi
   const values = dimension.values.map((value) => {
     if (!safeId(value.id)) throw new Error(`Invalid browser environment value id in ${dimension.id}: ${value.id}`)
     validateEnvironment(value.environment)
-    return { id: value.id, environment: canonicalEnvironment(value.environment), requiredCapabilities: uniqueSorted(value.requiredCapabilities ?? []), optionalCapabilities: uniqueSorted(value.optionalCapabilities ?? []) }
+    return { id: value.id, environment: canonicalEnvironment(value.environment), requiredCapabilities: uniqueSorted([...(value.requiredCapabilities ?? []), ...(value.environment.geolocation ? ["browser.environment.geolocation"] : [])]), optionalCapabilities: uniqueSorted(value.optionalCapabilities ?? []) }
   }).sort((left, right) => left.id.localeCompare(right.id) || stableJson(left.environment).localeCompare(stableJson(right.environment)))
   if (new Set(values.map(({ id }) => id)).size !== values.length) throw new Error(`Browser environment value ids must be unique in ${dimension.id}.`)
   return { id: dimension.id, values }
@@ -325,7 +327,7 @@ function validateEnvironment(environment: BrowserEnvironment): void {
 }
 
 function canonicalEnvironment(environment: BrowserEnvironment): BrowserEnvironment {
-  return JSON.parse(stableJson(JSON.parse(JSON.stringify(environment)))) as BrowserEnvironment
+  return JSON.parse(stableJson(JSON.parse(JSON.stringify({ ...environment, ...(environment.geolocation ? { geolocation: browserGeolocation(environment.geolocation) } : {}) })))) as BrowserEnvironment
 }
 
 function mergeEnvironment(left: BrowserEnvironment, right: BrowserEnvironment): BrowserEnvironment {

packages/runtime-core/src/browser-probe-contract.ts

@@ -17,6 +17,37 @@ export const BROWSER_PROBE_BROWSER_VALUES = ["chromium"] as const
 export const BROWSER_PROBE_CAPTURE_VALUES = ["console", "errors", "html", "network", "websocket", "performance", "memory", "screenshot"] as const
 export const BROWSER_PROBE_CHROMIUM_PROFILE_IDS = ["desktop-chrome", "mobile-chrome", "low-end-mobile-slow-4g"] as const
 export const BROWSER_PROBE_THROTTLE_PROFILE_IDS = ["low-end-mobile-slow-4g"] as const
+export const BROWSER_GEOLOCATION_PERMISSION_STATES = ["granted", "denied", "prompt"] as const
+export const BROWSER_GEOLOCATION_PERMISSION_ALIASES = ["default"] as const
+export const BROWSER_GEOLOCATION_MAX_ACCURACY_METERS = 1_000_000
+
+export type BrowserGeolocationPermissionState = (typeof BROWSER_GEOLOCATION_PERMISSION_STATES)[number]
+
+export interface BrowserGeolocation {
+  latitude: number
+  longitude: number
+  accuracy?: number
+  permission: BrowserGeolocationPermissionState
+}
+
+export function normalizeBrowserGeolocationPermissionState(value: string): BrowserGeolocationPermissionState {
+  const normalized = value.trim().toLowerCase()
+  if (normalized === "default") return "prompt"
+  if ((BROWSER_GEOLOCATION_PERMISSION_STATES as readonly string[]).includes(normalized)) return normalized as BrowserGeolocationPermissionState
+  throw new Error(`Browser geolocation permission must be ${[...BROWSER_GEOLOCATION_PERMISSION_STATES, ...BROWSER_GEOLOCATION_PERMISSION_ALIASES].join(", ")}: ${value}`)
+}
+
+export function browserGeolocation(input: Omit<BrowserGeolocation, "permission"> & { permission?: BrowserGeolocationPermissionState | "default" }): BrowserGeolocation {
+  if (!Number.isFinite(input.latitude) || input.latitude < -90 || input.latitude > 90) throw new Error("Browser geolocation latitude must be a finite number between -90 and 90.")
+  if (!Number.isFinite(input.longitude) || input.longitude < -180 || input.longitude > 180) throw new Error("Browser geolocation longitude must be a finite number between -180 and 180.")
+  if (input.accuracy !== undefined && (!Number.isFinite(input.accuracy) || input.accuracy < 0 || input.accuracy > BROWSER_GEOLOCATION_MAX_ACCURACY_METERS)) throw new Error(`Browser geolocation accuracy must be a finite number between 0 and ${BROWSER_GEOLOCATION_MAX_ACCURACY_METERS}.`)
+  return {
+    latitude: input.latitude,
+    longitude: input.longitude,
+    ...(input.accuracy !== undefined ? { accuracy: input.accuracy } : {}),
+    permission: normalizeBrowserGeolocationPermissionState(input.permission ?? "prompt"),
+  }
+}
 
 export const BROWSER_PROBE_PROFILES: Record<(typeof BROWSER_PROBE_CHROMIUM_PROFILE_IDS)[number], BrowserProbeProfileDefinition> = {
   "desktop-chrome": {
@@ -49,6 +80,10 @@ export const BROWSER_PROBE_ACCEPTED_ARGS: BrowserProbeAcceptedArg[] = [
   { name: "timezone", description: "Optional browser context timezone.", format: "IANA timezone, e.g. America/New_York" },
   { name: "user-agent", description: "Optional browser context user agent override.", format: "string" },
   { name: "permissions", description: "Comma-separated browser permissions to grant to the context.", format: "comma-separated permission names" },
+  { name: "geolocation-latitude", description: "Browser context geolocation latitude.", format: "finite number from -90 to 90" },
+  { name: "geolocation-longitude", description: "Browser context geolocation longitude.", format: "finite number from -180 to 180" },
+  { name: "geolocation-accuracy", description: "Optional browser context geolocation accuracy in meters.", format: `finite number from 0 to ${BROWSER_GEOLOCATION_MAX_ACCURACY_METERS}` },
+  { name: "geolocation-permission", description: "Explicit browser context geolocation permission state. default is normalized to prompt.", format: [...BROWSER_GEOLOCATION_PERMISSION_STATES, ...BROWSER_GEOLOCATION_PERMISSION_ALIASES].join("|") },
   { name: "throttle", description: "Optional Chromium/CDP throttle profile, or none.", format: `none|${BROWSER_PROBE_THROTTLE_PROFILE_IDS.join("|")}` },
   { name: "auth", description: "Optional in-memory browser authentication mode. Use wordpress-admin to bootstrap WordPress admin cookies from PHP without writing token-bearing storage-state artifacts.", format: "wordpress-admin" },
   { name: "auth-user-id", description: "WordPress user ID used with auth=wordpress-admin; defaults to 1.", format: "positive integer" },

packages/runtime-core/src/command-registry.ts

@@ -1,4 +1,4 @@
-import { BROWSER_PROBE_ACCEPTED_ARGS, BROWSER_PROBE_BROWSER_VALUES, BROWSER_PROBE_CAPTURE_VALUES, BROWSER_PROBE_CHROMIUM_PROFILE_IDS, BROWSER_PROBE_THROTTLE_PROFILE_IDS } from "./browser-probe-contract.js"
+import { BROWSER_GEOLOCATION_MAX_ACCURACY_METERS, BROWSER_GEOLOCATION_PERMISSION_ALIASES, BROWSER_GEOLOCATION_PERMISSION_STATES, BROWSER_PROBE_ACCEPTED_ARGS, BROWSER_PROBE_BROWSER_VALUES, BROWSER_PROBE_CAPTURE_VALUES, BROWSER_PROBE_CHROMIUM_PROFILE_IDS, BROWSER_PROBE_THROTTLE_PROFILE_IDS } from "./browser-probe-contract.js"
 import { WORDPRESS_PAGE_LOAD_RESULT_JSON_SCHEMA, WORDPRESS_PAGE_LOAD_RESULT_SCHEMA } from "./wordpress-page-load-contracts.js"
 import { WORDPRESS_DB_RESULT_JSON_SCHEMA, WORDPRESS_DB_RESULT_SCHEMA } from "./wordpress-db-contracts.js"
 import { WORDPRESS_CRUD_RESULT_JSON_SCHEMA, WORDPRESS_CRUD_RESULT_SCHEMA } from "./wordpress-crud-contracts.js"
@@ -67,6 +67,7 @@ export type CommandArgValidationDescriptor =
   | { name: string; kind: "duration"; code: string; message: string }
   | { name: string; kind: "positive-integer"; code: string; message: string }
   | { name: string; kind: "viewport"; code: string; message: string }
+  | { name: string; kind: "number"; minimum: number; maximum: number; code: string; message: string }
   | { name: string; kind: "enum"; values: readonly string[]; prefixes?: readonly string[]; code: string; message: string }
   | { name: string; kind: "comma-list-enum"; values: readonly string[]; code: string; message: string }
 
@@ -127,6 +128,10 @@ const browserProbeValidation: CommandValidationDescriptor = {
     { name: "throttle", kind: "enum", values: ["none", ...BROWSER_PROBE_THROTTLE_PROFILE_IDS], code: "invalid-throttle", message: "wordpress.browser-probe throttle is unsupported" },
     { name: "browser", kind: "enum", values: BROWSER_PROBE_BROWSER_VALUES, code: "invalid-browser", message: `wordpress.browser-probe browser must be ${BROWSER_PROBE_BROWSER_VALUES.join(" or ")}.` },
     { name: "viewport", kind: "viewport", code: "invalid-viewport", message: "wordpress.browser-probe viewport must use <width>x<height>, for example 390x844." },
+    { name: "geolocation-latitude", kind: "number", minimum: -90, maximum: 90, code: "invalid-geolocation-latitude", message: "wordpress.browser-probe geolocation-latitude must be a finite number from -90 to 90." },
+    { name: "geolocation-longitude", kind: "number", minimum: -180, maximum: 180, code: "invalid-geolocation-longitude", message: "wordpress.browser-probe geolocation-longitude must be a finite number from -180 to 180." },
+    { name: "geolocation-accuracy", kind: "number", minimum: 0, maximum: BROWSER_GEOLOCATION_MAX_ACCURACY_METERS, code: "invalid-geolocation-accuracy", message: `wordpress.browser-probe geolocation-accuracy must be a finite number from 0 to ${BROWSER_GEOLOCATION_MAX_ACCURACY_METERS}.` },
+    { name: "geolocation-permission", kind: "enum", values: [...BROWSER_GEOLOCATION_PERMISSION_STATES, ...BROWSER_GEOLOCATION_PERMISSION_ALIASES], code: "invalid-geolocation-permission", message: "wordpress.browser-probe geolocation-permission must be granted, denied, prompt, or default." },
     { name: "capture", kind: "comma-list-enum", values: BROWSER_PROBE_CAPTURE_VALUES, code: "invalid-capture", message: "wordpress.browser-probe capture does not support" },
   ],
 }

packages/runtime-playground/src/browser-artifacts.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path"
-import { artifactManifestFile, type ArtifactManifestFile, type ArtifactManifestFileOptions, type ArtifactReviewBrowserSummary } from "@automattic/wp-codebox-core"
+import { artifactManifestFile, type ArtifactManifestFile, type ArtifactManifestFileOptions, type ArtifactReviewBrowserSummary, type BrowserGeolocation } from "@automattic/wp-codebox-core"
 import type { PlaygroundPreviewProxyDiagnostics } from "./preview-server.js"
 import type { Request } from "playwright"
 
@@ -353,6 +353,8 @@ export interface BrowserProbeReviewSummary {
     throttle: string | null
     waitFor: string
     durationMs: number
+    context?: BrowserProbeContextDetails
+    capabilities?: BrowserProbeCapabilityDiagnostics
   }
   timings: {
     startedAt: string
@@ -461,6 +463,21 @@ export interface BrowserProbeCapabilityDiagnostics {
     available: boolean
   }
   permissions: Record<string, BrowserProbePermissionState>
+  geolocation?: {
+    requested: BrowserGeolocation
+    effective: {
+      latitude: number
+      longitude: number
+      accuracy?: number
+      permission: BrowserProbePermissionState["state"]
+    }
+    support: {
+      coordinates: "supported" | "unsupported"
+      permission: "supported" | "unsupported"
+      unavailable: "unsupported"
+      reason: string
+    }
+  }
 }
 
 export interface BrowserProbePermissionState {
@@ -508,6 +525,7 @@ export interface BrowserProbeContextDetails {
     device?: string
     locale?: string
     permissions?: string[]
+    geolocation?: BrowserGeolocation
     profile?: string
     throttle?: string
     timezone?: string
@@ -522,6 +540,7 @@ export interface BrowserProbeContextDetails {
     device?: string
     locale?: string
     permissions?: string[]
+    geolocation?: BrowserGeolocation
     profile?: string
     throttle?: string
     timezone?: string

packages/runtime-playground/src/browser-environment-matrix.ts

@@ -31,6 +31,7 @@ export const PLAYWRIGHT_BROWSER_ENVIRONMENT_CAPABILITIES = [
   "browser.environment.cpu-profile",
   "browser.environment.online-state",
   "browser.environment.clock",
+  "browser.environment.geolocation",
   "browser.environment.capability-state",
 ] as const
 
@@ -83,6 +84,11 @@ export async function resolvePlaywrightBrowserEnvironment(cell: BrowserEnvironme
   if (requested.timezone) exact("browser.environment.timezone")
   if (requested.online !== undefined) exact("browser.environment.online-state")
   if (requested.clock) exact("browser.environment.clock")
+  if (requested.geolocation) {
+    requested.geolocation.permission !== "denied" || browser.browserType().name() === "chromium"
+      ? exact("browser.environment.geolocation")
+      : unsupported("browser.environment.geolocation", "This provider cannot express an explicit denied geolocation permission without Chromium browser permission controls.")
+  }
   if (requested.capabilities) exact("browser.environment.capability-state")
   if (requested.zoom !== undefined) emulated("browser.environment.zoom", "Applied as page scale through the browser debugging protocol; OS-level zoom and browser chrome are outside the page context.")
   if (requested.networkProfile) options.networkProfiles?.[requested.networkProfile] ? emulated("browser.environment.network-profile", "Latency and throughput are applied through the browser debugging protocol.") : unsupported("browser.environment.network-profile", `Unknown network profile: ${requested.networkProfile}`)
@@ -114,11 +120,22 @@ export async function createPlaywrightBrowserEnvironmentContext(browser: Browser
     ...(environment.forcedColors ? { forcedColors: environment.forcedColors } : {}),
     ...(environment.contrast ? { contrast: environment.contrast } : {}),
     ...(environment.online !== undefined ? { offline: !environment.online } : {}),
+    ...(environment.geolocation ? { geolocation: { latitude: environment.geolocation.latitude, longitude: environment.geolocation.longitude, ...(environment.geolocation.accuracy !== undefined ? { accuracy: environment.geolocation.accuracy } : {}) } } : {}),
+    ...(environment.geolocation?.permission === "granted" ? { permissions: ["geolocation"] } : {}),
   }
   const context = await browser.newContext(contextOptions)
   const page = await context.newPage()
+  const geolocationPermissionCleanup = environment.geolocation?.permission === "denied" ? await applyPlaywrightGeolocationPermission(page, "denied") : undefined
   await applyPlaywrightPageEnvironment(page, environment, options)
-  return { context, page, close: () => context.close() }
+  return { context, page, close: async () => { await geolocationPermissionCleanup?.(); await context.close() } }
+}
+
+export async function applyPlaywrightGeolocationPermission(page: Page, state: "denied"): Promise<() => Promise<void>> {
+  if (page.context().browser()?.browserType().name() !== "chromium") throw new Error("Explicit denied geolocation permission is unsupported by this browser provider.")
+  const session = await page.context().newCDPSession(page)
+  const { targetInfo } = await session.send("Target.getTargetInfo")
+  await session.send("Browser.setPermission", { permission: { name: "geolocation" }, setting: state, browserContextId: targetInfo.browserContextId })
+  return () => session.detach().catch(() => undefined)
 }
 
 export async function applyPlaywrightPageEnvironment(page: Page, environment: BrowserEnvironment, options: PlaywrightBrowserEnvironmentOptions = {}): Promise<void> {