March 2024 Release of the APL 2024.1 compliant APL Viewhost Web

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

CHANGELOG.md

@@ -1,38 +1,48 @@
 # Changelog for apl-viewhost-web
 
+## [2024.1]
+This release adds support for version 2024.1 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
+
+### Added
+- Add support for Log command
+- Add support for runtime to override the package loading method
+
+### Changed
+- Bug fixes
+
 ## [2023.3]
 This release adds support for version 2023.3 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
- 
+
 ### Added
 - Add support for conditional import
 - Add support for auto sizing
 - Add support gradient as Frame background
 - Exported caption control class `cueControl` for APL videos
- 
+
 ### Changed
 - Changed default font to sans-serif to meet the APL Spec
 - Bug fixes
- 
+
 ## [2023.2]
 This release adds support for version 2023.2 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
- 
+
 ### Added
 - Add support for the seekTo ControlMedia command
- 
+
 ### Changed
 - Remove usage of APL Core Library's deprecated getTheme API
 - Bug fixes
- 
+
 ## [2023.1]
 This release adds support for version 2023.1 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
- 
+
 ### Added
 - SRT support for APL Video textTrack
 - Support for new Porter-Duff blend modes
- 
+
 ### Changed
 - Bug fixes
- 
+
 ## [2022.2]
 This release adds support for version 2022.2 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
 

README.md

@@ -1,10 +1,10 @@
 # Alexa Presentation Language (APL) Viewhost Web
 
 <p>
- <a href="https://github.com/alexa/apl-viewhost-web/tree/v2023.3.0" alt="version">
- <img src="https://img.shields.io/badge/stable%20version-2023.3.0-brightgreen" /></a>
- <a href="https://github.com/alexa/apl-core-library/tree/v2023.3.0" alt="APLCore">
- <img src="https://img.shields.io/badge/apl%20core%20library-2023.3.0-navy" /></a>
+ <a href="https://github.com/alexa/apl-viewhost-web/tree/v2024.1.0" alt="version">
+ <img src="https://img.shields.io/badge/stable%20version-2024.1.0-brightgreen" /></a>
+ <a href="https://github.com/alexa/apl-core-library/tree/v2024.1.0" alt="APLCore">
+ <img src="https://img.shields.io/badge/apl%20core%20library-2024.1.0-navy" /></a>
 </p>
 
 ## Introduction

js/apl-html/lib/dts/Content.d.ts

@@ -16,7 +16,7 @@ declare namespace APL {
     }
 
     export class Content extends Deletable {
-        public static create(document: string): Content;
+        public static create(document: string, session: Session): Content;
         public refresh(metrics: Metrics, config: RootConfig): void;
         public getRequestedPackages(): Set<ImportRequest>;
         public addPackage(request: ImportRequest, data: string): void;

js/apl-html/lib/dts/Module.d.ts

@@ -95,6 +95,7 @@ declare namespace APL {
         public AudioPlayerFactory: typeof AudioPlayerFactory;
         public MediaPlayer: typeof MediaPlayer;
         public MediaPlayerFactory: typeof MediaPlayerFactory;
+        public Session : typeof Session;
     }
 }
 

js/apl-html/src/Content.ts

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { logLevelToLogCommandLevel, OnLogCommand } from './logging/LogCommand';
+
 /**
  * Holds all of the documents and data necessary to inflate an APL component hierarchy.
  */
