loic/crates/loic-gui/README.md

# loic-gui

The Loic Observatory—a temporal meditation interface.

## What It Shows

The Observatory renders the current moment with obsessive precision. Layout, top to bottom:

### Header

A single line at the top showing observation rate (`obs/sec`) and render rate (`renders/sec`). The observer threads sample `LoicInstant::now()` at whatever rate the kernel's clock can be read; the number on the left is their summed rate, and the header is the only place it is reported, because it is the only place it matters.

### The Digit Waterfall

The cosmic time—Planck times elapsed since Creation (the Big Bang)—rendered as a cascade of digits below the header. Each digit position updates at a different frequency, from the leftmost (geological timescales) to the rightmost (faster than perception). The shimmer is real: time passing at 10⁴³ Planck times per second.

The colours are counted from the last digit, because that is where time moves. The last 34 digits are cyan: 10³⁴ Planck times fit in a nanosecond, and every one of those digits is the entropy of the observation, fresh each frame. The 9 before them are gray: nanosecond to second, faster than perception. Everything above is white and changes slower than once a second. The count grows with the age of the universe; the zones do not.

The digits are 61 today and will be 154 at Annihilation. The waterfall reserves four rows of the largest font for them and, when the count outgrows the reserve, steps the font down by an integer factor and carries on: the first step holds 120 digits, the next 200. The one shrink falls at 10¹²⁰ Planck times, around the year 1.7 × 10⁶⁹, and nothing below the waterfall moves, then or ever.

### The Mask Wheels

Two wheels in the middle, **COSMIC** on the left and **CYCLE** on the right, one per channel. Each wheel shows its selection's whole neighbourhood in the lattice: every mask with one more prime above it, every mask with one fewer below it, and the selection itself, named in full, between them. A neighbour is labelled by the one edge that reaches it. `× Sigma` is the mask whose divisor is the selection's multiplied by Sigma, one prime finer; `÷ Dyad` is the selection's divided by Dyad, one prime coarser. The strip is always one row per prime plus the selection, so the Whisper sits at the bottom of its wheel beneath seven or eight parents, and the full mask at the top above its children. The two selections compose the 15-bit observer mask.

Under each wheel, `pos n/total`: the tick of that channel's own subdivision the instant falls in, over the ticks in one traversal, which is the channel's divisor. Both numbers go to three significant figures and a power of ten once they outgrow the column. Below both wheels, a single line shows the Planck times into the current tick, on the cycle channel when it is engaged and on the cosmic channel otherwise, and says which.

Interaction:
- **Scroll** over a wheel: up selects the parent directly above (the lowest inactive prime joins), down the child directly below (the lowest active prime leaves). At the full mask, up loops to the Whisper; at the Whisper, down loops to the full mask. A wheel has no top.
- **Click** any neighbour: jump to it. Every mask is reachable by clicks alone, in at most seven or eight steps from the Whisper.

A `[ random ]` button below the wheels invokes the entropy default observer—nine bits of hardware entropy select a mask. With probability 75%, the wheels jump to the resulting valid mask. With probability 25%, the cosmic pool overflows: the universe has rejected the unframed query, and a topological scar manifests at a random screen location.

See *Topological Scars* below.

### The Timeline

A navigable visualization spanning all of time, from Creation at the left to Annihilation at the right, sitting just above the coordinate cards. The entire span is 10¹⁵⁴ Planck times, and the present is 10⁻⁹³ of the way along it, which is why the full view shows nothing at all: every event is hidden until you have zoomed in far enough for it to be worth mentioning. Scroll over the bar to zoom into the segment under the cursor, scroll the other way to back out, and click a marker to read the event's passage.

There are some sixty events, tiered by how far in you must be to see each: the first stars, the Solar System and the Sun's death at the widest views of the past; the Snowball Earth, the Cambrian and the Great Dying once the window is a billion years wide; the Whisper and, sixty-two days after it, the Unix epoch, when the window is a decade wide. The far future is where most of the zooming happens, and where the entries of the widest views are: the last stars, the dispersal of galaxies, proton decay if there is any, Dyson's rocks flowing into spheres, the white dwarfs eroding away, Sagittarius A* evaporating, and the last black hole, at a googol years. The passages say what is established, what is argued, and what is a calculation on an assumption; the timeline marks a conjecture at its date without pretending it is a fact, and the one entry with even odds of not happening at all says so in its name.

### The Progress Decimal

Between the timeline and the cards, the fraction of everything that has happened so far, as a decimal with all 154 of its places, wrapped to the width: ninety-two zeros, and then digits. It is derived from the frame's own observation, like everything else on the surface, and its last places move.

### Coordinate Cards

Three panels at the bottom showing:
- **COSMIC TIME** — Planck times since the Big Bang
- **WHISPER TIME** — Planck times since the Loic epoch (first ARPANET transmission)
- **ANNIHILATION TIME** — Planck times until heat death

### Audio

A continuous **quantum hum**—background noise sampled fresh from `getrandom` at 44.1 kHz, low-pass filtered, and modulated by a slow random walk. The hum never repeats. The kernel's entropy pool guarantees that.

No transition sounds. The lattice has no seconds, minutes, hours, days, months, or years to mark, and a tone at a boundary that does not exist would be a lie in the audible range. The hum is what a calendar sounds like from underneath.

## Topological Scars

Each invocation of the random observer that lands on a cosmic-pool overflow leaves a scar—a frozen visual record of the malformed question. Scars manifest at random screen locations, on top of all other UI, and persist until the application exits.

