janela 0.9.0 → 0.10.0

package/README.md

@@ -542,10 +542,28 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 - `console.log` from commands goes to stdout — visible under `janela dev`,
   not when launched from Finder.
 
+## iOS
+
+An iOS build runs the same app from the same source — same `main.ts`, same
+contract, same frontend:
+
+```bash
+janela build --target ios     # -> .janela/out-ios/<name>.app  (simulator)
+janela dev   --target ios     # build, boot a simulator, install, launch
+```
+
+It is **not part of a release yet** and is simulator-only. Commands, the typed
+contract, events, Vite frontends, async commands (`commandAsync`, `defer`,
+`sleep`) and file I/O all work the same as on desktop — the shell owns the
+clock and the file queue on both. File dialogs are not on iOS yet and report
+clearly when called; window control is a no-op there by nature. See
+[docs/ios.md](../../docs/ios.md).
+
 ## Status
 
 Early proof of concept, on macOS (arm64), Linux (WebKitGTK) and Windows
-(WebView2). The design notes and scriptc findings behind it are in
+(WebView2), with iOS on a branch (above). The design notes and scriptc
+findings behind it are in
 [docs/findings.md](../../docs/findings.md). Not yet: async commands that run in
 parallel (host code is single-threaded; `commandAsync` interleaves instead),
 tray icons and menus, multi-window, directory picking on Windows,

package/bin/janela.mjs

@@ -263,8 +263,213 @@ function webview2Include(cacheDir) {
   return incDir;
 }
 
