janela 0.7.0 → 0.9.0

package/README.md

@@ -141,9 +141,10 @@ framework templates' default.
 import type { JanelaApp } from "janela/host";
 
 export type AppCommands = {
-  add:   { args: { a: number; b: number }; result: number };
-  greet: { args: { name: string };         result: string };
-  wait:  { args: { ms: number };           result: string };
+  add:   (args: { a: number; b: number }) => number;
+  greet: (args: { name: string }) => string;
+  wait:  (args: { ms: number }) => string;
+  quit:  () => void;                        // a command that takes nothing
 };
 export type AppEvents = { added: number };
 
@@ -195,11 +196,23 @@ Two things worth knowing:
   own declarations rather than from an assertion you write by hand, which is
   only possible because both sides are TypeScript.
 
-Write `args: null` for a command that takes nothing — `args: undefined`
-lowers to a zero-parameter function and fails to compile.
+A command that takes nothing is declared `() => void`, and its handler
+returns `null` — every command answers the page's promise with a value, so
+`void` is normalised to `null`. The page calls it as
+`client.invoke("quit", null)`.
 
-The untyped `invoke` / `listen` still work unchanged; the contract is
-additive, and the `vanilla` template still uses the global.
+An **event payload is a single value** of any JSON-shaped type. For an event
+carrying several things, prefer an object (`{ done: number; total: number }`):
+adding a field later does not break existing listeners, and the names read
+better at the call site. A tuple works too, but note that only the payload
+*value* may be a tuple — the varargs spelling `app.emit("progress", 3, 10)`
+does not compile (`SC2011: values of type '[done: number, total: number]'
+have no static representation`, which would require `--dynamic` and ~620 KB
+of embedded engine).
+
+The `{ args; result }` record form of 0.5.x–0.7.x is still accepted, and the
+untyped `invoke` / `listen` still work unchanged; the contract is additive,
+and the `vanilla` template still uses the global.
 
 ## Async commands
 
@@ -266,9 +279,10 @@ in scriptc and can cost far more than the read did.
 **Use `app.sleep`, not `setTimeout`.** scriptc's own event loop is parked for
 as long as the program sits inside the `run()` FFI call, so `setTimeout`,
 `queueMicrotask` and `await` in host code never fire while the window is open
-(they all run after it closes). janela supplies its own loop instead: a native
-ticker posts work to the UI thread via `webview_dispatch`, and it only runs
-while something is queued, so an idle app costs nothing.
+(they all run after it closes). janela schedules through the shell instead: the
+runtime parks a continuation under an id, the shell keeps the clock and calls
+it back on the UI thread when it comes due. Nothing polls, so an idle app
+costs nothing at all.
 
 **Still single-threaded.** scriptc's runtime is not thread-safe (concurrent
 calls from several threads abort the process), so host code always runs on the
@@ -310,6 +324,30 @@ nested modal loop would otherwise re-enter the host loop underneath a live TS
 frame; [docs/native-shell.md](../../docs/native-shell.md) has the details, the
 per-platform table, and the Windows GUI-subsystem note.
 
+## Migrating from 0.7.x
+
+Commands are declared as the functions they are. The old `{ args; result }`
+record form still compiles, so this is optional — but the function form is
+shorter, and a command that takes nothing is finally natural to write.
+
+```ts
+// 0.7.x
+export type AppCommands = {
+  add:  { args: { a: number; b: number }; result: number };
+  quit: { args: null; result: null };
+};
+
+// 0.8.0
+export type AppCommands = {
+  add:  (args: { a: number; b: number }) => number;
+  quit: () => void;
+};
+```
+
+Nothing else changes: `export type App = JanelaApp<AppCommands, AppEvents>`,
+`setup(app: App)`, `app.command(...)` and the page's `createClient<App>()` are
+all as they were. A handler for a `() => void` command returns `null`.
+
 ## Migrating from 0.6.x
 
 The contract lives entirely in the types now, so the runtime tokens are gone.

package/api/index.d.ts

@@ -6,7 +6,7 @@
  * parse.
  */
 
-import type { JanelaApp } from "../runtime/janela";
+import type { JanelaAppImpl } from "../runtime/janela";
 import type { CommandShapes, Commands, Events } from "../runtime/types";
 
 /** Removes a subscription created by `listen` / `client.on`. */
