MOB-112: one process per screen, owned and linked

[GenericJam]

Fourth step of epic MOB-108. Follows #95 (MOB-109), #96 (MOB-110), #97 (MOB-111).

Problem

One Mob.Screen process held {module, socket, nav, render_mode} and swapped the first two in place on navigation. Every screen shared one mailbox, so a crash in any handle_event took down navigation and every other screen with it. The moduledoc claimed the opposite for a long time; mob#76 corrected the docs, which documented the gap rather than closing it.

Change

Mob.Screen.Server is one process per live screen, owning that screen's socket. Mob.Screen becomes the owner: it holds navigation, starts/stops/restarts screens, and keeps the :mob_screen registered name so native's enif_whereis_pid lookups are unaffected. Mob.Nav needed no change — it always treated entries as opaque.

self() inside a screen is now the screen's own pid, which is what user code always assumed when writing on_tap: {self(), :save} or starting a task — and what stops screen A's task result landing in screen B (MOB-107).

Public API is unchanged. Adds get_screen_pid/1.

Rationale in decisions/2026-08-28-screen-processes-and-supervision.md.

Three review passes, and what each found

This went through three adversarial reviews. Recording the sequence because each round's fix created the next round's bug, which is the useful part.

Review #1 (14 findings). Two unprotected owner→screen calls meant a crash in handle_event still killed the owner — the exact acceptance criterion. Restarts discarded mount params, so a screen mounting on %{id: id} could never come back and the owner kept a dead pid as current forever.

Review #2 (1 critical). My fix for #1 introduced it: making every screen a live process means the ones below the top of the stack repaint, but Mob.Sender was still addressed per navigation stack and every screen in a stack shared one ref. A Process.send_after tick in a screen the user cannot see committed its tree — tap table included — over the screen they can. MOB-107's whole point is that those messages now arrive on the screen's own pid, so this is the ordinary case. No test could see it: every test runs :no_render, where painting short-circuits.

The render ref is now unique per screen, and Mob.Sender.set_active/1 is called from exactly one place — make_current/2, the single point where current changes.

Review #3 (2 blockers). It cleared the new ref model — attacked every path and race and could not make the sender's active disagree with state.current.ref. The blockers were older code: resolve_destination/1's raise runs in the owner, so push_screen(socket, :typo) killed navigation and every screen; and the give-up branch bricked a tab-bar app, because every tab root has an empty history so "nothing beneath it" is the ordinary shape — the owner kept a dead pid as current while a live screen sat parked under another tab.

Notable decisions

Linked, with both sides trapping. Two wrong turns worth recording. Linking alone kills the owner when it stops a popped screen. Unlinking fixes that and orphans every screen when the owner dies — and an orphaned persisted screen keeps its 30s timer, dumping to ScreenState under the same key as its replacement. The answer is both.

Not a DynamicSupervisor. A supervisor restarting a screen produces a process the owner knows nothing about, in a slot the supervisor cannot know — the crashed screen might be current, in history, or parked. The owner is the only thing that knows, so it restarts, and carries its own max-restart-intensity (5 in 10s per screen ref) since it gave up the one a supervisor provides.

Verification

• 1233 tests, 36 new. 10/10 clean full-suite runs, 12/12 on the restart file
• Negative controls on every substantive fix: reverting the per-screen ref, the params/ref preservation, or the parked-stack fallback fails exactly the test written for it
• mix format, credo --strict, --warnings-as-errors clean
• Device-verified on both platforms: cold boot, first frame, tap, navigation push (the pushed screen renders its own pid, distinct from the owner), pop, and on_change. Zero errors in the BEAM log

Deferred, with reasoning written down

MOB-121 — the owner is now a shared serialisation point (:infinity calls mean one wedged screen blocks every other), and stopping a wedged screen costs 5s that pop_to_root/reset pay serially. Neither is a regression — before this there was one process to block — but both change shape with N screens. MOB-113 is the natural place, since keeping the router off the hot path is its premise.

MOB-116 is resolved by this change: every screen now schedules its own state sync and dumps in its own terminate/2, so parked and history screens finally get both.