@hawsen-the-first/interactiv 0.0.1 → 0.0.3

package/README.md

@@ -253,6 +253,65 @@ eventManager.drag(".draggable", {
 });
 ```
 
+### Screensaver Manager
+
+The screensaver manager monitors user activity and triggers actions after a configurable timeout period. It supports two modes:
+
+#### Standard Screensaver Mode
+
+Navigate to a dedicated screensaver page after inactivity. User activity exits the screensaver and returns to the previous or starting page.
+
+```typescript
+// Create a screensaver page with views
+const screensaverPage = new Page("screensaver-page", orchestrator, false);
+const screensaverView = new View("screensaver-view", orchestrator, false, 
+  html`<div class="screensaver">...</div>`,
+  css`.screensaver { /* styles */ }`
+);
+screensaverPage.addView(screensaverView);
+
+// Add screensaver with standard behavior
+app.addScreensaver(screensaverPage, {
+  timeoutSeconds: 30,
+  defaultViewId: "screensaver-view",
+  exitBehavior: "return",       // Return to where the user was before
+  transitionConfig: { type: "fade", duration: 500 },
+});
+```
+
+#### Return-to-Home Mode
+
+Instead of showing a screensaver, navigate back to a specified home page/view after inactivity. No screensaver page is needed — the app simply redirects to the home screen. The screensaver never enters an "active" state, so user activity just resets the inactivity timer.
+
+```typescript
+// No screensaver page needed — pass null
+app.addScreensaver(null, {
+  timeoutSeconds: 60,
+  screensaverViewBehavior: "returnHome",
+  startingPageId: "home-page",    // The home page to navigate to
+  defaultViewId: "home-view",     // Optional: the home view to show
+  transitionConfig: { type: "fade", duration: 500 },
+});
+```
+
+#### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeoutSeconds` | `number` | Seconds of inactivity before activation |
+| `page` | `Page` | Screensaver page (required unless using `returnHome`) |
+| `screensaverViewBehavior` | `"default" \| "specific" \| "return" \| "returnHome"` | How to handle the view on activation |
+| `defaultViewId` | `string` | Default view to show (or home view for `returnHome`) |
+| `exitBehavior` | `"reset" \| "return"` | Where to go when exiting the screensaver |
+| `startingPageId` | `string` | Page to navigate to on exit/reset (or home page for `returnHome`) |
+| `startingViewId` | `string` | View within the starting page on exit |
+| `transitionConfig` | `TransitionConfig` | Transition animation configuration |
+| `activateCallback` | `() => void` | Called when screensaver activates or returns home |
+| `deactivateCallback` | `() => void` | Called when screensaver deactivates |
+| `blockerCallback` | `() => boolean` | Return `true` to prevent activation |
+| `rebootTimeout` | `number \| null` | Minutes before triggering a reboot callback |
+| `rebootCallback` | `() => void` | Called when reboot timeout elapses |
+
 ### Settings Manager
 
 Create hidden settings pages with corner touch activation. See [SETTINGS_MANAGER.md](./SETTINGS_MANAGER.md) for detailed documentation.

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,11 +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;
@@ -128,26 +129,61 @@ declare class AppBuilder extends RenderableComponent {
     isTransitioning(): boolean;
     /**
      * Add a screensaver page with the specified configuration
-     * The screensaver page can contain multiple views for rich interactive experiences
-     * @param screensaverPage The page to use as the screensaver (can contain multiple views)
+     * The screensaver page can contain multiple views for rich interactive experiences.
+     * Pass `null` for screensaverPage when using `screensaverViewBehavior: "returnHome"` mode,
+     * which navigates back to a home page/view on timeout instead of showing a screensaver.
+     * @param screensaverPage The page to use as the screensaver (can contain multiple views), or null for returnHome mode
      * @param config Configuration object for the screensaver (excluding 'page' property)
      */
-    addScreensaver(screensaverPage: Page, config: Omit<ScreensaverConfig, 'page'>): void;
+    addScreensaver(screensaverPage: Page | null, config: Omit<ScreensaverConfig, 'page'>): void;
     attachToDom(): void;
 }
 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;
     /**
-     * Add a screensaver page with the specified configuration
-     * @param screensaverPage The page to use as the screensaver (can contain multiple views)
+     * 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,
+     * which navigates back to a home page/view on timeout instead of showing a screensaver.
+     * @param screensaverPage The page to use as the screensaver (can contain multiple views), or null for returnHome mode
      * @param config Configuration object for the screensaver (excluding 'page' property)
      */
