Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,89 @@ crate follows [SemVer](https://semver.org/).

## [Unreleased]

### Upgrade notes

- **The ephemeris snapshot contract is now `ephemeris-snapshot.v4`.** v4 adds the root
`star_frame`, catalogue right ascension and declination on stars, the `future_nominal_utc`
and `modeled_future` time states, and a nullable DUT1 uncertainty. The published v3 schema
is unchanged and still validates archived snapshots
(`tools/validate_ephemeris_snapshot.py --historical-v3`). See
[the contract notes](docs/EPHEMERIS_V3.md).
- **A self-hosted ephemeris server and the web app must be updated together.** The server now
answers `/v4/sky`; `/v1/sky`, `/v2/sky` and `/v3/sky` return HTTP 409 with an upgrade
message. A new web app pointed at an old server, or an old web app pointed at a new server,
receives no remote sky data. On-device computation is unaffected, and a deployment that sets
no `SOL_EPHEMERIS_SERVER` (including the public Pages site) needs no action. See
[the server notes](services/ephemeris-server/README.md).
- **`solar-ephemeris` has a breaking public API change; its next crates.io version must be
0.3.0.** The public TOP2013 and VSOP2013 coefficient structs gained phase-index fields
(`TopTerm::phase`, the per-body `multipliers` table and the VSOP `phase` index), so external
code that builds these structs with literals no longer compiles. The workspace version stays
0.2.0 in this tree because both engines stamp it into snapshots, the committed research data
bundle and the hash-bound evidence fixtures. Change the version, and regenerate those files,
in the same change that publishes the crate. crates.io already holds 0.2.0, so that version
cannot be published again.
- **Browser WASM is built with a dedicated Cargo profile.** `tools/build_wasm.py` builds with
`--profile wasm-release` (abort on panic, ephemeris optimized for speed) and records that
profile in the build receipt. Output from a plain `cargo build --release` is not accepted by
the release builder. Native `release` builds now unwind by default.

### Changed

- **The web app ships as bundled view and shared chunks.** A pinned esbuild step emits one
entry per view plus shared chunks, external source maps with embedded sources, and
original-source and output hashes in the release manifest. Full moon and star catalogues load
on selection, search or galaxy demand instead of at System startup.
- **Raw planetary positions are about five times cheaper to compute.** TOP2013 and VSOP2013
reuse identical phase evaluations within one calculation while preserving argument and
summation order. The 4x CPU-throttled p95 fell from 45.3 ms to 8.8 ms under the unchanged
16 ms gate, and 324 position values at 12 epochs match the previous WASM output bit for bit.
- **System labels stay attached to what they name.** A label needs a finite on-screen target
with adjacent clearance; crowded names are suppressed and remain reachable through search and
the catalogue. The selected body keeps its label near a canvas corner. A target hidden behind
the jump bar is not labelled.
- **Body and satellite-system framing share one policy**, and focusing a planet's satellite
system is a separate, accessible action from inspecting its globe.
- **One animation-frame scheduler owns drawing.** It coalesces input, owns cancellation and
first-frame recovery, and no longer redraws an idle scene while the pointer hovers.
- **Automatic display resolution.** Auto starts at High and steps down under sustained frame
delay, with hysteresis, a cooldown and a growing wait after an upgrade the device cannot
hold. Slow frames in the first three seconds of drawing are treated as loading and cannot
lower resolution. A paused scene recovers from short drags separated by idle gaps. Low,
Balanced and High remain available as fixed choices.
- **Reference textures are verified before decode** (PNG and JPEG source grids), decoded
asynchronously and uploaded within fixed memory budgets.
- **Sky.** Stars, constellation lines and star hit targets fade together with daylight;
constellation figures use the engine's star reduction for the selected epoch; a failed
provider is not restarted implicitly by a redraw.
- **Future dates state their assumptions.** Beyond observed Earth-orientation data, nominal UTC
holds the last leap-second offset as a stated assumption and UT1 follows a modeled Delta T
with unknown uncertainty. The server refuses unsupported future dates before doing cache or
upstream work.
- **Touch targets** for planets, moons and small bodies have a 22 px minimum on touch input.
- **WASM build receipts.** A receipt naming Cargo's plain `release` profile is readable only
for the root manifest that predates the browser profile, and `write_receipt` refuses any
profile other than the one `build_wasm.py` requested.
- **The release manifest validator no longer passes a component release with missing parts.**
An artifact that carries the ephemeris component portal, or speaks an ephemeris contract
newer than v3, must include the WASM build receipt, the source manifest and the source
archive, and the archive must match the size and SHA-256 its source manifest publishes.
- **Retry recovers from a failed download.** "Retry this view" and "Retry catalogue downloads"
reload the page when the browser still holds an earlier failed download and the file is
reachable again. While it is not reachable, the page and its error stay as they were.

### Added

- **Independent accuracy evidence is published with the app.** The accuracy page and its JSON
registry record 160 comparisons of native geometric positions with retained JPL Horizons
DE441 vectors (16 epochs for each of ten target and origin pairs), including the failures:
141 pass the 10 arcsec budget and 19 fail, all at years 1, 5000, 7000 and 9999. All 60
samples from 1900 to 2100 pass. The records do not certify dates between the samples.
- **WASM source and binary receipts** bind both engine binaries to the exact workspace sources
that produced them, and the release builder refuses binaries without a matching receipt.
- **Corresponding source for the ephemeris component** (license texts, coefficient source
inventory and rebuild instructions) is distributed with the web app.

- **Moons cast their real shadows.** When a catalogued moon transits its planet's sunlit face,
the umbra/penumbra cross the disc — computed in the planet's body frame from PHYSICAL
planetocentric positions (not the inflated display offsets), in fractions of the equatorial
Expand Down Expand Up @@ -101,6 +182,12 @@ crate follows [SemVer](https://semver.org/).

### Fixed

- **Speed readouts** derive their unit conversion from the AU and Julian-year constants.
- **Solar differential rotation** is attributed to the original Doppler-feature fit; the
coefficients are unchanged.
- **Reference imagery in JPEG form loads again** after the verified loader initially accepted
PNG only.

- **Earth's Moon now discloses when the clock outruns it.** The 21 catalogued moons are hidden
with a notice past the Nyquist rate; Earth's Moon rides the ELP engine on a different path
and kept moving silently — at five simulated years per second a frame covers more than a
Expand Down
10 changes: 10 additions & 0 deletions apps/web/app.js
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { createViewEvidence } from "./js/viewEvidence.js";
import { workspace, renderWorkspace, openInspector, revealWorkspaceControl } from "./js/workspace.js";
import { explorer, initExplorer } from "./js/explorer.js";
import {createViewLoader} from './js/viewLoader.js';
import {createDocumentRecovery} from './js/catalogueLoader.js';
import {registerDestinationRenderer} from './js/viewRegistry.js';
import {initObservationMedia} from './js/observationMedia.js';
import {afterObservationPaint} from './js/offlineBoot.js';
Expand All @@ -22,12 +23,21 @@ export const offlineStartup=new Promise(resolve=>{markOfflineStartup=resolve;});
const loadedViews={research:null,sky:null,orrery:null};
const viewNames={research:'Solar research',sky:'My Sky',orrery:'Solar System'};
let activeView='observe',retryFocus=false;
// "Retry this view" re-imports first. If the browser still holds the earlier failure and
// the view's code is reachable again, the page reloads into the saved view. This module
// and the page that loads it share a directory, so the page's base resolves the same URLs.
const reloadWhenReachable=(...paths)=>createDocumentRecovery({urls:()=>paths.map(path=>new URL(path,document.baseURI).href),graphUrl:()=>new URL('./module-dependencies.v1.json',document.baseURI).href});
const viewCode=createViewLoader({
loaders:{
research:()=>import('./js/research.js'),
sky:async()=>{const [view,overview]=await Promise.all([import('./js/sky.js'),import('./js/destinationOverview.js')]);return {...view,overview};},
orrery:async()=>{const [view,overview]=await Promise.all([import('./js/orrery.js'),import('./js/destinationOverview.js')]);return {...view,overview};},
},
recoveries:{
research:reloadWhenReachable('./js/research.js'),
sky:reloadWhenReachable('./js/sky.js','./js/destinationOverview.js'),
orrery:reloadWhenReachable('./js/orrery.js','./js/destinationOverview.js'),
},
onState(state){
document.body.setAttribute('data-view-code',state.status);
document.body.setAttribute('data-view-code-name',state.name);
Expand Down
5 changes: 5 additions & 0 deletions apps/web/js/butterflyGeometry.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
// Backing-store coordinates shared by painting and pointer hit testing.
export function butterflyPlot(width,textScale){
const left=38*textScale,right=14*textScale;
return {left,width:width-left-right};
}
79 changes: 72 additions & 7 deletions apps/web/js/catalogueLoader.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,82 @@
// its physical fetch; cancellation and retry do not promise a new transfer.
export const CATALOGUE_DEADLINE_MS = 30000;

export function createCatalogueLoader({load,timeoutMs=CATALOGUE_DEADLINE_MS,
// A browser keeps a failed module fetch for the life of its document, so importing the
// same URL again fails without touching the network. The only way to fetch it again is a
// new document. When every listed module is reachable now, replace the document and
// report true. When one is not, report false and leave the page, and any offline state,
// exactly as it is: reloading an unreachable page would trade an error for a blank one.
export function createDocumentRecovery({urls,graphUrl=null,fetchModule=(url,init)=>fetch(url,init),reload=()=>location.reload()}) {
if(typeof urls!=='function'||typeof fetchModule!=='function'||typeof reload!=='function')throw new TypeError('Document recovery needs urls, fetchModule and reload functions');
return async({signal=undefined,isCurrent=()=>true}={})=>{
const current=()=>!signal?.aborted&&isCurrent();
if(!current())return false;
let targets=urls();
if(graphUrl){
const graphLocation=typeof graphUrl==='function'?graphUrl():graphUrl;
const response=await fetchModule(graphLocation,{cache:'no-store',signal});
if(!current()||!response?.ok)return false;
const graph=await response.json();
if(!current())return false;
if(graph?.schema_version!=='module-dependencies.v1'||!graph.modules||typeof graph.modules!=='object'
||Array.isArray(graph.modules)||Object.keys(graph.modules).length>4096)return false;
const root=new URL('./',graphLocation),queue=[...targets],seen=new Set();
const local=/^(?:js\/)?[A-Za-z0-9_.-]+\.js$/;
for(let i=0;i<queue.length;i++){
const url=new URL(queue[i],root);
if(url.origin!==root.origin||!url.pathname.startsWith(root.pathname)||url.search||url.hash)return false;
const name=url.pathname.slice(root.pathname.length);
if(!local.test(name)||!Object.hasOwn(graph.modules,name))return false;
if(seen.has(url.href))continue;
seen.add(url.href);
const dependencies=graph.modules[name];
if(!Array.isArray(dependencies)||dependencies.length>4096)return false;
for(const dependency of dependencies){
if(typeof dependency!=='string'||!local.test(dependency))return false;
const next=new URL(dependency,root).href;
if(!seen.has(next))queue.push(next);
}
if(queue.length>16384)return false;
}
targets=[...seen];
}
for(const url of targets){
const response=await fetchModule(url,{cache:'no-store',signal});
if(!current())return false;
if(!response||response.ok!==true){void response?.body?.cancel().catch(()=>{});return false;}
await response.arrayBuffer();
if(!current())return false;
}
if(!current())return false;
reload();return true;
};
}

export function createCatalogueLoader({load,recover=null,timeoutMs=CATALOGUE_DEADLINE_MS,
now=()=>performance.now(),setTimer=(callback,delay)=>setTimeout(callback,delay),clearTimer=timer=>clearTimeout(timer)}) {
if(typeof load!=='function')throw new TypeError('Catalogue load must be a function');
if(recover!==null&&typeof recover!=='function')throw new TypeError('Catalogue recovery must be a function');
if(!Number.isSafeInteger(timeoutMs)||timeoutMs<=0)throw new RangeError('Catalogue deadline must be a positive integer');
let status='idle',value=null,error=null,pending=null;
let status='idle',value=null,error=null,pending=null,loadRejected=false;
return Object.freeze({
get status(){return status;},get value(){return value;},get error(){return error;},
request(){
// recover:true marks an explicit retry by the person using the page. Only such a retry
// may replace the document, and only after the import has been rejected twice.
request({recover:explicitRetry=false}={}){
if(pending)return pending.promise;
if(status==='ready')return Promise.resolve(value);
const rejectedBefore=loadRejected;
const start=now();
if(!Number.isFinite(start))throw new TypeError('Catalogue clock must be finite');
let resolve,reject;
const promise=new Promise((yes,no)=>{resolve=yes;reject=no;});
const attempt={promise,resolve,reject,timer:null,deadline:start+timeoutMs};
const attempt={promise,resolve,reject,timer:null,deadline:start+timeoutMs,controller:new AbortController()};
pending=attempt;status='loading';error=null;
const timeout=()=>new Error('Catalogue request exceeded its deadline');
const finish=(ok,result)=>{
if(pending!==attempt)return;
if(now()>=attempt.deadline){ok=false;result=timeout();}
clearTimer(attempt.timer);pending=null;
clearTimer(attempt.timer);pending=null;attempt.controller.abort();
if(ok){value=result;status='ready';error=null;resolve(value);}
else {status='failed';error=result instanceof Error?result:new Error(String(result));reject(error);}
};
Expand All @@ -39,12 +94,22 @@ export function createCatalogueLoader({load,timeoutMs=CATALOGUE_DEADLINE_MS,
if(pending!==attempt)return;
if(now()>=attempt.deadline){finish(false,timeout());return;}
return load();
}).then(result=>finish(true,result),failure=>finish(false,failure));
}).then(result=>finish(true,result),async failure=>{
// Recorded even for a superseded attempt: the browser's failure outlives this request.
loadRejected=true;
if(explicitRetry&&recover&&rejectedBefore&&pending===attempt){
let reloading=false;
try{reloading=await recover({signal:attempt.controller.signal,isCurrent:()=>pending===attempt&&now()<attempt.deadline})===true;}catch(_){ /* the import failure below is the report */ }
// The document is being replaced. The deadline still bounds this attempt.
if(reloading)return;
}
finish(false,failure);
});
return promise;
},
cancel(){
if(!pending)return;
const attempt=pending;pending=null;clearTimer(attempt.timer);
const attempt=pending;pending=null;clearTimer(attempt.timer);attempt.controller.abort();
status='idle';error=null;
const failure=new Error('Catalogue request cancelled');failure.name='AbortError';attempt.reject(failure);
},
Expand Down
19 changes: 11 additions & 8 deletions apps/web/js/orrery.js
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ import { buildEarthMapSliced, buildFeatureMap } from "./surfacemap.js";
import { resolveDisplayRadii, moonGuideVisible } from "./displayGeometry.js";
import { textureEligible, missingDetailColor } from "./visualAssets.js";
import { catalogueDemand } from "./catalogueDemand.js";
import { createCatalogueLoader } from "./catalogueLoader.js";
import { createCatalogueLoader, createDocumentRecovery } from "./catalogueLoader.js";
import { moonOffsetAU, moonOrbitPath, systemScale, satelliteSystemExtent, withinMoonValidity, aliasedByClock, synchronousMoonRotation } from "./moonorbits.js";
import { MAX_MOON_SHADOWS, moonShadowsOnPlanet, packMoonShadows, sunlightOnMoon } from "./moonshadows.js";
import * as moonCatalogue from "./moons.js";
Expand Down Expand Up @@ -282,12 +282,15 @@ let starCataloguePromise = null;
const catalogueRetryOwners=new Set();
let catalogueRetryGeneration=0,catalogueRecoveryNotice=false;
let catalogueFocusIntent=null;
const moonLoader=createCatalogueLoader({load:async()=>{
// "Retry catalogue downloads" re-imports first. If the browser still holds the earlier
// failure and the catalogue is reachable again, the page reloads into Solar System.
const reloadWhenReachable=path=>createDocumentRecovery({urls:()=>[new URL(path,import.meta.url).href],graphUrl:()=>new URL("../module-dependencies.v1.json",import.meta.url).href});
const moonLoader=createCatalogueLoader({recover:reloadWhenReachable("./moonelements.js"),load:async()=>{
const module=await import("./moonelements.js");
if(!moonSet.MOONS.every(m=>Array.isArray(module.MOON_ELEMENTS?.[m.n]?.el)&&module.MOON_ELEMENTS[m.n].el.length>0))throw new Error('Moon orbital catalogue is incomplete');
return module;
}});
const starLoader=createCatalogueLoader({load:async()=>{
const starLoader=createCatalogueLoader({recover:reloadWhenReachable("./starcatalog.js"),load:async()=>{
const module=await import("./starcatalog.js");
if(!Array.isArray(module.NAMED_STARS)||!module.NAMED_STARS.length||!Number.isSafeInteger(module.STAR_COUNT)||module.STAR_COUNT<=0
||!Number.isSafeInteger(module.STAR_STRIDE)||module.STAR_STRIDE<3||module.STARS_PACKED?.length!==module.STAR_COUNT*module.STAR_STRIDE)throw new Error('Named-star catalogue is incomplete');
Expand Down Expand Up @@ -344,7 +347,7 @@ function retryCatalogues(){
const generation=catalogueRetryGeneration,button=document.getElementById('orreryCatalogueRetry');
catalogueFocusIntent=button&&document.activeElement===button?{generation}:null;
for(const load of jobs){
const pending=load();catalogueRetryOwners.add(pending);
const pending=load(true);catalogueRetryOwners.add(pending);
void pending.finally(()=>{
if(generation!==catalogueRetryGeneration||!state.active)return;
catalogueRetryOwners.delete(pending);updateCatalogueStatus();
Expand Down Expand Up @@ -1036,12 +1039,12 @@ async function buildGeneratedMaps() {
* the knots are deferred, and they are ~99% of the bytes, so the first-paint cost of widening the
* validated window is a few KB rather than a megabyte.
*/
function loadMoonCatalogue() {
function loadMoonCatalogue(explicitRetry=false) {
if(moonElementsReady)return Promise.resolve(moonSet);
if (moonElementsPromise) return moonElementsPromise;
// Retry retains the immutable release URL. The loader bounds logical ownership;
// the browser may share an existing physical import with a later attempt.
const request=moonLoader.request();
const request=moonLoader.request({recover:explicitRetry});
const pending = request
.then((mod) => {
if(moonElementsPromise!==pending)return moonSet;
Expand All @@ -1060,10 +1063,10 @@ function loadMoonCatalogue() {
return moonElementsPromise;
}

function loadStarCatalogue(){
function loadStarCatalogue(explicitRetry=false){
if(starCat)return Promise.resolve(starCat);
if(starCataloguePromise)return starCataloguePromise;
const request=starLoader.request();
const request=starLoader.request({recover:explicitRetry});
const pending=request.then(catalogue=>{
if(starCataloguePromise!==pending)return null;
starCat=catalogue;updateOrreryPositions();
Expand Down
Loading
Loading