janela 0.4.0 → 0.5.0

package/README.md

@@ -126,6 +126,80 @@ export function setup(app: JanelaApp): void {
 }
 ```
 
+## The typed contract
+
+The API above works, but `invoke<number>("add", …)` is an *assertion*: nothing
+checks that the command exists, that the arguments match, or that the result
+is really a number. Rename a command and the page still compiles.
+
+Declare a contract instead, and both sides are checked against the same
+declarations — no code generation, nothing to keep in sync. This is the
+framework templates' default.
+
+```ts
+// src-host/main.ts
+import { defineCommands, defineEvents, emit, on, onAsync, type JanelaApp } from "janela/host";
+
+export const commands = defineCommands<{
+  add:   { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string };         result: string };
+  wait:  { args: { ms: number };           result: string };
+}>();
+
+export const events = defineEvents<{ added: number }>();
+
+export type App = { commands: typeof commands; events: typeof events };
+
+export function setup(app: JanelaApp): void {
+  on(app, commands, "add", (args) => {      // args inferred: { a: number; b: number }
+    emit(app, events, "added", args.a + args.b);
+    return args.a + args.b;                 // return type checked against the contract
+  });
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => resolve("waited " + args.ms + "ms"));
+  });
+}
+```
+
+```ts
+// src/App.tsx (or .vue, .svelte …)
+import { createClient } from "janela/api";
+import type { App } from "../src-host/main";   // type-only: erased at compile time
+
+const client = createClient<App>();
+
+const sum = await client.invoke("add", { a: 2, b: 40 });  // sum: number
+const off = client.on("added", (v) => console.log(v));    // v: number
+off();                                                     // unsubscribe
+```
+
+Now these are all compile errors:
+
+```ts
+await client.invoke("addd", { a: 1, b: 2 });   // unknown command
+await client.invoke("add", { a: 1, b: "2" });  // wrong argument type
+const s: string = await client.invoke("add", { a: 1, b: 2 });  // wrong result
+client.on("addedd", () => {});                 // unknown event
+client.on("added", (v: string) => {});         // wrong payload type
+```
+
+Two things worth knowing:
+
+- **`import type` is erased**, so no host code is bundled into the page — the
+  contract is a type edge and nothing more. (Verified: the built frontend
+  bundle contains none of the host's strings.)
+- **Types erase at runtime.** Payloads still cross as JSON and nothing
+  validates a malformed one. This is compile-time safety, like Tauri's
+  `invoke<T>()` — the difference is that here the types come from the host's
+  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.
+
+The untyped `invoke` / `listen` still work unchanged; the contract is
+additive, and the `vanilla` template still uses the global.
+
 ## Async commands
 
 A command that has to wait — or to chew through real work — should not freeze
@@ -235,6 +309,41 @@ 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.4.x
+
+Nothing breaks: `app.command`, `app.emit`, and the untyped `invoke` / `listen`
+all work exactly as before, and the `vanilla` template is unchanged.
+
+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,
+  `createClient<App>()` on the page. The framework templates now scaffold with
+  it. See [The typed contract](#the-typed-contract).
+
+To adopt it in an existing app, declare what the host already exposes and swap
+the registrations:
+
+```ts
+// before
+app.command("add", (args) => {
+  const a = args as { a: number; b: number };
+  return a.a + a.b;
+});
+
+// after
+export const commands = defineCommands<{
+  add: { args: { a: number; b: number }; result: number };
+}>();
+export type App = { commands: typeof commands; events: typeof events };
+
+on(app, commands, "add", (args) => args.a + args.b);   // args inferred, no cast
+```
+
+then on the page, replace `invoke<number>("add", …)` with
+`client.invoke("add", …)` built from `createClient<App>()`.
+
 ## Migrating from 0.3.x
 
 Nothing breaks: the injected `janela` global still works exactly as before.

package/api/index.d.ts

@@ -6,10 +6,15 @@
  * parse.
  */
 
+import type { CommandShapes, Commands, Events } from "../runtime/types";
+
+/** Removes a subscription created by `listen` / `client.on`. */
+export type Unlisten = () => void;
+
 /** The bridge janela injects as `window.janela` before each document loads. */
 export interface JanelaBridge {
   invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
-  listen<T = unknown>(event: string, cb: (payload: T) => void): void;
+  listen<T = unknown>(event: string, cb: (payload: T) => void): Unlisten;
 }
 
 /**
@@ -19,19 +24,79 @@ export interface JanelaBridge {
  * const sum = await invoke<number>("add", { a: 2, b: 40 });
  * ```
  *
