@ifc-lite/viewer 1.29.0 → 1.30.0

package/src/hooks/useSolarSweep.ts

@@ -0,0 +1,66 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Solar sweep animation — advances the studied instant while playing.
+ *
+ * Lives at the viewport level (not inside the panel) so collapsing or
+ * closing the Sun & Sky panel doesn't stop a running sweep.
+ *
+ * Reads/writes the store imperatively each tick to avoid stale closures,
+ * and wraps within the current day (day sweep) or year (year sweep) so the
+ * animation loops cleanly.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useViewerStore } from '@/store';
+import { solarDisplayOffsetMinutes, MS_PER_MIN, MS_PER_DAY } from '@/lib/solar-time';
+
+/** Wall-clock cadence for the animation sweep. */
+const TICK_MS = 80;
+/** Per-tick advance: 8 minutes of solar time (day) or 2 days (year). */
+const DAY_STEP_MIN = 8;
+const YEAR_STEP_DAYS = 2;
+
+export function useSolarSweep(): void {
+  const enabled = useViewerStore((s) => s.solarEnabled);
+  const playing = useViewerStore((s) => s.solarPlaying);
+  const sweepMode = useViewerStore((s) => s.solarSweepMode);
+
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  useEffect(() => {
+    if (!enabled || !playing) return;
+    intervalRef.current = setInterval(() => {
+      const store = useViewerStore.getState();
+      const current = store.solarDateMs;
+      let next: number;
+      if (store.solarSweepMode === 'day') {
+        // Wrap in the same display frame the slider edits in, so the day seam
+        // lands at displayed midnight (not UTC midnight) and the date doesn't
+        // flip mid-sweep when site/local time is active.
+        const offsetMin = solarDisplayOffsetMinutes(store.solarUseLocalTime, store.solarSunInfo?.longitude);
+        const displayMs = current + offsetMin * MS_PER_MIN;
+        const disp = new Date(displayMs);
+        const dayStart = Date.UTC(disp.getUTCFullYear(), disp.getUTCMonth(), disp.getUTCDate());
+        const minutes = (displayMs - dayStart) / MS_PER_MIN;
+        const nextMinutes = (minutes + DAY_STEP_MIN) % 1440;
+        next = dayStart + nextMinutes * MS_PER_MIN - offsetMin * MS_PER_MIN;
+      } else {
+        const d = new Date(current);
+        const yearStart = Date.UTC(d.getUTCFullYear(), 0, 1);
+        const dayOfYear = Math.floor((current - yearStart) / MS_PER_DAY);
+        const isLeap = (d.getUTCFullYear() % 4 === 0 && d.getUTCFullYear() % 100 !== 0) || d.getUTCFullYear() % 400 === 0;
+        const daysInYear = isLeap ? 366 : 365;
+        const timeOfDay = current - (yearStart + dayOfYear * MS_PER_DAY);
+        const nextDay = (dayOfYear + YEAR_STEP_DAYS) % daysInYear;
+        next = yearStart + nextDay * MS_PER_DAY + timeOfDay;
+      }
+      store.setSolarDateMs(next);
+    }, TICK_MS);
+    return () => {
+      if (intervalRef.current !== null) clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    };
+  }, [enabled, playing, sweepMode]);
+}

package/src/hooks/useSymbolicAnnotations.ts

@@ -19,6 +19,7 @@ import { decodeIfcString } from '@ifc-lite/encoding';
 import { useViewerStore } from '@/store';
 import { useShallow } from 'zustand/react/shallow';
 import type { IfcDataStore } from '@ifc-lite/parser';
