lint

Co-authored-by: shenlong-tanwen <139912620+shalong-tanwen@users.noreply.github.com>

docs/static/archived-versions.json

@@ -1,7 +1,7 @@
 [
   {
-    "label": "v3.0.0-rc.3",
-    "url": "https://docs.v3.0.0-rc.3.archive.immich.app"
+    "label": "v3.0.0-rc.4",
+    "url": "https://docs.v3.0.0-rc.4.archive.immich.app"
   },
   {
     "label": "v2.7.5",

e2e/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immich-e2e",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "description": "",
   "main": "index.js",
   "type": "module",

i18n/en.json

@@ -1461,6 +1461,7 @@
   "never": "Never",
   "new_album": "New Album",
   "new_api_key": "New API Key",
+  "new_feature": "New Feature",
   "new_password": "New password",
   "new_person": "New person",
   "new_pin_code": "New PIN code",
@@ -1521,6 +1522,8 @@
   "obtainium_configurator": "Obtainium Configurator",
   "obtainium_configurator_instructions": "Use Obtainium to install and update the Android app directly from Immich GitHub's release. Create an API key and select a variant to create your Obtainium configuration link",
   "ocr": "OCR",
+  "ocr_body": "Immich now reads the text inside your photos, so you can search for them by what they say.",
+  "ocr_title": "Search text in your photos",
   "official_immich_resources": "Official Immich Resources",
   "offline": "Offline",
   "offset": "Offset",
@@ -1539,6 +1542,8 @@
   "open": "Open",
   "open_calendar": "Open calendar",
   "open_in_browser": "Open in browser",
+  "open_in_immich_body": "Set Immich as your gallery on Android to open photos straight from other apps.",
+  "open_in_immich_title": "Open photos in Immich",
   "open_in_map_view": "Open in map view",
   "open_in_openstreetmap": "Open in OpenStreetMap",
   "open_the_search_filters": "Open the search filters",
@@ -1697,7 +1702,9 @@
   "recent": "Recent",
   "recent_searches": "Recent searches",
   "recently_added": "Recently added",
+  "recently_added_body": "Jump straight to everything you've added lately on a dedicated page.",
   "recently_added_page_title": "Recently Added",
+  "recently_added_title": "Recently added",
   "recently_taken": "Recently taken",
   "refresh": "Refresh",
   "refresh_encoded_videos": "Refresh encoded videos",
@@ -1904,6 +1911,8 @@
   "share_link": "Share Link",
   "share_original": "Use original (large)",
   "share_preview": "Use thumbnail (small)",
+  "share_quality_body": "Press and hold the share button to choose the image quality before you share.",
+  "share_quality_title": "Choose your share quality",
   "shared": "Shared",
   "shared_album_activities_input_disable": "Comment is disabled",
   "shared_album_activity_remove_content": "Do you want to delete this activity?",
@@ -1985,16 +1994,19 @@
   "sign_out": "Sign Out",
   "sign_up": "Sign up",
   "size": "Size",
+  "skip": "Skip",
   "skip_to_content": "Skip to content",
   "skip_to_folders": "Skip to folders",
   "skip_to_tags": "Skip to tags",
   "slideshow": "Slideshow",
+  "slideshow_body": "Sit back and watch your photos play in a full-screen slideshow.",
   "slideshow_metadata_overlay_mode": "Overlay content",
   "slideshow_metadata_overlay_mode_description_only": "Description only",
   "slideshow_metadata_overlay_mode_full": "Full",
   "slideshow_repeat": "Repeat slideshow",
   "slideshow_repeat_description": "Loop back to beginning when slideshow ends",
   "slideshow_settings": "Slideshow settings",
+  "slideshow_title": "Slideshow",
   "smart_album": "Smart album",
   "some_assets_already_have_a_location_warning": "Some of the selected assets already have a location",
   "sort_albums_by": "Sort albums by...",
@@ -2157,6 +2169,8 @@
   "upload_status_errors": "Errors",
   "upload_status_uploaded": "Uploaded",
   "upload_success": "Upload success, refresh the page to see new upload assets.",
+  "upload_to_album_body": "Add photos directly into an album as you upload them.",
+  "upload_to_album_title": "Upload straight to an album",
   "upload_to_immich": "Upload to Immich ({count})",
   "uploading": "Uploading",
   "uploading_media": "Uploading media",
@@ -2224,6 +2238,10 @@
   "week": "Week",
   "welcome": "Welcome",
   "welcome_to_immich": "Welcome to Immich",
+  "whats_new": "What's new",
+  "whats_new_preview_unavailable": "Preview coming soon",
+  "whats_new_settings_subtitle": "See what's new in version {version}",
+  "whats_new_version": "Version {version}",
   "when": "When",
   "width": "Width",
   "wifi_name": "Wi-Fi Name",

machine-learning/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "immich-ml"
-version = "3.0.0rc3"
+version = "3.0.0rc4"
 description = ""
 authors = [{ name = "Hau Tran", email = "alex.tran1502@gmail.com" }]
 requires-python = ">=3.11,<4.0"

machine-learning/uv.lock

@@ -974,7 +974,7 @@ wheels = [
 
 [[package]]
 name = "immich-ml"
-version = "3.0.0rc3"
+version = "3.0.0rc4"
 source = { editable = "." }
 dependencies = [
     { name = "aiocache" },

mobile/android/app/CMakeLists.txt

@@ -7,6 +7,7 @@ project(native_buffer LANGUAGES C)
 
 add_library(native_buffer SHARED
     src/main/cpp/native_buffer.c
+    src/main/cpp/native_image.c
 )
 
 target_link_libraries(native_buffer jnigraphics)

mobile/android/app/src/main/cpp/native_image.c

@@ -0,0 +1,109 @@
+#include <jni.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <android/bitmap.h>
+
+// Cache-friendly block size for the tiled rotation (in pixels). 32x32 uint32 = 4KB, fits L1.
+#define TILE 32
+
+// EXIF orientation values (androidx.exifinterface.media.ExifInterface.ORIENTATION_*).
+enum {
+  ORIENTATION_FLIP_HORIZONTAL = 2,
+  ORIENTATION_ROTATE_180 = 3,
+  ORIENTATION_FLIP_VERTICAL = 4,
+  ORIENTATION_TRANSPOSE = 5,
+  ORIENTATION_ROTATE_90 = 6,
+  ORIENTATION_TRANSVERSE = 7,
+  ORIENTATION_ROTATE_270 = 8,
+};
+
+// The orientations that swap width and height. Must stay in sync with affine_for's dim usage.
+static int swaps_dims(int o) {
+  return o == ORIENTATION_ROTATE_90 || o == ORIENTATION_ROTATE_270 ||
+         o == ORIENTATION_TRANSPOSE || o == ORIENTATION_TRANSVERSE;
+}
+
+// A source pixel (sx, sy) maps to destination index base + sx*stepX + sy*stepY, where dw is the
+// destination width. This affine form covers all 8 EXIF orientations and matches the pixel layout
+// of Bitmap.createBitmap(src, matrixForExifOrientation(o)). int64_t so it stays correct on
+// armeabi-v7a (32-bit long) regardless of how large MAX_RAW_DECODE_PIXELS grows.
+static void affine_for(int o, int sw, int sh, int dw, int64_t *base, int64_t *stepX, int64_t *stepY) {
+  switch (o) {
+    case ORIENTATION_ROTATE_90:       *base = sh - 1;                             *stepX = dw;  *stepY = -1;  break;
+    case ORIENTATION_ROTATE_270:      *base = (int64_t) (sw - 1) * dw;            *stepX = -dw; *stepY = 1;   break;
+    case ORIENTATION_ROTATE_180:      *base = (int64_t) (sh - 1) * dw + (sw - 1); *stepX = -1;  *stepY = -dw; break;
+    case ORIENTATION_FLIP_HORIZONTAL: *base = sw - 1;                             *stepX = -1;  *stepY = dw;  break;
+    case ORIENTATION_FLIP_VERTICAL:   *base = (int64_t) (sh - 1) * dw;            *stepX = 1;   *stepY = -dw; break;
+    case ORIENTATION_TRANSPOSE:       *base = 0;                                  *stepX = dw;  *stepY = 1;   break;
+    case ORIENTATION_TRANSVERSE:      *base = (int64_t) (sw - 1) * dw + (sh - 1); *stepX = -dw; *stepY = -1;  break;
+    default:                          *base = 0;                                  *stepX = 1;   *stepY = dw;  break;
+  }
+}
+
+// Copy each source pixel (whole uint32, so channel order/premult is irrelevant) to its rotated
+// destination, walking TILE x TILE blocks so the scattered writes of a 90/270 transpose stay
+// cache-resident. dst is densely packed (rowBytes == dw*4, no padding), which the affine math relies on.
+static void rotate_tiled(const uint8_t *src, int srcStride, uint32_t *dst,
+                         int sw, int sh, int64_t base, int64_t stepX, int64_t stepY) {
+  for (int ty = 0; ty < sh; ty += TILE) {
+    int yEnd = ty + TILE < sh ? ty + TILE : sh;
+    for (int tx = 0; tx < sw; tx += TILE) {
+      int xEnd = tx + TILE < sw ? tx + TILE : sw;
+      for (int sy = ty; sy < yEnd; sy++) {
+        const uint32_t *srcRow = (const uint32_t *) (src + (size_t) sy * srcStride);
+        int64_t idx = base + (int64_t) sy * stepY + (int64_t) tx * stepX;
+        for (int sx = tx; sx < xEnd; sx++) {
+          dst[idx] = srcRow[sx];
+          idx += stepX;
+        }
+      }
+    }
+  }
+}
+
+// Rotates an RGBA_8888 bitmap to the given EXIF orientation into a freshly malloc'd buffer (free it
+// via NativeBuffer.free). Fills outInfo with {width, height, rowBytes} and returns the buffer
+// address, or 0 if the bitmap can't be handled (e.g. a non-8888 format) so the caller can fall back.
+JNIEXPORT jlong JNICALL
+Java_app_alextran_immich_NativeImage_rotate(
+    JNIEnv *env, jclass clazz, jobject bitmap, jint orientation, jintArray outInfo) {
+  AndroidBitmapInfo info;
+  if (AndroidBitmap_getInfo(env, bitmap, &info) != ANDROID_BITMAP_RESULT_SUCCESS) {
+    return 0;
+  }
+  if (info.format != ANDROID_BITMAP_FORMAT_RGBA_8888) {
+    return 0;
+  }
+
+  int sw = (int) info.width;
+  int sh = (int) info.height;
+  int dw = swaps_dims(orientation) ? sh : sw;
+  int dh = swaps_dims(orientation) ? sw : sh;
+
+  uint32_t *dst = (uint32_t *) malloc((size_t) dw * dh * 4);
+  if (dst == NULL) {
+    return 0;
+  }
+
+  void *srcPixels = NULL;
+  if (AndroidBitmap_lockPixels(env, bitmap, &srcPixels) != ANDROID_BITMAP_RESULT_SUCCESS) {
+    free(dst);
+    return 0;
+  }
+
+  int64_t base, stepX, stepY;
+  affine_for(orientation, sw, sh, dw, &base, &stepX, &stepY);
+  rotate_tiled((const uint8_t *) srcPixels, (int) info.stride, dst, sw, sh, base, stepX, stepY);
+
+  AndroidBitmap_unlockPixels(env, bitmap);
+
+  jint dims[3] = {dw, dh, dw * 4};
+  (*env)->SetIntArrayRegion(env, outInfo, 0, 3, dims);
+  // Keep ownership in C until the buffer is safely handed back: if outInfo was somehow too small,
+  // SetIntArrayRegion left a pending exception and Kotlin will never receive (or free) dst.
+  if ((*env)->ExceptionCheck(env)) {
+    free(dst);
+    return 0;
+  }
+  return (jlong) dst;
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/NativeImage.kt

@@ -0,0 +1,19 @@
+package app.alextran.immich
+
+import android.graphics.Bitmap
+
+object NativeImage {
+  init {
+    // rotate() is compiled into the native_buffer shared lib (which already links jnigraphics).
+    System.loadLibrary("native_buffer")
+  }
+
+  /**
+   * Rotates an RGBA_8888 [bitmap] to the given EXIF [orientation], writing the result into a freshly
+   * malloc'd native buffer. Returns the buffer address (free it with [NativeBuffer.free]) and fills
+   * [outInfo] with {width, height, rowBytes}. Returns 0 when the bitmap can't be handled (e.g. a
+   * non-8888 config) so the caller can fall back.
+   */
+  @JvmStatic
+  external fun rotate(bitmap: Bitmap, orientation: Int, outInfo: IntArray): Long
+}

mobile/android/app/src/main/kotlin/app/alextran/immich/images/LocalImagesImpl.kt

@@ -12,7 +12,9 @@ import android.provider.MediaStore.Images
 import android.provider.MediaStore.Video
 import android.util.Size
 import androidx.annotation.RequiresApi
+import androidx.exifinterface.media.ExifInterface
 import app.alextran.immich.NativeBuffer
+import app.alextran.immich.NativeImage
 import kotlin.math.*
 import java.io.IOException
 import java.util.concurrent.Executors
@@ -181,35 +183,88 @@ class LocalImagesImpl(context: Context) : LocalImageApi {
     val id = assetId.toLong()
 
     signal.throwIfCanceled()
-    val bitmap = if (isVideo) {
-      decodeVideoThumbnail(id, size, signal)
-    } else {
-      decodeImage(id, size, signal)
-    }
-
     try {
-      signal.throwIfCanceled()
-      val res = bitmap.toNativeBuffer()
-      signal.throwIfCanceled()
+      val res = if (isVideo) {
+        decodeVideoThumbnail(id, size, signal).toNativeBuffer()
+      } else {
+        val (bitmap, orientation) = decodeImage(id, size, signal)
+        signal.throwIfCanceled()
+        if (orientation == ExifInterface.ORIENTATION_NORMAL || orientation == ExifInterface.ORIENTATION_UNDEFINED) {
+          bitmap.toNativeBuffer()
+        } else {
+          rotateToNativeBuffer(bitmap, orientation, signal)
+        }
+      }
+      // Don't re-check cancellation here: res owns a malloc'd buffer, and bailing to CANCELLED would
+      // orphan it. Deliver it; Dart frees the buffer itself if the request was cancelled meanwhile.
       callback(Result.success(res))
     } catch (e: Exception) {
       callback(if (e is OperationCanceledException) CANCELLED else Result.failure(e))
     }
   }
 
-  private fun decodeImage(id: Long, size: Size, signal: CancellationSignal): Bitmap {
+  // Returns the decoded bitmap plus the EXIF orientation that still needs applying. Only Q+ raw
+  // decodes come back unrotated (ImageDecoder / loadThumbnail skip EXIF for raw like DNG); every
+  // other path already orients itself, so it reports ORIENTATION_NORMAL.
+  private fun decodeImage(id: Long, size: Size, signal: CancellationSignal): Pair<Bitmap, Int> {
     signal.throwIfCanceled()
     val uri = ContentUris.withAppendedId(Images.Media.EXTERNAL_CONTENT_URI, id)
+    val handleRaw = Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && isRawMime(uri)
+    val orientation = if (handleRaw) rawOrientation(uri) else ExifInterface.ORIENTATION_NORMAL
+
     if (size.width <= 0 || size.height <= 0 || size.width > 768 || size.height > 768) {
-      return decodeSource(uri, size, signal)
+      // A "load original" request is unsized -> a full-res decode (a sized > 768 just samples to target).
+      return decodeSource(uri, size, signal) to orientation
     }
 
-    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+    val bitmap = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
       resolver.loadThumbnail(uri, size, signal)
     } else {
       signal.setOnCancelListener { Images.Thumbnails.cancelThumbnailRequest(resolver, id) }
       Images.Thumbnails.getThumbnail(resolver, id, Images.Thumbnails.MINI_KIND, OPTIONS)
     }
+    return bitmap to orientation
+  }
+
+  private fun isRawMime(uri: Uri): Boolean {
+    val mime = resolver.getType(uri) ?: return false
+    return mime.startsWith("image/x-") || mime == "image/dng"
+  }
+
+  private fun rawOrientation(uri: Uri): Int {
+    return resolver.openInputStream(uri)?.use {
+      ExifInterface(it).getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL)
+    } ?: ExifInterface.ORIENTATION_NORMAL
+  }
+
+  // ImageDecoder / loadThumbnail skip EXIF orientation for raw (e.g. DNG) on Q+, so the decoded
+  // bitmap comes back unrotated. Rotate it into the output buffer in native code (one pass, no
+  // intermediate rotated bitmap).
+  private fun rotateToNativeBuffer(bitmap: Bitmap, orientation: Int, signal: CancellationSignal): Map<String, Long> {
+    signal.throwIfCanceled()
+    // Force ARGB_8888: the native rotate needs a lockable 8888 buffer, and toNativeBuffer() below
+    // allocates width*height*4 (an F16/HDR decode would otherwise under-allocate). No-op for the
+    // common already-8888 case.
+    val src = if (bitmap.config != Bitmap.Config.ARGB_8888) {
+      val converted = bitmap.copy(Bitmap.Config.ARGB_8888, false)
+      bitmap.recycle()
+      converted ?: throw IOException("could not convert bitmap to ARGB_8888")
+    } else {
+      bitmap
+    }
+    try {
+      val info = IntArray(3)
+      val pointer = NativeImage.rotate(src, orientation, info)
+      if (pointer == 0L) throw IOException("native rotate failed for orientation $orientation")
+      return mapOf(
+        "pointer" to pointer,
+        "width" to info[0].toLong(),
+        "height" to info[1].toLong(),
+        "rowBytes" to info[2].toLong()
+      )
+    } finally {
+      if (!src.isRecycled) src.recycle()
+    }
   }
 
   private fun decodeVideoThumbnail(id: Long, target: Size, signal: CancellationSignal): Bitmap {

mobile/android/fastlane/Fastfile

@@ -22,8 +22,8 @@ platform :android do
       task: 'bundle', 
       build_type: 'Release',
       properties: {
-        "android.injected.version.code" => 3051,
-        "android.injected.version.name" => "3.0.0-rc.3",
+        "android.injected.version.code" => 3052,
+        "android.injected.version.name" => "3.0.0-rc.4",
       }
     )
     upload_to_play_store(skip_upload_apk: true, skip_upload_images: true, skip_upload_screenshots: true, aab: '../build/app/outputs/bundle/release/app-release.aab', track: 'beta')
@@ -35,8 +35,8 @@ platform :android do
       task: 'bundle', 
       build_type: 'Release',
       properties: {
-        "android.injected.version.code" => 3051,
-        "android.injected.version.name" => "3.0.0-rc.3",
+        "android.injected.version.code" => 3052,
+        "android.injected.version.name" => "3.0.0-rc.4",
       }
     )
     upload_to_play_store(skip_upload_apk: true, skip_upload_images: true, skip_upload_screenshots: true, aab: '../build/app/outputs/bundle/release/app-release.aab')

mobile/lib/domain/models/config/app_config.dart

@@ -4,6 +4,7 @@ import 'package:immich_mobile/constants/enums.dart';
 import 'package:immich_mobile/domain/models/config/album_config.dart';
 import 'package:immich_mobile/domain/models/config/backup_config.dart';
 import 'package:immich_mobile/domain/models/config/cleanup_config.dart';
+import 'package:immich_mobile/domain/models/config/feature_message_config.dart';
 import 'package:immich_mobile/domain/models/config/image_config.dart';
 import 'package:immich_mobile/domain/models/config/map_config.dart';
 import 'package:immich_mobile/domain/models/config/network_config.dart';
@@ -32,6 +33,7 @@ class AppConfig {
   final BackupConfig backup;
   final NetworkConfig network;
   final ShareConfig share;
+  final FeatureMessageConfig featureMessage;
 
   const AppConfig({
     this.logLevel = .info,
@@ -46,6 +48,7 @@ class AppConfig {
     this.backup = const .new(),
     this.network = const .new(),
     this.share = const .new(),
+    this.featureMessage = const .new(),
   });
 
   AppConfig copyWith({
@@ -61,6 +64,7 @@ class AppConfig {
     BackupConfig? backup,
     NetworkConfig? network,
     ShareConfig? share,
+    FeatureMessageConfig? featureMessage,
   }) => .new(
     logLevel: logLevel ?? this.logLevel,
     theme: theme ?? this.theme,
@@ -74,6 +78,7 @@ class AppConfig {
     backup: backup ?? this.backup,
     network: network ?? this.network,
     share: share ?? this.share,
+    featureMessage: featureMessage ?? this.featureMessage,
   );
 
   @override
@@ -91,15 +96,29 @@ class AppConfig {
           other.album == album &&
           other.backup == backup &&
           other.network == network &&
-          other.share == share);
+          other.share == share &&
+          other.featureMessage == featureMessage);
 
   @override
-  int get hashCode =>
-      Object.hash(logLevel, theme, cleanup, map, timeline, image, viewer, slideshow, album, backup, network, share);
+  int get hashCode => Object.hash(
+    logLevel,
+    theme,
+    cleanup,
+    map,
+    timeline,
+    image,
+    viewer,
+    slideshow,
+    album,
+    backup,
+    network,
+    share,
+    featureMessage,
+  );
 
   @override
   String toString() =>
-      'AppConfig(logLevel: $logLevel, theme: $theme, cleanup: $cleanup, map: $map, timeline: $timeline, image: $image, viewer: $viewer, slideshow: $slideshow, album: $album, backup: $backup, network: $network, share: $share)';
+      'AppConfig(logLevel: $logLevel, theme: $theme, cleanup: $cleanup, map: $map, timeline: $timeline, image: $image, viewer: $viewer, slideshow: $slideshow, album: $album, backup: $backup, network: $network, share: $share, featureMessage: $featureMessage)';
 
   T read<T>(SettingsKey<T> key) =>
       (switch (key) {
@@ -146,6 +165,7 @@ class AppConfig {
             .slideshowDuration => slideshow.duration,
             .slideshowLook => slideshow.look,
             .slideshowDirection => slideshow.direction,
+            .featureMessageSeenVersion => featureMessage.seenVersion,
           })
           as T;
 
@@ -199,6 +219,7 @@ class AppConfig {
       .slideshowDuration => copyWith(slideshow: slideshow.copyWith(duration: value as int)),
       .slideshowLook => copyWith(slideshow: slideshow.copyWith(look: value as SlideshowLook)),
       .slideshowDirection => copyWith(slideshow: slideshow.copyWith(direction: value as SlideshowDirection)),
+      .featureMessageSeenVersion => copyWith(featureMessage: featureMessage.copyWith(seenVersion: value as int)),
     };
   }
 }

mobile/lib/domain/models/config/feature_message_config.dart

@@ -0,0 +1,18 @@
+class FeatureMessageConfig {
+  final int seenVersion;
+
+  const FeatureMessageConfig({this.seenVersion = 0});
+
+  FeatureMessageConfig copyWith({int? seenVersion}) =>
+      FeatureMessageConfig(seenVersion: seenVersion ?? this.seenVersion);
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) || (other is FeatureMessageConfig && other.seenVersion == seenVersion);
+
+  @override
+  int get hashCode => seenVersion.hashCode;
+
+  @override
+  String toString() => 'FeatureMessageConfig(seenVersion: $seenVersion)';
+}

mobile/lib/domain/models/feature_message.model.dart

@@ -0,0 +1,54 @@
+import 'dart:io';
+
+enum FeaturePlatform { all, android, ios }
+
+class FeatureHighlight {
+  /// Asset path of the feature screenshot, or null to show a placeholder.
+  final String? image;
+  final String titleKey;
+  final String bodyKey;
+  final FeaturePlatform platform;
+
+  const FeatureHighlight({
+    this.image,
+    required this.titleKey,
+    required this.bodyKey,
+    this.platform = FeaturePlatform.all,
+  });
+
+  bool get isVisibleOnCurrentPlatform => switch (platform) {
+    FeaturePlatform.all => true,
+    FeaturePlatform.android => Platform.isAndroid,
+    FeaturePlatform.ios => Platform.isIOS,
+  };
+}
+
+const int featureMessageHighlightVersion = 1;
+
+const String featureMessageReleaseLabel = '3.0.0';
+
+/// Highlights relevant to the current platform.
+List<FeatureHighlight> get visibleFeatureMessageHighlights =>
+    featureMessageHighlights.where((h) => h.isVisibleOnCurrentPlatform).toList();
+
+const List<FeatureHighlight> featureMessageHighlights = [
+  FeatureHighlight(
+    image: 'assets/feature_message/share_quality.webp',
+    titleKey: 'share_quality_title',
+    bodyKey: 'share_quality_body',
+  ),
+  FeatureHighlight(
+    image: 'assets/feature_message/slideshow.webp',
+    titleKey: 'slideshow_title',
+    bodyKey: 'slideshow_body',
+  ),
+  FeatureHighlight(
+    image: 'assets/feature_message/recently_added.webp',
+    titleKey: 'recently_added_title',
+    bodyKey: 'recently_added_body',
+  ),
+
+  FeatureHighlight(image: 'assets/feature_message/ocr.webp', titleKey: 'ocr_title', bodyKey: 'ocr_body'),
+  FeatureHighlight(titleKey: 'open_in_immich_title', bodyKey: 'open_in_immich_body', platform: FeaturePlatform.android),
+  FeatureHighlight(titleKey: 'upload_to_album_title', bodyKey: 'upload_to_album_body'),
+];

mobile/lib/domain/models/settings_key.dart

@@ -73,7 +73,10 @@ enum SettingsKey<T> {
   slideshowRepeat<bool>(),
   slideshowDuration<int>(),
   slideshowLook<SlideshowLook>(codec: _EnumCodec(SlideshowLook.values)),
-  slideshowDirection<SlideshowDirection>(codec: _EnumCodec(SlideshowDirection.values));
+  slideshowDirection<SlideshowDirection>(codec: _EnumCodec(SlideshowDirection.values)),
+
+  // Feature message
+  featureMessageSeenVersion<int>();
 
   final _SettingsCodec<T>? _codecOverride;
 

mobile/lib/domain/services/feature_message.service.dart

@@ -0,0 +1,17 @@
+import 'package:immich_mobile/domain/models/feature_message.model.dart';
+import 'package:immich_mobile/domain/models/settings_key.dart';
+import 'package:immich_mobile/infrastructure/repositories/settings.repository.dart';
+
+class FeatureMessageService {
+  final SettingsRepository _settingsRepository;
+
+  const FeatureMessageService(this._settingsRepository);
+
+  bool shouldShow() {
+    final seen = _settingsRepository.appConfig.read(SettingsKey.featureMessageSeenVersion);
+    return featureMessageHighlights.isNotEmpty && featureMessageHighlightVersion > seen;
+  }
+
+  Future<void> markSeen() =>
+      _settingsRepository.write(SettingsKey.featureMessageSeenVersion, featureMessageHighlightVersion);
+}

mobile/lib/pages/common/settings.page.dart

@@ -2,7 +2,9 @@ import 'package:auto_route/auto_route.dart';
 import 'package:easy_localization/easy_localization.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_hooks/flutter_hooks.dart' hide Store;
+import 'package:immich_mobile/domain/models/feature_message.model.dart';
 import 'package:immich_mobile/extensions/build_context_extensions.dart';
+import 'package:immich_mobile/presentation/widgets/feature_message/feature_message_dialog.widget.dart';
 import 'package:immich_mobile/routing/router.dart';
 import 'package:immich_mobile/widgets/settings/advanced_settings.dart';
 import 'package:immich_mobile/widgets/settings/asset_list_settings/asset_list_settings.dart';
@@ -87,6 +89,14 @@ class _MobileLayout extends StatelessWidget {
                 ],
         )
         .toList();
+    settings.add(
+      SettingsCard(
+        icon: Icons.auto_awesome_outlined,
+        title: 'whats_new'.tr(),
+        subtitle: 'whats_new_settings_subtitle'.tr(namedArgs: {'version': featureMessageReleaseLabel}),
+        onTap: () => showFeatureMessageDialog(context),
+      ),
+    );
     return ListView(padding: const EdgeInsets.only(top: 10.0, bottom: 60), children: [...settings]);
   }
 }
@@ -116,6 +126,13 @@ class _TabletLayout extends HookWidget {
                   ),
                 ),
               ),
