# Fractal Explorer

A fast, interactive deep-zoom fractal explorer — Mandelbrot and Julia sets —
built with **Rust + wgpu + egui + WGSL**. It zooms far past the ~10¹³× limit of
plain `f64` using **perturbation theory**: one high-precision reference orbit is
computed on the CPU (arbitrary precision via `dashu-float`), and every pixel is
rendered on the GPU as a cheap `f32` delta from it, with **rebasing** to avoid
glitches. Runs natively (Vulkan/Metal/DX12) and in the browser (WebGPU).

The `f32` GPU tier reaches roughly **10³⁰× magnification** with sharp detail.

## Features

- Mandelbrot and Julia sets (with Julia-constant editor + presets)
- Smooth continuous coloring, `sqrt`-compressed to stay clean at deep zoom
- Several palettes
- Drag to pan, scroll to zoom toward the cursor
- Arbitrary-precision center; per-view reference orbit computed on a background
  thread (native) so the UI stays responsive
- Reference reuse: small pans/zooms reuse the current reference (no recompute)
- PNG export at up to 4× the on-screen resolution
- Shareable/bookmarkable deep-zoom links (`#…` URL fragment, full precision)

## Build & run — native

```sh
cargo run --release
```

## Build & run — web (WebGPU)

Requires the `wasm32-unknown-unknown` target and `wasm-bindgen-cli` (matching the
`wasm-bindgen` crate version, currently 0.2.x):

```sh
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.128   # once

./build-web.sh                       # outputs ./dist (index.html, .js, .wasm)
python3 -m http.server -d dist 8080  # serve over http
```

Then open <http://localhost:8080> in a **WebGPU-capable browser** (recent
Chrome/Edge, Firefox, or Safari 26+). WebGPU needs a secure context; `localhost`
qualifies. Deploy by serving the `dist/` directory as static files.

> Note: `trunk` also works in principle, but on some systems its `libdeflate-sys`
> C dependency fails to compile; `build-web.sh` uses `wasm-bindgen-cli` directly
> to avoid that.

## Controls

- **Drag** — pan
- **Scroll** — zoom toward the cursor
- **iterations** — raise this as you zoom deeper (deep boundary pixels need many
  more iterations; too few shows solid black)
- **Copy link** — copies a URL that restores the exact view
- **Export PNG** — saves `fractal-<timestamp>.png` (native, in the working dir)
  or downloads it (web)

## How it works

- `src/view.rs` — view state. Center is arbitrary precision (`FBig`); the pixel
  scale stays `f64` (even at 10³⁰× it is ~10⁻³³, within `f64` range).
- `src/fractal/reference.rs` — high-precision reference orbit `Z_{n+1}=Z_n²+C`.
- `src/shaders/mandelbrot.wgsl` — per-pixel perturbation `e_{n+1}=2·Z_n·e_n+e_n²+δc`
  with Zhuoran rebasing (`e ← z − Z₀` when the true value drops below the delta),
  a `dc_offset` so a reused/slightly-stale reference still maps correctly, and
  smooth coloring.
- `src/fractal/renderer.rs` — wgpu pipeline, storage buffer for the orbit, egui
  paint callback, and offscreen render-to-PNG.
- `src/worker.rs` — native background thread for the reference orbit (coalesces
  bursts of requests). The web build computes it inline.
- `src/fractal/share.rs` — URL-fragment encode/decode.

### Limits & possible extensions

The `f32` tier degrades past ~10³⁰×. Natural next steps (scaffolding is in
place): an emulated **double-float** GPU tier (~10⁶⁰×), **floatexp** rescaling
and **BLA** iteration-skipping for near-unlimited depth, and moving the web
reference computation to a Web Worker.

## Tests

```sh
cargo test
```

Covers the reference orbit (vs. a naive `f64` iteration, Mandelbrot and Julia)
and share-link round-tripping.

## Debug/testing env vars (native)

- `MANDEL_VIEW="re,im,half_height[,iterations]"` — start at a specific view
- `MANDEL_JULIA="cre,cim"` — start in Julia mode with constant `c`
- `MANDEL_SHARE="<fragment>"` — restore a share fragment
- `MANDEL_EXPORT=1` (+ optional `MANDEL_EXPORT_PATH=out.png`) — export on the
  first frame, for scripted captures