@hawsen-the-first/interactiv 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { Logger } from "./utils/logger";
 import { useAnimations, AnimationManager } from "./src/animationBus";
 import { configureLogger } from "./src/logger";
 import { GarbageCollector, createGarbageCollector, type GarbageCollectionStats } from "./src/garbageCollector";
-export { createOrchestrator, EventOrchestrator, EventBus, AppBuilder, Page, View, Component, NavigationManager, ScreensaverManager, SettingsManager, EventManager, AnimationManager, stateManager, getGlobalState, setGlobalState, subscribeToGlobalState, useGlobalStateExternal, useAnimations, ExternalStateManager, ComponentStateManager, GarbageCollector, createGarbageCollector, css, html, Logger, configureLogger, };
-export type { PointerEventData, DragCallbacks, HoverCallbacks, SwipeCallbacks, StateSubscription, ScreensaverConfig, SettingsConfig, PageProps, ViewProps, ComponentProps, GarbageCollectionStats, };
+import { TransitionOverlay, transitionWithOverlay, type TransitionOverlayConfig, type TransitionRequestPayload } from "./src/transitionOverlay";
+export { createOrchestrator, EventOrchestrator, EventBus, AppBuilder, Page, View, Component, NavigationManager, ScreensaverManager, SettingsManager, EventManager, AnimationManager, stateManager, getGlobalState, setGlobalState, subscribeToGlobalState, useGlobalStateExternal, useAnimations, ExternalStateManager, ComponentStateManager, GarbageCollector, createGarbageCollector, TransitionOverlay, transitionWithOverlay, css, html, Logger, configureLogger, };
+export type { PointerEventData, DragCallbacks, HoverCallbacks, SwipeCallbacks, StateSubscription, ScreensaverConfig, SettingsConfig, PageProps, ViewProps, ComponentProps, GarbageCollectionStats, TransitionOverlayConfig, TransitionRequestPayload, };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAEhB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EAErB,gBAAgB,EAChB,sBAAsB,EACtB,GAAG,EACH,IAAI,EACJ,MAAM,EACN,eAAe,GAChB,CAAC;AAEF,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,SAAS,EACT,cAAc,EACd,sBAAsB,GACvB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAEhB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EAErB,gBAAgB,EAChB,sBAAsB,EAEtB,iBAAiB,EACjB,qBAAqB,EACrB,GAAG,EACH,IAAI,EACJ,MAAM,EACN,eAAe,GAChB,CAAC;AAEF,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,SAAS,EACT,cAAc,EACd,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,CAAC"}

package/dist/index.js

@@ -10,12 +10,15 @@ import { Logger } from "./utils/logger";
 import { useAnimations, AnimationManager } from "./src/animationBus";
 import { configureLogger } from "./src/logger";
 import { GarbageCollector, createGarbageCollector, } from "./src/garbageCollector";
+import { TransitionOverlay, transitionWithOverlay, } from "./src/transitionOverlay";
 5;
 export { createOrchestrator, EventOrchestrator, EventBus, AppBuilder, Page, View, Component, NavigationManager, ScreensaverManager, SettingsManager, EventManager, AnimationManager, 
 // External State Management
 stateManager, getGlobalState, setGlobalState, subscribeToGlobalState, useGlobalStateExternal, useAnimations, ExternalStateManager, ComponentStateManager, 
 // Garbage Collection
-GarbageCollector, createGarbageCollector, css, html, Logger, configureLogger, };
+GarbageCollector, createGarbageCollector, 
+// Transition Overlay System
+TransitionOverlay, transitionWithOverlay, css, html, Logger, configureLogger, };
 // Named exports for direct import
 // export {
 //   stateManager,

package/dist/src/appBuilder.d.ts

@@ -5,6 +5,7 @@ import { EventManager } from "./eventManager";
 import { ComponentStateManager } from "./stateManager";
 import type { PointerEventData, DragCallbacks, HoverCallbacks, SwipeCallbacks } from "./eventManager";
 import type { RenderOptions } from "./types";
