@a2f0/skyline 0.2.59 → 0.2.61

package/docs/package.md

@@ -255,7 +255,7 @@ the option out.
 
 ### How the viewer's code loads
 
-The package's module (`lib/`) is a small loader that a host bundles (under 4 KB). When
+The package's module (`lib/`) is a small loader that a host bundles (under 4.5 KB). When
 it mounts, it imports the viewer's code from the assets (`skyline-viewer.js`) with a
 dynamic `import()` that carries `webpackIgnore`, `turbopackIgnore` and `@vite-ignore`
 comments, so webpack (including Next.js with `--webpack`), Turbopack and Vite leave it
@@ -263,13 +263,17 @@ to the browser; Rollup, esbuild and Bun leave an import of a variable alone anyw
 bundler that tried to resolve it would fail to build: tell it to ignore that import.
 The viewer then loads its stylesheets, the scene's markup from `skyline-3d.html`, its
 stars from `stars.svg`, and the scene's modules and models from the same directory.
-Each module loads once per page, however many viewers mount.
+Each module loads once per page, however many viewers mount. So that those modules
+arrive together rather than one import at a time, the loader also reads
+`viewer-modules.json`, which the build writes, and adds a `modulepreload` link for each
+to the document's head, leaving out the vendored engine when the host shares its own;
+the links leave the head once the viewer is ready, fails, or is destroyed.
 
 ### Content security policy and other origins
 
 The viewer runs in the host's page, under the host's content security policy. A host
 with one must allow the assets' origin (usually `'self'`) in `script-src`,
-`style-src` and `connect-src` (the viewer fetches its markup and stars), and inline
+`style-src` and `connect-src` (the viewer fetches its markup, stars and module list), and inline
 styles in `style-src`, which the viewer sets on its elements. Serve the assets from
 the host's origin when you can; on another origin, every file must allow the page's
 origin through CORS. The viewer's code runs with the host page's privileges wherever

package/lib/models/colour-materials.d.ts

@@ -44,3 +44,13 @@ export interface SkylineColour {
     refresh(): void;
 }
 export declare function createSkylineColour(models: readonly BuildingModel[]): SkylineColour;
+/** A colour layer that is made on first use; see `deferSkylineColour`. */
+export interface DeferredSkylineColour extends SkylineColour {
+    /**
+     * Makes the layer now, if it isn't made yet. Call it before anything rewrites the buildings'
+     * colours, such as a celebration's window illumination: the layer reads their greys once,
+     * when it is made.
+     */
+    prepare(): void;
+}
+export declare function deferSkylineColour(models: readonly BuildingModel[]): DeferredSkylineColour;

package/lib/models/colour-materials.js

@@ -506,3 +506,43 @@ export function createSkylineColour(models) {
         },
     };
 }
+// Making the layer reads every vertex of every building, a large share of the scene's start-up
+// time, and changes nothing on screen until colour, a previewed time or a celebration needs it:
+// its facade shaders install only then (colour-reflections.ts). So this one is made on first
+// use, or by `prepare`, from the same buildings and with the sky and night it was given
+// meanwhile, and acts from then on exactly as one made at once.
+export function deferSkylineColour(models) {
+    let layer;
+    let sky, night = null;
+    const made = () => {
+        if (layer)
+            return layer;
+        layer = createSkylineColour(models);
+        if (sky !== undefined)
+            layer.setSky(sky);
+        if (night)
+            layer.setNight(night);
+        return layer;
+    };
+    return {
+        get enabled() { return layer?.enabled ?? false; },
+        prepare() { made(); },
+        set(enabled) {
+            if (layer || enabled)
+                made().set(enabled);
+        },
+        setSky(colours) {
+            sky = colours;
+            layer?.setSky(colours);
+        },
+        setNight(lighting) {
+            night = lighting;
+            if (layer)
+                layer.setNight(lighting);
+            else if (lighting)
+                made();
+        },
+        // Until it is made, nothing shows colour or a previewed night for it to refresh.
+        refresh() { layer?.refresh(); },
+    };
+}

package/lib/skyline-shell.js

@@ -1,6 +1,12 @@
 // The viewer's code and styles, relative to the assets.
 const VIEWER = "skyline-viewer.js";
 const STYLESHEETS = ["study.css", "viewer.css"];
