Backdrops: living backgrounds for OxygenHub

Status: the engine and the dashboard's Your sky are built (oxygenhub#157, 2026-10-13); the other scenes are proposed (oxygenhub#156).

1. What a backdrop is

A backdrop is a quiet, moving picture behind a page's content: a field of small marks that drift slowly and respond a little to the cursor. It gives the hub a sense of motion and depth without asking for attention.

Three rules shape everything else:

1. True, not invented. The footer says "nothing here is inferred: what a page says, the object store says". A backdrop keeps that promise. Every mark stands for something real the viewer may see: one of their repositories, a change, a push, a runner. Nothing is made-up decoration that only looks like data, such as fake chunks or fake peers.
2. Behind, never in the way. Content is opaque cards on top. A backdrop shows only in the margins and the gaps between cards. It never takes a click, never moves the layout, and is never needed to read or use the page.
3. Cheap and polite. It costs well under a millisecond a frame. It stops when the tab is hidden, and it is still for people who ask for reduced motion. Anyone can turn it off.

2. Which pages

Never: code, file, blame, diff, conflict and proposal pages, the editor, issues and proposals while being written, settings and admin tables. Those pages are for reading closely, and motion behind them costs attention. Repository overviews have none for the same reason; their README is the picture.

Each scene is its own issue, done one at a time, the dashboard first.

3. Colours

A backdrop takes its colours from the page's own tokens, so it is right in both looks (GitHub, the default, and classic) and in both themes (light, the default, and dark), and it follows a theme switch at once. Three new tokens join each look's light and dark sets:

Two more colour rules:

• The brand gradient (#00F0FF → #0072FF) is kept for moments: a new push arriving, the mark scene. A whole field in it would shout.
• Status colours are used only where the data has a status: the Diffusion pill's green, amber and red, and a run's outcome. They never appear as decoration.

In light mode a backdrop must be barely there: if you notice it before the content, it is too strong. The contrast test (tests/contrast.rs) gains a check that --bd-mark stays under 1.3:1 against --bg.

4. Motion and the cursor

• Drift. Marks move slowly, at most 12 px a second, along gentle streams around their cluster. Two streams can cross: their marks pass each other without touching, and the change in order means nothing. That is how Oxygen's changes behave, which is where this comes from.
• The cursor lights, it does not pull. Marks within about 140 px of the cursor light up in --bd-lit, ramping in over 150 ms and fading out over 600 ms. Nothing is attracted or pushed, so the cursor never rearranges the picture.
• Lines mean something. Among the lit marks, a faint line joins two marks only when they belong together in the data: events of the same repository that happened one after another and sit within 70 px of each other, so a busy repository reads as a constellation, not a scribble. Lines fade as the cursor moves on or rests for 2 s.
• Labels, sparingly. When the cursor rests near a cluster, its name fades in just above the cluster's outer ring in --mute, small. This is the only text a backdrop draws, and it is never a link; the dashboard's own list is the link.
• Parallax. Three depth layers shift by at most 6 px, 3 px and 1 px against the cursor's offset from the page's centre. That gives a little depth with no feeling of motion sickness.
• Arrivals. When the page learns of new activity, its mark appears with one soft ring in the brand gradient that widens and fades over 1.2 s. This is the one moment a backdrop may draw the eye, and only briefly.

5. The dashboard: Your sky

Data. The dashboard handler already loads your repositories and the activity feed from the database. The backdrop needs a little more of the same:

• the repositories in Your repositories, by name;
• up to 1,500 events from the last 30 days across them (pushes, proposal and issue events, releases, Flow runs), each with its repository, kind and time, and for a push the number of changes it brought. A push draws one dot for each change, up to 40, and the sky draws up to 3,000 marks.

The handler embeds these as JSON in the page (<script type="application/json" id="backdrop">), so the backdrop costs no second request and never reads a repository's store. That matters: some stores are slow, such as GCS-backed ones. Private repositories appear only for viewers who may see them, exactly as the list beside them does.

Layout.

• Each repository is a cluster, placed by its name's BLAKE3 on a golden angle spiral, so your sky looks the same on every visit and on every device.
• The most active repositories sit in the front layer and the quiet ones further back.
• A cluster's events are its marks: today's are brightest and a month old are faint.
• Kinds differ by shape, not colour: a change pushed is a dot, a proposal event a small diamond, an issue event a ring, a release a four-point star, a Flow run a small square, and the repository itself a thin ring at the cluster's core.
• A busy repository gets more orbit lanes (6 to 14), so its marks spread out instead of piling up.

Live. When the page learns of new activity (it already polls for the notification count), the event joins its cluster with an arrival ring (§4). Nothing reloads.

6. Engine

The engine is Rust compiled to WebAssembly (Andy's choice, 2026-10-13): crates/backdrop, a workspace of its own outside the hub's. sky.rs is the scene with no browser in it, tested natively; gl.rs draws it; lib.rs is the browser glue. make backdrop builds it for wasm32-unknown-unknown and runs wasm-bindgen --target web into assets/backdrop/ (about 186 KB of wasm, 60 KB gzipped, and the glue), which is committed and embedded in the hub, as make ts commits the API types, so neither the hub build nor its offline CI needs the wasm toolchain. make backdrop-check runs its fmt, clippy (wasm32) and tests.

• Drawing. WebGL2 with instanced quads for marks (one draw for all, each shape a signed distance in the fragment shader) and one line buffer for links. Without WebGL2 there is no backdrop, and nothing breaks.
• The canvas. One fixed full-viewport <canvas aria-hidden="true"> behind main, with pointer-events: none. Its device pixel ratio is capped at 1.5.
• Frame rate. It runs at 60 fps while the cursor moves, eases to 30 fps when the cursor is still, and pauses on visibilitychange. After 2 minutes without input it draws one last frame and stops until the next movement.
• Reduced motion. With prefers-reduced-motion: reduce it draws one still frame with no drift, parallax or arrival rings; lit marks still respond, instantly.
• Budget. Under 1 ms of script a frame on a 2020 laptop, checked with the browser's performance panel before each scene ships.
• Scenes are data. A scene is a preset of layout, shapes, counts and which data it reads; the engine is shared.

Why Rust and WASM. A small script would have done for a few hundred marks; Rust keeps the whole of Oxygen in one language, lets the scene be tested like the rest, and is ready for scenes with heavy layout (a repository's full change graph) where sharing oxy-core's own types would pay. The cost is kept out of the hub's build by committing the output.

7. The viewer's choice

Settings › Appearance gains Background: Moving (default), Still, Off, kept in a backdrop cookie read before first paint, like the theme cookie, so a page never flashes a backdrop it should not have. Still draws the reduced-motion frame. Save-Data: on and a pointer that is coarse only (a phone) default to Still.

8. Order of work

1. The engine and the dashboard's Your sky, with the tokens, the setting and the contrast check (the next issue).
2. Signed-out home and Explore (the same scene, public data).
3. Sign in and register (the mark).
4. Diffusion ripples.
5. The swarm on Admin › Runners › Images.
6. Adrift on error pages.

9. Open questions

• Should a cluster's lit marks show the event's title on rest, as a tooltip would? It is useful, but it is more text in the background. For now, no: the activity list beside them has the titles.
• Organisation pages could have their own sky (the organisation's repositories). That is cheap once Your sky exists.