A pass at the app's structure, for discussion

README.md

@@ -27,7 +27,7 @@ Please open bug reports when you find things wrong, bug reports help me build th
   ViewModel-backed decode buffering for multipart messages.
 
 See `android/README.md` for build and usage details, and
-`android/ENGINE_INTEGRATION_COMPLETE.md` for the end-to-end architecture notes.
+`android/ARCHITECTURE.md` for how the app layer is put together.
 
 ## License
 

adapters/android/jni/js8_engine_jni.cpp

@@ -43,6 +43,8 @@ JNIEXPORT void JNICALL Java_com_js8call_core_JS8Engine_nativeStopTransmit(JNIEnv
 JNIEXPORT jboolean JNICALL Java_com_js8call_core_JS8Engine_nativeIsTransmitting(JNIEnv*, jobject, jlong);
 JNIEXPORT jboolean JNICALL Java_com_js8call_core_JS8Engine_nativeIsTransmittingAudio(JNIEnv*, jobject, jlong);
 JNIEXPORT jint JNICALL Java_com_js8call_core_JS8Engine_nativeTxMillisecondsUntilAudio(JNIEnv*, jobject, jlong);
+JNIEXPORT jint JNICALL Java_com_js8call_core_JS8Engine_nativeTxFrameIndex(JNIEnv*, jobject, jlong);
+JNIEXPORT jint JNICALL Java_com_js8call_core_JS8Engine_nativeTxFrameCount(JNIEnv*, jobject, jlong);
 JNIEXPORT void JNICALL Java_com_js8call_core_JS8Engine_nativeSetTxReady(JNIEnv*, jobject, jlong, jboolean);
 JNIEXPORT void JNICALL Java_com_js8call_core_JS8Engine_nativeSetTimeDriftMs(JNIEnv*, jobject, jlong, jlong);
 JNIEXPORT jlong JNICALL Java_com_js8call_core_JS8Engine_nativeGetTimeDriftMs(JNIEnv*, jobject, jlong);
@@ -223,6 +225,9 @@ static bool is_callsign_like(std::string const& token) {
   return has_digit;
 }
 
+// Only valid on a line's first frame. A continuation frame of a buffered
+// command is plain payload text, and rewriting "KA0XYZ N0CALL QRV" into
+// "KA0XYZ: N0CALL QRV" there corrupts the body and breaks its checksum.
 static std::string maybe_insert_callsign_prefix(std::string const& text) {
   std::size_t first_sep = std::string::npos;
   for (std::size_t i = 0; i < text.size(); ++i) {
@@ -269,6 +274,10 @@ static std::string render_decoded_text(js8core::events::Decoded const& decoded)
   }
 
   bool is_data_flag = (decoded.type & 0b100) == 0b100;
+  // The transmitter sets this bit only on a line's first frame
+  // (varicode.cpp build_message_frames), so a continuation frame of a
+  // buffered command never carries it.
+  bool is_first_frame = (decoded.type & 0b1) == 0b1;
   // Try data payloads first (mirrors desktop unpack order).
   __android_log_print(ANDROID_LOG_DEBUG, "JS8FrameDebug",
                       "Trying data unpacker: frame='%s', decoded.type=0x%02x",
@@ -277,7 +286,9 @@ static std::string render_decoded_text(js8core::events::Decoded const& decoded)
     auto data = unpack_fast_data_message(frame);
     __android_log_print(ANDROID_LOG_DEBUG, "JS8FrameDebug",
                         "unpack_fast_data returned: '%s'", data.c_str());
-    if (!data.empty()) return maybe_insert_callsign_prefix(data);
+    if (!data.empty()) {
+      return is_first_frame ? maybe_insert_callsign_prefix(data) : data;
+    }
     // Fast-data frames should not be treated as heartbeat/compound/directed.
     __android_log_print(ANDROID_LOG_WARN, "JS8FrameDebug",
                         "Fast data unpack failed, returning raw frame: '%s'", frame.c_str());
@@ -286,7 +297,9 @@ static std::string render_decoded_text(js8core::events::Decoded const& decoded)
     auto data = unpack_data_message(frame);
     __android_log_print(ANDROID_LOG_DEBUG, "JS8FrameDebug",
                         "unpack_data returned: '%s'", data.c_str());
-    if (!data.empty()) return maybe_insert_callsign_prefix(data);
+    if (!data.empty()) {
+      return is_first_frame ? maybe_insert_callsign_prefix(data) : data;
+    }
   }
 
   // Heartbeat (most common for status beacons)
@@ -436,6 +449,17 @@ static void event_callback(JS8Engine_Native* native, js8core::events::Variant co
       env->CallVoidMethod(native->callback_handler, method,
                          static_cast<jint>(decode_finished->decoded));
     }
+  } else if (auto* timing = std::get_if<js8core::events::TimingSuggestion>(&event)) {
+    // Call onTimingSuggestion(int kind, int driftMs, int step, int steps)
+    jmethodID method = env->GetMethodID(handler_class, "onTimingSuggestion", "(IIIII)V");
+    if (method) {
+      env->CallVoidMethod(native->callback_handler, method,
+                          static_cast<jint>(timing->kind),
+                          static_cast<jint>(timing->drift_ms),
+                          static_cast<jint>(timing->step),
+                          static_cast<jint>(timing->steps),
+                          static_cast<jint>(timing->period_ms));
+    }
   }
 
   env->DeleteLocalRef(handler_class);
@@ -888,6 +912,16 @@ int js8_engine_tx_milliseconds_until_audio(JS8Engine_Native* engine) {
   return engine->engine->tx_milliseconds_until_audio();
 }
 
+int js8_engine_tx_frame_index(JS8Engine_Native* engine) {
+  if (!engine || !engine->engine) return 0;
+  return engine->engine->tx_frame_index();
+}
+
+int js8_engine_tx_frame_count(JS8Engine_Native* engine) {
+  if (!engine || !engine->engine) return 0;
+  return engine->engine->tx_frame_count();
+}
+
 void js8_engine_set_tx_ready(JS8Engine_Native* engine, bool ready) {
   if (!engine || !engine->engine) return;
   engine->engine->set_tx_ready(ready);
@@ -945,6 +979,10 @@ int js8_register_natives(JavaVM* vm, JNIEnv* env) {
       (void*)Java_com_js8call_core_JS8Engine_nativeIsTransmittingAudio},
     {"nativeTxMillisecondsUntilAudio", "(J)I",
      (void*)Java_com_js8call_core_JS8Engine_nativeTxMillisecondsUntilAudio},
+    {"nativeTxFrameIndex", "(J)I",
+     (void*)Java_com_js8call_core_JS8Engine_nativeTxFrameIndex},
+    {"nativeTxFrameCount", "(J)I",
+     (void*)Java_com_js8call_core_JS8Engine_nativeTxFrameCount},
     {"nativeSetTxReady", "(JZ)V",
      (void*)Java_com_js8call_core_JS8Engine_nativeSetTxReady},
     {"nativeSetTimeDriftMs", "(JJ)V",

adapters/android/jni/js8_engine_jni.h

@@ -54,6 +54,8 @@ void js8_engine_stop_transmit(JS8Engine_Native* engine);
 int js8_engine_is_transmitting(JS8Engine_Native* engine);
 int js8_engine_is_transmitting_audio(JS8Engine_Native* engine);
 int js8_engine_tx_milliseconds_until_audio(JS8Engine_Native* engine);
+int js8_engine_tx_frame_index(JS8Engine_Native* engine);
+int js8_engine_tx_frame_count(JS8Engine_Native* engine);
 void js8_engine_set_tx_ready(JS8Engine_Native* engine, bool ready);
 
 // Status queries

adapters/android/jni/js8_jni_methods.cpp

@@ -366,6 +366,24 @@ Java_com_js8call_core_JS8Engine_nativeTxMillisecondsUntilAudio(
   return static_cast<jint>(js8_engine_tx_milliseconds_until_audio(engine));
 }
 
+JNIEXPORT jint JNICALL
+Java_com_js8call_core_JS8Engine_nativeTxFrameIndex(
+    JNIEnv* /* env */,
+    jobject /* thiz */,
+    jlong handle) {
+  JS8Engine_Native* engine = reinterpret_cast<JS8Engine_Native*>(handle);
+  return static_cast<jint>(js8_engine_tx_frame_index(engine));
+}
+
+JNIEXPORT jint JNICALL
+Java_com_js8call_core_JS8Engine_nativeTxFrameCount(
+    JNIEnv* /* env */,
+    jobject /* thiz */,
+    jlong handle) {
+  JS8Engine_Native* engine = reinterpret_cast<JS8Engine_Native*>(handle);
+  return static_cast<jint>(js8_engine_tx_frame_count(engine));
+}
+
 JNIEXPORT void JNICALL
 Java_com_js8call_core_JS8Engine_nativeSetTxReady(
     JNIEnv* /* env */,

adapters/android/jni/kotlin/JS8Engine.kt

@@ -232,6 +232,20 @@ class JS8Engine private constructor(
         return withNativeHandleOr(-1) { nativeTxMillisecondsUntilAudio(it) }
     }
 
+    /**
+     * 1-based index of the frame now being sent, or 0 when idle or tuning.
+     */
+    fun txFrameIndex(): Int {
+        return withNativeHandleOr(0) { nativeTxFrameIndex(it) }
+    }
+
+    /**
+     * Total frames in the current message, or 0 when idle or tuning.
+     */
+    fun txFrameCount(): Int {
+        return withNativeHandleOr(0) { nativeTxFrameCount(it) }
+    }
+
     /** Controls whether scheduled modulation may advance and reach the output. */
     fun setTransmitReady(ready: Boolean) {
         withNativeHandle { nativeSetTxReady(it, ready) }
@@ -337,6 +351,8 @@ class JS8Engine private constructor(
     private external fun nativeIsTransmitting(handle: Long): Boolean
     private external fun nativeIsTransmittingAudio(handle: Long): Boolean
     private external fun nativeTxMillisecondsUntilAudio(handle: Long): Int
+    private external fun nativeTxFrameIndex(handle: Long): Int
+    private external fun nativeTxFrameCount(handle: Long): Int
     private external fun nativeSetTxReady(handle: Long, ready: Boolean)
     private external fun nativeSetTimeDriftMs(handle: Long, driftMs: Long)
     private external fun nativeGetTimeDriftMs(handle: Long): Long
@@ -396,5 +412,12 @@ class JS8Engine private constructor(
          * Called with TX audio PCM samples when enabled.
          */
         fun onTxAudio(samples: ShortArray, sampleRateHz: Int) {}
+
+        /**
+         * Raised when decoding has gone dead and the engine is trying shifted
+         * windows to find the clock offset. [kind] is 0 searching, 1 found,
+         * 2 gave up. [driftMs] is the total drift to apply on a find.
+         */
+        fun onTimingSuggestion(kind: Int, driftMs: Int, step: Int, steps: Int, periodMs: Int) {}
     }
 }