+import { TransitionOverlay, type TransitionOverlayConfig } from "./transitionOverlay";
 declare abstract class RenderableComponent {
     componentId: string;
     state: any;
@@ -139,11 +140,42 @@ declare class AppBuilder extends RenderableComponent {
 }
 declare class Page extends RenderableComponent {
     private views;
+    private transitionOverlay;
+    private transitionBus;
     constructor(id: string, orchestrator: EventOrchestrator, bubbleChanges?: boolean, customTemplate?: string, customStyles?: string);
     protected defineTemplate(): void;
     protected defineStyles(): void;
     addView(view: View): void;
     removeView(viewId: string): void;
+    /**
+     * Enable transition overlay for this page
+     *
+     * Creates a full-screen overlay that fades in/out to hide content changes during state updates.
+     * Once enabled, components can request transitions via the "page-transition-overlay" event bus.
+     *
+     * @param config - Configuration for the overlay appearance and timing
+     */
+    useTransitionOverlay(config: TransitionOverlayConfig): void;
+    /**
+     * Execute a callback wrapped in the transition overlay lifecycle
+     *
+     * This is a convenience method for direct Page-level access to the overlay.
+     * For deeply nested components, prefer using the standalone `transitionWithOverlay` utility
+     * or emitting to the "page-transition-overlay" event bus.
+     *
+     * @param callback - Function to execute while overlay is opaque (state changes happen here)
+     * @returns Promise that resolves after the full transition completes
+     * @throws Error if useTransitionOverlay() hasn't been called
+     */
+    transitionWithOverlay(callback: () => void | Promise<void>): Promise<void>;
+    /**
+     * Check if this page has a transition overlay enabled
+     */
+    hasTransitionOverlay(): boolean;
+    /**
+     * Get the TransitionOverlay instance for this page (for NavigationManager integration)
+     */
+    getTransitionOverlay(): TransitionOverlay | null;
     /**
      * Add a screensaver page with the specified configuration.
      * Pass `null` for screensaverPage when using `screensaverViewBehavior: "returnHome"` mode,

package/dist/src/appBuilder.d.ts.map

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

package/dist/src/appBuilder.js

@@ -6,6 +6,7 @@ import { SettingsManager } from "./settingsManager";
 import { EventManager } from "./eventManager";
 import { ComponentStateManager } from "./stateManager";
 import { logger } from "./logger";
+import { TransitionOverlay, stateChangesToCallback, } from "./transitionOverlay";
 class RenderableComponent {
     componentId;
     state;
@@ -538,6 +539,8 @@ class AppBuilder extends RenderableComponent {
 // Page - Contains Views
 class Page extends RenderableComponent {
     views = [];
+    transitionOverlay = null;
+    transitionBus = null;
     constructor(id, orchestrator, bubbleChanges = true, customTemplate, customStyles) {
         super(id, orchestrator, bubbleChanges);
         // Set custom template/styles before initial render if provided
@@ -647,6 +650,96 @@ class Page extends RenderableComponent {
             this.removeChild(viewId);
         }
     }
+    /**
+     * Enable transition overlay for this page
+     *
+     * Creates a full-screen overlay that fades in/out to hide content changes during state updates.
+     * Once enabled, components can request transitions via the "page-transition-overlay" event bus.
+     *
+     * @param config - Configuration for the overlay appearance and timing
+     */
+    useTransitionOverlay(config) {
+        if (this.transitionOverlay) {
+            logger.warn(`Page ${this.componentId} already has a transition overlay configured`);
+            return;
+        }
+        // Create the transition overlay
+        this.transitionOverlay = new TransitionOverlay(config, this.shadowRoot);
+        // Register the event bus for transition requests
+        this.transitionBus = this.orchestrator.registerEventBus("page-transition-overlay");
+        // Listen for transition requests
+        this.transitionBus.on("request-transition", async (e) => {
+            const payload = e.detail;
+            try {
+                // Build the callback from state changes or use provided callback
+                let callback;
+                if (payload.callback) {
+                    // Direct callback provided (from standalone utility)
+                    callback = payload.callback;
+                }
+                else if (payload.stateChanges) {
+                    // State changes array provided (from consumer usage)
+                    callback = async () => {
+                        stateChangesToCallback(payload.stateChanges)();
+                        // Execute afterStateChange if provided
+                        if (payload.afterStateChange) {
+                            await Promise.resolve(payload.afterStateChange());
+                        }
+                    };
+                }
+                else {
+                    throw new Error("Transition request must include either 'callback' or 'stateChanges'");
+                }
+                // Execute the transition with config overrides
+                await this.transitionOverlay.executeTransition(callback, {
+                    fadeInDuration: payload.fadeInDuration,
+                    holdDuration: payload.holdDuration,
+                    fadeOutDuration: payload.fadeOutDuration,
+                });
+                // Resolve the promise if provided (from standalone utility)
+                if (payload._resolve) {
+                    payload._resolve();
+                }
+            }
+            catch (error) {
+                logger.error("Transition overlay error:", error);
+                // Reject the promise if provided (from standalone utility)
+                if (payload._reject) {
+                    payload._reject(error);
+                }
+            }
+        });
+        logger.trace(`Transition overlay enabled for page ${this.componentId}`);
+    }
+    /**
+     * Execute a callback wrapped in the transition overlay lifecycle
+     *
+     * This is a convenience method for direct Page-level access to the overlay.
+     * For deeply nested components, prefer using the standalone `transitionWithOverlay` utility
+     * or emitting to the "page-transition-overlay" event bus.
+     *
+     * @param callback - Function to execute while overlay is opaque (state changes happen here)
+     * @returns Promise that resolves after the full transition completes
+     * @throws Error if useTransitionOverlay() hasn't been called
+     */
+    async transitionWithOverlay(callback) {
+        if (!this.transitionOverlay) {
+            throw new Error(`Page ${this.componentId} does not have a transition overlay. Call useTransitionOverlay() first.`);
+        }
+        return this.transitionOverlay.executeTransition(callback);
+    }
+    /**
+     * Check if this page has a transition overlay enabled
+     */
+    hasTransitionOverlay() {
+        return this.transitionOverlay !== null;
+    }
+    /**
+     * Get the TransitionOverlay instance for this page (for NavigationManager integration)
+     */
+    getTransitionOverlay() {
+        return this.transitionOverlay;
+    }
     /**
      * Add a screensaver page with the specified configuration.
      * Pass `null` for screensaverPage when using `screensaverViewBehavior: "returnHome"` mode,

package/dist/src/eventBus.d.ts

@@ -18,8 +18,7 @@ export declare class EventBus<DetailType = any> {
      * Destroy this event bus and clean up all listeners
      */
     destroy(): void;
-    emit(type: string, detail?: DetailType): boolean | undefined;
-    private validateEventDispatch;
+    emit(type: string, detail?: DetailType): boolean;
 }
 export declare class EventOrchestrator {
     private eventBuses;

package/dist/src/eventBus.d.ts.map

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

package/dist/src/eventBus.js

@@ -86,24 +86,12 @@ export class EventBus {
         log.trace(`Event Bus ${this.id} destroyed`);
     }
     emit(type, detail) {
-        try {
-            this.validateEventDispatch(type);
-            return this.eventTarget.dispatchEvent(new CustomEvent(type, { detail }));
-        }
-        catch (error) {
-            log.error(error.message, error);
-        }
-    }
-    // private validateNewListener(type: string): void {
-    //   // Allow multiple listeners for the same event type
-    //   // This validation is too restrictive for our use case
-    //   // Components may need to register multiple listeners for the same event
-    //   return;
-    // }
-    validateEventDispatch(type) {
+        // Check if there are any listeners before dispatching
         if (this.activeListeners.filter((l) => l.eventName === type).length === 0) {
-            throw new Error(`Failed to dispatch event. Event Bus with Id ${this.id} does not contain a listener for an event with the name ${type}`);
+            log.trace(`Event Bus [${this.id}]: No listeners registered for event "${type}", skipping dispatch.`);
+            return true; // Return true to indicate the event was "handled" (just not dispatched)
         }
+        return this.eventTarget.dispatchEvent(new CustomEvent(type, { detail }));
     }
 }
 export class EventOrchestrator {

package/dist/src/navigationManager.d.ts

@@ -66,6 +66,10 @@ export declare class NavigationManager {
     private performPageNavigationInternal;
     private performViewNavigationInternal;
     private performPageTransition;
+    /**
+     * Perform an immediate view swap (no animation) - used when transition overlay is handling the fade
+     */
+    private performViewSwapImmediate;
     private performViewTransition;
     private animateOut;
     private animateIn;

package/dist/src/navigationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigationManager.d.ts","sourceRoot":"","sources":["../../src/navigationManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC9D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IACzD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAkB;IAE5C,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,wBAAwB,CAA2C;IAE3E;;;OAGG;WACW,WAAW,IAAI,iBAAiB,GAAG,IAAI;gBAIzC,YAAY,EAAE,iBAAiB;IA4B3C,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,mBAAmB;IAsBpB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAa9B,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQrC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,kBAAkB;IAMb,cAAc,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,gBAAmC,EAC3C,QAAQ,GAAE,MAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAYH,cAAc,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,gBAAmC,EAC3C,QAAQ,GAAE,MAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC;YAYF,6BAA6B;YA6B7B,6BAA6B;YAgC7B,qBAAqB;YAmBrB,qBAAqB;YAqBrB,UAAU;YAuEV,SAAS;IA2FvB,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,qBAAqB;IAwB7B,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,YAAY;IAQb,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC,eAAe,IAAI,OAAO;IAI1B,kBAAkB,IAAI,MAAM,EAAE;IAI9B,kBAAkB,IAAI,MAAM,EAAE;IAK9B,sBAAsB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,iBAAiB;IAIpF,sBAAsB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,iBAAiB;IAIpF,0BAA0B,CAAC,QAAQ,EAAE,CAAC,eAAe,EAAE,OAAO,KAAK,IAAI,GAAG,iBAAiB;IAIlG;;;OAGG;IACI,0BAA0B,IAAI,IAAI;IAezC;;OAEG;IACI,wBAAwB,IAAI,MAAM;IAIzC;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;CAoBvB"}
+{"version":3,"file":"navigationManager.d.ts","sourceRoot":"","sources":["../../src/navigationManager.ts"],"names":[],"mappings":"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"}

package/dist/src/navigationManager.js

@@ -181,13 +181,35 @@ export class NavigationManager {
         log.trace(`Starting navigation from ${previousViewId} to ${viewId}`);
         stateManager.set("navigation.isTransitioning", true);
         try {
-            await this.performViewTransition(viewId, config);
-            stateManager.set("navigation.currentViewId", viewId);
-            this.eventBus.emit("view-changed", {
-                newViewId: viewId,
-                previousViewId,
-            });
-            log.trace(`Navigation to ${viewId} completed successfully`);
+            // Check if current page has a transition overlay
+            const currentPageId = stateManager.get("navigation.currentPageId");
+            const currentPage = currentPageId ? this.pages.get(currentPageId) : null;
+            const hasOverlay = currentPage && currentPage.hasTransitionOverlay();
+            if (hasOverlay) {
+                // Use the overlay to wrap the view transition
+                log.trace(`Using transition overlay for view navigation to ${viewId}`);
+                const overlay = currentPage.getTransitionOverlay();
+                await overlay.executeTransition(async () => {
+                    // Perform the view swap while overlay is opaque
+                    await this.performViewSwapImmediate(viewId, previousViewId);
+                    stateManager.set("navigation.currentViewId", viewId);
+                });
+                this.eventBus.emit("view-changed", {
+                    newViewId: viewId,
+                    previousViewId,
+                });
+                log.trace(`Navigation to ${viewId} completed successfully with overlay`);
+            }
+            else {
+                // No overlay - use standard transition
+                await this.performViewTransition(viewId, config);
+                stateManager.set("navigation.currentViewId", viewId);
+                this.eventBus.emit("view-changed", {
+                    newViewId: viewId,
+                    previousViewId,
+                });
+                log.trace(`Navigation to ${viewId} completed successfully`);
+            }
         }
         catch (error) {
             log.error(`Navigation to ${viewId} failed:`, error);
@@ -211,6 +233,23 @@ export class NavigationManager {
         }
         await this.animateIn(targetPage.getHostElement(), normalizedConfig);
     }
+    /**
+     * Perform an immediate view swap (no animation) - used when transition overlay is handling the fade
+     */
+    async performViewSwapImmediate(targetViewId, currentViewId) {
+        const currentView = currentViewId ? this.views.get(currentViewId) : null;
+        const targetView = this.views.get(targetViewId);
+        // Hide current view immediately
+        if (currentView) {
+            this.hideView(currentViewId);
+        }
+        // Show target view immediately (no animation since overlay handles the fade)
+        this.showView(targetViewId, false);
+        const element = targetView.getHostElement();
+        element.style.opacity = "1";
+        element.style.visibility = "visible";
+        element.style.transform = "none";
+    }
     async performViewTransition(targetViewId, config) {
         const currentViewId = stateManager.get("navigation.currentViewId");
         const currentView = currentViewId ? this.views.get(currentViewId) : null;

package/dist/src/screensaverManager.d.ts

@@ -32,7 +32,10 @@ export declare class ScreensaverManager {
     private lastScreensaverViewId;
     private lastActivityResetTime;
     private globalListeners;
+    private interactionShieldActive;
+    private shieldRemovalTimer;
     private readonly DEBOUNCE_INTERVAL;
+    private readonly SHIELD_DURATION;
     private readonly DEFAULT_ACTIVITY_EVENTS;
     constructor(orchestrator: EventOrchestrator, navigationManager: NavigationManager);
     private initializeGlobalState;
@@ -69,5 +72,15 @@ export declare class ScreensaverManager {
     private checkAndPerformReboot;
     private startRebootCheckInterval;
     private stopRebootCheckInterval;
+    /**
+     * Activates the interaction shield to block follow-up events from the same gesture
+     * that dismissed the screensaver. This prevents touch events from bleeding through
+     * to elements on the home page.
+     */
+    private activateInteractionShield;
+    /**
+     * Deactivates the interaction shield, allowing normal event processing to resume.
+     */
+    private deactivateInteractionShield;
 }
 //# sourceMappingURL=screensaverManager.d.ts.map

package/dist/src/screensaverManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screensaverManager.d.ts","sourceRoot":"","sources":["../../src/screensaverManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM/E,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,mBAAmB,CAAkB;IAC7C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,eAAe,CAIf;IAGR,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAG1C,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAStC;gBAEU,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB;IASjF,OAAO,CAAC,qBAAqB;IAkB7B,OAAO,CAAC,mBAAmB;IAyCpB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAyC3D,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;IAkCtB,OAAO,CAAC,4BAA4B;IAmDpC,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,kBAAkB;YAOZ,mBAAmB;IA6DjC;;;;OAIG;YACW,kBAAkB;IAkDhC,OAAO,CAAC,wBAAwB;YAclB,qBAAqB;YAmDrB,qBAAqB;IAI5B,QAAQ,IAAI,OAAO;IAInB,gBAAgB,IAAI,iBAAiB,GAAG,IAAI;IAI5C,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC,wBAAwB,IAAI,MAAM,GAAG,IAAI;IAKzC,aAAa,IAAI,IAAI;IAKrB,eAAe,IAAI,IAAI;IAIvB,UAAU,IAAI,IAAI;IAMzB,OAAO,CAAC,OAAO;IAcR,OAAO,IAAI,IAAI;IAUtB,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,uBAAuB;CAOhC"}
+{"version":3,"file":"screensaverManager.d.ts","sourceRoot":"","sources":["../../src/screensaverManager.ts"],"names":[],"mappings":"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"}

package/dist/src/screensaverManager.js

@@ -14,8 +14,13 @@ export class ScreensaverManager {
     lastScreensaverViewId = null;
     lastActivityResetTime = null;
     globalListeners = [];
+    // Interaction shield state
+    interactionShieldActive = false;
+    shieldRemovalTimer = null;
     // Debounce interval for activity timer resets (in milliseconds)
     DEBOUNCE_INTERVAL = 1000;
+    // Shield duration to block follow-up events from the same gesture (in milliseconds)
+    SHIELD_DURATION = 400;
     // Default activity events to monitor
     DEFAULT_ACTIVITY_EVENTS = [
         "mousemove",
@@ -156,6 +161,13 @@ export class ScreensaverManager {
         if (!this.config)
             return;
         const activityHandler = (event) => {
+            // Block all events if interaction shield is active
+            if (this.interactionShieldActive) {
+                event.stopPropagation();
+                event.preventDefault();
+                log.trace(`Interaction shield blocked ${event.type} event`);
+                return;
+            }
             // Check if event should be ignored based on excludeSelectors
             if (this.shouldIgnoreActivity(event)) {
                 return;
@@ -174,9 +186,14 @@ export class ScreensaverManager {
             }
         };
         // Add listeners to document for global coverage
+        // Use non-passive listeners for click and touch events to allow preventDefault()
         this.config.activityEvents.forEach((eventType) => {
             const listener = activityHandler.bind(this);
-            document.addEventListener(eventType, listener, { passive: true });
+            const usePassive = !["click", "touchstart", "touchend"].includes(eventType);
+            document.addEventListener(eventType, listener, {
+                passive: usePassive,
+                capture: true // Use capture phase to intercept events before they reach targets
+            });
             this.globalListeners.push({
                 element: document,
                 type: eventType,
@@ -356,6 +373,8 @@ export class ScreensaverManager {
         if (!this.config || !this.isScreensaverActive)
             return;
         log.trace(`Exiting screensaver with '${this.config.exitBehavior}' behavior`);
+        // Activate interaction shield to block follow-up events from the same gesture
+        this.activateInteractionShield();
         // Stop the reboot check interval
         this.stopRebootCheckInterval();
         if (this.config.deactivateCallback)
@@ -432,6 +451,7 @@ export class ScreensaverManager {
     cleanup() {
         this.clearActivityTimer();
         this.stopRebootCheckInterval();
+        this.deactivateInteractionShield();
         // Remove all global event listeners
         this.globalListeners.forEach(({ element, type, listener }) => {
             element.removeEventListener(type, listener);
@@ -490,4 +510,34 @@ export class ScreensaverManager {
             log.trace("Reboot check interval stopped");
         }
     }
+    // Interaction shield methods
+    /**
+     * Activates the interaction shield to block follow-up events from the same gesture
+     * that dismissed the screensaver. This prevents touch events from bleeding through
+     * to elements on the home page.
+     */
+    activateInteractionShield() {
+        // Clear any existing shield timer
+        if (this.shieldRemovalTimer !== null) {
+            clearTimeout(this.shieldRemovalTimer);
+            this.shieldRemovalTimer = null;
+        }
+        this.interactionShieldActive = true;
+        log.trace("Interaction shield activated");
+        // Automatically deactivate shield after the gesture completes
+        this.shieldRemovalTimer = window.setTimeout(() => {
+            this.deactivateInteractionShield();
+        }, this.SHIELD_DURATION);
+    }
+    /**
+     * Deactivates the interaction shield, allowing normal event processing to resume.
+     */
+    deactivateInteractionShield() {
+        if (this.shieldRemovalTimer !== null) {
+            clearTimeout(this.shieldRemovalTimer);
+            this.shieldRemovalTimer = null;
+        }
+        this.interactionShieldActive = false;
+        log.trace("Interaction shield deactivated");
+    }
 }

package/dist/src/transitionOverlay.d.ts

@@ -0,0 +1,96 @@
+import { EventOrchestrator } from "./eventBus";
+export interface TransitionOverlayConfig {
+    backgroundColor?: string;
+    fadeInDuration?: number;
+    holdDuration?: number;
+    fadeOutDuration?: number;
+    zIndex?: number;
+}
+export interface TransitionRequestPayload {
+    stateChanges?: Array<{
+        key: string;
+        value: any;
+    }>;
+    afterStateChange?: () => void | Promise<void>;
+    fadeInDuration?: number;
+    holdDuration?: number;
+    fadeOutDuration?: number;
+}
+type TransitionPhase = "idle" | "fade-in" | "hold" | "fade-out";
+/**
+ * TransitionOverlay - Manages visual overlay transitions for seamless content updates
+ *
+ * This class provides a fade-to-opaque overlay that hides content changes during state updates.
+ *
+ * **Concurrency Strategy:**
+ * - If a transition is in the **fade-in or hold phase**, incoming requests queue their callbacks
+ *   to be batched into the current cycle's hold phase
+ * - If a transition is in the **fade-out phase**, incoming requests start a new transition cycle
+ *   after the current one completes
+ *
+ * This ensures smooth transitions without jarring interruptions or visible content changes.
+ */
+export declare class TransitionOverlay {
+    private config;
+    private shadowRoot;
+    private overlayElement;
+    private currentPhase;
+    private queuedCallbacks;
+    private queuedRequests;
+    private activeTransitionPromise;
+    constructor(config: TransitionOverlayConfig, shadowRoot: ShadowRoot);
+    private injectOverlayElement;
+    /**
+     * Execute a transition with the overlay lifecycle
+     *
+     * @param callback - Function to execute while overlay is opaque (state changes happen here)
+     * @param configOverrides - Optional per-request config overrides
+     * @returns Promise that resolves after the full transition completes
+     */
+    executeTransition(callback: () => void | Promise<void>, configOverrides?: Partial<TransitionOverlayConfig>): Promise<void>;
+    private handleConcurrentRequest;
+    private performTransition;
+    private fadeIn;
+    private executeCallbacks;
+    private fadeOut;
+    private processQueuedRequests;
+    /**
+     * Update the overlay configuration
+     */
+    updateConfig(config: Partial<TransitionOverlayConfig>): void;
+    /**
+     * Get the current transition phase
+     */
+    getPhase(): TransitionPhase;
+    /**
+     * Check if a transition is currently active
+     */
+    isTransitioning(): boolean;
+    /**
+     * Clean up the overlay element and resources
+     */
+    destroy(): void;
+}
+/**
+ * Standalone utility for requesting overlay transitions via event bus
+ *
+ * This is the recommended way for components to request transitions, as it:
+ * 1. Works from anywhere in the component tree
+ * 2. Gracefully falls back to direct execution if no overlay is available
+ * 3. Supports state changes via the standardized event format
+ *
+ * @param orchestrator - The EventOrchestrator instance
+ * @param callback - Function to execute during the transition (while overlay is opaque)
+ * @param config - Optional per-request config overrides
+ * @returns Promise that resolves after the transition completes
+ */
+export declare function transitionWithOverlay(orchestrator: EventOrchestrator, callback: () => void | Promise<void>, config?: Partial<TransitionOverlayConfig>): Promise<void>;
+/**
+ * Helper to convert state changes array to callback function
+ */
+export declare function stateChangesToCallback(stateChanges: Array<{
+    key: string;
+    value: any;
+}>): () => void;
+export {};
+//# sourceMappingURL=transitionOverlay.d.ts.map

package/dist/src/transitionOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitionOverlay.d.ts","sourceRoot":"","sources":["../../src/transitionOverlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAM/C,MAAM,WAAW,uBAAuB;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAClD,gBAAgB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AASD,KAAK,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,uBAAuB,CAA8B;gBAEjD,MAAM,EAAE,uBAAuB,EAAE,UAAU,EAAE,UAAU;IAYnE,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;OAMG;IACU,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACpC,eAAe,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GACjD,OAAO,CAAC,IAAI,CAAC;IAiBhB,OAAO,CAAC,uBAAuB;YAwBjB,iBAAiB;IAmC/B,OAAO,CAAC,MAAM;YAoDA,gBAAgB;IAsB9B,OAAO,CAAC,OAAO;IAmDf,OAAO,CAAC,qBAAqB;IAW7B;;OAEG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,IAAI;IAgBnE;;OAEG;IACI,QAAQ,IAAI,eAAe;IAIlC;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;OAEG;IACI,OAAO,IAAI,IAAI;CAUvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,iBAAiB,EAC/B,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACpC,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,CAAC,GAC/C,MAAM,IAAI,CAMZ"}

package/dist/src/transitionOverlay.js

@@ -0,0 +1,328 @@
+import { setGlobalState } from "./stateManager";
+import { logger } from "./logger";
+const log = logger;
+/**
+ * TransitionOverlay - Manages visual overlay transitions for seamless content updates
+ *
+ * This class provides a fade-to-opaque overlay that hides content changes during state updates.
+ *
+ * **Concurrency Strategy:**
+ * - If a transition is in the **fade-in or hold phase**, incoming requests queue their callbacks
+ *   to be batched into the current cycle's hold phase
+ * - If a transition is in the **fade-out phase**, incoming requests start a new transition cycle
+ *   after the current one completes
+ *
+ * This ensures smooth transitions without jarring interruptions or visible content changes.
+ */
+export class TransitionOverlay {
+    config;
+    shadowRoot;
+    overlayElement = null;
+    currentPhase = "idle";
+    queuedCallbacks = [];
+    queuedRequests = [];
+    activeTransitionPromise = null;
+    constructor(config, shadowRoot) {
+        this.config = {
+            backgroundColor: config.backgroundColor ?? "#000",
+            fadeInDuration: config.fadeInDuration ?? 200,
+            holdDuration: config.holdDuration ?? 100,
+            fadeOutDuration: config.fadeOutDuration ?? 200,
+            zIndex: config.zIndex ?? 100,
+        };
+        this.shadowRoot = shadowRoot;
+        this.injectOverlayElement();
+    }
+    injectOverlayElement() {
+        this.overlayElement = document.createElement("div");
+        this.overlayElement.className = "transition-overlay";
+        this.overlayElement.style.cssText = `
+      position: absolute;
+      inset: 0;
+      background-color: ${this.config.backgroundColor};
+      opacity: 0;
+      pointer-events: none;
+      z-index: ${this.config.zIndex};
+      will-change: opacity;
+      transition: opacity ${this.config.fadeInDuration}ms ease-in-out;
+    `;
+        // Append to the shadow root or to .page if it exists
+        const pageElement = this.shadowRoot.querySelector(".page");
+        const container = pageElement || this.shadowRoot;
+        // Ensure the container has relative positioning for absolute overlay
+        if (container instanceof HTMLElement) {
+            const currentPosition = window.getComputedStyle(container).position;
+            if (currentPosition === "static") {
+                container.style.position = "relative";
+            }
+        }
+        container.appendChild(this.overlayElement);
+        log.trace("TransitionOverlay element injected into shadow DOM");
+    }
+    /**
+     * Execute a transition with the overlay lifecycle
+     *
+     * @param callback - Function to execute while overlay is opaque (state changes happen here)
+     * @param configOverrides - Optional per-request config overrides
+     * @returns Promise that resolves after the full transition completes
+     */
+    async executeTransition(callback, configOverrides) {
+        // Merge config overrides
+        const effectiveConfig = {
+            ...this.config,
+            ...configOverrides,
+        };
+        // Handle concurrency
+        if (this.currentPhase !== "idle") {
+            return this.handleConcurrentRequest(callback, effectiveConfig);
+        }
+        // Start new transition
+        this.activeTransitionPromise = this.performTransition(callback, effectiveConfig);
+        return this.activeTransitionPromise;
+    }
+    handleConcurrentRequest(callback, config) {
+        return new Promise((resolve, reject) => {
+            // If we're in fade-in or hold, batch this callback into the current cycle
+            if (this.currentPhase === "fade-in" || this.currentPhase === "hold") {
+                log.trace("Batching callback into current transition cycle", {
+                    currentPhase: this.currentPhase
+                });
+                this.queuedCallbacks.push(callback);
+                // Resolve when the current transition completes
+                this.activeTransitionPromise?.then(resolve).catch(reject);
+            }
+            // If we're in fade-out, queue for the next cycle
+            else if (this.currentPhase === "fade-out") {
+                log.trace("Queueing request for next transition cycle", {
+                    currentPhase: this.currentPhase
+                });
+                this.queuedRequests.push({ callback, config, resolve, reject });
+            }
+        });
+    }
+    async performTransition(callback, config) {
+        if (!this.overlayElement) {
+            throw new Error("Overlay element not initialized");
+        }
+        try {
+            // Phase 1: Fade in
+            this.currentPhase = "fade-in";
+            await this.fadeIn(config.fadeInDuration);
+            // Phase 2: Hold & execute callbacks
+            this.currentPhase = "hold";
+            await this.executeCallbacks(callback, config.holdDuration);
+            // Phase 3: Fade out
+            this.currentPhase = "fade-out";
+            await this.fadeOut(config.fadeOutDuration);
+            // Back to idle
+            this.currentPhase = "idle";
+            // Process any queued requests
+            this.processQueuedRequests();
+        }
+        catch (error) {
+            log.error("Transition error:", error);
+            this.currentPhase = "idle";
+            this.queuedCallbacks = [];
+            throw error;
+        }
+    }
+    fadeIn(duration) {
+        if (!this.overlayElement)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const element = this.overlayElement;
+            // Update transition duration
+            element.style.transition = `opacity ${duration}ms ease-in-out`;
+            // Enable pointer events to block interaction
+            element.style.pointerEvents = "all";
+            let transitionEndFired = false;
+            let fallbackTimerId = null;
+            const cleanup = () => {
+                if (transitionEndFired)
+                    return;
+                transitionEndFired = true;
+                element.removeEventListener("transitionend", transitionEndHandler);
+                if (fallbackTimerId !== null) {
+                    clearTimeout(fallbackTimerId);
+                    fallbackTimerId = null;
+                }
+                log.trace("Overlay fade-in complete");
+                resolve();
+            };
+            const transitionEndHandler = (e) => {
+                // Only respond to opacity transitions on this element
+                if (e.target === element && e.propertyName === "opacity") {
+                    cleanup();
+                }
+            };
+            element.addEventListener("transitionend", transitionEndHandler);
+            // Trigger fade-in by setting opacity to 1
+            // Use requestAnimationFrame to ensure CSS transition is applied
+            requestAnimationFrame(() => {
+                element.style.opacity = "1";
+            });
+            // Fallback timeout
+            fallbackTimerId = window.setTimeout(() => {
+                log.trace("Overlay fade-in fallback timeout triggered");
+                cleanup();
+            }, duration + 50);
+        });
+    }
+    async executeCallbacks(callback, holdDuration) {
+        // Execute the main callback
+        await Promise.resolve(callback());
+        // Execute any batched callbacks
+        if (this.queuedCallbacks.length > 0) {
+            log.trace(`Executing ${this.queuedCallbacks.length} batched callbacks`);
+            for (const queuedCallback of this.queuedCallbacks) {
+                await Promise.resolve(queuedCallback());
+            }
+            this.queuedCallbacks = [];
+        }
+        // Hold duration
+        if (holdDuration > 0) {
+            await new Promise(resolve => setTimeout(resolve, holdDuration));
+        }
+    }
+    fadeOut(duration) {
+        if (!this.overlayElement)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const element = this.overlayElement;
+            // Update transition duration
+            element.style.transition = `opacity ${duration}ms ease-in-out`;
+            let transitionEndFired = false;
+            let fallbackTimerId = null;
+            const cleanup = () => {
+                if (transitionEndFired)
+                    return;
+                transitionEndFired = true;
+                element.removeEventListener("transitionend", transitionEndHandler);
+                if (fallbackTimerId !== null) {
+                    clearTimeout(fallbackTimerId);
+                    fallbackTimerId = null;
+                }
+                // Disable pointer events after fade-out
+                element.style.pointerEvents = "none";
+                log.trace("Overlay fade-out complete");
+                resolve();
+            };
+            const transitionEndHandler = (e) => {
+                // Only respond to opacity transitions on this element
+                if (e.target === element && e.propertyName === "opacity") {
+                    cleanup();
+                }
+            };
+            element.addEventListener("transitionend", transitionEndHandler);
+            // Trigger fade-out by setting opacity to 0
+            requestAnimationFrame(() => {
+                element.style.opacity = "0";
+            });
+            // Fallback timeout
+            fallbackTimerId = window.setTimeout(() => {
+                log.trace("Overlay fade-out fallback timeout triggered");
+                cleanup();
+            }, duration + 50);
+        });
+    }
+    processQueuedRequests() {
+        if (this.queuedRequests.length > 0) {
+            log.trace(`Processing ${this.queuedRequests.length} queued transition requests`);
+            const request = this.queuedRequests.shift();
+            this.performTransition(request.callback, request.config)
+                .then(request.resolve)
+                .catch(request.reject);
+        }
+    }
+    /**
+     * Update the overlay configuration
+     */
+    updateConfig(config) {
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+        if (this.overlayElement) {
+            if (config.backgroundColor) {
+                this.overlayElement.style.backgroundColor = config.backgroundColor;
+            }
+            if (config.zIndex !== undefined) {
+                this.overlayElement.style.zIndex = String(config.zIndex);
+            }
+        }
+    }
+    /**
+     * Get the current transition phase
+     */
+    getPhase() {
+        return this.currentPhase;
+    }
+    /**
+     * Check if a transition is currently active
+     */
+    isTransitioning() {
+        return this.currentPhase !== "idle";
+    }
+    /**
+     * Clean up the overlay element and resources
+     */
+    destroy() {
+        if (this.overlayElement && this.overlayElement.parentNode) {
+            this.overlayElement.parentNode.removeChild(this.overlayElement);
+        }
+        this.overlayElement = null;
+        this.queuedCallbacks = [];
+        this.queuedRequests = [];
+        this.currentPhase = "idle";
+        log.trace("TransitionOverlay destroyed");
+    }
+}
+/**
+ * Standalone utility for requesting overlay transitions via event bus
+ *
+ * This is the recommended way for components to request transitions, as it:
+ * 1. Works from anywhere in the component tree
+ * 2. Gracefully falls back to direct execution if no overlay is available
+ * 3. Supports state changes via the standardized event format
+ *
+ * @param orchestrator - The EventOrchestrator instance
+ * @param callback - Function to execute during the transition (while overlay is opaque)
+ * @param config - Optional per-request config overrides
+ * @returns Promise that resolves after the transition completes
+ */
+export async function transitionWithOverlay(orchestrator, callback, config) {
+    const transitionBus = orchestrator.getEventBus("page-transition-overlay");
+    if (transitionBus) {
+        // Wrap in a promise that resolves when the transition completes
+        return new Promise((resolve, reject) => {
+            try {
+                transitionBus.emit("request-transition", {
+                    callback,
+                    ...config,
+                    _resolve: resolve,
+                    _reject: reject,
+                });
+            }
+            catch (error) {
+                // If the emit fails (no listeners), fall back to direct execution
+                log.warn("No transition overlay available, executing callback directly");
+                Promise.resolve(callback()).then(resolve).catch(reject);
+            }
+        });
+    }
+    else {
+        // Fallback: no overlay available, execute directly
+        log.trace("No transition overlay bus found, executing callback directly");
+        await Promise.resolve(callback());
+    }
+}
+/**
+ * Helper to convert state changes array to callback function
+ */
+export function stateChangesToCallback(stateChanges) {
+    return () => {
+        stateChanges.forEach(({ key, value }) => {
+            setGlobalState(key, value);
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawsen-the-first/interactiv",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A TypeScript framework for building interactive applications with event management, state management, navigation, and screensaver functionality",
   "main": "./dist/index.js",
   "module": "./dist/index.js",