From 1ef112c232da0d7ed6918b3fb070f4dd2285951a Mon Sep 17 00:00:00 2001
From: Danny McGee <dannymcgee@gmail.com>
Date: Wed, 6 Mar 2024 21:38:11 -0500
Subject: [PATCH] Document URL params and app startup workflow (#77)

---
 studio-frontend/README.md        | 20 +++++++++
 studio-web/src/lib/url-params.ts | 69 ++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 studio-frontend/README.md

diff --git a/studio-frontend/README.md b/studio-frontend/README.md
new file mode 100644
index 0000000..aac42fe
--- /dev/null
+++ b/studio-frontend/README.md
@@ -0,0 +1,20 @@
+# studio-frontend
+
+This is the primary microfrontend to be embedded in the [Storyteller.ai
+website](https://fakeyou.com/studio).
+
+### Running
+
+The project can be served locally using the `serve` target:
+```sh
+npx nx serve studio-frontend
+```
+
+### Configuring application startup
+
+After running the `serve` command above, the web app can be viewed in the
+browser at `http://localhost:4200` and configured through a set of URL
+parameters which are documented [here](../studio-web/src/lib/url-params.ts).
+
+For example, to load the bundled `sample-room.gltf` scene in `StudioMode.Editor`,
+visit: http://localhost:4200/?mode=studio&objectId=sample-room.gltf
diff --git a/studio-web/src/lib/url-params.ts b/studio-web/src/lib/url-params.ts
index cadf983..7afe080 100644
--- a/studio-web/src/lib/url-params.ts
+++ b/studio-web/src/lib/url-params.ts
@@ -1,18 +1,87 @@
 import { StudioMode } from "@storyteller/studio";
 import { match } from "@storyteller/utility";
 
+/**
+ * A thin wrapper around
+ * {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams URLSearchParams}
+ * for retrieving URL parameters supported by the Storyteller Studio
+ * microfrontend and (where applicable) translating them into the types expected
+ * by the [`StudioElement`](./studio.element.ts) component.
+ *
+ * The following parameters are mutually exclusive, and one of them must be
+ * present in order to progress past the "Loading" screen:
+ *
+ * - {@linkcode objectId}
+ * - {@linkcode bvh}
+ * - {@linkcode mixamo}
+ * - {@linkcode sceneImport}
+ * - {@linkcode scene}
+ *
+ * `bvh`, `mixamo`, `sceneImport` and `scene` can accept an "asset path" in any
+ * of the following formats:
+ * - **relative/path/to/file** - Looks for the given file path relative to the
+ *   `studio/assets` directory
+ * - **http[s]://remote/path/to/file** - Any http(s) URL to an asset type
+ *   supported by Bevy Engine
+ * - **remote://&lt;media-token&gt;.&lt;file-extension&gt;** - A token for a
+ *   media file that can be fetched from the Storyteller.ai API
+ */
 export class StudioURLParams {
 	#_nativeParams?: URLSearchParams;
 	get #nativeParams() {
 		return this.#_nativeParams ??= new URLSearchParams(document.location.search);
 	}
 
+	/**
+	 * Initialize the application from an asset in the "bundled" asset library.
+	 * Takes a filename, including the extension, that can be found under
+	 * `studio/assets/gltf` (e.g., "base-human-female.gltf").
+	 */
 	get objectId() { return this.#nativeParams.get("objectId") ?? undefined; }
+
+	/**
+	 * Initialize the application by retargeting a BVH animation (currently only
+	 * supports the MocapNET skeleton) onto the bundled `Mannequin.gltf` model.
+	 */
 	get bvh() { return this.#nativeParams.get("bvh") ?? undefined; }
+
+	/**
+	 * Initialize the application by retargeting a Mixamo animation onto the
+	 * bundled `Mannequin.gltf` model.
+	 */
 	get mixamo() { return this.#nativeParams.get("mixamo") ?? undefined; }
+
+	/**
+	 * Initialize the application by loading an arbitrary glTF scene from any
+	 * source.
+	 */
 	get sceneImport() { return this.#nativeParams.get("sceneImport") ?? undefined; }
+
+	/**
+	 * Initialize the application by loading a previously saved Storyteller
+	 * Studio scene in `*.scn.ron` format.
+	 */
 	get scene() { return this.#nativeParams.get("scene") ?? undefined; }
+
+	/**
+	 * One of:
+	 * - A skybox name that corresponds to a matching set of assets under
+	 *   `studio/assets/skyboxes`, _not_ including file extensions or "diffuse" /
+	 *   "specular" qualifiers (e.g., "gum_trees_4k").
+	 * - A hex-formatted color, without the leading `#` (e.g., "1A1A27")
+	 */
 	get skybox() { return this.#nativeParams.get("skybox") ?? undefined; }
+
+	/**
+	 * Determines whether the app initializes in a minimal, read-only "viewer"
+	 * mode or the full "Studio" mode with editor controls.
+	 *
+	 * URL parameters:
+	 * - `?mode=viewer` outputs `StudioMode.Viewer`
+	 * - `?mode=studio` outputs `StudioMode.Editor`
+	 *
+	 * @default StudioMode.Viewer
+	 */
 	get mode(): StudioMode {
 		return match(this.#nativeParams.get("mode"), {
 			"studio": () => StudioMode.Editor,