+// ---- iOS ------------------------------------------------------------------
+//
+// The second build lane. Desktop compiles TypeScript to an EXECUTABLE that
+// drives a C library over FFI; iOS compiles it to a LIBRARY that a UIKit shell
+// drives. scriptc refuses executables for iOS targets, so the inversion is not
+// a preference — and library mode links no event loop (SC4005), which is why
+// the async surface is desktop-only there.
+//
+// Everything below is simulator-only: a device build additionally needs a
+// signing identity and a provisioning profile, which is its own project.
+
+const IOS_MIN_VERSION = "15.0";
+const IOS_PREFIX = "jl_";
+
+function iosDeviceOrFail(name) {
+  const json = capture(["xcrun", "simctl", "list", "devices", "available", "--json"]);
+  const devices = JSON.parse(json).devices ?? {};
+  const runtimes = Object.keys(devices).filter((k) => /iOS/i.test(k));
+  if (runtimes.length === 0) {
+    fail(
+      "no iOS simulator runtime is installed — open Xcode > Settings > Components " +
+        "and get an iOS simulator, or run `xcodebuild -downloadPlatform iOS` in a terminal " +
+        "(it needs admin rights, so it cannot run unattended)",
+    );
+  }
+  const all = runtimes.flatMap((k) => devices[k]);
+  const pick = name
+    ? all.find((d) => d.name === name)
+    : all.find((d) => /^iPhone/.test(d.name)) ?? all[0];
+  if (!pick) fail(`no simulator named '${name}' — see \`xcrun simctl list devices\``);
+  return pick;
+}
+
+function iosConf(conf) {
+  const ios = conf.ios ?? {};
+  return {
+    identifier: ios.identifier ?? conf.identifier,
+    displayName: ios.displayName ?? conf.window?.title ?? conf.name,
+    minimumVersion: String(ios.minimumVersion ?? IOS_MIN_VERSION),
+    device: ios.device ?? null,
+  };
+}
+
+// The library profile: one export carries every command, so a project's own
+// commands need no ABI of their own. `janelaEmit` is the reverse channel the
+// shell registers before init.
+function iosProfile() {
+  return {
+    profile_format: 1,
+    name: "janela",
+    entry: "./entry.ts",
+    emission: "llvm",
+    abi: {
+      prefix: IOS_PREFIX,
+      init_symbol: `${IOS_PREFIX}init`,
+      sink_register_symbol: `${IOS_PREFIX}set_panic_sink`,
+      collect_symbol: `${IOS_PREFIX}collect`,
+      result_reset_symbol: `${IOS_PREFIX}reset`,
+      callback_register_symbol: `${IOS_PREFIX}set_callback`,
+    },
+    exports: [
+      {
+        export: "handleInvoke",
+        symbol: `${IOS_PREFIX}handle_invoke`,
+        params: ["string", "string"],
+        returns: "string",
+      },
+      {
+        export: "indexHtml",
+        symbol: `${IOS_PREFIX}index_html`,
+        params: [],
+        returns: "string",
+      },
+      // The shell calls these back on the main queue when work it owns comes
+      // due. They are the mirror of the desktop shim's wv_on_timer: the
+      // library parks a continuation under an id and is re-entered with it.
+      {
+        export: "onTimer",
+        symbol: `${IOS_PREFIX}on_timer`,
+        params: ["f64"],
+        returns: "void",
+      },
+      {
+        export: "onFsDone",
+        symbol: `${IOS_PREFIX}on_fs_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
+    // these only records the request; the shell acts on its own queue and
+    // re-enters through an export above on a later turn.
+    callbacks: [
+      { name: "janelaEmit", params: ["string", "string"], returns: "void" },
+      { name: "hostSchedule", params: ["f64", "f64"], returns: "void" },
+      { name: "hostSettle", params: ["f64", "string"], returns: "void" },
+      { name: "hostReadFile", params: ["f64", "string"], returns: "void" },
+      { name: "hostWriteFile", params: ["f64", "string", "string"], returns: "void" },
+    ],
+  };
+}
+
+function iosPlist(conf) {
+  const ios = iosConf(conf);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>${conf.name}</string>
+  <key>CFBundleDisplayName</key><string>${ios.displayName}</string>
+  <key>CFBundleIdentifier</key><string>${ios.identifier}</string>
+  <key>CFBundleExecutable</key><string>${conf.name}</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleVersion</key><string>${conf.version ?? "0.1.0"}</string>
+  <key>CFBundleShortVersionString</key><string>${conf.version ?? "0.1.0"}</string>
+  <key>LSRequiresIPhoneOS</key><true/>
+  <key>UILaunchScreen</key><dict/>
+  <key>MinimumOSVersion</key><string>${ios.minimumVersion}</string>
+  <key>CFBundleSupportedPlatforms</key><array><string>iPhoneSimulator</string></array>
+</dict>
+</plist>
+`;
+}
+
+function buildIos(root, conf, buildDir, outDir) {
+  if (process.platform !== "darwin") {
+    fail("iOS builds need macOS with Xcode — `--target ios` is only available there");
+  }
+  if (!which("zig")) {
+    fail(
+      "iOS builds need zig on PATH: scriptc routes mobile targets through `zig cc`. " +
+        "Install it with `brew install zig`",
+    );
+  }
+  const ios = iosConf(conf);
+
+  writeFileSync(join(buildDir, "profile.json"), JSON.stringify(iosProfile(), null, 2) + "\n");
+
+  console.log("janela: compiling TypeScript to an iOS library");
+  run(["node", scriptcBin(), "build", "--lib", "--profile", "profile.json"], {
+    cwd: buildDir,
+    env: {
+      ...process.env,
+      SCRIPTC_CC: "zigcc",
+      SCRIPTC_TARGET: "aarch64-apple-ios-simulator",
+    },
+  });
+  const lib = join(buildDir, ".scriptc", "entry.lib.a");
+  if (!existsSync(lib)) fail(`scriptc produced no library at ${lib}`);
+
+  console.log("janela: compiling the UIKit shell");
+  const bundle = join(outDir, `${conf.name}.app`);
+  mkdirSync(bundle, { recursive: true });
+  const sdk = capture(["xcrun", "--sdk", "iphonesimulator", "--show-sdk-path"]);
+  // The .mm extension picks Objective-C++; an explicit `-x objective-c++`
+  // would leak onto the archive that follows and be compiled as source.
+  run([
+    "xcrun", "clang++",
+    join(KIT, "shim", "ios", "app.mm"),
+    "-target", `arm64-apple-ios${ios.minimumVersion}-simulator`,
+    "-isysroot", sdk,
+    "-fobjc-arc", "-std=c++17", "-O2",
+    "-framework", "UIKit", "-framework", "WebKit", "-framework", "Foundation",
+    lib,
+    "-o", join(bundle, conf.name),
+  ]);
+  run(["strip", join(bundle, conf.name)]);
+  writeFileSync(join(bundle, "Info.plist"), iosPlist(conf));
+
+  console.log(
+    `janela: built ${relative(root, bundle)} ` +
+      `(${statSync(join(bundle, conf.name)).size} bytes, iOS Simulator)`,
+  );
+  return bundle;
+}
+
+async function devIos(root) {
+  const conf = loadConf(root);
+  const device = iosDeviceOrFail(iosConf(conf).device);
+  const bundle = build(root, { target: "ios" });
+
+  if (device.state !== "Booted") {
+    console.log(`janela: booting ${device.name}`);
+    spawnSync("xcrun", ["simctl", "boot", device.udid]);
+    spawnSync("xcrun", ["simctl", "bootstatus", device.udid, "-b"]);
+  }
+  spawnSync("open", ["-a", "Simulator"]);
+
+  console.log(`janela: installing on ${device.name}`);
+  run(["xcrun", "simctl", "install", device.udid, bundle]);
+  console.log("janela: launching (Ctrl-C to stop following the log)");
+  run([
+    "xcrun", "simctl", "launch", "--console-pty",
+    device.udid, iosConf(conf).identifier,
+  ]);
+}
+
 // ---- shim ----------------------------------------------------------------
 
+function which(bin) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", [bin], {
+    encoding: "utf8",
+  });
+  return r.status === 0 ? r.stdout.trim().split("\n")[0] : null;
+}
+
 function buildShim(cacheDir) {
   const src = join(KIT, "shim", "wvshim.cc");
   const win = process.platform === "win32";
@@ -470,17 +675,23 @@ function makeGuiSubsystem(exePath) {
 
 // `devUrl` points the window at a running vite server instead of inlining the
 // frontend; `gui` asks for a GUI-subsystem .exe on Windows (build, not dev).
-function build(root, { devUrl = null, gui = true } = {}) {
+function build(root, { devUrl = null, gui = true, target = "desktop" } = {}) {
   const conf = loadConf(root);
-  const buildDir = join(root, ".janela", "build");
+  const ios = target === "ios";
+  const buildDir = join(root, ".janela", ios ? "build-ios" : "build");
   const cacheDir = join(root, ".janela", "cache");
-  const outDir = join(root, ".janela", "out");
+  const outDir = join(root, ".janela", ios ? "out-ios" : "out");
   for (const d of [buildDir, cacheDir, outDir]) mkdirSync(d, { recursive: true });
 
-  const shimLib = buildShim(cacheDir);
+  // Desktop links a C shim over webview.h; iOS links no shim at all — the
+  // UIKit shell is the program, and it links this build's output instead.
+  const shimLib = ios ? null : buildShim(cacheDir);
 
   // Assemble the compile unit: runtime + user's commands + generated modules.
-  cpSync(join(KIT, "runtime", "janela.ts"), join(buildDir, "janela.ts"));
+  // Which runtime lane lands here as "./janela" is the whole difference
+  // between the two targets — a project's main.ts is compiled unchanged
+  // against either.
+  cpSync(join(KIT, "runtime", ios ? "ios.ts" : "janela.ts"), join(buildDir, "janela.ts"));
   cpSync(join(KIT, "runtime", "types.ts"), join(buildDir, "types.ts"));
   const mainSrc = join(root, "src-host", "main.ts");
   if (!existsSync(mainSrc)) fail("missing src-host/main.ts");
@@ -512,6 +723,34 @@ function build(root, { devUrl = null, gui = true } = {}) {
       `width: ${Number(w.width ?? 800)}, height: ${Number(w.height ?? 600)} };\n`,
   );
 
+  // The iOS entry exports the library's two entry points instead of running a
+  // loop: UIKit owns the loop and calls in. Everything above this line — the
+  // contract, main.ts, the flattened frontend — is identical to desktop.
+  const entryTail = ios
+    ? `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
+      `setup(app);\n` +
+      `app.setHtml(INDEX_HTML);\n\n` +
+      `/** One page invoke; the UIKit shell calls this through the library ABI. */\n` +
+      `export function handleInvoke(cmd: string, argsJson: string): string {\n` +
+      `  return app.dispatch(cmd, argsJson);\n` +
+      `}\n\n` +
+      `/** The document the shell loads into its WKWebView. */\n` +
+      `export function indexHtml(): string {\n` +
+      `  return app.indexHtml();\n` +
+      `}\n\n` +
+      `/** A continuation the shell parked has come due (main queue). */\n` +
+      `export function onTimer(id: number): void {\n` +
+      `  app.onTimer(id);\n` +
+      `}\n\n` +
+      `/** 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`
+    : `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
+      `setup(app);\n` +
+      `const rc = app.run(INDEX_HTML) + 0;\n` +
+      `console.log("[janela] run returned", rc);\n`;
+
   writeFileSync(
     join(buildDir, "entry.ts"),
     `// Generated by janela — do not edit.\n` +
@@ -529,12 +768,11 @@ function build(root, { devUrl = null, gui = true } = {}) {
       `// and what is wanted here is the normalised table anyway.\n` +
       `type CmdsOf<F> = F extends (app: JanelaAppImpl<infer C, infer _E>) => void ? C : CommandShapes;\n` +
       `type EvtsOf<F> = F extends (app: JanelaAppImpl<infer _C, infer E>) => void ? E : Record<string, unknown>;\n\n` +
-      `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
-      `setup(app);\n` +
-      `const rc = app.run(INDEX_HTML) + 0;\n` +
-      `console.log("[janela] run returned", rc);\n`,
+      entryTail,
   );
 
+  if (ios) return buildIos(root, conf, buildDir, outDir);
+
   writeFileSync(join(buildDir, "janela.ffi.json"), JSON.stringify(ffiManifest(shimLib), null, 2) + "\n");
 
   console.log("janela: compiling TypeScript to a native binary");
@@ -730,20 +968,30 @@ function positionals() {
   return out;
 }
 
+const TARGETS = ["desktop", "ios"];
+
+function targetOrFail() {
+  const t = flag("target", "desktop");
+  if (!TARGETS.includes(t)) fail(`unknown target '${t}' (${TARGETS.join(", ")})`);
+  return t;
+}
+
 switch (cmd) {
   case "init":
     init(positionals()[0], flag("template", "vanilla"));
     break;
   case "build":
-    build(process.cwd());
+    build(process.cwd(), { target: targetOrFail() });
     break;
   case "dev":
-    await dev(process.cwd());
+    if (targetOrFail() === "ios") await devIos(process.cwd());
+    else await dev(process.cwd());
     break;
   default:
     console.log(
       "usage: janela init <name> [--template vanilla|vue|react|svelte|solid]\n" +
-        "       janela build | janela dev",
+        "       janela build [--target desktop|ios]\n" +
+        "       janela dev   [--target desktop|ios]",
     );
     process.exit(cmd ? 1 : 0);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "janela",
-  "version": "0.9.0",
-  "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
+  "version": "0.10.0",
+  "description": "Desktop and iOS apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
     "janela": "bin/janela.mjs",
@@ -40,7 +40,8 @@
     "native",
     "tauri",
     "electron-alternative",
-    "scriptc"
+    "scriptc",
+    "ios"
   ],
   "engines": {
     "node": ">=24"

package/runtime/ios.ts

@@ -0,0 +1,483 @@
+// janela's iOS runtime lane.
+//
+// Same public surface as runtime/janela.ts — `app.command`, `app.emit`, the
+// typed contract — so a project's src-host/main.ts compiles unchanged on both.
+// The CLI picks a lane by copying one of these two files in as `./janela`.
+//
+// What differs is who is in charge. On desktop, TypeScript owns `main` and
+// calls a blocking wvRun(); scriptc's event loop is parked for the app's life,
+// so this runtime carries a ticker, a timer queue and a deferred-job pool to
+// get work done anyway. On iOS none of that can exist:
+//
+//   - scriptc builds iOS as a LIBRARY (it refuses executables for the target),
+//     and library mode requires an async-free module graph — SC4005 rejects a
+//     build whose graph reaches setTimeout, promises or threads. There is no
+//     event loop linked into the artifact at all.
+//   - UIKit owns the run loop and calls us. Each handleInvoke() runs to
+//     completion and returns, so nothing needs pumping.
+//
+// The result is much smaller: a command registry and a dispatch function.
+// Everything that needed the loop is not available on iOS *yet* — it reports
+// when called rather than failing silently, and every such path goes through
+// one guard so that restoring parity is a single edit. See the stubs below.
+
+import type {
+  AsyncCommandHandler,
+  CommandHandler,
+  CommandShapes,
+  CommandSpecs,
+  DialogFilter,
+  FsCallback,
+  Norm,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
+
+// The host-callback channel declared in the generated library profile. The
+// shell registers it before jl_init(); calling a channel the host never
+// registered is a defined trap (SC4025), not undefined behaviour.
+declare function janelaEmit(event: string, payloadJson: string): void;
+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;
+
+// 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
+// must be module-level singletons rather than fresh closures.
+const nullRead: FsCallback = (_e: string | null, _t: string) => {};
+const nullWrite: (err: string | null) => void = (_e: string | null) => {};
+
+function encode(value: unknown): string {
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+// ---------------------------------------------------------------------------
+// The one place iOS says "not yet"
+// ---------------------------------------------------------------------------
+//
+// Everything below funnels through `pending()`. Nothing else in this file
+// decides what is or is not available, so the day a capability lands on iOS
+// its stub becomes a real implementation and this comment shrinks.
+//
+// The scheduling family — commandAsync, defer, sleep — and file I/O now work
+// exactly as they do on desktop: TS never holds a timer or a file handle, it
+// parks work with the shell under an id and is re-entered when the shell has
+// 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.
+//
+// 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
+// never throw from setup() — registering an async command at startup would
+// kill the app before its first frame. Stubs that hand back a callback report
+// through it; fire-and-forget stubs log; and commandAsync registers a command
+// that throws only when the page calls it, where dispatch()'s try/catch turns
+// it into a rejected promise.
+
+/** The single message every not-yet-on-iOS path reports. */
+function pending(api: string, why: string): string {
+  return (
+    "janela: app." + api + " is not available on iOS yet — " + why + ". " +
+    "Parity is planned; see docs/ios.md."
+  );
+}
+
+/**
+ * The scheduling family's guard — commandAsync, defer and sleep.
+ *
+ * These three are absent for one shared reason, and will return for one
+ * shared reason. Replacing this function with a real implementation (timers
+ * scheduled by the shell, the library re-entered when they fire) is the whole
+ * of that change on this side.
+ */
+/**
+ * A running janela app on iOS, typed by the contract it serves.
+ *
+ * Deliberately the same class name as the desktop lane: the generated entry
+ * and a project's main.ts are compiled against whichever file the CLI copied
+ * in, so both must present the same type.
+ */
+export class JanelaAppImpl<
+  C extends CommandShapes = CommandShapes,
+  E = Record<string, unknown>,
+> {
+  names: string[] = [];
+  handlers: CommandHandler[] = [];
+  html = "";
+
+  // ---- scheduling ----------------------------------------------------------
+  // Identical in shape to the desktop lane, and for a stronger reason: an iOS
+  // library links no event loop at all (SC4005), so TS could not hold a timer
+  // even if it wanted to. It parks a continuation under an id, asks the shell
+  // to schedule it, and the shell re-enters onTimer(id) on the main queue when
+  // it comes due. Nothing here polls.
+  contIds: number[] = [];
+  contFns: (() => void)[] = [];
+  nextCont = 1;
+
+  // An invoke whose answer is not ready when dispatch() returns. The shell
+  // holds the page's reply under this id and settles it when hostSettle()
+  // arrives. Mirrors the desktop shim's wv_defer/wv_resolve pair.
+  pendingIds: number[] = [];
+  nextPending = 1;
+  deferred = -1; // set by an async command during its own dispatch()
+
+  // In-flight file jobs: the shell does the blocking I/O on its own queue and
+  // re-enters onFsDone() with the result.
+  jobIds: number[] = [];
+  jobCbs: FsCallback[] = [];
+  jobWriteCbs: ((err: string | null) => void)[] = [];
+  nextJob = 1;
+
+  // Kept so the shared WindowConfig shape compiles; iOS has no window to size.
+  constructor(_cfg: WindowConfig) {}
+
+  /**
+   * Register a named command, callable from the page as janela.invoke(name, args).
+   *
+   * With a contract (`JanelaApp<App>`) the name must be one the contract
+   * declares, `args` is inferred from it, and the return value is checked
+   * against it. Without one, `args` is `unknown` and any name is accepted.
+   */
+  command<K extends keyof C & string>(
+    name: K,
+    handler: (args: C[K]["args"]) => C[K]["result"],
+  ): void {
+    this.names.push(name);
+    // The cast is on the VALUE, inside a contextually-typed closure: casting
+    // the function itself to another signature and calling through it fails
+    // at runtime.
+    this.handlers.push((args: unknown) => handler(args as C[K]["args"]));
+  }
+
+  /**
+   * Fire an event into the page; the payload is delivered as a value. Under a
+   * contract, the name must be declared and the payload must match its type.
+   *
+   * Reaches the page through the host-callback channel: the shell evaluates
+   * `window.__wvEmit(...)` on the main queue.
+   */
+  emit<K extends keyof E & string>(event: K, payload: E[K]): void {
+    janelaEmit(event, encode(payload));
+  }
+
+  /**
+   * Answer one page invoke. Called by the generated entry, which the shell
+   * calls through the library's C ABI.
+   *
+   * A command that throws is caught here and reported as a rejection rather
+   * than taking the app down with it — on iOS an uncaught throw would abort
+   * the process.
+   */
+  dispatch(cmd: string, argsJson: string): string {
+    try {
+      const args = JSON.parse(argsJson) as unknown;
+      for (let i = 0; i < this.names.length; i++) {
+        if (this.names[i] === cmd) {
+          this.deferred = -1;
+          const value = this.handlers[i](args);
+          // An async command parked its answer during the call above. Tell the
+          // shell to hold the page's reply under that id instead of settling
+          // now; hostSettle() answers it later.
+          if (this.deferred >= 0) {
+            const held = this.deferred;
+            this.deferred = -1;
+            return encode({ pending: held });
+          }
+          return encode({ ok: true, value });
+        }
+      }
+      return encode({ ok: false, error: "unknown command: " + cmd });
+    } catch (e) {
+      return encode({ ok: false, error: (e as Error).message });
+    }
+  }
+
+  /** The document the shell should load. Set by the generated entry. */
+  setHtml(html: string): void {
+    this.html = html;
+  }
+
+  indexHtml(): string {
+    return this.html;
+  }
+
+  // -------------------------------------------------------------------------
+  // Not yet on iOS
+  // -------------------------------------------------------------------------
+  // Present so that a project written for desktop still COMPILES for iOS —
+  // the typed contract and main.ts are shared source. Each reports clearly at
+  // the point of use instead of doing nothing quietly, and each routes through
+  // pending() above so there is one place to change.
+
+  /**
+   * An async command: answer later, without freezing the window.
+   *
+   * The handler runs during dispatch() but need not produce a value. It parks
+   * a pending id; dispatch() returns that id to the shell, which holds the
+   * page's promise until resolve/reject settles it. Same contract as desktop.
+   */
+  commandAsync<K extends keyof C & string>(
+    name: K,
+    handler: (
+      args: C[K]["args"],
+      resolve: (value: C[K]["result"]) => void,
+      reject: (reason: unknown) => void,
+    ) => void,
+  ): void {
+    this.names.push(name);
+    this.handlers.push((args: unknown) => {
+      const id = this.nextPending;
+      this.nextPending = id + 1;
+      this.pendingIds.push(id);
+      // dispatch() reads this immediately after the handler returns.
+      this.deferred = id;
+      handler(
+        args as C[K]["args"],
+        (value: C[K]["result"]) => {
+          this.settle(id, encode({ ok: true, value: value }));
+        },
+        (reason: unknown) => {
+          this.settle(id, encode({ ok: false, error: String(reason) }));
+        },
+      );
+      return null;
+    });
+  }
+
+  /** Settle a held reply once, ignoring a second resolve/reject. */
+  settle(id: number, envelope: string): void {
+    for (let i = 0; i < this.pendingIds.length; i++) {
+      if (this.pendingIds[i] === id) {
+        this.pendingIds.splice(i, 1);
+        hostSettle(id, envelope);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Park `fn` with the shell and ask to be called back in `ms`.
+   *
+   * The id is the whole protocol: TS keeps the closure, the shell keeps the
+   * clock. Identical to the desktop lane.
+   */
+  schedule(ms: number, fn: () => void): void {
+    const id = this.nextCont;
+    this.nextCont = id + 1;
+    this.contIds.push(id);
+    this.contFns.push(fn);
+    const delay = ms > 0 ? ms : 0;
+    hostSchedule(id, delay);
+  }
+
+  /** Run fn on the next turn of the host loop — no timer involved. */
+  defer(fn: () => void): void {
+    this.schedule(0, fn);
+  }
+
+  /** Run fn after roughly `ms`, without blocking the window meanwhile. */
+  sleep(ms: number, fn: () => void): void {
+    this.schedule(ms, fn);
+  }
+
+  /**
+   * Called by the shell on the main queue when a continuation comes due.
+   *
+   * This always lands at the top of a fresh turn with no TS frame beneath it,
+   * because the shell posts through its own queue rather than calling back
+   * from inside a channel handler (upstream #263: a breach silently appears
+   * to work, so it has to hold by construction).
+   */
+  onTimer(id: number): void {
+    for (let i = 0; i < this.contIds.length; i++) {
+      if (this.contIds[i] === id) {
+        const fn = this.contFns[i];
+        // Unregister BEFORE running: a continuation that schedules another one
+        // must not disturb the entry being removed.
+        this.contIds.splice(i, 1);
+        this.contFns.splice(i, 1);
+        fn();
+        return;
+      }
+    }
+  }
+
+  /** Read a file without blocking the UI; the shell does the I/O off-queue. */
+  readFileAsync(path: string, cb: FsCallback): void {
+    const id = this.nextJob;
+    this.nextJob = id + 1;
+    this.jobIds.push(id);
+    this.jobCbs.push(cb);
+    this.jobWriteCbs.push(nullWrite);
+    hostReadFile(id, path);
+  }
+
+  /** Write a file without blocking the UI; the shell does the I/O off-queue. */
+  writeFileAsync(path: string, data: string, cb: (err: string | null) => void): void {
+    const id = this.nextJob;
+    this.nextJob = id + 1;
+    this.jobIds.push(id);
+    this.jobCbs.push(nullRead);
+    this.jobWriteCbs.push(cb);
+    hostWriteFile(id, path, data);
+  }
+
+  /**
+   * Called by the shell on the main queue when a file job finishes. `payload`
+   * carries the contents on a read, or the error message when `ok` is false.
+   */
+  onFsDone(id: number, ok: boolean, payload: string): void {
+    for (let i = 0; i < this.jobIds.length; i++) {
+      if (this.jobIds[i] === id) {
+        const readCb = this.jobCbs[i];
+        const writeCb = this.jobWriteCbs[i];
+        this.jobIds.splice(i, 1);
+        this.jobCbs.splice(i, 1);
+        this.jobWriteCbs.splice(i, 1);
+        if (readCb !== nullRead) {
+          if (ok) readCb(null, payload);
+          else readCb(payload, "");
+        } else {
+          writeCb(ok ? null : payload);
+        }
+        return;
+      }
+    }
+  }
+
+  /** @remarks Not on iOS yet; reports through the callback. */
+  openFileDialog(
+    _options: OpenDialogOptions,
+    cb: (paths: string[] | null, err?: string) => void,
+  ): void {
+    cb(null, pending("openFileDialog", "iOS needs a document picker"));
+  }
+
+  /** @remarks Not on iOS yet; reports through the callback. */
+  saveFileDialog(
+    _options: SaveDialogOptions,
+    cb: (path: string | null, err?: string) => void,
+  ): void {
+    cb(null, pending("saveFileDialog", "iOS needs a document picker"));
+  }
+
+  /** @remarks No-op on iOS: an app has no window title to set. */
+  setTitle(_title: string): void {
+    console.error(pending("setTitle", "an iOS app has no window title"));
+  }
+
+  /** @remarks No-op on iOS: an app fills the screen. */
+  setSize(_width: number, _height: number, _hint?: number): void {
+    console.error(pending("setSize", "an iOS app fills the screen"));
+  }
+
+  /** @remarks No-op on iOS: an app is always fullscreen. */
+  setFullscreen(_on: boolean): void {
+    console.error(pending("setFullscreen", "an iOS app is always fullscreen"));
+  }
+
+  /** @remarks No-op on iOS: apps are dismissed by the user, not by code. */
+  quit(): void {
+    console.error(pending("quit", "iOS apps are dismissed by the user"));
+  }
+
+  /**
+   * Present for source compatibility with the desktop lane; UIKit owns the run
+   * loop here, so the shell shows the page rather than this.
+   */
+  run(html: string): number {
+    this.setHtml(html);
+    return 0;
+  }
+}
+
+// The public host types live in ./types (shipped as `janela/host` too, so a
+// user's editor can see them). Re-exported here because the compiled build
+// resolves them through this module — see the specifier rewrite in the CLI.
+export type {
+  ArgsOf,
+  AsyncCommandHandler,
+  CommandHandler,
+  CommandShape,
+  CommandShapes,
+  CommandSpec,
+  CommandSpecs,
+  Commands,
+  Norm,
+  ResultOf,
+  DialogFilter,
+  Events,
+  FsCallback,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
+
+export { defineCommands, defineEvents } from "./types";
+
+/**
+ * A running janela app, typed by the contract it serves. See the desktop lane
+ * for the full explanation; the alias exists so a contract may be written as
+ * plain function types.
+ */
+export type JanelaApp<
+  C extends CommandSpecs = CommandShapes,
+  E = Record<string, unknown>,
+> = JanelaAppImpl<Norm<C>, E>;
+
+export function createApp<
+  C extends CommandShapes = CommandShapes,
+  E = Record<string, unknown>,
+>(cfg: WindowConfig): JanelaAppImpl<C, E> {
+  return new JanelaAppImpl<C, E>(cfg);
+}
+
+// ---------------------------------------------------------------------------
+// Deprecated standalone registrars (0.5.x)
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use `app.command(name, handler)` on a contract-typed app. */
+export function on<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaAppImpl,
+  _commands: unknown,
+  name: K,
+  handler: (args: M[K]["args"]) => M[K]["result"],
+): void {
+  app.command(name, (args: unknown) => handler(args as M[K]["args"]));
+}
+
+/** @deprecated Use `app.commandAsync(name, handler)` on a contract-typed app. */
+export function onAsync<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaAppImpl,
+  _commands: unknown,
+  name: K,
+  handler: (
+    args: M[K]["args"],
+    resolve: (value: M[K]["result"]) => void,
+    reject: (reason: unknown) => void,
+  ) => void,
+): void {
+  app.commandAsync(
+    name,
+    (args: unknown, resolve: (v: unknown) => void, reject: (r: unknown) => void) => {
+      handler(args as M[K]["args"], (value: M[K]["result"]) => resolve(value), reject);
+    },
+  );
+}
+
+/** @deprecated Use `app.emit(event, payload)` on a contract-typed app. */
+export function emit<E, K extends keyof E & string>(
+  app: JanelaAppImpl,
+  _events: unknown,
+  name: K,
+  payload: E[K],
+): void {
+  app.emit(name, payload as unknown);
+}

package/shim/ios/app.mm

@@ -0,0 +1,386 @@
+// janela's iOS shell: UIKit owns the run loop, WKWebView is the window, and
+// the app's TypeScript is a linked scriptc library we call into.
+//
+// This is the mirror image of the desktop shim. There, TypeScript owns main()
+// and drives a C library over FFI; here the platform owns main() and calls a
+// TypeScript library. scriptc builds iOS as a library only, and library mode
+// links no event loop (SC4005), so there is nothing to pump: each invoke runs
+// to completion and returns.
+//
+// The WKWebView / WKUserContentController / script-message-handler wiring
+// follows the approach used by wry (https://github.com/tauri-apps/wry,
+// Apache-2.0, © Tauri Programme within The Commons Conservancy) in
+// src/wkwebview/. wry attaches its webview to a UIView supplied by tao; janela
+// has no tao, so it creates the UIWindow and root view controller itself. The
+// IPC envelope and the page-side bridge are janela's own, and match what the
+// desktop shim injects so that `janela/api` works unchanged.
+
+#import <UIKit/UIKit.h>
+#import <WebKit/WebKit.h>
+
+#include <string.h>
+
+// ---- the scriptc library's C ABI (see the generated profile) ---------------
+extern "C" {
+void jl_init(void);
+void jl_reset(void);
+void jl_set_panic_sink(void (*fn)(void *, const char *, size_t, const char *, size_t), void *ctx);
+int32_t jl_set_callback(const char *name, void (*fn)(void), void *ctx);
+void jl_handle_invoke(const char *cmd, size_t cmd_len, const char *args, size_t args_len,
+                      char **out, size_t *out_len);
+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);
+}
+
+static WKWebView *gWebView = nil;
+
+/// Settle one page-side promise with an envelope that is already JSON.
+static void settlePage(NSNumber *callId, NSString *envelope) {
+  NSString *js =
+      [NSString stringWithFormat:@"window.__janelaSettle(%@,%@);", callId, envelope];
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [gWebView evaluateJavaScript:js completionHandler:nil];
+  });
+}
+
+static void panicSink(void *ctx, const char *sym, size_t symlen, const char *msg, size_t msglen) {
+  (void)ctx;
+  NSLog(@"[janela] host panic in %.*s: %.*s", (int)symlen, sym, (int)msglen, msg);
+}
+
+// ---- what the shell owns for the library ----------------------------------
+//
+// Two tables, mirroring the desktop shim: continuations the library parked
+// with us, and page replies we are holding until the library says what they
+// are. Both live on the main queue and are only touched there.
+//
+// THE RULE (upstream #263): a channel handler must never re-enter the library.
+// Every handler below therefore only records what it was told and returns; the
+// re-entry happens from a dispatch_async block, i.e. at the top of a later
+// turn with no library frame beneath it. A breach silently appears to work, so
+// this has to hold by construction rather than by testing.
+
+/// Page replies whose answer was not ready when handle_invoke returned.
+/// pendingId -> the page-side call id we have not settled yet.
+static NSMutableDictionary<NSNumber *, NSNumber *> *gHeld = nil;
+/// Envelopes that arrived before we knew the page call id — a command that
+/// resolves synchronously settles during its own dispatch, before the
+/// {"pending":id} envelope has made it back to us.
+static NSMutableDictionary<NSNumber *, NSString *> *gEarly = nil;
+
+/// Answer the page for a pending id, whichever half arrived first.
+static void resolvePending(NSNumber *pendingId, NSString *envelope) {
+  NSNumber *callId = gHeld[pendingId];
+  if (callId) {
+    [gHeld removeObjectForKey:pendingId];
+    settlePage(callId, envelope);
+  } else {
+    gEarly[pendingId] = envelope; // handle_invoke has not returned yet
+  }
+}
+
+/// Register the page call id a pending answer belongs to.
+static void holdPending(NSNumber *pendingId, NSNumber *callId) {
+  NSString *early = gEarly[pendingId];
+  if (early) {
+    [gEarly removeObjectForKey:pendingId];
+    settlePage(callId, early); // it resolved synchronously; answer now
+  } else {
+    gHeld[pendingId] = callId;
+  }
+}
+
+// ---- channels the library calls (TS -> shell) ------------------------------
+
+/// Park a continuation with us and call back when it comes due. A zero delay
+/// still goes through dispatch_after(0), which posts to the next turn — that
+/// is app.defer(), and it costs no timer.
+static void hostSchedule(void *ctx, double id, double ms) {
+  (void)ctx;
+  int64_t delay = (int64_t)(ms > 0 ? ms : 0);
+  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delay * NSEC_PER_MSEC),
+                 dispatch_get_main_queue(), ^{
+    jl_on_timer(id); // fresh turn: no library frame beneath us
+  });
+}
+
+/// The library has an answer for a held page reply.
+static void hostSettle(void *ctx, double pendingId, const char *env, size_t env_len) {
+  (void)ctx;
+  NSString *envelope = [[NSString alloc] initWithBytes:env
+                                                length:env_len
+                                              encoding:NSUTF8StringEncoding] ?: @"null";
+  NSNumber *key = @((int64_t)pendingId);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    resolvePending(key, envelope);
+  });
+}
+
+/// The file queue: blocking I/O happens here, never on the main queue, and
+/// never inside the library. The library links no threads of its own, so this
+/// is the only place a read can go.
+/// An iOS app has no useful working directory and cannot see host paths, so a
+/// relative path is taken as relative to the app's Documents directory — the
+/// one place a sandboxed app can freely read and write.
+static NSString *resolvePath(NSString *path) {
+  if ([path hasPrefix:@"/"]) return path;
+  NSArray<NSString *> *dirs =
+      NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
+  NSString *docs = dirs.firstObject ?: NSTemporaryDirectory();
+  return [docs stringByAppendingPathComponent:path];
+}
+
+static dispatch_queue_t fsQueue(void) {
+  static dispatch_queue_t q;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    q = dispatch_queue_create("dev.janela.fs", DISPATCH_QUEUE_SERIAL);
+  });
+  return q;
+}
+
+static void finishFs(double id, bool ok, NSString *payload) {
+  // Convert INSIDE the block: -UTF8String hands back an autoreleased buffer
+  // whose lifetime does not survive the hop to another queue. The NSString is
+  // captured (and retained) by the block; the bytes are taken on arrival.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    const char *bytes = payload.UTF8String ?: "";
+    jl_on_fs_done(id, ok, bytes, strlen(bytes));
+  });
+}
+
+static void hostReadFile(void *ctx, double id, const char *path, size_t path_len) {
+  (void)ctx;
+  NSString *p = resolvePath([[NSString alloc] initWithBytes:path
+                                                     length:path_len
+                                                   encoding:NSUTF8StringEncoding] ?: @"");
+  dispatch_async(fsQueue(), ^{
+    NSError *err = nil;
+    NSString *text = [NSString stringWithContentsOfFile:p
+                                               encoding:NSUTF8StringEncoding
+                                                  error:&err];
+    if (text) finishFs(id, true, text);
+    else finishFs(id, false, err.localizedDescription ?: @"read failed");
+  });
+}
+
+static void hostWriteFile(void *ctx, double id, const char *path, size_t path_len,
+                          const char *data, size_t data_len) {
+  (void)ctx;
+  NSString *p = resolvePath([[NSString alloc] initWithBytes:path
+                                                     length:path_len
+                                                   encoding:NSUTF8StringEncoding] ?: @"");
+  NSString *d = [[NSString alloc] initWithBytes:data
+                                         length:data_len
+                                       encoding:NSUTF8StringEncoding] ?: @"";
+  dispatch_async(fsQueue(), ^{
+    NSError *err = nil;
+    BOOL ok = [d writeToFile:p atomically:YES encoding:NSUTF8StringEncoding error:&err];
+    if (ok) finishFs(id, true, @"");
+    else finishFs(id, false, err.localizedDescription ?: @"write failed");
+  });
+}
+
+/// 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.
+static NSString *takeResult(char *out, size_t out_len) {
+  NSString *s = out ? [[NSString alloc] initWithBytes:out
+                                               length:out_len
+                                             encoding:NSUTF8StringEncoding]
+                    : nil;
+  jl_reset();
+  return s ?: @"null";
+}
+
+/// Escape a JSON document for splicing into a JS expression as a string
+/// literal. Used for the event payload, which the page parses back.
+static NSString *jsQuote(NSString *raw) {
+  NSData *d = [NSJSONSerialization dataWithJSONObject:@[ raw ] options:0 error:nil];
+  NSString *arr = [[NSString alloc] initWithData:d encoding:NSUTF8StringEncoding];
+  // ["..."] -> "..."
+  return [arr substringWithRange:NSMakeRange(1, arr.length - 2)];
+}
+
+// ---- host -> page: the event channel ---------------------------------------
+//
+// The library calls this through the declared callback channel whenever the
+// app emits. Evaluating JS must happen on the main queue.
+
+static void emitEvent(void *ctx, const char *name, size_t name_len,
+                      const char *payload, size_t payload_len) {
+  (void)ctx;
+  NSString *event = [[NSString alloc] initWithBytes:name length:name_len
+                                           encoding:NSUTF8StringEncoding];
+  NSString *json = [[NSString alloc] initWithBytes:payload length:payload_len
+                                          encoding:NSUTF8StringEncoding];
+  if (!event || !json) return;
+  NSString *js = [NSString stringWithFormat:@"window.__wvEmit(%@,%@);", jsQuote(event), json];
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [gWebView evaluateJavaScript:js completionHandler:nil];
+  });
+}
+
+// ---- page -> host: the invoke bridge ---------------------------------------
+
+@interface JanelaBridge : NSObject <WKScriptMessageHandler>
+@end
+
+@implementation JanelaBridge
+
+- (void)userContentController:(WKUserContentController *)controller
+      didReceiveScriptMessage:(WKScriptMessage *)message {
+  NSDictionary *body = (NSDictionary *)message.body;
+  if (![body isKindOfClass:NSDictionary.class]) return;
+
+  NSNumber *callId = body[@"id"];
+  NSString *cmd = body[@"cmd"];
+  NSString *args = body[@"args"] ?: @"null";
+  if (!callId || !cmd) return;
+
+  const char *c = cmd.UTF8String;
+  const char *a = args.UTF8String;
+  char *out = NULL;
+  size_t out_len = 0;
+  jl_handle_invoke(c, strlen(c), a, strlen(a), &out, &out_len);
+  NSString *reply = takeResult(out, out_len);
+
+  // An async command answers later: the library returns {"pending":<id>} and
+  // we hold the page's promise until hostSettle() tells us what it is.
+  NSData *replyData = [reply dataUsingEncoding:NSUTF8StringEncoding];
+  NSDictionary *env = replyData
+      ? [NSJSONSerialization JSONObjectWithData:replyData options:0 error:nil]
+      : nil;
+  NSNumber *pendingId = [env isKindOfClass:NSDictionary.class] ? env[@"pending"] : nil;
+  if (pendingId) {
+    holdPending(pendingId, callId);
+    return;
+  }
+
+  // Otherwise the reply is an envelope: {"ok":true,"value":…} or
+  // {"ok":false,"error":…}, already JSON, so it splices straight into the
+  // expression that settles the page-side promise.
+  settlePage(callId, reply);
+}
+
+@end
+
+// ---- the page-side bridge --------------------------------------------------
+//
+// Same surface the desktop shim injects — window.janela.invoke/listen and
+// window.__wvEmit — so `janela/api` and a project's frontend work unchanged.
+// Only the transport differs: a script message instead of a webview bind.
+
+static NSString *const kBootstrap =
+    @"window.__wvListeners = {};"
+    @"window.__janelaPending = {};"
+    @"window.__janelaSeq = 0;"
+    @"window.__janelaSettle = function (id, env) {"
+    @"  var p = window.__janelaPending[id];"
+    @"  if (!p) return;"
+    @"  delete window.__janelaPending[id];"
+    @"  if (env && env.ok) p.resolve(env.value); else p.reject(new Error((env && env.error) || 'janela: invoke failed'));"
+    @"};"
+    @"window.janela = {"
+    @"  invoke: function (cmd, args) {"
+    @"    var id = ++window.__janelaSeq;"
+    @"    return new Promise(function (resolve, reject) {"
+    @"      window.__janelaPending[id] = { resolve: resolve, reject: reject };"
+    @"      window.webkit.messageHandlers.janela.postMessage({"
+    @"        id: id, cmd: cmd, args: JSON.stringify(args === undefined ? null : args)"
+    @"      });"
+    @"    });"
+    @"  },"
+    @"  listen: function (event, cb) {"
+    @"    if (!window.__wvListeners[event]) window.__wvListeners[event] = [];"
+    @"    window.__wvListeners[event].push(cb);"
+    @"    return function () {"
+    @"      var a = window.__wvListeners[event] || [];"
+    @"      var i = a.indexOf(cb);"
+    @"      if (i >= 0) a.splice(i, 1);"
+    @"    };"
+    @"  },"
+    @"};"
+    @"window.__wvEmit = function (event, payload) {"
+    @"  var cbs = window.__wvListeners[event] || [];"
+    @"  for (var i = 0; i < cbs.length; i++) cbs[i](payload);"
+    @"};";
+
+@interface JanelaViewController : UIViewController
+@end
+
+@implementation JanelaViewController {
+  JanelaBridge *_bridge;
+}
+
+- (void)viewDidLoad {
+  [super viewDidLoad];
+
+  WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
+  WKUserContentController *manager = config.userContentController;
+
+  _bridge = [[JanelaBridge alloc] init];
+  [manager addScriptMessageHandler:_bridge name:@"janela"];
+
+  // Injected before the document loads, exactly as the desktop shim does with
+  // webview_init — so the page can call janela.invoke from its first line.
+  WKUserScript *boot = [[WKUserScript alloc] initWithSource:kBootstrap
+                                              injectionTime:WKUserScriptInjectionTimeAtDocumentStart
+                                           forMainFrameOnly:YES];
+  [manager addUserScript:boot];
+
+  WKWebView *webview = [[WKWebView alloc] initWithFrame:self.view.bounds
+                                          configuration:config];
+  webview.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  [self.view addSubview:webview];
+  gWebView = webview;
+
+  char *out = NULL;
+  size_t out_len = 0;
+  jl_index_html(&out, &out_len);
+  NSString *html = takeResult(out, out_len);
+  [webview loadHTMLString:html baseURL:nil];
+}
+
+@end
+
+@interface JanelaAppDelegate : UIResponder <UIApplicationDelegate>
+@property(nonatomic, strong) UIWindow *window;
+@end
+
+@implementation JanelaAppDelegate
+
+- (BOOL)application:(UIApplication *)application
+    didFinishLaunchingWithOptions:(NSDictionary *)options {
+  // Registration is a pure store and is legal before init; the panic sink and
+  // the event channel must both be in place before any TypeScript runs, since
+  // setup() executes during jl_init().
+  jl_set_panic_sink(panicSink, NULL);
+  gHeld = [NSMutableDictionary dictionary];
+  gEarly = [NSMutableDictionary dictionary];
+  // Registration is a pure store and is legal before init; it also survives
+  // jl_reset(), so it is done once here.
+  if (jl_set_callback("hostSchedule", (void (*)(void))hostSchedule, NULL) != 0 ||
+      jl_set_callback("hostSettle", (void (*)(void))hostSettle, NULL) != 0 ||
+      jl_set_callback("hostReadFile", (void (*)(void))hostReadFile, NULL) != 0 ||
+      jl_set_callback("hostWriteFile", (void (*)(void))hostWriteFile, NULL) != 0) {
+    NSLog(@"[janela] could not register a host channel");
+  }
+  if (jl_set_callback("janelaEmit", (void (*)(void))emitEvent, NULL) != 0) {
+    NSLog(@"[janela] could not register the event channel — app.emit will trap");
+  }
+  jl_init();
+
+  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
+  self.window.rootViewController = [[JanelaViewController alloc] init];
+  [self.window makeKeyAndVisible];
+  return YES;
+}
+
+@end
+
+int main(int argc, char *argv[]) {
+  @autoreleasepool {
+    return UIApplicationMain(argc, argv, nil, NSStringFromClass([JanelaAppDelegate class]));
+  }
+}

