content [nfc]: Record href and src straightforwardly on ImagePreviewNode

I've frequently gotten confused about the roles of `srcUrl` and
`thumbnail`. The former has been especially confusing while thinking
through all the cases we have to handle. The name `srcUrl` seemed to
suggest (a) parsing something into a Uri object and (b) representing
the `src` attribute in the HTML. Neither was true: it was a String,
and it held the HTML's `href` at least as commonly as `src`.

To straighten this out, just have ImagePreviewNode hold `href` and
`src`, and transcribe the fields' meanings from the API doc and CZO
discussions. The `src` field is a new type ImagePreviewNodeSrc with
two subclasses corresponding to the thumbnail- and not-thumbnail-URL
cases.

Author: chrisbobbe

lib/model/content.dart

@@ -539,8 +539,8 @@ class ImagePreviewNodeList extends BlockContentNode {
 class ImagePreviewNode extends BlockContentNode {
   const ImagePreviewNode({
     super.debugHtmlNode,
-    required this.srcUrl,
-    required this.thumbnail,
+    required this.originalSrc,
+    required this.src,
     required this.loading,
     required this.originalWidth,
     required this.originalHeight,
@@ -550,51 +550,129 @@ class ImagePreviewNode extends BlockContentNode {
   ///
   /// This may be a relative URL string. It also may not work without adding
   /// authentication credentials to the request.
-  final String srcUrl;
+  ///
+  /// Clients are expected to use this URL when saving the image to the device.
+  ///
+  /// For images processed in modern thumbnailing (as of 2026-01),
+  /// this is also meant for viewing the image by itself, in a lightbox
+  /// (but if `data-transcoded-image` is present, it's better to use that [1]).
+  /// The modern-thumbnailing case is recognized when [loading] is true
+  /// or when [src] is an [ImagePreviewNodeSrcThumbnail].
+  /// From discussion:
+  ///   https://chat.zulip.org/#narrow/channel/412-api-documentation/topic/documenting.20inline.20images/near/2279483
+  ///
+  /// [1] The "transcoded image" feature is meant to keep the lightbox working
+  ///     when the original image is in an uncommon format, like TIFF.
+  ///     This isn't implemented yet; it's #1268.
+  // TODO(#1268) implement transcoded-image feature; update dartdoc
+  final String originalSrc;
 
-  /// The thumbnail URL of the image and whether it has an animated version.
+  /// A URL for the image intended to be shown here in Zulip content.
+  ///
+  /// If [loading] is true, this will point to a "spinner" image.
+  /// Clients are invited to show a custom loading indicator instead; we do.
   ///
-  /// This will be null if the server hasn't yet generated a thumbnail,
-  /// or is a version that doesn't offer thumbnails.
-  /// It will also be null when [loading] is true.
-  final ImageThumbnailLocator? thumbnail;
+  /// Except for images processed in modern thumbnailing (2026-01),
+  /// this is also meant for viewing the image by itself, in a lightbox.
+  /// For how to recognize that case, see [originalSrc].
+  final ImagePreviewNodeSrc src;
 
-  /// A flag to indicate whether to show the placeholder.
+  /// Whether the img has the "image-loading-placeholder" classname.
   ///
-  /// Typically it will be `true` while Server is generating thumbnails.
+  /// This is expected to be true (as of 2026-01)
+  /// while an uploaded image is being thumbnailed.
+  ///
+  /// When this is true, [src] will point to a "spinner" image.
+  /// Clients are invited to show a custom loading indicator instead; we do.
   final bool loading;
 
-  /// The width of the canonical image.
+  /// The width part of data-original-dimensions, if that attribute is present.
   final double? originalWidth;
 
-  /// The height of the canonical image.
+  /// The height part of data-original-dimensions, if that attribute is present.
   final double? originalHeight;
 
   @override
   bool operator ==(Object other) {
     return other is ImagePreviewNode
-      && other.srcUrl == srcUrl
-      && other.thumbnail == thumbnail
+      && other.originalSrc == originalSrc
+      && other.src == src
       && other.loading == loading
       && other.originalWidth == originalWidth
       && other.originalHeight == originalHeight;
   }
 
   @override
   int get hashCode => Object.hash('ImagePreviewNode',
-    srcUrl, thumbnail, loading, originalWidth, originalHeight);
+    originalSrc, src, loading, originalWidth, originalHeight);
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
-    properties.add(StringProperty('srcUrl', srcUrl));
-    properties.add(DiagnosticsProperty<ImageThumbnailLocator>('thumbnail', thumbnail));
+    properties.add(StringProperty('originalSrc', originalSrc));
+    properties.add(DiagnosticsProperty<ImagePreviewNodeSrc>('src', src));
     properties.add(FlagProperty('loading', value: loading, ifTrue: "is loading"));
     properties.add(DoubleProperty('originalWidth', originalWidth));
     properties.add(DoubleProperty('originalHeight', originalHeight));
   }
 }
 
+/// A value of [ImagePreviewNode.src].
+sealed class ImagePreviewNodeSrc extends DiagnosticableTree {
+  const ImagePreviewNodeSrc();
+}
+
+/// A thumbnail URL, starting with [ImageThumbnailLocator.srcPrefix].
+class ImagePreviewNodeSrcThumbnail extends ImagePreviewNodeSrc {
+  const ImagePreviewNodeSrcThumbnail(this.value);
+
+  final ImageThumbnailLocator value;
+
+  @override
+  bool operator ==(Object other) {
+    return other is ImagePreviewNodeSrcThumbnail && other.value == value;
+  }
+
+  @override
+  int get hashCode => Object.hash('ImagePreviewNodeSrcThumbnail', value);
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(DiagnosticsProperty<ImageThumbnailLocator>('value', value));
+  }
+}
+
+/// A `src` that does not start with [ImageThumbnailLocator.srcPrefix].
+///
+/// This may be a relative URL string. It also may not work without adding
+/// authentication credentials to the request.
+// In 2026-01, this class covers these known cases:
+// - This may be a hard-coded "spinner" image,
+//   when thumbnailing of an uploaded image is in progress.
+// - This may match `href`, e.g. from pre-thumbnailing servers.
+// - This may start with CAMO_URI, a server variable (e.g. on Zulip Cloud
+//   it's "https://uploads.zulipusercontent.net/" in 2025-10).
+class ImagePreviewNodeSrcOther extends ImagePreviewNodeSrc {
+  const ImagePreviewNodeSrcOther(this.value);
+
+  final String value;
+
+  @override
+  bool operator ==(Object other) {
+    return other is ImagePreviewNodeSrcOther && other.value == value;
+  }
+
+  @override
+  int get hashCode => Object.hash('ImagePreviewNodeSrcOther', value);
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(StringProperty('value', value));
+  }
+}
+
 /// Data to locate an image thumbnail,
 /// and whether the image has an animated version.
 ///
