feat: Add local WordPress environment powered by wp-env

.gitignore

@@ -200,5 +200,10 @@ src/translations/
 e2e/test-results/
 playwright-report/
 
+# wp-env
+.wp-env.credentials.json
+wp-env/mu-plugins/*
+!wp-env/mu-plugins/gutenbergkit-cors.php
+
 # Claude
 .claude/settings.local.json

.wp-env.json

@@ -0,0 +1,13 @@
+{
+	"plugins": [
+		"https://downloads.wordpress.org/plugin/gutenberg.zip",
+		"https://downloads.wordpress.org/plugin/jetpack.zip"
+	],
+	"mappings": {
+		"wp-content/mu-plugins": "./wp-env/mu-plugins"
+	},
+	"config": {
+		"WP_DEBUG": true,
+		"WP_DEBUG_LOG": true
+	}
+}

AGENTS.md

@@ -96,6 +96,29 @@ make local-android-library
 make test-android
 ```
 
+### Local WordPress Environment (wp-env)
+
+A local WordPress environment powered by `@wordpress/env` for testing the full editor experience with theme styles, media uploads, and plugin block assets.
+
+```bash
+# Start the local WordPress environment (requires Docker)
+make wp-env-start
+
+# Stop the environment (preserves data)
+make wp-env-stop
+
+# Destroy the environment and remove all data
+make wp-env-clean
+
+# View WordPress logs
+make wp-env-logs
+
+# Run a WP-CLI command
+make wp-env-cli CMD="post list"
+```
+
+See `docs/code/local-wordpress.md` for detailed setup instructions and troubleshooting.
+
 > **Note:** Most `make` targets have equivalent `npm` scripts in `package.json`. Build targets accept `REFRESH_DEPS=1`, `REFRESH_L10N=1`, and `REFRESH_JS_BUILD=1` flags to force refresh of dependencies, translations, and JavaScript builds respectively. Run `make help` for full details.
 
 ## Architecture

Makefile

@@ -135,6 +135,32 @@ dev-tools: npm-dependencies ## Start the React Developer Tools
 preview: npm-dependencies ## Preview the production build locally
 	npm run preview
 
+################################################################################
+# Local WordPress Environment Targets (wp-env)
+################################################################################
+
+.PHONY: wp-env-start
+wp-env-start: npm-dependencies ## Start the local WordPress environment (requires Docker; RESET=1 to regenerate credentials)
+	npm run wp-env start
+	@RESET=$(RESET) bash bin/wp-env-setup.sh
+
+.PHONY: wp-env-stop
+wp-env-stop: ## Stop the local WordPress environment
+	npm run wp-env stop
+
+.PHONY: wp-env-clean
+wp-env-clean: ## Stop wp-env and remove all data (fresh start)
+	npm run wp-env destroy
+	@rm -f .wp-env.credentials.json
+
+.PHONY: wp-env-logs
+wp-env-logs: ## Show wp-env WordPress logs
+	npm run wp-env logs
+
+.PHONY: wp-env-cli
+wp-env-cli: ## Run a WP-CLI command in wp-env (usage: make wp-env-cli CMD="post list")
+	npm run wp-env run cli wp $(CMD)
+
 ################################################################################
 # Code Quality Targets
 ################################################################################

android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt

@@ -42,7 +42,8 @@ import org.wordpress.gutenberg.model.GBKitGlobal
 import org.wordpress.gutenberg.services.EditorService
 import java.util.Locale
 
-const val ASSET_URL = "https://appassets.androidplatform.net/assets/index.html"
+private const val ASSET_URL = "https://appassets.androidplatform.net/assets/index.html"
+private const val ASSET_URL_HTTP = "http://appassets.androidplatform.net/assets/index.html"
 
 /**
  * A WebView-based Gutenberg block editor for Android.
@@ -85,9 +86,7 @@ const val ASSET_URL = "https://appassets.androidplatform.net/assets/index.html"
 class GutenbergView : WebView {
     private var isEditorLoaded = false
     private var didFireEditorLoaded = false
-    private var assetLoader = WebViewAssetLoader.Builder()
-        .addPathHandler("/assets/", AssetsPathHandler(this.context))
-        .build()
+    private lateinit var assetLoader: WebViewAssetLoader
     private val configuration: EditorConfiguration
     private lateinit var dependencies: EditorDependencies
 
@@ -268,7 +267,7 @@ class GutenbergView : WebView {
                 }
 
                 // Allow asset URLs
-                if (url.host == Uri.parse(ASSET_URL).host) {
+                if (url.host == "appassets.androidplatform.net") {
                     return false
                 }
 
@@ -392,19 +391,31 @@ class GutenbergView : WebView {
             configuration.cachedAssetHosts
         )
 
+        // Build the asset loader. When the site is a local dev server over HTTP,
+        // serve assets over HTTP too so that Android WebView doesn't block site
+        // resources as mixed content. Only allow this for known local hosts to
+        // avoid accidentally downgrading asset traffic for production sites.
+        val siteUri = Uri.parse(configuration.siteURL)
+        val isLocalHttpSite = siteUri.scheme == "http" && siteUri.host in LOCAL_HOSTS
+        assetLoader = WebViewAssetLoader.Builder()
+            .setHttpAllowed(isLocalHttpSite)
+            .addPathHandler("/assets/", AssetsPathHandler(this.context))
+            .build()
+
         // Notify that dependency loading is complete (spinner phase begins)
         loadingListener?.onDependencyLoadingFinished()
 
         initializeWebView()
 
+        val assetUrl = if (isLocalHttpSite) ASSET_URL_HTTP else ASSET_URL
         val editorUrl = BuildConfig.GUTENBERG_EDITOR_URL.ifEmpty {
-            ASSET_URL
+            assetUrl
         }
 
         WebStorage.getInstance().deleteAllData()
         this.clearCache(true)
         // All cookies are third-party cookies because the root of this document
-        // lives under `https://appassets.androidplatform.net`
+        // lives under `appassets.androidplatform.net`
         CookieManager.getInstance().setAcceptThirdPartyCookies(this, true)
 
         // Erase all local cookies before loading the URL – we don't want to persist
@@ -870,6 +881,9 @@ class GutenbergView : WebView {
     }
 
     companion object {
+        /** Hosts that are safe to serve assets over HTTP (local development only). */
+        private val LOCAL_HOSTS = setOf("localhost", "127.0.0.1", "10.0.2.2")
+
         private const val ASSET_LOADING_TIMEOUT_MS = 5000L
 
         // Warmup state management