+ * The generic is an assertion, not a check — prefer `createClient` when the
+ * host declares a contract, which verifies the name, the arguments and the
+ * result against the host's own types.
+ *
  * Rejects if the command is unknown, if the handler rejected, or if the page
  * is not running inside a janela window.
  */
 export declare function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
 
 /**
- * Subscribe to an event the host sends with `app.emit`.
+ * Subscribe to an event the host sends with `app.emit`. Returns a disposer.
  *
  * ```ts
- * listen<number>("added", (sum) => console.log(sum));
+ * const off = listen<number>("added", (sum) => console.log(sum));
+ * off();
  * ```
  */
 export declare function listen<T = unknown>(
   event: string,
   cb: (payload: T) => void,
-): void;
+): Unlisten;
+
+// ---------------------------------------------------------------------------
+// Typed contract
+// ---------------------------------------------------------------------------
+
+/** Anything shaped like a host contract module's exported `App` type. */
+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 event table declared by a contract. */
+export type EventsOf<A> = A extends { events: Events<infer E> } ? E : never;
+
+/**
+ * A client bound to a host contract: command names, argument shapes, result
+ * types and event payloads are all checked against the host's declarations.
+ */
+export interface JanelaClient<A> {
+  /**
+   * Call a declared command. Unknown names and wrong argument shapes are
+   * compile errors, and the result type comes from the contract.
+   */
+  invoke<K extends keyof CommandsOf<A> & string>(
+    name: K,
+    args: CommandsOf<A>[K]["args"],
+  ): Promise<CommandsOf<A>[K]["result"]>;
+  /**
+   * Subscribe to a declared event; the payload type is inferred. Returns a
+   * disposer that removes the subscription.
+   */
+  on<K extends keyof EventsOf<A> & string>(
+    event: K,
+    cb: (payload: EventsOf<A>[K]) => void,
+  ): Unlisten;
+}
+
+/**
+ * Build a client checked against a host's contract.
+ *
+ * ```ts
+ * import type { App } from "../src-host/main";
+ * 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
+ * ```
+ *
+ * `import type` is erased, so no host code is bundled into the page — the
+ * contract is a type edge and nothing else. Payloads still cross as JSON, so
+ * this is compile-time safety; nothing is validated at runtime.
+ */
+export declare function createClient<A>(): JanelaClient<A>;

package/api/index.js

@@ -29,7 +29,36 @@ export async function invoke(cmd, args) {
   return bridge().invoke(cmd, args);
 }
 
-/** Subscribe to an event the host sends with `app.emit`. */
+/**
+ * Subscribe to an event the host sends with `app.emit`. Returns a function
+ * that removes the subscription.
+ */
 export function listen(event, cb) {
-  bridge().listen(event, cb);
+  const off = bridge().listen(event, cb);
+  // Hosts before 0.5.0 returned nothing from listen; keep a working disposer
+  // either way rather than handing back undefined.
+  if (typeof off === "function") return off;
+  return function unlisten() {
+    const all = globalThis.__wvListeners ? globalThis.__wvListeners[event] : undefined;
+    if (!all) return;
+    const i = all.indexOf(cb);
+    if (i >= 0) all.splice(i, 1);
+  };
+}
+
+/**
+ * A client bound to a host's declared contract. The type parameter carries the
+ * command and event tables; at runtime this is the same bridge as `invoke` and
+ * `listen`, so the contract costs nothing and validates nothing — it is
+ * checked entirely by the compiler.
+ */
+export function createClient() {
+  return {
+    invoke(name, args) {
+      return invoke(name, args);
+    },
+    on(event, cb) {
+      return listen(event, cb);
+    },
+  };
 }

package/package.json

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

package/runtime/janela.ts

@@ -67,6 +67,11 @@ const BOOTSTRAP =
   "  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) {" +