@@ -1436,31 +1514,15 @@ class _ZulipContentParser {
     final src = imgElement.attributes['src'];
     if (src == null) return null;
     final loading = imgElement.className == 'image-loading-placeholder';
-
-    final String srcUrl;
-    final ImageThumbnailLocator? thumbnail;
-    if (loading) {
-      // This lets us offer a lightbox showing the full image,
-      // even while the thumbnail is loading.
-      srcUrl = href;
-      thumbnail = null; // (The thumbnail is the thing that's loading.)
-    } else if (src.startsWith(ImageThumbnailLocator.srcPrefix)) {
-      final parsedSrc = Uri.tryParse(src);
-      if (parsedSrc == null) return null;
-
+    ImageThumbnailLocator? thumbnailSrc;
+    if (src.startsWith(ImageThumbnailLocator.srcPrefix)) {
+      final srcUrl = Uri.tryParse(src);
+      if (srcUrl == null) return null;
       // For why we recognize this as the thumbnail form, see discussion:
       //   https://chat.zulip.org/#narrow/channel/412-api-documentation/topic/documenting.20inline.20images/near/2279872
-      srcUrl = href;
-      thumbnail = ImageThumbnailLocator(
-        defaultFormatSrc: parsedSrc,
+      thumbnailSrc = ImageThumbnailLocator(
+        defaultFormatSrc: srcUrl,
         animated: imgElement.attributes['data-animated'] == 'true');
-    } else {
-      // Known cases this handles:
-      // - `src` starts with CAMO_URI, a server variable (e.g. on Zulip Cloud
-      //   it's "https://uploads.zulipusercontent.net/" in 2025-10).
-      // - `src` matches `href`, e.g. from pre-thumbnailing servers.
-      srcUrl = src;
-      thumbnail = null;
     }
 
     double? originalWidth, originalHeight;
@@ -1483,8 +1545,10 @@ class _ZulipContentParser {
     }
 
     return ImagePreviewNode(
-      srcUrl: srcUrl,
-      thumbnail: thumbnail,
+      originalSrc: href,
+      src: thumbnailSrc != null
+        ? ImagePreviewNodeSrcThumbnail(thumbnailSrc)
+        : ImagePreviewNodeSrcOther(src),
       loading: loading,
       originalWidth: originalWidth,
       originalHeight: originalHeight,

lib/widgets/content.dart

@@ -636,15 +636,18 @@ class MessageImagePreview extends StatelessWidget {
     final store = PerAccountStoreWidget.of(context);
     final message = InheritedMessage.of(context);
 
-    final resolvedThumbnailUrl = node.thumbnail?.resolve(context,
-      width: MessageMediaContainer.width,
-      height: MessageMediaContainer.height,
-      animationMode: ImageAnimationMode.animateConditionally);
-
-    final urlInPreview = node.thumbnail != null
-      ? resolvedThumbnailUrl
-      : store.tryResolveUrl(node.srcUrl);
-    final child = switch ((node.loading, urlInPreview)) {
+    final resolvedSrc = switch (node.src) {
+      ImagePreviewNodeSrcThumbnail(:final value) => value.resolve(context,
+        width: MessageMediaContainer.width,
+        height: MessageMediaContainer.height,
+        animationMode: .animateConditionally),
+      ImagePreviewNodeSrcOther(:final value) => store.tryResolveUrl(value),
+    };
+    final resolvedOriginalSrc = store.tryResolveUrl(node.originalSrc);
+
+    final child = switch ((node.loading, resolvedSrc)) {
+      // resolvedSrc would be a "spinner" image URL.
+      // Use our own progress indicator instead.
       (true, _) => const CupertinoActivityIndicator(),
 
       // TODO(#265) use an error-case placeholder
@@ -654,10 +657,12 @@ class MessageImagePreview extends StatelessWidget {
       (false, Uri()) => RealmContentNetworkImage(
         // TODO(#265) use an error-case placeholder for `errorBuilder`
         filterQuality: FilterQuality.medium,
-        urlInPreview!),
+        resolvedSrc!),
     };
 
-    final lightboxDisplayUrl = store.tryResolveUrl(node.srcUrl);
+    final lightboxDisplayUrl = (node.loading || node.src is ImagePreviewNodeSrcThumbnail)
+      ? resolvedOriginalSrc
+      : resolvedSrc;
     if (lightboxDisplayUrl == null) {
       // TODO(log)
       return MessageMediaContainer(onTap: null, child: child);
@@ -670,7 +675,9 @@ class MessageImagePreview extends StatelessWidget {
           message: message,
           messageImageContext: context,
           src: lightboxDisplayUrl,
-          thumbnailUrl: resolvedThumbnailUrl,
+          thumbnailUrl: (node.src is ImagePreviewNodeSrcThumbnail && !node.loading)
+            ? resolvedSrc
+            : null,
           originalWidth: node.originalWidth,
           originalHeight: node.originalHeight));
       },