docs: align screen lifecycle docs with single-GenServer navigation - #76
Draft
minibikini wants to merge 1 commit into
Draft
docs: align screen lifecycle docs with single-GenServer navigation#76minibikini wants to merge 1 commit into
minibikini wants to merge 1 commit into
Conversation
guides/screen_lifecycle.md, navigation.md, Mob.Screen moduledoc, and PLAN.md claimed each screen in the nav stack is a separate supervised process and that popping calls terminate/2. In reality one Mob.Screen GenServer owns the whole stack: push mounts in the same process, pop restores a snapshot from nav_history. terminate/2 fires only when the whole GenServer stops. Rewrite the affected sections to match the shipped model.
minibikini
marked this pull request as draft
August 8, 2026 19:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs describe a per-screen-process model that the shipped implementation doesn't have, and
terminate/2semantics that never fire the way they're described.What the code actually does (verified against
lib/mob/screen.ex):Mob.ScreenGenServer owns the whole navigation stack. The active screen is a{module, socket}pair in its state.pushmounts the next module in that same process and stores{module, socket}innav_history.pop/pop_to/pop_to_root/resetrestore a snapshot fromnav_history— they start no process and call no lifecycle callback.terminate/2runs only when the wholeMob.ScreenGenServer stops (app exit, crash, shutdown), and delegates to the module active at that time only.The native side confirms this is intentional:
mob_handle_back(iOSmob_nif.m, Androidmob_nif.zig) looks up a single registered:mob_screenprocess, andrenderer.excallsset_root/1once per render. There is no per-screen process anywhere.Docs fixed in this PR
guides/screen_lifecycle.md— "Each screen in the navigation stack is a separate, supervised process" and the "popped → terminate/2" diagram step.guides/navigation.md— "Passing data on pop" claimed popping restores a still-running per-screen process.lib/mob/screen.ex@moduledoc— claimed one supervised GenServer per screen with per-screen crash isolation.PLAN.md— "terminate/2 is called on every screen process exit" used for crash reporting.No runtime code changes. Formatting +
mix credo --strictare clean.This is documentation-only. If a per-screen actor model is actually the intended direction, this PR highlights exactly where the shipped implementation and the docs diverge, and it would be worth deciding which way to take it before md docs keep promising isolate process-per-screen behaviour that doesn't exist.