janela 0.12.0 → 0.13.0

package/README.md

@@ -33,7 +33,7 @@ janela dev                # build + run with logs in the terminal
 janela build              # .janela/out/my-app  (+ my-app.app on macOS)
 ```
 
-Or start from a frontend framework — any Vite-based one:
+Or start from a frontend framework:
 
 ```bash
 janela init my-app --template vue     # or react | svelte | solid | vanilla
@@ -43,8 +43,18 @@ janela dev                            # Vite dev server + HMR, in a native windo
 
 `vanilla` is the default and needs no frontend toolchain at all. With a
 framework, `janela dev` runs your Vite dev server and points the window at it,
-and `janela build` flattens the production bundle into the binary — see
-[docs/frontend.md](../../docs/frontend.md).
+and `janela build` flattens the production bundle into the binary.
+
+All five templates are built and run on desktop, the iOS simulator and an
+Android emulator — the matrix and sizes are in
+[docs/frontend.md](../../docs/frontend.md). Your own Vite project works too, as
+long as it produces a **single-page `dist`**: multi-entry builds, SSR/SSG
+(Astro, Nuxt) and frameworks with their own non-Vite build are out of scope,
+because the output is flattened into one HTML document.
+
+Packaging for distribution — icons, a macOS `.dmg`, Android release signing, and
+what requires an Apple or Google account — is in
+[docs/distribution.md](../../docs/distribution.md).
 
 Requirements: Node 24+ and a C++ toolchain for the platform you are building —
 Xcode CLT on macOS; `g++` + `libwebkit2gtk-4.1-dev` on Linux; an llvm-mingw

package/bin/janela.mjs

@@ -351,6 +351,15 @@ function libraryProfile() {
         params: ["f64", "bool", "string"],
         returns: "void",
       },
+      // Deliberately its own export rather than reusing onFsDone, whose
+      // signature would fit: a dialog result arriving through the file-I/O
+      // path would read as a bug for as long as the code lived.
+      {
+        export: "onDialogDone",
+        symbol: `${IOS_PREFIX}on_dialog_done`,
+        params: ["f64", "bool", "string"],
+        returns: "void",
+      },
     ],
     // TS -> shell. A channel handler must never re-enter the library (see
     // upstream #263: violations silently appear to work), so every one of
@@ -362,6 +371,7 @@ function libraryProfile() {
       { name: "hostSettle", params: ["f64", "string"], returns: "void" },
       { name: "hostReadFile", params: ["f64", "string"], returns: "void" },
       { name: "hostWriteFile", params: ["f64", "string", "string"], returns: "void" },
+      { name: "hostOpenDialog", params: ["f64", "string"], returns: "void" },
     ],
   };
 }
@@ -1219,6 +1229,9 @@ function build(root, { devUrl = null, gui = true, target = "desktop" } = {}) {
       `/** A file job the shell owns has finished (main queue). */\n` +
       `export function onFsDone(id: number, ok: boolean, payload: string): void {\n` +
       `  app.onFsDone(id, ok, payload);\n` +
+      `}\n` +
+      `export function onDialogDone(id: number, ok: boolean, payload: string): void {\n` +
+      `  app.onDialogDone(id, ok, payload);\n` +
       `}\n`
     : `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
       `setup(app);\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

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");
   }

package/shim/android/java/dev/janela/host/JanelaActivity.java

@@ -1,6 +1,8 @@
 package dev.janela.host;
 
 import android.app.Activity;
