@lucent-lang/lucent 0.0.4 → 0.1.1

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

@@ -5,27 +5,40 @@
 #import <objc/runtime.h>
 #import <Foundation/Foundation.h>
 
+#include <functional>
+#include <initializer_list>
+#include <memory>
 #include <variant>
 
 #include "../array.h"
+#include "../bigint.h"
 #include "../bytes.h"
 #include "../date.h"
 #include "../jsstring.h"
 #include "../map.h"
 #include "../native.h"
+#include "../report.h"
+
+// Lucent code checks the OS before using an API newer than the deployment
+// target (LUCENT3007), with available(), which Clang does not see as a check:
+// the glue that includes this header uses them unwarned.
+#pragma clang diagnostic ignored "-Wunguarded-availability"
+#pragma clang diagnostic ignored "-Wunguarded-availability-new"
 
 namespace lucent::objc {
 
-void releaseOnMain(void* retained);
+inline void releaseObject(void* retained) { CFRelease(retained); }
 
-/// A Lucent reference to `obj` (retained). Throws TypeError for nil.
+/// A Lucent reference to `obj` (retained), released on the main thread:
+/// UIKit objects must be deallocated there, and the last Lucent reference
+/// can go on any thread. Throws TypeError for nil.
 inline NativeRef wrap(id obj, const char* what) {
   if (!obj) throw Exception(makeError(String::fromLatin1("TypeError"), String::fromUtf8(std::string(what) + " returned nil")));
-  return NativeRef((__bridge_retained void*)obj, releaseOnMain, nullptr);
+  return NativeRef((__bridge_retained void*)obj, releaseObject, nullptr, &ExecutionContext::main());
 }
 inline Opt<NativeRef> wrapOpt(id obj) {
   if (!obj) return Opt<NativeRef>(null);
-  return NativeRef((__bridge_retained void*)obj, releaseOnMain, nullptr);
+  return wrap(obj, "");
 }
 inline id unwrap(const NativeRef& r) { return (__bridge id)r.get(); }
 inline id unwrap(const Opt<NativeRef>& r) { return r.has() ? (__bridge id)r.get().get() : nil; }
@@ -137,10 +150,14 @@ Opt<Dict<V>> fromNSDictionaryOpt(NSDictionary* d, F fromObject) {
   return d ? Opt<Dict<V>>(fromNSDictionary<V>(d, fromObject, "")) : Opt<Dict<V>>(null);
 }
 
-/// Applies `f` to a value that may be absent; absent gives a null pointer.
+/// Applies `f` to a value that may be absent; absent gives a null pointer
+/// (of f's result type: a nil object, block or CoreFoundation reference).
 template <class T, class F>
 auto ifPresent(const Opt<T>& v, F f) -> decltype(f(v.get())) {
-  return v.has() ? f(v.get()) : nullptr;
+  using R = decltype(f(v.get()));
+  if (v.has()) return f(v.get());
+
+  return R(nullptr);
 }
 template <class T, class F>
   requires(!IsOpt<T>::value)
@@ -197,15 +214,93 @@ inline Opt<Date> asDate(const Opt<NativeRef>& o) {
   return [x isKindOfClass:[NSDate class]] ? Opt<Date>(fromNSDate(x, "")) : Opt<Date>(null);
 }
 
+// --- C structs, as Swift shims pass them: their bytes ----------------------------------
+
+template <class S>
+NSData* structBytes(const S& s) {
+  return [NSData dataWithBytes:&s length:sizeof(S)];
+}
+template <class S>
+S structFromBytes(id data) {
+  S s{};
+  [(NSData*)data getBytes:&s length:sizeof(S)];
+  return s;
+}
+
+// --- Swift enums with payloads ---------------------------------------------------------
+
+/// A case of a Swift enum with payloads, as the shims pass it: {"kind": case, field: payload…}.
+inline id swiftCase(NSString* kind, std::initializer_list<std::pair<const char*, id>> payload) {
+  NSMutableDictionary* d = [NSMutableDictionary dictionaryWithObject:kind forKey:@"kind"];
+  // An absent optional payload is left out.
+  for (const auto& [field, value] : payload)
+    if (value) d[@(field)] = value;
+  return d;
+}
+inline id swiftCase(const char* kind, std::initializer_list<std::pair<const char*, id>> payload) {
+  return swiftCase(@(kind), payload);
+}
+/// Cases whose payloads have the same fields share an object type in Lucent: its kind says which.
+inline id swiftCase(const String& kind, std::initializer_list<std::pair<const char*, id>> payload) {
+  return swiftCase(toNSString(kind), payload);
+}
+inline bool isSwiftCase(id c, const char* kind) {
+  return [((NSDictionary*)c)[@"kind"] isEqualToString:@(kind)];
+}
+/// A payload of a case, nil for an absent optional one (NSNull from Swift).
+inline id swiftPayload(id c, const char* field) {
+  id v = ((NSDictionary*)c)[@(field)];
+  return v == [NSNull null] ? nil : v;
+}
+[[noreturn]] inline void unknownSwiftCase(id c, const char* type) {
+  throw Exception(makeError(String::fromLatin1("TypeError"),
+                            String::fromUtf8(std::string(type) + " has no case " + [[((NSDictionary*)c)[@"kind"] description] UTF8String])));
+}
+
 // --- errors ----------------------------------------------------------------------------
 
-/// An NSError as a Lucent error: code "<domain>:<code>".
+/// The domain of the NSErrors Lucent errors become (toNSError).
+inline NSString* const lucentErrorDomain = @"Lucent";
+
+/// An NSError as a Lucent error: code "<domain>:<code>". One toNSError made
+/// is the Lucent error it was made from again: its name, message and code.
 inline Error fromNSError(NSError* e, const char* what) {
   if (!e) throw Exception(makeError(String::fromLatin1("TypeError"), String::fromUtf8(std::string(what) + " got no error")));
+
+  NSString* name = [e.domain isEqualToString:lucentErrorDomain] ? e.userInfo[@"LucentErrorName"] : nil;
+  if (name) {
+    Error err = makeError(fromNSString(name, ""), fromNSString(e.localizedDescription ?: @"", ""));
+    if (NSString* code = e.userInfo[@"LucentErrorCode"]) err->code = fromNSString(code, "");
+    return err;
+  }
+
   Error err = makeError(String::fromLatin1("Error"), fromNSString(e.localizedDescription ?: @"", ""));
   err->code = fromNSString([NSString stringWithFormat:@"%@:%ld", e.domain, (long)e.code], "");
   return err;
 }
+
+/// A Lucent error as an NSError, for Swift to throw where Lucent code
+/// implements a throwing requirement: its message as the description, its
+/// name and code kept for the way back (fromNSError).
+inline NSError* toNSError(const Error& e) {
+  NSMutableDictionary* info = [NSMutableDictionary dictionary];
+  info[NSLocalizedDescriptionKey] = toNSString(e->message);
+  info[@"LucentErrorName"] = toNSString(e->name);
+  if (e->code.has()) info[@"LucentErrorCode"] = toNSString(e->code.get());
+
+  return [NSError errorWithDomain:lucentErrorDomain code:0 userInfo:info];
+}
+
+/// In a catch: what was thrown, as the NSError a Swift requirement's error
+/// out-parameter takes (retained).
+inline void setError(void** out) {
+  *out = (__bridge_retained void*)toNSError(currentError(std::current_exception()));
+}
+
+/// Reports an error Swift has no way to receive (a requirement that does not throw).
+inline void reportError(const Error& e, const char* where) {
+  reportUncaught(std::make_exception_ptr(Exception(e)), where);
+}
 inline Opt<Error> fromNSErrorOpt(NSError* e) { return e ? Opt<Error>(fromNSError(e, "")) : Opt<Error>(null); }
 
 /// A method's NSError** result as a thrown Lucent error.
@@ -216,8 +311,10 @@ inline void throwIfError(NSError* e) {
 // --- blocks ----------------------------------------------------------------------------
 
 /// One Objective-C object per `key` (a Lucent object) while the object is
-/// alive: `make` creates it. Callers hold the Lucent lock.
-inline id cachedObject(const void* key, id (^make)(void)) {
+/// alive: `make` creates it. Callers hold the Lucent lock. Each `Table`
+/// has its own: a Lucent object's Objective-C and Swift delegates differ.
+template <int Table = 0>
+id cachedObject(const void* key, id (^make)(void)) {
   static NSMapTable* objects = [NSMapTable strongToWeakObjectsMapTable];
   NSValue* k = [NSValue valueWithPointer:key];
   id o = [objects objectForKey:k];
@@ -228,6 +325,43 @@ inline id cachedObject(const void* key, id (^make)(void)) {
   return o;
 }
 
+// --- Lucent classes extending Objective-C classes ------------------------------------
+//
+// A generated subclass of the base stands for each instance: it holds the
+// Lucent object, and Lucent references to the object hold it (nativeOwned).
+
+/// The native object of each Lucent object extending an Objective-C class,
+/// by the Lucent object's address; held weakly, as the native one holds it.
+inline NSMapTable* subclassObjects() {
+  static NSMapTable* objects = [NSMapTable strongToWeakObjectsMapTable];
+  return objects;
+}
+
+inline void adoptSubclassObject(const void* lucent, id object) {
+  [subclassObjects() setObject:object forKey:[NSValue valueWithPointer:lucent]];
+}
+
+inline id subclassObject(const void* lucent) {
+  return [subclassObjects() objectForKey:[NSValue valueWithPointer:lucent]];
+}
+
+/// The native object `lucent` is, for the members it inherits.
+inline NativeRef nativeOfSubclass(const void* lucent, const char* what) {
+  id o = subclassObject(lucent);
+  if (!o) throw Exception(makeError(String::fromLatin1("TypeError"), String::fromUtf8(std::string(what) + ": its native object is gone")));
+  return wrap(o, what);
+}
+
+/// A reference to `o` that holds its native object, which holds `o`: an
+/// aliasing reference, so the two go together. Before the native object is
+/// made (in the constructor, before super(…)), the Lucent object's own.
+template <class T>
+Ref<T> nativeOwned(T* o) {
+  id x = subclassObject(o);
+  if (!x) return std::static_pointer_cast<T>(static_cast<Object*>(o)->shared_from_this());
+  return Ref<T>(std::make_shared<NativeRef>(wrap(x, "")), o);
+}
+
 /// A C++ callable as a heap block of type `Block` (the platform may keep it).
 template <class Block, class F>
 Block block(F f) {
@@ -237,16 +371,25 @@ Block block(F f) {
 
 // --- out-parameters --------------------------------------------------------------------
 
-/// `new Out()` from lucent:ios: a CFTypeRef a C function writes into.
+/// `new Out()` from lucent:ios: what a method writes through a pointer, and
+/// (for inout pointers) reads first. An object as a CFTypeRef; a number, an
+/// enum or a BOOL as a number; a 64-bit integer as a bigint; a C struct as
+/// the Lucent object it converts to.
 struct OutSlot {
   CFTypeRef value = nullptr;
   bool owned = false;
+  Opt<double> number = Opt<double>(null);
+  Opt<BigInt> integer = Opt<BigInt>(null);
+  std::shared_ptr<Object> record;
   ~OutSlot() {
     if (value && owned) CFRelease(value);
   }
 };
+inline OutSlot* slotOf(const NativeRef& r) { return static_cast<OutSlot*>(r.get()); }
+inline OutSlot* slotOf(const Opt<NativeRef>& r) { return r.has() ? slotOf(r.get()) : nullptr; }
+/// Released on the main thread, like the object it may hold.
 inline NativeRef makeOut() {
-  return NativeRef(new OutSlot(), [](void* p) { delete static_cast<OutSlot*>(p); }, nullptr);
+  return NativeRef(new OutSlot(), [](void* p) { delete static_cast<OutSlot*>(p); }, nullptr, &ExecutionContext::main());
 }
 /// The slot for a call; `owned` per CoreFoundation's Create/Copy rule.
 inline CFTypeRef* outSlot(const NativeRef& r, bool owned) {
@@ -257,33 +400,190 @@ inline CFTypeRef* outSlot(const NativeRef& r, bool owned) {
   return &s->value;
 }
 inline CFTypeRef* outSlot(const Opt<NativeRef>& r, bool owned) { return r.has() ? outSlot(r.get(), owned) : nullptr; }
-inline Opt<NativeRef> outValue(const NativeRef& r) { return wrapOpt((__bridge id) static_cast<OutSlot*>(r.get())->value); }
+inline Opt<NativeRef> outValue(const NativeRef& r) { return wrapOpt((__bridge id) slotOf(r)->value); }
 
 /**
- * An NSError** argument writing into an Out<Error>: the method writes an
- * autoreleased error, which the slot retains when the call's full
- * expression ends (before any autorelease pool drains).
+ * An object pointer argument (`NSDate **`, `NSError **`) writing into an
+ * Out: the method writes an autoreleased object, which the slot retains
+ * when the call's full expression ends (before any autorelease pool
+ * drains). `T` is the pointee, `NSDate*` or `id`.
  */
-class ErrorOut {
+template <class T>
+class ObjectOut {
  public:
-  explicit ErrorOut(const NativeRef& out) : slot_(static_cast<OutSlot*>(out.get())) {}
-  explicit ErrorOut(const Opt<NativeRef>& out) : slot_(out.has() ? static_cast<OutSlot*>(out.get().get()) : nullptr) {}
-  ~ErrorOut() {
+  explicit ObjectOut(const NativeRef& out) : ObjectOut(slotOf(out)) {}
+  explicit ObjectOut(const Opt<NativeRef>& out) : ObjectOut(slotOf(out)) {}
+  ~ObjectOut() {
     if (!slot_) return;
     if (slot_->value && slot_->owned) CFRelease(slot_->value);
-    slot_->value = error_ ? CFBridgingRetain(error_) : nullptr;
+    slot_->value = object_ ? CFBridgingRetain(object_) : nullptr;
     slot_->owned = true;
   }
-  ErrorOut(const ErrorOut&) = delete;
-  ErrorOut& operator=(const ErrorOut&) = delete;
-  NSError* __autoreleasing* ptr() { return slot_ ? reinterpret_cast<NSError* __autoreleasing*>(&error_) : nullptr; }
+  ObjectOut(const ObjectOut&) = delete;
+  ObjectOut& operator=(const ObjectOut&) = delete;
+  T __autoreleasing* ptr() { return slot_ ? reinterpret_cast<T __autoreleasing*>(&object_) : nullptr; }
+
+ private:
+  explicit ObjectOut(OutSlot* slot) : slot_(slot), object_(slot ? (__bridge T)slot->value : nil) {}
+  OutSlot* slot_;
+  T __unsafe_unretained object_;
+};
+using ErrorOut = ObjectOut<NSError*>;
+
+/// A 64-bit integer (NSInteger, int64_t, NSUInteger): a bigint in Lucent.
+template <class T>
+constexpr bool kWideInteger = std::is_integral_v<T> && sizeof(T) == 8;
+
+/// A number, enum or BOOL pointer argument (`CGFloat *`): the slot's number
+/// goes in, and the method's comes out; a 64-bit integer's (`NSInteger *`)
+/// as a bigint, exactly.
+template <class T>
+class NumberOut {
+ public:
+  explicit NumberOut(const NativeRef& out) : NumberOut(slotOf(out)) {}
+  explicit NumberOut(const Opt<NativeRef>& out) : NumberOut(slotOf(out)) {}
+
+  ~NumberOut() {
+    if (!slot_) return;
+
+    if constexpr (kWideInteger<T>) slot_->integer = Opt<BigInt>(BigInt(value_));
+    else slot_->number = Opt<double>(static_cast<double>(value_));
+  }
+
+  NumberOut(const NumberOut&) = delete;
+  NumberOut& operator=(const NumberOut&) = delete;
+  T* ptr() { return slot_ ? &value_ : nullptr; }
+
+ private:
+  static T in(OutSlot* slot) {
+    if constexpr (kWideInteger<T>) {
+      return slot && slot->integer.has() ? toNativeInteger<T>(slot->integer.get(), "an Out's value") : T{};
+    } else {
+      return slot && slot->number.has() ? static_cast<T>(slot->number.get()) : T{};
+    }
+  }
+
+  explicit NumberOut(OutSlot* slot) : slot_(slot), value_(in(slot)) {}
+
+  OutSlot* slot_;
+  T value_;
+};
+
+/// A C struct pointer argument (`NSRange *`), converted to and from the Lucent object the slot holds.
+template <class T>
+class StructOut {
+ public:
+  using ToC = std::function<T(const std::shared_ptr<Object>&)>;
+  using FromC = std::function<std::shared_ptr<Object>(const T&)>;
+  StructOut(const NativeRef& out, ToC toC, FromC fromC) : StructOut(slotOf(out), toC, std::move(fromC)) {}
+  StructOut(const Opt<NativeRef>& out, ToC toC, FromC fromC) : StructOut(slotOf(out), toC, std::move(fromC)) {}
+  ~StructOut() {
+    if (slot_) slot_->record = fromC_(value_);
+  }
+  StructOut(const StructOut&) = delete;
+  StructOut& operator=(const StructOut&) = delete;
+  T* ptr() { return slot_ ? &value_ : nullptr; }
 
  private:
+  StructOut(OutSlot* slot, const ToC& toC, FromC fromC)
+      : slot_(slot), value_(slot && slot->record ? toC(slot->record) : T{}), fromC_(std::move(fromC)) {}
   OutSlot* slot_;
-  NSError* __unsafe_unretained error_ = nil;
+  T value_;
+  FromC fromC_;
 };
 
-inline Opt<Error> outError(const NativeRef& r) { return fromNSErrorOpt((__bridge NSError*) static_cast<OutSlot*>(r.get())->value); }
+inline Opt<Error> outError(const NativeRef& r) { return fromNSErrorOpt((__bridge NSError*) slotOf(r)->value); }
+inline Opt<double> outNumber(const NativeRef& r) { return slotOf(r)->number; }
+inline Opt<BigInt> outBigInt(const NativeRef& r) { return slotOf(r)->integer; }
+inline Opt<bool> outBool(const NativeRef& r) {
+  const Opt<double>& n = slotOf(r)->number;
+  return n.has() ? Opt<bool>(n.get() != 0) : Opt<bool>(null);
+}
+/// The struct a method wrote, as the Lucent object type `S` it converts to.
+template <class S>
+Opt<Ref<S>> outRecord(const NativeRef& r) {
+  const auto& o = slotOf(r)->record;
+  return o ? Opt<Ref<S>>(std::static_pointer_cast<S>(o)) : Opt<Ref<S>>(null);
+}
+
+inline void setOutObject(const NativeRef& r, id v) {
+  OutSlot* s = slotOf(r);
+  if (s->value && s->owned) CFRelease(s->value);
+  s->value = v ? CFBridgingRetain(v) : nullptr;
+  s->owned = true;
+}
+/// A pointer a block receives (`BOOL *stop`) as an Out, holding what it points to.
+template <class T>
+NativeRef outOf(T* p) {
+  NativeRef out = makeOut();
+  if (!p) return out;
+
+  if constexpr (kWideInteger<T>) slotOf(out)->integer = Opt<BigInt>(BigInt(*p));
+  else slotOf(out)->number = Opt<double>(static_cast<double>(*p));
+  return out;
+}
+/// What the Lucent function set, written back through the block's pointer.
+template <class T>
+void writeOut(const NativeRef& out, T* p) {
+  if (!p) return;
+
+  if constexpr (kWideInteger<T>) {
+    const Opt<BigInt>& n = slotOf(out)->integer;
+    if (n.has()) *p = toNativeInteger<T>(n.get(), "an Out's value");
+  } else {
+    const Opt<double>& n = slotOf(out)->number;
+    if (n.has()) *p = static_cast<T>(n.get());
+  }
+}
+
+// `out.value = x`: what an inout pointer passes in. Each gives the value assigned.
+inline double setOut(const NativeRef& r, double v) {
+  slotOf(r)->number = Opt<double>(v);
+  return v;
+}
+inline BigInt setOut(const NativeRef& r, BigInt v) {
+  slotOf(r)->integer = Opt<BigInt>(v);
+  return v;
+}
+inline bool setOut(const NativeRef& r, bool v) {
+  slotOf(r)->number = Opt<double>(v ? 1.0 : 0.0);
+  return v;
+}
+template <class S>
+Ref<S> setOut(const NativeRef& r, Ref<S> v) {
+  slotOf(r)->record = std::static_pointer_cast<Object>(v);
+  return v;
+}
+inline NativeRef setOut(const NativeRef& r, NativeRef v) {
+  setOutObject(r, unwrap(v));
+  return v;
+}
+inline String setOut(const NativeRef& r, String v) {
+  setOutObject(r, toNSString(v));
+  return v;
+}
+inline Date setOut(const NativeRef& r, Date v) {
+  setOutObject(r, toNSDate(v));
+  return v;
+}
+inline Bytes setOut(const NativeRef& r, Bytes v) {
+  setOutObject(r, toNSData(v));
+  return v;
+}
+template <class T>
+Opt<T> setOut(const NativeRef& r, Opt<T> v) {
+  if (v.has()) {
+    setOut(r, v.get());
+  } else {
+    OutSlot* s = slotOf(r);
+    if (s->value && s->owned) CFRelease(s->value);
+    s->value = nullptr;
+    s->number = Opt<double>(null);
+    s->integer = Opt<BigInt>(null);
+    s->record.reset();
+  }
+  return v;
+}
 
 /// `mainQueue()` from lucent:ios: the main dispatch queue (an OS object).
 inline NativeRef mainQueue() { return wrap(dispatch_get_main_queue(), "mainQueue"); }

package/runtime/cpp/lucent/platform/ios.mm

@@ -1,4 +1,4 @@
-// Lucent runtime — iOS: the main queue, and releasing objects there.
+// Lucent runtime — iOS: the main queue.
 #include "ios.h"
 
 #import <dispatch/dispatch.h>
@@ -15,17 +15,4 @@ void postToMain(std::function<void()> job) {
 
 bool onMainThread() { return [NSThread isMainThread]; }
 
-namespace objc {
-
-// UIKit objects must be deallocated on the main thread; the last Lucent
-// reference can go on any thread.
-void releaseOnMain(void* retained) {
-  if ([NSThread isMainThread]) {
-    CFRelease(retained);
-    return;
-  }
-  dispatch_async_f(dispatch_get_main_queue(), retained, [](void* p) { CFRelease(p); });
-}
-
-}  // namespace objc
 }  // namespace lucent

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

@@ -0,0 +1,192 @@
+// Lucent runtime — UIKit glue: the scene to present from, presentations,
+// and lifecycle subscriptions, for *.ios.lucent.ts units and native
+// wrappers (Objective-C++ with ARC, iOS only).
+//
+// Nothing here keeps a window or view controller: the presentation context
+// is looked up in UIKit's scenes each time it is asked for, and scenes are
+// named by SceneIds (lucent/lifecycle.h). UIKit's notifications feed the
+// shared Lifecycle from the moment the binary loads; no app or scene
+// delegate is replaced, so the app's own, and other modules', keep working.
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+#include <functional>
+#include <memory>
+#include <optional>
+#include <type_traits>
+
+#include "../lifecycle.h"
+#include "../presentation.h"
+#include "ios.h"
+
+namespace lucent::objc {
+
+/// Where to present from, as UIKit has it now.
+struct PresentationContext {
+  SceneId id = 0;
+  UIWindowScene* scene = nil;
+  UIWindow* window = nil;
+  /// The key window's root view controller, or the view controller it
+  /// presents (and so on), minus one being dismissed.
+  UIViewController* top = nil;
+};
+
+/**
+ * The presentation context of the scene the person is using: the most
+ * recently activated window scene in the foreground (active before
+ * inactive), its key window and top view controller. None while every
+ * scene is in the background, or it has no window with a root view
+ * controller. On the main thread only (InvalidStateError elsewhere). Keep
+ * none of it past the current turn of the main thread: ask again.
+ */
+std::optional<PresentationContext> presentationContext();
+
+/// The id of a connected scene (given when UIKit connects it, or when it
+/// is first seen); 0 for nil. Main thread.
+SceneId sceneIdOf(UIScene* scene);
+
+/// The connected scene with that id, else nil. Main thread.
+UIScene* sceneOf(SceneId id);
+
+namespace detail {
+
+/**
+ * Presents `viewController` from the top view controller of `scene`'s key
+ * window, and returns what dismisses it: at once if it is shown, else once
+ * UIKit has shown it (some view controllers appear later than the call).
+ * `dismissed` runs once if, before that, the person dismisses it (a sheet
+ * swiped down) or it is released. Throws InvalidStateError if it is
+ * already shown, another presentation is under way, or UIKit throws.
+ * Main thread.
+ */
+std::function<void()> show(SceneId scene, UIViewController* viewController, bool animated, std::function<void()> dismissed);
+
+/// What cancels a presentation the person dismissed: an AbortError.
+Error dismissedError();
+
+/// The root scope of the calling context: what Lucent code's presentations
+/// and subscriptions belong to.
+std::shared_ptr<Scope> callerScope();
+
+}  // namespace detail
+
+/**
+ * For native wrappers: presents, on the main thread, the view controller
+ * `build` returns, from the presentation context now, as an operation under
+ * `scope` (lucent/presentation.h: it settles once, and whatever settles it
+ * dismisses the view controller). `build` runs here, before anything is
+ * shown, and wires the view controller's own outcome (a delegate, a
+ * completion handler) to the operation; it may settle it at once, and then
+ * nothing is shown. The person dismissing it, or its release, cancels the
+ * operation with an AbortError; so does its scene disconnecting.
+ */
+template <class T>
+std::shared_ptr<Operation<T>> presentOperation(const std::shared_ptr<Scope>& scope, Opt<AbortSignal> signal,
+                                               const std::function<UIViewController*(const std::shared_ptr<Operation<T>>&)>& build,
+                                               bool animated = true) {
+  std::optional<PresentationContext> context = presentationContext();
+  SceneId scene = context ? context->id : 0;
+
+  return presentIn<T>(Lifecycle::shared(), scene, scope, signal, [&](const std::shared_ptr<Operation<T>>& op) -> std::function<void()> {
+    UIViewController* viewController = build(op);
+    if (op->state() != OperationState::Pending) return {};
+    if (!viewController) returnedNil("present's view controller");
+
+    std::weak_ptr<Operation<T>> weak = op;
+    return detail::show(scene, viewController, animated, [weak] {
+      if (auto op = weak.lock()) op->cancel(detail::dismissedError());
+    });
+  });
+}
+
+namespace detail {
+template <class T>
+struct ResolveOf {
+  using type = Fn<void(T)>;
+};
+template <>
+struct ResolveOf<void> {
+  using type = Fn<void()>;
+};
+}  // namespace detail
+
+/// What `present` gives its function to settle with a value.
+template <class T>
+using Resolve = typename detail::ResolveOf<T>::type;
+
+/**
+ * `present(build, signal)` from lucent:ios: on the main thread, holding the
+ * Lucent lock (build is module code), presents the view controller `build`
+ * returns (presentOperation) under the calling context's root scope, and
+ * settles the promise, which belongs to the calling context, with the
+ * outcome.
+ */
+template <class T>
+Promise<T> present(Fn<NativeRef(Resolve<T>, Fn<void(Error)>)> build, Opt<AbortSignal> signal = {}) {
+  Promise<T> promise;
+  std::shared_ptr<Scope> scope = detail::callerScope();
+
+  postToMain([promise, build = std::move(build), signal, scope]() mutable {
+    LucentScope lucent;
+
+    std::shared_ptr<Operation<T>> op;
+    try {
+      op = presentOperation<T>(scope, signal, [&](const std::shared_ptr<Operation<T>>& op) -> UIViewController* {
+        std::weak_ptr<Operation<T>> weak = op;
+
+        Resolve<T> resolve;
+        if constexpr (std::is_void_v<T>) {
+          resolve = Resolve<T>([weak] {
+            if (auto op = weak.lock()) op->succeed();
+          });
+        } else {
+          resolve = Resolve<T>([weak](T value) {
+            if (auto op = weak.lock()) op->succeed(std::move(value));
+          });
+        }
+
+        Fn<void(Error)> reject([weak](Error error) {
+          if (auto op = weak.lock()) op->fail(std::move(error));
+        });
+
+        id made = unwrap(build(resolve, reject));
+        if (made && ![made isKindOfClass:[UIViewController class]])
+          throw Exception(makeError(String::fromLatin1("TypeError"), String::fromLatin1("present's function must return a UIViewController")));
+
+        return (UIViewController*)made;
+      });
+    } catch (...) {
+      promise.reject(currentError(std::current_exception()));
+      return;
+    }
+
+    op->onSettled([promise](const typename Operation<T>::Outcome& outcome) {
+      if (outcome.state != OperationState::Succeeded) {
+        promise.reject(outcome.error);
+      } else if constexpr (std::is_void_v<T>) {
+        promise.resolve(undefined);
+      } else {
+        promise.resolve(*outcome.value);
+      }
+    });
+  });
+
+  return promise;
+}
+
+/**
+ * `onAppEvent(event, listener, signal)` from lucent:ios: calls `listener`
+ * on each of UIApplication's `event` notifications ("didBecomeActive"…),
+ * on the main thread holding the Lucent lock, until the returned function
+ * is called or `signal` aborts. What it throws is reported; UIKit and the
+ * other observers go on.
+ */
+Fn<void()> onAppEvent(const String& event, Fn<void()> listener, Opt<AbortSignal> signal = {});
+
+/// `onSceneEvent(event, listener, signal)` from lucent:ios: as onAppEvent,
+/// for UIScene's notifications ("willConnect"…); `listener` gets the
+/// scene's session's persistent identifier.
+Fn<void()> onSceneEvent(const String& event, Fn<void(String)> listener, Opt<AbortSignal> signal = {});
+
+}  // namespace lucent::objc