# Fractal

![Fractal icon](pwa-192x192.png)

**Follow a spiral. Discover an island. Let the colours drift.**

Turn your screen into a window onto the Mandelbrot set. Explore with a tap, visit eighteen hand-picked destinations, or settle back and watch a slow tour unfold. Use the display on its own, or invite phones to steer the same view together.

![Spiral whirlpool in the Classic blue-and-gold palette](guide-spirals.jpg)

*Spiral whirlpool: one of eighteen places to begin your next exploration.*

## Your first journey

1. Open [Fractal](/fractal/) on your display, or launch it from **Visuals** in the RCWeb app menu.
2. Click or tap an interesting edge to zoom towards it. Each touch moves twice as close by default.
3. To use your phone, scan the display's QR code. Phones already in the room follow automatically when you launch Fractal from the app menu.

Explore solo, pass control between friends, or use several phones in the same room. Everyone sees the same view; the display takes one zoom at a time. No scores, rounds or time limit: choose whatever catches your eye.

![The whole Mandelbrot set with the display's three exploration controls](guide-overview.jpg)

*Start with the whole set, then follow its bright coastline into finer detail.*

## A few controls, a lot to explore

The display keeps its controls in the top-left corner:

- **Magnifying glass with minus:** zoom out along your recent route. It stays visible but dims at the widest view.
- **Circular arrow:** reset to the whole set, including during a zoom. It dims when you are already reset.
- **Play / Stop:** begin the demo immediately, or stop the current demo or destination journey after its current zoom step.

The corner-frame icon at the top right opens fullscreen. The small number at the bottom shows your magnification. During a journey, the location name appears in the bottom-left corner; it is a label, not a button.

Your phone mirrors the picture. Tap its preview to choose the next point, use **Zoom out** or **Reset view**, and return through **Back to apps** when you want to choose something else. Returning to the app menu leaves the display running.

![Phone controller with a matching fractal preview and destination cards](guide-phone.jpg)

*Your phone becomes a touch remote for the shared screen.*

## Skip straight to somewhere extraordinary

Open **Explore a destination** on your phone and pick a thumbnail. Fractal travels there smoothly, zooming out first when the new destination is elsewhere in the set.

Try **Spiral whirlpool** for tightly wound curves, **Snowflake** for delicate branching, **Square pattern** for surprising geometry, or **Carousel** for a much deeper journey. The collection also includes Twin spirals, Lacework spiral, Spiral-pair minibrot, Seahorse Valley and Elephant Valley.

![The phone's destination gallery, with previews and arrival magnifications](guide-gallery.jpg)

*Eighteen destinations, each with a preview and a magnification to show how far you will travel. Scroll the gallery to see them all.*

Thumbnails use the Classic palette. Your selected colours and the display's shape apply to the actual journey, so the same destination can feel very different on your next visit.

![Snowflake destination with fine branching patterns in the Ocean palette](guide-snowflake.jpg)

*Snowflake in Ocean: teal and ice colours trace its delicate branches.*

![Twin spirals destination in the Rainbow palette](guide-twin-spirals.jpg)

*Twin spirals in Rainbow: follow the coloured bands around the paired curves.*

![Seahorse island surrounded by fine filaments in Monochrome](guide-island.jpg)

*Seahorse island in Monochrome: a miniature Mandelbrot set among silver-and-ink filaments.*

## Let the demo take the lead

Press **Play** on the display for an immediate tour. Each destination rests on screen for five seconds, then the view pulls back and heads somewhere new. Play works even when automatic demo is switched off.

By default, a demo also starts after one minute without input. In **Colour & options**, change **Demo delay** to 30 seconds, 1, 2, 5 or 10 minutes, or turn automatic starts off. Stop with the dedicated square icon, or take control through the display or phone. **Reset view** returns to the whole set immediately. Stopping a tour keeps your chosen idle delay.

## Make it yours

Open **Colour & options** on your phone to change the character of the image:

- **Six palettes:** Classic blue and gold, Ocean teal and ice, Fire amber and crimson, Aurora violet and mint, Rainbow, or Monochrome.
- **Living colour:** palette animation is off by default. Enable it to slowly cycle the colours; adjust colour offset, spacing or reversal for a different finish.
- **3D relief shading:** add highlights and shadows that give the patterns a carved, textured appearance.
- **Your pace:** choose 1.5×, 2× or 4× per touch, and separate zoom-in and zoom-out times from 0.7 to 8 seconds. Defaults are 3 seconds in and 1 second out.
- **Your display:** choose Automatic, Standard or High detail, and hide the QR invitation after everyone has joined if you prefer.

![Expanded phone options showing palette, colour, relief, detail, zoom speed and demo settings](guide-options.jpg)

*The phone's Colour & options panel brings the display settings together.*

![Shepherd crook spiral with Fire colours and relief shading](guide-relief.jpg)

*Shepherd crook spiral in Fire, with relief shading bringing out ridges and folds.*

Preferences are saved in the display browser and shared with the phones. **Reset view** keeps them. Reopening the display begins a fresh exploration with your saved look; it does not resume the previous zoom or demo.

## Keep Fractal on your home screen

Use your browser's **Install app** or **Add to Home Screen** command while viewing [Fractal](/fractal/). The installed viewer opens in its own app window and remembers the room used at installation. You can explore directly there or connect a phone as usual.

Fractal works in landscape and portrait. Installation needs a supported browser and an HTTPS address; localhost also works for local development. It remains an online RCWeb app: the server must be reachable to open it and keep devices connected.

![Portrait Fractal display exploring Square pattern in Aurora colours](guide-portrait.jpg)

*Square pattern in Aurora, framed for a portrait screen.*

## Behind the picture

Fractal is an HTML, CSS and vanilla JavaScript RCWeb app. The following details explain how the shared view and rendering work.

### A shared view

One elected display owns the view, zoom history, options and tour. Phones send commands over RCWeb's WebSocket connection; the display distributes updates to controllers and other displays. Additional displays keep the host's aspect ratio, with letterboxing where necessary. Reconnecting phones recover the current session while a display remains open. Reloading the only display starts a new view.

Settings live in the display browser's local storage. The room-aware web manifest uses a stable app identity and a start URL containing the installation room. It reuses the supplied regular, maskable and Apple touch icons. No service worker or offline room cache is installed; app files and room setup are loaded from the server. See [MDN's installation guide](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable) for browser requirements.

### Smooth travel and colour

Destination routes use steps of at most 2×, distributed along one ease-in/ease-out curve for the whole journey. Individual tap zooms ease separately. The current image stays visible while the next image is calculated; new detail blends in over 180 milliseconds without cutting the movement short. Progress slows if rendering needs more time. Zooming out prepares the wider image first to avoid empty edges.

The last ten zoom steps can be retraced. Cached images are reused when their view, colour settings, detail and dimensions still match. Beyond that history, zoom-out widens the current centre.

Palette animation completes a colour cycle every 20 seconds without recalculating the fractal each frame. Displays and phones share its timing, and the dark interior remains fixed. Relief shading uses escape-time values as a height map, with light from the upper left. It is off by default and adds CPU work when generating an image, while colour cycling reuses the result.

### Rendering and older devices

WebGL accelerates drawing when available. Both the display and phone preview verify actual WebGL pixels at startup, including palette cycling. Failed test draws, shader failures, texture errors and drawing errors automatically switch to Canvas without changing the URL. WebGL context loss also falls back to Canvas. Browsers without an animation-frame API use a timer.

During movement, up to four CPU workers generate pixel strips for a display; phone previews use up to two. The worker pool leaves one reported CPU core available and uses one worker on lean TV devices, for coarse images, or when core information is unavailable. Failed workers, or workers that do not respond within 30 seconds, fall back to one worker, then to small Canvas batches on the main thread.

The display and controller connect to RCWeb before starting graphics. If scripts or Canvas rendering cannot run, a persistent error shows the reason and connection status while remote app switching remains available. This requires working JavaScript, WebSocket support and a network connection; page code cannot recover a frozen or crashed browser process.

Deep zooms use JavaScript double precision. A numerical limit prevents zooming beyond meaningful precision; very fine boundaries can still vary with the iteration budget. Automatic detail targets roughly 1080p, Standard roughly 720p, and High up to 4K, subject to device limits. Higher detail and relief shading can take longer on older hardware. The phone calculates the same region at its own resolution, so small pixel differences are normal.

The bottom status indicator reports GPU, CPU workers, the CPU main-thread fallback, or a cached image. Worker counts are browser threads, not measured physical-core use. A ready image can still be moving or cycling through colours.

### Diagnostics and sources

Use `?r=test-0001&canvas=1` to force Canvas, add `&worker=0` to test without workers, or use `&lean=1` for the lean display path. Regenerate destination thumbnails with `node src/main/apps/app/fractal/make-previews.cjs`; capture the guide's live screenshots with `node src/main/apps/app/fractal/make-screenshots.cjs` while RCWeb is running locally.

Published centres come from Robert P. Munafo's Mu-Ency ([Seahorse Valley](https://mrob.com/pub/muency/seahorsevalley.html), [Elephant Valley](https://mrob.com/pub/muency/elephantvalley.html)), [Exploring the Mandelbrot Set](https://mandelbrot.dev/) and the [Mandelbrot Gallery](https://mandelbrot.neocities.org/gallery). Framing and descriptive labels are adapted for this app. Relief shading follows the approach described in [Hill-Shading the Mandelbrot Set](https://eamonn.org/mandelbrot-3).