♻️ refactor(RegionBuilder): Add onEnter callback for initial state after all handlers are registered.

Author: Biont

specs/core/region.yaml

@@ -93,6 +93,10 @@ features:
         intent: Ensures entry-triggered events execute synchronously within the same lifecycle, maintaining predictable state progression during transitions
         test: vendor/bin/phpunit tests/PHPUnit/Unit/Core/Region/ImmediateCascadeProcessingTest.php
 
+      - acceptanceCriteria: Region fires onEnter callback when entering initial state during construction
+        intent: Ensures initialization logic executes for the starting state by triggering onEnter callbacks during region instantiation, enabling consistent state setup regardless of whether states are entered via transition or initial construction
+        test: vendor/bin/phpunit tests/PHPUnit/Unit/Core/Region/InitialStateBootstrapTest.php
+        
   - name: path-generation
     description: Hierarchical path representation for state machines
     specs:

src/RegionBuilder.php

@@ -307,7 +307,14 @@ public function build(Mesh|iterable|null $featureArgs = null, ?bool $skipMiddlew
             $builder = $enhance->call(new BuildParams($this, $featureArgs));
         }
 
-        return $this->buildChain->withProvider($provider)->call($builder);
+        $region = $this->buildChain->withProvider($provider)->call($builder);
+        
+        // Fire onEnter callback for initial state after all handlers are registered
+        //TODO This should be done on the first trigger, not after building
+        $events = $this->chainMail->get(Events::class);
+        $events->onEnterState($region, $region->currentState(), new \stdClass());
+        
+        return $region;
     }
 
     protected function assertValidConfig(): void

tests/PHPUnit/Unit/Core/Region/InitialStateBootstrapTest.php

@@ -0,0 +1,110 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Noem\State\Tests\Unit\Core\Region;
+
+use Noem\State\RegionBuilder;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+use stdClass;
+
+/**
+ * Acceptance Criterion: Region fires onEnter callback when entering initial state during construction
+ */
+#[Group('region')]
+#[Group('event-lifecycle')]
+class InitialStateBootstrapTest extends TestCase
+{
+    public function testOnEnterCalledForInitialState(): void
+    {
+        $enterCalled = false;
+        $enteredState = null;
+        
+        $region = (new RegionBuilder())
+            ->setStates('initial', 'next', 'final')
+            ->markInitial('initial')
+            ->onEnter('initial', function(object $t) use (&$enterCalled, &$enteredState) {
+                $enterCalled = true;
+                $enteredState = 'initial';
+            })
+            ->build();
+        
+        // onEnter callback should have been called during construction
+        $this->assertTrue($enterCalled, 'onEnter callback must fire when region enters initial state');
+        $this->assertEquals('initial', $enteredState, 'Callback should receive initial state');
+    }
+    
+    public function testOnEnterNotCalledForNonInitialStates(): void
+    {
+        $nextEnterCalled = false;
+        $finalEnterCalled = false;
+        
+        $region = (new RegionBuilder())
+            ->setStates('initial', 'next', 'final')
+            ->markInitial('initial')
+            ->onEnter('next', function(object $t) use (&$nextEnterCalled) {
+                $nextEnterCalled = true;
+            })
+            ->onEnter('final', function(object $t) use (&$finalEnterCalled) {
+                $finalEnterCalled = true;
+            })
+            ->build();
+        
+        // Only initial state onEnter should fire during construction
+        $this->assertFalse($nextEnterCalled, 'onEnter for non-initial states should not fire during construction');
+        $this->assertFalse($finalEnterCalled, 'onEnter for non-initial states should not fire during construction');
+    }
+    
+    public function testOnEnterReceivesProperContext(): void
+    {
+        $receivedRegion = null;
+        $receivedTrigger = null;
+        
+        $region = (new RegionBuilder())
+            ->setStates('start')
+            ->onEnter('start', function(object $t) use (&$receivedTrigger) {
+                $receivedTrigger = $t;
+            })
+            ->build();
+        
+        // The trigger should be an empty stdClass or similar for bootstrap
+        $this->assertIsObject($receivedTrigger, 'onEnter callback should receive trigger object during bootstrap');
+    }
+    
+    public function testMultipleOnEnterCallbacksCalledForInitialState(): void
+    {
+        $firstCalled = false;
+        $secondCalled = false;
+        
+        $region = (new RegionBuilder())
+            ->setStates('initial')
+            ->onEnter('initial', function(object $t) use (&$firstCalled) {
+                $firstCalled = true;
+            })
+            ->onEnter('initial', function(object $t) use (&$secondCalled) {
+                $secondCalled = true;
+            })
+            ->build();
+        
+        $this->assertTrue($firstCalled, 'First onEnter callback must fire during bootstrap');
+        $this->assertTrue($secondCalled, 'Second onEnter callback must fire during bootstrap');
+    }
+    
+    public function testOnEnterCalledBeforeRegionIsUsable(): void
+    {
+        $callbackExecuted = false;
+
+        $region = (new RegionBuilder())
+            ->setStates('initial', 'next')
+            ->markInitial('initial')
+            ->onEnter('initial', function(object $t) use (&$callbackExecuted) {
+                // Callback should execute during build
+                $callbackExecuted = true;
+            })
+            ->build();
+
+        $this->assertTrue($callbackExecuted, 'onEnter callback should execute during build');
+        $this->assertEquals('initial', $region->currentState(), 'Region should be in initial state after construction');
+    }
+}