Merge fix/355-zoned-ignition: build the ignition instant in the model's timezone

Closes #355.

Author: spydmobile

frontend/src/App.tsx

@@ -24,6 +24,7 @@ import {
   NotificationPermissionBanner,
 } from './features/Notifications';
 import { resolveIgnitionLatitude } from './features/ModelSetup/utils/ignitionLatitude';
+import { resolveZonedInstant } from './features/ModelSetup/utils/zonedInstant';
 import { runModel } from './services/api';
 import { registerServiceWorker } from './services/serviceWorker';
 import type { ModelResultsResponse } from './features/ModelReview/types';
@@ -187,7 +188,12 @@ function AppContent() {
       }
 
       // Build time range
-      const startDateTime = new Date(`${data.temporal.startDate}T${data.temporal.startTime}`);
+      // Resolved in the model's own timezone, never the browser's (#355).
+      const startDateTime = resolveZonedInstant(
+        data.temporal.startDate,
+        data.temporal.startTime,
+        data.temporal.timezone,
+      );
       const endDateTime = new Date(startDateTime.getTime() + data.temporal.durationHours * 60 * 60 * 1000);
 
       // Helper to read file content

frontend/src/features/ModelSetup/utils/__tests__/weatherPreflight.test.ts

@@ -14,6 +14,7 @@ import {
   type StartingCodeCandidate,
 } from '../weatherPreflight.js';
 import type { ModelSetupData } from '../../types/index.js';
