igneum/docs/plans/miner-ui-2.md

# Igneum Miner UI 2: sections behind a rail, 5 October 2026

the project lead, 18:40 UTC: "can any updates be made to the UI of the miner? different sections for different features. Made
super simple for users, all settings super easy and simple and everything looking gorgeous, as close to shippable
as we can get right now." Worktree `/Users/joshm/Projects/igneum-wt-miner-ui`, branch `miner-ui-2` from master
a93199a. the project lead approved the redesign from the screenshots (20:1x UTC) and moved it into 0.3.10: the 0.3.10 shipper merges
`miner-ui-2` last and rebuilds the app. Times are UTC.

## 1. What changed

| Where | What |
|---|---|
| `app/igneum-app/ui/index.html` | One page became a rail with six sections: Mine, Prove, Rewards, Node, Updates, Settings. The welcome, GPU and address screens and the one-time key sheet stay as they were. The settings panel, the bottom bar and the proving tile are gone; every control they held is placed on a section. |
| `app/igneum-app/ui/app.css` | Rewritten around the rail, the thin top bar, the status strip and the pages. Same tokens as the site (obsidian, graphite, ember, molten, bone, ash; Unbounded, IBM Plex Sans, IBM Plex Mono). One accent. Lays out from 900 x 600: under 1000 px the rail folds to icons, the number strips to two columns, the two-column grid to one. Focus rings on every control (`:focus-visible`, the switch tracks). |
| `app/igneum-app/ui/app.js` | New pure block `View` (the words every section shows for a state), tested by `view.test.mjs`. The Notices and UpdateCard blocks, the log drawer and the blocks canvas are unchanged. `?page=<name>` forces a section and `?logs=1` opens the drawer (screenshots). |
| `app/igneum-app/ui/view.test.mjs` | 10 tests: the GPU row (names, kinds, integrated off, temperatures amber then red, unknown numbers blank), the big button, the node words, the next switch, the prove words, the dev-fee lines, the jobs line. Added to `.github/workflows/ci.yml`. |
| `app/igneum-app/src/state.rs`, `engine.rs` | Engine addition 1: `node.consensus_digest`, the node's own "Consensus params digest" line (`digest_from_line`, tested; a peer's digest in a WARN line is never taken). Addition 2: `node.consensus_switches`, every `*_activation_daa` in the override file the node was started with, lowest first, in plain words (`switches_of`, tested). |
| `app/igneum-app/src/prover.rs` | Engine addition 3: `proving.program_id` and `proving.aggregator_id` from `igneum-prove-host --mode id` (`ids_from_describe`, tested), read once at thread start on macOS and Linux and when the WSL2 host is found on Windows, proving on or off. |
| `app/mac/IgneumMiner.swift` | Window minimum 900 x 600 (was 900 x 620). |
| `app/windows/host.cpp` | One `WM_GETMINMAXINFO` case: minimum 900 x 600 (there was no minimum). |

The API contract is otherwise as it was: the UI calls the same routes (`api/state`, `api/cards`, `api/pause`,
`api/resume`, `api/prove`, `api/settings`, `api/update/*`, `api/jobs/*`, `api/sweep/*`, `api/key/*`, `api/log`,
`api/open`, `api/quit`, `api/clock/sync`, `api/power/apply`, `api/detect`, `api/phase`, `api/setup`, `api/start`).

## 2. The sections

