add scripts for specifically running integration tests, remove one last CDN link to aws-sdk and use the local version, and update docs as needed for the new ESM format without a required build

Author: trusktr

CONTRIBUTING.md

@@ -66,11 +66,14 @@ npm install
 
 ### Building
 
-To build all packages in the repository, run:
+The Host libraries work without a build. Only the Babylon Hosts library has a build step for generating type definition files, which is totally optional for use in TypeScript projects.
+
+To run the build (which runs only the Babylon Host lib's type declaration build step), run:
 ```
 npm run build
 ```
-Distributable build artifacts will be generated into a `dist/` directory within each package folder.
+
+Distributable build artifacts (type declaration files) will be generated into a `dist/` directory inside the Babylon Host lib.
 
 ### Testing
 
@@ -82,12 +85,14 @@ Example applications for Babylon.js can be found in the `packages/demos-babylon/
 
 #### Unit Tests
 
-If you've already built the packages, you can execute the unit tests for all packages using the command:
+You can execute the unit tests for all packages using the command:
 ```
-npm run test
+npm test
 ```
 
-Alternately, you can both build and run the unit tests with a single command:
+Running the build is not necessary for running tests, as all source files as JavaScript modules that work as-is without transformation.
+
+You can run both the Babylon build and the unit tests with a single command to ensure both work at the same time:
 ```
 npm run build-test
 ```

README.md

@@ -2,9 +2,10 @@
 
 Amazon Sumerian Hosts (Hosts) is an experimental open source project that aims to make it easy to create interactive animated 3D characters for Babylon.js, three.js, and other web 3D frameworks. It leverages AWS services including [Amazon Polly](https://aws.amazon.com/polly/) (text-to-speech) and [Amazon Lex](https://aws.amazon.com/lex/) (chatbot).
 
+<!-- CONTINUE Update this after the Babylon fix -->
 > **Compatibility**
 >
-> ⚠️ Hosts is currently compatible with **BabylonJS v4** (4.2.1+). There are know issues if you try to use Hosts with BabylonJS v5. If you would like to see support for BabylonJS v5 added, comment on [this enhancement request issue](https://github.com/aws-samples/amazon-sumerian-hosts/issues/155).
+> ⚠️ Hosts is currently compatible with **BabylonJS v4** (4.2.1+). There are known issues if you try to use Hosts with BabylonJS v5. If you would like to see support for BabylonJS v5 added, comment on [this enhancement request issue](https://github.com/aws-samples/amazon-sumerian-hosts/issues/155).
 >
 > ✏️ Hosts have been tested with **Three.js v0.127.0**.
 
@@ -34,7 +35,7 @@ The easiest way to get started using the hosts is by using plugins we provide fo
 
 Visit the [aws-tools-for-babylonjs-editor](https://github.com/aws-samples/aws-tools-for-babylonjs-editor/blob/main/README.md) repository for more details.
 
-#### Using pre-built NPM modules
+#### Using NPM modules
 
 If you are creating applications outside of the Babylon.JS Editor, you can easily install the relevant Hosts module using NPM.
 
@@ -56,7 +57,20 @@ For full detail on the classes and methods available, see the [API Documentation
 
 #### Building from source
 
-Building from source is considered an advanced option. It is not recommended unless you need to heavily customize the core Hosts functionality. Instructions on how to build from source can be found in the [CONTRIBUTING](CONTRIBUTING.md) document.
+Both the core Host lib and the Three.js Host lib do not have a build. You can
+customize them by simply editing the .js files in your own fork, and simply
+running a static server to run the apps.
+
+The Babylon Host lib has a TypeScript build step *only* for creating output
+type definitions from its .js files, and is otherwise not required for running
+the Babylon demos: simply edit the JavaScript files, and start the static
+server to run the demos.
+
+If you need to build the type definitions for consumption in a TypeScript
+project, then run `npm run build` at the root of the repo (after first running
+`npm install` if you haven't already).
+
+Find more details in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Demos
 

package.json

@@ -29,7 +29,9 @@
     "start": "five-server .",
     "start-core": "five-server . --open=./packages/amazon-sumerian-hosts-core/test/integration_test/core",
     "start-three": "five-server . --open=./packages/amazon-sumerian-hosts-three/examples/",
-    "start-babylon": "five-server . --open=./packages/demos-babylon/src/"
+    "start-three-tests": "five-server . --open=./packages/amazon-sumerian-hosts-three/test/integration_test/three.js/",
+    "start-babylon": "five-server . --open=./packages/demos-babylon/src/",
+    "start-babylon-tests": "five-server . --open=./packages/demos-babylon/src/"
   },
   "devDependencies": {
     "cross-env": "^7.0.3",

packages/amazon-sumerian-hosts-babylon/README.md

@@ -22,49 +22,77 @@ More details can be found in [demos-babylon](https://github.com/aws-samples/amaz
 
 Before you use Hosts in your applications, you will need to set up a few thing in your AWS account. For step-by-step instructions on setting up this required infrastructure, see [AWS-Infrastructure-Setup.md](https://github.com/aws-samples/amazon-sumerian-hosts/tree/mainline2.0/AWS-Infrastructure-Setup.md) in the root of this repository.
 
-### Configurating the AWS SDK
+## Configurating the Babylon HOST app
 
-## Configuring Webpack
-
-We recommend using a module bundler such as [Webpack](https://webpack.js.org/) to package and distribute your code. As BabylonJS relies on static singletons for certain features, it may be necessary to configure Webpack so that all modules and submodules use the same instance of BabylonJS. Add the following to `module.exports.resolve`:
-
-```
-resolve: {
-  ...
-  modules: ['node_modules'],
-  alias: {
-      // configure all modules to point at the same instance of BabylonJS
-      '@babylonjs/core': path.resolve('./node_modules/@babylonjs/core')
-  }
-},
+### Step 1. Adding Script Dependencies
 
-```
+Here we will take a look at the scripts necessary for the example code to function:
 
-### Step 1. Adding Script Dependencies
+> [!Note] Before you continue, make sure you've ran `npm install` at the root of
+the repo so that dependencies are installed locally.
 
-One way to configure AWS SDK is to include dependency script:
 
 - ```html
-  <!--Text to speech dependency-->
-  <script
-      type="text/javascript"
-      src="https://sdk.amazonaws.com/js/aws-sdk-2.645.0.min.js"
-  ></script>
+  <!-- This fetches the AWS SDK for JavaScript, and installs it as a global `AWS` variable. -->
+  <script src="../../../node_modules/aws-sdk/dist/aws-sdk.min.js"></script>
   ```
 
-  The hosts will need to connect to Amazon Polly to convert text into audio assets. https://sdk.amazonaws.com/js/aws-sdk-2.645.0.min.js is a minified build of the AWS SDK for Javascript. For the latest version, see the [AWS SDK for JavaScript API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/).
-
-And then configure the AWS SDK with our region and credentials:
+  This file has to be included first, so that it is available by the time the
+  rest of our code runs.
 
-- ```javascript
-  // Initialize AWS and create Polly service objects
-  AWS.config.region = 'us-west-2';
-  AWS.config.credentials = new AWS.CognitoIdentityCredentials({
-    IdentityPoolId: '<Enter Cognito Identity Pool ID here>',
-  });
+- ```html
+  <!-- Define the locations for each of the libraries that we've installed so we can import them. -->
+  <script type="importmap">
+    {
+      "imports": {
+        "three": "https://cdn.jsdelivr.net/npm/three@0.127.0/build/three.module.js",
+        "three/": "https://cdn.jsdelivr.net/npm/three@0.127.0/",
+        "@amazon-sumerian-hosts/core": "../../../node_modules/@amazon-sumerian-hosts/core/src/core/index.js",
+        "@amazon-sumerian-hosts/three": "../../../node_modules/@amazon-sumerian-hosts/three/src/three.js/index.js",
+        "compare-versions": "../../../node_modules/compare-versions/lib/esm/index.js",
+        "aws-sdk": "../../demos-babylon/src/aws-sdk-global.js"
+      }
+    }
+  </script>
   ```
 
-  Replace `<Enter Cognito Identity Pool ID here>` with the id you created in the [Prerequisites](#Prerequisites) section. Make sure to set the region to the one you created your Cognito Identity Pool in. Using CognitoIdentityCredentials is just one example of how you can authenticate your host to access Polly. See the [AWS SDK documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html) to see other credentials classes you can use.
+  The `importmap` script defines where dependencies are to be found, so
+  that code that has `import` statements will receive the expected libraries. For
+  example, the `imports.three` entry in the following import map (which is in JSON
+  format) defines where the `three` library will be fetched from when an import
+  statement like `import * as THREE from 'three'` is encountered in JavaScript.
+  For more info on import maps, see [Mozilla's import map
+  docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
+  which also has links to broader concepts like JavaScript modules in general, and
+  the [import map spec repository on GitHub](https://github.com/WICG/import-maps)
+  which has the original ideation and links to resources for managing import maps.
+
+  The hosts will need to connect to Amazon Polly to convert text into audio
+  assets. Here we map imports to `aws-sdk` to an `aws-sdk-global.js` file that
+  exports the global `AWS` variable so that we can `import` it in our JavaScript
+  code instead of relying on the global variable everywhere that we need to use
+  it. For the latest version of the SDK, see the [AWS SDK for JavaScript API
+  Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/).
+
+  > [!Note] The version after the `@` for the `three` URL should be the same as
+  found in the [package.json](package.json) to guarantee that it works. Feel
+  free to try newer versions of Three.js to see if they work, and if not then
+  restore the known working version. If you get it working with newer Three.js
+  (sometimes there are small tweaks needed from breaking changes in Three.js),
+  please submit a pull request to get it updated.
+
+## Configure the AWS SDK with our region and credentials:
+
+```javascript
+// Initialize AWS and create Polly service objects
+AWS.config.region = 'us-west-2';
+AWS.config.credentials = new AWS.CognitoIdentityCredentials({
+  IdentityPoolId: cognitoIdentityPoolId,
+});
+```
+
+> [!Note]
+> Here the `cognitoIdentityPoolId` variable will contain the id you created and placed inside of `demo-credentials.js` in the [Prerequisites](#Prerequisites) section. Make sure to set the region to the one you created your Cognito Identity Pool in. Using CognitoIdentityCredentials is just one example of how you can authenticate your host to access Polly. See the [AWS SDK documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html) to see other credentials classes you can use.
 
 ### Instantiating the Host
 
@@ -172,6 +200,14 @@ Then, you can setup a simple button used for recording microphone input purpose
   LexFeature also supports text input as well as a list of other events for tracking recording state for instance. See [LexFeature](https://aws-samples.github.io/amazon-sumerian-hosts/core_LexFeature.html) for more details.
 
 ### Next Steps
+
 Now that you've demonstrated your hosts running locally, consider publishing them to the web via one of these related tutorials:
-- [Publishing a Web Application Using AWS Amplify](https://docs.sumerian.amazonaws.com/tutorials/create/solutions/gltf-viewer-amplify-public/)
-- [Privately Publish a Web Application Using AWS Amplify](https://docs.sumerian.amazonaws.com/tutorials/create/solutions/gltf-viewer-amplify-private/)
+
+- [Hosting a static site on AWS Amplify](https://aws.amazon.com/getting-started/hands-on/host-static-website/)
+- [Creating a static GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site)
+- [Publishing a static site on Vercel from git](https://vercel.com/docs/deployments/git)
+
+If you're more advanced, you probably want to set up a server that contains your
+AWS key privately, so that it is not served publicy in via a static website.
+You'd want to require user authentication, and proxy request through your server
+so that the client-side code does not contain the key.

packages/amazon-sumerian-hosts-babylon/test/integration_test/README.md

@@ -16,6 +16,6 @@ npm install
 
 ## Running the Tests
 
-Run `npm run start-babylon` from the repository root. This will start a local web server and open two tabs in your browser. One will provide a list of demos (from the `packages/demos-babylon` package.) The other will be the list of available integration tests. From this tab you can access and exercise each test.
+Run `npm run start-babylon-tests` from the repository root. The tab will provide a list of available integration tests. From this tab you can access and exercise each test.
 
 When you're finished runnin the tests, you can quit the local dev server by pressing CTRL-C in the same terminal in which you started the server.

packages/amazon-sumerian-hosts-core/README.md

@@ -4,7 +4,13 @@ For a general introduction to Amazon Sumerian Hosts and examples of how to integ
 
 Amazon Sumerian Hosts is an experimental open source project that aims to make it easy to create interactive animated 3D characters that can be rendered on the Web and leverage AWS Services such as [Amazon Polly](https://aws.amazon.com/polly/). The core API provides an abstraction layer so that these can be extended to support the Web rendering engine of your choice. 
 
-Refer to the [API Documentation](https://aws-samples.github.io/amazon-sumerian-hosts/) for more detailed information on the classes and methods available. Amazon Sumerian Hosts is a published [npm](https://www.npmjs.com/) package, so alternatively you can install in an existing Node.js project by running `npm install --save-dev @amazon-sumerian-hosts/core`. If you'd like to pull the GitHub repository and create your own build, see [Building the Repository](https://github.com/aws-samples/amazon-sumerian-hosts/blob/mainline2.0/README.md#building-the-repository) for prerequisites and instructions on how to do that.
+Refer to the [API Documentation](https://aws-samples.github.io/amazon-sumerian-hosts/) for more detailed information on the classes and methods available. Amazon Sumerian Hosts is a published [npm](https://www.npmjs.com/) package, so alternatively you can install in an existing Node.js project by running `npm install --save-dev @amazon-sumerian-hosts/core`.
+
+If you'd like to pull the GitHub repository and customize the hosts, a build is
+not required unless you want to generate type defintions for use in TypeScript,
+and the demos simply run on their own without a build step. See [Building from
+source](https://github.com/aws-samples/amazon-sumerian-hosts/blob/mainline2.0/README.md#building-from-source)
+for prerequisites and instructions on how to do that.
 
 ## License
 

packages/amazon-sumerian-hosts-core/test/integration_test/README.md

@@ -18,7 +18,7 @@ npm install
 
 Run `npm run start-core` from the repository root. This will start a local web server and open a web browser tab containing a list of available integration tests. From this tab you can access and exercise each test.
 
-When you're finished runnin the tests, you can quit the local dev server by pressing CTRL-C in the same terminal in which you started the server.
+When you're finished running the tests, you can quit the local dev server by pressing CTRL-C in the same terminal in which you started the server.
 
 
 

packages/amazon-sumerian-hosts-core/test/integration_test/core/core.texttospeech.html

@@ -8,20 +8,24 @@
     <meta charset="UTF-8" />
     <title>Core Host Test</title>
     <link rel="icon" href="data:;base64,iVBORw0KGgo=" />
+
+    <script src="../../../../../node_modules/aws-sdk/dist/aws-sdk.min.js"></script>
+
     <script type="importmap">
       {
         "imports": {
           "@amazon-sumerian-hosts/core": "../../../../../node_modules/@amazon-sumerian-hosts/core/src/core/index.js",
-          "compare-versions": "../../../../../node_modules/compare-versions/lib/esm/index.js"
+          "compare-versions": "../../../../../node_modules/compare-versions/lib/esm/index.js",
+          "aws-sdk": "../../../../demos-babylon/src/aws-sdk-global.js"
         }
       }
     </script>
   </head>
   <body>
-    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.645.0.min.js"></script>
     <script type="module">
       import {cognitoIdentityPoolId} from '../../../../../demo-credentials.js';
       import * as HOST from '@amazon-sumerian-hosts/core';
+      import AWS from 'aws-sdk';
 
       async function main() {
         // Parse the region out of the cognito Id
@@ -41,7 +45,7 @@
         await TextToSpeechFeature.initializeService(
           polly,
           presigner,
-          window.AWS.VERSION
+          AWS.VERSION
         );
 
         // Create the speaker who will deliver speeches