+import android.content.Intent;
+import android.net.Uri;
 import android.os.Bundle;
 
 /**
@@ -10,17 +12,159 @@ import android.os.Bundle;
  * Looper. Everything janela does starts from onCreate, which hands the
  * Activity to the native shell — the mirror of the iOS shell, where UIKit owns
  * the loop and the app's TypeScript is a linked scriptc library we call into.
+ *
+ * <p>The file picker also lives here rather than in native code, because the
+ * Storage Access Framework is reached through {@code startActivityForResult}
+ * and answered on an Activity method. Native code cannot receive that: ART's
+ * JNI {@code DefineClass} is unimplemented, so a class the framework can call
+ * back into has to exist in the APK. The shell asks this class to open a
+ * picker and gets the answer back through {@code nativeOnDialogResult}.
  */
 public final class JanelaActivity extends Activity {
   static {
     System.loadLibrary("janela");
   }
 
+  /** Matches the request code the shell passes; only one picker at a time. */
+  private static final int PICK_REQUEST = 0x4a41;
+
   private static native void nativeOnCreate(Activity activity);
 
+  /**
+   * Hands a picker result to the shell.
+   *
+   * @param job the shell's dialog job id
+   * @param ok false when the pick failed outright
+   * @param payload a JSON array of copied paths, or an error message
+   */
+  private static native void nativeOnDialogResult(double job, boolean ok, String payload);
+
+  /**
+   * Resolves a content:// URI into a file inside the app's storage.
+   *
+   * <p>Implemented natively so the copy, the JSON and the error strings live
+   * in one place shared with iOS, rather than being written twice.
+   */
+  private static native String nativeCopyUri(String uri, String displayName);
+
+  private double pendingJob = -1;
+
   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     nativeOnCreate(this);
   }
+
+  /**
+   * Called from the shell (on the UI thread) to present a document picker.
+   *
+   * @param job the dialog job id to answer with
+   * @param multiple allow more than one selection
+   * @param mimeTypes MIME types to filter on, or an empty array for anything
+   */
+  public void openDocumentPicker(double job, boolean multiple, String[] mimeTypes) {
+    if (pendingJob >= 0) {
+      nativeOnDialogResult(job, false, "EBUSY: a file dialog is already open on this app");
+      return;
+    }
+    try {
+      Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+      intent.addCategory(Intent.CATEGORY_OPENABLE);
+      // A concrete type is required; the extras narrow it when filters exist.
+      intent.setType("*/*");
+      if (mimeTypes != null && mimeTypes.length > 0) {
+        intent.putExtra(Intent.EXTRA_MIME_TYPES, mimeTypes);
+      }
+      intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, multiple);
+      pendingJob = job;
+      startActivityForResult(intent, PICK_REQUEST);
+    } catch (Throwable t) {
+      pendingJob = -1;
+      nativeOnDialogResult(job, false, "EIO: could not open a document picker: " + t);
+    }
+  }
+
+  @Override
+  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+    super.onActivityResult(requestCode, resultCode, data);
+    if (requestCode != PICK_REQUEST) {
+      return;
+    }
+    double job = pendingJob;
+    pendingJob = -1;
+    if (job < 0) {
+      return;
+    }
+    // Cancel is not an error: an empty array becomes null on the page, which
+    // is what desktop answers.
+    if (resultCode != Activity.RESULT_OK || data == null) {
+      nativeOnDialogResult(job, true, "[]");
+      return;
+    }
+
+    StringBuilder json = new StringBuilder("[");
+    try {
+      if (data.getClipData() != null) {
+        int n = data.getClipData().getItemCount();
+        for (int i = 0; i < n; i++) {
+          Uri uri = data.getClipData().getItemAt(i).getUri();
+          if (!appendCopied(json, uri, job)) {
+            return;
+          }
+        }
+      } else if (data.getData() != null) {
+        if (!appendCopied(json, data.getData(), job)) {
+          return;
+        }
+      }
+    } catch (Throwable t) {
+      nativeOnDialogResult(job, false, "EIO: could not read the picked selection: " + t);
+      return;
+    }
+    json.append("]");
+    nativeOnDialogResult(job, true, json.toString());
+  }
+
+  /**
+   * The file's own name, so a copy is not named after the URI.
+   *
+   * A content:// URI's last segment is an opaque document id — picking
+   * "pickme.txt" yielded a copy called "3A18" before this. OpenableColumns
+   * carries the name the user actually saw.
+   */
+  private String displayName(Uri uri) {
+    try (android.database.Cursor c =
+        getContentResolver().query(uri, null, null, null, null)) {
+      if (c != null && c.moveToFirst()) {
+        int i = c.getColumnIndex(android.provider.OpenableColumns.DISPLAY_NAME);
+        if (i >= 0) {
+          String name = c.getString(i);
+          if (name != null && !name.isEmpty()) {
+            return name;
+          }
+        }
+      }
+    } catch (Throwable ignored) {
+      // Fall through: the shell names the copy from the URI instead.
+    }
+    return "";
+  }
+
+  /** Copies one URI and appends its quoted path; false if it failed. */
+  private boolean appendCopied(StringBuilder json, Uri uri, double job) {
+    if (uri == null) {
+      return true;
+    }
+    String copied = nativeCopyUri(uri.toString(), displayName(uri));
+    if (copied == null || copied.isEmpty()) {
+      nativeOnDialogResult(
+          job, false, "EIO: could not copy the picked file into the app's storage");
+      return false;
+    }
+    if (json.length() > 1) {
+      json.append(",");
+    }
+    json.append("\"").append(copied.replace("\\", "\\\\").replace("\"", "\\\"")).append("\"");
+    return true;
+  }
 }

