Premium Analytics: Wire Simple bootstrap behind gate

projects/packages/jetpack-mu-wpcom/changelog/wooa7s-1636-premium-analytics-simple

@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+WordPress.com Simple: Add gated Premium Analytics bootstrap wiring.

projects/packages/jetpack-mu-wpcom/composer.json

@@ -19,6 +19,7 @@
 		"automattic/jetpack-google-analytics": "@dev",
 		"automattic/jetpack-masterbar": "@dev",
 		"automattic/jetpack-podcast": "@dev",
+		"automattic/jetpack-premium-analytics": "@dev",
 		"automattic/jetpack-redirect": "@dev",
 		"automattic/jetpack-rtc": "@dev",
 		"automattic/jetpack-stats-admin": "@dev",
@@ -63,7 +64,14 @@
 			"type": "path",
 			"url": "../../packages/*",
 			"options": {
-				"monorepo": true
+				"monorepo": true,
+				"versions": {
+					"automattic/block-delimiter": "dev-trunk",
+					"automattic/jetpack-assets": "dev-trunk",
+					"automattic/jetpack-connection": "dev-trunk",
+					"automattic/jetpack-constants": "dev-trunk",
+					"automattic/jetpack-device-detection": "dev-trunk"
+				}
 			}
 		}
 	],

projects/packages/jetpack-mu-wpcom/src/class-jetpack-mu-wpcom.php

@@ -9,6 +9,8 @@
 
 namespace Automattic\Jetpack;
 
+use Automattic\Jetpack\PremiumAnalytics\Analytics as Premium_Analytics;
+
 define( 'WPCOM_ADMIN_BAR_UNIFICATION', true );
 /**
  * Jetpack_Mu_Wpcom main class.
@@ -64,6 +66,7 @@ public static function init() {
 			add_action( 'plugins_loaded', array( __CLASS__, 'load_verbum_comments' ) );
 			add_action( 'plugins_loaded', array( __CLASS__, 'load_verbum_moderate' ) );
 			add_action( 'wp_loaded', array( __CLASS__, 'load_verbum_comments_admin' ) );
+			add_action( 'plugins_loaded', array( __CLASS__, 'load_wpcom_simple_premium_analytics' ) );
 			add_action( 'admin_menu', array( __CLASS__, 'load_wpcom_simple_odyssey_stats' ) );
 			add_action( 'plugins_loaded', array( __CLASS__, 'load_wpcom_random_redirect' ) );
 			add_action( 'plugins_loaded', array( __CLASS__, 'load_podcast' ) );
@@ -774,6 +777,41 @@ public static function load_wpcom_simple_odyssey_stats() {
 		require_once __DIR__ . '/features/wpcom-simple-odyssey-stats/wpcom-simple-odyssey-stats.php';
 	}
 
+	/**
+	 * Whether Premium Analytics should be loaded on WordPress.com Simple.
+	 *
+	 * @return bool True when the Simple rollout gate is enabled.
+	 */
+	public static function should_load_wpcom_simple_premium_analytics() {
+		$blog_id = (int) get_wpcom_blog_id();
+		$enabled = $blog_id > 0 && wpcom_has_blog_sticker( 'jetpack-premium-analytics', $blog_id );
+
+		/**
+		 * Filters whether Premium Analytics loads on WordPress.com Simple.
+		 *
+		 * @since $$next-version$$
+		 *
+		 * @param bool $enabled Whether the Simple rollout gate is enabled.
+		 * @param int  $blog_id WPCOM blog ID.
+		 */
+		return (bool) apply_filters( 'jetpack_premium_analytics_wpcom_simple_enabled', $enabled, $blog_id );
+	}
+
+	/**
+	 * Load Premium Analytics on WordPress.com Simple sites behind the rollout gate.
+	 */
+	public static function load_wpcom_simple_premium_analytics() {
+		if ( ! self::should_load_wpcom_simple_premium_analytics() ) {
+			return;
+		}
+
+		Premium_Analytics::init_wpcom_simple(
+			array(
+				'menu_title' => 'Premium Analytics',
+			)
+		);
+	}
+
 	/**
 	 * Load the Jetpack Custom CSS feature.
 	 */

projects/packages/jetpack-mu-wpcom/tests/php/features/premium-analytics/Wpcom_Simple_Premium_Analytics_Test.php

