camera: previewRotationQuarterTurns + async previewSize event

Black-screen + extra-90°-rotation on Android both came from
AVFoundation vs CameraX behaving differently at the preview output:

  - AVFoundation: data-output connection's `videoOrientation`
    pre-rotates sample buffers. The Flutter Texture displays them
    upright; `device.activeFormat` reports the sensor-native size
    synchronously.
  - CameraX: the SurfaceProvider hands back a Surface; CameraX
    writes raw sensor frames into it. Rotation is a *transform hint*
    via Preview.setTargetRotation that consumers must apply
    themselves. And the final negotiated resolution isn't known
    until the first SurfaceRequest fires — which happens AFTER
    bindToLifecycle, AFTER lifecycle.start, async on the camera
    executor. So `create` was returning Size(0,0).

Surface extension to bridge the gap:

  - UxCameraValue.previewRotationQuarterTurns (int 0/1/2/3).
    iOS native always emits 0; Android native emits
    `(sensorRotationDegrees / 90) % 4` for the active camera.
    [UxCameraPreview] wraps the Texture in a RotatedBox by that many
    quarter-turns (applied *before* the front-cam mirror so the
    flip lives in screen space, not sensor space).

  - UxCameraPreviewSizeChanged event. Android emits this from
    PreviewSink.onResize whenever a SurfaceRequest carries a new
    resolution; the controller copies it into value.previewSize.
    First emission is what unblocks the camera_thumb's SizedBox
    from its initial 0x0 = "render nothing" state.

  - UxCameraBackend.setDescription's return changed from `Size` to
    `({Size previewSize, int previewRotationQuarterTurns})` so
    a lens swap can both update the rotation and signal that a new
    previewSizeChanged event is incoming.

iOS continues to send previewSize in the create result (the active
format is known synchronously); no previewSizeChanged emission is
needed there. The new field is set to 0 in both create and
setDescription results on iOS.

lib/src/camera/camera.dart

@@ -71,6 +71,7 @@ class UxCameraValue {
     this.deviceOrientation = DeviceOrientation.portraitUp,
     this.enableAudio = false,
     this.audioPermissionGranted = false,
+    this.previewRotationQuarterTurns = 0,
     this.errorDescription,
   });
 
