import 'dart:typed_data'; /// Minimal, dependency-free abstraction over the neural image codec used by /// [ImageSendPreviewSheet]. /// /// The real implementation lives in `lib/services/image_codec_service.dart` /// (`ImageCodecService implements ImageSendCodec`) and /// `lib/services/image_chunk_transport.dart`. This file deliberately does NOT /// import them, so the preview sheet can be built, analyzed and previewed on /// its own and so the service depends on the UI contract rather than the other /// way round. /// // Packet-count and airtime maths deliberately live in // `lib/utils/lora_airtime.dart`, not here. /// Hard minimum resolution for the codec. Images are centre-cropped to this /// square before encoding; the decoder collapses below it. const int kImageCodecSquareSize = 512; /// Availability of the image codec, as far as the UI is concerned. enum ImageCodecAvailability { /// The feature is switched off in app settings. disabled, /// The codec model is being fetched; the feature is temporarily unusable. downloading, /// The codec is usable right now. ready, /// The codec cannot run on this device/platform at all. unavailable, } /// Rate points the wire format can express. /// /// The shipping build encodes at [standard] (`ft32`) only — see /// [kImageSendRatePoint]. The enum keeps more than one value because the rate /// point is written into the chunk-0 metadata byte by /// `image_chunk_transport.dart`, so the ordinals are part of the wire format and /// must stay stable even for rate points the UI never offers. Removing [high] /// would renumber nothing today but would make a future rate point silently /// reuse ordinal 1 and be decoded as ft16 by older builds. enum ImageCodecRatePoint { /// `ft32` — the only rate point this build sends. Measured 110-209 B /// (mean 156 B) over 26 images, i.e. 1-2 data chunks plus parity. standard, /// `ft16` — larger, higher fidelity. **Not offered in the UI**: the model /// registry ships ft32 weights only. Retained so the ordinal stays reserved /// and so bitstreams produced elsewhere can still be identified on the wire. high, } /// The single rate point the compose UI encodes at. /// /// The quality selector was removed once ft32 became the only shipping model; /// every send goes out at this rate. Named rather than inlined so a future /// second rate point has one place to come back to. const ImageCodecRatePoint kImageSendRatePoint = ImageCodecRatePoint.standard; /// Measured payload statistics for a rate point, in bytes. /// /// These are real measurements over 26 images of rANS bitstreams produced by /// the codec at 512x512, not estimates. They let the sheet show a plausible /// range instantly, before an encode has finished. class ImageCodecRateStats { final int meanBytes; final int minBytes; final int maxBytes; const ImageCodecRateStats({ required this.meanBytes, required this.minBytes, required this.maxBytes, }); static const ImageCodecRateStats standard = ImageCodecRateStats( meanBytes: 156, minBytes: 110, maxBytes: 209, ); /// Retained for [ImageCodecRatePoint.high], which the UI no longer offers. static const ImageCodecRateStats high = ImageCodecRateStats( meanBytes: 288, minBytes: 176, maxBytes: 409, ); static ImageCodecRateStats forRate(ImageCodecRatePoint rate) { switch (rate) { case ImageCodecRatePoint.standard: return standard; case ImageCodecRatePoint.high: return high; } } } /// The encode interface the preview sheet consumes. abstract class ImageSendCodec { /// Current availability. The sheet renders a non-interactive explanation for /// anything other than [ImageCodecAvailability.ready]. ImageCodecAvailability get availability; /// Why [availability] is [ImageCodecAvailability.unavailable], as one /// user-facing sentence, or null when the codec is not permanently /// unavailable. /// /// This is the sentence the compose sheet shows in place of its generic /// "not available on this device" string: `unavailable` is a permanent /// property of the build (no native runtime, no entropy path, backend failed /// to load) and the only useful thing the UI can do is say WHICH one it hit. /// Implementations must not return an empty string; return null instead. String? get unavailableReason; /// Encode [imageBytes] (any common still format) at [rate], returning the /// compressed bitstream that will be chunked onto the air. /// /// Implementations are expected to centre-crop to /// [kImageCodecSquareSize] square first. Future encode(Uint8List imageBytes, ImageCodecRatePoint rate); /// Decodes [payload] to PNG exactly as a recipient would, or null when this /// device cannot decode. Future decodePreview(Uint8List payload); } /// A deterministic stand-in used for widget previews and tests. /// /// It produces a buffer of the measured mean size for the requested rate point /// so the sheet can be exercised end-to-end without the real codec. class FakeImageSendCodec implements ImageSendCodec { @override final ImageCodecAvailability availability; /// Mirrors `ImageCodecService.unavailableReason`; null unless a test wants to /// exercise the "why can't I send?" path. @override final String? unavailableReason; final Duration latency; const FakeImageSendCodec({ this.availability = ImageCodecAvailability.ready, this.unavailableReason, this.latency = const Duration(milliseconds: 250), }); @override Future encode( Uint8List imageBytes, ImageCodecRatePoint rate, ) async { if (latency > Duration.zero) { await Future.delayed(latency); } final size = ImageCodecRateStats.forRate(rate).meanBytes; return Uint8List.fromList( List.generate(size, (i) => (i * 31 + rate.index) & 0xFF), ); } @override Future decodePreview(Uint8List payload) async => null; }