+import { resolveZonedInstant } from '../zonedInstant.js';
 
 const CANDIDATE: StartingCodeCandidate = {
   ffmc: 84.65,
@@ -73,14 +74,19 @@ describe('buildIgnitionInstant', () => {
     expect(iso).toMatch(/Z$|[+-]\d{2}:\d{2}$/);
   });
 
-  it('matches what App.tsx sends as timeRange.start, byte for byte', () => {
-    // Deliberate: App.tsx:189 parses this naive string in the BROWSER zone,
-    // which is wrong (#355). The gate reproduces that exactly so the reading
-    // it offers cannot disagree with the run that follows. When #355 is fixed,
-    // both move together and this test is what proves it.
-    const { startDate, startTime } = baseData().temporal;
-    const appTsx = new Date(`${startDate}T${startTime}`).toISOString();
-    expect(buildIgnitionInstant(baseData().temporal)).toBe(appTsx);
+  it('resolves the wall clock in the MODEL timezone, not the browser zone', () => {
+    // 2026-08-04 12:00 in America/Edmonton (MDT, UTC-6) is 18:00Z. Before #355
+    // this depended on where the operator was sitting.
+    expect(buildIgnitionInstant(baseData().temporal)).toBe('2026-08-04T18:00:00.000Z');
+  });
+
+  it('agrees with what App.tsx sends as timeRange.start', () => {
+    // Both now go through resolveZonedInstant, so the codes offered cannot
+    // disagree with the run that follows.
+    const { startDate, startTime, timezone } = baseData().temporal;
+    expect(buildIgnitionInstant(baseData().temporal)).toBe(
+      resolveZonedInstant(startDate, startTime, timezone).toISOString(),
+    );
   });
 });
 

frontend/src/features/ModelSetup/utils/__tests__/zonedInstant.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Zone-aware instant construction — issue #355.
+ *
+ * The wizard collects a date, a time, and an IANA timezone. Those three must
+ * combine into one instant. Every existing site does `new Date("YYYY-MM-DDTHH:mm")`,
+ * which JavaScript reads in the BROWSER's zone, so the declared timezone is
+ * ignored and the same inputs produce different runs by operator location.
+ *
+ * No date library exists in this package, deliberately — these use Intl, the
+ * same mechanism dateHelpers.ts already relies on.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveZonedInstant } from '../zonedInstant.js';
+
+describe('resolveZonedInstant', () => {
+  it('resolves a summer mountain-daylight time to the right instant', () => {
+    // 2026-08-04 12:00 MDT (UTC-6) === 18:00Z. Vita's ignition.
+    const instant = resolveZonedInstant('2026-08-04', '12:00', 'America/Edmonton');
+    expect(instant.toISOString()).toBe('2026-08-04T18:00:00.000Z');
+  });
+
+  it('resolves a winter mountain-standard time, offset and all', () => {
+    // 2026-01-04 12:00 MST (UTC-7) === 19:00Z. The offset differs from summer,
+    // which a fixed offset would get wrong half the year.
+    const instant = resolveZonedInstant('2026-01-04', '12:00', 'America/Edmonton');
+    expect(instant.toISOString()).toBe('2026-01-04T19:00:00.000Z');
+  });
+
+  it('handles a half-hour offset zone', () => {
+    // Newfoundland daylight time is UTC-2:30.
+    const instant = resolveZonedInstant('2026-08-04', '12:00', 'America/St_Johns');
+    expect(instant.toISOString()).toBe('2026-08-04T14:30:00.000Z');
+  });
+
+  it('is the identity for UTC', () => {
+    const instant = resolveZonedInstant('2026-08-04', '12:00', 'UTC');
+    expect(instant.toISOString()).toBe('2026-08-04T12:00:00.000Z');
+  });
+
+  it('resolves an eastern-hemisphere zone', () => {
+    // Tokyo is UTC+9 year round.
+    const instant = resolveZonedInstant('2026-08-04', '12:00', 'Asia/Tokyo');
+    expect(instant.toISOString()).toBe('2026-08-04T03:00:00.000Z');
+  });
+
+  it('produces different instants for the same wall clock in different zones', () => {
+    // The whole point of #355: an Ontario duty officer and an NWT one entering
+    // identical wizard values must get the fire's zone, not their own.
+    const edmonton = resolveZonedInstant('2026-08-04', '12:00', 'America/Edmonton');
+    const toronto = resolveZonedInstant('2026-08-04', '12:00', 'America/Toronto');
+
+    expect(edmonton.getTime()).not.toBe(toronto.getTime());
+    expect(edmonton.getTime() - toronto.getTime()).toBe(2 * 60 * 60 * 1000);
+  });
+
+  it('crosses a DST boundary correctly on the day the clocks go forward', () => {
+    // 2026-03-08 is the US/Canada spring-forward date. 03:00 local is MDT.
+    const instant = resolveZonedInstant('2026-03-08', '03:00', 'America/Edmonton');
+    expect(instant.toISOString()).toBe('2026-03-08T09:00:00.000Z');
+  });
+
+  it('resolves a time on the day the clocks go back', () => {
+    // 2026-11-01, fall-back. 12:00 local is MST (UTC-7) by midday.
+    const instant = resolveZonedInstant('2026-11-01', '12:00', 'America/Edmonton');
+    expect(instant.toISOString()).toBe('2026-11-01T19:00:00.000Z');
+  });
+
+  it('accepts a time with seconds', () => {
+    const instant = resolveZonedInstant('2026-08-04', '12:30:45', 'UTC');
+    expect(instant.toISOString()).toBe('2026-08-04T12:30:45.000Z');
+  });
+
+  it('defaults a missing time to midnight local', () => {
+    const instant = resolveZonedInstant('2026-08-04', '', 'America/Edmonton');
+    expect(instant.toISOString()).toBe('2026-08-04T06:00:00.000Z');
+  });
+
+  describe('fail-fast', () => {
+    it('throws on an unknown timezone rather than silently using the browser zone', () => {
+      expect(() => resolveZonedInstant('2026-08-04', '12:00', 'Mars/Olympus_Mons')).toThrow(/timezone/i);
+    });
+
+    it('throws on a malformed date', () => {
+      expect(() => resolveZonedInstant('not-a-date', '12:00', 'UTC')).toThrow(/date/i);
+    });
+
+    it('throws on a malformed time', () => {
+      expect(() => resolveZonedInstant('2026-08-04', '25:99', 'UTC')).toThrow(/time/i);
+    });
+  });
+});

frontend/src/features/ModelSetup/utils/weatherPreflight.ts

@@ -18,6 +18,7 @@
  */
 
 import type { ModelSetupData, TemporalData, WeatherData } from '../types/index.js';