@@ -103,6 +104,16 @@ class UxCameraValue {
   /// no audio track and callers should surface a hint.
   final bool audioPermissionGranted;
 
+  /// Number of 90° clockwise rotations the preview Texture needs so
+  /// the sensor frames display upright. On iOS the data output
+  /// pre-rotates via `AVCaptureConnection.videoOrientation` and this
+  /// is always 0. On Android CameraX delivers sensor-native frames to
+  /// the Surface and the consumer rotates — typically 1 for
+  /// `sensorOrientation: 90` back cams and 3 for `sensorOrientation:
+  /// 270` front cams. Applied inside [UxCameraPreview]; consumers
+  /// don't read this directly.
+  final int previewRotationQuarterTurns;
+
   /// Set to the last native session error's message when one fires.
   /// Cleared on the next successful state transition.
   final String? errorDescription;
@@ -117,6 +128,7 @@ class UxCameraValue {
     DeviceOrientation? deviceOrientation,
     bool? enableAudio,
     bool? audioPermissionGranted,
+    int? previewRotationQuarterTurns,
     Object? errorDescription = _unset,
   }) =>
       UxCameraValue(
@@ -127,6 +139,8 @@ class UxCameraValue {
         deviceOrientation: deviceOrientation ?? this.deviceOrientation,
         enableAudio: enableAudio ?? this.enableAudio,
         audioPermissionGranted: audioPermissionGranted ?? this.audioPermissionGranted,
+        previewRotationQuarterTurns:
+            previewRotationQuarterTurns ?? this.previewRotationQuarterTurns,
         errorDescription: identical(errorDescription, _unset)
             ? this.errorDescription
             : errorDescription as String?,
@@ -211,6 +225,7 @@ class UxCameraController extends ValueNotifier<UxCameraValue> {
       value = value.copyWith(
         isInitialized: true,
         previewSize: result.previewSize,
+        previewRotationQuarterTurns: result.previewRotationQuarterTurns,
         audioPermissionGranted: audioGranted,
       );
     } catch (_) {
@@ -235,6 +250,8 @@ class UxCameraController extends ValueNotifier<UxCameraValue> {
         break;
       case UxCameraDiagnostic(:final message):
         _log.i('recorder: $message');
+      case UxCameraPreviewSizeChanged(:final previewSize):
+        value = value.copyWith(previewSize: previewSize);
     }
   }
 
@@ -257,8 +274,12 @@ class UxCameraController extends ValueNotifier<UxCameraValue> {
   /// recording is in flight — call [stopVideoRecording] first.
   Future<void> setDescription(UxCameraDescription description) async {
     final handle = _requireHandle('setDescription');
-    final size = await UxCameraBackend.instance.setDescription(handle, description.id);
-    value = value.copyWith(description: description, previewSize: size);
+    final r = await UxCameraBackend.instance.setDescription(handle, description.id);
+    value = value.copyWith(
+      description: description,
+      previewSize: r.previewSize,
+      previewRotationQuarterTurns: r.previewRotationQuarterTurns,
+    );
   }
 
   Future<void> setFlashMode(UxFlashMode mode) async {

lib/src/camera/camera_backend.dart

@@ -47,8 +47,13 @@ abstract class UxCameraBackend {
   Future<void> disposeInstance(int handle);
 
   /// Swap to a different camera mid-session. Resets the lock and clears
-  /// any pending recording. Returns the new preview size.
-  Future<Size> setDescription(int handle, String cameraId);
+  /// any pending recording. Returns the new preview size and rotation;
+  /// the size may again be `Size.zero` initially on Android, with a
+  /// follow-up [UxCameraPreviewSizeChanged] event.
+  Future<({Size previewSize, int previewRotationQuarterTurns})> setDescription(
+    int handle,
+    String cameraId,
+  );
 
   /// Set the flash mode used for the next [takePicture]. On front cameras
   /// without a screen-flash fallback the backend silently no-ops; the
@@ -104,11 +109,21 @@ class UxCameraCreateResult {
     required this.handle,
     required this.textureId,
     required this.previewSize,
+    this.previewRotationQuarterTurns = 0,
   });
 
   final int handle;
   final int textureId;
+
+  /// Initial preview size; may be `Size.zero` when the native side
+  /// can't determine it synchronously (Android CameraX needs the
+  /// first `SurfaceRequest` to fire before it knows). In that case
+  /// a [UxCameraPreviewSizeChanged] event follows.
   final Size previewSize;
+
+  /// Number of 90° CW rotations the Texture widget needs. iOS: 0.
+  /// Android: derived from the selected camera's sensor orientation.
+  final int previewRotationQuarterTurns;
 }
 
 /// Events pushed by the native side over `ux/camera/events`. Sealed —
@@ -138,6 +153,16 @@ class UxCameraSessionResumed extends UxCameraEvent {
   const UxCameraSessionResumed(super.handle);
 }
 
+/// Fired when the native side learns or revises the preview's pixel
+/// dimensions. Android emits this after CameraX's first
+/// `SurfaceRequest` resolves (the size isn't known at `create` time);
+/// iOS doesn't emit it (the size lands in the `create` result
+/// synchronously from `device.activeFormat`).
+class UxCameraPreviewSizeChanged extends UxCameraEvent {
+  const UxCameraPreviewSizeChanged(super.handle, this.previewSize);
+  final Size previewSize;
+}
+
 /// Free-text diagnostic message from the native recorder. Routed by
 /// the controller to `Log.tag('camera').i(...)` so it lands in the
 /// log_server pipeline (`~/banlu/tools/log_server/data/banlu.jsonl`).

lib/src/camera/camera_channel.dart

@@ -58,6 +58,8 @@ class MethodChannelUxCameraBackend implements UxCameraBackend {
         (size['width'] as num).toDouble(),
         (size['height'] as num).toDouble(),
       ),
+      previewRotationQuarterTurns:
+          (m['previewRotationQuarterTurns'] as num?)?.toInt() ?? 0,
     );
   }
 
@@ -70,15 +72,22 @@ class MethodChannelUxCameraBackend implements UxCameraBackend {
       _invokeVoid('dispose', {'handle': handle});
 
   @override
-  Future<Size> setDescription(int handle, String cameraId) async {
+  Future<({Size previewSize, int previewRotationQuarterTurns})> setDescription(
+    int handle,
+    String cameraId,
+  ) async {
     final m = await _invokeMap('setDescription', {
       'handle': handle,
       'cameraId': cameraId,
     });
     final s = (m['previewSize'] as Map).cast<Object?, Object?>();
-    return Size(
-      (s['width'] as num).toDouble(),
-      (s['height'] as num).toDouble(),
+    return (
+      previewSize: Size(
+        (s['width'] as num).toDouble(),
+        (s['height'] as num).toDouble(),
+      ),
+      previewRotationQuarterTurns:
+          (m['previewRotationQuarterTurns'] as num?)?.toInt() ?? 0,
     );
   }
 
@@ -173,6 +182,15 @@ class MethodChannelUxCameraBackend implements UxCameraBackend {
           handle,
           m['message'] as String? ?? '',
         );
+      case 'previewSizeChanged':
+        final s = (m['previewSize'] as Map).cast<Object?, Object?>();
+        return UxCameraPreviewSizeChanged(
+          handle,
+          Size(
+            (s['width'] as num).toDouble(),
+            (s['height'] as num).toDouble(),
+          ),
+        );
       default:
         return UxCameraSessionError(handle, 'unknown_event', null);
     }

lib/src/camera/camera_preview.dart

@@ -27,11 +27,18 @@ class UxCameraPreview extends StatelessWidget {
       builder: (context, value, _) {
         final id = controller.textureId;
         if (id == null) return SizedBox.expand();
-        final mirror = value.description.lens == UxCameraLens.front;
-        final texture = Texture(textureId: id);
-        return mirror
-            ? Transform.flip(flipX: true, child: texture)
-            : texture;
+        Widget child = Texture(textureId: id);
+        // Order matters: rotate first (sensor → screen frame), then
+        // mirror in screen space. Reversing them would mirror across
+        // an axis that's still aligned with the sensor.
+        final turns = value.previewRotationQuarterTurns;
+        if (turns != 0) {
+          child = RotatedBox(quarterTurns: turns, child: child);
+        }
+        if (value.description.lens == UxCameraLens.front) {
+          child = Transform.flip(flipX: true, child: child);
+        }
+        return child;
       },
     );
   }