janela 0.4.0 → 0.6.0

package/README.md

@@ -126,6 +126,83 @@ 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, 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 };
+};
+export type AppEvents = { added: number };
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+
+export type App = { commands: typeof commands; events: typeof events };
+
+// Typing the app with the contract is what makes the methods below checked.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): 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
+  });
+  app.commandAsync("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 +312,78 @@ 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.5.x
+
+The contract now rides on the app itself, so the standalone registrars are no
+longer needed. Type the app with your contract and call its methods:
+
+```ts
+// before (0.5.x)
+export function setup(app: JanelaApp): void {
+  on(app, commands, "add", (args) => args.a + args.b);
+  onAsync(app, commands, "wait", (args, resolve) => { … });
+  emit(app, events, "added", 42);
+}
+
+// after (0.6.x)
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => args.a + args.b);
+  app.commandAsync("wait", (args, resolve) => { … });
+  app.emit("added", 42);
+}
+```
+
+Declare each contract as a named type so the same one feeds `defineCommands`
+and the `setup` signature:
+
+```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>();
+```
+
+`on`, `onAsync` and `emit` still work — they are `@deprecated` one-line
+wrappers now — so 0.5.x code keeps compiling. The page side is unchanged:
+`createClient<App>()` and `client.invoke(...)` are exactly as before. An app
+with no contract needs no change at all: `setup(app: JanelaApp)` still gets an
+untyped `app.command(name, handler)`.
+
+## 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 };
+
+app.command("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/bin/janela.mjs

@@ -516,10 +516,18 @@ 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 { WINDOW } from "./config";\n` +
       `import { INDEX_HTML } from "./frontend";\n` +
       `import { setup } from "./main";\n\n` +
-      `const app = createApp(WINDOW);\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` +
+      `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
       `setup(app);\n` +
       `const rc = app.run(INDEX_HTML) + 0;\n` +
       `console.log("[janela] run returned", rc);\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
       "default": "./api/index.js"
     },
     "./host": {
-      "types": "./runtime/types.ts"
+      "types": "./runtime/janela.ts"
     },
     "./global": {
       "types": "./api/global.d.ts"