diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 93dea9f55..239da85b2 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -8566,7 +8566,12 @@ Playback advances two seconds after all products settle, wraps, and stops with fewer than two union times or when all products are suspended. Hidden documents, reduced motion and unavailable imagery hosts suspend products. Re-enabling or restoring a host joins the retained history target. The wind row explicitly says -“Forecast · does not follow history” while the observed clock is in history mode. +“Forecast · does not follow history” while the observed clock is in history mode, +unless a host follows the world clock for `wind` (`weatherClock.follows('wind')`): +its source then follows the timeline and the row says nothing of it. In history +mode, frame ages and the “Source observations delayed” status are measured from +the timeline time rather than the wall clock, and the timeline readout shows the +time alone; live, they count from now as before. The catalog exposes `weatherClock` and destroys it with its lifetime signal. Source, opacity, coverage navigation and transport controls live in the WEATHER diff --git a/src/layers/weather/clock.js b/src/layers/weather/clock.js index 7384935b0..754887235 100644 --- a/src/layers/weather/clock.js +++ b/src/layers/weather/clock.js @@ -248,6 +248,12 @@ export function createWeatherClock({ }, getTimeline, selectFor, + /** + * Whether layer `id` follows the world clock (see the world clock's + * `follows`): a host that follows it for a layer of its own, such as + * wind, gives that layer the timeline time rather than the live edge. + */ + follows: (id) => world.follows(id), setTarget(time) { if (destroyed) return Promise.resolve(false); if (!Number.isFinite(Date.parse(time))) diff --git a/src/layers/weather/index.js b/src/layers/weather/index.js index dcfc06081..215061970 100644 --- a/src/layers/weather/index.js +++ b/src/layers/weather/index.js @@ -120,9 +120,17 @@ export function createWeatherLayer({ rendering?.cancelPrefetch?.(); notify(); }); + // Ages and delays are measured from the time the layer shows: the world + // clock's time at a past time, the wall clock while live. + const worldNow = () => { + const shared = clock?.getState(); + return shared?.mode === 'history' && shared.target + ? Date.parse(shared.target) + : Date.now(); + }; const observationDelayed = () => manifest?.latest && - Date.now() - Date.parse(manifest.latest) > + worldNow() - Date.parse(manifest.latest) > (product === 'clouds' ? 240 : lightning ? 45 : 20) * 60_000; const stop = () => { if (clock) return; @@ -573,7 +581,7 @@ export function createWeatherLayer({ const index = times.indexOf(time); const current = index >= 0; const age = time - ? Math.max(0, Math.floor((Date.now() - Date.parse(time)) / 60000)) + ? Math.max(0, Math.floor((worldNow() - Date.parse(time)) / 60000)) : null; const lag = age === null diff --git a/src/layers/weather/weather.test.mjs b/src/layers/weather/weather.test.mjs index 2a6d62e40..4eee04135 100644 --- a/src/layers/weather/weather.test.mjs +++ b/src/layers/weather/weather.test.mjs @@ -2681,3 +2681,44 @@ test('the layer hands rendering a frame source only when its feed is one', () => assert.equal(typeof seen[1].getTile, 'function'); assert.equal(seen[1].getImage, undefined); }); + +test('at a past time a frame is aged and its source judged delayed from the timeline time', async (t) => { + // Live at twenty minutes past the newest frame: the source is late. + t.mock.method(Date, 'now', () => Date.parse(times[2]) + 25 * 60_000); + const clock = createWeatherClock(); + const h = layerHarness({ clock }); + t.after(() => { + h.layer.destroy(); + clock.destroy(); + }); + const update = h.layer.update(); + await flush(); + h.stages.at(-1).finish(); + await update; + await flush(); + assert.equal( + h.layer.getRowControls().summary.status, + 'Source observations delayed', + ); + assert.match(h.layer.getRowControls().summary.detail, /25m ago/); + + // Years later, the world clock is moved back to the newest frame. + Date.now.mock.mockImplementation(() => Date.parse('2032-01-01T00:00:00Z')); + void clock.setTarget(times[2]); + await flush(); + h.stages.at(-1)?.finish(); + await flush(); + assert.equal(clock.getState().mode, 'history'); + const controls = h.layer.getRowControls(); + assert.equal(controls.summary.status, null); + assert.match(controls.summary.detail, /History · 09-15 20:10 UTC · 0m ago/); + assert.equal(h.layer.getStats().stale, false); + + // Ten minutes after the newest frame, the frame is ten minutes old. + void clock.setTarget('2026-09-15T20:20:00.000Z'); + await flush(); + h.stages.at(-1)?.finish(); + await flush(); + assert.match(h.layer.getRowControls().summary.detail, /10m ago · nearest/); + assert.equal(h.layer.getRowControls().summary.status, null); +}); diff --git a/src/layers/wind/index.js b/src/layers/wind/index.js index 567aaa91b..8fb69b53e 100644 --- a/src/layers/wind/index.js +++ b/src/layers/wind/index.js @@ -258,8 +258,9 @@ export function createWindLayer({ return { model, overlay, paused, units }; }, getRowControls() { + // A source that follows the timeline shows the wind at its time. const historyStatus = - clock?.getState().mode === 'history' + clock?.getState().mode === 'history' && !clock.follows?.('wind') ? t('Forecast · does not follow history') : null; const valid = formatWindValidTime(manifest?.cycle?.validIso); diff --git a/src/layers/wind/index.test.mjs b/src/layers/wind/index.test.mjs index 223867392..45a54b24e 100644 --- a/src/layers/wind/index.test.mjs +++ b/src/layers/wind/index.test.mjs @@ -454,3 +454,19 @@ test('a parameter replacement during manager enable does not roll the layer back assert.equal(layer.getStats().count, 4); await manager.destroyAll(); }); + +test('wind whose source follows the timeline drops the note that it does not follow the timeline', async () => { + const { createWeatherClock } = await import('../weather/clock.js'); + const { createWorldClock } = await import('../../time/worldClock.js'); + const world = createWorldClock(); + const clock = createWeatherClock({ world }); + const layer = createWindLayer({ feed: { getSnapshot: async () => snapshot('gfs') }, clock }); + world.follow('wind'); + await clock.setTarget('2026-09-14T12:00:00.000Z'); + assert.equal(clock.getState().mode, 'history'); + assert.doesNotMatch(layer.getRowControls().info, /does not follow history/); + world.follow('wind', false); + assert.match(layer.getRowControls().info, /Forecast · does not follow history/); + layer.destroy(); + clock.destroy(); +}); diff --git a/src/ui/weatherPanel.js b/src/ui/weatherPanel.js index bb285403e..273f5b11c 100644 --- a/src/ui/weatherPanel.js +++ b/src/ui/weatherPanel.js @@ -21,11 +21,12 @@ const utc = (time) => ? `${formatUtcDayMonth(time)} ${utcClock(time)}` : t('Unavailable'); const clockTime = (time) => utcClock(time) || t('Unavailable'); -const age = (time) => { - const minutes = Math.max( - 0, - Math.floor((Date.now() - Date.parse(time)) / 60_000), - ); +// Ages are measured from `nowMs`: the world clock's time at a past time, the +// wall clock while live. +const minutesBefore = (time, nowMs = Date.now()) => + Math.max(0, Math.floor((nowMs - Date.parse(time)) / 60_000)); +const age = (time, nowMs) => { + const minutes = minutesBefore(time, nowMs); return minutes >= 60 ? t('{hours}h {minutes}m ago', { hours: Math.floor(minutes / 60), @@ -33,12 +34,21 @@ const age = (time) => { }) : t('{minutes}m ago', { minutes }); }; -const historyTime = (time) => - t('{time} · {minutes} min ago', { - time: clockTime(time), - minutes: Math.max(0, Math.floor((Date.now() - Date.parse(time)) / 60_000)), - }); -const dated = (time) => `${utc(time)} · ${age(time)}`; +// A frame's time on the timeline: its age while live; at a past time, the +// clock time alone, as the timeline time is the one it is measured from. +const historyTime = (time, state) => + state?.mode === 'history' + ? clockTime(time) + : t('{time} · {minutes} min ago', { + time: clockTime(time), + minutes: minutesBefore(time), + }); +const dated = (time, nowMs) => `${utc(time)} · ${age(time, nowMs)}`; +/** The time the observed products show: the timeline time, or now while live. */ +const shownNow = (state) => + state?.mode === 'history' && Number.isFinite(Date.parse(state.target)) + ? Date.parse(state.target) + : Date.now(); const set = (node, key, value) => { if (node[key] !== value) node[key] = value; }; @@ -90,7 +100,7 @@ export function createWeatherPanel({ }, transport: { onCommit: (tick) => clock?.setTarget(tick), - onPreview: historyTime, + onPreview: (time) => historyTime(time, clock?.getState()), onStep: (direction) => clock?.step(direction), onLatest: () => clock?.latest(), onPlay: () => clock?.togglePlay(), @@ -149,7 +159,7 @@ export function createWeatherPanel({ readout: state.mode === 'latest' ? t('LATEST · newest per product') - : historyTime(state.target), + : historyTime(state.target, state), }; const models = active.map((entry) => { const { id, icon, summary, legend = [], list } = entry; @@ -167,7 +177,7 @@ export function createWeatherPanel({ ? t('No frame within {gap} min of {time}', { gap, time }) : t('No frame within {gap} h of {time}', { gap: gap / 60, time }); } else if (shown) { - detail = dated(shown); + detail = dated(shown, shownNow(state)); if (state.mode === 'history') detail = Date.parse(shown) === Date.parse(state.target) @@ -179,7 +189,8 @@ export function createWeatherPanel({ valid: utc(summary.validTime), issued: utc(summary.issuedTime), }); - if (state.mode === 'history') + // Unless its source follows the timeline, wind stays at the live edge. + if (state.mode === 'history' && !clock?.follows?.(id)) detail = t('{detail} · Does not follow history', { detail }); } const lines = [ diff --git a/src/ui/weatherPanel.test.mjs b/src/ui/weatherPanel.test.mjs index b3978e070..4a438e4d9 100644 --- a/src/ui/weatherPanel.test.mjs +++ b/src/ui/weatherPanel.test.mjs @@ -506,9 +506,10 @@ test('compact lines show observation age, forecast validity, storm selection or 'Forecast · valid 09-22 01:00 UTC', ); f.state({ mode: 'history', target: ticks[1] }); + // At a past time a frame's age counts from the timeline time. assert.equal( compact(radar.id).textContent, - '09-22 01:05 UTC · 8m ago · synced', + '09-22 01:05 UTC · 0m ago · synced', ); assert.equal( compact(wind.id).textContent, @@ -523,7 +524,7 @@ test('compact lines show observation age, forecast validity, storm selection or }); assert.equal( compact(radar.id).textContent, - '09-22 01:00 UTC · 13m ago · nearest', + '09-22 01:00 UTC · 5m ago · nearest', ); clickHeader(f, wind.id); assert.equal( @@ -787,3 +788,44 @@ test('source-supplied legend units are shown as given; catalog units are transla setLocale('en'); } }); + +test('at a past time, frame ages and the timeline readout count from the timeline time, not now', (t) => { + t.mock.timers.enable({ + apis: ['Date'], + now: Date.parse('2032-01-01T00:00:00Z'), + }); + const f = fixture(); + const view = createWeatherPanel(f); + view.update([radar]); + f.state({ + mode: 'history', + target: '2026-09-22T01:20:00Z', + products: [{ id: radar.id, shown: ticks[1], selected: ticks[1] }], + }); + assert.equal( + line(f, radar.id, 'time').textContent, + '09-22 01:05 UTC · 15m ago · nearest', + ); + const readout = f.find((n) => n.textContent === '01:20 UTC'); + assert.ok(readout, 'the readout names the timeline time'); + assert.doesNotMatch(timelineHost(f).textContent, /min ago/); + view.destroy(); +}); + +test('the wind card notes it stays live only while its source does not follow the timeline', () => { + const f = fixture(); + const following = new Set(); + f.clock.follows = (id) => following.has(id); + const view = createWeatherPanel(f); + view.update([wind, radar]); + f.state({ mode: 'history', target: ticks[1] }); + assert.match(line(f, 'wind', 'time').textContent, /Does not follow history/); + following.add('wind'); + f.state({ target: ticks[0] }); + assert.match(line(f, 'wind', 'time').textContent, /^Forecast · valid /); + assert.doesNotMatch( + line(f, 'wind', 'time').textContent, + /Does not follow history/, + ); + view.destroy(); +});