+import { resolveZonedInstant } from './zonedInstant.js';
 
 /** The reading recovered by the backend, as it arrives over JSON. */
 export interface StartingCodeCandidate {
@@ -45,18 +46,15 @@ export function needsPreflight(weather: WeatherData): boolean {
 }
 
 /**
- * The ignition instant, built exactly as App.tsx:189 builds timeRange.start.
+ * The ignition instant, resolved in the MODEL's timezone.
  *
- * That line parses a naive date-time string, which JavaScript reads in the
- * BROWSER's zone rather than the model's declared timezone — filed as #355.
- * This reproduces the bug deliberately: the pre-flight answer depends on which
- * daily reading precedes ignition, so if the gate computed a more correct
- * instant than the run that follows it, the codes offered could disagree with
- * the codes the model actually needed. One consistent error beats two
- * inconsistent ones. When #355 is fixed, both move together.
+ * Previously this deliberately reproduced App.tsx:189's browser-zone bug so the
+ * pre-flight answer could not disagree with the run that followed it. #355 is
+ * now fixed, and both sites moved together — App.tsx and this helper share
+ * resolveZonedInstant, so they cannot drift apart again.
  */
 export function buildIgnitionInstant(temporal: TemporalData): string {
-  return new Date(`${temporal.startDate}T${temporal.startTime}`).toISOString();
+  return resolveZonedInstant(temporal.startDate, temporal.startTime, temporal.timezone).toISOString();
 }
 
 /**

frontend/src/features/ModelSetup/utils/zonedInstant.ts

@@ -0,0 +1,102 @@
+/**
+ * Zone-aware instant construction — issue #355.
+ *
+ * The wizard collects a date, a time, and an IANA timezone. Combining them with
+ * `new Date("YYYY-MM-DDTHH:mm")` reads the string in the BROWSER's zone, so the
+ * timezone the user explicitly chose is ignored and the same inputs produce
+ * different instants depending on where the operator happens to be sitting.
+ *
+ * There is no date library in this package and we are not adding one for this.
+ * Intl carries the whole timezone database, and dateHelpers.ts already leans on
+ * it, so the offset is looked up rather than assumed — which also means DST and
+ * half-hour zones fall out correctly instead of needing special cases.
+ */
+
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIME_PATTERN = /^(\d{2}):(\d{2})(?::(\d{2}))?$/;
+
+/**
+ * How far the given zone sits from UTC at a particular instant, in ms.
+ *
+ * Works by asking Intl what wall-clock time the zone shows at that instant,
+ * then reading that wall clock back as if it were UTC. The difference is the
+ * offset. hourCycle h23 keeps midnight as 00 rather than 24.
+ */
+function zoneOffsetMs(instant: number, timeZone: string): number {
+  const formatter = new Intl.DateTimeFormat('en-CA', {
+    timeZone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+
+  const parts: Record<string, number> = {};
+  for (const { type, value } of formatter.formatToParts(new Date(instant))) {
+    if (type !== 'literal') parts[type] = Number(value);
+  }
+
+  const wallClockAsUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+  );
+
+  return wallClockAsUtc - instant;
+}
+
+/** Rejects an unknown zone rather than letting Intl fall back to the browser's. */
+function assertZone(timeZone: string): void {
+  try {
+    new Intl.DateTimeFormat('en-CA', { timeZone });
+  } catch {
+    throw new Error(`Unknown timezone: ${timeZone}`);
+  }
+}
+
+/**
+ * @param date     YYYY-MM-DD
+ * @param time     HH:mm or HH:mm:ss. Empty means midnight local.
+ * @param timeZone IANA identifier — the model's zone, never the browser's.
+ */
+export function resolveZonedInstant(date: string, time: string, timeZone: string): Date {
+  assertZone(timeZone);
+
+  const dateMatch = DATE_PATTERN.exec(date);
+  if (!dateMatch) {
+    throw new Error(`Invalid date "${date}" — expected YYYY-MM-DD`);
+  }
+
+  const normalisedTime = time.trim() === '' ? '00:00' : time.trim();
+  const timeMatch = TIME_PATTERN.exec(normalisedTime);
+  if (!timeMatch) {
+    throw new Error(`Invalid time "${time}" — expected HH:mm`);
+  }
+
+  const [, year, month, day] = dateMatch.map(Number);
+  const [, hour, minute, second] = timeMatch.map((v) => Number(v ?? 0));
+
+  if (month < 1 || month > 12 || day < 1 || day > 31) {
+    throw new Error(`Invalid date "${date}"`);
+  }
+  if (hour > 23 || minute > 59 || (second || 0) > 59) {
+    throw new Error(`Invalid time "${time}"`);
+  }
+
+  // Read the wall clock as if it were UTC, then walk back by the zone's offset.
+  const wallClockAsUtc = Date.UTC(year, month - 1, day, hour, minute, second || 0);
+
+  // Two passes. The first offset is looked up at the wrong instant by exactly
+  // the offset itself; re-reading at the corrected instant settles it, which is
+  // what makes DST changeover days land correctly.
+  let instant = wallClockAsUtc - zoneOffsetMs(wallClockAsUtc, timeZone);
+  instant = wallClockAsUtc - zoneOffsetMs(instant, timeZone);
+
+  return new Date(instant);
+}