@xibosignage/xibo-layout-renderer 1.0.22 → 1.0.23

package/README.md

@@ -1,2 +1,69 @@
 # Xibo Layout Renderer
 This is a npm module for rendering Xibo layouts to a browser window.
+
+## How It Works
+
+### 1. Initialization Flow
+
+```
+Consumer calls XiboLayoutRenderer(inputLayouts, overlays, options)
+  ├─ bootstrap()         → Sets up DOM (#preview_canvas), splash screen
+  ├─ init()              → Calls prepareLayouts()
+  │   ├─ parseLayouts()  → Determines current + next layout from schedule loop
+  │   ├─ prepareLayoutXlf()  → Fetches XLF XML, parses with DOMParser
+  │   └─ new Layout()    → Parses XLF → creates Regions → creates Media objects
+  └─ playSchedules()     → Makes current layout visible, runs regions + overlays
+```
+
+### 2. Layout Lifecycle
+
+Each layout goes through these states defined in `ELayoutState`:
+
+| State       | Meaning                                    |
+|-------------|---------------------------------------------|
+| `IDLE`      | Layout created but not yet running          |
+| `RUNNING`   | Layout is actively displayed                |
+| `PLAYED`    | Layout has finished (all regions expired)   |
+| `CANCELLED` | Layout was removed before completing        |
+| `ERROR`     | Layout encountered an error                 |
+
+### 3. Region → Media Playback
+
+- A **Layout** contains one or more **Regions** (positioned `<div>` containers)
+- Each **Region** contains a playlist of **Media** items (widgets)
+- Media items can be: `image`, `video`, `audio`, `html` (iframe-based widgets)
+- When a media item's duration expires, the region transitions to the next media
+- When all regions have completed their cycle, the layout emits `'end'`, triggering the next layout
+
+### 4. Schedule Loop
+
+The orchestrator (IXlr) maintains a **current** and **next** layout. When the current layout ends:
+1. The next layout becomes current
+2. A new next layout is prepared from the input schedule
+3. This creates a continuous loop of layouts
+
+### 5. Overlay System
+
+OverlayLayoutManager handles layouts that display on top of the main schedule. Overlays are paused during "interrupt" layouts (layouts with `shareOfVoice > 0`).
+
+### 6. Event System
+
+Uses [nanoevents](https://github.com/ai/nanoevents) for a pub/sub event pattern:
+
+| Level   | Events                                           |
+|---------|--------------------------------------------------|
+| **XLR** | `layoutChange`, `layoutStart`, `layoutEnd`, `layoutError`, `widgetStart`, `widgetEnd`, `updateLoop`, `updateOverlays`, `adRequest`, `overlayStart`, `overlayEnd`, `commandCodeReceived` |
+| **Layout** | `start`, `end`, `cancelled`                   |
+| **Region** | `start`, `end`                                |
+| **Media**  | `start`, `end`                                |
+
+### 7. Platform Abstraction
+
+The library supports multiple platforms via `ConsumerPlatform` enum and the `options.platform` flag:
+
+| Platform    | XLF Source                     | Special Behavior                 |
+|-------------|--------------------------------|-----------------------------------|
+| `CMS`       | Fetched via URL with JWT       | Preview-only features, "Play again" UI |
+| `chromeOS`  | Local file path                | Fault reporting via Service Worker |
+| `electron`  | App host + URL                 | Standard playback                 |
+| PWA         | Proxy/hosted                   | Service Worker caching            |

package/dist/src/Lib/BlobLoader.d.ts

@@ -0,0 +1,11 @@
+export declare class BlobLoader {
+    private static cache;
+    /**
+     * Fetches a video and returns a local Blob URL (e.g., blob:http://localhost/...)
+     */
+    static load(url: string): Promise<string>;
+    /**
+     * Frees memory. CRITICAL for 24/7 signage.
+     */
+    static release(url: string): void;
+}

package/dist/src/Lib/index.d.ts

@@ -0,0 +1,3 @@
+export { BlobLoader } from './BlobLoader';
+export { default as PwaSW } from './pwa-sw';
+export * from './translations';

package/dist/src/Modules/ActionController/index.d.ts

@@ -1 +1,2 @@
-export { default, Action, ActionsWrapper, InactOptions, } from './ActionController';
+export type { InactOptions, } from './ActionController';
+export { default, Action, ActionsWrapper, } from './ActionController';

package/dist/src/Modules/Generators/Generators.d.ts

@@ -1,5 +1,6 @@
 import { IMedia } from '../../Types/Media';
 import { InputLayoutType, OptionsType } from '../../Types/Layout';
+import { IRegion } from "../../Types/Region";
 export declare function nextId(options: {
     idCounter: number;
 }): number;
@@ -51,5 +52,14 @@ export declare function getLayoutIndexByLayoutId(layouts: InputLayoutType[], lay
 export declare function hasDefaultOnly(inputLayouts: InputLayoutType[]): boolean;
 export declare function isDefaultLayout(inputLayout: InputLayoutType): boolean;
 export declare function hasSspLayout(inputLayouts: InputLayoutType[], defaultValue?: boolean): boolean;
-export declare function createMediaElement(mediaObject: IMedia, role: 'current' | 'next'): HTMLElement;
+export declare function prepareIframe(media: IMedia): HTMLIFrameElement;
+export declare function prepareImage(media: IMedia, container: HTMLElement): HTMLElement;
+export declare function prepareVideo(media: IMedia, container: HTMLVideoElement): HTMLVideoElement;
+export declare function prepareAudio(media: IMedia, container: HTMLAudioElement): HTMLAudioElement;
+export declare function createMediaElement(mediaObject: IMedia): HTMLElement;
+export declare function prepareVideoMedia(media: IMedia, region: IRegion): void;
+export declare function prepareImageMedia(media: IMedia, region: IRegion): void;
+export declare function prepareAudioMedia(media: IMedia, region: IRegion): void;
+export declare function prepareHtmlMedia(media: IMedia, region: IRegion): void;
+export declare function playerReportFault(msg: string, media: IMedia): Promise<void>;
 export {};

package/dist/src/Modules/Generators/index.d.ts

@@ -1 +1,2 @@
-export { getFileExt, nextId, preloadMediaBlob, getMediaId, fetchJSON, capitalizeStr, audioFileType, MediaTypes, videoFileType, setExpiry, composeMediaUrl, fetchText, getDataBlob, composeResourceUrl, composeResourceUrlByPlatform, getIndexByLayoutId, isEmpty, composeBgUrlByPlatform, hasDefaultOnly, isLayoutValid, } from './Generators';
+export type { MediaTypes, } from './Generators';
+export { getFileExt, nextId, preloadMediaBlob, getMediaId, fetchJSON, capitalizeStr, audioFileType, videoFileType, setExpiry, composeMediaUrl, fetchText, getDataBlob, composeResourceUrl, composeResourceUrlByPlatform, getIndexByLayoutId, isEmpty, composeBgUrlByPlatform, hasDefaultOnly, isLayoutValid, createMediaElement, } from './Generators';

package/dist/src/Modules/Layout/Layout.d.ts

@@ -1,5 +1,6 @@
 import { Emitter } from 'nanoevents';
-import { ELayoutState, GetLayoutParamType, GetLayoutType, ILayout, ILayoutEvents, OptionsType } from '../../Types/Layout';
+import { ELayoutState, GetLayoutParamType, GetLayoutType, ILayout, LayoutPlaybackType, OptionsType } from '../../Types/Layout';
+import { ILayoutEvents } from "../../types";
 import { IXlr } from '../../Types/XLR';
 import './layout.css';
 import ActionController, { Action } from '../ActionController';
@@ -49,6 +50,7 @@ export default class Layout implements ILayout {
     layoutNode?: Document;
     path?: string;
     errorCode: number | null;
+    html: HTMLElement | null;
     options: OptionsType;
     xlr: IXlr;
     private readonly layoutObj;
@@ -60,11 +62,11 @@ export default class Layout implements ILayout {
     playRegions(): void;
     regionExpired(): void;
     end(): void;
-    regionEnded(): Promise<void>;
+    regionEnded(): void;
     stopAllMedia(): Promise<void>;
     resetLayout(): Promise<void>;
     finishAllRegions(): Promise<void[]>;
-    removeLayout(): void;
+    removeLayout(caller?: LayoutPlaybackType): void;
     getXlf(): string;
     isInterrupt(): boolean;
     on<E extends keyof ILayoutEvents>(event: E, callback: ILayoutEvents[E]): import("nanoevents").Unsubscribe;

package/dist/src/Modules/Layout/OverlayLayout.d.ts

@@ -1,7 +1,8 @@
+import { Emitter, Unsubscribe } from "nanoevents";
 import Layout from "./Layout";
-import { ILayout, ILayoutEvents, OptionsType } from "../../Types/Layout";
+import { ILayout, OptionsType } from "../../Types/Layout";
+import { ILayoutEvents } from "../../Types/Events";
 import { IXlr } from "../../Types/XLR";
-import { Emitter, Unsubscribe } from "nanoevents";
 export interface IOverlayLayoutEvents extends ILayoutEvents {
 }
 export default class OverlayLayout extends Layout {

package/dist/src/Modules/Media/Media.d.ts

@@ -2,14 +2,11 @@ import { Emitter } from 'nanoevents';
 import Player from "video.js/dist/types/player";
 import { OptionsType } from '../../Types/Layout';
 import { IRegion } from '../../Types/Region';
-import { IMedia } from '../../Types/Media';
+import { IMedia, MediaState } from '../../Types/Media';
 import { IXlr } from '../../Types/XLR';
-import { MediaState } from "../../Types/Media/Media.types";
+import { IMediaEvents } from "../../Types/Events";
 import 'video.js/dist/video-js.min.css';
-export interface IMediaEvents {
-    start: (media: IMedia) => void;
-    end: (media: IMedia) => void;
-}
+import { IVideoMediaHandler } from "./VideoMedia";
 export declare class Media implements IMedia {
     attachedAudio: boolean;
     checkIframeStatus: boolean;
@@ -49,14 +46,23 @@ export declare class Media implements IMedia {
     url: string | null;
     useDuration: boolean;
     xml: Element | null;
-    private mediaTimer;
+    videoHandler?: IVideoMediaHandler;
+    mediaTimer: ReturnType<typeof setInterval> | undefined;
     private mediaTimeCount;
     private xlr;
     private readonly statsBC;
+    private hasCommandExecuted;
     constructor(region: IRegion, mediaId: string, xml: Element, options: OptionsType, xlr: IXlr);
     private startMediaTimer;
     private on;
     private init;
     run(): void;
     stop(): Promise<void>;
+    /**
+     * Emits a command from the shell command widget.
+     *
+     * @param media
+     * @private
+     */
+    private emitCommand;
 }

package/dist/src/Modules/Media/VideoMedia.d.ts

@@ -1,9 +1,24 @@
+import Player from "video.js/dist/types/player";
 import { IMedia } from '../../Types/Media';
-import { IXlr } from '../../types';
+import { IXlr, OptionsType } from '../../types';
 import './media.css';
 export declare function composeVideoSource($media: HTMLVideoElement, media: IMedia): HTMLVideoElement;
+export declare const defaultVjsOpts: {
+    autoplay: boolean;
+    muted: boolean;
+    preload: string;
+    controls: boolean;
+};
+export declare const vjsDefaultOptions: (opts?: any) => any;
+export interface IVideoMediaHandler {
+    player: Player | undefined;
+    duration: number;
+    stop(disposeOnly?: boolean): void;
+}
+export declare function videoMediaHandler(media: IMedia, platform: OptionsType['platform']): IVideoMediaHandler;
 export declare function VideoMedia(media: IMedia, xlr: IXlr): {
     duration: number;
     init: () => void;
     stop: (disposeOnly?: boolean) => void;
+    play: () => void;
 };

package/dist/src/Modules/Region/Region.d.ts

@@ -1,4 +1,57 @@
 import { ILayout, OptionsType } from '../../Types/Layout';
 import { IRegion } from '../../Types/Region';
+import { IMedia } from '../../Types/Media';
+import { IRegionEvents } from "../../Types/Events";
 import { IXlr } from '../../Types/XLR';
-export default function Region(layout: ILayout, xml: Element, regionId: string, options: OptionsType, xlr: IXlr): IRegion;
+export default class Region implements IRegion {
+    layout: ILayout;
+    xml: Element | null;
+    regionId: string;
+    options: OptionsType;
+    xlr: IXlr;
+    complete: boolean;
+    containerName: string;
+    currMedia: IMedia | undefined;
+    currEl: HTMLElement | null;
+    currentMedia: number;
+    currentMediaIndex: number;
+    ended: boolean;
+    ending: boolean;
+    html: HTMLDivElement;
+    id: string;
+    index: number;
+    mediaObjects: IMedia[];
+    mediaObjectsActions: IMedia[];
+    nxtMedia: IMedia | undefined;
+    nxtEl: HTMLElement | null;
+    offsetX: number;
+    offsetY: number;
+    oldMedia: IMedia | undefined;
+    oneMedia: boolean;
+    ready: boolean;
+    sHeight: number;
+    sWidth: number;
+    totalMediaObjects: number;
+    uniqueId: string;
+    zIndex: number;
+    emitter: import("nanoevents").Emitter<IRegionEvents>;
+    constructor(layout: ILayout, xml: Element, regionId: string, options: OptionsType, xlr: IXlr);
+    prepareRegion(): void;
+    prepareMedia(media: IMedia): void;
+    prepareFirstMedia(): void;
+    prepareNextMedia(): void;
+    prepareMediaObjects(): void;
+    finished(): void;
+    private prepareVideo;
+    private prepareImage;
+    private prepareIframe;
+    run(): void;
+    transitionNodes(oldMedia: IMedia | undefined, newMedia: IMedia | undefined): void;
+    playNextMedia(): void;
+    playPreviousMedia(): void;
+    end(): void;
+    exitTransition(): void;
+    exitTransitionComplete(): void;
+    reset(): void;
+    on<E extends keyof IRegionEvents>(event: E, callback: IRegionEvents[E]): import("nanoevents").Unsubscribe;
+}

package/dist/src/Modules/SplashScreen/index.d.ts

@@ -1 +1,2 @@
-export { default, ISplashScreen, PreviewSplashElement, } from './SplashScreen';
+export type { ISplashScreen, PreviewSplashElement, } from './SplashScreen';
+export { default, } from './SplashScreen';

package/dist/src/Modules/Transitions/index.d.ts

@@ -1 +1,2 @@
-export { compassPoints, defaultTrans, fadeInElem, fadeOutElem, flyInElem, flyOutElem, transitionElement, flyTransitionKeyframes, flyTransitionParams, TransitionNameType, KeyframeOptionsType, TransitionElementOptions, } from './Transitions';
+export type { compassPoints, flyTransitionParams, TransitionNameType, KeyframeOptionsType, TransitionElementOptions, } from './Transitions';
+export { defaultTrans, fadeInElem, fadeOutElem, flyInElem, flyOutElem, transitionElement, flyTransitionKeyframes, } from './Transitions';

package/dist/src/Types/Events/Events.types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Centralized event type definitions
+ * All module events should be defined here
+ */
+import { ILayout } from "../Layout";
+import { IMedia } from "../Media";
+import { IRegion } from "../Region";
+/**
+ * Events emitted by Layout
+ */
+export interface ILayoutEvents {
+    start: (layout: ILayout) => void;
+    end: (layout: ILayout) => void;
+    cancelled: (layout: ILayout) => void;
+    layoutStart?: (layout: ILayout) => void;
+    layoutEnd?: (layout: ILayout) => void;
+}
+/**
+ * Events emitted by Region
+ */
+export interface IRegionEvents {
+    start: (region: IRegion) => void;
+    end: (region: IRegion) => void;
+}
+/**
+ * Events emitted by Media
+ */
+export interface IMediaEvents {
+    start: (media: IMedia) => void;
+    end: (media: IMedia) => void;
+    cancelled: (media: IMedia) => void;
+}
+/**
+ * Type alias for event unsubscriber
+ */
+export type EventUnsubscriber = () => void;
+export type EventEmitter<T> = <K extends keyof T>(event: K, ...args: Parameters<T[K] extends (...args: any[]) => any ? T[K] : never>) => void;

package/dist/src/Types/Events/index.d.ts

@@ -0,0 +1 @@
+export * from './Events.types';

package/dist/src/Types/Layout/Layout.types.d.ts

@@ -2,11 +2,8 @@ import { Emitter, Unsubscribe } from 'nanoevents';
 import { IRegion } from '../Region';
 import { IXlr } from '../XLR';
 import InteractiveActions, { Action } from '../../Modules/ActionController';
-export interface ILayoutEvents {
-    start: (layout: ILayout) => void;
-    end: (layout: ILayout) => void;
-    cancelled: (layout: ILayout) => void;
-}
+import { ILayoutEvents } from "../Events";
+import { ConsumerPlatform } from "../Platform";
 export declare enum ELayoutState {
     IDLE = 0,
     RUNNING = 1,
@@ -14,6 +11,11 @@ export declare enum ELayoutState {
     CANCELLED = 3,
     ERROR = 4
 }
+export declare enum LayoutPlaybackType {
+    CURRENT = "current",
+    NEXT = "next",
+    OVERLAY = "overlay"
+}
 export type InputLayoutType = {
     response: any;
     layoutId: number;
@@ -35,7 +37,7 @@ export type OptionsType = {
     idCounter: number;
     inPreview: boolean;
     appHost?: string | null;
-    platform: 'CMS' | 'chromeOS';
+    platform: ConsumerPlatform;
     config?: {
         cmsUrl: string | null;
         schemaVersion: number;
@@ -88,7 +90,7 @@ export interface ILayout {
     on<E extends keyof ILayoutEvents>(event: E, callback: ILayoutEvents[E]): Unsubscribe;
     regionExpired(): void;
     end(): void;
-    regionEnded(): Promise<void>;
+    regionEnded(): void;
     stopAllMedia(): Promise<void>;
     resetLayout(): Promise<void>;
     index: number;
@@ -97,7 +99,7 @@ export interface ILayout {
     xlr: IXlr;
     finishAllRegions(): Promise<void[]>;
     inLoop: boolean;
-    removeLayout(): void;
+    removeLayout(caller?: LayoutPlaybackType): void;
     xlfString: string;
     getXlf(): string;
     ad: any;
@@ -106,6 +108,7 @@ export interface ILayout {
     isInterrupt(): boolean;
     state: ELayoutState;
     errorCode: number | null;
+    html: HTMLElement | null;
 }
 export declare const initialLayout: ILayout;
 export type GetLayoutParamType = {

package/dist/src/Types/Layout/index.d.ts

@@ -1 +1,2 @@
-export { GetLayoutParamType, GetLayoutType, ILayout, InputLayoutType, OptionsType, initialLayout, ILayoutEvents, ELayoutState, } from './Layout.types';
+export type { GetLayoutParamType, GetLayoutType, ILayout, InputLayoutType, OptionsType, } from './Layout.types';
+export { initialLayout, ELayoutState, LayoutPlaybackType, } from './Layout.types';

package/dist/src/Types/Media/Media.types.d.ts

@@ -1,13 +1,15 @@
 import { Emitter } from 'nanoevents';
 import Player from "video.js/dist/types/player";
-import { IMediaEvents } from '../../Modules/Media/Media';
 import { IRegion } from '../Region';
 import { OptionsType } from '../Layout';
-export type MediaState = 'idle' | 'playing' | 'ended';
+import { IVideoMediaHandler } from "../../Modules/Media";
+import { IMediaEvents } from "../Events";
+export type MediaState = 'idle' | 'playing' | 'ended' | 'cancelled';
 export declare const MediaState: {
     readonly IDLE: "idle";
     readonly PLAYING: "playing";
     readonly ENDED: "ended";
+    readonly CANCELLED: "cancelled";
 };
 export interface IMedia {
     attachedAudio: boolean;
@@ -50,5 +52,7 @@ export interface IMedia {
     url: string | null;
     useDuration: boolean;
     xml: Element | null;
+    videoHandler?: IVideoMediaHandler;
+    mediaTimer: ReturnType<typeof setInterval> | undefined;
 }
 export declare const initialMedia: IMedia;

package/dist/src/Types/Media/index.d.ts

@@ -1 +1,2 @@
-export { IMedia, initialMedia, } from './Media.types';
+export type { IMedia, } from './Media.types';
+export { initialMedia, MediaState, } from './Media.types';

package/dist/src/Types/Platform/Platform.types.d.ts

@@ -0,0 +1,12 @@
+export declare enum ConsumerPlatform {
+    CMS = "CMS",
+    CHROMEOS = "chromeOS",
+    ELECTRON = "electron",
+    IOS = "ios",
+    MACOS = "macos",
+    ANDROID = "android",
+    LINUX = "linux",
+    WINDOWS = "windows",
+    WEBOS = "webos",
+    TIZEN = "tizen"
+}

package/dist/src/Types/Platform/index.d.ts

@@ -0,0 +1 @@
+export * from './Platform.types';

package/dist/src/Types/Region/Region.types.d.ts

@@ -1,15 +1,13 @@
 import { DefaultEvents, Emitter, Unsubscribe } from 'nanoevents';
 import { ILayout } from '../Layout';
 import { IMedia } from '../Media';
-export interface IRegionEvents {
-    start: (layout: IRegion) => void;
-    end: (layout: IRegion) => void;
-}
+import { IRegionEvents } from "../Events";
+import { IXlr } from "../XLR";
 export interface IRegion {
     complete: boolean;
     containerName: string;
     currMedia: IMedia | undefined;
-    currEl: HTMLElement | undefined;
+    currEl: HTMLElement | null;
     currentMedia: number;
     currentMediaIndex: number;
     emitter?: Emitter<DefaultEvents>;
@@ -26,7 +24,7 @@ export interface IRegion {
     mediaObjects: IMedia[];
     mediaObjectsActions: IMedia[];
     nxtMedia: IMedia | undefined;
-    nxtEl: HTMLElement | undefined;
+    nxtEl: HTMLElement | null;
     offsetX: number;
     offsetY: number;
     oldMedia: IMedia | undefined;
@@ -50,5 +48,7 @@ export interface IRegion {
     uniqueId: string;
     xml: null | Element;
     zIndex: number;
+    prepareNextMedia(): void;
+    xlr: IXlr;
 }
 export declare const initialRegion: IRegion;

package/dist/src/Types/Region/index.d.ts

@@ -1 +1,2 @@
-export { IRegion, IRegionEvents, initialRegion, } from './Region.types';
+export type { IRegion, } from './Region.types';
+export { initialRegion, } from './Region.types';

package/dist/src/Types/XLR/XLR.types.d.ts

@@ -21,6 +21,8 @@ export type IXlrEvents = {
     updateOverlays: (overlays: InputLayoutType[]) => void;
     overlayStart: (overlay: ILayout) => void;
     overlayEnd: (overlay: ILayout) => void;
+    commandCodeReceived: (commandCode: string) => void;
+    commandStringReceived: (commandString: string) => void;
 };
 export interface IXlrPlayback {
     currentLayout: ILayout | undefined;
@@ -56,7 +58,7 @@ export interface IXlr {
     overlays: InputLayoutType[];
     parseLayouts(loopUpdate?: boolean): IXlrPlayback;
     playLayouts(xlr: IXlr): void;
-    playSchedules(xlr: IXlr): void;
+    playSchedules(xlr: IXlr): Promise<void>;
     prepareForSsp(nextLayout: ILayout): Promise<ILayout>;
     prepareLayoutXlf(inputLayout: ILayout | undefined): Promise<ILayout>;
     prepareLayouts(): Promise<IXlr>;

package/dist/src/Types/XLR/index.d.ts

@@ -1 +1,2 @@
-export { ELayoutType, IXlr, initialXlr, IXlrEvents, PrepareLayoutsType, IXlrPlayback, } from './XLR.types';
+export type { IXlr, IXlrEvents, PrepareLayoutsType, IXlrPlayback, } from './XLR.types';
+export { ELayoutType, initialXlr, } from './XLR.types';

package/dist/src/types.d.ts

@@ -1,4 +1,6 @@
 export * from './Types/Layout';
 export * from './Types/Media';
 export * from './Types/Region';
+export * from './Types/Events';
 export * from './Types/XLR';
+export * from './Types/Platform';