@ifc-lite/viewer 1.28.1 → 1.30.0

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;
+}

package/src/lib/recent-files.ts

@@ -24,19 +24,11 @@ export interface RecentFileEntry {
   name: string;
   size: number;
   timestamp: number;
-  /** Native filesystem path (Tauri only) — enables direct re-open from disk. */
-  path?: string;
-  /** Last-modified epoch in ms when known (Tauri stat). */
-  modifiedMs?: number | null;
 }
 
-// Input shape for `recordRecentFiles` — accepts the optional native fields
-// so callers can persist a path / modifiedMs without lying about the type.
 export type RecentFileInput = {
   name: string;
   size: number;
-  path?: string;
-  modifiedMs?: number | null;
 };
 
 // ── localStorage (metadata) ─────────────────────────────────────────────
@@ -46,12 +38,10 @@ export function getRecentFiles(): RecentFileEntry[] {
   catch { return []; }
 }
 
-// Path-aware dedup key: when a native filesystem path is available it
-// uniquely identifies the file (so `A/model.ifc` and `B/model.ifc` are
-// kept separate); otherwise fall back to the name (browser uploads
-// don't expose paths).
-function recentKey(f: { name: string; path?: string }): string {
-  return f.path ? `path:${f.path}` : `name:${f.name}`;
+// Browser uploads don't expose filesystem paths, so the file name is the
+// dedup key.
+function recentKey(f: { name: string }): string {
+  return `name:${f.name}`;
 }
 
 export function recordRecentFiles(files: RecentFileInput[]) {
@@ -62,8 +52,6 @@ export function recordRecentFiles(files: RecentFileInput[]) {
       name: f.name,
       size: f.size,
       timestamp: Date.now(),
-      path: f.path,
-      modifiedMs: f.modifiedMs ?? null,
     }));
     localStorage.setItem(KEY, JSON.stringify([...entries, ...existing].slice(0, 10)));
   } catch (err) {
@@ -130,14 +118,6 @@ export async function cacheFileBlobs(files: File[]): Promise<void> {
 
 /** Retrieve a cached file blob and reconstruct a File object. */
 export async function getCachedFile(target: string | RecentFileEntry): Promise<File | null> {
-  // Path-bearing entries (Tauri filesystem) are uniquely keyed by path
-  // in the recents list, but the IndexedDB cache is name-keyed. A
-  // name-only hit could resolve `A/model.ifc` to the cached blob from
-  // `B/model.ifc`, opening the wrong file silently. Defer to the
-  // caller's native re-open path instead.
-  if (typeof target !== 'string' && target.path) {
-    return null;
-  }
   const name = typeof target === 'string' ? target : target.name;
   try {
     const db = await openDB();

package/src/lib/solar-time.ts

@@ -0,0 +1,55 @@
+/* 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/. */
+
+/**
+ * Display-frame time helpers for the solar study.
+ *
+ * The studied instant is always stored as an absolute UTC epoch. For display
+ * the UI defaults to *local solar time* derived from the site longitude
+ * (15°/hour) — civil-timezone-agnostic on purpose, since sun-path studies
+ * care about solar time and a longitude offset needs no timezone database or
+ * DST rules. The user can switch the readout to UTC.
+ */
+
+export const MS_PER_MIN = 60_000;
+export const MS_PER_DAY = 86_400_000;
+
+/** Longitude → display offset in minutes (local solar time), or 0 for UTC. */
+export function solarDisplayOffsetMinutes(useLocal: boolean, longitude: number | undefined): number {
+  if (!useLocal || longitude === undefined) return 0;
+  return Math.round((longitude / 15) * 60);
+}
+
+/** Epoch ms shifted into the display frame (UTC + offset). */
+export function toSolarDisplay(ms: number, offsetMin: number): Date {
+  return new Date(ms + offsetMin * MS_PER_MIN);
+}
+
+/** "YYYY-MM-DD" of the display-frame day for an instant. */
+export function toSolarDateInputValue(ms: number, offsetMin: number): string {
+  const d = toSolarDisplay(ms, offsetMin);
+  const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(d.getUTCDate()).padStart(2, '0');
+  return `${d.getUTCFullYear()}-${mm}-${dd}`;
+}
+
+/** Minutes since midnight in the display frame. */
+export function solarMinutesOfDay(ms: number, offsetMin: number): number {
+  const d = toSolarDisplay(ms, offsetMin);
+  return d.getUTCHours() * 60 + d.getUTCMinutes();
+}
+
+/** Compose an absolute UTC epoch from a display-frame date string + minutes. */
+export function composeSolarMs(dateStr: string, minutes: number, offsetMin: number): number {
+  const [y, m, d] = dateStr.split('-').map(Number);
+  const displayMs = Date.UTC(y, (m ?? 1) - 1, d ?? 1, Math.floor(minutes / 60), minutes % 60, 0);
+  return displayMs - offsetMin * MS_PER_MIN;
+}
+
+/** Epoch ms → "HH:MM" in the display frame. */
+export function formatSolarTime(ms: number | null, offsetMin: number): string {
+  if (ms === null) return '—';
+  const d = toSolarDisplay(ms, offsetMin);
+  return `${String(d.getUTCHours()).padStart(2, '0')}:${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}