# glimmer-cosmic

The **libcosmic** backend for glimmer — a spike. The same hiccup that
[glimmer-vidya](../glimmer-vidya) paints with egui and [glimmer-tui](../glimmer-tui)
paints in a terminal, painted with COSMIC's widgets and theme through
[`crates/jolt-cosmic`](../../crates/jolt-cosmic).

```bash
cargo build --release -p jolt-cosmic
LD_LIBRARY_PATH=../../target/release jolt counter
LD_LIBRARY_PATH=../../target/release jolt smoke    # non-interactive, quits itself
```

## What is the same

The tree half is glimmer-vidya's. Nodes are integer handles in a Rust arena,
props are written across by name, handlers stay on the jolt side and are found
by node id when an event comes back, and a widget writes its new value into its
own props so a control that ignores its event still works.

## What is not: who owns the loop

egui lets its caller drive frames. libcosmic does not: `cosmic::app::run` takes
the main thread (winit insists) and keeps it until the window closes. So the
loop is inverted:

```
main thread      cosmic_run ──────────────────────────────────── returns on close
                     ▲ wake(tree)              │ click / change / toggled
worker (future)  mount → commit → wait ─ drain, dispatch, timers → commit → wait …
```

* The reconciler runs on a worker, which is the "UI thread" as glimmer sees it:
  `schedule` queues onto it, handlers and timers run on it.
* Its edits land in the arena under a mutex, but libcosmic paints a snapshot
  taken at `cosmic_tree_commit`, once per pass. A reconcile half-way through a
  patch is never on screen, and a pass that changed nothing commits nothing.
* The worker sleeps in `cosmic_wait` until there is an event, a `schedule`, a
  due timer or a close — an idle window costs neither side anything.
* Every call but `cosmic_run` is safe from any thread, which is not true of
  libvidya.

## Spike limits

* Tags: `:window` `:box`/`:hbox`/`:vbox` `:page` `:card` `:frame` `:scroll`
  `:label` `:title` `:title-2` `:dim-label` `:button` `:checkbutton` `:entry`
  `:separator` `:spacer` `:progress`. Anything else paints as a column.
* Events: `click`, `toggled`, `change`, `activate`.
* One window per process — winit cannot make a second event loop — so there is
  no REPL `start!`/`stop!` yet, and no headless test beyond the arena's own
  Rust tests.
* libcosmic is MPL-2.0 and a git dependency; see `crates/jolt-cosmic/Cargo.toml`.