@ifc-lite/viewer 1.29.0 → 1.30.0

package/src/components/viewer/SunSkyPanel.tsx

@@ -0,0 +1,363 @@
+/* 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/. */
+
+/**
+ * Sun & Sky panel — one place for sky, lighting and the sun-path study,
+ * aware of which rendering path is active:
+ *
+ *   • Standalone (WebGPU): lighting preset + exposure shape the model's
+ *     shading, Sky draws the procedural sky, and the sun study (when the
+ *     model is georeferenced) drives the real sun direction.
+ *   • World context (Cesium): the model is composited into Cesium, which
+ *     lights the scene from its sun and atmosphere — so preset/exposure
+ *     hide and Sky toggles the atmosphere instead. The study adds the
+ *     sun-path dome and real cast shadows.
+ *
+ * The whole panel collapses to its header row; the study keeps running
+ * (sweep animation lives in useSolarSweep at the viewport level).
+ */
+
+import { useState } from 'react';
+import { Play, Pause, ChevronDown, ChevronUp } from 'lucide-react';
+import { useViewerStore } from '@/store';
+import { cn } from '@/lib/utils';
+import type { CesiumDataSource } from '@/store/slices/cesiumSlice';
+import type { SolarSweepMode } from '@/store/slices/solarSlice';
+import { LIGHTING_PRESETS, LIGHTING_PRESET_ORDER, isLightingPresetId } from '@/lib/lighting-presets';
+import {
+  solarDisplayOffsetMinutes,
+  toSolarDateInputValue,
+  solarMinutesOfDay,
+  composeSolarMs,
+  formatSolarTime,
+} from '@/lib/solar-time';
+
+const CONTEXT_SOURCES: Array<{ value: CesiumDataSource; label: string; hint: string }> = [
+  { value: 'osm-buildings', label: 'OSM Buildings', hint: 'Extruded footprints over the satellite base map' },
+  { value: 'google-photorealistic', label: 'Photorealistic', hint: 'Google 3D Tiles — textured real-world context' },
+];
+
+const SWEEP_MODES: Array<{ value: SolarSweepMode; label: string; hint: string }> = [
+  { value: 'day', label: 'Day', hint: 'Sweep the time of day' },
+  { value: 'year', label: 'Year', hint: 'Sweep the date across the year' },
+];
+
+export function SunSkyPanel() {
+  const open = useViewerStore((s) => s.envPanelOpen);
+
+  const skyEnabled = useViewerStore((s) => s.envSkyEnabled);
+  const setSkyEnabled = useViewerStore((s) => s.setEnvSkyEnabled);
+  const preset = useViewerStore((s) => s.envPreset);
+  const setPreset = useViewerStore((s) => s.setEnvPreset);
+  const exposure = useViewerStore((s) => s.envExposure);
+  const setExposure = useViewerStore((s) => s.setEnvExposure);
+
+  const cesiumAvailable = useViewerStore((s) => s.cesiumAvailable);
+  const cesiumEnabled = useViewerStore((s) => s.cesiumEnabled);
+  const setCesiumEnabled = useViewerStore((s) => s.setCesiumEnabled);
+  const dataSource = useViewerStore((s) => s.cesiumDataSource);
+  const setDataSource = useViewerStore((s) => s.setCesiumDataSource);
+
+  const solarEnabled = useViewerStore((s) => s.solarEnabled);
+  const setSolarEnabled = useViewerStore((s) => s.setSolarEnabled);
+  const dateMs = useViewerStore((s) => s.solarDateMs);
+  const setDateMs = useViewerStore((s) => s.setSolarDateMs);
+  const showSunPath = useViewerStore((s) => s.solarShowSunPath);
+  const setShowSunPath = useViewerStore((s) => s.setSolarShowSunPath);
+  const showShadows = useViewerStore((s) => s.solarShowShadows);
+  const setShowShadows = useViewerStore((s) => s.setSolarShowShadows);
+  const sunInfo = useViewerStore((s) => s.solarSunInfo);
+  const useLocalTime = useViewerStore((s) => s.solarUseLocalTime);
+  const setUseLocalTime = useViewerStore((s) => s.setSolarUseLocalTime);
+  const playing = useViewerStore((s) => s.solarPlaying);
+  const togglePlaying = useViewerStore((s) => s.toggleSolarPlaying);
+  const sweepMode = useViewerStore((s) => s.solarSweepMode);
+  const setSweepMode = useViewerStore((s) => s.setSolarSweepMode);
+
+  const [collapsed, setCollapsed] = useState(false);
+
+  if (!open) return null;
+
+  const offsetMin = solarDisplayOffsetMinutes(useLocalTime, sunInfo?.longitude);
+  const minutes = solarMinutesOfDay(dateMs, offsetMin);
+  const tzLabel = useLocalTime
+    ? `Site${sunInfo ? ` (UTC${offsetMin >= 0 ? '+' : '−'}${Math.abs(offsetMin / 60).toFixed(1)})` : ''}`
+    : 'UTC';
+
+  return (
+    <div className="pointer-events-auto w-60 bg-background/90 backdrop-blur-sm rounded-lg border shadow-lg p-2 flex flex-col gap-2 text-xs">
+      {/* Header — click anywhere to collapse/expand */}
+      <button
+        type="button"
+        onClick={() => setCollapsed(!collapsed)}
+        aria-expanded={!collapsed}
+        className="flex items-center justify-between gap-2 text-left"
+      >
+        <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+          Sun &amp; Sky
+        </span>
+        <span className="text-muted-foreground">
+          {collapsed ? <ChevronDown className="h-3 w-3" /> : <ChevronUp className="h-3 w-3" />}
+        </span>
+      </button>
+
+      {!collapsed && (
+        <>
+          {/* Environment — the preset IS the whole look: every preset except
+              Default brings its own sky. In the world context the model is
+              lit by Cesium's sun instead, so the choice becomes a single
+              Atmosphere switch. */}
+          {cesiumEnabled ? (
+            <div className="flex items-center gap-1">
+              <ToggleChip
+                label="Atmosphere"
+                active={skyEnabled}
+                onClick={() => setSkyEnabled(!skyEnabled)}
+                title="Sky, sun disc and haze in the world context"
+              />
+              <span className="flex-1 px-1 text-[9px] leading-tight text-muted-foreground">
+                Lighting follows the sun &amp; atmosphere
+              </span>
+            </div>
+          ) : (
+            <label className="flex flex-col gap-0.5">
+              <span className="text-[9px] uppercase tracking-wider text-muted-foreground">Environment</span>
+              <select
+                aria-label="Environment preset"
+                value={preset}
+                onChange={(e) => { if (isLightingPresetId(e.target.value)) setPreset(e.target.value); }}
+                title={LIGHTING_PRESETS[preset].hint}
+                className="w-full bg-muted/40 rounded px-1.5 py-1 border text-foreground text-[10px]"
+              >
+                {LIGHTING_PRESET_ORDER.map((id) => (
+                  <option key={id} value={id}>
+                    {LIGHTING_PRESETS[id].label}{id === 'default' ? ' (no sky)' : ''}
+                  </option>
+                ))}
+              </select>
+            </label>
+          )}
+
+          {/* Exposure — WebGPU shading only, hidden in world-context mode */}
+          {!cesiumEnabled && (
+            <label className="flex flex-col gap-0.5">
+              <span className="flex justify-between text-[9px] uppercase tracking-wider text-muted-foreground">
+                <span>Exposure</span>
+                <button
+                  type="button"
+                  onClick={() => setExposure(1)}
+                  title="Reset exposure"
+                  className={cn('tabular-nums transition-colors', exposure !== 1 && 'text-foreground hover:text-teal-600')}
+                >
+                  {exposure.toFixed(2)}×
+                </button>
+              </span>
+              <input
+                type="range"
+                min={0.4}
+                max={2}
+                step={0.05}
+                value={exposure}
+                onChange={(e) => setExposure(Number(e.target.value))}
+                className="w-full accent-teal-600"
+              />
+            </label>
+          )}
+
+          {/* Sun study — needs a georeferenced model for the real sun */}
+          {cesiumAvailable && (
+            <>
+              <div className="flex items-center justify-between gap-2 pt-2 border-t">
+                <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+                  Sun study
+                </span>
+                <button
+                  type="button"
+                  aria-pressed={solarEnabled}
+                  onClick={() => setSolarEnabled(!solarEnabled)}
+                  className={cn(
+                    'px-2 py-0.5 rounded text-[10px] font-semibold uppercase transition-colors',
+                    solarEnabled ? 'bg-amber-500 text-zinc-950' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                  )}
+                >
+                  {solarEnabled ? 'On' : 'Off'}
+                </button>
+              </div>
+
+              {solarEnabled && (
+                <>
+                  {/* Date + play/pause */}
+                  <div className="flex items-end gap-1.5">
+                    {/* Not a <label>: the tz toggle is interactive, so wrapping the
+                        input in a label would forward tz clicks to the date picker. */}
+                    <div className="flex flex-col gap-0.5 flex-1">
+                      <span className="flex justify-between text-[9px] uppercase tracking-wider text-muted-foreground">
+                        <span>Date</span>
+                        <button
+                          type="button"
+                          onClick={() => setUseLocalTime(!useLocalTime)}
+                          title="Toggle UTC / local solar time (from site longitude)"
+                          className="hover:text-foreground transition-colors"
+                        >
+                          {tzLabel}
+                        </button>
+                      </span>
+                      <input
+                        type="date"
+                        aria-label="Sun study date"
+                        value={toSolarDateInputValue(dateMs, offsetMin)}
+                        onChange={(e) => setDateMs(composeSolarMs(e.target.value, minutes, offsetMin))}
+                        className="w-full bg-muted/40 rounded px-1.5 py-1 border text-foreground"
+                      />
+                    </div>
+                    <button
+                      type="button"
+                      onClick={togglePlaying}
+                      aria-label={playing ? 'Pause sweep' : 'Play sweep'}
+                      aria-pressed={playing}
+                      className={cn(
+                        'h-[26px] w-[26px] flex items-center justify-center rounded transition-colors shrink-0',
+                        playing ? 'bg-teal-600 text-white' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                      )}
+                    >
+                      {playing ? <Pause className="h-3.5 w-3.5" /> : <Play className="h-3.5 w-3.5" />}
+                    </button>
+                  </div>
+
+                  {/* Time of day */}
+                  <label className="flex flex-col gap-0.5">
+                    <span className="flex justify-between text-[9px] uppercase tracking-wider text-muted-foreground">
+                      <span>Time</span>
+                      <span className="tabular-nums text-foreground">{formatSolarTime(dateMs, offsetMin)}</span>
+                    </span>
+                    <input
+                      type="range"
+                      min={0}
+                      max={1439}
+                      step={5}
+                      value={minutes}
+                      onChange={(e) => setDateMs(composeSolarMs(toSolarDateInputValue(dateMs, offsetMin), Number(e.target.value), offsetMin))}
+                      className="w-full accent-teal-600"
+                    />
+                  </label>
+
+                  {/* Sweep mode */}
+                  <div className="flex gap-1">
+                    {SWEEP_MODES.map((m) => (
+                      <button
+                        key={m.value}
+                        type="button"
+                        title={m.hint}
+                        aria-pressed={sweepMode === m.value}
+                        onClick={() => setSweepMode(m.value)}
+                        className={cn(
+                          'flex-1 px-1.5 py-1 rounded text-[10px] transition-colors',
+                          sweepMode === m.value
+                            ? 'bg-teal-600 text-white'
+                            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                        )}
+                      >
+                        {m.label}
+                      </button>
+                    ))}
+                  </div>
+
+                  {/* World-context extras: dome + shadows + context source */}
+                  {cesiumEnabled ? (
+                    <>
+                      <div className="flex gap-1">
+                        <ToggleChip className="flex-1" label="Dome" active={showSunPath} onClick={() => setShowSunPath(!showSunPath)} />
+                        <ToggleChip className="flex-1" label="Shadows" active={showShadows} onClick={() => setShowShadows(!showShadows)} />
+                      </div>
+                      <div className="flex gap-1">
+                        {CONTEXT_SOURCES.map((src) => (
+                          <button
+                            key={src.value}
+                            type="button"
+                            title={src.hint}
+                            aria-pressed={dataSource === src.value}
+                            onClick={() => setDataSource(src.value)}
+                            className={cn(
+                              'flex-1 px-1.5 py-1 rounded text-[10px] transition-colors',
+                              dataSource === src.value
+                                ? 'bg-teal-600 text-white'
+                                : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                            )}
+                          >
+                            {src.label}
+                          </button>
+                        ))}
+                      </div>
+                    </>
+                  ) : (
+                    <button
+                      type="button"
+                      onClick={() => setCesiumEnabled(true)}
+                      className="text-left text-[9px] leading-snug text-muted-foreground hover:text-foreground transition-colors"
+                    >
+                      The sun lights the model directly; for the sun-path dome and
+                      real cast shadows, click to enable the 3D world context.
+                    </button>
+                  )}
+
+                  {!sunInfo && (
+                    <p className="text-[9px] leading-snug text-amber-600 dark:text-amber-500">
+                      Site location unavailable — the model's projected CRS
+                      could not be resolved, so the real sun position can't be
+                      computed.
+                    </p>
+                  )}
+
+                  {/* Readout */}
+                  <div className="mt-1 pt-2 border-t grid grid-cols-2 gap-x-2 gap-y-0.5 tabular-nums">
+                    <Readout label="Azimuth" value={sunInfo ? `${sunInfo.azimuth.toFixed(1)}°` : '—'} />
+                    <Readout label="Altitude" value={sunInfo ? `${sunInfo.altitude.toFixed(1)}°` : '—'} />
+                    <Readout label="Sunrise" value={formatSolarTime(sunInfo?.sunriseMs ?? null, offsetMin)} />
+                    <Readout label="Sunset" value={formatSolarTime(sunInfo?.sunsetMs ?? null, offsetMin)} />
+                    <Readout label="Noon" value={formatSolarTime(sunInfo?.solarNoonMs ?? null, offsetMin)} />
+                    <Readout
+                      label="Site"
+                      value={sunInfo ? `${sunInfo.latitude.toFixed(2)}, ${sunInfo.longitude.toFixed(2)}` : '—'}
+                    />
+                  </div>
+                </>
+              )}
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+/** Small pill toggle button. */
+function ToggleChip({ label, active, onClick, title, className }: {
+  label: string; active: boolean; onClick: () => void; title?: string; className?: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      title={title}
+      className={cn(
+        'px-2 py-1 rounded text-[10px] font-semibold uppercase transition-colors',
+        active ? 'bg-teal-600 text-white' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+        className,
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
+/** One label/value cell in the sun readout grid. */
+function Readout({ label, value }: { label: string; value: string }) {
+  return (
+    <>
+      <span className="text-muted-foreground">{label}</span>
+      <span className="text-right text-foreground">{value}</span>
+    </>
+  );
+}

package/src/components/viewer/Viewport.tsx

@@ -7,9 +7,11 @@
  */
 
 import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
-import { Renderer, type VisualEnhancementOptions } from '@ifc-lite/renderer';
+import { Renderer, type VisualEnhancementOptions, type LightingEnvironment } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo, PointCloudAsset } from '@ifc-lite/geometry';
 import { useViewerStore, resolveEntityRef, type MeasurePoint, type SnapVisualization } from '@/store';
+import { LIGHTING_PRESETS } from '@/lib/lighting-presets';
+import { sunLightingForAltitude } from '@/lib/geo/solar-direction';
 import {
   useSelectionState,
   useVisibilityState,
@@ -348,6 +350,51 @@ export function Viewport({
     rendererRef.current?.requestRender();
   }, [cesiumActive, theme]);
 
+  // ── Lighting environment ───────────────────────────────────────────────
+  // Compose the renderer's lighting from the active preset (which brings
+  // its own sky — picking "Day" means day lighting AND a day sky), the
+  // user's exposure trim, and (when the solar study runs) the true sun
+  // position at the site. The sky pass must stay OFF while Cesium is
+  // active — the WebGPU canvas composites over Cesium with a transparent
+  // clear, and Cesium draws its own atmosphere.
+  const envPreset = useViewerStore((s) => s.envPreset);
+  const envExposure = useViewerStore((s) => s.envExposure);
+  const solarEnabledForEnv = useViewerStore((s) => s.solarEnabled);
+  const solarSunDirection = useViewerStore((s) => s.solarSunDirection);
+  const solarSunAltitude = useViewerStore((s) => s.solarSunInfo?.altitude);
+
+  const environment = useMemo<LightingEnvironment>(() => {
+    const preset = LIGHTING_PRESETS[envPreset].environment;
+    const env: LightingEnvironment = {
+      ...preset,
+      skyEnabled: (preset.skyEnabled ?? false) && !cesiumActive,
+      exposure: (preset.exposure ?? 0.85) * envExposure,
+    };
+    if (solarEnabledForEnv && solarSunDirection) {
+      const altitude = solarSunAltitude
+        ?? Math.asin(Math.max(-1, Math.min(1, solarSunDirection[1]))) * (180 / Math.PI);
+      const sun = sunLightingForAltitude(altitude);
+      env.sunDirection = solarSunDirection;
+      env.sunColor = sun.color;
+      env.sunIntensity = (preset.sunIntensity ?? 0.55) * sun.intensityFactor;
+      env.ambientIntensity = (preset.ambientIntensity ?? 0.25) * sun.ambientFactor;
+      // Let the sky derive its palette from the real sun altitude.
+      delete env.sky;
+    }
+    return env;
+  }, [
+    envPreset,
+    envExposure,
+    cesiumActive,
+    solarEnabledForEnv,
+    solarSunDirection,
+    solarSunAltitude,
+  ]);
+  const environmentRef = useLatestRef(environment);
+  useEffect(() => {
+    rendererRef.current?.requestRender();
+  }, [environment]);
+
   // Animation frame ref
   const animationFrameRef = useRef<number | null>(null);
   const lastFrameTimeRef = useRef<number>(0);
@@ -1095,6 +1142,7 @@ export function Viewport({
     sectionRangeRef,
     modelBoundsRef,
     visualEnhancementRef,
+    environmentRef,
     selectedEntityIdsRef,
     coordinateInfoRef,
     isInteractingRef,

package/src/components/viewer/ViewportContainer.tsx

@@ -14,6 +14,9 @@ import { BasketPresentationDock } from './BasketPresentationDock';
 import { BCFOverlay } from './bcf/BCFOverlay';
 import { CesiumOverlay } from './CesiumOverlay';
 import { CesiumPlacementEditor } from './CesiumPlacementEditor';
+import { SunSkyPanel } from './SunSkyPanel';
+import { useSolarEnvironment } from '@/hooks/useSolarEnvironment';
+import { useSolarSweep } from '@/hooks/useSolarSweep';
 import { getViewerStoreApi, useViewerStore } from '@/store';
 import { toGlobalIdFromModels } from '@/store/globalId';
 import { collectIfcBuildingStoreyElementsWithIfcSpace } from '@/store/basketVisibleSet';
@@ -73,6 +76,7 @@ export function ViewportContainer() {
   const resetViewerState = useViewerStore((s) => s.resetViewerState);
   const bcfOverlayVisible = useViewerStore((s) => s.bcfOverlayVisible);
   const cesiumEnabled = useViewerStore((s) => s.cesiumEnabled);
+  const solarEnabled = useViewerStore((s) => s.solarEnabled);
   const cesiumPlacementDraft = useViewerStore((s) => s.cesiumPlacementDraft);
   const cesiumPlacementDraftModelId = useViewerStore((s) => s.cesiumPlacementDraftModelId);
   const anchorModelIdOverride = useViewerStore((s) => s.anchorModelIdOverride);
@@ -266,8 +270,10 @@ export function ViewportContainer() {
 
   // Extract georeferencing info merged with any live mutations (for Cesium overlay).
   // Reacts to: model load, Cesium toggle, and every georef field edit.
+  // Also computed while the solar study runs without Cesium — the WebGPU sun
+  // needs the site's lat/lon + map rotation to track the studied instant.
   const georef = useMemo(() => {
-    if (!cesiumEnabled) return null;
+    if (!cesiumEnabled && !solarEnabled) return null;
 
     const applyPlacementDraft = <T extends { mapConversion?: MapConversion }>(
       modelId: string,
@@ -347,6 +353,7 @@ export function ViewportContainer() {
     return null;
   }, [
     cesiumEnabled,
+    solarEnabled,
     storeModels,
     ifcDataStore,
     georefMutations,
@@ -357,6 +364,12 @@ export function ViewportContainer() {
     anchorModelIdOverride,
   ]);
 
+  // Feed the solar study's sun position into the WebGPU lighting environment
+  // (viewer-space sun direction + panel readout when Cesium is off).
+  useSolarEnvironment(georef);
+  // Sweep animation runs here so collapsing/closing the panel doesn't stop it.
+  useSolarSweep();
+
   // Determine whether Cesium button should be visible (model has georef or user added it via mutations).
   // Runs independently of cesiumEnabled so the button appears/disappears reactively.
   useEffect(() => {
@@ -1104,6 +1117,12 @@ export function ViewportContainer() {
           storeyElevations={georef.storeyElevations}
         />
       )}
+      {/* Sun & Sky panel — sky, lighting presets and the sun-path study.
+          Anchored below the ViewCube (60px cube at top-6 right-6, plus the
+          overflow of its rotating faces) so it never covers navigation. */}
+      <div className="absolute top-32 right-4 z-10 pointer-events-none flex flex-col items-end gap-2">
+        <SunSkyPanel />
+      </div>
       {cesiumEnabled && georef?.mapConversion && georef.baseMapConversion && (
         <CesiumPlacementEditor
           modelId={georef.sourceModelId}

package/src/components/viewer/useAnimationLoop.ts

@@ -17,7 +17,7 @@
  */
 
 import { useEffect, type MutableRefObject, type RefObject } from 'react';
-import type { Renderer, VisualEnhancementOptions } from '@ifc-lite/renderer';
+import type { Renderer, VisualEnhancementOptions, LightingEnvironment } from '@ifc-lite/renderer';
 import type { CoordinateInfo } from '@ifc-lite/geometry';
 import type { SectionPlane } from '@/store';
 
@@ -37,6 +37,8 @@ export interface UseAnimationLoopParams {
   selectedModelIndexRef: MutableRefObject<number | undefined>;
   clearColorRef: MutableRefObject<[number, number, number, number]>;
   visualEnhancementRef: MutableRefObject<VisualEnhancementOptions>;
+  /** Lighting environment (sun, hemisphere ambient, exposure, sky pass). */
+  environmentRef: MutableRefObject<LightingEnvironment>;
   sectionPlaneRef: MutableRefObject<SectionPlane>;
   sectionRangeRef: MutableRefObject<{ min: number; max: number } | null>;
   /**
@@ -77,6 +79,7 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
     selectedModelIndexRef,
     clearColorRef,
     visualEnhancementRef,
+    environmentRef,
     sectionPlaneRef,
     sectionRangeRef,
     modelBoundsRef,
@@ -102,6 +105,7 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
     let lastRotationUpdate = 0;
     let lastScaleUpdate = 0;
     let lastRenderTime = 0;
+    let wasAnimating = false;
 
     // Adaptive render throttle: large models get fewer FPS during continuous
     // rendering (interaction + inertia) to prevent the main thread from being
@@ -150,6 +154,16 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
       // 2. Camera update (animation / inertia)
       const isAnimating = camera.update(deltaTime);
 
+      // Camera tweens (Home / view cube / zoom-extent) render their frames
+      // with isInteracting=true; without a settle render the last tween frame
+      // could stay on screen at degraded quality until the next incidental
+      // render. Mouse/wheel/touch paths already request their own settle
+      // frame on release — this covers the animation path.
+      if (wasAnimating && !isAnimating && !isInteractingRef.current) {
+        renderer.requestRender();
+      }
+      wasAnimating = isAnimating;
+
       // 3. Render if anything changed
       // Peek first — only consume the flag when we actually commit to rendering.
       // This prevents a throttled frame from eating the dirty flag.
@@ -174,7 +188,11 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
           selectedModelIndex: selectedModelIndexRef.current,
           clearColor: clearColorRef.current,
           visualEnhancement: visualEnhancementRef.current,
+          environment: environmentRef.current,
           isInteracting: isInteractingRef.current || isAnimating,
+          // Let the effects governor judge missed frames against the
+          // intentional large-model throttle instead of display refresh.
+          interactionFrameIntervalMs: continuousThrottleMs || undefined,
           buildingRotation: coordinateInfoRef.current?.buildingRotation,
           sectionPlane: activeToolRef.current === 'section' ? {
             axis: sectionPlaneRef.current.axis,

package/src/disable-react-dev-perf-track.ts

@@ -0,0 +1,38 @@
+/* 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/. */
+
+/**
+ * Disable React 19.2's DEV-mode component-render Performance tracking.
+ *
+ * react-dom (dev build) calls `logComponentRender` on every commit whose props
+ * changed; it recursively walks the prop diff (`addObjectDiffToProperties` →
+ * `addObjectToProperties`, a `for..in` recursion with no depth/size bound) to feed
+ * the browser's Performance timeline. The viewer passes large IFC `geometryResult`
+ * (typed arrays — `for..in` enumerates every index across thousands of meshes) and
+ * the `ifcDataStore` (circular relationship-graph refs → unbounded recursion) as
+ * props, so on big models (schependomlaan, Holter Tower) the diff array grows until
+ * `RangeError: Invalid array length` and a multi-GB main-thread OOM — the load
+ * "stops halfway" and the tab stalls/crashes. (Playwright-confirmed: with this
+ * tracker off, Holter loads in ~350MB instead of OOMing at ~4GB.)
+ *
+ * React gates the entire tracker on `supportsUserTiming`, cached at react-dom init
+ * from `typeof performance.measure === 'function'`. Making `performance.measure`
+ * unavailable BEFORE react-dom initializes (this is the first import in main.tsx)
+ * disables ONLY this tracking; the viewer times with `performance.now()`, not
+ * `measure`. DEV-only — the production build strips the tracker, so this is a no-op.
+ */
+if (import.meta.env.DEV && typeof performance !== 'undefined') {
+  try {
+    (performance as unknown as { measure?: unknown }).measure = undefined;
+  } catch (err) {
+    // `performance.measure` is read-only in some engines — surface it so a
+    // failed patch (which leaves large models OOM-prone) isn't silently hidden.
+    if (typeof console !== 'undefined') {
+      console.warn(
+        '[perf-track] could not disable React DEV perf tracking; large models may OOM',
+        err,
+      );
+    }
+  }
+}

package/src/hooks/has-entity-type.ts

@@ -0,0 +1,33 @@
+/* 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 type { IfcDataStore } from '@ifc-lite/parser';
+
+/**
+ * Cheap presence check against the data store's type index — true if the store
+ * contains at least one entity of any of the given IFC types.
+ *
+ * `entityIndex.byType` indexes EVERY parsed entity (it backs on-demand
+ * extraction), so absence here is authoritative: a model with no `IfcAlignment`
+ * truly has none. Keys are the raw IFC type strings, which are UPPERCASE in
+ * STEP files but can be mixed-case on some cache-load paths, so we check both.
+ *
+ * Used to skip the always-on full-source WASM scans (`parseAlignmentLines`,
+ * `parseGridLines`, `parseSymbolicRepresentations`) on models that have none of
+ * the relevant entities — those scans copy the entire IFC source into the WASM
+ * heap (hundreds of ms on a 170MB file) on the main thread during load, purely
+ * to find nothing.
+ *
+ * Returns `true` (i.e. do NOT skip) when the index is missing/empty, so gating
+ * can never drop real data — worst case is the pre-existing behaviour.
+ */
+export function hasEntityType(store: IfcDataStore, ...types: string[]): boolean {
+  const byType = store.entityIndex?.byType;
+  if (!byType || byType.size === 0) return true;
+  for (const t of types) {
+    if ((byType.get(t.toUpperCase())?.length ?? 0) > 0) return true;
+    if ((byType.get(t)?.length ?? 0) > 0) return true;
+  }
+  return false;
+}