+// The modules the viewer's first frame needs, which the build lists (scripts/build/viewer-modules.ts).
+const MODULES = "viewer-modules.json";
+// The asset directories whose viewers were offered the host's engine: each directory's first
+// scene keeps the engine it took (three-engine.ts), so its later viewers never fetch the
+// vendored one either.
+const sharedEngines = new Set();
 /** The validated, slash-terminated directory the assets are served from. */
 export function assetsBase(document, assetsUrl) {
     const base = new URL(assetsUrl, document.baseURI);
@@ -20,6 +26,19 @@ export function assetsBase(document, assetsUrl) {
 function importViewer(url) {
     return import(/* webpackIgnore: true */ /* @vite-ignore */ /* turbopackIgnore: true */ url);
 }
+/**
+ * Asks the browser to fetch every module the viewer's first frame needs at once, rather than
+ * each only once the module importing it has arrived, a chain several round trips deep. The
+ * links go in the document's head, where modulepreload applies, and leave it once the viewer
+ * settles or is destroyed. The vendored engine is fetched only when no viewer from the same
+ * assets offered the host's Three.js. Preloading only saves time, so a list that fails to load changes nothing else.
+ */
+function preloadModules(document, assets, hostEngine, signal) {
+    return fetch(new URL(MODULES, assets), { signal })
+        .then((response) => response.json())
+        .then(({ modules, engine }) => signal.aborted ? [] : [...(hostEngine || !engine ? [] : [engine]), ...modules].map((file) => document.head.appendChild(Object.assign(document.createElement("link"), { rel: "modulepreload", href: new URL(file, assets).href }))))
+        .catch(() => []);
+}
 /** Resolves once `link` has loaded its stylesheet. */
 function loaded(link) {
     return new Promise((resolve, reject) => {
@@ -79,6 +98,11 @@ export function mountViewer(container, { assetsUrl, title, ...options }) {
     const controller = new AbortController();
     let destroyed = false, mounted = false;
     const context = { ...options, theme, assets, signal: controller.signal };
+    if (options.three)
+        sharedEngines.add(assets.href);
+    const preloads = preloadModules(document, assets, sharedEngines.has(assets.href), controller.signal);
+    const dropPreloads = () => void preloads.then((links) => links.forEach((link) => link.remove()));
+    controller.signal.addEventListener("abort", dropPreloads, { once: true });
     const ready = new Promise((resolve, reject) => {
         Promise.all([importViewer(new URL(VIEWER, assets).href), ...stylesheets.map(loaded)])
             .then(async ([viewer]) => {
@@ -108,7 +132,7 @@ export function mountViewer(container, { assetsUrl, title, ...options }) {
     });
     // The element and the console report a failure, so a host that ignores `ready` sees no
     // unhandled rejection.
-    ready.catch(() => { });
+    ready.then(dropPreloads, dropPreloads);
     return {
         element,
         ready,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/skyline",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "description": "Interactive Chicago skyline viewer and reusable Three.js building models",
   "license": "UNLICENSED",
   "repository": {

package/site/index.html

@@ -10,8 +10,11 @@
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <title>Chicago Skyline — Living Night</title>
     <!-- viewer-page.js mounts the viewer from skyline-viewer.js, its styles and skyline-3d.html,
-         and starts the scene's code; fetch them alongside it. -->
+         and starts the scene's code; fetch them alongside it, with the list of the scene's
+         modules that the viewer's shell preloads. -->
+    <link rel="modulepreload" href="skyline-shell.js" />
     <link rel="modulepreload" href="skyline-viewer.js" />
+    <link rel="preload" href="viewer-modules.json" as="fetch" crossorigin="anonymous" />
     <link rel="preload" href="viewer.css" as="style" />
     <link rel="preload" href="study.css" as="style" />
     <style>

package/site/models/colour-materials.js

@@ -506,3 +506,43 @@ export function createSkylineColour(models) {
         },
     };
 }
+// Making the layer reads every vertex of every building, a large share of the scene's start-up
+// time, and changes nothing on screen until colour, a previewed time or a celebration needs it:
+// its facade shaders install only then (colour-reflections.ts). So this one is made on first
+// use, or by `prepare`, from the same buildings and with the sky and night it was given
+// meanwhile, and acts from then on exactly as one made at once.
+export function deferSkylineColour(models) {
+    let layer;
+    let sky, night = null;
+    const made = () => {
+        if (layer)
+            return layer;
+        layer = createSkylineColour(models);
+        if (sky !== undefined)
+            layer.setSky(sky);
+        if (night)
+            layer.setNight(night);
+        return layer;
+    };
+    return {
+        get enabled() { return layer?.enabled ?? false; },
+        prepare() { made(); },
+        set(enabled) {
+            if (layer || enabled)
+                made().set(enabled);
+        },
+        setSky(colours) {
+            sky = colours;
+            layer?.setSky(colours);
+        },
+        setNight(lighting) {
+            night = lighting;
+            if (layer)
+                layer.setNight(lighting);
+            else if (lighting)
+                made();
+        },
+        // Until it is made, nothing shows colour or a previewed night for it to refresh.
+        refresh() { layer?.refresh(); },
+    };
+}

package/site/skyline-3d.js

@@ -4,7 +4,7 @@ import { chicagoDay, chicagoTime } from "./solar-time.js";
 import { createTimeLighting } from "./time-of-day.js";
 import { createGeographicRoads, geographicOrigin } from "./models/skyline-geography.js";
 import { celebrations } from "./models/celebrations.js";
-import { createDaylight, createSkylineColour, daylightGround } from "./models/colour-materials.js";
+import { createDaylight, daylightGround, deferSkylineColour } from "./models/colour-materials.js";
 import { loadMarkup, loadStylesheet } from "./markup.js";
 // The skyline viewer's full-screen 3D mode: every mapped building, seen through the
 // drawing's own camera and framed as the viewer frames the drawing, so each tower stands
@@ -60,8 +60,9 @@ export function startSkyline3d({ root, frame, assets, signal, colour: initiallyC
         enablePan: true,
         minimumCameraHeight: 1,
     });
-    // The colour trial's layer (models/colour-materials.ts), which the colour toggle turns on.
-    const colour = createSkylineColour(models);
+    // The colour trial's layer (models/colour-materials.ts), which the colour toggle turns on. It
+    // is made on first use rather than before the first frame, which it does not change.
+    const colour = deferSkylineColour(models);
     // A toolbar badge applies one celebration across the skyline, using each
     // building's own supported wording. Context menus change only their building.
     const illuminated = models.filter((model) => model.illumination);
@@ -69,6 +70,8 @@ export function startSkyline3d({ root, frame, assets, signal, colour: initiallyC
     const celebrationAnnouncement = root.querySelector("#celebration-announcement");
     const celebrationButtons = [...root.querySelectorAll("[data-celebration]")];
     function setCelebration(targets, next) {
+        // The colour layer reads the buildings' greys before the lights rewrite them.
+        colour.prepare();
         targets.forEach((model) => model.illumination.set(model.illumination.presets.some(({ id }) => id === next) ? next : null));
         colour.refresh();
         for (const button of celebrationButtons) {

package/site/skyline-shell.js

@@ -1,6 +1,12 @@
 // The viewer's code and styles, relative to the assets.
 const VIEWER = "skyline-viewer.js";
 const STYLESHEETS = ["study.css", "viewer.css"];
+// The modules the viewer's first frame needs, which the build lists (scripts/build/viewer-modules.ts).
+const MODULES = "viewer-modules.json";
+// The asset directories whose viewers were offered the host's engine: each directory's first
+// scene keeps the engine it took (three-engine.ts), so its later viewers never fetch the
+// vendored one either.
+const sharedEngines = new Set();
 /** The validated, slash-terminated directory the assets are served from. */
 export function assetsBase(document, assetsUrl) {
     const base = new URL(assetsUrl, document.baseURI);
@@ -20,6 +26,19 @@ export function assetsBase(document, assetsUrl) {
 function importViewer(url) {
     return import(/* webpackIgnore: true */ /* @vite-ignore */ /* turbopackIgnore: true */ url);
 }
+/**
+ * Asks the browser to fetch every module the viewer's first frame needs at once, rather than
+ * each only once the module importing it has arrived, a chain several round trips deep. The
+ * links go in the document's head, where modulepreload applies, and leave it once the viewer
+ * settles or is destroyed. The vendored engine is fetched only when no viewer from the same
+ * assets offered the host's Three.js. Preloading only saves time, so a list that fails to load changes nothing else.
+ */
+function preloadModules(document, assets, hostEngine, signal) {
+    return fetch(new URL(MODULES, assets), { signal })
+        .then((response) => response.json())
+        .then(({ modules, engine }) => signal.aborted ? [] : [...(hostEngine || !engine ? [] : [engine]), ...modules].map((file) => document.head.appendChild(Object.assign(document.createElement("link"), { rel: "modulepreload", href: new URL(file, assets).href }))))
+        .catch(() => []);
+}
 /** Resolves once `link` has loaded its stylesheet. */
 function loaded(link) {
     return new Promise((resolve, reject) => {
@@ -79,6 +98,11 @@ export function mountViewer(container, { assetsUrl, title, ...options }) {
     const controller = new AbortController();
     let destroyed = false, mounted = false;
     const context = { ...options, theme, assets, signal: controller.signal };
+    if (options.three)
+        sharedEngines.add(assets.href);
+    const preloads = preloadModules(document, assets, sharedEngines.has(assets.href), controller.signal);
+    const dropPreloads = () => void preloads.then((links) => links.forEach((link) => link.remove()));
+    controller.signal.addEventListener("abort", dropPreloads, { once: true });
     const ready = new Promise((resolve, reject) => {
         Promise.all([importViewer(new URL(VIEWER, assets).href), ...stylesheets.map(loaded)])
             .then(async ([viewer]) => {
@@ -108,7 +132,7 @@ export function mountViewer(container, { assetsUrl, title, ...options }) {
     });
     // The element and the console report a failure, so a host that ignores `ready` sees no
     // unhandled rejection.
-    ready.catch(() => { });
+    ready.then(dropPreloads, dropPreloads);
     return {
         element,
         ready,

package/site/viewer-modules.json

@@ -0,0 +1,62 @@
+{
+  "modules": [
+    "markup.js",
+    "three-engine.js",
+    "skyline-3d.js",
+    "study-viewer.js",
+    "vendor/three-r186.js",
+    "skyline-scene.js",
+    "models/skyline-geography-data.js",
+    "models/skyline-geography.js",
+    "models/building-kit.js",
+    "models/aon-geographic.js",
+    "models/aon-tower.js",
+    "models/facade-grid.js",
+    "models/blue-cross-geographic.js",
+    "models/window-illumination.js",
+    "models/celebrations.js",
+    "models/borg-warner-geographic.js",
+    "models/buckingham-geographic.js",
+    "models/chicago-athletic-association-geographic.js",
+    "models/crain-geographic.js",
+    "models/crain-tower.js",
+    "models/gage-geographic.js",
+    "models/heritage-geographic.js",
+    "models/hyatt-west-tower-geographic.js",
+    "models/keith-ascher-geographic.js",
+    "models/kemper-geographic.js",
+    "models/lake-view-geographic.js",
+    "models/maclean-center-geographic.js",
+    "models/michigan-boulevard-geographic.js",
+    "models/michigan-plaza-south-geographic.js",
+    "models/millennium-park-plaza-geographic.js",
+    "models/monroe-geographic.js",
+    "models/north-michigan-180-geographic.js",
+    "models/north-wabash-geographic.js",
+    "models/on-the-park-geographic.js",
+    "models/one-prudential-geographic.js",
+    "models/one-prudential-tower.js",
+    "models/peoples-gas-geographic.js",
+    "models/railway-exchange-geographic.js",
+    "models/river-plaza-geographic.js",
+    "models/sheraton-grand-geographic.js",
+    "models/six-north-michigan-geographic.js",
+    "models/swissotel-geographic.js",
+    "models/three-illinois-center-geographic.js",
+    "models/trump-geographic.js",
+    "models/trump-tower.js",
+    "models/two-illinois-center-geographic.js",
+    "models/two-prudential-geographic.js",
+    "models/two-prudential-tower.js",
+    "models/university-club-geographic.js",
+    "models/willoughby-tower-geographic.js",
+    "solar-time.js",
+    "time-of-day.js",
+    "models/colour-materials.js",
+    "models/colour-palette.js",
+    "models/colour-reflections.js",
+    "models/night-windows.js",
+    "models/material-names.js"
+  ],
+  "engine": "vendor/three-r186.bundle.js"
+}