From 688ae9ef0b4e5416347fdafaf4c966dfb6df7964 Mon Sep 17 00:00:00 2001
From: Simon Hamp <simon.hamp@me.com>
Date: Fri, 2 Oct 2026 11:28:29 +0100
Subject: [PATCH] Point #[Lazy] docs at async tasks

#[Lazy] runs mount() on the UI thread, so the screen can't be used or left
until it returns. Async tasks render the real screen straight away and keep
it interactive, so recommend them for slow screens.

Also drop "in the background" from the #[Lazy] intro, since mount() doesn't
run in the background.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../4/digging-deeper/lifecycle-hooks.md       | 25 ++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

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 82415a31c..a7daa9bb7 100644
--- a/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md
+++ b/resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md
@@ -120,7 +120,7 @@ public function updatedQuery(string $value): void
 ## Instant screens with #[Lazy]
 
 When `mount()` does slow work (a network call, a heavy query), mark the component `#[Lazy]` to paint a
-placeholder **immediately** while `mount()` runs in the background, so navigation feels instant:
+placeholder **immediately** while `mount()` runs, so navigation feels instant:
 
 ```php
 use Native\Mobile\Attributes\Lazy;
@@ -143,6 +143,29 @@ 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.
 
+<aside>
+
+Prefer [async tasks](async-tasks) for slow screens. `#[Lazy]` still runs `mount()` on the UI thread, so while the
+placeholder is showing the user can't interact with the screen or navigate away from it until `mount()` returns.
+
+Dispatching the slow work as an async task from `mount()` lets the real screen render straight away. It stays
+interactive while the work runs, and you decide exactly which parts show a loading state:
+
+```php
+class Dashboard extends NativeComponent
+{
+    public ?array $stats = null;
+
+    public function mount(): void
+    {
+        $this->async(static fn () => Stats::crunch())
+            ->finished(fn (array $stats) => $this->stats = $stats);
+    }
+}
+```
+
+</aside>
+
 ## Observing the lifecycle from outside
 
 <x-docs.version-badge since="4.1" />