package/shim/ios/app.cc

@@ -18,6 +18,7 @@
 
 #include <dispatch/dispatch.h>
 #include <os/log.h>
+#include <sys/stat.h>
 #include <unistd.h>
 
 #include <cstdio>
@@ -42,6 +43,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 {
@@ -305,6 +308,275 @@ void host_write_file(void *, double id, const char *path, size_t path_len,
   });
 }
 
+// ---- the document picker ---------------------------------------------------
+//
+// A picked file cannot simply be handed to readFileAsync. iOS returns a
+// security-scoped URL: readable only between startAccessingSecurityScopedResource
+// and its counterpart, and not readable at all after a relaunch without a
+// bookmark. So the shell copies the file into the app's container while the
+// scope is held and hands back that path, which readFileAsync can already
+// open. The copy is a snapshot; nothing tracks the original afterwards.
+
+std::string js_quote(const std::string &raw); // defined with the event channel
+
+namespace objc = webview::detail::objc;
+
+id ns_string(const std::string &s) {
+  return objc::msg_send<id>(objc::get_class("NSString"),
+                            objc::selector("stringWithUTF8String:"), s.c_str());
+}
+
+std::string from_ns_string(id s) {
+  if (!s) {
+    return {};
+  }
+  const char *c = objc::msg_send<const char *>(s, objc::selector("UTF8String"));
+  return c ? std::string(c) : std::string{};
+}
+
+/// Extension -> uniform type identifier.
+///
+/// UIDocumentPickerViewController wants UTIs, and turning an arbitrary
+/// extension into one needs UniformTypeIdentifiers or CoreServices. Rather
+/// than link a framework for a lookup table, this covers the common cases; an
+/// extension that is not here widens the picker to public.item and says so in
+/// the log, so a filter is never silently dropped.
+const char *uti_for_extension(const std::string &ext) {
+  static const std::map<std::string, const char *> kUtis = {
+      {"txt", "public.plain-text"},   {"text", "public.plain-text"},
+      {"md", "net.daringfireball.markdown"},
+      {"json", "public.json"},        {"csv", "public.comma-separated-values-text"},
+      {"xml", "public.xml"},          {"html", "public.html"},
+      {"htm", "public.html"},         {"pdf", "com.adobe.pdf"},
+      {"png", "public.png"},          {"jpg", "public.jpeg"},
+      {"jpeg", "public.jpeg"},        {"gif", "com.compuserve.gif"},
+      {"heic", "public.heic"},        {"mp3", "public.mp3"},
+      {"wav", "com.microsoft.waveform-audio"},
+      {"mp4", "public.mpeg-4"},       {"mov", "com.apple.quicktime-movie"},
+      {"zip", "public.zip-archive"},  {"js", "com.netscape.javascript-source"},
+      {"ts", "public.plain-text"},    {"css", "public.css"},
+      {"yaml", "public.yaml"},        {"yml", "public.yaml"},
+  };
+  auto it = kUtis.find(ext);
+  return it == kUtis.end() ? nullptr : it->second;
+}
+
+std::string lower(std::string s) {
+  for (char &c : s) {
+    if (c >= 'A' && c <= 'Z') {
+      c = (char)(c - 'A' + 'a');
+    }
+  }
+  return s;
+}
+
+/// Copy a picked file into the app's container, returning the new path.
+/// Called with the security scope already held.
+std::string copy_into_container(const std::string &src) {
+  std::string name = src;
+  size_t slash = name.find_last_of('/');
+  if (slash != std::string::npos) {
+    name = name.substr(slash + 1);
+  }
+  if (name.empty()) {
+    name = "picked";
+  }
+  std::string dest = resolve_path("picked/" + name);
+  size_t cut = dest.find_last_of('/');
+  if (cut != std::string::npos) {
+    // The pick directory may not exist yet; mkdir -p one level is enough.
+    std::string dir = dest.substr(0, cut);
+    ::mkdir(dir.c_str(), 0755);
+  }
+  std::ifstream in(src, std::ios::binary);
+  if (!in) {
+    return {};
+  }
+  std::ofstream out(dest, std::ios::binary | std::ios::trunc);
+  if (!out) {
+    return {};
+  }
+  out << in.rdbuf();
+  out.close();
+  return out ? dest : std::string{};
+}
+
+/// The dialog job the picker delegate answers. Only ever touched on the main
+/// queue, where UIKit presents and dismisses.
+double g_dialog_id = 0;
+bool g_dialog_open = false;
+
+void finish_dialog(double id, bool ok, std::string payload) {
+  // BY VALUE, and dispatched: never re-enter the library from inside a UIKit
+  // callback (upstream #263) — this lands at the top of a later turn.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    g_dialog_open = false;
+    jl_on_dialog_done(id, ok, payload.c_str(), payload.size());
+  });
+}
+
+/// Turn the picked URLs into a JSON array of container paths.
+void deliver_picked(id urls) {
+  double id_ = g_dialog_id;
+  if (!urls) {
+    finish_dialog(id_, true, "[]");
+    return;
+  }
+  auto count = objc::msg_send<unsigned long>(urls, objc::selector("count"));
+  std::string json = "[";
+  for (unsigned long i = 0; i < count; i++) {
+    id url = objc::msg_send<id>(urls, objc::selector("objectAtIndex:"), i);
+    if (!url) {
+      continue;
+    }
+    // The scope must be held across the copy, and released even on failure.
+    bool scoped = objc::msg_send<bool>(
+        url, objc::selector("startAccessingSecurityScopedResource"));
+    std::string path =
+        from_ns_string(objc::msg_send<id>(url, objc::selector("path")));
+    std::string copied = copy_into_container(path);
+    if (scoped) {
+      objc::msg_send<void>(url,
+                           objc::selector("stopAccessingSecurityScopedResource"));
+    }
+    if (copied.empty()) {
+      finish_dialog(id_, false,
+                    "EIO: could not copy the picked file into the app's "
+                    "container ('" + path + "')");
+      return;
+    }
+    if (json.size() > 1) {
+      json += ",";
+    }
+    json += js_quote(copied);
+  }
+  json += "]";
+  finish_dialog(id_, true, json);
+}
+
+/// The picker's delegate, built at runtime.
+///
+/// UIKit needs a real Objective-C class to send the delegate messages to, and
+/// this shell is plain C++, so the class is registered once with the runtime
+/// and its two methods are plain C functions. One shared instance is enough:
+/// only one picker can be up at a time, which g_dialog_open enforces.
+Class picker_delegate_class() {
+  static Class cls = nullptr;
+  if (cls) {
+    return cls;
+  }
+  cls = objc_allocateClassPair(objc::get_class("NSObject"),
+                               "JanelaPickerDelegate", 0);
+  class_addMethod(
+      cls, objc::selector("documentPicker:didPickDocumentsAtURLs:"),
+      (IMP)(+[](id, SEL, id, id urls) { deliver_picked(urls); }), "v@:@@");
+  class_addMethod(cls, objc::selector("documentPickerWasCancelled:"),
+                  (IMP)(+[](id, SEL, id) {
+                    // Cancel is not an error: an empty list becomes null.
+                    finish_dialog(g_dialog_id, true, "[]");
+                  }),
+                  "v@:@");
+  objc_registerClassPair(cls);
+  return cls;
+}
+
+id picker_delegate() {
+  static id instance = objc::msg_send<id>(
+      objc::msg_send<id>((id)picker_delegate_class(), objc::selector("alloc")),
+      objc::selector("init"));
+  return instance;
+}
+
+/// TS -> shell: present a document picker. Records the request and returns;
+/// UIKit work happens on the main queue, never inside this handler.
+void host_open_dialog(void *, double job, const char *options, size_t len) {
+  std::string opts(options, len);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    if (g_dialog_open) {
+      finish_dialog(job, false,
+                    "EBUSY: a file dialog is already open on this app");
+      return;
+    }
+
+    // `directory` has no picker on iOS; report rather than quietly opening a
+    // file picker instead, which is what desktop does for unsupported options.
+    if (webview::detail::json_parse(opts, "directory", 0) == "true") {
+      finish_dialog(job, false,
+                    "ENOTSUP: picking a directory is not supported on iOS");
+      return;
+    }
+
+    // Build the UTI list from the filters' extensions. An unmapped extension
+    // widens to public.item and is logged, so a filter is never silently lost.
+    id types = objc::msg_send<id>(objc::get_class("NSMutableArray"),
+                                  objc::selector("array"));
+    bool widened = false;
+    for (size_t i = 0;; i++) {
+      std::string ext = webview::detail::json_parse(opts, "extensions", i);
+      if (ext.empty()) {
+        break;
+      }
+      const char *uti = uti_for_extension(lower(ext));
+      if (uti) {
+        objc::msg_send<void>(types, objc::selector("addObject:"),
+                             ns_string(uti));
+      } else if (!widened) {
+        widened = true;
+        std::fprintf(stderr,
+                     "[janela] no uniform type identifier is mapped for '.%s', "
+                     "so the picker is not filtered\n",
+                     ext.c_str());
+      }
+    }
+    auto count = objc::msg_send<unsigned long>(types, objc::selector("count"));
+    if (count == 0 || widened) {
+      objc::msg_send<void>(types, objc::selector("addObject:"),
+                           ns_string("public.item"));
+    }
+
+    // initWithDocumentTypes:inMode: rather than the UTType-based initialiser,
+    // which would mean linking UniformTypeIdentifiers for a lookup table.
+    id picker = objc::msg_send<id>(
+        objc::msg_send<id>(
+            objc::get_class("UIDocumentPickerViewController"),
+            objc::selector("alloc")),
+        objc::selector("initWithDocumentTypes:inMode:"), types,
+        (unsigned long)0 /* UIDocumentPickerModeImport: hands us a copy */);
+    if (!picker) {
+      finish_dialog(job, false, "EIO: could not create a document picker");
+      return;
+    }
+    objc::msg_send<void>(picker, objc::selector("setDelegate:"),
+                         picker_delegate());
+    if (webview::detail::json_parse(opts, "multiple", 0) == "true") {
+      objc::msg_send<void>(picker, objc::selector("setAllowsMultipleSelection:"),
+                           true);
+    }
+
+    id window = nullptr;
+    if (g_webview) {
+      auto w = g_webview->window();
+      if (w.ok()) {
+        window = (id)w.value();
+      }
+    }
+    id root = window ? objc::msg_send<id>(
+                           window, objc::selector("rootViewController"))
+                     : nullptr;
+    if (!root) {
+      finish_dialog(job, false,
+                    "EINVAL: the app has no root view controller to present on");
+      return;
+    }
+
+    g_dialog_id = job;
+    g_dialog_open = true;
+    objc::msg_send<void>(root,
+                         objc::selector("presentViewController:animated:completion:"),
+                         picker, true, nullptr);
+  });
+}
+
 // ---- host -> page: the event channel ---------------------------------------
 
 /// Minimal JSON string quoting, for splicing an event name into a JS call.
@@ -424,6 +696,8 @@ int main() {
       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)) {
     std::fprintf(stderr, "[janela] could not register a host channel\n");
   }