+              SliverToBoxAdapter(
+                child: ListTile(
+                  title: Text('whats_new'.tr()),
+                  leading: const Icon(Icons.auto_awesome_outlined),
+                  onTap: () => showFeatureMessageDialog(context),
+                ),
+              ),
             ],
           ),
         ),

mobile/lib/presentation/pages/dev/main_timeline.page.dart

@@ -3,14 +3,37 @@ import 'package:flutter/material.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:immich_mobile/presentation/widgets/memory/memory_lane.widget.dart';
 import 'package:immich_mobile/presentation/widgets/timeline/timeline.widget.dart';
+import 'package:immich_mobile/presentation/widgets/feature_message/feature_message_dialog.widget.dart';
+import 'package:immich_mobile/providers/feature_message.provider.dart';
 import 'package:immich_mobile/providers/infrastructure/memory.provider.dart';
 
 @RoutePage()
-class MainTimelinePage extends ConsumerWidget {
+class MainTimelinePage extends ConsumerStatefulWidget {
   const MainTimelinePage({super.key});
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
+  ConsumerState<MainTimelinePage> createState() => _MainTimelinePageState();
+}
+
+class _MainTimelinePageState extends ConsumerState<MainTimelinePage> {
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted || ref.read(featureMessageCheckedProvider)) {
+        return;
+      }
+      ref.read(featureMessageCheckedProvider.notifier).state = true;
+
+      final service = ref.read(featureMessageServiceProvider);
+      // if (service.shouldShow()) {
+      showFeatureMessageDialog(context).then((_) => service.markSeen());
+      // }
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
     final hasMemories = ref.watch(driftMemoryFutureProvider.select((state) => state.value?.isNotEmpty ?? false));
     return Timeline(
       topSliverWidget: const SliverToBoxAdapter(child: DriftMemoryLane()),

mobile/lib/presentation/widgets/action_buttons/base_action_button.widget.dart

@@ -49,14 +49,21 @@ class BaseActionButton extends ConsumerWidget {
 
     if (menuItem) {
       final iconColor = this.iconColor;
+      final onPressed = this.onPressed;
 
       return MenuItemButton(
+        closeOnActivate: false,
         style: MenuItemButton.styleFrom(
           alignment: Alignment.centerLeft,
           padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 14),
         ),
         leadingIcon: Icon(iconData, color: iconColor, size: 20),
-        onPressed: onPressed,
+        onPressed: onPressed == null
+            ? null
+            : () {
+                onPressed();
+                MenuController.maybeOf(context)?.close();
+              },
         child: Text(label, style: TextStyle(fontSize: 15, color: iconColor)),
       );
     }

mobile/lib/presentation/widgets/asset_viewer/video_viewer.widget.dart

@@ -260,7 +260,7 @@ class _NativeVideoViewerState extends ConsumerState<NativeVideoViewer> with Widg
     return IgnorePointer(
       child: Stack(
         children: [
-          Center(child: widget.image),
+          if (!_isVideoReady || widget.asset.isMotionPhoto || isCasting) Center(child: widget.image),
           if (!isCasting) ...[
             Visibility.maintain(
               visible: _isVideoReady,

mobile/lib/presentation/widgets/feature_message/feature_message_dialog.widget.dart

@@ -0,0 +1,331 @@
+import 'dart:math' as math;
+
+import 'package:easy_localization/easy_localization.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:immich_mobile/domain/models/feature_message.model.dart';
+import 'package:immich_mobile/extensions/build_context_extensions.dart';
+import 'package:immich_mobile/extensions/theme_extensions.dart';
+
+Future<void> showFeatureMessageDialog(BuildContext context) {
+  return showGeneralDialog<void>(
+    context: context,
+    useRootNavigator: true,
+    barrierDismissible: true,
+    barrierLabel: 'whats_new'.tr(),
+    barrierColor: Colors.black.withValues(alpha: 0.55),
+    transitionDuration: const Duration(milliseconds: 280),
+    pageBuilder: (_, __, ___) => const _FeatureMessageDialog(),
+    transitionBuilder: (_, animation, __, child) {
+      final curved = CurvedAnimation(parent: animation, curve: Curves.easeOutCubic, reverseCurve: Curves.easeInCubic);
+      return FadeTransition(
+        opacity: animation,
+        child: ScaleTransition(scale: Tween<double>(begin: 0.94, end: 1.0).animate(curved), child: child),
+      );
+    },
+  );
+}
+
+class _FeatureMessageDialog extends StatefulWidget {
+  const _FeatureMessageDialog();
+
+  @override
+  State<_FeatureMessageDialog> createState() => _FeatureMessageDialogState();
+}
+
+class _FeatureMessageDialogState extends State<_FeatureMessageDialog> with SingleTickerProviderStateMixin {
+  static const double _radius = 24;
+
+  final PageController _controller = PageController();
+  late final AnimationController _borderController = AnimationController(
+    vsync: this,
+    duration: const Duration(seconds: 7),
+  )..repeat();
+  final List<FeatureHighlight> _highlights = visibleFeatureMessageHighlights;
+  int _index = 0;
+
+  bool get _isLast => _index >= _highlights.length - 1;
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    _borderController.dispose();
+    super.dispose();
+  }
+
+  void _advance() {
+    if (_isLast) {
+      Navigator.of(context).pop();
+      return;
+    }
+    _controller.nextPage(duration: const Duration(milliseconds: 320), curve: Curves.easeOutCubic);
+  }
+
+  List<Color> _borderColors(BuildContext context) {
+    final scheme = context.colorScheme;
+    // Mute the hues toward the surface and drop opacity in dark mode to keep it gentle.
+    Color tone(Color c) => context.isDarkTheme ? Color.lerp(c, scheme.surface, 0.45)!.withValues(alpha: 0.6) : c;
+    return [tone(scheme.primary), tone(scheme.tertiary), tone(scheme.secondary), tone(scheme.primary)];
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Dialog(
+      insetPadding: const EdgeInsets.symmetric(horizontal: 8, vertical: 64),
+      clipBehavior: Clip.antiAlias,
+      backgroundColor: context.isDarkTheme ? context.colorScheme.surfaceContainerLow : Colors.white,
+      shape: const RoundedRectangleBorder(borderRadius: BorderRadius.all(Radius.circular(_radius))),
+      child: AnimatedBuilder(
+        animation: _borderController,
+        builder: (context, child) => CustomPaint(
+          foregroundPainter: _GradientBorderPainter(
+            rotation: _borderController.value,
+            colors: _borderColors(context),
+            radius: _radius,
+            strokeWidth: 3,
+          ),
+          child: child,
+        ),
+        child: ConstrainedBox(
+          constraints: BoxConstraints(maxHeight: context.height * 0.9, maxWidth: 480),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            mainAxisAlignment: MainAxisAlignment.start,
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Padding(
+                padding: const EdgeInsets.fromLTRB(24, 20, 24, 4),
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    Text('whats_new'.tr(), style: context.textTheme.titleLarge?.copyWith(fontWeight: FontWeight.w700)),
+                    const SizedBox(height: 2),
+                    Text(
+                      'whats_new_version'.tr(namedArgs: {'version': featureMessageReleaseLabel}),
+                      style: context.textTheme.bodyLarge?.copyWith(color: context.colorScheme.onSurfaceSecondary),
+                    ),
+                  ],
+                ),
+              ),
+              const SizedBox(height: 32),
+
+              Expanded(
+                child: PageView.builder(
+                  controller: _controller,
+                  itemCount: _highlights.length,
+                  onPageChanged: (i) => setState(() => _index = i),
+                  itemBuilder: (_, index) => _FeaturePage(highlight: _highlights[index]),
+                ),
+              ),
+              const SizedBox(height: 8),
+              _PageDots(controller: _controller, index: _index, count: _highlights.length),
+              Padding(
+                padding: const EdgeInsets.fromLTRB(20, 18, 20, 26),
+                child: Row(
+                  children: [
+                    TextButton(
+                      onPressed: () => Navigator.of(context).pop(),
+                      style: TextButton.styleFrom(padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 14)),
+                      child: Text('skip'.tr()),
+                    ),
+                    const SizedBox(width: 8),
+                    Expanded(
+                      child: DecoratedBox(
+                        decoration: BoxDecoration(
+                          borderRadius: const BorderRadius.all(Radius.circular(100)),
+                          boxShadow: [
+                            // Soft wide primary glow.
+                            BoxShadow(
+                              color: context.primaryColor.withValues(alpha: 0.38),
+                              blurRadius: 22,
+                              spreadRadius: -4,
+                              offset: const Offset(0, 10),
+                            ),
+                            // Tight contact shadow for grounding.
+                            BoxShadow(
+                              color: context.primaryColor.withValues(alpha: 0.22),
+                              blurRadius: 6,
+                              offset: const Offset(0, 2),
+                            ),
+                          ],
+                        ),
+                        child: FilledButton(
+                          onPressed: _advance,
+                          style: FilledButton.styleFrom(
+                            padding: const EdgeInsets.symmetric(vertical: 16),
+                            elevation: 0,
+                            textStyle: context.textTheme.labelLarge?.copyWith(
+                              fontWeight: FontWeight.w700,
+                              fontSize: 16,
+                            ),
+                          ),
+                          child: AnimatedSwitcher(
+                            duration: const Duration(milliseconds: 200),
+                            child: Text(_isLast ? 'ok'.tr() : 'next'.tr(), key: ValueKey(_isLast)),
+                          ),
+                        ),
+                      ),
+                    ),
+                  ],
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _GradientBorderPainter extends CustomPainter {
+  const _GradientBorderPainter({
+    required this.rotation,
+    required this.colors,
+    required this.radius,
+    this.strokeWidth = 3,
+  });
+
+  final double rotation;
+  final List<Color> colors;
+  final double radius;
+  final double strokeWidth;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final inset = strokeWidth / 2;
+    final rect = (Offset.zero & size).deflate(inset);
+    final rrect = RRect.fromRectAndRadius(rect, Radius.circular(radius - inset));
+
+    final shader = SweepGradient(
+      transform: GradientRotation(rotation * 2 * math.pi),
+      colors: colors,
+    ).createShader(rect);
+
+    final paint = Paint()
+      ..shader = shader
+      ..style = PaintingStyle.stroke
+      ..strokeWidth = strokeWidth;
+    canvas.drawRRect(rrect, paint);
+  }
+
+  @override
+  bool shouldRepaint(_GradientBorderPainter oldDelegate) =>
+      oldDelegate.rotation != rotation || !listEquals(oldDelegate.colors, colors);
+}
+
+class _FeaturePage extends StatelessWidget {
+  final FeatureHighlight highlight;
+
+  const _FeaturePage({required this.highlight});
+
+  @override
+  Widget build(BuildContext context) {
+    final scheme = context.colorScheme;
+
+    return SingleChildScrollView(
+      child: Column(
+        children: [
+          Padding(
+            padding: const EdgeInsets.fromLTRB(20, 8, 20, 0),
+            child: DecoratedBox(
+              decoration: BoxDecoration(
+                color: scheme.surfaceContainerHighest,
+                borderRadius: const BorderRadius.all(Radius.circular(18)),
+                border: Border.all(color: scheme.outlineVariant.withValues(alpha: 0.5)),
+              ),
+              child: ClipRRect(
+                borderRadius: const BorderRadius.all(Radius.circular(18)),
+                child: SizedBox(
+                  width: double.infinity,
+                  height: 256,
+                  child: highlight.image == null
+                      ? const _ImagePlaceholder()
+                      : Image.asset(
+                          highlight.image!,
+                          fit: BoxFit.contain,
+                          errorBuilder: (context, _, __) => const _ImagePlaceholder(),
+                        ),
+                ),
+              ),
+            ),
+          ),
+          Padding(
+            padding: const EdgeInsets.fromLTRB(24, 18, 24, 8),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Text(
+                  highlight.titleKey.tr(),
+                  style: context.textTheme.titleLarge?.copyWith(fontWeight: FontWeight.w700, fontSize: 24),
+                ),
+                const SizedBox(height: 8),
+                Text(
+                  highlight.bodyKey.tr(),
+                  style: context.textTheme.bodyLarge?.copyWith(color: scheme.onSurfaceVariant, height: 1.4),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+/// Shown in place of a feature screenshot when no image asset is provided.
+class _ImagePlaceholder extends StatelessWidget {
+  const _ImagePlaceholder();
+
+  @override
+  Widget build(BuildContext context) {
+    final scheme = context.colorScheme;
+    return Center(
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Icon(Icons.local_fire_department_rounded, color: context.colorScheme.primary, size: 84),
+          const SizedBox(height: 12),
+          Text('new_feature'.tr(), style: context.textTheme.titleMedium?.copyWith(color: scheme.onSurfaceVariant)),
+        ],
+      ),
+    );
+  }
+}
+
+class _PageDots extends StatelessWidget {
+  final PageController controller;
+  final int index;
+  final int count;
+
+  const _PageDots({required this.controller, required this.index, required this.count});
+
+  @override
+  Widget build(BuildContext context) {
+    final primary = context.primaryColor;
+
+    return AnimatedBuilder(
+      animation: controller,
+      builder: (context, _) {
+        final page = controller.hasClients ? (controller.page ?? index.toDouble()) : index.toDouble();
+        return Row(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: List.generate(count, (i) {
+            final activeness = (1 - (page - i).abs()).clamp(0.0, 1.0);
+            return AnimatedContainer(
+              duration: const Duration(milliseconds: 150),
+              margin: const EdgeInsets.symmetric(horizontal: 3),
+              height: 7,
+              width: 7 + 16 * activeness,
+              decoration: BoxDecoration(
+                color: Color.lerp(context.colorScheme.surfaceContainerHighest, primary, activeness),
+                borderRadius: const BorderRadius.all(Radius.circular(8)),
+              ),
+            );
+          }),
+        );
+      },
+    );
+  }
+}

mobile/lib/presentation/widgets/feature_message/feature_message_sheet.widget.dart

@@ -0,0 +1,105 @@
+import 'package:easy_localization/easy_localization.dart';
+import 'package:flutter/material.dart';
+import 'package:immich_mobile/domain/models/feature_message.model.dart';
+import 'package:immich_mobile/extensions/build_context_extensions.dart';
+import 'package:immich_mobile/presentation/widgets/bottom_sheet/base_bottom_sheet.widget.dart';
+
+Future<void> showFeatureMessageSheet(BuildContext context) {
+  return showModalBottomSheet(
+    context: context,
+    isScrollControlled: true,
+    backgroundColor: Colors.transparent,
+    useRootNavigator: true,
+    builder: (_) => const _FeatureMessageSheet(),
+  );
+}
+
+class _FeatureMessageSheet extends StatelessWidget {
+  const _FeatureMessageSheet();
+
+  @override
+  Widget build(BuildContext context) {
+    return BaseBottomSheet(
+      actions: const [],
+      resizeOnScroll: false,
+      expand: false,
+      initialChildSize: 0.6,
+      minChildSize: 0.4,
+      maxChildSize: 0.9,
+      slivers: [
+        SliverToBoxAdapter(
+          child: Padding(
+            padding: const EdgeInsets.fromLTRB(24, 4, 24, 16),
+            child: Text(
+              'whats_new'.tr(),
+              style: context.textTheme.headlineSmall?.copyWith(fontWeight: FontWeight.w600),
+            ),
+          ),
+        ),
+        SliverList.separated(
+          itemCount: visibleFeatureMessageHighlights.length,
+          separatorBuilder: (_, __) => const SizedBox(height: 8),
+          itemBuilder: (_, index) => _HighlightCard(highlight: visibleFeatureMessageHighlights[index]),
+        ),
+        const SliverToBoxAdapter(child: SizedBox(height: 16)),
+      ],
+      footer: SafeArea(
+        top: false,
+        child: Padding(
+          padding: const EdgeInsets.fromLTRB(24, 8, 24, 16),
+          child: SizedBox(
+            width: double.infinity,
+            child: FilledButton(
+              onPressed: () => Navigator.of(context).pop(),
+              style: FilledButton.styleFrom(padding: const EdgeInsets.symmetric(vertical: 14)),
+              child: Text('got_it'.tr()),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _HighlightCard extends StatelessWidget {
+  final FeatureHighlight highlight;
+
+  const _HighlightCard({required this.highlight});
+
+  Widget _placeholder(BuildContext context) => ColoredBox(
+    color: context.colorScheme.surfaceContainerHigh,
+    child: Center(child: Icon(Icons.local_fire_department_rounded, color: context.colorScheme.primary, size: 48)),
+  );
+
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.symmetric(horizontal: 16),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          ClipRRect(
+            borderRadius: const BorderRadius.all(Radius.circular(16)),
+            child: AspectRatio(
+              aspectRatio: 16 / 9,
+              child: highlight.image == null
+                  ? _placeholder(context)
+                  : Image.asset(
+                      highlight.image!,
+                      fit: BoxFit.cover,
+                      errorBuilder: (context, _, __) => _placeholder(context),
+                    ),
+            ),
+          ),
+          const SizedBox(height: 12),
+          Text(highlight.titleKey.tr(), style: context.textTheme.titleMedium?.copyWith(fontWeight: FontWeight.w600)),
+          const SizedBox(height: 4),
+          Text(
+            highlight.bodyKey.tr(),
+            style: context.textTheme.bodyMedium?.copyWith(color: context.colorScheme.onSurfaceVariant),
+          ),
+        ],
+      ),
+    );
+  }
+}

mobile/lib/providers/feature_message.provider.dart

@@ -0,0 +1,9 @@
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:immich_mobile/domain/services/feature_message.service.dart';
+import 'package:immich_mobile/providers/infrastructure/settings.provider.dart';
+
+final featureMessageServiceProvider = Provider<FeatureMessageService>(
+  (ref) => FeatureMessageService(ref.read(settingsProvider)),
+);
+
+final featureMessageCheckedProvider = StateProvider<bool>((ref) => false);

mobile/lib/widgets/forms/login/login_form.dart

@@ -18,6 +18,7 @@ import 'package:immich_mobile/extensions/translate_extensions.dart';
 import 'package:immich_mobile/infrastructure/repositories/settings.repository.dart';
 import 'package:immich_mobile/providers/auth.provider.dart';
 import 'package:immich_mobile/providers/background_sync.provider.dart';
+import 'package:immich_mobile/providers/feature_message.provider.dart';
 import 'package:immich_mobile/providers/gallery_permission.provider.dart';
 import 'package:immich_mobile/providers/oauth.provider.dart';
 import 'package:immich_mobile/providers/server_info.provider.dart';
@@ -254,6 +255,7 @@ class LoginForm extends HookConsumerWidget {
           }
           unawaited(handleSyncFlow());
           ref.read(websocketProvider.notifier).connect();
+          unawaited(ref.read(featureMessageServiceProvider).markSeen());
           unawaited(context.router.replaceAll([const TabShellRoute()]));
           return;
         }
@@ -341,6 +343,7 @@ class LoginForm extends HookConsumerWidget {
               await getManageMediaPermission();
             }
             unawaited(handleSyncFlow());
+            unawaited(ref.read(featureMessageServiceProvider).markSeen());
             unawaited(context.router.replaceAll([const TabShellRoute()]));
             return;
           }

mobile/lib/widgets/settings/settings_card.dart

@@ -8,13 +8,15 @@ class SettingsCard extends StatelessWidget {
     required this.icon,
     required this.title,
     required this.subtitle,
-    required this.settingRoute,
+    this.settingRoute,
+    this.onTap,
   });
 
   final IconData icon;
   final String title;
   final String subtitle;
-  final PageRouteInfo settingRoute;
+  final PageRouteInfo? settingRoute;
+  final VoidCallback? onTap;
 
   @override
   Widget build(BuildContext context) {
@@ -38,7 +40,7 @@ class SettingsCard extends StatelessWidget {
           ),
           title: Text(title, style: context.textTheme.titleMedium!.copyWith(color: context.primaryColor)),
           subtitle: Text(subtitle, style: context.textTheme.bodyMedium),
-          onTap: () => context.pushRoute(settingRoute),
+          onTap: onTap ?? (settingRoute != null ? () => context.pushRoute(settingRoute!) : null),
         ),
       ),
     );

mobile/openapi/README.md

@@ -3,7 +3,7 @@ Immich API
 
 This Dart package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
-- API version: 3.0.0-rc.3
+- API version: 3.0.0-rc.4
 - Generator version: 7.22.0
 - Build package: org.openapitools.codegen.languages.DartClientCodegen
 

mobile/pubspec.yaml

@@ -2,7 +2,7 @@ name: immich_mobile
 description: Immich - selfhosted backup media file on mobile phone
 
 publish_to: 'none'
-version: 3.0.0-rc.3+3051
+version: 3.0.0-rc.4+3052
 
 environment:
   sdk: '>=3.12.0 <4.0.0'
@@ -119,6 +119,7 @@ flutter:
   uses-material-design: true
   assets:
     - assets/
+    - assets/feature_message/
   fonts:
     - family: GoogleSans
       fonts:

mobile/test/flutter_test_config.dart

@@ -0,0 +1,13 @@
+import 'dart:async';
+
+import 'package:easy_localization/easy_localization.dart';
+import 'package:flutter/foundation.dart';
+import 'package:logging/logging.dart';
+
+Future<void> testExecutable(FutureOr<void> Function() testMain) async {
+  Logger.root.level = Level.OFF;
+  EasyLocalization.logger.enableBuildModes = [];
+  // ignore: banned-usage
+  debugPrint = (String? message, {int? wrapWidth}) {};
+  return testMain();
+}

mobile/test/modules/map/map_theme_override_test.dart

@@ -1,5 +1,4 @@
 @Skip('Flaky test, needs investigation')
-@Tags(['widget'])
 library;
 
 import 'package:drift/drift.dart';

mobile/test/unit/mocks.dart

@@ -1,7 +1,10 @@
 import 'dart:typed_data';
 
 import 'package:immich_mobile/constants/enums.dart';
+import 'package:immich_mobile/domain/models/album/local_album.model.dart';
+import 'package:immich_mobile/domain/models/asset/base_asset.model.dart';
 import 'package:immich_mobile/domain/models/user.model.dart';
+import 'package:immich_mobile/platform/native_sync_api.g.dart';
 import 'package:mocktail/mocktail.dart' as mock;
 import 'package:mocktail/mocktail.dart';
 
@@ -12,11 +15,11 @@ import 'factories/local_asset_factory.dart';
 import 'factories/user_factory.dart';
 
 class RepositoryMocks {
-  final localAlbum = MockLocalAlbumRepository();
-  final localAsset = MockDriftLocalAssetRepository();
+  final localAlbum = LocalAlbumRepositoryStub(MockLocalAlbumRepository());
+  final localAsset = LocalAssetRepositoryStub(MockDriftLocalAssetRepository());
   final trashedAsset = MockTrashedLocalAssetRepository();
 
-  final nativeApi = MockNativeSyncApi();
+  final nativeApi = NativeSyncApiStub(MockNativeSyncApi());
 
   RepositoryMocks() {
     resetAll();
@@ -24,17 +27,34 @@ class RepositoryMocks {
 
   void resetAll() {
     _registerFallbacks();
-    reset(localAlbum);
-    reset(localAsset);
+    localAlbum.reset();
+    localAsset.reset();
     reset(trashedAsset);
-    reset(nativeApi);
+    nativeApi.reset();
+    _stubLocalAlbumRepository();
+    _stubLocalAssetRepository();
+    _stubNativeSyncApi();
+  }
+
+  void _stubLocalAlbumRepository() {
+    when(localAlbum.getBackupAlbums).thenAnswer((_) async => []);
+    when(localAlbum.getAssetsToHash).thenAnswer((_) async => []);
+  }
+
+  void _stubLocalAssetRepository() {
+    when(localAsset.reconcileHashesFromCloudId).thenAnswer((_) async => {});
+    when(localAsset.updateHashes).thenAnswer((_) async => {});
+  }
+
+  void _stubNativeSyncApi() {
+    when(nativeApi.hashAssets).thenAnswer((_) async => []);
   }
 }
 
 class ServiceMocks {
-  final PartnerStub partner = PartnerStub(MockPartnerService());
-  final UserStub user = UserStub(MockUserService());
-  final asset = AssetStub(MockAssetService());
+  final partner = PartnerServiceStub(MockPartnerService());
+  final user = UserServiceStub(MockUserService());
+  final asset = AssetServiceStub(MockAssetService());
 
   ServiceMocks() {
     resetAll();
@@ -78,11 +98,28 @@ void _registerFallbacks() {
   registerFallbackValue(Uint8List(0));
 }
 
-extension type const Stub<T extends Mock>(T mockedService) {
-  void reset() => mock.reset(mockedService);
+extension type const Stub<T extends Mock>(T mockedClass) {
+  void reset() => mock.reset(mockedClass);
 }
 
-extension type const PartnerStub(MockPartnerService service) implements Stub<MockPartnerService> {
+extension type const LocalAlbumRepositoryStub(MockLocalAlbumRepository repo) implements Stub<MockLocalAlbumRepository> {
+  Future<List<LocalAlbum>> Function() get getBackupAlbums =>
+      () => repo.getBackupAlbums();
+
+  Future<List<LocalAsset>> Function() get getAssetsToHash =>
+      () => repo.getAssetsToHash(any());
+}
+
+extension type const LocalAssetRepositoryStub(MockDriftLocalAssetRepository repo)
+    implements Stub<MockDriftLocalAssetRepository> {
+  Future<void> Function() get reconcileHashesFromCloudId =>
+      () => repo.reconcileHashesFromCloudId();
+
+  Future<void> Function() get updateHashes =>
+      () => repo.updateHashes(any());
+}
+
+extension type const PartnerServiceStub(MockPartnerService service) implements Stub<MockPartnerService> {
   Stream<Iterable<User>> Function() get getCandidates =>
       () => service.getCandidates(any());
 
@@ -110,7 +147,7 @@ extension type const PartnerStub(MockPartnerService service) implements Stub<Moc
       );
 }
 
-extension type const UserStub(MockUserService service) implements Stub<MockUserService> {
+extension type const UserServiceStub(MockUserService service) implements Stub<MockUserService> {
   UserDto Function() get getMyUser =>
       () => service.getMyUser();
 
@@ -127,7 +164,12 @@ extension type const UserStub(MockUserService service) implements Stub<MockUserS
       () => service.createProfileImage(any(), any());
 }
 
-extension type const AssetStub(MockAssetService service) implements Stub<MockAssetService> {
+extension type const AssetServiceStub(MockAssetService service) implements Stub<MockAssetService> {
   Future<void> Function() get updateFavorite =>
       () => service.updateFavorite(any(), any());
 }
+
+extension type const NativeSyncApiStub(MockNativeSyncApi api) implements Stub<MockNativeSyncApi> {
+  Future<List<HashResult>> Function() get hashAssets =>
+      () => api.hashAssets(any(), allowNetworkAccess: any(named: 'allowNetworkAccess'));
+}

mobile/test/unit/presentation/actions/asset_debug_action_test.dart

@@ -6,7 +6,7 @@ import 'package:immich_mobile/presentation/actions/asset_debug.action.dart';
 import 'package:immich_ui/immich_ui.dart';
 
 import '../../factories/remote_asset_factory.dart';
-import '../../presentation_context.dart';
+import '../presentation_context.dart';
 
 void main() {
   late PresentationContext context;
@@ -23,8 +23,8 @@ void main() {
   group('AssetDebugAction', () {
     testWidgets('visible for a single asset when advanced troubleshooting is on', (tester) async {
       await tester.pumpTestWidget(
+        context,
         ActionIconButtonWidget(action: AssetDebugAction(assets: [RemoteAssetFactory.create()])),
-        overrides: context.overrides,
       );
 
       expect(find.byType(ImmichIconButton), findsOneWidget);
@@ -32,10 +32,10 @@ void main() {
 
     testWidgets('hidden for multiple assets', (tester) async {
       await tester.pumpTestWidget(
+        context,
         ActionIconButtonWidget(
           action: AssetDebugAction(assets: [RemoteAssetFactory.create(), RemoteAssetFactory.create()]),
         ),
-        overrides: context.overrides,
       );
 
       expect(find.byType(ImmichIconButton), findsNothing);
@@ -44,8 +44,8 @@ void main() {
     testWidgets('hidden when advanced troubleshooting is off', (tester) async {
       await StoreService.I.put(StoreKey.advancedTroubleshooting, false);
       await tester.pumpTestWidget(
+        context,
         ActionIconButtonWidget(action: AssetDebugAction(assets: [RemoteAssetFactory.create()])),
-        overrides: context.overrides,
       );
 
       expect(find.byType(ImmichIconButton), findsNothing);

mobile/test/unit/presentation/actions/favorite_action_test.dart

@@ -1,30 +1,26 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
-import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:immich_mobile/domain/models/asset/base_asset.model.dart';
 import 'package:immich_mobile/presentation/actions/favorite.action.dart';
-import 'package:immich_mobile/providers/infrastructure/asset.provider.dart';
 import 'package:mocktail/mocktail.dart';
 
+import '../../../domain/service.mock.dart';
 import '../../factories/remote_asset_factory.dart';
-import '../../presentation_context.dart';
+import '../presentation_context.dart';
 
 void main() {
   late PresentationContext context;
+  late MockAssetService assetService;
 
   setUp(() async {
     context = await PresentationContext.create();
+    assetService = context.service.asset.service;
   });
 
   tearDown(() {
     context.dispose();
   });
 
-  List<Override> overrides() => [
-    ...context.overrides,
-    assetServiceProvider.overrideWithValue(context.mocks.asset.service),
-  ];
-
   RemoteAsset owned({bool isFavorite = false}) =>
       RemoteAssetFactory.create(ownerId: context.currentUser.id, isFavorite: isFavorite);
 
@@ -32,48 +28,48 @@ void main() {
     testWidgets('favorites the eligible owned assets', (tester) async {
       final asset = owned();
 
-      await tester.pumpTestAction(FavoriteAction(assets: [asset]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [asset]));
 
-      verify(() => context.mocks.asset.service.updateFavorite([asset.id], true)).called(1);
+      verify(() => assetService.updateFavorite([asset.id], true)).called(1);
     });
 
     testWidgets('unfavorite the eligible owned assets', (tester) async {
       final asset = owned(isFavorite: true);
 
-      await tester.pumpTestAction(FavoriteAction(assets: [asset]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [asset]));
 
-      verify(() => context.mocks.asset.service.updateFavorite([asset.id], false)).called(1);
+      verify(() => assetService.updateFavorite([asset.id], false)).called(1);
     });
 
     testWidgets('ignores assets owned by someone else', (tester) async {
       final mine = owned();
       final theirs = RemoteAssetFactory.create();
 
-      await tester.pumpTestAction(FavoriteAction(assets: [mine, theirs]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [mine, theirs]));
 
-      verify(() => context.mocks.asset.service.updateFavorite([mine.id], true)).called(1);
+      verify(() => assetService.updateFavorite([mine.id], true)).called(1);
     });
 
     testWidgets('batches every eligible owned asset into a single call', (tester) async {
       final first = owned();
       final second = owned();
 
-      await tester.pumpTestAction(FavoriteAction(assets: [first, second]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [first, second]));
 
-      verify(() => context.mocks.asset.service.updateFavorite([first.id, second.id], true)).called(1);
+      verify(() => assetService.updateFavorite([first.id, second.id], true)).called(1);
     });
 
     testWidgets('skips owned assets already in the target state', (tester) async {
       final stale = owned();
       final alreadyFavorite = owned(isFavorite: true);
 
-      await tester.pumpTestAction(FavoriteAction(assets: [stale, alreadyFavorite]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [stale, alreadyFavorite]));
 
-      verify(() => context.mocks.asset.service.updateFavorite([stale.id], true)).called(1);
+      verify(() => assetService.updateFavorite([stale.id], true)).called(1);
     });
 
     testWidgets('shows a confirmation snackbar on success', (tester) async {
-      await tester.pumpTestAction(FavoriteAction(assets: [owned()]), overrides: overrides());
+      await tester.pumpTestAction(context, FavoriteAction(assets: [owned()]));
       await tester.pumpUntilFound(find.byType(SnackBar));
 
       expect(find.byType(SnackBar), findsOneWidget);

mobile/test/unit/presentation/actions/partner_action_test.dart

@@ -4,17 +4,19 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:immich_mobile/domain/models/user.model.dart';
 import 'package:immich_mobile/presentation/actions/partner.action.dart';
-import 'package:immich_mobile/providers/infrastructure/user.provider.dart';
 import 'package:mocktail/mocktail.dart';
 
+import '../../../domain/service.mock.dart';
 import '../../factories/user_factory.dart';
-import '../../presentation_context.dart';
+import '../presentation_context.dart';
 
 void main() {
   late PresentationContext context;
+  late MockPartnerService partnerService;
 
   setUp(() async {
     context = await PresentationContext.create();
+    partnerService = context.service.partner.service;
   });
 
   tearDown(() {
@@ -22,8 +24,6 @@ void main() {
   });
 
   List<Override> overrides({List<User> candidates = const []}) => [
-    ...context.overrides,
-    partnerServiceProvider.overrideWithValue(context.mocks.partner.service),
     candidatesStateProvider.overrideWith((ref) => Stream<Iterable<User>>.value(candidates)),
   ];
 
@@ -31,22 +31,24 @@ void main() {
     testWidgets('creates a partner for the selected candidate', (tester) async {
       final candidate = UserFactory.create();
 
-      await tester.pumpTestAction(const PartnerAddAction(), overrides: overrides(candidates: [candidate]));
+      await tester.pumpTestAction(context, const PartnerAddAction(), overrides: overrides(candidates: [candidate]));
       await tester.pumpUntilFound(find.text(candidate.name));
       await tester.tap(find.text(candidate.name));
       await tester.pumpAndSettle();
 
-      verify(
-        () => context.mocks.partner.service.create(sharedById: context.currentUser.id, sharedWithId: candidate.id),
-      ).called(1);
+      verify(() => partnerService.create(sharedById: context.currentUser.id, sharedWithId: candidate.id)).called(1);
     });
 
     testWidgets('creates nothing when the selection dialog is dismissed', (tester) async {
-      await tester.pumpTestAction(const PartnerAddAction(), overrides: overrides(candidates: [UserFactory.create()]));
+      await tester.pumpTestAction(
+        context,
+        const PartnerAddAction(),
+        overrides: overrides(candidates: [UserFactory.create()]),
+      );
       await tester.sendKeyEvent(LogicalKeyboardKey.escape); // dismiss without selecting
       await tester.pumpAndSettle();
 
-      verifyNever(context.mocks.partner.create);
+      verifyNever(context.service.partner.create);
     });
   });
 
@@ -54,27 +56,27 @@ void main() {
     testWidgets('deletes the partner after confirmation', (tester) async {
       final partner = UserFactory.create();
       await tester.pumpTestAction(
+        context,
         PartnerRemoveAction(sharedWithId: partner.id, partnerName: partner.name),
         overrides: overrides(),
       );
       await tester.tap(find.byType(TextButton).last); // confirm
       await tester.pumpAndSettle();
 
-      verify(
-        () => context.mocks.partner.service.delete(sharedById: context.currentUser.id, sharedWithId: partner.id),
-      ).called(1);
+      verify(() => partnerService.delete(sharedById: context.currentUser.id, sharedWithId: partner.id)).called(1);
     });
 
     testWidgets('deletes nothing when the confirmation is cancelled', (tester) async {
       final partner = UserFactory.create();
       await tester.pumpTestAction(
+        context,
         PartnerRemoveAction(sharedWithId: partner.id, partnerName: partner.name),
         overrides: overrides(),
       );
       await tester.tap(find.byType(TextButton).first); // cancel
       await tester.pumpAndSettle();
 
-      verifyNever(context.mocks.partner.delete);
+      verifyNever(context.service.partner.delete);
     });
   });
 }

mobile/test/unit/presentation/actions/timeline_action_test.dart

@@ -7,7 +7,7 @@ import 'package:immich_mobile/presentation/actions/timeline.action.dart';
 import 'package:immich_mobile/providers/timeline/multiselect.provider.dart';
 
 import '../../factories/remote_asset_factory.dart';
-import '../../presentation_context.dart';
+import '../presentation_context.dart';
 
 class _FakeAction extends BaseAction {
   _FakeAction({this.visible = true, this.error});
@@ -48,8 +48,7 @@ void main() {
     context.dispose();
   });
 
-  List<Override> seededOverrides() => [
-    ...context.overrides,
+  List<Override> overrides() => [
     multiSelectProvider.overrideWith(
       () => MultiSelectNotifier(
         MultiSelectState(selectedAssets: {RemoteAssetFactory.create()}, lockedSelectionAssets: const {}),
@@ -61,6 +60,7 @@ void main() {
     late ActionScope scope;
     late ProviderContainer container;
     await tester.pumpTestWidget(
+      context,
       Consumer(
         builder: (innerContext, ref, _) {
           scope = ActionScope(context: innerContext, ref: ref, authUser: context.currentUser);
@@ -68,7 +68,7 @@ void main() {
           return const SizedBox.shrink();
         },
       ),
-      overrides: seededOverrides(),
+      overrides: overrides(),
     );
     return (scope, container);
   }
@@ -97,8 +97,8 @@ void main() {
 
     testWidgets('delegates visibility to the wrapped action', (tester) async {
       await tester.pumpTestWidget(
+        context,
         ActionIconButtonWidget(action: TimelineAction(action: _FakeAction(visible: false))),
-        overrides: context.overrides,
       );
 
       expect(find.byType(ActionIconButtonWidget), findsOneWidget);

mobile/test/unit/presentation/partner_page_test.dart

@@ -7,7 +7,7 @@ import 'package:immich_mobile/presentation/actions/partner.action.dart';
 
 import '../factories/partner_user_factory.dart';
 import '../factories/user_factory.dart';
-import '../presentation_context.dart';
+import 'presentation_context.dart';
 
 void main() {
   late PresentationContext context;
@@ -19,7 +19,7 @@ void main() {
     testWidgets('shows the empty-state add button when there are no partners', (tester) async {
       final action = const PartnerAddAction();
 
-      await tester.pumpTestWidget(const PartnerSharedByList(partners: []), overrides: context.overrides);
+      await tester.pumpTestWidget(context, const PartnerSharedByList(partners: []));
 
       expect(find.byType(ListView), findsNothing);
       expect(find.widgetWithIcon(TextButton, action.icon), findsOneWidget);
@@ -28,8 +28,7 @@ void main() {
     testWidgets('renders a tile per partner with name and email', (tester) async {
       final partner1 = PartnerFactory.create();
       final partner2 = PartnerFactory.create();
-      await tester.pumpTestWidget(PartnerSharedByList(partners: [partner1, partner2]), overrides: context.overrides);
-
+      await tester.pumpTestWidget(context, PartnerSharedByList(partners: [partner1, partner2]));
       expect(find.byType(ListTile), findsNWidgets(2));
       expect(find.text(partner1.name), findsOneWidget);
       expect(find.text(partner1.email), findsOneWidget);
@@ -41,7 +40,7 @@ void main() {
       final partner1 = PartnerFactory.create(inTimeline: true);
       final partner2 = PartnerFactory.create();
       final action = const PartnerRemoveAction(sharedWithId: '', partnerName: '');
-      await tester.pumpTestWidget(PartnerSharedByList(partners: [partner1, partner2]), overrides: context.overrides);
+      await tester.pumpTestWidget(context, PartnerSharedByList(partners: [partner1, partner2]));
       expect(find.byIcon(action.icon), findsNWidgets(2));
     });
   });
@@ -62,13 +61,12 @@ void main() {
     }
 
     List<Override> withCandidates(List<User> candidates) => [
-      ...context.overrides,
       candidatesStateProvider.overrideWith((ref) => Stream<Iterable<User>>.value(candidates)),
     ];
 
     testWidgets('renders an option per candidate fetched from the provider', (tester) async {
       final user = UserFactory.create();
-      await tester.pumpTestWidget(dialogWidget(), overrides: withCandidates([user]));
+      await tester.pumpTestWidget(context, dialogWidget(), overrides: withCandidates([user]));
 
       await tester.tap(find.byKey(dialogButtonKey));
       await tester.pumpAndSettle();
@@ -78,7 +76,7 @@ void main() {
     });
 
     testWidgets('shows no options when the provider returns no candidates', (tester) async {
-      await tester.pumpTestWidget(dialogWidget(), overrides: withCandidates(const []));
+      await tester.pumpTestWidget(context, dialogWidget(), overrides: withCandidates(const []));
 
       await tester.tap(find.byKey(dialogButtonKey));
       await tester.pumpAndSettle();
@@ -89,7 +87,11 @@ void main() {
     testWidgets('pops the selected candidate when an option is tapped', (tester) async {
       final user = UserFactory.create();
       User? selected;
-      await tester.pumpTestWidget(dialogWidget(onClosed: (user) => selected = user), overrides: withCandidates([user]));
+      await tester.pumpTestWidget(
+        context,
+        dialogWidget(onClosed: (user) => selected = user),
+        overrides: withCandidates([user]),
+      );
 
       await tester.tap(find.byKey(dialogButtonKey));
       await tester.pumpAndSettle();

mobile/test/unit/presentation/presentation_context.dart

@@ -13,16 +13,21 @@ import 'package:immich_mobile/infrastructure/repositories/db.repository.dart';
 import 'package:immich_mobile/infrastructure/repositories/store.repository.dart';
 import 'package:immich_mobile/presentation/actions/action.dart';
 import 'package:immich_mobile/presentation/actions/action.widget.dart';
+import 'package:immich_mobile/providers/infrastructure/asset.provider.dart';
+import 'package:immich_mobile/providers/infrastructure/user.provider.dart';
 import 'package:immich_mobile/providers/user.provider.dart';
 import 'package:immich_ui/immich_ui.dart';
 import 'package:mocktail/mocktail.dart';
 
-import '../test_utils.dart';
-import 'factories/user_factory.dart';
-import 'mocks.dart';
+import '../../test_utils.dart';
+import '../factories/user_factory.dart';
+import '../mocks.dart';
 
 class PresentationContext {
-  PresentationContext._({required UserDto user}) : currentUser = user, mocks = ServiceMocks() {
+  PresentationContext._({required UserDto user})
+    : currentUser = user,
+      service = ServiceMocks(),
+      repository = RepositoryMocks() {
     setup();
   }
 
@@ -31,9 +36,14 @@ class PresentationContext {
   static Drift? _db;
 
   final UserDto currentUser;
-  final ServiceMocks mocks;
+  final ServiceMocks service;
+  final RepositoryMocks repository;
 
-  List<Override> get overrides => [currentUserProvider.overrideWith((ref) => CurrentUserProvider(mocks.user.service))];
+  List<Override> get overrides => [
+    currentUserProvider.overrideWith((ref) => CurrentUserProvider(service.user.service)),
+    assetServiceProvider.overrideWithValue(service.asset.service),
+    partnerServiceProvider.overrideWithValue(service.partner.service),
+  ];
 
   static Future<PresentationContext> create() async {
     TestUtils.init();
@@ -47,18 +57,18 @@ class PresentationContext {
   }
 
   void setup() {
-    when(mocks.user.tryGetMyUser).thenReturn(currentUser);
+    when(service.user.tryGetMyUser).thenReturn(currentUser);
   }
 
   void dispose() {
     addTearDown(() {
-      mocks.resetAll();
+      service.resetAll();
     });
   }
 }
 
 extension PumpPresentationWidget on WidgetTester {
-  Future<void> pumpTestWidget(Widget widget, {List<Override> overrides = const []}) async {
+  Future<void> pumpTestWidget(PresentationContext context, Widget widget, {List<Override> overrides = const []}) async {
     await pumpWidget(
       EasyLocalization(
         supportedLocales: locales.values.toList(),
@@ -69,7 +79,7 @@ extension PumpPresentationWidget on WidgetTester {
         useFallbackTranslations: true,
         assetLoader: const CodegenLoader(),
         child: ProviderScope(
-          overrides: overrides,
+          overrides: [...context.overrides, ...overrides],
           child: Builder(
             builder: (context) => MaterialApp(
               debugShowCheckedModeBanner: false,
@@ -86,8 +96,12 @@ extension PumpPresentationWidget on WidgetTester {
     await pumpAndSettle();
   }
 
-  Future<void> pumpTestAction(BaseAction action, {List<Override> overrides = const []}) async {
-    await pumpTestWidget(ActionIconButtonWidget(action: action), overrides: overrides);
+  Future<void> pumpTestAction(
+    PresentationContext context,
+    BaseAction action, {
+    List<Override> overrides = const [],
+  }) async {
+    await pumpTestWidget(context, ActionIconButtonWidget(action: action), overrides: overrides);
     await tap(find.byType(ImmichIconButton));
     await pump();
   }

mobile/test/unit/services/hash_service_test.dart

@@ -14,14 +14,11 @@ void main() {
 
   setUp(() {
     sut = HashService(
-      localAlbumRepository: mocks.localAlbum,
-      localAssetRepository: mocks.localAsset,
-      nativeSyncApi: mocks.nativeApi,
+      localAlbumRepository: mocks.localAlbum.repo,
+      localAssetRepository: mocks.localAsset.repo,
+      nativeSyncApi: mocks.nativeApi.api,
       trashedLocalAssetRepository: mocks.trashedAsset,
     );
-
-    when(() => mocks.localAsset.reconcileHashesFromCloudId()).thenAnswer((_) async => {});
-    when(() => mocks.localAsset.updateHashes(any())).thenAnswer((_) async => {});
   });
 
   tearDown(() {
@@ -32,22 +29,20 @@ void main() {
     group('hashAssets', () {
       test('skips albums with no assets to hash', () async {
         final album = LocalAlbumFactory.create(assetCount: 0);
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => []);
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
 
         await sut.hashAssets();
 
-        verifyNever(() => mocks.nativeApi.hashAssets(any(), allowNetworkAccess: any(named: 'allowNetworkAccess')));
+        verifyNever(mocks.nativeApi.hashAssets);
       });
 
       test('skips empty batches', () async {
         final album = LocalAlbumFactory.create();
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => []);
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
 
         await sut.hashAssets();
 
-        verifyNever(() => mocks.nativeApi.hashAssets(any(), allowNetworkAccess: any(named: 'allowNetworkAccess')));
+        verifyNever(mocks.nativeApi.hashAssets);
       });
 
       test('processes assets when available', () async {
@@ -55,15 +50,17 @@ void main() {
         final asset = LocalAssetFactory.create();
         final result = HashResult(assetId: asset.id, hash: 'test-hash');
 
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
-        when(() => mocks.nativeApi.hashAssets([asset.id], allowNetworkAccess: false)).thenAnswer((_) async => [result]);
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
+        when(
+          () => mocks.nativeApi.api.hashAssets([asset.id], allowNetworkAccess: false),
+        ).thenAnswer((_) async => [result]);
 
         await sut.hashAssets();
 
-        verify(() => mocks.nativeApi.hashAssets([asset.id], allowNetworkAccess: false)).called(1);
+        verify(() => mocks.nativeApi.api.hashAssets([asset.id], allowNetworkAccess: false)).called(1);
         final captured =
-            verify(() => mocks.localAsset.updateHashes(captureAny())).captured.first as Map<String, String>;
+            verify(() => mocks.localAsset.repo.updateHashes(captureAny())).captured.first as Map<String, String>;
         expect(captured.length, 1);
         expect(captured[asset.id], result.hash);
       });
@@ -72,16 +69,16 @@ void main() {
         final album = LocalAlbumFactory.create();
         final asset = LocalAssetFactory.create();
 
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
         when(
-          () => mocks.nativeApi.hashAssets([asset.id], allowNetworkAccess: false),
+          () => mocks.nativeApi.api.hashAssets([asset.id], allowNetworkAccess: false),
         ).thenAnswer((_) async => [HashResult(assetId: asset.id, error: 'Failed to hash')]);
 
         await sut.hashAssets();
 
         final captured =
-            verify(() => mocks.localAsset.updateHashes(captureAny())).captured.first as Map<String, String>;
+            verify(() => mocks.localAsset.repo.updateHashes(captureAny())).captured.first as Map<String, String>;
         expect(captured.length, 0);
       });
 
@@ -89,25 +86,25 @@ void main() {
         final album = LocalAlbumFactory.create();
         final asset = LocalAssetFactory.create();
 
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(album.id)).thenAnswer((_) async => [asset]);
         when(
-          () => mocks.nativeApi.hashAssets([asset.id], allowNetworkAccess: false),
+          () => mocks.nativeApi.api.hashAssets([asset.id], allowNetworkAccess: false),
         ).thenAnswer((_) async => [HashResult(assetId: asset.id, hash: null)]);
 
         await sut.hashAssets();
 
         final captured =
-            verify(() => mocks.localAsset.updateHashes(captureAny())).captured.first as Map<String, String>;
+            verify(() => mocks.localAsset.repo.updateHashes(captureAny())).captured.first as Map<String, String>;
         expect(captured.length, 0);
       });
 
       test('batches by size limit', () async {
         const batchSize = 2;
         final sut = HashService(
-          localAlbumRepository: mocks.localAlbum,
-          localAssetRepository: mocks.localAsset,
-          nativeSyncApi: mocks.nativeApi,
+          localAlbumRepository: mocks.localAlbum.repo,
+          localAssetRepository: mocks.localAsset.repo,
+          nativeSyncApi: mocks.nativeApi.api,
           batchSize: batchSize,
           trashedLocalAssetRepository: mocks.trashedAsset,
         );
@@ -119,12 +116,9 @@ void main() {
 
         final capturedCalls = <List<String>>[];
 
-        when(() => mocks.localAsset.updateHashes(any())).thenAnswer((_) async => {});
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => [asset1, asset2, asset3]);
-        when(() => mocks.nativeApi.hashAssets(any(), allowNetworkAccess: any(named: 'allowNetworkAccess'))).thenAnswer((
-          invocation,
-        ) async {
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(album.id)).thenAnswer((_) async => [asset1, asset2, asset3]);
+        when(mocks.nativeApi.hashAssets).thenAnswer((invocation) async {
           final assetIds = invocation.positionalArguments[0] as List<String>;
           capturedCalls.add(List<String>.from(assetIds));
           return assetIds.map((id) => HashResult(assetId: id, hash: '$id-hash')).toList();
@@ -136,7 +130,7 @@ void main() {
         expect(capturedCalls[0], [asset1.id, asset2.id], reason: 'First call should batch the first two assets');
         expect(capturedCalls[1], [asset3.id], reason: 'Second call should have the remaining asset');
 
-        verify(() => mocks.localAsset.updateHashes(any())).called(2);
+        verify(() => mocks.localAsset.repo.updateHashes(any())).called(2);
       });
 
       test('handles mixed success and failure in batch', () async {
@@ -144,9 +138,9 @@ void main() {
         final asset1 = LocalAssetFactory.create();
         final asset2 = LocalAssetFactory.create();
 
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [album]);
-        when(() => mocks.localAlbum.getAssetsToHash(album.id)).thenAnswer((_) async => [asset1, asset2]);
-        when(() => mocks.nativeApi.hashAssets([asset1.id, asset2.id], allowNetworkAccess: false)).thenAnswer(
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [album]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(album.id)).thenAnswer((_) async => [asset1, asset2]);
+        when(() => mocks.nativeApi.api.hashAssets([asset1.id, asset2.id], allowNetworkAccess: false)).thenAnswer(
           (_) async => [
             HashResult(assetId: asset1.id, hash: 'asset1-hash'),
             HashResult(assetId: asset2.id, error: 'Failed to hash asset2'),
@@ -156,7 +150,7 @@ void main() {
         await sut.hashAssets();
 
         final captured =
-            verify(() => mocks.localAsset.updateHashes(captureAny())).captured.first as Map<String, String>;
+            verify(() => mocks.localAsset.repo.updateHashes(captureAny())).captured.first as Map<String, String>;
         expect(captured.length, 1);
         expect(captured[asset1.id], 'asset1-hash');
       });
@@ -167,20 +161,18 @@ void main() {
         final asset1 = LocalAssetFactory.create();
         final asset2 = LocalAssetFactory.create();
 
-        when(() => mocks.localAlbum.getBackupAlbums()).thenAnswer((_) async => [selectedAlbum, nonSelectedAlbum]);
-        when(() => mocks.localAlbum.getAssetsToHash(selectedAlbum.id)).thenAnswer((_) async => [asset1]);
-        when(() => mocks.localAlbum.getAssetsToHash(nonSelectedAlbum.id)).thenAnswer((_) async => [asset2]);
-        when(() => mocks.nativeApi.hashAssets(any(), allowNetworkAccess: any(named: 'allowNetworkAccess'))).thenAnswer((
-          invocation,
-        ) async {
+        when(mocks.localAlbum.getBackupAlbums).thenAnswer((_) async => [selectedAlbum, nonSelectedAlbum]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(selectedAlbum.id)).thenAnswer((_) async => [asset1]);
+        when(() => mocks.localAlbum.repo.getAssetsToHash(nonSelectedAlbum.id)).thenAnswer((_) async => [asset2]);
+        when(mocks.nativeApi.hashAssets).thenAnswer((invocation) async {
           final assetIds = invocation.positionalArguments[0] as List<String>;
           return assetIds.map((id) => HashResult(assetId: id, hash: '$id-hash')).toList();
         });
 
         await sut.hashAssets();
 
-        verify(() => mocks.nativeApi.hashAssets([asset1.id], allowNetworkAccess: true)).called(1);
-        verify(() => mocks.nativeApi.hashAssets([asset2.id], allowNetworkAccess: false)).called(1);
+        verify(() => mocks.nativeApi.api.hashAssets([asset1.id], allowNetworkAccess: true)).called(1);
+        verify(() => mocks.nativeApi.api.hashAssets([asset2.id], allowNetworkAccess: false)).called(1);
       });
     });
   });

mobile/test/widget_tester_extensions.dart

@@ -1,27 +1,51 @@
+import 'package:easy_localization/easy_localization.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:immich_mobile/constants/locales.dart';
+import 'package:immich_mobile/generated/codegen_loader.g.dart';
 
 extension PumpConsumerWidget on WidgetTester {
-  /// Wraps the provided [widget] with Material app such that it becomes:
+  /// Wraps the provided [widget] with a localized Material app such that it
+  /// becomes:
+  ///
+  /// EasyLocalization
+  ///   |-ProviderScope
+  ///     |-MaterialApp (localization delegates wired up)
+  ///       |-Material
+  ///         |-[widget]
   ///
-  /// ProviderScope
-  ///   |-MaterialApp
-  ///     |-Material
-  ///       |-[widget]
   Future<void> pumpConsumerWidget(
     Widget widget, {
     Duration? duration,
     EnginePhase phase = EnginePhase.sendSemanticsUpdate,
     List<Override> overrides = const [],
   }) async {
-    return pumpWidget(
-      ProviderScope(
-        overrides: overrides,
-        child: MaterialApp(debugShowCheckedModeBanner: false, home: Material(child: widget)),
+    await pumpWidget(
+      EasyLocalization(
+        supportedLocales: locales.values.toList(),
+        path: translationsPath,
+        startLocale: locales.values.first,
+        fallbackLocale: locales.values.first,
+        saveLocale: false,
+        useFallbackTranslations: true,
+        assetLoader: const CodegenLoader(),
+        child: ProviderScope(
+          overrides: overrides,
+          child: Builder(
+            builder: (context) => MaterialApp(
+              debugShowCheckedModeBanner: false,
+              localizationsDelegates: context.localizationDelegates,
+              supportedLocales: context.supportedLocales,
+              locale: context.locale,
+              home: Material(child: widget),
+            ),
+          ),
+        ),
       ),
       duration: duration,
       phase: phase,
     );
+    await pumpAndSettle();
   }
 }

open-api/immich-openapi-specs.json

@@ -16206,7 +16206,7 @@
   "info": {
     "title": "Immich",
     "description": "Immich API",
-    "version": "3.0.0-rc.3",
+    "version": "3.0.0-rc.4",
     "contact": {}
   },
   "tags": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "immich-monorepo",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "description": "Monorepo for Immich",
   "type": "module",
   "private": true,

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immich/cli",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "description": "Command Line Interface (CLI) for Immich",
   "repository": {
     "type": "git",

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immich/sdk",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "description": "Auto-generated TypeScript SDK for the Immich API",
   "repository": {
     "type": "git",

packages/sdk/src/fetch-client.ts

@@ -1,6 +1,6 @@
 /**
  * Immich
- * 3.0.0-rc.3
+ * 3.0.0-rc.4
  * DO NOT MODIFY - This file has been generated using oazapfts.
  * See https://www.npmjs.com/package/oazapfts
  */

server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immich",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "description": "",
   "author": "",
   "private": true,

server/src/repositories/metadata.repository.ts

@@ -53,10 +53,10 @@ export interface ImmichTags extends Omit<Tags, TagsWithWrongTypes> {
     RegionList: {
       Area: {
         // (X,Y) // center of the rectangle
-        X: number;
-        Y: number;
-        W: number;
-        H: number;
+        X: number | string;
+        Y: number | string;
+        W: number | string;
+        H: number | string;
         Unit: string;
       };
       Rotation?: number;

server/src/services/metadata.service.spec.ts

@@ -39,7 +39,10 @@ const forSidecarJob = (
   };
 };
 
-const makeFaceTags = (face: Partial<{ Name: string }> = {}, orientation?: ImmichTags['Orientation']) => ({
+const makeFaceTags = (
+  face: Partial<{ Name: string }> = {},
+  orientation?: ImmichTags['Orientation'],
+): Partial<ImmichTags> => ({
   Orientation: orientation,
   RegionInfo: {
     AppliedToDimensions: { W: 1000, H: 100, Unit: 'pixel' },
@@ -1371,6 +1374,35 @@ describe(MetadataService.name, () => {
       expect(mocks.person.updateAll).not.toHaveBeenCalled();
     });
 
+    it('should handle string coordinates in face region bounding box calculation by limiting to 16 decimal places', async () => {
+      const asset = AssetFactory.create();
+      const person = PersonFactory.create();
+
+      mocks.assetJob.getForMetadataExtraction.mockResolvedValue(getForMetadataExtraction(asset));
+      mocks.systemMetadata.get.mockResolvedValue({ metadata: { faces: { import: true } } });
+      const faceTags = makeFaceTags({ Name: person.name });
+
+      // Simulating EXIF returning a string with >16 decimal places
+      faceTags.RegionInfo!.RegionList[0].Area.X = '0.48564814814814824';
+      faceTags.RegionInfo!.RegionList[0].Area.W = '0.2';
+
+      mockReadTags(faceTags);
+      mocks.person.getDistinctNames.mockResolvedValue([]);
+      mocks.person.createAll.mockResolvedValue([person.id]);
+      mocks.person.update.mockResolvedValue(person);
+
+      await sut.handleMetadataExtraction({ id: asset.id });
+
+      expect(mocks.person.refreshFaces).toHaveBeenCalledWith(
+        [
+          expect.objectContaining({
+            boundingBoxX1: Math.floor((0.485_648_148_148_148_2 - 0.2 / 2) * 1000),
+          }),
+        ],
+        [],
+      );
+    });
+
     it('should apply metadata face tags creating new people', async () => {
       const asset = AssetFactory.create();
       const person = PersonFactory.create();

server/src/services/metadata.service.ts

@@ -854,6 +854,13 @@ export class MetadataService extends BaseService {
     // update area coordinates and dimensions in RegionList assuming "normalized" unit as per MWG guidelines
     const adjustedRegionList = regionInfo.RegionList.map((region) => {
       let { X, Y, W, H } = region.Area;
+
+      // EXIF floats with >16 decimals are serialized as strings. Ensure they are numbers.
+      X = Number(X);
+      Y = Number(Y);
+      W = Number(W);
+      H = Number(H);
+
       switch (orientation) {
         case ExifOrientation.MirrorHorizontal: {
           X = 1 - X;
@@ -926,16 +933,21 @@ export class MetadataService extends BaseService {
       const loweredName = region.Name.toLowerCase();
       const personId = existingNameMap.get(loweredName) || this.cryptoRepository.randomUUID();
 
+      const X = Number(region.Area.X);
+      const Y = Number(region.Area.Y);
+      const W = Number(region.Area.W);
+      const H = Number(region.Area.H);
+
       const face = {
         id: this.cryptoRepository.randomUUID(),
         personId,
         assetId: asset.id,
         imageWidth,
         imageHeight,
-        boundingBoxX1: Math.floor((region.Area.X - region.Area.W / 2) * imageWidth),
-        boundingBoxY1: Math.floor((region.Area.Y - region.Area.H / 2) * imageHeight),
-        boundingBoxX2: Math.floor((region.Area.X + region.Area.W / 2) * imageWidth),
-        boundingBoxY2: Math.floor((region.Area.Y + region.Area.H / 2) * imageHeight),
+        boundingBoxX1: Math.floor((X - W / 2) * imageWidth),
+        boundingBoxY1: Math.floor((Y - H / 2) * imageHeight),
+        boundingBoxX2: Math.floor((X + W / 2) * imageWidth),
+        boundingBoxY2: Math.floor((Y + H / 2) * imageHeight),
         sourceType: SourceType.Exif,
       };
 

web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immich-web",
-  "version": "3.0.0-rc.3",
+  "version": "3.0.0-rc.4",
   "license": "GNU Affero General Public License version 3",
   "type": "module",
   "scripts": {