@@ -65,18 +65,22 @@ export interface Contract {
 /**
  * The command table declared by a contract.
  *
- * Reads the contract off a `JanelaApp<C, E>` — what a host's `App` type is
- * from 0.7.0 — and falls back to the 0.5.x/0.6.x `{ commands, events }`
- * wrapper, so a project written against either shape keeps checking.
+ * Reads the contract off the app type — what a host's `App` is from 0.7.0 —
+ * and falls back to the 0.5.x/0.6.x `{ commands, events }` wrapper, so a
+ * project written against either shape keeps checking.
+ *
+ * The inference targets the class rather than the `JanelaApp` alias: the
+ * alias applies `Norm<C>`, which cannot be inferred backwards, and the
+ * normalised table is what indexing wants in any case.
  */
-export type CommandsOf<A> = A extends JanelaApp<infer M, infer _E>
+export type CommandsOf<A> = A extends JanelaAppImpl<infer M, infer _E>
   ? M
   : A extends { commands: Commands<infer M> }
     ? M
     : never;
 
 /** The event table declared by a contract; see CommandsOf for the two shapes. */
-export type EventsOf<A> = A extends JanelaApp<infer _M, infer E>
+export type EventsOf<A> = A extends JanelaAppImpl<infer _M, infer E>
   ? E
   : A extends { events: Events<infer E> }
     ? E

package/bin/janela.mjs

@@ -324,21 +324,21 @@ function ffiManifest(shimLib) {
       returns: "i32",
     },
     {
-      name: "wvOnTick", symbol: "wv_on_tick",
+      name: "wvOnTimer", symbol: "wv_on_timer",
       params: [
         "i32",
-        { callback: { id: "tick", params: [{ context: "tick" }], returns: "void", lifetime: "retained" } },
-        { context: "tick" },
+        { callback: { id: "timer", params: ["i32", { context: "timer" }], returns: "void", lifetime: "retained" } },
+        { context: "timer" },
       ],
       returns: "i32",
     },
     { name: "wvRun", symbol: "wv_run", params: ["i32"], returns: "i32" },
     { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
-    // async: deferred returns + the UI-thread pump behind app.defer/sleep
+    // async: the held-reply table (deferred returns) plus shell-owned
+    // scheduling — TS parks a continuation id, the shell calls it back due.
     { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
     { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
-    { name: "wvTickStart", symbol: "wv_tick_start", params: ["i32", "i32"], returns: "i32" },
-    { name: "wvTickStop", symbol: "wv_tick_stop", params: ["i32"], returns: "i32" },
+    { name: "wvSchedule", symbol: "wv_schedule", params: ["i32", "i32", "i32"], returns: "i32" },
     // async file I/O: the blocking syscall runs on a shim worker thread
     { name: "wvFsRead", symbol: "wv_fs_read", params: ["i32", "string"], returns: "i32" },
     { name: "wvFsWrite", symbol: "wv_fs_write", params: ["i32", "string", "string"], returns: "i32" },
@@ -516,17 +516,19 @@ function build(root, { devUrl = null, gui = true } = {}) {
     join(buildDir, "entry.ts"),
     `// Generated by janela — do not edit.\n` +
       `import { createApp } from "./janela";\n` +
-      `import type { CommandShapes, JanelaApp } from "./janela";\n` +
+      `import type { CommandShapes, JanelaAppImpl } from "./janela";\n` +
       `import { WINDOW } from "./config";\n` +
       `import { INDEX_HTML } from "./frontend";\n` +
       `import { setup } from "./main";\n\n` +
       `// The app's type parameters are read back off setup()'s own signature,\n` +
-      `// so a contract-typed setup(app: JanelaApp<App>) and a plain\n` +
-      `// setup(app: JanelaApp) each get an app instantiated to match. scriptc\n` +
-      `// monomorphises generic classes, so the right instantiation must be\n` +
-      `// CONSTRUCTED here - no cast can bridge JanelaApp<A> and JanelaApp<B>.\n` +
-      `type CmdsOf<F> = F extends (app: JanelaApp<infer C, infer _E>) => void ? C : CommandShapes;\n` +
-      `type EvtsOf<F> = F extends (app: JanelaApp<infer _C, infer E>) => void ? E : Record<string, unknown>;\n\n` +
+      `// so a contract-typed setup(app: App) and a plain setup(app: JanelaApp)\n` +
+      `// each get an app instantiated to match. scriptc monomorphises generic\n` +
+      `// classes, so the right instantiation must be CONSTRUCTED here - no cast\n` +
+      `// can bridge two of them. The inference reads the CLASS, not the\n` +
+      `// JanelaApp alias: the alias applies Norm<C>, which cannot be reversed,\n` +
+      `// 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` +

package/package.json

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

package/runtime/janela.ts

@@ -19,13 +19,12 @@ declare function wvEval(h: number, js: string): number;
 declare function wvBind(h: number, name: string): number;
 declare function wvReply(h: number, body: string): number;
 declare function wvOnInvoke(h: number, cb: (req: string) => number): number;
-declare function wvOnTick(h: number, cb: () => void): number;
+declare function wvOnTimer(h: number, cb: (id: number) => void): number;
 declare function wvRun(h: number): number;
 declare function wvTerminate(h: number): number;
 declare function wvDefer(h: number): number;
 declare function wvResolve(h: number, id: number, status: number): number;
-declare function wvTickStart(h: number, intervalMs: number): number;
-declare function wvTickStop(h: number): number;
+declare function wvSchedule(h: number, id: number, ms: number): number;
 declare function wvFsRead(h: number, path: string): number;
 declare function wvFsWrite(h: number, path: string, data: string): number;
 declare function wvJobStatus(h: number, id: number): number;
@@ -83,11 +82,16 @@ const BOOTSTRAP =
 // 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,
@@ -105,7 +109,9 @@ import type {
   AsyncCommandHandler,
   CommandHandler,
   CommandShapes,
+  CommandSpecs,
   Commands,
+  Norm,
   DialogFilter,
   Events,
   FsCallback,
@@ -141,11 +147,10 @@ function encodeFilters(filters: DialogFilter[] | undefined): string {
 const DRAIN_BUDGET_MS = 4; // = a quarter of a 60fps frame
 const DRAIN_SLICE = 131072; // 128 KB - granularity within the budget
 
-// 8 ms is plenty for timers and task chains, but while a payload is draining
-// the loop does real work every turn, and waiting 8 ms between 4 ms slices
-// would halve throughput for no benefit.
-const TICK_IDLE_MS = 8;
-const TICK_DRAIN_MS = 4;
+// The shell posts this id when a file read or a dialog reaches a terminal
+// state. It is not a continuation - it means "service the jobs you are
+// waiting on". Continuation ids start at 1, so the two can never collide.
+const TIMER_JOBS = -1;
 
 /**
  * A running janela app.
@@ -156,7 +161,7 @@ const TICK_DRAIN_MS = 4;
  * interface (being signature-only) never is. A class receiver works even as a
  * plain function parameter, which is what `setup(app)` is.
  */
-export class JanelaApp<
+export class JanelaAppImpl<
   C extends CommandShapes = CommandShapes,
   E = Record<string, unknown>,
 > {
@@ -164,21 +169,23 @@ export class JanelaApp<
   names: string[] = [];
   handlers: CommandHandler[] = [];
 
-  // ---- the host loop -------------------------------------------------------
+  // ---- scheduling ----------------------------------------------------------
   // scriptc's event loop is parked for as long as the program sits inside the
   // wvRun() FFI call, so setTimeout/await never fire while the window is open.
-  // These queues are drained instead by the retained tick handler that the
-  // shim's ticker posts to the UI thread, and the ticker only runs while there
-  // is work - an idle app costs nothing.
+  // The shell schedules instead: a continuation is parked here under an id and
+  // handed to wvSchedule(), and the shim calls onTimer(id) back on the UI
+  // thread once it comes due. Nothing here polls and nothing wakes
+  // periodically - an idle app is genuinely idle.
+  //
+  // This is the same shape the iOS shell must use, where the compiled TS links
+  // no event loop at all and could not hold a timer even if it wanted to.
   asyncNames: string[] = [];
   asyncHandlers: AsyncCommandHandler[] = [];
-  taskFns: (() => void)[] = [];
-  timerFns: (() => void)[] = [];
-  timerDue: number[] = [];
+  contIds: number[] = [];
+  contFns: (() => void)[] = [];
+  nextCont = 1; // ids start at 1; TIMER_JOBS (-1) is the shell's own
   jobIds: number[] = [];
   jobCbs: FsCallback[] = [];
-  ticking = false;
-  tickMs = TICK_IDLE_MS;
 
   // ---- the drain -----------------------------------------------------------
   // A finished job's bytes still have to be decoded into a TypeScript string,
@@ -187,6 +194,7 @@ export class JanelaApp<
   // decoded a slice at a time, giving the run loop the thread back between
   // slices - total work is unchanged, but no single turn carries much of it.
   drainIds: number[] = [];
+  draining = false; // a drain continuation is already queued
   drainCbs: FsCallback[] = [];
   drainOk: boolean[] = [];
   drainParts: string[][] = [];
@@ -201,37 +209,49 @@ export class JanelaApp<
     wvInit(h, BOOTSTRAP);
   }
 
-  retick(): void {
-    const want = this.drainIds.length > 0 ? TICK_DRAIN_MS : TICK_IDLE_MS;
-    if (!this.ticking || want === this.tickMs) return;
-    this.tickMs = want;
-    wvTickStart(this.handle, want);
-  }
-
-  wake(): void {
-    if (this.ticking) return;
-    this.ticking = true;
-    this.tickMs = this.drainIds.length > 0 ? TICK_DRAIN_MS : TICK_IDLE_MS;
-    wvTickStart(this.handle, this.tickMs);
+  /**
+   * 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, and neither needs to know anything else about the other.
+   */
+  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;
+    // `+ 0` per the note at the top of this file: a bare FFI call is not safe
+    // in every position, and this one is silently dropped without it.
+    const rc = wvSchedule(this.handle, id, delay) + 0;
+    if (rc < 0) console.log("[janela] could not schedule continuation", id);
   }
 
-  idle(): void {
-    if (!this.ticking) return;
-    if (
-      this.taskFns.length > 0 ||
-      this.timerFns.length > 0 ||
-      this.jobIds.length > 0 ||
-      this.drainIds.length > 0
-    ) {
-      return;
+  /** Run the continuation parked under `id`, if it is still waiting. */
+  runCont(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, and a continuation that
+        // throws must not stay parked forever.
+        this.contIds.splice(i, 1);
+        this.contFns.splice(i, 1);
+        fn();
+        return;
+      }
     }
-    this.ticking = false;
-    wvTickStop(this.handle);
   }
 
   // Decode as much of the pending payloads as the budget allows, then yield.
   // Slices are taken from one job at a time so a big read finishes promptly
   // rather than every concurrent read finishing slowly.
+  /**
+   * Decode as much of the pending payloads as the budget allows, then hand the
+   * thread back. If work remains, a zero-delay continuation carries on at the
+   * top of the next turn, so a 100 MB read is spread across frames instead of
+   * freezing one.
+   */
   drainSome(): void {
     if (this.drainIds.length === 0) return;
     const started = Date.now() + 0;
@@ -274,38 +294,39 @@ export class JanelaApp<
         // before starting another payload.
       }
 
-      if (Date.now() - started >= DRAIN_BUDGET_MS) return;
+      if (Date.now() - started >= DRAIN_BUDGET_MS) {
+        this.drainMore();
+        return;
+      }
     }
   }
 
-  // One turn of the loop: every task queued so far, plus every due timer.
-  // Tasks queued *by* this turn wait for the next one, so a defer() chain
-  // yields to the UI between slices instead of starving it.
-  turn(): void {
-    const tasks = this.taskFns;
-    this.taskFns = [];
-    for (let i = 0; i < tasks.length; i++) tasks[i]();
-
-    if (this.timerFns.length > 0) {
-      const now = Date.now() + 0;
-      const keptFns: (() => void)[] = [];
-      const keptDue: number[] = [];
-      const fire: (() => void)[] = [];
-      for (let i = 0; i < this.timerFns.length; i++) {
-        if (this.timerDue[i] <= now) {
-          fire.push(this.timerFns[i]);
-        } else {
-          keptFns.push(this.timerFns[i]);
-          keptDue.push(this.timerDue[i]);
-        }
-      }
-      this.timerFns = keptFns;
-      this.timerDue = keptDue;
-      for (let i = 0; i < fire.length; i++) fire[i]();
+  /** Continue draining on the next turn, without stacking duplicate work. */
+  drainMore(): void {
+    if (this.drainIds.length === 0 || this.draining) return;
+    this.draining = true;
+    this.schedule(0, () => {
+      this.draining = false;
+      this.drainSome();
+    });
+  }
+
+  /**
+   * The shell calls here on the UI thread when something it was holding comes
+   * due: a continuation TS parked (id >= 1), or a job that finished
+   * (TIMER_JOBS). This is the only entry into the loop, and it always lands at
+   * the top of a fresh turn — never underneath a TS frame.
+   */
+  onTimer(id: number): void {
+    if (id !== TIMER_JOBS) {
+      this.runCont(id);
+      return;
     }
+    this.serviceJobs();
+  }
 
-    // Finished file jobs: the worker thread has already done the blocking
-    // syscall, so all that happens on this (UI) thread is the drain.
+  /** A job reached a terminal state: move the finished ones to the drain. */
+  serviceJobs(): void {
     if (this.jobIds.length > 0) {
       const keptIds: number[] = [];
       const keptCbs: FsCallback[] = [];
@@ -339,8 +360,6 @@ export class JanelaApp<
     }
 
     this.drainSome();
-    this.retick();
-    this.idle();
   }
 
   // Both dialog kinds share one path: start the job, then let the same drain
@@ -364,8 +383,7 @@ export class JanelaApp<
       encodeFilters(filters),
     ) + 0;
     if (id < 0) {
-      this.taskFns.push(() => cb(null, "EAGAIN: could not open a dialog"));
-      this.wake();
+      this.defer(() => cb(null, "EAGAIN: could not open a dialog"));
       return;
     }
     this.jobIds.push(id);
@@ -377,7 +395,6 @@ export class JanelaApp<
       // "null" is a cancel; anything else is a JSON array of paths.
       cb(JSON.parse(text) as string[] | null);
     });
-    this.wake();
   }
 
   /**
@@ -420,16 +437,14 @@ export class JanelaApp<
 
   /** Run fn on the next turn of the host loop - the way to slice long work. */
   defer(fn: () => void): void {
-    this.taskFns.push(fn);
-    this.wake();
+    // Zero delay: the shell posts straight to the next turn, no timer at all.
+    this.schedule(0, fn);
   }
 
-  /** Run fn after at least ms. The host loop's timer; scriptc's setTimeout
+  /** Run fn after at least ms. The shell owns the clock; scriptc's setTimeout
    *  cannot fire while the window is open (its loop is parked inside run()). */
   sleep(ms: number, fn: () => void): void {
-    this.timerFns.push(fn);
-    this.timerDue.push(Date.now() + (ms > 0 ? ms : 0));
-    this.wake();
+    this.schedule(ms, fn);
   }
 
   /**
@@ -444,7 +459,6 @@ export class JanelaApp<
     }
     this.jobIds.push(id);
     this.jobCbs.push(cb);
-    this.wake();
   }
 
   /** Write a file without blocking the window; cb(null) on success. */
@@ -458,7 +472,6 @@ export class JanelaApp<
     // The write payload is empty on success; the shared callback shape just
     // ignores the text argument.
     this.jobCbs.push((err, _text) => cb(err));
-    this.wake();
   }
 
   /** Show the native "open" dialog; cb gets the paths, or null on cancel. */
@@ -524,8 +537,8 @@ export class JanelaApp<
     const h = this.handle;
     // Both handlers are retained: registered once here, called by the shim
     // for as long as the window is open.
-    wvOnTick(h, () => {
-      this.turn();
+    wvOnTimer(h, (id) => {
+      this.onTimer(id);
     });
     wvOnInvoke(h, (req) => {
       const env = JSON.parse(req) as string[];
@@ -571,11 +584,34 @@ export class JanelaApp<
   }
 }
 
+/**
+ * A running janela app, typed by the contract it serves.
+ *
+ * This is an alias rather than the class itself so that a contract may be
+ * written as plain function types: `Norm` converts it to the record form the
+ * class indexes, at a point where the table is still concrete. Writing the
+ * record form directly keeps working — `Norm` is idempotent.
+ *
+ * ```ts
+ * export type AppCommands = { add: (args: { a: number; b: number }) => number };
+ * export type AppEvents = { added: number };
+ * export type App = JanelaApp<AppCommands, AppEvents>;
+ *
+ * export function setup(app: App): void {
+ *   app.command("add", (args) => args.a + args.b);   // args inferred, result checked
+ * }
+ * ```
+ */
+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): JanelaApp<C, E> {
-  return new JanelaApp<C, E>(cfg);
+>(cfg: WindowConfig): JanelaAppImpl<C, E> {
+  return new JanelaAppImpl<C, E>(cfg);
 }
 
 // ---------------------------------------------------------------------------
@@ -586,7 +622,7 @@ export function createApp<
 
 /** @deprecated Use `app.command(name, handler)` on a contract-typed app. */
 export function on<M extends CommandShapes, K extends keyof M & string>(
-  app: JanelaApp,
+  app: JanelaAppImpl,
   _commands: Commands<M>,
   name: K,
   handler: (args: M[K]["args"]) => M[K]["result"],
@@ -596,7 +632,7 @@ export function on<M extends CommandShapes, K extends keyof M & string>(
 
 /** @deprecated Use `app.commandAsync(name, handler)` on a contract-typed app. */
 export function onAsync<M extends CommandShapes, K extends keyof M & string>(
-  app: JanelaApp,
+  app: JanelaAppImpl,
   _commands: Commands<M>,
   name: K,
   handler: (
@@ -615,7 +651,7 @@ export function onAsync<M extends CommandShapes, K extends keyof M & string>(
 
 /** @deprecated Use `app.emit(event, payload)` on a contract-typed app. */
 export function emit<E, K extends keyof E & string>(
-  app: JanelaApp,
+  app: JanelaAppImpl,
   _events: Events<E>,
   name: K,
   payload: E[K],

package/runtime/types.ts

@@ -90,15 +90,78 @@ export interface WindowConfig {
 // tokens and their `define*` constructors are the 0.5.x/0.6.x shape, kept so
 // projects written against it still compile.
 
-/** One command's argument and result types. */
+/**
+ * One command's argument and result types, in normalised form.
+ *
+ * This is what the app class works with internally. A contract is *written*
+ * as plain function types — see CommandSpec — and normalised to this by
+ * `Norm` before it reaches the class.
+ */
 export interface CommandShape {
   args: unknown;
   result: unknown;
 }
 
-/** A contract's command table: name → shape. */
+/** A normalised command table: name → shape. */
 export type CommandShapes = Record<string, CommandShape>;
 
+/**
+ * How a command may be declared in a contract: as a plain function type
+ * (preferred), or as the `{ args; result }` record of 0.5.x–0.7.x.
+ *
+ * ```ts
+ * type AppCommands = {
+ *   add: (args: { a: number; b: number }) => number;
+ *   quit: () => void;                                    // no arguments
+ *   legacy: { args: { name: string }; result: string };  // still accepted
+ * };
+ * ```
+ */
+export type CommandSpec = ((...args: never[]) => unknown) | CommandShape;
+
+/** A contract's command table as written: name → spec. */
+export type CommandSpecs = Record<string, CommandSpec>;
+
+/**
+ * The argument type of a declared command. A function's single parameter, or
+ * a record's `args`. A command declared with no parameters takes `null` — the
+ * page's `invoke(name)` sends null, and nothing is lost.
+ */
+export type ArgsOf<F> = F extends (...a: infer P) => unknown
+  ? P extends [infer A]
+    ? A
+    : null
+  : F extends { args: infer A }
+    ? A
+    : null;
+
+/**
+ * The result type of a declared command. `void` is normalised to `null`:
+ * every command answers the page's promise with a value, and scriptc has no
+ * conversion from a void value to the `unknown` the handler table holds.
+ */
+export type ResultOf<F> = F extends (...a: never[]) => infer R
+  ? [R] extends [void]
+    ? null
+    : R
+  : F extends { result: infer R }
+    ? R
+    : never;
+
+/**
+ * Normalise a written contract to the record form the app class indexes.
+ *
+ * This runs where `C` is still concrete — in the `JanelaApp<C, E>` alias, one
+ * step before the class — on purpose. scriptc cannot compile a *value* whose
+ * type is an unresolved conditional or a mapped type indexed by a type
+ * parameter (`SC2001: values of type 'ArgsOf<C[K]>' cannot be compiled yet`),
+ * so the class body only ever sees plain indexed access on a record.
+ * Idempotent: normalising a record-form table returns it unchanged.
+ */
+export type Norm<C> = {
+  [K in keyof C]: { args: ArgsOf<C[K]>; result: ResultOf<C[K]> };
+};
+
 /**
  * A declared command contract. Carries `M` at the type level only — the value
  * is empty, and exists so that inference has something to read at a call site.
@@ -119,7 +182,7 @@ export interface Events<E> {
  * types and name the app itself:
  *
  * ```ts
- * export type AppCommands = { add: { args: { a: number; b: number }; result: number } };
+ * export type AppCommands = { add: (args: { a: number; b: number }) => number };
  * export type AppEvents = { added: number };
  * export type App = JanelaApp<AppCommands, AppEvents>;
  * export function setup(app: App): void { … }

package/shim/wvshim.cc

@@ -8,15 +8,22 @@
 //   * format 3 — callback params may be `string`/`bytes`, so a payload crosses
 //     into TS as one argument instead of one FFI call per byte. Payloads going
 //     the other way ride `string` params on ordinary functions.
-//   * format 4 — callbacks may be `retained`, so the invoke and tick handlers
+//   * format 4 — callbacks may be `retained`, so the invoke and timer handlers
 //     are registered once and live for the app's lifetime. wv_run() is a plain
 //     blocking call again; it no longer has to carry a callback whose "call
 //     scope" was standing in for "app lifetime".
+//
+// The shell owns scheduling. TS never holds a timer: it registers a
+// continuation under an id and calls wv_schedule(), and this shim calls back
+// into TS with that id once the delay is up. That is the same shape a library
+// -mode host (iOS) must use, where the compiled TS links no event loop at all.
 
 #include "webview.h"
 
+#include <algorithm>
 #include <atomic>
 #include <chrono>
+#include <condition_variable>
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
@@ -50,6 +57,13 @@ struct Pending {
   std::string call_id;
 };
 
+// A continuation TS has parked with the shell: run whatever TS registered
+// under `id` once `due` has passed. The shell owns the clock; TS owns the id.
+struct Timer {
+  int32_t id;
+  std::chrono::steady_clock::time_point due;
+};
+
 struct App {
   webview_t w = nullptr;
   bool used = false;
@@ -59,8 +73,8 @@ struct App {
   // request rides in as a (ptr, len) string param.
   int32_t (*on_invoke)(const uint8_t *, size_t, void *) = nullptr;
   void *on_invoke_ctx = nullptr;
-  void (*on_tick)(void *) = nullptr;
-  void *on_tick_ctx = nullptr;
+  void (*on_timer)(int32_t, void *) = nullptr;
+  void *on_timer_ctx = nullptr;
 
   // Staging for the in-flight request.
   std::string req;      // JSON args array from JS
@@ -69,13 +83,26 @@ struct App {
   uint32_t seq = 0;
 
   // ---- async support ----
-  std::vector<Pending> pending;  // deferred invokes, addressed by index
-  bool deferred = false;         // set by wv_defer() during the current call
-  std::thread ticker;            // pure-C++ thread; never touches TS itself
-  std::atomic<bool> ticking{false};
-  std::atomic<int32_t> tick_ms{16};
+  // The held-reply table: an invoke whose answer is not ready yet. The page's
+  // promise stays unsettled until wv_resolve() answers this call id.
+  std::vector<Pending> pending;
+  bool deferred = false;  // set by wv_defer() during the current call
+
+  // The shell's timer queue, and the one thread that watches it. The thread
+  // only sleeps and posts — it never touches TS, because scriptc's runtime is
+  // not thread-safe. Everything reaches TS through webview_dispatch, on the UI
+  // thread, on a LATER turn of the shell's own loop (see timer_on_ui_thread).
+  std::vector<Timer> timers;
+  std::mutex timers_mu;
+  std::condition_variable timers_cv;
+  std::thread scheduler;
+  std::atomic<bool> scheduling{false};
 };
 
+// Reserved timer id: not a TS continuation but "a job changed state, service
+// them". TS allocates its own continuation ids from 1 upwards.
+const int32_t TIMER_JOBS = -1;
+
 // Fixed-size table: handles are indices, never pointers.
 App g_apps[8];
 
@@ -92,8 +119,9 @@ std::string to_str(const uint8_t *p, size_t n) {
 // ---- jobs ------------------------------------------------------------------
 //
 // A job is any unit of work whose answer cannot be produced during the FFI
-// call that asks for it. TS starts one, gets an id back immediately, and polls
-// wv_job_status() from its tick loop until the job is terminal.
+// call that asks for it. TS starts one and gets an id back immediately; when
+// the job reaches a terminal state it posts TIMER_JOBS to the UI thread, and
+// TS then reads wv_job_status() for the jobs it is waiting on.
 //
 // Two kinds use this pool, for opposite reasons:
 //   * file I/O — the blocking syscall must happen off the UI thread, so a
@@ -102,9 +130,9 @@ std::string to_str(const uint8_t *p, size_t n) {
 //     later, on the UI thread.
 //   * native dialogs — the modal must run ON the UI thread, but not while TS
 //     is on the stack (runModal/gtk_dialog_run spin a nested event loop, which
-//     would re-enter the tick handler underneath the invoke handler that asked
-//     for the dialog). So the job is posted with webview_dispatch and runs at
-//     the top of a later turn, with no TS frame beneath it.
+//     would re-enter TS underneath the invoke handler that asked for the
+//     dialog). So the job is posted with webview_dispatch and runs at the top
+//     of a later turn, with no TS frame beneath it.
 
 const int32_t JOB_PENDING = 0;
 const int32_t JOB_OK = 1;
@@ -119,6 +147,9 @@ struct Job {
   std::string data;  // payload on success, the error message on failure
   std::thread worker;  // unused by dialog jobs, which run on the UI thread
   bool used = false;
+  // Which app to wake when this job finishes. Without the ticker there is
+  // nothing polling, so a finished job has to announce itself.
+  int32_t app = -1;
 };
 
 // Jobs are addressed by index and held behind unique_ptr so the vector may
@@ -135,7 +166,7 @@ Job *job_at(int32_t id) {
 
 // Reuses a finished slot when one is free, so a long-running app that reads
 // many files does not grow the table without bound.
-int32_t new_job() {
+int32_t new_job(int32_t app) {
   std::lock_guard<std::mutex> lock(g_jobs_mu);
   for (size_t i = 0; i < g_jobs.size(); i++) {
     if (g_jobs[i]->used) continue;
@@ -143,10 +174,12 @@ int32_t new_job() {
     g_jobs[i]->status.store(JOB_PENDING);
     g_jobs[i]->data.clear();
     g_jobs[i]->used = true;
+    g_jobs[i]->app = app;
     return static_cast<int32_t>(i);
   }
   g_jobs.push_back(std::unique_ptr<Job>(new Job()));
   g_jobs.back()->used = true;
+  g_jobs.back()->app = app;
   return static_cast<int32_t>(g_jobs.size() - 1);
 }
 
@@ -166,9 +199,18 @@ std::string fs_error_message(const std::string &path, const char *op) {
   return "EIO: failed to " + std::string(op) + " '" + path + "'";
 }
 
+// Defined below, once the app table is in scope. Posts `id` to the app's UI
+// thread via webview_dispatch, so TS is entered on a later turn of the shell's
+// own loop and never underneath a frame it is already inside.
+void post_timer(int32_t app, int32_t id);
+
 void job_finish(Job *j, int32_t status, std::string payload) {
   j->data = std::move(payload);
   j->status.store(status, std::memory_order_release);
+  // Nothing polls any more, so a finished job announces itself. Safe from a
+  // worker thread: webview_dispatch is the documented cross-thread hand-off,
+  // and it only queues — TS runs later, on the UI thread.
+  if (j->app >= 0) post_timer(j->app, TIMER_JOBS);
 }
 
 void fs_read_worker(Job *j, std::string path) {
@@ -614,18 +656,67 @@ void trampoline(const char *id, const char *req, void *arg) {
   webview_return(a->w, a->cur_id.c_str(), status,
                  a->reply.empty() ? "null" : a->reply.c_str());
   // wv_defer() treats a non-empty cur_id as "an invoke is in flight". Clearing
-  // it here means a defer from anywhere else — a tick, say — fails with -1
+  // it here means a defer from anywhere else — a timer, say — fails with -1
   // instead of stealing this already-answered call's id.
   a->cur_id.clear();
 }
 
-// Runs on the UI thread (posted by the ticker via webview_dispatch), so the
-// TS it calls stays single-threaded — scriptc's runtime is NOT thread-safe.
-void tick_on_ui_thread(webview_t, void *arg) {
-  App *a = &g_apps[reinterpret_cast<uintptr_t>(arg)];
-  if (!a->used || !a->on_tick) return;  // app quit between dispatch and delivery
+// The app index and the timer id, packed into the single void* that
+// webview_dispatch carries.
+void *pack_timer(int32_t app, int32_t id) {
+  uintptr_t packed = (static_cast<uintptr_t>(static_cast<uint32_t>(app)) << 32) |
+                     static_cast<uint32_t>(id);
+  return reinterpret_cast<void *>(packed);
+}
+
+// Runs on the UI thread, posted via webview_dispatch, so the TS it calls stays
+// single-threaded — scriptc's runtime is NOT thread-safe.
+//
+// This is also the one place that guarantees the shell never re-enters TS from
+// inside a frame TS is already in. Everything that wants to reach TS — a due
+// timer, a finished file read, a dismissed dialog — goes through a dispatch
+// and therefore lands at the top of a later turn, with no TS beneath it. That
+// rule is invisible when broken: a violating host gets correct-looking results
+// right up until it doesn't, so it is kept by construction, not by testing.
+void timer_on_ui_thread(webview_t, void *arg) {
+  uintptr_t packed = reinterpret_cast<uintptr_t>(arg);
+  App *a = &g_apps[packed >> 32];
+  int32_t id = static_cast<int32_t>(static_cast<uint32_t>(packed & 0xffffffffu));
+  if (!a->used || !a->on_timer) return;  // app quit between dispatch and delivery
   a->seq++;
-  a->on_tick(a->on_tick_ctx);
+  a->on_timer(id, a->on_timer_ctx);
+}
+
+void post_timer(int32_t app, int32_t id) {
+  if (app < 0 || app >= 8) return;
+  App *a = &g_apps[app];
+  if (!a->used || !a->w) return;
+  webview_dispatch(a->w, timer_on_ui_thread, pack_timer(app, id));
+}
+
+// The scheduler thread: sleep until the earliest timer is due, hand its id to
+// the UI thread, repeat. It never touches TS and holds no TS state.
+void scheduler_loop(App *a, int32_t h) {
+  std::unique_lock<std::mutex> lk(a->timers_mu);
+  while (a->scheduling.load()) {
+    if (a->timers.empty()) {
+      a->timers_cv.wait(lk);
+      continue;
+    }
+    auto soonest = std::min_element(
+        a->timers.begin(), a->timers.end(),
+        [](const Timer &x, const Timer &y) { return x.due < y.due; });
+    auto due = soonest->due;
+    if (due > std::chrono::steady_clock::now()) {
+      a->timers_cv.wait_until(lk, due);
+      continue;  // re-check: an earlier timer may have arrived meanwhile
+    }
+    int32_t id = soonest->id;
+    a->timers.erase(soonest);
+    lk.unlock();
+    post_timer(h, id);
+    lk.lock();
+  }
 }
 
 }  // namespace
@@ -642,16 +733,16 @@ int32_t wv_create(int32_t debug) {
     g_apps[i].binds.clear();
     g_apps[i].on_invoke = nullptr;
     g_apps[i].on_invoke_ctx = nullptr;
-    g_apps[i].on_tick = nullptr;
-    g_apps[i].on_tick_ctx = nullptr;
+    g_apps[i].on_timer = nullptr;
+    g_apps[i].on_timer_ctx = nullptr;
     g_apps[i].req.clear();
     g_apps[i].cur_id.clear();
     g_apps[i].reply.clear();
     g_apps[i].seq = 0;
     g_apps[i].pending.clear();
     g_apps[i].deferred = false;
-    g_apps[i].ticking.store(false);
-    g_apps[i].tick_ms.store(16);
+    g_apps[i].scheduling.store(false);
+    g_apps[i].timers.clear();
     g_apps[i].w = w;
     g_apps[i].used = true;
     return i;
@@ -723,8 +814,8 @@ int32_t wv_reply(int32_t h, const uint8_t *p, size_t n) {
 // call, and wv_run() is one such call for the app's whole life — so setTimeout
 // and promise continuations in TS never fire while the window is open. These
 // four functions supply the missing loop: TS may postpone an invoke's answer
-// (wv_defer), answer it later (wv_resolve), and get called back periodically
-// on the UI thread to make progress (wv_tick_start / wv_tick_stop).
+// (wv_defer), answer it later (wv_resolve), and park a continuation with the
+// shell to be called back on the UI thread when it comes due (wv_schedule).
 
 // Postpone the answer to the invoke being handled right now. Returns a
 // pending id to hand back to wv_resolve(), or -1 outside a bind callback.
@@ -759,43 +850,60 @@ int32_t wv_resolve(int32_t h, int32_t id, int32_t status) {
   return 0;
 }
 
-// Start pumping the retained tick handler every interval_ms. The thread
-// itself only sleeps and posts; all TS execution happens on the UI thread.
-int32_t wv_tick_start(int32_t h, int32_t interval_ms) {
+// Ask the shell to call the retained timer handler with `id` after `ms`.
+//
+// This is the whole of scheduling: TS keeps the continuation, the shell keeps
+// the clock. A zero delay is not a special case — it posts on the next turn of
+// the loop, which is exactly what app.defer() wants, with no timer involved.
+//
+// An idle app now costs nothing at all: with no timers queued the scheduler
+// thread blocks on a condition variable rather than waking every few
+// milliseconds to find nothing to do.
+int32_t wv_schedule(int32_t h, int32_t id, int32_t ms) {
   App *a = app_at(h);
   if (!a) return -1;
-  a->tick_ms = interval_ms > 0 ? interval_ms : 16;
-  if (a->ticking.exchange(true)) return 0;  // already running
-  uintptr_t idx = static_cast<uintptr_t>(h);
-  a->ticker = std::thread([a, idx]() {
-    while (a->ticking.load()) {
-      std::this_thread::sleep_for(
-          std::chrono::milliseconds(a->tick_ms.load()));
-      if (!a->ticking.load()) break;
-      webview_dispatch(a->w, tick_on_ui_thread, reinterpret_cast<void *>(idx));
+
+  // Zero delay skips the queue: there is nothing to wait for, and posting
+  // straight to the UI thread keeps a defer() chain as short as possible.
+  if (ms <= 0) {
+    post_timer(h, id);
+    return 0;
+  }
+
+  {
+    std::lock_guard<std::mutex> lock(a->timers_mu);
+    a->timers.push_back(
+        Timer{id, std::chrono::steady_clock::now() +
+                      std::chrono::milliseconds(ms)});
+    if (!a->scheduling.exchange(true)) {
+      a->scheduler = std::thread(scheduler_loop, a, h);
     }
-  });
+  }
+  a->timers_cv.notify_one();
   return 0;
 }
 
-int32_t wv_tick_stop(int32_t h) {
-  App *a = app_at(h);
-  if (!a) return -1;
-  if (!a->ticking.exchange(false)) return 0;
-  if (a->ticker.joinable()) a->ticker.join();
-  return 0;
+// Stop the scheduler thread and drop any timers that never came due. Called on
+// the way out of wv_run(), so nothing can reach TS after the window closes.
+void stop_scheduler(App *a) {
+  if (!a->scheduling.exchange(false)) return;
+  a->timers_cv.notify_all();
+  if (a->scheduler.joinable()) a->scheduler.join();
+  std::lock_guard<std::mutex> lock(a->timers_mu);
+  a->timers.clear();
 }
 
 // ---- async file I/O ---------------------------------------------------------
 //
 // wv_fs_read/wv_fs_write start a worker thread and return immediately with a
-// job id. TS polls wv_job_status() from its tick loop and drains the payload
+// job id. TS is woken with TIMER_JOBS when it finishes, reads wv_job_status()
+// and drains the payload
 // with wv_fs_byte() once the job is terminal. On failure the payload is the
 // error message, so success and failure share one drain path.
 
 int32_t wv_fs_read(int32_t h, const uint8_t *p, size_t n) {
   if (!app_at(h)) return -1;
-  int32_t id = new_job();
+  int32_t id = new_job(h);
   Job *j = job_at(id);
   if (!j) return -1;
   j->worker = std::thread(fs_read_worker, j, to_str(p, n));
@@ -805,7 +913,7 @@ int32_t wv_fs_read(int32_t h, const uint8_t *p, size_t n) {
 int32_t wv_fs_write(int32_t h, const uint8_t *p, size_t n, const uint8_t *dp,
                     size_t dn) {
   if (!app_at(h)) return -1;
-  int32_t id = new_job();
+  int32_t id = new_job(h);
   Job *j = job_at(id);
   if (!j) return -1;
   j->worker = std::thread(fs_write_worker, j, to_str(p, n), to_str(dp, dn));
@@ -906,7 +1014,7 @@ int32_t wv_dialog(int32_t h, int32_t kind, int32_t flags, const uint8_t *tp,
                   size_t nn, const uint8_t *fp, size_t fn) {
   App *a = app_at(h);
   if (!a) return -1;
-  int32_t id = new_job();
+  int32_t id = new_job(h);
   Job *j = job_at(id);
   if (!j) return -1;
 
@@ -994,12 +1102,13 @@ int32_t wv_on_invoke(int32_t h,
   return 0;
 }
 
-// Register the retained handler the ticker pumps on the UI thread.
-int32_t wv_on_tick(int32_t h, void (*cb)(void *), void *ctx) {
+// Register the retained handler the shell calls when a scheduled id comes due
+// (and with TIMER_JOBS when a file read or dialog finishes).
+int32_t wv_on_timer(int32_t h, void (*cb)(int32_t, void *), void *ctx) {
   App *a = app_at(h);
   if (!a) return -1;
-  a->on_tick = cb;
-  a->on_tick_ctx = ctx;
+  a->on_timer = cb;
+  a->on_timer_ctx = ctx;
   return 0;
 }
 
@@ -1009,11 +1118,10 @@ int32_t wv_run(int32_t h) {
   if (!a) return -1;
   int rc = webview_run(a->w);
   // Nothing may call into TS once run() has returned.
-  a->ticking.store(false);
-  if (a->ticker.joinable()) a->ticker.join();
+  stop_scheduler(a);
   jobs_join_all();  // nor may an in-flight read outlive the app
   a->on_invoke = nullptr;
-  a->on_tick = nullptr;
+  a->on_timer = nullptr;
   return rc;
 }
 
@@ -1026,8 +1134,7 @@ int32_t wv_terminate(int32_t h) {
 int32_t wv_destroy(int32_t h) {
   App *a = app_at(h);
   if (!a) return -1;
-  a->ticking.store(false);
-  if (a->ticker.joinable()) a->ticker.join();
+  stop_scheduler(a);
   webview_destroy(a->w);
   a->used = false;
   a->w = nullptr;

package/templates/react/files/src-host/main.ts

@@ -9,19 +9,18 @@
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
 //     wrap it in any expression (`+ 0`);
-//   - write `args: null` for a command that takes nothing, not `undefined` —
-//     an `undefined` argument lowers to a zero-parameter function and fails
-//     to compile.
+//   - a command that returns nothing is declared `() => void` and its handler
+//     returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 
 /** Every command this app answers. Declared once; the page checks against it. */
 export type AppCommands = {
-  add: { args: { a: number; b: number }; result: number };
-  greet: { args: { name: string }; result: string };
-  log: { args: string; result: null };
-  wait: { args: { ms: number }; result: string };
-  quit: { args: null; result: null };
+  add: (args: { a: number; b: number }) => number;
+  greet: (args: { name: string }) => string;
+  log: (args: string) => void;
+  wait: (args: { ms: number }) => string;
+  quit: () => void;
 };
 
 /** Every event this app emits, and what each one carries. */

package/templates/solid/files/src-host/main.ts

@@ -9,19 +9,18 @@
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
 //     wrap it in any expression (`+ 0`);
-//   - write `args: null` for a command that takes nothing, not `undefined` —
-//     an `undefined` argument lowers to a zero-parameter function and fails
-//     to compile.
+//   - a command that returns nothing is declared `() => void` and its handler
+//     returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 
 /** Every command this app answers. Declared once; the page checks against it. */
 export type AppCommands = {
-  add: { args: { a: number; b: number }; result: number };
-  greet: { args: { name: string }; result: string };
-  log: { args: string; result: null };
-  wait: { args: { ms: number }; result: string };
-  quit: { args: null; result: null };
+  add: (args: { a: number; b: number }) => number;
+  greet: (args: { name: string }) => string;
+  log: (args: string) => void;
+  wait: (args: { ms: number }) => string;
+  quit: () => void;
 };
 
 /** Every event this app emits, and what each one carries. */

package/templates/svelte/files/src-host/main.ts

@@ -9,19 +9,18 @@
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
 //     wrap it in any expression (`+ 0`);
-//   - write `args: null` for a command that takes nothing, not `undefined` —
-//     an `undefined` argument lowers to a zero-parameter function and fails
-//     to compile.
+//   - a command that returns nothing is declared `() => void` and its handler
+//     returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 
 /** Every command this app answers. Declared once; the page checks against it. */
 export type AppCommands = {
-  add: { args: { a: number; b: number }; result: number };
-  greet: { args: { name: string }; result: string };
-  log: { args: string; result: null };
-  wait: { args: { ms: number }; result: string };
-  quit: { args: null; result: null };
+  add: (args: { a: number; b: number }) => number;
+  greet: (args: { name: string }) => string;
+  log: (args: string) => void;
+  wait: (args: { ms: number }) => string;
+  quit: () => void;
 };
 
 /** Every event this app emits, and what each one carries. */

package/templates/vue/files/src-host/main.ts

@@ -9,19 +9,18 @@
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
 //     wrap it in any expression (`+ 0`);
-//   - write `args: null` for a command that takes nothing, not `undefined` —
-//     an `undefined` argument lowers to a zero-parameter function and fails
-//     to compile.
+//   - a command that returns nothing is declared `() => void` and its handler
+//     returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 
 /** Every command this app answers. Declared once; the page checks against it. */
 export type AppCommands = {
-  add: { args: { a: number; b: number }; result: number };
-  greet: { args: { name: string }; result: string };
-  log: { args: string; result: null };
-  wait: { args: { ms: number }; result: string };
-  quit: { args: null; result: null };
+  add: (args: { a: number; b: number }) => number;
+  greet: (args: { name: string }) => string;
+  log: (args: string) => void;
+  wait: (args: { ms: number }) => string;
+  quit: () => void;
 };
 
 /** Every event this app emits, and what each one carries. */