@@ -80,7 +85,11 @@ const BOOTSTRAP =
 export type {
   AsyncCommandHandler,
   CommandHandler,
+  CommandShape,
+  CommandShapes,
+  Commands,
   DialogFilter,
+  Events,
   FsCallback,
   JanelaApp,
   OpenDialogOptions,
@@ -88,6 +97,11 @@ export type {
   WindowConfig,
 } from "./types";
 
+// The typed-contract helpers are values, so they are re-exported as values.
+// A project's `import { defineCommands } from "janela/host"` is rewritten to
+// this module by the CLI before scriptc sees it.
+export { defineCommands, defineEvents, emit, on, onAsync } from "./types";
+
 import type {
   AsyncCommandHandler,
   CommandHandler,

package/runtime/types.ts

@@ -8,7 +8,8 @@
  *   - re-exported by runtime/janela.ts, which is what the compiled build
  *     actually links against (the CLI copies both files into .janela/build/).
  *
- * Keep it declaration-only: no runtime code lives here.
+ * Mostly declarations; the typed-contract helpers at the bottom are the only
+ * runtime code, and they are deliberately trivial.
  */
 
 // Handlers take the invoked arguments as a value and return a value; the
@@ -129,3 +130,122 @@ export interface JanelaApp {
   /** Show the page and block until the window closes. Returns the run status. */
   run: (html: string) => number;
 }
+
+// ---------------------------------------------------------------------------
+// Typed IPC contract
+// ---------------------------------------------------------------------------
+//
+// The contract is a TYPE the host declares and the frontend imports with
+// `import type`. Because both sides are TypeScript, no code generation is
+// involved and nothing can drift: the frontend checks against the host's own
+// declarations, and the import is erased, so no host code reaches the bundle.
+//
+// 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.
+
+/** One command's argument and result types. */
+export interface CommandShape {
+  args: unknown;
+  result: unknown;
+}
+
+/** A contract's command table: name → shape. */
+export type CommandShapes = Record<string, CommandShape>;
+
+/**
+ * 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.
+ */
+export interface Commands<M extends CommandShapes> {
+  __commands?: M;
+}
+
+/** A declared event contract: event name → payload type. */
+export interface Events<E> {
+  __events?: E;
+}
+
+/**
+ * Declare the commands a host exposes.
+ *
+ * ```ts
+ * export const commands = defineCommands<{
+ *   add: { args: { a: number; b: number }; result: number };
+ * }>();
+ * ```
+ */
+export function defineCommands<M extends CommandShapes>(): Commands<M> {
+  return {};
+}
+
+/** Declare the events a host emits: `defineEvents<{ added: number }>()`. */
+export function defineEvents<E>(): Events<E> {
+  return {};
+}
+
+/**
+ * Register a command against the contract. `args` is inferred from the
+ * contract, and the return type is checked against it, so the handler is
+ * written once with no casts.
+ *
+ * ```ts
+ * on(app, commands, "add", (args) => args.a + args.b);
+ * ```
+ */
+export function on<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaApp,
+  _commands: Commands<M>,
+  name: K,
+  handler: (args: M[K]["args"]) => M[K]["result"],
+): void {
+  app.command(name, (args: unknown) => handler(args as M[K]["args"]));
+}
+
+/**
+ * Register a command that answers on a later turn. `resolve` takes the
+ * contract's result type; see AsyncCommandHandler for the timing rules.
+ */
+export function onAsync<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaApp,
+  _commands: Commands<M>,
+  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: (value: unknown) => void, reject: (reason: unknown) => void) => {
+      handler(
+        args as M[K]["args"],
+        (value: M[K]["result"]) => resolve(value),
+        reject,
+      );
+    },
+  );
+}
+
+/**
+ * Emit a declared event. The name must exist in the contract and the payload
+ * must match its type.
+ *
+ * ```ts
+ * emit(app, events, "added", 42);
+ * ```
+ */
+export function emit<E, K extends keyof E & string>(
+  app: JanelaApp,
+  _events: Events<E>,
+  name: K,
+  payload: E[K],
+): void {
+  app.emit(name, payload);
+}

package/templates/react/files/src/App.tsx

@@ -1,7 +1,12 @@
 import { useEffect, useState } from "react";
