diff --git a/app/Actions/Photo/Pipes/Standalone/PlaceGoogleMotionVideo.php b/app/Actions/Photo/Pipes/Standalone/PlaceGoogleMotionVideo.php
index efd802cf890..619abe1a25d 100644
--- a/app/Actions/Photo/Pipes/Standalone/PlaceGoogleMotionVideo.php
+++ b/app/Actions/Photo/Pipes/Standalone/PlaceGoogleMotionVideo.php
@@ -10,6 +10,7 @@
 
 use App\DTO\PhotoCreate\StandaloneDTO;
 use App\Image\Files\FlysystemFile;
+use App\Image\Handlers\GoogleMotionPictureHandler;
 
 class PlaceGoogleMotionVideo extends AbstractStandalonePipe
 {
@@ -19,11 +20,7 @@ protected function execute(StandaloneDTO $state, \Closure $next): StandaloneDTO
 		// we must move the preliminary extracted video file next to the
 		// final target file
 		if ($state->tmp_video_file !== null) {
-			$video_target_path =
-				pathinfo($state->target_file->getRelativePath(), PATHINFO_DIRNAME) .
-				'/' .
-				pathinfo($state->target_file->getRelativePath(), PATHINFO_FILENAME) .
-				$state->tmp_video_file->getExtension();
+			$video_target_path = GoogleMotionPictureHandler::videoPathNextTo($state->target_file->getRelativePath());
 			$video_target_file = new FlysystemFile($state->target_file->getDisk(), $video_target_path);
 			$video_target_file->write($state->tmp_video_file->read());
 			$state->photo->live_photo_short_path = $video_target_file->getRelativePath();
diff --git a/app/Console/Commands/ImageProcessing/ExtractMotionPhotos.php b/app/Console/Commands/ImageProcessing/ExtractMotionPhotos.php
new file mode 100644
index 00000000000..65e32aa093d
--- /dev/null
+++ b/app/Console/Commands/ImageProcessing/ExtractMotionPhotos.php
@@ -0,0 +1,223 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Console\Commands\ImageProcessing;
+
+use App\Constants\PhotoAlbum as PA;
+use App\Enum\SizeVariantType;
+use App\Events\PhotoSaved;
+use App\Exceptions\MediaFileOperationException;
+use App\Image\Files\FlysystemFile;
+use App\Image\Files\NativeLocalFile;
+use App\Image\Files\TemporaryLocalFile;
+use App\Image\Handlers\GoogleMotionPictureHandler;
+use App\Models\Album;
+use App\Models\Photo;
+use App\Repositories\ConfigManager;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use PHPExif\MotionPhoto\MotionPhotoLocator;
+use Safe\Exceptions\InfoException;
+use function Safe\set_time_limit;
+
+/**
+ * Extracts the video of Google Motion Photos that were imported as plain
+ * stills, before Feature 100 recognised the Motion Photo 1.0 format.
+ *
+ * The original size variant keeps the whole camera file, video included, so
+ * the video is cut from it and stored next to it, as the upload pipeline
+ * does (FR-100-04).
+ */
+class ExtractMotionPhotos extends Command
+{
+	private const MIME_TYPE_JPEG = 'image/jpeg';
+
+	/**
+	 * The name and signature of the console command.
+	 *
+	 * @var string
+	 */
+	protected $signature = 'lychee:extract_motion_photos' .
+		' {limit=100 : number of photos to check}' .
+		' {tm=600 : timeout time requirement}' .
+		' {--after= : continue after this photo id (printed by the previous run)}' .
+		' {--album= : only check the photos of this album}' .
+		' {--dry-run : list the motion photos without extracting their video}' .
+		' {--reencode : extract again the video of motion photos that already have one, transcoding HEVC clips to H.264}';
+
+	/**
+	 * The console command description.
+	 *
+	 * @var string
+	 */
+	protected $description = 'Extract the video of Google Motion Photos imported as plain photos';
+
+	/**
+	 * Execute the console command.
+	 */
+	public function handle(ConfigManager $config_manager): int
+	{
+		$limit = (int) $this->argument('limit');
+		$timeout = (int) $this->argument('tm');
+		$after = $this->option('after');
+		$album_id = $this->option('album');
+		$dry_run = $this->option('dry-run') === true;
+		$reencode = $this->option('reencode') === true;
+
+		try {
+			set_time_limit($timeout);
+		} catch (InfoException) {
+			// Silently do nothing, if `set_time_limit` is denied.
+		}
+
+		if (!$dry_run && !$config_manager->hasFFmpeg()) {
+			$this->error('FFmpeg is required to extract motion photo videos (or use --dry-run).');
+
+			return 1;
+		}
+		if (is_string($album_id) && Album::query()->find($album_id) === null) {
+			$this->error('Album ' . $album_id . ' not found.');
+
+			return 1;
+		}
+
+		$photos = Photo::query()
+			->with(['size_variants' => fn ($r) => $r->where('type', '=', SizeVariantType::ORIGINAL)])
+			->where('type', '=', self::MIME_TYPE_JPEG)
+			// Re-encoding only concerns Google motion photos: an Apple pair has a content id.
+			->when(
+				$reencode,
+				fn ($q) => $q->whereNotNull('live_photo_short_path')->whereNull('live_photo_content_id'),
+				fn ($q) => $q->whereNull('live_photo_short_path'),
+			)
+			->when(is_string($album_id), fn ($q) => $q->whereIn('id', DB::table(PA::PHOTO_ALBUM)->select(PA::PHOTO_ID)->where(PA::ALBUM_ID, '=', $album_id)))
+			// Cursor, not offset: extracted photos leave this set, the others stay in it.
+			->when(is_string($after) && $after !== '', fn ($q) => $q->where('id', '>', $after))
+			->orderBy('id')
+			->limit($limit)
+			->get();
+
+		if ($photos->isEmpty()) {
+			$this->line('No photos require motion photo extraction.');
+
+			return 0;
+		}
+
+		$found = [];
+		$failed = 0;
+		foreach ($photos as $photo) {
+			$is_motion_photo = $this->process($photo, $dry_run);
+			$failed += $is_motion_photo === null ? 1 : 0;
+			if ($is_motion_photo === true) {
+				$found[] = $photo->id;
+				$this->line('Motion photo: ' . $photo->id . ' (' . $photo->title . ')');
+			}
+		}
+
+		PhotoSaved::dispatchIf(!$dry_run && $found !== [], $found);
+
+		$outcome = match (true) {
+			$dry_run => 'found (dry run)',
+			$reencode => 're-extracted',
+			default => 'extracted',
+		};
+		$this->line(sprintf('Checked %d photos: %d motion photos %s, %d failed.', $photos->count(), count($found), $outcome, $failed));
+		if ($photos->count() === $limit) {
+			$this->line('More photos may remain: continue with --after=' . $photos->last()->id);
+			$this->retryHint($failed, $after);
+		}
+
+		return $failed === 0 ? 0 : 1;
+	}
+
+	/**
+	 * @return bool|null true for a motion photo (its video extracted unless `$dry_run`), false for a still, null if the photo could not be processed
+	 */
+	private function process(Photo $photo, bool $dry_run): ?bool
+	{
+		$local_file = null;
+		try {
+			$original = $photo->size_variants->getOriginal()->getFile();
+			if (!$original->exists()) {
+				throw new MediaFileOperationException('original file is missing');
+			}
+
+			$local_file = $this->toLocalFile($original, $photo);
+			$video_length = MotionPhotoLocator::locate($local_file->getRealPath());
+			if ($video_length > 0 && !$dry_run) {
+				$this->extract($photo, $original, $local_file, $video_length);
+			}
+
+			return $video_length > 0;
+		} catch (\Throwable $e) {
+			Log::warning(__METHOD__ . ':' . __LINE__ . ' Motion photo extraction failed for photo ' . $photo->id . ': ' . $e->getMessage());
+			$this->warn('Failed: ' . $photo->id . ' (' . $photo->title . '): ' . $e->getMessage());
+
+			return null;
+		} finally {
+			if ($local_file instanceof TemporaryLocalFile) {
+				$local_file->delete();
+			}
+		}
+	}
+
+	/**
+	 * Continuing with the printed cursor would skip the photos that failed in
+	 * this batch: tell the operator to run the batch again first.
+	 */
+	private function retryHint(int $failed, mixed $after): void
+	{
+		if ($failed === 0) {
+			return;
+		}
+
+		$same_batch = is_string($after) && $after !== '' ? 'with --after=' . $after : 'without --after';
+		$this->line(sprintf('%d photos failed in this batch and would be skipped by that cursor: run it again %s to retry them first.', $failed, $same_batch));
+	}
+
+	/**
+	 * Returns the original itself when it is hosted locally, a downloaded
+	 * temporary copy otherwise (as {@see \App\Image\SizeVariantDefaultFactory}).
+	 */
+	private function toLocalFile(FlysystemFile $original, Photo $photo): NativeLocalFile
+	{
+		if ($original->isLocalFile()) {
+			return $original->toLocalFile();
+		}
+
+		// @codeCoverageIgnoreStart
+		$local_file = new TemporaryLocalFile($original->getOriginalExtension(), $photo->title);
+		$local_file->write($original->read(), false, $photo->type);
+
+		return $local_file;
+		// @codeCoverageIgnoreEnd
+	}
+
+	private function extract(Photo $photo, FlysystemFile $original, NativeLocalFile $local_file, int $video_length): void
+	{
+		$video_file = new TemporaryLocalFile(GoogleMotionPictureHandler::FINAL_VIDEO_FILE_EXTENSION, $local_file->getBasename());
+		try {
+			$handler = new GoogleMotionPictureHandler();
+			$handler->load($local_file, $video_length);
+			$handler->saveVideoStream($video_file);
+
+			// A re-encoded clip replaces the stored one; a new clip goes next to the original.
+			$target_path = $photo->live_photo_short_path ?? GoogleMotionPictureHandler::videoPathNextTo($original->getRelativePath());
+			// Staged and moved over the target, so a failed write never truncates a clip in use.
+			$staged_file = new FlysystemFile($original->getDisk(), $target_path . '.part');
+			$staged_file->write($video_file->read());
+			$staged_file->move($target_path);
+			$photo->live_photo_short_path = $target_path;
+			$photo->save();
+		} finally {
+			$video_file->close();
+			$video_file->delete();
+		}
+	}
+}
diff --git a/app/Image/Handlers/GoogleMotionPictureHandler.php b/app/Image/Handlers/GoogleMotionPictureHandler.php
index 839d3815097..711539e9141 100644
--- a/app/Image/Handlers/GoogleMotionPictureHandler.php
+++ b/app/Image/Handlers/GoogleMotionPictureHandler.php
@@ -15,6 +15,7 @@
 use App\Exceptions\MediaFileOperationException;
 use App\Image\Files\NativeLocalFile;
 use App\Image\Files\TemporaryLocalFile;
+use App\ModelFunctions\H264MOVFormat;
 use App\ModelFunctions\MOVFormat;
 use App\Repositories\ConfigManager;
 use FFMpeg\Exception\ExecutableNotFoundException;
@@ -42,10 +43,22 @@ class GoogleMotionPictureHandler extends VideoHandler
 {
 	public const PRELIMINARY_VIDEO_FILE_EXTENSION = '.mp4';
 	public const FINAL_VIDEO_FILE_EXTENSION = '.mov';
+	private const CODEC_H264 = 'h264';
 
 	/** @var TemporaryLocalFile a working copy of the video stream */
 	protected TemporaryLocalFile $working_copy;
 
+	/**
+	 * Path at which the video of a motion photo is stored: next to the
+	 * original, under the same file name, with the final video extension.
+	 *
+	 * @param string $original_path path of the original size variant, relative to its disk
+	 */
+	public static function videoPathNextTo(string $original_path): string
+	{
+		return pathinfo($original_path, PATHINFO_DIRNAME) . '/' . pathinfo($original_path, PATHINFO_FILENAME) . self::FINAL_VIDEO_FILE_EXTENSION;
+	}
+
 	/**
 	 * @throws MediaFileOperationException
 	 */
@@ -106,6 +119,10 @@ public function load(NativeLocalFile $file, int $video_length = 0): void
 	/**
 	 * Save the video stream to the provided file.
 	 *
+	 * An H.264 stream is copied as is; any other codec (HEVC on current
+	 * Pixel phones) is transcoded to H.264 so that every browser can play it
+	 * (Feature 100, Q-100-09).
+	 *
 	 * @param NativeLocalFile $file the file to write into
 	 *
 	 * @throws MediaFileOperationException
@@ -113,9 +130,9 @@ public function load(NativeLocalFile $file, int $video_length = 0): void
 	public function saveVideoStream(NativeLocalFile $file): void
 	{
 		try {
-			$format = new MOVFormat();
+			$format = $this->isH264() ? new MOVFormat() : new H264MOVFormat();
 			// Add additional parameter to extract the first video stream
-			$format->setAdditionalParameters(['-map', '0:0']);
+			$format->setAdditionalParameters([...($format->getAdditionalParameters() ?? []), '-map', '0:0']);
 			$this->video->save($format, $file->getRealPath());
 			// @codeCoverageIgnoreStart
 		} catch (RuntimeException $e) {
@@ -125,4 +142,12 @@ public function saveVideoStream(NativeLocalFile $file): void
 		}
 		// @codeCoverageIgnoreEnd
 	}
+
+	/**
+	 * Whether the first video stream is already H.264.
+	 */
+	private function isH264(): bool
+	{
+		return $this->video->getStreams()->videos()->first()?->get('codec_name') === self::CODEC_H264;
+	}
 }
\ No newline at end of file
diff --git a/app/ModelFunctions/H264MOVFormat.php b/app/ModelFunctions/H264MOVFormat.php
new file mode 100644
index 00000000000..f288694d02a
--- /dev/null
+++ b/app/ModelFunctions/H264MOVFormat.php
@@ -0,0 +1,64 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\ModelFunctions;
+
+use App\Exceptions\Internal\LycheeAssertionError;
+use FFMpeg\Exception\InvalidArgumentException;
+
+/**
+ * Format class for FFMpeg to transcode a video stream to H.264 in a
+ * Quicktime (MOV) container.
+ *
+ * Current Pixel phones record the clip of a Google Motion Photo in HEVC,
+ * which several browsers cannot decode (Feature 100, Q-100-09). H.264 plays
+ * everywhere. Quality is set by a constant rate factor rather than a
+ * bitrate, so a single pass is enough; FFmpeg's default auto-rotation applies
+ * the clip's rotation to the frames.
+ */
+class H264MOVFormat extends MOVFormat
+{
+	public const FFMPEG_VIDEO_CODEC_ID = 'libx264';
+
+	/**
+	 * No bitrate: quality comes from `-crf` (see {@see self::ENCODER_PARAMETERS}).
+	 */
+	protected $kiloBitrate = 0;
+
+	/** @var string[] */
+	private const ENCODER_PARAMETERS = [
+		'-crf', '23',
+		'-preset', 'veryfast',
+		'-pix_fmt', 'yuv420p',
+		'-movflags', '+faststart',
+	];
+
+	public function __construct()
+	{
+		parent::__construct();
+		try {
+			$this
+				->setVideoCodec(self::FFMPEG_VIDEO_CODEC_ID)
+				->setAdditionalParameters(self::ENCODER_PARAMETERS);
+			// @codeCoverageIgnoreStart
+		} catch (InvalidArgumentException $e) {
+			throw LycheeAssertionError::createFromUnexpectedException($e);
+		}
+		// @codeCoverageIgnoreEnd
+	}
+
+	/**
+	 * The parent's `copy` stays available: its constructor sets it first.
+	 *
+	 * @return string[]
+	 */
+	public function getAvailableVideoCodecs(): array
+	{
+		return [...parent::getAvailableVideoCodecs(), self::FFMPEG_VIDEO_CODEC_ID];
+	}
+}
diff --git a/composer.json b/composer.json
index f17133d6f48..2ee680c7909 100644
--- a/composer.json
+++ b/composer.json
@@ -69,7 +69,7 @@
         "league/omnipay": "^3",
         "lychee-org/lycheeverify": "^2.0.7",
         "lychee-org/nestedset": "^12.0.0",
-        "lychee-org/php-exif": "^1.4.0",
+        "lychee-org/php-exif": "^1.5.0",
         "maennchen/zipstream-php": "^2.1 || ^3.1",
         "mavinoo/laravel-batch": "^2.4",
         "moneyphp/money": "^4.7",
diff --git a/composer.lock b/composer.lock
index 5caad5a2263..aa46f49e682 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "8bdb87358acdb351e20620bd2a80d3b9",
+    "content-hash": "dfa82bfe9c25d5ec4ee7377518956ca0",
     "packages": [
         {
             "name": "apimatic/core",
@@ -4672,16 +4672,16 @@
         },
         {
             "name": "lychee-org/php-exif",
-            "version": "1.4.0",
+            "version": "1.5.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/LycheeOrg/php-exif.git",
-                "reference": "483a982fbf58551a0e9cd7932d97bb839d0bd905"
+                "reference": "05f9945e6393a697e4a64b3f4bb87fc86b183785"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/LycheeOrg/php-exif/zipball/483a982fbf58551a0e9cd7932d97bb839d0bd905",
-                "reference": "483a982fbf58551a0e9cd7932d97bb839d0bd905",
+                "url": "https://api.github.com/repos/LycheeOrg/php-exif/zipball/05f9945e6393a697e4a64b3f4bb87fc86b183785",
+                "reference": "05f9945e6393a697e4a64b3f4bb87fc86b183785",
                 "shasum": ""
             },
             "require": {
@@ -4759,11 +4759,7 @@
                 "jpeg",
                 "tiff"
             ],
-            "support": {
-                "source": "https://github.com/LycheeOrg/php-exif/tree/1.4.0",
-                "issues": "https://github.com/LycheeOrg/php-exif/issues"
-            },
-            "time": "2026-10-03T20:15:01+00:00"
+            "time": "2026-10-19T07:44:26+00:00"
         },
         {
             "name": "maennchen/zipstream-php",
diff --git a/docs/specs/1-concepts/photos.md b/docs/specs/1-concepts/photos.md
index 16f634bf39a..7b2d01925b5 100644
--- a/docs/specs/1-concepts/photos.md
+++ b/docs/specs/1-concepts/photos.md
@@ -45,9 +45,10 @@ A **Photo** is the fundamental content unit in Lychee. Each photo represents a s
   - Supported: All Rights Reserved, CC BY, CC BY-SA, CC BY-ND, CC BY-NC, CC BY-NC-SA, CC BY-NC-ND, CC0, Public Domain
 
 **Special Features:**
-- **Live Photos**: Support for Apple Live Photos (photo + video pair)
+- **Live Photos**: Support for Apple Live Photos (photo + video pair) and Google Motion Photos (video embedded in the JPEG, legacy `MicroVideoOffset` and Motion Photo 1.0 / Ultra HDR, Feature 100)
   - Stores video component path, checksum, and content ID
-  - Seamlessly integrates motion with still image
+  - Seamlessly integrates motion with still image; v8 grids badge live photos and play the motion on hover
+  - `php artisan lychee:extract_motion_photos` extracts the video of motion photos imported as plain stills
 - **Color Palette**: Extracted dominant colors for visual search and theming
 - **Tags**: Many-to-many relationship with tag entities (not comma-separated strings)
 - **Purchasable**: E-commerce integration for selling prints/downloads (webshop feature)
diff --git a/docs/specs/4-architecture/features/100-google-motion-photos/open-questions.md b/docs/specs/4-architecture/features/100-google-motion-photos/open-questions.md
new file mode 100644
index 00000000000..4332dc76ec2
--- /dev/null
+++ b/docs/specs/4-architecture/features/100-google-motion-photos/open-questions.md
@@ -0,0 +1,148 @@
+# Open Questions – Feature 100
+
+Open questions for [Feature 100](spec.md). Log every high- and medium-impact question here (table row + Question Details entry) before asking the user; see [open-questions-format.md](../../spec-guidelines/open-questions-format.md). Once answered, fold the outcome into [spec.md](spec.md) (and an ADR when architecturally significant), then mark the entry resolved.
+
+## Active Questions
+
+| Question ID | Feature | Priority | Summary | Status | Opened | Updated |
+|-------------|---------|----------|---------|--------|--------|---------|
+| ~~Q-100-01~~ | 100 – Google Motion Photos | High | How does the album grid let the viewer play the motion? (A hover-to-play + badge, B badge as play button, C hover only) | Resolved (Option A — hover-to-play on hover-capable pointers + motion badge everywhere; owner, 2026-10-17; spec FR-100-03, NFR-100-01, NFR-100-04, UI-100-01/02) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-02~~ | 100 – Google Motion Photos | High | How is the embedded video located in Motion Photo 1.0 files? (A pure-PHP XMP `Container:Directory` read + `ftyp` scan when the item is absent, B extend php-exif to map the tags, C `ftyp` scan only) | Resolved (Option A — pure-PHP `MotionPhotoLocator` called from `Extractor`; owner, 2026-10-17; spec FR-100-01, NFR-100-02, NFR-100-03; reader later moved to php-exif by Q-100-08) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-03~~ | 100 – Google Motion Photos | Medium | Does grid playback apply to Apple Live Photos too? (A all live photos, B Google only) | Resolved (Option A — every live photo; owner, 2026-10-17; spec FR-100-03) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-04~~ | 100 – Google Motion Photos | Medium | How are already-imported new-format motion photos backfilled? (A artisan command, B re-upload only) | Resolved (Option A — `lychee:extract_motion_photos`; owner, 2026-10-17; spec FR-100-04, CLI-100-01) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-05~~ | 100 – Google Motion Photos | Medium | Which frontends get grid playback? (A v8 only, B v7 and v8) | Resolved (Option A — v8 only; owner, 2026-10-17; spec FR-100-03, Non-Goals) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-06~~ | 100 – Google Motion Photos | Medium | Which test fixture covers the new format? (A synthetic fixture + one real Pixel sample from the owner, B synthetic only, C issue #1283 images) | Resolved (Option A — synthetic fixtures + one owner-supplied Pixel `.MP.jpg`; owner, 2026-10-17; spec FX-100-01 … 03) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-07~~ | 100 – Google Motion Photos | Medium | Where does a v3 grid tile get its video URL for hover playback? (A fetch tier-3 details on hover intent, B add `live_photo_urls[]` to the tier-2 resources, C hover playback only where the URL is already loaded) | Resolved (Option A — the owning view provides its details loader, called on `mouseenter`; owner, 2026-10-17; spec FR-100-03, FR-100-05, S-100-19, S-100-20) | 2026-10-17 | 2026-10-17 |
+| ~~Q-100-08~~ | 100 – Google Motion Photos | High | Where does motion photo detection live: Lychee or `lychee-org/php-exif`? (A php-exif, B keep it in Lychee) | Resolved (Option A — move it to php-exif, as maintainer ildyria asked on PR #4900; owner, 2026-10-18; ADR-100-01, spec FR-100-01) | 2026-10-18 | 2026-10-18 |
+| ~~Q-100-09~~ | 100 – Google Motion Photos | Medium | Transcode HEVC motion clips to H.264 so every browser plays them? (A Google clips at extraction, B every live photo video incl. Apple, C keep HEVC + add an H.264 fallback file, D no transcode) | Resolved (Option A — transcode Google clips at extraction, `--reencode` for stored ones; owner, 2026-10-19; spec FR-100-02, FR-100-04, S-100-21 … 23, Non-Goals) | 2026-10-19 | 2026-10-19 |
+
+## Question Details
+
+### ~~Q-100-01~~ – Grid interaction for motion photos
+
+**Context:** Today the lightbox already plays live photos through LivePhotosKit (`v8/.../PhotoBox.vue:109-133`), with its own LIVE badge. Grid thumbnails (`PhotoThumb.vue`, `PhotoThumbVirtual.vue`) carry only an unstyled `livephoto` class: no badge, no hover playback. The owner asked for "show the video when hovered over, or a play button". Touch devices have no hover, and a tap on a thumbnail opens the lightbox.
+
+- **Option A (chosen):** hover-to-play on pointer devices plus an always-visible motion badge.
+  - Pointer with hover (`matchMedia('(hover: hover)')`): after ~250 ms of hover a muted, looping `<video preload="none">` fades in over the thumbnail; it stops and unloads on leave.
+  - Every device: a small motion badge in the thumbnail badge row tells the viewer the photo moves; on touch the motion plays in the lightbox.
+  - ✅ Matches Google Photos' own behaviour; zero clicks on desktop.
+  - ✅ Badge makes motion discoverable on touch without hijacking the tap.
+  - ❌ Hover playback fetches the video on demand (1–4 MB per clip).
+- **Option B:** the badge is a play button; clicking it plays inline without opening the lightbox.
+  - ✅ Works the same on touch and pointer; no accidental downloads.
+  - ❌ Small tap target competing with selection and lightbox open.
+  - ❌ One extra click per photo on desktop.
+- **Option C:** hover-to-play only, no badge.
+  - ✅ Smallest UI change.
+  - ❌ Invisible on touch devices; nothing tells the viewer which photos move.
+
+### ~~Q-100-02~~ – Locating the embedded video
+
+**Context:** Android 11+ writes the Motion Photo 1.0 format: XMP `GCamera:MotionPhoto=1` plus a `Container:Directory` sequence of `Container:Item`s (`Item:Mime`, `Item:Semantic`, `Item:Length`, `Item:Padding`). The video is the item with `Item:Semantic="MotionPhoto"` and sits at the end of the file, so its start is `filesize − Item:Length`. Ultra HDR photos add a `GainMap` item between the primary JPEG and the video. Lychee today reads only `XMP-GCamera:MicroVideoOffset` through php-exif 1.4.0 (`Mapper/Exiftool.php:72`), which the Imagick and Native readers do not provide. Issue #1283's exiftool dump lists only the `Primary` directory item, so some files may lack the video's directory entry.
+
+- **Option A (chosen):** pure-PHP reader `App\Metadata\MotionPhotoLocator`.
+  - Reads the XMP packet from the JPEG's APP1 segments (no external tool), returns the video's byte length from the `MotionPhoto` item, or from `MicroVideoOffset` for the legacy format.
+  - When `GCamera:MotionPhoto=1` but no `MotionPhoto` item exists, scans for the MP4 `ftyp` box after the primary image's EOI marker.
+  - ✅ Works on every install (exiftool, Imagick or Native reader); no dependency change.
+  - ✅ One place handles legacy, current and Ultra HDR layouts.
+  - ❌ We maintain a small XMP/JPEG segment parser.
+- **Option B:** extend `lychee-org/php-exif` to map `XMP-GCamera:MotionPhoto` and `XMP-GContainer:DirectoryItem*`, then bump the dependency.
+  - ✅ Keeps all metadata reading in the library.
+  - ❌ Requires exiftool as the reader; Imagick/Native installs stay unsupported.
+  - ❌ Two-repository release and a dependency bump that needs owner approval.
+- **Option C:** scan for the `ftyp` box after the JPEG EOI only (the approach of ViRb3/google-camera-motion-photo-splitter).
+  - ✅ Simplest; ignores metadata entirely.
+  - ❌ Heuristic; false positives possible on any JPEG with trailing data.
+  - ❌ Does not use the declared length, so padding/gain-map layouts rely on luck.
+
+### ~~Q-100-03~~ – Apple Live Photos in the grid
+
+**Context:** Google motion videos are stored exactly like Apple Live Photo videos (`photos.live_photo_short_path`), and the frontend only knows `precomputed.is_livephoto` / `is_live_photos[]`. Apple `.mov` files are often HEVC, which Firefox and some Chromium builds cannot decode.
+
+- **Option A (chosen):** grid playback applies to every live photo (Apple and Google).
+  - ✅ No new API field or column; consistent UX.
+  - ❌ HEVC clips fail silently on browsers without HEVC; the still stays visible.
+- **Option B:** Google motion photos only.
+  - ✅ Only H.264 clips, so playback works everywhere.
+  - ❌ Needs a new `live_photo_kind` (or similar) column, migration and API field.
+
+### ~~Q-100-04~~ – Backfilling existing photos
+
+**Context:** New-format motion photos uploaded before this feature are stored as plain photos, but the original size variant keeps the full file including the video trailer, so the video can still be extracted. Feature 082 used `lychee:detect_360` for the same situation.
+
+- **Option A (chosen):** `php artisan lychee:extract_motion_photos` over JPEG photos with `live_photo_short_path IS NULL`, with `--dry-run` and an album filter; reads originals from local or S3 storage.
+  - ✅ Existing libraries gain motion without re-upload.
+  - ❌ Must read every candidate original once (I/O on large libraries).
+- **Option B:** no backfill; owners re-upload.
+  - ✅ No new command.
+  - ❌ Re-upload loses ratings, titles, album placement and tags.
+
+### ~~Q-100-05~~ – Frontend scope
+
+**Context:** Both `resources/js/v7` and `resources/js/v8` render thumbnails; Feature 077 shipped v8 only, Feature 097 shipped both.
+
+- **Option A (chosen):** v8 only (`PhotoThumb.vue`, `PhotoThumbVirtual.vue`).
+  - ✅ Half the UI work and test surface; v8 is where new work lands.
+  - ❌ v7 users get extraction (lightbox playback) but no grid playback.
+- **Option B:** v7 and v8.
+  - ✅ Parity across trees.
+  - ❌ Duplicated component and CSS work.
+
+### ~~Q-100-06~~ – Test fixture
+
+**Context:** `tests/Samples/google_motion_photo.jpg` is the legacy `MicroVideoOffset` format (checked 2026-10-17). No Motion Photo 1.0 sample exists in the repository, and fixtures must be redistributable.
+
+- **Option A (chosen):** a small synthetic fixture (existing sample JPEG + a short H.264 MP4 + a hand-written `Container:Directory` XMP) for unit and upload tests, plus one real Pixel `.MP.jpg` from the owner, downscaled, for an end-to-end test.
+  - ✅ Deterministic layout tests (including a `GainMap` item) and proof against a real camera file.
+  - ❌ Owner must supply a photo they are happy to publish.
+- **Option B:** synthetic fixture only.
+  - ✅ No owner action needed.
+  - ❌ Nothing proves the parser against real camera output.
+- **Option C:** the sample images attached to issue #1283.
+  - ✅ Real Pixel files.
+  - ❌ Licence unclear; GitHub may have stripped the video trailer.
+
+### ~~Q-100-07~~ – Video URL for grid tiles
+
+**Context:** Found while planning FR-100-03 (2026-10-17). v8 grids built from the v3 struct-of-arrays endpoints (Feature 064/065) only know `is_live_photos[i]` at tile time; `live_photo_url` arrives with the tier-3 `details` call (`adaptPhotoTile.ts` `mergePhotoDetail()`), which today runs only when a photo is selected or opened. So on hover the tile has no URL to play. Every grid store already has a deduped details loader: `AlbumState.loadPhotoDetails`, `TimelineState.loadPhotoDetailsV3`, `SearchState.loadPhotoDetailsV3`, `FlowState.loadPhotoDetailsV3`. The URL's storage disk comes from the original size variant, which the ratios query does not join (NFR-064-03 caps it at 3 fixed `size_variants` joins).
+
+- **Option A (chosen):** on `mouseenter` of a live photo tile, ask the owning store's details loader for that id (injected into `PhotoThumb` / `PhotoThumbVirtual` by the panel); play once `live_photo_url` is set and the 250 ms hover delay has passed.
+  - ✅ No API or query change; respects the Feature 064 tier split and NFR-064-03.
+  - ✅ The details fetch is deduped per id and also fills the other tier-3 fields the lightbox needs anyway.
+  - ❌ One small request per newly hovered live photo; a slow network delays the first play past 250 ms.
+- **Option B:** add a nullable `live_photo_urls[]` to `PhotoRatioResource` and `SearchPhotoResource`.
+  - ✅ URL known at render time; no extra request.
+  - ❌ API contract change (`lychee.d.ts`), and a 4th `size_variants` join for the disk, amending NFR-064-03.
+- **Option C:** hover playback only on tiles whose URL is already loaded (v2 payloads, or after the photo was selected/opened).
+  - ✅ No change beyond the thumbnail.
+  - ❌ On v3 grids hover does nothing on first visit, which looks broken.
+
+### ~~Q-100-08~~ – Library or application
+
+**Context:** On PR #4900 maintainer ildyria asked why the support was not added to `lychee-org/php-exif` instead (comment 6251741379). Q-100-02 had kept the XMP reader in Lychee because php-exif's exiftool mapping flattens `Container:Directory`. That argument is about the mapping, not about where the code lives: the same file-level reader can sit in php-exif.
+
+- **Option A (chosen):** move the reader into php-exif (`PHPExif\MotionPhoto\*`), run it from `Reader::read()` for every adapter, and report the result as the existing `MicroVideoOffset`.
+  - ✅ What the maintainers asked for; every php-exif user gets motion photos; Lychee's `Extractor` needs no special case.
+  - ❌ Two-repository change: php-exif release, then a dependency bump in Lychee.
+- **Option B:** keep the reader in Lychee (Q-100-02 Option A).
+  - ✅ No cross-repository coordination.
+  - ❌ Against the maintainers' request; metadata reading split between the library and the app.
+
+### ~~Q-100-09~~ – Transcode HEVC clips
+
+**Context:** Maintainer ildyria asked on PR #4900 (comment 6264700405): "Should we transcode them with ffmpeg then?", about the Non-Goal "Transcoding HEVC clips for browsers that cannot decode them". `GoogleMotionPictureHandler` re-muxes with `MOVFormat` (codec `copy`), so Pixel clips are stored as HEVC and browsers without HEVC decoding (Firefox on many systems, Chromium without hardware support) keep the still, in the grid and in the LivePhotosKit lightbox. Modern iPhones also record Live Photo video in HEVC by default, so Apple pairs have the same gap today (the repository's `train.mov` is an older H.264 one). Measured on the Pixel sample (2.37 s, 1440×1080, HEVC 3.69 MB, rotation −90°): libx264 `veryfast` CRF 23 → 1.15 MB in 0.17 s on an Apple M5 Pro (CRF 28 → 0.42 MB); the rotation is applied to the frames. Both Docker images install Debian trixie's `ffmpeg`, which includes libx264.
+
+- **Option A (chosen):** transcode Google motion clips to H.264 during extraction (upload and `lychee:extract_motion_photos`) when the stream is not already H.264: libx264, `yuv420p`, CRF 23, `+faststart`, still `.mov` for LivePhotosKit; add `--reencode` to the command for clips already stored as HEVC.
+  - ✅ Plays in every browser, grid and lightbox; files about a third of the size; rotation baked in.
+  - ✅ FFmpeg already runs at that step; no schema change.
+  - ❌ Lossy second encode; a few hundred ms to ~2 s CPU per upload on small servers.
+  - ❌ Apple HEVC Live Photos keep the gap (follow-up).
+- **Option B:** same, for every live photo video, including Apple pairs (`VideoPartner` pipes) and a backfill for them.
+  - ✅ Fixes the gap for Apple Live Photos too.
+  - ❌ Touches the Apple pairing path and existing libraries; larger scope than this PR.
+- **Option C:** keep the original HEVC and store an extra H.264 file used as a `<source>` fallback.
+  - ✅ No quality loss where HEVC plays.
+  - ❌ New column or size variant, migration, and double storage.
+- **Option D:** no transcode; document the limitation.
+  - ✅ No change.
+  - ❌ Firefox users on systems without HEVC see no motion for Pixel (and recent iPhone) clips.
diff --git a/docs/specs/4-architecture/features/100-google-motion-photos/plan.md b/docs/specs/4-architecture/features/100-google-motion-photos/plan.md
new file mode 100644
index 00000000000..2632f23374c
--- /dev/null
+++ b/docs/specs/4-architecture/features/100-google-motion-photos/plan.md
@@ -0,0 +1,166 @@
+# Feature Plan 100 – Google Motion Photos
+
+_Linked specification:_ [spec.md](spec.md)  
+_Linked tasks:_ [tasks.md](tasks.md)  
+_Status:_ Implemented  
+_Last updated:_ 2026-10-17
+
+> Guardrail: Keep this plan traceable back to the governing spec. Reference FR/NFR/Scenario IDs from `spec.md` where relevant, log any new high- or medium-impact questions in the feature's [open-questions.md](open-questions.md), and assume clarifications are resolved only when the spec’s normative sections (requirements/NFR/behaviour/telemetry) and, where applicable, ADRs under `docs/specs/6-decisions/` have been updated.
+
+## Vision & Success Criteria
+A photo taken on a current Android phone shows its motion in Lychee: in the lightbox (already works once the video is stored) and in the v8 grid on hover. Success signals:
+- A Pixel `.MP.jpg` uploads as a live photo on exiftool, Imagick and Native installs (S-100-01, 03, 09).
+- Existing libraries gain their videos with `lychee:extract_motion_photos` (S-100-11).
+- Grid pages make no video request until hover intent (NFR-100-01).
+- Quality gate green: `php-cs-fixer`, `make phpstan`, scoped `php artisan test`, `npx vp check` (no `--fix`), `vp run typecheck`, `vp test`.
+
+## Scope Alignment
+- **In scope:** `App\Metadata\MotionPhoto` reader (FR-100-01); `Extractor` wiring (FR-100-01/02); backfill command (FR-100-04); v8 badge and hover playback for every live photo (FR-100-03); fixtures; docs.
+- **Out of scope:** Spec Non-Goals (Samsung legacy trailer, HEIC motion photos, presentation timestamp, HEVC transcoding, lightbox player change, v7 grid, touch inline playback).
+
+## Dependencies & Interfaces
+- `App\Metadata\Extractor::createFromFile` (call site of the locator), `PanoramaDetector` (style precedent: final class, pure helpers, readonly record).
+- Unchanged consumers: `ExtractGoogleMotionPictures`, `GoogleMotionPictureHandler`, `PlaceGoogleMotionVideo`.
+- `Detect360` command (cursor/limit/timeout pattern for CLI-100-01).
+- v8 `PhotoThumb.vue`, `Virtualized/PhotoThumbVirtual.vue`, `ThumbBadge.vue`; grid stores' details loaders (Q-100-07).
+- Tooling: exiftool and FFmpeg for the image-processing tests (they `assertHasExifToolOrSkip` / `assertHasFFMpegOrSkip`).
+- ADR-100-01.
+
+- **Dependency bump (owner approval, 2026-10-19):** `lychee-org/php-exif` `^1.4.0` → `^1.5.0` (lock 1.5.0, commit `05f9945`). Rationale: 1.5.0 ships the motion photo reader moved out of Lychee (LycheeOrg/php-exif#83, ADR-100-01) and runs it from `Reader::read()` for every adapter. Only `lychee-org/php-exif` changed in `composer.lock`; its source URL kept on HTTPS.
+
+## Assumptions & Risks
+- **Assumptions:**
+  - Pixel files carry the video's `Container:Item` in the standard XMP packet (extended XMP is not read).
+  - The owner supplies one Pixel `.MP.jpg` cleared for publication (FX-100-03, Q-100-06).
+- **Risks / Mitigations:**
+  - _Local toolchain (resolved 2026-10-17):_ installed at the owner's request: Homebrew `php@8.4` 8.4.26 (CI version) + PECL `imagick` 3.8.1, `exiftool` 13.55, `ffmpeg` 9.0.2, `imagemagick` 7.1.2, `ghostscript` (added during T-100-09: the Imagick PDF tests fail with `FailedToExecuteCommand 'gs'` without it); Composer 2.10.3 phar (SHA-256 checked) in `/opt/homebrew/bin`; `composer install` and `npm ci` from the lockfiles (no dependency change). Frontend commands run as `npx vp …`. Baseline: `php artisan test --filter=GoogleMotion` 10/10 passed (not skipped), `npx vp test` 13/13, `npx vp run typecheck` green.
+  - _Some files lack the directory item_ (issue #1283 dump): covered by the `ftyp` scan (S-100-04).
+  - _False-positive `ftyp` in JPEG entropy data:_ scan only when `MotionPhoto="1"`, require size 8…256 and a whitelisted brand; FFmpeg's open then rejects garbage (existing broken-video path).
+  - _HEVC Apple clips in the grid on Firefox:_ fall back to the still (S-100-18), accepted in Q-100-03.
+  - _v3 grid tiles have no URL at hover:_ Q-100-07 resolved (Option A): each view provides its store's deduped details loader; the first hover of a photo costs one details request (FR-100-05).
+
+## Implementation Drift Gate
+After T-100-15, during T-100-16, compare every FR/NFR/S-ID against the tests named in tasks.md, re-run all verification commands listed there, and record the report (traceability table, divergences, lessons) under "Drift Gate Report" below.
+
+## Increment Map
+
+1. **I1 – Fixtures** (FX-100-01, 02, 04)
+   - _Goal:_ Deterministic Motion Photo 1.0 and Ultra HDR sample files.
+   - _Steps:_ Build from `tests/Samples/google_motion_photo.jpg`: cut its MP4 trailer (legacy offset 4 495 341), rewrite the XMP APP1 with a `Container:Directory` (Primary / MotionPhoto, and Primary / GainMap / MotionPhoto using a small JPEG as gain map), drop `MicroVideoOffset`. Keep the builder as `tests/Samples/build_motion_photo_fixtures.php` (pure PHP, no dependency); register constants in `TestConstants`.
+   - _Commands:_ `php tests/Samples/build_motion_photo_fixtures.php`; `exiftool -a -G1 -XMP-GContainer:all <file>` to eyeball.
+   - _Exit:_ both files committed, each < 5 MB, exiftool lists the expected items.
+2. **I2 – `JpegXmpReader`** (FR-100-01, S-100-10, NFR-100-02)
+   - _Steps:_ failing `tests/Unit/Metadata/JpegXmpReaderTest` (no SOI, truncated segment, segment length > file, XMP present, XMP absent, stops at SOS) → implement.
+   - _Commands:_ `php artisan test --filter=JpegXmpReaderTest`, `make phpstan`.
+3. **I3 – `MotionPhotoXmp`** (FR-100-01, S-100-01, 03, 04, 09, 10)
+   - _Steps:_ failing `MotionPhotoXmpTest` (v1 directory, Ultra HDR directory, `MotionPhoto=1` without item, legacy offset, attribute vs element syntax for `Item:*`, malformed XML, unrelated XMP) → implement with `xml_parser_create_ns`.
+   - _Commands:_ `php artisan test --filter=MotionPhotoXmpTest`, `make phpstan`.
+4. **I4 – `MotionPhotoLocator`** (FR-100-01, S-100-04, 05, 08, NFR-100-02)
+   - _Steps:_ failing `MotionPhotoLocatorTest` on bytes generated in the test (valid length; length → non-`ftyp`; scan hit; scan miss; no motion XMP + trailing `ftyp` → 0; 20 MB memory check) → implement `ftyp` matcher + chunked scan + composition.
+   - _Commands:_ `php artisan test --filter=MotionPhotoLocatorTest`, `make phpstan`.
+5. **I5 – `Extractor` wiring + upload tests** (FR-100-01/02, S-100-01 … 07, 09)
+   - _Steps:_ failing `BaseImageHandler` tests `testGoogleMotionPhotoV1Upload`, `testGoogleMotionPhotoUltraHdrUpload`, `testGoogleMotionPhotoNoFfmpegUpload`; then call the locator from `Extractor::createFromFile` for `image/jpeg` when `micro_video_offset === 0`; update the field doc comment (DO-100-01).
+   - _Commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest`, `--filter=PhotosAddHandlerGdTest` (whichever `BaseImageHandler` subclasses exist), `--filter=PhotoAddTest`, `--filter=DownloadTest`, `make phpstan`.
+6. **I6 – Backfill command** (FR-100-04, S-100-11 … 14)
+   - _Steps:_ failing `tests/ImageProcessing/Commands/ExtractMotionPhotosTest` → `app/Console/Commands/ImageProcessing/ExtractMotionPhotos.php`, extracting the "video path next to original" computation of `PlaceGoogleMotionVideo` into a small shared helper used by both.
+   - _Commands:_ `php artisan test --filter=ExtractMotionPhotosTest`, `--filter=PhotosAddHandlerImagickTest`, `make phpstan`.
+7. **I7 – Motion badge + lang key** (FR-100-03, UI-100-01, NFR-100-04)
+   - _Steps:_ `gallery.motion_photo` in the 23 `lang/*/gallery.php`; `ThumbBadge` in `PhotoThumb.vue` and `PhotoThumbVirtual.vue`.
+   - _Commands:_ `php artisan test --filter=LangTest`, `php scripts/check_translations.php` (if present), `npx vp check` (no `--fix`), `vp run typecheck`.
+8. **I8 – `useMotionHover` composable, URL loader, hover overlay** (FR-100-03, FR-100-05, S-100-15 … 20, NFR-100-01)
+   - _Steps:_ failing Vitest `useMotionHover.test.ts` (250 ms intent, cancel on leave, hover/pointer media gate, reduced motion, error reset, loader called once only when the URL is missing, late URL, leave before URL, loader rejection) → composable in `resources/js/v8/composables/photo/useMotionHover.ts`; `motionUrlLoader.ts` injection key and `provide` in `AlbumPanel.vue`, `Timeline.vue` and `Search.vue` (not `Flow.vue`, which renders no `PhotoThumb`); overlay `<video muted loop playsinline>` in both thumbs.
+   - _Commands:_ `vp test`, `npx vp check` (no `--fix`), `vp run typecheck`; manual check on Chrome, Firefox, Safari, one phone, in album, timeline and search views.
+9. **I9 – Real-sample test** (FX-100-03, S-100-01, S-100-03)
+   - _Steps:_ `testGoogleMotionPhotoPixelUpload` on `google_motion_photo_pixel.jpg` (placed 2026-10-17).
+   - _Commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest`.
+10. **I10 – Docs + drift gate**
+    - _Steps:_ knowledge map, `1-concepts/photos.md`, `request-lifecycle-photo-upload.md`, roadmap; drift gate report.
+
+## Scenario Tracking
+
+| Scenario ID | Increment / Task reference | Notes |
+|-------------|---------------------------|-------|
+| S-100-01 | I3, I5, I9 / T-100-04, T-100-08, T-100-15 | `MotionPhotoXmpTest`, `testGoogleMotionPhotoV1Upload`, `testGoogleMotionPhotoPixelUpload` |
+| S-100-02 | I5 / T-100-08 | existing `testGoogleMotionPhotoUpload` |
+| S-100-03 | I3, I5 / T-100-04, T-100-08 | `testGoogleMotionPhotoUltraHdrUpload` |
+| S-100-04 | I3, I4 / T-100-04, T-100-06 | `MotionPhotoLocatorTest` scan hit |
+| S-100-05 | I4 / T-100-06 | length → non-`ftyp` |
+| S-100-06 | I5 / T-100-08 | existing `testBrokenGoogleMotionPhotoUpload` |
+| S-100-07 | I5 / T-100-08 | `testGoogleMotionPhotoNoFfmpegUpload` |
+| S-100-08 | I4 / T-100-06 | no motion XMP + trailing `ftyp` |
+| S-100-09 | I3, I5 / T-100-04, T-100-08 | legacy via XMP on Imagick reader |
+| S-100-10 | I2, I3 / T-100-02, T-100-04 | malformed input |
+| S-100-11 … 14 | I6 / T-100-10 | `ExtractMotionPhotosTest` |
+| S-100-15 … 18 | I8 / T-100-13, T-100-14 | `useMotionHover.test.ts` + manual |
+| S-100-19, 20 | I8 / T-100-13, T-100-17 | `useMotionHover.test.ts` + manual per view |
+
+## Analysis Gate
+
+Run 2026-10-17 by the agent (owner review pending).
+
+1. Specification completeness — ✅ objectives, FR, NFR populated; Q-100-01 … 06 folded into FR/NFR/Non-Goals; ASCII mock-up present.
+2. Open questions review — ✅ Q-100-01 … 07 resolved (Q-100-07 Option A, owner 2026-10-17, folded into FR-100-03/05, S-100-19/20). An ADR was written for Q-100-02 (in-house reader; dropped after Q-100-08, see Review Follow-up); Q-100-07 stays inside existing contracts, no ADR.
+3. Plan alignment — ✅ plan links spec and tasks; success criteria match the spec.
+4. Tasks coverage — ✅ every FR maps to tasks (FR-100-01: T-100-01…09, T-100-15; FR-100-02: T-100-08/09; FR-100-03: T-100-12…14; FR-100-04: T-100-10/11; FR-100-05: T-100-13, T-100-17); tests precede code in every increment; failure branches listed (S-100-05, 06, 07, 10, 13, 14, 18).
+5. Working-agreement compliance — ✅ no dependency change; locator split into pure helpers (NFR-100-05); the Q-100-02 ADR reviewed. No other ADR references Feature 100.
+6. Tooling readiness — ✅ commands documented per increment; local toolchain installed and baseline green 2026-10-17 (see Risks).
+
+**Outcome:** cleared for I1–I10 (owner's sample placed 2026-10-17). Re-run 2026-10-17 after Q-100-07 and the toolchain install: no new findings.
+
+## Exit Criteria
+- All tasks `[x]`; quality gate green (PHP + frontend); `vp test` green.
+- `lychee.d.ts` unchanged (no resource change, Q-100-07 Option A).
+- Roadmap, knowledge map, concept and lifecycle docs updated; drift gate report below.
+- Open questions all resolved.
+
+## Follow-ups / Backlog
+- Samsung legacy `MotionPhoto_Data` trailer.
+- HEIC primary motion photos.
+- Start the hover clip at `MotionPhotoPresentationTimestampUs`.
+- v7 grid playback, if requested.
+
+## Intent Log
+- 2026-10-17: owner asked for a plan for Google motion photos (#753, #1283) with grid hover or play button. Agent surveyed the live photo pipeline (Explore agent + direct reads of `GoogleMotionPictureHandler`, `ExtractGoogleMotionPictures`, `Extractor`, php-exif 1.4.0 mapper via `gh api`), parsed the existing sample's XMP with a Python one-off (legacy format confirmed), drafted spec + Q-100-01 … 06. Owner chose Option A for all six. While planning FR-100-03 the agent found v3 tiles lack `live_photo_url` until tier-3 details load → Q-100-07; owner chose Option A (details on hover) → FR-100-05, T-100-17. Owner supplied a Pixel 11 Pro motion photo; agent stripped GPS, C2PA and the HDR+ maker note with exiftool (owner asked for GPS removal so they cannot be identified; C2PA/maker note removed as device fingerprints), verified trailer bytes identical and inspected the still and video frames for identifying content (none), placed it as FX-100-03 at full resolution; findings (Primary item without `Item:Length`, HEVC video) folded into the spec Appendix. Grep of v8 thumbnail hosts: `PhotoThumbPanel`, `PhotoThumbPanelVirtual`, `TimelineDatesV3`, `ResultPanel`, views `Timeline`, `Search`, `Flow`; Ken Burns hover is CSS-only, no conflict.
+
+## Review Follow-up (PR #4900, 2026-10-18)
+- CodeRabbit: the feature number collided with upstream's Feature 098 (Tag Albums Category, merged meanwhile; 099 is PDF Photo View). Renumbered to the next free ID, 100: folder `features/100-google-motion-photos/`, `ADR-100-01`, every `*-098-*` identifier, and the code and test doc comments. Tag Albums' own 098 references (roadmap row, knowledge map line) left untouched.
+- CodeRabbit: repeated hover sent duplicate details requests while the first was in flight. `useMotionHover` now keeps the pending request per photo id until it settles (FR-100-05); Vitest cases added for reuse and for retry after a failure (20/20).
+- CodeRabbit (second review, on 2cdecef): (a) the fallback scan started at SOS, so compressed image data looking like an MP4 header could be taken for the video; it now starts after the primary image's EOI (`JpegImageEnd`, SVC-100-04), with tests for a look-alike header inside the image data, an EOI across a chunk boundary and a missing EOI (locator 21/21); (b) the plan and tasks still prescribed `vp check --fix`, now `npx vp check`; (c) T-100-17 and I8 still listed `Flow.vue` as a loader provider, removed.
+- Maintainer ildyria (comment 6251741379): asked why the support was not added to php-exif. Owner chose to move it (Q-100-08, ADR-100-01). T-100-18 done on `mlapaglia/php-exif` `feat/google-motion-photos`; T-100-19 (php-exif PR, release, Lychee bump) pending.
+- 2026-10-19: php-exif #83 merged and released as 1.5.0; upstream `master` merged (CONTRIBUTING.md only); php-exif bumped to `^1.5.0` with owner approval. Verified: php-exif alone reports 10705 / 10705 / 3725212 / 4495341 bytes for the v1, Ultra HDR, Pixel and legacy samples with the Native and Imagick readers, `false` for a plain JPEG; upload suites, `ExtractMotionPhotosTest`, `PhotoAddTest`, `DownloadTest`, `Detect360Test` and `make phpstan` green. Lychee's own reader was then removed with owner approval of the exact paths (T-100-19): `app/Metadata/MotionPhoto/` and `tests/Unit/Metadata/MotionPhoto/` deleted, `Extractor` reads php-exif only, the command calls `PHPExif\MotionPhoto\MotionPhotoLocator`; the four upload suites, `ExtractMotionPhotosTest`, `PhotoAddTest`, `DownloadTest`, `Detect360Test`, the other `Extractor` users and `make phpstan` green.
+- Maintainer ildyria (comment 6264700405) asked whether to transcode HEVC clips. Owner chose Q-100-09 Option A (2026-10-19): `GoogleMotionPictureHandler::saveVideoStream()` copies H.264 and transcodes other codecs with `H264MOVFormat` (libx264 CRF 23 `veryfast`, `yuv420p`, `+faststart`, rotation applied); `lychee:extract_motion_photos --reencode` re-extracts stored Google clips from their originals (Apple pairs excluded). Measured on the Pixel sample: HEVC 3.69 MB → H.264 1.15 MB, 0.17 s on an M5 Pro. Tests: Pixel upload stores upright H.264 1080×1440, v1 stays copied H.264 (`ProbesStoredVideo` trait), three `--reencode` command tests; the four upload suites, `ExtractMotionPhotosTest` (11), `PhotoAddTest`, `DownloadTest` and `make phpstan` green.
+- CodeRabbit (discussion r4313351119): a full batch with a failed photo printed a cursor that skips it. The command now prints each failure (`Failed: <id> (<title>): <reason>`) and, after the cursor, asks to run the same batch again first; `testCursorAfterAFailureAsksToRetryTheBatch` added (12/12).
+- CodeRabbit (discussion r4314927585): `--reencode` wrote the new clip straight over the stored one, so an interrupted write could leave a truncated clip in use. The command now writes `<target>.part` and moves it over the target (a rename on local disks); `testReencodeKeepsTheStoredClipWhenTheWriteFails` blocks the staging path and checks the stored clip is unchanged (13/13). On the orphan-file thread (r4313351124) ildyria rejected CodeRabbit's transaction-wrapping patch and CodeRabbit withdrew it; no change.
+- Maintainer ildyria (review on `docs/specs/6-decisions/README.md`): the superseded in-house reader ADR should not stay. Removed it and renumbered the php-exif ADR from ADR-100-02 to ADR-100-01 (`ADR-100-01-motion-photo-reader-in-php-exif.md`), now self-contained: its context and alternatives carry what the removed ADR recorded (exiftool flattening, Native/Imagick gaps, `ftyp`-only scan). References updated in the ADR index, spec, plan, tasks, open questions, roadmap, knowledge map.
+- Maintainer ildyria (discussion r4317257862, "is this comment necessary?"): the doc comment on `Extractor::$micro_video_offset` was left over from the in-house locator call that T-100-19 removed. Dropped it, so `Extractor.php` matches upstream again (DO-100-01 updated). On the same review ildyria checked the hover wiring for `Flow.vue` (it does not use `PhotoThumb`, no change) and accepted the `MOTION_URL_LOADER` provide (Q-100-07), no change.
+- CodeRabbit docstring-coverage warning (31.75 % of touched functions): not a repository rule; the new PHP classes and public methods carry doc comments, the uncovered ones are tests and Vue setup functions. No change.
+
+## Drift Gate Report
+
+Run 2026-10-17 by the agent after T-100-01 … T-100-17 (owner acknowledgement pending).
+
+**Preconditions:** 17/17 tasks `[x]`. Quality gate green on the final tree: `vendor/bin/php-cs-fixer fix --dry-run` (0 of 2994 files), `make phpstan` (no errors, 3156 files), `npx vp check` (0 errors; 18 pre-existing warnings, none in feature files), `npx vp run typecheck`, `npx vp test` (31/31), `php scripts/check_translations.php` (gallery.php complete).
+
+**Traceability**
+
+| Requirement | Code | Tests (latest run, all green) |
+|-------------|------|-------------------------------|
+| FR-100-01 | `app/Metadata/MotionPhoto/{JpegXmpReader,JpegHeader,MotionPhotoXmp,MotionPhotoXmpHandler,FtypBox,MotionPhotoLocator}.php`, `Extractor::createFromFile()` | `JpegXmpReaderTest` 13, `MotionPhotoXmpTest` 18, `MotionPhotoLocatorTest` 18 (incl. Pixel, v1, Ultra HDR, legacy samples, 20 MB memory check) |
+| FR-100-02 | unchanged pipes; `PlaceGoogleMotionVideo` uses `GoogleMotionPictureHandler::videoPathNextTo()` | `BaseImageHandler::testGoogleMotionPhoto{V1,UltraHdr,Pixel,WithoutFFMpeg}Upload`, `testLegacyGoogleMotionPhotoWithoutExifToolUpload`, existing GMP tests, in GD/Imagick/RawUploadImagick/Watermarker (34/40/37/39); `PhotoAddTest` 10, `DownloadTest` 15 |
+| FR-100-03 | `ThumbBadge.vue` (`label`), `PhotoThumb.vue`, `PhotoThumbVirtual.vue`, `useMotionHover.ts`, 23 × `lang/*/gallery.php` | `useMotionHover.test.ts` 18; `LangTest` 2; browser check below |
+| FR-100-04 | `app/Console/Commands/ImageProcessing/ExtractMotionPhotos.php` | `ExtractMotionPhotosTest` 8 |
+| FR-100-05 | `motionUrlLoader.ts`; `provide` in `AlbumPanel.vue`, `Timeline.vue`, `Search.vue` | `useMotionHover.test.ts` (loader cases); browser check below |
+| NFR-100-01 | `<video>` rendered only after intent | browser: 0 `.mov` requests on load and after a 120 ms sweep |
+| NFR-100-02 | `JpegXmpReader` stops at SOS, `FtypBox::scan` 64 KiB chunks | `MotionPhotoLocatorTest::testScanUsesConstantMemory` |
+| NFR-100-03 | no `composer.json`/`package.json` change | `git diff` |
+| NFR-100-04 | `canPlayMotionOnHover()`, muted video, badge `aria-label` | Vitest gate cases; browser reduced-motion context |
+| NFR-100-05 | small pure helpers | PHPStan, review |
+
+**Browser check (scratch instance, 2026-10-17):** separate SQLite file and `public/uploads-motion/` via env overrides, `NUXT_UI_ENABLED` + `STRUCT_OF_ARRAY_ENABLED`, samples imported with `lychee:sync` (all four Google files and the Apple pair became live photos). Google Chrome via Playwright `channel: "chrome"`: 5 badges, none on the plain photo; first hover on the Pixel tile sent exactly one `GET /api/v3/Albums/{id}/Photos/details?photo_ids[]=…` and one `.mov` request, the HEVC clip played muted (`readyState` 4, time advancing, opacity 1); leave removed the element; second hover sent no details request; reduced motion showed badges only; a `.mov` routed to non-video bytes was dropped with the still visible, no toast, no console error; the lightbox shows LivePhotosKit's LIVE control for the Pixel photo. Not done: Firefox, Safari, a touch device (owner).
+
+**Divergences:** all low impact, fixed in the spec: `JpegXmpReader` returns `JpegHeader` (SVC-100-01); FR-100-04 output strings, dry run without FFmpeg, missing original counted as failed, remote originals downloaded (branch not testable with `Storage::fake`, `@codeCoverageIgnore` like `SizeVariantDefaultFactory`); FR-100-05 providers are Album/Timeline/Search (Flow renders no `PhotoThumb`; tag/favourites carry the URL); badge sits after the 360° badge; badge label via new `ThumbBadge` `label` prop; fade-in uses `isPlaying` from the composable. Over-delivery: legacy motion photos now work without exiftool (S-100-09), covered by tests. No high/medium divergence; no new open question.
+
+**Lessons**
+- `npx vp check --fix` fixes the whole tree: it rewrote five unrelated files and its "useless escape" fix broke both `EmbedCodeDialog.vue` (`<\/script>` inside a template literal of a `.vue` `<script>` block must stay escaped). Reverted; use `npx vp check` (no `--fix`) or review `git status` after a fix run. Worth an Oxlint rule override or an AGENTS.md note (owner decision).
+- The Imagick PDF tests need Ghostscript locally (`FailedToExecuteCommand 'gs'`).
+- Playwright's bundled Chromium lacks proprietary codecs (and the cached build lagged the installed Playwright); `channel: "chrome"` gives real H.264/HEVC playback.
diff --git a/docs/specs/4-architecture/features/100-google-motion-photos/spec.md b/docs/specs/4-architecture/features/100-google-motion-photos/spec.md
new file mode 100644
index 00000000000..ab102affd68
--- /dev/null
+++ b/docs/specs/4-architecture/features/100-google-motion-photos/spec.md
@@ -0,0 +1,198 @@
+# Feature 100 – Google Motion Photos
+
+| Field | Value |
+|-------|-------|
+| Status | Implemented |
+| Last updated | 2026-10-17 |
+| Owners | mlapaglia |
+| Linked plan | [plan.md](plan.md) |
+| Linked tasks | [tasks.md](tasks.md) |
+| Roadmap entry | #100 |
+
+> Guardrail: This specification is the single normative source of truth for the feature. Track high- and medium-impact questions in the feature's [open-questions.md](open-questions.md), encode resolved answers directly in the Requirements/NFR/Behaviour/UI/Telemetry sections below (no per-feature `## Clarifications` sections), and use ADRs under `docs/specs/6-decisions/` for architecturally significant clarifications (referencing their IDs from the relevant spec sections).
+
+## Overview
+Lychee extracts the video from Google Motion Photos only in the legacy format (Android ≤ 10, XMP `GCamera:MicroVideoOffset`), and only when exiftool is the metadata reader (php-exif maps the tag for exiftool alone). Android 11+ writes the Motion Photo 1.0 format (`GCamera:MotionPhoto` + `Container:Directory`), which Lychee imports as a plain still (LycheeOrg/Lychee#753, #1283). This feature reads both formats with an in-house XMP reader, stores the video through the existing live photo path (`photos.live_photo_short_path`; the lightbox already plays it through LivePhotosKit), backfills existing photos with an artisan command, and adds motion playback to v8 grid thumbnails for every live photo.
+
+Affected layers: metadata extraction (`app/Metadata`), one artisan command, v8 grid thumbnails and the views that host them. No migration. No REST contract change: v3 grid tiles fetch their video URL through the existing tier-3 details endpoint on hover (Q-100-07).
+
+## Goals
+- Motion Photo 1.0 JPEGs (Pixel, Ultra HDR included) import as live photos, the video placed next to the original as `.mov`.
+- Legacy `MicroVideoOffset` files keep working, now on every metadata reader (exiftool, Imagick, Native).
+- On v8 grids, live photos (Apple and Google) carry a motion badge and play their motion on hover.
+- Already-imported motion photos gain their video through `lychee:extract_motion_photos`.
+
+## Non-Goals
+- Samsung's legacy `MotionPhoto_Data` / SEF trailer format.
+- HEIC/AVIF motion photos (primary image other than JPEG).
+- Honouring `MotionPhotoPresentationTimestampUs`.
+- Transcoding Apple Live Photo videos (separate `.mov` partners); only clips embedded in Google Motion Photos are transcoded (Q-100-09).
+- Changing the lightbox player (LivePhotosKit stays).
+- v7 grid playback (Q-100-05).
+- Inline playback on touch devices (Q-100-01).
+
+## Functional Requirements
+
+| ID | Requirement | Success path | Validation path | Failure path | Telemetry & traces | Source |
+|----|-------------|--------------|-----------------|--------------|--------------------|--------|
+| FR-100-01 | Locate the embedded video of a JPEG. | `Extractor::createFromFile` takes the php-exif (`^1.5.0`) `MicroVideoOffset`. php-exif's `Reader::read()` fills it for every reader when the adapter found none, by calling `PHPExif\MotionPhoto\MotionPhotoLocator::locate()` (ADR-100-01), which reads the XMP packet from the JPEG APP1 segments and returns the video length in bytes from the end of the file: (1) `Item:Length` of the `Container:Item` with `Item:Semantic="MotionPhoto"`; (2) else `GCamera:MicroVideoOffset`; (3) else, when `GCamera:MotionPhoto="1"`, the distance from the first plausible MP4 `ftyp` box after the primary image's end-of-image marker (`JpegImageEnd`, the first `FF D9` after SOS) to the end of the file; no end-of-image marker → 0. The result goes into `Extractor::$micro_video_offset`. | A declared length (1 or 2) is accepted only when `0 < length < filesize` and the bytes at `filesize − length + 4` read `ftyp`; otherwise step 3 applies when `MotionPhoto="1"`, else 0. A plausible `ftyp` box has a big-endian size in 8…256 and a major brand from the Appendix list. Non-JPEG, no XMP, malformed XMP → 0. | Any read/parse error → 0 and `Log::warning`; the photo imports as a still. Never throws out of `Extractor`. | Existing span `photo.extract_google_motion_pictures` unchanged. | #753, #1283, Q-100-02, ADR-100-01 |
+| FR-100-02 | Extract and place the video at upload. | `ExtractGoogleMotionPictures` passes the length to `GoogleMotionPictureHandler::load`; `saveVideoStream()` copies an H.264 stream into `.mov` (`MOVFormat`, `-map 0:0`) and transcodes any other codec (HEVC from current Pixels) to H.264 (`H264MOVFormat`: libx264, CRF 23, `veryfast`, `yuv420p`, `+faststart`, `-map 0:0`, rotation applied to the frames), so every browser plays it (Q-100-09); `PlaceGoogleMotionVideo` writes it next to the original and sets `live_photo_short_path`. Ultra HDR files (`GainMap` item) extract the video, not the gain map. | Requires `has_ffmpeg` (unchanged). | FFmpeg disabled/missing or unreadable stream → still imported, no video, error reported via `Handler::reportSafely` (unchanged). | — | Existing pipeline |
+| FR-100-03 | Grid motion playback (v8, every live photo). | `PhotoThumb.vue` and `PhotoThumbVirtual.vue`: a motion badge (`ThumbBadge` with `lucide:smartphone` on `bg-purple-700`, the icon and colour of the list-view "Live" label, FR-014-06; its new `label` prop sets `title` and `aria-label` to `gallery.motion_photo`) in the badge row whenever `precomputed.is_livephoto`. On devices matching `(hover: hover) and (pointer: fine)`, after 250 ms of continuous hover a muted, looping, `playsinline` `<video>` fades in over the thumbnail (`object-cover`, same box) and plays `live_photo_url`; on `mouseleave` it pauses, its `src` is removed and the still shows again. When `live_photo_url` is still `null` at `mouseenter`, the URL is fetched per FR-100-05; playback starts once both the 250 ms have passed and the URL is set, and never if the pointer left first. The overlay covers the still, so the Ken Burns hover zoom (when enabled) keeps running unseen underneath. | Only tiles with `is_livephoto === true`; nothing when `prefers-reduced-motion: reduce` (badge only); nothing on touch-only devices (badge only, tap opens the lightbox as today). | Video `error` event → overlay removed, still stays, no toast, no retry during that hover. | None (frontend only). | Owner request, Q-100-01, Q-100-03, Q-100-05 |
+| FR-100-04 | Backfill already-imported photos. | `php artisan lychee:extract_motion_photos {limit=100} {tm=600} {--after=} {--album=} {--dry-run} {--reencode}` walks photos with `type = 'image/jpeg'` and `live_photo_short_path IS NULL`, ordered by id with an `--after` cursor (as `lychee:detect_360`). For each it uses the original in place when hosted locally, or a downloaded temporary copy otherwise (as `SizeVariantDefaultFactory`), runs `PHPExif\MotionPhoto\MotionPhotoLocator::locate()` on its path, and when the length > 0 extracts via `GoogleMotionPictureHandler` and writes `GoogleMotionPictureHandler::videoPathNextTo(<original path>)` on the original's disk (the helper the upload pipe `PlaceGoogleMotionVideo` now shares), then sets `live_photo_short_path` and dispatches `PhotoSaved` for the extracted ids. Output: `Motion photo: <id> (<title>)` per hit, then `Checked N photos: X motion photos extracted, Y failed.` (`found (dry run)` with `--dry-run`), and `More photos may remain: continue with --after=<last id>` when `N = limit`; nothing to scan → `No photos require motion photo extraction.` | `--reencode` switches the candidates to Google motion photos that already have a video (`live_photo_short_path` set, `live_photo_content_id` null) and re-extracts each clip from the original into its current path, transcoding as in FR-100-02; the summary says `re-extracted`. Every clip the command writes is staged at `<target>.part` on the same disk and then moved over the target, so a failed write leaves an existing clip intact (PR #4900 review). `--dry-run` writes nothing and does not need FFmpeg. `--album` restricts to that album's direct photos; unknown id → `Album <id> not found.`, exit 1. FFmpeg disabled without `--dry-run` → `FFmpeg is required to extract motion photo videos (or use --dry-run).`, exit 1, before the scan. | Missing original or any per-photo error → `Log::warning` and `Failed: <id> (<title>): <reason>` on the console, counted as failed, loop continues; exit 1 when any failed. When the batch is full and some photos failed, the cursor line is followed by `N photos failed in this batch and would be skipped by that cursor: run it again with --after=<same value> (or without --after) to retry them first.` (PR #4900 review). Plain JPEGs stay candidates, so a re-run checks them again (no "checked" marker; the cursor bounds each run). | Command output only. | Q-100-04 |
+| FR-100-05 | Video URL for v3 grid tiles. | Each v8 view that renders photo thumbnails provides a `MotionUrlLoader` (`(photoIds: string[]) => Promise<void>`, Vue `provide`/`inject` key in `resources/js/v8/composables/photo/motionUrlLoader.ts`) wrapping its store's existing deduped details loader: `AlbumPanel.vue` → `AlbumState.loadPhotoDetails`, `Timeline.vue` → `TimelineState.loadPhotoDetailsV3`, `Search.vue` → `SearchState.loadPhotoDetailsV3`. `Flow.vue` renders its own cards, not these thumbnails, and the tag and favourites views use v2 `PhotoResource` payloads that already carry `live_photo_url`, so they provide none. The thumbnail calls it with its own id on `mouseenter` when `is_livephoto` and `live_photo_url === null`, on hover-capable devices only; the result lands in `live_photo_url` through `mergePhotoDetail()`. | No call when the URL is already set, the tile is not a live photo, or the device/motion gates of FR-100-03 fail. A view that provides no loader plays only tiles whose URL is already loaded. | Loader rejects or leaves the URL `null` → no playback for that hover, no toast; the next hover tries again (the store's dedupe makes a resolved id free). A request still in flight is reused when the pointer leaves and re-enters, because the stores mark an id resolved only once its response arrives (PR #4900 review). | None. | Q-100-07 |
+
+## Non-Functional Requirements
+
+| ID | Requirement | Driver | Measurement | Dependencies | Source |
+|----|-------------|--------|-------------|--------------|--------|
+| NFR-100-01 | No video bytes are requested until hover intent (250 ms). | Grids show hundreds of tiles. | `<video>` is not in the DOM before intent; browser network panel shows no `.mov` on page load or quick mouse sweeps. | v8 thumbnails | Q-100-01 |
+| NFR-100-02 | `MotionPhotoLocator` uses constant memory: header segments are read one by one (stop at SOS), the end-of-image search and the `ftyp` scan read 64 KiB chunks with an overlap, the file is never loaded whole. | 8–20 MB uploads under the PHP memory limit. | Unit test on a synthetic 20 MB file with `memory_get_peak_usage` delta < 2 MB. | — | Q-100-02 |
+| NFR-100-03 | No new composer/npm dependency and no new PHP extension: XMP is parsed with `ext-xml` (`xml_parser_create_ns`), already required. The existing `lychee-org/php-exif` is bumped to `^1.5.0`, which carries the reader (ADR-100-01, owner approval 2026-10-19). | AGENTS.md dependency rule. | `composer.json` / `package.json` unchanged. | — | AGENTS.md, ADR-100-01 |
+| NFR-100-04 | Hover playback is muted, has no controls, respects `prefers-reduced-motion`, and the badge has an accessible label (`gallery.motion_photo`). | Accessibility. | Manual check with reduced motion; `LangTest` for the new key. | lang files (23 locales) | WCAG 2.3.3 |
+| NFR-100-05 | The locator is a set of small pure helpers (segment reader, XMP parser returning a record, `ftyp` matcher) composed in one straight-line method. | AGENTS.md straight-line increments. | Code review; PHPStan level of `phpstan.neon`. | — | AGENTS.md |
+
+## UI / Interaction Mock-ups
+
+```
+ Idle (all devices)               Hover ≥250 ms (fine pointer, no reduced motion)
+┌────────────────────────┐        ┌────────────────────────┐
+│ (◎)                  ♡ │        │ (◎)                  ♡ │
+│                        │        │  ▶ muted looping video │
+│      still image       │        │    fades in over the   │
+│                        │        │    still (object-cover)│
+│ Title                  │        │ Title                  │
+└────────────────────────┘        └────────────────────────┘
+ (◎) = motion badge in the existing badge row, right after the 360° badge
+       (purple background, tooltip and aria-label "Motion photo")
+ Leave → video paused, src removed, still visible again.
+ Touch / reduced motion → badge only; tap opens the lightbox (LivePhotosKit plays it).
+```
+
+## Branch & Scenario Matrix
+
+| Scenario ID | Description / Expected outcome |
+|-------------|--------------------------------|
+| S-100-01 | Upload Motion Photo 1.0 JPEG with a `MotionPhoto` directory item → live photo, `.mov` next to the original. |
+| S-100-02 | Upload legacy `MicroVideoOffset` JPEG with exiftool → unchanged behaviour. |
+| S-100-03 | Upload Ultra HDR motion photo (`Primary`, `GainMap`, `MotionPhoto` items) → video extracted, gain map ignored. |
+| S-100-04 | `MotionPhoto="1"` but no `MotionPhoto` directory item → video found by the `ftyp` scan. |
+| S-100-05 | Declared length points at non-`ftyp` bytes → `ftyp` scan when `MotionPhoto="1"`, else not a motion photo. |
+| S-100-06 | Motion photo with a corrupt video trailer → still imported, no video, error logged. |
+| S-100-07 | Motion photo with FFmpeg disabled → still imported, no video. |
+| S-100-08 | Plain JPEG with unrelated trailing bytes and no motion XMP → not a motion photo (no scan). |
+| S-100-09 | Legacy `MicroVideoOffset` JPEG with the Imagick reader → now extracted (locator reads the XMP). |
+| S-100-10 | Malformed XMP / truncated JPEG → 0, warning logged, still imported. |
+| S-100-11 | `lychee:extract_motion_photos` over a library with new-format photos → videos attached; second run reports 0 extracted. |
+| S-100-12 | `--dry-run` → candidates listed, no file written, no row changed. |
+| S-100-13 | `--album=<id>` → only that album's photos; unknown id → exit 1. |
+| S-100-14 | Backfill with FFmpeg disabled → exit 1 before scanning. |
+| S-100-21 | Upload a motion photo whose clip is HEVC → stored `.mov` is H.264, upright (rotation applied). |
+| S-100-22 | Upload a motion photo whose clip is already H.264 → stream copied, not re-encoded. |
+| S-100-23 | `lychee:extract_motion_photos --reencode` on a motion photo stored with an HEVC clip → clip re-extracted from the original and stored as H.264 at the same path; `--dry-run` lists it and changes nothing; Apple pairs (`live_photo_content_id` set) are never candidates. |
+| S-100-24 | `--reencode` when writing the new clip fails → photo reported as failed, exit 1, stored clip unchanged. |
+| S-100-15 | Grid, fine pointer: hover a live photo ≥250 ms → muted loop plays; leave → stops and unloads. |
+| S-100-16 | Grid: hover < 250 ms → no video element, no request. |
+| S-100-17 | Grid: touch device or `prefers-reduced-motion` → badge only. |
+| S-100-18 | Grid: video fails to load (e.g. HEVC in Firefox) → still stays, no toast. |
+| S-100-19 | Grid on a v3 payload, URL not loaded: `mouseenter` triggers one details request for that id; playback starts after 250 ms or when the URL arrives, whichever is later; a second hover sends no request, including one that starts before the first request has answered. |
+| S-100-20 | Details request fails or the pointer leaves before the URL arrives → no playback, no toast, no stray `<video>`. |
+
+## Test Strategy
+- **Unit:** in php-exif since 1.5.0 (`tests/PHPExif/MotionPhoto/`: `JpegXmpReaderTest`, `MotionPhotoXmpTest`, `MotionPhotoLocatorTest`, `ReaderMotionPhotoTest`), over synthetic byte layouts and the v1/Ultra HDR samples (S-100-01, 03, 04, 05, 08, 09, 10; NFR-100-02). Lychee covers the integration through the upload and command tests below.
+- **Image processing (`BaseImageHandler`):** `testGoogleMotionPhotoV1Upload`, `testGoogleMotionPhotoUltraHdrUpload`, `testGoogleMotionPhotoPixelUpload` (owner sample), with FFmpeg disabled variant (S-100-01, 03, 06, 07); existing `testGoogleMotionPhotoUpload` / `testBrokenGoogleMotionPhotoUpload` stay green (S-100-02, 06).
+- **Artisan (`tests/ImageProcessing/Commands/ExtractMotionPhotosTest`):** S-100-11 … 14, plus missing original and cursor. The remote-original download branch is not covered: `Storage::fake('s3')` is a local adapter, so `isLocalFile()` is always true in tests (same gap as `SizeVariantDefaultFactory`; marked `@codeCoverageIgnore`).
+- **Frontend (v8):** Vitest for the `useMotionHover` composable (timer, intent, reduced-motion and hover-capability gates, error reset, loader called once and only when the URL is missing, late URL, pointer leaving before the URL, loader rejection) (S-100-15 … 20); manual browser check on desktop Chrome, Firefox, Safari and a phone, in album, timeline, search and flow views.
+- **Docs/Contracts:** `lychee.d.ts` unchanged.
+
+## Interface & Contract Catalogue
+
+### Domain Objects
+| ID | Description | Modules |
+|----|-------------|---------|
+| DO-100-01 | `Extractor::$micro_video_offset` keeps its name and meaning, "video length in bytes from the end of the file", now filled by php-exif for both formats and every reader. `Extractor.php` itself is unchanged. | `app/Metadata/Extractor.php` |
+| DO-100-02 | `MotionPhotoXmp` readonly record: `is_motion_photo: bool`, `item_length: int`, `legacy_offset: int`. | `app/Metadata/MotionPhoto/` |
+
+### Services
+Provided by `lychee-org/php-exif` 1.5.0 (LycheeOrg/php-exif#83, ADR-100-01); Lychee calls only SVC-100-03, from `lychee:extract_motion_photos`.
+
+| ID | Class | Description |
+|----|-------|-------------|
+| SVC-100-01 | `PHPExif\MotionPhoto\JpegXmpReader::read(resource $stream, int $file_size): ?JpegHeader` | Walks JPEG markers from SOI to SOS (fill bytes allowed), returns `JpegHeader(?string $xmp, int $image_data_offset)`: the first standard XMP packet (`http://ns.adobe.com/xap/1.0/\0` APP1, namespace stripped) and the offset of the SOS marker, where the `ftyp` scan of FR-100-01 starts. Null when the stream is not a JPEG, a marker is truncated, or a segment length is < 2 or runs past `$file_size`. |
+| SVC-100-02 | `PHPExif\MotionPhoto\MotionPhotoXmp::fromXml(string $xmp): self` | Namespace-aware parse with `ext-xml`; unknown or malformed → all-zero record. |
+| SVC-100-03 | `PHPExif\MotionPhoto\MotionPhotoLocator::locate(string $path): int` | Composes SVC-100-01/02, the `ftyp` check and the scan (FR-100-01). |
+| SVC-100-04 | `PHPExif\MotionPhoto\JpegImageEnd::find(resource $stream, int $from, int $file_size): ?int` | Offset just after the first `FF D9` at or after the SOS marker (byte stuffing keeps it unique inside entropy-coded data); the scan of FR-100-01 starts there, so image data cannot match. Null when the image never ends (PR #4900 review). |
+
+### CLI Commands / Flags
+| ID | Command | Behaviour |
+|----|---------|-----------|
+| CLI-100-01 | `php artisan lychee:extract_motion_photos {limit=100} {tm=600} {--after=} {--album=} {--dry-run} {--reencode}` | FR-100-04. |
+
+### Fixtures & Sample Data
+| ID | Path | Purpose |
+|----|------|---------|
+| FX-100-01 | `tests/Samples/google_motion_photo_v1.jpg` | Synthetic Motion Photo 1.0: existing sample JPEG + short H.264 MP4 + `Container:Directory` XMP. |
+| FX-100-02 | `tests/Samples/google_motion_photo_ultrahdr.jpg` | Synthetic: Primary + GainMap + MotionPhoto items. |
+| FX-100-03 | `tests/Samples/google_motion_photo_pixel.jpg` | Real Pixel 11 Pro Ultra HDR motion photo supplied by the owner (2026-10-17), 4.85 MB, 3064×4080 still + 1753-byte gain map + 2.37 s HEVC 1440×1080 video. Kept at full resolution so the camera layout stays byte-faithful (smaller than the existing 8.2 MB legacy sample). Privacy-stripped with exiftool 13.55: `-GPS:all= -XMP:GPS*= -JUMBF:all= -XMP-GCamera:HDRPlusMakerNote=` (GPS, C2PA manifest, HDR+ debug maker note / extended XMP); gain map + video bytes verified identical to the original. Make, model and capture time remain. |
+| FX-100-04 | `tests/Samples/build_motion_photo_fixtures.php` (or a documented one-off script in the plan) | Rebuilds FX-100-01/02 deterministically. |
+
+### UI States
+| ID | State | Trigger / Expected outcome |
+|----|-------|---------------------------|
+| UI-100-01 | Motion badge | `precomputed.is_livephoto` → badge in the thumbnail badge row. |
+| UI-100-02 | Hover playback | FR-100-03 success path. |
+| UI-100-03 | Playback failed | Video error → back to UI-100-01. |
+
+## Telemetry & Observability
+No new events. Extraction keeps the `photo.extract_google_motion_pictures` span. Locator failures log `Log::warning` with the file basename (no path); FFmpeg failures go through `Handler::reportSafely` as today.
+
+## Documentation Deliverables
+- Roadmap row 100.
+- Knowledge map: php-exif `Reader::read()` → `Extractor` → standalone pipeline; the command.
+- `docs/specs/1-concepts/photos.md` and `docs/specs/4-architecture/request-lifecycle-photo-upload.md`: Motion Photo 1.0 support and the backfill command.
+- ADR-100-01 (motion photo reader in php-exif).
+
+## Spec DSL
+
+```
+domain_objects:
+  - id: DO-100-02
+    name: MotionPhotoXmp
+    fields:
+      - { name: is_motion_photo, type: bool }
+      - { name: item_length, type: int, constraints: ">= 0" }
+      - { name: legacy_offset, type: int, constraints: ">= 0" }
+cli_commands:
+  - id: CLI-100-01
+    command: php artisan lychee:extract_motion_photos
+fixtures:
+  - { id: FX-100-01, path: tests/Samples/google_motion_photo_v1.jpg }
+  - { id: FX-100-02, path: tests/Samples/google_motion_photo_ultrahdr.jpg }
+  - { id: FX-100-03, path: tests/Samples/google_motion_photo_pixel.jpg }
+ui_states:
+  - { id: UI-100-01, description: Motion badge on live photo thumbnails }
+  - { id: UI-100-02, description: Muted looping hover playback }
+  - { id: UI-100-03, description: Playback failure falls back to the still }
+```
+
+## Appendix – Motion Photo 1.0 layout
+
+```
+<JPEG primary: SOI … APP1 XMP … EOI> [Item:Padding] [GainMap JPEG] [MP4 video]
+                                                                    ^ filesize − Item:Length(MotionPhoto)
+XMP namespaces:
+  GCamera   = http://ns.google.com/photos/1.0/camera/         MotionPhoto, MotionPhotoVersion, MotionPhotoPresentationTimestampUs,
+                                                              MicroVideo, MicroVideoOffset (legacy)
+  Container = http://ns.google.com/photos/1.0/container/      Directory → rdf:Seq of Container:Item
+  Item      = http://ns.google.com/photos/1.0/container/item/ Mime, Semantic (Primary|GainMap|MotionPhoto), Length, Padding
+MP4 `ftyp` box: [uint32 size][ 'ftyp' ][major brand ×4] …
+Accepted major brands: isom, iso2, iso4, iso5, iso6, mp41, mp42, avc1, qt␣␣
+
+Observed on a Pixel 11 Pro (FX-100-03), in the standard XMP packet (not the extended one):
+  <Container:Item Item:Mime="image/jpeg" Item:Semantic="Primary"/>                    ← no Item:Length
+  <Container:Item Item:Length="1753" Item:Mime="image/jpeg" Item:Semantic="GainMap"/>
+  <Container:Item Item:Mime="video/mp4" Item:Semantic="MotionPhoto" Item:Length="3725212" Item:Padding="0"/>
+Attributes appear in any order; an absent attribute reads as "not set". exiftool's flattened output
+pads the Primary length as 0, one more reason to read the XMP from the file (ADR-100-01).
+The video is HEVC (`hvc1`, ftyp brand `isom`), so FR-100-03's playback-failure path applies to
+Pixel clips on browsers without HEVC, not only to Apple clips.
+```
diff --git a/docs/specs/4-architecture/features/100-google-motion-photos/tasks.md b/docs/specs/4-architecture/features/100-google-motion-photos/tasks.md
new file mode 100644
index 00000000000..7a7685cfc38
--- /dev/null
+++ b/docs/specs/4-architecture/features/100-google-motion-photos/tasks.md
@@ -0,0 +1,139 @@
+# Feature 100 Tasks – Google Motion Photos
+
+_Status: Complete_  
+_Last updated: 2026-10-17_
+
+> Keep this checklist aligned with the feature plan increments. Stage tests before implementation, record verification commands beside each task, and prefer bite-sized entries (≤90 minutes).
+> **Mark tasks `[x]` immediately** after each one passes verification—do not batch completions. Update the roadmap status when all tasks are done.
+> When referencing requirements, keep feature IDs (`F-`), non-goal IDs (`N-`), and scenario IDs (`S-<NNN>-`) inside the same parentheses immediately after the task title (omit categories that do not apply).
+> When new high- or medium-impact questions arise during execution, add them to the feature's [open-questions.md](open-questions.md) instead of informal notes, and treat a task as fully resolved only once the governing spec sections (requirements/NFR/behaviour/telemetry) and, when required, ADRs under `docs/specs/6-decisions/` reflect the clarified behaviour.
+
+## Checklist
+
+### I1 – Fixtures
+- [x] T-100-01 – Build synthetic Motion Photo 1.0 and Ultra HDR fixtures (F-100-01, S-100-01, S-100-03).  
+  _Intent:_ `tests/Samples/build_motion_photo_fixtures.php` derives `google_motion_photo_v1.jpg` and `google_motion_photo_ultrahdr.jpg` from `google_motion_photo.jpg` (cut the legacy trailer, rewrite XMP with `Container:Directory`, drop `MicroVideoOffset`); constants in `tests/Constants/TestConstants.php`.  
+  _Verification commands:_  
+  - `php tests/Samples/build_motion_photo_fixtures.php`  
+  - `exiftool -a -G1 -XMP-GCamera:all -XMP-GContainer:all tests/Samples/google_motion_photo_v1.jpg tests/Samples/google_motion_photo_ultrahdr.jpg`  
+  _Notes:_ FX-100-01, 02, 04. Each file < 5 MB.
+
+### I2 – JPEG XMP segment reader
+- [x] T-100-02 – Failing `JpegXmpReaderTest` (F-100-01, S-100-10).  
+  _Intent:_ cases: not a JPEG, truncated marker, segment length beyond EOF, XMP APP1 present, absent, non-XMP APP1 before XMP, stop at SOS.  
+  _Verification commands:_ `php artisan test --filter=JpegXmpReaderTest` (red)  
+- [x] T-100-03 – Implement `App\Metadata\MotionPhoto\JpegXmpReader` (F-100-01, S-100-10).  
+  _Verification commands:_  
+  - `php artisan test --filter=JpegXmpReaderTest`  
+  - `make phpstan`  
+  - `vendor/bin/php-cs-fixer fix`  
+  _Notes:_ license header; bounds every read by the file size (ADR-100-01 security).
+
+### I3 – XMP parser
+- [x] T-100-04 – Failing `MotionPhotoXmpTest` (F-100-01, S-100-01, S-100-03, S-100-04, S-100-09, S-100-10).  
+  _Intent:_ v1 directory, Ultra HDR directory (use the exact Pixel XMP from the spec Appendix: `Primary` without `Item:Length`, attributes in varying order), `MotionPhoto=1` without video item, legacy `MicroVideoOffset`, `Item:*` as attributes and as child elements, malformed XML, unrelated XMP.  
+  _Verification commands:_ `php artisan test --filter=MotionPhotoXmpTest` (red)  
+- [x] T-100-05 – Implement `App\Metadata\MotionPhoto\MotionPhotoXmp` readonly record + `fromXml()` (F-100-01).  
+  _Verification commands:_  
+  - `php artisan test --filter=MotionPhotoXmpTest`  
+  - `make phpstan`  
+  - `vendor/bin/php-cs-fixer fix`  
+  _Notes:_ `xml_parser_create_ns` (ext-xml); no new extension (NFR-100-03).
+
+### I4 – Locator
+- [x] T-100-06 – Failing `MotionPhotoLocatorTest` (F-100-01, S-100-04, S-100-05, S-100-08).  
+  _Intent:_ bytes generated in the test: valid declared length; declared length → non-`ftyp` with and without `MotionPhoto=1`; scan hit; scan miss; plain JPEG with trailing `ftyp` and no motion XMP → 0; 20 MB file peak memory delta < 2 MB (NFR-100-02).  
+  _Verification commands:_ `php artisan test --filter=MotionPhotoLocatorTest` (red)  
+- [x] T-100-07 – Implement `App\Metadata\MotionPhoto\MotionPhotoLocator` (F-100-01, NFR-100-02, NFR-100-05).  
+  _Verification commands:_  
+  - `php artisan test --filter=MotionPhotoLocatorTest`  
+  - `make phpstan`  
+  - `vendor/bin/php-cs-fixer fix`  
+
+### I5 – Extractor wiring
+- [x] T-100-08 – Failing upload tests in `BaseImageHandler` (F-100-01, F-100-02, S-100-01, S-100-03, S-100-07, S-100-09).  
+  _Intent:_ `testGoogleMotionPhotoV1Upload`, `testGoogleMotionPhotoUltraHdrUpload`, `testGoogleMotionPhotoNoFfmpegUpload`; legacy sample on the Imagick reader extracts its video.  
+  _Verification commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest` (red for the new cases)  
+- [x] T-100-09 – Call the locator from `Extractor::createFromFile` (F-100-01, F-100-02, S-100-02, S-100-06).  
+  _Intent:_ `image/jpeg` and `micro_video_offset === 0` → `MotionPhotoLocator::locate()`; doc comment of `$micro_video_offset` (DO-100-01).  
+  _Verification commands:_  
+  - `php artisan test --filter=PhotosAddHandlerImagickTest`  
+  - `php artisan test --filter=PhotoAddTest`  
+  - `php artisan test --filter=DownloadTest`  
+  - `make phpstan`  
+  - `vendor/bin/php-cs-fixer fix`  
+  _Notes:_ run every `BaseImageHandler` subclass; existing GMP tests must stay green.
+
+### I6 – Backfill command
+- [x] T-100-10 – Failing `ExtractMotionPhotosTest` (F-100-04, S-100-11, S-100-12, S-100-13, S-100-14).  
+  _Intent:_ extract + idempotent second run, `--dry-run`, `--album` valid/unknown, FFmpeg disabled → exit 1, per-photo failure counted.  
+  _Verification commands:_ `php artisan test --filter=ExtractMotionPhotosTest` (red)  
+- [x] T-100-11 – Implement `lychee:extract_motion_photos` + shared "video path next to original" helper used by `PlaceGoogleMotionVideo` (F-100-04).  
+  _Verification commands:_  
+  - `php artisan test --filter=ExtractMotionPhotosTest`  
+  - `php artisan test --filter=PhotosAddHandlerImagickTest`  
+  - `make phpstan`  
+  - `vendor/bin/php-cs-fixer fix`  
+
+### I7 – Motion badge
+- [x] T-100-12 – `gallery.motion_photo` lang key (23 locales) + badge in v8 `PhotoThumb.vue` and `PhotoThumbVirtual.vue` (F-100-03, S-100-17, UI-100-01, NFR-100-04).  
+  _Verification commands:_  
+  - `php artisan test --filter=LangTest`  
+  - `npx vp check` (non-mutating; format only the changed files with `npx vp fmt <file>`)  
+  - `vp run typecheck`  
+
+### I8 – Hover playback
+- [x] T-100-13 – Failing Vitest `useMotionHover.test.ts` (F-100-03, F-100-05, S-100-15, S-100-16, S-100-17, S-100-18, S-100-19, S-100-20).  
+  _Intent:_ 250 ms intent timer, cancel on leave, `(hover: hover) and (pointer: fine)` gate, reduced-motion gate, error reset; loader called once and only when the URL is missing; playback at max(250 ms, URL arrival); leave before URL → nothing; loader rejection → nothing; no loader injected → URL-present tiles only.  
+  _Verification commands:_ `vp test` (red)  
+- [x] T-100-17 – `motionUrlLoader.ts` injection key + `provide` in the album panel (`AlbumState.loadPhotoDetails`), `Timeline.vue` and `Search.vue` (`loadPhotoDetailsV3`); `Flow.vue` renders no `PhotoThumb`, so it provides none (F-100-05, S-100-19).  
+  _Verification commands:_  
+  - `npx vp check` (non-mutating; format only the changed files with `npx vp fmt <file>`)  
+  - `vp run typecheck`  
+  _Notes:_ numbered after T-100-16 to keep IDs stable; do it before T-100-14.  
+- [x] T-100-14 – Implement `resources/js/v8/composables/photo/useMotionHover.ts` and the overlay `<video muted loop playsinline>` in `PhotoThumb.vue` and `PhotoThumbVirtual.vue` (F-100-03, F-100-05, S-100-15 … 20, NFR-100-01).  
+  _Verification commands:_  
+  - `vp test`  
+  - `npx vp check` (non-mutating; format only the changed files with `npx vp fmt <file>`)  
+  - `vp run typecheck`  
+  - Manual: Chrome, Firefox, Safari desktop + one phone, in album, timeline, search and flow views; network panel shows no `.mov` before hover and one details request on the first hover of a photo.  
+
+### I9 – Real sample
+- [x] T-100-15 – `testGoogleMotionPhotoPixelUpload` with `google_motion_photo_pixel.jpg` (F-100-01, S-100-01, S-100-03).  
+  _Intent:_ upload → live photo with `.mov`; register `SAMPLE_FILE_GMP_PIXEL_IMAGE` in `TestConstants`.  
+  _Verification commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest`  
+  _Notes:_ FX-100-03 placed 2026-10-17 (privacy-stripped, full resolution, see spec Fixtures). Sample is an Ultra HDR file, so it also covers S-100-03 with real camera output.
+
+### I10 – Docs and drift gate
+- [x] T-100-16 – Knowledge map, `1-concepts/photos.md`, `request-lifecycle-photo-upload.md`, roadmap; Implementation Drift Gate report in plan.md.  
+  _Verification commands:_ re-run every command above.
+
+
+### I11 – Move the reader to php-exif (ADR-100-01, Q-100-08)
+- [x] T-100-18 – Port `App\Metadata\MotionPhoto` to php-exif `PHPExif\MotionPhoto`, run it from `Reader::read()`, tests and usage doc (F-100-01, S-100-01 … 10).  
+  _Intent:_ branch `feat/google-motion-photos` on `mlapaglia/php-exif`, from `upstream/master`.  
+  _Verification commands (php-exif):_  
+  - `vendor/bin/phpunit -c phpunit.xml.dist --no-coverage` (464 tests; only the pre-existing `ExifTest::testAdapterConsistency` GPS failure)  
+  - `vendor/bin/phpstan analyze` (level 7)  
+  - `composer check-code-style`, `composer validate-files`  
+  _Notes:_ exiftool tests only pass in the full run: `ExiftoolProcOpenTest` overrides `proc_open` and enables the real one as a side effect.  
+- [x] T-100-19 – Open the php-exif PR; after release, bump `lychee-org/php-exif` in Lychee (owner approval), delete `app/Metadata/MotionPhoto` and its unit tests, drop the locator call in `Extractor`, point `ExtractMotionPhotos` at `PHPExif\MotionPhoto\MotionPhotoLocator` (F-100-01, F-100-04).  
+  _Verification commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest`, `--filter=ExtractMotionPhotosTest`, `make phpstan`.  
+  _Notes:_ php-exif PR opened 2026-10-18: LycheeOrg/php-exif#83, merged and released as 1.5.0 on 2026-10-19. Done 2026-10-19: upstream merged, `lychee-org/php-exif` bumped to `^1.5.0` (owner approval), suites and PHPStan green. Done 2026-10-19 (owner approved the paths): deleted `app/Metadata/MotionPhoto/` (7 files) and `tests/Unit/Metadata/MotionPhoto/` (3 files, now in php-exif), dropped the locator call in `Extractor`, `ExtractMotionPhotos` uses `PHPExif\MotionPhoto\MotionPhotoLocator`; spec, knowledge map and lifecycle doc updated. Suites and PHPStan green.  
+
+
+### I12 – Transcode HEVC clips (Q-100-09)
+- [x] T-100-20 – Failing tests: stored clip is H.264 after uploading the Pixel (HEVC) sample and the v1 (H.264) sample; `--reencode` turns a stored HEVC clip into H.264, `--dry-run` with it changes nothing, Apple pairs are not candidates (F-100-02, F-100-04, S-100-21, S-100-22, S-100-23).  
+  _Verification commands:_ `php artisan test --filter=PhotosAddHandlerImagickTest`, `--filter=ExtractMotionPhotosTest` (red)  
+- [x] T-100-21 – `H264MOVFormat`, codec-based format choice in `GoogleMotionPictureHandler::saveVideoStream()`, `--reencode` in `lychee:extract_motion_photos` (F-100-02, F-100-04).  
+  _Verification commands:_  
+  - all four `BaseImageHandler` subclasses, `ExtractMotionPhotosTest`, `PhotoAddTest`, `DownloadTest`  
+  - `make phpstan`, `vendor/bin/php-cs-fixer fix`  
+
+### I13 – Review follow-up: staged clip write
+- [x] T-100-22 – Failing test `testReencodeKeepsTheStoredClipWhenTheWriteFails` (a directory blocks the staging path), then stage the clip at `<target>.part` and move it over the target in `ExtractMotionPhotos::extract()` (F-100-04, S-100-24).  
+  _Verification commands:_ `php artisan test --filter=ExtractMotionPhotosTest` (red, then 13/13), `vendor/bin/php-cs-fixer fix`, `make phpstan`.  
+
+## Notes / TODOs
+- 2026-10-17: local toolchain installed (PHP 8.4 + imagick, Composer, exiftool, FFmpeg, `vendor/`, `node_modules/`); `vp` is not global, run it as `npx vp …` (e.g. `npx vp check` (never `--fix`: it rewrites unrelated files), `npx vp run typecheck`, `npx vp test`).
+- Image-processing tests skip silently without exiftool/FFmpeg (`assertHasExifToolOrSkip`, `assertHasFFMpegOrSkip`): a "green" run without them proves nothing for T-100-08/09/11/15.
diff --git a/docs/specs/4-architecture/knowledge-map.md b/docs/specs/4-architecture/knowledge-map.md
index d0ea657fe15..81812e0a121 100644
--- a/docs/specs/4-architecture/knowledge-map.md
+++ b/docs/specs/4-architecture/knowledge-map.md
@@ -431,6 +431,10 @@ The main v8 lightbox (`PhotoPanel.vue` → `PhotoBox.vue` with `isZoomEnabled`)
 ### 360° Photos (Feature 082, v8 viewer)
 Detection: `lychee-org/php-exif` 1.4.0 maps XMP-GPano into `Exif` getters (`getProjectionType()`, `getUsePanoramaViewer()`, crop getters) for the exiftool and Imagick readers; the pure `App\Metadata\PanoramaDetector` turns them into a `PanoramaInfo` (equirectangular, viewer flag, crop scaled to the file width, malformed crop → flat), called by `Extractor::createFromFile()` and copied by `HydrateMetadata` while `photos.is_360` is `NULL`. `photos.is_360` is `NULL` until checked; `pano_full_width`/`pano_full_height`/`pano_crop_left`/`pano_crop_top` are `NULL` for full spheres. `lychee:detect_360` checks photos still `NULL`; `PATCH /Photo` takes an optional `is_360` (dispatches `PhotoSaved` on change); `Photo::rotate` rejects 360° photos (422). Exposure: `PreComputedPhotoData::$is_360`, `PhotoResource::$panorama` (`PanoramaResource`), v3 `is_360s[]` (ratios, search) and `panoramas[]` (details). Viewer: `PhotoState.isSphereCapable`/`isSphereView` (the shared `imageViewMode` getter is untouched for v7); the v8 `PhotoBox` (main lightbox only, not during the slideshow) renders the lazy `SphereView.vue`, which wires `resources/js/v8/composables/useSphereViewer.ts` (WebGL2 context, texture from `medium2x`/`medium` then the original when needed, Pointer Events drag/pinch, wheel, context loss, disposal) and registers `PhotoState.zoom_controls` like the flat view. Pure math in `v8/utils/sphere.ts`, GLSL in `v8/utils/sphereShader.ts`, WebGL2 probe in `v8/utils/webgl.ts`. Gestures stop at the canvas; a tap still bubbles to `usePanZoom` and rotates the overlay. `v`/`PhotoHeader` toggle switch to the flat view. ADR-082-01.
 
+### Google Motion Photos (Feature 100)
+Detection: `lychee-org/php-exif` 1.5.0 reads the motion photo itself: `Reader::read()` calls `PHPExif\MotionPhoto\MotionPhotoLocator::locate()` whenever the adapter returned no `MicroVideoOffset` (so every reader, exiftool, Imagick or Native, reports legacy and Motion Photo 1.0 files the same way); the locator walks the JPEG header to the standard XMP, reads `GCamera:MotionPhoto`/`MicroVideoOffset` and the `Container:Item` with `Item:Semantic="MotionPhoto"`, checks a declared length against an MP4 `ftyp` box, and otherwise scans after the primary image's EOI. `Extractor::createFromFile()` just copies `getMicroVideoOffset()` into `Extractor::$micro_video_offset` (bytes from end of file), so the unchanged pipes `ExtractGoogleMotionPictures` → `GoogleMotionPictureHandler` (FFmpeg: H.264 copied into `.mov` with `MOVFormat`, any other codec such as Pixel HEVC transcoded with `H264MOVFormat`, Q-100-09) → `PlaceGoogleMotionVideo` store it in `photos.live_photo_short_path`; `GoogleMotionPictureHandler::videoPathNextTo()` is shared with `lychee:extract_motion_photos` (backfill of JPEGs without a video, `--after`/`--album`/`--dry-run`, `--reencode` to redo stored Google clips, calls the php-exif locator directly). ADR-100-01.
+Grid: v8 `PhotoThumb.vue`/`PhotoThumbVirtual.vue` show a `ThumbBadge` (`lucide:smartphone`, `label` → `title`/`aria-label`) for `precomputed.is_livephoto` and play the clip on hover via `v8/composables/photo/useMotionHover.ts` (250 ms intent, `(hover: hover) and (pointer: fine)` and no reduced motion, `<video>` only after intent, fade-in on `playing`, removed on `error`). v3 tiles get `live_photo_url` on hover through `MOTION_URL_LOADER` (`v8/composables/photo/motionUrlLoader.ts`), provided by `AlbumPanel` (`AlbumState.loadPhotoDetails`), `Timeline.vue` and `Search.vue` (`loadPhotoDetailsV3`); tag and favourites views use v2 payloads that already carry the URL. Lightbox playback is the existing LivePhotosKit path.
+
 ### Library Insights (Feature 085, v8 only)
 `GET /api/v3/Insights` (`InsightsController`, `support:se`) backs the v8 Insights page, which replaces the v8 Statistics page; v7 keeps its Statistics page and `Statistics::getCountsOverTime`, and the unused `Statistics::userSpace` is removed; `Statistics::sizeVariantSpace`, `::albumSpace` (rows now carry the album `id`) and `::totalAlbumSpace` stay for the Insights Storage section, the space diagram, the album selector and the album statistics drawer. `GetInsightsRequest` builds an `InsightsScope` (one owner, every owner for administrators, or one album tree for its owner or an administrator, ADR-085-02) and an `InsightsPeriod` (library, year, inclusive local-date range). `InsightsScopeQuery` applies the scope (owner filter, or `EXISTS` over `photo_album` + `albums._lft` range). `CachedInsights` keys the Laravel cache on scope, period and `InsightsRevision` (count and latest `updated_at` of the scope's photos and albums, one-hour TTL); `ComputeInsights` streams a narrow `photos` projection once (`lazyById`, `EXISTS` album flag, ORIGINAL size variant `filesize`/`width`/`height` via left join), converts capture times with `Helpers\LocalCaptureTime`, narrows Year/Range periods to a UTC window widened by 14 hours, and feeds six accumulators (`Accumulators\Overview`, `Time`, `Device`, `Exposure`, `Format`, `Timeline`) built on pure helpers (`StreakCalculator`, `Distribution`, `ExposureParser`, `DeviceNormaliser`, `AspectRatioClassifier`, `MilestoneFinder`). Albums and people for a period come from keyset/`lazyById` side streams filtered the same way (ADR-085-03). Thumbnail URLs of the time-span photos are resolved per request by `ResolveInsightsThumbs`, outside the cache. Frontend: `resources/js/v8/views/Insights.vue` (scope and album selectors, period toggle, `LycheeLoadingIcon` while loading) with section components in `resources/js/v8/components/insights/` (calendar squares, timeline, focal cones and dimension frames as SVG, sunburst/treemap space diagram), ECharts option builders in `resources/js/v8/utils/insights/options/`, colours from Nuxt UI tokens via `useInsightsTheme`, SE preview data from `usePreviewData().getInsightsData()`.
 
diff --git a/docs/specs/4-architecture/request-lifecycle-photo-upload.md b/docs/specs/4-architecture/request-lifecycle-photo-upload.md
index fa159e1334a..5a54f75cd58 100644
--- a/docs/specs/4-architecture/request-lifecycle-photo-upload.md
+++ b/docs/specs/4-architecture/request-lifecycle-photo-upload.md
@@ -343,6 +343,8 @@ public function add(NativeLocalFile $source_file, ?AbstractAlbum $album, ?int $f
 }
 ```
 
+Google Motion Photos take the standalone path: `Extractor::createFromFile()` reports the length of the embedded video (php-exif `MicroVideoOffset`, filled for every reader by php-exif 1.5+ for legacy and Motion Photo 1.0 files, Feature 100), and the standalone pipes `ExtractGoogleMotionPictures` and `PlaceGoogleMotionVideo` cut it out with FFmpeg and store it next to the original as the photo's live video.
+
 For a comprehensive understanding of the photo creation pipeline, including all pipe interfaces, DTOs, and processing stages, see the **[Photo Actions Documentation](../../../app/Actions/Photo/README.md)** which provides detailed technical documentation about the Action Pattern implementation and pipeline architecture used in photo processing.
 
 ### 11. Metadata Extraction
diff --git a/docs/specs/4-architecture/roadmap.md b/docs/specs/4-architecture/roadmap.md
index 6633db946f8..04192a1639e 100644
--- a/docs/specs/4-architecture/roadmap.md
+++ b/docs/specs/4-architecture/roadmap.md
@@ -6,6 +6,7 @@ High-level planning document for Lychee features and architectural initiatives.
 
 | Feature ID | Name | Status | Priority | Assignee | Started | Updated | Progress |
 |------------|------|--------|----------|----------|---------|---------|----------|
+| 100 | Google Motion Photos | Testing | Medium | mlapaglia | 2026-10-17 | 2026-10-19 | 21/21 tasks. LycheeOrg/Lychee#753, #1283. Motion Photo 1.0 / Ultra HDR / legacy JPEGs import as live photos on every metadata reader: in-house `App\Metadata\MotionPhoto` reader (JPEG marker walk, `ext-xml` XMP, `ftyp` check and scan) feeds `Extractor::$micro_video_offset`; `lychee:extract_motion_photos` backfills (`--after`, `--album`, `--dry-run`); v8 grid motion badge (23 locales) + 250 ms hover playback for every live photo, v3 tiles loading `live_photo_url` on hover through `MOTION_URL_LOADER` (Q-100-07). Q-100-01 … 07 resolved Option A. Fixtures: owner's privacy-stripped Pixel 11 Pro sample + synthetic v1/Ultra HDR builds. Verified: 16 PHP test classes (279 tests), PHPStan, php-cs-fixer, `vp check`, typecheck, Vitest 31, Playwright on Chrome (scratch instance); drift gate passed. Pending: owner check on Firefox/Safari/touch, commit. 2026-10-19: reader moved to php-exif 1.5.0 (#83, ADR-100-01), Lychee bumped and its in-house copy removed (T-100-19); HEVC clips transcoded to H.264, `--reencode` for stored ones (Q-100-09). See `features/100-google-motion-photos/`. |
 | 099 | PDF Photo View | Testing | Medium | ildyria | 2026-10-17 | 2026-10-17 | 4/4 tasks. Wheel no longer changes photo over a PDF (Q-099-01 A); dock hidden for PDFs, move/delete in the photo header (Q-099-02 B); v8 only (Q-099-03 A). Escape closes the photo edit modal (FR-099-04). See `features/099-pdf-photo-view/`. |
 | 098 | Tag Albums Category | Testing | Medium | ildyria | 2026-10-17 | 2026-10-17 | 7/7 tasks (T-098-06: PR #4895 review, virtual panel headers stay visible next to Featured/shared albums. T-098-07: 1rem gap between consecutive v8 virtual panels). Settings `TA_separate_category` and `PA_separate_category` (Smart Albums, off by default) move tag albums and person albums out of the Smart Albums panel into their own "Tag Albums" / "Person Albums" panels directly below it (Q-098-01 A, Q-098-02 C), in v7 and v8 (Q-098-03 A). Exposed via `RootConfig` (v2 `/Albums`, v3 `/Albums/root/config`), split client-side in `AlbumsState` (no new query). Verified: `RootConfigSeparateCategoriesTest` (4), `AlbumRootConfigV3Test` (5), `LangTest`, php-cs-fixer, phpstan, `vp check`, `vp run typecheck`, browser check on a scratch instance (v8 struct-of-array and v7 v2 paths, all four flag combinations). Awaiting commit. See `features/098-tag-albums-category/`. |
 | 097 | Open Album in New Tab | Testing | Medium | ildyria | 2026-10-17 | 2026-10-17 | 7/7 tasks. `Open in a new tab` is the first entry of the single-album context menu in v7 and v8 (shared helper `composables/album/openAlbumInNewTab.ts`: the tile's own route through `useAlbumRoute`, `window.open(href, "_blank", "noopener")`), followed by a divider only when an action is accessible; label in 23 locales; the v8 root listing's menu opens for guests on public albums (`selectableAlbums` guard, FR-097-06). Middle click verified in both trees: tiles are `router-link` anchors and the drag selection ignores non-left buttons (no code). First Vitest unit tests of the repository (`vp test`, 13 tests, `test` block in `vite.config.ts`, no new dependency, Q-097-02). Verified: `vp check`, `vp run typecheck`, `vp test`, `LangTest`, `check_translations.php`; Playwright on a scratch instance: v8 12/12 + list 3/3, v7 (flag off) 12/12, v7 (flag on) 8/8 owner + list 3/3. Q-097-01 (both trees) and Q-097-02 (unit tests kept) resolved Option A 2026-10-17. Pending: owner browser check, `vp test` step in CI. See `features/097-open-album-new-tab/`. |
diff --git a/docs/specs/6-decisions/ADR-100-01-motion-photo-reader-in-php-exif.md b/docs/specs/6-decisions/ADR-100-01-motion-photo-reader-in-php-exif.md
new file mode 100644
index 00000000000..5660b52ff1f
--- /dev/null
+++ b/docs/specs/6-decisions/ADR-100-01-motion-photo-reader-in-php-exif.md
@@ -0,0 +1,55 @@
+# ADR-100-01: Motion photo reader in php-exif
+
+- **Status:** Accepted
+- **Date:** 2026-10-18
+- **Related features/specs:** Feature 100 (docs/specs/4-architecture/features/100-google-motion-photos/spec.md)
+- **Related open questions:** Q-100-08, Q-100-02
+
+## Context
+
+Lychee reads photo metadata through `lychee-org/php-exif`, with the exiftool, Imagick, FFprobe or Native reader chosen in `App\Metadata\Extractor`. Google Motion Photos embed an MP4 after the JPEG and describe it in XMP:
+- The legacy format (Android ≤ 10) declares `GCamera:MicroVideoOffset`. php-exif 1.4.0 maps it only for the exiftool reader, so Imagick and Native installs never extract the video.
+- The Motion Photo 1.0 format (Android 11+) declares `GCamera:MotionPhoto` and a `Container:Directory` sequence of items with `Item:Semantic` and `Item:Length`. exiftool flattens the directory into parallel per-field lists that misalign when an item has no `Item:Length` (the Pixel's `Primary` item), and the Native and Imagick adapters do not expose it at all. Mapping the tags per adapter is therefore not enough: the video has to be located from the file itself.
+
+On PR #4900 the maintainers asked for this support to live in `lychee-org/php-exif` rather than in Lychee.
+
+## Decision
+
+The reader lives in php-exif as `PHPExif\MotionPhoto\*` (`JpegXmpReader`, `JpegHeader`, `JpegImageEnd`, `FtypBox`, `MotionPhotoXmp`, `MotionPhotoXmpHandler`, `MotionPhotoLocator::locate(string $path): int`), released in php-exif 1.5.0 (LycheeOrg/php-exif#83):
+- It walks the JPEG markers to the standard XMP APP1 packet and parses it with `ext-xml`.
+- A declared length (the `Container:Item` with `Item:Semantic="MotionPhoto"`, else `GCamera:MicroVideoOffset`) is accepted only when an MP4 `ftyp` box sits at the computed start.
+- Otherwise, when `MotionPhoto="1"`, it scans for the first plausible `ftyp` box after the primary image's end-of-image marker, so compressed image data cannot match.
+
+`Reader::read()` calls it whenever the adapter reports no `MicroVideoOffset` and stores the video length there, so every adapter reports legacy and Motion Photo 1.0 files the same way. Lychee's `Extractor` reads `getMicroVideoOffset()` as before, with no motion photo special case, and `lychee:extract_motion_photos` calls `PHPExif\MotionPhoto\MotionPhotoLocator` directly.
+
+## Consequences
+
+### Positive
+- Motion photos work on every reader, not only exiftool.
+- Metadata reading stays in one library; other php-exif users get motion photos.
+- One place handles the legacy, Motion Photo 1.0 and Ultra HDR (`GainMap`) layouts.
+
+### Negative
+- Two-repository change: php-exif release, then a php-exif bump in Lychee (`^1.5.0`, owner approval 2026-10-19).
+- The `ftyp` scan is a heuristic, limited to files that declare `MotionPhoto="1"`.
+
+## Alternatives Considered
+
+- **Keep the reader in Lychee** (`App\Metadata\MotionPhoto`, the first answer to Q-100-02): no cross-repository coordination, but against the maintainers' request and splits metadata reading between the library and the app.
+- **Map the tags per adapter:** exiftool's flattened lists misalign on real Pixel files, Native and Imagick do not expose the directory.
+- **`ftyp` scan only:** simplest, but ignores the declared length and is more prone to false positives.
+
+## Security / Privacy Impact
+
+- Parses untrusted uploaded bytes: the reader bounds every segment length by the file size, stops at SOS, and uses `ext-xml`'s SAX parser, which does not resolve external entities (no XXE).
+- No new endpoint or stored data; the extracted video follows the existing live photo storage and access rules.
+
+## Operational Impact
+
+- One header read per JPEG (stops at SOS, typically < 100 KB) and, only for files declaring `MotionPhoto="1"` without a valid length, a chunked scan in constant memory.
+- Failures log a warning and the photo imports as a still.
+
+## Links
+
+- Related spec sections: `docs/specs/4-architecture/features/100-google-motion-photos/spec.md#functional-requirements` (FR-100-01), NFR-100-02, NFR-100-03
+- Related issues / PRs: LycheeOrg/php-exif#83, LycheeOrg/Lychee#4900 (comment 6251741379), #753, #1283
diff --git a/docs/specs/6-decisions/README.md b/docs/specs/6-decisions/README.md
index c138f753324..7ad63e19f0d 100644
--- a/docs/specs/6-decisions/README.md
+++ b/docs/specs/6-decisions/README.md
@@ -26,6 +26,7 @@ Numbering convention: new ADRs use `ADR-<NNN>-<YY>`, where `<NNN>` is the featur
 | [ADR-092-01](ADR-092-01-granularity-free-bucket-keys.md) | Accepted | Granularity-free bucket keys, bucket ids derived at read time |
 | [ADR-092-02](ADR-092-02-capture-local-photo-date-buckets.md) | Accepted | Photo capture dates bucketed in the zone the photo was taken in |
 | [ADR-096-01](ADR-096-01-vite-plus-single-frontend-toolchain.md) | Accepted | Vite+ (`vp`: Vite 8, Oxlint, Oxfmt, `vp staged`) as the single frontend toolchain; `vue-tsc` and the npm bootstrap kept |
+| [ADR-100-01](ADR-100-01-motion-photo-reader-in-php-exif.md) | Accepted | The Google Motion Photo reader (legacy `MicroVideoOffset` and Motion Photo 1.0 `Container:Directory`) lives in `lychee-org/php-exif` (`PHPExif\MotionPhoto`, run by `Reader::read()` for every adapter, result in `MicroVideoOffset`) |
 
 ## Templates
 
diff --git a/lang/ar/gallery.php b/lang/ar/gallery.php
index 0d06e317780..fb1f4e2a474 100644
--- a/lang/ar/gallery.php
+++ b/lang/ar/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'عنصر نائب للصورة منخفضة الجودة',
     'thumbnail' => 'مصغر الصورة',
     'live_video' => 'جزء الفيديو من الصورة الحية',
+    'motion_photo' => 'صورة متحركة',
     'download_raw' => 'تنزيل RAW',
     'download_album' => 'اختر دقة الصورة لأرشيف ZIP للألبوم. إذا لم تكن الصورة تحتوي على النوع المحدد، سيتم استخدام النسخة الأصلية.',
     'downloading_part' => 'جارٍ تنزيل الجزء :current / :total',
diff --git a/lang/bg/gallery.php b/lang/bg/gallery.php
index fda7c03971c..16cf3716824 100644
--- a/lang/bg/gallery.php
+++ b/lang/bg/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Заместител с ниско качество',
     'thumbnail' => 'Миниатюра на снимка',
     'live_video' => 'Видео част от live-photo',
+    'motion_photo' => 'Движеща се снимка',
     'download_raw' => 'Изтегли RAW',
     'download_album' => 'Изберете разделителна способност на изображенията за ZIP архива на албума. Ако снимка няма избрания вариант, ще бъде използван оригиналът.',
     'downloading_part' => 'Изтегляне на част :current / :total',
diff --git a/lang/cz/gallery.php b/lang/cz/gallery.php
index bb27e8d07cd..926760283ea 100644
--- a/lang/cz/gallery.php
+++ b/lang/cz/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Zástupný obrázek nízké kvality',
     'thumbnail' => 'Miniatura fotografie',
     'live_video' => 'Video část live-photo',
+    'motion_photo' => 'Pohyblivá fotka',
     'download_raw' => 'Stáhnout RAW',
     'download_album' => 'Vyberte rozlišení obrázků pro ZIP archiv alba. Pokud fotografie nemá vybranou variantu, bude použit originál.',
     'downloading_part' => 'Stahování části :current / :total',
diff --git a/lang/de/gallery.php b/lang/de/gallery.php
index 4022bb918b9..40d06362121 100644
--- a/lang/de/gallery.php
+++ b/lang/de/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Platzhalter für Bilder niedriger Qualität',
     'thumbnail' => 'Foto-Miniaturansicht',
     'live_video' => 'Videoteil des Live-Fotos',
+    'motion_photo' => 'Bewegtes Foto',
     'download_raw' => 'RAW Herunterladen',
     'download_album' => 'Wählen Sie die Bildauflösung für das Album-ZIP-Archiv. Falls ein Foto die gewählte Variante nicht hat, wird das Original verwendet.',
     'downloading_part' => 'part :current / :total Herunterladen',
diff --git a/lang/el/gallery.php b/lang/el/gallery.php
index 992d1b2524a..1152c4bf88d 100644
--- a/lang/el/gallery.php
+++ b/lang/el/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Εικόνα κράτησης θέσης χαμηλής ποιότητας',
     'thumbnail' => 'Μικρογραφία φωτογραφίας',
     'live_video' => 'Τμήμα βίντεο της live φωτογραφίας',
+    'motion_photo' => 'Φωτογραφία με κίνηση',
     'download_raw' => 'Λήψη RAW',
     'download_album' => 'Επιλέξτε την ανάλυση εικόνας για το αρχείο ZIP του άλμπουμ. Αν μια φωτογραφία δεν διαθέτει την επιλεγμένη παραλλαγή, θα χρησιμοποιηθεί η αρχική.',
     'downloading_part' => 'Λήψη τμήματος :current / :total',
diff --git a/lang/en/gallery.php b/lang/en/gallery.php
index ca739395924..9e7dd5bc8f5 100644
--- a/lang/en/gallery.php
+++ b/lang/en/gallery.php
@@ -37,6 +37,7 @@
     'placeholder' => 'Low Quality Image Placeholder',
     'thumbnail' => 'Photo thumbnail',
     'live_video' => 'Video part of live-photo',
+    'motion_photo' => 'Motion photo',
     'download_raw' => 'Download RAW',
     'download_album' => 'Select the image resolution for the album ZIP archive. If a photo does not have the selected variant, the original will be used instead.',
     'downloading_part' => 'Downloading part :current / :total',
diff --git a/lang/es/gallery.php b/lang/es/gallery.php
index abb4039d572..5fa860efe20 100644
--- a/lang/es/gallery.php
+++ b/lang/es/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Espacio para imagen de baja calidad',
     'thumbnail' => 'Miniatura de la foto',
     'live_video' => 'Vídeo parte de foto en directo',
+    'motion_photo' => 'Foto en movimiento',
     'download_raw' => 'Descargar RAW',
     'download_album' => 'Seleccione la resolución de imagen para el archivo ZIP del álbum. Si una foto no tiene la variante seleccionada, se usará la original.',
     'downloading_part' => 'Descargando parte :current / :total',
diff --git a/lang/fa/gallery.php b/lang/fa/gallery.php
index 70bff86a30c..f495d01da35 100644
--- a/lang/fa/gallery.php
+++ b/lang/fa/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'تصویر با کیفیت پایین',
     'thumbnail' => 'تصویر کوچک',
     'live_video' => 'بخش ویدئویی لایو-فوتو',
+    'motion_photo' => 'عکس متحرک',
     'download_raw' => 'دانلود RAW',
     'download_album' => 'رزولوشن تصویر را برای فایل ZIP آلبوم انتخاب کنید. اگر عکسی نوع انتخاب‌شده را نداشته باشد، از نسخه اصلی استفاده می‌شود.',
     'downloading_part' => 'در حال دانلود بخش :current از :total',
diff --git a/lang/fr/gallery.php b/lang/fr/gallery.php
index 89fdc32c45d..127c85695a6 100644
--- a/lang/fr/gallery.php
+++ b/lang/fr/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Image de basse qualité (LQIP)',
     'thumbnail' => 'Vignette de la photo',
     'live_video' => 'Partie vidéo d’une live-photo',
+    'motion_photo' => 'Photo animée',
     'download_raw' => 'Télécharger RAW',
     'download_album' => 'Sélectionnez la résolution d\'image pour l\'archive ZIP de l\'album. Si une photo ne possède pas la variante sélectionnée, l\'originale sera utilisée.',
     'downloading_part' => 'Téléchargement de la partie :current / :total',
diff --git a/lang/hu/gallery.php b/lang/hu/gallery.php
index 7a67c29b5ff..384c6f686b4 100644
--- a/lang/hu/gallery.php
+++ b/lang/hu/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Alacsony minőségű helyőrző kép',
     'thumbnail' => 'Fénykép miniatűr',
     'live_video' => 'Az élő fotó videó része',
+    'motion_photo' => 'Mozgó fotó',
     'download_raw' => 'RAW letöltése',
     'download_album' => 'Válassza ki a képfelbontást az album ZIP archívumához. Ha egy fotónak nincs meg a kiválasztott változata, az eredeti lesz használva.',
     'downloading_part' => 'Rész letöltése: :current / :total',
diff --git a/lang/it/gallery.php b/lang/it/gallery.php
index b132209e9c2..807fffa48e7 100644
--- a/lang/it/gallery.php
+++ b/lang/it/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Segnaposto immagine a bassa qualità',
     'thumbnail' => 'Miniatura della foto',
     'live_video' => 'Parte video della live photo',
+    'motion_photo' => 'Foto in movimento',
     'download_raw' => 'Scarica RAW',
     'download_album' => 'Seleziona la risoluzione dell\'immagine per l\'archivio ZIP dell\'album. Se una foto non ha la variante selezionata, verrà utilizzato l\'originale.',
     'downloading_part' => 'Download della parte :current / :total',
diff --git a/lang/ja/gallery.php b/lang/ja/gallery.php
index 51461acb0e8..739469afebb 100644
--- a/lang/ja/gallery.php
+++ b/lang/ja/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => '低画質画像プレースホルダー',
     'thumbnail' => '写真のサムネイル',
     'live_video' => 'ライブフォトの動画部分',
+    'motion_photo' => 'モーションフォト',
     'download_raw' => 'RAWをダウンロード',
     'download_album' => 'アルバムZIPアーカイブの画像解像度を選択してください。選択した種類がない写真にはオリジナルが使用されます。',
     'downloading_part' => 'パート :current / :total をダウンロード中',
diff --git a/lang/nl/gallery.php b/lang/nl/gallery.php
index 75ff3846598..9e13b5ae5aa 100644
--- a/lang/nl/gallery.php
+++ b/lang/nl/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Laagkwaliteitsafbeelding Placeholder',
     'thumbnail' => 'Foto miniatuur',
     'live_video' => 'Videodeel van live-foto',
+    'motion_photo' => 'Bewegende foto',
     'download_raw' => 'RAW downloaden',
     'download_album' => 'Selecteer de beeldresolutie voor het album-ZIP-archief. Als een foto de geselecteerde variant niet heeft, wordt het origineel gebruikt.',
     'downloading_part' => 'Deel :current van :total downloaden',
diff --git a/lang/no/gallery.php b/lang/no/gallery.php
index 340055a7cc0..1015e955912 100644
--- a/lang/no/gallery.php
+++ b/lang/no/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Plassholder for lavkvalitetsbilde',
     'thumbnail' => 'Bildeminiatyr',
     'live_video' => 'Videodel av live-bilde',
+    'motion_photo' => 'Bevegelsesbilde',
     'download_raw' => 'Last ned RAW',
     'download_album' => 'Velg bildeoppløsning for albumets ZIP-arkiv. Hvis et bilde ikke har den valgte varianten, brukes originalen i stedet.',
     'downloading_part' => 'Laster ned del :current / :total',
diff --git a/lang/pl/gallery.php b/lang/pl/gallery.php
index 45537720312..e4fdf806af2 100644
--- a/lang/pl/gallery.php
+++ b/lang/pl/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Obraz zastępczy o niskiej jakości',
     'thumbnail' => 'Miniatura zdjęcia',
     'live_video' => 'Część wideo zdjęcia na żywo',
+    'motion_photo' => 'Ruchome zdjęcie',
     'download_raw' => 'Pobierz RAW',
     'download_album' => 'Wybierz rozdzielczość obrazów dla archiwum ZIP albumu. Jeśli zdjęcie nie ma wybranego wariantu, zostanie użyty oryginał.',
     'downloading_part' => 'Pobieranie części :current / :total',
diff --git a/lang/pt/gallery.php b/lang/pt/gallery.php
index 70474fc8363..55131005700 100644
--- a/lang/pt/gallery.php
+++ b/lang/pt/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Marcador de imagem de baixa qualidade',
     'thumbnail' => 'Miniatura da foto',
     'live_video' => 'Parte de vídeo da live photo',
+    'motion_photo' => 'Foto em movimento',
     'download_raw' => 'Transferir RAW',
     'download_album' => 'Selecione a resolução da imagem para o arquivo ZIP do álbum. Se uma foto não tiver a variante selecionada, a original será usada.',
     'downloading_part' => 'A transferir a parte :current / :total',
diff --git a/lang/ru/gallery.php b/lang/ru/gallery.php
index 23bf96693ea..8b34deea0ae 100644
--- a/lang/ru/gallery.php
+++ b/lang/ru/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Заглушка изображения низкого качества',
     'thumbnail' => 'Миниатюра фото',
     'live_video' => 'Часть видео с живого фото',
+    'motion_photo' => 'Фото с движением',
     'download_raw' => 'Скачать RAW',
     'download_album' => 'Выберите разрешение изображений для ZIP-архива альбома. Если у фотографии нет выбранного варианта, будет использован оригинал.',
     'downloading_part' => 'Скачивание части :current / :total',
diff --git a/lang/sk/gallery.php b/lang/sk/gallery.php
index 0436c79bd2b..ec80caf4698 100644
--- a/lang/sk/gallery.php
+++ b/lang/sk/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Zástupný obrázok nízkej kvality',
     'thumbnail' => 'Miniatúra fotografie',
     'live_video' => 'Video časť živej fotografie',
+    'motion_photo' => 'Pohyblivá fotka',
     'download_raw' => 'Stiahnuť RAW',
     'download_album' => 'Vyberte rozlíšenie obrázkov pre ZIP archív albumu. Ak fotografia nemá vybranú variantu, použije sa originál.',
     'downloading_part' => 'Sťahovanie časti :current / :total',
diff --git a/lang/sv/gallery.php b/lang/sv/gallery.php
index 5de3b709d5e..9b3c32c2e1c 100644
--- a/lang/sv/gallery.php
+++ b/lang/sv/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Platshållarbild i låg kvalitet',
     'thumbnail' => 'Fotominiatyr',
     'live_video' => 'Videodel av livefoto',
+    'motion_photo' => 'Rörligt foto',
     'download_raw' => 'Ladda ner RAW',
     'download_album' => 'Välj bildupplösning för albumets ZIP-arkiv. Om ett foto saknar den valda varianten används originalet istället.',
     'downloading_part' => 'Laddar ner del :current / :total',
diff --git a/lang/tr/gallery.php b/lang/tr/gallery.php
index a8b3e8e3b15..e1c8ff6412b 100644
--- a/lang/tr/gallery.php
+++ b/lang/tr/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Düşük Kaliteli Görüntü Yer Tutucusu',
     'thumbnail' => 'Fotoğraf küçük resmi',
     'live_video' => 'Canlı fotoğrafın video kısmı',
+    'motion_photo' => 'Hareketli fotoğraf',
     'download_raw' => 'RAW İndir',
     'download_album' => 'Albüm ZIP arşivi için görüntü çözünürlüğünü seçin. Bir fotoğrafta seçilen boyut yoksa, bunun yerine orijinali kullanılır.',
     'downloading_part' => 'Parça indiriliyor :current / :total',
diff --git a/lang/vi/gallery.php b/lang/vi/gallery.php
index 79843e37668..66ac9e1d1c1 100644
--- a/lang/vi/gallery.php
+++ b/lang/vi/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => 'Ảnh giữ chỗ chất lượng thấp',
     'thumbnail' => 'Ảnh thu nhỏ',
     'live_video' => 'Phần video của ảnh động (live photo)',
+    'motion_photo' => 'Ảnh chuyển động',
     'download_raw' => 'Tải xuống RAW',
     'download_album' => 'Chọn độ phân giải hình ảnh cho tệp ZIP album. Nếu ảnh không có biến thể đã chọn, ảnh gốc sẽ được sử dụng.',
     'downloading_part' => 'Đang tải xuống phần :current / :total',
diff --git a/lang/zh_CN/gallery.php b/lang/zh_CN/gallery.php
index 3790ead179b..789e5d319a4 100644
--- a/lang/zh_CN/gallery.php
+++ b/lang/zh_CN/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => '低质量图片占位符',
     'thumbnail' => '照片缩略图',
     'live_video' => '实况照片视频部分',
+    'motion_photo' => '动态照片',
     'download_raw' => '下载 RAW',
     'download_album' => '选择相册ZIP压缩包的图片分辨率。如果照片没有所选的版本，将使用原始版本。',
     'downloading_part' => '正在下载第 :current / :total 部分',
diff --git a/lang/zh_TW/gallery.php b/lang/zh_TW/gallery.php
index a7e67ea1c5a..85f69004aef 100644
--- a/lang/zh_TW/gallery.php
+++ b/lang/zh_TW/gallery.php
@@ -36,6 +36,7 @@
     'placeholder' => '低畫質圖片預留位置',
     'thumbnail' => '照片縮圖',
     'live_video' => '原況照片的影片部分',
+    'motion_photo' => '動態相片',
     'download_raw' => '下載 RAW',
     'download_album' => '選擇相簿ZIP壓縮檔的圖片解析度。如果照片沒有所選的版本，將使用原始版本。',
     'downloading_part' => '正在下載第 :current / :total 部分',
diff --git a/resources/js/v8/components/gallery/albumModule/AlbumPanel.vue b/resources/js/v8/components/gallery/albumModule/AlbumPanel.vue
index 4917b66f52d..cb4a4d4ecb8 100644
--- a/resources/js/v8/components/gallery/albumModule/AlbumPanel.vue
+++ b/resources/js/v8/components/gallery/albumModule/AlbumPanel.vue
@@ -182,7 +182,8 @@
 	</UMain>
 </template>
 <script setup lang="ts">
-import { computed, ref, ComponentPublicInstance } from "vue";
+import { computed, ref, ComponentPublicInstance, provide } from "vue";
+import { MOTION_URL_LOADER } from "@/v8/composables/photo/motionUrlLoader";
 import AlbumThumbPanel from "@/v8/components/gallery/albumModule/AlbumThumbPanel.vue";
 import AlbumThumbPanelVirtual from "@/v8/components/gallery/albumModule/Virtualized/AlbumThumbPanelVirtual.vue";
 import PhotoThumbPanel from "@/v8/components/gallery/albumModule/PhotoThumbPanel.vue";
@@ -238,6 +239,8 @@ const props = defineProps<{
 
 const userStore = useUserStore();
 const albumStore = useAlbumStore();
+// Feature 100: thumbnails fetch their live photo video URL on hover.
+provide(MOTION_URL_LOADER, (ids) => albumStore.loadPhotoDetails(ids));
 const photosStore = usePhotosStore();
 const catalogStore = useCatalogStore();
 const albumsStore = useAlbumsStore();
diff --git a/resources/js/v8/components/gallery/albumModule/Virtualized/PhotoThumbVirtual.vue b/resources/js/v8/components/gallery/albumModule/Virtualized/PhotoThumbVirtual.vue
index 392f06d1bc6..8e4c346cebe 100644
--- a/resources/js/v8/components/gallery/albumModule/Virtualized/PhotoThumbVirtual.vue
+++ b/resources/js/v8/components/gallery/albumModule/Virtualized/PhotoThumbVirtual.vue
@@ -9,7 +9,8 @@
 		:style="boxStyle"
 		:data-photo-id="props.photo.id"
 		data-drag-select-start="true"
-		@mouseenter="prefetchFaces"
+		@mouseenter="onMouseEnter"
+		@mouseleave="stopMotion"
 	>
 		<span class="thumbimg block relative w-full h-full border-none overflow-hidden">
 			<Thumb
@@ -19,6 +20,21 @@
 				:photo-id="props.photo.id"
 				type="small2x"
 			/>
+			<video
+				v-if="motionSrc"
+				:src="motionSrc"
+				class="absolute top-0 left-0 w-full h-full object-cover pointer-events-none transition-opacity duration-300"
+				:class="isMotionPlaying ? 'opacity-100' : 'opacity-0'"
+				muted
+				loop
+				autoplay
+				playsinline
+				disablepictureinpicture
+				aria-hidden="true"
+				data-overlay="false"
+				@playing="onMotionPlaying"
+				@error="onMotionError"
+			/>
 		</span>
 		<div
 			v-if="props.isSelected && is_selection_overlay_enabled"
@@ -85,6 +101,12 @@
 			<ThumbBadge v-if="showHeaderIdFlag" class="bg-slate-400 hidden sm:block" pi="lucide:image" />
 			<ThumbBadge v-if="showValidatedFlag" class="bg-neutral-800" border-color="border-none" pi="lucide:shield text-amber-500 text-shadow-md" />
 			<ThumbBadge v-if="props.photo.precomputed.is_360" class="bg-sky-700" pi="lucide:rotate-3d" />
+			<ThumbBadge
+				v-if="props.photo.precomputed.is_livephoto"
+				class="bg-purple-700"
+				pi="lucide:smartphone"
+				:label="$t('gallery.motion_photo')"
+			/>
 		</div>
 		<!-- Rating Overlay -->
 		<ThumbRatingOverlay v-if="rating_album_view_mode !== 'never' && props.photo.rating !== null" :rating="props.photo.rating" />
@@ -116,7 +138,9 @@
  * (those live in `PhotoListItemVirtual.vue`/its own effective no-op, see
  * that file and `adaptPhotoTile.ts`'s own doc comment — NG11/Q-065-06).
  */
-import { computed, ref, toRef } from "vue";
+import { computed, inject, ref, toRef } from "vue";
+import { useMotionHover } from "@/v8/composables/photo/useMotionHover";
+import { MOTION_URL_LOADER } from "@/v8/composables/photo/motionUrlLoader";
 import MiniIcon from "@/v8/components/icons/MiniIcon.vue";
 import ThumbBadge from "@/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue";
 import ThumbRatingOverlay from "@/v8/components/gallery/albumModule/thumbs/ThumbRatingOverlay.vue";
@@ -199,6 +223,22 @@ function prefetchFaces() {
 	// Intentional no-op — see this component's own doc comment (NG11/Q-065-06).
 }
 
+// Feature 100: live photos play their motion on hover; v3 tiles fetch the
+// video URL through the loader their view provides.
+const {
+	videoSrc: motionSrc,
+	isPlaying: isMotionPlaying,
+	onEnter: startMotion,
+	onLeave: stopMotion,
+	onPlaying: onMotionPlaying,
+	onError: onMotionError,
+} = useMotionHover(() => props.photo, inject(MOTION_URL_LOADER, undefined));
+
+function onMouseEnter() {
+	prefetchFaces();
+	startMotion();
+}
+
 const isFavourite = computed(() => favourites.getPhotoIds.includes(props.photo.id));
 const isInBasket = computed(
 	() => orderStore?.order?.items?.some((item: App.Http.Resources.Shop.OrderItemResource) => item.photo_id === props.photo.id) ?? false,
diff --git a/resources/js/v8/components/gallery/albumModule/thumbs/PhotoThumb.vue b/resources/js/v8/components/gallery/albumModule/thumbs/PhotoThumb.vue
index c56e97afa2d..9b97bc390d8 100644
--- a/resources/js/v8/components/gallery/albumModule/thumbs/PhotoThumb.vue
+++ b/resources/js/v8/components/gallery/albumModule/thumbs/PhotoThumb.vue
@@ -10,7 +10,8 @@
 		:data-height="props.photo.size_variants.original?.height"
 		:data-photo-id="props.photo.id"
 		data-drag-select-start="true"
-		@mouseenter="prefetchFaces"
+		@mouseenter="onMouseEnter"
+		@mouseleave="stopMotion"
 	>
 		<span
 			class="thumbimg relative w-full h-full border-none overflow-hidden"
@@ -40,6 +41,21 @@
 				loading="lazy"
 				@load="onImageLoad"
 			/>
+			<video
+				v-if="motionSrc"
+				:src="motionSrc"
+				class="absolute top-0 left-0 w-full h-full object-cover pointer-events-none transition-opacity duration-300"
+				:class="isMotionPlaying ? 'opacity-100' : 'opacity-0'"
+				muted
+				loop
+				autoplay
+				playsinline
+				disablepictureinpicture
+				aria-hidden="true"
+				data-overlay="false"
+				@playing="onMotionPlaying"
+				@error="onMotionError"
+			/>
 		</span>
 		<div
 			v-if="props.isSelected && is_selection_overlay_enabled"
@@ -106,13 +122,21 @@
 			<ThumbBadge v-if="showHeaderIdFlag" class="bg-slate-400 hidden sm:block" pi="lucide:image" />
 			<ThumbBadge v-if="showValidatedFlag" class="bg-neutral-800" border-color="border-none" pi="lucide:shield text-amber-500 text-shadow-md" />
 			<ThumbBadge v-if="props.photo.precomputed.is_360" class="bg-sky-700" pi="lucide:rotate-3d" />
+			<ThumbBadge
+				v-if="props.photo.precomputed.is_livephoto"
+				class="bg-purple-700"
+				pi="lucide:smartphone"
+				:label="$t('gallery.motion_photo')"
+			/>
 		</div>
 		<!-- Rating Overlay -->
 		<ThumbRatingOverlay v-if="rating_album_view_mode !== 'never' && props.photo.rating !== null" :rating="props.photo.rating" />
 	</a>
 </template>
 <script setup lang="ts">
-import { computed, ref, toRef, watch } from "vue";
+import { computed, inject, ref, toRef, watch } from "vue";
+import { useMotionHover } from "@/v8/composables/photo/useMotionHover";
+import { MOTION_URL_LOADER } from "@/v8/composables/photo/motionUrlLoader";
 import MiniIcon from "@/v8/components/icons/MiniIcon.vue";
 import ThumbBadge from "@/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue";
 import ThumbRatingOverlay from "@/v8/components/gallery/albumModule/thumbs/ThumbRatingOverlay.vue";
@@ -192,6 +216,22 @@ function prefetchFaces() {
 	}
 }
 
+// Feature 100: live photos play their motion on hover; v3 tiles fetch the
+// video URL through the loader their view provides.
+const {
+	videoSrc: motionSrc,
+	isPlaying: isMotionPlaying,
+	onEnter: startMotion,
+	onLeave: stopMotion,
+	onPlaying: onMotionPlaying,
+	onError: onMotionError,
+} = useMotionHover(() => props.photo, inject(MOTION_URL_LOADER, undefined));
+
+function onMouseEnter() {
+	prefetchFaces();
+	startMotion();
+}
+
 const isFavourite = computed(() => favourites.getPhotoIds.includes(props.photo.id));
 const isInBasket = computed(
 	() => orderStore?.order?.items?.some((item: App.Http.Resources.Shop.OrderItemResource) => item.photo_id === photoId.value) ?? false,
diff --git a/resources/js/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue b/resources/js/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue
index 5538e440c50..6450be36509 100644
--- a/resources/js/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue
+++ b/resources/js/v8/components/gallery/albumModule/thumbs/ThumbBadge.vue
@@ -1,5 +1,11 @@
 <template>
-	<span class="badge inline-block ltr:ml-1 rtl:mr-1 px-2 pt-2 pb-1 rounded-md rounded-t-none text-white text-center" :class="spanClass">
+	<span
+		class="badge inline-block ltr:ml-1 rtl:mr-1 px-2 pt-2 pb-1 rounded-md rounded-t-none text-white text-center"
+		:class="spanClass"
+		:title="props.label"
+		:aria-label="props.label"
+		:role="props.label ? 'img' : undefined"
+	>
 		<UIcon v-if="props.pi" :name="piIconName" :class="piExtraClasses" />
 		<svg v-if="props.icon" class="iconic inline w-4 h-4 fill-white">
 			<use :xlink:href="iconHref" />
@@ -15,6 +21,8 @@ const props = defineProps<{
 	/** Full Iconify name, optionally followed by extra classes for the icon: "lucide:shield text-amber-500". */
 	pi?: string;
 	borderColor?: string;
+	/** Tooltip and accessible name; without it the badge is decorative. */
+	label?: string;
 }>();
 
 const iconHref = computed(() => (props.icon ? `#${props.icon}` : ""));
diff --git a/resources/js/v8/composables/photo/motionUrlLoader.ts b/resources/js/v8/composables/photo/motionUrlLoader.ts
new file mode 100644
index 00000000000..f60783e49a7
--- /dev/null
+++ b/resources/js/v8/composables/photo/motionUrlLoader.ts
@@ -0,0 +1,20 @@
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+import type { InjectionKey } from "vue";
+
+/**
+ * Loads the tier-3 details (Feature 064) of the given photos, which fills
+ * their `live_photo_url` in place through `mergePhotoDetail()`.
+ *
+ * Grid tiles built from the v3 struct-of-arrays payloads only know
+ * `is_livephoto`; each view that renders photo thumbnails provides its
+ * store's deduplicated details loader under {@link MOTION_URL_LOADER}, so a
+ * thumbnail can fetch its video URL on hover (Feature 100, FR-100-05).
+ */
+export type MotionUrlLoader = (photoIds: string[]) => Promise<void>;
+
+export const MOTION_URL_LOADER: InjectionKey<MotionUrlLoader> = Symbol("motionUrlLoader");
diff --git a/resources/js/v8/composables/photo/useMotionHover.test.ts b/resources/js/v8/composables/photo/useMotionHover.test.ts
new file mode 100644
index 00000000000..6be1b9527c5
--- /dev/null
+++ b/resources/js/v8/composables/photo/useMotionHover.test.ts
@@ -0,0 +1,361 @@
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { reactive } from "vue";
+import { canPlayMotionOnHover, MOTION_HOVER_DELAY_MS, useMotionHover, type MotionPhoto } from "@/v8/composables/photo/useMotionHover";
+
+const URL = "https://lychee.test/uploads/original/ab/cd/photo.mov";
+
+function livePhoto(url: string | null = URL): MotionPhoto {
+	return reactive({ id: "p1", live_photo_url: url, precomputed: { is_livephoto: true } });
+}
+
+/** A loader that sets the URL when `resolve()` is called, like `mergePhotoDetail()` does. */
+function deferredLoader(photo: MotionPhoto) {
+	let resolve: () => void = () => undefined;
+	let reject: (e: Error) => void = () => undefined;
+	const loader = vi.fn(
+		() =>
+			new Promise<void>((res, rej) => {
+				resolve = () => {
+					photo.live_photo_url = URL;
+					res();
+				};
+				reject = rej;
+			}),
+	);
+	return { loader, resolve: () => resolve(), reject: () => reject(new Error("offline")) };
+}
+
+beforeEach(() => {
+	vi.useFakeTimers();
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe("useMotionHover: hover intent (S-100-15, S-100-16)", () => {
+	it("plays the loaded URL after the hover delay, not before", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS - 1);
+		expect(hover.videoSrc.value).toBeNull();
+
+		await vi.advanceTimersByTimeAsync(1);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+
+	it("never plays when the pointer leaves before the delay", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS - 50);
+		hover.onLeave();
+		await vi.advanceTimersByTimeAsync(1000);
+
+		expect(hover.videoSrc.value).toBeNull();
+	});
+
+	it("unloads the video when the pointer leaves", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		hover.onLeave();
+
+		expect(hover.videoSrc.value).toBeNull();
+	});
+
+	it("restarts the delay when the pointer comes back quickly", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(200);
+		hover.onLeave();
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(100);
+		expect(hover.videoSrc.value).toBeNull();
+
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS - 100);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+});
+
+describe("useMotionHover: gates (S-100-17)", () => {
+	it("ignores photos that are not live photos", async () => {
+		const photo = reactive({ id: "p1", live_photo_url: null, precomputed: { is_livephoto: false } });
+		const loader = vi.fn(() => Promise.resolve());
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(1000);
+
+		expect(hover.videoSrc.value).toBeNull();
+		expect(loader).not.toHaveBeenCalled();
+	});
+
+	it("does nothing when the device cannot hover or prefers reduced motion", async () => {
+		const loader = vi.fn(() => Promise.resolve());
+		const hover = useMotionHover(
+			() => livePhoto(null),
+			loader,
+			() => false,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(1000);
+
+		expect(hover.videoSrc.value).toBeNull();
+		expect(loader).not.toHaveBeenCalled();
+	});
+});
+
+describe("useMotionHover: fade-in state", () => {
+	it("is playing from the first frame until the pointer leaves", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		expect(hover.isPlaying.value).toBe(false);
+
+		hover.onPlaying();
+		expect(hover.isPlaying.value).toBe(true);
+
+		hover.onLeave();
+		expect(hover.isPlaying.value).toBe(false);
+	});
+
+	it("stops being playing on error", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		hover.onPlaying();
+		hover.onError();
+
+		expect(hover.isPlaying.value).toBe(false);
+	});
+});
+
+describe("useMotionHover: playback failure (S-100-18)", () => {
+	it("drops the video on error and tries again on the next hover", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		hover.onError();
+		expect(hover.videoSrc.value).toBeNull();
+
+		hover.onLeave();
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+});
+
+describe("useMotionHover: URL loading (S-100-19, S-100-20)", () => {
+	it("does not call the loader when the URL is already known", async () => {
+		const loader = vi.fn(() => Promise.resolve());
+		const hover = useMotionHover(
+			() => livePhoto(),
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+
+		expect(loader).not.toHaveBeenCalled();
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+
+	it("loads a missing URL once, on enter, and waits for it past the delay", async () => {
+		const photo = livePhoto(null);
+		const { loader, resolve } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		expect(loader).toHaveBeenCalledTimes(1);
+		expect(loader).toHaveBeenCalledWith(["p1"]);
+
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS + 150);
+		expect(hover.videoSrc.value).toBeNull();
+
+		resolve();
+		await vi.advanceTimersByTimeAsync(0);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+
+	it("still waits for the delay when the URL arrives first", async () => {
+		const photo = livePhoto(null);
+		const { loader, resolve } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		resolve();
+		await vi.advanceTimersByTimeAsync(10);
+		expect(hover.videoSrc.value).toBeNull();
+
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+
+	it("does not play a URL that arrives after the pointer left", async () => {
+		const photo = livePhoto(null);
+		const { loader, resolve } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		hover.onLeave();
+		resolve();
+		await vi.advanceTimersByTimeAsync(0);
+
+		expect(hover.videoSrc.value).toBeNull();
+	});
+
+	it("swallows a failed load and stays on the still", async () => {
+		const photo = livePhoto(null);
+		const { loader, reject } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		reject();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+
+		expect(hover.videoSrc.value).toBeNull();
+	});
+
+	it("reuses the pending request when the pointer comes back before it finishes", async () => {
+		const photo = livePhoto(null);
+		const { loader, resolve } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(100);
+		hover.onLeave();
+		hover.onEnter();
+		hover.onLeave();
+		hover.onEnter();
+		expect(loader).toHaveBeenCalledTimes(1);
+
+		resolve();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		expect(hover.videoSrc.value).toBe(URL);
+	});
+
+	it("asks again on the next hover after a failed request", async () => {
+		const photo = livePhoto(null);
+		const { loader, reject } = deferredLoader(photo);
+		const hover = useMotionHover(
+			() => photo,
+			loader,
+			() => true,
+		);
+
+		hover.onEnter();
+		reject();
+		await vi.advanceTimersByTimeAsync(MOTION_HOVER_DELAY_MS);
+		hover.onLeave();
+		hover.onEnter();
+
+		expect(loader).toHaveBeenCalledTimes(2);
+	});
+
+	it("plays nothing without a loader when the URL is unknown", async () => {
+		const hover = useMotionHover(
+			() => livePhoto(null),
+			undefined,
+			() => true,
+		);
+
+		hover.onEnter();
+		await vi.advanceTimersByTimeAsync(1000);
+
+		expect(hover.videoSrc.value).toBeNull();
+	});
+});
+
+describe("canPlayMotionOnHover", () => {
+	function stubMedia(matches: Record<string, boolean>) {
+		vi.stubGlobal("matchMedia", (query: string) => ({ matches: matches[query] ?? false }));
+	}
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	it("allows a fine pointer that can hover", () => {
+		stubMedia({ "(hover: hover) and (pointer: fine)": true });
+		expect(canPlayMotionOnHover()).toBe(true);
+	});
+
+	it("refuses touch-only devices", () => {
+		stubMedia({});
+		expect(canPlayMotionOnHover()).toBe(false);
+	});
+
+	it("refuses when reduced motion is preferred", () => {
+		stubMedia({ "(hover: hover) and (pointer: fine)": true, "(prefers-reduced-motion: reduce)": true });
+		expect(canPlayMotionOnHover()).toBe(false);
+	});
+});
diff --git a/resources/js/v8/composables/photo/useMotionHover.ts b/resources/js/v8/composables/photo/useMotionHover.ts
new file mode 100644
index 00000000000..9495f8d5a31
--- /dev/null
+++ b/resources/js/v8/composables/photo/useMotionHover.ts
@@ -0,0 +1,122 @@
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+import { ref, type Ref } from "vue";
+import type { MotionUrlLoader } from "@/v8/composables/photo/motionUrlLoader";
+
+/** How long the pointer must rest on a thumbnail before its motion plays (FR-100-03). */
+export const MOTION_HOVER_DELAY_MS = 250;
+
+/** The fields of a photo tile that hover playback reads. */
+export type MotionPhoto = {
+	id: string;
+	live_photo_url: string | null;
+	precomputed: { is_livephoto: boolean };
+};
+
+/**
+ * Whether hover playback suits this device: a fine pointer that can hover,
+ * and no preference for reduced motion (NFR-100-04). Touch devices and
+ * reduced-motion users get the badge only.
+ */
+export function canPlayMotionOnHover(): boolean {
+	if (typeof window.matchMedia !== "function") {
+		return false;
+	}
+	return window.matchMedia("(hover: hover) and (pointer: fine)").matches && !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * Plays the motion of a live photo thumbnail on hover (Feature 100).
+ *
+ * `videoSrc` stays `null` until the pointer has rested for
+ * {@link MOTION_HOVER_DELAY_MS} and the photo's video URL is known; until
+ * then no video element exists, so nothing is downloaded (NFR-100-01). A
+ * missing URL is requested through `loader` as soon as the pointer enters,
+ * so the request overlaps the delay.
+ *
+ * @param photo    getter of the tile's photo, read on every hover
+ * @param loader   fills `live_photo_url` (FR-100-05); without it only already-known URLs play
+ * @param canPlay  device check, {@link canPlayMotionOnHover} by default
+ */
+export function useMotionHover(
+	photo: () => MotionPhoto,
+	loader?: MotionUrlLoader,
+	canPlay: () => boolean = canPlayMotionOnHover,
+): {
+	videoSrc: Ref<string | null>;
+	isPlaying: Ref<boolean>;
+	onEnter: () => void;
+	onLeave: () => void;
+	onPlaying: () => void;
+	onError: () => void;
+} {
+	const videoSrc = ref<string | null>(null);
+	// True from the first rendered frame, so the video can fade in over the
+	// still instead of flashing an empty element.
+	const isPlaying = ref(false);
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	// Bumped on every enter and leave, so a late timer or URL from an
+	// earlier hover cannot start the video.
+	let hoverId = 0;
+	// The details request in flight, reused when the pointer leaves and comes
+	// back before it settles: the stores mark an id resolved only once its
+	// response arrives, so asking again would send a duplicate request.
+	let pending: { photoId: string; request: Promise<void> } | null = null;
+
+	function urlReady(): Promise<void> {
+		if (photo().live_photo_url !== null || loader === undefined) {
+			return Promise.resolve();
+		}
+
+		const photoId = photo().id;
+		if (pending?.photoId !== photoId) {
+			const request: Promise<void> = loader([photoId])
+				.catch(() => undefined)
+				.finally(() => {
+					// Settled (failed requests included): the next hover asks again.
+					pending = pending?.request === request ? null : pending;
+				});
+			pending = { photoId, request };
+		}
+		return pending.request;
+	}
+
+	function onEnter(): void {
+		if (!photo().precomputed.is_livephoto || !canPlay()) {
+			return;
+		}
+
+		const current = ++hoverId;
+		const delay = new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, MOTION_HOVER_DELAY_MS);
+		});
+		void Promise.all([urlReady(), delay]).then(() => {
+			if (current === hoverId) {
+				videoSrc.value = photo().live_photo_url;
+			}
+		});
+	}
+
+	function onLeave(): void {
+		hoverId++;
+		clearTimeout(timer);
+		videoSrc.value = null;
+		isPlaying.value = false;
+	}
+
+	function onPlaying(): void {
+		isPlaying.value = true;
+	}
+
+	/** The browser cannot play the clip (e.g. HEVC in Firefox): keep the still. */
+	function onError(): void {
+		videoSrc.value = null;
+		isPlaying.value = false;
+	}
+
+	return { videoSrc, isPlaying, onEnter, onLeave, onPlaying, onError };
+}
diff --git a/resources/js/v8/views/gallery-panels/Search.vue b/resources/js/v8/views/gallery-panels/Search.vue
index 070bbf6694c..b0acce843ae 100644
--- a/resources/js/v8/views/gallery-panels/Search.vue
+++ b/resources/js/v8/views/gallery-panels/Search.vue
@@ -141,7 +141,8 @@ import { useSelection } from "@/composables/selections/selections";
 import { useLycheeStateStore } from "@/stores/LycheeState";
 import { useDebounceFn } from "@vueuse/core";
 import { storeToRefs } from "pinia";
-import { computed, nextTick, ref, watch } from "vue";
+import { computed, nextTick, provide, ref, watch } from "vue";
+import { MOTION_URL_LOADER } from "@/v8/composables/photo/motionUrlLoader";
 import { useRoute, useRouter } from "vue-router";
 import AlbumMergeDialog from "@/v8/components/forms/gallery-dialogs/AlbumMergeDialog.vue";
 import RenameDialog from "@/v8/components/forms/gallery-dialogs/RenameDialog.vue";
@@ -202,6 +203,8 @@ const nsfwDetectionsStore = usePhotoNsfwDetectionsStore();
 const photosStore = usePhotosStore();
 const userStore = useUserStore();
 const searchStore = useSearchStore();
+// Feature 100: thumbnails fetch their live photo video URL on hover.
+provide(MOTION_URL_LOADER, (ids) => searchStore.loadPhotoDetailsV3(ids));
 const layoutStore = useLayoutStore();
 
 // Pre-fill the store from a bookmarked/shared URL before children (e.g. SearchBox)
diff --git a/resources/js/v8/views/gallery-panels/Timeline.vue b/resources/js/v8/views/gallery-panels/Timeline.vue
index 9904e81d537..2fd4fc54276 100644
--- a/resources/js/v8/views/gallery-panels/Timeline.vue
+++ b/resources/js/v8/views/gallery-panels/Timeline.vue
@@ -200,7 +200,8 @@
 	</UContextMenu>
 </template>
 <script setup lang="ts">
-import { computed, nextTick } from "vue";
+import { computed, nextTick, provide } from "vue";
+import { MOTION_URL_LOADER } from "@/v8/composables/photo/motionUrlLoader";
 import { useUserStore } from "@/stores/UserState";
 import { ref } from "vue";
 import { useLycheeStateStore } from "@/stores/LycheeState";
@@ -276,6 +277,8 @@ const albumsStore = useAlbumsStore();
 const layoutStore = useLayoutStore();
 const userStore = useUserStore();
 const timelineStore = useTimelineStore();
+// Feature 100: thumbnails fetch their live photo video URL on hover.
+provide(MOTION_URL_LOADER, (ids) => timelineStore.loadPhotoDetailsV3(ids));
 
 // oxlint-disable-next-line vue/no-dupe-keys
 const { photoId } = storeToRefs(photoStore);
diff --git a/tests/Constants/TestConstants.php b/tests/Constants/TestConstants.php
index 57cb3098dd9..e0af63c2613 100644
--- a/tests/Constants/TestConstants.php
+++ b/tests/Constants/TestConstants.php
@@ -38,6 +38,9 @@ class TestConstants
 	public const SAMPLE_FILE_GIF = 'tests/Samples/gif.gif';
 	public const SAMPLE_FILE_GMP_BROKEN_IMAGE = 'tests/Samples/google_motion_photo_broken.jpg';
 	public const SAMPLE_FILE_GMP_IMAGE = 'tests/Samples/google_motion_photo.jpg';
+	public const SAMPLE_FILE_GMP_PIXEL_IMAGE = 'tests/Samples/google_motion_photo_pixel.jpg';
+	public const SAMPLE_FILE_GMP_ULTRAHDR_IMAGE = 'tests/Samples/google_motion_photo_ultrahdr.jpg';
+	public const SAMPLE_FILE_GMP_V1_IMAGE = 'tests/Samples/google_motion_photo_v1.jpg';
 	public const SAMPLE_FILE_HOCHUFERWEG = 'tests/Samples/hochuferweg.jpg';
 	public const SAMPLE_FILE_MONGOLIA_IMAGE = 'tests/Samples/mongolia.jpeg';
 	public const SAMPLE_FILE_NIGHT_IMAGE = 'tests/Samples/night.jpg';
@@ -74,6 +77,9 @@ class TestConstants
 		self::SAMPLE_FILE_GIF => self::MIME_TYPE_IMG_GIF,
 		self::SAMPLE_FILE_GMP_BROKEN_IMAGE => self::MIME_TYPE_IMG_JPEG,
 		self::SAMPLE_FILE_GMP_IMAGE => self::MIME_TYPE_IMG_JPEG,
+		self::SAMPLE_FILE_GMP_PIXEL_IMAGE => self::MIME_TYPE_IMG_JPEG,
+		self::SAMPLE_FILE_GMP_ULTRAHDR_IMAGE => self::MIME_TYPE_IMG_JPEG,
+		self::SAMPLE_FILE_GMP_V1_IMAGE => self::MIME_TYPE_IMG_JPEG,
 		self::SAMPLE_FILE_HOCHUFERWEG => self::MIME_TYPE_IMG_JPEG,
 		self::SAMPLE_FILE_MONGOLIA_IMAGE => self::MIME_TYPE_IMG_JPEG,
 		self::SAMPLE_FILE_NIGHT_IMAGE => self::MIME_TYPE_IMG_JPEG,
diff --git a/tests/ImageProcessing/Commands/ExtractMotionPhotosTest.php b/tests/ImageProcessing/Commands/ExtractMotionPhotosTest.php
new file mode 100644
index 00000000000..3e8d240f393
--- /dev/null
+++ b/tests/ImageProcessing/Commands/ExtractMotionPhotosTest.php
@@ -0,0 +1,331 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * We don't care for unhandled exceptions in tests.
+ * It is the nature of a test to throw an exception.
+ * Without this suppression we had 100+ Linter warning in this file which
+ * don't help anything.
+ *
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\ImageProcessing\Commands;
+
+use App\Enum\StorageDiskType;
+use App\Events\PhotoSaved;
+use App\Models\Album;
+use App\Models\Configs;
+use App\Models\Photo;
+use App\Repositories\ConfigManager;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Storage;
+use Tests\Constants\TestConstants;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+use Tests\Traits\ProbesStoredVideo;
+use Tests\Traits\RequiresFFMpeg;
+
+/**
+ * Covers `lychee:extract_motion_photos` (Feature 100, FR-100-04, S-100-11 …
+ * S-100-14).
+ */
+class ExtractMotionPhotosTest extends BaseApiWithDataTest
+{
+	use ProbesStoredVideo;
+	use RequiresFFMpeg;
+
+	private Album $album;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		// The shared fixture photos have no file on disk: take them out of
+		// the candidate set (JPEGs without a video) so only the photos of
+		// this test are scanned.
+		DB::table('photos')->update(['type' => TestConstants::MIME_TYPE_IMG_PNG]);
+		$this->album = Album::factory()->as_root()->owned_by($this->admin)->create();
+	}
+
+	public function testNothingToDo(): void
+	{
+		$this->artisan('lychee:extract_motion_photos')
+			->expectsOutput('No photos require motion photo extraction.')
+			->assertExitCode(0);
+	}
+
+	public function testExtractsMotionPhotosAndIsIdempotent(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$motion = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		$plain = $this->uploadAsStill(TestConstants::SAMPLE_FILE_HOCHUFERWEG);
+		Event::fake([PhotoSaved::class]);
+
+		$this->artisan('lychee:extract_motion_photos')
+			->expectsOutputToContain('Motion photo: ' . $motion->id)
+			->expectsOutput('Checked 2 photos: 1 motion photos extracted, 0 failed.')
+			->assertExitCode(0);
+
+		$this->assertVideoNextToOriginal($motion->fresh());
+		self::assertNull($plain->fresh()->live_photo_short_path);
+		Event::assertDispatched(PhotoSaved::class, fn (PhotoSaved $event) => $event->photo_ids === [$motion->id]);
+
+		$this->artisan('lychee:extract_motion_photos')
+			->expectsOutput('Checked 1 photos: 0 motion photos extracted, 0 failed.')
+			->assertExitCode(0);
+	}
+
+	public function testDryRunChangesNothing(): void
+	{
+		$motion = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_ULTRAHDR_IMAGE);
+
+		$this->artisan('lychee:extract_motion_photos', ['--dry-run' => true])
+			->expectsOutputToContain('Motion photo: ' . $motion->id)
+			->expectsOutput('Checked 1 photos: 1 motion photos found (dry run), 0 failed.')
+			->assertExitCode(0);
+
+		self::assertNull($motion->fresh()->live_photo_short_path);
+		self::assertFalse(Storage::disk(StorageDiskType::LOCAL->value)->exists($this->expectedVideoPath($motion)));
+	}
+
+	public function testAlbumOption(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$inside = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		$other_album = Album::factory()->as_root()->owned_by($this->admin)->create();
+		$outside = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_ULTRAHDR_IMAGE, $other_album);
+
+		$this->artisan('lychee:extract_motion_photos', ['--album' => $this->album->id])
+			->expectsOutput('Checked 1 photos: 1 motion photos extracted, 0 failed.')
+			->assertExitCode(0);
+
+		self::assertNotNull($inside->fresh()->live_photo_short_path);
+		self::assertNull($outside->fresh()->live_photo_short_path);
+	}
+
+	public function testUnknownAlbum(): void
+	{
+		$this->artisan('lychee:extract_motion_photos', ['--album' => 'doesnotexist'])
+			->expectsOutput('Album doesnotexist not found.')
+			->assertExitCode(1);
+	}
+
+	public function testRequiresFFMpeg(): void
+	{
+		$motion = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		Configs::set(TestConstants::CONFIG_HAS_FFMPEG, 0);
+
+		$this->artisan('lychee:extract_motion_photos')
+			->expectsOutput('FFmpeg is required to extract motion photo videos (or use --dry-run).')
+			->assertExitCode(1);
+
+		self::assertNull($motion->fresh()->live_photo_short_path);
+	}
+
+	public function testUnreadableOriginalIsReported(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$broken = $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		$broken->size_variants->getOriginal()->getFile()->delete();
+
+		$this->artisan('lychee:extract_motion_photos')
+			->expectsOutput('Failed: ' . $broken->id . ' (' . $broken->title . '): original file is missing')
+			->expectsOutput('Checked 1 photos: 0 motion photos extracted, 1 failed.')
+			->assertExitCode(1);
+
+		self::assertNull($broken->fresh()->live_photo_short_path);
+	}
+
+	/**
+	 * PR #4900 review: continuing with the printed cursor would skip a photo
+	 * that failed in the batch, so the command says to run the batch again
+	 * first.
+	 */
+	public function testCursorAfterAFailureAsksToRetryTheBatch(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$photos = [$this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE), $this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_ULTRAHDR_IMAGE)];
+		// Order as the database does: its collation of ids is not byte order on MySQL/PostgreSQL.
+		[$first, $second] = Photo::query()->with('size_variants')->whereIn('id', array_map(fn (Photo $p) => $p->id, $photos))->orderBy('id')->get()->all();
+		$first->size_variants->getOriginal()->getFile()->delete();
+
+		$this->artisan('lychee:extract_motion_photos', ['limit' => 1])
+			->expectsOutput('Failed: ' . $first->id . ' (' . $first->title . '): original file is missing')
+			->expectsOutput('More photos may remain: continue with --after=' . $first->id)
+			->expectsOutput('1 photos failed in this batch and would be skipped by that cursor: run it again without --after to retry them first.')
+			->assertExitCode(1);
+
+		$this->artisan('lychee:extract_motion_photos', ['limit' => 1, '--after' => $first->id])
+			->expectsOutput('Checked 1 photos: 1 motion photos extracted, 0 failed.')
+			->expectsOutput('More photos may remain: continue with --after=' . $second->id)
+			->doesntExpectOutputToContain('failed in this batch')
+			->assertExitCode(0);
+	}
+
+	public function testCursorContinuesAfterThePreviousBatch(): void
+	{
+		$photos = [$this->uploadAsStill(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE), $this->uploadAsStill(TestConstants::SAMPLE_FILE_HOCHUFERWEG)];
+		// Order as the database does: its collation of ids is not byte order on MySQL/PostgreSQL.
+		[$first, $second] = Photo::query()->whereIn('id', array_map(fn (Photo $p) => $p->id, $photos))->orderBy('id')->get()->all();
+
+		$this->artisan('lychee:extract_motion_photos', ['limit' => 1, '--dry-run' => true])
+			->expectsOutput('More photos may remain: continue with --after=' . $first->id)
+			->assertExitCode(0);
+
+		$this->artisan('lychee:extract_motion_photos', ['limit' => 1, '--after' => $first->id, '--dry-run' => true])
+			->expectsOutput('More photos may remain: continue with --after=' . $second->id)
+			->assertExitCode(0);
+
+		$this->artisan('lychee:extract_motion_photos', ['limit' => 1, '--after' => $second->id, '--dry-run' => true])
+			->expectsOutput('No photos require motion photo extraction.')
+			->assertExitCode(0);
+	}
+
+	/**
+	 * S-100-23: a motion photo stored before Q-100-09 kept its HEVC clip;
+	 * `--reencode` extracts it again from the original as H.264.
+	 */
+	public function testReencodeTranscodesStoredHevcClips(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$motion = $this->uploadPhoto(TestConstants::SAMPLE_FILE_GMP_PIXEL_IMAGE);
+		$this->storeHevcClip($motion);
+		self::assertSame('hevc', $this->probeStoredVideo($motion->live_photo_short_path)->get('codec_name'));
+
+		$this->artisan('lychee:extract_motion_photos', ['--reencode' => true])
+			->expectsOutputToContain('Motion photo: ' . $motion->id)
+			->expectsOutput('Checked 1 photos: 1 motion photos re-extracted, 0 failed.')
+			->assertExitCode(0);
+
+		$motion = $motion->fresh();
+		self::assertSame($this->expectedVideoPath($motion), $motion->live_photo_short_path);
+		self::assertFalse(Storage::disk(StorageDiskType::LOCAL->value)->exists($motion->live_photo_short_path . '.part'));
+		$stream = $this->probeStoredVideo($motion->live_photo_short_path);
+		self::assertSame('h264', $stream->get('codec_name'));
+		self::assertSame(1080, $stream->get('width'));
+		self::assertSame(1440, $stream->get('height'));
+	}
+
+	/**
+	 * PR #4900 review: the new clip is staged next to the stored one and
+	 * moved over it, so a failed write leaves the stored clip intact.
+	 * A directory in the staging path makes that write fail.
+	 */
+	public function testReencodeKeepsTheStoredClipWhenTheWriteFails(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$motion = $this->uploadPhoto(TestConstants::SAMPLE_FILE_GMP_PIXEL_IMAGE);
+		$this->storeHevcClip($motion);
+		$disk = Storage::disk(StorageDiskType::LOCAL->value);
+		$staging = $motion->live_photo_short_path . '.part';
+		$disk->makeDirectory($staging);
+
+		try {
+			$this->artisan('lychee:extract_motion_photos', ['--reencode' => true])
+				->expectsOutputToContain('Failed: ' . $motion->id)
+				->expectsOutput('Checked 1 photos: 0 motion photos re-extracted, 1 failed.')
+				->assertExitCode(1);
+		} finally {
+			$disk->deleteDirectory($staging);
+		}
+
+		self::assertSame('hevc', $this->probeStoredVideo($motion->live_photo_short_path)->get('codec_name'));
+	}
+
+	public function testReencodeDryRunChangesNothing(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$motion = $this->uploadPhoto(TestConstants::SAMPLE_FILE_GMP_PIXEL_IMAGE);
+		$this->storeHevcClip($motion);
+
+		$this->artisan('lychee:extract_motion_photos', ['--reencode' => true, '--dry-run' => true])
+			->expectsOutputToContain('Motion photo: ' . $motion->id)
+			->expectsOutput('Checked 1 photos: 1 motion photos found (dry run), 0 failed.')
+			->assertExitCode(0);
+
+		self::assertSame('hevc', $this->probeStoredVideo($motion->live_photo_short_path)->get('codec_name'));
+	}
+
+	public function testReencodeLeavesApplePairsAlone(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		$apple = $this->uploadPhoto(TestConstants::SAMPLE_FILE_TRAIN_IMAGE);
+		$response = $this->actingAs($this->admin)->upload('Photo', filename: TestConstants::SAMPLE_FILE_TRAIN_VIDEO, album_id: $this->album->id);
+		$this->assertCreated($response);
+		self::assertNotNull($apple->fresh()->live_photo_content_id);
+		self::assertNotNull($apple->fresh()->live_photo_short_path);
+
+		$this->artisan('lychee:extract_motion_photos', ['--reencode' => true])
+			->expectsOutput('No photos require motion photo extraction.')
+			->assertExitCode(0);
+	}
+
+	/**
+	 * Uploads with FFmpeg disabled, so the file is stored as a plain still,
+	 * the way photos were imported before Feature 100. FFmpeg is restored to
+	 * the value the test started with.
+	 */
+	private function uploadAsStill(string $filename, ?Album $album = null): Photo
+	{
+		$album ??= $this->album;
+		$has_ffmpeg = resolve(ConfigManager::class)->getValueAsString(TestConstants::CONFIG_HAS_FFMPEG);
+		Configs::set(TestConstants::CONFIG_HAS_FFMPEG, 0);
+
+		$before = DB::table('photo_album')->where('album_id', '=', $album->id)->pluck('photo_id')->all();
+		$response = $this->actingAs($this->admin)->upload('Photo', filename: $filename, album_id: $album->id);
+		$this->assertCreated($response);
+		$id = DB::table('photo_album')->where('album_id', '=', $album->id)->whereNotIn('photo_id', $before)->sole(['photo_id'])->photo_id;
+
+		Configs::set(TestConstants::CONFIG_HAS_FFMPEG, $has_ffmpeg);
+		$photo = Photo::query()->with('size_variants')->findOrFail($id);
+		self::assertNull($photo->live_photo_short_path);
+
+		return $photo;
+	}
+
+	/**
+	 * Uploads into `$album` (this test's album by default) and returns the
+	 * new photo.
+	 */
+	private function uploadPhoto(string $filename, ?Album $album = null): Photo
+	{
+		$album ??= $this->album;
+		$before = DB::table('photo_album')->where('album_id', '=', $album->id)->pluck('photo_id')->all();
+		$response = $this->actingAs($this->admin)->upload('Photo', filename: $filename, album_id: $album->id);
+		$this->assertCreated($response);
+		$id = DB::table('photo_album')->where('album_id', '=', $album->id)->whereNotIn('photo_id', $before)->sole(['photo_id'])->photo_id;
+
+		return Photo::query()->with('size_variants')->findOrFail($id);
+	}
+
+	/**
+	 * Replaces the stored clip with the raw HEVC stream embedded in the
+	 * original, as extraction did before Q-100-09.
+	 */
+	private function storeHevcClip(Photo $photo): void
+	{
+		$disk = Storage::disk(StorageDiskType::LOCAL->value);
+		$original = $disk->get($photo->size_variants->getOriginal()->short_path);
+		$disk->put($photo->live_photo_short_path, substr($original, -3725212));
+	}
+
+	private function expectedVideoPath(Photo $photo): string
+	{
+		$original = $photo->size_variants->getOriginal()->short_path;
+
+		return pathinfo($original, PATHINFO_DIRNAME) . '/' . pathinfo($original, PATHINFO_FILENAME) . '.mov';
+	}
+
+	private function assertVideoNextToOriginal(Photo $photo): void
+	{
+		self::assertSame($this->expectedVideoPath($photo), $photo->live_photo_short_path);
+		$header = Storage::disk(StorageDiskType::LOCAL->value)->get($photo->live_photo_short_path);
+		self::assertSame('ftyp', substr($header, 4, 4));
+	}
+}
diff --git a/tests/ImageProcessing/Image/Handlers/BaseImageHandler.php b/tests/ImageProcessing/Image/Handlers/BaseImageHandler.php
index bf5913d8229..a600435435f 100644
--- a/tests/ImageProcessing/Image/Handlers/BaseImageHandler.php
+++ b/tests/ImageProcessing/Image/Handlers/BaseImageHandler.php
@@ -18,17 +18,20 @@
 
 namespace Tests\ImageProcessing\Image\Handlers;
 
+use App\Enum\StorageDiskType;
 use App\Facades\Helpers;
 use App\Image\Handlers\GdHandler;
 use App\Models\Configs;
 use App\Repositories\ConfigManager;
 use Carbon\Carbon;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Storage;
 use function Safe\date;
 use function Safe\file_get_contents;
 use function Safe\file_put_contents;
 use Tests\Constants\TestConstants;
 use Tests\Feature_v2\Base\BaseApiWithDataTest;
+use Tests\Traits\ProbesStoredVideo;
 use Tests\Traits\RequiresExifTool;
 use Tests\Traits\RequiresFFMpeg;
 
@@ -41,6 +44,7 @@
  */
 abstract class BaseImageHandler extends BaseApiWithDataTest
 {
+	use ProbesStoredVideo;
 	use RequiresExifTool;
 	use RequiresFFMpeg;
 
@@ -523,6 +527,123 @@ public function testBrokenGoogleMotionPhotoUpload(): void
 		self::assertNotEmpty(file_get_contents(storage_path('logs/daily-' . date('Y-m-d') . '.log')));
 	}
 
+	/**
+	 * Feature 100 (S-100-01): a Motion Photo 1.0 file declares its video in a
+	 * `Container:Directory` instead of `MicroVideoOffset`. It is detected
+	 * without exiftool, so only FFmpeg is required.
+	 */
+	public function testGoogleMotionPhotoV1Upload(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+
+		$response = $this->uploadImage(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		$photo = $response->json('photos.0');
+
+		$this->assertMotionVideoStored($photo);
+		// S-100-22: an H.264 clip is copied as is.
+		$stream = $this->probeStoredVideo($this->livePhotoShortPath($photo));
+		self::assertSame('h264', $stream->get('codec_name'));
+		self::assertSame(320, $stream->get('width'));
+		self::assertSame(240, $stream->get('height'));
+	}
+
+	/**
+	 * Feature 100 (S-100-03): an Ultra HDR motion photo has a gain map
+	 * between the still and the video; the video is extracted, not the gain
+	 * map.
+	 */
+	public function testGoogleMotionPhotoUltraHdrUpload(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+
+		$response = $this->uploadImage(TestConstants::SAMPLE_FILE_GMP_ULTRAHDR_IMAGE);
+
+		$this->assertMotionVideoStored($response->json('photos.0'));
+	}
+
+	/**
+	 * Feature 100 (S-100-01, S-100-03, FX-100-03): a real Pixel 11 Pro Ultra
+	 * HDR motion photo, whose primary container item has no `Item:Length`.
+	 * The stored clip must be the HEVC video, not the gain map JPEG.
+	 */
+	public function testGoogleMotionPhotoPixelUpload(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+
+		$response = $this->uploadImage(TestConstants::SAMPLE_FILE_GMP_PIXEL_IMAGE);
+		$photo = $response->json('photos.0');
+
+		$this->assertMotionVideoStored($photo);
+		self::assertEquals(3064, $photo['size_variants']['original']['width']);
+		self::assertEquals(4080, $photo['size_variants']['original']['height']);
+
+		$short_path = $this->livePhotoShortPath($photo);
+		$header = Storage::disk(StorageDiskType::LOCAL->value)->get($short_path);
+		self::assertSame('ftyp', substr($header, 4, 4));
+
+		// S-100-21: the Pixel clip is HEVC 1440×1080 rotated by −90°; it is
+		// stored as upright H.264 so every browser can play it.
+		$stream = $this->probeStoredVideo($short_path);
+		self::assertSame('h264', $stream->get('codec_name'));
+		self::assertSame(1080, $stream->get('width'));
+		self::assertSame(1440, $stream->get('height'));
+	}
+
+	/**
+	 * Feature 100 (S-100-07): without FFmpeg the still is imported as a plain
+	 * photo.
+	 */
+	public function testGoogleMotionPhotoWithoutFFMpegUpload(): void
+	{
+		Configs::set(TestConstants::CONFIG_HAS_FFMPEG, 0);
+
+		$response = $this->uploadImage(TestConstants::SAMPLE_FILE_GMP_V1_IMAGE);
+		$photo = $response->json('photos.0');
+
+		self::assertNull($photo['live_photo_url']);
+		self::assertEquals(TestConstants::MIME_TYPE_IMG_JPEG, $photo['type']);
+		self::assertEquals(1280, $photo['size_variants']['original']['width']);
+		self::assertEquals(850, $photo['size_variants']['original']['height']);
+	}
+
+	/**
+	 * Feature 100 (S-100-09): the legacy `MicroVideoOffset` is now read from
+	 * the XMP packet too, so exiftool is no longer needed for old files.
+	 */
+	public function testLegacyGoogleMotionPhotoWithoutExifToolUpload(): void
+	{
+		$this->assertHasFFMpegOrSkip();
+		Configs::set(TestConstants::CONFIG_HAS_EXIF_TOOL, 0);
+
+		$response = $this->uploadImage(TestConstants::SAMPLE_FILE_GMP_IMAGE);
+
+		$this->assertMotionVideoStored($response->json('photos.0'));
+	}
+
+	/**
+	 * Asserts that the motion video of `$photo` was stored as a `.mov` next
+	 * to the original, under the same file name.
+	 *
+	 * @param array<string,mixed> $photo
+	 */
+	protected function assertMotionVideoStored(array $photo): void
+	{
+		self::assertNotNull($photo['live_photo_url']);
+		self::assertStringEndsWith('.mov', $photo['live_photo_url']);
+		self::assertEquals(pathinfo($photo['live_photo_url'], PATHINFO_DIRNAME), pathinfo($photo['size_variants']['original']['url'], PATHINFO_DIRNAME));
+		self::assertEquals(pathinfo($photo['live_photo_url'], PATHINFO_FILENAME), pathinfo($photo['size_variants']['original']['url'], PATHINFO_FILENAME));
+
+		self::assertGreaterThan(0, Storage::disk(StorageDiskType::LOCAL->value)->size($this->livePhotoShortPath($photo)));
+	}
+
+	/**
+	 * @param array<string,mixed> $photo
+	 */
+	protected function livePhotoShortPath(array $photo): string
+	{
+		return DB::table('photos')->where('id', '=', $photo['id'])->value('live_photo_short_path');
+	}
+
 	/**
 	 * Tests a trick video which is falsely identified as `application/octet-stream`.
 	 *
diff --git a/tests/Samples/build_motion_photo_fixtures.php b/tests/Samples/build_motion_photo_fixtures.php
new file mode 100644
index 00000000000..b65e4051b43
--- /dev/null
+++ b/tests/Samples/build_motion_photo_fixtures.php
@@ -0,0 +1,159 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * Rebuilds the synthetic Google Motion Photo 1.0 fixtures of Feature 100
+ * (FX-100-01, FX-100-02, FX-100-04):
+ *
+ *  - google_motion_photo_v1.jpg        Primary + MotionPhoto
+ *  - google_motion_photo_ultrahdr.jpg  Primary + GainMap + MotionPhoto
+ *
+ * The still is mongolia.jpeg with its XMP packet replaced by a motion photo
+ * packet written like a Pixel camera writes it (attributes on
+ * `Container:Item`, no `Item:Length` on the primary item). The gain map is
+ * the real one of google_motion_photo_pixel.jpg. The video is a one second
+ * H.264 test pattern generated by FFmpeg.
+ *
+ * Usage: php tests/Samples/build_motion_photo_fixtures.php [path/to/ffmpeg]
+ */
+const SAMPLES_DIR = __DIR__;
+const XMP_STD_NAMESPACE = "http://ns.adobe.com/xap/1.0/\x00";
+
+// Layout of google_motion_photo_pixel.jpg, see the Appendix of the spec.
+const PIXEL_VIDEO_LENGTH = 3725212;
+const PIXEL_GAIN_MAP_LENGTH = 1753;
+
+$ffmpeg = $argv[1] ?? 'ffmpeg';
+
+$still = file_get_contents(SAMPLES_DIR . '/mongolia.jpeg');
+$gain_map = read_pixel_gain_map(SAMPLES_DIR . '/google_motion_photo_pixel.jpg');
+$video = generate_clip($ffmpeg);
+
+write_fixture('google_motion_photo_v1.jpg', $still, [
+	['mime' => 'video/mp4', 'semantic' => 'MotionPhoto', 'bytes' => $video],
+]);
+write_fixture('google_motion_photo_ultrahdr.jpg', $still, [
+	['mime' => 'image/jpeg', 'semantic' => 'GainMap', 'bytes' => $gain_map],
+	['mime' => 'video/mp4', 'semantic' => 'MotionPhoto', 'bytes' => $video],
+]);
+
+/**
+ * @param array<int,array{mime:string,semantic:string,bytes:string}> $secondary_items
+ */
+function write_fixture(string $name, string $still, array $secondary_items): void
+{
+	$xmp = motion_photo_xmp($secondary_items);
+	$bytes = replace_xmp($still, $xmp) . implode('', array_column($secondary_items, 'bytes'));
+	file_put_contents(SAMPLES_DIR . '/' . $name, $bytes);
+	echo $name . ': ' . strlen($bytes) . " bytes\n";
+}
+
+/**
+ * @param array<int,array{mime:string,semantic:string,bytes:string}> $secondary_items
+ */
+function motion_photo_xmp(array $secondary_items): string
+{
+	$items = "          <rdf:li rdf:parseType=\"Resource\">\n" .
+		"            <Container:Item\n" .
+		"              Item:Mime=\"image/jpeg\"\n" .
+		"              Item:Semantic=\"Primary\"/>\n" .
+		"          </rdf:li>\n";
+	foreach ($secondary_items as $item) {
+		$items .= "          <rdf:li rdf:parseType=\"Resource\">\n" .
+			"            <Container:Item\n" .
+			'              Item:Mime="' . $item['mime'] . "\"\n" .
+			'              Item:Semantic="' . $item['semantic'] . "\"\n" .
+			'              Item:Length="' . strlen($item['bytes']) . "\"\n" .
+			"              Item:Padding=\"0\"/>\n" .
+			"          </rdf:li>\n";
+	}
+
+	return "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\" x:xmptk=\"Lychee motion photo fixture\">\n" .
+		"  <rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">\n" .
+		"    <rdf:Description rdf:about=\"\"\n" .
+		"        xmlns:GCamera=\"http://ns.google.com/photos/1.0/camera/\"\n" .
+		"        xmlns:Container=\"http://ns.google.com/photos/1.0/container/\"\n" .
+		"        xmlns:Item=\"http://ns.google.com/photos/1.0/container/item/\"\n" .
+		"      GCamera:MotionPhoto=\"1\"\n" .
+		"      GCamera:MotionPhotoVersion=\"1\"\n" .
+		"      GCamera:MotionPhotoPresentationTimestampUs=\"500000\">\n" .
+		"      <Container:Directory>\n" .
+		"        <rdf:Seq>\n" .
+		$items .
+		"        </rdf:Seq>\n" .
+		"      </Container:Directory>\n" .
+		"    </rdf:Description>\n" .
+		"  </rdf:RDF>\n" .
+		"</x:xmpmeta>\n";
+}
+
+/**
+ * Returns the JPEG with its standard XMP APP1 segment replaced by `$xmp`,
+ * or with `$xmp` added after the last APPn segment when there was none.
+ */
+function replace_xmp(string $jpeg, string $xmp): string
+{
+	$payload = XMP_STD_NAMESPACE . $xmp;
+	$segment = "\xFF\xE1" . pack('n', strlen($payload) + 2) . $payload;
+
+	$head = "\xFF\xD8";
+	$offset = 2;
+	$inserted = false;
+	while (true) {
+		$marker = ord($jpeg[$offset + 1]);
+		$length = unpack('n', substr($jpeg, $offset + 2, 2))[1];
+		$raw = substr($jpeg, $offset, $length + 2);
+		$is_app = $marker >= 0xE0 && $marker <= 0xEF;
+		$is_xmp = $marker === 0xE1 && str_starts_with(substr($raw, 4), XMP_STD_NAMESPACE);
+
+		if (!$is_app && !$inserted) {
+			$head .= $segment;
+			$inserted = true;
+		}
+		$head .= $is_xmp ? '' : $raw;
+		if ($marker === 0xDA) {
+			break;
+		}
+		$offset += $length + 2;
+	}
+
+	return $head . substr($jpeg, $offset + strlen($raw));
+}
+
+function read_pixel_gain_map(string $path): string
+{
+	$bytes = file_get_contents($path);
+	$gain_map = substr($bytes, -(PIXEL_VIDEO_LENGTH + PIXEL_GAIN_MAP_LENGTH), PIXEL_GAIN_MAP_LENGTH);
+	if (!str_starts_with($gain_map, "\xFF\xD8") || !str_ends_with($gain_map, "\xFF\xD9")) {
+		fwrite(STDERR, "Unexpected layout of $path\n");
+		exit(1);
+	}
+
+	return $gain_map;
+}
+
+function generate_clip(string $ffmpeg): string
+{
+	$base = tempnam(sys_get_temp_dir(), 'lychee-clip-');
+	$target = $base . '.mp4';
+	$command = escapeshellarg($ffmpeg) . ' -v error -y' .
+		' -f lavfi -i testsrc2=size=320x240:rate=15:duration=1' .
+		' -c:v libx264 -preset veryslow -crf 35 -pix_fmt yuv420p -g 15 -bf 0' .
+		' -map_metadata -1 -fflags +bitexact -flags:v +bitexact -brand isom ' .
+		escapeshellarg($target);
+	exec($command, $output, $status);
+	if ($status !== 0) {
+		fwrite(STDERR, "FFmpeg failed\n");
+		exit(1);
+	}
+	$clip = file_get_contents($target);
+	unlink($target);
+	unlink($base);
+
+	return $clip;
+}
diff --git a/tests/Samples/google_motion_photo_pixel.jpg b/tests/Samples/google_motion_photo_pixel.jpg
new file mode 100644
index 00000000000..ad77aab3fbd
Binary files /dev/null and b/tests/Samples/google_motion_photo_pixel.jpg differ
diff --git a/tests/Samples/google_motion_photo_ultrahdr.jpg b/tests/Samples/google_motion_photo_ultrahdr.jpg
new file mode 100644
index 00000000000..4784e0a2b70
Binary files /dev/null and b/tests/Samples/google_motion_photo_ultrahdr.jpg differ
diff --git a/tests/Samples/google_motion_photo_v1.jpg b/tests/Samples/google_motion_photo_v1.jpg
new file mode 100644
index 00000000000..0b1bdc4d663
Binary files /dev/null and b/tests/Samples/google_motion_photo_v1.jpg differ
diff --git a/tests/Traits/ProbesStoredVideo.php b/tests/Traits/ProbesStoredVideo.php
new file mode 100644
index 00000000000..033ff9c32fb
--- /dev/null
+++ b/tests/Traits/ProbesStoredVideo.php
@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * We don't care for unhandled exceptions in tests.
+ * It is the nature of a test to throw an exception.
+ * Without this suppression we had 100+ Linter warning in this file which
+ * don't help anything.
+ *
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Traits;
+
+use App\Enum\StorageDiskType;
+use App\Repositories\ConfigManager;
+use FFMpeg\FFProbe;
+use FFMpeg\FFProbe\DataMapping\Stream;
+use Illuminate\Support\Facades\Storage;
+
+/**
+ * Reads the first video stream of a file stored on the local images disk,
+ * with the ffprobe binary configured for Lychee (Feature 100, Q-100-09).
+ */
+trait ProbesStoredVideo
+{
+	protected function probeStoredVideo(string $short_path): Stream
+	{
+		$ffprobe = FFProbe::create([
+			'ffprobe.binaries' => resolve(ConfigManager::class)->getValueAsString('ffprobe_path'),
+		]);
+
+		return $ffprobe->streams(Storage::disk(StorageDiskType::LOCAL->value)->path($short_path))->videos()->first();
+	}
+}