@pickleball/rtmp-native 0.1.0 → 0.2.0

package/ios/PickleballRtmpNativeModule.swift

@@ -1,7 +1,20 @@
 import AVFoundation
+import CoreImage
 import ExpoModulesCore
 import HaishinKit
+import ImageIO
 import UIKit
+import VideoToolbox
+
+/// Xin quyền camera + mic qua AVFoundation. SDK 1.0 gỡ LiveKit/WebRTC nên không
+/// còn getUserMedia để "mượn" hộp thoại quyền; hỏi ở đây TRƯỚC khi prepare —
+/// hỏi trong lúc AVCaptureSession đang dựng là camera đen im lặng ở lần đầu.
+/// Hỏi tuần tự (video rồi audio) để hai hộp thoại không chồng nhau.
+private func requestCaptureAccess() async -> Bool {
+  let video = await AVCaptureDevice.requestAccess(for: .video)
+  let audio = await AVCaptureDevice.requestAccess(for: .audio)
+  return video && audio
+}
 
 /// Cầu nối Expo cho mode deliveryMode="device-rtmp".
 ///
@@ -13,18 +26,75 @@ import UIKit
 public final class PickleballRtmpNativeModule: Module {
   private var mixer: MediaMixer?
   private var session: (any Session)?
+  /// Tổng byte đã RỜI máy (socket RTMP, NetworkMonitor báo mỗi ~1s qua
+  /// BandwidthReportingStrategy). -1 = chưa có số liệu. Watchdog publish so
+  /// mốc đổi gần nhất để bắt ca "TCP sống mà không frame nào đi" — chính là ca
+  /// 26/08/2026: 2 phiên mất 10-13 phút đuôi footage trong khi isConnected
+  /// vẫn true và app vẫn tưởng mình phát tốt.
+  private var bytesOutSeen: Int = -1
+  private var bytesOutChangedAt = Date.distantPast
+  /// Mốc event NetworkMonitor gần nhất — actor socket treo cứng là event tắt hẳn.
+  private var monitorEventAt = Date.distantPast
+  /// Từ lúc nào fps video = 0 trong khi vẫn publish. Đây là chữ ký đo được
+  /// 26/08: encoder VIDEO chết (nghi thermal) nhưng AUDIO vẫn chảy — byte vẫn
+  /// nhích nên luật byte mù, chỉ fps mới tố được.
+  private var fpsZeroSince: Date?
   // PHẢI khớp mặc định của engine (`isCameraFront: false`) và LiveKitRoomAdapter.
   // Lệch một chỗ là nhãn UI và hình thực tế ngược nhau vĩnh viễn, và
   // switchCamera() càng làm lệch thêm.
   private var cameraPosition: AVCaptureDevice.Position = .back
   private var microphoneEnabled = true
   private var publishing = false
+  /// Đồng hồ canh socket RTMP khi đang publish. iOS KHÔNG có callback đứt kết
+  /// nối như Android (ConnectChecker.onDisconnect) — HaishinKit chỉ lộ
+  /// `session.isConnected`, không ai chủ động báo. Thiếu watchdog này thì app
+  /// hiện "đang phát" vô hạn sau khi server reset socket (quan sát prod
+  /// 17/08/2026: phiên chết 01:15:43, app im lặng, không thử lại).
+  private var publishWatchdog: Task<Void, Never>?
   private var videoBitrate = 6_000_000
   private var videoSize = CGSize(width: 1920, height: 1080)
+  /// Ống kính đang gắn — nguồn cho capabilities và các control zoom/EV/lock.
+  private var currentVideoDevice: AVCaptureDevice?
+  /// State controls người dùng đã chọn — đổi lens reset state trên
+  /// AVCaptureDevice nên phải áp lại sau mỗi attachVideo.
+  private var zoomFactor: Double?
+  private var exposureBiasValue: Double?
+  private var focusLocked = false
+  private var exposureLocked = false
+  private var torchEnabled = false
+  /// Trần zoom thực dụng — vượt quá là ảnh vỡ hạt, không có giá trị cho live thể thao.
+  private static let maxZoomCap: CGFloat = 8
   /// SessionBuilderFactory KHÔNG có sẵn factory nào — phải tự đăng ký, nếu không
   /// build() ném Error.notFound (error 1). Đăng ký một lần cho cả vòng đời app.
   private static var sessionFactoriesRegistered = false
   private var orientationObserver: NSObjectProtocol?
+  /// Tap giữ khung hình mới nhất cho snapshot() (dashboard xem trước từ xa).
+  /// Thêm vào mixer ở prepare(), gỡ ở teardown(). Không đụng publish/preview.
+  private let snapshotOutput = SnapshotOutput()
+  /// Logo giải cần nướng vào khung hình (BTC đặt trên dashboard, thiết bị nhận
+  /// kèm nhịp beat rồi tải ảnh về đĩa). `nil` = không vẽ gì → mixer giữ nguyên
+  /// `.passthrough` như trước, không tốn thêm một vòng render nào.
+  private var overlayLogoSpec: OverlayLogoOptions?
+  /// Đối tượng vẽ trên `Screen`. Isolate ở `ScreenActor` giống chính `screen`
+  /// của HaishinKit — mọi lượt đọc/ghi đều nằm trong `applyOverlayOnScreen`.
+  @ScreenActor
+  private var overlayLogoObject: ImageScreenObject?
+  /// Các lớp overlay ĐỘNG (gif chạy khung / video lặp) — thứ tự mảng là thứ tự
+  /// chồng lớp, vẽ TRÊN composite tĩnh. Rỗng = không có lớp động nào.
+  private var overlayAnimatedSpecs: [OverlayAnimatedOptions] = []
+  /// Object đang gắn trên screen theo id lớp — cùng kỷ luật ScreenActor và cùng
+  /// bài học 9d5414e: screen chết theo phiên, object sống xuyên phiên, mỗi lần
+  /// áp phải detach khỏi parent THẬT rồi gắn lại.
+  @ScreenActor
+  private var overlayAnimatedObjects: [String: ScreenObject] = [:]
+  /// Vòng đổi khung gif / vòng canh lặp video theo id — huỷ khi lớp bị gỡ/đổi.
+  private var overlayAnimatedTasks: [String: Task<Void, Never>] = [:]
+  /// Các lớp CHỮ đã điền sẵn (JS điền template tỉ số/tên đội, native chỉ vẽ) —
+  /// trên cùng mọi lớp khác. Chuỗi đổi ~2 lần/phút theo pha bóng.
+  private var overlayTextSpecs: [OverlayTextOptions] = []
+  /// Object chữ theo id — cùng kỷ luật ScreenActor + detach-parent-thật (9d5414e).
+  @ScreenActor
+  private var overlayTextObjects: [String: ImageScreenObject] = [:]
 
   public func definition() -> ModuleDefinition {
     Name("PickleballRtmpNative")
@@ -33,6 +103,12 @@ public final class PickleballRtmpNativeModule: Module {
     // View hiển thị camera. Thiếu nó thì màn preview tối đen dù camera đã mở.
     View(PickleballRtmpPreviewView.self) {}
 
+    // Quyền camera/mic — JS (createRtmpRuntime) gọi trước prepare; binary cũ
+    // không có hàm này nên JS guard typeof và để AVFoundation tự hỏi lúc mở.
+    AsyncFunction("requestPermissions") { () -> Bool in
+      await requestCaptureAccess()
+    }
+
     AsyncFunction("prepare") { (options: PrepareOptions) in
       try await self.prepare(options)
     }
@@ -79,15 +155,87 @@ public final class PickleballRtmpNativeModule: Module {
       await self.applyVideoBitrate(bitsPerSecond)
     }
 
+    // ===== Camera controls (app device-streamer) — toàn API public AVFoundation =====
+
+    AsyncFunction("getCameraCapabilities") { () -> [String: Any] in
+      self.cameraCapabilities()
+    }
+
+    AsyncFunction("setZoom") { (factor: Double) in
+      self.zoomFactor = factor
+      try self.applyZoom(factor)
+    }
+
+    AsyncFunction("setExposureBias") { (ev: Double) in
+      self.exposureBiasValue = ev
+      try self.applyExposureBias(ev)
+    }
+
+    AsyncFunction("setFocusLocked") { (locked: Bool) in
+      self.focusLocked = locked
+      try self.applyFocusLocked(locked)
+    }
+
+    AsyncFunction("setExposureLocked") { (locked: Bool) in
+      self.exposureLocked = locked
+      try self.applyExposureLocked(locked)
+    }
+
+    AsyncFunction("setTorch") { (enabled: Bool) in
+      self.torchEnabled = enabled
+      await self.mixer?.setTorchEnabled(enabled)
+    }
+
     Function("getStats") {
       [
         "isConnected": self.session != nil,
         "isPublishing": self.publishing,
         "videoBitrate": self.videoBitrate,
         "currentFps": 0,
+        // Tổng byte đã rời máy — số liệu chẩn đoán cho ca media-stall; -1 khi
+        // NetworkMonitor chưa báo lần nào.
+        "totalBytesOut": self.bytesOutSeen,
       ] as [String: Any]
     }
 
+    /**
+     Logo nướng vào khung hình. `nil` = gỡ logo.
+
+     Hình học tính SẴN Ở JS bằng `logoRect()` của @pickleball/shared — cùng công
+     thức dashboard dùng để vẽ preview. Cố ý KHÔNG tính lại ở đây: hai bản công
+     thức là hai thứ lệch nhau được, mà cái lệch đó bị nướng vĩnh viễn vào video.
+     */
+    AsyncFunction("setOverlayLogo") { (options: OverlayLogoOptions?) -> [String: Any] in
+      await self.setOverlayLogo(options)
+    }
+
+    AsyncFunction("setOverlayAnimated") { (items: [OverlayAnimatedOptions]?) -> [String: Any] in
+      await self.setOverlayAnimated(items)
+    }
+
+    AsyncFunction("setOverlayTexts") { (items: [OverlayTextOptions]?) -> [String: Any] in
+      await self.setOverlayTexts(items)
+    }
+
+    AsyncFunction("getDeviceHealth") { () -> [String: Any] in
+      Self.deviceHealth()
+    }
+
+    // iOS không có API tương đương ApplicationExitInfo (MetricKit chỉ giao
+    // chẩn đoán crash theo lô, trễ tới 24h) — trả rỗng để JS gọi đồng nhất.
+    AsyncFunction("getProcessExitReasons") { (max: Int) -> [[String: Any]] in
+      _ = max
+      return []
+    }
+
+    // Chụp 1 ảnh JPEG base64 từ khung hình đang compose — dashboard xem trước từ xa.
+    AsyncFunction("snapshot") { () -> String in
+      guard let base64 = self.snapshotOutput.snapshotBase64(maxWidth: 480, quality: 0.5) else {
+        throw RtmpException("chưa có khung hình để chụp (camera chưa chạy)")
+      }
+      return base64
+    }
+
     AsyncFunction("dispose") {
       await self.teardown()
     }
@@ -124,20 +272,38 @@ public final class PickleballRtmpNativeModule: Module {
       ? CGSize(width: 1280, height: 720)
       : CGSize(width: 1920, height: 1080)
 
-    try await mixer.attachVideo(
-      AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: cameraPosition),
-      track: 0
-    ) { unit in
+    // Ống kính người dùng đã chọn được ưu tiên; id không còn tồn tại trên máy
+    // thì lặng lẽ quay về wide mặc định thay vì ném lỗi và chặn cả phiên.
+    let requested = options.cameraId.flatMap { id in
+      availableCameras().first { $0.uniqueID == id }
+    }
+    let device = requested ?? AVCaptureDevice.default(
+      .builtInWideAngleCamera, for: .video, position: cameraPosition
+    )
+    if let requested {
+      cameraPosition = requested.position == .front ? .front : .back
+    }
+    try await mixer.attachVideo(device, track: 0) { unit in
       // Lần gắn đầu cũng phải lật gương như switchCamera(), nếu không khởi động
       // bằng camera trước sẽ hiện ngược so với mode LiveKit.
       unit.isVideoMirrored = self.cameraPosition == .front
     }
+    currentVideoDevice = device
     if microphoneEnabled {
       try await mixer.attachAudio(AVCaptureDevice.default(for: .audio))
     }
     await applyVideoOrientation()
     observeOrientation()
     await mixer.startRunning()
+    // setFrameRate PHẢI đứng SAU startRunning(). AVCaptureSession áp lại
+    // sessionPreset lúc chạy, và preset ghi đè activeFormat — cuốn theo cả
+    // activeVideoMin/MaxFrameDuration vừa đặt. Đặt trước thì 24fps bị nuốt và
+    // ra 30 (đo thật: 29,85fps), trong khi 60fps lại sống sót vì nó buộc
+    // HaishinKit ĐỔI hẳn activeFormat và session chuyển sang inputPriority.
+    await mixer.setFrameRate(Float64(options.frameRate))
+    await reapplyCameraControls()
+    // Tap snapshot nhận khung compose như MTHKView — cho phép chụp ảnh xem trước.
+    await mixer.addOutput(snapshotOutput)
     emitStatus(["status": "idle"])
   }
 
@@ -151,6 +317,28 @@ public final class PickleballRtmpNativeModule: Module {
 
     await Self.registerSessionFactories()
 
+    // Dọn session cũ TRƯỚC khi dựng cái mới. Thiếu đoạn này thì `self.session =
+    // built` bên dưới chỉ thay con trỏ: socket RTMP cũ vẫn mở và stream cũ vẫn
+    // nằm trong mixer, không ai tham chiếu tới nữa nhưng vẫn sống.
+    //
+    // Vì sao connect() bị gọi nhiều lần: engine.ts gọi nó ở start() và LẠI gọi ở
+    // reconnect() sau mỗi lỗi. Mỗi vòng reconnect rò một socket.
+    //
+    // Đã quan sát trên prod 16/08/2026 (phiên k972erjy…): MediaMTX nhận BA kết
+    // nối RTMP từ cùng một máy cho một lần publish. Hai cái mồ côi chết vì
+    // `i/o timeout` sau 30s (chúng chưa từng publish), và khi path bị dọn theo
+    // thì socket ĐANG SỐNG chết cùng — `connection reset by peer` cùng giây đó.
+    // Phiên tắt sau 24,1 giây, playlist đóng băng, còn app vẫn hiện "đang phát"
+    // vì `publishing` chưa bao giờ được đặt lại.
+    if let stale = session {
+      stopPublishWatchdog()
+      let staleStream = await stale.stream
+      await mixer.removeOutput(staleStream)
+      try? await stale.close()
+      session = nil
+      publishing = false
+    }
+
     emitStatus(["status": "connecting"])
     do {
       // build() trả optional: URL sai scheme (không phải rtmp/srt) thì trả nil
@@ -167,6 +355,35 @@ public final class PickleballRtmpNativeModule: Module {
       await applyVideoBitrate(options.videoBitrate)
       await applyAudioBitrate(options.audioBitrate)
 
+      // NetworkMonitor của HaishinKit phát hiện nghẽn (hàng đợi gửi phình ra
+      // liên tục) và đưa sự kiện vào bitrate strategy. Strategy của mình KHÔNG
+      // tự chỉnh — chỉ báo onBandwidth cho JS để chính sách hạ/hồi nằm một chỗ
+      // (RtmpRoomAdapter) cho cả Android lẫn iOS.
+      if let rtmpStream = stream as? RTMPStream {
+        await rtmpStream.setBitrateStorategy(
+          BandwidthReportingStrategy { [weak self] sufficient, totalBytesOut, fps in
+            guard let self else { return }
+            // Nuôi watchdog media-stall TRƯỚC guard publishing: mốc byte phải
+            // sống cả lúc chưa publish để lần publish kế không so với mốc cũ.
+            self.monitorEventAt = Date()
+            if totalBytesOut != self.bytesOutSeen {
+              self.bytesOutSeen = totalBytesOut
+              self.bytesOutChangedAt = Date()
+            }
+            if fps > 0 {
+              self.fpsZeroSince = nil
+            } else if self.fpsZeroSince == nil {
+              self.fpsZeroSince = Date()
+            }
+            guard self.publishing else { return }
+            self.sendEvent("onBandwidth", [
+              "sufficient": sufficient,
+              "videoBitrate": self.videoBitrate,
+            ])
+          }
+        )
+      }
+
       emitStatus(["status": "connected"])
       if options.publish {
         try await setPublishing(true)
@@ -184,6 +401,34 @@ public final class PickleballRtmpNativeModule: Module {
 
   /// `SessionBuilderFactory.shared` khởi tạo RỖNG. Thiếu bước này thì mọi
   /// build() đều ném `Error.notFound` dù URL rtmp:// hoàn toàn hợp lệ.
+  /**
+   Mức tiết giảm nhiệt của máy.
+
+   🔴 Vì sao phải là native: không package Expo nào đọc được `thermalState`. Hai
+   ngày thực địa 08–09/08/2026 ghi 5.598 mẫu `deviceMetrics` mà `thermal` RỖNG
+   TRẮNG, nên lúc nghi máy quá nhiệt thì không có số liệu nào để đối chiếu.
+
+   🔴 Quy đổi sang THANG CỦA ANDROID (`PowerManager.THERMAL_STATUS_*`), không
+   dùng raw value 0–3 của iOS. Dashboard báo "máy quá nóng" từ mức ≥ 3, mà iOS
+   chỉ có 4 bậc trong khi Android có 7 — trả thẳng raw thì `.critical` của iOS
+   thành 3 còn `.serious` thành 2, và một máy iPhone sắp tắt vì nóng lại hiện
+   nhẹ hơn thực tế. Ánh xạ: nominal→0, fair→1, serious→3, critical→4.
+
+   `batteryTempC` KHÔNG có trên iOS — không API công khai nào cho nhiệt độ pin.
+   Bỏ trường thay vì bịa số; bên nhận đã coi nó optional.
+   */
+  private static func deviceHealth() -> [String: Any] {
+    let thermal: Int
+    switch ProcessInfo.processInfo.thermalState {
+    case .nominal: thermal = 0
+    case .fair: thermal = 1
+    case .serious: thermal = 3
+    case .critical: thermal = 4
+    @unknown default: thermal = 0
+    }
+    return ["thermal": thermal]
+  }
+
   private static func registerSessionFactories() async {
     guard !sessionFactoriesRegistered else { return }
     sessionFactoriesRegistered = true
@@ -198,17 +443,86 @@ public final class PickleballRtmpNativeModule: Module {
       guard !publishing else { return }
       try await session.connect(.ingest)
       publishing = true
+      startPublishWatchdog(session)
       emitStatus(["status": "publishing"])
     } else {
       guard publishing else { return }
+      stopPublishWatchdog()
       try await session.close()
       publishing = false
       emitStatus(["status": "connected"])
     }
   }
 
+  /// Canh socket mỗi 2s trong lúc publish. `isConnected` về false (server cắt,
+  /// mạng rớt) → dọn session + báo "disconnected" cho JS. Engine phía JS nhận
+  /// event này để chạy vòng quay số lại — native KHÔNG tự reconnect, chính sách
+  /// retry nằm một chỗ ở engine cho cả hai nền tảng.
+  /// Byte đứng yên bao lâu (khi đang publish) thì coi là luồng đã chết dù
+  /// isConnected còn true. 1080p30 đẩy ~700KB/s — 30 giây im là chắc chắn bệnh.
+  private static let mediaStallTimeout: TimeInterval = 30
+
+  private func startPublishWatchdog(_ session: any Session) {
+    stopPublishWatchdog()
+    // Mốc mới cho lượt publish này — không so với tàn dư của lượt trước.
+    bytesOutChangedAt = Date()
+    monitorEventAt = Date()
+    fpsZeroSince = nil
+    publishWatchdog = Task { [weak self] in
+      while !Task.isCancelled {
+        try? await Task.sleep(nanoseconds: 2_000_000_000)
+        guard let self, !Task.isCancelled else { return }
+        guard self.publishing, self.session === session else { return }
+        if await !session.isConnected {
+          self.stopPublishWatchdog()
+          await self.closeSession(reason: "connection_lost")
+          return
+        }
+        // Ca treo "TCP sống, không frame": isConnected true nhưng tổng byte
+        // rời máy đứng yên. CHỈ xét khi đã từng thấy byte thật (>0) — thiếu
+        // guard này thì Android/khoảnh khắc trước byte đầu tiên bị cắt oan.
+        // Tự đóng như một cú rớt mạng thật để engine JS chạy vòng quay số vô
+        // hạn sẵn có — chính sách retry vẫn nằm một chỗ ở engine.
+        if self.bytesOutSeen > 0,
+          Date().timeIntervalSince(self.bytesOutChangedAt) >= Self.mediaStallTimeout {
+          self.stopPublishWatchdog()
+          await self.closeSession(reason: "media_stalled")
+          return
+        }
+        // Encoder VIDEO chết nhưng audio còn chảy (chữ ký đo 26/08): byte vẫn
+        // nhích nên luật trên mù — fps = 0 kéo dài mới tố được. 25s ≈ 12 nhịp
+        // đo liên tiếp không một khung hình nào.
+        if let zeroSince = self.fpsZeroSince,
+          Date().timeIntervalSince(zeroSince) >= 25 {
+          self.stopPublishWatchdog()
+          await self.closeSession(reason: "media_stalled")
+          return
+        }
+        // Actor socket treo cứng: event NetworkMonitor tắt hẳn — hai luật trên
+        // không còn được nuôi số liệu, phải tự ngắt theo sự im lặng.
+        if self.monitorEventAt != Date.distantPast,
+          Date().timeIntervalSince(self.monitorEventAt) >= Self.mediaStallTimeout {
+          self.stopPublishWatchdog()
+          await self.closeSession(reason: "media_stalled")
+          return
+        }
+      }
+    }
+  }
+
+  private func stopPublishWatchdog() {
+    publishWatchdog?.cancel()
+    publishWatchdog = nil
+  }
+
   private func closeSession(reason: String) async {
+    stopPublishWatchdog()
     guard let session else { return }
+    // Gỡ stream khỏi mixer, không chỉ đóng socket. connect() đã addOutput(stream)
+    // nên bỏ qua bước này là để lại một output chết vẫn nhận khung hình — và
+    // teardown() cũng không dọn hộ, nó chỉ gỡ snapshotOutput.
+    let stream = await session.stream
+    await mixer?.removeOutput(stream)
     try? await session.close()
     self.session = nil
     publishing = false
@@ -219,6 +533,7 @@ public final class PickleballRtmpNativeModule: Module {
     stopObservingOrientation()
     await closeSession(reason: "dispose")
     if let mixer {
+      await mixer.removeOutput(snapshotOutput)
       await mixer.stopRunning()
       try? await mixer.attachAudio(nil)
       try? await mixer.attachVideo(nil, track: 0)
@@ -237,6 +552,23 @@ public final class PickleballRtmpNativeModule: Module {
     var settings = await stream.videoSettings
     settings.bitRate = bitsPerSecond
     settings.videoSize = videoSize
+    // Mặc định của HaishinKit là H264 Baseline 3.1 — level đó chỉ hợp lệ tới
+    // 1280x720. Yêu cầu 1920x1080 ở Baseline 3.1 là cấu hình ngoài chuẩn:
+    // VideoToolbox có thể không dựng nổi compression session, encoder câm lặng
+    // và RTMP chỉ còn track audio (người xem thấy màn đen nhưng vẫn nghe tiếng,
+    // còn preview trên máy vẫn bình thường vì nó vẽ từ mixer, trước encoder).
+    // AutoLevel để VideoToolbox tự chọn level khớp khung hình.
+    settings.profileLevel = kVTProfileLevel_H264_High_AutoLevel as String
+    // Tắt B-frame — BẮT BUỘC, và chính dòng profileLevel ngay trên là lý do phải
+    // có nó: HaishinKit mặc định `allowFrameReordering = !isBaseline`
+    // (VideoCodecSettings.swift), nên khoảnh khắc rời Baseline là encoder bật
+    // đảo thứ tự khung hình. RTP/WebRTC không chở được B-frame, MediaMTX từ chối
+    // ngay ("WebRTC doesn't support H264 streams with B-frames") nên "Siêu nhanh"
+    // đứng hình rồi rơi về HLS chậm 10s — đo tại nguồn RTMP thấy pts < dts
+    // (404.304 < 404.339). Android không dính vì MediaCodec không tự bật B-frame.
+    // Đổi lại là tốn thêm ~5-10% bitrate cho cùng chất lượng: rẻ, và còn bớt được
+    // độ trễ mã hoá vì encoder hết phải giữ bộ đệm đảo khung.
+    settings.allowFrameReordering = false
     // Keyframe 2 giây: khớp ranh giới segment HLS phía server, nếu không segment
     // sẽ không cắt được đúng chỗ và người xem bị giật.
     settings.maxKeyFrameIntervalDuration = 2
@@ -316,18 +648,698 @@ public final class PickleballRtmpNativeModule: Module {
     try await mixer.attachVideo(device, track: 0) { unit in
       unit.isVideoMirrored = mirrored
     }
+    currentVideoDevice = device
+    await reapplyCameraControls()
   }
 
   private func switchCamera() async throws {
     guard let mixer else { return }
     let next: AVCaptureDevice.Position = cameraPosition == .back ? .front : .back
-    try await mixer.attachVideo(
-      AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: next),
-      track: 0
-    ) { unit in
+    let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: next)
+    try await mixer.attachVideo(device, track: 0) { unit in
       unit.isVideoMirrored = next == .front
     }
     cameraPosition = next
+    currentVideoDevice = device
+    await reapplyCameraControls()
+  }
+
+  // MARK: - Camera controls
+
+  /// Bounds cho UI (sheet điều khiển ẩn control có supported:false).
+  /// fps mà UI được phép chào. Không hỏi phần cứng ra danh sách tự do: encoder
+  /// và chính sách bitrate chỉ được kiểm với ba mức này.
+  private static let offeredFrameRates = [24, 30, 60]
+
+  /// Lọc `offeredFrameRates` theo đúng tiêu chí mà HaishinKit dùng lúc chạy:
+  /// `VideoDeviceUnit.setFrameRate` chỉ đổi được sang format CÙNG kích thước với
+  /// activeFormat. Không có format nào khớp thì nó im lặng bỏ qua — UI mà chào
+  /// 60fps trong trường hợp đó sẽ là nút chết.
+  private func supportedFrameRates(for device: AVCaptureDevice) -> [Int] {
+    let dims = device.activeFormat.formatDescription.dimensions
+    return Self.offeredFrameRates.filter { fps in
+      device.formats.contains { format in
+        let d = format.formatDescription.dimensions
+        guard d.width == dims.width, d.height == dims.height else { return false }
+        return format.videoSupportedFrameRateRanges.contains {
+          $0.minFrameRate <= Double(fps) && Double(fps) <= $0.maxFrameRate
+        }
+      }
+    }
+  }
+
+  private func cameraCapabilities() -> [String: Any] {
+    guard let device = currentVideoDevice else {
+      return [
+        "zoom": ["min": 1.0, "max": 1.0, "supported": false],
+        "exposureBias": ["min": 0.0, "max": 0.0, "step": 0.1, "supported": false],
+        "torch": ["supported": false],
+        "focusLock": ["supported": false],
+        "exposureLock": ["supported": false],
+        // Camera chưa mở: chào mức an toàn nhất thay vì danh sách rỗng, nếu
+        // không sheet sẽ không có fps nào để chọn.
+        "supportedFrameRates": [30],
+      ]
+    }
+    let minZoom = Double(device.minAvailableVideoZoomFactor)
+    let maxZoom = Double(min(device.activeFormat.videoMaxZoomFactor, Self.maxZoomCap))
+    return [
+      "supportedFrameRates": supportedFrameRates(for: device),
+      "zoom": ["min": minZoom, "max": maxZoom, "supported": maxZoom > minZoom],
+      "exposureBias": [
+        "min": Double(device.minExposureTargetBias),
+        "max": Double(device.maxExposureTargetBias),
+        // AVFoundation nhận bias liên tục, không có step phần cứng — 0.1 cho slider.
+        "step": 0.1,
+        "supported": device.maxExposureTargetBias > device.minExposureTargetBias,
+      ],
+      "torch": ["supported": device.hasTorch],
+      "focusLock": ["supported": device.isFocusModeSupported(.locked)],
+      "exposureLock": ["supported": device.isExposureModeSupported(.locked)],
+    ]
+  }
+
+  private func withDeviceLock(_ body: (AVCaptureDevice) -> Void) throws {
+    guard let device = currentVideoDevice else {
+      throw RtmpException("chưa có camera — gọi prepare() trước")
+    }
+    do {
+      try device.lockForConfiguration()
+    } catch {
+      throw RtmpException("không khoá được cấu hình camera: \(error)")
+    }
+    defer { device.unlockForConfiguration() }
+    body(device)
+  }
+
+  private func applyZoom(_ factor: Double) throws {
+    try withDeviceLock { device in
+      let upper = min(device.activeFormat.videoMaxZoomFactor, Self.maxZoomCap)
+      device.videoZoomFactor = max(
+        device.minAvailableVideoZoomFactor, min(CGFloat(factor), upper)
+      )
+    }
+  }
+
+  private func applyExposureBias(_ ev: Double) throws {
+    try withDeviceLock { device in
+      let clamped = max(
+        device.minExposureTargetBias, min(Float(ev), device.maxExposureTargetBias)
+      )
+      device.setExposureTargetBias(clamped, completionHandler: nil)
+    }
+  }
+
+  private func applyFocusLocked(_ locked: Bool) throws {
+    try withDeviceLock { device in
+      if locked {
+        guard device.isFocusModeSupported(.locked) else { return }
+        device.focusMode = .locked
+      } else if device.isFocusModeSupported(.continuousAutoFocus) {
+        device.focusMode = .continuousAutoFocus
+      } else if device.isFocusModeSupported(.autoFocus) {
+        device.focusMode = .autoFocus
+      }
+    }
+  }
+
+  private func applyExposureLocked(_ locked: Bool) throws {
+    try withDeviceLock { device in
+      if locked {
+        guard device.isExposureModeSupported(.locked) else { return }
+        device.exposureMode = .locked
+      } else if device.isExposureModeSupported(.continuousAutoExposure) {
+        device.exposureMode = .continuousAutoExposure
+      } else if device.isExposureModeSupported(.autoExpose) {
+        device.exposureMode = .autoExpose
+      }
+    }
+  }
+
+  // MARK: - Overlay
+
+  /// Trả BÁO CÁO thay vì im lặng — sự cố 26/08: JS áp thành công, native nhận
+  /// không ném, hình vẫn trắng, và không ai có một dòng dữ kiện nào. JS log
+  /// nguyên object này ra console.
+  @discardableResult
+  private func setOverlayLogo(_ options: OverlayLogoOptions?) async -> [String: Any] {
+    overlayLogoSpec = options
+    return await applyOverlayLogo()
+  }
+
+  /**
+   Áp trạng thái overlay hiện tại lên mixer.
+
+   Hai chiều KHÔNG đối xứng, cố ý:
+   · bật  — dựng xong `screen` RỒI mới chuyển `.offscreen`, nếu không có vài
+     khung hình vẽ bằng screen chưa kịp cấu hình (nền đen, chưa có camera);
+   · tắt  — trả `.passthrough` TRƯỚC rồi mới gỡ child, để không có khung nào
+     rơi vào khoảng screen đã mất logo mà mixer vẫn còn đang render offscreen.
+
+   Ảnh hỏng/không đọc được cũng đi nhánh tắt: thà không có logo còn hơn chặn sóng.
+   */
+  @discardableResult
+  private func applyOverlayLogo() async -> [String: Any] {
+    guard let mixer else { return ["applied": false, "why": "no_mixer"] }
+    let spec = overlayLogoSpec
+    let image = spec.flatMap {
+      Self.makeLogoImage(
+        path: $0.filePath,
+        opacity: $0.opacity,
+        targetSize: CGSize(width: $0.width, height: $0.height)
+      )
+    }
+    guard let spec, let image else {
+      // Vế tĩnh tắt nhưng còn lớp ĐỘNG thì mixer phải giữ offscreen.
+      let fallback: VideoMixerSettings.Mode =
+        overlayAnimatedSpecs.isEmpty && overlayTextSpecs.isEmpty ? .passthrough : .offscreen
+      await mixer.setVideoMixerSettings(.init(mode: fallback, mainTrack: 0))
+      await applyOverlayOnScreen(mixer, image: nil, rect: .zero, frame: videoSize)
+      // spec có mà image nil = DECODE HỎNG — trước đây nhánh này lặng lẽ gỡ
+      // overlay và không ai biết vì sao hình trắng.
+      return [
+        "applied": false,
+        "why": spec == nil ? "no_spec" : "decode_failed",
+        "mode": "passthrough",
+      ]
+    }
+    let rect = CGRect(x: spec.x, y: spec.y, width: spec.width, height: spec.height)
+    let attached = await applyOverlayOnScreen(mixer, image: image, rect: rect, frame: videoSize)
+    guard attached else {
+      let fallback: VideoMixerSettings.Mode =
+        overlayAnimatedSpecs.isEmpty && overlayTextSpecs.isEmpty ? .passthrough : .offscreen
+      await mixer.setVideoMixerSettings(.init(mode: fallback, mainTrack: 0))
+      return ["applied": false, "why": "add_child_failed"]
+    }
+    await mixer.setVideoMixerSettings(.init(mode: .offscreen, mainTrack: 0))
+    // Đọc NGƯỢC từ mixer sau khi đặt — "đã yêu cầu offscreen" và "mixer đang
+    // offscreen" là hai mệnh đề khác nhau, và khác biệt đó chính là thứ cần soi.
+    let modeNow = await mixer.videoMixerSettings.mode
+    return [
+      "applied": true,
+      "mode": modeNow == .offscreen ? "offscreen" : "khac",
+      "imageW": image.width,
+      "imageH": image.height,
+      "rect": "\(Int(rect.origin.x)),\(Int(rect.origin.y)),\(Int(rect.width))x\(Int(rect.height))",
+      "mixerRunning": await mixer.isRunning,
+    ]
+  }
+
+  /**
+   Kẹp ô vẽ NẰM TRỌN trong khung hình — điều kiện để lớp được vẽ, không phải
+   chuyện canh đẹp.
+
+   `ImageScreenObject.makeImage` (Pods/HaishinKit/…/Screen/ScreenObject.swift)
+   so `bounds` với `renderer.bounds`; lệch dù 1 pixel là rơi vào nhánh "quá
+   khổ", mà nhánh đó cắt ảnh tại toạ độ TUYỆT ĐỐI trên màn (`x =
+   bounds.origin.x`) trong khi `cgImage` chỉ rộng đúng bằng ô. Cắt tại x=1280
+   trên ảnh rộng 640 ⇒ vùng cắt nằm ngoài hoàn toàn ⇒ `cropping()` trả nil ⇒
+   LỚP KHÔNG VẼ GÌ — im lặng, `applied: true` vẫn xanh.
+
+   Vế logo/động đã được JS kẹp sẵn; ở đây là lưới đỡ. Vế CHỮ thì đây là chỗ DUY
+   NHẤT kẹp được: bề rộng ảnh chữ do `makeTextImage` quyết định lúc chạy nên JS
+   không thể biết trước — trước bản vá này chỉ mép trái được kẹp (`max(0,
+   left)`), còn mép phải và mép dưới tràn tự do, tức lớp TỈ SỐ có thể biến mất
+   không dấu vết.
+
+   Dời trước, co sau: tràn kiểu làm tròn thì dời vài pixel không ai thấy, còn
+   co lại là méo chữ. Chỉ co khi lớp thật sự to hơn cả khung.
+   */
+  private static func clampedRect(_ rect: CGRect, in frame: CGSize) -> CGRect {
+    guard frame.width > 0, frame.height > 0 else { return rect }
+    let w = min(max(1, rect.width), frame.width)
+    let h = min(max(1, rect.height), frame.height)
+    let x = min(max(0, rect.origin.x), frame.width - w)
+    let y = min(max(0, rect.origin.y), frame.height - h)
+    return CGRect(x: x, y: y, width: w, height: h)
+  }
+
+  /// Mọi thao tác trên `Screen`/`ScreenObject` đều isolate ở `ScreenActor`.
+  /// Trả `false` khi không gắn được object vào screen — caller PHẢI báo đỏ.
+  @discardableResult
+  @ScreenActor
+  private func applyOverlayOnScreen(
+    _ mixer: MediaMixer,
+    image: CGImage?,
+    rect: CGRect,
+    frame: CGSize
+  ) -> Bool {
+    let screen = mixer.screen
+    guard let image else {
+      if let object = overlayLogoObject {
+        // Gỡ khỏi parent THẬT của object (có thể là screen của phiên trước) —
+        // screen.removeChild trên screen hiện tại là no-op nếu parent khác.
+        object.parent?.removeChild(object)
+        overlayLogoObject = nil
+      }
+      return true
+    }
+    // BẮT BUỘC: Screen.size mặc định 1280×720. Quên dòng này là mọi phiên 1080p
+    // bị compose xuống 720 rồi encoder phóng ngược lên — mờ mà không ai báo lỗi.
+    screen.size = frame
+    let rect = Self.clampedRect(rect, in: frame)
+    // KHÔNG chỉnh được `videoGravity` của track camera: HaishinKit để
+    // `Screen.videoTrackScreenObject` ở mức internal và không mở API nào duyệt
+    // children. May là cấu hình này không cần: module chưa bao giờ gọi
+    // `setSessionPreset` nên session chạy `.high` (16:9), còn `videoSize` chỉ
+    // nhận 1280x720 hoặc 1920x1080. Nguồn và screen cùng tỉ lệ thì mặc định
+    // `.resizeAspect` cho ra đúng khung như `.resizeAspectFill` — không viền
+    // đen. Ngày nào ép nguồn sang 4:3 thì phải fork HaishinKit mới sửa được.
+    let object = overlayLogoObject ?? ImageScreenObject()
+    object.cgImage = image
+    // size != .zero nên `makeBounds` lấy thẳng size + layoutMargin làm toạ độ —
+    // khớp đúng ô mà `logoRect()` đã tính, không qua một phép canh lề nào nữa.
+    object.size = rect.size
+    object.horizontalAlignment = .left
+    object.verticalAlignment = .top
+    object.layoutMargin = .init(top: rect.origin.y, left: rect.origin.x, bottom: 0, right: 0)
+    // Mixer + Screen sinh MỚI mỗi phiên, còn object này sống xuyên phiên. Bản cũ
+    // chỉ addChild lần đầu đời app → từ phiên thứ hai object vẫn dính screen ĐÃ
+    // CHẾT, invalidateLayout vào hư không, report vẫn xanh — sóng thì trắng
+    // (bắt quả tang bằng khung hình S1 15:28 26/08). Luôn detach khỏi parent
+    // thật rồi gắn lại vào screen hiện tại; addChild từ chối thì trả false.
+    object.parent?.removeChild(object)
+    do {
+      try screen.addChild(object)
+    } catch {
+      overlayLogoObject = object
+      return false
+    }
+    overlayLogoObject = object
+    return true
+  }
+
+  // MARK: - Overlay động (gif/video)
+
+  @discardableResult
+  private func setOverlayAnimated(_ items: [OverlayAnimatedOptions]?) async -> [String: Any] {
+    overlayAnimatedSpecs = items ?? []
+    return await applyOverlayAnimated()
+  }
+
+  /**
+   Áp các lớp ĐỘNG lên mixer. Tách khỏi vế tĩnh vì vòng đời khác hẳn (mỗi lớp
+   một object + một Task animator theo id), nhưng chung hai kỷ luật:
+   · bất đối xứng bật/tắt của vế tĩnh (passthrough TRƯỚC khi gỡ, dựng xong RỒI
+     mới offscreen);
+   · detach-khỏi-parent-thật rồi gắn lại (bài học 9d5414e — screen chết theo
+     phiên, object sống xuyên phiên).
+   Một lớp hỏng chỉ rơi RIÊNG nó (animation là trang trí) — báo cáo mang từng
+   item để JS log ra console.
+   */
+  @discardableResult
+  private func applyOverlayAnimated() async -> [String: Any] {
+    guard let mixer else { return ["applied": false, "why": "no_mixer"] }
+    let specs = overlayAnimatedSpecs
+    for (_, task) in overlayAnimatedTasks { task.cancel() }
+    overlayAnimatedTasks = [:]
+    if specs.isEmpty && overlayLogoSpec == nil && overlayTextSpecs.isEmpty {
+      await mixer.setVideoMixerSettings(.init(mode: .passthrough, mainTrack: 0))
+    }
+    await detachRemovedAnimated(keep: Set(specs.map { $0.id }))
+    guard !specs.isEmpty else { return ["applied": true, "count": 0] }
+    var details: [[String: Any]] = []
+    var ok = 0
+    for spec in specs {
+      let d = await attachAnimated(mixer, spec: spec)
+      if d["applied"] as? Bool == true { ok += 1 }
+      details.append(d)
+    }
+    await mixer.setVideoMixerSettings(.init(mode: .offscreen, mainTrack: 0))
+    return ["applied": ok == specs.count, "count": ok, "total": specs.count, "items": details]
+  }
+
+  private func attachAnimated(
+    _ mixer: MediaMixer, spec: OverlayAnimatedOptions
+  ) async -> [String: Any] {
+    let rect = CGRect(x: spec.x, y: spec.y, width: spec.width, height: spec.height)
+    guard rect.width >= 1, rect.height >= 1 else {
+      return ["id": spec.id, "applied": false, "why": "bad_rect"]
+    }
+    switch spec.kind {
+    case "gif":
+      guard
+        let gif = GifSource(path: spec.filePath, targetSize: rect.size, opacity: spec.opacity)
+      else {
+        return ["id": spec.id, "applied": false, "why": "gif_decode_failed"]
+      }
+      guard
+        await attachAnimatedImage(
+          mixer, id: spec.id, rect: rect, frame: videoSize, firstFrame: gif.frame(0))
+      else {
+        return ["id": spec.id, "applied": false, "why": "add_child_failed"]
+      }
+      startGifTask(id: spec.id, gif: gif)
+      return ["id": spec.id, "applied": true, "kind": "gif", "frames": gif.count]
+    case "video":
+      guard
+        await attachAnimatedVideo(
+          mixer, id: spec.id, rect: rect, frame: videoSize, filePath: spec.filePath)
+      else {
+        return ["id": spec.id, "applied": false, "why": "video_attach_failed"]
+      }
+      startVideoLoopTask(id: spec.id)
+      return ["id": spec.id, "applied": true, "kind": "video"]
+    default:
+      return ["id": spec.id, "applied": false, "why": "unknown_kind"]
+    }
+  }
+
+  @ScreenActor
+  private func detachRemovedAnimated(keep: Set<String>) {
+    for (id, object) in overlayAnimatedObjects where !keep.contains(id) {
+      (object as? AssetScreenObject)?.cancelReading()
+      object.parent?.removeChild(object)
+      overlayAnimatedObjects[id] = nil
+    }
+  }
+
+  @ScreenActor
+  private func attachAnimatedImage(
+    _ mixer: MediaMixer, id: String, rect: CGRect, frame: CGSize, firstFrame: CGImage?
+  ) -> Bool {
+    let screen = mixer.screen
+    screen.size = frame
+    let rect = Self.clampedRect(rect, in: frame)
+    let object = (overlayAnimatedObjects[id] as? ImageScreenObject) ?? ImageScreenObject()
+    object.cgImage = firstFrame
+    object.size = rect.size
+    object.horizontalAlignment = .left
+    object.verticalAlignment = .top
+    object.layoutMargin = .init(top: rect.origin.y, left: rect.origin.x, bottom: 0, right: 0)
+    object.parent?.removeChild(object)
+    do { try screen.addChild(object) } catch { return false }
+    overlayAnimatedObjects[id] = object
+    return true
+  }
+
+  @ScreenActor
+  private func attachAnimatedVideo(
+    _ mixer: MediaMixer, id: String, rect: CGRect, frame: CGSize, filePath: String
+  ) -> Bool {
+    let screen = mixer.screen
+    screen.size = frame
+    let rect = Self.clampedRect(rect, in: frame)
+    let object = (overlayAnimatedObjects[id] as? AssetScreenObject) ?? AssetScreenObject()
+    object.videoGravity = .resizeAspect
+    object.size = rect.size
+    object.horizontalAlignment = .left
+    object.verticalAlignment = .top
+    object.layoutMargin = .init(top: rect.origin.y, left: rect.origin.x, bottom: 0, right: 0)
+    object.parent?.removeChild(object)
+    do { try screen.addChild(object) } catch { return false }
+    do {
+      try object.startReading(AVURLAsset(url: URL(fileURLWithPath: filePath)))
+    } catch {
+      object.parent?.removeChild(object)
+      overlayAnimatedObjects[id] = nil
+      return false
+    }
+    overlayAnimatedObjects[id] = object
+    return true
+  }
+
+  /// Đổi khung gif theo delay gốc. Decode-khi-đến-lượt trên executor của Task
+  /// (KHÔNG chặn ScreenActor), rồi chỉ ĐỔI NGUỒN ảnh của đúng một object —
+  /// renderer tự re-layout riêng lớp đó (chi phí ∝ diện tích lớp, đo 26/08).
+  private func startGifTask(id: String, gif: GifSource) {
+    overlayAnimatedTasks[id]?.cancel()
+    guard gif.count > 1 else { return }
+    overlayAnimatedTasks[id] = Task { [weak self] in
+      var index = 0
+      while !Task.isCancelled {
+        let delay = gif.delays[index]
+        try? await Task.sleep(nanoseconds: UInt64(max(0.02, delay) * 1_000_000_000))
+        if Task.isCancelled { return }
+        index = (index + 1) % gif.count
+        guard let image = gif.frame(index) else { continue }
+        await self?.setAnimatedFrame(id: id, image: image)
+      }
+    }
+  }
+
+  @ScreenActor
+  private func setAnimatedFrame(id: String, image: CGImage) {
+    (overlayAnimatedObjects[id] as? ImageScreenObject)?.cgImage = image
+  }
+
+  /// AssetScreenObject không tự lặp — hết file là ngừng đọc. Canh 700ms một
+  /// lần, hết thì mở lại từ đầu (decode cứng, rẻ).
+  private func startVideoLoopTask(id: String) {
+    overlayAnimatedTasks[id]?.cancel()
+    overlayAnimatedTasks[id] = Task { [weak self] in
+      while !Task.isCancelled {
+        try? await Task.sleep(nanoseconds: 700_000_000)
+        if Task.isCancelled { return }
+        await self?.restartVideoIfEnded(id: id)
+      }
+    }
+  }
+
+  @ScreenActor
+  private func restartVideoIfEnded(id: String) {
+    guard let object = overlayAnimatedObjects[id] as? AssetScreenObject, !object.isReading
+    else { return }
+    guard let spec = overlayAnimatedSpecs.first(where: { $0.id == id }) else { return }
+    try? object.startReading(AVURLAsset(url: URL(fileURLWithPath: spec.filePath)))
+  }
+
+  /**
+   Nguồn gif decode-khi-đến-lượt: giữ CGImageSource (không cache) + mảng delay,
+   mỗi tick mới decode + chuẩn hoá ĐÚNG MỘT khung về cỡ ô (cùng lý do 4ef575c).
+   RAM = O(1 khung) bất kể gif dài bao nhiêu — bài học 26/08: gif thật ngoài
+   sản xuất 268 khung / 27s, pre-decode cần 234MB và bị trần 48MB chặn chết.
+   CPU: ~1 khung decode+vẽ mỗi tick ở nhịp gif (≤25fps) — không đáng kể so với
+   camera track. Trần 2000 khung chỉ để chặn file rác.
+   */
+  private final class GifSource {
+    let delays: [Double]
+    private let source: CGImageSource
+    private let targetSize: CGSize
+    private let opacity: Double
+    private let renderer: UIGraphicsImageRenderer
+
+    var count: Int { delays.count }
+
+    init?(path: String, targetSize: CGSize, opacity: Double) {
+      guard targetSize.width >= 1, targetSize.height >= 1,
+        let src = CGImageSourceCreateWithURL(
+          URL(fileURLWithPath: path) as CFURL,
+          [kCGImageSourceShouldCache: false] as CFDictionary)
+      else { return nil }
+      let count = CGImageSourceGetCount(src)
+      guard count >= 1, count <= 2000 else { return nil }
+      // Khung đầu phải decode được thì mới nhận — file hỏng lộ ngay ở đây
+      // thay vì thành lớp "áp xanh mà không vẽ" giữa chừng.
+      guard CGImageSourceCreateImageAtIndex(src, 0, nil) != nil else { return nil }
+      self.source = src
+      self.targetSize = targetSize
+      self.opacity = opacity
+      let format = UIGraphicsImageRendererFormat.default()
+      format.scale = 1
+      format.opaque = false
+      self.renderer = UIGraphicsImageRenderer(size: targetSize, format: format)
+      self.delays = (0..<count).map {
+        PickleballRtmpNativeModule.gifFrameDelay(source: src, index: $0)
+      }
+    }
+
+    func frame(_ index: Int) -> CGImage? {
+      guard index >= 0, index < delays.count,
+        let cg = CGImageSourceCreateImageAtIndex(
+          source, index, [kCGImageSourceShouldCache: false] as CFDictionary)
+      else { return nil }
+      let size = targetSize
+      let alpha = CGFloat(opacity)
+      return renderer.image { _ in
+        UIImage(cgImage: cg).draw(
+          in: CGRect(origin: .zero, size: size), blendMode: .normal, alpha: alpha)
+      }.cgImage
+    }
+  }
+
+  private static func gifFrameDelay(source: CGImageSource, index: Int) -> Double {
+    guard
+      let props = CGImageSourceCopyPropertiesAtIndex(source, index, nil) as? [CFString: Any],
+      let gif = props[kCGImagePropertyGIFDictionary] as? [CFString: Any]
+    else { return 0.1 }
+    let delay =
+      (gif[kCGImagePropertyGIFUnclampedDelayTime] as? Double)
+      ?? (gif[kCGImagePropertyGIFDelayTime] as? Double) ?? 0.1
+    // Gif khai delay 0 nghĩa là "nhanh nhất có thể" — trình duyệt quy về 100ms.
+    return delay < 0.02 ? 0.1 : delay
+  }
+
+  /// Đọc ảnh từ đĩa, nướng độ đậm vào pixel VÀ chuẩn hoá về ĐÚNG kích thước ô
+  /// đích. Hai lý do, cả hai đo được 26/08:
+  /// · A/B trên máy thật: ImageScreenObject với ảnh nguồn 1920×1080 KHÔNG được
+  ///   CPU renderer vẽ ra khung (mọi cỡ rect đều trắng), trong khi nguồn ~384px
+  ///   vẽ bình thường — nguồn == đích là cấu hình duy nhất đã chứng minh chạy.
+  /// · Blend mỗi khung hình tỉ lệ diện tích ảnh — đưa ảnh về đúng cỡ ô là trả
+  ///   đúng giá, không bắt CPU gánh 1920×1080 cho một logo góc màn hình.
+  /// (`ScreenObject` không có thuộc tính opacity nên độ đậm phải vào pixel ở đây.)
+  private static func makeLogoImage(
+    path: String, opacity: Double, targetSize: CGSize
+  ) -> CGImage? {
+    guard let ui = UIImage(contentsOfFile: path) else { return nil }
+    guard targetSize.width >= 1, targetSize.height >= 1 else { return nil }
+    let format = UIGraphicsImageRendererFormat.default()
+    // scale = 1: kích thước tính bằng PIXEL. Để mặc định (scale màn hình) thì ảnh
+    // phình 2-3× so với ô đã tính và logo tràn khỏi góc.
+    format.scale = 1
+    format.opaque = false
+    let renderer = UIGraphicsImageRenderer(size: targetSize, format: format)
+    return renderer.image { _ in
+      ui.draw(in: CGRect(origin: .zero, size: targetSize), blendMode: .normal, alpha: CGFloat(opacity))
+    }.cgImage
+  }
+
+  /// Áp lại state controls sau khi attachVideo — best-effort: lens mới không hỗ
+  /// trợ control nào thì bỏ qua control đó, không chặn việc đổi lens.
+  // MARK: - Overlay chữ (tỉ số/tên đội — JS đã điền template, native chỉ vẽ)
+
+  @discardableResult
+  private func setOverlayTexts(_ items: [OverlayTextOptions]?) async -> [String: Any] {
+    overlayTextSpecs = items ?? []
+    return await applyOverlayTexts()
+  }
+
+  /**
+   Áp các lớp CHỮ lên mixer. Mỗi lớp một ImageScreenObject tái dùng theo id;
+   mỗi lượt áp vẽ lại ảnh của lớp (2 lần/phút theo pha bóng — rẻ, đo cùng cỡ
+   với một khung gif). Chung kỷ luật với hai vế kia: passthrough chỉ khi MỌI vế
+   trống, detach-khỏi-parent-thật trước khi gắn (bài học 9d5414e).
+   */
+  @discardableResult
+  private func applyOverlayTexts() async -> [String: Any] {
+    guard let mixer else { return ["applied": false, "why": "no_mixer"] }
+    let specs = overlayTextSpecs
+    if specs.isEmpty && overlayLogoSpec == nil && overlayAnimatedSpecs.isEmpty {
+      await mixer.setVideoMixerSettings(.init(mode: .passthrough, mainTrack: 0))
+    }
+    await detachRemovedTexts(keep: Set(specs.map { $0.id }))
+    guard !specs.isEmpty else { return ["applied": true, "count": 0] }
+    var details: [[String: Any]] = []
+    var ok = 0
+    for spec in specs {
+      guard let image = Self.makeTextImage(spec) else {
+        details.append(["id": spec.id, "applied": false, "why": "render_failed"])
+        continue
+      }
+      // Mỏ neo theo align: x của spec là mép trái/tâm/mép phải của ẢNH đã vẽ
+      // (ảnh ôm trọn nền) — cùng quy ước transform bên preview editor.
+      let w = Double(image.width)
+      let left: Double
+      switch spec.align {
+      case "center": left = spec.x - w / 2
+      case "right": left = spec.x - w
+      default: left = spec.x
+      }
+      let rect = CGRect(
+        x: max(0, left), y: spec.y, width: w, height: Double(image.height))
+      let attached = await attachTextImage(
+        mixer, id: spec.id, rect: rect, frame: videoSize, image: image)
+      if attached { ok += 1 }
+      details.append(["id": spec.id, "applied": attached, "w": image.width, "h": image.height])
+    }
+    await mixer.setVideoMixerSettings(.init(mode: .offscreen, mainTrack: 0))
+    return ["applied": ok == specs.count, "count": ok, "total": specs.count, "items": details]
+  }
+
+  @ScreenActor
+  private func detachRemovedTexts(keep: Set<String>) {
+    for (id, object) in overlayTextObjects where !keep.contains(id) {
+      object.parent?.removeChild(object)
+      overlayTextObjects[id] = nil
+    }
+  }
+
+  @ScreenActor
+  private func attachTextImage(
+    _ mixer: MediaMixer, id: String, rect: CGRect, frame: CGSize, image: CGImage
+  ) -> Bool {
+    let screen = mixer.screen
+    screen.size = frame
+    let rect = Self.clampedRect(rect, in: frame)
+    let object = overlayTextObjects[id] ?? ImageScreenObject()
+    object.cgImage = image
+    object.size = rect.size
+    object.horizontalAlignment = .left
+    object.verticalAlignment = .top
+    object.layoutMargin = .init(top: rect.origin.y, left: rect.origin.x, bottom: 0, right: 0)
+    object.parent?.removeChild(object)
+    do { try screen.addChild(object) } catch {
+      overlayTextObjects[id] = object
+      return false
+    }
+    overlayTextObjects[id] = object
+    return true
+  }
+
+  /**
+   Vẽ MỘT lớp chữ thành ảnh: nền bo góc (nếu có) + chữ, opacity CẢ LỚP nướng
+   vào pixel. Hình học nền là bội của fontSize (0.45 / 0.25 / 0.22) — PHẢI khớp
+   OVERLAY_TEXT_BG của @pickleball/shared: preview editor và khung hình thật
+   chung một công thức, đừng sửa lệch một bên.
+   */
+  private static func makeTextImage(_ spec: OverlayTextOptions) -> CGImage? {
+    let fontSize = CGFloat(max(8, spec.fontSizePx))
+    let font = UIFont.systemFont(
+      ofSize: fontSize, weight: spec.weight == "regular" ? .regular : .bold)
+    let color = Self.colorFromHex(spec.color) ?? .white
+    let attributes: [NSAttributedString.Key: Any] = [.font: font, .foregroundColor: color]
+    let textSize = (spec.text as NSString).size(withAttributes: attributes)
+    let hasBg = spec.bgColor != nil
+    let padX = hasBg ? fontSize * 0.45 : 0
+    let padY = hasBg ? fontSize * 0.25 : 0
+    let width = ceil(textSize.width + padX * 2)
+    let height = ceil(textSize.height + padY * 2)
+    guard width >= 1, height >= 1, width <= 4096, height <= 1024 else { return nil }
+    let format = UIGraphicsImageRendererFormat()
+    format.scale = 1
+    format.opaque = false
+    let renderer = UIGraphicsImageRenderer(
+      size: CGSize(width: width, height: height), format: format)
+    let image = renderer.image { ctx in
+      // setAlpha + transparency layer: opacity áp lên CẢ nhóm (nền + chữ) một
+      // lần — không bị cộng dồn alpha ở chỗ chữ đè lên nền.
+      ctx.cgContext.setAlpha(CGFloat(max(0, min(1, spec.opacity))))
+      ctx.cgContext.beginTransparencyLayer(auxiliaryInfo: nil)
+      if let bgHex = spec.bgColor, let bg = Self.colorFromHex(bgHex) {
+        let path = UIBezierPath(
+          roundedRect: CGRect(x: 0, y: 0, width: width, height: height),
+          cornerRadius: fontSize * 0.22)
+        bg.withAlphaComponent(CGFloat(max(0, min(1, spec.bgOpacity ?? 0.5)))).setFill()
+        path.fill()
+      }
+      (spec.text as NSString).draw(at: CGPoint(x: padX, y: padY), withAttributes: attributes)
+      ctx.cgContext.endTransparencyLayer()
+    }
+    return image.cgImage
+  }
+
+  private static func colorFromHex(_ hex: String) -> UIColor? {
+    var s = hex.trimmingCharacters(in: .whitespaces)
+    if s.hasPrefix("#") { s.removeFirst() }
+    guard s.count == 6, let v = UInt32(s, radix: 16) else { return nil }
+    return UIColor(
+      red: CGFloat((v >> 16) & 0xff) / 255,
+      green: CGFloat((v >> 8) & 0xff) / 255,
+      blue: CGFloat(v & 0xff) / 255,
+      alpha: 1)
+  }
+
+  private func reapplyCameraControls() async {
+    if let zoomFactor { try? applyZoom(zoomFactor) }
+    if let exposureBiasValue { try? applyExposureBias(exposureBiasValue) }
+    if focusLocked { try? applyFocusLocked(true) }
+    if exposureLocked { try? applyExposureLocked(true) }
+    if torchEnabled { await mixer?.setTorchEnabled(true) }
+    // Đổi ống kính dựng lại đường video của mixer — áp lại overlay ở đây để cả ba
+    // chỗ attachVideo (prepare/selectCamera/switchCamera) dùng chung một lối.
+    await applyOverlayLogo()
+    await applyOverlayAnimated()
+    await applyOverlayTexts()
   }
 
   private func emitStatus(_ payload: [String: Any]) {
@@ -335,11 +1347,152 @@ public final class PickleballRtmpNativeModule: Module {
   }
 }
 
+// MARK: - Bandwidth
+
+/// Cầu nối NetworkMonitorEvent của HaishinKit → sự kiện onBandwidth cho JS.
+///
+/// `publishInsufficientBWOccured` = hàng đợi gửi phình ra liên tục (mạng không
+/// theo kịp encoder); `status` = nhịp đo bình thường (đủ băng thông). Không tự
+/// chỉnh bitrate ở đây — RtmpRoomAdapter (JS) giữ chính sách chung hai nền tảng.
+internal final class BandwidthReportingStrategy: HKStreamBitRateStrategy {
+  // Tên trường (mamimum...) giữ nguyên chính tả của HaishinKit 2.0.9. Hai giá
+  // trị này không được dùng vì strategy không tự điều chỉnh.
+  let mamimumVideoBitRate: Int = 0
+  let mamimumAudioBitRate: Int = 0
+  /// (đủ băng thông, tổng byte đã rời máy, fps video nhịp này) — byte + fps
+  /// nuôi watchdog media-stall: byte bắt chết-toàn-phần, fps bắt chết-video-
+  /// còn-audio (chữ ký 26/08).
+  private let report: @Sendable (Bool, Int, Int) -> Void
+
+  init(report: @escaping @Sendable (Bool, Int, Int) -> Void) {
+    self.report = report
+  }
+
+  func adjustBitrate(_ event: NetworkMonitorEvent, stream: some HKStream) async {
+    // currentFPS = số khung hình stream nhận trong nhịp đo vừa rồi (RTMPStream
+    // reset mỗi event) — chính là nhịp tim của VIDEO, độc lập với audio.
+    let fps = await Int((stream as? RTMPStream)?.currentFPS ?? 0)
+    switch event {
+    case .publishInsufficientBWOccured(let r):
+      report(false, r.totalBytesOut, fps)
+    case .status(let r):
+      report(true, r.totalBytesOut, fps)
+    default:
+      break
+    }
+  }
+}
+
+// MARK: - Snapshot
+
+/// Nhận khung video đã compose từ MediaMixer (đường giống MTHKView) và giữ lại
+/// pixel buffer mới nhất để snapshot() nén JPEG khi dashboard xin xem trước từ
+/// xa. Không phát, không hiển thị — chỉ giữ frame gần nhất.
+private final class SnapshotOutput: MediaMixerOutput, @unchecked Sendable {
+  // UInt8.max để nhận track video như MTHKView (xem View/MTHKView.swift).
+  var videoTrackId: UInt8? = UInt8.max
+  var audioTrackId: UInt8?
+  private let lock = NSLock()
+  private var latest: CVPixelBuffer?
+  private let ciContext = CIContext()
+
+  nonisolated func mixer(_ mixer: MediaMixer, didOutput sampleBuffer: CMSampleBuffer) {
+    guard let pixelBuffer = sampleBuffer.imageBuffer else { return }
+    lock.lock()
+    latest = pixelBuffer
+    lock.unlock()
+  }
+
+  nonisolated func mixer(_ mixer: MediaMixer, didOutput buffer: AVAudioPCMBuffer, when: AVAudioTime) {}
+
+  func selectTrack(_ id: UInt8?, mediaType: CMFormatDescription.MediaType) async {}
+
+  /// Nén khung mới nhất → JPEG base64 (thu nhỏ về maxWidth). nil khi chưa có frame.
+  func snapshotBase64(maxWidth: CGFloat, quality: CGFloat) -> String? {
+    lock.lock()
+    let pixelBuffer = latest
+    lock.unlock()
+    guard let pixelBuffer else { return nil }
+    let image = CIImage(cvImageBuffer: pixelBuffer)
+    let width = image.extent.width
+    let scale = width > maxWidth ? maxWidth / width : 1
+    let scaled = scale < 1
+      ? image.transformed(by: CGAffineTransform(scaleX: scale, y: scale))
+      : image
+    guard let cgImage = ciContext.createCGImage(scaled, from: scaled.extent) else {
+      return nil
+    }
+    guard let data = UIImage(cgImage: cgImage).jpegData(compressionQuality: quality) else {
+      return nil
+    }
+    return data.base64EncodedString()
+  }
+}
+
 // MARK: - Records
 
 internal struct PrepareOptions: Record {
   @Field var quality: Int = 1080
   @Field var frameRate: Int = 30
+  /**
+   Ống kính mở ngay ở lần prepare này (uniqueID của AVCaptureDevice).
+
+   PHẢI khai báo dù chỉ để đọc: Expo Record vứt IM LẶNG mọi trường JS gửi xuống
+   mà Swift không khai — thiếu dòng này thì `cameraId` người dùng chọn bốc hơi
+   và máy luôn mở camera sau mặc định sau mỗi lần khởi động app.
+   */
+  @Field var cameraId: String?
+  /**
+   Giữ cho khớp API với Android; iOS KHÔNG dùng vì hướng video lấy từ
+   `UIDevice.current.orientation` trong `applyVideoOrientation()`.
+   */
+  @Field var landscape: Bool = true
+}
+
+/**
+ Ô đặt logo, tính bằng PIXEL của khung hình đang encode, gốc trên-trái.
+
+ JS gửi xuống đã qua `logoRect()` (@pickleball/shared) nên ở đây không kiểm biên
+ lại — biên đã được ép ở `clampLogoGeometry` từ lúc BTC lưu cấu hình.
+ */
+internal struct OverlayLogoOptions: Record {
+  /// Đường dẫn file ảnh trên đĩa máy (app tải về theo URL rồi cache).
+  @Field var filePath: String = ""
+  @Field var x: Double = 0
+  @Field var y: Double = 0
+  @Field var width: Double = 0
+  @Field var height: Double = 0
+  @Field var opacity: Double = 1
+}
+
+/// Một lớp overlay ĐỘNG — cùng hệ pixel với OverlayLogoOptions, thêm id để
+/// native tái dùng object/animator, và kind ("gif" | "video") chọn đường decode.
+internal struct OverlayAnimatedOptions: Record {
+  @Field var id: String = ""
+  @Field var kind: String = ""
+  @Field var filePath: String = ""
+  @Field var x: Double = 0
+  @Field var y: Double = 0
+  @Field var width: Double = 0
+  @Field var height: Double = 0
+  @Field var opacity: Double = 1
+}
+
+/// Một lớp CHỮ đã điền sẵn — JS gửi CHUỖI CHỐT + hình học pixel (mỏ neo x theo
+/// align); native chỉ vẽ, không biết template/tỉ số. Nền là field PHẲNG
+/// (bgColor/bgOpacity) — không có bgColor = không nền.
+internal struct OverlayTextOptions: Record {
+  @Field var id: String = ""
+  @Field var text: String = ""
+  @Field var x: Double = 0
+  @Field var y: Double = 0
+  @Field var fontSizePx: Double = 48
+  @Field var align: String = "left"
+  @Field var weight: String = "bold"
+  @Field var color: String = "#ffffff"
+  @Field var opacity: Double = 1
+  @Field var bgColor: String?
+  @Field var bgOpacity: Double?
 }
 
 internal struct ConnectOptions: Record {