| Section | What it holds | Where it was |
|---|---|---|
| Mine | One big Start mining / Stop mining button (pause and resume), hash rate, blocks found, next program; one row per GPU with its real name, kind tag (Integrated shown as such and off by default, the engine's rule), on/off switch (applies at once; the other cards keep their identities and caps), hash rate, temperature and power where the card reports them; the blocks strip; Activity | the dashboard strip, the Cards card, the Pause button, the Events card |
| Prove | The proving switch with three plain sentences on what proving is; state, assigned, proven, paid (IGN when paid); the verifier's state with one line; the shard program id and the aggregator id with Copy; Set up when the WSL2 host is missing | the Proving tile and the Settings switch |
| Rewards | The address with one Copy; blocks found, this run, balance; the Save your key card (two lines, Show my key, Hide) or the "you pasted your own address" line; Use another address; the dev-fee line; the wallet page | the Settings address block |
| Node | Node state, height, peers, version, each with a plain line; the chain numbers; the consensus digest with Copy; the next switch with its height and how far away; every switch with the applied ones dimmed; finality; the clock card when the clock is off | the Node and Finality cards |
| Updates | The version, Check now, Install now when a download is ready, the auto-update switch; remote jobs: Check now, the state line, the history table, the signing key | the Settings version and remote-jobs blocks |
| Settings | Per card: power cap slider with the watt number (NVIDIA; Apple silicon says it manages its own power), identities stepper, sweep line with Sweep now / Stop / Unpin, the cap-applied or Retry line, draw and temperatures; the sweep switch; start at login; remote jobs allowed; vote on checkpoints; the machine name; the dev fee stated plainly; Copy the log and Show the log, the log and chain folders; Advanced (collapsed): the devnet trust switch, the live page | the Settings panel |
| Status strip | Unchanged (Notices): updates, remote jobs, the clock, one at a time, under the top bar | the same place |
| Rail foot | Machine name, rewards address, Logs (the drawer), Quit, version and chain | the bottom bar |

Every control in Settings is one switch, one slider or one field with one line of help under it. Nothing was
removed: the identities stepper, the sweep buttons, the power Retry, the trust switch, the live page, the machine
rename, the key reveal, the log drawer with its chips, search, ruler and jump controls all still exist.

Empty, loading and error states: Mine says "Asking the graphics cards to report in" then "No GPU this app can drive
was found" (red) with the detect message; the big button is disabled with a reason while no card is on, the engine
is away or the app quits; Prove says off, needs setup, waiting, proving, submitted or idle, each with a sentence;
Node says starting, syncing with a percentage and the ETA, synced, restarting, failed or stopped, and the digest
box says "not printed yet" or "the node is not running"; Updates says "Not checked yet" or "This build has no update
address"; the jobs table says "No job has run on this machine yet"; Settings says "No card yet"; a lost engine
turns the pill to "engine away" and the Mine and Node words to "no answer".

## 3. Proof

The engine was built from this worktree on the Mac under the build lock (`with-lock.sh build nice -n 19 cargo build
--release -j 4`, rustup's cargo 1.99; Homebrew's cargo 1.69 in PATH cannot read the lock file) and run on its own
port and data directory in devnet v4 mode (`IGNEUM_APP_BIN` = the installed 0.3.9 bundle's `Resources/bin`,
`IGNEUM_APP_DATA`, `IGNEUM_APP_LOGS`, `IGNEUM_APP_NODE_DIR` under the session scratchpad, RPC 27610, P2P 27611,
a scratch `igneum-app.json` next to the binary with the devnet override params, no update manifest) through
`with-lock.sh run`. The live Mac app's engine, node 1 and the observer were not touched; the test node peered with
the seed and node 1 and synced 123,559 blocks in about 12 minutes, then the M5 Max mined on it (22 MH/s, digest
1f4b4425..., the devnet's). The setup flow was walked in the built-in browser pane (Get started, the GPU switch,
Make me an address, the key sheet, Start mining) and every section was clicked through, the rail driven with the
arrow keys, and the window checked at 900 x 600.

Tests: `node --test notices.test.mjs update-card.test.mjs view.test.mjs` = 20 pass, 0 fail; `cargo test --release
--bin igneum-app -- digest_comes switches_are pinned_ids` = 3 pass (the three new engine tests, run on the Mac
under the build lock; the full suites go to PC 2 with the 0.3.11 cut as usual).

The PNGs below were taken with the installed Mac host's snapshot mode (`"Igneum Miner" --snapshot <png> --url <the
test engine> --size 1200x780`, a real WKWebView, Retina 2400 x 1560), in `docs/plans/miner-ui-2/`.

| File | Shows | Placeholder or sample |
|---|---|---|
| `00-welcome.png` | The welcome screen (unchanged) | none |
| `01-setup-gpu.png` | Step 1, the M5 Max row with its switch | none |
| `02-setup-address.png` | Step 2, make an address or paste one | none |
| `03-setup-key.png` | The one-time key sheet | the key is zeros (`?screen=key` sample) |
| `04-mine.png` | Mine while mining: the big button, 23 MH/s, the GPU row, the blocks strip | temperature and power say n/a on Apple silicon (the engine has no reading for it) |
| `05-prove-off.png` | Prove with proving off, the verifier verifying, both pinned ids | none |
| `06-prove-on.png` | Prove with proving on: Proving (CPU), block 35507 shard 0 | none (the Mac CPU prover was switched on for 25 s, then off) |
| `07-rewards.png` | Rewards: the address, 343 lifetime blocks, Save your key, Use another address | the balance cell says "--, shown in the wallet, not here yet" (no API) |
| `08-node.png` | Node synced: height, 2 peers, version 2.1.0, the digest, next switch Fees v1 at 210,000, finality | none |
| `09-updates.png` | Updates: 0.3.9, Check now, auto-update, remote jobs | this build has no manifest, so "no update address" and "no jobs address" |
| `10-settings.png` | Settings: the card block, the sweep switch, this machine, dev fee, logs, Advanced collapsed | the NVIDIA power slider is not in the shot (no NVIDIA card on this Mac); its markup is in `setCardHtml` |
| `11-logs-drawer.png` | Mine with the log drawer open (chips, search, ruler, follow, close) | none |
| `12-strip-update.png` | The status strip with "Igneum Miner 0.3.7 is available", Install now, Later | `?update=available` sample |
| `13-strip-job.png` | Updates with a running remote job in the strip and the table | `?job=running` sample |
| `14-node-syncing.png` | Node while syncing: 59,602 of 123,559 (48%), the next switch from that height | none |
| `15-mine-syncing.png` | Mine while the node syncs: the button says Stop mining, waiting for the node to sync | taken before the blank marker in the GPU row became `n/a` (it shows a dash) |
| `16-narrow-900-mine.png` | Mine at 900 x 620 (the installed host's minimum; the new hosts say 600): the icon rail, two-column numbers, the power column dropped | none |
| `17-narrow-900-settings.png` | Settings at 900 x 620 | none |
| `18-narrow-900-node.png` | Node at 900 x 620 | none |

## 4. Shippable now, placeholder, follow-ups

Shippable now: the six sections, the rail, the strip, the drawer, every setting, the three engine fields, the
hosts' minimum size. The Windows host line is untested on Windows (one `WM_GETMINMAXINFO` case; the 0.3.11 cut
builds it on the runner as usual). The NVIDIA power slider, telemetry and sweep lines on Settings and the
temperature and power columns on Mine are rendered from the same state fields the old tiles used, but no NVIDIA
card was on this Mac, so they are unseen in these shots: the PC screenshot is the first thing to look at after
the cut.

Placeholder: the balance cell on Rewards ("shown in the wallet, not here yet").

Follow-ups (engine work, not built here; the budget was three small additions):

| Follow-up | What it needs |
|---|---|
| Balance on Rewards | the engine reads `eth_getBalance` for the rewards address from the node's EVM RPC every 30 s (`update.rs` has the curl shape) and puts `address.balance_wei` on the state |
| "Pause while I use the machine" | does not exist in the engine: an idle-input reading per platform and a pause/resume on it; the Settings switch is one line once the field exists |
| Log export as a file | today Copy the log puts the last 2,000 ring lines on the clipboard and the folder path is shown; a `/api/log/export` that writes the ring to the log folder and reveals it in Finder or Explorer needs a `platform::reveal_path` |
| Temperature and power on Apple silicon | the engine reads no telemetry for Metal; `powermetrics` needs root, so this stays blank unless a non-root source is found |
| A per-card "pause this card" without restarting the others | exists already through the row switch (only that card's worker restarts); nothing to do unless the project lead wants a timer |

## 5. The 0.3.10 merge: gpu-hotplug (4d122e1) resolved on the new UI

The branch was merged with `gpu-hotplug` 4d122e1 (the 0.3.10 tree carries it). The engine, relay and tooling files
merged by themselves; `app.js` and `app.css` were taken from this branch and the hot-plug UI ported by hand:

| Hot-plug state | On the six-section UI |
|---|---|
| The strip notices (card added, mining; new card not usable (Code 43); card removed) | the Notices block is gpu-hotplug's, unchanged; `notices.test.mjs` (12) passes |
| A card the OS reports a problem on (`problem`, "Code 43") | Mine row: name in ember, the word "not usable (Code 43)", the reboot hint under it, the switch disabled; the Mine note repeats the hint; first-run row and Settings card say the same, with no controls |
| A removed card (`removed_at`) | Mine row dimmed, the word "removed", "unplugged; its worker stopped. The row goes in five minutes."; no switch; Settings card says the same; after five minutes (`gone`) the row is not shown |
| The counts and the big button | only present cards count (a removed or faulty card never makes the button say "Stop mining") |
| The name tooltip | the tool's code (gfx1201), the device index, the OpenCL platform, the PCI address (`View.cardTitle`) |
| The card list sent on a switch | removed and faulty cards are left out, as gpu-hotplug's `readCardRows` does |

`view.test.mjs` has an eleventh test for the two states. The whole app crate's unit tests pass on the merged tree
(99, on the Mac under the build lock, `cargo test --release --bin igneum-app`). `relay/test/parse.test.mjs`
passes. The Mac engine builds and runs (the same scratch instance as section 3).

Build tooling for the Windows compile: `packaging/windows/push-build-inputs.sh --no-node` and
`node tools/build-job.mjs run --no-node` pack and build the app engine only (no node source, no node build, no node
tests), so an app-only change compiles on PC 1 in a fraction of the full job.

PC 1 job (20:21Z, from this tree at d62b445, `node tools/build-job.mjs run --target ae432dc7 --no-node --targets
windows --no-tests --no-place`): extract 167 files, `windows app/igneum-app build exit 0 6 s` (the PC's target dir
was warm), `igneum-app.exe` 2,970,112 bytes sha256 62ce96a9..., PE check ok, coin icon and version block ok, done
after 13 s. The exe carries the new UI and engine strings ("Prove shards on this machine" x2, `consensus_switches`
x6, "Consensus params digest:" x1, `card:removed:` x1), so the 6 s was a real compile of the merged sources, with
gpu-hotplug's Windows-only `detect::adapters` path and this branch's prover change in it. Downloads under the session
scratchpad (`pc1-app/`), not placed.

The ship tool runs no node tests of its own (`tools/ship-app.mjs --self-test` is the version bump), so the only
list to carry `view.test.mjs` is `.github/workflows/ci.yml` (done in 83a293f).

What the PC job does not compile: `app/windows/host.cpp` (the window host with the `WM_GETMINMAXINFO` and
`WM_DEVICECHANGE` cases) is built by the GitHub runner (`windows.yml`) at the shipper's push, never on a PC; the
`WM_GETMINMAXINFO` case is three lines of plain Win32 (`MINMAXINFO`, `ptMinTrackSize`) and reads at the runner's log.

## 6. The changelog paragraph for the 0.3.10 manifest notes (what the user sees)

The miner has six sections behind a rail: Mine, Prove, Rewards, Node, Updates, Settings. Mine has one big Start
mining / Stop mining button, the hash rate, the blocks found, and one row per graphics card with its name, an on/off
switch, its hash rate, temperature and power. Prove says in plain words what proving is and shows the shards
assigned, proven and paid, the verifier and the program ids. Rewards shows the address with one Copy and keeps the
key backup in its own card. Node shows the sync, height, peers and version with a plain line under each, the
consensus digest, and the list of planned rule switches with the next one and its height. Updates holds the
version, Check now and the remote jobs. Settings has one switch or slider per setting with one line of help under
each: the power cap per card with the watt number, identities, start at login, remote jobs, voting, the dev fee
stated plainly, the log. The window lays out from 900 x 600. Not in this release: the balance on Rewards (shown in
the wallet), a "pause while I use the machine" switch, log export as a file, temperature and power on Apple
silicon.

## 7. The branch

| Commit | What |
|---|---|
| 83a293f | the UI pass, the three engine additions with tests, the hosts' minimum size, this plan and the 19 screenshots (the blank marker in a GPU row is `n/a`, not a dash: copy law) |
| 364feef | this plan's hash line |
| d62b445 | Merge gpu-hotplug 4d122e1: the hot-plug states on the new UI, `--no-node` for the build tools |