Solar Wanderer: a 1:1 browser solar system built on NASA JPL ephemerides

What Solar Wanderer actually renders, and for whom

The README frames the project as a 1:1 real-time solar system explorer that runs entirely in a browser. Scale is stated as true 1:1 km across a range from 0.5 m to 100,000 AU, which covers a walk on a planetary surface at one end and the Oort Cloud at the other. Position data comes from NASA JPL ephemerides, so the README's claim is that "the planets are where they are right now" rather than at a fixed epoch.

The intended audience is visible in the repository structure. There is a README-zh.md alongside the English README, a docs/ tree with screenshots, and a ROADMAP.md that lists teacher, classroom and museum toolkits as a goal. The project's own framing is educational: the README describes a child standing on the Moon and seeing Earth as a small blue marble, and a teacher taking a class to Mars in five minutes.

That framing matters for judging it. This is not an observatory-grade ephemeris library. It is a viewing tool whose accuracy claims are bounded and published in a table, with planets listed between 0.0007° and 0.074° against JPL Horizons and 21 moons fitted from state vectors. The README also notes 28 real TNOs and 4 comets, plus the positions of Voyager 1 and 2 past the heliopause.

Floating origin, logarithmic depth and a pure-function ephemeris layer

The interesting engineering problem here is numeric. A single scene spanning 0.5 m to 100,000 AU cannot use ordinary 32-bit float positions without visible jitter, because precision runs out long before the far plane. The README and package metadata name the two techniques used: a floating-origin renderer, which keeps the camera near the coordinate origin and shifts the world instead, and a logarithmic depth buffer, which spreads depth precision across a huge dynamic range.

The tech stack is listed as Three.js 0.165, Vite 5, native ESM and WebGL2, with three as the only runtime dependency in package.json. Everything else in that file is a devDependency (vite, puppeteer, puppeteer-core). The README also mentions GPU auto-tiering for mobile and low-end devices, which is consistent with the v2.0.0 release note titled "Full Mobile Support" and the claim that desktop and mobile share the same physics and scale.

The ephemeris layer is described as a set of pure functions that can be tested under Node without a browser. That design choice is what makes the repository's test story work: the orbital math is separable from the rendering, so precision can be checked in a headless process. The tools/ directory holds the data pipeline scripts, including fit-moons.mjs, fit-tnos.mjs, fetch-small-bodies.mjs, fetch-vsop87.mjs and fetch-dem.mjs, which suggests the shipped data is generated ahead of time rather than fetched at runtime. The README's "zero backend" claim depends on that.

Installing Solar Wanderer and taking a first look

There is a hosted instance at sw.icodestar.net, and the README is explicit that it needs no install and no account. For local work, the quick start section gives the clone, install and dev commands. The dev server prints a local URL on port 5173.

git clone https://github.com/hyqzz/Solar-Wanderer.git
cd Solar-Wanderer
npm install
npm run dev      # → http://localhost:5173

Two further scripts are worth running before you trust anything. The README describes npm test as 33 precision tests that need no network, and npm run verify as a live cross-check against NASA JPL Horizons that does need internet access. Running the offline suite first tells you whether the ephemeris layer works on your machine before any network variable enters the picture.

npm test         # 33 precision tests (no network needed)
npm run verify   # live cross-check against NASA JPL Horizons (needs internet)

For a first real use, the README suggests three sequences rather than a tour. Open the directory, select the Moon, pinch in until you land, then look up at Earth. Pull back from Earth until the planets become dots and continue until the Oort Cloud appears. Double-click Saturn and zoom until the Cassini Division resolves. Those three exercises test the near field, the far field and the ring detail respectively, which is a reasonable way to find out whether the renderer holds up on your hardware. If you want to rebuild the bundled data, the package scripts include npm run fetch-textures, npm run fit-moons and npm run make-previews, but the README does not document what each one downloads or how long it takes.

Where Solar Wanderer is the wrong tool