@@ -0,0 +1,94 @@
+<?php
+/**
+ * Tests for the WordPress.com Simple Premium Analytics bootstrap gate.
+ *
+ * @package automattic/jetpack-mu-wpcom
+ */
+
+use Automattic\Jetpack\Jetpack_Mu_Wpcom;
+use PHPUnit\Framework\Attributes\PreserveGlobalState;
+use PHPUnit\Framework\Attributes\RunInSeparateProcess;
+
+/**
+ * Tests for Premium Analytics Simple loading.
+ */
+class Wpcom_Simple_Premium_Analytics_Test extends \WorDBless\BaseTestCase {
+
+	/**
+	 * Tear down.
+	 */
+	public function tear_down() {
+		remove_all_filters( 'jetpack_premium_analytics_wpcom_simple_enabled' );
+		\Mockery::close();
+
+		parent::tear_down();
+	}
+
+	/**
+	 * The Simple bootstrap gate is disabled by default.
+	 */
+	public function test_wpcom_simple_premium_analytics_gate_is_off_by_default() {
+		$this->assertFalse( Jetpack_Mu_Wpcom::should_load_wpcom_simple_premium_analytics() );
+	}
+
+	/**
+	 * The Simple bootstrap gate can be enabled for a staged site.
+	 */
+	public function test_wpcom_simple_premium_analytics_gate_can_be_enabled_by_filter() {
+		add_filter( 'jetpack_premium_analytics_wpcom_simple_enabled', '__return_true' );
+
+		$this->assertTrue( Jetpack_Mu_Wpcom::should_load_wpcom_simple_premium_analytics() );
+	}
+
+	/**
+	 * The Simple loader returns before bootstrapping Premium Analytics when gated off.
+	 */
+	public function test_wpcom_simple_premium_analytics_loader_returns_when_gate_is_disabled() {
+		Jetpack_Mu_Wpcom::load_wpcom_simple_premium_analytics();
+
+		$this->assertFalse( class_exists( \Automattic\Jetpack\PremiumAnalytics\Analytics::class, false ) );
+	}
+
+	/**
+	 * The Simple loader boots Premium Analytics when the rollout gate is enabled.
+	 *
+	 * @runInSeparateProcess
+	 * @preserveGlobalState disabled
+	 */
+	#[RunInSeparateProcess]
+	#[PreserveGlobalState( false )]
+	public function test_wpcom_simple_premium_analytics_loader_boots_premium_analytics_when_enabled() {
+		add_filter( 'jetpack_premium_analytics_wpcom_simple_enabled', '__return_true' );
+
+		\Mockery::mock( 'alias:' . \Automattic\Jetpack\PremiumAnalytics\Analytics::class )
+			->shouldReceive( 'init_wpcom_simple' )
+			->once()
+			->with(
+				array(
+					'menu_title' => 'Premium Analytics',
+				)
+			);
+
+		Jetpack_Mu_Wpcom::load_wpcom_simple_premium_analytics();
+
+		$this->addToAssertionCount( 1 );
+	}
+
+	/**
+	 * The Simple bootstrap gate can be enabled by the rollout sticker.
+	 *
+	 * @runInSeparateProcess
+	 * @preserveGlobalState disabled
+	 */
+	#[RunInSeparateProcess]
+	#[PreserveGlobalState( false )]
+	public function test_wpcom_simple_premium_analytics_gate_can_be_enabled_by_sticker() {
+		if ( ! defined( 'IS_WPCOM' ) ) {
+			define( 'IS_WPCOM', true );
+		}
+
+		eval( 'function has_blog_sticker( $sticker, $blog_id ) { return $sticker === "jetpack-premium-analytics" && $blog_id > 0; }' ); // phpcs:ignore Squiz.PHP.Eval.Discouraged,MediaWiki.Usage.ForbiddenFunctions.eval
+
+		$this->assertTrue( Jetpack_Mu_Wpcom::should_load_wpcom_simple_premium_analytics() );
+	}
+}

projects/packages/premium-analytics/AGENTS.md

@@ -101,6 +101,62 @@ routes (`jetpack/v4/stats-app/*`) → `stats` / `jetpack-stats` / `subscribers`
 prefixes; Woo `analytics/reports/*` → `proxy/v2/analytics/reports/*`. The dashboard UI lives in
 `routes/` here, not in Calypso. Frontend helpers go under `packages/data/src/api/`.
 
