janela 0.11.0 → 0.13.0

package/runtime/ios.ts

@@ -42,6 +42,7 @@ declare function hostSchedule(id: number, ms: number): void;
 declare function hostSettle(pendingId: number, envelopeJson: string): void;
 declare function hostReadFile(jobId: number, path: string): void;
 declare function hostWriteFile(jobId: number, path: string, data: string): void;
+declare function hostOpenDialog(jobId: number, optionsJson: string): void;
 
 // One job table serves reads and writes; these sentinels say which callback of
 // the pair is the real one. Identity comparison is the whole trick, so they
@@ -68,9 +69,14 @@ function encode(value: unknown): string {
 // an answer. A library build still links no event loop (SC4005); that is why
 // the design routes through the shell rather than a limitation of iOS.
 //
-// What remains behind pending(): the file dialogs (iOS wants a document
-// picker, which is its own delegate lifecycle) and window control, which is
-// permanently meaningless on a phone rather than unfinished.
+// `openFileDialog` now works too: the shell presents the platform picker and
+// copies the chosen file into the app's container, so the path it hands back
+// is one `readFileAsync` can open.
+//
+// What remains behind pending(): `saveFileDialog`, which is not a missing
+// implementation but an unmade API decision (see its doc comment — mobile
+// wants an export-shaped call, not a path to write to), and window control,
+// which is permanently meaningless on a phone rather than unfinished.
 //
 // FAILING LOUDLY WITHOUT KILLING THE APP: an uncaught throw in library mode
 // reaches the panic sink and then ABORTS the process (SC4013). So a stub must
@@ -135,6 +141,14 @@ export class JanelaAppImpl<
   jobWriteCbs: ((err: string | null) => void)[] = [];
   nextJob = 1;
 
+  // In-flight file dialogs. Separate from the file jobs above: a picker is
+  // presented by the shell and answered when the user is done, which may be
+  // never. Kept in its own table so a dialog result can never be mistaken for
+  // a file-I/O result.
+  dialogIds: number[] = [];
+  dialogCbs: ((paths: string[] | null, err?: string) => void)[] = [];
+  nextDialog = 1;
+
   // Kept so the shared WindowConfig shape compiles; iOS has no window to size.
   constructor(_cfg: WindowConfig) {}
 
@@ -352,20 +366,80 @@ export class JanelaAppImpl<
     }
   }
 
-  /** @remarks Not on iOS yet; reports through the callback. */
+  /**
+   * Present the platform's document picker.
+   *
+   * The paths handed back are **copies inside the app's own storage**, not the
+   * locations the user picked. Neither platform gives an app a durable path to
+   * a file outside its container: iOS returns a security-scoped URL that is
+   * readable only while its access is held and does not survive a relaunch
+   * without a bookmark, and Android returns a `content://` URI that is not a
+   * path at all. Copying is what makes the result something `readFileAsync`
+   * can open, and keeps this API identical to desktop. Nothing tracks the
+   * original afterwards, so a later read sees the file as it was when picked.
+   */
   openFileDialog(
-    _options: OpenDialogOptions,
+    options: OpenDialogOptions,
     cb: (paths: string[] | null, err?: string) => void,
   ): void {
-    cb(null, pending("openFileDialog", "iOS needs a document picker"));
+    const id = this.nextDialog;
+    this.nextDialog = id + 1;
+    this.dialogIds.push(id);
+    this.dialogCbs.push(cb);
+    hostOpenDialog(id, JSON.stringify(options));
   }
 
