@lucent-lang/lucent 0.0.4 → 0.1.0

package/runtime/cpp/lucent/platform/android.cpp

@@ -8,10 +8,14 @@
 #include <fbjni/fbjni.h>
 #include <sys/system_properties.h>
 
+#include <atomic>
+#include <cstdint>
 #include <cstdlib>
 #include <mutex>
+#include <optional>
 #include <string>
 #include <unordered_map>
+#include <vector>
 
 namespace lucent::jni {
 
@@ -84,9 +88,75 @@ jmethodID staticMethod(jclass cls, const char* name, const char* sig) { LUCENT_J
 jfieldID field(jclass cls, const char* name, const char* sig) { LUCENT_JNI_ID(GetFieldID, "field") }
 jfieldID staticField(jclass cls, const char* name, const char* sig) { LUCENT_JNI_ID(GetStaticFieldID, "field") }
 
+namespace {
+
+/// Lucent errors thrown to Java, by the Java exception carrying each (a weak
+/// reference): errorOf gives back the error itself, not a copy.
+struct Thrown {
+  jweak exception;
+  Error error;
+};
+
+std::mutex thrownMutex;
+std::vector<Thrown>& thrown() {
+  static auto* v = new std::vector<Thrown>();
+  return *v;
+}
+
+/// The Lucent error `t` carries, removed from the list; none for other exceptions.
+std::optional<Error> takeThrown(JNIEnv* e, jobject t) {
+  std::lock_guard<std::mutex> g(thrownMutex);
+  auto& v = thrown();
+  for (auto it = v.begin(); it != v.end(); ++it) {
+    if (!e->IsSameObject(it->exception, t)) continue;
+
+    Error error = std::move(it->error);
+    e->DeleteWeakGlobalRef(it->exception);
+    v.erase(it);
+    return error;
+  }
+  return std::nullopt;
+}
+
+}  // namespace
+
+void throwToJava(JNIEnv* e, Error error) {
+  static jclass cls = findClass("java/lang/RuntimeException");
+  static jmethodID init = method(cls, "<init>", "(Ljava/lang/String;)V");
+  jstring message = toJString(e, error->message);
+  auto exception = static_cast<jthrowable>(e->NewObject(cls, init, message));
+  e->DeleteLocalRef(message);
+  if (!exception) return;  // A pending OutOfMemoryError ends the call instead.
+
+  {
+    std::lock_guard<std::mutex> g(thrownMutex);
+    auto& v = thrown();
+    // Exceptions Java dropped without Lucent reading them.
+    std::erase_if(v, [e](Thrown& x) {
+      if (!e->IsSameObject(x.exception, nullptr)) return false;
+      e->DeleteWeakGlobalRef(x.exception);
+      return true;
+    });
+    v.push_back({e->NewWeakGlobalRef(exception), std::move(error)});
+  }
+  e->Throw(exception);
+  e->DeleteLocalRef(exception);
+}
+
 void rethrowPending(JNIEnv* e) {
   jthrowable t = e->ExceptionOccurred();
   e->ExceptionClear();
+  throw Exception(errorOf(e, t));
+}
+
+Error errorOf(JNIEnv* e, jobject t) {
+  if (auto own = t ? takeThrown(e, t) : std::nullopt) return std::move(*own);
+  if (!t) {
+    // No exception to read: a cancelled task.
+    Error err = makeError(String::fromLatin1("Error"), String::fromLatin1("cancelled"));
+    err->code = String::fromLatin1("java.util.concurrent.CancellationException");
+    return err;
+  }
   jclass objectCls = e->FindClass("java/lang/Object");
   jobject cls = e->CallObjectMethod(t, e->GetMethodID(objectCls, "getClass", "()Ljava/lang/Class;"));
   jclass classCls = e->FindClass("java/lang/Class");
@@ -97,7 +167,14 @@ void rethrowPending(JNIEnv* e) {
   String className = name ? fromJString(e, name, "") : String::fromLatin1("java.lang.Throwable");
   Error err = makeError(String::fromLatin1("Error"), message ? fromJString(e, message, "") : className);
   err->code = className;
-  throw Exception(err);
+  return err;
+}
+
+void close(const NativeRef& closeable) {
+  JNIEnv* e = env();
+  static jmethodID m = method(findClass("java/lang/AutoCloseable"), "close", "()V");
+  e->CallVoidMethod(unwrap(closeable), m);
+  check(e);
 }
 
 NativeRef wrap(JNIEnv* e, jobject local, const char* what) {
@@ -161,13 +238,13 @@ jobjectArray toStringArray(JNIEnv* e, const Array<String>& a) {
   return out;
 }
 
-Array<double> fromLongArray(JNIEnv* e, jlongArray a, const char* what) {
+Array<BigInt> fromLongArray(JNIEnv* e, jlongArray a, const char* what) {
   if (!a) failWith("TypeError", std::string(what) + " returned null");
   jsize n = e->GetArrayLength(a);
   std::vector<jlong> buf(static_cast<size_t>(n));
   e->GetLongArrayRegion(a, 0, n, buf.data());
-  Array<double> out;
-  for (jlong v : buf) out.push(static_cast<double>(v));
+  Array<BigInt> out;
+  for (jlong v : buf) out.push(BigInt(v));
   return out;
 }
 
@@ -202,11 +279,11 @@ Array<String> fromStringArray(JNIEnv* e, jobjectArray a, const char* what) {
   return out;
 }
 
-jlongArray toLongArray(JNIEnv* e, const Array<double>& a) {
+jlongArray toLongArray(JNIEnv* e, const Array<BigInt>& a, const char* what) {
   auto n = static_cast<jsize>(a.size());
-  jlongArray out = e->NewLongArray(n);
   std::vector<jlong> buf(static_cast<size_t>(n));
-  for (jsize i = 0; i < n; i++) buf[static_cast<size_t>(i)] = static_cast<jlong>(a.at(static_cast<size_t>(i)));
+  for (jsize i = 0; i < n; i++) buf[static_cast<size_t>(i)] = toNativeInteger<jlong>(a.at(static_cast<size_t>(i)), what);
+  jlongArray out = e->NewLongArray(n);
   e->SetLongArrayRegion(out, 0, n, buf.data());
   return out;
 }
@@ -220,6 +297,94 @@ jintArray toIntArray(JNIEnv* e, const Array<double>& a) {
   return out;
 }
 
+void returnedNull(const char* what) { failWith("TypeError", std::string(what) + " returned null"); }
+
+jobjectArray listElements(JNIEnv* e, jobject list, const char* what) {
+  if (!list) returnedNull(what);
+
+  static jmethodID toArray = method(findClass("java/util/Collection"), "toArray", "()[Ljava/lang/Object;");
+  auto a = static_cast<jobjectArray>(e->CallObjectMethod(list, toArray));
+  check(e);
+  return a;
+}
+
+jobject newList(JNIEnv* e, jsize n) {
+  static jclass cls = findClass("java/util/ArrayList");
+  static jmethodID init = method(cls, "<init>", "(I)V");
+  jobject list = e->NewObject(cls, init, n);
+  check(e);
+  return list;
+}
+
+void listAdd(JNIEnv* e, jobject list, jobject element) {
+  static jmethodID add = method(findClass("java/util/List"), "add", "(Ljava/lang/Object;)Z");
+  e->CallBooleanMethod(list, add, element);
+  check(e);
+}
+
+namespace {
+
+/// A Java array of primitives as numbers (or booleans), read in one copy.
+template <class R, class A, class J>
+Array<R> fromPrimitives(JNIEnv* e, A a, void (JNIEnv::*get)(A, jsize, jsize, J*), const char* what) {
+  if (!a) returnedNull(what);
+
+  jsize n = e->GetArrayLength(a);
+  std::vector<J> buf(static_cast<size_t>(n));
+  (e->*get)(a, 0, n, buf.data());
+
+  Array<R> out;
+  for (J v : buf) out.push(static_cast<R>(v));
+  return out;
+}
+
+/// Numbers (or booleans) as a Java array of primitives, each converted by `to`.
+template <class A, class J, class T, class F>
+A toPrimitives(JNIEnv* e, const Array<T>& a, A (JNIEnv::*make)(jsize), void (JNIEnv::*set)(A, jsize, jsize, const J*), F to) {
+  auto n = static_cast<jsize>(a.size());
+  A out = (e->*make)(n);
+
+  std::vector<J> buf(static_cast<size_t>(n));
+  for (jsize i = 0; i < n; i++) buf[static_cast<size_t>(i)] = to(a.at(static_cast<size_t>(i)));
+  (e->*set)(out, 0, n, buf.data());
+  return out;
+}
+
+}  // namespace
+
+Array<double> fromShortArray(JNIEnv* e, jshortArray a, const char* what) { return fromPrimitives<double>(e, a, &JNIEnv::GetShortArrayRegion, what); }
+Array<double> fromCharArray(JNIEnv* e, jcharArray a, const char* what) { return fromPrimitives<double>(e, a, &JNIEnv::GetCharArrayRegion, what); }
+Array<double> fromFloatArray(JNIEnv* e, jfloatArray a, const char* what) { return fromPrimitives<double>(e, a, &JNIEnv::GetFloatArrayRegion, what); }
+Array<double> fromDoubleArray(JNIEnv* e, jdoubleArray a, const char* what) { return fromPrimitives<double>(e, a, &JNIEnv::GetDoubleArrayRegion, what); }
+
+Array<bool> fromBooleanArray(JNIEnv* e, jbooleanArray a, const char* what) {
+  if (!a) returnedNull(what);
+
+  jsize n = e->GetArrayLength(a);
+  std::vector<jboolean> buf(static_cast<size_t>(n));
+  e->GetBooleanArrayRegion(a, 0, n, buf.data());
+
+  Array<bool> out;
+  for (jboolean v : buf) out.push(v == JNI_TRUE);
+  return out;
+}
+
+jshortArray toShortArray(JNIEnv* e, const Array<double>& a) {
+  return toPrimitives<jshortArray, jshort>(e, a, &JNIEnv::NewShortArray, &JNIEnv::SetShortArrayRegion, [](double v) { return static_cast<jshort>(toInt32(v)); });
+}
+jcharArray toCharArray(JNIEnv* e, const Array<double>& a) {
+  return toPrimitives<jcharArray, jchar>(e, a, &JNIEnv::NewCharArray, &JNIEnv::SetCharArrayRegion, [](double v) { return static_cast<jchar>(toInt32(v)); });
+}
+jfloatArray toFloatArray(JNIEnv* e, const Array<double>& a) {
+  return toPrimitives<jfloatArray, jfloat>(e, a, &JNIEnv::NewFloatArray, &JNIEnv::SetFloatArrayRegion, [](double v) { return static_cast<jfloat>(v); });
+}
+jdoubleArray toDoubleArray(JNIEnv* e, const Array<double>& a) {
+  return toPrimitives<jdoubleArray, jdouble>(e, a, &JNIEnv::NewDoubleArray, &JNIEnv::SetDoubleArrayRegion, [](double v) { return v; });
+}
+jbooleanArray toBooleanArray(JNIEnv* e, const Array<bool>& a) {
+  return toPrimitives<jbooleanArray, jboolean>(e, a, &JNIEnv::NewBooleanArray, &JNIEnv::SetBooleanArrayRegion, [](bool v) { return static_cast<jboolean>(v ? JNI_TRUE : JNI_FALSE); });
+}
+
 // --- proxies ---------------------------------------------------------------------------
 
 namespace {
@@ -339,8 +504,10 @@ jobject cachedJavaObject(JNIEnv* e, std::pair<const void*, std::string> key, std
 
 }  // namespace
 
-jobject proxyFor(JNIEnv* e, const char* iface, const void* identity, std::initializer_list<std::pair<const char*, ProxyMethod>> methods) {
-  return cachedJavaObject(e, {identity, iface}, methods, [&](jlong handle) {
+jobject proxyFor(JNIEnv* e, const char* iface, const void* identity, std::initializer_list<std::pair<const char*, ProxyMethod>> methods,
+                 const char* variant) {
+  std::string key = variant ? std::string(iface) + "#" + variant : std::string(iface);
+  return cachedJavaObject(e, {identity, key}, methods, [&](jlong handle) {
     jclass cls = nativeProxyClass(e);
     static jmethodID create = staticMethod(cls, "create", "(Ljava/lang/Class;J)Ljava/lang/Object;");
     return e->CallStaticObjectMethod(cls, create, findClass(iface), handle);
@@ -356,6 +523,19 @@ jobject subclassFor(JNIEnv* e, const char* cls, const void* identity, std::initi
 
 jobject arg(JNIEnv* e, jobjectArray args, int i) { return e->GetObjectArrayElement(args, i); }
 
+jobject detail::completionFor(JNIEnv* e, std::function<void(JNIEnv*, jobject, jobject)> settle) {
+  // A fresh identity for each call: proxies are cached per identity while Java holds them.
+  static std::atomic<uintptr_t> next{1};
+  const void* identity = reinterpret_cast<const void*>(next.fetch_add(1));
+
+  ProxyMethod accept = [settle = std::move(settle)](JNIEnv* env, jobjectArray args) -> jobject {
+    settle(env, arg(env, args, 0), arg(env, args, 1));
+    return nullptr;
+  };
+
+  return proxyFor(e, "java/util/function/BiConsumer", identity, {{"accept(Ljava/lang/Object;Ljava/lang/Object;)", accept}});
+}
+
 double unboxNumber(JNIEnv* e, jobject boxed) {
   static jmethodID doubleValue = method(findClass("java/lang/Number"), "doubleValue", "()D");
   double v = e->CallDoubleMethod(boxed, doubleValue);
@@ -363,6 +543,13 @@ double unboxNumber(JNIEnv* e, jobject boxed) {
   return v;
 }
 
+jlong unboxLong(JNIEnv* e, jobject boxed) {
+  static jmethodID longValue = method(findClass("java/lang/Number"), "longValue", "()J");
+  jlong v = e->CallLongMethod(boxed, longValue);
+  check(e);
+  return v;
+}
+
 bool unboxBoolean(JNIEnv* e, jobject boxed) {
   static jmethodID booleanValue = method(findClass("java/lang/Boolean"), "booleanValue", "()Z");
   bool v = e->CallBooleanMethod(boxed, booleanValue) == JNI_TRUE;
@@ -371,6 +558,9 @@ bool unboxBoolean(JNIEnv* e, jobject boxed) {
 }
 
 jobject boxInt(JNIEnv* e, jint v) { return boxWith(e, "java/lang/Integer", "(I)Ljava/lang/Integer;", jvalue{.i = v}); }
+jobject boxShort(JNIEnv* e, jshort v) { return boxWith(e, "java/lang/Short", "(S)Ljava/lang/Short;", jvalue{.s = v}); }
+jobject boxByte(JNIEnv* e, jbyte v) { return boxWith(e, "java/lang/Byte", "(B)Ljava/lang/Byte;", jvalue{.b = v}); }
+jobject boxChar(JNIEnv* e, jchar v) { return boxWith(e, "java/lang/Character", "(C)Ljava/lang/Character;", jvalue{.c = v}); }
 jobject boxLong(JNIEnv* e, jlong v) { return boxWith(e, "java/lang/Long", "(J)Ljava/lang/Long;", jvalue{.j = v}); }
 jobject boxDouble(JNIEnv* e, jdouble v) { return boxWith(e, "java/lang/Double", "(D)Ljava/lang/Double;", jvalue{.d = v}); }
 jobject boxFloat(JNIEnv* e, jfloat v) { return boxWith(e, "java/lang/Float", "(F)Ljava/lang/Float;", jvalue{.f = v}); }
@@ -383,11 +573,34 @@ NativeRef appContext() {
     check(e);
     jmethodID current = e->GetStaticMethodID(cls, "currentApplication", "()Landroid/app/Application;");
     check(e);
-    return new NativeRef(wrap(e, e->CallStaticObjectMethod(cls, current), "ActivityThread.currentApplication()"));
+    auto* kept = new NativeRef(wrap(e, e->CallStaticObjectMethod(cls, current), "ActivityThread.currentApplication()"));
+
+    // Never released: not what a JavaScript runtime's teardown leaves behind.
+    kept->keepForProcess();
+    return kept;
   }();
   return *app;
 }
 
+namespace {
+thread_local jobject hostingView = nullptr;
+}  // namespace
+
+HostViewEntry::HostViewEntry(jobject view) : outer_(hostingView) { hostingView = view; }
+
+HostViewEntry::~HostViewEntry() { hostingView = outer_; }
+
+Opt<NativeRef> hostContext() {
+  if (!hostingView) return Opt<NativeRef>(null);
+
+  JNIEnv* e = env();
+  static jmethodID getContext = method(findClass("android/view/View"), "getContext", "()Landroid/content/Context;");
+  jobject context = e->CallObjectMethod(hostingView, getContext);
+
+  check(e);
+  return wrapOpt(e, context);
+}
+
 bool available(double api) {
   static int level = [] {
     char value[PROP_VALUE_MAX] = {0};

package/runtime/cpp/lucent/platform/android.h

@@ -7,10 +7,15 @@
 #include <initializer_list>
 #include <utility>
 
+#include "../abort.h"
 #include "../array.h"
+#include "../async.h"
+#include "../bigint.h"
 #include "../bytes.h"
+#include "../function.h"
 #include "../jsstring.h"
 #include "../native.h"
+#include "../operation.h"
 
 namespace lucent::jni {
 
@@ -30,6 +35,12 @@ void rethrowPending(JNIEnv* env);
 inline void check(JNIEnv* env) {
   if (env->ExceptionCheck()) rethrowPending(env);
 }
+/// A Java exception (a Throwable) as a Lucent error, coded as rethrowPending does.
+Error errorOf(JNIEnv* env, jobject throwable);
+
+/// Closes an AutoCloseable (a Closeable, a Cursor…): how a `using`
+/// declaration disposes one. Throws what close() throws.
+void close(const NativeRef& closeable);
 
 /// A Lucent reference to `local` (a global ref; the local ref is deleted).
 /// Throws TypeError for null.
@@ -46,16 +57,29 @@ String charSequenceToString(JNIEnv* env, jobject s, const char* what);
 Opt<String> charSequenceToStringOpt(JNIEnv* env, jobject s);
 
 // Arrays are copied in both directions; a null reference is an absent value.
-jlongArray toLongArray(JNIEnv* env, const Array<double>& a);
+// Numbers go to Java's integral types as ToInt32 would, then narrowed (short,
+// char), as JavaScript's typed arrays store them.
+/// Each element exactly, or RangeError naming `what`.
+jlongArray toLongArray(JNIEnv* env, const Array<BigInt>& a, const char* what);
 jintArray toIntArray(JNIEnv* env, const Array<double>& a);
+jshortArray toShortArray(JNIEnv* env, const Array<double>& a);
+jcharArray toCharArray(JNIEnv* env, const Array<double>& a);
+jfloatArray toFloatArray(JNIEnv* env, const Array<double>& a);
+jdoubleArray toDoubleArray(JNIEnv* env, const Array<double>& a);
+jbooleanArray toBooleanArray(JNIEnv* env, const Array<bool>& a);
 jbyteArray toByteArray(JNIEnv* env, const Bytes& b);
 jobjectArray toStringArray(JNIEnv* env, const Array<String>& a);
 template <class T, class F>
 auto toArrayOpt(JNIEnv* env, const Opt<T>& v, F convert) -> decltype(convert(env, v.get())) {
   return v.has() ? convert(env, v.get()) : nullptr;
 }
-Array<double> fromLongArray(JNIEnv* env, jlongArray a, const char* what);
+Array<BigInt> fromLongArray(JNIEnv* env, jlongArray a, const char* what);
 Array<double> fromIntArray(JNIEnv* env, jintArray a, const char* what);
+Array<double> fromShortArray(JNIEnv* env, jshortArray a, const char* what);
+Array<double> fromCharArray(JNIEnv* env, jcharArray a, const char* what);
+Array<double> fromFloatArray(JNIEnv* env, jfloatArray a, const char* what);
+Array<double> fromDoubleArray(JNIEnv* env, jdoubleArray a, const char* what);
+Array<bool> fromBooleanArray(JNIEnv* env, jbooleanArray a, const char* what);
 Bytes fromByteArray(JNIEnv* env, jbyteArray a, const char* what);
 Array<String> fromStringArray(JNIEnv* env, jobjectArray a, const char* what);
 template <class T, class A, class F>
@@ -76,6 +100,69 @@ class LocalFrame {
   JNIEnv* env_;
 };
 
+[[noreturn]] void returnedNull(const char* what);
+
+/// A Java array of objects (or of arrays) as a Lucent array: `each` gets
+/// every element as a local reference, which is freed once it has run.
+template <class T, class F>
+Array<T> fromObjectArray(JNIEnv* env, jobjectArray a, F each, const char* what) {
+  if (!a) returnedNull(what);
+
+  jsize n = env->GetArrayLength(a);
+  Array<T> out;
+  for (jsize i = 0; i < n; i++) {
+    LocalFrame frame(env);
+    out.push(each(env->GetObjectArrayElement(a, i)));
+  }
+  return out;
+}
+
+/// A Lucent array as a Java array of `elementClass` (a class, or an array
+/// type's descriptor): `each` gives every element's reference, a local one
+/// freed once it is stored.
+template <class T, class F>
+jobjectArray toObjectArray(JNIEnv* env, const Array<T>& a, const char* elementClass, F each) {
+  auto n = static_cast<jsize>(a.size());
+  jobjectArray out = env->NewObjectArray(n, findClass(elementClass), nullptr);
+  for (jsize i = 0; i < n; i++) {
+    LocalFrame frame(env);
+    env->SetObjectArrayElement(out, i, each(a.at(static_cast<size_t>(i))));
+  }
+  return out;
+}
+
+// --- Kotlin's read-only lists, copied ------------------------------------------------
+
+/// A list's elements, in one copy (Collection.toArray()): a local reference.
+jobjectArray listElements(JNIEnv* env, jobject list, const char* what);
+/// A new java.util.ArrayList with room for `n` elements: a local reference.
+jobject newList(JNIEnv* env, jsize n);
+/// Appends `element` (null allowed) to `list`.
+void listAdd(JNIEnv* env, jobject list, jobject element);
+
+/// A java.util.List as a Lucent array, copied: `each` gets every element (a
+/// local reference, null where the list holds null), freed once it has run.
+template <class T, class F>
+Array<T> fromList(JNIEnv* env, jobject list, F each, const char* what) {
+  jobjectArray a = listElements(env, list, what);
+  Array<T> out = fromObjectArray<T>(env, a, each, what);
+  env->DeleteLocalRef(a);
+  return out;
+}
+
+/// A Lucent array as a new java.util.ArrayList, copied: `each` gives every
+/// element's reference (null allowed), a local one freed once it is added.
+template <class T, class F>
+jobject toList(JNIEnv* env, const Array<T>& a, F each) {
+  auto n = static_cast<jsize>(a.size());
+  jobject out = newList(env, n);
+  for (jsize i = 0; i < n; i++) {
+    LocalFrame frame(env);
+    listAdd(env, out, each(a.at(static_cast<size_t>(i))));
+  }
+  return out;
+}
+
 // --- Java interfaces implemented by Lucent code --------------------------------------
 
 /// Handles one method of a proxy: its arguments (boxed), its result (boxed,
@@ -87,9 +174,12 @@ using ProxyMethod = std::function<jobject(JNIEnv*, jobjectArray)>;
  * methods are `methods`, keyed by name and parameter descriptor
  * (`onLocationChanged(Landroid/location/Location;)`). One per `identity` (a Lucent function or
  * object) while Java holds it, so passing the same function twice passes
- * the same object. A local reference.
+ * the same object; one per `variant` too, when methods of the same
+ * interface differ by where the object is passed (a Kotlin function's
+ * arguments are read as each place types them). A local reference.
  */
-jobject proxyFor(JNIEnv* env, const char* iface, const void* identity, std::initializer_list<std::pair<const char*, ProxyMethod>> methods);
+jobject proxyFor(JNIEnv* env, const char* iface, const void* identity, std::initializer_list<std::pair<const char*, ProxyMethod>> methods,
+                 const char* variant = nullptr);
 
 /**
  * An instance of `cls` (a generated Java subclass of an SDK class, made with
@@ -102,16 +192,149 @@ jobject subclassFor(JNIEnv* env, const char* cls, const void* identity, std::ini
 jobject arg(JNIEnv* env, jobjectArray args, int i);
 /// Primitive values of boxed arguments, and boxed results.
 double unboxNumber(JNIEnv* env, jobject boxed);
+/// A boxed long, as it is (the glue makes it a bigint, or a group's number).
+jlong unboxLong(JNIEnv* env, jobject boxed);
 bool unboxBoolean(JNIEnv* env, jobject boxed);
 jobject boxInt(JNIEnv* env, jint v);
+jobject boxShort(JNIEnv* env, jshort v);
+jobject boxByte(JNIEnv* env, jbyte v);
+jobject boxChar(JNIEnv* env, jchar v);
 jobject boxLong(JNIEnv* env, jlong v);
 jobject boxDouble(JNIEnv* env, jdouble v);
 jobject boxFloat(JNIEnv* env, jfloat v);
 jobject boxBoolean(JNIEnv* env, bool v);
 
+// --- Kotlin coroutines through generated shims ----------------------------------------
+
+/// Throws `error` to Java as a java.lang.RuntimeException carrying its
+/// message, which errorOf reads back as `error` itself.
+void throwToJava(JNIEnv* env, Error error);
+
+/**
+ * A Lucent function a generated shim runs as a Kotlin suspend function (a
+ * suspend function argument, a fun interface's suspending function), which
+ * Kotlin waits for: `f` runs on the calling thread holding the Lucent lock
+ * and gives the boxed result. What it throws is thrown to Kotlin (see
+ * throwToJava), so the Kotlin call ends with that error.
+ */
+template <class F>
+jobject callSuspending(JNIEnv* env, F f) {
+  LucentScope scope;
+  try {
+    return f();
+  } catch (...) {
+    throwToJava(env, currentError(std::current_exception()));
+    return nullptr;
+  }
+}
+
+namespace detail {
+
+/// A java.util.function.BiConsumer whose accept(value, error) calls
+/// `settle`, where Java calls it. A local reference, new for each call.
+jobject completionFor(JNIEnv* env, std::function<void(JNIEnv*, jobject value, jobject error)> settle);
+
+}  // namespace detail
+
+/**
+ * A suspend function called through a generated Kotlin shim, as a promise
+ * of the calling context. `start` calls the shim with a completion (a
+ * BiConsumer of the value, or of the Throwable it threw) and returns what
+ * cancels the coroutine (an AutoCloseable). `convert` reads the value,
+ * where the coroutine completes. The signal aborting, or the context's
+ * scope being disposed, rejects the promise and cancels the coroutine; a
+ * value that arrives after that is released (nativeOperation).
+ */
+template <class T>
+Promise<T> launch(Opt<AbortSignal> signal, const char* what, const std::function<jobject(JNIEnv*, jobject)>& start,
+                  std::function<::lucent::detail::Stored<T>(JNIEnv*, jobject)> convert) {
+  auto registration = [&start, convert = std::move(convert), what](const std::shared_ptr<Operation<T>>& op) -> std::function<void()> {
+    JNIEnv* e = env();
+    LocalFrame frame(e);
+    std::weak_ptr<Operation<T>> pending = op;
+
+    jobject done = detail::completionFor(e, [pending, convert](JNIEnv* e, jobject value, jobject error) {
+      auto o = pending.lock();
+      if (!o) return;
+
+      if (error) {
+        o->fail(errorOf(e, error));
+        return;
+      }
+
+      try {
+        if constexpr (std::is_void_v<T>) {
+          o->succeed();
+        } else {
+          o->succeed(convert(e, value));
+        }
+      } catch (...) {
+        o->fail(currentError(std::current_exception()));
+      }
+    });
+
+    jobject cancel = start(e, done);
+    check(e);
+
+    NativeRef stop = wrap(e, cancel, what);
+    return [stop] { close(stop); };
+  };
+
+  return nativeOperation<T>(registration, std::move(signal));
+}
+
 /// `appContext()` from lucent:android: the Application.
 NativeRef appContext();
+
+/// The context of the view hosting the mount whose setup runs now on this
+/// thread (the Activity's, as React Native themes its views), or null
+/// outside any setup.
+Opt<NativeRef> hostContext();
+
+/**
+ * While one lives, `view` (a local reference) hosts the mount whose setup
+ * runs on this thread, and hostContext() is its context: the Android host
+ * of components holds one around each setup. Nests.
+ */
+class HostViewEntry {
+ public:
+  explicit HostViewEntry(jobject view);
+  ~HostViewEntry();
+
+  HostViewEntry(const HostViewEntry&) = delete;
+  HostViewEntry& operator=(const HostViewEntry&) = delete;
+
+ private:
+  jobject outer_;
+};
 /// `available("android", api)`.
 bool available(double api);
 
+// --- the app's Activities (platform/android_activity.cpp) ------------------------------
+
+/// `currentActivity()` from lucent:android: the Activity in front (created,
+/// started or resumed, and not destroyed), or null. Lucent holds Activities
+/// weakly; the reference returned is one, for the caller's use now.
+Opt<NativeRef> currentActivity();
+
+/// `startActivityForResult(intent, signal)`: starts `intent` from the
+/// Activity in front, through Lucent's request Activity, and resolves with
+/// an android.app.Instrumentation.ActivityResult. Rejects with
+/// ERR_NO_ACTIVITY without one; an aborted signal or the calling context's
+/// root disposed cancels it, and a later answer is dropped.
+Promise<NativeRef> startActivityForResult(const NativeRef& intent, Opt<AbortSignal> signal = {});
+
+/// `requestPermissions(permissions, signal)`: whether each was granted, in
+/// order. Requests run one at a time, as Android requires.
+Promise<Array<bool>> requestPermissions(const Array<String>& permissions, Opt<AbortSignal> signal = {});
+
+/// A lifecycle event's handler: the Activity, and the intent of a new intent.
+using ActivityHandler = Fn<void(NativeRef, Opt<NativeRef>)>;
+
+/// `onActivityEvent(event, handler)`: runs `handler` on the subscribing
+/// context after each such event of the app's Activities ("created",
+/// "started", "resumed", "paused", "stopped", "destroyed", "newIntent").
+/// Returns the function that unsubscribes.
+Fn<void()> onActivityEvent(const String& event, ActivityHandler handler);
+
 }  // namespace lucent::jni