@serenity-js/core 3.42.1 → 3.43.0

package/esm/stage/ActorLifecycleManager.js

@@ -0,0 +1,255 @@
+import { ensure, isDefined, property } from 'tiny-types';
+import { ConfigurationError, LogicError, RaiseErrors } from '../errors/index.js';
+import { ActorEntersStage, ActorSpotlighted, } from '../events/index.js';
+import { CorrelationId } from '../model/index.js';
+import { Actor, ScheduleWork } from '../screenplay/index.js';
+/**
+ * Manages the lifecycle of [actors](https://serenity-js.org/api/core/class/Actor/) on the [stage](https://serenity-js.org/api/core/class/Stage/),
+ * including their creation, retrieval, and tracking of which actors are in the foreground (scene-scoped)
+ * versus background (test run-scoped).
+ *
+ * The `ActorLifecycleManager` is responsible for:
+ * - Instantiating and caching actors via the configured [cast](https://serenity-js.org/api/core/class/Cast/)
+ * - Tracking which actor is currently in the spotlight (active)
+ * - Managing the focus area (foreground vs background) where new actors are created
+ * - Providing access to actors for dismissal when scenes or test runs finish
+ *
+ * ## Default behaviour
+ *
+ * By default, actors created before the actual test scenario starts, e.g. in beforeAll hooks, are placed in the `'background'` focus area.
+ * When a [`SceneStarts`](https://serenity-js.org/api/core-events/class/SceneStarts/) event is announced,
+ * the focus switches to `'foreground'`. When a [`SceneFinishes`](https://serenity-js.org/api/core-events/class/SceneFinishes/)
+ * event is announced, foreground actors are dismissed, their abilities [discarded](https://serenity-js.org/api/core/interface/Discardable/)
+ * and focus returns to `'background'`.
+ *
+ * ## Custom lifecycle management
+ *
+ * Test runner adapters like [`@serenity-js/playwright-test`](https://serenity-js.org/api/playwright-test/),
+ * where test execution and reporting happen in separate processes, can inject a custom `ActorLifecycleManager` instance
+ * to control actor lifecycle programmatically.
+ *
+ * ```typescript
+ * const actorLifecycleManager = new ActorLifecycleManager(cast, clock, interactionTimeout);
+ * const serenity = new Serenity(clock, cueTimeout, actorLifecycleManager);
+ *
+ * // At the start of each test:
+ * actorLifecycleManager.switchFocus('foreground');
+ * ```
+ *
+ * ## Learn more
+ * - [`Stage`](https://serenity-js.org/api/core/class/Stage/)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ *
+ * @group Stage
+ */
+export class ActorLifecycleManager {
+    cast;
+    clock;
+    interactionTimeout;
+    /**
+     * The most recent actor referenced via the {@apilink actor} method
+     */
+    currentActor;
+    /**
+     * The scene in which the spotlight was last set.
+     * Used to detect when the spotlight shifts to a different scene context.
+     */
+    currentActorScene = new CorrelationId('unknown');
+    currentFocusValue = 'background';
+    actors = {
+        'foreground': new Map(),
+        'background': new Map(),
+    };
+    stage;
+    constructor(cast, clock, interactionTimeout) {
+        this.cast = cast;
+        this.clock = clock;
+        this.interactionTimeout = interactionTimeout;
+    }
+    /**
+     * Configures the manager with new settings.
+     *
+     * @param options - Configuration options
+     * @param options.interactionTimeout - The maximum time to wait for an interaction to complete
+     */
+    configure({ interactionTimeout }) {
+        this.interactionTimeout = interactionTimeout;
+    }
+    /**
+     * Associates this manager with a [`Stage`](https://serenity-js.org/api/core/class/Stage/) instance.
+     *
+     * This method is called automatically by the `Stage` during construction.
+     * It establishes the bidirectional relationship between the manager and the stage,
+     * allowing the manager to emit [domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
+     * when actors enter the stage or are spotlighted.
+     *
+     * @param stage - The Stage instance to associate with this manager
+     */
+    assignTo(stage) {
+        this.stage = stage;
+    }
+    /**
+     * Configures the manager to use the provided [cast](https://serenity-js.org/api/core/class/Cast/) for preparing actors.
+     *
+     * @param actors - The cast to use for preparing new actors
+     *
+     * @throws [`ConfigurationError`](https://serenity-js.org/api/core/class/ConfigurationError/)
+     *  If the provided cast is not defined or doesn't have a `prepare` method
+     */
+    engage(actors) {
+        this.cast = ensure('actors', actors, isDefined(), property('prepare', isDefined()));
+    }
+    /**
+     * Returns the current [cast](https://serenity-js.org/api/core/class/Cast/) used for preparing actors.
+     *
+     * @returns The currently configured cast
+     */
+    currentCast() {
+        return this.cast;
+    }
+    /**
+     * Instantiates a new [`Actor`](https://serenity-js.org/api/core/class/Actor/) or fetches an existing one
+     * identified by their name if they've already been instantiated.
+     *
+     * When a new actor is instantiated, an [`ActorEntersStage`](https://serenity-js.org/api/core-events/class/ActorEntersStage/)
+     * event is announced. When the spotlight shifts to a different actor (or the same actor in a different scene),
+     * an [`ActorSpotlighted`](https://serenity-js.org/api/core-events/class/ActorSpotlighted/) event is announced.
+     *
+     * Actors are first looked up in the `'background'` focus area, then in `'foreground'`.
+     * New actors are always created in the current focus area.
+     *
+     * @param name - Case-sensitive name of the Actor, e.g. `Alice`
+     * @returns The actor with the given name
+     */
+    actor(name) {
+        if (!this.existingActorCalled(name)) {
+            const actor = this.prepareActor(new Actor(name, this.stage, [
+                new RaiseErrors(this.stage),
+                new ScheduleWork(this.clock, this.interactionTimeout)
+            ]));
+            this.actors[this.currentFocusValue].set(actor.name, actor);
+            this.stage.announce(new ActorEntersStage(this.stage.currentSceneId(), actor.toJSON(), this.stage.currentTime()));
+        }
+        const previousActorInSpotlight = this.currentActor;
+        const previousSceneOfSpotlightedActor = this.currentActorScene;
+        this.currentActor = this.existingActorCalled(name);
+        this.currentActorScene = this.stage.currentSceneId();
+        const spotlightShifted = this.currentActor !== previousActorInSpotlight
+            || !this.stage.currentSceneId().equals(previousSceneOfSpotlightedActor);
+        if (spotlightShifted) {
+            this.stage.announce(new ActorSpotlighted(this.stage.currentSceneId(), this.currentActor.toJSON(), this.stage.currentTime()));
+        }
+        return this.currentActor;
+    }
+    prepareActor(actor) {
+        let preparedActor;
+        try {
+            preparedActor = this.cast.prepare(actor);
+        }
+        catch (error) {
+            throw new ConfigurationError(`${this.typeOf(this.cast)} encountered a problem when preparing actor "${actor.name}" for stage`, error);
+        }
+        if (!(preparedActor instanceof Actor)) {
+            throw new ConfigurationError(`Instead of a new instance of actor "${actor.name}", ${this.typeOf(this.cast)} returned ${preparedActor}`);
+        }
+        return preparedActor;
+    }
+    typeOf(cast) {
+        return cast.constructor === Object
+            ? 'Cast'
+            : cast.constructor.name;
+    }
+    existingActorCalled(name) {
+        return this.actors['background'].has(name)
+            ? this.actors['background'].get(name)
+            : this.actors['foreground'].get(name);
+    }
+    /**
+     * Returns `true` if there is an [`Actor`](https://serenity-js.org/api/core/class/Actor/) in the spotlight, `false` otherwise.
+     *
+     * @returns `true` if an actor is currently spotlighted
+     */
+    hasActorInTheSpotlight() {
+        return Boolean(this.currentActor);
+    }
+    /**
+     * Returns the last [`Actor`](https://serenity-js.org/api/core/class/Actor/) instantiated
+     * via [`actor`](https://serenity-js.org/api/core/class/ActorLifecycleManager/#actor).
+     *
+     * @returns The currently spotlighted actor
+     *
+     * @throws [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
+     *  If no [`Actor`](https://serenity-js.org/api/core/class/Actor/) has been activated yet
+     */
+    actorInTheSpotlight() {
+        if (!this.currentActor) {
+            throw new LogicError(`There is no actor in the spotlight yet. Make sure you instantiate one with stage.actor(actorName) before calling this method.`);
+        }
+        return this.currentActor;
+    }
+    /**
+     * Switches the focus to the specified stage area.
+     *
+     * Actors created after this call will be added to the specified area.
+     * This method is typically called automatically by the [`Stage`](https://serenity-js.org/api/core/class/Stage/)
+     * in response to [`SceneStarts`](https://serenity-js.org/api/core-events/class/SceneStarts/) and
+     * [`SceneFinishes`](https://serenity-js.org/api/core-events/class/SceneFinishes/) events.
+     *
+     * Test runner adapters can also call this method directly to control actor lifecycle
+     * when scene events are not available (e.g., in Playwright Test where the reporter
+     * runs in a separate process).
+     *
+     * @param focus - The focus area to switch to: `'foreground'` for scene-scoped actors,
+     *                `'background'` for test run-scoped actors
+     */
+    switchFocus(focus) {
+        this.currentFocusValue = focus;
+    }
+    /**
+     * Returns the current focus area.
+     *
+     * @returns The current focus: `'foreground'` or `'background'`
+     */
+    currentFocus() {
+        return this.currentFocusValue;
+    }
+    /**
+     * Returns all actors in the specified focus area.
+     *
+     * This method is used by the [`Stage`](https://serenity-js.org/api/core/class/Stage/) to retrieve
+     * actors for dismissal when scenes or test runs finish.
+     *
+     * @param focus - The focus area to retrieve actors from
+     * @returns An array of actors in the specified focus area
+     */
+    actorsIn(focus) {
+        return Array.from(this.actors[focus].values());
+    }
+    /**
+     * Clears the spotlight if the current actor is in the specified focus area.
+     *
+     * This ensures that after actors in a focus area are dismissed, the spotlight
+     * doesn't reference a dismissed actor.
+     *
+     * @param focus - The focus area to check
+     */
+    clearSpotlightIfIn(focus) {
+        const actors = this.actorsIn(focus);
+        if (actors.includes(this.currentActor)) {
+            this.currentActor = undefined;
+        }
+    }
+    /**
+     * Clears all actors from the specified focus area.
+     *
+     * This method is called by the [`Stage`](https://serenity-js.org/api/core/class/Stage/) after
+     * actors have been dismissed to remove them from the internal tracking maps.
+     *
+     * @param focus - The focus area to clear
+     */
+    clearActorsIn(focus) {
+        this.actors[focus].clear();
+    }
+}
+//# sourceMappingURL=ActorLifecycleManager.js.map

