@a2f0/skyline 0.2.20 → 0.2.23

package/site/models/colour-materials.js

@@ -1,6 +1,7 @@
 import * as THREE from "../vendor/three-r186.js";
 import { daylightColours, measuredColours } from "./colour-palette.js";
-import { glassReflection } from "./colour-reflections.js";
+import { glassReflection, daylightReflections } from "./colour-reflections.js";
+import { nightWindowMask } from "./night-windows.js";
 // The colour trial (https://github.com/a2f0/skyline/issues/115): which named material each
 // surface of each building is, and a layer that shows the colours measured for those materials
 // (colour-palette.ts) over the greys the models build in, restoring the greys exactly when it is
@@ -358,9 +359,16 @@ export function createDaylight() {
 // another batch already took, since the builder lets batches share them.
 export function createSkylineColour(models) {
     const painted = [], flat = [], taken = new Set();
-    const reflections = [];
+    const facades = [];
+    const outlines = [];
+    let night = null;
     const glassMaterials = new Set(["glass", "green glass", "blue-green glass", "bronze glass", "crown glass", "lit window", "dim window"]);
     for (const model of models) {
+        model.building.traverse((object) => {
+            const line = object;
+            if (line.isLineSegments && line.material instanceof THREE.LineBasicMaterial)
+                outlines.push({ material: line.material, opacity: line.material.opacity });
+        });
         const buildingId = String(model.building.userData["buildingId"]);
         if (!measuredColours[buildingId])
             continue;
@@ -381,7 +389,13 @@ export function createSkylineColour(models) {
                 return;
             const [base, tones = {}] = batch;
             const material = mesh.material;
-            const materialOf = (grey) => tones[toneOf(grey)] ?? base;
+            const names = new Map();
+            const materialOf = (grey) => {
+                let name = names.get(grey);
+                if (!name)
+                    names.set(grey, name = tones[toneOf(grey)] ?? base);
+                return name;
+            };
             const attribute = mesh.geometry.getAttribute("color");
             if (material.vertexColors) {
                 if (!(attribute?.array instanceof Float32Array) || taken.has(attribute))
@@ -413,8 +427,9 @@ export function createSkylineColour(models) {
                 }
                 mask[vertex] = reflects;
             }
-            if (mask.some((value) => value > 0))
-                reflections.push(glassReflection(material, geometry, mask));
+            const windows = nightWindowMask(geometry, buildingId, (vertex) => materialOf(colours ? colours.array[vertex * 3] : material.color.r));
+            if (mask.some((value) => value > 0) || windows.some((value) => value > 0))
+                facades.push({ light: glassReflection(material, geometry, mask, windows), model });
             const colourOf = (grey) => {
                 const swatch = swatches.get(materialOf(grey));
                 return swatch ? paint(grey, swatch) : [grey, grey, grey];
@@ -435,6 +450,12 @@ export function createSkylineColour(models) {
         }
     }
     let enabled = false;
+    function updateNight() {
+        for (const { light, model } of facades)
+            light.setNight(night, enabled, Boolean(model.illumination?.active));
+        for (const { material, opacity } of outlines)
+            material.opacity = opacity * (night?.outlineStrength ?? 1);
+    }
     return {
         get enabled() { return enabled; },
         set(next) {
@@ -459,10 +480,20 @@ export function createSkylineColour(models) {
             }
             for (const { material, grey, colour } of flat)
                 material.color.copy(next ? colour : grey);
-            for (const reflect of reflections)
-                reflect(next);
+            for (const { light } of facades)
+                light(next);
+            updateNight();
+        },
+        setSky(colours) {
+            for (const { light } of facades)
+                light.setSky(colours ?? daylightReflections);
+        },
+        setNight(lighting) {
+            night = lighting;
+            updateNight();
         },
         refresh() {
+            updateNight();
             if (!enabled)
                 return;
             for (const batch of painted) {

package/site/models/colour-palette.js

@@ -290,3 +290,14 @@ export const measuredColours = {
 // above the horizon, each the median of a clear box of the same panorama (scripts/sample-colours.ts,
 // the day study's sky), and the sun's warm white, chosen.
 export const daylightColours = { sky: 0x9ebbdb, horizon: 0xc4d1e1, sun: 0xfff4e6 };
+// Art-directed night illumination: quiet cool facades and a mix of warm office lamps.
+export const nightColours = { ambient: 0xa1afc8, fill: 0x8d9fbd, window: 0xffcf91, windowWhite: 0xffedce };
+// Illustrated clear-sky time previews. Solar elevation chooses the stops; these are
+// artistic colours, separate from the photograph-calibrated daytime palette above.
+export const timeOfDayColours = [
+    { elevation: -18, sky: 0x02040c, horizon: 0x080d1b, sun: 0xffb077 },
+    { elevation: -8, sky: 0x142345, horizon: 0x5b526e, sun: 0xffad76 },
+    { elevation: -2, sky: 0x415b89, horizon: 0xe89b79, sun: 0xffb477 },
+    { elevation: 6, sky: 0x829fc5, horizon: 0xf0c3a0, sun: 0xffd4a8 },
+    { elevation: 25, ...daylightColours },
+];

package/site/models/colour-reflections.js

@@ -1,32 +1,51 @@
 import * as THREE from "../vendor/three-r186.js";
-import { daylightColours } from "./colour-palette.js";
+import { daylightColours, nightColours } from "./colour-palette.js";
+export const daylightReflections = { ...daylightColours, ground: 0x444444 };
 // A small sky reflection over the measured glass colour. This is an illustration of an open
 // sky, not a reflection of nearby buildings or a replacement for the toon renderer. The mask
 // separates glass from masonry and mullions even when the builder batches them in one mesh.
-// Install only in colour mode, and restore the original shader on exit. Keep the mask attached
-// once used so Three.js releases its GPU buffer when it disposes the geometry.
-export function glassReflection(material, geometry, mask) {
+// The same shader adds night-window emission, independently of material colour. Restore the
+// original shader outside colour/time previews. Keep attributes attached once used so Three.js
+// releases their GPU buffers when it disposes the geometry.
+export function glassReflection(material, geometry, mask, windows = new Float32Array(mask.length * 4)) {
     const attribute = new THREE.Float32BufferAttribute(mask, 1);
+    const windowAttribute = new THREE.Float32BufferAttribute(windows, 4);
     const originalCompile = material.onBeforeCompile, originalKey = material.customProgramCacheKey;
     const key = originalKey.call(material);
     const uniforms = {
         skylineSky: { value: new THREE.Color(daylightColours.sky) },
         skylineHorizon: { value: new THREE.Color(daylightColours.horizon) },
         skylineGround: { value: new THREE.Color(0x444444) },
+        skylineReflecting: { value: 0 },
+        skylineDarkness: { value: 0 },
+        skylineActivity: { value: 0 },
+        skylineWindowsSuppressed: { value: 0 },
+        skylineWindowWarm: { value: new THREE.Color(nightColours.window) },
+        skylineWindowWhite: { value: new THREE.Color(nightColours.windowWhite) },
     };
     const compile = (shader, renderer) => {
         originalCompile.call(material, shader, renderer);
         Object.assign(shader.uniforms, uniforms);
         shader.vertexShader = shader.vertexShader.replace("#include <common>", `#include <common>
 attribute float skylineGlass;
-varying float vSkylineGlass;`).replace("#include <begin_vertex>", `#include <begin_vertex>
-vSkylineGlass = skylineGlass;`);
+attribute vec4 skylineWindow;
+varying float vSkylineGlass;
+varying vec4 vSkylineWindow;`).replace("#include <begin_vertex>", `#include <begin_vertex>
+vSkylineGlass = skylineGlass;
+vSkylineWindow = skylineWindow;`);
         shader.fragmentShader = shader.fragmentShader.replace("#include <common>", `#include <common>
 varying float vSkylineGlass;
+varying vec4 vSkylineWindow;
 uniform vec3 skylineSky;
 uniform vec3 skylineHorizon;
-uniform vec3 skylineGround;`).replace("#include <opaque_fragment>", `
-if (vSkylineGlass > 0.0) {
+uniform vec3 skylineGround;
+uniform float skylineReflecting;
+uniform float skylineDarkness;
+uniform float skylineActivity;
+uniform float skylineWindowsSuppressed;
+uniform vec3 skylineWindowWarm;
+uniform vec3 skylineWindowWhite;`).replace("#include <opaque_fragment>", `
+if (vSkylineGlass > 0.0 && skylineReflecting > 0.0) {
   vec3 eye = vec3(0.0);
   eye.z = 1.0;
   if (!isOrthographic) eye = normalize(vViewPosition);
@@ -36,18 +55,58 @@ if (vSkylineGlass > 0.0) {
   float grazing = pow(1.0 - clamp(dot(normal, eye), 0.0, 1.0), 5.0);
   outgoingLight = mix(outgoingLight, environment, vSkylineGlass * (0.06 + 0.54 * grazing));
 }
+if (vSkylineWindow.z > 0.0 && skylineDarkness > 0.0) {
+  float occupied = 1.0 - smoothstep(skylineActivity - 0.05, skylineActivity + 0.05, vSkylineWindow.x);
+  float dusk = smoothstep(0.12 + 0.35 * vSkylineWindow.x, 0.45 + 0.35 * vSkylineWindow.x, skylineDarkness);
+  float light = vSkylineWindow.z > 1.5 ? skylineDarkness : occupied * dusk * (1.0 - skylineWindowsSuppressed);
+  vec3 lamp = mix(skylineWindowWarm, skylineWindowWhite, vSkylineWindow.w);
+  outgoingLight += lamp * vSkylineWindow.y * light;
+}
 #include <opaque_fragment>`);
     };
-    return (enabled) => {
+    let reflecting = false, night = false, installed = false;
+    function install() {
+        const enabled = reflecting || night;
+        if (enabled === installed)
+            return;
+        installed = enabled;
         if (enabled) {
             geometry.setAttribute("skylineGlass", attribute);
+            geometry.setAttribute("skylineWindow", windowAttribute);
             material.onBeforeCompile = compile;
-            material.customProgramCacheKey = () => `${key}:skyline-glass-v1`;
+            material.customProgramCacheKey = () => `${key}:skyline-facade-v2`;
         }
         else {
             material.onBeforeCompile = originalCompile;
             material.customProgramCacheKey = originalKey;
         }
         material.needsUpdate = true;
+    }
+    const set = (enabled) => {
+        reflecting = enabled;
+        uniforms.skylineReflecting.value = enabled ? 1 : 0;
+        install();
     };
+    return Object.assign(set, {
+        setSky(colours) {
+            uniforms.skylineSky.value.setHex(colours.sky);
+            uniforms.skylineHorizon.value.setHex(colours.horizon);
+            uniforms.skylineGround.value.setHex(colours.ground);
+        },
+        setNight(lighting, coloured, celebration) {
+            night = lighting !== null;
+            // A deliberately composed celebration takes precedence over ordinary office rooms.
+            uniforms.skylineDarkness.value = lighting?.darkness ?? 0;
+            uniforms.skylineWindowsSuppressed.value = celebration ? 1 : 0;
+            uniforms.skylineActivity.value = lighting?.activity ?? 0;
+            for (const [uniform, hex] of [[uniforms.skylineWindowWarm, nightColours.window], [uniforms.skylineWindowWhite, nightColours.windowWhite]]) {
+                uniform.value.setHex(hex);
+                if (!coloured) {
+                    const { r, g, b } = uniform.value, grey = r * 0.2126 + g * 0.7152 + b * 0.0722;
+                    uniform.value.setRGB(grey, grey, grey);
+                }
+            }
+            install();
+        },
+    });
 }

package/site/models/night-windows.js

@@ -0,0 +1,76 @@
+export const smooth = (low, high, value) => {
+    const t = Math.max(0, Math.min(1, (value - low) / (high - low)));
+    return t * t * (3 - 2 * t);
+};
+// A continuous daily cycle: busy evenings, a few overnight rooms, then early arrivals.
+// Midnight shares the same curve from either side, including when scrubbing backwards.
+export function windowActivity(hour) {
+    const late = hour < 12 ? hour + 24 : hour;
+    return 0.76 - 0.52 * smooth(21, 26, late) + 0.3 * smooth(29, 32, late) + (hour < 12 ? 0.22 * smooth(8, 12, hour) : 0);
+}
+function hash(value) {
+    let seed = 2166136261;
+    for (const character of value)
+        seed = Math.imul(seed ^ character.charCodeAt(0), 16777619);
+    // Avalanche adjacent room keys: plain FNV leaves trailing bay digits correlated,
+    // making a whole east-facing floor turn on together instead of small room groups.
+    seed = Math.imul(seed ^ (seed >>> 16), 0x85ebca6b);
+    seed = Math.imul(seed ^ (seed >>> 13), 0xc2b2ae35);
+    seed ^= seed >>> 16;
+    return (seed >>> 0) / 4294967296;
+}
+const architectural = new Set(["lamp", "crown lights", "band lights", "sign letters", "cap lights"]);
+// The building kit emits panes as paired triangles, interspersed with standalone
+// triangles for other features. Find shared edges rather than assuming quad alignment.
+// Reuse those exact surfaces;
+// never turn a generic glass shell, spandrel, masonry face or roof into a light source.
+// Adjacent bays share a floor/room seed, so offices come on in small groups. Identity
+// depends on local geometry and building ID, not load order, camera or slider direction.
+export function nightWindowMask(geometry, buildingId, materialOf) {
+    const positions = geometry.getAttribute("position"), normals = geometry.getAttribute("normal");
+    const mask = new Float32Array(positions.count * 4);
+    const samePoint = (a, b) => positions.getX(a) === positions.getX(b) && positions.getY(a) === positions.getY(b) && positions.getZ(a) === positions.getZ(b);
+    for (let first = 0; first < positions.count;) {
+        const name = materialOf(first), crown = architectural.has(name);
+        const window = name === "lit window" || name === "dim window";
+        if (!crown && (!window || Math.abs(normals.getY(first)) > 0.5)) {
+            first += 3;
+            continue;
+        }
+        let count = 3;
+        if (first + 6 <= positions.count && materialOf(first + 3) === name
+            && normals.getX(first) === normals.getX(first + 3) && normals.getY(first) === normals.getY(first + 3) && normals.getZ(first) === normals.getZ(first + 3)) {
+            let shared = 0;
+            for (let a = first; a < first + 3; a += 1) {
+                for (let b = first + 3; b < first + 6; b += 1)
+                    if (samePoint(a, b)) {
+                        shared += 1;
+                        break;
+                    }
+            }
+            if (shared === 2)
+                count = 6;
+        }
+        const end = first + count;
+        let x = 0, y = 0, z = 0;
+        for (let vertex = first; vertex < end; vertex += 1) {
+            x += positions.getX(vertex);
+            y += positions.getY(vertex);
+            z += positions.getZ(vertex);
+        }
+        const floor = Math.round(y / count / 3.4), across = Math.floor(x / count / 7), depth = Math.floor(z / count / 7);
+        const room = hash(`${buildingId}:${floor}:${across}:${depth}`);
+        const brightness = hash(`${buildingId}:${floor}:${across}:${depth}:brightness`);
+        for (let vertex = first; vertex < end; vertex += 1) {
+            if (materialOf(vertex) !== name)
+                continue;
+            const rank = name === "lit window" ? 0.05 + room * 0.8 : 0.3 + room * 0.75;
+            mask[vertex * 4] = rank;
+            mask[vertex * 4 + 1] = crown ? 0.3 : 0.25 + brightness * 0.45;
+            mask[vertex * 4 + 2] = crown ? 2 : 1;
+            mask[vertex * 4 + 3] = brightness;
+        }
+        first = end;
+    }
+    return mask;
+}

package/site/skyline-3d.html

@@ -56,6 +56,12 @@
         <button type="button" id="colour" aria-pressed="false" title="Colour trial: a sunny day, each measured building in its photographed colours; the rest stay grey">colour</button>
         <button type="button" id="turntable" aria-pressed="false" aria-describedby="motion-status">turntable</button>
         <button type="button" id="show-original" title="Compare with the original skyline SVG" hidden>show original</button>
+        <div class="time-controls">
+          <label for="time-of-day"><span id="time-caption">Chicago time</span> <span id="time-date"></span></label>
+          <input id="time-of-day" type="range" min="0" max="1439" step="1" value="0" aria-labelledby="time-caption" />
+          <output id="time-value" for="time-of-day" aria-live="off">original night</output>
+          <button type="button" id="reset-light" disabled title="Restore the original lighting preset">reset light</button>
+        </div>
         <div class="celebration-controls" id="celebration-controls" role="group" aria-label="Celebratory window lighting">
           <span class="celebration-caption">lights</span>
           <button type="button" data-celebration="bulls" aria-label="Bulls lighting" aria-pressed="false">

package/site/skyline-3d.js

@@ -1,6 +1,8 @@
 import { createBuildingStudy, frameBox } from "./study-viewer.js";
 import { createGeographicSkyline } from "./skyline-scene.js";
-import { createGeographicRoads } from "./models/skyline-geography.js";
+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 { loadMarkup, loadStylesheet } from "./markup.js";
@@ -109,26 +111,60 @@ export function startSkyline3d({ root, frame, assets, signal, colour: initiallyC
             viewer.requestRender();
         }, listening);
     }
-    // The colour trial's toggle, pressed while the scene shows a sunny day, the measured buildings in
-    // their colours over the greys; pressed again, it restores the night and every grey exactly.
+    // Preserve the original grey/day presets until time is scrubbed. Once previewing,
+    // material colour and time are independent; reset light returns to the chosen preset.
     const colourButton = root.querySelector("#colour");
     const roadway = roads.material;
+    const timeInput = root.querySelector("#time-of-day");
+    const timeOutput = root.querySelector("#time-value");
+    const timeReset = root.querySelector("#reset-light");
+    const day = chicagoDay(new Date());
+    root.querySelector("#time-date").textContent = day.label;
+    timeInput.max = String(day.minutes - 1);
+    const timeLight = createTimeLighting(geographicOrigin[1], geographicOrigin[0], root instanceof ShadowRoot);
+    let selectedTime = null;
     let daylight;
     let detailView;
-    signal.addEventListener("abort", () => daylight?.sky.dispose(), { once: true });
+    signal.addEventListener("abort", () => { daylight?.sky.dispose(); timeLight.dispose(); }, { once: true });
     function setColour(enabled) {
         colour.set(enabled);
-        if (enabled)
-            daylight ??= createDaylight();
-        roadway.color.setHex(colour.enabled ? daylightGround.roads : nightRoads);
-        viewer.setDaylight(colour.enabled ? daylight : null);
-        colourButton.setAttribute("aria-pressed", String(colour.enabled));
-        colourButton.title = enabled ? "Restore the greyscale skyline" : "Show the skyline in sunny-day colour";
-        detailView?.setColour(enabled);
+        if (selectedTime) {
+            const lighting = timeLight.update(selectedTime, enabled);
+            colour.setSky(lighting.reflections);
+            colour.setNight(lighting.night);
+            roadway.color.setHex(lighting.roads);
+            viewer.setDaylight(lighting);
+            timeOutput.value = chicagoTime(selectedTime);
+        }
+        else {
+            if (enabled)
+                daylight ??= createDaylight();
+            colour.setSky(null);
+            colour.setNight(null);
+            roadway.color.setHex(enabled ? daylightGround.roads : nightRoads);
+            viewer.setDaylight(enabled ? daylight : null);
+            timeInput.value = enabled ? "720" : "0";
+            timeOutput.value = enabled ? "sunny day" : "original night";
+        }
+        timeReset.disabled = !selectedTime;
+        timeInput.setAttribute("aria-valuetext", `${timeOutput.value}, ${day.label}, Chicago${selectedTime ? "" : ", move to preview a time"}`);
+        colourButton.setAttribute("aria-pressed", String(enabled));
+        colourButton.title = selectedTime ? (enabled ? "Show this time in greyscale" : "Show this time in colour")
+            : enabled ? "Restore the greyscale skyline" : "Show the skyline in sunny-day colour";
+        detailView?.setTime(selectedTime, enabled);
     }
+    timeInput.addEventListener("input", () => {
+        const firstPreview = selectedTime === null;
+        selectedTime = new Date(day.start + timeInput.valueAsNumber * 60_000);
+        setColour(firstPreview || colour.enabled);
+    }, listening);
+    timeReset.addEventListener("click", () => {
+        timeInput.focus({ preventScroll: true });
+        selectedTime = null;
+        setColour(colour.enabled);
+    }, listening);
     colourButton.addEventListener("click", () => setColour(!colour.enabled), listening);
-    if (initiallyColoured)
-        setColour(true);
+    setColour(initiallyColoured);
     // The star in the middle of the bar opens and closes the toolbar. Each group unfolds from
     // the star: clipped open from its `--fold` inset while it fades in, one beside the star
     // slides out from it to its edge of the bar, and it folds back the same way before it hides. A toggle mid-way reverses the moving
@@ -412,6 +448,7 @@ export function startSkyline3d({ root, frame, assets, signal, colour: initiallyC
             markup.classList.add("framed");
             detailRoot.append(document.importNode(markup, true));
             detailView = showBuildingDetail({ root: detailRoot, id, frame: detailRoot.querySelector(".detail-root"), signal: controller.signal, colour: colour.enabled, onColourChange: setColour });
+            detailView?.setTime(selectedTime, colour.enabled);
         }).catch((error) => {
             if (controller.signal.aborted)
                 return;

package/site/skyline-shell.js

@@ -33,7 +33,7 @@ function loaded(link) {
 // mirroring the viewer's layout, and the rest sizes it to fill the container.
 const HOST_STYLE = "all:initial;direction:ltr;display:block;position:relative;isolation:isolate;width:100%;height:100%;overflow:hidden";
 // The failure message's own look, since the viewer's stylesheets may be what failed.
-const FAILURE_STYLE = "box-sizing:border-box;height:100%;margin:0;padding:24px;background:#000;color:#aaa;font:12px/1.5 ui-monospace,monospace";
+const FAILURE_STYLE = "box-sizing:border-box;height:100%;margin:0;padding:24px;background:inherit;color:inherit;font:12px/1.5 ui-monospace,monospace";
 /** Shows why the viewer couldn't start, in place of the viewer. */
 function showFailure(root, error) {
     const message = root.ownerDocument.createElement("p");
@@ -49,8 +49,16 @@ function showFailure(root, error) {
 export function mountViewer(container, { assetsUrl, title, ...options }) {
     const document = container.ownerDocument;
     const assets = assetsBase(document, assetsUrl);
+    const theme = options.theme === undefined ? (options.colour ? "light" : "dark") : options.theme;
+    if (theme !== "light" && theme !== "dark")
+        throw new TypeError('Skyline theme must be "light" or "dark".');
     const element = document.createElement("div");
     element.style.cssText = HOST_STYLE;
+    // Paint before any assets arrive, including when a stylesheet fails to load.
+    // Keep the boot palette in sync with viewer.css and index.html.
+    element.style.colorScheme = theme;
+    element.style.backgroundColor = theme === "light" ? "#f5f5f5" : "#000";
+    element.style.color = theme === "light" ? "#444" : "#aaa";
     element.setAttribute("role", "region");
     element.setAttribute("aria-label", title);
     element.setAttribute("aria-busy", "true");
@@ -70,7 +78,7 @@ export function mountViewer(container, { assetsUrl, title, ...options }) {
         Promise.resolve(options.three).catch(() => { });
     const controller = new AbortController();
     let destroyed = false, mounted = false;
-    const context = { ...options, assets, signal: controller.signal };
+    const context = { ...options, theme, assets, signal: controller.signal };
     const ready = new Promise((resolve, reject) => {
         Promise.all([importViewer(new URL(VIEWER, assets).href), ...stylesheets.map(loaded)])
             .then(async ([viewer]) => {

package/site/skyline-viewer.js

@@ -22,7 +22,7 @@ function element(document, tag, properties = {}, attributes = {}) {
         created.setAttribute(name, value);
     return created;
 }
-export function mount(root, { assets, signal, controls, colour, attribution, navigation, page, three }) {
+export function mount(root, { assets, signal, controls, colour, theme, attribution, navigation, page, three }) {
     const document = root.ownerDocument;
     const host = root.host;
     const listening = { signal };
@@ -35,6 +35,7 @@ export function mount(root, { assets, signal, controls, colour, attribution, nav
     const sceneMarkup = loadMarkup(new URL("skyline-3d.html", assets), signal);
     sceneMarkup.catch(() => { });
     const viewer = element(document, "div", { className: "skyline-viewer" });
+    viewer.dataset["theme"] = theme;
     if (!navigation)
         viewer.dataset["embedded"] = "";
     const stars = element(document, "div", { className: "stars", id: "stars" }, { "aria-hidden": "true" });
@@ -52,6 +53,7 @@ export function mount(root, { assets, signal, controls, colour, attribution, nav
     const frames = {};
     const toolbar = navigation ? createToolbar() : null;
     function updateView() {
+        viewer.toggleAttribute("data-booting", sceneUnavailable && mode === "3d");
         scene.hidden = mode !== "3d";
         if (mode === "original" && !drawing.getAttribute("src"))
             drawing.src = new URL("skyline-original-fit.svg", assets).href;
@@ -201,7 +203,7 @@ export function mount(root, { assets, signal, controls, colour, attribution, nav
             // As the scene's own page says it: its controls stay, disabled, and the drawing one
             // press away.
             scene.querySelector("#loading").textContent = SCENE_FAILURE;
-            scene.querySelectorAll("button").forEach((button) => { button.disabled = true; });
+            scene.querySelectorAll("button, input").forEach((control) => { control.disabled = true; });
             throw error;
         }
     }

package/site/solar-time.js

@@ -0,0 +1,53 @@
+const radians = Math.PI / 180;
+const minute = 60_000;
+const chicago = new Intl.DateTimeFormat("en-US", { timeZone: "America/Chicago", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", hourCycle: "h23" });
+const clock = new Intl.DateTimeFormat("en-US", { timeZone: "America/Chicago", hour: "numeric", minute: "2-digit", timeZoneName: "short" });
+function parts(date) {
+    const values = Object.fromEntries(chicago.formatToParts(date).map(({ type, value }) => [type, Number(value)]));
+    return { year: values["year"], month: values["month"], day: values["day"], hour: values["hour"], minute: values["minute"] };
+}
+// Chicago's midnight is unambiguous even on clock-change dates. Resolve each end
+// separately: those days contain 23 or 25 hours, and both repeated hours are reachable.
+function midnight(year, month, day) {
+    const wall = Date.UTC(year, month - 1, day);
+    let instant = wall;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const p = parts(new Date(instant));
+        instant += wall - Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute);
+    }
+    return instant;
+}
+export function chicagoDay(now) {
+    const { year, month, day } = parts(now);
+    const start = midnight(year, month, day), end = midnight(year, month, day + 1);
+    return {
+        start,
+        minutes: (end - start) / minute,
+        label: new Intl.DateTimeFormat("en-US", { timeZone: "America/Chicago", month: "short", day: "numeric", year: "numeric" }).format(now),
+    };
+}
+export const chicagoTime = (date) => clock.format(date);
+export const chicagoHour = (date) => {
+    const { hour, minute: minutes } = parts(date);
+    return hour + minutes / 60;
+};
+// NOAA's general solar-position equations (geometric elevation, no refraction):
+// https://gml.noaa.gov/grad/solcalc/solareqns.PDF
+// An absolute instant and east-positive longitude avoid browser time-zone/DST offsets.
+export function solarPosition(date, latitude, longitude) {
+    const year = date.getUTCFullYear(), start = Date.UTC(year, 0, 1);
+    const days = (Date.UTC(year + 1, 0, 1) - start) / 86_400_000;
+    const fraction = 2 * Math.PI / days * ((date.getTime() - start) / 86_400_000 - 0.5);
+    const equation = 229.18 * (0.000075 + 0.001868 * Math.cos(fraction) - 0.032077 * Math.sin(fraction)
+        - 0.014615 * Math.cos(2 * fraction) - 0.040849 * Math.sin(2 * fraction));
+    const declination = 0.006918 - 0.399912 * Math.cos(fraction) + 0.070257 * Math.sin(fraction)
+        - 0.006758 * Math.cos(2 * fraction) + 0.000907 * Math.sin(2 * fraction)
+        - 0.002697 * Math.cos(3 * fraction) + 0.00148 * Math.sin(3 * fraction);
+    const utcMinutes = date.getUTCHours() * 60 + date.getUTCMinutes() + date.getUTCSeconds() / 60;
+    const hour = ((utcMinutes + equation + 4 * longitude) / 4 - 180) * radians;
+    const lat = latitude * radians;
+    const east = -Math.cos(declination) * Math.sin(hour);
+    const north = Math.cos(lat) * Math.sin(declination) - Math.sin(lat) * Math.cos(declination) * Math.cos(hour);
+    const up = Math.sin(lat) * Math.sin(declination) + Math.cos(lat) * Math.cos(declination) * Math.cos(hour);
+    return { elevation: Math.asin(Math.max(-1, Math.min(1, up))) / radians, direction: [east, up, -north] };
+}

package/site/study-loader.js

@@ -3,7 +3,7 @@
     const entry = document.currentScript.dataset["study"];
     function showStudyError(message) {
         document.querySelector("#loading").textContent = message;
-        document.querySelectorAll("button").forEach((button) => { button.disabled = true; });
+        document.querySelectorAll("button, input").forEach((control) => { control.disabled = true; });
     }
     if (location.protocol === "file:") {
         const page = location.pathname.split("/").pop();

package/site/study-viewer.js

@@ -109,6 +109,7 @@ export function createBuildingStudy({ models, defaultView = "quarter", views = {
     const night = { sun: [0xffffff, 2.4], ambient: [0xffffff, 0.7], fill: [0xffffff, 0.55] };
     const ambientLight = new THREE.AmbientLight(...night.ambient);
     scene.add(ambientLight);
+    let lightBounds;
     const keyLight = new THREE.DirectionalLight(...night.sun);
     keyLight.position.fromArray(lightPosition);
     keyLight.target.position.set(0, 80, 0);
@@ -489,6 +490,7 @@ export function createBuildingStudy({ models, defaultView = "quarter", views = {
         const next = { ...original, ...layouts?.[name] };
         layout = name;
         ({ models, fit, target, platform, lightPosition, shadowCamera, clippingMargin } = next);
+        lightBounds = undefined;
         extras = next.extras || [];
         models.forEach((model) => { scene.add(model.building); model.setWireframe(wireframe); });
         extras.forEach((object) => scene.add(object));
@@ -501,6 +503,7 @@ export function createBuildingStudy({ models, defaultView = "quarter", views = {
         base.position.set(platform.x || 0, -1.1, platform.z || 0);
         baseEdges.position.copy(base.position);
         keyLight.position.fromArray(lightPosition);
+        keyLight.target.position.set(0, 80, 0);
         Object.assign(keyLight.shadow.camera, shadowCamera);
         keyLight.shadow.camera.updateProjectionMatrix();
         const nextView = previousView && previousView !== defaultView ? previousView : next.defaultView || defaultView;
@@ -586,6 +589,8 @@ export function createBuildingStudy({ models, defaultView = "quarter", views = {
         get groundShadows() { return base.receiveShadow; },
         get activeView() { return activeView; },
         get selectedBuilding() { return selectedModel?.building.userData["buildingId"] || null; },
+        get sunDirection() { return keyLight.position.clone().sub(keyLight.target.position).normalize().toArray(); },
+        get sunIntensity() { return keyLight.intensity; },
         get shadowBounds() {
             // Actual rendered geometry in the shadow camera's clip space, for coverage checks.
             const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
@@ -667,7 +672,29 @@ export function createBuildingStudy({ models, defaultView = "quarter", views = {
     Object.defineProperty(canvas, "__buildingStudy", { value: api, configurable: true });
     onReady();
     // Day or night: the transparent canvas shows the page's night behind it until a sky covers it.
+    // A sphere enclosing every caster and the platform fits the shadow camera at any
+    // solar azimuth/elevation. Cache it: dragging time never traverses model vertices.
     function setDaylight(day) {
+        if (day?.direction) {
+            if (!lightBounds) {
+                const min = new THREE.Vector3(Infinity, Infinity, Infinity), max = new THREE.Vector3(-Infinity, -Infinity, -Infinity);
+                for (const bounds of [api.platformBounds, ...api.modelBounds]) {
+                    min.min(new THREE.Vector3().fromArray(bounds.min));
+                    max.max(new THREE.Vector3().fromArray(bounds.max));
+                }
+                lightBounds = { center: min.clone().add(max).multiplyScalar(0.5), radius: max.distanceTo(min) / 2 };
+            }
+            const radius = lightBounds.radius * 1.02;
+            keyLight.target.position.copy(lightBounds.center);
+            keyLight.position.fromArray(day.direction).multiplyScalar(2 * radius + 1).add(lightBounds.center);
+            Object.assign(keyLight.shadow.camera, { left: -radius, right: radius, top: radius, bottom: -radius, near: 1, far: 4 * radius + 2 });
+        }
+        else {
+            keyLight.position.fromArray(lightPosition);
+            keyLight.target.position.set(0, 80, 0);
+            Object.assign(keyLight.shadow.camera, shadowCamera);
+        }
+        keyLight.shadow.camera.updateProjectionMatrix();
         scene.background = day?.sky ?? null;
         base.material.color.setHex(day?.ground ?? nightGround);
         for (const [light, [colour, intensity]] of [[keyLight, day?.sun ?? night.sun], [ambientLight, day?.ambient ?? night.ambient], [fillLight, day?.fill ?? night.fill]]) {

package/site/study.css

@@ -162,6 +162,12 @@ body.skyline-3d { height: 100vh; height: 100dvh; }
 .control-bar .button-group { gap: 4px; }
 .control-bar .camera-views { grid-area: views; justify-self: start; --fold: inset(0 0 0 100%); }
 .control-bar .model-display { grid-area: display; justify-self: end; justify-content: end; --fold: inset(0 100% 0 0); }
+.time-controls { display: grid; grid-template-columns: auto minmax(60px, 1fr) auto auto; align-items: center; gap: 8px; flex-basis: 100%; width: 100%; font-size: 10px; }
+.time-controls label { color: #bbb; }
+.time-controls #time-date { display: block; margin-top: 2px; color: #888; font-size: 9px; }
+.time-controls input { width: 100%; min-width: 0; height: 28px; margin: 0; accent-color: #bbb; cursor: pointer; }
+.time-controls output { min-width: 88px; text-align: right; color: #ddd; font-variant-numeric: tabular-nums; }
+.time-controls button:disabled { opacity: 0.45; cursor: default; }
 .celebration-controls { display: flex; flex-wrap: wrap; align-items: center; justify-content: end; gap: 4px; flex-basis: 100%; }
 .celebration-caption { margin-right: 4px; color: #888; font-size: 10px; }
 .control-bar .celebration-controls button { display: grid; place-items: center; width: 36px; height: 36px; padding: 4px; }
@@ -179,8 +185,8 @@ body.skyline-3d { height: 100vh; height: 100dvh; }
 .control-bar .menu-toggle:hover { color: #fff; background: #ffffff14; }
 .menu-toggle svg { width: 20px; height: 20px; fill: currentColor; transition: rotate 0.35s cubic-bezier(0.2, 0.7, 0.2, 1); }
 .menu-toggle[aria-expanded="true"] svg { rotate: 30deg; }
-/* At desktop widths the badges share the display row, so opening the controls
-   keeps the canvas height unchanged. Smaller screens retain 36px touch targets. */
+/* Compact badges leave room for the time slider. Smaller screens retain 36px
+   touch targets. */
 @container skyline (min-width: 1440px) {
   .celebration-controls { flex-basis: auto; flex-wrap: nowrap; }
   .celebration-caption { display: none; }
@@ -203,6 +209,12 @@ body.skyline-3d { height: 100vh; height: 100dvh; }
   .skyline-trace-tip { display: none; animation: none; }
 }
 @container skyline (max-width: 600px) {
+  .time-controls { grid-template-columns: minmax(0, 1fr) auto; gap: 2px 8px; }
+  .time-controls label { grid-column: 1; grid-row: 1; }
+  .time-controls #time-date { display: inline; margin-left: 8px; }
+  .time-controls output { grid-column: 2; grid-row: 1; }
+  .time-controls input { grid-column: 1; grid-row: 2; height: 32px; }
+  .time-controls button { grid-column: 2; grid-row: 2; }
   .skyline-trace { stroke-width: 8.4; }
   .skyline-trace-tip { stroke-width: 12; }
   .skyline-3d .hint { font-size: 9px; }