Three variants, picked uniformly per crash:

- **GIN gear**: a ~100-pixel-wide glyph rendered as the 21-bit GIN waveform from the project's logo seam, randomly rotated. Each tooth is one bit set in the binary encoding of "GIN."
- **Failed mask**: the cosmic boundary as a thin ring with seven dots placed around it (one per cosmic prime—filled if active in the failed entropy, hollow otherwise). A red phantom dot dangles outside the ring, connected by a thin line, marking where bit 7 would have gone if the cosmic lattice extended that far. It does not.
- **Soliton**: 3–6 concentric amber rings emanating from a point. Inner rings are most opaque; outer rings fade. The workspace README, section 4.5: *"the holes left in the weave stay in the cloth, and the cloth is spacetime."*

Scars block clicks and scroll on their visible (non-transparent) pixels. You may click and scroll through the gaps between an artifact's primitives to interact with the UI underneath. The scars themselves are inert.

To clear them, restart the application.

## Installation

### From Source

```bash
cargo build --release --package loic-gui
./target/release/loic-gui
```

### The Icon

On Wayland a window does not carry its own icon; launchers, taskbars and switchers find it by looking up the desktop entry whose file name matches the window's `app_id`, which the Observatory sets to `loic-observatory`. The entry is `loic-observatory.desktop` in this directory and the icons are in `icons/`, rendered from the logo itself. To install both for one user:

```bash
install -Dm644 loic-observatory.desktop ~/.local/share/applications/loic-observatory.desktop
for s in 16 32 48 64 128 256 512; do
    install -Dm644 icons/loic-observatory-$s.png ~/.local/share/icons/hicolor/${s}x${s}/apps/loic-observatory.png
done
```

The entry runs `loic-gui` from `PATH`; point its `Exec=` line at the binary's full path if it lives elsewhere. The icons are the logo itself, rendered at the seven sizes the hicolor theme expects.

## Requirements

- **Linux** with `CLOCK_TAI`, and a kernel that has been told the TAI−UTC offset. A time daemon that reads a leap-second table sets it (chrony with `leapseclist` or `leapsectz`, ntpd with `leapfile`); systemd-timesyncd never will. On a kernel whose offset is zero the Observatory opens, renders the library's verdict as its only frame, and observes nothing. It refuses to lie.
- **Wayland.** The X11 path is not compiled.
- **GPU** with Vulkan, or OpenGL as the one permitted fallback (wgpu backend). The Observatory renders on the GPU the compositor lives on: it asks the driver for no preference and takes the first device offered, so on a machine with two GPUs `DRI_PRIME=1` sends it to the other one, as with any Mesa application. A discrete GPU buys it nothing; its frames are a few thousand glyph quads, and every one of them would have to cross the bus to be composited. The adapter, backend, present mode and surface format are printed once on standard error at startup.
- **Audio device** (optional, for the quantum hum)

## Controls

| Input | Action |
|-------|--------|
| Scroll over wheel | Step to the neighbour above (finer) or below (coarser); loops at the ends |
| Click wheel row | Jump to that neighbour |
| Click `[ random ]` | Invoke entropy observer (~25% triggers a scar) |
| Scroll over timeline bar | Zoom into the segment under the cursor, or back out |
| Click timeline bar | Zoom into that segment |
| Click timeline event | Show cosmic passage |
| Click passage | Dismiss overlay |
| Click on scar | Nothing — scars are inert |
| Backspace | Close passage / step back one zoom level |
| Escape | Reset timeline / close passage |

## Architecture

One observer thread per logical CPU, and the main thread:

- **Observers** — Each samples `LoicInstant::now()` as fast as the kernel's clock can be read, counts its collapses on a tally of its own, and reads none of them. Every core the machine has, at full tilt, observing moments nobody will see. That is the meditation. It is also why the fans are on.
- **Main thread** — Makes exactly one observation per frame, derives everything on screen from that single instant (the waterfall, the cards, the progress decimal, the timeline's "now", the wheels' offset), renders it via wgpu, and handles window events. The screen never shows two moments at once.

The observers' summed rate and the render rate are independent; the header reports both, and how many observers there are. The Observatory is not nice: before it looses the observers it asks the kernel for a nice value of −11, the most a desktop's usual limit grants an unprivileged process, and every thread inherits it, so whatever else the machine is doing yields to the observation of moments nobody will see. If the kernel declines, it says so once on standard error and observes at the priority of everything else.

## Performance

The Observatory targets maximum frame rate with minimal latency:

- GPU-accelerated text rendering via custom glyph atlas
- Instanced digit rendering for the waterfall display
- One relaxed atomic per observer between the threads, and nothing else
- No VSync where the surface offers an alternative (temporal observation should not be throttled); the present mode is printed at startup

On capable hardware, expect thousands of frames per second. The digits will blur. This is correct.

## The Point

The Observatory does nothing useful whatsoever.

It does not schedule meetings. It does not set alarms. It does not convert to Gregorian. It shows you one thing: Now, expressed with more precision than any human could perceive, contextualized against the entire span of cosmic time, with the option to ask the universe a malformed question and accumulate frozen records of the failures across your screen.

You are approximately 10⁻⁹³ of the way through everything that will ever happen.

The Observatory exists to make this viscerally apparent.

## License

Dual-licensed under AGPL-3.0 and the Loic Public License.