@@ -12,12 +14,25 @@ export class Content {
      * Creates an instance of a Content object. a single Content instance
      * can be used with multiple [[APLRenderer]]s.
      * @param doc The main APL document
+     * @param data The data used for the main document
+     * @param onLogCommand The callback to send back the log info
      */
-    public static create(doc: string, data?: string) {
-        if (data === undefined) {
-            return new Content(doc, '');
+    public static create(doc: string, data: string = '', onLogCommand?: OnLogCommand) {
+        return new Content(doc, data, onLogCommand);
+    }
+
+    /**
+     * Creates an instance of a Content object. a single Content instance
+     * can be used with multiple [[APLRenderer]]s.
+     * @param doc The main APL document
+     * @param data The data used for the main document
+     * @param onLogCommand The callback to send back the log info
+     */
+    public static recreate(other: Content, onLogCommand?: OnLogCommand) {
+        if (other.data) {
+            return new Content(other.doc, other.data, onLogCommand);
         }
-        return new Content(doc, data);
+        return new Content(other.doc, JSON.stringify(other.dataMap), onLogCommand);
     }
 
     /**
@@ -43,22 +58,27 @@ export class Content {
      * @internal
      * @ignore
      * @param doc The main APL document
+     * @param data The data used for the main document
      */
-    private constructor(doc: string, private data: string) {
+    private constructor(private doc: string, private data: string, onLogCommand?: OnLogCommand) {
         try {
             this.settings = JSON.parse(doc).settings || {};
         } catch (e) {
             this.settings = {};
         }
-        this.content = Module.Content.create(doc);
+        this.content = Module.Content.create(this.doc, Module.Session.create((level, message, args) => {
+            if (onLogCommand) {
+                onLogCommand(logLevelToLogCommandLevel(level), message, args);
+            }
+        }));
         if (this.data) {
-            const jsonDoc = JSON.parse(doc);
+            const jsonDoc = JSON.parse(this.doc);
             if (jsonDoc.mainTemplate && jsonDoc.mainTemplate.parameters &&
                 Array.isArray(jsonDoc.mainTemplate.parameters) &&
                 jsonDoc.mainTemplate.parameters.length > 0) {
                 const parsedData = JSON.parse(data);
                 jsonDoc.mainTemplate.parameters.forEach((name: string) => {
-                   if (name === 'payload') {
+                    if (name === 'payload') {
                         this.content.addData(name, data);
                     } else if (parsedData[name]) {
                         this.content.addData(name, JSON.stringify(parsedData[name]));
@@ -111,11 +131,20 @@ export class Content {
     }
 
     /**
+     * @deprecated Should use create(doc, data, onLogCommand)
      * Add data
      * @param name The name of the data source
      * @param data The raw data source
      */
     public addData(name: string, data: string): void {
+        if (this.data) {
+            console.warn('Created with datasource already, no-op for addData.');
+            return;
+        }
+        if (name === 'payload') {
+            this.dataMap = {...this.dataMap, ...JSON.parse(data)};
+        }
+        this.dataMap[name] = JSON.parse(data);
         this.content.addData(name, data);
     }
 
@@ -176,4 +205,6 @@ export class Content {
     public getParameterCount(): number {
         return this.content.getParameterCount();
     }
+
+    private dataMap = {};
 }

js/apl-html/src/index.ts

@@ -103,6 +103,7 @@ export * from './utils/SoftRandom';
 export * from './utils/TextTrackUtils';
 export * from './utils/LocaleMethods';
 export * from './logging/ILogger';
+export * from './logging/LogCommand';
 export * from './logging/LoggerFactory';
 export {LogLevel as JSLogLevel} from './logging/LogLevel';
 export * from './logging/LogTransport';

js/apl-html/src/logging/LogCommand.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { LogLevel } from '../enums/LogLevel';
+
+/// All supported levels for log command.
+export enum LogCommandLevel {
+    debug,
+    info,
+    warn,
+    error,
+    critical
+}
+
+/// Convert a Core log level to a supported log level.
+export function logLevelToLogCommandLevel(level: LogLevel) {
+    switch (level) {
+        case LogLevel.kDebug:
+            return LogCommandLevel.debug;
+        case LogLevel.kInfo:
+            return LogCommandLevel.info;
+        case LogLevel.kWarn:
+            return LogCommandLevel.warn;
+        case LogLevel.kError:
+            return LogCommandLevel.error;
+        case LogLevel.kCritical:
+            return LogCommandLevel.critical;
+        default:
+            return LogCommandLevel.info;
+    }
+}
+
+/// Simple function type for log command callback.
+export type OnLogCommand = (level: LogCommandLevel, message: string, args: object) => void;

js/apl-html/src/utils/AplVersionUtils.ts

@@ -19,6 +19,7 @@ export const APL_2022_2 = 11;
 export const APL_2023_1 = 12;
 export const APL_2023_2 = 13;
 export const APL_2023_3 = 14;
+export const APL_2024_1 = 14;
 export const APL_LATEST = Number.MAX_VALUE;
 
 export interface AplVersionUtils {
@@ -42,7 +43,8 @@ export function createAplVersionUtils(): AplVersionUtils {
         ['2022.2', APL_2022_2],
         ['2023.1', APL_2023_1],
         ['2023.2', APL_2023_2],
-        ['2023.3', APL_2023_3]
+        ['2023.3', APL_2023_3],
+        ['2024.1', APL_2024_1]
     ]);
 
     return {

js/apl-wasm/src/APLWASMRenderer.ts

@@ -6,8 +6,8 @@
 import APLRenderer, {
     commandFactory, Content, DefaultAudioPlayer, DeviceMode, DisplayState,
     FontUtils, IAPLOptions, IAudioEventListener, IAudioPlayerFactory,
-    IConfigurationChangeOptions, ILogger, JSLogLevel, LiveArray, LiveMap,
-    LocaleMethods, LoggerFactory, LogLevel, LogTransport, MediaPlayerHandle, ViewportShape
+    IConfigurationChangeOptions, JSLogLevel, LiveArray, LiveMap,
+    LocaleMethods, LoggerFactory, LogTransport, MediaPlayerHandle, OnLogCommand, ViewportShape
 } from 'apl-html';
 import {ConfigurationChange} from './ConfigurationChange';
 import {ExtensionManager} from './extensions/ExtensionManager';
@@ -50,6 +50,10 @@ export interface IAPLWASMOptions extends IAPLOptions {
     extensionManager?: ExtensionManager;
     /** Document State to restore */
     documentState?: IDocumentState;
+    /** Override package download. Reject the Promise to fallback to the default logic. */
+    packageLoader?: (name: string, version: string, url?: string) => Promise<string>;
+    /** callback for APL Log Command handling, will overwrite the callback during Content creation */
+    onLogCommand?: OnLogCommand;
 }
 
 const LEGACY_KARAOKE_APL_VERSION = '1.0';
@@ -70,9 +74,6 @@ export class APLWASMRenderer extends APLRenderer<IAPLWASMOptions> {
     protected legacyKaroke: boolean;
     protected isAutoSizing: boolean;
 
-    /// Logger to be used for core engine logs.
-    private coreLogger: ILogger;
-
     /// Viewport metrics.
     private metrics: APL.Metrics;
 
@@ -97,9 +98,13 @@ export class APLWASMRenderer extends APLRenderer<IAPLWASMOptions> {
     private constructor(options: IAPLWASMOptions) {
         LoggerFactory.initialize(options.logLevel || 'debug', options.logTransport);
         super(options);
-        this.coreLogger = LoggerFactory.getLogger('Core');
-        this.content = this.options.documentState ?
-            this.options.documentState.content : this.options.content;
+        if (this.options.documentState) {
+            this.content = this.options.documentState.content;
+        } else if (this.options.onLogCommand) {
+            this.content = Content.recreate(this.options.content, this.options.onLogCommand);
+        } else {
+            this.content = this.options.content;
+        }
         this.legacyKaroke = this.content.getAPLVersion() === LEGACY_KARAOKE_APL_VERSION;
         this.documentAplVersion = this.content.getAPLVersion();
         this.metrics = Module.Metrics.create();
@@ -198,36 +203,6 @@ export class APLWASMRenderer extends APLRenderer<IAPLWASMOptions> {
     }
 
     public async init() {
-        const logTransport: APL.CoreLogTransport = (level: number, log: string) => {
-            const logLevel: LogLevel = level as LogLevel;
-            switch (logLevel) {
-                case LogLevel.TRACE:
-                    this.coreLogger.trace(log);
-                    break;
-                case LogLevel.DEBUG:
-                    this.coreLogger.debug(log);
-                    break;
-                case LogLevel.INFO:
-                    this.coreLogger.info(log);
-                    break;
-                case LogLevel.WARN:
-                    this.coreLogger.warn(log);
-                    break;
-                case LogLevel.ERROR:
-                    this.coreLogger.error(log);
-                    break;
-                case LogLevel.CRITICAL:
-                    this.coreLogger.error(log);
-                    break;
-                case LogLevel.NONE:
-                    break;
-                default:
-                    this.coreLogger.warn(`Log with unknown level: ${level} : ${log}`);
-                    break;
-            }
-        };
-        Module.Logger.setLogTransport(logTransport);
-
         this.supportsResizing = this.content.getAPLSettings('supportsResizing');
 
         if (!this.options.documentState) {
@@ -348,7 +323,7 @@ export class APLWASMRenderer extends APLRenderer<IAPLWASMOptions> {
     }
 
     public async loadPackages(): Promise<boolean> {
-        const packageLoader: PackageLoader = new PackageLoader();
+        const packageLoader: PackageLoader = new PackageLoader(this.options.packageLoader);
         while (this.content.isWaiting()) {
             const importRequests = this.content.getRequestedPackages();
             if (importRequests.size > 0) {