+import { hasEntityType } from './has-entity-type.js';
 
 /** Lines belonging to a single storey, ready to feed into the section overlay. */
 export interface AnnotationsForStorey {
@@ -240,6 +241,15 @@ async function parseAnnotations(
     if (debugEnabled()) console.log('[annotations] skip: missing/empty source');
     return result;
   }
+  // Skip the full-source WASM scan only when the model has neither IfcAnnotation
+  // nor IfcGridAxis — this parse path ALSO feeds the grid buckets (gridByStorey /
+  // gridLoose*), so gating on IfcAnnotation alone would drop grid-only models.
+  // The scan copies the entire IFC source into the WASM heap on the main thread,
+  // so skipping it when there is nothing to find still matters.
+  if (!hasEntityType(store, 'IfcAnnotation', 'IfcGridAxis')) {
+    if (debugEnabled()) console.log('[annotations] skip: no IfcAnnotation/IfcGridAxis entities');
+    return result;
+  }
 
   const hierarchy = store.spatialHierarchy;
   const elementToStorey = hierarchy?.elementToStorey;

package/src/hooks/useViewerSelectors.ts

@@ -8,7 +8,7 @@
  * Extracted from Viewport.tsx for reusability
  */
 
-import { useViewerStore } from '../store.js';
+import { useViewerStore } from '../store/index.js';
 
 /**
  * Selection-related store state and actions

package/src/lib/geo/cesium-sun.ts

@@ -0,0 +1,277 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Cesium sun helpers — turn the renderer-agnostic geometry from
+ * `@ifc-lite/solar` into real Cesium scene state for a georeferenced sun-path
+ * + shadow study:
+ *
+ *   • applySolarScene  — drive Cesium's sun, lighting and shadow map from a
+ *                        chosen instant (the model + OSM context then cast and
+ *                        receive real shadows).
+ *   • SunPathDome      — a self-contained set of polyline/point entities for
+ *                        the 3D dome (day arc, hourly analemmas, graticule,
+ *                        cardinals, and the live sun marker + beam).
+ *
+ * All dome geometry is positioned by mapping the solar package's ENU unit
+ * vectors through `eastNorthUpToFixedFrame(origin)`, the same ENU→ECEF frame
+ * the coordinate bridge uses, so the dome is pinned to the model's true site.
+ */
+
+import {
+  analemmaPaths,
+  dayPath,
+  domeGraticule,
+  azimuthAltitudeToEnu,
+  sunPosition,
+  type Enu,
+} from '@ifc-lite/solar';
+
+type CesiumNs = typeof import('cesium');
+type CesiumViewer = InstanceType<typeof import('cesium').Viewer>;
+
+export interface SolarSceneOptions {
+  /** Studied instant. */
+  date: Date;
+  /** Master enable — false restores the neutral (no-sun) overlay state. */
+  enabled: boolean;
+  /** Whether to render the shadow map (mutual model ↔ context shadows). */
+  shadows: boolean;
+  /**
+   * Show the sun billboard. Off by default (transparent compositing); the
+   * environment panel's Sky toggle turns it on together with the atmosphere.
+   */
+  showSun?: boolean;
+}
+
+/**
+ * Drive Cesium's sun, lighting and shadow map from the studied instant.
+ * Idempotent — safe to call every time the date or toggles change.
+ */
+export function applySolarScene(
+  Cesium: CesiumNs,
+  viewer: CesiumViewer,
+  options: SolarSceneOptions,
+): void {
+  const scene = viewer.scene;
+  const { enabled, shadows, date, showSun = false } = options;
+
+  if (!enabled) {
+    // Restore the transparent-compositing defaults set up in CesiumOverlay
+    // (the sun billboard stays available for the Sky toggle).
+    if (scene.sun) scene.sun.show = showSun;
+    scene.globe.enableLighting = false;
+    viewer.shadows = false;
+    scene.light = new Cesium.DirectionalLight({
+      direction: new Cesium.Cartesian3(0.5, -1.0, -0.3),
+    });
+    return;
+  }
+
+  // Pin the simulation clock to the studied instant so Cesium's SunLight and
+  // shadow map are computed for exactly this date/time.
+  const julian = Cesium.JulianDate.fromDate(date);
+  viewer.clock.shouldAnimate = false;
+  viewer.clock.currentTime = julian;
+  scene.light = new Cesium.SunLight();
+  if (scene.sun) scene.sun.show = showSun; // billboard only with the Sky toggle
+  scene.globe.enableLighting = true;
+  viewer.shadows = shadows;
+  if (viewer.shadowMap) {
+    viewer.shadowMap.enabled = shadows;
+    viewer.shadowMap.softShadows = true;
+    viewer.shadowMap.darkness = 0.35;
+  }
+  scene.requestRender();
+}
+
+export interface SunPathDomeOptions {
+  /** Site origin (model georef). */
+  origin: { longitude: number; latitude: number; height: number };
+  /** Dome radius in metres. */
+  radius: number;
+  /** Studied instant (positions the live sun marker). */
+  date: Date;
+  /** Show the hourly analemma figure-eights. */
+  showAnalemmas?: boolean;
+}
+
+const DAY_ARC_COLOR = [255, 200, 40] as const; // warm yellow
+const ANALEMMA_COLOR = [120, 170, 255] as const; // cool blue
+const GRID_COLOR = [255, 255, 255] as const;
+const SUN_COLOR = [255, 230, 120] as const;
+
+/**
+ * A self-contained collection of Cesium entities forming the 3D sun-path
+ * dome. Construct once for a site/date, then call {@link update} as the
+ * studied instant changes (only the sun marker + beam move), and
+ * {@link destroy} to remove every entity.
+ */
+export class SunPathDome {
+  private readonly Cesium: CesiumNs;
+  private readonly viewer: CesiumViewer;
+  private readonly dataSource: InstanceType<typeof import('cesium').CustomDataSource>;
+  private readonly options: SunPathDomeOptions;
+  private readonly enuToEcef: InstanceType<typeof import('cesium').Matrix4>;
+  private sunMarker: InstanceType<typeof import('cesium').Entity> | null = null;
+  private sunBeam: InstanceType<typeof import('cesium').Entity> | null = null;
+
+  /** Build the dome's data source + static geometry and add it to the viewer. */
+  constructor(Cesium: CesiumNs, viewer: CesiumViewer, options: SunPathDomeOptions) {
+    this.Cesium = Cesium;
+    this.viewer = viewer;
+    this.options = options;
+    this.dataSource = new Cesium.CustomDataSource('ifc-lite-sun-path');
+
+    const originCart = Cesium.Cartesian3.fromDegrees(
+      options.origin.longitude,
+      options.origin.latitude,
+      options.origin.height,
+    );
+    this.enuToEcef = Cesium.Transforms.eastNorthUpToFixedFrame(originCart);
+
+    this.buildStatic();
+    this.update(options.date);
+    // Await attach, THEN request a render: the viewer runs in requestRenderMode,
+    // so a render requested before the data source is attached would paint
+    // nothing and the dome would stay invisible until the next camera move.
+    viewer.dataSources
+      .add(this.dataSource)
+      .then(() => {
+        viewer.scene.requestRender();
+        console.log('[SunPathDome] built', {
+          lat: options.origin.latitude,
+          lon: options.origin.longitude,
+          height: options.origin.height,
+          radius: options.radius,
+          entities: this.dataSource.entities.values.length,
+        });
+      })
+      .catch((err) => console.warn('[SunPathDome] failed to add data source:', err));
+  }
+
+  /** Map a single ENU direction (unit) at the dome radius to an ECEF position. */
+  private enuDirToEcef(dir: Enu, radiusScale = 1): InstanceType<typeof import('cesium').Cartesian3> {
+    const r = this.options.radius * radiusScale;
+    return this.Cesium.Matrix4.multiplyByPoint(
+      this.enuToEcef,
+      new this.Cesium.Cartesian3(dir.e * r, dir.n * r, dir.u * r),
+      new this.Cesium.Cartesian3(),
+    );
+  }
+
+  /** Add a polyline entity from a list of ENU directions at the dome radius. */
+  private polyline(
+    dirs: Enu[],
+    rgb: readonly [number, number, number],
+    width: number,
+  ): void {
+    if (dirs.length < 2) return;
+    const positions = dirs.map((d) => this.enuDirToEcef(d));
+    this.dataSource.entities.add({
+      polyline: {
+        positions,
+        width,
+        material: this.Cesium.Color.fromBytes(rgb[0], rgb[1], rgb[2], 235),
+        // Draw the dome even where it sits behind terrain / 3D tiles or the
+        // model, dimmer, so the full sun path stays legible in 3D.
+        depthFailMaterial: this.Cesium.Color.fromBytes(rgb[0], rgb[1], rgb[2], 90),
+        arcType: this.Cesium.ArcType.NONE,
+      },
+    });
+  }
+
+  /** Build the date-independent geometry: graticule, cardinals, analemmas, day arc. */
+  private buildStatic(): void {
+    const { origin, date } = this.options;
+
+    // Graticule — altitude rings + azimuth spokes.
+    const grat = domeGraticule({ altitudeStep: 15, azimuthStep: 30 });
+    for (const ring of grat.altitudeRings) {
+      this.polyline(ring.ring, GRID_COLOR, ring.altitude === 0 ? 2 : 1);
+    }
+    for (const spoke of grat.azimuthSpokes) {
+      this.polyline(spoke.arc, GRID_COLOR, 1);
+    }
+
+    // Cardinal / ordinal labels on the horizon.
+    for (const c of grat.cardinals) {
+      this.dataSource.entities.add({
+        position: this.enuDirToEcef(c.dir, 1.05),
+        label: {
+          text: c.label,
+          font: '600 14px sans-serif',
+          fillColor: this.Cesium.Color.WHITE,
+          outlineColor: this.Cesium.Color.BLACK,
+          outlineWidth: 2,
+          style: this.Cesium.LabelStyle.FILL_AND_OUTLINE,
+          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        },
+      });
+    }
+
+    // Hourly analemmas (figure-eights) across the year.
+    if (this.options.showAnalemmas ?? true) {
+      const year = date.getUTCFullYear();
+      for (const path of analemmaPaths(year, origin.latitude, origin.longitude, { dayStep: 5 })) {
+        const above = path.samples.filter((s) => s.aboveHorizon).map((s) => s.dir);
+        this.polyline(above, ANALEMMA_COLOR, 1);
+      }
+    }
+
+    // Day arc for the studied date.
+    const arc = dayPath(date, origin.latitude, origin.longitude, { stepMinutes: 10 });
+    this.polyline(arc.map((s) => s.dir), DAY_ARC_COLOR, 2);
+  }
+
+  /** Reposition the live sun marker + beam for a new instant. */
+  update(date: Date): void {
+    const { origin } = this.options;
+    const pos = sunPosition(date, origin.latitude, origin.longitude);
+    const dir = azimuthAltitudeToEnu(pos.azimuth, pos.altitude);
+    const show = pos.altitude >= 0;
+    const sunEcef = this.enuDirToEcef(dir);
+    const originEcef = this.enuDirToEcef({ e: 0, n: 0, u: 0 });
+
+    if (!this.sunMarker) {
+      this.sunMarker = this.dataSource.entities.add({
+        position: sunEcef,
+        point: {
+          pixelSize: 16,
+          color: this.Cesium.Color.fromBytes(SUN_COLOR[0], SUN_COLOR[1], SUN_COLOR[2], 255),
+          outlineColor: this.Cesium.Color.fromBytes(255, 140, 0, 255),
+          outlineWidth: 3,
+          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        },
+      });
+      this.sunBeam = this.dataSource.entities.add({
+        polyline: {
+          positions: [originEcef, sunEcef],
+          width: 2,
+          material: this.Cesium.Color.fromBytes(SUN_COLOR[0], SUN_COLOR[1], SUN_COLOR[2], 160),
+          depthFailMaterial: this.Cesium.Color.fromBytes(SUN_COLOR[0], SUN_COLOR[1], SUN_COLOR[2], 70),
+          arcType: this.Cesium.ArcType.NONE,
+        },
+      });
+    } else {
+      this.sunMarker.position = new this.Cesium.ConstantPositionProperty(sunEcef);
+      if (this.sunBeam?.polyline) {
+        this.sunBeam.polyline.positions = new this.Cesium.ConstantProperty([originEcef, sunEcef]);
+      }
+    }
+    if (this.sunMarker.point) {
+      this.sunMarker.point.show = new this.Cesium.ConstantProperty(show);
+    }
+    if (this.sunBeam?.polyline) {
+      this.sunBeam.polyline.show = new this.Cesium.ConstantProperty(show);
+    }
+    this.viewer.scene.requestRender();
+  }
+
+  /** Remove every dome entity and detach the data source from the viewer. */
+  destroy(): void {
+    this.dataSource.entities.removeAll();
+    void this.viewer.dataSources.remove(this.dataSource, true);
+  }
+}

package/src/lib/geo/solar-direction.test.ts

@@ -0,0 +1,70 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { enuToViewerDirection, sunLightingForAltitude } from './solar-direction.js';
+
+function assertVecClose(actual: number[], expected: number[], eps = 1e-9) {
+  for (let i = 0; i < 3; i++) {
+    assert.ok(
+      Math.abs(actual[i] - expected[i]) < eps,
+      `component ${i}: ${actual[i]} !≈ ${expected[i]}`,
+    );
+  }
+}
+
+describe('enuToViewerDirection', () => {
+  it('maps the cardinal frame with no rotation: east→+X, up→+Y, north→−Z', () => {
+    assertVecClose(enuToViewerDirection({ e: 1, n: 0, u: 0 }), [1, 0, 0]);
+    assertVecClose(enuToViewerDirection({ e: 0, n: 0, u: 1 }), [0, 1, 0]);
+    assertVecClose(enuToViewerDirection({ e: 0, n: 1, u: 0 }), [0, 0, -1]);
+  });
+
+  it('is the inverse of the cesium-bridge viewer→ENU matrix for a rotated site', () => {
+    // 30° Helmert rotation, deliberately unnormalized (scaled ×2) the way
+    // IFC files sometimes author the direction cosines.
+    const absc = 2 * Math.cos(Math.PI / 6);
+    const ordi = 2 * Math.sin(Math.PI / 6);
+    const a = Math.cos(Math.PI / 6);
+    const o = Math.sin(Math.PI / 6);
+
+    const enu = { e: 0.3, n: 0.8, u: 0.52 };
+    const [vx, vy, vz] = enuToViewerDirection(enu, absc, ordi);
+
+    // Forward map from cesium-bridge.ts (unit-scale): east = a·vx + o·vz,
+    // north = o·vx − a·vz, up = vy. Round-tripping must recover the input.
+    const norm = Math.hypot(enu.e, enu.n, enu.u);
+    assert.ok(Math.abs((a * vx + o * vz) - enu.e / norm) < 1e-9, 'east');
+    assert.ok(Math.abs((o * vx - a * vz) - enu.n / norm) < 1e-9, 'north');
+    assert.ok(Math.abs(vy - enu.u / norm) < 1e-9, 'up');
+  });
+
+  it('returns a unit vector', () => {
+    const v = enuToViewerDirection({ e: 3, n: 4, u: 5 }, 0.6, -0.8);
+    assert.ok(Math.abs(Math.hypot(...v) - 1) < 1e-9);
+  });
+});
+
+describe('sunLightingForAltitude', () => {
+  it('full sun at midday, none at night', () => {
+    assert.ok(sunLightingForAltitude(45).intensityFactor > 0.99);
+    assert.strictEqual(sunLightingForAltitude(-20).intensityFactor, 0);
+  });
+
+  it('warms toward the horizon', () => {
+    const noon = sunLightingForAltitude(60);
+    const sunset = sunLightingForAltitude(1);
+    assert.ok(sunset.color[2] < noon.color[2], 'blue drops near horizon');
+    assert.ok(sunset.color[1] < noon.color[1], 'green drops near horizon');
+  });
+
+  it('ambient fades through twilight to a night floor', () => {
+    assert.ok(sunLightingForAltitude(30).ambientFactor > 0.99);
+    const night = sunLightingForAltitude(-30).ambientFactor;
+    assert.ok(night > 0.1 && night < 0.25, `night floor, got ${night}`);
+    const dusk = sunLightingForAltitude(-5).ambientFactor;
+    assert.ok(dusk > night && dusk < 1, `twilight between floors, got ${dusk}`);
+  });
+});

package/src/lib/geo/solar-direction.ts

@@ -0,0 +1,94 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Map sun positions from the solar package's ENU frame into the WebGPU
+ * viewer's world space, and shape the sun's photometric properties from its
+ * altitude (warm low sun, twilight fade, night).
+ *
+ * Frame math — must stay the inverse of the viewer→ENU matrix built in
+ * `cesium-bridge.ts` (createCesiumBridge):
+ *
+ *   east  = absc·vx + ordi·vz
+ *   north = ordi·vx − absc·vz
+ *   up    = vy
+ *
+ * With (absc, ordi) normalized that matrix is orthonormal, so the inverse is
+ * the transpose:
+ *
+ *   vx = absc·e + ordi·n
+ *   vy = u
+ *   vz = ordi·e − absc·n
+ *
+ * Sanity check at no rotation (absc=1, ordi=0): east→+X, up→+Y, north→−Z.
+ */
+
+import type { Enu } from '@ifc-lite/solar';
+
+/**
+ * Convert an ENU unit direction to viewer/world space (Y-up) using the
+ * model's IfcMapConversion XAxisAbscissa/Ordinate rotation. Defaults match
+ * IFC's "no rotation" convention (cos=1, sin=0).
+ */
+export function enuToViewerDirection(
+  enu: Enu,
+  xAxisAbscissa = 1,
+  xAxisOrdinate = 0,
+): [number, number, number] {
+  // The IFC pair may be unnormalized direction cosines — normalize first.
+  const len = Math.hypot(xAxisAbscissa, xAxisOrdinate) || 1;
+  const a = xAxisAbscissa / len;
+  const o = xAxisOrdinate / len;
+  const vx = a * enu.e + o * enu.n;
+  const vy = enu.u;
+  const vz = o * enu.e - a * enu.n;
+  const vlen = Math.hypot(vx, vy, vz) || 1;
+  return [vx / vlen, vy / vlen, vz / vlen];
+}
+
+export interface SunLighting {
+  /** Multiplier 0..1 on the preset's sun intensity. */
+  intensityFactor: number;
+  /** Sun light colour (warm at low altitudes, cool residual at night). */
+  color: [number, number, number];
+  /** Multiplier 0..~1 on the preset's hemisphere-ambient strength. */
+  ambientFactor: number;
+}
+
+function smooth(x: number, lo: number, hi: number): number {
+  const t = Math.min(1, Math.max(0, (x - lo) / (hi - lo)));
+  return t * t * (3 - 2 * t);
+}
+
+function mix(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/**
+ * Photometric shaping of the sun by altitude (degrees above horizon):
+ * full warm-white sun by ~15°, golden tint near the horizon, fading to
+ * zero through civil twilight (0…−6°), with ambient dimming to a small
+ * night floor so the model stays barely readable.
+ */
+export function sunLightingForAltitude(altitudeDeg: number): SunLighting {
+  // Direct sun: none below the horizon, ramping in over the first ~10°.
+  const dayness = smooth(altitudeDeg, -1, 10);
+  // Twilight ambient: holds through −6° (civil twilight), then night floor.
+  const twilight = smooth(altitudeDeg, -10, 2);
+
+  // Warmth peaks at the horizon: white overhead → amber at 0°.
+  const warmth = 1 - smooth(altitudeDeg, 2, 25);
+  const color: [number, number, number] = [
+    1.0,
+    mix(0.98, 0.72, warmth),
+    mix(0.95, 0.45, warmth),
+  ];
+
+  return {
+    intensityFactor: dayness,
+    color,
+    // Night keeps 18% ambient so geometry silhouettes stay visible.
+    ambientFactor: mix(0.18, 1.0, twilight),
+  };
+}

package/src/lib/lighting-presets.ts

@@ -0,0 +1,128 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Lighting presets for the WebGPU viewport.
+ *
+ * Each preset is a partial `LightingEnvironment`; unset fields fall back to
+ * the renderer defaults (the historical hardcoded look). The `default`
+ * preset is intentionally empty so it renders pixel-identical to every
+ * ifc-lite build before lighting became configurable.
+ *
+ * A preset IS the whole environment: every preset except `default` brings
+ * its sky along (`skyEnabled: true`) — picking "Day" gives day lighting AND
+ * a day sky, with no separate sky switch to discover.
+ *
+ * When the solar study drives the sun, the preset still supplies the base
+ * sun intensity and hemisphere colours; only direction/colour/fades are
+ * overridden per the computed sun altitude.
+ */
+
+import type { LightingEnvironment } from '@ifc-lite/renderer';
+
+export type LightingPresetId = 'default' | 'daylight' | 'overcast' | 'golden' | 'night';
+
+export interface LightingPreset {
+  id: LightingPresetId;
+  label: string;
+  hint: string;
+  environment: LightingEnvironment;
+}
+
+export const LIGHTING_PRESETS: Record<LightingPresetId, LightingPreset> = {
+  default: {
+    id: 'default',
+    label: 'Default',
+    hint: 'The classic ifc-lite studio look',
+    environment: {},
+  },
+  daylight: {
+    id: 'daylight',
+    label: 'Day',
+    hint: 'Bright neutral daylight, high sun',
+    environment: {
+      skyEnabled: true,
+      sunDirection: [0.45, 0.83, 0.33],
+      sunColor: [1.0, 0.98, 0.92],
+      sunIntensity: 0.62,
+      skyColor: [0.42, 0.52, 0.65],
+      groundColor: [0.22, 0.19, 0.15],
+      ambientIntensity: 0.3,
+      exposure: 0.9,
+    },
+  },
+  overcast: {
+    id: 'overcast',
+    label: 'Overcast',
+    hint: 'Soft shadowless grey-sky light',
+    environment: {
+      skyEnabled: true,
+      sunDirection: [0.2, 0.95, 0.24],
+      sunColor: [0.9, 0.92, 0.95],
+      sunIntensity: 0.28,
+      skyColor: [0.55, 0.57, 0.6],
+      groundColor: [0.28, 0.28, 0.28],
+      ambientIntensity: 0.45,
+      fillIntensity: 0.1,
+      rimIntensity: 0.08,
+      exposure: 0.85,
+      sky: {
+        zenith: [0.5, 0.54, 0.58],
+        horizon: [0.66, 0.68, 0.7],
+        ground: [0.2, 0.2, 0.2],
+      },
+    },
+  },
+  golden: {
+    id: 'golden',
+    label: 'Evening',
+    hint: 'Low warm sun, golden-hour mood',
+    environment: {
+      skyEnabled: true,
+      sunDirection: [0.85, 0.18, 0.49],
+      sunColor: [1.0, 0.72, 0.45],
+      sunIntensity: 0.6,
+      skyColor: [0.3, 0.26, 0.32],
+      groundColor: [0.16, 0.11, 0.08],
+      ambientIntensity: 0.22,
+      exposure: 0.82,
+    },
+  },
+  night: {
+    id: 'night',
+    label: 'Night',
+    hint: 'Cool moonlit ambience',
+    environment: {
+      skyEnabled: true,
+      sunDirection: [-0.3, 0.7, -0.65],
+      sunColor: [0.65, 0.72, 0.9],
+      sunIntensity: 0.18,
+      skyColor: [0.1, 0.12, 0.2],
+      groundColor: [0.05, 0.05, 0.07],
+      ambientIntensity: 0.3,
+      fillIntensity: 0.08,
+      rimIntensity: 0.2,
+      exposure: 0.75,
+      // Explicit night sky — the altitude-derived palette would read the
+      // high moon direction as a midday sun and paint a blue daytime sky.
+      sky: {
+        zenith: [0.012, 0.018, 0.04],
+        horizon: [0.04, 0.05, 0.09],
+        ground: [0.02, 0.02, 0.025],
+      },
+    },
+  },
+};
+
+export const LIGHTING_PRESET_ORDER: LightingPresetId[] = [
+  'default',
+  'daylight',
+  'overcast',
+  'golden',
+  'night',
+];
+
+export function isLightingPresetId(value: string): value is LightingPresetId {
+  return value in LIGHTING_PRESETS;
+}