package/esm/stage/ActorLifecycleManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorLifecycleManager.js","sourceRoot":"","sources":["../../src/stage/ActorLifecycleManager.ts"],"names":[],"mappings":"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"}

package/esm/stage/Stage.d.ts

@@ -2,9 +2,11 @@ import type { SerenityConfig } from '../config/index.js';
 import { ErrorFactory, type ErrorOptions, type RuntimeError } from '../errors/index.js';
 import { type DomainEvent, type EmitsDomainEvents } from '../events/index.js';
 import { type ActivityDetails, CorrelationId, type CorrelationIdFactory } from '../model/index.js';
-import { Actor, type Clock, type Duration, type Timestamp } from '../screenplay/index.js';
-import type { ListensToDomainEvents } from '../stage/index.js';
+import type { Actor } from '../screenplay/index.js';
+import type { Clock, Duration, Timestamp } from '../screenplay/index.js';
+import { ActorLifecycleManager } from './ActorLifecycleManager.js';
 import type { Cast } from './Cast.js';
+import type { ListensToDomainEvents } from './ListensToDomainEvents.js';
 import type { StageManager } from './StageManager.js';
 /**
  * Stage is the place where [actors](https://serenity-js.org/api/core/class/Actor/) perform.
@@ -23,44 +25,28 @@ import type { StageManager } from './StageManager.js';
  * @group Stage
  */
 export declare class Stage implements EmitsDomainEvents {
-    private cast;
-    private manager;
+    private readonly manager;
     private errors;
     private readonly clock;
-    private interactionTimeout;
     private readonly sceneIdFactory;
     static readonly unknownSceneId: CorrelationId;
-    /**
-     * Actors instantiated after the scene has started,
-     * who will be dismissed when the scene finishes.
-     */
-    private actorsOnFrontStage;
-    /**
-     * Actors instantiated before the scene has started,
-     * who will be dismissed when the test run finishes.
-     */
-    private actorsOnBackstage;
-    private actorsOnStage;
-    /**
-     * The most recent actor referenced via the [`Actor`](https://serenity-js.org/api/core/class/Actor/) method
-     */
-    private actorInTheSpotlight;
-    /**
-     * The scene in which the spotlight was last set.
-     * Used to detect when the spotlight shifts to a different scene context.
-     */
-    private sceneOfSpotlightedActor;
     private currentActivity;
     private currentScene;
+    private readonly actorLifecycleManager;
     /**
-     * @param cast
-     * @param manager
-     * @param errors
-     * @param clock
-     * @param interactionTimeout
-     * @param sceneIdFactory
-     */
-    constructor(cast: Cast, manager: StageManager, errors: ErrorFactory, clock: Clock, interactionTimeout: Duration, sceneIdFactory?: CorrelationIdFactory);
+     * Creates a new Stage instance.
+     *
+     * @param cast - The default cast to use for preparing actors
+     * @param manager - The stage manager responsible for notifying listeners of domain events
+     * @param errors - Factory for creating runtime errors with proper context
+     * @param clock - Clock used for timestamping domain events
+     * @param interactionTimeout - Default timeout for actor interactions
+     * @param sceneIdFactory - Factory for creating scene correlation IDs
+     * @param actorLifecycleManager - Optional custom ActorLifecycleManager instance.
+     *        When provided, allows test runner adapters to control actor lifecycle programmatically.
+     *        If not provided, a default manager is created.
+     */
+    constructor(cast: Cast, manager: StageManager, errors: ErrorFactory, clock: Clock, interactionTimeout: Duration, sceneIdFactory?: CorrelationIdFactory, actorLifecycleManager?: ActorLifecycleManager);
     configure(options: Pick<SerenityConfig, 'actors' | 'cueTimeout' | 'interactionTimeout' | 'diffFormatter'>): void;
     /**
      * An alias for [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor)
@@ -97,7 +83,7 @@ export declare class Stage implements EmitsDomainEvents {
     engage(actors: Cast): void;
     /**
      * Assigns listeners to be notified of [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
-     * emitted via [`Stage.announce`](https://serenity-js.org/api/core/class/Stage/#announce).s
+     * emitted via [`Stage.announce`](https://serenity-js.org/api/core/class/Stage/#announce).
      *
      * @param listeners
      */
@@ -110,6 +96,8 @@ export declare class Stage implements EmitsDomainEvents {
      */
     announce(...events: Array<DomainEvent>): void;
     private announceSingle;
+    private notifyOfStageExit;
+    private dismissActorsIn;
     /**
      * Returns current time. This method should be used whenever
      * [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects are instantiated by you programmatically.
@@ -161,9 +149,5 @@ export declare class Stage implements EmitsDomainEvents {
      */
     waitForNextCue(): Promise<void>;
     createError<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE;
-    private instantiatedActorCalled;
-    private notifyOfStageExit;
-    private dismiss;
-    private typeOf;
 }
 //# sourceMappingURL=Stage.d.ts.map

package/esm/stage/Stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stage.d.ts","sourceRoot":"","sources":["../../src/stage/Stage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Stage.d.ts","sourceRoot":"","sources":["../../src/stage/Stage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EACH,YAAY,EACZ,KAAK,YAAY,EAEjB,KAAK,YAAY,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAKH,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAIzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAQ,MAAM,mBAAmB,CAAC;AACzG,OAAO,KAAK,EAAE,KAAK,EAAC,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAmB,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,KAAM,YAAW,iBAAiB;IAyBvC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,cAAc;IA3BnC,gBAAuB,cAAc,gBAA+B;IAEpE,OAAO,CAAC,eAAe,CAA8D;IAErF,OAAO,CAAC,YAAY,CAAuC;IAE3D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAuB;IAE7D;;;;;;;;;;;;OAYG;gBAEC,IAAI,EAAE,IAAI,EACO,OAAO,EAAE,YAAY,EAC9B,MAAM,EAAE,YAAY,EACX,KAAK,EAAE,KAAK,EAC7B,kBAAkB,EAAE,QAAQ,EACX,cAAc,GAAE,oBAAoC,EACrE,qBAAqB,CAAC,EAAE,qBAAqB;IAajD,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,YAAY,GAAG,oBAAoB,GAAG,eAAe,CAAC,GAAG,IAAI;IAkBhH;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAInC;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAI1B;;;;;;OAMG;IACH,sBAAsB,IAAI,KAAK;IAI/B;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,SAAS,EAAE,qBAAqB,EAAE,GAAG,IAAI;IAInD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI;IAM7C,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,iBAAiB;YAUX,eAAe;IAqC7B;;;OAGG;IACH,WAAW,IAAI,SAAS;IAIxB;;;;;;;;;OASG;IACH,gBAAgB,IAAI,aAAa;IAMjC;;;;;OAKG;IACH,cAAc,IAAI,aAAa;IAI/B;;;;;;;;;OASG;IACH,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,aAAa;IASpE;;;;;OAKG;IACH,iBAAiB,IAAI,aAAa;IAQlC;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,WAAW,CAAC,EAAE,SAAS,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE;CAMzG"}

package/esm/stage/Stage.js

@@ -1,8 +1,8 @@
-import { ensure, isDefined, property } from 'tiny-types';
-import { ConfigurationError, ErrorFactory, LogicError, RaiseErrors } from '../errors/index.js';
-import { ActorEntersStage, ActorSpotlighted, ActorStageExitAttempted, ActorStageExitCompleted, ActorStageExitFailed, ActorStageExitStarts, SceneFinishes, SceneStarts, TestRunFinishes } from '../events/index.js';
+import { ensure, isDefined } from 'tiny-types';
+import { ErrorFactory, LogicError } from '../errors/index.js';
+import { ActorStageExitAttempted, ActorStageExitCompleted, ActorStageExitFailed, ActorStageExitStarts, SceneFinishes, SceneStarts, TestRunFinishes } from '../events/index.js';
 import { CorrelationId, Name } from '../model/index.js';
-import { Actor, ScheduleWork } from '../screenplay/index.js';
+import { ActorLifecycleManager } from './ActorLifecycleManager.js';
 /**
  * Stage is the place where [actors](https://serenity-js.org/api/core/class/Actor/) perform.
  *
@@ -20,49 +20,31 @@ import { Actor, ScheduleWork } from '../screenplay/index.js';
  * @group Stage
  */
 export class Stage {
-    cast;
     manager;
     errors;
     clock;
-    interactionTimeout;
     sceneIdFactory;
     static unknownSceneId = new CorrelationId('unknown');
-    /**
-     * Actors instantiated after the scene has started,
-     * who will be dismissed when the scene finishes.
-     */
-    actorsOnFrontStage = new Map();
-    /**
-     * Actors instantiated before the scene has started,
-     * who will be dismissed when the test run finishes.
-     */
-    actorsOnBackstage = new Map();
-    actorsOnStage = this.actorsOnBackstage;
-    /**
-     * The most recent actor referenced via the [`Actor`](https://serenity-js.org/api/core/class/Actor/) method
-     */
-    actorInTheSpotlight = undefined;
-    /**
-     * The scene in which the spotlight was last set.
-     * Used to detect when the spotlight shifts to a different scene context.
-     */
-    sceneOfSpotlightedActor = undefined;
     currentActivity = undefined;
     currentScene = Stage.unknownSceneId;
+    actorLifecycleManager;
     /**
-     * @param cast
-     * @param manager
-     * @param errors
-     * @param clock
-     * @param interactionTimeout
-     * @param sceneIdFactory
-     */
-    constructor(cast, manager, errors, clock, interactionTimeout, sceneIdFactory = CorrelationId) {
-        this.cast = cast;
+     * Creates a new Stage instance.
+     *
+     * @param cast - The default cast to use for preparing actors
+     * @param manager - The stage manager responsible for notifying listeners of domain events
+     * @param errors - Factory for creating runtime errors with proper context
+     * @param clock - Clock used for timestamping domain events
+     * @param interactionTimeout - Default timeout for actor interactions
+     * @param sceneIdFactory - Factory for creating scene correlation IDs
+     * @param actorLifecycleManager - Optional custom ActorLifecycleManager instance.
+     *        When provided, allows test runner adapters to control actor lifecycle programmatically.
+     *        If not provided, a default manager is created.
+     */
+    constructor(cast, manager, errors, clock, interactionTimeout, sceneIdFactory = CorrelationId, actorLifecycleManager) {
         this.manager = manager;
         this.errors = errors;
         this.clock = clock;
-        this.interactionTimeout = interactionTimeout;
         this.sceneIdFactory = sceneIdFactory;
         ensure('Cast', cast, isDefined());
         ensure('StageManager', manager, isDefined());
@@ -70,11 +52,15 @@ export class Stage {
         ensure('Clock', clock, isDefined());
         ensure('interactionTimeout', interactionTimeout, isDefined());
         ensure('sceneIdFactory', sceneIdFactory, isDefined());
+        this.actorLifecycleManager = actorLifecycleManager ?? new ActorLifecycleManager(cast, this.clock, interactionTimeout);
+        this.actorLifecycleManager.assignTo(this);
     }
     configure(options) {
-        this.interactionTimeout = options.interactionTimeout || this.interactionTimeout;
+        if (options.interactionTimeout) {
+            this.actorLifecycleManager.configure({ interactionTimeout: options.interactionTimeout });
+        }
         if (options.actors) {
-            this.engage(options.actors);
+            this.actorLifecycleManager.engage(options.actors);
         }
         if (options.cueTimeout) {
             this.manager.configure({ cueTimeout: options.cueTimeout });
@@ -99,34 +85,7 @@ export class Stage {
      *  Case-sensitive name of the Actor, e.g. `Alice`
      */
     actor(name) {
-        if (!this.instantiatedActorCalled(name)) {
-            let actor;
-            try {
-                const newActor = new Actor(name, this, [
-                    new RaiseErrors(this),
-                    new ScheduleWork(this.clock, this.interactionTimeout)
-                ]);
-                actor = this.cast.prepare(newActor);
-            }
-            catch (error) {
-                throw new ConfigurationError(`${this.typeOf(this.cast)} encountered a problem when preparing actor "${name}" for stage`, error);
-            }
-            if (!(actor instanceof Actor)) {
-                throw new ConfigurationError(`Instead of a new instance of actor "${name}", ${this.typeOf(this.cast)} returned ${actor}`);
-            }
-            this.actorsOnStage.set(name, actor);
-            this.announce(new ActorEntersStage(this.currentScene, actor.toJSON()));
-        }
-        const previousActorInSpotlight = this.actorInTheSpotlight;
-        const previousSceneOfSpotlightedActor = this.sceneOfSpotlightedActor;
-        this.actorInTheSpotlight = this.instantiatedActorCalled(name);
-        this.sceneOfSpotlightedActor = this.currentScene;
-        const spotlightShifted = this.actorInTheSpotlight !== previousActorInSpotlight
-            || !this.currentScene.equals(previousSceneOfSpotlightedActor);
-        if (spotlightShifted) {
-            this.announce(new ActorSpotlighted(this.currentScene, this.actorInTheSpotlight.toJSON()));
-        }
-        return this.actorInTheSpotlight;
+        return this.actorLifecycleManager.actor(name);
     }
     /**
      * Returns the last [`Actor`](https://serenity-js.org/api/core/class/Actor/) instantiated via [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor).
@@ -136,16 +95,13 @@ export class Stage {
      *  If no [`Actor`](https://serenity-js.org/api/core/class/Actor/) has been activated yet
      */
     theActorInTheSpotlight() {
-        if (!this.actorInTheSpotlight) {
-            throw new LogicError(`There is no actor in the spotlight yet. Make sure you instantiate one with stage.actor(actorName) before calling this method.`);
-        }
-        return this.actorInTheSpotlight;
+        return this.actorLifecycleManager.actorInTheSpotlight();
     }
     /**
      * Returns `true` if there is an [`Actor`](https://serenity-js.org/api/core/class/Actor/) in the spotlight, `false` otherwise.
      */
     theShowHasStarted() {
-        return !!this.actorInTheSpotlight;
+        return this.actorLifecycleManager.hasActorInTheSpotlight();
     }
     /**
      * Configures the Stage to prepare [actors](https://serenity-js.org/api/core/class/Actor/)
@@ -154,11 +110,11 @@ export class Stage {
      * @param actors
      */
     engage(actors) {
-        this.cast = ensure('actors', actors, isDefined(), property('prepare', isDefined()));
+        this.actorLifecycleManager.engage(actors);
     }
     /**
      * Assigns listeners to be notified of [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
-     * emitted via [`Stage.announce`](https://serenity-js.org/api/core/class/Stage/#announce).s
+     * emitted via [`Stage.announce`](https://serenity-js.org/api/core/class/Stage/#announce).
      *
      * @param listeners
      */
@@ -178,26 +134,52 @@ export class Stage {
     }
     announceSingle(event) {
         if (event instanceof SceneStarts) {
-            this.actorsOnStage = this.actorsOnFrontStage;
+            this.actorLifecycleManager.switchFocus('foreground');
         }
         if (event instanceof SceneFinishes || event instanceof TestRunFinishes) {
-            this.notifyOfStageExit(this.currentSceneId());
+            this.notifyOfStageExit(this.actorLifecycleManager.currentFocus());
         }
         this.manager.notifyOf(event);
         if (event instanceof SceneFinishes) {
-            this.dismiss(this.actorsOnStage);
-            this.actorsOnStage = this.actorsOnBackstage;
+            this.dismissActorsIn('foreground');
+            this.actorLifecycleManager.switchFocus('background');
         }
         if (event instanceof TestRunFinishes) {
-            this.dismiss(this.actorsOnStage);
+            this.dismissActorsIn('background');
+        }
+    }
+    notifyOfStageExit(focus) {
+        for (const actor of this.actorLifecycleManager.actorsIn(focus)) {
+            this.announce(new ActorStageExitStarts(this.currentSceneId(), actor.toJSON(), this.currentTime()));
+        }
+    }
+    async dismissActorsIn(focus) {
+        const actors = this.actorLifecycleManager.actorsIn(focus);
+        this.actorLifecycleManager.clearSpotlightIfIn(focus);
+        // Wait for the Photographer to finish taking any screenshots
+        await this.manager.waitForAsyncOperationsToComplete();
+        const actorsToDismiss = new Map(actors.map(actor => [actor, CorrelationId.create()]));
+        for (const [actor, correlationId] of actorsToDismiss) {
+            this.announce(new ActorStageExitAttempted(correlationId, new Name(actor.name), this.currentTime()));
+        }
+        // Try to dismiss each actor
+        for (const [actor, correlationId] of actorsToDismiss) {
+            try {
+                await actor.dismiss();
+                this.announce(new ActorStageExitCompleted(correlationId, new Name(actor.name), this.currentTime()));
+            }
+            catch (error) {
+                this.announce(new ActorStageExitFailed(error, correlationId, this.currentTime()));
+            }
         }
+        this.actorLifecycleManager.clearActorsIn(focus);
     }
     /**
      * Returns current time. This method should be used whenever
      * [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects are instantiated by you programmatically.
      */
     currentTime() {
-        return this.manager.currentTime();
+        return this.clock.now();
     }
     /**
      * Generates and remembers a `CorrelationId`
@@ -268,43 +250,5 @@ export class Stage {
             ...options,
         });
     }
-    instantiatedActorCalled(name) {
-        return this.actorsOnBackstage.has(name)
-            ? this.actorsOnBackstage.get(name)
-            : this.actorsOnFrontStage.get(name);
-    }
-    notifyOfStageExit(sceneId) {
-        for (const actor of this.actorsOnStage.values()) {
-            this.announce(new ActorStageExitStarts(sceneId, actor.toJSON(), this.currentTime()));
-        }
-    }
-    async dismiss(activeActors) {
-        const actors = Array.from(activeActors.values());
-        if (actors.includes(this.actorInTheSpotlight)) {
-            this.actorInTheSpotlight = undefined;
-        }
-        // Wait for the Photographer to finish taking any screenshots
-        await this.manager.waitForAsyncOperationsToComplete();
-        const actorsToDismiss = new Map(actors.map(actor => [actor, CorrelationId.create()]));
-        for (const [actor, correlationId] of actorsToDismiss) {
-            this.announce(new ActorStageExitAttempted(correlationId, new Name(actor.name), this.currentTime()));
-        }
-        // Try to dismiss each actor
-        for (const [actor, correlationId] of actorsToDismiss) {
-            try {
-                await actor.dismiss();
-                this.announce(new ActorStageExitCompleted(correlationId, new Name(actor.name), this.currentTime()));
-            }
-            catch (error) {
-                this.announce(new ActorStageExitFailed(error, correlationId, this.currentTime()));
-            }
-        }
-        activeActors.clear();
-    }
-    typeOf(cast) {
-        return cast.constructor === Object
-            ? 'Cast'
-            : cast.constructor.name;
-    }
 }
 //# sourceMappingURL=Stage.js.map