android/Gutenberg/src/main/java/org/wordpress/gutenberg/model/EditorAssetBundle.kt

@@ -117,6 +117,10 @@ data class EditorAssetBundle(
      * @return `true` if the asset has been cached locally.
      */
     fun hasAssetData(url: String): Boolean {
+        if(this == empty) {
+            return false
+        }
+
         return assetDataPath(url).exists()
     }
 

android/app/build.gradle.kts

@@ -4,6 +4,22 @@ plugins {
     alias(libs.plugins.jetbrains.kotlin.compose)
 }
 
+// Read wp-env credentials at build time. The emulator cannot access host
+// filesystem paths at runtime, so we bake the values into BuildConfig.
+@Suppress("UNCHECKED_CAST")
+val wpEnvCredentials: Map<String, String> = run {
+    val file = rootProject.file("../.wp-env.credentials.json")
+    if (file.exists()) {
+        try {
+            groovy.json.JsonSlurper().parseText(file.readText()) as Map<String, String>
+        } catch (_: Exception) {
+            emptyMap()
+        }
+    } else {
+        emptyMap()
+    }
+}
+
 android {
     namespace = "com.example.gutenbergkit"
     compileSdk = 34
@@ -16,6 +32,10 @@ android {
         versionName = "1.0"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        buildConfigField("String", "WP_ENV_SITE_URL", "\"${wpEnvCredentials["siteUrl"] ?: ""}\"")
+        buildConfigField("String", "WP_ENV_SITE_API_ROOT", "\"${wpEnvCredentials["siteApiRoot"] ?: ""}\"")
+        buildConfigField("String", "WP_ENV_AUTH_HEADER", "\"${wpEnvCredentials["authHeader"] ?: ""}\"")
     }
 
     buildTypes {
@@ -36,6 +56,7 @@ android {
     }
     buildFeatures {
         compose = true
+        buildConfig = true
     }
 }
 

android/app/src/main/java/com/example/gutenbergkit/ConfigurationAdapter.kt

@@ -27,6 +27,13 @@ class ConfigurationAdapter(
                 holder.subtitleText.visibility = View.VISIBLE
             }
 
+            is ConfigurationItem.LocalWordPress -> {
+                holder.titleText.text = holder.itemView.context.getString(R.string.local_wordpress)
+                holder.subtitleText.text =
+                    holder.itemView.context.getString(R.string.local_wordpress_subtitle)
+                holder.subtitleText.visibility = View.VISIBLE
+            }
+
             is ConfigurationItem.ConfiguredEditor -> {
                 holder.titleText.text = item.name
                 holder.subtitleText.text = item.siteUrl

android/app/src/main/java/com/example/gutenbergkit/ConfigurationItem.kt

@@ -2,6 +2,7 @@ package com.example.gutenbergkit
 
 sealed class ConfigurationItem {
     object BundledEditor : ConfigurationItem()
+    object LocalWordPress : ConfigurationItem()
     data class ConfiguredEditor(
         val name: String,
         val siteUrl: String,

android/app/src/main/java/com/example/gutenbergkit/LocalWordPressCredentials.kt

@@ -0,0 +1,28 @@
+package com.example.gutenbergkit
+
+data class LocalWordPressCredentials(
+    val siteUrl: String,
+    val siteApiRoot: String,
+    val authHeader: String
+) {
+    companion object {
+        /**
+         * Loads credentials from BuildConfig fields populated at build time from
+         * `.wp-env.credentials.json`. Remaps `localhost` to `10.0.2.2` so the
+         * Android emulator can reach the host machine.
+         */
+        fun load(): LocalWordPressCredentials? {
+            val siteUrl = BuildConfig.WP_ENV_SITE_URL
+            if (siteUrl.isEmpty()) return null
+
+            return LocalWordPressCredentials(
+                siteUrl = remapLocalhost(siteUrl),
+                siteApiRoot = remapLocalhost(BuildConfig.WP_ENV_SITE_API_ROOT),
+                authHeader = BuildConfig.WP_ENV_AUTH_HEADER
+            )
+        }
+
+        private fun remapLocalhost(url: String): String =
+            url.replace("://localhost", "://10.0.2.2")
+    }
+}