Instant-Astronomer

June 1, 2026 · View on GitHub

Instant-Astronomer — play in your browser

Support the Project

Buy Me A Coffee

Instant-Astronomer is open-source and free to use, maintained in spare time as a labor of love. Friends James Smith and Dan Ruskin help out from time to time too.

If you find it useful, here are a few ways to help keep development going:

  • Donations: Buy Me a Coffee — every coffee helps.
  • Star the repo: Costs nothing and helps others find the project.
  • Report issues: Open an issue for bugs or feature ideas.
  • Contribute: PRs welcome — open an issue first to discuss larger changes.

▶︎ Open it in your browser

Point your phone at the sky and see what you're looking at. A lightweight, serverless, client-side Rust application that renders an interactive overlay of stars, planets, the Sun, the Moon, and constellations — driven by the user's location, the current time, and (on mobile) the device's compass + IMU.

The reason this exists: it's sunset, you're staring at two bright "stars" above the horizon, and you want to know that you're looking at Venus and Jupiter. Open the app, point your phone, you have your answer.

Built with agg-gui for every pixel on screen — no separate WebGL / wgpu 3-D pipeline. Runs natively (winit + wgpu present surface) and in the browser (WebAssembly + WebGL2 present surface) from the same workspace.

Part of the rust-apps suite.

Quick start

# Native (hot-reload via cargo-watch)
cargo install cargo-watch        # one-time
cargo dev                        # builds + runs the native shell on save

# Or a single run
cargo run -p instant-astronomer-native

# WebAssembly
wasm-pack build instant-astronomer-wasm --target web --out-dir ../demo/public/pkg --no-typescript

Testing on a phone (LAN, with sensors)

The web build uses navigator.geolocation and DeviceOrientation, both of which require a secure context (HTTPS) on a real device. The Vite dev server is configured to bind to all interfaces and serve a self-signed cert (demo/vite.config.ts), so a phone on the same Wi-Fi can reach it and the sensors work.

Prerequisites (one-time): a JS runtime — Bun is what the repo's lockfile + CI use — plus cargo install cargo-watch.

cd demo
bun install                 # one-time

# Terminal 1 — rebuild the wasm pkg on every Rust edit
bun run wasm:watch          # cargo-watch -> wasm-pack into demo/public/pkg

# Terminal 2 — HTTPS dev server bound to the LAN
bun run dev                 # prints a https://<your-lan-ip>:5173/ Network URL

On the phone, open the printed Network URL (e.g. https://192.168.x.x:5173/) and accept the self-signed-cert warning once. After a Rust change, wasm:watch rebuilds the pkg — just reload the page on the phone. bun run wasm does a single (non-watching) build.

Sending a phone screenshot back to the dev machine

When the dev server is running it also serves a small screenshot relay at /__shot (dev only — it's stripped from production builds). To capture what the phone is actually rendering:

  1. Take a normal OS screenshot on the phone.
  2. Open https://<your-lan-ip>:5173/__shot in the phone browser.
  3. Pick the screenshot and tap Upload.

The image is saved on the dev machine under demo/shots/ (gitignored), where you — or a coding agent pair-debugging the mobile layout — can open it directly. Implemented in demo/vite-plugins/phone-shots.ts.

Workspace layout

instant-astronomer-core/    # astronomy math, city DB, sky + horizon widgets (wasm32-clean)
instant-astronomer-native/  # winit + wgpu present + native geolocation hook
instant-astronomer-wasm/    # cdylib wasm-bindgen shell + navigator.geolocation + deviceorientation

instant-astronomer-core is wasm32-clean: no tokio, no winit, no direct wgpu. Platform shells inject capabilities via the AstronomerPlatform trait.

Architecture invariants

  • All UI through agg-gui. Every visible pixel goes through agg-gui's DrawCtx. No HTML/CSS controls in the WASM shell beyond the bootstrap canvas; no separate wgpu 3D pipeline in core. Sky-sphere stars, planets, constellation lines, and the horizon HUD are 2-D primitives painted at positions computed by the projection pipeline in Rust.
  • Single application, two host adapters. instant-astronomer-core exposes build_astronomer_app and the runtime state cells (lat / lng / yaw / pitch / roll / timestamp). Native and WASM shells just create a window/canvas, forward events, and pump the projection clock.
  • agg-gui is a path dep — improve it as you go. The workspace Cargo.toml redirects agg-gui = "0.2" to ../agg-gui/agg-gui via [patch.crates-io]. CI clones larsbrubaker/agg-gui as a sibling so the patch resolves there too. When the app needs a primitive that doesn't exist, add it to agg-gui first.
  • File-size guardrail. instant-astronomer-core/tests/file_line_count.rs enforces 800 lines per file across first-party source. Split when it trips — don't strip comments.

See CLAUDE.md for the full agent guide.

Implementation roadmap

See implementation.md for the original design spec — the three-phase delivery plan, the Yale Bright Star Catalog / Keplerian / Meeus pipelines, and the SQLite-backed city search the asset payload is moving toward.

Prior art and inspiration

  • Sky Map (stardroid) by the Sky Map team — the mature, Google-incubated Android star-map app that set the bar for "point your phone at the sky" interaction.

License

MIT — see LICENSE.