-  /** @remarks Not on iOS yet; reports through the callback. */
+  /**
+   * Called by the shell on the main queue when a picker closes.
+   *
+   * `ok` false carries an error message in `payload`. `ok` true carries a JSON
+   * array of paths — empty when the user cancelled, which answers `null` to
+   * match desktop.
+   */
+  onDialogDone(id: number, ok: boolean, payload: string): void {
+    for (let i = 0; i < this.dialogIds.length; i++) {
+      if (this.dialogIds[i] === id) {
+        const cb = this.dialogCbs[i];
+        this.dialogIds.splice(i, 1);
+        this.dialogCbs.splice(i, 1);
+        if (!ok) {
+          cb(null, payload);
+          return;
+        }
+        const paths = JSON.parse(payload) as string[];
+        // Cancel is not an error: desktop answers null, so this does too.
+        if (paths.length < 1) cb(null);
+        else cb(paths);
+        return;
+      }
+    }
+  }
+
+  /**
+   * @remarks Not on mobile; reports through the callback.
+   *
+   * Deliberately still absent while `openFileDialog` works, because the two
+   * are not symmetrical here. Desktop's "save" means *tell me where to write*,
+   * and neither mobile platform offers that: iOS's `forExporting:` picker
+   * requires the file to already exist before it opens, and Android's
+   * `ACTION_CREATE_DOCUMENT` hands back a URI to write into rather than a
+   * path. Both want an export-shaped call — "here is a file, put it
+   * somewhere" — which is a different operation, not a different spelling of
+   * this one. Implementing it as `saveFileDialog` would give the same method
+   * two meanings across platforms, so it waits for an API decision.
+   */
   saveFileDialog(
     _options: SaveDialogOptions,
     cb: (path: string | null, err?: string) => void,
   ): void {
-    cb(null, pending("saveFileDialog", "iOS needs a document picker"));
+    cb(
+      null,
+      pending(
+        "saveFileDialog",
+        "a phone has no 'choose a path to write' picker; iOS and Android both " +
+          "want an export-shaped call, which is a different operation",
+      ),
+    );
   }
 
   /** @remarks No-op on iOS: an app has no window title to set. */

package/shim/android/app.cc

@@ -36,6 +36,8 @@
 #include <vector>
 
 #include <android/log.h>
+#include <sys/stat.h>
+#include <unistd.h>
 
 #define JANELA_LOG(...)                                                        \
   __android_log_print(ANDROID_LOG_INFO, "janela", __VA_ARGS__)