+## WordPress.com Simple
+
+Simple has no local proxy, notices, sync, or dashboard support routes — WPCOM serves the dashboard
+and reaches `public-api.wordpress.com` directly. `jetpack-mu-wpcom` boots the package via
+`Analytics::init_wpcom_simple()`, behind the `jetpack-premium-analytics` blog sticker.
+
+### Route guards must use the shared site-readiness helpers
+
+Every route's `beforeLoad` that checks connection or sync state must call
+`isPremiumAnalyticsSiteConnected()` / `isPremiumAnalyticsInitialSyncFinished()` from
+`routes/site-readiness.ts` — never read `getScriptData()?.connection?.connectionStatus?.isRegistered`
+or `getScriptData()?.premium_analytics?.initial_full_sync_finished` directly. Simple has no Jetpack
+connection, so a direct read silently evaluates to "not connected" there.
+
+That's more than one broken route: it's a redirect loop. `/connect` and `/syncing` already go
+through the shared helpers and treat Simple as connected and synced, so if a route added later
+skips the helpers, Simple hits that route, gets redirected to `/connect`, and `/connect` — seeing
+Simple as already connected — immediately redirects back to `/`. From the user's side this looks
+like "the page just bounces to the dashboard," with nothing in the console pointing at the cause.
+This shipped once (Automattic/jetpack#50266): the `/reports/$report` route was left reading script
+data directly when the other four routes were migrated to the shared helpers, so it fell out of
+sync with `/connect`'s guard and the two routes bounced traffic between each other on Simple.
+
+Adding a new route with a connection/sync guard: grep `routes/` for
+`isPremiumAnalyticsSiteConnected` first and copy that shape — don't re-derive the check from
+script data.
+
+### Why the dashboard support routes moved from `jetpack/v4` to `wpcom/v2`
+
+The dashboard support routes (widget modules, default layout, sections) used to live under
+`jetpack/v4` — the self-hosted Jetpack plugin's own namespace. WPCOM's REST centralization doesn't
+recognize or expose that namespace for Simple sites, which run no Jetpack plugin at all, so those
+routes were unreachable from public-api. `wpcom/v2` is a namespace WPCOM's centralization already
+treats as site-specific by default for plain function-callback routes: registering under it is
+enough for WPCOM to rewrite and expose the route as `/wpcom/v2/sites/<blog_id>/...` through
+public-api, with no separate dotcom-side registration and no `wpcom_rest_api_v2_load_plugin()`
+class shim required. That's why the rename happened (Automattic/jetpack#50266), and it's why
+`Dashboard_Support_Routes::register()` exists as a standalone entry point WPCOM can call.
+
+### Choosing a REST namespace for new endpoints
+
+**Any future Premium Analytics REST endpoint that needs to work on both connected Jetpack sites
+and WPCOM Simple must register under `wpcom/v2`** (via `DASHBOARD_REST_NAMESPACE` in
+`src/rest-namespace.php`), not `jetpack/v4` or a plugin-specific namespace — those only reach
+connected sites. An endpoint that's intentionally connected-site-only (e.g. the local data proxy,
+notices) can stay under `jetpack-premium-analytics/v1`, since Simple never calls it.
+
+**WPCOM's public-api process calls `Dashboard_Support_Routes::register()` directly**
+(`src/class-dashboard-support-routes.php`) to register the dashboard's REST support routes
+(widget modules, default layout, sections) standalone. The WPCOM-side caller is
+`wp-content/rest-api-plugins/jetpack-endpoints/premium-analytics-dashboard.php` in the `wpcom`
+repo — it `require_once`s this exact file and calls `::register()` by name.
+
+**Renaming, moving, or changing this method's signature requires a matching WPCOM-side update.**
+See Automattic/jetpack#50266 for the PR that established this contract.
+
 ## Pitfalls
 
 - Never put the blog ID in a proxy path — it's injected server-side.

projects/packages/premium-analytics/changelog/wooa7s-1636-wpcom-simple-poc

@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Premium Analytics: Add a gated WordPress.com Simple bootstrap proof of concept.

projects/packages/premium-analytics/composer.json

@@ -46,7 +46,14 @@
 			"type": "path",
 			"url": "../*",
 			"options": {
-				"monorepo": true
+				"monorepo": true,
+				"versions": {
+					"automattic/block-delimiter": "dev-trunk",
+					"automattic/jetpack-assets": "dev-trunk",
+					"automattic/jetpack-connection": "dev-trunk",
+					"automattic/jetpack-constants": "dev-trunk",
+					"automattic/jetpack-device-detection": "dev-trunk"
+				}
 			}
 		}
 	],

projects/packages/premium-analytics/packages/data/package.json

@@ -9,6 +9,7 @@
 	"types": "src/index.ts",
 	"sideEffects": false,
 	"dependencies": {
+		"@automattic/jetpack-script-data": "workspace:*",
 		"@date-fns/tz": "1.4.1",
 		"@jetpack-premium-analytics/datetime": "workspace:*",
 		"@tanstack/react-query": "5.101.2",