From 6871ae130ee9f85ef3a04a5654ddafc0c85bdf6e Mon Sep 17 00:00:00 2001
From: fufesou <linlong1266@gmail.com>
Date: Sat, 12 Sep 2026 10:46:05 +0800
Subject: [PATCH] docs(cursor): clarify optional capture metadata and rendering
 scope

---
 flutter/lib/desktop/pages/remote_page.dart | 2 ++
 flutter/lib/models/model.dart              | 5 +++--
 libs/base/protos/message.proto             | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/flutter/lib/desktop/pages/remote_page.dart b/flutter/lib/desktop/pages/remote_page.dart
index cf33ff48b..12f8f365c 100644
--- a/flutter/lib/desktop/pages/remote_page.dart
+++ b/flutter/lib/desktop/pages/remote_page.dart
@@ -1116,6 +1116,8 @@ class _ImagePaintState extends State<ImagePaint> {
             if (!isWeb && isViewScaled() && !zoomCursor.value && peerDpr > 0) {
               return (isWindows ? dpr : 1.0) / peerDpr;
             }
+            // Density metadata is optional. Keep the legacy path for hosts that
+            // omit it so capture-backend upgrades are not a client prerequisite.
             var cursorScale = 1.0;
             if (isWindows) {
               // debug win10
diff --git a/flutter/lib/models/model.dart b/flutter/lib/models/model.dart
index 56e4b31c3..520bf6cbb 100644
--- a/flutter/lib/models/model.dart
+++ b/flutter/lib/models/model.dart
@@ -2850,7 +2850,8 @@ class CanvasModel with ChangeNotifier {
   }
 }
 
-// data for cursor
+// Scale the host's bitmap and hotspot together. Incorrect source geometry
+// must be fixed in host capture, independently of the client's sizing policy.
 class CursorData {
   final String peerId;
   final String id;
@@ -2858,7 +2859,7 @@ class CursorData {
   // Borrowed from CursorModel/PredefinedCursor, which own its lifetime.
   // The plugin clones the handle before starting asynchronous encoding.
   final ui.Image nativeImage;
-  // Zero preserves sizing for peers that predate cursor density metadata.
+  // Zero preserves legacy sizing for capture backends without density metadata.
   final double pixelRatio;
   double scale;
   Uint8List? data;
diff --git a/libs/base/protos/message.proto b/libs/base/protos/message.proto
index 718f35e4c..1d8eccc0c 100644
--- a/libs/base/protos/message.proto
+++ b/libs/base/protos/message.proto
@@ -316,7 +316,7 @@ message CursorData {
   int32 width = 4;
   int32 height = 5;
   bytes colors = 6;
-  // Physical bitmap pixels per remote logical pixel; 0 means an older sender.
+  // Physical bitmap pixels per remote logical pixel; 0 means unknown density.
   double scale = 7;
 }