From 82f5c399c5dcbadbef2798c67376ffef65d881d7 Mon Sep 17 00:00:00 2001
From: Sylvester Damgaard <sn@cbox.dk>
Date: Mon, 3 Aug 2026 12:12:42 +0200
Subject: [PATCH] docs(mobile/4): document the screen lifecycle events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers ScreenMounted / ScreenResumed / ScreenUnmounted from
NativePHP/mobile-air#248 — a new 'Observing the lifecycle from outside'
section on the Lifecycle Hooks page, plus a pointer from the Events page,
which until now only covered component-targeted native events.

Leads with why they exist rather than what they are: the hooks are the
app's to override, so a base class's mount() is the wrong home for
anything cross-cutting. Also documents the two behaviours a reader would
otherwise have to discover from the source — listener exceptions are
logged rather than propagated, and restoring a preloaded stack after a
hot reload stays quiet.
---
 .../4/digging-deeper/lifecycle-hooks.md       | 42 +++++++++++++++++++
 .../views/docs/mobile/4/the-basics/events.md  |  4 ++
 2 files changed, 46 insertions(+)

diff --git a/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md b/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md
index 981cdfa3..dad099dd 100644
--- a/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md
+++ b/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md
@@ -143,6 +143,48 @@ class Dashboard extends NativeComponent
 Override `placeholder()` to customize the loading frame; the default is a centered activity indicator wrapped in
 the screen's layout chrome.
 
+## Observing the lifecycle from outside
+
+The hooks above are yours to override, which makes them the wrong place for anything cross-cutting. Put
+analytics, telemetry, or crash breadcrumbs in a base class's `mount()` and any screen that defines its own
+`mount()` silently replaces it — so the observer goes quiet on exactly the screens with the most logic in them.
+
+For that, the router dispatches ordinary Laravel events alongside each hook:
+
+| Event | Fires |
+|-------|-------|
+| `ScreenMounted` | after a freshly pushed screen's `mount()` |
+| `ScreenResumed` | after `onResume()`, when the user returns to a screen already on the stack |
+| `ScreenUnmounted` | after `unmount()`, as the screen leaves the stack |
+
+Each carries the component class and the screen's uri, and you listen for them anywhere you'd listen for a
+Laravel event — a service provider, an `AppServiceProvider` boot method, a dedicated subscriber:
+
+```php
+use Illuminate\Support\Facades\Event;
+use Native\Mobile\Events\Screen\ScreenMounted;
+
+Event::listen(ScreenMounted::class, function (ScreenMounted $event) {
+    Analytics::screen($event->component, $event->uri);
+});
+```
+
+These fire *around* your hooks rather than instead of them — overriding `mount()` changes nothing about when
+they arrive, which is the whole point.
+
+Two things worth knowing. A listener that throws is caught and logged rather than propagated: an observer
+should not be able to take the navigation loop down with it, so check your logs if one seems not to run. And
+restoring a preloaded stack after a hot reload stays quiet — those screens are being restored, not navigated
+to.
+
+<aside>
+
+These are app-wide Laravel events, not the component-targeted native events on the
+[Events](../the-basics/events) page. Use `#[On]` when a screen needs to react to something; use these when
+something outside the screens needs to know what the user is doing.
+
+</aside>
+
 ## Related
 
 Beyond the lifecycle, screens react to the outside world through a few attributes:
diff --git a/resources/views/docs/mobile/4/the-basics/events.md b/resources/views/docs/mobile/4/the-basics/events.md
index dd2ca72f..cc220bb7 100644
--- a/resources/views/docs/mobile/4/the-basics/events.md
+++ b/resources/views/docs/mobile/4/the-basics/events.md
@@ -59,6 +59,10 @@ Native events originate on the device side and are delivered to whichever screen
 events an async native call resolves with. Because delivery targets the live screen, a listener only fires while
 its screen is on the stack.
 
+That last part is also the limit of this page. If something outside your screens needs to follow what the user
+is doing — analytics, telemetry, crash breadcrumbs — listen for the app-wide
+[screen lifecycle events](../digging-deeper/lifecycle-hooks#observing-the-lifecycle-from-outside) instead.
+
 <aside>
 
 You can drive events in tests without a device — `emitNative(Event::class, [...])` delivers one straight to the