@@ -53,6 +55,8 @@ void jl_handle_invoke(const char *cmd, size_t cmd_len, const char *args,
 void jl_index_html(char **out, size_t *out_len);
 void jl_on_timer(double id);
 void jl_on_fs_done(double id, bool ok, const char *payload, size_t payload_len);
+void jl_on_dialog_done(double id, bool ok, const char *payload,
+                       size_t payload_len);
 }
 
 namespace {
@@ -60,6 +64,112 @@ namespace {
 webview::webview *g_webview = nullptr;
 std::string g_files_dir; // the app's private storage, resolved at startup
 
+// ---- host output -> logcat -------------------------------------------------
+//
+// Android discards a process's stdout and stderr. `setprop log.redirect-stdio
+// true` is refused on API 36, so a host `console.log` simply vanished and the
+// only way to see what the host printed was to render it and screenshot the
+// screen. That is not a debugging story, and it is the same problem iOS had
+// before its os_log tee.
+//
+// So the shell tees stdout and stderr into logcat line by line under stable
+// tags, and still writes to the original descriptors so nothing is lost:
+//
+//   adb logcat -s janela-host:V              # what the app printed
+//   adb logcat -s janela:V janela-stderr:V   # shell notices and stderr
+//
+// The library may not create threads; the shell may, and does — one reader per
+// descriptor.
+
+/// Replace `fd` with a pipe, forwarding every line to logcat and on to the
+/// original descriptor.
+///
+/// `tag` differs per descriptor on purpose. Replacing fd 2 captures everything
+/// in the process that writes to stderr, not just the library — on the
+/// emulator the GL driver is extremely chatty there — so host output goes to
+/// `janela-host` and stderr to `janela-stderr`, keeping
+/// `adb logcat -s janela-host:V` a clean view of what the app itself printed.
+void tee_fd_to_logcat(int fd, android_LogPriority prio, const char *label,
+                      const char *tag) {
+  int original = dup(fd);
+  if (original < 0) {
+    return;
+  }
+  int fds[2];
+  if (pipe(fds) != 0) {
+    close(original);
+    return;
+  }
+  if (dup2(fds[1], fd) < 0) {
+    close(fds[0]);
+    close(fds[1]);
+    close(original);
+    return;
+  }
+  close(fds[1]);
+
+  int read_fd = fds[0];
+  // A pipe is not a tty, so stdio switches to full buffering and would hold
+  // the library's output until the buffer filled or the process exited. Pin
+  // line buffering back on, or a log line only appears long after the event.
+  if (fd == STDOUT_FILENO) {
+    setvbuf(stdout, nullptr, _IOLBF, 0);
+  } else if (fd == STDERR_FILENO) {
+    setvbuf(stderr, nullptr, _IOLBF, 0);
+  }
+
+  std::thread([read_fd, original, prio, tag] {
+    std::string pending;
+    std::vector<char> buf(4096);
+    for (;;) {
+      ssize_t n = read(read_fd, buf.data(), buf.size());
+      if (n <= 0) {
+        break; // writer closed, or an unrecoverable error
+      }
+      // Pass the bytes through untouched first: stdout must behave as before.
+      ssize_t off = 0;
+      while (off < n) {
+        ssize_t w = write(original, buf.data() + off, (size_t)(n - off));
+        if (w <= 0) {
+          break;
+        }
+        off += w;
+      }
+      // Then split into lines: logcat is line-oriented and truncates long
+      // records, so one write per line rather than per read.
+      pending.append(buf.data(), (size_t)n);
+      size_t nl;
+      while ((nl = pending.find('\n')) != std::string::npos) {
+        std::string line = pending.substr(0, nl);
+        pending.erase(0, nl + 1);
+        if (!line.empty() && line.back() == '\r') {
+          line.pop_back();
+        }
+        if (!line.empty()) {
+          __android_log_write(prio, tag, line.c_str());
+        }
+      }
+      // A very long line with no newline would otherwise grow without bound.
+      if (pending.size() > 64 * 1024) {
+        __android_log_write(prio, tag, pending.c_str());
+        pending.clear();
+      }
+    }
+    if (!pending.empty()) {
+      __android_log_write(prio, tag, pending.c_str());
+    }
+  }).detach();
+
+  JANELA_LOG("%s is mirrored to logcat under tag %s", label, tag);
+}
+
+/// Mirror the library's output into logcat. Called before jl_init(), so
+/// anything setup() prints is already captured.
+void start_logging() {
+  tee_fd_to_logcat(STDOUT_FILENO, ANDROID_LOG_INFO, "stdout", "janela-host");
+  tee_fd_to_logcat(STDERR_FILENO, ANDROID_LOG_ERROR, "stderr", "janela-stderr");
+}
+
 /// Copy a library-owned result out of its arena and release it. Results live
 /// until the next jl_reset(), so nothing may hold the pointer past this call.
 std::string take_result(char *out, size_t out_len) {
@@ -386,6 +496,228 @@ std::string files_dir(JNIEnv *env, jobject activity) {
 
 JavaVM *g_vm = nullptr;
 
+// ---- the document picker ---------------------------------------------------
+//
+// Android hands back a content:// URI, which is not a path and cannot be given
+// to readFileAsync. So the shell copies the picked bytes into the app's own
+// storage and returns that path, which readFileAsync can already open. The
+// copy is a snapshot; nothing tracks the original afterwards.
+//
+// The picker itself is presented from Java: the Storage Access Framework
+// answers on Activity#onActivityResult, and native code cannot receive that
+// (ART's JNI DefineClass is unimplemented). JanelaActivity owns that half and
+// calls back in through the two JNI entry points at the bottom of this file.
+
+/// A global ref to the Activity, so the picker can be presented from a later
+/// turn. Local refs do not survive the call that produced them.
+jobject g_activity = nullptr;
+
+/// Attach the calling thread if needed and hand back an env for it.
+struct scoped_env {
+  JNIEnv *env = nullptr;
+  bool detach = false;
+  scoped_env() {
+    if (!g_vm) {
+      return;
+    }
+    if (g_vm->GetEnv((void **)&env, JNI_VERSION_1_6) == JNI_EDETACHED) {
+      if (g_vm->AttachCurrentThread(&env, nullptr) == JNI_OK) {
+        detach = true;
+      }
+    }
+  }
+  ~scoped_env() {
+    if (detach && g_vm) {
+      g_vm->DetachCurrentThread();
+    }
+  }
+};
+
+/// Read a content:// URI through the ContentResolver and copy it into the
+/// app's storage, returning the new path (empty on failure).
+std::string copy_uri_into_storage(JNIEnv *env, const std::string &uri_str,
+                                 const std::string &display_name) {
+  if (!g_activity) {
+    return {};
+  }
+  jclass uri_cls = env->FindClass("android/net/Uri");
+  jmethodID parse = env->GetStaticMethodID(uri_cls, "parse",
+                                           "(Ljava/lang/String;)Landroid/net/Uri;");
+  jstring juri = env->NewStringUTF(uri_str.c_str());
+  jobject uri = env->CallStaticObjectMethod(uri_cls, parse, juri);
+  env->DeleteLocalRef(juri);
+  if (!uri || env->ExceptionCheck()) {
+    env->ExceptionClear();
+    return {};
+  }
+
+  jclass act_cls = env->GetObjectClass(g_activity);
+  jmethodID get_resolver = env->GetMethodID(act_cls, "getContentResolver",
+                                            "()Landroid/content/ContentResolver;");
+  jobject resolver = env->CallObjectMethod(g_activity, get_resolver);
+  if (!resolver || env->ExceptionCheck()) {
+    env->ExceptionClear();
+    return {};
+  }
+  jclass res_cls = env->GetObjectClass(resolver);
+  jmethodID open = env->GetMethodID(res_cls, "openInputStream",
+                                    "(Landroid/net/Uri;)Ljava/io/InputStream;");
+  jobject stream = env->CallObjectMethod(resolver, open, uri);
+  if (!stream || env->ExceptionCheck()) {
+    env->ExceptionClear();
+    return {};
+  }
+
+  // Prefer the name the user saw. A content:// URI's last segment is an opaque
+  // document id, so falling back to it produces copies called things like
+  // "3A18"; the Activity resolves OpenableColumns.DISPLAY_NAME for us.
+  std::string name = display_name;
+  if (name.empty()) {
+    name = uri_str;
+    size_t slash = name.find_last_of("/%");
+    if (slash != std::string::npos && slash + 1 < name.size()) {
+      name = name.substr(slash + 1);
+    }
+  }
+  // A display name is untrusted input and must not escape the pick directory.
+  for (char &c : name) {
+    if (c == '/' || c == '\\') {
+      c = '_';
+    }
+  }
+  if (name == "." || name == "..") {
+    name = "picked";
+  }
+  for (char &c : name) {
+    if (c == ':' || c == '?' || c == '&' || c == '=') {
+      c = '_';
+    }
+  }
+  if (name.empty()) {
+    name = "picked";
+  }
+  std::string dir = resolve_path("picked");
+  ::mkdir(dir.c_str(), 0755);
+  std::string dest = dir + "/" + name;
+
+  jclass stream_cls = env->GetObjectClass(stream);
+  jmethodID read = env->GetMethodID(stream_cls, "read", "([B)I");
+  jmethodID close = env->GetMethodID(stream_cls, "close", "()V");
+  jbyteArray buf = env->NewByteArray(8192);
+  std::ofstream out(dest, std::ios::binary | std::ios::trunc);
+  bool ok = out.good();
+  while (ok) {
+    jint n = env->CallIntMethod(stream, read, buf);
+    if (env->ExceptionCheck()) {
+      env->ExceptionClear();
+      ok = false;
+      break;
+    }
+    if (n <= 0) {
+      break;
+    }
+    jbyte *bytes = env->GetByteArrayElements(buf, nullptr);
+    out.write(reinterpret_cast<const char *>(bytes), n);
+    env->ReleaseByteArrayElements(buf, bytes, JNI_ABORT);
+  }
+  out.close();
+  env->CallVoidMethod(stream, close);
+  env->ExceptionClear();
+
+  env->DeleteLocalRef(buf);
+  env->DeleteLocalRef(stream_cls);
+  env->DeleteLocalRef(stream);
+  env->DeleteLocalRef(res_cls);
+  env->DeleteLocalRef(resolver);
+  env->DeleteLocalRef(act_cls);
+  env->DeleteLocalRef(uri);
+  env->DeleteLocalRef(uri_cls);
+
+  if (!ok || !out) {
+    return {};
+  }
+  return dest;
+}
+
+void finish_dialog(double job, bool ok, std::string payload) {
+  // BY VALUE and dispatched: never re-enter the library from inside a JNI
+  // callback (upstream #263) — this lands at the top of a later turn.
+  if (g_webview) {
+    g_webview->dispatch([job, ok, payload] {
+      jl_on_dialog_done(job, ok, payload.c_str(), payload.size());
+    });
+  }
+}
+
+/// TS -> shell: present a document picker. Records the request and returns;
+/// the Activity presents it on the UI thread.
+void host_open_dialog(void *, double job, const char *options, size_t len) {
+  std::string opts(options, len);
+  if (!g_webview) {
+    return;
+  }
+  g_webview->dispatch([job, opts] {
+    // Android's SAF has no directory mode through ACTION_OPEN_DOCUMENT;
+    // report rather than quietly opening a file picker instead.
+    if (webview::detail::json_parse(opts, "directory", 0) == "true") {
+      finish_dialog(job, false,
+                    "ENOTSUP: picking a directory is not supported on Android");
+      return;
+    }
+    scoped_env se;
+    if (!se.env || !g_activity) {
+      finish_dialog(job, false, "EINVAL: the app has no Activity to present on");
+      return;
+    }
+    JNIEnv *env = se.env;
+
+    // Filters are MIME types here, so an extension list cannot be honoured
+    // directly; a type given as "image/*" or "text/plain" passes through.
+    std::vector<std::string> mimes;
+    for (size_t i = 0;; i++) {
+      std::string ext = webview::detail::json_parse(opts, "extensions", i);
+      if (ext.empty()) {
+        break;
+      }
+      if (ext.find('/') != std::string::npos) {
+        mimes.push_back(ext);
+      } else {
+        JANELA_LOG("filter '.%s' is an extension, but Android's picker takes "
+                   "MIME types, so the picker is not filtered",
+                   ext.c_str());
+      }
+    }
+
+    jclass str_cls = env->FindClass("java/lang/String");
+    jobjectArray arr =
+        env->NewObjectArray((jsize)mimes.size(), str_cls, nullptr);
+    for (size_t i = 0; i < mimes.size(); i++) {
+      jstring s = env->NewStringUTF(mimes[i].c_str());
+      env->SetObjectArrayElement(arr, (jsize)i, s);
+      env->DeleteLocalRef(s);
+    }
+
+    jclass act_cls = env->GetObjectClass(g_activity);
+    jmethodID mid = env->GetMethodID(act_cls, "openDocumentPicker",
+                                     "(DZ[Ljava/lang/String;)V");
+    if (!mid) {
+      env->ExceptionClear();
+      finish_dialog(job, false,
+                    "EIO: the Activity has no openDocumentPicker method");
+    } else {
+      bool multiple = webview::detail::json_parse(opts, "multiple", 0) == "true";
+      env->CallVoidMethod(g_activity, mid, (jdouble)job, (jboolean)multiple, arr);
+      if (env->ExceptionCheck()) {
+        env->ExceptionClear();
+        finish_dialog(job, false, "EIO: could not open a document picker");
+      }
+    }
+    env->DeleteLocalRef(arr);
+    env->DeleteLocalRef(str_cls);
+    env->DeleteLocalRef(act_cls);
+  });
+}
+
 } // namespace
 
 extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
@@ -393,6 +725,46 @@ extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
   return JNI_VERSION_1_6;
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_dev_janela_host_JanelaActivity_nativeOnDialogResult(JNIEnv *env, jclass,
+                                                         jdouble job,
+                                                         jboolean ok,
+                                                         jstring payload) {
+  std::string p;
+  if (payload) {
+    const char *chars = env->GetStringUTFChars(payload, nullptr);
+    if (chars) {
+      p = chars;
+      env->ReleaseStringUTFChars(payload, chars);
+    }
+  }
+  finish_dialog((double)job, ok == JNI_TRUE, p);
+}
+
+extern "C" JNIEXPORT jstring JNICALL
+Java_dev_janela_host_JanelaActivity_nativeCopyUri(JNIEnv *env, jclass,
+                                                  jstring uri,
+                                                  jstring display_name) {
+  std::string u;
+  if (uri) {
+    const char *chars = env->GetStringUTFChars(uri, nullptr);
+    if (chars) {
+      u = chars;
+      env->ReleaseStringUTFChars(uri, chars);
+    }
+  }
+  std::string dn;
+  if (display_name) {
+    const char *chars = env->GetStringUTFChars(display_name, nullptr);
+    if (chars) {
+      dn = chars;
+      env->ReleaseStringUTFChars(display_name, chars);
+    }
+  }
+  std::string path = copy_uri_into_storage(env, u, dn);
+  return env->NewStringUTF(path.c_str());
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_dev_janela_host_JanelaActivity_nativeOnCreate(JNIEnv *env, jclass,
                                                    jobject activity) {
@@ -401,6 +773,12 @@ Java_dev_janela_host_JanelaActivity_nativeOnCreate(JNIEnv *env, jclass,
     return;
   }
   g_files_dir = files_dir(env, activity);
+  // A global ref: the picker is presented from a later turn, and a local
+  // ref does not survive the call that produced it.
+  g_activity = env->NewGlobalRef(activity);
+
+  // Before jl_init(), so anything setup() prints reaches logcat.
+  start_logging();
 
   // Registration is a pure store and is legal before init; the panic sink and
   // every channel must be in place before any TypeScript runs, since setup()
@@ -411,6 +789,8 @@ Java_dev_janela_host_JanelaActivity_nativeOnCreate(JNIEnv *env, jclass,
       jl_set_callback("hostReadFile", (void (*)(void))host_read_file, nullptr) ||
       jl_set_callback("hostWriteFile", (void (*)(void))host_write_file,
                       nullptr) ||
+      jl_set_callback("hostOpenDialog", (void (*)(void))host_open_dialog,
+                      nullptr) ||
       jl_set_callback("janelaEmit", (void (*)(void))emit_event, nullptr)) {
     JANELA_LOG("could not register a host channel");
   }