janela 0.6.0 → 0.8.0

package/README.md

@@ -138,22 +138,21 @@ framework templates' default.
 
 ```ts
 // src-host/main.ts
-import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+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 };
 
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
-
-export type App = { commands: typeof commands; events: typeof events };
+/** The app, carrying its contract. This is what the page imports. */
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 // Typing the app with the contract is what makes the methods below checked.
-export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+export function setup(app: App): void {
   app.command("add", (args) => {            // args inferred: { a: number; b: number }
     app.emit("added", args.a + args.b);     // event name and payload checked
     return args.a + args.b;                 // return type checked against the contract
@@ -197,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)`.
+
+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 untyped `invoke` / `listen` still work unchanged; the contract is
-additive, and the `vanilla` template still uses the global.
+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
 
@@ -312,6 +323,61 @@ 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.
+Name the app instead of wrapping its two tables:
+
+```ts
+// before (0.6.x)
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+export type App = { commands: typeof commands; events: typeof events };
+
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void { … }
+
+// after (0.7.x)
+import type { JanelaApp } from "janela/host";
+
+export type App = JanelaApp<AppCommands, AppEvents>;
+
+export function setup(app: App): void { … }
+```
+
+`AppCommands` and `AppEvents` are unchanged, and so is every page: the
+frontend still writes `createClient<App>()` and `client.invoke(...)`, because
+`createClient` reads the contract off either shape.
+
+`defineCommands` and `defineEvents` still exist and still work — they are
+`@deprecated` no-ops that only ever carried types — so a 0.6.x project keeps
+compiling and running untouched.
+
 ## Migrating from 0.5.x
 
 The contract now rides on the app itself, so the standalone registrars are no
@@ -333,14 +399,13 @@ export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
 }
 ```
 
-Declare each contract as a named type so the same one feeds `defineCommands`
-and the `setup` signature:
+Declare each contract as a named type and hand both to the app (0.7.x drops
+the `defineCommands` / `defineEvents` tokens entirely — see above):
 
 ```ts
 export type AppCommands = { add: { args: { a: number; b: number }; result: number } };
 export type AppEvents = { added: number };
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
+export type App = JanelaApp<AppCommands, AppEvents>;
 ```
 
 `on`, `onAsync` and `emit` still work — they are `@deprecated` one-line
@@ -358,9 +423,11 @@ Two things are new:
 
 - `listen()` (and the injected `janela.listen`) now **return a disposer**.
   Previously they returned nothing, so existing code is unaffected.
-- The **typed contract** — `defineCommands` / `defineEvents` on the host,
+- The **typed contract** — a contract-typed app on the host,
   `createClient<App>()` on the page. The framework templates now scaffold with
-  it. See [The typed contract](#the-typed-contract).
+  it. See [The typed contract](#the-typed-contract). (0.4.x shipped this with
+  `defineCommands` / `defineEvents` tokens; 0.7.x replaced them with the `App`
+  type alias below, and the tokens are deprecated but still work.)
 
 To adopt it in an existing app, declare what the host already exposes and swap
 the registrations:
@@ -373,10 +440,11 @@ app.command("add", (args) => {
 });
 
 // after
-export const commands = defineCommands<{
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
-}>();
-export type App = { commands: typeof commands; events: typeof events };
+};
+export type AppEvents = { added: number };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 app.command("add", (args) => args.a + args.b);   // args inferred, no cast
 ```

package/api/index.d.ts

@@ -6,6 +6,7 @@
  * parse.
  */
 
+import type { JanelaAppImpl } from "../runtime/janela";
 import type { CommandShapes, Commands, Events } from "../runtime/types";
 
 /** Removes a subscription created by `listen` / `client.on`. */
