Admin Settings Screen Implementation

.github/workflows/test.yml

@@ -260,7 +260,6 @@ jobs:
         permissions:
             contents: read
         timeout-minutes: 20
-        if: false  # Temporarily disabled
 
         steps:
             - name: Checkout repository

composer.json

@@ -77,7 +77,7 @@
   "scripts": {
     "format": "phpcbf --standard=phpcs.xml.dist",
     "lint": "phpcs --standard=phpcs.xml.dist",
-    "phpstan": "phpstan analyse --memory-limit=1G",
+    "stan": "phpstan analyse --memory-limit=1G",
     "test": "phpunit --strict-coverage"
   },
   "scripts-descriptions": {

docs/DEVELOPER_GUIDE.md

@@ -71,7 +71,14 @@ ai/
 │       └── Example_Feature/          # Each feature in own directory
 │           ├── Example_Feature.php
 │           └── README.md
-├── admin/                            # Admin interface (planned)
+├── includes/Admin/                   # Admin settings services, controllers, assets
+│   ├── Admin_Settings_Page.php       # Registers WP admin menu/page
+│   ├── Settings_Page_Assets.php      # Enqueues scripts/styles
+│   ├── Settings_Payload_Builder.php  # Serializes registry data
+│   └── Settings/                     # Admin settings sub-namespace
+│       ├── Feature_Toggles.php
+│       ├── Settings_Service.php
+│       └── …
 ├── assets/                           # CSS, JS, images
 ├── docs/                             # Documentation
 │   ├── DEVELOPER_GUIDE.md            # This guide
@@ -140,12 +147,20 @@ class My_Feature extends Abstract_Feature {
 	}
 
 	/**
-	 * Registers the feature's hooks and functionality.
+	 * Registers hooks that should always run.
 	 *
 	 * @since 0.1.0
 	 */
-	public function register(): void {
-		// Register your hooks here
+	protected function register_shared_hooks(): void {
+		// Admin settings or dependency checks go here.
+	}
+
+	/**
+	 * Registers hooks that only run when the feature is enabled.
+	 *
+	 * @since 0.1.0
+	 */
+	protected function register_enabled_hooks(): void {
 		add_action( 'init', array( $this, 'initialize' ) );
 		add_filter( 'the_content', array( $this, 'filter_content' ) );
 	}
@@ -176,19 +191,25 @@ class My_Feature extends Abstract_Feature {
 
 ### Step 3: Register the Feature
 
-Add your feature class name to the default features list in `Feature_Loader::get_default_features()`:
+Add your feature to the default list returned by `Feature_Loader::get_default_features()`:
 
 ```php
 private function get_default_features(): array {
-	$feature_classes = array(
-		'WordPress\AI\Features\Example_Feature\Example_Feature',
-		'WordPress\AI\Features\My_Feature\My_Feature', // Add your feature
+	$feature_toggles_provider = apply_filters( 'ai_feature_toggles_service', null );
+	$feature_toggles          = $feature_toggles_provider instanceof Feature_Toggles ? $feature_toggles_provider : null;
+	$feature_toggles_factory  = $this->resolve_feature_toggles_factory( $feature_toggles_provider );
+
+	$features = array(
+		new \WordPress\AI\Features\Example_Feature\Example_Feature( $feature_toggles, $feature_toggles_factory ),
+		new \WordPress\AI\Features\My_Feature\My_Feature( $feature_toggles, $feature_toggles_factory ),
 	);
 
-	// ... rest of the method
+	return apply_filters( 'ai_default_features', $features, $feature_toggles, $feature_toggles_factory );
 }
 ```
 
+Third-party developers should prefer the `ai_register_features` or `ai_default_features` hooks described later in this guide so core files don’t need to be modified.
+
 ### Step 4: Add Feature Documentation
 
 Create a `README.md` in your feature directory:
@@ -213,6 +234,81 @@ Examples of how to use the feature.
 Any settings or filters available.
 ```
 
+## Admin Settings Architecture
+
+The admin settings screen allows site administrators to manage AI Experiments globally and per feature. The PHP services live under `includes/Admin/` and the React application under `src/`.
+
+```
+includes/
+├── Admin/
+│   ├── Admin_Settings_Page.php          # Registers the options page and fallback markup
+│   ├── Settings_Page_Assets.php         # Enqueues the React bundle when viewing the page
+│   ├── Settings_Payload_Builder.php     # Builds the data passed to the React app
+│   └── Settings/
+│       ├── Feature_Toggles.php          # Persists per-feature enable/disable state
+│       ├── Settings_Renderer.php        # Renders the fallback UI for the toggle section
+│       ├── Settings_Registry.php        # Registry of settings sections registered by features
+│       ├── Settings_Section.php         # Immutable value object describing a section
+│       ├── Settings_Service.php         # Coordinates registration of toggles, sections, and page
+│       └── Settings_Toggle.php          # Manages the global experiments option
+└── Features/
+    └── Traits/
+        └── Provides_Settings_Section.php # Helper trait for feature-owned sections
+
+src/
+├── admin/
+│   └── settings/
+│       ├── app.tsx                      # Top-level settings UI
+│       └── components/
+│           ├── feature-section.tsx      # Card UI for per-feature toggles
+│           └── toggle-section.tsx       # Card UI for the global toggle
+├── global.d.ts                          # Ambient declaration for the payload on window
+├── index.tsx                            # React entry point mounted on the admin page
+├── style.scss                           # Styles for the settings screen
+└── types.ts                             # Shared payload types
+```
+
+`includes/bootstrap.php` wires the settings services on the `init` hook via `initialize_admin_settings()`. That function:
+
+1. Instantiates the toggle, registry, renderer, payload builder, page assets handler, and admin page controller.
+2. Registers the shared `Feature_Toggles` service on the `ai_feature_toggles_service` filter. The filter may return an instantiated service, a callable factory, or a `class-string<Feature_Toggles>`, allowing features to resolve the dependency only when they actually need it.
+3. Calls `Settings_Service::register()` to hook the global toggle option, expose REST fields, register the admin menu, and trigger section registration with `ai_register_settings_sections`.
+
+Feature settings panels should be registered inside the `ai_register_settings_sections` hook. The `Provides_Settings_Section` trait streamlines the process:
+
+```php
+class Example_Feature extends Abstract_Feature {
+	use Provides_Settings_Section;
+
+	protected function register_shared_hooks(): void {
+		add_action( 'ai_register_settings_sections', array( $this, 'register_settings_sections' ) );
+	}
+
+	protected function register_enabled_hooks(): void {
+		// Register functional hooks only when enabled.
+	}
+
+	public function register_settings_sections( Settings_Registry $registry ): void {
+		$this->register_feature_settings_section(
+			$registry,
+			'example-feature',
+			__( 'Example Feature', 'ai' ),
+			array( $this, 'render_settings_section' ),
+			array(
+				'description' => __( 'Demonstration controls for the example feature.', 'ai' ),
+				'priority'    => 20,
+			)
+		);
+	}
+
+	public function render_settings_section( Settings_Toggle $toggle, Settings_Section $section ): void {
+		// Output fallback markup when JavaScript is unavailable.
+	}
+}
+```
+
+`Settings_Payload_Builder` serializes the registry into a payload consumed by the React app. Each section’s `enabled` state reflects persisted data from `Feature_Toggles`, ensuring the UI mirrors stored values immediately.
+
 ### Conditional Features
 
 If your feature has requirements (PHP extensions, other plugins, etc.), implement validation in your constructor:
@@ -251,21 +347,24 @@ add_action( 'ai_register_features', function( $registry ) {
 
 ### Filtering Default Features
 
-Modify the list of default feature classes before they are instantiated:
+Modify the list of default feature instances before they are registered:
 
 ```php
-add_filter( 'ai_default_feature_classes', function( $feature_classes ) {
+add_filter( 'ai_default_features', function( $features, $feature_toggles, $feature_toggles_factory ) {
 	// Add a custom feature
-	$feature_classes[] = 'My_Namespace\My_Custom_Feature';
-
-	// Remove a default feature
-	$key = array_search( 'WordPress\AI\Features\Example_Feature\Example_Feature', $feature_classes );
-	if ( false !== $key ) {
-		unset( $feature_classes[ $key ] );
-	}
+	$features[] = new My_Namespace\My_Custom_Feature(
+		$feature_toggles,
+		$feature_toggles_factory
+	);
 
-	return $feature_classes;
-} );
+	// Remove the bundled Example Feature
+	return array_filter(
+		$features,
+		static function ( $feature ) {
+			return ! $feature instanceof WordPress\AI\Features\Example_Feature\Example_Feature;
+		}
+	);
+}, 10, 3 );
 ```
 
 ### Disabling a Feature
@@ -371,4 +470,4 @@ GPL-2.0-or-later
 
 ---
 
-<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
+<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>