diff --git a/.gitignore b/.gitignore
index 9713846c4..e6c33865c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@ auth.json
 
 # storage
 /storage/*.key
+/storage/docs-screenshots
 
 # vendor
 /vendor
diff --git a/app/Console/Commands/CaptureDocsScreenshots.php b/app/Console/Commands/CaptureDocsScreenshots.php
new file mode 100644
index 000000000..040502c34
--- /dev/null
+++ b/app/Console/Commands/CaptureDocsScreenshots.php
@@ -0,0 +1,278 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Enums\DocsScreenshotCrop;
+use App\Enums\DocsScreenshotPlatform;
+use App\Services\DocsScreenshots\ScreenshotCapturer;
+use App\Services\DocsScreenshots\ScreenshotPublisher;
+use App\Support\DocsScreenshotManifest;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\File;
+
+final class CaptureDocsScreenshots extends Command
+{
+    /** Exclusive ceiling for `--crop-percent` — matches `native:screenshot`'s own single-edge ceiling. */
+    private const CROP_PERCENT_CEILING = 1.0;
+
+    protected $signature = 'docs:capture-screenshots
+        {--platform=both : ios, android, or both}
+        {--super-native-path= : Local checkout of NativePHP/super-native}
+        {--udid= : Specific simulator/emulator UDID — required whenever native:run would otherwise have more than one device to pick from}
+        {--only= : Comma-separated screen keys to limit to, e.g. top-bar,bottom-nav}
+        {--settle-ms=2000 : Milliseconds to wait after launch before capturing}
+        {--full : Keep the full, uncropped screenshot instead of the tight top/bottom crop most screens use}
+        {--crop-percent= : Override the configured crop_percent for this run (0-1)}
+        {--crop-offset= : Override the configured crop_offset for this run (0-1) — skips the OS status bar/nav bar before measuring crop-percent}
+        {--dry-run : Print what would be captured without running anything}
+        {--publish : Copy every staged screenshot into public/img/docs}';
+
+    protected $description = "Regenerate the mobile docs' Edge Component screenshots from a running super-native checkout";
+
+    public function handle(): int
+    {
+        $superNativePath = $this->resolveSuperNativePath();
+
+        if ($superNativePath === null) {
+            return self::FAILURE;
+        }
+
+        $platforms = DocsScreenshotPlatform::fromOption((string) $this->option('platform'));
+
+        if ($platforms === []) {
+            $this->error(sprintf("Invalid --platform '%s'. Use 'ios', 'android', or 'both'.", $this->option('platform')));
+
+            return self::FAILURE;
+        }
+
+        $keys = $this->resolveScreenKeys();
+
+        if ($keys === null) {
+            return self::FAILURE;
+        }
+
+        $cropPercent = $this->resolveCropPercent();
+
+        if ($cropPercent === null) {
+            return self::FAILURE;
+        }
+
+        $cropOffset = $this->resolveCropOffset($cropPercent);
+
+        if ($cropOffset === null) {
+            return self::FAILURE;
+        }
+
+        if ($this->option('dry-run')) {
+            $this->printDryRun($superNativePath, $keys, $platforms, $cropPercent, $cropOffset);
+
+            return self::SUCCESS;
+        }
+
+        $stagingPath = (string) config('docs.screenshots.staging_path');
+        File::ensureDirectoryExists($stagingPath);
+
+        $capturer = new ScreenshotCapturer($superNativePath, (int) config('docs.screenshots.process_timeout'));
+        $failures = [];
+
+        foreach ($keys as $key) {
+            foreach ($platforms as $platform) {
+                if (! $this->captureScreen($capturer, $stagingPath, $key, $platform, $cropPercent, $cropOffset)) {
+                    $failures[] = sprintf('%s (%s)', $key, $platform->value);
+                }
+            }
+        }
+
+        if ($failures !== []) {
+            $this->error(sprintf('Failed to capture: %s', implode(', ', $failures)));
+
+            return self::FAILURE;
+        }
+
+        $this->info(sprintf('Captured %d screen(s) into %s', count($keys), $stagingPath));
+
+        if ($this->option('publish') && ! $this->publish($stagingPath, $keys, $platforms)) {
+            return self::FAILURE;
+        }
+
+        return self::SUCCESS;
+    }
+
+    private function resolveSuperNativePath(): ?string
+    {
+        $path = rtrim((string) $this->option('super-native-path'), '/');
+
+        if ($path === '') {
+            $this->error('--super-native-path is required — pass the local checkout of NativePHP/super-native, e.g. a sibling directory of this repo.');
+
+            return null;
+        }
+
+        if (! is_dir($path) || ! is_file($path.'/artisan') || ! is_file($path.'/routes/mobile.php')) {
+            $this->error(sprintf("'%s' doesn't look like a super-native checkout (missing artisan or routes/mobile.php).", $path));
+
+            return null;
+        }
+
+        return $path;
+    }
+
+    /**
+     * @return list<string>|null
+     */
+    private function resolveScreenKeys(): ?array
+    {
+        $only = (string) $this->option('only');
+
+        if ($only === '') {
+            return DocsScreenshotManifest::keys();
+        }
+
+        $keys = array_filter(array_map('trim', explode(',', $only)));
+        $unknown = array_filter($keys, fn (string $key): bool => ! DocsScreenshotManifest::has($key));
+
+        if ($unknown !== []) {
+            $this->error(sprintf('Unknown screen key(s): %s', implode(', ', $unknown)));
+
+            return null;
+        }
+
+        return array_values($keys);
+    }
+
+    private function resolveCropPercent(): ?float
+    {
+        $given = (string) $this->option('crop-percent');
+        $percent = $given === '' ? (float) config('docs.screenshots.crop_percent') : (float) $given;
+
+        if ($percent <= 0 || $percent >= self::CROP_PERCENT_CEILING) {
+            $this->error(sprintf(
+                '--crop-percent must be between 0 and %s (exclusive), got %s.',
+                self::CROP_PERCENT_CEILING,
+                $given
+            ));
+
+            return null;
+        }
+
+        return $percent;
+    }
+
+    private function resolveCropOffset(float $cropPercent): ?float
+    {
+        $given = (string) $this->option('crop-offset');
+        $offset = $given === '' ? (float) config('docs.screenshots.crop_offset') : (float) $given;
+
+        if ($offset < 0 || $offset + $cropPercent >= self::CROP_PERCENT_CEILING) {
+            $this->error(sprintf(
+                '--crop-offset (%s) plus --crop-percent (%s) must be less than %s.',
+                $given === '' ? $offset : $given,
+                $cropPercent,
+                self::CROP_PERCENT_CEILING
+            ));
+
+            return null;
+        }
+
+        return $offset;
+    }
+
+    /**
+     * @param  list<string>  $keys
+     * @param  list<DocsScreenshotPlatform>  $platforms
+     */
+    private function printDryRun(string $superNativePath, array $keys, array $platforms, float $cropPercent, float $cropOffset): void
+    {
+        $this->info(sprintf('Would use super-native checkout: %s', $superNativePath));
+
+        foreach ($keys as $key) {
+            $screen = DocsScreenshotManifest::get($key);
+
+            foreach ($platforms as $platform) {
+                $crop = $this->option('full') || $screen['crop'] === DocsScreenshotCrop::Full
+                    ? 'full'
+                    : sprintf('%s %d%% (offset %d%%)', $screen['crop']->value, (int) round($cropPercent * 100), (int) round($cropOffset * 100));
+
+                $this->line(sprintf(
+                    '  %s (%s) — route %s — %s%s',
+                    $key,
+                    $platform->value,
+                    $screen['route'],
+                    $crop,
+                    $screen['requires_drawer_open'] ? ' — needs a manual drawer-open step' : ''
+                ));
+            }
+        }
+    }
+
+    private function captureScreen(
+        ScreenshotCapturer $capturer,
+        string $stagingPath,
+        string $key,
+        DocsScreenshotPlatform $platform,
+        float $cropPercent,
+        float $cropOffset,
+    ): bool {
+        $screen = DocsScreenshotManifest::get($key);
+        $outputPath = sprintf('%s/%s', $stagingPath, $screen[$platform->value]);
+        $crop = $this->option('full') ? DocsScreenshotCrop::Full : $screen['crop'];
+
+        $failure = $capturer->capture(
+            key: $key,
+            platform: $platform,
+            route: $screen['route'],
+            requiresDrawerOpen: $screen['requires_drawer_open'],
+            udid: (string) $this->option('udid'),
+            settleMs: (int) $this->option('settle-ms'),
+            outputPath: $outputPath,
+            crop: $crop,
+            cropPercent: $cropPercent,
+            cropOffset: $cropOffset,
+            isInteractive: $this->input->isInteractive(),
+            confirmDrawerOpen: fn (string $message) => $this->ask($message),
+        );
+
+        if ($failure !== null) {
+            $this->error($failure);
+
+            return false;
+        }
+
+        $this->info($crop === DocsScreenshotCrop::Full
+            ? sprintf('Captured %s (full, uncropped).', $outputPath)
+            : sprintf('Captured %s (cropped to %s).', $outputPath, $crop->value));
+
+        return true;
+    }
+
+    /**
+     * @param  list<string>  $keys
+     * @param  list<DocsScreenshotPlatform>  $platforms
+     */
+    private function publish(string $stagingPath, array $keys, array $platforms): bool
+    {
+        $publishPath = (string) config('docs.screenshots.publish_path');
+
+        $filenames = [];
+
+        foreach ($keys as $key) {
+            foreach ($platforms as $platform) {
+                $filenames[] = DocsScreenshotManifest::get($key)[$platform->value];
+            }
+        }
+
+        $failures = (new ScreenshotPublisher)->publish($stagingPath, $publishPath, $filenames);
+
+        if ($failures !== []) {
+            $this->error(sprintf('Failed to publish: %s', implode(', ', $failures)));
+
+            return false;
+        }
+
+        $this->info(sprintf('Published %s.', $publishPath));
+
+        return true;
+    }
+}
diff --git a/app/Enums/DocsScreenshotCrop.php b/app/Enums/DocsScreenshotCrop.php
new file mode 100644
index 000000000..4a910fc5e
--- /dev/null
+++ b/app/Enums/DocsScreenshotCrop.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums;
+
+/**
+ * Which edge of a captured screenshot documents the component being shown.
+ * `Top`/`Bottom` keep only a strip nearest that edge — matching every
+ * existing top-bar/bottom-nav image in public/img/docs, which are cropped
+ * tight rather than full-screen. `Full` keeps the whole screenshot, for
+ * components (like the side nav) that need their full height visible.
+ */
+enum DocsScreenshotCrop: string
+{
+    case Top = 'top';
+    case Bottom = 'bottom';
+    case Full = 'full';
+}
diff --git a/app/Enums/DocsScreenshotPlatform.php b/app/Enums/DocsScreenshotPlatform.php
new file mode 100644
index 000000000..d2e438d03
--- /dev/null
+++ b/app/Enums/DocsScreenshotPlatform.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums;
+
+enum DocsScreenshotPlatform: string
+{
+    case Ios = 'ios';
+    case Android = 'android';
+
+    /**
+     * Parse the `--platform` option ('ios', 'android', or 'both') into the
+     * concrete platforms to capture. Returns an empty array for anything else.
+     *
+     * @return list<self>
+     */
+    public static function fromOption(string $value): array
+    {
+        return match ($value) {
+            'ios' => [self::Ios],
+            'android' => [self::Android],
+            'both' => [self::Ios, self::Android],
+            default => [],
+        };
+    }
+}
diff --git a/app/Services/DocsScreenshots/ScreenshotCapturer.php b/app/Services/DocsScreenshots/ScreenshotCapturer.php
new file mode 100644
index 000000000..488d187c6
--- /dev/null
+++ b/app/Services/DocsScreenshots/ScreenshotCapturer.php
@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\DocsScreenshots;
+
+use App\Enums\DocsScreenshotCrop;
+use App\Enums\DocsScreenshotPlatform;
+use Illuminate\Process\Exceptions\ProcessTimedOutException;
+use Illuminate\Support\Facades\Process;
+
+/**
+ * Drives one screen/platform capture in a super-native checkout: launches
+ * the screen with `native:run`, optionally waits for a manually-confirmed
+ * drawer-open step, then captures it with `native:screenshot` — which owns
+ * cropping itself (`--crop`/`--crop-percent`/`--crop-offset`), so every
+ * NativePHP developer gets it too, not just this docs pipeline.
+ */
+final class ScreenshotCapturer
+{
+    private const MICROSECONDS_PER_MILLISECOND = 1_000;
+
+    public function __construct(
+        private readonly string $superNativePath,
+        private readonly int $timeout,
+    ) {}
+
+    /**
+     * Returns null on success, or a human-readable failure reason.
+     *
+     * @param  callable(string): void  $confirmDrawerOpen  Prompts the user and blocks until they respond.
+     */
+    public function capture(
+        string $key,
+        DocsScreenshotPlatform $platform,
+        string $route,
+        bool $requiresDrawerOpen,
+        string $udid,
+        int $settleMs,
+        string $outputPath,
+        DocsScreenshotCrop $crop,
+        float $cropPercent,
+        float $cropOffset,
+        bool $isInteractive,
+        callable $confirmDrawerOpen,
+    ): ?string {
+        $runCommand = $this->buildArgv([
+            'php', 'artisan', 'native:run', $platform->value, $udid,
+            '--build=debug',
+            '--start-url='.$route,
+            '--no-tty',
+        ]);
+
+        if (! $this->runProcess($runCommand)) {
+            return sprintf(
+                'native:run failed for %s (%s). If it has more than one device to pick from, pass --udid explicitly.',
+                $key,
+                $platform->value
+            );
+        }
+
+        if ($requiresDrawerOpen) {
+            if (! $isInteractive) {
+                return sprintf(
+                    'Skipping %s (%s): opening its drawer needs a manual step, so it can only be captured interactively.',
+                    $key,
+                    $platform->value
+                );
+            }
+
+            $confirmDrawerOpen(sprintf(
+                'Manually open the side drawer for "%s" in the %s simulator/emulator now, then press Enter to continue',
+                $key,
+                $platform->value
+            ));
+        }
+
+        usleep(max(0, $settleMs) * self::MICROSECONDS_PER_MILLISECOND);
+
+        $screenshotCommand = $this->buildArgv([
+            'php', 'artisan', 'native:screenshot', $platform->value, $udid,
+            '--output='.$outputPath,
+            $crop === DocsScreenshotCrop::Full ? '' : '--crop='.$crop->value,
+            $crop === DocsScreenshotCrop::Full ? '' : '--crop-percent='.$cropPercent,
+            $crop === DocsScreenshotCrop::Full ? '' : '--crop-offset='.$cropOffset,
+        ]);
+
+        if (! $this->runProcess($screenshotCommand)) {
+            return sprintf('native:screenshot failed for %s (%s).', $key, $platform->value);
+        }
+
+        return null;
+    }
+
+    /**
+     * `native:run` prompts interactively when `--udid` is ambiguous and no
+     * real terminal is attached to this subprocess, which can time out
+     * rather than fail fast — caught here and reported as an ordinary
+     * failure instead of crashing the caller.
+     *
+     * @param  list<string>  $command
+     */
+    private function runProcess(array $command): bool
+    {
+        try {
+            return Process::path($this->superNativePath)->timeout($this->timeout)->run($command)->successful();
+        } catch (ProcessTimedOutException) {
+            return false;
+        }
+    }
+
+    /**
+     * Drop empty arguments (an omitted `--udid`) so the target command sees
+     * a clean argv instead of a blank positional argument.
+     *
+     * @param  list<string>  $argv
+     * @return list<string>
+     */
+    private function buildArgv(array $argv): array
+    {
+        return array_values(array_filter($argv, fn (string $argument): bool => $argument !== ''));
+    }
+}
diff --git a/app/Services/DocsScreenshots/ScreenshotPublisher.php b/app/Services/DocsScreenshots/ScreenshotPublisher.php
new file mode 100644
index 000000000..af1fe4837
--- /dev/null
+++ b/app/Services/DocsScreenshots/ScreenshotPublisher.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\DocsScreenshots;
+
+use Illuminate\Support\Facades\File;
+
+/**
+ * Copies staged screenshots into their public docs path.
+ */
+final class ScreenshotPublisher
+{
+    /**
+     * Copies each filename from $stagingPath to $publishPath.
+     *
+     * @param  list<string>  $filenames
+     * @return list<string> the filenames that failed to publish (empty on full success)
+     */
+    public function publish(string $stagingPath, string $publishPath, array $filenames): array
+    {
+        File::ensureDirectoryExists($publishPath);
+
+        $failures = [];
+
+        foreach ($filenames as $filename) {
+            $source = sprintf('%s/%s', $stagingPath, $filename);
+            $destination = sprintf('%s/%s', $publishPath, $filename);
+
+            if (! File::exists($source) || ! File::copy($source, $destination)) {
+                $failures[] = $filename;
+            }
+        }
+
+        return $failures;
+    }
+}
diff --git a/app/Support/DocsScreenshotManifest.php b/app/Support/DocsScreenshotManifest.php
new file mode 100644
index 000000000..0ad0397ae
--- /dev/null
+++ b/app/Support/DocsScreenshotManifest.php
@@ -0,0 +1,218 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support;
+
+use App\Enums\DocsScreenshotCrop;
+use InvalidArgumentException;
+
+/**
+ * The docs-reference screens captured by `docs:capture-screenshots`, one
+ * entry per screen in `NativePHP/super-native`'s "Edge Component showcase"
+ * route group. Adding a new prop-variant screen there means adding its
+ * entry here too.
+ *
+ * @phpstan-type Screen array{route: string, ios: string, android: string, requires_drawer_open: bool, crop: DocsScreenshotCrop}
+ */
+final class DocsScreenshotManifest
+{
+    /**
+     * @var array<string, Screen>
+     */
+    private const SCREENS = [
+        'top-bar' => [
+            'route' => '/edge-components/top-bar',
+            'ios' => 'edge-top-bar-ios.png',
+            'android' => 'edge-top-bar-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Top,
+        ],
+        'top-bar-large-title' => [
+            'route' => '/edge-components/top-bar-large-title',
+            'ios' => 'edge-top-bar-large-title-ios.png',
+            'android' => 'edge-top-bar-large-title-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Top,
+        ],
+        'top-bar-search' => [
+            'route' => '/edge-components/top-bar-search',
+            'ios' => 'edge-top-bar-search-ios.png',
+            'android' => 'edge-top-bar-search-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Top,
+        ],
+        'top-bar-destructive-action' => [
+            'route' => '/edge-components/top-bar-destructive-action',
+            'ios' => 'edge-top-bar-destructive-action-ios.png',
+            'android' => 'edge-top-bar-destructive-action-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Top,
+        ],
+        'top-bar-logo' => [
+            'route' => '/edge-components/top-bar-logo',
+            'ios' => 'edge-top-bar-logo-ios.png',
+            'android' => 'edge-top-bar-logo-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Top,
+        ],
+        'bottom-nav' => [
+            'route' => '/edge-components/bottom-nav',
+            'ios' => 'edge-bottom-nav-ios.png',
+            'android' => 'edge-bottom-nav-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Bottom,
+        ],
+        'bottom-nav-search-item' => [
+            'route' => '/edge-components/bottom-nav-search-item',
+            'ios' => 'edge-bottom-nav-search-item-ios.png',
+            'android' => 'edge-bottom-nav-search-item-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Bottom,
+        ],
+        'side-nav' => [
+            'route' => '/edge-components/side-nav',
+            'ios' => 'edge-side-nav-ios.png',
+            'android' => 'edge-side-nav-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'side-nav-header-image' => [
+            'route' => '/edge-components/side-nav-header-image',
+            'ios' => 'edge-side-nav-header-image-ios.png',
+            'android' => 'edge-side-nav-header-image-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'bottom-sheet' => [
+            'route' => '/explore/sheets',
+            'ios' => 'edge-bottom-sheet-ios.png',
+            'android' => 'edge-bottom-sheet-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'modal' => [
+            'route' => '/explore/sheets',
+            'ios' => 'edge-modal-ios.png',
+            'android' => 'edge-modal-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'menus' => [
+            'route' => '/explore/menus',
+            'ios' => 'edge-menus-ios.png',
+            'android' => 'edge-menus-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'list' => [
+            'route' => '/mail-demo',
+            'ios' => 'edge-list-ios.png',
+            'android' => 'edge-list-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'refreshable' => [
+            'route' => '/refreshable-demo',
+            'ios' => 'edge-refreshable-ios.png',
+            'android' => 'edge-refreshable-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'virtual-list' => [
+            'route' => '/explore/icons',
+            'ios' => 'edge-virtual-list-ios.png',
+            'android' => 'edge-virtual-list-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'slider' => [
+            'route' => '/explore/forms',
+            'ios' => 'edge-slider-ios.png',
+            'android' => 'edge-slider-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'toggle' => [
+            'route' => '/explore/forms',
+            'ios' => 'edge-toggle-ios.png',
+            'android' => 'edge-toggle-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'checkbox' => [
+            'route' => '/explore/forms',
+            'ios' => 'edge-checkbox-ios.png',
+            'android' => 'edge-checkbox-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'select' => [
+            'route' => '/explore/forms',
+            'ios' => 'edge-select-ios.png',
+            'android' => 'edge-select-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'radio-group' => [
+            'route' => '/explore/forms',
+            'ios' => 'edge-radio-group-ios.png',
+            'android' => 'edge-radio-group-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'web-view' => [
+            'route' => '/webview-demo',
+            'ios' => 'edge-web-view-ios.png',
+            'android' => 'edge-web-view-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'gesture-area' => [
+            'route' => '/animate',
+            'ios' => 'edge-gesture-area-ios.png',
+            'android' => 'edge-gesture-area-android.png',
+            'requires_drawer_open' => true,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'tab-row' => [
+            'route' => '/twitter/profile/0',
+            'ios' => 'edge-tab-row-ios.png',
+            'android' => 'edge-tab-row-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+        'text' => [
+            'route' => '/explore/typography',
+            'ios' => 'edge-text-ios.png',
+            'android' => 'edge-text-android.png',
+            'requires_drawer_open' => false,
+            'crop' => DocsScreenshotCrop::Full,
+        ],
+    ];
+
+    /**
+     * @return list<string>
+     */
+    public static function keys(): array
+    {
+        return array_keys(self::SCREENS);
+    }
+
+    public static function has(string $key): bool
+    {
+        return array_key_exists($key, self::SCREENS);
+    }
+
+    /**
+     * @return Screen
+     */
+    public static function get(string $key): array
+    {
+        if (! self::has($key)) {
+            throw new InvalidArgumentException("Unknown docs screenshot screen: {$key}");
+        }
+
+        return self::SCREENS[$key];
+    }
+}
diff --git a/config/docs.php b/config/docs.php
index 92c545a15..ae6fd0b80 100644
--- a/config/docs.php
+++ b/config/docs.php
@@ -63,6 +63,45 @@
         ],
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Screenshot Capture
+    |--------------------------------------------------------------------------
+    |
+    | Where `docs:capture-screenshots` writes captured screenshots. Every run
+    | writes to staging_path; `--publish` additionally copies them into
+    | publish_path, overwriting the tracked images the docs pages reference.
+    |
+    | staging_path deliberately sits outside storage/app (the `local`
+    | filesystem disk's root) — these are scratch files from a local dev
+    | tool, not app-managed disk content.
+    |
+    | process_timeout bounds each `native:run` / `native:screenshot` call
+    | (seconds) — a real simulator/emulator boot and build can take a while.
+    |
+    | crop_percent is how much of the image height a top/bottom-cropped
+    | screenshot keeps (matches every existing top-bar/bottom-nav image in
+    | public/img/docs, which are cropped tight rather than full-screen).
+    | It's an approximation, not a per-device measurement — review a staged
+    | screenshot before publishing and adjust here if a component's bar is
+    | taller or shorter than this assumes. --full skips cropping entirely.
+    |
+    | crop_offset is how much of the image height to skip from the crop edge
+    | before measuring crop_percent, so the OS status bar (top crop) or OS
+    | nav bar/home indicator (bottom crop) is excluded from the captured
+    | strip. Like crop_percent, it's an approximation tuned against real
+    | device captures — review a staged screenshot before publishing.
+    |
+    */
+
+    'screenshots' => [
+        'staging_path' => storage_path('docs-screenshots'),
+        'publish_path' => public_path('img/docs'),
+        'process_timeout' => 300,
+        'crop_percent' => 0.15,
+        'crop_offset' => 0.05,
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Jump
diff --git a/docker-compose.local.yml b/docker-compose.local.yml
new file mode 100644
index 000000000..745301e3e
--- /dev/null
+++ b/docker-compose.local.yml
@@ -0,0 +1,21 @@
+# Lightweight local MySQL for developers who aren't running Herd's own
+# database service — matches .env.example's default DB_* values.
+# Usage: docker compose -f docker-compose.local.yml up -d
+services:
+    mysql:
+        image: mysql:8.4
+        environment:
+            MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+            MYSQL_DATABASE: "nativephp.com"
+        ports:
+            - "3306:3306"
+        volumes:
+            - mysql-data:/var/lib/mysql
+        healthcheck:
+            test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+            interval: 5s
+            timeout: 5s
+            retries: 10
+
+volumes:
+    mysql-data:
diff --git a/public/img/docs/edge-bottom-nav-android.png b/public/img/docs/edge-bottom-nav-android.png
index a0bf2273f..b7367cdf9 100644
Binary files a/public/img/docs/edge-bottom-nav-android.png and b/public/img/docs/edge-bottom-nav-android.png differ
diff --git a/public/img/docs/edge-bottom-nav-ios.png b/public/img/docs/edge-bottom-nav-ios.png
index 9a3784cc0..2076c5385 100644
Binary files a/public/img/docs/edge-bottom-nav-ios.png and b/public/img/docs/edge-bottom-nav-ios.png differ
diff --git a/public/img/docs/edge-bottom-sheet-android.png b/public/img/docs/edge-bottom-sheet-android.png
new file mode 100644
index 000000000..f0a228daa
Binary files /dev/null and b/public/img/docs/edge-bottom-sheet-android.png differ
diff --git a/public/img/docs/edge-bottom-sheet-ios.png b/public/img/docs/edge-bottom-sheet-ios.png
new file mode 100644
index 000000000..a9c3c5f4e
Binary files /dev/null and b/public/img/docs/edge-bottom-sheet-ios.png differ
diff --git a/public/img/docs/edge-checkbox-android.png b/public/img/docs/edge-checkbox-android.png
new file mode 100644
index 000000000..137551fc0
Binary files /dev/null and b/public/img/docs/edge-checkbox-android.png differ
diff --git a/public/img/docs/edge-checkbox-ios.png b/public/img/docs/edge-checkbox-ios.png
new file mode 100644
index 000000000..c953f361b
Binary files /dev/null and b/public/img/docs/edge-checkbox-ios.png differ
diff --git a/public/img/docs/edge-gesture-area-android.png b/public/img/docs/edge-gesture-area-android.png
new file mode 100644
index 000000000..25bcf4a92
Binary files /dev/null and b/public/img/docs/edge-gesture-area-android.png differ
diff --git a/public/img/docs/edge-gesture-area-ios.png b/public/img/docs/edge-gesture-area-ios.png
new file mode 100644
index 000000000..31f2c5462
Binary files /dev/null and b/public/img/docs/edge-gesture-area-ios.png differ
diff --git a/public/img/docs/edge-list-android.png b/public/img/docs/edge-list-android.png
new file mode 100644
index 000000000..b093db89e
Binary files /dev/null and b/public/img/docs/edge-list-android.png differ
diff --git a/public/img/docs/edge-list-ios.png b/public/img/docs/edge-list-ios.png
new file mode 100644
index 000000000..c5ab92beb
Binary files /dev/null and b/public/img/docs/edge-list-ios.png differ
diff --git a/public/img/docs/edge-menus-android.png b/public/img/docs/edge-menus-android.png
new file mode 100644
index 000000000..be6afe046
Binary files /dev/null and b/public/img/docs/edge-menus-android.png differ
diff --git a/public/img/docs/edge-menus-ios.png b/public/img/docs/edge-menus-ios.png
new file mode 100644
index 000000000..76697b87b
Binary files /dev/null and b/public/img/docs/edge-menus-ios.png differ
diff --git a/public/img/docs/edge-modal-android.png b/public/img/docs/edge-modal-android.png
new file mode 100644
index 000000000..0ebc53e0c
Binary files /dev/null and b/public/img/docs/edge-modal-android.png differ
diff --git a/public/img/docs/edge-modal-ios.png b/public/img/docs/edge-modal-ios.png
new file mode 100644
index 000000000..3d06a48eb
Binary files /dev/null and b/public/img/docs/edge-modal-ios.png differ
diff --git a/public/img/docs/edge-radio-group-android.png b/public/img/docs/edge-radio-group-android.png
new file mode 100644
index 000000000..137551fc0
Binary files /dev/null and b/public/img/docs/edge-radio-group-android.png differ
diff --git a/public/img/docs/edge-radio-group-ios.png b/public/img/docs/edge-radio-group-ios.png
new file mode 100644
index 000000000..00ac307f0
Binary files /dev/null and b/public/img/docs/edge-radio-group-ios.png differ
diff --git a/public/img/docs/edge-refreshable-android.png b/public/img/docs/edge-refreshable-android.png
new file mode 100644
index 000000000..da70eb985
Binary files /dev/null and b/public/img/docs/edge-refreshable-android.png differ
diff --git a/public/img/docs/edge-refreshable-ios.png b/public/img/docs/edge-refreshable-ios.png
new file mode 100644
index 000000000..901af46c2
Binary files /dev/null and b/public/img/docs/edge-refreshable-ios.png differ
diff --git a/public/img/docs/edge-select-android.png b/public/img/docs/edge-select-android.png
new file mode 100644
index 000000000..137551fc0
Binary files /dev/null and b/public/img/docs/edge-select-android.png differ
diff --git a/public/img/docs/edge-select-ios.png b/public/img/docs/edge-select-ios.png
new file mode 100644
index 000000000..e7605daba
Binary files /dev/null and b/public/img/docs/edge-select-ios.png differ
diff --git a/public/img/docs/edge-side-nav-android.png b/public/img/docs/edge-side-nav-android.png
index 46f0fb7b6..efa863ce5 100644
Binary files a/public/img/docs/edge-side-nav-android.png and b/public/img/docs/edge-side-nav-android.png differ
diff --git a/public/img/docs/edge-side-nav-ios.png b/public/img/docs/edge-side-nav-ios.png
index 01abcd893..f3a6d2873 100644
Binary files a/public/img/docs/edge-side-nav-ios.png and b/public/img/docs/edge-side-nav-ios.png differ
diff --git a/public/img/docs/edge-slider-android.png b/public/img/docs/edge-slider-android.png
new file mode 100644
index 000000000..f5b6290c8
Binary files /dev/null and b/public/img/docs/edge-slider-android.png differ
diff --git a/public/img/docs/edge-slider-ios.png b/public/img/docs/edge-slider-ios.png
new file mode 100644
index 000000000..3a3caf84c
Binary files /dev/null and b/public/img/docs/edge-slider-ios.png differ
diff --git a/public/img/docs/edge-tab-row-android.png b/public/img/docs/edge-tab-row-android.png
new file mode 100644
index 000000000..a07cf8991
Binary files /dev/null and b/public/img/docs/edge-tab-row-android.png differ
diff --git a/public/img/docs/edge-tab-row-ios.png b/public/img/docs/edge-tab-row-ios.png
new file mode 100644
index 000000000..ef37ad4c3
Binary files /dev/null and b/public/img/docs/edge-tab-row-ios.png differ
diff --git a/public/img/docs/edge-text-android.png b/public/img/docs/edge-text-android.png
new file mode 100644
index 000000000..f30753486
Binary files /dev/null and b/public/img/docs/edge-text-android.png differ
diff --git a/public/img/docs/edge-text-ios.png b/public/img/docs/edge-text-ios.png
new file mode 100644
index 000000000..b8bbc36af
Binary files /dev/null and b/public/img/docs/edge-text-ios.png differ
diff --git a/public/img/docs/edge-toggle-android.png b/public/img/docs/edge-toggle-android.png
new file mode 100644
index 000000000..f5b6290c8
Binary files /dev/null and b/public/img/docs/edge-toggle-android.png differ
diff --git a/public/img/docs/edge-toggle-ios.png b/public/img/docs/edge-toggle-ios.png
new file mode 100644
index 000000000..3a3caf84c
Binary files /dev/null and b/public/img/docs/edge-toggle-ios.png differ
diff --git a/public/img/docs/edge-top-bar-android.png b/public/img/docs/edge-top-bar-android.png
index f4b2ce56f..ee24cf151 100644
Binary files a/public/img/docs/edge-top-bar-android.png and b/public/img/docs/edge-top-bar-android.png differ
diff --git a/public/img/docs/edge-top-bar-ios.png b/public/img/docs/edge-top-bar-ios.png
index 1af165665..b99ef39bd 100644
Binary files a/public/img/docs/edge-top-bar-ios.png and b/public/img/docs/edge-top-bar-ios.png differ
diff --git a/public/img/docs/edge-virtual-list-android.png b/public/img/docs/edge-virtual-list-android.png
new file mode 100644
index 000000000..b85eade17
Binary files /dev/null and b/public/img/docs/edge-virtual-list-android.png differ
diff --git a/public/img/docs/edge-virtual-list-ios.png b/public/img/docs/edge-virtual-list-ios.png
new file mode 100644
index 000000000..486cb6f9b
Binary files /dev/null and b/public/img/docs/edge-virtual-list-ios.png differ
diff --git a/public/img/docs/edge-web-view-android.png b/public/img/docs/edge-web-view-android.png
new file mode 100644
index 000000000..6142e34df
Binary files /dev/null and b/public/img/docs/edge-web-view-android.png differ
diff --git a/public/img/docs/edge-web-view-ios.png b/public/img/docs/edge-web-view-ios.png
new file mode 100644
index 000000000..c9a6792f7
Binary files /dev/null and b/public/img/docs/edge-web-view-ios.png differ
diff --git a/resources/views/components/docs/edge-preview.blade.php b/resources/views/components/docs/edge-preview.blade.php
new file mode 100644
index 000000000..4476f0d73
--- /dev/null
+++ b/resources/views/components/docs/edge-preview.blade.php
@@ -0,0 +1,107 @@
+@props([
+    'ios' => null,
+    'android' => null,
+    'source' => null,
+    'alt' => 'Screenshot',
+    'edge' => null,
+    'sidebarWidthIos' => null,
+    'sidebarWidthAndroid' => null,
+])
+
+@php
+    $default = $ios ? 'ios' : 'android';
+    $showTop = in_array($edge, ['top', 'both'], true);
+    $showBottom = in_array($edge, ['bottom', 'both'], true);
+    $storageKey = 'nativephp-docs-edge-preview-collapsed:'.($ios ?? $android ?? $alt);
+    [$iosRadius, $androidRadius] = match (true) {
+        $showTop && ! $showBottom => ['rounded-t-[2.25rem]', 'rounded-t-[1.75rem]'],
+        $showBottom && ! $showTop => ['rounded-b-[2.25rem]', 'rounded-b-[1.75rem]'],
+        default => ['rounded-[2.25rem]', 'rounded-[1.75rem]'],
+    };
+
+    // When a screenshot shows an open drawer/sheet that only covers part of
+    // the width, the real device's dimming scrim sits over everything below
+    // it — including the status bar and home-indicator zones. Splitting the
+    // fake chrome bars' background to match keeps that scrim visually
+    // continuous through the chrome instead of stopping dead at its edge.
+    $scrim = '#8c8d8f';
+    $splitBackground = fn (?int $width, string $base): ?string => $width !== null
+        ? "background: linear-gradient(to right, {$base} 0%, {$base} {$width}%, {$scrim} {$width}%, {$scrim} 100%);"
+        : null;
+    $iosTopStyle = $splitBackground($sidebarWidthIos, '#ffffff');
+    $iosBottomStyle = $splitBackground($sidebarWidthIos, '#f9fafb');
+    $androidStyle = $splitBackground($sidebarWidthAndroid, '#f8fafc');
+@endphp
+
+<div x-data="{ platform: '{{ $default }}', collapsed: false, clockIos: '', clockAndroid: '', init() { try { this.collapsed = localStorage.getItem('{{ $storageKey }}' + window.location.pathname) === '1'; } catch (e) {} this.tickClock(); setInterval(() => this.tickClock(), 1000); }, tickClock() { const d = new Date(); let h = d.getHours() % 12; if (h === 0) h = 12; const m = String(d.getMinutes()).padStart(2, '0'); this.clockIos = h + ':' + m; this.clockAndroid = String(d.getHours()).padStart(2, '0') + ':' + m; }, toggleCollapsed() { this.collapsed = !this.collapsed; try { localStorage.setItem('{{ $storageKey }}' + window.location.pathname, this.collapsed ? '1' : '0'); } catch (e) {} } }" class="not-prose my-8 overflow-hidden rounded-2xl border border-gray-200 bg-gray-50 dark:border-white/10 dark:bg-white/[0.03]">
+    <div class="flex flex-wrap items-center justify-between gap-3 border-b border-gray-200 px-4 py-2.5 dark:border-white/10">
+        @if ($ios && $android)
+            <div class="flex gap-1 transition-opacity" :class="collapsed ? 'pointer-events-none opacity-40' : ''">
+                <button type="button" @click="platform = 'ios'" :class="platform === 'ios' ? 'bg-white text-gray-900 shadow-sm dark:bg-gray-700 dark:text-white' : 'text-gray-500 hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200'" class="rounded-md px-3 py-1 text-xs font-medium transition-colors">iOS</button>
+                <button type="button" @click="platform = 'android'" :class="platform === 'android' ? 'bg-white text-gray-900 shadow-sm dark:bg-gray-700 dark:text-white' : 'text-gray-500 hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200'" class="rounded-md px-3 py-1 text-xs font-medium transition-colors">Android</button>
+            </div>
+        @else
+            <span class="text-xs font-medium text-gray-500 transition-opacity dark:text-gray-400" :class="collapsed ? 'opacity-40' : ''">{{ $ios ? 'iOS' : 'Android' }}</span>
+        @endif
+        <div class="flex items-center gap-2">
+            @if ($source)
+                <a href="https://github.com/NativePHP/super-native/blob/main/{{ $source }}" target="_blank" rel="noopener" title="View this example in super-native" class="inline-flex items-center gap-1.5 rounded-md border border-gray-200 px-2 py-1 text-xs font-medium text-gray-500 transition-colors hover:border-gray-300 hover:text-gray-800 dark:border-white/10 dark:text-gray-400 dark:hover:border-white/20 dark:hover:text-white">
+                    <x-icons.github class="size-3.5" />
+                    Source
+                </a>
+            @endif
+            <button type="button" @click="toggleCollapsed()" class="inline-flex items-center gap-1.5 rounded-md border border-gray-200 px-2 py-1 text-xs font-medium text-gray-500 transition-colors hover:border-gray-300 hover:text-gray-800 dark:border-white/10 dark:text-gray-400 dark:hover:border-white/20 dark:hover:text-white">
+                <span x-text="collapsed ? 'Show preview' : 'Hide preview'"></span>
+                <svg class="size-3 transition-transform" :class="collapsed ? '-rotate-90' : ''" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M2.5 4.5L6 8l3.5-3.5" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" /></svg>
+            </button>
+        </div>
+    </div>
+    <div x-show="!collapsed" x-transition class="flex justify-center bg-[radial-gradient(circle_at_center,var(--color-gray-100)_0%,transparent_70%)] p-6 sm:p-10 dark:bg-[radial-gradient(circle_at_center,--alpha(var(--color-white)/4%)_0%,transparent_70%)]">
+        <div class="w-fit overflow-hidden shadow-xl ring-1 ring-black/10 transition-[border-radius] duration-200" :class="platform === 'ios' ? '{{ $iosRadius }}' : '{{ $androidRadius }}'">
+            @if ($ios)
+                <div x-show="platform === 'ios'">
+                    @if ($showTop)
+                        <div class="relative flex h-11 items-center justify-center bg-white px-6 text-gray-900" @if ($iosTopStyle) style="{{ $iosTopStyle }}" @endif>
+                            <span class="absolute left-6 text-[10px] font-semibold tabular-nums" x-text="clockIos"></span>
+                            <span class="h-7 w-[31%] rounded-full bg-black"></span>
+                            <div class="absolute right-6 flex items-center gap-1.5">
+                                <svg class="h-2.5 w-3.5" viewBox="0 0 14 10" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="6" width="2" height="4" rx="0.5" /><rect x="4" y="4" width="2" height="6" rx="0.5" /><rect x="8" y="2" width="2" height="8" rx="0.5" /><rect x="12" y="0" width="2" height="10" rx="0.5" /></svg>
+                                <svg class="size-3" viewBox="0 0 16 12" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 4.5C4.5 1 11.5 1 15 4.5M3.5 7C5.8 4.8 10.2 4.8 12.5 7" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" /><circle cx="8" cy="9.3" r="1" fill="currentColor" /></svg>
+                                <svg class="h-3 w-5" viewBox="0 0 24 12" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="1" y="1" width="19" height="10" rx="2.5" stroke="currentColor" stroke-width="1.3" /><rect x="2.5" y="2.5" width="16" height="7" rx="1.5" fill="currentColor" /><rect x="21.5" y="4" width="1.5" height="4" rx="0.75" fill="currentColor" /></svg>
+                            </div>
+                        </div>
+                    @endif
+                    <img src="/img/docs/{{ $ios }}" alt="{{ $alt }} (iOS)" class="no-format block max-h-[28rem]" />
+                    @if ($showBottom)
+                        <div class="flex justify-center bg-gray-50 py-2" @if ($iosBottomStyle) style="{{ $iosBottomStyle }}" @endif>
+                            <span class="h-1 w-[32%] rounded-full bg-gray-900/40"></span>
+                        </div>
+                    @endif
+                </div>
+            @endif
+            @if ($android)
+                <div x-show="platform === 'android'">
+                    @if ($showTop)
+                        <div class="relative flex h-9 items-center justify-end bg-slate-50 px-6 text-gray-900" @if ($androidStyle) style="{{ $androidStyle }}" @endif>
+                            <span class="absolute left-6 text-[10px] font-medium tabular-nums" x-text="clockAndroid"></span>
+                            <span class="absolute left-1/2 top-1/2 size-3 -translate-x-1/2 -translate-y-1/2 rounded-full bg-black"></span>
+                            <div class="flex items-center gap-2">
+                                <svg class="h-2.5 w-3.5" viewBox="0 0 14 10" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="6" width="2" height="4" rx="0.5" /><rect x="4" y="4" width="2" height="6" rx="0.5" /><rect x="8" y="2" width="2" height="8" rx="0.5" /><rect x="12" y="0" width="2" height="10" rx="0.5" /></svg>
+                                <svg class="h-2.5 w-3.5" viewBox="0 0 16 12" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 4.5C4.5 1 11.5 1 15 4.5M3.5 7C5.8 4.8 10.2 4.8 12.5 7" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" /><circle cx="8" cy="9.3" r="1" fill="currentColor" /></svg>
+                                <svg class="h-3 w-5" viewBox="0 0 24 12" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="1" y="1" width="19" height="10" rx="2.5" stroke="currentColor" stroke-width="1.3" /><rect x="2.5" y="2.5" width="16" height="7" rx="1.5" fill="currentColor" /><rect x="21.5" y="4" width="1.5" height="4" rx="0.75" fill="currentColor" /></svg>
+                            </div>
+                        </div>
+                    @endif
+                    <img src="/img/docs/{{ $android }}" alt="{{ $alt }} (Android)" class="no-format block max-h-[28rem]" />
+                    @if ($showBottom)
+                        <div class="flex items-center justify-evenly bg-slate-50 px-6 py-3 text-gray-400" @if ($androidStyle) style="{{ $androidStyle }}" @endif>
+                            <svg class="h-2 w-[3%]" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M20 2L2 12l18 10" stroke="currentColor" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" /></svg>
+                            <span class="block h-2 w-[3%] rounded-full ring-2 ring-current"></span>
+                            <span class="block h-2 w-[3%] rounded-[3px] ring-2 ring-current"></span>
+                        </div>
+                    @endif
+                </div>
+            @endif
+        </div>
+    </div>
+</div>
diff --git a/resources/views/docs/mobile/4/edge-components/bottom-nav.md b/resources/views/docs/mobile/4/edge-components/bottom-nav.md
index cee4c63ee..bc6456b7e 100644
--- a/resources/views/docs/mobile/4/edge-components/bottom-nav.md
+++ b/resources/views/docs/mobile/4/edge-components/bottom-nav.md
@@ -5,13 +5,13 @@ order: 120
 
 ## Overview
 
-<div class="images-two-up not-prose">
-
-![](/img/docs/edge-bottom-nav-ios.png)
-
-![](/img/docs/edge-bottom-nav-android.png)
-
-</div>
+<x-docs.edge-preview
+    ios="edge-bottom-nav-ios.png"
+    android="edge-bottom-nav-android.png"
+    source="resources/views/native/edge-components/bottom-nav.blade.php"
+    alt="Bottom navigation"
+    edge="bottom"
+/>
 
 A bottom navigation bar with up to 5 items — your app's primary navigation. Placing `<native:bottom-nav>` at the
 root of a screen's Blade **hoists it onto the real native chrome root** (a `TabView` on iOS, a `NavigationBar` in a
diff --git a/resources/views/docs/mobile/4/edge-components/bottom-sheet.md b/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
index 4bbdd035f..342a35b7d 100644
--- a/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
+++ b/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
@@ -5,6 +5,14 @@ order: 130
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-bottom-sheet-ios.png"
+    android="edge-bottom-sheet-android.png"
+    source="resources/views/native/explore/sheets.blade.php"
+    alt="Bottom sheet"
+    edge="both"
+/>
+
 A modal panel that slides up from the bottom of the screen. Use it for contextual actions, forms, and detail views
 that overlay the main content. Renders as SwiftUI's `.sheet` with `presentationDetents` on iOS and a Material3
 `ModalBottomSheet` on Android.
diff --git a/resources/views/docs/mobile/4/edge-components/checkbox.md b/resources/views/docs/mobile/4/edge-components/checkbox.md
index e1254dd2d..23cd070c4 100644
--- a/resources/views/docs/mobile/4/edge-components/checkbox.md
+++ b/resources/views/docs/mobile/4/edge-components/checkbox.md
@@ -5,6 +5,14 @@ order: 190
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-checkbox-ios.png"
+    android="edge-checkbox-android.png"
+    source="resources/views/native/explore/forms.blade.php"
+    alt="Checkbox"
+    edge="both"
+/>
+
 A binary tick/untick control with an optional inline label. On iOS, renders as a tappable SF Symbol pair
 (`checkmark.square.fill` / `square`) — SwiftUI has no native checkbox primitive. On Android, renders as a Material3
 `Checkbox`.
diff --git a/resources/views/docs/mobile/4/edge-components/divider.md b/resources/views/docs/mobile/4/edge-components/divider.md
index bbe359f4a..9e0f7d0a5 100644
--- a/resources/views/docs/mobile/4/edge-components/divider.md
+++ b/resources/views/docs/mobile/4/edge-components/divider.md
@@ -14,8 +14,7 @@ the platform separator color (`UIColor.separator` on iOS, Material `outlineVaria
 ```
 @endverbatim
 
-`<native:horizontal-divider />` is an equivalent divider component exposed for use inside [side navigation](side-nav). It
-emits its own `horizontal_divider` element but renders the same visual rule as `<native:divider />`.
+`<native:divider />` also works as a separator between items inside [side navigation](side-nav).
 
 <aside>
 
diff --git a/resources/views/docs/mobile/4/edge-components/gesture-area.md b/resources/views/docs/mobile/4/edge-components/gesture-area.md
index 63da331ed..09fe07526 100644
--- a/resources/views/docs/mobile/4/edge-components/gesture-area.md
+++ b/resources/views/docs/mobile/4/edge-components/gesture-area.md
@@ -5,6 +5,14 @@ order: 225
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-gesture-area-ios.png"
+    android="edge-gesture-area-android.png"
+    source="resources/views/native/animate.blade.php"
+    alt="Gesture area"
+    edge="both"
+/>
+
 Captures a vertical pan/drag gesture over its content and writes the translation to a bound
 [shared value](../digging-deeper/gestures), so the drag can drive animation on the UI thread with no PHP round-trip.
 Children render normally — gesture detection wraps the whole content frame.
diff --git a/resources/views/docs/mobile/4/edge-components/list.md b/resources/views/docs/mobile/4/edge-components/list.md
index 87bbabd1c..6bd7cc818 100644
--- a/resources/views/docs/mobile/4/edge-components/list.md
+++ b/resources/views/docs/mobile/4/edge-components/list.md
@@ -5,6 +5,14 @@ order: 270
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-list-ios.png"
+    android="edge-list-android.png"
+    source="resources/views/native/mail-demo.blade.php"
+    alt="List"
+    edge="both"
+/>
+
 A virtualized list container. On iOS, renders as a SwiftUI `List` with native pull-to-refresh and trailing
 swipe-to-delete. On Android, renders as a `LazyColumn` / `LazyRow`.
 
diff --git a/resources/views/docs/mobile/4/edge-components/menus.md b/resources/views/docs/mobile/4/edge-components/menus.md
index 86df571fd..be53e16c1 100644
--- a/resources/views/docs/mobile/4/edge-components/menus.md
+++ b/resources/views/docs/mobile/4/edge-components/menus.md
@@ -5,6 +5,14 @@ order: 275
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-menus-ios.png"
+    android="edge-menus-android.png"
+    source="resources/views/native/explore/menus.blade.php"
+    alt="Menu"
+    edge="both"
+/>
+
 A menu is a tap-to-open dropdown (SwiftUI `Menu` / Compose `DropdownMenu`) attached to a component. It isn't a
 standalone element — you build a list of actions and attach it with an attribute:
 
diff --git a/resources/views/docs/mobile/4/edge-components/modal.md b/resources/views/docs/mobile/4/edge-components/modal.md
index f547d7e2d..540d08a3b 100644
--- a/resources/views/docs/mobile/4/edge-components/modal.md
+++ b/resources/views/docs/mobile/4/edge-components/modal.md
@@ -5,6 +5,14 @@ order: 280
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-modal-ios.png"
+    android="edge-modal-android.png"
+    source="resources/views/native/explore/sheets.blade.php"
+    alt="Modal"
+    edge="both"
+/>
+
 A full-screen modal overlay. Visibility is driven by the `visible` prop. Use a [bottom sheet](bottom-sheet) for
 contextual actions; reach for `<native:modal>` when you want the entire screen covered (e.g. an onboarding flow,
 image preview, or detail view).
diff --git a/resources/views/docs/mobile/4/edge-components/radio-group.md b/resources/views/docs/mobile/4/edge-components/radio-group.md
index b92320304..0bf4dd8ab 100644
--- a/resources/views/docs/mobile/4/edge-components/radio-group.md
+++ b/resources/views/docs/mobile/4/edge-components/radio-group.md
@@ -5,6 +5,14 @@ order: 310
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-radio-group-ios.png"
+    android="edge-radio-group-android.png"
+    source="resources/views/native/explore/forms.blade.php"
+    alt="Radio group"
+    edge="both"
+/>
+
 A single-choice container holding `<native:radio>` children. The group owns the selection; each child declares its
 own `value` and label.
 
diff --git a/resources/views/docs/mobile/4/edge-components/refreshable.md b/resources/views/docs/mobile/4/edge-components/refreshable.md
index f78ee07a0..e21ad05c8 100644
--- a/resources/views/docs/mobile/4/edge-components/refreshable.md
+++ b/resources/views/docs/mobile/4/edge-components/refreshable.md
@@ -5,6 +5,14 @@ order: 315
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-refreshable-ios.png"
+    android="edge-refreshable-android.png"
+    source="resources/views/native/refreshable-demo.blade.php"
+    alt="Refreshable"
+    edge="both"
+/>
+
 A standalone scrolling container with native pull-to-refresh. Wrap any content in it, point `@refresh` at a
 component method, and the platform handles the gesture, spinner, and physics for you. On iOS it uses SwiftUI
 `ScrollView { ... }.refreshable { }`; on Android, Compose `PullToRefreshBox` wrapping a `LazyColumn`. Both show
diff --git a/resources/views/docs/mobile/4/edge-components/select.md b/resources/views/docs/mobile/4/edge-components/select.md
index ae31ec2bf..409f7b778 100644
--- a/resources/views/docs/mobile/4/edge-components/select.md
+++ b/resources/views/docs/mobile/4/edge-components/select.md
@@ -5,6 +5,14 @@ order: 350
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-select-ios.png"
+    android="edge-select-android.png"
+    source="resources/views/native/explore/forms.blade.php"
+    alt="Select"
+    edge="both"
+/>
+
 A single-choice dropdown picker over a flat list of strings. On iOS, renders as a SwiftUI `Menu` (popover); on
 Android, as an M3 `ExposedDropdownMenuBox` with an outlined trigger.
 
diff --git a/resources/views/docs/mobile/4/edge-components/side-nav.md b/resources/views/docs/mobile/4/edge-components/side-nav.md
index a1a77e88c..25dbbd078 100644
--- a/resources/views/docs/mobile/4/edge-components/side-nav.md
+++ b/resources/views/docs/mobile/4/edge-components/side-nav.md
@@ -3,89 +3,87 @@ title: Side Navigation
 order: 370
 ---
 
-> [!IMPORTANT]
-> **Use the [Drawer layout](../the-basics/layouts#drawer-navigation).** Unlike the other inline chrome elements
-> ([`top-bar`](top-bar), [`bottom-nav`](bottom-nav), [`fab`](fab)), an inline `<native:side-nav>` currently has
-> **no built-in drawer host**: the element compiles and is hoisted onto the chrome root, but nothing consumes it
-> yet, so it renders nothing on either platform. Provide drawers with the `Drawer` builder in a `NativeLayout` —
-> its contents are any Blade view. The element reference below is kept for when the inline drawer host lands.
-
 ## Overview
 
-<div class="images-two-up not-prose">
-
-![](/img/docs/edge-side-nav-ios.png)
-
-![](/img/docs/edge-side-nav-android.png)
-
-</div>
+<x-docs.edge-preview
+    ios="edge-side-nav-ios.png"
+    android="edge-side-nav-android.png"
+    source="resources/views/native/edge-components/side-nav-drawer.blade.php"
+    alt="Side navigation drawer"
+    edge="both"
+    :sidebar-width-ios="85"
+    :sidebar-width-android="87"
+/>
+
+A slide-out navigation drawer with support for groups, headers, and dividers. Side navigation is hosted by the
+[`Drawer` layout](../the-basics/layouts#drawer-navigation) — its content is a plain Blade view, so you build it from
+the components below rather than a self-contained `<native:side-nav>` element:
+
+```php
+use Nativephp\NativeUi\Builders\Drawer;
+use Nativephp\NativeUi\Concerns\HasLayoutDrawer;
+
+class AppLayout extends NativeLayout
+{
+    use HasLayoutDrawer;
+
+    public function drawer(NativeComponent $screen): ?Drawer
+    {
+        return Drawer::make(view('native.sidebar'));
+    }
+}
+```
 
-A slide-out navigation drawer with support for groups, headers, and dividers.
+`resources/views/native/sidebar.blade.php`:
 
 @verbatim
 ```blade static
-<native:side-nav gestures-enabled="true">
-    <native:side-nav-header
-        title="My App"
-        subtitle="user@example.com"
+<native:side-nav-header
+    title="My App"
+    subtitle="user@example.com"
+    icon="person"
+/>
+
+<native:side-nav-item
+    id="home"
+    label="Home"
+    icon="home"
+    url="/home"
+    :active="true"
+/>
+
+<native:side-nav-group heading="Account" :expanded="false">
+    <native:side-nav-item
+        id="profile"
+        label="Profile"
         icon="person"
+        url="/profile"
     />
-
     <native:side-nav-item
-        id="home"
-        label="Home"
-        icon="home"
-        url="/home"
-        :active="true"
+        id="settings"
+        label="Settings"
+        icon="settings"
+        url="/settings"
     />
+</native:side-nav-group>
 
-    <native:side-nav-group heading="Account" :expanded="false">
-        <native:side-nav-item
-            id="profile"
-            label="Profile"
-            icon="person"
-            url="/profile"
-        />
-        <native:side-nav-item
-            id="settings"
-            label="Settings"
-            icon="settings"
-            url="/settings"
-        />
-    </native:side-nav-group>
-
-    <native:horizontal-divider />
+<native:divider />
 
-    <native:side-nav-item
-        id="help"
-        label="Help"
-        icon="help"
-        url="https://help.example.com"
-        open-in-browser="true"
-    />
-</native:side-nav>
+<native:side-nav-item
+    id="help"
+    label="Help"
+    icon="help"
+    url="https://help.example.com"
+    open-in-browser="true"
+/>
 ```
 @endverbatim
 
-## Props
-
-- `gestures-enabled` - Swipe to open (default: `false`) [Android]
-- `label-visibility` - `labeled` (default), `selected`, or `unlabeled` (optional)
-- `dark` - Force dark mode (optional, boolean)
-
-<aside>
-
-On iOS, gesture support is always enabled for the side nav.
-
-</aside>
+See [Drawer navigation](../the-basics/layouts#drawer-navigation) for the `Drawer` builder itself — width, modal vs.
+reveal presentation, per-screen overrides, and the built-in ☰ hamburger/edge-swipe/auto-close behavior.
 
 ## Children
 
-> [!IMPORTANT]
-> In the [Layout model](../the-basics/layouts#drawer-navigation) a drawer's contents are any Blade view — build
-> the header, items, and groups below with standard EDGE components inside a `Drawer`, rather than the
-> `<native:side-nav-*>` elements.
-
 ### `<native:side-nav-header>`
 
 - `title` - Title text (optional)
@@ -119,6 +117,6 @@ force the browser even for a same-domain `url`.
 - `expanded` - Initially expanded (optional, default: `false`)
 - `icon` - Material icon (optional)
 
-### `<native:horizontal-divider>`
+### `<native:divider>`
 
-Add visual separators between navigation items. This item has no properties.
+A visual separator between navigation items. See [Divider](divider) for its full reference.
diff --git a/resources/views/docs/mobile/4/edge-components/slider.md b/resources/views/docs/mobile/4/edge-components/slider.md
index 9de495d27..1eeee965d 100644
--- a/resources/views/docs/mobile/4/edge-components/slider.md
+++ b/resources/views/docs/mobile/4/edge-components/slider.md
@@ -5,6 +5,14 @@ order: 380
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-slider-ios.png"
+    android="edge-slider-android.png"
+    source="resources/views/native/explore/forms.blade.php"
+    alt="Slider"
+    edge="both"
+/>
+
 A continuous (or stepped) value selector. The active track and thumb use `theme.primary` — there are no
 per-instance color overrides.
 
diff --git a/resources/views/docs/mobile/4/edge-components/tab-row.md b/resources/views/docs/mobile/4/edge-components/tab-row.md
index bece3222b..71f5bb874 100644
--- a/resources/views/docs/mobile/4/edge-components/tab-row.md
+++ b/resources/views/docs/mobile/4/edge-components/tab-row.md
@@ -5,6 +5,14 @@ order: 410
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-tab-row-ios.png"
+    android="edge-tab-row-android.png"
+    source="resources/views/native/twitter-profile.blade.php"
+    alt="Tab row"
+    edge="both"
+/>
+
 A horizontal tab strip with an underline indicator on the selected tab. Scrollable when tabs overflow. The row
 owns the selected-index state.
 
diff --git a/resources/views/docs/mobile/4/edge-components/text.md b/resources/views/docs/mobile/4/edge-components/text.md
index 1211bc0b7..6cddb3006 100644
--- a/resources/views/docs/mobile/4/edge-components/text.md
+++ b/resources/views/docs/mobile/4/edge-components/text.md
@@ -5,6 +5,14 @@ order: 420
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-text-ios.png"
+    android="edge-text-android.png"
+    source="resources/views/native/explore/typography.blade.php"
+    alt="Text"
+    edge="both"
+/>
+
 Displays text content using platform-native typography. Text content goes between the opening and closing tags.
 
 @verbatim
diff --git a/resources/views/docs/mobile/4/edge-components/toggle.md b/resources/views/docs/mobile/4/edge-components/toggle.md
index 76a226477..088da62f6 100644
--- a/resources/views/docs/mobile/4/edge-components/toggle.md
+++ b/resources/views/docs/mobile/4/edge-components/toggle.md
@@ -5,6 +5,14 @@ order: 440
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-toggle-ios.png"
+    android="edge-toggle-android.png"
+    source="resources/views/native/explore/forms.blade.php"
+    alt="Toggle"
+    edge="both"
+/>
+
 A native on/off switch. Renders as a SwiftUI `Toggle` on iOS and a Material3 `Switch` on Android.
 
 Per Material 3, the active track / thumb colors come from `theme.primary` / `theme.onPrimary`. There are no per-instance
diff --git a/resources/views/docs/mobile/4/edge-components/top-bar.md b/resources/views/docs/mobile/4/edge-components/top-bar.md
index f798080cf..fc88fe493 100644
--- a/resources/views/docs/mobile/4/edge-components/top-bar.md
+++ b/resources/views/docs/mobile/4/edge-components/top-bar.md
@@ -4,13 +4,14 @@ order: 450
 ---
 
 ## Overview
-<div class="images-two-up not-prose">
 
-![](/img/docs/edge-top-bar-ios.png)
-
-![](/img/docs/edge-top-bar-android.png)
-
-</div>
+<x-docs.edge-preview
+    ios="edge-top-bar-ios.png"
+    android="edge-top-bar-android.png"
+    source="resources/views/native/edge-components/top-bar.blade.php"
+    alt="Top bar"
+    edge="top"
+/>
 
 A top bar with title, subtitle, and action buttons. Placing `<native:top-bar>` at the root of a screen's Blade is a
 first-class way to give that screen its own bar — the element **hoists onto the real native chrome root** (a
diff --git a/resources/views/docs/mobile/4/edge-components/virtual-list.md b/resources/views/docs/mobile/4/edge-components/virtual-list.md
index 7d8a6bdc6..982732754 100644
--- a/resources/views/docs/mobile/4/edge-components/virtual-list.md
+++ b/resources/views/docs/mobile/4/edge-components/virtual-list.md
@@ -5,6 +5,14 @@ order: 455
 
 ## Overview
 
+<x-docs.edge-preview
+    ios="edge-virtual-list-ios.png"
+    android="edge-virtual-list-android.png"
+    source="resources/views/native/explore-icons.blade.php"
+    alt="Virtual list"
+    edge="both"
+/>
+
 Renders only the visible slice of a large collection. Where [`<native:list>`](list) builds every row, a virtual
 list emits just the rows inside the current window — so a 10,000-item list paints instantly and stays smooth,
 because PHP only ever builds ~80 rows at a time. The native side fires a window-change callback as the user
diff --git a/resources/views/docs/mobile/4/edge-components/web-view.md b/resources/views/docs/mobile/4/edge-components/web-view.md
index 79b78d0dd..c5c1dcf3c 100644
--- a/resources/views/docs/mobile/4/edge-components/web-view.md
+++ b/resources/views/docs/mobile/4/edge-components/web-view.md
@@ -3,6 +3,14 @@ title: Web View
 order: 460
 ---
 
+<x-docs.edge-preview
+    ios="edge-web-view-ios.png"
+    android="edge-web-view-android.png"
+    source="resources/views/native/webview-demo.blade.php"
+    alt="Web view"
+    edge="both"
+/>
+
 With EDGE, native UI is the primary way to build your app — the web view is just one more component you can reach for,
 not the foundation everything sits on. You're free to compose entire screens from native EDGE components and never
 render a web view at all.
diff --git a/tests/Feature/Console/CaptureDocsScreenshotsCommandTest.php b/tests/Feature/Console/CaptureDocsScreenshotsCommandTest.php
new file mode 100644
index 000000000..0304db92a
--- /dev/null
+++ b/tests/Feature/Console/CaptureDocsScreenshotsCommandTest.php
@@ -0,0 +1,441 @@
+<?php
+
+namespace Tests\Feature\Console;
+
+use App\Support\DocsScreenshotManifest;
+use Illuminate\Support\Facades\File;
+use Illuminate\Support\Facades\Process;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class CaptureDocsScreenshotsCommandTest extends TestCase
+{
+    private string $superNativePath;
+
+    private string $stagingPath;
+
+    private string $publishPath;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->superNativePath = sys_get_temp_dir().'/super-native-fake-'.uniqid();
+        File::ensureDirectoryExists($this->superNativePath.'/routes');
+        File::put($this->superNativePath.'/artisan', '');
+        File::put($this->superNativePath.'/routes/mobile.php', '');
+
+        $this->stagingPath = sys_get_temp_dir().'/docs-screenshots-staging-'.uniqid();
+        $this->publishPath = sys_get_temp_dir().'/docs-screenshots-publish-'.uniqid();
+
+        config([
+            'docs.screenshots.staging_path' => $this->stagingPath,
+            'docs.screenshots.publish_path' => $this->publishPath,
+        ]);
+    }
+
+    protected function tearDown(): void
+    {
+        File::deleteDirectory($this->superNativePath);
+        File::deleteDirectory($this->stagingPath);
+        File::deleteDirectory($this->publishPath);
+
+        parent::tearDown();
+    }
+
+    #[Test]
+    public function it_fails_without_a_super_native_path_before_running_any_process(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots')->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_fails_when_the_path_does_not_look_like_a_super_native_checkout(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => sys_get_temp_dir(),
+        ])->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_fails_for_an_invalid_platform(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'blackberry',
+        ])->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_fails_for_an_unknown_only_key(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--only' => 'not-a-real-screen',
+        ])->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function the_manifest_has_both_filenames_for_every_screen_with_no_collisions(): void
+    {
+        $seen = [];
+
+        foreach (DocsScreenshotManifest::keys() as $key) {
+            $screen = DocsScreenshotManifest::get($key);
+
+            $this->assertNotSame('', $screen['ios']);
+            $this->assertNotSame('', $screen['android']);
+
+            foreach ([$screen['ios'], $screen['android']] as $filename) {
+                $this->assertArrayNotHasKey($filename, $seen, "Filename [{$filename}] is used by more than one screen.");
+                $seen[$filename] = $key;
+            }
+        }
+    }
+
+    #[Test]
+    public function it_captures_a_single_screen_to_staging_without_publishing(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--full' => true,
+        ])->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-top-bar-ios.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:run', 'ios', '--build=debug', '--start-url=/edge-components/top-bar', '--no-tty',
+        ]);
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'ios', '--output='.$outputPath,
+        ]);
+
+        $this->assertFileDoesNotExist($this->publishPath.'/edge-top-bar-ios.png');
+    }
+
+    #[Test]
+    public function it_passes_the_udid_through_to_both_commands(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'android',
+            '--only' => 'bottom-nav',
+            '--udid' => 'emulator-5554',
+            '--settle-ms' => 0,
+            '--full' => true,
+        ])->assertSuccessful();
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:run', 'android', 'emulator-5554', '--build=debug', '--start-url=/edge-components/bottom-nav', '--no-tty',
+        ]);
+    }
+
+    #[Test]
+    public function it_fails_the_whole_run_when_one_capture_fails(): void
+    {
+        Process::fake([
+            '*native:run*' => Process::result(exitCode: 1),
+        ]);
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+        ])->assertFailed();
+    }
+
+    #[Test]
+    public function it_publishes_staged_screenshots_when_requested(): void
+    {
+        Process::fake();
+
+        File::ensureDirectoryExists($this->stagingPath);
+        File::put($this->stagingPath.'/edge-top-bar-ios.png', 'fake-png-bytes');
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--full' => true,
+            '--publish' => true,
+        ])->assertSuccessful();
+
+        $this->assertFileExists($this->stagingPath.'/edge-top-bar-ios.png');
+        $this->assertFileExists($this->publishPath.'/edge-top-bar-ios.png');
+        $this->assertSame('fake-png-bytes', File::get($this->publishPath.'/edge-top-bar-ios.png'));
+    }
+
+    #[Test]
+    public function it_asks_to_manually_open_the_drawer_for_a_drawer_screen(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'side-nav',
+            '--settle-ms' => 0,
+            '--full' => true,
+        ])
+            ->expectsQuestion(
+                'Manually open the side drawer for "side-nav" in the ios simulator/emulator now, then press Enter to continue',
+                ''
+            )
+            ->assertSuccessful();
+    }
+
+    #[Test]
+    public function it_skips_a_drawer_screen_and_fails_when_run_non_interactively(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'side-nav',
+            '--settle-ms' => 0,
+            '--no-interaction' => true,
+        ])->assertFailed();
+
+        Process::assertNotRan(fn ($process): bool => ($process->command[2] ?? '') === 'native:screenshot');
+    }
+
+    #[Test]
+    public function it_clamps_a_negative_settle_ms_instead_of_crashing(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => -500,
+            '--full' => true,
+        ])->assertSuccessful();
+    }
+
+    #[Test]
+    public function it_fails_to_publish_a_screen_never_staged(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--full' => true,
+            '--publish' => true,
+        ])->assertFailed();
+    }
+
+    #[Test]
+    public function it_fails_cleanly_instead_of_crashing_when_a_capture_step_times_out(): void
+    {
+        // No Process::fake() here — this exercises a real subprocess that
+        // outlives the configured timeout, to prove the timeout is caught
+        // rather than left to crash the command as an uncaught exception.
+        File::put($this->superNativePath.'/artisan', "<?php\nsleep(5);\n");
+
+        config(['docs.screenshots.process_timeout' => 1]);
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+        ])->assertFailed();
+    }
+
+    #[Test]
+    public function it_dry_runs_without_running_any_process(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar,side-nav',
+            '--dry-run' => true,
+        ])->assertSuccessful();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_fails_for_an_invalid_crop_percent(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--crop-percent' => '1.5',
+        ])->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_passes_the_screen_crop_direction_and_percent_to_native_screenshot(): void
+    {
+        // Cropping itself is native:screenshot's job (mobile-air) — this
+        // only verifies the right flags reach it for a top-bar screen.
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--crop-percent' => '0.3',
+        ])->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-top-bar-ios.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'ios',
+            '--output='.$outputPath,
+            '--crop=top',
+            '--crop-percent=0.3',
+            '--crop-offset=0.05',
+        ]);
+    }
+
+    #[Test]
+    public function it_fails_for_a_crop_offset_that_leaves_no_room_for_crop_percent(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--crop-percent' => '0.5',
+            '--crop-offset' => '0.5',
+        ])->assertFailed();
+
+        Process::assertNothingRan();
+    }
+
+    #[Test]
+    public function it_passes_a_custom_crop_offset_to_native_screenshot(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--crop-percent' => '0.3',
+            '--crop-offset' => '0.1',
+        ])->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-top-bar-ios.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'ios',
+            '--output='.$outputPath,
+            '--crop=top',
+            '--crop-percent=0.3',
+            '--crop-offset=0.1',
+        ]);
+    }
+
+    #[Test]
+    public function it_passes_the_bottom_crop_direction_for_a_bottom_nav_screen(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'android',
+            '--only' => 'bottom-nav',
+            '--settle-ms' => 0,
+        ])->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-bottom-nav-android.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'android',
+            '--output='.$outputPath,
+            '--crop=bottom',
+            '--crop-percent=0.15',
+            '--crop-offset=0.05',
+        ]);
+    }
+
+    #[Test]
+    public function it_passes_no_crop_flags_for_a_side_nav_screen(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'side-nav',
+            '--settle-ms' => 0,
+        ])
+            ->expectsQuestion(
+                'Manually open the side drawer for "side-nav" in the ios simulator/emulator now, then press Enter to continue',
+                ''
+            )
+            ->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-side-nav-ios.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'ios',
+            '--output='.$outputPath,
+        ]);
+    }
+
+    #[Test]
+    public function it_passes_no_crop_flags_when_full_is_requested(): void
+    {
+        Process::fake();
+
+        $this->artisan('docs:capture-screenshots', [
+            '--super-native-path' => $this->superNativePath,
+            '--platform' => 'ios',
+            '--only' => 'top-bar',
+            '--settle-ms' => 0,
+            '--full' => true,
+        ])->assertSuccessful();
+
+        $outputPath = $this->stagingPath.'/edge-top-bar-ios.png';
+
+        Process::assertRan(fn ($process): bool => $process->command === [
+            'php', 'artisan', 'native:screenshot', 'ios',
+            '--output='.$outputPath,
+        ]);
+    }
+}
diff --git a/tests/Unit/Services/DocsScreenshots/ScreenshotPublisherTest.php b/tests/Unit/Services/DocsScreenshots/ScreenshotPublisherTest.php
new file mode 100644
index 000000000..57db4306e
--- /dev/null
+++ b/tests/Unit/Services/DocsScreenshots/ScreenshotPublisherTest.php
@@ -0,0 +1,71 @@
+<?php
+
+namespace Tests\Unit\Services\DocsScreenshots;
+
+use App\Services\DocsScreenshots\ScreenshotPublisher;
+use Illuminate\Support\Facades\File;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class ScreenshotPublisherTest extends TestCase
+{
+    private string $stagingPath;
+
+    private string $publishPath;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->stagingPath = sys_get_temp_dir().'/screenshot-publisher-staging-'.uniqid();
+        $this->publishPath = sys_get_temp_dir().'/screenshot-publisher-publish-'.uniqid();
+    }
+
+    protected function tearDown(): void
+    {
+        File::deleteDirectory($this->stagingPath);
+        File::deleteDirectory($this->publishPath);
+
+        parent::tearDown();
+    }
+
+    #[Test]
+    public function it_copies_every_staged_file_to_the_publish_path(): void
+    {
+        File::ensureDirectoryExists($this->stagingPath);
+        File::put($this->stagingPath.'/a.png', 'a-bytes');
+        File::put($this->stagingPath.'/b.png', 'b-bytes');
+
+        $failures = (new ScreenshotPublisher)->publish($this->stagingPath, $this->publishPath, ['a.png', 'b.png']);
+
+        $this->assertSame([], $failures);
+        $this->assertSame('a-bytes', File::get($this->publishPath.'/a.png'));
+        $this->assertSame('b-bytes', File::get($this->publishPath.'/b.png'));
+    }
+
+    #[Test]
+    public function it_reports_a_filename_that_was_never_staged(): void
+    {
+        File::ensureDirectoryExists($this->stagingPath);
+        File::put($this->stagingPath.'/a.png', 'a-bytes');
+
+        $failures = (new ScreenshotPublisher)->publish($this->stagingPath, $this->publishPath, ['a.png', 'missing.png']);
+
+        $this->assertSame(['missing.png'], $failures);
+        $this->assertFileExists($this->publishPath.'/a.png');
+        $this->assertFileDoesNotExist($this->publishPath.'/missing.png');
+    }
+
+    #[Test]
+    public function it_creates_the_publish_directory_when_missing(): void
+    {
+        File::ensureDirectoryExists($this->stagingPath);
+        File::put($this->stagingPath.'/a.png', 'a-bytes');
+
+        $this->assertDirectoryDoesNotExist($this->publishPath);
+
+        (new ScreenshotPublisher)->publish($this->stagingPath, $this->publishPath, ['a.png']);
+
+        $this->assertDirectoryExists($this->publishPath);
+    }
+}