@@ -50,17 +51,40 @@ export declare function listen<T = unknown>(
 // Typed contract
 // ---------------------------------------------------------------------------
 
-/** Anything shaped like a host contract module's exported `App` type. */
+/**
+ * Anything shaped like a host contract module's exported `App` type.
+ *
+ * @deprecated The `{ commands, events }` wrapper of 0.5.x/0.6.x. Export
+ * `type App = JanelaApp<AppCommands, AppEvents>` instead.
+ */
 export interface Contract {
   commands: Commands<CommandShapes>;
   events: Events<unknown>;
 }
 
-/** The command table declared by a contract. */
-export type CommandsOf<A> = A extends { commands: Commands<infer M> } ? M : never;
+/**
+ * The command table declared by a contract.
+ *
+ * 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 JanelaAppImpl<infer M, infer _E>
+  ? M
+  : A extends { commands: Commands<infer M> }
+    ? M
+    : never;
 
-/** The event table declared by a contract. */
-export type EventsOf<A> = A extends { events: Events<infer E> } ? E : never;
+/** The event table declared by a contract; see CommandsOf for the two shapes. */
+export type EventsOf<A> = A extends JanelaAppImpl<infer _M, infer E>
+  ? E
+  : A extends { events: Events<infer E> }
+    ? E
+    : never;
 
 /**
  * A client bound to a host contract: command names, argument shapes, result
@@ -89,7 +113,7 @@ export interface JanelaClient<A> {
  * Build a client checked against a host's contract.
  *
  * ```ts
- * import type { App } from "../src-host/main";
+ * import type { App } from "../src-host/main";   // App = JanelaApp<Cmds, Evts>
  * const client = createClient<App>();
  * const sum = await client.invoke("add", { a: 2, b: 40 });   // number
  * const off = client.on("added", (v) => console.log(v));      // v: number

package/bin/janela.mjs

@@ -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.6.0",
+  "version": "0.8.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

package/runtime/janela.ts

@@ -83,11 +83,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 +110,9 @@ import type {
   AsyncCommandHandler,
   CommandHandler,
   CommandShapes,
+  CommandSpecs,
   Commands,
+  Norm,
   DialogFilter,
   Events,
   FsCallback,
@@ -156,7 +163,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>,
 > {
@@ -571,11 +578,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 +616,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 +626,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 +645,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

@@ -85,21 +85,83 @@ export interface WindowConfig {
 // Payloads still cross as JSON, so these types are compile-time only. Nothing
 // validates a malformed payload at runtime.
 //
-// SHAPE NOTE: the registrars below are standalone generic FUNCTIONS taking the
-// contract as a value, rather than methods on a returned registrar object.
-// That is not a style choice — scriptc cannot dispatch a generic method
-// through an interface-typed receiver (SC1090), so `commands.on(...)` does not
-// compile in a host build, while `on(app, commands, ...)` does.
+// The contract is carried by the app's own type — `JanelaApp<Commands, Events>`
+// — so the tables below are types and nothing more. The `Commands`/`Events`
+// 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.
@@ -116,17 +178,25 @@ export interface Events<E> {
 /**
  * Declare the commands a host exposes.
  *
+ * @deprecated The contract needs no runtime token. Declare the tables as
+ * types and name the app itself:
+ *
  * ```ts
- * export const commands = defineCommands<{
- *   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 { … }
  * ```
  */
 export function defineCommands<M extends CommandShapes>(): Commands<M> {
   return {};
 }
 
-/** Declare the events a host emits: `defineEvents<{ added: number }>()`. */
+/**
+ * Declare the events a host emits: `defineEvents<{ added: number }>()`.
+ *
+ * @deprecated Pass the event table to `JanelaApp` instead — see defineCommands.
+ */
 export function defineEvents<E>(): Events<E> {
   return {};
 }

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

@@ -1,26 +1,26 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// The contract below is the single declaration of what this app exposes. The
-// frontend imports `App` with `import type`, so the page is checked against
-// these exact types — command names, argument shapes, results and event
-// payloads — with no code generation and nothing to keep in sync.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. The frontend imports `App` with
+// `import type`, so the page is checked against these exact types — command
+// names, argument shapes, results and event payloads — with no code
+// generation and nothing to keep in sync.
 //
 // 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 { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+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. */
@@ -28,16 +28,13 @@ export type AppEvents = {
   added: number;
 };
 
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
-
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
-export type App = { commands: typeof commands; events: typeof events };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 // Typing the app with the contract is what makes `app.command` checked: the
 // name must be one of the declared ones, `args` is inferred from it, and the
 // return value has to match. Same for `app.emit`.
-export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+export function setup(app: App): void {
   app.command("add", (args) => {
     const sum = args.a + args.b;
     app.emit("added", sum);

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

@@ -1,26 +1,26 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// The contract below is the single declaration of what this app exposes. The
-// frontend imports `App` with `import type`, so the page is checked against
-// these exact types — command names, argument shapes, results and event
-// payloads — with no code generation and nothing to keep in sync.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. The frontend imports `App` with
+// `import type`, so the page is checked against these exact types — command
+// names, argument shapes, results and event payloads — with no code
+// generation and nothing to keep in sync.
 //
 // 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 { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+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. */
@@ -28,16 +28,13 @@ export type AppEvents = {
   added: number;
 };
 
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
-
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
-export type App = { commands: typeof commands; events: typeof events };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 // Typing the app with the contract is what makes `app.command` checked: the
 // name must be one of the declared ones, `args` is inferred from it, and the
 // return value has to match. Same for `app.emit`.
-export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+export function setup(app: App): void {
   app.command("add", (args) => {
     const sum = args.a + args.b;
     app.emit("added", sum);

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

@@ -1,26 +1,26 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// The contract below is the single declaration of what this app exposes. The
-// frontend imports `App` with `import type`, so the page is checked against
-// these exact types — command names, argument shapes, results and event
-// payloads — with no code generation and nothing to keep in sync.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. The frontend imports `App` with
+// `import type`, so the page is checked against these exact types — command
+// names, argument shapes, results and event payloads — with no code
+// generation and nothing to keep in sync.
 //
 // 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 { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+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. */
@@ -28,16 +28,13 @@ export type AppEvents = {
   added: number;
 };
 
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
-
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
-export type App = { commands: typeof commands; events: typeof events };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 // Typing the app with the contract is what makes `app.command` checked: the
 // name must be one of the declared ones, `args` is inferred from it, and the
 // return value has to match. Same for `app.emit`.
-export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+export function setup(app: App): void {
   app.command("add", (args) => {
     const sum = args.a + args.b;
     app.emit("added", sum);

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

@@ -1,26 +1,26 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// The contract below is the single declaration of what this app exposes. The
-// frontend imports `App` with `import type`, so the page is checked against
-// these exact types — command names, argument shapes, results and event
-// payloads — with no code generation and nothing to keep in sync.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. The frontend imports `App` with
+// `import type`, so the page is checked against these exact types — command
+// names, argument shapes, results and event payloads — with no code
+// generation and nothing to keep in sync.
 //
 // 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 { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+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. */
@@ -28,16 +28,13 @@ export type AppEvents = {
   added: number;
 };
 
-export const commands = defineCommands<AppCommands>();
-export const events = defineEvents<AppEvents>();
-
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
-export type App = { commands: typeof commands; events: typeof events };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
 // Typing the app with the contract is what makes `app.command` checked: the
 // name must be one of the declared ones, `args` is inferred from it, and the
 // return value has to match. Same for `app.emit`.
-export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+export function setup(app: App): void {
   app.command("add", (args) => {
     const sum = args.a + args.b;
     app.emit("added", sum);