Release commit created with Cranko.

+++ cranko-release-info-v1
[[projects]]
qnames = ["@wwtelescope/research-app-messages", "npm"]
version = "0.17.2"
age = 1

[[projects]]
qnames = ["@wwtelescope/engine-types", "npm"]
version = "0.6.7"
age = 0

[[projects]]
qnames = ["@wwtelescope/engine", "npm"]
version = "7.29.2"
age = 0

[[projects]]
qnames = ["@wwtelescope/embed-common", "npm"]
version = "0.3.5"
age = 1

[[projects]]
qnames = ["@wwtelescope/embed-creator", "npm"]
version = "0.5.0"
age = 1

[[projects]]
qnames = ["@wwtelescope/astro", "npm"]
version = "0.2.5"
age = 0

[[projects]]
qnames = ["@wwtelescope/engine-helpers", "npm"]
version = "0.16.0"
age = 1

[[projects]]
qnames = ["@wwtelescope/engine-pinia", "npm"]
version = "0.9.0"
age = 1

[[projects]]
qnames = ["@wwtelescope/research-app", "npm"]
version = "0.16.0"
age = 1

[[projects]]
qnames = ["@wwtelescope/embed", "npm"]
version = "1.7.0"
age = 1

+++

.eslintrc.js

@@ -10,13 +10,7 @@ module.exports = {
     'plugin:@typescript-eslint/recommended'
   ],
   rules: {
-    "no-unused-vars": [
-      "warn", {
-        "args": "all",
-        "argsIgnorePattern": "^_",
-        "varsIgnorePattern": "^_"
-      }
-    ],
+    "no-unused-vars": "off", // this rule is superseded by typescript-eslint's version
     "@typescript-eslint/no-unused-vars": [
       "warn", {
         "args": "all",

astro/CHANGELOG.md

@@ -1,3 +1,9 @@
+# @wwtelescope/astro 0.2.5 (2023-11-03)
+
+- Update to the latest typedoc, and other improvements to the documentation
+  infrastructure (#274, #275, #276, #277, #278, @pkgw).
+
+
 # @wwtelescope/astro 0.2.4 (2023-09-15)
 
 - Update sponsorship branding and "front door" email address (#269, #271, @pkgw).

astro/package.json

@@ -10,7 +10,7 @@
     "@typescript-eslint/parser": "^5.38.1",
     "eslint": "^8.24.0",
     "rimraf": "^3",
-    "typedoc": "0.23.20",
+    "typedoc": "0.25.1",
     "typescript": "~4.8.4"
   },
   "homepage": "https://worldwidetelescope.org/home/",
@@ -32,5 +32,5 @@
   },
   "type": "module",
   "types": "./dist/src/index.d.ts",
-  "version": "0.2.4"
+  "version": "0.2.5"
 }

ci/azure-main-build.yml

@@ -5,7 +5,7 @@
 
 parameters:
 - name: 'zolaVersion'
-  default: '0.13.0'
+  default: '0.15.3'
   type: string
 
 jobs:

docs/engine/config.toml

@@ -1,9 +1,12 @@
-base_url = "//docs.worldwidetelescope.org/webgl-reference/1/"
+base_url = "https://docs.worldwidetelescope.org/webgl-reference/latest/"
 title = "WWT WebGL Engine Reference Manual"
 description = "The WorldWide Telescope WebGL Engine reference manual."
 theme = "wwtguide"
 
+[markdown]
+highlight_code = true
+
 [extra]
-github_base = "//github.com/WorldWideTelescope/wwt-webgl-engine"
-google_analytics_id = "UA-107473046-3"
+github_base = "https://github.com/WorldWideTelescope/wwt-webgl-engine"
+google_analytics_id = "G-D1J49XX0CV"
 stylesheets = ["extras.css"]

docs/engine/content/apiref/_index.md

@@ -17,3 +17,17 @@ packages:
 
 [Vue]: https://vuejs.org/
 [Pinia]: https://pinia.vuejs.org/
+
+If you’re interested in writing code to control a WWT display, you might want to
+check out the following sections of the documentation:
+
+- For pure JavaScript without any frameworks (the [hosted JavaScript
+  model](../getting-started/hosted-javascript-model.md)) see
+  [@wwtelescope/engine](./engine/).
+- To control an embedded instance of the research app (the [embedded app
+  model](../getting-started/embedded-app-model.md)) see
+  [@wwtelescope/research-app-messages](./research-app-messages/).
+- For a custom component-based web app built with Vue (the [Vue component
+  model](../getting-started/vue-component-model.md)) see [the WWT Pinia
+  interface](engine-pinia/functions/engineStore.html#md:the-wwt-pinia-interface)
+  in [@wwtelescope/engine-pinia](./engine-pinia/).

docs/engine/content/freestanding-mode/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Freestanding Mode"
-weight = 100
+weight = 10000
 sort_by = "weight"
 insert_anchor_links = "right"
 +++

docs/engine/content/getting-started/_index.md

@@ -7,27 +7,29 @@ insert_anchor_links = "right"
 
 There are a range of ways that you can use the WWT WebGL engine, depending on
 the level of sophistication that you’re trying to achieve and the tools you’re
-prepared to use.
+prepared to use. If you’re considering a WWT-based project, it’s important to be
+aware of the range of options.
 
 - If you want to deploy a generic interface for astronomical data visualization,
   you can probably skip most of the coding by simply **[embedding the WWT
   research app](@/getting-started/embedded-app-model.md)** and not building your
   own custom UI.
 - Prototyping a custom UI with basic HTML and JavaScript, and no build tools or
   fancy infrastructure? You may want to use the **[hosted JavaScript
-  model](@/getting-started/hosted-javascript-model.md)**. But for serious
+  model](@/getting-started/hosted-javascript-model.md)**. But for complex
   applications, we recommend adopting more sophisticated tooling.
 - If you’re using [npm] or another JavaScript package manager, a slightly more
   elaborate approach is the **[bundled TypeScript
   model](@/getting-started/bundled-typescript-model.md)**: import
   the {{engineapi(p="index.html",t="@wwtelescope/engine")}} package into your
   project and interface with it using the [TypeScript] language.
-- If the bundled TypeScript approach sounds good *and* you can use [Vue] with
-  [Pinia] — or if you don’t know that you *can’t* use them — we strongly
-  recommend the **[Vue/Pinia component
-  model](@/getting-started/vue-component-model.md)**.
+- For the most complex applications, we suggest a reactive, component-based
+  architecture. The **[Vue/Pinia component
+  model](@/getting-started/vue-component-model.md)** provides a clean way to
+  include WWT in apps based on the [Vue 3] framework using the [Pinia] state
+  management system.
 
 [npm]: https://npmjs.com/
 [TypeScript]: https://www.typescriptlang.org/
-[Vue]: https://vuejs.org/
+[Vue 3]: https://vuejs.org/
 [Pinia]: https://pinia.vuejs.org/

docs/engine/content/getting-started/bundled-typescript-model.md

@@ -57,14 +57,14 @@ await wwt.waitForReady();
 ```
 
 After the engine has signaled readiness, you can start controlling it.
-The {{helpersapi(p="classes/wwtinstance.html",t="WWTInstance")}} class offers
+The {{helpersapi(p="classes/WWTInstance.html",t="WWTInstance")}} class offers
 two conveniences:
 
 1. Its `ctl`, `si`, `lm`, and `stc` fields provide access to the core components
    of the WWT engine as exposed in {{engineapi(p="index.html",t="@wwtelescope/engine")}}.
 2. The class also provides convenience wrappers around certain APIs that benefit from
    more idiomatic JavaScript/TypeScript usage, as in the async-aware
-   method {{helpersapi(p="classes/wwtinstance.html#waitforready",t="waitForReady()")}}.
+   method {{helpersapi(p="classes/WWTInstance.html#waitForReady",t="waitForReady()")}}.
 
-Check out the {{helpersapi(p="classes/wwtinstance.html",t="WWTInstance")}} API
+Check out the {{helpersapi(p="classes/WWTInstance.html",t="WWTInstance")}} API
 reference to explore the possibilities!

docs/engine/content/getting-started/hosted-javascript-model.md

@@ -13,22 +13,23 @@ Here’s simple HTML that will get you going:
 ```html
 <!doctype html>
 <html lang="en">
-  <head>
+<head>
     <title>My First WWT Application</title>
     <script src="https://web.wwtassets.org/engine/7/wwtsdk.js"></script>
-    <!--[if IE]> <script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
-  </head>
-  <body>
-    <div id="wwtcanvas" style="width: 750px; height: 750px"></div>
+</head>
+<body>
+    <div id="wwtcanvas" style="width: 750px; height: 750px; background-color: #000"></div>
 
     <script type="text/javascript">
-      function init_wwt() {
-          wwtlib.WWTControl.initControl('wwtcanvas');
-      }
+        function init_wwt() {
+            const builder = new wwtlib.WWTControlBuilder("wwtcanvas");
+            builder.startRenderLoop(true);
+            builder.create();
+        }
 
-      window.addEventListener('load', init_wwt);
+        window.addEventListener("load", init_wwt);
     </script>
-  </body>
+</body>
 </html>
 ```
 
@@ -38,9 +39,9 @@ The key elements are:
    engine. You interface with this library via a global variable named
    `wwtlib`.
 2. A `<div>` element that becomes home for the WWT viewport.
-3. A JavaScript shim that calls the
-   function {{engineapi(p="modules/wwtcontrol.html#initcontrol",t="WWTControl.initControl")}}
-   to initialize the engine and start it rendering.
+3. A JavaScript shim that uses the
+   {{engineapi(p="classes/WWTControlBuilder.html",t="WWTControlBuilder")}}
+   class to initialize the engine and start it rendering.
 
 With this minimal initialization, you get a viewer that allows you to pan around
 and use the scroll wheel to zoom in, providing an interface reminiscent of
@@ -51,11 +52,11 @@ full power of the WWT rendering engine through the JavaScript APIs that are
 documented in the {{engineapi(p="index.html",t="@wwtelescope/engine")}}
 TypeScript module, namespaced inside the `wwtlib` variable. The majority of your
 programmatic interactions with the engine will occur
-the {{engineapi(p="modules/wwtcontrol.html",t="WWTControl")}}
+the {{engineapi(p="classes/WWTControl-1.html",t="WWTControl")}}
 class, accessed through
-the {{engineapi(p="modules/wwtcontrol.html#singleton",t="wwtlib.WWTControl.singleton")}}
+the {{engineapi(p="variables/WWTControl.singleton.html",t="wwtlib.WWTControl.singleton")}}
 singleton value, and
-the {{engineapi(p="classes/scriptinterface.html",t="ScriptInterface")}} class,
+the {{engineapi(p="classes/ScriptInterface.html",t="ScriptInterface")}} class,
 returned by
-the {{engineapi(p="modules/wwtcontrol.html#initcontrol",t="wwtlib.WWTControl.initControl")}}
+the {{engineapi(p="classes/WWTControlBuilder.html#create",t="WWTControlBuilder.create()")}}
 function.

docs/engine/content/getting-started/vue-component-model.md

@@ -3,11 +3,12 @@ title = "The Vue/Pinia Component Model"
 weight = 400
 +++
 
-The main WWT applications are built using the [Vue] UI framework using the
-[Pinia] state management library. If you use these too, you can take advantage of
-a lot of useful tools for creating your own customized WWT-based applications.
+The main WWT applications are built using the [Vue 3] UI framework with the
+[Pinia] state management library. If you use these too, you can take advantage
+of a lot of useful tools for creating your own customized WWT-based
+applications.
 
-[Vue]: https://vuejs.org/
+[Vue 3]: https://vuejs.org/
 [Pinia]: https://pinia.vuejs.org/
 
 We’ll assume that you already have a skeleton Vue app in place. To add WWT to

docs/engine/content/tutorial/_index.md

@@ -0,0 +1,17 @@
++++
+title = "WWT API Tutorial"
+weight = 200
+sort_by = "weight"
+insert_anchor_links = "right"
++++
+
+In the [Getting Started](@/getting-started/_index.md) section, we discussed
+different ways that you can use WWT in a project. In this tutorial, we’ll dive
+in with an introduction to the capabilities of WWT engine and common tasks you
+might want to accomplish using it.
+
+This tutorial will assume familiarity with the terminal, a code editor like [VS
+Code], and core elements of the web platform like the JavaScript language and
+CSS.
+
+[VS Code]: https://code.visualstudio.com/

docs/engine/content/tutorial/add-image/index.md

@@ -0,0 +1,131 @@
++++
+title = "Loading an Image"
+weight = 400
++++
+
+Now that we’ve played with WWT’s background image, let’s load up an image in the
+foreground. Edit the JavaScript code of your `index.html` file to read as
+follows. Once again, changes relative to the previous section are subtly
+highlighted:
+```js,hl_lines=13-14 17-22
+var script_interface, wwt;
+
+function init_wwt() {
+    const builder = new wwtlib.WWTControlBuilder("wwtcanvas");
+    builder.startRenderLoop(true);
+    script_interface = builder.create();
+    script_interface.add_ready(on_ready);
+}
+
+function on_ready() {
+    console.log("WWT is ready!");
+    wwt = wwtlib.WWTControl.singleton;
+    script_interface.add_collectionLoaded(on_wtml_loaded);
+    script_interface.loadImageCollection("https://data1.wwtassets.org/packages/2023/07_jwst/weic2316a/index.wtml");
+}
+
+function on_wtml_loaded() {
+    wwt.setForegroundImageByName("Rho Ophiuchi cloud complex");
+    script_interface.setForegroundOpacity(100);
+    script_interface.add_arrived(on_arrived);
+    wwt.gotoRADecZoom(16.442, -24.385, 1.06, false);
+}
+
+function on_arrived() {
+    wwt.setBackgroundImageByName("PanSTARRS");
+}
+
+window.addEventListener("load", init_wwt);
+```
+
+When you reload your app, you should see WWT zoom in on and load up [a lovely
+JWST image][weic2316a] of ρ Oph:
+
+[weic2316a]: https://esawebb.org/images/weic2316a/
+
+![WWT showing Rho Oph as imaged by JWST](rho-oph.jpg)
+
+Here, the API function
+{{engineapi(p="classes/ScriptInterface.html#loadImageCollection",t="ScriptInterface.loadImageCollection()")}}
+allows us to extend WWT’s built-in corpus of data with additional data sets. We
+register a callback with
+{{engineapi(p="classes/ScriptInterface.html#add_collectionLoaded",t="ScriptInterface.add_collectionLoaded()")}}
+to get notified when the information has been downloaded, at which point we can
+tell the engine to change the foreground to the new image that it has just
+learned about.
+
+<div class="callout callout-note">
+
+Try changing the opacity setting to, say, 50, to transparently blend the
+foreground on top of the background.
+
+</div>
+
+If you load up the URL used here,
+
+> <https://data1.wwtassets.org/packages/2023/07_jwst/weic2316a/index.wtml>
+
+you will see that it is another [WTML collection][wtml], which is stored in
+[XML] format. That WTML file, in turn, points at the actual imagery data, which
+have been processed into WWT’s cloud-friendly tiled formats. This two-step
+approach is an important element of WWT’s data model: while the actual data
+files that WWT displays might be large and slow to download, the WTML files that
+tell the engine *about* data are small and efficient.
+
+[wtml]: https://docs.worldwidetelescope.org/data-guide/1/data-file-formats/collections/
+[XML]: https://en.wikipedia.org/wiki/XML
+
+<div class="callout callout-note">
+
+Once again, other coding models provide slightly more sophisticated interfaces.
+The
+{{helpersapi(p="classes/WWTInstance.html#loadImageCollection",t="WWTInstance.loadImageCollection()")}}
+and
+{{piniaapi(p="functions/engineStore.html#loadImageCollection",t="engineStore().loadImageCollection()")}}
+APIs return promises that resolve to
+{{engineapi(p="classes/Folder.html",t="Folder")}} objects, which provide direct
+access to the information retrieved from the WTML URL.
+
+</div>
+
+<div class="callout callout-note">
+
+WWT can overlay more than two images at once if needed: it has a generic system
+for adding visual
+{{piniaapi(p="functions/engineStore.html#md:general-layer-management",t="layers")}},
+which can be stacked and combined in arbitrary numbers. “Imageset layers” add
+imagery using the same underlying framework as the background/foreground system.
+
+</div>
+
+
+# Getting Data into WWT
+
+These examples are suggesting that WTML files are pretty important to WWT.
+Indeed, they are. The WWT project includes a lot of support tooling to help you
+manage them:
+
+- The [toasty] Python library and CLI tool provide lots of tools for importing
+  images into WWT’s formats, including producing appropriate WTML metadata
+- The [wwt_data_formats] Python library and associated `wwtdatatool` CLI program
+  provide some lower-level tools for working with various WWT data and file
+  formats, including WTML files.
+
+See also the [WWT Data Guide].
+
+[toasty]: https://toasty.readthedocs.io/
+[wwt_data_formats]: https://wwt-data-formats.readthedocs.io/
+[WWT Data Guide]: https://docs.worldwidetelescope.org/data-guide/1/
+
+
+# Callback Hell
+
+You might note that we’re piling up a lot of callbacks here. We sure are!
+There’s a reason that web developers talk about [callback
+hell](http://callbackhell.com) — this style of programming rapidly becomes very
+hard to scale and maintain. **This is why we strongly recommend avoiding plain
+JavaScript when building complex WWT apps.** More sophisticated models like the
+[Vue component model](@/getting-started/vue-component-model.md), or even the
+[TypeScript model](@/getting-started/bundled-typescript-model.md) with `async`
+syntax, take a bit more effort to learn, but provide much better tools for
+managing the complex timing concerns of modern web apps.