package/templates/janela.conf.json

@@ -6,5 +6,10 @@
     "title": "__NAME__",
     "width": 640,
     "height": 420
+  },
+  "ios": {
+    "identifier": "dev.janela.__NAME__",
+    "displayName": "__NAME__",
+    "minimumVersion": "15.0"
   }
 }

package/templates/react/files/janela.conf.json

@@ -6,5 +6,10 @@
     "title": "__NAME__",
     "width": 640,
     "height": 420
+  },
+  "ios": {
+    "identifier": "dev.janela.__NAME__",
+    "displayName": "__NAME__",
+    "minimumVersion": "15.0"
   }
 }

package/templates/solid/files/janela.conf.json

@@ -6,5 +6,10 @@
     "title": "__NAME__",
     "width": 640,
     "height": 420
+  },
+  "ios": {
+    "identifier": "dev.janela.__NAME__",
+    "displayName": "__NAME__",
+    "minimumVersion": "15.0"
   }
 }

package/templates/svelte/files/janela.conf.json

@@ -6,5 +6,10 @@
     "title": "__NAME__",
     "width": 640,
     "height": 420
+  },
+  "ios": {
+    "identifier": "dev.janela.__NAME__",
+    "displayName": "__NAME__",
+    "minimumVersion": "15.0"
   }
 }

package/templates/vue/files/janela.conf.json

@@ -6,5 +6,10 @@
     "title": "__NAME__",
     "width": 640,
     "height": 420
+  },
+  "ios": {
+    "identifier": "dev.janela.__NAME__",
+    "displayName": "__NAME__",
+    "minimumVersion": "15.0"
   }
 }