-import { invoke, listen } from "janela/api";
+import { createClient } from "janela/api";
+// Type-only import of the host contract: erased at compile time, so no host
+// code is bundled into the page.
+import type { App as Contract } from "../src-host/main";
 import "./App.css";
 
+const client = createClient<Contract>();
+
 export default function App() {
   const [greeting, setGreeting] = useState("…");
   const [a, setA] = useState(2);
@@ -10,16 +15,17 @@ export default function App() {
   const [events, setEvents] = useState<string[]>([]);
 
   useEffect(() => {
-    // Backend→frontend events. The payload arrives as a value, and the
-    // generic says which value.
-    listen<number>("added", (value) =>
+    // The event name is checked against the contract, `value` is inferred,
+    // and `on` returns a disposer.
+    const off = client.on("added", (value) =>
       setEvents((prev) => [`host emitted: ${value}`, ...prev]),
     );
-    invoke<string>("greet", { name: "__NAME__" }).then(setGreeting);
+    client.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+    return off;
   }, []);
 
   const add = async () =>
-    setSum(await invoke<number>("add", { a, b }));
+    setSum(await client.invoke("add", { a, b }));
 
   return (
     <>

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

@@ -1,42 +1,68 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// 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.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// 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.
 
-import type { JanelaApp } from "janela/host";
+import {
+  defineCommands,
+  defineEvents,
+  emit,
+  on,
+  onAsync,
+  type JanelaApp,
+} from "janela/host";
+
+export const commands = defineCommands<{
+  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 };
+}>();
+
+export const events = defineEvents<{
+  added: number;
+}>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
-    app.emit("added", sum);
+  // `args` is inferred from the contract, and the return type is checked
+  // against it — no casts, and no way to drift from what the page expects.
+  on(app, commands, "add", (args) => {
+    const sum = args.a + args.b;
+    emit(app, events, "added", sum);
     return sum;
   });
 
-  app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+  on(app, commands, "greet", (args) => {
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+  on(app, commands, "log", (args) => {
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
-  app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  on(app, commands, "quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/solid/files/src/App.tsx

@@ -1,7 +1,12 @@
 import { createSignal, onMount, For, Show } from "solid-js";
-import { invoke, listen } from "janela/api";
+import { createClient } from "janela/api";
+// Type-only import of the host contract: erased at compile time, so no host
+// code is bundled into the page.
+import type { App as Contract } from "../src-host/main";
 import "./App.css";
 
+const client = createClient<Contract>();
+
 export default function App() {
   const [greeting, setGreeting] = createSignal("…");
   const [a, setA] = createSignal(2);
@@ -11,16 +16,16 @@ export default function App() {
 
   // Backend→frontend events. The payload arrives as a value, and the generic
   // says which value.
-  listen<number>("added", (value) =>
+  client.on("added", (value) =>
     setEvents((prev) => [`host emitted: ${value}`, ...prev]),
   );
 
   onMount(async () =>
-    setGreeting(await invoke<string>("greet", { name: "__NAME__" })),
+    setGreeting(await client.invoke("greet", { name: "__NAME__" })),
   );
 
   const add = async () =>
-    setSum(await invoke<number>("add", { a: a(), b: b() }));
+    setSum(await client.invoke("add", { a: a(), b: b() }));
 
   return (
     <>

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

@@ -1,42 +1,68 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// 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.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// 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.
 
-import type { JanelaApp } from "janela/host";
+import {
+  defineCommands,
+  defineEvents,
+  emit,
+  on,
+  onAsync,
+  type JanelaApp,
+} from "janela/host";
+
+export const commands = defineCommands<{
+  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 };
+}>();
+
+export const events = defineEvents<{
+  added: number;
+}>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
-    app.emit("added", sum);
+  // `args` is inferred from the contract, and the return type is checked
+  // against it — no casts, and no way to drift from what the page expects.
+  on(app, commands, "add", (args) => {
+    const sum = args.a + args.b;
+    emit(app, events, "added", sum);
     return sum;
   });
 
-  app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+  on(app, commands, "greet", (args) => {
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+  on(app, commands, "log", (args) => {
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
-  app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  on(app, commands, "quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/svelte/files/src/App.svelte

@@ -1,5 +1,10 @@
 <script lang="ts">
-  import { invoke, listen } from "janela/api";
+  import { createClient } from "janela/api";
+  // Type-only import of the host contract: erased at compile time, so no
+  // host code is bundled into the page.
+  import type { App as Contract } from "../src-host/main";
+
+  const client = createClient<Contract>();
 
   let greeting = $state("…");
   let a = $state(2);
@@ -9,12 +14,12 @@
 
   // Backend→frontend events. The payload arrives as a value, and the generic
   // says which value.
-  listen<number>("added", (value) => (events = [`host emitted: ${value}`, ...events]));
+  client.on("added", (value) => (events = [`host emitted: ${value}`, ...events]));
 
-  invoke<string>("greet", { name: "__NAME__" }).then((g) => (greeting = g));
+  client.invoke("greet", { name: "__NAME__" }).then((g) => (greeting = g));
 
   async function add() {
-    sum = await invoke<number>("add", { a: Number(a), b: Number(b) });
+    sum = await client.invoke("add", { a: Number(a), b: Number(b) });
   }
 </script>
 

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

@@ -1,42 +1,68 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// 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.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// 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.
 
-import type { JanelaApp } from "janela/host";
+import {
+  defineCommands,
+  defineEvents,
+  emit,
+  on,
+  onAsync,
+  type JanelaApp,
+} from "janela/host";
+
+export const commands = defineCommands<{
+  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 };
+}>();
+
+export const events = defineEvents<{
+  added: number;
+}>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
-    app.emit("added", sum);
+  // `args` is inferred from the contract, and the return type is checked
+  // against it — no casts, and no way to drift from what the page expects.
+  on(app, commands, "add", (args) => {
+    const sum = args.a + args.b;
+    emit(app, events, "added", sum);
     return sum;
   });
 
-  app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+  on(app, commands, "greet", (args) => {
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+  on(app, commands, "log", (args) => {
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
-  app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  on(app, commands, "quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/vue/files/src/App.vue

@@ -1,6 +1,11 @@
 <script setup lang="ts">
-import { onMounted, ref } from "vue";
-import { invoke, listen } from "janela/api";
+import { onMounted, onUnmounted, ref } from "vue";
+import { createClient } from "janela/api";
+// A type-only import of the host's contract. It is erased at compile time, so
+// no host code is bundled into the page — this is purely a type edge.
+import type { App } from "../src-host/main";
+
+const client = createClient<App>();
 
 const greeting = ref("…");
 const a = ref(2);
@@ -8,16 +13,17 @@ const b = ref(40);
 const sum = ref<number | null>(null);
 const events = ref<string[]>([]);
 
-// Backend→frontend events. The payload arrives as a value, not a JSON string,
-// and the generic says which value.
-listen<number>("added", (value) => events.value.unshift(`host emitted: ${value}`));
+// The event name is checked against the contract and `value` is inferred.
+// `on` returns a disposer.
+const off = client.on("added", (value) => events.value.unshift(`host emitted: ${value}`));
+onUnmounted(off);
 
 onMounted(async () => {
-  greeting.value = await invoke<string>("greet", { name: "__NAME__" });
+  greeting.value = await client.invoke("greet", { name: "__NAME__" });
 });
 
 async function add() {
-  sum.value = await invoke<number>("add", { a: Number(a.value), b: Number(b.value) });
+  sum.value = await client.invoke("add", { a: Number(a.value), b: Number(b.value) });
 }
 </script>
 

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

@@ -1,42 +1,68 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// 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.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// 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.
 
-import type { JanelaApp } from "janela/host";
+import {
+  defineCommands,
+  defineEvents,
+  emit,
+  on,
+  onAsync,
+  type JanelaApp,
+} from "janela/host";
+
+export const commands = defineCommands<{
+  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 };
+}>();
+
+export const events = defineEvents<{
+  added: number;
+}>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
-    app.emit("added", sum);
+  // `args` is inferred from the contract, and the return type is checked
+  // against it — no casts, and no way to drift from what the page expects.
+  on(app, commands, "add", (args) => {
+    const sum = args.a + args.b;
+    emit(app, events, "added", sum);
     return sum;
   });
 
-  app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+  on(app, commands, "greet", (args) => {
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+  on(app, commands, "log", (args) => {
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
-  app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  on(app, commands, "quit", (_args) => {
     app.quit();
+    return null;
   });
 }