@lucent-lang/lucent 0.0.4 → 0.1.0

package/runtime/js/index.d.ts

@@ -1,7 +1,17 @@
-/** Returns the exports object of a compiled Lucent module. */
+/** What lucent build compiled: the runtime ABI, each target's program and each module's API. */
+export interface BuildIdentity {
+  runtimeAbi: number;
+  programs: Record<string, string>;
+  apis: Record<string, Record<string, string>>;
+}
+/**
+ * Returns the exports object of a compiled Lucent module, after checking
+ * the app's native code against `expected`.
+ */
 export declare function loadModule(
   name: string,
   registry: () => { get(name: string): unknown },
+  expected?: BuildIdentity,
 ): Record<string, unknown>;
 /** Wraps a native class factory in a constructor usable with `new`. */
 export declare function lucentClass<T>(factory: T): T;

package/runtime/js/index.js

@@ -9,12 +9,10 @@
 let native;
 
 function getNative(registry) {
+  // Test hosts install modules directly, and may install new ones.
+  if (typeof globalThis.__lucentModules === "object" && globalThis.__lucentModules)
+    return globalThis.__lucentModules;
   if (native) return native;
-  // Test hosts install modules directly.
-  if (typeof globalThis.__lucentModules === "object" && globalThis.__lucentModules) {
-    native = globalThis.__lucentModules;
-    return native;
-  }
   native = registry().get("Lucent");
   if (!native) {
     throw new Error(
@@ -25,13 +23,91 @@ function getNative(registry) {
   return native;
 }
 
+const REBUILD =
+  "Recompile the app's native code: run `lucent build`, then build and install the app again " +
+  "(compile-native). A JavaScript update (a reload, or over the air) cannot replace native code.";
+const RELOAD = "Reload JavaScript built for the installed app (reload-js).";
+
+/** An error that names what to do: `action` is one of lucent build's pending action kinds. */
+function mismatch(problem, action) {
+  const e = new Error(`Lucent: ${problem} ${action === "reload-js" ? RELOAD : REBUILD}`);
+  e.code = "LUCENT_NATIVE_MISMATCH";
+  e.action = action;
+  return e;
+}
+
+/**
+ * What the native code and this JavaScript's build share, once per host and
+ * build: undefined, or the error to throw. A different program with the
+ * same APIs runs, with a warning: calls are safe, but the implementation is
+ * not the one this JavaScript was built with.
+ */
+const programs = new Map();
+
+function checkProgram(actual, expected) {
+  const key = `${actual.host}\n${expected.runtimeAbi}\n${expected.programs[actual.target]}`;
+  if (programs.has(key)) return programs.get(key);
+
+  let problem;
+  if (actual.runtimeAbi !== expected.runtimeAbi) {
+    problem = mismatch(
+      `the app's native code has Lucent runtime ABI ${actual.runtimeAbi}, and this JavaScript needs ${expected.runtimeAbi}.`,
+      actual.runtimeAbi > expected.runtimeAbi ? "reload-js" : "compile-native",
+    );
+  } else if (!expected.programs[actual.target]) {
+    problem = mismatch(
+      `this JavaScript was built without the ${actual.target} native code the app runs.`,
+      "compile-native",
+    );
+  } else if (actual.program !== expected.programs[actual.target]) {
+    console.warn(
+      `Lucent: the app's native code (${actual.target} program ${actual.program}) was not built from ` +
+        `the sources this JavaScript was (program ${expected.programs[actual.target]}): its modules have ` +
+        `the same APIs, but the installed implementation runs. ${REBUILD} If the app was installed ` +
+        `after this JavaScript was built, reload JavaScript instead (reload-js).`,
+    );
+  }
+
+  programs.set(key, problem);
+  return problem;
+}
+
+/** Throws unless module `name` of the native code is what this JavaScript was built against. */
+function check(n, name, expected) {
+  const actual = n.__lucentIdentity;
+  if (!actual)
+    throw mismatch(
+      "the app's native code was built before Lucent gave it a build identity, so it cannot be checked against this JavaScript.",
+      "compile-native",
+    );
+
+  const problem = checkProgram(actual, expected);
+  if (problem) throw problem;
+
+  const want = expected.apis[actual.target] && expected.apis[actual.target][name];
+  const have = actual.modules[name];
+  if (have === undefined)
+    throw mismatch(`module "${name}" is not in the app's native code.`, "compile-native");
+  if (have !== want)
+    throw mismatch(
+      `module "${name}" of the app's native code has other exports or signatures (API ${have}) ` +
+        `than this JavaScript was built for (API ${want}).`,
+      "compile-native",
+    );
+}
+
 /**
- * The exports of a compiled Lucent module.
+ * The exports of a compiled Lucent module, after checking that the app's
+ * native code was built as this JavaScript expects.
  * @param {string} name module name (the file name without .lucent.ts)
  * @param {() => { get(name: string): any }} registry returns React Native's TurboModuleRegistry
+ * @param {{ runtimeAbi: number, programs: Record<string, string>, apis: Record<string, Record<string, string>> }} [expected]
+ *   the build identity lucent build wrote next to the proxies (none from older proxies: nothing is checked)
  */
-function loadModule(name, registry) {
-  const m = getNative(registry)[name];
+function loadModule(name, registry, expected) {
+  const n = getNative(registry);
+  if (expected) check(n, name, expected);
+  const m = n[name];
   if (!m) {
     throw new Error(
       `Lucent: module "${name}" is not in the native build. Run \`lucent build\` and rebuild the app.`,

package/runtime/js/views.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How a value is encoded for its native view: 0, as it is; `n`, a nullable
+ * value, boxed; `a`, an array's elements; `o`, some of an object's fields.
+ */
+export type Shape =
+  | 0
+  | { n: Shape }
+  | { a: Shape }
+  | { o: readonly { name: string; shape: Shape }[] };
+
+/** A component's description, which the compiler generates into its module's proxy. */
+export interface ComponentConfig {
+  /** The registration name of its native view. */
+  name: string;
+  displayName: string;
+  /** Whether it takes React children, which its native view mounts in its slot. */
+  children?: boolean;
+  /** Its props, each under its transport key. */
+  props: readonly { name: string; key: string; shape: Shape }[];
+  /** Its events, by slot: the handler's key and the event's name. */
+  events: readonly { name: string; key: string; event: string }[];
+  /** Its ref's commands: whether each answers, and its parameters' shapes. */
+  commands: readonly { name: string; request: boolean; params: readonly Shape[] }[];
+}
+
+/** The React component rendering a Lucent component's native view. */
+export declare function lucentComponent(
+  config: ComponentConfig,
+  react: object,
+  reactNative: object,
+): (props: never) => unknown;
+
+/** Settles a command's request: rejected with `error` unless it is null, else resolved with `value`. */
+export declare function settleRequest(
+  id: number,
+  error: string | null | undefined,
+  value?: unknown,
+): void;

package/runtime/js/views.js

@@ -0,0 +1,226 @@
+"use strict";
+// Lucent components in React. A module's proxy describes each component it
+// exports (see lucentComponent), and this file makes the description a
+// React component rendering the native view React Native registers under
+// the component's registration name. `lucent build` copies it into the
+// native package (js/_lucent/views.js).
+// Like the loader, it requires nothing itself: the proxy passes the app's
+// React and React Native in.
+
+/**
+ * A value as its native view reads it. A nullable value travels boxed,
+ * `[value]` (`[null]` for null), because React sends a removed prop as
+ * null and turns undefined into null inside objects and argument lists:
+ * unboxed, a missing value and null would look the same. `shape` says
+ * where a value holds nullable ones: 0 (nowhere), `{ n }` (it is one),
+ * `{ a }` (its elements) or `{ o }` (some of its fields).
+ */
+function encode(value, shape) {
+  if (value === undefined || shape === 0) return value;
+
+  if ("n" in shape) return value === null ? [null] : [encode(value, shape.n)];
+
+  if ("a" in shape) return Array.isArray(value) ? value.map((v) => encode(v, shape.a)) : value;
+
+  if (value === null || typeof value !== "object") return value;
+
+  const out = { ...value };
+  for (const field of shape.o) {
+    if (Object.prototype.hasOwnProperty.call(out, field.name))
+      out[field.name] = encode(out[field.name], field.shape);
+  }
+  return out;
+}
+
+/** React Native's view configuration: the props and handlers under their keys, the events by slot. */
+function viewConfig(config) {
+  const validAttributes = {};
+  const directEventTypes = {};
+
+  for (const prop of config.props) validAttributes[prop.key] = true;
+
+  for (const event of config.events) {
+    validAttributes[event.key] = true;
+    directEventTypes[event.event] = { registrationName: event.key };
+  }
+
+  return { uiViewClassName: config.name, validAttributes, directEventTypes };
+}
+
+/** A prop React was given: not what every object inherits (toString, constructor). */
+const given = (props, name) =>
+  Object.prototype.hasOwnProperty.call(props, name) ? props[name] : undefined;
+
+/** The native view's props for React's `props` (but its ref). */
+function hostProps(config, props) {
+  const out = { style: props.style };
+
+  for (const prop of config.props) {
+    const value = given(props, prop.name);
+    if (value !== undefined) out[prop.key] = encode(value, prop.shape);
+  }
+
+  // React calls the handler of the latest commit, which calls that commit's
+  // callback with the arguments the native call passed, by position (React
+  // Native adds the view's tag to every payload as `target`).
+  for (const event of config.events) {
+    const callback = given(props, event.name);
+    if (typeof callback === "function") out[event.key] = (e) => callback(...e.nativeEvent.args);
+  }
+
+  return out;
+}
+
+// --- requests: commands that answer ---------------------------------------------------
+//
+// A request's promise settles once: with the command's result, with its
+// error (an Error of the native side's message), or with an AbortError
+// when its view unmounts first (the native side's work is not stopped:
+// its answer is dropped). A command sent while the view is not mounted
+// fails with an InvalidStateError: thrown by a void command, the
+// rejection of a request.
+
+/** An Error named `name`, as JavaScript names the state it reports. */
+function named(name, message) {
+  const e = new Error(message);
+  e.name = name;
+  return e;
+}
+
+const pending = new Map();
+let lastRequest = 0;
+let connected = false;
+
+/**
+ * Settles request `id`: rejects it with `error` (a message) unless that is
+ * null or undefined, else resolves it with `value`. A request that is no
+ * longer pending (its view unmounted) is ignored. The native host calls it
+ * on the JavaScript thread.
+ */
+function settleRequest(id, error, value) {
+  const request = pending.get(id);
+  if (!request) return;
+
+  pending.delete(id);
+  request.mount.delete(id);
+
+  if (error === null || error === undefined) request.resolve(value);
+  else request.reject(new Error(`Lucent: ${error}`));
+}
+
+/** Gives the native host settleRequest, once: requests are answered through its channel. */
+function connect(ReactNative) {
+  if (connected) return;
+
+  const host = ReactNative.TurboModuleRegistry.get("Lucent");
+  if (!host || typeof host.__lucentViewRequests !== "function") {
+    const e = new Error(
+      "Lucent: the app's native code cannot answer view commands. Recompile the app's native " +
+        "code: run `lucent build`, then build and install the app again (compile-native).",
+    );
+    e.code = "LUCENT_NATIVE_MISMATCH";
+    e.action = "compile-native";
+    throw e;
+  }
+
+  host.__lucentViewRequests(settleRequest);
+  connected = true;
+}
+
+/** The ref's methods: each sends its command to the mounted native view. */
+function commandsOf(config, host, mount, native, ReactNative) {
+  const out = {};
+
+  for (const command of config.commands) {
+    const where = `${config.displayName}.${command.name}()`;
+    const encoded = (args) =>
+      args.slice(0, command.params.length).map((a, i) => encode(a, command.params[i]));
+
+    const unmounted = () =>
+      named("InvalidStateError", `Lucent: ${where}: the view is not mounted.`);
+
+    out[command.name] = command.request
+      ? (...args) =>
+          new Promise((resolve, reject) => {
+            if (!host.current) throw unmounted();
+
+            connect(ReactNative);
+
+            // The answer comes in a later turn of the JavaScript thread, after the id is pending.
+            const id = ++lastRequest;
+            native[command.name](host.current, id, ...encoded(args));
+
+            pending.set(id, { resolve, reject, mount });
+            mount.add(id);
+          })
+      : (...args) => {
+          if (!host.current) throw unmounted();
+
+          native[command.name](host.current, ...encoded(args));
+        };
+  }
+
+  return out;
+}
+
+/** Rejects the requests a mount left unanswered: its unmount cancelled them. */
+function abandon(config, mount) {
+  for (const id of mount) {
+    const request = pending.get(id);
+    pending.delete(id);
+    if (request)
+      request.reject(
+        named("AbortError", `Lucent: ${config.displayName} unmounted before answering.`),
+      );
+  }
+  mount.clear();
+}
+
+/**
+ * The React component a proxy exports for a Lucent component.
+ * @param config the component's description, which the compiler generates
+ * @param React the app's React
+ * @param ReactNative the app's React Native
+ */
+function lucentComponent(config, React, ReactNative) {
+  const Host = ReactNative.NativeComponentRegistry.get(config.name, () => viewConfig(config));
+  const native = config.commands.length
+    ? ReactNative.codegenNativeCommands({ supportedCommands: config.commands.map((c) => c.name) })
+    : {};
+  // A component taking none gets children only from untyped code: its host has no slot for them.
+  let refused = false;
+  const childrenOf = (props) => {
+    if (config.children) return [props.children];
+
+    if (props.children !== undefined && !refused) {
+      refused = true;
+      console.error(
+        `Lucent: ${config.displayName} takes no children (its props declare no \`children: Children\`): they are not rendered.`,
+      );
+    }
+
+    return [];
+  };
+
+  function LucentComponent({ ref, ...props }) {
+    const host = React.useRef(null);
+    // The ids of this mount's unanswered requests.
+    const [requests] = React.useState(() => new Set());
+
+    React.useImperativeHandle(ref, () => commandsOf(config, host, requests, native, ReactNative), [
+      requests,
+    ]);
+    React.useEffect(() => () => abandon(config, requests), [requests]);
+
+    return React.createElement(
+      Host,
+      { ...hostProps(config, props), ref: host },
+      ...childrenOf(props),
+    );
+  }
+
+  LucentComponent.displayName = config.displayName;
+  return LucentComponent;
+}
+
+module.exports = { lucentComponent, settleRequest };

package/runtime/native/android/CMakeLists.txt

@@ -48,4 +48,7 @@ target_compile_options(lucentnative PRIVATE
   $<$<COMPILE_LANGUAGE:CXX>:-Wno-comma>
 )
 
-target_link_libraries(lucentnative jsi reactnative fbjni log lucentregexp)
+target_link_libraries(lucentnative jsi reactnative fbjni log android lucentregexp)
+
+# Lucent packages' C and C++ sources, when any (written by lucent build).
+include(${CMAKE_CURRENT_LIST_DIR}/packages.cmake OPTIONAL)

package/runtime/native/android/src/compose/java/dev/lucent/compose/CompositionRules.kt

@@ -0,0 +1,44 @@
+// Generated by Lucent. Do not edit.
+// The rules LucentComposition follows, in plain Kotlin: when a component's
+// composition starts and ends, and which owners it takes.
+package dev.lucent.compose
+
+/**
+ * When a component's composition starts and ends: at its view's first
+ * attach, and with its mount, once. A detach keeps it. A mount that ends
+ * before its view is ever attached (a view recycled before it showed)
+ * never composes.
+ */
+internal class CompositionTurns {
+  private enum class Turn {
+    NEW,
+    COMPOSED,
+    ENDED,
+  }
+
+  private var turn = Turn.NEW
+
+  /** The view is attached: whether its composition starts now. */
+  fun attached(): Boolean {
+    if (turn != Turn.NEW) return false
+
+    turn = Turn.COMPOSED
+    return true
+  }
+
+  /** The mount ended: whether a composition started, which ends now. */
+  fun ended(): Boolean {
+    val composed = turn == Turn.COMPOSED
+
+    turn = Turn.ENDED
+    return composed
+  }
+}
+
+/**
+ * The owner of kind `type` a composition takes: its view tree's, else the
+ * first of `contexts` (the context its view was made with, then each one
+ * that wraps: the host's Activity among them) that is one; null if none is.
+ */
+internal fun <T : Any> firstOwner(type: Class<T>, viewTree: T?, contexts: Sequence<Any>): T? =
+  viewTree ?: contexts.filterIsInstance(type).firstOrNull()

package/runtime/native/android/src/compose/java/dev/lucent/compose/LucentComposition.kt

@@ -0,0 +1,161 @@
+// Generated by Lucent. Do not edit.
+package dev.lucent.compose
+
+import android.content.Context
+import android.content.ContextWrapper
+import android.view.View
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.wrapContentSize
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.LocalSaveableStateRegistry
+import androidx.compose.runtime.saveable.SaveableStateRegistry
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.layout.onSizeChanged
+import androidx.compose.ui.platform.ComposeView
+import androidx.compose.ui.platform.ViewCompositionStrategy
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ViewModelStoreOwner
+import androidx.lifecycle.findViewTreeLifecycleOwner
+import androidx.lifecycle.findViewTreeViewModelStoreOwner
+import androidx.lifecycle.setViewTreeLifecycleOwner
+import androidx.lifecycle.setViewTreeViewModelStoreOwner
+import androidx.savedstate.SavedStateRegistryOwner
+import androidx.savedstate.findViewTreeSavedStateRegistryOwner
+import androidx.savedstate.setViewTreeSavedStateRegistryOwner
+
+/**
+ * A component's Compose content in the ComposeView its setup returns: the
+ * host of every body Lucent generates (`<registration>Host.create` gives
+ * it the body's composable). The C++ holder (lucent/platform/compose.h)
+ * makes it with the context of the view hosting the mount, the Activity's
+ * as React Native themes its views, and ends it with the mount.
+ *
+ * - The composition starts at the view's first attach (CompositionRules.kt),
+ *   with the owners of its view tree. A window whose tree lacks one (a
+ *   plain dialog's, an overlay's) gets the host Activity's, on its root.
+ * - A detach keeps it. The mount's end disposes it, and so does the
+ *   destruction of the view tree's lifecycle, for a host that ends a
+ *   window without dropping its views.
+ * - The content lays out at its own size. When that size changes, the view
+ *   asks for a layout, and the component's host measures it again.
+ * - rememberSaveable keeps a value as long as the mount: nothing is saved
+ *   for another mount, or restored from one.
+ * - Once the mount ends, the view keeps nothing of the body.
+ */
+class LucentComposition(context: Context, content: @Composable () -> Unit) :
+  View.OnAttachStateChangeListener {
+  private val composeView = ComposeView(context)
+
+  /**
+   * The view showing the content: the value of the setup's `compose()`.
+   * A View to JNI, which finds it by a descriptor a shrinker leaves alone.
+   */
+  val view: View
+    get() = composeView
+
+  /** The body, until the mount ends (see dispose). */
+  private var content: (@Composable () -> Unit)? = content
+
+  private val turns = CompositionTurns()
+
+  init {
+    composeView.addOnAttachStateChangeListener(this)
+  }
+
+  override fun onViewAttachedToWindow(v: View) {
+    if (!turns.attached()) return
+
+    composeView.removeOnAttachStateChangeListener(this)
+
+    // Before composing: the window's recomposer takes the lifecycle it finds from the root.
+    val contexts = generateSequence<Any>(composeView.context) { (it as? ContextWrapper)?.baseContext }
+
+    for (kind in OWNERS) kind.ensure(composeView, contexts)
+
+    composeView.setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
+    composeView.setContent { Hosted() }
+  }
+
+  override fun onViewDetachedFromWindow(v: View) = Unit
+
+  /**
+   * The mount ended: its composition ends, or never starts, and the view
+   * lets go of the body. A disposed composition leaves its layout nodes,
+   * whose modifiers hold the body's callbacks, and through them the
+   * holder's actions: the setup's functions, whose captures may hold this
+   * view by a JNI global reference, a cycle the garbage collector cannot
+   * see.
+   */
+  fun dispose() {
+    composeView.removeOnAttachStateChangeListener(this)
+
+    if (turns.ended()) composeView.disposeComposition()
+
+    composeView.removeAllViews()
+    content = null
+  }
+
+  @Composable
+  private fun Hosted() {
+    val saveable = remember { SaveableStateRegistry(null) { true } }
+
+    CompositionLocalProvider(LocalSaveableStateRegistry provides saveable) {
+      Box(
+        Modifier.wrapContentSize(Alignment.TopStart, unbounded = true).onSizeChanged {
+          composeView.requestLayout()
+        }
+      ) {
+        content?.invoke()
+      }
+    }
+  }
+}
+
+/** An owner Compose finds in its view tree, and whether it cannot compose without one. */
+private class OwnerKind<T : Any>(
+  private val type: Class<T>,
+  private val find: (View) -> T?,
+  private val give: (View, T) -> Unit,
+  private val required: Boolean,
+) {
+  /** Gives `view`'s window the first of `contexts` that is one if its tree has none. */
+  fun ensure(view: View, contexts: Sequence<Any>) {
+    val tree = find(view)
+    val owner = firstOwner(type, tree, contexts)
+
+    if (owner == null) {
+      check(!required) {
+        "Compose content needs a ${type.simpleName}: neither its window's view tree nor the " +
+          "Activity hosting it has one (host React Native in a ComponentActivity)"
+      }
+      return
+    }
+
+    if (owner !== tree) give(view.rootView, owner)
+  }
+}
+
+private val OWNERS =
+  listOf(
+    OwnerKind(
+      LifecycleOwner::class.java,
+      { it.findViewTreeLifecycleOwner() },
+      { v, o -> v.setViewTreeLifecycleOwner(o) },
+      required = true,
+    ),
+    OwnerKind(
+      SavedStateRegistryOwner::class.java,
+      { it.findViewTreeSavedStateRegistryOwner() },
+      { v, o -> v.setViewTreeSavedStateRegistryOwner(o) },
+      required = true,
+    ),
+    OwnerKind(
+      ViewModelStoreOwner::class.java,
+      { it.findViewTreeViewModelStoreOwner() },
+      { v, o -> v.setViewTreeViewModelStoreOwner(o) },
+      required = false,
+    ),
+  )