-    addScreensaver(screensaverPage: Page, config: Omit<ScreensaverConfig, 'page'>): void;
+    addScreensaver(screensaverPage: Page | null, config: Omit<ScreensaverConfig, 'page'>): void;
     /**
      * Add a hidden settings page to this page with the specified configuration
      * The settings page is activated by touching corners in sequence: top-left, top-right, bottom-right

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;
@@ -499,20 +500,24 @@ class AppBuilder extends RenderableComponent {
     }
     /**
      * Add a screensaver page with the specified configuration
-     * The screensaver page can contain multiple views for rich interactive experiences
-     * @param screensaverPage The page to use as the screensaver (can contain multiple views)
+     * The screensaver page can contain multiple views for rich interactive experiences.
+     * Pass `null` for screensaverPage when using `screensaverViewBehavior: "returnHome"` mode,
+     * which navigates back to a home page/view on timeout instead of showing a screensaver.
+     * @param screensaverPage The page to use as the screensaver (can contain multiple views), or null for returnHome mode
      * @param config Configuration object for the screensaver (excluding 'page' property)
      */
     addScreensaver(screensaverPage, config) {
-        // Add the screensaver page to the app
-        this.addPage(screensaverPage);
+        // Add the screensaver page to the app (only if provided)
+        if (screensaverPage) {
+            this.addPage(screensaverPage);
+        }
         // Register the screensaver with the screensaver manager via event bus
         const screensaverBus = this.orchestrator.getEventBus("screensaver-manager");
         if (screensaverBus) {
             screensaverBus.emit("register-screensaver", {
                 config: {
                     ...config,
-                    page: screensaverPage,
+                    page: screensaverPage || undefined,
                 },
             });
         }
@@ -534,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
@@ -644,8 +651,100 @@ class Page extends RenderableComponent {
         }
     }
     /**
-     * Add a screensaver page with the specified configuration
-     * @param screensaverPage The page to use as the screensaver (can contain multiple views)
+     * 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,
+     * which navigates back to a home page/view on timeout instead of showing a screensaver.
+     * @param screensaverPage The page to use as the screensaver (can contain multiple views), or null for returnHome mode
      * @param config Configuration object for the screensaver (excluding 'page' property)
      */
     addScreensaver(screensaverPage, config) {
@@ -655,7 +754,7 @@ class Page extends RenderableComponent {
             screensaverBus.emit("register-screensaver", {
                 config: {
                     ...config,
-                    page: screensaverPage,
+                    page: screensaverPage || undefined,
                 },
             });
         }

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":"AAMA,qBAAa,QAAQ,CAAC,UAAU,GAAG,GAAG;IACpC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,EAAE,CAAS;gBACP,WAAW,SAAc;IAIrC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;IAiBnE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;IAiBrE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAmB1B;;OAEG;IACH,SAAS,IAAI,IAAI;IAQjB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,OAAO,IAAI,IAAI;IASf,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU;IAgBtC,OAAO,CAAC,qBAAqB;CAO9B;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,aAAa,CAAW;;IAUhC,GAAG;IAqBH,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC;IAM9C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAI1C,OAAO,CACL,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAkB,EAC5B,MAAM,CAAC,EAAE,OAAO,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM;IAWjB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,yBAAyB;IAIzD,OAAO,CAAC,4BAA4B;IAKpC,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAG5D,OAAO;IAIP,cAAc,CAAC,WAAW,EAAE,GAAG;IAY/B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,4BAA4B;IAwDpC;;;OAGG;IACI,oBAAoB,IAAI,MAAM;IAmBrC;;OAEG;IACI,YAAY,IAAI,MAAM;IAI7B;;OAEG;IACI,gBAAgB,IAAI,MAAM;IAIjC;;OAEG;IACI,qBAAqB,IAAI,MAAM;IAMtC;;;;;;OAMG;IACI,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;QAC9D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;QAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EACD,QAAQ,GAAE,MAAoB,GAC7B,IAAI;IAOP;;;;;;OAMG;IACI,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;QAC9D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;QAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EACD,QAAQ,GAAE,MAAoB,GAC7B,IAAI;CAMR;AACD,cAAM,yBAAyB;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;gBAGtB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAkB,EAC5B,WAAW,GAAE,MAAmB,EAChC,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,OAAO;CAUnB;AAED,wBAAgB,kBAAkB,sBAEjC"}
+{"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

@@ -3,9 +3,9 @@ import { Page } from "./appBuilder";
 import { NavigationManager, type TransitionConfig } from "./navigationManager";
 export interface ScreensaverConfig {
     timeoutSeconds: number;
-    page: Page;
+    page?: Page;
     defaultViewId?: string;
-    screensaverViewBehavior?: "default" | "specific" | "return";
+    screensaverViewBehavior?: "default" | "specific" | "return" | "returnHome";
     specificViewId?: string;
     transitionConfig?: TransitionConfig;
     exitBehavior?: "reset" | "return";
@@ -38,6 +38,7 @@ export declare class ScreensaverManager {
     private initializeGlobalState;
     private setupEventListeners;
     registerScreensaver(config: ScreensaverConfig): void;
+    private isReturnHomeMode;
     private validateConfig;
     private setupGlobalActivityListeners;
     private shouldIgnoreActivity;
@@ -45,6 +46,12 @@ export declare class ScreensaverManager {
     private pauseActivityTimer;
     private clearActivityTimer;
     private activateScreensaver;
+    /**
+     * Return-to-home activation: navigates to the configured home page/view
+     * without entering "screensaver active" state. The timer resets immediately
+     * for the next inactivity cycle.
+     */
+    private activateReturnHome;
     private determineScreensaverView;
     private handleScreensaverExit;
     private deactivateScreensaver;

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,EAAE,IAAI,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC5D,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;IAwCpB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAiC3D,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,4BAA4B;IAmDpC,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,kBAAkB;YAOZ,mBAAmB;IAkDjC,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":"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"}

package/dist/src/screensaverManager.js

@@ -67,7 +67,8 @@ export class ScreensaverManager {
         if (navBus) {
             navBus.on("page-changed", (e) => {
                 const { newPageId } = e.detail;
-                if (!this.isScreensaverActive && newPageId !== this.config?.page.componentId) {
+                const screensaverPageId = this.config?.page?.componentId;
+                if (!this.isScreensaverActive && (!screensaverPageId || newPageId !== screensaverPageId)) {
                     this.lastActivePageId = newPageId;
                     stateManager.set("screensaver.lastActivePageId", newPageId);
                 }
@@ -103,33 +104,52 @@ export class ScreensaverManager {
                 type: "snap",
             },
         };
-        // Register the screensaver page with navigation manager
-        const navBus = this.orchestrator.getEventBus("navigation-manager");
-        if (navBus) {
-            navBus.emit("register-page", { page: this.config.page });
+        // Register the screensaver page with navigation manager (only in screensaver mode)
+        if (!this.isReturnHomeMode() && this.config.page) {
+            const navBus = this.orchestrator.getEventBus("navigation-manager");
+            if (navBus) {
+                navBus.emit("register-page", { page: this.config.page });
+            }
         }
         this.setupGlobalActivityListeners();
         this.resetActivityTimer();
-        log.trace(`Screensaver registered with ${config.timeoutSeconds}s timeout and '${this.config.exitBehavior}' exit behavior`);
+        if (this.isReturnHomeMode()) {
+            log.trace(`Screensaver registered in returnHome mode with ${config.timeoutSeconds}s timeout, target: ${this.config.startingPageId}/${this.config.defaultViewId || "default"}`);
+        }
+        else {
+            log.trace(`Screensaver registered with ${config.timeoutSeconds}s timeout and '${this.config.exitBehavior}' exit behavior`);
+        }
+    }
+    isReturnHomeMode() {
+        return this.config?.screensaverViewBehavior === "returnHome";
     }
     validateConfig(config) {
-        if (!config.page) {
-            throw new Error("Screensaver page is required");
-        }
         if (config.timeoutSeconds <= 0) {
             throw new Error("timeoutSeconds must be greater than 0");
         }
-        if (config.exitBehavior === "reset" && !config.startingPageId) {
-            throw new Error('startingPageId is required when exitBehavior is "reset"');
+        if (config.screensaverViewBehavior && !["default", "specific", "return", "returnHome"].includes(config.screensaverViewBehavior)) {
+            throw new Error('screensaverViewBehavior must be "default", "specific", "return", or "returnHome"');
         }
-        if (config.exitBehavior && !["reset", "return"].includes(config.exitBehavior)) {
-            throw new Error('exitBehavior must be either "reset" or "return"');
-        }
-        if (config.screensaverViewBehavior === "specific" && !config.specificViewId) {
-            throw new Error('specificViewId is required when screensaverViewBehavior is "specific"');
+        if (config.screensaverViewBehavior === "returnHome") {
+            // In returnHome mode, startingPageId is required as the home page target
+            if (!config.startingPageId) {
+                throw new Error('startingPageId is required when screensaverViewBehavior is "returnHome"');
+            }
         }
-        if (config.screensaverViewBehavior && !["default", "specific", "return"].includes(config.screensaverViewBehavior)) {
-            throw new Error('screensaverViewBehavior must be "default", "specific", or "return"');
+        else {
+            // In screensaver modes, page is required
+            if (!config.page) {
+                throw new Error('Screensaver page is required when screensaverViewBehavior is not "returnHome"');
+            }
+            if (config.exitBehavior === "reset" && !config.startingPageId) {
+                throw new Error('startingPageId is required when exitBehavior is "reset"');
+            }
+            if (config.exitBehavior && !["reset", "return"].includes(config.exitBehavior)) {
+                throw new Error('exitBehavior must be either "reset" or "return"');
+            }
+            if (config.screensaverViewBehavior === "specific" && !config.specificViewId) {
+                throw new Error('specificViewId is required when screensaverViewBehavior is "specific"');
+            }
         }
     }
     setupGlobalActivityListeners() {
@@ -219,17 +239,26 @@ export class ScreensaverManager {
         }
     }
     async activateScreensaver() {
-        if (!this.config || this.isScreensaverActive)
+        if (!this.config)
             return;
         if (this.config.blockerCallback && this.config.blockerCallback()) {
             this.resetActivityTimer();
             return;
         }
+        // Handle returnHome mode — navigate to home page/view without entering screensaver state
+        if (this.isReturnHomeMode()) {
+            await this.activateReturnHome();
+            return;
+        }
+        // Standard screensaver mode
+        if (this.isScreensaverActive)
+            return;
         log.trace("Activating screensaver");
         // Store the current page and view before switching to screensaver
         const currentPageId = this.navigationManager.getCurrentPageId();
         const currentViewId = this.navigationManager.getCurrentViewId();
-        if (currentPageId && currentPageId !== this.config.page.componentId) {
+        const screensaverPageId = this.config.page.componentId;
+        if (currentPageId && currentPageId !== screensaverPageId) {
             this.lastActivePageId = currentPageId;
             this.lastActiveViewId = currentViewId;
             stateManager.set("screensaver.lastActivePageId", currentPageId);
@@ -239,14 +268,14 @@ export class ScreensaverManager {
         stateManager.set("screensaver.isActive", true);
         try {
             // Navigate to screensaver page
-            await this.navigationManager.navigateToPage(this.config.page.componentId, this.config.transitionConfig);
+            await this.navigationManager.navigateToPage(screensaverPageId, this.config.transitionConfig);
             // Determine which view to show based on screensaverViewBehavior
             const targetViewId = this.determineScreensaverView();
             if (targetViewId) {
                 await this.navigationManager.navigateToView(targetViewId, { type: "snap" });
             }
             this.eventBus.emit("screensaver-activated", {
-                pageId: this.config.page.componentId,
+                pageId: screensaverPageId,
                 viewId: targetViewId,
                 previousPageId: this.lastActivePageId,
                 previousViewId: this.lastActiveViewId,
@@ -263,6 +292,53 @@ export class ScreensaverManager {
         this.startRebootCheckInterval();
         this.checkAndPerformReboot();
     }
+    /**
+     * Return-to-home activation: navigates to the configured home page/view
+     * without entering "screensaver active" state. The timer resets immediately
+     * for the next inactivity cycle.
+     */
+    async activateReturnHome() {
+        if (!this.config)
+            return;
+        const targetPageId = this.config.startingPageId;
+        const targetViewId = this.config.defaultViewId || null;
+        const currentPageId = this.navigationManager.getCurrentPageId();
+        const currentViewId = this.navigationManager.getCurrentViewId();
+        // Skip navigation if already on the target page/view
+        const alreadyOnTargetPage = currentPageId === targetPageId;
+        const alreadyOnTargetView = !targetViewId || currentViewId === targetViewId;
+        if (alreadyOnTargetPage && alreadyOnTargetView) {
+            log.trace("ReturnHome: Already on home page/view, resetting timer");
+            this.resetActivityTimer();
+            return;
+        }
+        log.trace(`ReturnHome: Navigating to ${targetPageId}/${targetViewId || "default"}`);
+        try {
+            // Navigate to home page
+            if (!alreadyOnTargetPage) {
+                await this.navigationManager.navigateToPage(targetPageId, this.config.transitionConfig);
+            }
+            // Navigate to home view if specified
+            if (targetViewId && !alreadyOnTargetView) {
+                await this.navigationManager.navigateToView(targetViewId, { type: "snap" });
+            }
+            this.eventBus.emit("screensaver-returned-home", {
+                targetPageId,
+                targetViewId,
+                previousPageId: currentPageId,
+                previousViewId: currentViewId,
+            });
+            if (this.config.activateCallback)
+                this.config.activateCallback();
+        }
+        catch (error) {
+            log.error("Failed to return to home:", error);
+        }
+        // Reset timer for next inactivity cycle
+        this.resetActivityTimer();
+        // Check reboot timeout if configured
+        this.checkAndPerformReboot();
+    }
     determineScreensaverView() {
         if (!this.config)
             return null;

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.1",
+  "version": "0.0.3",
   "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",