The accuracy table has an upper bound, and that bound is the honest limit of the project. Planets are stated at 0.0007° to 0.074° against JPL Horizons. That is fine for a visualisation and inadequate for occultation timing, astrometry or anything that needs arcsecond agreement. The README does not publish a validity window for the ephemeris, and the roadmap lists VSOP87 plus ELP2000 as a wanted contribution for ±3000 year validity, which implies the current implementation does not cover that span. If your work needs positions far outside the present era, this is not the library to reach for.

Several features the README lists as goals are not in the current release: real DEM terrain from LOLA, MOLA or SRTM, eclipse shadow volumes, dynamic weather, 16K to 32K textures, WebXR, and spacecraft models. Those appear under "The Road Ahead" and in the most-wanted contributions table, not as shipped capabilities. Anyone reading the roadmap as a feature list will be disappointed.

The README also does not document rollback, version pinning or a migration path between releases, and there is no changelog file at the top level. The release history shows three releases within a week in June 2026 (v2.0.0 on 2026-06-14, v2.1.0 on 2026-06-19, v2.2.0 on 2026-06-21), with the last push to the repository on 2026-08-23. The README does not state a support policy for older versions, so pinning to a tag is a decision you make on your own.

How it compares with running an ephemeris library yourself

The obvious alternative is to build the same view on top of a dedicated ephemeris package such as astronomy-engine or a JPL SPICE binding, and render it with Three.js. The difference is where the work sits. Those libraries give you positions and leave the entire rendering problem to you: the floating-origin camera, the depth buffer configuration, the scale transitions from orbit to surface, the mobile touch controls and the GPU tiering are all yours to write. Solar Wanderer ships those as part of the same MIT-licensed codebase, which is the actual trade being offered.

In the other direction, a planetarium application such as Stellarium gives you a mature, observation-oriented sky view with a long history and a much larger feature surface. The approach differs: Stellarium is built around looking outward from a point on Earth at the celestial sphere, while Solar Wanderer is built around moving between bodies at true distance. If your question is "what is in the sky tonight from this location", the planetarium model answers it directly and Solar Wanderer does not. If your question is "how far apart are these things and what does the scale feel like", the reverse holds.

The comparison that matters most is with doing nothing. Solar Wanderer's pitch is roughly 200 kB gzipped, no backend and no account, which means a teacher can open a URL rather than provision a server. That constraint is the project's real design centre, and it explains most of the other choices.

Licence, maintenance and the cost of upgrading

The repository is MIT licensed, with a LICENSE file at the top level and a matching license field in package.json. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but this is not legal advice; read the LICENSE file and the licences of the underlying data sources yourself. The README states that all data comes from public NASA and IAU sources, and it does not enumerate the terms attached to each of those sources, so a redistribution that bundles the generated ephemeris data needs its own check.

Maintenance signals are mixed and worth reading carefully. The repository is not archived, and the last push was on 2026-08-23. The release cadence in June 2026 was fast, with three versions in eight days, but the README does not describe a deprecation or support policy, and there is no CHANGELOG at the top level. Upgrade cost therefore depends on whether you track the main branch or pin a tag. The only runtime dependency is three at ^0.165.0, so a caret range means a minor Three.js bump can arrive without a Solar Wanderer release; the floating-origin code and the logarithmic depth buffer are exactly the kind of rendering code that tends to notice renderer changes, and the README does not say which Three.js versions have been validated.

The repository also carries AGENTS.md and CLAUDE.md at the top level, plus .audit-reports/ and .github/. Those indicate an automated or agent-assisted workflow around the codebase. That is not a quality claim in either direction, but it does mean the commit history may not read like a conventional human-maintained project.

Editorial conclusion

Adopt Solar Wanderer if you need a zero-install, MIT-licensed solar system view for a classroom screen, a museum kiosk or a personal project, and you are willing to run the repository's own verification scripts before trusting the numbers. Skip it if you need long-baseline ephemeris validity, real terrain, or VR, none of which the current release provides. First, clone the repository, run npm test offline, then run npm run verify with internet access and compare the reported angular errors against the 0.0007° to 0.074° range the README states for planets.

Frequently asked questions

Official sources

1. hyqzz/Solar-Wanderer on GitHub
2. License: MIT
3. Project website
4. README
5. Releases